Creating Your First Project 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 Creating Your First Project This tutorial guides you through the process of using the MPLAB Harmony Configurator (MHC) and MPLAB Harmony libraries to develop your first MPLAB Harmony project. Part I: Creating Your First MPLAB Harmony Application in MHC This section provides information on creating your first project in MPLAB Harmony. Overview Lists the basic steps necessary to create a MPLAB Harmony application using the MHC. Description MPLAB Harmony provides a convenient MPLAB X IDE plug-in configuration utility, the MPLAB Harmony Configurator (MHC), which you can use to easily create MPLAB Harmony-based projects. This tutorial will show you how to use the MHC to quickly create your first project. It also shows how to create a simple "heartbeat" LED application that flashes an LED. The project created can then serve as a test bed for understanding additional features of MPLAB Harmony, including error handling, system console, and debugging services, and using MPLAB Harmony Middleware and Drivers. You can also reuse the heartbeat LED application in future projects as a simple indicator of system health. Getting Started Provides information on getting started with creating your first project. Description Before beginning this tutorial, ensure that you have installed the MPLAB X IDE and necessary language tools as described in Volume I: Getting Started With MPLAB Harmony > Prerequisites. In addition, ensure that you have installed MPLAB Harmony on your hard drive and that you have the correct MHC plug-in installed in the MPLAB X IDE. You may want to check out your development board by first loading and running a MPLAB Harmony example that uses your board. Follow the instructions in Volume I: Getting Started With MPLAB Harmony > Applications Help > Examples for the demonstration you chose. Set up the board as detailed in the related User’s Guide. The example project in this tutorial can be used with any of the following boards: • PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit (DM320007). • PIC32 USB Starter Kit III (DM320003-3) • Explorer 16 Development Board (DM240001-2 ) with PIC32MX795F512L PIM (MA320003) The tutorial steps are equally valid on any other development board, but may be slightly different. In the event you do not have any of these boards, refer to Volume II: Supported Hardware > Supported Development Boards for a list of available development boards that you could use to complete this tutorial. If you are using some other development board, you will need to know what processor is on the board to select the correct Board Support Package. Finally, this tutorial assumes that you have some familiarity with the following: • MPLAB X IDE development and debugging fundamentals • C language programming • PIC32 product family and supported development boards What You Will Learn • How to set up your hardware • How to create a new MPLAB Harmony project from within MPLAB X IDE • How to use System Services, in this case Timer System Services • How to use the Board Support Package (BSP) to toggle an LED • How to add new application states to the application task loop • How to run and build your project Tutorial Steps Describes the necessary steps to create your project. Step 1: Setting Up Your Hardware Provides information for setting up your hardware. Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part I: Creating Your First MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 3 Description PIC32MZ Embedded Connectivity (EF) Starter Kit Connect the "USB Debug" port on the starter kit board to a USB port on your PC using a Mini-B to Type-A USB cable. See PIC32MZ Embedded Connectivity with Floating Point Unit (EF) Starter Kit for additional information on this hardware. PIC32 USB Starter Kit III Connect the debug port on the upper left side of the board to your PIC using a Mini-B to Type-A USB cable. Refer to the PIC32 USB Starter Kit III for additional information on this hardware. Explorer 16 Development Board with the PIC32MX795F512L Plug-in Module (PIM) Mount the PIC32MX795F512L PIM to PIM socket. Set switch S2 to PIM. Power the board with 9V to 15V DC using the J12 connector. Attach a REAL ICE In-circuit Emulator to the RJ12 jack on the board. Other Boards Consult the Information Sheet or User's Guide for your hardware. Refer to Volume II: Supported Hardware > Supported Development Boards for the list of hardware supported by MPLAB Harmony. Step 2: Create a New MPLAB X IDE Project Provides the required steps to create a new MPLAB X IDE project. Description Note: Prior to starting this tutorial, please ensure that the software requirements are met, as described in Volume I: Getting Started With MPLAB Harmony >Prerequisites. 1. Start MPLAB X IDE and select File > New Project. The New Project dialog appears. 2. In the New Project dialog, ensure that Microchip Embedded is selected, and that the project type is 32-bit MPLAB Harmony Project, and then click Next. Note: If the option “32-Bit MPLAB Harmony Project” is not visible, you need to stop and download/install MPLAB Harmony before continuing with this tutorial. 4. In the updated New Project dialog, make the following changes: • Harmony Path: Ensure that the path you enter is the path to your installation of MPLAB Harmony • Project Name: Enter heartbeat (all lowercase) • Device Family: Select the device family that includes your board’s processor. • For the PIC32MZ EF Starter Kit board, select PIC32MZ Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part I: Creating Your First MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 4 • For the PIC32 USB Starter Kit III and the Explorer 16 Development Board with PIC32MX795F512L PIM, select PIC32MX • Target Board: Select the board you are using (alternately, you can choose the Target Device first, and then look through a smaller list of Target Boards): • For the PIC32MZ EF Starter Kit board, select PIC32MZ (EF) Starter Kit. You will have to scroll down the list to find this board. • For the PIC32 USB Starter Kit III, select PIC32MX USB Starter Kit III. • For the Explorer 16 Development Board with PIC32MX795F512L Plug In Module, select PIC32MX795F512L PIM w/Explorer 16 Development Board. 5. The New Project dialog should appear, as follows. Descriptions of each field follow the image. 1: The path to your installation of MPLAB Harmony. 2: The location of your MPLAB project. 3: The name of the MPLAB project (the name must be all lowercase characters). 4: The path to the MPLAB project file. 5: The MPLAB project configuration name. 6: The selected device family (PIC32MZ or PIC32MX). 7: The selected target device. 8: The selected target board (PIC32MZ EF Starter Kit, PIC32MZ USB Starter Kit III, or PIC32MX795F5123L with the Explorer 16 Development Board). 6. Click Finish when done. A new empty project named heartbeat will be created in MPLAB X IDE, which opens the MPLAB Harmony Configurator (MHC) plug-in. Note: The selected Board Support Package (BSP) assigns device pins to various board functions and sets up the device’s clock tree based on the board’s clock source. You can review the pin assignments using the Pin Diagram or Pin Settings tabs in MHC. The Clock Diagram tab shows the board and application clock setup. Step 3: Configure MPLAB Harmony and the Application Describes how to configure MPLAB Harmony and the application. Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part I: Creating Your First MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 5 Description Within the MPLAB Harmony Configurator window, change the Application Name from “app” to “heartbeat”. Be sure to make the new application name all lowercase. The name is reused in source code for function and data type definitions and using lowercase will stay consistent with the naming conventions used in MPLAB Harmony code. Step 4: Generate the Configured Source Code Describes how to generate the configured source code. Description 1. In MHC, click Generate Code to generate the application’s code for the first time. 2. In the Modified Configuration dialog, click Save to save the project’s configuration. The Generate Project dialog appears. 3. Next, in the Generate Project dialog, click Generate. At this point, the project’s initial software has been configured. Let’s examine the software just created in the Projects panel of MPLAB X IDE, by expanding the Header Files and Source Files folders. Note the icons used in this image of the project’s organization make it seem like the files of the project are organized this way. Actually, this is a virtual organization of these files, not an actual one. Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part I: Creating Your First MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 6 If you click the Files tab you will see the actual organization of these files on your drive. Step 5: Use a Delay Timer to Toggle an LED on the Target Board Describes how to use a delay timer to toggle an LED. Description In this project we will use a delay timer to toggle an LED on the board using a delay of 500 milliseconds and LED1 on the PIC32MZ EF Starter Kit. 1. Double click system_config.h to open the file in an editor. 2. Add the following code to the end of the file, immediately after the line /*** Application Instance 0 Configuration ***/. Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part I: Creating Your First MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 7 // CUSTOM CODE - DO NOT DELETE #define HEARTBEAT_LED BSP_LED_1 #define HEARTBEAT_DELAY 500 // milliseconds // END OF CUSTOM CODE 2. In the system_config.h file within the editor, hold down the CTRL key and click BSP_LED_1. The editor will locate where this token is defined in the Board Support Package bsp.h file for the PIC32MZ EF Starter Kit. Step 6: Add the Timer System Service to Your Project Describes how to add the Timer System Service to your project. Description Next, the Timer System Service needs to be selected in MHC. 1. Select the MHC tab, expand Harmony Framework Configuration > System Services > Timer, and then select Use Timer System Service? 2. As observed in the Help window, the documentation for the Timer System Service is displayed. Using the Help, we can explore what this library provides and choose how to implement the timer delay we need to blink LED1. Click Library Interface and scroll down to Timed Delay Functions. Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part I: Creating Your First MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 8 The SYS_TMR_DelayMS function can be used to create a one-shot delay timer, and then poll that timer status using SYS_TMR_DElayStatusGet. When the timer times out, we can then toggle the LED. 3. Click SYS_TMR_DelayMS to open the related Help for this function. The code example in the documentation provides all that is needed to create the delay. First, the SYS_TMR_HANDLE variable is needed, which is assigned when the timer is created. Then, use SYS_TMR_DelayStatusGet to poll whether the timer has timed out using this handle. So now, we know what to do. Step 7: Add the Timer System Service Source Code to Your Project Describes how to add the source code for the Timer System Service to your project. Description 1. Before adding the Timer to the application, we need to regenerate the application to add the Timer System Service library to our code, using the same process as described in Generate the Configured Source Code. The merge will open a difference window for system_config.h that was modified, as described in Add the Timer System Service to Your Project. Accept all the changes using the icon shown in the following Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part I: Creating Your First MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 9 figure. • The next figure shows the customer code that was added previously, which we want to retain. Therefore, do not click the icon for this merge. Step 8: Use the Timer System Service in Your Application Describes how to use the Timer System Service in your application. Description 1. Next, from the Project tab in MPLAB X IDE, double-click the heartbeat.h file to open it in the editor. 2. Then, add the new state, HEARTBEAT_RESTART_TIMER, to the application's state enumeration, as shown in the following figure. We will show how that state is used later in the tutorial. // HEARTBEAT_STATES: HEARTBEAT_RESTART_TIMER Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part I: Creating Your First MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 10 3. Now, add the delay timer handle, SYS_TMR_HANDLE hDelayTimer; // Handle for delay timer, to the application's data structure, as shown in the following figure. // HEARTBEAT_DATA SYS_TMR_HANDLE hDelayTimer; // Handle for delay timer 4. Close and save heartbeat.h by clicking the 'x', and then clicking Save. 5. Next, from the Projects tab in MPLAB X IDE, double-click heartbeat.c from the Source Files > app folder to open it in the editor. We need to update heartbeat.c to add the first timer delay, execute the time-out wait, and restart timer code. Refer to the following figure for the locations to insert the different code blocks. • Insert the following code to start the first delay timer heartbeatData.hDelayTimer = SYS_TMR_DelayMS(HEARTBEAT_DELAY); if (heartbeatData.hDelayTimer != SYS_TMR_HANDLE_INVALID) { // Valid handle returned BSP_LEDOn(HEARTBEAT_LED); heartbeatData.state = HEARTBEAT_STATE_SERVICE_TASKS; } • Insert the following code to wait for a time-out if (SYS_TMR_DelayStatusGet(heartbeatData.hDelayTimer)) { // Single shot timer has now timed out. BSP_LEDToggle(HEARTBEAT_LED); heartbeatData.state = HEARTBEAT_RESTART_TIMER; } • Finally, insert the following code to add the state to the restart timer. case HEARTBEAT_RESTART_TIMER: { // Create a new timer heartbeatData.hDelayTimer = SYS_TMR_DelayMS(HEARTBEAT_DELAY); if (heartbeatData.hDelayTimer != SYS_TMR_HANDLE_INVALID) { // Valid handle returned heartbeatData.state = HEARTBEAT_STATE_SERVICE_TASKS; } break; } Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part I: Creating Your First MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 11 6. Once you have finished inserting the code blocks, the heartbeat.c file should appear like the following figure. Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part I: Creating Your First MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 12 7. After updating the code, close and save heartbeat.c. Step 9: Build and Run Your Project Describes how to build and run your project. Description 1. For the PIC32MZ EF Starter Kit, click the Run Main Project icon to build and run your project in MPLAB X IDE. If prompted, select the on-board debugger to load the project. • For the PIC32 USB Starter Kit III, select the PICkit On Board (PKOB) debugger • For the Explorer 16 Development Board, select REAL ICE Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part I: Creating Your First MPLAB Harmony © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 13 3. After making these selections click OK and close the Properties window. 4. Run the project using the Run Main Project button. For both boards, the LED should flash with a one second period. Part II: Debugging With Your Project This section discusses how to debug problems in your project from within MPLAB’s debugger Overview This section discusses how to debug problems in your project from within the MPLAB X IDE debugger. Part III: Debugging While Running Stand-alone discusses how to debug problems when running without the debugger, including using diagnostic messages to a HyperTerminal equivalent application on your computer. Description Two important tools in debugging any embedded software application are asserts and exception handling. By default, asserts in the PIC32 code write out an error message to USART2, and then jump into a while(1){} loop. However, if you have not set up USART2 you have no information. Even with USART2 set up, you can miss the message if your HyperTerminal isn’t set up correctly. By default, exceptions (e.g., divide by zero) cause the application to jump into a while(1){} loop, preventing the application from continuing, but providing no additional information. Therefore, in both cases your application stops working and you have no idea why. As a first step in developing any new application, you will be writing code and debugging it using the MPLAB debugger. This lesson shows you how to enable asserts and exception handling while running the debugger, so that you don’t have to setup USART2. The next tutorial will show how to support asserts and exception handling outside of the debugger. It will also show how to add other diagnostic messages to aid in debugging. Getting Started Provides information on getting started with project debugging. Description The following steps can be applied to any MPLAB Harmony-based project, but for the sake of clarity it is assumed that you have completed Part I: Creating Your First MPLAB Harmony Application in MHC. The project created in Part I will be used as the basis for this lesson, s it will be necessary to set up your board using the instructions from that tutorial. What You Will Learn • How to enable asserts from the debugger • How to enable Harmony’s built-in exception handler • How to decode the information reported by the exception handler to find where exception occurred in your code and what type of exception it was • How to test asserts and the exception handler Tutorial Steps This part of the tutorial explores how to use the debugger with your project. Asserts Under the Debugger This section explores how to use the debugger with asserts. Description 1. Launch MPLAB X IDE and load the project you created in Part I: Creating Your First MPLAB Harmony Application in MHC. 2. Open heartbeat.c. Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part II: Debugging With Your Project © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 14 3. Add assert(0); to the start of the HEARTBEAT_Initialize function, as shown in red in the following code example. void HEARTBEAT_Initialize ( void ) { assert(0); /* Place the App state machine in its initial state. */ heartbeatData.state = HEARTBEAT_STATE_INIT; 4. Build and run the application. You will see that the LED no longer flashes. This is because the assert(0) fired, and the application is now in an infinite loop within the compiler’s built-in assert function. However, if we hadn’t installed an assert(0) in the code in the first place, how would we know what happened? This is where the debugger can help. 5. As shown in the following figure, if you press and hold the Ctrl key and hover your cursor over the assert call, the Macro assert appears. However, where is this #define located? 6. Press and hold the Ctrl key and click the assert call. This will open the assert.h file that provides the definition of the assert. As shown in the next example, in the header file you can see how the assert is defined. extern void __attribute__((noreturn)) _fassert(int, const char *, const char *, const char*); #define __assert(line,file,expression,func) \ _fassert(line,file,expression,func) #define assert(expr) \ ((void)((expr) ? 0 : (__assert (__LINE__, __FILE__, #expr, __ASSERT_FUNC), 0))) 7. The function _fassert is the built-in assert handler provided by the compiler. Modify the file to allow the debugger to fire a breakpoint when running the debugger (when defined(__DEBUG) is true) by adding the code shown in red in the following example. #if defined(NDEBUG) || !defined(__DEBUG) # define __conditional_software_breakpoint(X) ((void)0) #else # define __conditional_software_breakpoint(X) \ ((X) ? \ (void) 0 : \ __builtin_software_breakpoint()) // Added to support debugger: # undef assert # define assert(expr) __conditional_software_breakpoint(expr) // End of addition #endif 8. Save your edits to assert.h by pressing Ctrl+S and closing the window. 9. Build and run the project under the debugger by clicking Debug Project. 10. The debugger should now stop at the assert(0) call. So by a slight modification to the compiler’s assert.h file, the debugger now stops with a breakpoint at the location of the failing assert. Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part II: Debugging With Your Project © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 15 For more information on how to use the built-in debugger in the MPLAB X IDE, refer to the IDE’s built-in help (Help Menu > Tool Help Contents > MPLAB X IDE >)for these topics: • Tutorial > Running and Debugging Code • Basic Tasks > Debug Run code • Basic Tasks > Control Program Execution with Breakpoints • Basic Tasks > Step Through Code • Basic Tasks > Watch Symbol Value Change • Basic Tasks > Watch Local Variable Values Change SYS_ASSERT Macro MPLAB Harmony uses a SYS_ASSERT macro in many places. Other libraries may have a localized assert. For example, the Graphics Library has its own macro GFX_ASSERT, which can help with debugging graphics development. By default, these macros are not defined. You can turn SYS_ASSERT on by the simply including the following code in your system_config.h file, which is located in Header Files > app > system_config > default). /*** Application Instance 0 Configuration ***/ // CUSTOM CODE - DO NOT DELETE #define HEARTBEAT_LED BSP_LED_1 #define HEARTBEAT_DELAY 500 // milliseconds #if defined( SYS_ASSERT ) #undef SYS_ASSERT #endif #define SYS_ASSERT(test,message) assert(test) // END OF CUSTOM CODE This code converts all of the MPLAB Harmony SYS_ASSERTs found into simple assert calls. However, this can greatly affect how the code works, depending on where the SYS_ASSERTs are located. Therefore, this method is best used sparingly. For more information on the SYS_ASSERT macro, refer to Volume V: MPLAB Harmony Framework > System Services Library Help > System Service Overview > Using the SYS_ASSERT Macro. By default, SYS_ASSERT is not defined. There are two alternatives provided in the MPLAB Harmony documentation, one for the debugger and a second for running outside of the debugger (stand-alone). Combining these two yields: #include "system/debug/sys_debug.h" #if !defined(NDEBUG) /*** SYS_DEBUG_Breakpoint Definition ***/ #if defined(__DEBUG) #define SYS_DEBUG_Breakpoint() __asm__ volatile (" sdbbp 0") #else #define SYS_DEBUG_BreakPoint() #endif//defined(__DEBUG) /*** SYS_ASSERT Definition ***/ #if defined( SYS_ASSERT ) //Remove prior definition – necessary to prevent ugly builds #undef SYS_ASSERT #endif #if defined(__DEBUG) //SYS_ASSERT for the debugger #define SYS_ASSERT(test, message) \ do{ if(!(test)) SYS_DEBUG_Breakpoint(); }while(false) #else //SYS_ASSERT for Standalone: #define SYS_ASSERT(test, message) \ do{ if(!(test)){ \ SYS_MESSAGE((message)); \ SYS_MESSAGE("\r\n"); \ while(1);} \ Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part II: Debugging With Your Project © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 16 }while(false) #endif//defined(__DEBUG) #endif//!defined(NDEBUG) The details of how to enable SYS_MESSAGE to allow output to a HyperTerminal are discussed in Part II: Debugging With Your First Project > Part III: Debugging While Running Stand-alone. Exception Handling in the Debugger This section explores how the debugger can be used in exception handling. Description 1. The first step in exploring how MPLAB Harmony handles exceptions is to verify that the exception handler is enabled. Before launching MHC, the project must be the Main Project within the MPLAB X IDE. To set the project as the Main Project, right click the project name, and select Set as Main Project. 2. Start MHC by clicking the MPLAB Harmony icon ( ). If this icon is not visible, this indicates the MHC plug-in is not installed (refer to Volume III: MPLAB harmony Configurator (MHC) > MPLAB Harmony Configurator User's Guide > Installing MHC to install MHC). 3. Verify that the MPLAB Harmony Exception Handler will be used. If correctly configured, the project should have the file system_exception.c within Source Files > app > system_config > default in the MPLAB X IDE Project tab. If this file is missing, go to MHC and select Use MPLAB Harmony Exception Handler Template? to enable MPLAB Harmony’s exception handler. Then, regenerate the application’s code to add Harmony’s exception handler. 4. Next, we need to create an exception in the code to observe how exceptions are handled. Replace the assert(0); in HEARTBEAT_Initialize with the following code. However, if we jump to trying out this code in the debugger, nothing will happen. Under the default optimization level (-01) the compiler will recognize that this code does not do anything useful, and will not include it in the build. Therefore, we will have to change the optimization level for the file to zero before proceeding. // Test out error handling under Optimization Level Zero for system_init.c { uint8_t x, y, z; x = 1; y = 0; z = x/y; } 5. Right click heartbeat.c and choose Properties from the resulting menu and make the following selections: • In File Properties, select Override build options ( ) • Next, select the compiler ( ) • Within the Optimization category ( ), set the optimization level to zero After making the selections, click OK to close the window 6. Next, build and run the application under the debugger. The application should stop at the debugger breakpoint in system_exceptions.c. Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part II: Debugging With Your Project © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 17 Hovering your cursor above the variable, _excep_code, will reveal the exception code. In this case, 0xD or 13, corresponds to an arithmetic trap (see the following table for a list of PIC32 Exception Codes. Hovering your cursor over the variable, _excep_addr, will reveal where in the code the exception occurred. Now we need to find out where 0x9D00_25D8 is located in the code (this address may be different for your appliation). Before going to the next step, stop the debugger session by pressing Shift+F5 or by clicking the Finish Debugger Session icon ( ). Exception Codes for PIC32 typedef enum { EXCEP_IRQ = 1, // interrupt (coded as zero) EXCEP_AdEL = 4, // address error exception (load or ifetch) EXCEP_AdES = 5, // address error exception (store) EXCEP_IBE = 6, // bus error (ifetch) EXCEP_DBE = 7, // bus error (load/store) EXCEP_Sys = 8, // syscall EXCEP_Bp = 9, // breakpoint EXCEP_RI = 10, // reserved instruction EXCEP_CpU = 11, // coprocessor unusable EXCEP_Overflow = 12, // arithmetic overflow EXCEP_Trap = 13, // trap (possible divide by zero) EXCEP_IS1 = 16, // implementation specfic 1 EXCEP_CEU = 17, // CorExtend Unuseable EXCEP_C2E = 18, // coprocessor 2 } EXCEPTION_CODES; 7. If the debugger is inside of a function, you can look at a disassembly of the code, but this is impractical when you don’t know where to look for the cause of the exception. Instead, you can build a list of all the application’s assembly code at build time. (Of course, this step can cause the build to take longer, so only use it when trying to debug an exception.) • Right click the project name and select Properties • Within the Building properties, enable Excecute this line after build, and enter the following text (Windows): • ${MP_CC_DIR}\xc32-objdump -S ${ImageDir}\${PROJECTNAME}.${IMAGE_TYPE}.elf > disassembly.lst • For Linux: ${MP_CC_DIR}/xc32-objdump -S ${ImageDir}/${PROJECTNAME}.${IMAGE_TYPE}.elf > disassembly.lst • At the end, the window should show: • Click OK to finish. 8. Run the project under the debugger again. When the breakpoint fires verify that the address is the same as before. Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part II: Debugging With Your Project © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 18 9. Now we need to examine the disassembly.lst file that was just generated. This file is located in the ./heartbeat/firmware/heartbeat.X folder. Load the file with your favorite text editor and search for 9D0025D8 (or the address you found) in the listing. The following example illustrates what you should see: void HEARTBEAT_Initialize ( void ) { 9d0025b4: 27bdfff0 addiu sp,sp,-16 9d0025b8 <.LCFI0>: 9d0025b8: afbe000c sw s8,12(sp) 9d0025bc: 03a0f021 move s8,sp 9d0025c0 <.LBB2>: // Test out error handling under Optimization Level Zero for system_init.c { uint8_t x, y, z; x = 1; 9d0025c0: 24020001 li v0,1 9d0025c4: a3c20000 sb v0,0(s8) 9d0025c8 <.LVL0>: y = 0; 9d0025c8: a3c00001 sb zero,1(s8) 9d0025cc <.LVL1>: z = x/y; 9d0025cc: 93c30000 lbu v1,0(s8) 9d0025d0: 93c20001 lbu v0,1(s8) 9d0025d4 <.LVL2>: 9d0025d4: 0062001b divu zero,v1,v0 9d0025d8: 004001f4 teq v0,zero,0x7 <----- Exception Address 9d0025dc: 00001010 mfhi v0 9d0025e0: 00001012 mflo v0 9d0025e4: a3c20002 sb v0,2(s8) 9d0025e8 <.LBE2>: } So the exception occurred during the assembly execution of the C instruction z = x/y, as expected. 10. Before proceeding, comment out the exception code in the heartbeat.c file. You could delete it from the file, but leaving it in as a comment provides a convenient way to validate that the exception handler is working; just uncomment and run to verify it still works as expected. 11. You should also remove the Override build options from heartbeat.c, returning it back to the projects default of Optimization Level One (-O1). Note: You might expect from the code in system_exceptions.c that it would also print out a message reporting the exception, but pressing and holding the Ctrl key while hovering your cursor reveals that SYS_DEBUG_PRINT is not defined, so nothing really happens in the code. Enabling this feature is discussed in the next tutorial. Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part III: Debugging While Running Stand-alone © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 19 Part III: Debugging While Running Stand-alone This section discusses how to debug problems when running without the debugger, including using diagnostic messages to a HyperTerminal or equivalent application on your computer. Description While the debugger in the MPLAB X IDE can help identify many bugs, there are cases where running the application outside of the debugger (i.e., Stand-alone mode), is necessary. The ability to dump error messages from failing asserts or from the exception handler is key to debugging an application outside of the debugger. Transmitting diagnostic or debug messages can also be key, both with and without the debugger. Getting Started Provides information on getting started with project debugging while running stand-alone. Description The steps outlined in this section can be applied to any MPLAB Harmony-based project, but for the sake of clarity we assume you have completed Part I: Creating Your First MPLAB Harmony Application in MHC. We will use the project from the this tutorial as the basis for this lesson. Board setup will be different than in the prior tutorials, primarily because of the need to support a USART connection to a COM port on your PC. Setting Up the Hardware PIC32MZ Embedded Connectivity (EF) Starter Kit Setting up this board is easy, since it has an on-board MCP2221A USART-to-USB Bridge. Therefore, all that is required to connect the device to a COM port is to plug in a mini-B to Type-A cable from the mini-B port beneath the Ethernet PHY to a USB port on your PC. PIC32 USB Starter Kit III As an older board design, there is no MCP2221A on this board, so you will need the following additional hardware: • MCP2221 Breakout Module (ADM00559) • Mini-B to Type-A USB cable for the Breakout Module • Starter Kit I/O Expansion Board (DM320002) • Jumper Wires • 0.1” Pitch Header Pins to connect jumpers between the breakout module and I/O expansion board. The hardware is set up as follows: Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part III: Debugging While Running Stand-alone © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 20 Explorer 16 Development Board with the PIC32MX795F512L Plug-in Module (PIM) As an older board design, there is no MCP2221A on this board, so you will need the following additional hardware: • MCP2221 Breakout Module (ADM00559) • Mini-B to Type-A USB cable for the Breakout Module • Prototype PICTail Plus Daughter Board (AC164126 for a three pack) • Jumper Wires • 0.1” Pitch Header Pins to connect jumpers between the breakout module and I/O expansion board. The hardware is set up as follows: Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part III: Debugging While Running Stand-alone © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 21 What You Will Learn • How the MPLAB Harmony Configurator (MHC) configures USARTs and device pins for USARTS • How MHC configures the Console System Service and the Debug System Service to support output via a USART • How to output diagnostic and debug messages via these system services • How to customize the assert handler and exception handler used in the application Tutorial Steps This part of the tutorial explores how to debug when running without the debugger (i.e., stand-alone). Enabling USART Output Using System Console and Debug System Services This section describes how to set up the System Console and Debug System Services using a USART port. Description 1. Launch the MPLAB X IDE and load the project you created in the Part I: Creating Your First MPLAB Harmony Application in MHC. 2. Set the project as the IDE’s Main Project and launch the MPLAB Harmony Configurator (MHC). 3. If you are using a board with a built-in MCP2221A USART-to-USB Bridge, in the BSP Configuration enable the USART-to-USB Bridge. This will assign device pins for use by the USART connected to the bridge. 4. Within Harmony Framework Configuration > Drivers > USART, configure USART 2. Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part III: Debugging While Running Stand-alone © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 22 Note: There are many options on how the USART driver is configured, but the simplest is always the best in this situation, since the USART must work after an assert has failed or an exception has fired. Therefore, the simplest set up is best. 5. Within Harmony Framework Configuration > System Services, configure the application to use the Console System Service. (The STATIC configuration is hard-wired to use USART Driver Instance 0 (the first one defined), which we set up in the previous step. To use another USART Driver Instance you must use the DYNAMIC service mode.) Again, the simplest setup is the best approach to handle asserts and exceptions. 6. Also under System Services, configure the application to use the Debug System Service. Set the System Error Level to SYS_ERROR_DEBUG to support SYS_DEBUG_PRINT. The pull-down menu for System Error Level has the options shown in the second figure. Note: The System Error Level determines which SYS_DEBUG_PRINT messages are actually printed on the USART port. Set to SYS_ERROR_DEBUG, all levels are printed. 7. Open the Pin Settings Tab in MHC. For boards with a MCP2221A, verify that the BSP has correctly set the USART pins. For boards without a MCP2221A, set the USART pins as shown. (Click the Function column to select the correct pin function.) • PIC32 USB Starter Kit III: Pin Number Pin ID Voltagea Tolerance Name Function 49 RF4 5V U2RX U2RX 50 RF5 5V U2TX U2TX • PIC32MZ EF Starter Kit: Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part III: Debugging While Running Stand-alone © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 23 Pin Number Pin ID Voltagea Tolerance Name Function 14 RG6 N/A USART-to-USB Bridge (USB) U2RX 61 RB14 N/A USART-to-USB Bridge (BSP) U2TX • Explorer 16 Development Board with PIC32MX795F512L Plug In Module: Pin Number Pin ID Voltagea Tolerance Name Function 49 RF4 5V U2RX U2RX 50 RF5 5V U2TX U2TX 8. Generate this new code configuration. For system_config.h, accept the changes, but do not discard the // CUSTOM CODE segment that you added in Part I: Creating Your First MPLAB Harmony Application in MHC. 9. Open heartbeat.c and add the following code shown in red to HEARTBEAT_Initialize. void HEARTBEAT_Initialize ( void ) { SYS_MESSAGE( "\r\nApplication created " __DATE__ " " __TIME__ " initialized!\r\n"); //Test out error handling // assert(0); // { // uint8_t x, y, z; // x = 1; // y = 0; // z = x/y; // SYS_DEBUG_PRINT(SYS_ERROR_DEBUG,"x: %d, y: %d, z: %d\r\n",x,y,z); // } /* Place the App state machine in its initial state. */ heartbeatData.state = HEARTBEAT_STATE_INIT; /* TODO: Initialize your application's state machine and other * parameters. */ } 10. Save the file by pressing Ctrl+S, and then close the window. Note: The portion of this addition that is commented can be uncommented to support testing that asserts and exceptions are correctly reported. Since we have enabled the Debug System Service, SYS_DEBUG_PRINT here actually works. Therefore, the compiler will not drop this this code when it is enabled, thereby eliminating the need to modify the code’s optimization level as before. 11. Set up your PC’s HyperTerminal to 115200 baud, 8 bits, 1 Stop Bit, No Parity. 12. Run the project. If you have correctly setup you HyperTerminal application you should see something similar to the following on its display: Application created Aug 8 2017 12:14:04 initialized! Getting the HyperTerminal to correctly identify the COM port belonging to the MCP2221A (either on-board or in a Breakout Module) can be a fussy and frustrating process. There will be times when you can’t find the COM port. In those cases, at least on a Windows PC, try the following: • In the Control Panel, select System > Device Manager • Within Ports (COM & LPT), identify the COM port belonging to the MCP2221A. Double click on this port to open its Properties window. • Select the Driver tab and disable, and then enable the driver • Close the window. This should allow your HyperTerminal to see the port. Note: If all else fails, you may need to put the SYS_DEBUG_PRINT statement in a while(1) loop and, worst case, use an oscilloscope to make sure the USART TX signal is getting to the MCP2221A and that the USB data lines are working as well. Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part III: Debugging While Running Stand-alone © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 24 If your board has a built-in MCP2221A but does not have an independent power supply, as with the PIC32MZ EF Starter Kit, where power is supplied by the debug port, you will not see the initial startup message when power cycling the application by unplugging and plugging in the debug port. When power is supplied to the board, the application starts, but the MCP2221A has to enumerate as a USB device with your PC before COM port output is accepted. So, the initial message has long since passed on the port before the COM port is working. If your board has a Master Clear (MCLR) button, you can simply press the button to reset the application after the MCP2221A enumerates. Then, the initial message will be seen on your HyperTerminal application. If your board does not have a MCLR button, you can still assert a Master Clear by grounding pin 1 of the ICSP header. The following figure show how this is done on the PIC32MZ EF Starter Kit. Adding Customized Assert and Exception Handling This section describes how to add customized assert and exception handling without a debugger. Description The default assert function provided by the PIC32 compiler is called _fassert. It is “weakly” defined, meaning that you can provide a customized replacement for it in your project. You may want to replace the default (compiler) assert for two reasons: • The default function is hardwired to use USART2 and you want to use another USART • You have a lot of asserts in your code, but do not need them to report out the line number, file name, failed expression, and function name in the message, because storing all of these string constants for every assert uses too much memory. Instead, you can invent a customized _fassert that only reports out, for example, only the line number and function name to save memory. The default exception handler is hardwired to USART2, so using MPLAB Harmony’s replacement handler, as we did in Part I: Creating Your First MPLAB Harmony Application in MHC, will at least give you the flexibility to control which USART is used. However, both handlers only report out the cause and program address of the exception, nothing more. Please note that there will be cases where this information is not sufficient to locate what went wrong. MHC provides two additional, advanced exception handlers that can be used instead. 1. The MHC menu Advanced Exception and Error Handling shows the options available. Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part III: Debugging While Running Stand-alone © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 25 2. Select the Advanced Harmony Exception Handler. (The other advanced handler shown supports filtering by saturating rather than overflowing integer arithmetic.) Select the MPLAB Harmony Assert Handler to replace the compiler’s built-in assert handler. By default, output uses SYS_DEBUG_PRINT, but using SYS_CONSOLE_Write can be chosen instead since it is a more robust way of reporting exceptions and errors. 3. Generate this configuration by clicking Generate Code. After completing this, your default project folder should contain the files shown in the following figure. Note the assembly (.S) file is required to report out extra information via the new exception handler. 4. Double click the new exception handler, general_exception_handler.c, to see what it reports. void __attribute__((nomips16)) _general_exception_handler (XCPT_FRAME* const pXFrame) { register uint32_t _localStackPointerValue asm("sp"); _excep_addr = pXFrame->epc; _excep_code = pXFrame->cause; // capture exception type _excep_code = (_excep_code & 0x0000007C) >> 2; _CP0_StatusValue = _CP0_GET_STATUS(); _StackPointerValue = _localStackPointerValue; _BadVirtualAddress = _CP0_GET_BADVADDR(); _ReturnAddress = pXFrame->ra; sprintf(msgBuffer,"**EXCEPTION:*\r\n" " ECode: %d, EAddr: 0x%08X, CPO Status: 0x%08X\r\n" " Stack Ptr: 0x%08X, Bad Addr: 0x%08X, Return Addr: 0x%08X\r\n" "**EXCEPTION:*\r\n", _excep_code,_excep_addr,_CP0_StatusValue, _StackPointerValue,_BadVirtualAddress,_ReturnAddress); SYS_CONSOLE_Write(SYS_CONSOLE_INDEX_0,STDOUT_FILENO,msgBuffer,strlen(msgBuffer)); SYS_DEBUG_BreakPoint(); // Stop here if in debugger. while(1) { //Do Nothing } } So, in addition to the cause (ECode) and address (EAddr) of the exception, this exception handler also reports the Core Register CP0 value (CPO Status), the Stack Pointer value (Stack Ptr), Bad Address value (Bad Addr), and the Return Address value (Return Addr). For more information on the bit fields in the CP0 register refer to one of these PIC32 Family Reference Manual sections: • PIC32MX: Section 02. "CPU for Devices with M4K Core" (DS6000113) • PIC32MK and PIC32MZ: Section 50. "CPU for Devices with microAptiv Core" (DS60001192) Both of these documents are available for download from the Microchip website at: www.microchip.com. 5. Add post processing to the project’s configuration to produce a disassembly listing. • Right click the project name and selecting Properties • Within the Building ( ) properties, enable Execute this line after build and enter the following text: • ${MP_CC_DIR}\xc32-objdump -S ${ImageDir}\${PROJECTNAME}.${IMAGE_TYPE}.elf > disassembly.lst • At the end the window should show: • Click OK to close the window 6. To explore how we can use the extra information reported by the new exception handler, make the following modifications shown in red text to heartbeat.c: void DivideByZero(void) { uint8_t x, y, z; x = 1; y = 0; Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part III: Debugging While Running Stand-alone © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 26 z = x/y; SYS_DEBUG_PRINT(SYS_ERROR_DEBUG,"x: %d, y: %d, z: %d\r\n",x,y,z); } void Dereference_Bad_Address(void) { uint32_t * pointer; uint32_t value; pointer = (uint32_t *)0xDEADBEEF; value = *pointer; SYS_DEBUG_PRINT(SYS_ERROR_DEBUG,"Value: %d\r\n",value); } void HEARTBEAT_Initialize ( void ) { SYS_MESSAGE( "\r\nApplication created " __DATE__ " " __TIME__ " initialized!\r\n"); // Test out error handling // assert(0); // { // uint8_t x, y, z; // x = 1; // y = 0; // z = x/y; // SYS_DEBUG_PRINT(SYS_ERROR_DEBUG,"x: %d, y: %d, z: %d\r\n",x,y,z); // } //assert(0); //DivideByZero(); //Dereference_Bad_Address(); /* Place the App state machine in its initial state. */ heartbeatData.state = HEARTBEAT_STATE_INIT; /* TODO: Initialize your application's state machine and other * parameters. */ } 7. Uncomment the //assert(0);, abd then build and run the application. In your HyperTerminal application, you should see something similar to the following: Application created Aug 8 2017 16:51:05 initialized! ASSERTION '0' FAILED! File: ../src/heartbeat.c, Line: 148, Function: HEARTBEAT_Initialize 8. Now comment out the assert and uncomment the call to DivideByZero, and then build and run. In your HyperTerminal application, you should see something similar to the following: Application created Aug 8 2017 16:37:51 initialized! **EXCEPTION:* ECode: 13, EAddr: 0x9D006CAC, CPO Status: 0x25000003 Stack Ptr: 0x8007FED8, Bad Addr: 0x25651D53, Return Addr: 0x9D007020 **EXCEPTION:* In the disassembly listing you will see: void DivideByZero(void) { uint8_t x, y, z; x = 1; y = 0; z = x/y; 9d006ca0: 24070001 li a3,1 Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part III: Debugging While Running Stand-alone © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 27 9d006ca4: 00001021 move v0,zero 9d006ca8: 00e2001b divu zero,a3,v0 9d006cac: 004001f4 teq v0,zero,0x7 <<------------------- EAddr 9d006cb0: 00003812 mflo a3 SYS_DEBUG_PRINT(SYS_ERROR_DEBUG,"x: %d, y: %d, z: %d\r\n",x,y,z); 9d006cb4: 3c049d00 lui a0,0x9d00 9d006cb8: 24846968 addiu a0,a0,26984 9d006cbc: 24050001 li a1,1 9d006cc0: 00003021 move a2,zero 9d006cc4: 0f4015fd jal 9d0057f4 9d006cc8: 30e700ff andi a3,a3,0xff 9d006ccc <.LVL2>: } //assert(0); DivideByZero(); 9d007018: 0f401b22 jal 9d006c88 <.LFE1152> 9d00701c: 00000000 nop 9d007020 <.LVL9>: <<------------ Return Address //Dereference_Bad_Address(); /* Place the App state machine in its initial state. */ heartbeatData.state = HEARTBEAT_STATE_INIT; 9d007020: af808054 sw zero,-32684(gp) <<---- Return Address In this example we see, as before, that the exception address correctly identifies the instruction that caused the exception. Note also that the return address points to the instruction after the call to the DivideByZero function. Note: The actual addresses may vary depending on the target device. 9. Now comment out the DivideByZero and uncomment the call to Dereference_Bad_Address, and then build and run. In your HyperTerminal application you should see something similar to the following: Application created Aug 8 2017 16:43:01 initialized! **EXCEPTION:* ECode: 4, EAddr: 0x9D006F38, CPO Status: 0x25000003 Stack Ptr: 0x8007FED8, Bad Addr: 0xDEADBEEF, Return Addr: 0x9D006F40 **EXCEPTION:* In the disassembly listing you will see: void Dereference_Bad_Address(void) { 9d006f24: 27bdffe8 addiu sp,sp,-24 9d006f28: afbf0014 sw ra,20(sp) 9d006f2c: afb00010 sw s0,16(sp) uint32_t * pointer; uint32_t value; pointer = (uint32_t *)0xDEADBEEF; value = *pointer; 9d006f30: 3c02dead lui v0,0xdead 9d006f34: 3442beef ori v0,v0,0xbeef 9d006f38 <.LVL4>: <<------------ EAddr SYS_DEBUG_PRINT(SYS_ERROR_DEBUG,"Value: %d\r\n",value); 9d006f38: 0f40003e jal 9d0000f8 <.LFE1164> 9d006f3c: 8c500000 lw s0,0(v0) 9d006f40 <.LVL5>: <<----- Return Address 9d006f40: 10400006 beqz v0,9d006f5c <.LVL6+0x4> <<-- 9d006f44: 8fbf0014 lw ra,20(sp) 9d006f48: 3c049d00 lui a0,0x9d00 9d006f4c: 24846980 addiu a0,a0,27008 9d006f50: 0f4015fd jal 9d0057f4 9d006f54: 02002821 move a1,s0 9d006f58 <.LVL6>: } Volume I: Getting Started With MPLAB Harmony Creating Your First Project Part III: Debugging While Running Stand-alone © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 28 The exception code reported, 4, corresponds to an “address error exception (load or ifetch)”. In this example, the return address didn’t provide much information but we see that the bad address used in the pointer dereference was correctly reported. As an additional step, replace value = *pointer with *pointer = value in the code and verify that an exception code of 5, “address error exception (store)”, is reported instead. Tips Provides tips for effective use. Description Warnings All Compiler Switch It is recommended that you enable the compiler switch, –Wall (Warnings-All), for your project. This will warn you of potential problems that may turn into bugs. In the configuration’s properties, select the compiler compiler and select Additional Warnings. Project Locations on Your Hard Drive In the first tutorial of this series, the project was created in the following folder (for Windows): C:\microchip\harmony\\apps. In reality, you can create a MPLAB Harmony project anywhere on the same hard drive that contains the MPLAB Harmony installation you are using. For MAC OS and Linux, that is the only limitation. For Windows, there is an operating system limitation that all paths in the project must be less than 256 characters in length. Therefore, you may run into trouble on Windows if the project is created too deep into the drive’s directory tree. Moving and Copying Projects All of files in your project are referenced by their relative path from the “.X” directory (heartbeat\firmware\heartbeat.X), which contains the Makefile make file and nbproject sub-directory. This provides flexibility in relocating and copying projects, since as long as the relative paths to files in the MPLAB Harmony installation (typically C:\microchip\harmony\) still work the project can be anywhere. Example You can move/copy a project: • Old Location: C:\MyWork\MyProject\heartbeat • New Location: C:\MyWork\MyNewProject\heartbeat (Good) However, neither of these new locations work, since it breaks the project’s relative paths: • Old Location: C:\MyWork\MyProject\heartbeat • New Location: C:\MyProject\heartbeat (Not Good), or • New Location: C:\MyWork \MyNewProject\Rev2\heartbeat (Not Good) Next Steps Provides information on where to find additional resources. Description To learn more about MPLAB Harmony, refer to Volume I: Getting Started With MPLAB Harmony > What is MPLAB Harmony? Revisit Volume I: Getting Started With MPLAB Harmony > Guided Tour for suggestions on where to begin learning more. Try an existing MPLAB Harmony demonstration that runs on a PIC32MZ EF Starter Kit: Peripheral Examples (/apps/examples/): Volume I: Getting Started With MPLAB Harmony Creating Your First Project Next Steps © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 29 peripheral Basic Bootloader (/apps/bootloader/): basic Graphics with MEB II Display (/apps/gfx/): • aria_quickstart • aria_showcase • aria_weather_forecast TCP/IP Stack (/apps/tcpip/): • tcpip_client_server • tcpip_tcp_server • tcpip_udp_client • tcpip_udp_client_server • tcpip_udp_server USB Device (/apps/usb/device/): • cdc_msd_basic • cdc_serial_emulator • hid_basic • hid_joystick • hid_msd_basic • msd_basic • hid_mouse USB Host (/apps/usb/host): • audio_speaker • cdc_basic • cdc_msd • hid_basic_keyboard • hid_basic_mouse_usart • hub_msd • msd_basic Volume I: Getting Started With MPLAB Harmony Creating Your First Project Next Steps © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 30 Index A Adding Customized Assert and Exception Handling 25 Asserts Under the Debugger 14 C Creating Your First Project 3 Overview 3 E Enabling USART Output Using System Console and Debug System Services 22 Exception Handling in the Debugger 17 G Getting Started 3, 14, 20 N Next Steps 29 O Overview 3, 14 P Part I: Creating Your First MPLAB Harmony Application in MHC 3 Part II: Debugging With Your Project 14 Part III: Debugging While Running Stand-alone 20 S Step 1: Setting Up Your Hardware 3 Step 2: Create a New MPLAB X IDE Project 4 Step 3: Configure MPLAB Harmony and the Application 5 Step 4: Generate the Configured Source Code 6 Step 5: Use a Delay Timer to Toggle an LED on the Target Board 7 Step 6: Add the Timer System Service to Your Project 8 Step 7: Add the Timer System Service Source Code to Your Project 9 Step 8: Use the Timer System Service in Your Application 10 Step 9: Build and Run Your Project 13 T Tips 29 Tutorial Steps 3, 14, 22 V Volume I: Getting Started With MPLAB Harmony Libraries and Applications 2 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 31

 2004 Microchip Technology Inc. DS51471A dsPICDEM.net™ 1 and dsPICDEM.net™ 2 Connectivity Development Board User’s Guide DS51471A-page ii  2004 Microchip Technology Inc. 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, under any intellectual property rights. Trademarks The Microchip name and logo, the Microchip logo, Accuron, dsPIC, KEELOQ, microID, MPLAB, PIC, PICmicro, PICSTART, PRO MATE, PowerSmart, rfPIC, and SmartShunt are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. AmpLab, FilterLab, MXDEV, MXLAB, PICMASTER, SEEVAL, SmartSensor and The Embedded Control Solutions Company are registered trademarks of Microchip Technology Incorporated in the U.S.A. Analog-for-the-Digital Age, Application Maestro, dsPICDEM, dsPICDEM.net, dsPICworks, ECAN, ECONOMONITOR, FanSense, FlexROM, fuzzyLAB, In-Circuit Serial Programming, ICSP, ICEPIC, Migratable Memory, MPASM, MPLIB, MPLINK, MPSIM, PICkit, PICDEM, PICDEM.net, PICLAB, PICtail, PowerCal, PowerInfo, PowerMate, PowerTool, rfLAB, rfPICDEM, Select Mode, Smart Serial, SmartTel and Total Endurance are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. 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. © 2004, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved. Printed on recycled paper. Note the following details of the code protection feature on Microchip devices: • Microchip products meet the specification contained in their particular Microchip Data Sheet. • Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the intended manner and under normal conditions. • There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data Sheets. Most likely, the person doing so is engaged in theft of intellectual property. • Microchip is willing to work with the customer who is concerned about the integrity of their code. • Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not mean that we are guaranteeing the product as “unbreakable.” Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of our products. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such acts allow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act. Microchip received ISO/TS-16949:2002 quality system certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona and Mountain View, California in October 2003. The Company’s quality system processes and procedures are for its PICmicro® 8-bit MCUs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and analog products. In addition, Microchip’s quality system for the design and manufacture of development systems is ISO 9001:2000 certified. dsPICDEM.net™ 1 AND dsPICDEM.net 2 CONNECTIVITY DEVELOPMENT BOARD USER’S GUIDE  2004 Microchip Technology Inc. DS51471A-page iii Table of Contents Preface ........................................................................................................................... 1 Chapter 1. Introduction 1.1 Introduction ..................................................................................................... 7 1.2 Highlights ........................................................................................................ 7 1.3 Overview ........................................................................................................ 7 1.4 dsPICDEM.net Package Contents ................................................................. 8 1.5 dsPICDEM.net Board Functionality ................................................................ 8 1.6 dsPICDEM.net Demonstration Programs ..................................................... 10 1.7 Reference Documents .................................................................................. 11 Chapter 2. Tutorial 2.1 Introduction ................................................................................................... 13 2.2 Highlights ...................................................................................................... 13 2.3 Tutorial Overview ......................................................................................... 13 2.4 Creating the Project ...................................................................................... 13 2.5 Building the Code ......................................................................................... 19 2.6 Device Configuration and Programming ...................................................... 22 2.7 Debugging the Code .................................................................................... 27 2.8 Summary ...................................................................................................... 30 Chapter 3. Quick Start Program 3.1 Introduction ................................................................................................... 31 3.2 Highlights ...................................................................................................... 31 3.3 Quick Start Program Overview ..................................................................... 31 3.4 Creating the Project ...................................................................................... 32 3.5 Building the Code ......................................................................................... 38 3.6 Device Configuration and Programming ...................................................... 40 3.7 Interacting with the Code .............................................................................. 45 3.8 Quick Start Demonstration Features and Peripherals .................................. 45 3.9 Data and Control Flow .................................................................................. 46 3.10 Summary .................................................................................................... 48 Chapter 4. HTTP Web Server Demonstration 4.1 Introduction ................................................................................................... 49 4.2 Highlights ...................................................................................................... 49 4.3 Demonstration Overview .............................................................................. 49 4.4 Demonstration Setup .................................................................................... 50 4.5 Configuring your Laptop or Desktop PC ....................................................... 51 4.6 HTTP Web Server Demonstration ............................................................... 52 dsPICDEM.net 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page iv  2004 Microchip Technology Inc. 4.7 Debugging Tips ............................................................................................ 57 4.8 Troubleshooting ........................................................................................... 58 4.9 Using HTTP Web Server in Your Application ............................................... 59 Chapter 5. FTP Server 5.1 Introduction ................................................................................................... 61 5.1 Highlights ...................................................................................................... 61 5.2 Application Overview .................................................................................... 61 5.3 Demonstration Setup .................................................................................... 62 5.4 Configuring your Laptop or Desktop PC ....................................................... 63 5.5 FTP Server Demonstration ........................................................................... 64 5.6 Summary ...................................................................................................... 70 Chapter 6. V.22bis Soft Modem Demonstration 6.1 Introduction ................................................................................................... 71 6.1 Highlights ...................................................................................................... 71 6.2 Demonstration Overview .............................................................................. 71 6.3 Demonstration Configurations ...................................................................... 72 6.4 Demonstration Procedures ........................................................................... 74 6.5 Reprogramming the dsPIC30F6014 ............................................................. 76 6.6 Description of dsPIC30F Soft Modem .......................................................... 78 6.7 dsPIC30F Soft Modem AT Command Set ................................................... 79 6.8 Troubleshooting the Connection .................................................................. 81 6.9 Regulatory Compliance Reference Information ........................................... 84 6.10 ITU-T Specifications ................................................................................... 86 Chapter 7. dsPICDEM.net Development Hardware 7.1 dsPICDEM.net Hardware Components ........................................................ 87 Appendix A. Hardware Schematics A.1 Board Layout and Schematics ..................................................................... 93 Index ...........................................................................................................................107 Worldwide Sales and Service ...................................................................................109  2004 Microchip Technology Inc. DS51471A-page 1 dsPICDEM.net™ 1 AND dsPICDEM.net 2 CONNECTIVITY DEVELOPMENT BOARD USER’S GUIDE Preface INTRODUCTION This user’s guide supports the dsPICDEM.net 1 and dsPICDEM.net 2 connectivity development boards. These boards provide basic platforms that enable the application developer to create and evaluate both connectivity and non-connectivity based solutions. This chapter previews the contents of the manual, tells you how to obtain valuable customer support and recommends useful reference information. HIGHLIGHTS Items discussed in this chapter are: • About This Guide • Warranty Registration • Recommended Reading • The Microchip Web Site • Development Systems Customer Notification Service • Customer Support ABOUT THIS GUIDE This user’s guide describes how to use the dsPICDEM.net 1 and dsPICDEM.net 2 connectivity development boards. The document is organized as follows: • Chapter 1: Introduction – This chapter introduces the dsPICDEM.net 1 and dsPICDEM.net 2 connectivity development board and provides a brief description of the hardware. • Chapter 2: Tutorial – This chapter presents a step-by-step process for getting your dsPICDEM.net 1 and dsPICDEM.net 2 connectivity development board up and running with the MPLAB® In-Circuit Debugger 2 (MPLAB ICD 2). • Chapter 3: Quick Start Program – This chapter describes the operational functionality of a demonstration program included on the dsPICDEM.net Development Kit Software CD. The demonstration program exercises several capabilities of the dsPIC30F by interacting with peripheral devices on the development board. • Chapter 4: HTTP Web Server Demonstration – This chapter describes the operational functionality of a sample HTTP Web Server based embedded application that is included on the dsPICDEM.net Development Kit Software CD. • Chapter 5: FTP Server Demonstration – This chapter describes the operational functionality of a sample FTP Server based embedded application that is included on the dsPICDEM.net Development Kit Software CD. • Chapter 6: V.22bis Soft Modem Demonstration – This chapter describes the operational functionality of a sample PSTN based application that is preprogrammed into the dsPIC30F6014 device. • Chapter 7: dsPICDEM.net™ Development Hardware – This chapter describes the hardware included on the of the dsPICDEM.net 1 and dsPICDEM.net 2 boards. • Appendix A: Hardware Schematics – This Appendix contains hardware layout and schematic diagrams of the dsPICDEM.net 1 and dsPICDEM.net 2. PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 2  2004 Microchip Technology Inc. Conventions Used in This Guide This User's Guide uses the following documentation conventions: DOCUMENTATION CONVENTION Documentation Updates All documentation becomes dated, and this user’s guide is no exception. Since Microchip tools are constantly evolving to meet customer needs, some actual dialogs and/or tool descriptions may differ from those in this document. Please refer to our web site to obtain the latest documentation available. Documentation Numbering Conventions Documents are numbered with a “DS” number. The number is located on the bottom of each page, in front of the page number. The numbering convention for the DS Number is DSXXXXXA, where: WARRANTY REGISTRATION Please complete the enclosed Warranty Registration Card and mail it promptly. Sending in your Warranty Registration Card entitles you to receive new product updates. Interim software releases are available at the Microchip web site. Description Represents Examples Code (Courier font): Plain characters Sample code Filenames and paths #define START c:\autoexec.bat Angle brackets: < > Variables , Square brackets [ ] Optional arguments pic30-as [main.s] Curly brackets and pipe character: { | } Choice of mutually exclusive arguments; an OR selection errorlevel {0|1} Lower case characters in quotes Type of data "filename" Ellipses... Used to imply (but not show) additional text that is not relevant to the example list ["list_option..., "list_option"] 0xnnn A hexadecimal number where n is a hexadecimal digit 0xFFFF, 0x007A Italic characters A variable argument; it can be either a type of data (in lower case characters) or a specific example (in upper case characters) char isascii (char, ch); Interface (Arial font): Underlined, italic text with right arrow A menu selection from the menu bar File > Save Bold characters A window or dialog button to click OK, Cancel Characters in angle brackets < > A key on the keyboard , Documents (Arial font): Italic characters Referenced books MPLAB IDE User’s Guide XXXXX = The document number. A = The revision level of the document. Preface  2004 Microchip Technology Inc. DS51471A-page 3 RECOMMENDED READING This user’s guide describes how to use the dsPICDEM.net 1 and dsPICDEM.net 2 Connectivity Development Board. Other useful documents include: dsPIC30F Family Reference Manual (DS70046) Consult this document for detailed information on dsPIC30F device operation. This reference manual explains the operation of the dsPIC30F MCU family architecture and peripheral modules but does not cover the specifics of each device. Refer to the appropriate device data sheet for device-specific information. dsPIC30F Data Sheet, Motor Control and Power Conversion Family (DS70082) Consult this document for detailed information on the dsPIC30F Motor Control and Power Conversion devices. Reference information found in this data sheet includes: • Device memory map • Device pinout and packaging details • Device electrical specifications • List of peripherals included on the device dsPIC30F Data Sheet, General Purpose and Sensor Families (DS70083) Consult this document for detailed information on the dsPIC30F Sensor and General Purpose devices. Reference information found in this data sheet includes: • Device memory map • Device pinout and packaging details • Device electrical specifications • List of peripherals included on the device dsPIC30F5011, dsPIC30F5013 Data Sheet, High Performance Digital Signal Controllers (DS70116) This data sheet contains specific information for the dsPIC30F5011/5013 Digital Signal Controller (DSC) devices. dsPIC30F6011, dsPIC30F6012, dsPIC30F6013, dsPIC30F6014 Data Sheet, High Performance Digital Signal Controllers (DS70117) This data sheet contains specific information for the dsPIC30F6011/6012/6013/6014 Digital Signal Controller (DSC) devices. dsPIC30F Programmer’s Reference Manual (DS70030) This manual is a software developer’s reference for the dsPIC30F 16-bit MCU family of devices. This manual describes the instruction set in detail and also provides general information to assist you in developing software for the dsPIC30F MCU family. dsPIC30F Family Overview (DS70043) This document provides an overview of the functionality of the dsPIC® product family. It helps determine how the dsPIC30F 16-bit Digital Signal Controller Family fits a specific product application. This document is a supplement to the dsPIC30F Family Reference Manual. MPLAB® ASM30, MPLAB® LINK30 and Utilities User's Guide (DS51317) This document helps you use Microchip Technology’s language tools for dsPIC devices based on GNU technology. The language tools discussed are: • MPLAB ASM30 Assembler • MPLAB LINK30 Linker • MPLAB LIB30 Archiver/Librarian • Other Utilities PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 4  2004 Microchip Technology Inc. MPLAB C30 C Compiler User’s Guide (DS51284) This document details the use of Microchip’s MPLAB C30 C Compiler for dsPIC devices to develop an application. MPLAB C30 is a GNU-based language tool, based on source code from the Free Software Foundation (FSF). For more information about the FSF, see www.fsf.org. Other GNU language tools available from Microchip are: • MPLAB ASM30 Assembler • MPLAB LINK30 Linker • MPLAB LIB30 Librarian/Archiver dsPIC™ Language Tools Libraries (DS51456) DSP, dsPIC peripheral and standard (including math) libraries for use with dsPIC language tools. GNU HTML Documentation This documentation is provided on the language tool CD-ROM. It describes the standard GNU development tools, upon which these tools are based. MPLAB® IDE Simulator, Editor User’s Guide (DS51025) Consult this document for more information pertaining to the installation and implementation of the MPLAB Integrated Development Environment (IDE) Software. To obtain any of these documents, visit the Microchip web site at www.microchip.com. THE MICROCHIP WEB SITE Microchip provides online support on the Microchip World Wide Web (WWW) site. The web site is used by Microchip as a means to make files and information easily available to customers. To view the site, you must have access to the Internet and a web browser, such as, Netscape® Navigator or Microsoft® Internet Explorer. The Microchip web site is available at:www.microchip.com. The web site provides a variety of services. Users may download files for the latest development tools, data sheets, application notes, user's guides, articles and sample programs. A variety of information specific to the business of Microchip is also available, including listings of Microchip sales offices, distributors and factory representatives. Technical Support • Frequently Asked Questions (FAQ) • Online Discussion Groups – conferences for products, development systems, technical information and more • Microchip Consultant Program Member Listing • Links to other useful web sites related to Microchip products Engineer’s Toolbox • Design Tips • Device Errata Other Available Information • Latest Microchip Press Releases • Listing of Seminars and Events • Job Postings Preface  2004 Microchip Technology Inc. DS51471A-page 5 DEVELOPMENT SYSTEMS CUSTOMER NOTIFICATION SERVICE Microchip started the customer notification service to help our customers stay current on Microchip products with the least amount of effort. Once you subscribe, you will receive E-mail notification whenever we change, update, revise or have errata related to your specified product family or development tool of interest. Go to the Microchip web site at (www.microchip.com) and click on Customer Change Notification. Follow the instructions to register. The Development Systems product group categories are: • Compilers • Emulators • In-Circuit Debuggers • MPLAB • Programmers Here is a description of these categories: Compilers – The latest information on Microchip C compilers and other language tools. These include the MPLAB C17, MPLAB C18 and MPLAB C30 C compilers; MPASM™ and MPLAB ASM30 assemblers; MPLINK™ and MPLAB LINK30 object linkers; MPLIB™ and MPLAB LIB30 object librarians. Emulators – The latest information on Microchip in-circuit emulators. This includes the MPLAB ICE 2000 and MPLAB ICE 4000. In-Circuit Debuggers – The latest information on Microchip in-circuit debuggers. These include the MPLAB ICD and MPLAB ICD 2. MPLAB – The latest information on Microchip MPLAB IDE, the Windows Integrated Development Environment for development systems tools. This list is focused on the MPLAB IDE, MPLAB SIM and MPLAB SIM30 simulators, MPLAB IDE Project Manager and general editing and debugging features. Programmers – The latest information on Microchip device programmers. These include the PRO MATE® II device programmer and PICSTART® Plus development programmer. PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 6  2004 Microchip Technology Inc. CUSTOMER SUPPORT Users of Microchip products can receive assistance through several channels: • Distributor or Representative • Local Sales Office • Field Application Engineer (FAE) • Corporate Applications Engineer (CAE) • Hotline Customers should call their distributor, representative or field application engineer (FAE) for support. Local sales offices are also available to help customers. See the sales offices and locations listed on the back of this publication. Corporate Applications Engineers (CAEs) may be contacted at (480) 792-7627. In addition, there is a Systems Information and Upgrade Line. This line provides system users a listing of the latest versions of all of Microchip's development systems software products. Plus, this line provides information on how customers can receive any currently available upgrade kits. The Hotline Numbers are: 1-800-755-2345 for U.S. and most of Canada. 1-480-792-7302 for the rest of the world.  2004 Microchip Technology Inc. DS51471A-page 7 dsPICDEM.net™ 1 AND dsPICDEM.net 2 CONNECTIVITY DEVELOPMENT BOARD USER’S GUIDE Chapter 1. Introduction 1.1 INTRODUCTION This chapter introduces several connectivity capabilities that can easily be implemented with the use of the dsPICDEM.net Connectivity Development Board. 1.2 HIGHLIGHTS This chapter discusses: • Overview • dsPICDEM.net Package Contents • dsPICDEM.net Board Functionality • dsPICDEM.net Demonstration Programs • Reference Documents 1.3 OVERVIEW The dsPICDEM.net 1 and dsPICDEM.net 2 connectivity development boards are tools designed to help the application developer create and evaluate both connectivity and non-connectivity based solutions using dsPIC30F High Performance Digital Signal Controllers. The dsPICDEM.net 1 board supports the Federal Communications Commission (FCC) and Japan Approval Institute for Telecommunications Equipment (JATE) country specific Public Switched Telephone Network (PSTN). The dsPICDEM.net 2 board supports the Common Technical Regulation 21 (CTR-21) PSTN. Both boards support the Realtek 10-base T Ethernet Network Interface Controller (NIC). Every country has telecommunication laws that prohibit the connection of unapproved telecommunication devices, including modems, to the phone line. Approval by a country's telecommunications regulatory agency may entail hardware/firmware modifications to your end-system modem in order to comply with their telecommunication laws relative to radio-frequency interference, pulse dial make/break ratios, redial capabilities, etc. The words “approved or compliant for use in country XYZ” mean that the modem has been modified to comply with the telecommunication laws of that country. Thus, a modem approved by the FCC to work in the USA, for example, is not automatically approved by the BZT to work in Germany. Note: For the sample applications described in this manual, connect to an analog line only. You could damage the modem if you use a non-analog line (e.g., digital or PBX multiline). PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 8  2004 Microchip Technology Inc. The boards come with an ITU-T compliant V.22bis/V.22 modem module and demonstration code pre-programmed on the installed dsPIC30F6014 device. This sample application lets you to connect and transfer data between the dsPIC30F Soft Modem and an ITU-T compliant reference modem. Application source code is included on the supplied development kit software CD. The Development Kit Software CD also includes additional sample applications, a tutorial module and complete product documentation. The additional sample applications will familiarize you with the CMX-MicroNet HTTP Web and FTP Servers, which demonstrate two TCP/IP protocol based applications over the 10-Base T Ethernet Datalink layer. Product tutorials provide hands-on experience in debugging with the MPLAB ICD 2. 1.4 dsPICDEM.net PACKAGE CONTENTS The following items comprise the dsPICDEM.net Connectivity Development Board package: • The dsPICDEM.net 1 or dsPICDEM.net 2 Printed Circuit Board (supports both embedded internet and ethernet connections). • A pre-programmed dsPIC30F6014 device on an adapter board that plugs into the main development board • A CAT5 “crossover” network cable (RJ45 connectors) for networking the board. • 9 VDC Power Supply • RS-232 Interface Cable • dsPICDEM.net Development Kit Software CD containing demonstration connectivity solutions from Microchip and it’s partners along with a product tutorial and complete documentation. 1.5 dsPICDEM.net BOARD FUNCTIONALITY The dsPICDEM.net Development Board (Figure 1-1) provides a basic platform for developing and evaluating solutions that use dsPIC30F6014 16-bit Digital Signal Controllers. The dsPICDEM.net Development Board includes the following capabilities: Power Supply • Single on-board +5V regulator for VDD and AVDD with direct input from 9V, AC/DC wall adapter • 9 VDC power source input jack for development board • Power-on indicator LED MPLAB ICD 2 and ICE 4000 Connections • MPLAB ICD 2 programming connector • Emulation header connection to MPLAB ICE 4000 • Pad location for 80-pin TQFP dsPIC device Serial Communication Channels • Single RS-232 communication channel • 6-pin terminal block and configuration jumper for RS-485 and RS-422 communication on UART1 from the dsPIC device • Single CAN communication channel Introduction  2004 Microchip Technology Inc. DS51471A-page 9 Public-Switched Telephone Network (PSTN) • Silicon Laboratories Si3035 DAA/AFE chipset (dsPICDEM.net 1 board) • Silicon Laboratories Si3034 DAA/AFE chipset (dsPICDEM.net 2 board) • Speaker for monitoring call progress • Si3021 reset push button switch FIGURE 1-1: dsPICDEM.net DEVELOPMENT BOARD 10-BaseT Ethernet • Realtek RTL8019AS 10-Base T single-chip Network Interface Controller and transceiver • Four link status LEDs • RJ-45 (10-Base T) modular connector Analog • Two 5 kΩ Potentiometers (RP1 and RP2) • Microchip MCP42050 Digital Potentiometer (dual-channel output) • Microchip TC1047A Thermal Sensor (U2) • Microchip MCP602 op amp configured as low-pass filter for thermal sensor (U12) Device Clocking • 7.3728 MHz crystal, X3, for dsPIC device • Socket U16, clock oscillator for dsPIC device (alternate clock source, X3 removed) • Pad for 32.768 kHz crystal (XTAL2) and load caps PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 10  2004 Microchip Technology Inc. Miscellaneous • Reset push button switch • Three red LEDs (LED1-LED3) • Three push button switches (S1-S3) for external input stimulus • 64k x 16 External SRAM • Microchip 24LC515 Serial EE memory device • 2 x 16 character LCD • 2 x 50 prototyping header for user hardware expansion (header not installed) • Prototype area for user hardware 1.6 dsPICDEM.net DEMONSTRATION PROGRAMS The dsPICDEM.net Development Board is supplied with several sample application programs for the dsPIC30F6014 to help you jump-start your own solutions. You will need the MPLAB C30 Compiler to program these applications into the dsPIC30F device. You can download a full-featured 60-day trial version of MPLAB C30 from the Microchip web site (www.microchip.com). Follow the download links under Products/Development Tools/Software. Source code is provided on the Development Kit Software CD for all these demonstration programs: • Tutorial – The tutorial introduces the new user to the basic skills needed to work with the dsPIC30F. It provides step-by-step instructions for programming the dsPIC30F chip with the MPLAB IDE and MPLAB C30 and debugging the program with the MPLAB ICD 2. See Chapter 2. “Tutorial”. • dsPIC30F Quick Start – Building on the tutorial, the dcPIC30F demonstration uses a sample application to illustrate functionality of the dsPIC30F and its peripherals interacting with components on the dsPICDEM.net board. This application is described fully in Chapter 3. “Quick Start Program”. • HTTP Web Server Demonstration – This sample application illustrates an embedded web server that supports remote monitoring and control over a 10-Base T Ethernet connection. This demonstration program uses the CMX-MicroNet TCP/IP Stack configured for HTTP Web Server protocol. This sample application is described fully in Chapter 4. “HTTP Web Server Demonstration”. • FTP Server Demonstration – This demonstration illustrates an embedded FTP server application that provides remote monitoring and control over a 10-Base T Ethernet connection. This sample application uses the CMX-MicroNet TCP/IP Stack configured for FTP Server protocol. This demonstration is described fully in Chapter 5. “FTP Server Demonstration”. • V.22bis Soft Modem Demonstration – The dsPIC30F6014 plug-in device is pre-programmed with an ITU-T compliant V.22bis/V.22 modem demonstration that lets you to connect and transfer data between the dsPIC30F Soft Modem and an ITU-T compliant reference modem. This demonstration is described fully in Chapter 6. “V.22bis Soft Modem Demonstration”. Introduction  2004 Microchip Technology Inc. DS51471A-page 11 1.7 REFERENCE DOCUMENTS The following documentation is available to support your use of the dsPICDEM.net Development Board: • dsPIC30F Family Reference Manual (DS70046) • dsPIC30F Data Sheet, Motor Control and Power Conversion Family (DS70082) • dsPIC30F Data Sheet, General Purpose and Sensor Families (DS70083) • dsPIC30F5011, dsPIC30F5013 Data Sheet, High Performance Digital Signal Controllers (DS70116) • dsPIC30F6011, dsPIC30F6012, dsPIC30F6013, dsPIC30F6014 Data Sheet, High Performance Digital Signal Controllers (DS70117) • dsPIC30F Programmer’s Reference Manual (DS70030) • dsPIC High Performance 16-bit Digital Signal Controller Family Overview (DS70043) • MPLAB C30 C Compiler User’s Guide (DS51284) • MPLAB ASM30, MPLAB LINK30 and Utilities User’s Guide (DS51317) • MPLAB ICD 2 In-Circuit Debugger Quick Start Guide (DS51268) • MPLAB ICE Emulator User’s Guide (DS51159) You can obtain these reference documents from your nearest Microchip sales office (listed in the back of this document) or by downloading them from the Microchip web site (www.microchip.com). PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 12  2004 Microchip Technology Inc. NOTES:  2004 Microchip Technology Inc. DS51471A-page 13 dsPICDEM.net™ 1 AND dsPICDEM.net 2 CONNECTIVITY DEVELOPMENT BOARD USER’S GUIDE Chapter 2. Tutorial 2.1 INTRODUCTION This chapter is a self-paced tutorial intended to get you started using the dsPICDEM.net Development Board. The tutorial demonstrates basic techniques for using the dsPIC30F development tools with the connectivity board. 2.2 HIGHLIGHTS This chapter discusses: • Tutorial Overview • Creating the Project • Building the Code • Programming the Chip • Debugging the Code • Summary 2.3 TUTORIAL OVERVIEW This tutorial combines step-by-step instructions for using the dsPIC development tools with files provided on the Development Kit Software CD to exercise key features of the MPLAB IDE, MPLAB ICD 2 and MPLAB C30 for programming and debugging the dsPIC30F chip. There are three or four steps to this tutorial, depending on the debug tool being used. 1. Create a project in MPLAB 2. Assemble and link the code 3. Program the chip if the MPLAB ICD 2 is being used 4. Debug the code with the MPLAB ICD 2 The MPLAB ICD 2 is used in the tutorial to illustrate debugging. 2.4 CREATING THE PROJECT The first step is to create a project and a workspace in MPLAB. Usually, you will have one project in one workspace. A project contains the files needed to build an application (source code, linker script files, etc.) along with their associations to various build tools and build options. A workspace contains one or more projects and information on the selected device, debug tool and/or programmer, open windows and their location, and other IDE configuration settings. MPLAB IDE contains a Project Wizard to help create new projects. Before starting, copy the Tutorial files from the dsPICDEM.net Sample Applications folder on the dsPICDEM.net Development Kit Software CD to your c:\ drive (see Figure 2-1). PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 14  2004 Microchip Technology Inc. FIGURE 2-1: TUTORIAL CODE FILES Your c:\Tutorial folder should now contain these files: • delay.c • delay.h • dsPICDEM net Tutorial.c • LCD Display.c • LCD Display.h 2.4.1 Select a Device 1. Start MPLAB IDE 2. Close any workspace that might be open (File>Close Workspace). 3. From the Project menu, select Project Wizard. 4. From the Welcome screen, click the Next> to display the Project Wizard Step One dialog (see Figure 2-2). FIGURE 2-2: PROJECT WIZARD, STEP 1, SELECT A DEVICE 5. Select dsPIC30F6014 as the device and click Next>. The Project Wizard Step Two dialog displays (see Figure 2-3). Copy Tutorial folder from CD to your C:\ drive Note: Files copied from the CD are read only; you will need to change the attributes of files that need to be edited. Select dsPIC30F6014 Tutorial  2004 Microchip Technology Inc. DS51471A-page 15 FIGURE 2-3: PROJECT WIZARD, STEP 2, SELECT LANGUAGE TOOLSUITE 2.4.2 Select Language Toolsuite 1. From the Active Toolsuite pull-down menu, select Microchip C30 Toolsuite. This toolsuite includes the compiler, assembler and linker that will be used. 2. From Toolsuite Contents, select MPLAB ASM 30 Assembler (pic30-as.exe). 3. In the Location group, click Browse... and navigate to: C:\pic30_tools\Bin\pic30-as.exe 4. From Toolsuite Contents, select MPLAB C30 Compiler (pic30-gcc.exe). 5. In the Location block, click Browse... and navigate to: C:\pic30_tools\Bin\pic30-gcc.exe 6. From Toolsuite Contents, select MPLAB LINK30 Object Linker (pic30-Id.exe). 7. In the Location block, click Browse... and navigate to: C:\pic30_tools\Bin\pic30-ld.exe. 8. Click Next> to continue. The Project Wizard Step Three dialog displays (see Figure 2-4). Select Microchip C30 Toolsuite Specify file locations for Assembler, Compiler and Object Linker Note: C:\ is the drive implemented for this tutorial example. The specific location on your system will depend on where you installed the MPLAB C30 compiler. If you haven’t purchased the MPLAB C30 compiler, you can download a full-featured 60-day trial version from the Microchip web site (www.microchip.com). Follow the download links under Products/Development Tools/Software. PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 16  2004 Microchip Technology Inc. FIGURE 2-4: PROJECT WIZARD, STEP 3, NAME YOUR PROJECT 2.4.3 Name Your Project 1. In the Project Name text box, type MyTutorial. 2. Click Browse... and navigate to C:\Tutorial to place your project in the Tutorial folder. 3. Click Next> to continue. 2.4.4 Add Files to Project 1. On the Project Wizard Step Four dialog (see Figure 2-5), locate the C:\Tutorial folder and add these files to the right side. dsPICDEMnet Tutorial.c LCD Display.c LCD Display.h delay.c delay.h 2. Navigate to the C:\pic30_tools\support\gld folder and add file p30f6014.gld to include the linker script file in the project. 3. Navigate to the C:\pic30_tools\support\h folder and add file p30f6014.h to include the header file in the project. Type a name for your project... ...and save it in the Project Directory (C:\Tutorial) Note: The linker script file and header file locations for your environment may be different. The location will depend on where you installed the C30 compiler. Tutorial  2004 Microchip Technology Inc. DS51471A-page 17 FIGURE 2-5: PROJECT WIZARD, STEP 4, ADD FILES TO PROJECT 4. There should now be seven files in the project. Click Next> to continue. The Project Wizard Summary screen (Figure 2-6) displays the parameters of your project. FIGURE 2-6: PROJECT WIZARD SUMMARY SCREEN 5. Click Finish. After the project wizard completes, the MPLAB project window shows the project and all the added files (see Figure 2-7). Add the Tutorial files and dsPIC30F6014 support files for the to your newly created project Project named “MyTutorial” for dsPIC30F6014 device will be saved to C:\Tutorial PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 18  2004 Microchip Technology Inc. FIGURE 2-7: PROJECT WINDOW At this point a project and workspace have been created in MPLAB. MyTutorial.mcw is the workspace file and MyTutorial.mcp is the project file. Double-click the dsPICDEMnet Tutorial.c file in the project window to open it. MPLAB should look similar to Figure 2-8. FIGURE 2-8: MPLAB WORKSPACE Project window displays the source files, header files and linker script file you added to your project Tutorial  2004 Microchip Technology Inc. DS51471A-page 19 2.5 BUILDING THE CODE In this project, the code is built in two stages, as shown in Figure 2-9. First the source files are compiled into object files, then the object files are linked. FIGURE 2-9: CODE BUILDING PROCESS The MyTutorial.hex output file contains the data necessary to program the device. The MyTutorial.cof output file contains additional information that lets you debug the code at the source code level. Before building, there are compiler and linker settings that must be specified. These settings indicate where to find the C library files and where to reserve space for the extra debug code when the MPLAB ICD 2 (In-Circuit Debugger) is used. 2.5.1 Set Project Build Options The tutorial project does not explicitly use any libraries, but the C compiler startup library code is always automatically linked into the project. Use the Project>Build Options>Project menu to specify the location of the library files as shown in Figure 2-10. dsPICDEM.net Tutorial.c dsPICDEM.net Tutorial.o LCD display.c Compile Compile LCD display.o Link MyTutorial.cof MyTutorial.hex STAGE ONE COMPILE delay.c delay.o STAGE ONE Compile COMPILE STAGE TWO LINK PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 20  2004 Microchip Technology Inc. FIGURE 2-10: BUILD OPTIONS 1. Select the Build Options General tab. 2. Add a Library Path by browsing to: C:\pic30_tools\lib 3. Select the MPLAB LINK30 tab to display the linker settings (see Figure 2-11). Let the project know where the library files are located Note: The library path for your environment may be different. The location will depend on where you installed the C30 compiler. Tutorial  2004 Microchip Technology Inc. DS51471A-page 21 FIGURE 2-11: MPLAB LINK30 BUILD OPTIONS 4. Check Link for ICD2 to tell the linker to reserve space for the debug code used by the MPLAB ICD 2 In-Circuit Debugger. 5. Click OK. 2.5.2 Build the Project At this point the project is ready to build. 1. From the Project menu select Make. The Build Output window displays (see Figure 2-12). 2. Observe the progress of the build. 3. When the BUILD SUCCEEDED message displays you are ready to program the device. Check Link for ICD2 PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 22  2004 Microchip Technology Inc. FIGURE 2-12: BUILD OUTPUT If you experience problems with the build, double check all the steps in this tutorial and ensure that you are using the latest versions of the development tools. The latest upgrades are available on the Microchip web site (www.microchip.com). If there are errors in the source code, you can double-click the error messages in the Output window and MPLAB will point to the offending line in the source code. This should not happen if the files were copied from the dsPICDEM.net Development Kit CD. 2.6 DEVICE CONFIGURATION AND PROGRAMMING After you have built the code you must set up the configuration bits and then connect the tool you plan to use for programming, running and debugging the code. 2.6.1 Set Up Device Configuration From the Configure menu select Configuration Bits to view the configuration bits (see Figure 2-13). Accept the settings resulting from your build. However, make sure these device categories are set up as shown here: Note: Before proceeding, make sure that the USB driver for the MPLAB ICD 2 has been installed on your PC (see the MPLAB ICD 2 User’s Guide (DS51331) for more details regarding the installation of the USB driver). Category Setting Oscillator Source Primary Oscillator Primary Oscillator Mode XT w/PLL 4x Watchdog Timer Disabled Comm Channel Select Use PGC/EMUC and PGD/EMUD Tutorial  2004 Microchip Technology Inc. DS51471A-page 23 FIGURE 2-13: CONFIGURATION SETTINGS After building the code and setting the configuration bits, use the MPLAB ICD 2 debugger to program the device and run and debug the code on the dsPICDEM.net Demonstration Board. 2.6.2 Enabling the MPLAB ICD 2 Connection The MPLAB ICD 2 can be used to program and debug the dsPIC30F6014 device in-circuit on the dsPICDEM.net board. 1. Connect the MPLAB ICD 2 to the PC with the USB cable (see Figure 2-14). 2. Connect the MPLAB ICD 2 to modular connector labeled ICD on the dsPICDEM.net board with the provided short RJ-11cable. 3. Apply power to the board. FIGURE 2-14: TUTORIAL DEMONSTRATION SETUP Note: Before proceeding, make sure that the USB driver for the MPLAB ICD 2 has been installed on your PC (see the MPLAB ICD 2 User’s Guide (DS51331) for details regarding the installation of the USB driver). PC running MPLAB® IDE dsPICDEM.net™ Connectivity Development Board running Tutorial program 115 VAC 9 VDC Power Cable ICD J14 USB Port MPLAB ICD 2 Connect MPLAB® ICD 2 to PC with USB cable Apply power to the board Connect MPLAB® ICD 2 to board with provided RJ-11 cable PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 24  2004 Microchip Technology Inc. 4. From the Debugger>Select Tool menu, select MPLAB ICD 2 as the debug tool. 5. From the Debugger menu, select Connect. MPLAB should report that it found the dsPIC30F6014 as shown in Figure 2-15. FIGURE 2-15: ENABLING MPLAB ICD 2 6. From the Debugger menu, select Settings to display the ICD Debugger settings (see Figure 2-16). FIGURE 2-16: MPLAB ICD 2 DEBUGGER SETTINGS Note: MPLAB may need to download new firmware if this is the first time the MPLAB ICD 2 is being used with a dsPIC30F device. Allow it to do so. If any errors are shown, double-click the error message to get more information. Make sure this option is selected: Allow MPLAB ICD 2 to select memories and ranges Tutorial  2004 Microchip Technology Inc. DS51471A-page 25 7. On the Program tab, ensure that Allow ICD 2 to select memories and ranges is selected. This setting will speed up programming by addressing only a small part of the total program memory. 8. Program the part (Debugger>Program). The Output window shows the results of the programming cycle as shown in Figure 2-17. The part is now programmed and is ready to run. FIGURE 2-17: MPLAB ICD 2 PROGRAM READY 9. Run the code (Debugger>Run). The MPLAB Output window should indicate that the target is running (see Figure 2-18). PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 26  2004 Microchip Technology Inc. FIGURE 2-18: TUTORIAL PROGRAM RUNNING On the board, LED2 should start blinking and the LCD display should display the following text: dsPICDEM.net Tutorial Output window shows program running Project status bar shows program running Note: When debugging with MPLAB ICD 2, it is always necessary to reprogram the part with the new code after each build. MPLAB will remind you with a message that states “Program memory has changed since last operation.” Tutorial  2004 Microchip Technology Inc. DS51471A-page 27 2.7 DEBUGGING THE CODE The MPLAB ICD 2 debugger/programmer can be used to run, halt, and step the code. You can set a breakpoint so that program execution halts after the code has executed the instruction at the breakpoint. A green arrow points to the next line to be executed. The contents of the RAM and registers can be viewed when the processor has been halted. MPLAB ICD 2 uses the following function keys to access the main debugging functions: There are more functions available by right clicking on a line of source code. The most important of these are Set Breakpoint and Run to Cursor. 2.7.1 Display the Code 1. From the View menu, select Program Memory. The Program Memory window displays. 2. Select the Symbolic tab at the bottom of the window. 3. Press to halt the processor. The program stops and the green arrow points to the next instruction, as shown in Figure 2-19. FIGURE 2-19: PROGRAM HALTED 4. Press to reset the program. The green arrow moves to address 00000, the goto _reset instruction, as shown in Figure 2-20. The linker inserted this instruction to make the program branch to the start of the code. FIGURE 2-20: PROGRAM RESET Halt Reset Single Step Run PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 28  2004 Microchip Technology Inc. 2.7.2 Step the Program 1. Press to single step the code. The green arrow moves to line 129, _reset mov.w #0x850,w15, as shown in Figure 2-21. This code comes from a library (archive) file, libpic30.a, which is automatically linked into C30 compiler projects. This code line initializes the stack pointer and is part of the initialization code that the C30 compiler uses to set up the stack and initialize data. Notice line 135, call main. This instruction calls the main() routine from the dsPICDEMnet Tutorial.c source file. FIGURE 2-21: PROGRAM SINGLE STEPPED 2. Open the dsPICDEMnet Tutorial.c source file. Double click on the file name in the Project Window if the file is not already open. 3. Select and right click line TMR1 = 0;, then choose Run to Cursor., as shown in Figure 2-22. FIGURE 2-22: RUN TO CURSOR COMMAND The code runs briefly until it reaches the specified line. It then halts with the green arrow pointing to the next line, as shown in Figure 2-23. Right-click TMR1 = 0 and select Run to Cursor Tutorial  2004 Microchip Technology Inc. DS51471A-page 29 FIGURE 2-23: PROGRAM HALTED AT CURSOR LOCATION 4. From the View menu select Watch to open a Watch Window. 5. Select PR1 from the SFR pull-down list, then click Add SFR. The PR1 register is added to the Watch Window, as shown in Figure 2-24. 6. Press twice. Watch the PR1 value change to 0x3840 as the green arrow moves to PR1 = FCY/512; in the code window. FIGURE 2-24: WATCH WINDOW DISPLAY 2.7.3 Set Breakpoint 1. To set a breakpoint, right-click a line and select Set Breakpoint from the pop-up menu. For this example, find the following line of code and set a breakpoint. IFS0bits.T1IF = 0; Green arrow shows where program halts Note: An alternate method is to simply double click the line. This feature may need to be enabled by using the Edit>Properties menu. PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 30  2004 Microchip Technology Inc. A red stop sign should appear in the gutter (grey bar on the left) of the source code window, as shown in Figure 2-25. 2. Press to run the code. The program will halt on the instruction following the breakpoint. In this example, every time is pressed to run the code, the program runs through the timing delay loop once before reaching the breakpoint. It toggles LED2 each time. FIGURE 2-25: SETTING BREAKPOINT 2.8 SUMMARY This tutorial has demonstrated several features of the MPLAB IDE programmer and the MPLAB C30 compiler. It also demonstrated the use of the MPLAB ICD 2 debugger with the dsPICDEM.net board. After completing this tutorial you should be able to: • Create a project using the project Wizard. • Compile and link the code and set the configuration bits. • Set up MPLAB to use the MPLAB ICD 2. • Program the chip with the MPLAB ICD 2. • View the code execution in program memory and source code. • View registers in a Watch Window. • Set a breakpoint and make the code halt at a chosen location. • Use the function keys to Reset, Run, Halt and Single Step the code. You can now add functionality to this simple project to create your own application. To familiarize yourself with several dsPIC peripherals and associated board functions proceed to Chapter 3. “Quick Start Program”. The quick start sample project in Chapter 3 provides several code module building blocks to help you accelerate your proficiency with the dsPICDEM.net board.  2004 Microchip Technology Inc. DS51471A-page 31 dsPICDEM.net™ 1 AND dsPICDEM.net 2 CONNECTIVITY DEVELOPMENT BOARD USER’S GUIDE Chapter 3. Quick Start Program 3.1 INTRODUCTION This chapter describes a demonstration program made up of several Assembly and C module building blocks that exercise dsPIC30F peripherals and associated hardware on the dsPICDEM.net Development Board. These code modules are intended to increase your comfort level with the dsPIC by getting you started initializing and controlling peripherals. Additional code modules are provided to initialize and perform loopback tests on board hardware such as the 64Kx16 SRAM, RealTek 10-Base T NIC and Si303x Data Access Arrangement (DAA) and Analog Front End (AFE) circuits. 3.2 HIGHLIGHTS This chapter discusses: • Quick Start Program Overview • Creating the Project • Building the Code • Device Configuration and Programming • Interacting with the Code • Quick Start Demonstration Features and Peripherals • Data and Control Flow • Summary 3.3 QUICK START PROGRAM OVERVIEW The quick start program is provided to accelerate your proficiency in working with the dsPIC30F device and dsPICDEM.net Development Board to create your own embedded solutions. The building block code modules can be used to initialize and control several dsPIC peripherals and associated board functions. The quick start program will also increase your familiarity with the dsPIC software development tools. You will use the MPLAB IDE to create a quick start project. You will use the MPLAB C30 compiler to build the quick start program. And you will use the MPLAB ICD 2 debugger to program the dsPIC30F chip and debug the program on the board. If you have not yet purchased the MPLAB C30 compiler you will need to download and install the full-feature 60-day trial available from the Microchip web site. The quick start program basically displays information on the LCD screen and toggles LEDs in response to specific actions. Source files are provided on the dsPICDEM.net Development Kit Software CD in the dsPICDEM.net Board Sample Applications/Quick Start folder. Full source code is provided to assist in debugging. The source files are used with a linker script file (p30f6014.gld) and a header file (p30f6014.h) from the MPLAB C30 compiler to form a simple quick start project. As you work with the step-by-step instructions you will become increasingly familiar with key features of the dsPIC30F. PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 32  2004 Microchip Technology Inc. There are three or four steps to this quick start, depending on the debug tool being used: 1. Create a project in MPLAB 2. Assemble and link the code 3. Program the chip if the MPLAB ICD 2 is being used 4. Debug the code with the MPLAB ICD 2 The MPLAB ICD 2 is used in the quick start procedures to illustrate debugging. 3.4 CREATING THE PROJECT The first step is to create a project and a workspace in MPLAB. Usually, you will have one project in one workspace. A project contains the files needed to build an application (source code, linker script files, etc.) along with their associations to various build tools and build options. A workspace contains one or more projects and information on the selected device, debug tool and/or programmer, open windows and their location, and other IDE configuration settings. MPLAB IDE contains a Project Wizard to help create new projects. Before starting, copy the Quick Start folder on the dsPICDEM.net Development Kit Software CD to your c:\ drive (see Figure 3-1). FIGURE 3-1: DEMONSTRATION CODE FILES The folder should contain these files: Note: Files copied from the CD are read only; you will need to change the attributes of files that need to be edited. h files: • defines.h • delay.h • lcd.h • nic_init_param.h • nic_strings.h • strings.h inc files • device_Fcy.inc • Si3021_mode.inc • Si3021_outputs.inc Copy Quick Start folder from CD to your C:\ drive Quick Start Program  2004 Microchip Technology Inc. DS51471A-page 33 3.4.1 Select a Device 1. Start MPLAB IDE. 2. Close any workspace that might be open (File>Close Workspace). 3. From the Project menu, select Project Wizard. 4. From the Welcome screen, click the Next> to display the Project Wizard Step One dialog (see Figure 3-2). FIGURE 3-2: PROJECT WIZARD, STEP 1, SELECT A DEVICE 5. Select dsPIC30F6014 as the device and click Next>. The Project Wizard Step Two dialog displays (see Figure 3-3). source files • 1khz.s • 2khz.s • bin2dec.c • Dac_Update.c • delay.c • device_config.s • display.s • init_Adc.s • init_Dci.s • init_INTpin.s • init_Ports.s • init_RealTek_NIC.c • init_Si3021.s • init_Spi1.s • init_Sram.c • init_Timers.s • init_Uart.s • isr_Adc.s • isr_Dci.s • isr_INTpin.s • isr_RealTek_NIC.s • isr_Timers.s • isr_Uart1_tx.s • lcd.c • main.c • TestCAN.c • TestUart1.c • traps.c Select dsPIC30F6014 PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 34  2004 Microchip Technology Inc. FIGURE 3-3: PROJECT WIZARD, STEP 2, SELECT LANGUAGE TOOLSUITE 3.4.2 Select Language Toolsuite 1. From the Active Toolsuite pull-down menu, select Microchip C30 Toolsuite. This toolsuite includes the compiler, assembler and linker that will be used. 2. Set Toolsuite Contents to MPLAB ASM 30 Assembler (pic30-as.exe). 3. Set Location to: C:\pic30_tools\Bin\pic30-as.exe. 4. Reset Toolsuite Contents to MPLAB C30 Compiler (pic30-gcc.exe). 5. Set Location to: C:\pic30_tools\Bin\pic30-gcc.exe. 6. Reset Toolsuite Contents to MPLAB LINK30 Object Linker (pic30-Id.exe). 7. Set Location to: C:\pic30_tools\Bin\pic30-ld.exe. 8. Click Next> to continue. The Project Wizard Step Three dialog displays (see Figure 3-4). Specify file location for Assembler Specify file location for Compiler Specify file location for Object Linker Select Microchip C30 Toolsuite Note: C:\ is the drive implemented for this example. The specific location of the MPLAB C30 compiler may be different on your system. Quick Start Program  2004 Microchip Technology Inc. DS51471A-page 35 FIGURE 3-4: PROJECT WIZARD, STEP 3, NAME YOUR PROJECT 3.4.3 Name Your Project 1. In the Project Name text box, type MyQuickStart. 2. Click Browse... and navigate to C:\Quick Start to place your project in the Quick Start folder. 3. Click Next> to continue. 3.4.4 Add Files to Project 1. On the Project Wizard Step Four dialog (see Figure 3-5), locate the C:\Quick Start folder and add all the hex, source and include files to the right side. Select and add all the files in the Quick Start/h folder: Select and add all the files in the Quick Start/inc folder: Select and add all the files in the Quick Start/source folder: • defines.h • delay.h • lcd.h • nic_init_param.h • nic_strings.h • strings.h • device_Fcy.inc • Si3021_mode.inc • Si3021_outputs.inc • bin2dec.c • Dac_Update.c • delay.c • init_RealTek_NIC.c • init_Sram.c • lcd.c • main.c • TestCAN.c • TestUart1.c • traps.c • 1khz.s • 2khz.s • device_config.s • display.s • init_Adc.s • init_Dci.s • init_INTpin.s • init_Ports.s • init_Si3021.s • init_Spi1.s • init_Timers.s • init_Uart.s • isr_Adc.s • isr_Dci.s • isr_INTpin.s • isr_RealTek_NIC.s • isr_Timers.s • isr_Uart1_tx.s Type a name for your project... ...and save it in the Project Directory (C:\Quick Start) PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 36  2004 Microchip Technology Inc. 2. Navigate to the C:\pic30_tools\support\gld folder and add file p30f6014.gld to include the linker script file in the project. 3. Navigate to the C:\pic30_tools\support\h folder and add file p30f6014.h to include the header file in the project. FIGURE 3-5: PROJECT WIZARD, STEP 4, ADD FILES TO PROJECT 4. Click Next> to continue. The Project Wizard Summary screen (Figure 3-6) displays the parameters of your project. FIGURE 3-6: PROJECT WIZARD SUMMARY SCREEN 5. Click Finish. Note: The linker script file and header file locations for your environment may be different. The location will depend on where the C30 compiler is installed. Add the Quick Start files and dsPIC30F6014 support files to your newly created project Project named “MyQuickStart” for dsPIC30F6014 device will be saved to C:\Quick Start Quick Start Program  2004 Microchip Technology Inc. DS51471A-page 37 After the project wizard completes, the MPLAB project window shows the project and all the added files (see Figure 3-7). FIGURE 3-7: PROJECT WINDOW At this point a project and workspace have been created in MPLAB. MyQuickStart.mcw is the workspace file and MyQuickStart.mcp is the project file. Double-click the main.c file in the project window to open it. MPLAB should look similar to Figure 3-8. FIGURE 3-8: MPLAB WORKSPACE Project window displays the files you added to your MyQuickStart project PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 38  2004 Microchip Technology Inc. 3.5 BUILDING THE CODE In this project, the code is built in two stages. First the source files are compiled into object files, then the object files are linked. The MyQuickStart.hex output file contains the data necessary to program the device. The MyQuickStart.cof output file contains additional information that lets you debug the code at the source code level. Before building the program, compiler and linker settings must be specified. These settings indicate where to find the C library files and where to reserve space for the extra debug code when the MPLAB ICD 2 (In-Circuit debugger) is used. 3.5.1 Set Project Build Options The Quick Start project does not explicitly use any libraries, but the C compiler startup library code is always automatically linked into the project. Use the Project>Build Options>Project menu to display the Build Options dialog. 1. Select the General tab. 2. Type or browse to the file locations shown in Figure 3-9. FIGURE 3-9: BUILD OPTIONS 3. Select the MPLAB LINK30 tab to display the linker settings. 4. Check Link for ICD2 to tell the linker to reserve space for the debug code used by the MPLAB ICD 2 In-Circuit Debugger (see Figure 3-10). 5. Click OK. Let the project know where the output files will be located Note: The library path for your environment may be different. The location will depend on where you installed the C30 compiler. Quick Start Program  2004 Microchip Technology Inc. DS51471A-page 39 FIGURE 3-10: MPLAB LINK30 BUILD OPTIONS 3.5.2 Build the Project At this point the project is ready to build. 1. From the Project menu select Build All. The Build Output window displays (see Figure 3-11). 2. Observe the progress of the build. 3. When the BUILD SUCCEEDED message displays you are ready to program the device. FIGURE 3-11: BUILD OUTPUT If you experience any problems with the build, double-click the error messages in the Output window and MPLAB will point to the offending line in the source code. This should not happen if the files were copied from the dsPICDEM.net Development Kit CD. Double check all the steps in this section and ensure that you are using the latest versions of the development tools. The latest upgrades are available on the Microchip web site (www.microchip.com). Check Link for ICD2 PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 40  2004 Microchip Technology Inc. 3.6 DEVICE CONFIGURATION AND PROGRAMMING After you have built the code you must set up the configuration bits and then connect the tool you plan to use for programming, running and debugging the code. 3.6.1 Set Up Device Configuration From the Configure menu select Configuration Bits to view the configuration bits and set up the bits as shown in Figure 3-12. The settings that will most likely need to change are: FIGURE 3-12: CONFIGURATION SETTINGS After building the code and setting the configuration bits, the MPLAB ICD 2 debugger can be used to run and debug the code on the dsPICDEM.net Demonstration Board. Follow the instructions in one of the next two sections depending on which tool you are using. 3.6.2 Enabling the MPLAB ICD 2 Connection The MPLAB ICD 2 can be used to program and debug the dsPIC30F6014 device in-circuit on the dsPICDEM.net board. 1. Connect the MPLAB ICD 2 to the PC with the USB cable (see Figure 3-13). 2. Connect the MPLAB ICD 2 to modular connector labeled ICD on the dsPICDEM.net board with the provided short RJ-11 cable. 3. Apply power to the board. Note: Before proceeding, make sure that the USB driver for the MPLAB ICD 2 has been installed on your PC (see the MPLAB ICD 2 User’s Guide (DS51331) for more details regarding the installation of the USB driver). Oscillator Source Primary Oscillator Primary Oscillator Mode XT w/PLL 8x Watchdog Timer Disabled Comm Channel Select Use PGC/EMUC and PGD/EMUD Note: Before proceeding, make sure that the USB driver for the MPLAB ICD 2 has been installed on your PC (see the MPLAB ICD 2 User’s Guide (DS51331) for details regarding the installation of the USB driver). Quick Start Program  2004 Microchip Technology Inc. DS51471A-page 41 FIGURE 3-13: dsPICDEM.net™ DEVELOPMENT BOARD CONNECTED TO MPLAB® ICD 2 4. From the Debugger>Select Tool menu, select MPLAB ICD 2 as the debug tool. 5. From the Debugger menu, select Connect. MPLAB should report that it found the dsPIC30F6014 as shown in Figure 3-14. FIGURE 3-14: ENABLING MPLAB ICD 2 6. From the Debugger menu, select Settings to display the ICD Debugger settings (see Figure 3-15). 7. On the Program tab, ensure that “Allow ICD 2 to select memories and ranges” is selected. This setting will speed up programming by addressing only a small part of the total program memory. PC running MPLAB® IDE dsPICDEM.net™ Connectivity Development Board running Quick Start program 115 VAC 9 VDC Power Cable RJ-11 Cable ICD J14 USB Cable MPLAB® ICD 2 Connect USB cable to PC Connect RJ-11 cable to Apply power to the board MPLAB® ICD 2 Note: MPLAB may need to download new firmware if this is the first time the MPLAB ICD 2 is being used with a dsPIC30F device. Allow it to do so. If any errors are shown, double-click the error message to get more information. PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 42  2004 Microchip Technology Inc. FIGURE 3-15: MPLAB ICD 2 DEBUGGER SETTINGS 8. Program the part (Debugger>Program). The Output window shows the results of the programming cycle as shown in Figure 3-16. The part is now programmed and is ready to run. FIGURE 3-16: OUTPUT WINDOW 9. Run the code (Debugger>Run). The program initializes and tests the peripherals, as depicted in Figure 3-17. Note the responses on the dsPICDEM.net board as the program executes. These responses are indicated along the right side of the flow chart. The code modules are identified along the left side of the flow chart. Quick Start Program  2004 Microchip Technology Inc. DS51471A-page 43 FIGURE 3-17: PERIPHERAL INITIALIZATION AND TEST PROGRAM FLOW main.c START Initialize Ports & W Registers Initialize Timers 1, 2 & 3 Initialize LCD Test SRAM SRAM Test Pass? NIC Loopback Pass? CAN Loopback Pass? UART1 Loopback Pass? ISOcap Frame Lock? Initialize & Test NIC Initialize & Test CAN Initialize & Test UART1 Initialize DCI Initialize Si3021 DAA/AFE Initialize INTx Pins for Interrupt Initialize SPI1 Module Initialize ADC Module Display SRAM FAIL Display SRAM PASS Display LOOPBACK PASS Display LOOPBACK PASS Display LOOPBACK PASS Display LOOPBACK FAIL Display LOOPBACK FAIL Display FAIL Message Display LOOPBACK FAIL Display LOCK Message START RUNNING init_ports.s init_timers.s LEDS ILLUMINATE LED2 and LED3 BLINK lcd.c init_Sram.s init_uart.s testuart1.c init_RealTek_NIC.c TestCAN.c init_DCI.s init_Si3021.s init_INTpin.s init_Spi1.s init_Adc.s SRAM TEST RESULT DISPLAYS NIC TEST RESULT DISPLAYS CAN TEST RESULT DISPLAYS UART1 TEST RESULT DISPLAYS FRAME LOCK STATUS DISPLAYS RP1 and RP2 VALUES DISPLAY No No No No No Yes Yes Yes Yes Yes PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 44  2004 Microchip Technology Inc. At this point the program is running in the main loop (see Figure 3-18). The LCD displays the current values of potentiometers RP1 and RP2: FIGURE 3-18: QUICK START PROGRAM MAIN LOOP RP1= 3.44v RP2= 2.14v INT1 Interrupt? (S1) RUNNING INT2 Interrupt? (S2) INT3 Interrupt? (S3) S1 DEPRESSED S2 DEPRESSED S3 DEPRESSED Execute OFF-HOOK and Display Message Yes Execute ON-HOOK and Display Message Yes Display TEMPERATURE Yes Delay 200 ms Call Display Conversion Update Digital Pot Display RP1 & RP2 Values isr_INTpin.s isr_INTpin.s isr_INTpin.s delay.c display.s bin2dec.c Dac_Update.c No No No Quick Start Program  2004 Microchip Technology Inc. DS51471A-page 45 3.7 INTERACTING WITH THE CODE With the program running you can interact with the peripherals on the dsPICDEM.net board and observe the results on the LCD. 1. Depress S1. The LCD displays the message: Off_Hook mode. In this mode, the dsPIC commands the Si3021 DAA/AFE to go off-hook and seize the line (i.e., the typical routine for a modem to connect to the PSTN). For this demonstration the dsPIC transmits a single tone to the AFE via the Data Converter Interface module on the dsPIC device. After the off-hook routine is completed the LCD reverts to the routine that displays the values of RP1 and RP2. The tone continues to be generated and can be heard until switch S2 is depressed. 2. Depress S2. The LCD displays the message: Ready... On_Hook. For this routine, the dsPIC commands the Si3021 DAA/AFE to go on-hook (i.e., the typical condition when a modem releases the telephone line). For this demonstration the dsPIC terminates the data transfer from the Data Converter Interface to the Si3021 AFE. After the on-hook routine is completed the LCD reverts to the routine that displays the values of RP1 and RP2. 3. Depress S3. The LCD displays the temperature as measure by sensor U2 followed by the Ready... On_Hook message and then reverts to the RP1 and RP2 readings. 4. Touch U2 (located just left of the LCD) for a few seconds, then depress S3 again. Notice the changed value of the temperature sensor. 5. Adjust RP1 and/or RP2. Notice the changed value(s). 3.8 QUICK START DEMONSTRATION FEATURES AND PERIPHERALS The intent of the Quick Start demonstration is to give you hands-on experience with the dsPIC30F processor and peripheral features. At this point, you can examine the program (main.c) and/or individual code modules in MPLAB IDE. You can set breakpoints to examine specific activities. Or you can step through the code modules one instruction at a time. 3.8.1 dsPIC30F Peripheral Features The Quick Start demonstration program initializes and controls these dsPIC30F peripherals and associated board functions: • Timer1 – Configured as a 16-bit timer with 1:1 prescaler used as toggle rate for LED1. • Timer2 – Configured as 16-bit timer with a 1:1 prescaler used as toggle rate for LED2. • Timer3 – Configured as 16-bit timer with a 1:1 prescaler used as toggle rate for LED3. • UART1 TX – Used to transmit demonstration data to the PC for display. • SPI™ 1 – Used to communicate to the MCP42050 Dual Channel Digital potentiometer. • 12-bit ADC – Used to convert multiple analog signals, such as potentiometer and temperature values (TC1047A temperature sensor). PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 46  2004 Microchip Technology Inc. • Data Converter Interface – Interfaced to an external Si303x DAA/AFE chipset for PSTN interface control and monitor. • INTx pins – Used for detecting switch S1-S3 inputs. • PORTD pins, RD0-RD15 – Used to interface to 64Kx16 SRAM, 10-base T NIC and 2x16 LCD. 3.9 DATA AND CONTROL FLOW 3.9.1 Power-up Sequence Table 3-1 provides more details on the power-up peripheral initialization sequence illustrated in Figure 3-17. 3.9.2 Main Loop Code Execution Table 3-2 explains the step-by-step execution sequence of the Main Loop shown in Figure 3-18 TABLE 3-1: POWER-UP PERIPHERAL INITIALIZATION SEQUENCE Seq Module or Board Function Initialization Process 1 Timer1 Configured to count to 2.2 mS and reset. 2 Timer2 Configured to count to 3.95 mS and reset. 3 Timer3 Configured to count to 2.2 mS and reset. 4 2x16 LCD Initialization of 2x16 character LCD, via PORTD pins RD0-RD15. 5 64Kx16 SRAM Initialization and test of 64Kx16 SRAM, via PORTD pins RD0-RD15. Testing is performed by writing and reading back a specific incrementing pattern. 6 10-base T NIC Initialization and test of 10-base T NIC, via PORTD pins RD0-RD15. Testing is performed by performing internal loop-back tests as supported by the NIC. 7 UART1 The transmitter is configured for interrupt-driven operation at 38400 baud. 8 Data Converter Interface (DCI) Configured for Slave mode. Configured to communicate to the Si303x DAA/AFE chipset operating in Master mode. Some DAA/AFE self test routines are executed. 9 External interrupt pins INT1-INT3 Configured to interrupt on the falling edge and used for switches S1-S3, respectively. 10 SPI™ 1 Configured for communication with MCP42050 Dual Channel Digital potentiometer. 11 12-bit ADC Configured to continuously sample channels AN3 (temperature sensor U2), AN4 (RP1) and AN5 (RP2). TABLE 3-2: MAIN LOOP CODE EXECUTION SEQUENCE Seq. Program Task 1 Check state of variable “hook_status”, which is modified in either INT1, INT2 and INT3 Interrupt Service Routines. 2 12-bit ADC collects a sample each from the digital potentiometer RP1 and RP2 and temperature sensor, U2. 3 Data obtained from ADC is converted to ASCII for display by UART and LCD. 4 LCD is updated with Potentiometer RP1 and RP2 values. 5 SPI 1 transmit RP1 and RP2 values to dual channel digital potentiometer. Monitor of potentiometer output is via PW0 and PW1 test points on board. Quick Start Program  2004 Microchip Technology Inc. DS51471A-page 47 3.9.3 Interrupts Used in the Demonstration Program 3.9.3.1 EXTERNAL INTERRUPTS TO MAIN ROUTINE External interrupts INT1-INT3 are controlled by switches S1-S3 respectively. Each switch is monitored by the respective Interrupt pin, INT1-INT3. For each switch detected the variable “hook_status” is modified in the ISR. The variable “hook_status” is then monitored in the main loop and based upon the variable state one of three actions are taken. 3.9.3.2 12-BIT ADC INTERRUPTS The 12-bit module is configured to continually sample and convert channels AN3 (temperature sensor U2), AN4 (RP1) and AN5 (RP2). When all three signals have been converted an ADC module based interrupt occurs and the ISR code simply saves off the converted values to variables defined in data memory. Outside the interrupt this “raw” data is converted to ASCII by a simple conversion routine and then used by the UART and LCD display code modules. 3.9.3.3 UART TRANSMIT INTERRUPTS Approximately every 200 mS, data is transmitted via the UART to the HyperTerminal session window. The term “data” refers to the following: • Analog data such as RP1 and RP2 voltages • Temperature sensor data, U2 3.9.3.4 TIMER1 Timer1 is a 16-bit timer that uses the instruction cycle as its time-base. It is configured to time out and generate an interrupt every 2.2 milliseconds. The Timer1 Interrupt Service Routine (ISR) simply toggles LED1 and clears the associated interrupt flag. 3.9.3.5 TIMER2 Timer2 is a 16-bit timer that uses the instruction cycle as its time-base. It is configured to time out and generate an interrupt every 3.95 milliseconds. The Timer2 Interrupt Service Routine (ISR) increments a variable, tests bit 9 of this variable and if set toggles LED2. If LED2 is toggled the ISR resets this same variable to zero. Finally the associated interrupt flag is cleared. 3.9.3.6 TIMER3 Timer3 is a 16-bit timer that uses the instruction cycle as its time-base. It is configured to time out and generate an interrupt every 2.2 milliseconds. The Timer3 Interrupt Service Routine (ISR) increments a variable, tests bit 9 of this variable and if set toggles LED3. If LED3 is toggled the ISR resets this same variable to zero. Finally the associated interrupt flag is cleared. PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 48  2004 Microchip Technology Inc. 3.10 SUMMARY This quick start demonstration program is aimed at getting users more familiar with the dsPIC peripherals and dsPICDEM.net Development Board functions. In working through this demonstration you should also become more comfortable with features of MPLAB IDE and the MPLAB C30 compiler and the use of the MPLAB ICD 2 debugger with the dsPICDEM.net board. After working with the Quick Start program you will have: • Increased your understanding of how the dsPIC30F works with its peripherals. • Gained a further understanding of how to initialize and control dsPIC30F peripherals and associated board functions. • Reduced the learning cycle for getting started with your development using the dsPIC30F product family.  2004 Microchip Technology Inc. DS51471A-page 49 dsPICDEM.net™ 1 AND dsPICDEM.net 2 CONNECTIVITY DEVELOPMENT BOARD USER’S GUIDE Chapter 4. HTTP Web Server Demonstration 4.1 INTRODUCTION This chapter describes a sample program that demonstrates Web-based monitoring and control of an embedded application operating with the CMX-MicroNet TCP/IP Stack configured for Hyper Text Transfer Protocol (HTTP) Web Server protocol. 4.2 HIGHLIGHTS Information in this chapter includes: • Demonstration Overview • Demonstration Setup • Configuring your Laptop or Desktop PC • HTTP Web Server Demonstration • Debugging TIPS • Troubleshooting • Using HTTP Web Server in Your Application 4.3 DEMONSTRATION OVERVIEW This demonstration program runs on the dsPIC30F6014 using the CMX-MicroNet TCP/IP Stack configured for HTTP Web Server protocol to support remote monitoring and control of the application over an Ethernet connection. The CMX-MicroNet TCP/IP Stack is designed for optimized use of Flash and RAM Memory on dsPIC30F devices. This software runs directly on the processor with no gateways or PCs required. The stack can be run in stand-alone mode or work in conjunction with an RTOS. This demonstration uses approximately 4.2K instructions in Flash and 300 bytes in RAM, not including the HTML, java applets and.jpg and.gif images. In this demonstration the dsPIC “serves-up” HTML pages to a browser and implements two basic HTML form methods: GET and POST. The GET and POST methods are demonstrated in the form of requests from and updates to the HTML page displayed on a browser. These functions enable you to monitor and change functions on the dsPICDEM.net board. The GET method retrieves information from the potentiometers, temperature sensor and switches to illustrate monitoring functionality. The POST method uploads information to the LCD and LEDs on the board to illustrate control and updating functionality. For this demonstration the HTML page served-up by the dsPIC device is stored in the Flash Program Memory. Alternatively, the dsPICDEM.net board provides a 24LC515 Serial I2C EE 64 Kbyte Memory device that can be used to store the HTML pages. PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 50  2004 Microchip Technology Inc. 4.4 DEMONSTRATION SETUP 4.4.1 Equipment Requirements The HTTP Web Server demonstration requires the following equipment: • dsPICDEM.net Development Board Kit with dsPIC30F6014 Plug-in-Module (PIM) • CAT-5 crossover cable (or standard Ethernet cable and access to a network or hub) • MPLAB IDE Integrated Development Environment • MPLAB ICD 2 In-Circuit Debugger • Laptop or Desktop PC with RS-232 serial port or USB port for connecting to the MPLAB ICD 2 In-Circuit Debugger • RJ-11 phone cable for connecting the MPLAB ICD 2 to the dsPICDEM.net board 4.4.2 Equipment Setup Connect the dsPICDEM.net board to your PC or laptop as shown in Figure 4-1. FIGURE 4-1: WEB SERVER DEMONSTRATION SETUP 1. Connect the MPLAB ICD 2 to your PC with the USB cable. 2. Using the short RJ-11 phone cable, connect the MPLAB ICD 2 to RJ-11 modular connector ICD on the board. 3. Connect one end of the supplied CAT-5 crossover cable to RJ-45 modular connector J15 on the board and the other end to the Ethernet network card on the PC or Laptop. 4. Connect the dsPICDEM.net power cable to the power input connector (J14). PC running MPLAB® IDE and Internet Explorer dsPICDEM.net™ Connectivity Development Board running web server demonstration Ethernet connection J15 115 VAC 9 VDC Power Cable ICD J14 USB Port ICD 2 Connect MPLAB® ICD 2 to board with RJ-11 phone cable Connect MPLAB® ICD 2 to PC with USB cable Connect board to PC with CAT-5 crossover cable Apply power to board HTTP Web Server Demonstration  2004 Microchip Technology Inc. DS51471A-page 51 4.4.3 WEB Server Program Setup Copy the WEB Server folder from the dsPICDEM.net Development Kit Software CD to the C:\ drive on your PC or laptop (see Figure 4-2). FIGURE 4-2: WEB SERVER DEMONSTRATION CODE 4.5 CONFIGURING YOUR LAPTOP OR DESKTOP PC This HTTP Web Server demonstration is configured to operate with a Static IP address. To run the demonstration program you must configure the local Network Connections on your laptop or Desktop to use a compatible Static IP address. To reconfigure your network connections, follow these steps: 1. From the Windows desktop, click Start>Settings>Network Connections> Local Area Connection. 2. Right-click Local Area Connection and select Properties. The Local Area Connection Properties dialog displays your current connections. 3. On the General tab, scroll down the list of connections to Internet Protocol TCP/IP, then click Properties. The Internet Protocol (TCP/IP) Properties dialog displays, as shown in Figure 4-3. 4. On the General tab, check Use the following IP address: and type in these settings: 5. Check OK in each dialog box until you close all the windows. Depending on the version of Windows you are running, you may be required to reboot your PC for the changes to take effect. 6. Proceed with the HTTP Web Server demonstration. Copy WEB Server folder from CD to your C:\ drive Note: Before reconfiguring your network connection settings for this demonstration, make a note of your current PC settings. You will want to restore your original PC settings after you complete this demonstration. Note: Record your current settings so you can restore them later. IP Address: 216 . 233 . 5 . 32 Subnet mask: 255 . 255 . 255 . 0 PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 52  2004 Microchip Technology Inc. FIGURE 4-3: IP SETTINGS DIALOG 4.6 HTTP WEB SERVER DEMONSTRATION 4.6.1 Programming the dsPIC30F6014 Device The dsPIC30F6014 device must be programmed with the HTTP Web demonstration program (webdemo.hex). If you have previously loaded this program on a dsPIC30F6014 device you can proceed directly to Section 4.6.2 “Start HTTP Web Server Session”. 1. Apply power to the board. The green POWER LED illuminates. 2. Launch MPLAB IDE on your PC. From the Configure menu, choose Select Device, then select dsPIC30F6014. 3. Select Programmer>Select Programmer>MPLAB ICD 2. You should see a connection message in the output window, as shown in Figure 4-4. If the MPLAB ICD 2 does not initially connect and recognize the dsPIC30F6014 device, click the MPLAB ICD 2 puck icon on the MPLAB IDE toolbar. The output window should then indicate a successful connection. FIGURE 4-4: MPLAB ICD 2 CONNECTION MESSAGE WITH dsPIC30F6014 Type IP address Check this option HTTP Web Server Demonstration  2004 Microchip Technology Inc. DS51471A-page 53 4. From the MPLAB IDE File menu, select Import. Browse to the C:\WEB Server directory where you saved the webdemo.hex file, select it and click Open. 5. From the MPLAB IDE Configure menu, select Configuration Bits and verify the device configuration settings shown in Figure 4-5. FIGURE 4-5: SETTING CONFIGURATION BITS IN MPLAB IDE 6. From the MPLAB IDE Programmer menu select Program. The webdemo.hex file downloads to the dsPIC30F6014. The Output Window records the process as it occurs and indicates completion by displaying “MPLAB ICD 2 Ready”. 7. Remove the MPLAB ICD 2 cable from the board then press “RESET” on the demonstration board to run the program. The LCD on the dsPICDEM.net board indicates that the program is running, as shown in Figure 4-6. FIGURE 4-6: LCD DISPLAY CMX-MicroNet WEB Server Demo PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 54  2004 Microchip Technology Inc. 4.6.2 Start HTTP Web Server Session This demonstration is intended to run with Windows 98, NT, and XP using Internet Explorer 5 or 6 or Netscape 4.7. 1. Launch your browser. 2. Type the following URL address: http://216.233.5.31 The dsPIC30F6014 Web Server returns the HTML page shown in Figure 4-7. FIGURE 4-7: WEB PAGE FROM dsPIC30F6014 If you encounter a connection problem refer to Section 4.8 “Troubleshooting”. HTTP Web Server Demonstration  2004 Microchip Technology Inc. DS51471A-page 55 4.6.3 Monitor the dsPICDEM.net™ Development Board This demonstration shows how you might monitor devices used in your embedded application program over an Ethernet connection (or over the internet). In this portion of the demonstration you will monitor the voltage on potentiometers RP1 and RP2, the temperature on sensor U12 and the status of switches S1, S2 and S3 (see Figure 4-8). 1. On the dsPICDEM.net board, adjust potentiometers RP1 and RP2. Observe the associated voltage value changing on the web page. 2. Touch temperature sensor U2 and monitor the temperature displayed on the web page. 3. Press switches S1-S3 and observe the switch indicators on the web page change between Off (red) and On (green). FIGURE 4-8: MONITORED DEVICES SWITCHES S1-S3 POTS RP1-RP2 TEMPERATURE SENSOR U2 PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 56  2004 Microchip Technology Inc. 4.6.4 Control the dsPICDEM.net™ Development Board This portion of the demonstration illustrates how you can remotely control functions in an embedded application from your browser. Information you enter on the web page affects the LEDs and LCD display on the dsPICDEM.net board. 1. Repeatedly click the LEDs button on the web page. LED1, LED2 and LED3 on the dsPICDEM.net development board toggle up and down in sequence for each mouse click. 2. Enter up to 16 characters in the text box on the web page, then click the LCD button. The information you typed displays as line 2 of the LCD on the dsPICDEM.net board. 3. Repeat step 2. The last typed entry replaces line 2 of the LCD. FIGURE 4-9: CONTROLLED DEVICES 4.6.5 Hyper Text Transfer Protocol HTTP is the defacto standard for transferring World Wide Web documents, although it is designed to be extensible to almost any document format. HTTP Version 1.1 is documented in RFC 2068. HTTP Version 1.0 (deprecated) is documented in RFC 1945. See also the W3C’s work on the standard at: www.w3.org/Protocols/. HTTP operates over TCP connections, usually to port 80, though this can be overridden and another port used. After a successful connection, the client transmits a request message to the server, which sends a reply message back. HTTP messages are human-readable. An HTTP server can be manually operated with a command such as Telnet Server 80. The simplest HTTP message is "GET url”, to which the server replies by sending the named document. In HTML, you can specify two different submission methods for a form. The method is specified inside a form element, using the METHOD attribute. The difference between METHOD="GET" (the default) and METHOD="POST" is primarily defined in terms of form data encoding. INFORMATION TYPED ON WEB PAGE DISPLAYS ON LCD LEDS 1-3 HTTP Web Server Demonstration  2004 Microchip Technology Inc. DS51471A-page 57 4.7 DEBUGGING TIPS Use a packet sniffer to monitor all the transmitted frames and observe exactly what is going on in real-time (see Figure 4-10). A packet sniffer can be used with the PC-side TCP/UDP client/server test programs that are included with the MicroNet software. A number of good packet sniffers are available as freeware. Freeware Packet Sniffers for Windows include: • AnalogX PacketMon (www.analogx.com) • Anasil (www.sniff-tech.com) • CommView (www.tamosoft.com) • Ethereal (www.ethereal.com) • Sniff'em (www.sniff-em.com) Commercially available packet sniffers include: • Klos Technologies' SerialView, PacketView (www.klos.com) • Windows Packet sniffing library for C#, C++, VB (www.packet-sniffing.com) For additional information on packet sniffers, refer to: www.robertgraham.com/pubs/sniffing-faq.html FIGURE 4-10: ETHEREAL FREEWARE PACKET SNIFFER PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 58  2004 Microchip Technology Inc. 4.8 TROUBLESHOOTING The HTTP Web Server program has been tested on a dsPICDEM.net connectivity board like the one you have received. No problems have been encountered (hence none expected when you run the demonstration). The Java applets used in the HTTP Web Server program have been tested with Internet Explorer 5 and 6 and Netscape 4.7 from Windows 98, NT, and XP platforms. Depending on the Java settings in your browser, you may experience the following error message when the browser begins communication with the dsPIC30F-based Web Server and attempts to load the Java applet: Loading class dsPICDEMO Exception:java.lang.NullPointerException To remedy this error condition, use this procedure: 1. Open the Internet Properties (XP) dialog box. From your browser select Tools>Internet Options. From Windows select Start>Settings>Control Panel>Internet Options>Advanced. Ensure that Java console enabled (requires restart) is selected (see Figure 4-11). Click OK and allow the browser to restart. FIGURE 4-11: BROWSER JAVA SETTINGS Note: The exact steps may be slightly different depending on the version of Windows, the browser type and browser version you are using. HTTP Web Server Demonstration  2004 Microchip Technology Inc. DS51471A-page 59 Next, go to Control Panel and select the Java Plug-in application. Open this application and select the Cache tab. Ensure the “Enable Caching” box is deselected. Once complete click on the Apply and close this control panel. Retry the browser refresh function and see if the entire HTML page is now displayed correctly. FIGURE 4-12: JAVA PLUG-IN BROWSER SETTINGS 4.9 USING HTTP WEB SERVER IN YOUR APPLICATION Operating the dsPIC30F with the CMX MicroNet TCP/IP stack gives you the ability to send data across the Internet. However, you must decide how to use it in your design. If you are simply looking for an interactive method of monitoring real time values as they are changing within your target device, you may want to utilize the HTTP protocol and server already developed. By setting up a series of URLs or “links”, you can have the HTTP module format the information in the form of HTML files. If you require a more efficient or a secure form of interaction, you could set up a proprietary method of communication and deliver it within the payload of the TCP packet itself. A Windows application could be created in order to communicate, interact and manage a group of your devices on the Net. One step further may be to give the ability of the devices themselves to interact with each other. PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 60  2004 Microchip Technology Inc. NOTES:  2004 Microchip Technology Inc. DS51471A-page 61 dsPICDEM.net™ 1 AND dsPICDEM.net 2 CONNECTIVITY DEVELOPMENT BOARD USER’S GUIDE Chapter 5. FTP Server Demonstration 5.1 INTRODUCTION This chapter describes a sample program that demonstrates remote monitoring and control of an embedded application using File Transfer Protocol (FTP) communication. 5.1 HIGHLIGHTS Information in this chapter includes: • Application Overview • Demonstration Setup • Configuring your Laptop or Desktop PC • FTP Server Demonstration • Summary 5.2 APPLICATION OVERVIEW This demonstration program illustrates file transfers between an embedded application on the dsPIC30F6014 and a remote computer. The embedded application uses the CMX-MicroNet TCP/IP Stack configured as an FTP Server. The FTP server “associates” system application data with a virtual file system implemented in the dsPIC Flash memory. A typical dsPIC30F FTP application allows data files produced by the dsPIC device and stored in the virtual file system to be retrieved remotely for such tasks as data logging, inventory control, performance analysis, and more, on the remote computer system. Some applications may update Program Flash on a remote dsPIC device from a central server location. In other applications, FTP activity may execute on a scheduled basis using automatic error detection/correction to ensure that data is properly transmitted and received. CMX-MicroNet FTP Server is fully compliant with Internet Engineering Task Force (IETF) and Request for Comments (RFC) standards and supports Windows-, DOS-, UNIX- and Linux-based FTP clients. For detailed information on these standards, refer to: www.ietf.org/ and www.faqs.org/rfcs/, respectively. This sample application demonstrates two main activities supported by the dsPIC30F6014 FTP Server: • Retrieving a file on the FTP server from an FTP client • Transmitting data to the FTP server from an FTP client This demonstration is set up to run with a Microsoft Windows FTP client or at the command prompt. PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 62  2004 Microchip Technology Inc. 5.3 DEMONSTRATION SETUP 5.3.1 Equipment Requirements This demonstration requires the following equipment: • dsPICDEM.net Development Board Kit with dsPIC30F6014 Plug-in-Module (PIM) • Crossover Cable (or standard Ethernet cable and access to a network or hub) • MPLAB IDE Integrated Development Environment • MPLAB ICD 2 In-Circuit Debugger • Laptop or Desktop PC with RS-232 serial port or USB port for connecting to the MPLAB ICE 2 In-Circuit Emulator • RJ-11 phone cable for connecting the MPLAB ICD 2 to the dsPICDEM.net board. 5.3.2 Equipment Setup Connect the dsPICDEM.net board to your PC or laptop as shown in Figure 5-1. FIGURE 5-1: FTP SERVER DEMONSTRATION SETUP 1. Connect the MPLAB ICD 2 to your PC with the USB cable. 2. Using the short RJ-11 phone cable, connect the MPLAB ICD 2 to RJ-11 modular connector ICD on the board. 3. Connect one end of the supplied CAT-5 crossover cable to RJ-45 modular connector J15 on the board and the other end to the Ethernet network card on the PC or Laptop. 4. Connect the dsPICDEM.net power cable to the power input connector (J14). PC running MPLAB® IDE and DOS Command Prompt dsPICDEM.net™ Connectivity Development Board running FTP Ssrver demonstration Ethernet connection J15 115 VAC 9 VDC Power Cable ICD J14 USB Port Connect board to PC with CAT-5 crossover cable Apply power to board Connect MPLAB® ICD 2 to PC with USB cable Connect MPLAB® ICD 2 to board with RJ-11 phone cable FTP Server Demonstration  2004 Microchip Technology Inc. DS51471A-page 63 5.3.3 FTP Server Program Setup Copy the FTP Server folder from the dsPICDEM.net Development Kit Software CD to the C:\ drive on your PC or laptop (see Figure 5-2). FIGURE 5-2: FTP SERVER DEMONSTRATION CODE 5.4 CONFIGURING YOUR LAPTOP OR DESKTOP PC The FTP server demonstration is configured to operate with a Static IP address. To run the sample program you must configure the local network connections on your laptop or desktop computer to use a compatible Static IP address. 5.4.1 Network Connections To reconfigure your network connections, follow these steps: 1. From the Windows desktop, click Start>Settings>Network Connections> Local Area Connection. 2. Right-click Local Area Connection and select Properties. The Local Area Connection Properties dialog displays your current connections. 3. On the General tab, scroll down the list of connections to Internet Protocol TCP/IP, then click Properties. The Internet Protocol (TCP/IP) Properties dialog displays, as shown in Figure 5-3. Make a note of your current settings so you can restore them later. 4. On the General tab, check Use the following IP address: and type in these settings: 5. Check OK in each dialog box until you close all the windows. Depending on the version of Windows you are running, you may be required to reboot your PC for the changes to take effect. 6. Proceed with the FTP Server demonstration. Copy FTP Server folder from CD to your C:\ drive Note: Before you reconfigure your network connection settings for this sample program, make a note of your current PC settings. You will want to restore your original PC settings after you complete the demonstration. IP Address: 216 . 233 . 5 . 32 Subnet mask: 255 . 255 . 255 . 0 PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 64  2004 Microchip Technology Inc. FIGURE 5-3: IP SETTINGS DIALOG 5.5 FTP SERVER DEMONSTRATION 5.5.1 Programming the dsPIC30F6014 Device This exercise requires that the dsPIC30F6014 device be programmed with the FTP demonstration program (ftpdemo.hex). If you have previously loaded this program on a dsPIC30F6014 device you can proceed directly to Section 5.5.2 “Start FTP Server Session”. 1. Apply power to the board. The green POWER LED illuminates. 2. Launch MPLAB IDE on your PC. From the Configure menu, choose Select Device, then select dsPIC30F6014. 3. From the MPLAB IDE Debugger menu, choose Select Tool, then select MPLAB ICD 2. You should see a connection message in the output window, as shown in Figure 5-4. Check button Type IP address FTP Server Demonstration  2004 Microchip Technology Inc. DS51471A-page 65 If the MPLAB ICD 2 does not initially connect and recognize the dsPIC30F6014 device, click the MPLAB ICD 2 puck icon on the MPLAB IDE toolbar. The output window should then indicate a successful connection. FIGURE 5-4: MPLAB ICD 2 CONNECTION MESSAGE WITH dsPIC30F6014 4. From the MPLAB IDE File menu, select Import. Browse to c:\FTP Server and open ftpdemo.hex. 5. From the MPLAB IDE Configure menu select "Configuration Bits” and verify the device configuration settings shown in Figure 5-5. FIGURE 5-5: FTP SERVER CONFIGURATION BITS SETTINGS 6. From the MPLAB IDE Debugger menu select Program. The ftpdemo.hex file downloads to the dsPIC30F6014. The Output Window records the process as it occurs and indicates completion by displaying "MPLAB ICD 2 Ready”. 7. Press to reset the program, then press to run the program. The LCD on the dsPICDEM.net board indicates that the program is running, as shown in Figure 5-6. FIGURE 5-6: LCD DISPLAY FOR FTP DEMONSTRATION CMX-MicroNet FTP Server Demo PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 66  2004 Microchip Technology Inc. 5.5.2 Start FTP Server Session After programming the demonstration into the dsPIC30F6014, follow these steps: 1. If CMX-MicroNet FTP Server is not running, press (Reset) followed by (Run). 2. From Windows, open a DOS command session. 3. From the command line prompt, type “ftp 216.233.5.31” to connect to the dsPIC30F6014 FTP Server. When the connection is made you will be prompted for your user name and password. 4. For the user name type “cmx”. 5. When prompted for the password, type “password”. Upon successful sign-on you will have connected to the FTP Server running on the dsPIC30F6014 device. You will see a transaction sequence similar to that shown in Figure 5-7. FIGURE 5-7: LOG ON FTP SERVER SESSION This screen shows when the connection is made and when the user is successfully logged on. This program only uses commands necessary to receive files from and send files to the dsPIC30F device. For information on the command set supported by CMX-MicroNet FTP Server, refer to the “FTP FUNCTIONS” section of the CMX-MicroNet TCP/IP STACK Manual. Note: Both the user and password are case-sensitive. Be sure both entries are lower case. Successful sign-on Successful connection FTP Server Demonstration  2004 Microchip Technology Inc. DS51471A-page 67 5.5.3 Receive File From FTP Server This portion of the demonstration shows how you might retrieve a file from the FTP Server virtual file system in dsPIC30F6014 memory. 1. At the ftp> prompt, type “dir”. 2. The FTP Server returns a listing of the files in its virtual file system, as shown in Figure 5-8. FIGURE 5-8: RECEIVING A FILE FROM THE FTP SERVER 3. At the next ftp> prompt, type get index.htm. As the file downloads, the DOS screen displays status milestones: command received (200), file ready to send (150), and file transferring (226). 4. When the file transfer is complete, the status displays the number of bytes transferred, how long it took, and the transfer rate achieved. At the next ftp> prompt, type “quit” to close the FTP session, but leave the DOS session running. 5. In Windows, locate and view the transferred file using a graphics program (see Figure 5-9). This file is located in the directory from which you ran the DOS command FTP session (c:\). PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 68  2004 Microchip Technology Inc. FIGURE 5-9: IMAGE OF TRANSFERRED FILE 5.5.4 Send a File to FTP Server This portion of the demonstration shows how you might transfer a file to the embedded application. The demonstration process is conducted in three parts. First you create a file on your PC to transfer to the dsPIC30F6014 FTP Server. Next you open an FTP session and transfer the file. And finally, you use MPLAB IDE to examine the actual contents of the FTP virtual file memory on the dsPIC30F6014 device. To create the demonstration file to be transferred: 1. At the DOS command line prompt, type “notepad”. 2. When Notepad displays, type the following message: “This is a test file to demonstrate the dsPIC30F6014 FTP Server.” 3. Save the message as c:\testdemo.txt. To transfer the demonstration file: 1. Open another FTP session (see Section 5.5.2 “Start FTP Server Session”). 2. At the ftp> prompt, type “put testdemo.txt”. As the transfer progresses, milestones are displayed sequentially. When the file transfer is complete, the status displays the number of bytes transferred, how long it took, and the transfer rate achieved. 3. At the next ftp> prompt, type “dir” to verify that the file is now in the FTP server virtual data memory. The listing shows that the file is included, as shown in Figure 5-10. FTP Server Demonstration  2004 Microchip Technology Inc. DS51471A-page 69 FIGURE 5-10: FTP SEND DEMONSTRATION SESSION 4. At the ftp> prompt, type “quit” to end the FTP session. Then type “exit” to close the DOS command prompt. 5. Go to MPLAB IDE and press to halt the FTP Server program in the dsPIC30F6014. To examine FTP Server memory: 1. In MPLAB IDE select View > File Registers. The File Registers window displays the contents of the FTP Server virtual file. The information displayed in red represents new data in FTP Server memory. Information related to this demonstration starts around address location 0x850. 2. Page down the File Registers window to until you see the values displayed in red. Examine the ASCII data to look for the file name (testdemo.txt) in the ASCII area, as shown in Figure 5-11. FIGURE 5-11: FTP VIRTUAL FILE DIRECTORY ENTRY 3. Next, scroll down to the next block of red data (approximately at address 0x2000-0x2100). Examine the ASCII area to find the content of the testdemo.txt file, as shown in Figure 5-12. Shows testdemo.txt file PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 70  2004 Microchip Technology Inc. FIGURE 5-12: FILE CONTENT RECEIVED BY FTP SERVER 4. In MPLAB, close the workspace and exit the program. 5.6 SUMMARY This demonstration has illustrated the basic capability of the dsPIC30F6014 functioning as an embedded FTP Server. As stated in Section 5.2 “Application Overview” an embedded FTP server may be suitable in such applications such as data logging, inventory control, remote system performance analysis and remote reprogramming of the dsPIC Program Memory Flash, just to mention a few. The FTP Server uses the TCP/IP protocol layer, which ensures an ordered reliable delivery of the data. The Program Memory Flash and Data RAM resources requirements for the CMX-MicroNet Stack is presented in Table 5-1. TABLE 5-1: RESOURCES FOR THE CMX-MICRONET STACK Content of testdemo.txt file Flash UDP/IP + Core 4470 bytes TCP/IP + Core 7827 bytes UDP/TCP/IP + Core 8685 bytes PPP 6681 bytes Modem 447 bytes HTTP Server 3888 bytes Virtual File 885 bytes Ethernet 2652 bytes DHCP Client 2202 bytes FTP Server 3657 bytes TFTP Client 723 bytes BOOTP 684 bytes SMTP 1918 bytes Utility 1314 bytes RAM (not including buffer sizes) UDP/SLIP 56 bytes TCP/HTTP/PPP 304 bytes Ethernet 38 bytes  2004 Microchip Technology Inc. DS51471A-page 71 dsPICDEM.net™ 1 AND dsPICDEM.net 2 CONNECTIVITY DEVELOPMENT BOARD USER’S GUIDE Chapter 6. V.22bis Soft Modem Demonstration 6.1 INTRODUCTION This chapter describes the dsPIC30F Soft Modem demonstration running on the dsPICDEM.net Development Board. The demonstration software is a subset of the dsPIC30F data modem library offered by Microchip. The dsPIC30F data modem library is composed of ITU-T compliant algorithms for V.21, V.22, V.22bis, V.23, V.32 and V.32bis modem recommendations and Bell standard 103. The dsPIC30F data-modem included as part of the dsPICDEM.net Connectivity Development Board and demonstrated in this section supports V.22bis and all lower data pump modulations. Full source code for V.22bis and lower data pump modulations is provided on the dsPICDEM.net Development Kit Software CD. V.32bis is not part of this demonstration package but is available for purchase. For detailed information on the soft modem refer to the dsPIC30F Soft Modem User’s Guide provided on the dsPICDEM.net Development Kit Software CD. 6.1 HIGHLIGHTS Information covered in this chapter includes: • Demonstration Overview • Demonstration Configurations • Demonstration Procedures • Reprogramming the dsPIC30F6014 • Description of dsPIC30F Soft Modem • dsPIC30F Soft Modem AT Command Set • Troubleshooting the Connection • Regulatory Compliance Reference Information • ITU-T Specifications 6.2 DEMONSTRATION OVERVIEW This demonstration illustrates the ability of the dsPIC30F Soft Modem to connect to another modem for transmitting and receiving data over the PSTN. The demonstration program implements real-time ITU-T V.22bis Transmit and Receive Data Pump Modulations. For specific information related to key features and performance metrics for the dsPIC30F Soft Modem see Section 6.6 “Description of dsPIC30F Soft Modem”. PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 72  2004 Microchip Technology Inc. Some possible applications implied by this demonstration include: • POS Terminals • Set Top Boxes • Drop Boxes • Fire Panels • Internet-enabled home security systems • Internet-connected power, gas and water meters • Internet-connected vending machines • Smart Appliances • Industrial Monitoring 6.3 DEMONSTRATION CONFIGURATIONS The soft modem demonstration is set up to run either as a pair of dsPIC30F devices running the soft modem and connected end-to-end, or as a dsPIC30F device communicating with a remote terminal equipped with a standard reference modem. The LEDs and switches on the dsPICDEM.net board are not used for the soft modem demonstration. 6.3.1 Equipment Requirements The soft modem demonstration requires the following equipment: • dsPICDEM.net Development Board for originate/answer modem • dsPICDEM.net Development Board or standard reference modem for answer/originate modem • PC or laptop for configuring and controlling dsPIC30F soft modem(s) via AT commands • PC or laptop for configuring and controlling standard reference modem via AT commands • Analog phone line for each originate and answer modem • RJ-11 phone cable for each dsPICDEM.net board and standard reference modem (not provided) 6.3.2 Selecting the Demonstration Configuration Figure 6-1 illustrates the set-up configuration for operating the end-to-end soft modem demonstration. This configuration requires the modem software on both dsPICDEM.net boards. The soft modem is controlled by AT commands entered on the Windows HyperTerminal (or suitable alternative terminal emulator) running on the PC or Laptop. This demonstration requires two analog phone lines, one each for the originate and answer modems. Note: Connect dsPICDEM.net to an analog line only. Using a non-analog line (e.g., digital, PBX Multi line) may damage the modem. V.22bis Soft Modem Demonstration  2004 Microchip Technology Inc. DS51471A-page 73 FIGURE 6-1: END-TO-END DEMONSTRATION SET UP Figure 6-2 illustrates the set-up configuration for the interoperability soft modem demonstration. With this configuration, one terminal is the dsPIC30F running the soft modem. The other terminal is a PC or laptop with a standard reference modem. (See Section 6.8.1 “Standard Reference Modems” for a list of tested reference modems). The soft modem is controlled by AT commands entered on the HyperTerminal or suitable terminal emulator program running on a PC or laptop. The other terminal is controlled by the terminal emulator on the opposite PC or laptop. This demonstration requires two analog phone lines, one each for the originate and answer modems. FIGURE 6-2: INTEROPERABILITY DEMONSTRATION SET UP Analog Telephone Exchange RS232 or TAS RS232 RJ-11 PC running Windows HyperTerminal PC running Windows HyperTerminal dsPICDEM.net™ Connectivity Board running Soft Modem Analog Telephone Exchange RS232 or TAS RS232 RJ-11 PC running Windows HyperTerminal PC running Windows HyperTerminal dsPICDEM.net™ Connectivity Board with Soft Modem Standard Reference Modem PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 74  2004 Microchip Technology Inc. 6.4 DEMONSTRATION PROCEDURES Follow these steps to exercise the soft modem functionality in real time. The dsPIC30F6014 device plugged into the dsPICDEM.net board has been pre-programmed with the V.22bis data-modem for this demonstration. If the demonstration program has been replaced by another application, you will need to reprogram the dsPIC30F6014 (see Section 6.5 “Reprogramming the dsPIC30F6014” for instructions on programming the soft modem into the dsPIC). 6.4.1 Initialize the Hardware 1. Configure the demonstration for end-to-end operation, as shown in Figure 6-1, or interoperability, as shown in Figure 6-2. 2. Make sure the 2x2 shunts on J17 and J19 are inserted in vertical alignment (perpendicular to the LCD display) 3. Apply power to the dsPICDEM.net Board(s) and/or the standard reference modem. 4. Press and release the RESET switch located to the right of the LCD. The LCD acknowledges that the soft modem is initialized, as shown in Figure 6-3 FIGURE 6-3: LCD DISPLAY 6.4.2 Configure the Terminal for dsPIC30F Soft Modem These procedures assume, but do not require, that you are using the Windows HyperTerminal. 1. Start HyperTerminal on both PCs. If you are set up for interoperability and are using a standard reference modem on one terminal, consult the modem user manual for specifics on configuring the modem. 2. Configure HyperTerminal with these settings: Bits per second = 19200 Data bits = 8 Parity = None Stop bits = 1 Flow Control = Hardware Set the Comm Channel appropriately for each PC. dsPIC30F V.22bis Soft-Modem Demo V.22bis Soft Modem Demonstration  2004 Microchip Technology Inc. DS51471A-page 75 3. Execute these AT commands on each HyperTerminal and note the response. 6.4.3 Initiate Communication At this point, the dsPIC30F Soft Modem is ready to establish a dial connection with another modem. 1. Initiate dialing with the following AT command: ATD where indicates the telephone number of the remote soft modem. By default, ‘auto answer after one ring’ is enabled. The remote soft modem answers the call after one ring and connects in V.22bis and V.42 (LAPM) Mode. ITU-T Recommendation V.42 contains a High Level Data Link Control (HDLC) protocol referred to as Link Access Procedure for Modems (LAPM) and defines error-correcting protocols for modems The following result codes are displayed on both the Hyper Terminals upon a successful connection. CARRIER 2400 PROTOCOL LAPM CONNECT 19200 You should hear the call negotiation and training sequence on the call progress speaker. If you are using a standard reference modem on one terminal, the connection message transmitted and displayed on the PC may be slightly different but should present this same basic information. See Section 6.8.6 “Response Messages for Successful Modem Connections” for an example of a connection message provided by a USR 5686E type modem. 2. With the two modems connected, test data transfer by typing information on one terminal and verifying that the same data is displayed on the other terminal. 3. Test file transfer by creating a brief text file and using following file transfer options on the HyperTerminal. HyperTerminal>Transfer>Send Text File HyperTerminal>Transfer>Capture File 4. Repeat the test procedure for the other modulation protocols by executing the following AT commands: Command* Response AT OK AT&F OK ATX0 OK ATS0=1 OK *Refer to Section 6.7 “dsPIC30F Soft Modem AT Command Set” for descriptions of AT commands supported. Protocol Command V.22bis-2400 bps AT+MS=2,0,300,2400 V.22bis-1200 bps AT+MS=2,0,300,1200 V.23 bps AT+MS=3,0,300,1200 V.21 bps AT+MS=0,0,300,300 Bell 103-300 bps AT+MS=1,0,300,300 PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 76  2004 Microchip Technology Inc. 5. You may need to reset and reconfigure the standard reference modem for enabling these specific data modulations. Consult the standard reference modem user’s manual for this information. An example of configuring a USR modem for V.21 and V.23 is presented in Section 6.8.4 “V.23 Connection Between dsPIC30F Soft Modem and US Robotics Modem” and Section 6.8.5 “V.21 connection Between dsPIC30F Soft Modem and US Robotics Modem” 6.5 REPROGRAMMING THE dsPIC30F6014 Should you need to reprogram the dsPIC30F6014 device begin by copying the PC-Based Soft Modem folder from the dsPICDEM.net Development Kit Software CD to the C:\drive on your PC or laptop (see Figure 6-4). FIGURE 6-4: PC-BASED SOFT MODEM DEMONSTRATION CODE The easiest way to get the soft modem demonstration up and running is to program the provided .hex file into the dsPIC device using this procedure: 1. Apply power to the board. The green POWER LED illuminates. 2. Launch MPLAB IDE on your PC. From the menu bar select Configure>Select Device>dsPIC30F6014. 3. Select Programmer>Select Tool>MPLAB ICD 2. You should see a connection message in the MPLAB IDE output window, as shown in Figure 6-5. If the MPLAB ICD 2 does not initially connect and recognize the dsPIC30F6014 device, click the MPLAB ICD 2 puck icon on the MPLAB IDE toolbar. The output window should then indicate a successful connection. FIGURE 6-5: MPLAB ICD 2 CONNECTION MESSAGE WITH dsPIC30F6014 Copy V.22bis Soft Modem folder from CD to your C:\ drive V.22bis Soft Modem Demonstration  2004 Microchip Technology Inc. DS51471A-page 77 4. From the MPLAB IDE File menu, select Import. Select V22bisdemo.hex and click Open. 5. From the MPLAB IDE Configure menu, select Configuration Bits and verify the device configuration settings shown in Figure 6-6. FIGURE 6-6: CONFIGURATION BITS WINDOW 6. From the MPLAB IDE Programmer menu select Program. The V22bisdemo.hex file downloads to the dsPIC30F6014. The Output Window records the process as it occurs and indicates completion by displaying “MPLAB ICD 2 Ready”. 7. Remove the MPLAB ICD 2 cable from the board then press RESET on the demonstration board to run the program. The LCD on the dsPICDEM.net board indicates that the program is running, as shown in Figure 6-7. FIGURE 6-7: LCD DISPLAY At this point you are ready to run the soft modem demonstration, as described in Section 6.4 “Demonstration Procedures”. Recapture dsPIC30F V.22bis Soft-Modem Demo PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 78  2004 Microchip Technology Inc. 6.6 DESCRIPTION OF dsPIC30F SOFT MODEM The Microchip data modem library includes ITU-T compliant algorithms for V.21, V.22, V.22bis, V.23, V.32 and V.32bis modem recommendations as well as Bell standard 103. These are the important parameters: • V.21, V.23 and Bell 103 are Frequency Shift Keying (FSK) modems. • V.32, V.32bis and V.22bis are Quadrature Amplitude Modulated (QAM) modems. • V.22 is a Phase Shift Keyed (PSK) modem. • V.21, V.22, V.22bis, V.32 and V.32bis are two-wire, full-duplex modems. • V.23 is full-duplex when it operates with a 75-bps backwards channel. • V.22bis includes fallback to V.22, V.23 and V.21 standards. • V.32bis optionally falls back to V.22bis, V.22, V.23 and V.21 standards. These key parameters are further detailed in Table 6-1. TABLE 6-1: SOFT MODEM FEATURES AND PERFORMANCE Algorithm(1) Performance Memory(2) (Kbytes) Data Rate MIPS (bps) Half/Full Duplex Data Modulation Program Data V.21/Bell 103(4) 300 Full FSK 13 1.0 4.5 V.22/V.22bis 1200 Full PSK/QAM 22 1.7 7 2400 V.23(4) 1200 Half FSK 15 1.0 4.5 600 V.32 9600 Full QAM/TCM 31 3.2 12 4800 v.32BIS 14400 Full QAM/TCM 36 3.6 15 1200 9600 7200 4800 v.42 n/a 14 2.0 1.5 DP + V.42 API n/a 7 1.2 - AT Command Set n/a 7 0.15 - Note 1: Data pump modules, V.21, V.22, V.22bis, V.23, V.32, V.32bis and Bell 103 are implemented in Assembly language. V.42, Data Pump and AT Command APIs are implemented in C language. 2: The program/data memory usage for the V-series data pumps is NOT cumulative, due to the sharing of components internally. 3: Memory size does not account for application which combines data pump, V.42 and AT commands (if required). 4: V.21/Bell 103 and V.23 data pumps do not require V.42. V.22bis Soft Modem Demonstration  2004 Microchip Technology Inc. DS51471A-page 79 6.7 dsPIC30F SOFT MODEM AT COMMAND SET The AT commands listed in Table have been selected to serve embedded soft modem applications on the dsPIC30F product family. These commands are a subset of the overall AT command set. Although the command set includes support for up to V.32bis, only V.22bis is supported in this demonstration. TABLE 6-2: AT COMMAND SET FOR dsPIC30F SOFT MODEM Command Description En Command Echo E0 – Inhibits the echoing of commands to the computer E1 – Echoes commands to the computer Hn Hang Up And Hook Control H – Modem hangs up and go on-hook. H0 – Causes the modem to go on-hook H1 – Causes the modem to go off-hook Ln Control Speaker Volume L0 – Speaker Turn off L1 – Low L2 – Medium (Default) L3 – High In Information and Identification This command has various options which are used to instruct the modem to provide specific information about itself I0 – Displays the modem controller firmware revision I3 – Same as I0 I4 – Current modem settings I6 – Link diagnostics Qn Quiet Mode Determines whether the modem sends result codes and status codes (OK, BUSY, RING, etc.) to the terminal. Q0 – Display result codes, user sees command responses (e.g., OK) Q1 – Result codes are suppressed, user does not see responses Vn Result Code Form Selects whether the modem sends long form (in words) or short form (numeric) result codes the terminal. V0 – Numeric result codes V1 – English result codes (e.g., CONNECT, BUSY etc.) A Answer Modem goes off hook, transmits answer tone and waits for a carrier response from the remote modem. Dnnn.. Dial Dials a telephone number and attempts to connect. The dial command must be the last command on the line. To cancel the Dial command, press any key. To dial 5588257, type ATD5588257 T Local Loop Back Modem Starts Local loop back On Enter Connect State and Retrain O0 – Leave online command mode and return to online data mode. O1 – Issues the retrain command PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 80  2004 Microchip Technology Inc. Wn Negotiation Progress Message Control W0 – CONNECT result code reports DTE speed; disable the display of all extended result codes. W1 – CONNECT result code reports DTE speed, enable the display of CARRIER and PROTOCOL extended codes only. W2 – CONNECT result code reports DCE speed; disable the display of all the extended result codes. Xn Dial Tone And Busy Tone Detection X0 – Busy detect and dial tone detect disabled X1 – Busy detect and dial tone detect disabled X2 – Busy detect disabled and dial tone detect enabled X3 – Busy detect enabled and dial tone detect disabled X4 – Busy detect and dial tone detect enabled &F Modem Reset Restore settings to defaults (Modem reset). &Kn Modem Flow Control This command determines how the flow control between the computer and the local modem is handled. &K0 – Disable local flow control &K3 – Enable RTS/CTS (Hardware) flow control (default) &K4 – Enable XON/XOFF (Software) flow control &Qn Communication Mode Q5 – Modem negotiates an Error-corrected link (default) Q6 – Selects asynchronous operation +MS_1,2,3,4, Select Modulation +MS=,,, Where, - Is specified modulation - Enables the auto mode operation. This mode is always enabled. - Sets the lowest modem speed - Sets the highest modem speed Modulation Possible Rates (bps) 0 V.21 300 2 V.22bis 2400 or 1200 31 V.23 1200 9 V.32 9600 or 4800 By default V.32-9600 mode is selected and V.22bis/V.23/V.21 modes can be selected by the following commands respectively V.32bis-14400 bps - AT+MS=9,0,300,14400 V.32bis-12000 bps - AT+MS=9,0,300,12000 V.32bis-9600 bps - AT+MS=9,0,300,9600 V.32bis-7200 bps - AT+MS=9,0,300,7200 V.32-9600 bps - AT+MS=8,0,300,9600 V.32-4800 bps - AT+MS=8,0,300,4800 V.22bis -2400 bps - AT+MS=2,0,300,2400 V.22bis-1200 bps - AT+MS=2,0,300,1200 V.23 bps - AT+MS=3,0,300,1200 V.21 bps - AT+MS=0,0,300,300 Bell 103 -300 bps - AT+MS=1,0,300,300 Note 1: For V.23, originating mode transmits at 75 bps and receives at 1200 bps. Answering mode transmits at 1200 bps and receives at 75 bps. TABLE 6-2: AT COMMAND SET FOR dsPIC30F SOFT MODEM (CONTINUED) Command Description V.22bis Soft Modem Demonstration  2004 Microchip Technology Inc. DS51471A-page 81 6.8 TROUBLESHOOTING THE CONNECTION The dsPIC30F Soft Modem has undergone multiple levels of testing, ranging from extensive bench testing using standard, off-the-shelf reference modems to full ITU-T compliance testing. The reference modems used in the testing are listed in Table 6-3. Reference modems are not all equal in terms of data pump (DP) modulations they support as power-on default. For example, the US Robotics External 56K modem, model 5686E, supports V.21 and V.23, but only if it is enabled via suitable AT commands. Attempts to connect with V.21 and V.23 will fail until these DP modulations have been enabled. Also the US Robotics External 56K modem, model 5686E, does not support V.32 9600 bps (NTCM). The modem will disconnect after the rate exchange sequence during the V.32 hand shake, since this is an invalid speed setting in V.32 mode. It connects at 9600 bps (TCM) in V.32bis mode. This troubleshooting section does not address every specification or operational feature of the reference modems. It is intended to be a starting point should you experience some basic connection issues. ATSn=x ATSn? S-Registers These registers are used set some of the simple modem configurations. Command writes the value ‘x’ to the specified S-register (n). Command displays the value of S-register (n) S0 Ring to Auto-answer On Sets the number of rings required before the modem answers. Auto answer ring count. Default Value: S0 = 1 S1 Ring Counter Counts and stores the number of rings from an incoming call. S6 Wait Before Dialing Sets the number of seconds the modem waits for dial tone before dialing. Default Value S6 = 1 S7 Wait for Carrier After Dial/Answer Sets the number of seconds the modem waits for a carrier or answers before returning on-hook and sending a NO CARRIER result code. Default Value S7 = 60 S91 Transmit Signal Level This register is used to specify the transmit signal level in –dBm value. Default Value S91 = 12 (-12 dBm) +++ Escape Sequence This is a three character escape code used to enter into the command mode from the data mode. TABLE 6-2: AT COMMAND SET FOR dsPIC30F SOFT MODEM (CONTINUED) Command Description PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 82  2004 Microchip Technology Inc. 6.8.1 Standard Reference Modems The dsPIC30F Soft Modem has undergone extensive testing to ensure ITU-T compliance and robust system operation. During performance and interoperability testing, the reference modems listed in Table 6-3 were used in both the originate and answer modes while communicating with the dsPIC30F Soft Modem on the dsPICDEM.net Connectivity Board. TABLE 6-3: REFERENCE MODEMS 6.8.2 ITU-T V.8 Support Currently the dsPIC30F Soft Modem falls back to other modulations only through V.8 handshake. Therefore the dsPIC30F Soft Modem will not be able to establish a connection in any DP modulation mode with reference modems that do not support the V.8 handshake. For example, D-Link and Zoom reference modems do not support the V.23 modulation selection through V.8 handshake when they are in originating mode. Therefore the dsPIC30F Soft Modem in answer mode will not be able to establish a V.23 connection with these reference modems. However in answer mode, these reference modems do support the falling back to V.23 modulations through V.8 handshake. Therefore the dsPIC30F Soft Modem in originate mode is able to establish a V.23 connection with these reference modems. 6.8.3 Data Flow Control By default, the dsPIC30F Soft Modem uses hardware flow control for data transfer. The dsPIC30F Soft Modem uses the UART flow control pins (RTS & CTS) on the dsPICDEM.net connectivity board. This configuration requires that a two-position shunt be installed in the vertical position on jumpers J17 and J19. Also, it is necessary to enable the hardware flow control in HyperTerminal (or other terminal emulation program running on the PC). It is possible to change the flow control mode of the dsPIC30F Soft Modem to Xon/Xoff by using a specific AT command (AT&Kn) and selecting a corresponding flow control mode in the HyperTerminal. Reference Modem Model Description U.S. Robotics 5686E External V.90/V.92 56k Fax/Modem U.S. Robotics 0839 External Sportster 33.6 Fax/Modem U.S. Robotics 98117203 External Sportster Voice 33.6 Fax/Modem Zoom 2949 External V.90 Fax/Modem Zoom 3049 External V.92 Fax/Modem D-Link DMF-336/E External 33.6 Fax/Modem D-Link DMF-560/ES External 56k Data/Fax/Voice Modem 3Com 455630-01 External 56k Fax/Modem V.22bis Soft Modem Demonstration  2004 Microchip Technology Inc. DS51471A-page 83 6.8.4 V.23 Connection Between dsPIC30F Soft Modem and US Robotics Modem Following are AT commands for enabling V.23 between the dsPIC03F Soft Modem and US Robotics Model 5686E Reference Modem. If the AT command is valid, HyperTerminal displays 'OK' as the response message. If the AT command is invalid or unsupported, HyperTerminal displays 'ERROR' as the response message. Supported AT commands for V.23 connection on US Robotics Modem: AT Command Function AT&F1 Enable factory default settings ATS0=1 Enable auto answer after one ring ATS27=16 Enable the V.23 fallback AT commands for V.23 connection on dsPIC30F Soft Modem: AT Command Function AT&F dsPIC30 Soft Modem default settings AT+MS=3,0,300,1200 Force V.23 connection 6.8.5 V.21 connection Between dsPIC30F Soft Modem and US Robotics Modem Following are AT commands for enabling V.21 between the dsPIC30F Soft Modem and US Robotics Model 5686E Reference Modem. If the AT command is valid, HyperTerminal displays 'OK' as the response message. If the AT command is invalid or unsupported, HyperTerminal displays 'ERROR' as the response message. Supported AT commands for V.21 connection on US Robotics Modem: AT Command Function AT&F1 Factory Default settings ATS0=1 Enable auto answer after one ring ATS27=1 Enable the V.21 fallback Supported AT commands for V.21 connection on dsPIC30F Soft Modem: AT Command Function AT&F Enable dsPIC30F Soft Modem default settings AT+MS=0,0,300,300 Force V.21 connection Note: In almost all the modems, a V.42 LAPM connection is not supported for V.21 and V.23 data pump modulation modes. Hence a connection will be established in Non-V.42 mode (PROTOCOL NONE). PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 84  2004 Microchip Technology Inc. 6.8.6 Response Messages for Successful Modem Connections Table 6-3 lists connection messages displayed on the HyperTerminal when a successful modem connection has been established between the dsPIC30F Soft Modem and the US Robotics Model 5686E modem using the V22bis demonstration. TABLE 6-4: SUCCESSFUL CONNECTION RESPONSE MESSAGES 6.9 REGULATORY COMPLIANCE REFERENCE INFORMATION Every country has telecommunication laws that prohibit the connection of unapproved telecommunication devices, including modems, to the phone line. Approval by a country's telecommunications regulatory agency may entail hardware/firmware modifications to your end-system modem in order to comply with telecommunication laws. Approval could require modifications for radio-frequency interference, pulse dial make/break ratios, redial capabilities, and so forth. The words "approved or compliant for use in country XYZ" mean that the modem has been modified to comply with the telecommunication laws of that country. An American modem approved by the Federal Communications Commission (FCC) in the United States and imported to Germany would not be a legal telecommunications device in Germany. FCC approval in the USA does not imply BZT approved in Germany. The Silicon Laboratories chipsets used with the dsPICDEM.net 1 and dsPICDEM.net 2 Connectivity Boards are compliant with FCC, Japan Approval Institute for Telecommunications Equipment (JATE) and Common Technical Regulation (CTR_21) country-specific Post, Telephone & Telegraph (PTT) specifications. The chipsets can be fully programmed for AC termination, DC termination, ringer impedance and ringer threshold, enabling the devices to meet worldwide telephone line interface requirements. The devices interface directly to standard modem DSPs or system interface circuits. Data Pump Modulation dsPIC30F Soft Modem US Robotics Model 5686E V.22bis 2400 bps CARRIER 2400 PROTOCOL LAPM CONNECT 19200 CONNECT 2400/ARQ/LAPM V.22 1200 bps CARRIER 1200 PROTOCOL LAPM CONNECT 19200 CONNECT 1200/ARQ/LAPM V.23 1200 bps CARRIER 1200/75 PROTOCOL NONE CONNECT 19200 (dsPIC30F Soft Modem is the answer modem) CONNECT 75/1200/NONE (USRobotics is the originate modem) CARRIER 75/1200 PROTOCOL NONE CONNECT 19200 (dsPIC30F Soft Modem is the originate modem) CONNECT 1200/75/NONE (USRobotics is the answer modem) V.21 300 bps CARRIER 300 PROTOCOL NONE CONNECT 19200 CONNECT Bell 103 TBP TBP V.22bis Soft Modem Demonstration  2004 Microchip Technology Inc. DS51471A-page 85 6.9.1 Federal Communications Commission The Federal Communications Commission (FCC) rules (47 C.F.R. Part 68) governs the direct connection of Terminal Equipment (TE) to the Public Switched Telephone Network (PSTN), and to wireline carrier-owned facilities used to provide private line services. 6.9.2 Industry Canada DOC CS-03 Approval of equipment for Canada is relatively straight-forward. Testing and compliance should be in accordance with technical standard CS-03. The requirements are well harmonized with FCC part-68. In many instances it is possible to use FCC reports to obtain Industry Canada DOC CS-03 approval. For additional information on FCC part-68 and approved test facilities refer to www.fcc.gov. 6.9.3 Common Technical Regulation CTR-21 CTR-21 is a Common Technical Regulation that defines a harmonized standard for analog access to the PSTN throughout the European Economic Area (EEA) and Switzerland. In the past, analog standards were not harmonized. Manufacturers were required to go to each country and test analog equipment to that country's unique specifications. CTR-21 simplifies this process by enabling manufacturers to go to one test lab and take one compliance test for all EEA member countries. The result is faster product delivery throughout the EEA market. 6.9.4 Japan Approval Institute for Telecommunications Equipment JATE is the institute that approves telecommunications equipment for use with Japan's public telephone network. Approved equipment bears a JATE approval mark or number. For more information on JATE refer to: www.jate.or.jp/index_e.html or Nippon Telegraph and Telephone (NTT) Corporation: www.ntt.co.jp/index_e.html. PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 86  2004 Microchip Technology Inc. 6.10 ITU-T SPECIFICATIONS Table 6-5 lists the ITU-T specifications used for development of the soft modem and DTMF implementation on the dsPIC30F product family TABLE 6-5: ITU-T SPECIFICATIONS ITU-T Specification Name Of The Document ITU-T V.32bis A duplex modem operating at data signalling rates of up to 14400 bit/s for use on the general switched telephone network and on leased point-to-point 2-wire telephone-type circuits. ITU-T V.32 A family of 2-wire, duplex modems operating at data signalling rates of up to 9600 bit/s for use on the general switched telephone network and on leased telephone-type circuits. ITU-T V.22bis 2400 bits per second duplex modem using the frequency division technique standardized for use on the general switched telephone network and on point-to-point 2-wire leased telephone-type circuits. ITU-T V.21 300 bits per second duplex modem standardized for use in the general switched telephone network. ITU-T V.23 600/1200-baud modem standardized for use in the general switched telephone network. ITU-T V.8 Procedures for starting sessions of data transmission over the public switched telephone network. ITU-T V.25 Automatic answering equipment and general procedures for automatic calling equipment on the general switched telephone network including procedures for disabling of echo control devices for both manually and automatically established calls. ITU-T V.42 Error-correcting procedures for DCEs using asynchronous-to-synchronous conversion. ITU-T V.56bis Network transmission model for evaluating modem performance over 2-wire voice grade connections. ITU-T V.56ter Test procedure for evaluation of 2-wire 4 kHz voice band duplex modems. ITU-T Q.23 Technical features of push-button telephone sets. ITU-T Q.24 Multi-frequency push-button signal reception.  2004 Microchip Technology Inc. DS51471A-page 87 dsPICDEM.net™ 1 AND dsPICDEM.net 2 CONNECTIVITY DEVELOPMENT BOARD USER’S GUIDE Chapter 7. dsPICDEM.net Development Hardware 7.1 dsPICDEM.net Hardware Components Figure 7-1 illustrates the major components that comprise the dsPICDEM.net Development Board. Table 7-1 identifies these hardware elements and points to the specific instructions for using each item. FIGURE 7-1: dsPIC30F6014 16-BIT SIGNAL CONTROLLER HARDWARE COMPONENTS TABLE 7-1: dsPICDEM™.net DEVELOPMENT BOARD HARDWARE No. Hardware Element No. Hardware Element 1 CAN Port (Section 7.1.2) 12 LCD Graphic Display (Section 7.1.9) 2 10-Base T Ethernet (Section 7.1.12) 13 Temperature Sensor (Section 7.1.4) 3 Oscillator (Section 7.1.18) 14 PSTN Telephone Interface (Section 7.1.11) 4 Emulation Header (Section 7.1.15) 15 Power On Indicator (Section 7.1.17) 5 Sample Devices (Section 7.1.21) 16 Power Supply (Section 7.1.16) 6 Prototyping Area (Section 7.1.20) 17 RS-232 Serial Port (Section 7.1.1) 7 64kx16 External SRAM (Section 7.1.14) 18 Serial EE Memory (Section 7.1.13) 8 Push Button Switches (Section 7.1.6) 19 RS-485/RS-422 Port (Section 7.1.3) 9 Reset Switch (Section 7.1.19) 20 Digital Potentiometer (Section 7.1.8) 10 LEDs (Section 7.1.7) 21 ICD 2 Connector (Section 7.1.10) 11 Analog Potentiometers (Section 7.1.5) 1 11 10 9 8 6 2 3 4 5 12 7 16 17 18 19 20 21 15 13 14 PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 88  2004 Microchip Technology Inc. 7.1.1 RS-232 Serial Port A single RS-232 serial communication channel is provided on the dsPICDEM.net Development Board. This serial communication channel, labeled J5, can be configured as an RS-232 or RS-485/RS-422 communication channel via jumpers J17, J18 and J19. The following jumper connections are required for RS-232 serial communications: • J19, shunt pins 1-2 for Tx channel support • J19, shunt pins 3-4 for Rx channel support • J17, shunt pins 1-2 for Request-to-Send (RTS) support • J17, shunt pins 3-4 for Clear-to-Send (CTS) support • J18, shunt pins 2-3 for Rx connection to the dsPIC device Jumper 19 connects the dsPIC UART channel 1 U1RX and U1TX pins to an RS-232 level shifting IC, U7. The serial port is configured as DCE, and can be connected to a PC using a straight-through cable. If hardware handshaking is required, inserting shunts on jumper J17 will connect CTS and RTS to port pins RA9 and RA10 on the dsPIC device. These pins can support CTS/RTS through a bit-bang control approach. Both pins are connected to IC U7. 7.1.2 CAN Port The CAN RXD and TXD lines of the MCP2551 are connected to the dsPIC CANRX and CANTX pins. CAN bus signals, CANH and CANL, are available on the DB9 connector J4. The CANH and CANL bus can be locally terminated with a 120 ohm by inserting jumper, J3. 7.1.3 RS-485/RS-422 Port Signals for the RS-485/RS-422 port are available on the 6-pin terminal block labeled TB1. The terminal block is configurable from RS-485 to RS-422 by removing the jumper on J2. Inserting jumper J1 will terminate the bus with a 120 ohm resistor. The RX485 and TX485 lines of the MAX489E can be tied to the dsPIC UART channel 1 U1RX and U1TX pins by the following jumper settings: • J19, shunt pins 1-2 for Tx channel support • J19, shunt pins 3-4 for Rx channel support • J18, shunt pins 1-2 for Rx connection to the dsPIC device MAX489E receiver and driver output enables are controlled by port pins RG0 and RG1, respectively. 7.1.4 Temperature Sensor This is a -40°C to +125°C linear output temperature sensor (TC1047A) connected to analog channel AN3 of the dsPIC device. The output of the temperature sensor, U2, is fed through a second order low-pass filter before connection to the dsPIC device. The LP filter cutoff frequency is set at 10 Hz. The output voltage range for the TC1047A is typically 750 mV at +25°C. The TC1047A exhibits a typical 10 mV/C voltage slope. Note: The shunts for J17 and J19 must be connected vertically. Note: The shunts for J19 must be connected vertically. dsPICDEM.net Development Hardware  2004 Microchip Technology Inc. DS51471A-page 89 7.1.5 Analog Potentiometers Two 5 kOhm potentiometers are connected to analog channels AN4 and AN5. The voltage output range for each potentiometer is between 0 VDC and 5 VDC. The voltage source is provided by VR1, through a low-pass filter. VR1 is the main voltage regulator for all components on the development board. 7.1.6 Push Button Switches Three switches, S1-S3, are connected to port pins RA12-RA14, respectively on the dsPIC device. The signal lines are normally pulled up to +5 VDC through 10 kΩ resistors. Pressing the switch will short the line to ground. Port pins RA12-RA14 are configured as the INT1-INT3 external interrupt pins. 7.1.7 LEDs Three red LEDs, LED1-LED3, are connected to port pins RC2 to RC4, respectively on the dsPIC device. The LED anodes are tied to VDD through a 1.2K resistor. 7.1.8 Digital Potentiometer A dual channel digital potentiometer, MCP42050, is provided on the development board. Control of the digital potentiometer is via the dsPIC SPI 1 communication channel. The outputs of the digital potentiometer are applied to test points PW0 and PW1. 7.1.9 LCD Graphic Display A 2 x 16 character dot matrix LCD display is provided on the development board. The dsPIC device accesses the LCD via PORTD pins RD0-RD7. The three LCD control signals, RS, RW and E are connected to dsPIC port pins RA6, RB11 and RA7 respectively. 7.1.10 ICD Connector By way of the modular connector ICD, the MPLAB ICD 2 can be connected for low-cost programming and debugging of the dsPIC device. Programming and debugging the dsPIC device is through dedicated use of the PGC/EMUC/RB1 and PGD/EMUD/RB0 pins on the development board. 7.1.11 Public-Switch Telephone Network (PSTN) Interface The dsPICDEM.net Development board is available in 2 configurations, one using the Si3035 chipset for the FCC and JATE compliant designs and the other using Si3034 chipset for worldwide applications.The dsPIC communicates with this port with its Data Converter Interface (DCI). The Si3035 chipset is composed of the Si3012 DAA and a Si3021 AFE ICs. The dsPIC communicates to the Si3021 AFE via its DCI peripheral module.The Si3034 chipset is composed of a Si3014 DAA and the same Si3021 AFE. A speaker is provided on the development board and provides for call progress monitoring. For detailed operation, please refer to the Si3034 and Si3035 data sheets available on www.silabs.com. PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 90  2004 Microchip Technology Inc. 7.1.12 10-Base T Ethernet An Ethernet interface is provided using the Realtek RTL8019 ethernet controller. This is accessed via the bidirectional bus on PORTD. For detailed operation of this device please see the RTL8019 data sheet from Realtek • STATUS LEDs: Four LEDs are provided: - LINK STATUS – This LED can be used for link status. - XMIT and RX – When the board is connected correctly, these are normally lit, and flash OFF (inverted logic), when the board is transmitting or receiving a packet (respectively). - BNC – This LED is enabled as default and indicates medium type. Connection to the Ethernet is supported via the RJ-45 modular connector. 7.1.13 Serial EE Memory Device A Microchip 24LC515 serial EEPROM provides 512 Kbit (64 Kbyte) of storage for constants such as Web pages, linearization tables for sensors and custom data tables. The 24LC515 is programmable via a two-wire serial I2CTM interface. 7.1.14 64k x 16 External SRAM A Cypress 1 Mbit (64k words) CY7C1021B CMOS Static RAM is provided and can be used to store temporary data for product development or diagnostic purposes. The CY7C1021B is accessible via a multiplexed bus on PORTD pins RD0-RD15. The SRAM control signals, CE, OE and WE are provided by the dsPIC PORTB pins RB9, RB10 and RB11 respectively. Two 74HCT573 Octal D-latches are implemented for latching the SRAM address. The high and low byte control signals, BHE and BLE, of the SRAM are tied to ground, through zero ohm resistors. Reads and writes to the SRAM are performed in the x16 data mode. The following is a typical sequence of steps for accessing the external SRAM device: 1. Place 16-bit address on PORTD and set pin direction (TRISD) as outputs 2. Assert ALE (RB12) to a logic ‘1’ from a logic ‘0’ to latch address 3. Assert control signal OE (RB10) to a logic ‘0’ for a read or logic ‘1’ for a write 4. For a write, place data on PORTD 5. Assert CE (RB9) to a logic ‘0’ to select SRAM chip 6. If performing a read, read data on PORTD 7. If performing a write, assert control signal WE (RB11) to a logic ‘1’ from a logic ‘0’ 8. Assert control signal CE (RB9) to a logic ‘1’ to deselect the SRAM 7.1.15 Emulation Header Headers J10-J13 provide for a connection to the MPLAB ICE 4K In-Circuit Emulator. The emulation headers also support the processor adaptor boards (see Section 7.1.21 “Sample Devices”). The processor adaptor boards enable quick change out of the 80-pin TQFP device. dsPICDEM.net Development Hardware  2004 Microchip Technology Inc. DS51471A-page 91 7.1.16 Power Supply The dsPICDEM.net Development Board is powered by a +9V AC/DC wall adapter. A single +5 VDC regulator provides all board components with +5 VDC. Analog components are sourced from this same regulator through a low-pass filter circuit. Separate analog and digital ground planes are connected through a single point. Jumper J6 allows the supplied power source to be bypassed and an alternate supply to be provided. 7.1.17 Power-on Indicator A green LED is connected to the input of the regulators to indicate the presence of power. 7.1.18 Oscillator • Crystal oscillator (7.3728 MHz) supplied. • Thru holes and pads provided for user furnished watch-type crystal and two capacitors for SOSC1 and SOSC2. • Socket and pads for an output pull up resistor for user furnished crystal oscillator to processor. • External clock connections from J8. TABLE 7-2: OSCILLATOR SELECTIONS 7.1.19 Reset Switch This switch is tied to the MCLR pin on the dsPIC controller, and is used to reset the device. 7.1.20 Prototyping Area A prototyping area and associated header are provided which enables additional ICs and attachment boards to be added. 7.1.21 Sample Devices A sample dsPIC device programmed with the demonstration code is included in the dsPICDEM.net Development Board Kit. The 80-pin TQFP is soldered to a 1.5″ x 1.5″ adaptor PCB which is inserted onto the emulation header, J11 and J13-J15. Careful device handling should be used for inserting and extracting the adaptor board. The orientation of the adaptor board is important. The Microchip logo and device part numbering should be aligned to read from left to right before the insertion of the adapter board. Oscillator Selection on dsPICDEM™ Modifications on dsPICDEM™ Crystal R61, R62, R67, C42, C41 and XTAL2 open, U16 empty. Crystal in XTAL3, caps in C40 and C39. Mini Crystal R67, R61, R62, C40, C39 and XTAL3 open, U16 empty. Crystal in XTAL2, caps in C42 and C41. Canned Oscillator R67, R61, R62, C42, C41, C40, C39, XTAL2 and XTAL3 open, U16 installed. RC R61, R62, C42, C41, C40, XTAL2 and XTAL3 open, U16 empty. Cap in C39 and resistor in R67. External Clock R67, C42, C41, C40, C39, U16, XTAL2 and XTAL3 open. 0 ohm installed for R61 and R62. PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 92  2004 Microchip Technology Inc. NOTES:  2004 Microchip Technology Inc. DS51471A-page 93 dsPICDEM.net™ 1 AND dsPICDEM.net 2 CONNECTIVITY DEVELOPMENT BOARD USER’S GUIDE Appendix A. Hardware Schematics A.1 BOARD LAYOUT AND SCHEMATICS A.1.1 dsPICDEM.net 1 and dsPICDEM.net 2 Development Board The following figures show the parts layout (silk screen) and schematics for the dsPICDEM.net 1 and dsPICDEM.net 2 Development Board. PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 94  2004 Microchip Technology Inc. FIGURE A-1: dsPICDEM.net™ DEVELOPMENT BOARD LAYOUT Hardware Schematics  2004 Microchip Technology Inc. DS51471A-page 95 FIGURE A-2: dsPICDEM.net™ DEVELOPMENT BOARD SCHEMATIC (SHEET 1 OF 11) PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 96  2004 Microchip Technology Inc. FIGURE A-3: dsPICDEM.net™ DEVELOPMENT BOARD SCHEMATIC (SHEET 2 OF 11) Hardware Schematics  2004 Microchip Technology Inc. DS51471A-page 97 FIGURE A-4: dsPICDEM.net™ DEVELOPMENT BOARD SCHEMATIC (SHEET 3 OF 11) PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 98  2004 Microchip Technology Inc. FIGURE A-5: dsPICDEM.net™ DEVELOPMENT BOARD SCHEMATIC (SHEET 4 OF 11) Hardware Schematics  2004 Microchip Technology Inc. DS51471A-page 99 FIGURE A-6: dsPICDEM.net™ DEVELOPMENT BOARD SCHEMATIC (SHEET 5 OF 11) PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 100  2004 Microchip Technology Inc. FIGURE A-7: dsPICDEM.net™ DEVELOPMENT BOARD SCHEMATIC (SHEET 6 OF 11) Hardware Schematics  2004 Microchip Technology Inc. DS51471A-page 101 FIGURE A-8: dsPICDEM.net™ DEVELOPMENT BOARD SCHEMATIC (SHEET 7 OF 11) PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 102  2004 Microchip Technology Inc. FIGURE A-9: dsPICDEM.net™ DEVELOPMENT BOARD SCHEMATIC (SHEET 8 OF 11) Hardware Schematics  2004 Microchip Technology Inc. DS51471A-page 103 FIGURE A-10: dsPICDEM.net™ DEVELOPMENT BOARD SCHEMATIC (SHEET 9 OF 11) PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 104  2004 Microchip Technology Inc. FIGURE A-11: dsPICDEM.net™ DEVELOPMENT BOARD SCHEMATIC (SHEET 10 OF 11) Hardware Schematics  2004 Microchip Technology Inc. DS51471A-page 105 FIGURE A-12: dsPICDEM.net™ DEVELOPMENT BOARD SCHEMATIC (SHEET 11 OF 11) PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 106  2004 Microchip Technology Inc. NOTES:  2004 Microchip Technology Inc. DS51471A-page 107 dsPICDEM.net™ 1 AND dsPICDEM.net 2 CONNECTIVITY DEVELOPMENT BOARD USER’S GUIDE Index A Analog Devices .......................................................... 9 B Board Hardware......................................................... 9 C CAN Channel ............................................................. 8 Crossover Cable ........................................................ 8 Customer Notification Service.................................... 5 Customer Support...................................................... 6 D Data and Control Flow ............................................. 46 Power-up Peripheral Initialization ..................... 46 Demonstration Setup Tutorial.............................................................. 23 Web Server....................................................... 50 Development Board Features 10-Base T Ethernet............................................. 9 Analog Devices................................................... 9 Device Clocking .................................................. 9 MPLAB ICD 2 Connection MPLAB ICD 2 Connection ........................... 8 MPLAB ICE4000 Connections MPLAB ICE 4000 Connection ..................... 8 Power Supply Circuit .......................................... 8 Serial Communication Channels......................... 8 Voice-band Codec .............................................. 9 Development Board Layout ..................................... 94 Development Board Schematic................................ 95 Devlopment Board Features PTSN .................................................................. 9 Digital Potentiometers................................................ 9 Documentation Updates .............................................................. 2 E Emulation Header ...................................................... 8 External SRAM ........................................................ 10 F Free Software Foundation ......................................... 4 FTP Server Demonstration LCD Display...................................................... 65 Overview........................................................... 61 G GNU Language Tools ................................................ 4 H Hardware Board Components Analog Potentiometer Input .............................. 89 CAN Port........................................................... 88 Digital Potentiometer......................................... 89 Emulation Header ............................................. 90 ICD Connector .................................................. 89 LCD Graphic Display ........................................ 89 LEDs ................................................................. 89 Oscillator Options.............................................. 91 Power Supply.................................................... 91 Power-on Indicator............................................ 91 Prototyping Area ............................................... 91 Push Button Switches ....................................... 89 Reset Switch ..................................................... 91 RS-232 Serial Ports .......................................... 88 RS-485/RS-422 Port ......................................... 88 Sample Devices ................................................ 91 Si3000 Voice-band Codec .......................... 89, 90 Temperature Sensor......................................... 88 I Interface Cable........................................................... 8 Internet Address......................................................... 4 L Language Toolsuite............................................ 15, 34 LCD .......................................................................... 10 LCD Display FTP Server Demonstration ............................... 65 Web Server Demonstration............................... 53 LED Power-On............................................................ 8 LED Indicators.......................................................... 10 Link Status LEDs........................................................ 9 Low-Pass Filter .......................................................... 9 M Microchip Web Site .................................................... 4 MPLAB ICD 2........................................................... 11 MPLAB ICE 4000 ....................................................... 8 MPLAB ICE User’s Guide ........................................ 11 MPLAB IDE User’s Guide .......................................... 4 O Overview .................................................................. 13 FTP Server Demonstration ............................... 61 Web Server Demonstration............................... 49 P Packet Sniffers ......................................................... 57 Power Supply ............................................................. 8 Project ................................................................ 13, 32 Project Wizard.................................................... 13, 32 Prototyping Header .................................................. 10 PTSN.......................................................................... 9 PICDEM.net™ 1 and dsPICDEM.net 2 Connectivity Dev Board User’s Guide DS51471A-page 108  2004 Microchip Technology Inc. Push Button Reset................................................................. 91 Pushbutton Switches................................................ 10 R Recommended Reading............................................. 3 Reference Documents.............................................. 11 Reset Switch ............................................................ 10 RJ-45 (10-Base T) Connector .................................... 9 RS-232 Connection.................................................... 8 RS-422 Connection.................................................... 8 RS-485 Connection.................................................... 8 S Serial EE Memory .................................................... 10 Si3021 Reset Switch .................................................. 9 Si3034 DAA/AFE Chipset........................................... 9 Si3035 DAA/AFE Chipset........................................... 9 T Temperature Sensor ................................................ 88 Thermal Sensor (U12)................................................ 9 Troubleshooting Web Server Demonstration............................... 58 Tutorial ............................................................... 13, 31 U UART1........................................................................ 8 W Warranty Registration................................................. 2 Web Page Web Server Demonstration............................... 54 Web Server Demonstration LCD Display ...................................................... 53 Overview ........................................................... 49 Web Page ......................................................... 54 Workspace ......................................................... 13, 32 WWW Address ........................................................... 4  2004 Microchip Technology Inc. DS51471A-page 109 Index NOTES: DS51471A-page 110  2004 Microchip Technology Inc. AMERICAS Corporate Office 2355 West Chandler Blvd. Chandler, AZ 85224-6199 Tel: 480-792-7200 Fax: 480-792-7277 Technical Support: 480-792-7627 Web Address: www.microchip.com Atlanta 3780 Mansell Road, Suite 130 Alpharetta, GA 30022 Tel: 770-640-0034 Fax: 770-640-0307 Boston 2 Lan Drive, Suite 120 Westford, MA 01886 Tel: 978-692-3848 Fax: 978-692-3821 Chicago 333 Pierce Road, Suite 180 Itasca, IL 60143 Tel: 630-285-0071 Fax: 630-285-0075 Dallas 4570 Westgrove Drive, Suite 160 Addison, TX 75001 Tel: 972-818-7423 Fax: 972-818-2924 Detroit Tri-Atria Office Building 32255 Northwestern Highway, Suite 190 Farmington Hills, MI 48334 Tel: 248-538-2250 Fax: 248-538-2260 Kokomo 2767 S. Albright Road Kokomo, IN 46902 Tel: 765-864-8360 Fax: 765-864-8387 Los Angeles 18201 Von Karman, Suite 1090 Irvine, CA 92612 Tel: 949-263-1888 Fax: 949-263-1338 San Jose 1300 Terra Bella Avenue Mountain View, CA 94043 Tel: 650-215-1444 Fax: 650-961-0286 Toronto 6285 Northam Drive, Suite 108 Mississauga, Ontario L4V 1X5, Canada Tel: 905-673-0699 Fax: 905-673-6509 ASIA/PACIFIC Australia Suite 22, 41 Rawson Street Epping 2121, NSW Australia Tel: 61-2-9868-6733 Fax: 61-2-9868-6755 China - Beijing Unit 706B Wan Tai Bei Hai Bldg. No. 6 Chaoyangmen Bei Str. Beijing, 100027, China Tel: 86-10-85282100 Fax: 86-10-85282104 China - Chengdu Rm. 2401-2402, 24th Floor, Ming Xing Financial Tower No. 88 TIDU Street Chengdu 610016, China Tel: 86-28-86766200 Fax: 86-28-86766599 China - Fuzhou Unit 28F, World Trade Plaza No. 71 Wusi Road Fuzhou 350001, China Tel: 86-591-7503506 Fax: 86-591-7503521 China - Hong Kong SAR Unit 901-6, Tower 2, Metroplaza 223 Hing Fong Road Kwai Fong, N.T., Hong Kong Tel: 852-2401-1200 Fax: 852-2401-3431 China - Shanghai Room 701, Bldg. B Far East International Plaza No. 317 Xian Xia Road Shanghai, 200051 Tel: 86-21-6275-5700 Fax: 86-21-6275-5060 China - Shenzhen Rm. 1812, 18/F, Building A, United Plaza No. 5022 Binhe Road, Futian District Shenzhen 518033, China Tel: 86-755-82901380 Fax: 86-755-8295-1393 China - Shunde Room 401, Hongjian Building, No. 2 Fengxiangnan Road, Ronggui Town, Shunde District, Foshan City, Guangdong 528303, China Tel: 86-757-28395507 Fax: 86-757-28395571 China - Qingdao Rm. B505A, Fullhope Plaza, No. 12 Hong Kong Central Rd. Qingdao 266071, China Tel: 86-532-5027355 Fax: 86-532-5027205 India Divyasree Chambers 1 Floor, Wing A (A3/A4) No. 11, O’Shaugnessey Road Bangalore, 560 025, India Tel: 91-80-22290061 Fax: 91-80-22290062 Japan 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 168-1, Youngbo Bldg. 3 Floor Samsung-Dong, Kangnam-Ku Seoul, Korea 135-882 Tel: 82-2-554-7200 Fax: 82-2-558-5932 or 82-2-558-5934 Singapore 200 Middle Road #07-02 Prime Centre Singapore, 188980 Tel: 65-6334-8870 Fax: 65-6334-8850 Taiwan Kaohsiung Branch 30F - 1 No. 8 Min Chuan 2nd Road Kaohsiung 806, Taiwan Tel: 886-7-536-4818 Fax: 886-7-536-4803 Taiwan Taiwan Branch 11F-3, No. 207 Tung Hua North Road Taipei, 105, Taiwan Tel: 886-2-2717-7175 Fax: 886-2-2545-0139 EUROPE Austria Durisolstrasse 2 A-4600 Wels Austria Tel: 43-7242-2244-399 Fax: 43-7242-2244-393 Denmark Regus Business Centre Lautrup hoj 1-3 Ballerup DK-2750 Denmark Tel: 45-4420-9895 Fax: 45-4420-9910 France 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 Steinheilstrasse 10 D-85737 Ismaning, Germany Tel: 49-89-627-144-0 Fax: 49-89-627-144-44 Italy Via Quasimodo, 12 20025 Legnano (MI) Milan, Italy Tel: 39-0331-742611 Fax: 39-0331-466781 Netherlands P. A. De Biesbosch 14 NL-5152 SC Drunen, Netherlands Tel: 31-416-690399 Fax: 31-416-690340 United Kingdom 505 Eskdale Road Winnersh Triangle Wokingham Berkshire, England RG41 5TU Tel: 44-118-921-5869 Fax: 44-118-921-5820 02/17/04 WORLDWIDE SALES AND SERVICE

SAM L10/L11 Family Ultra Low-Power, 32-bit Cortex-M23 MCUs with TrustZone, Crypto, and Enhanced PTC Features • Operating Conditions: 1.62V to 3.63V, -40ºC to +125ºC, DC to 32 MHz • Core: 32 MHz (2.62 CoreMark/MHz and up to 31 DMIPS) ARM® Cortex®-M23 with: – Single-cycle hardware multiplier – Hardware divider – Nested Vector Interrupt Controller (NVIC) – Memory Protection Unit (MPU) – Stack Limit Checking – TrustZone® for ARMv8-M (optional) • System – Power-on Reset (POR) and programmable Brown-out Detection (BOD) – 8-channel Direct Memory Access Controller (DMAC) – 8-channel event system for Inter-peripheral Core-independent Operation – CRC-32 generator • Memory – 64/32/16 KB Flash – 16/8/4 KB SRAM – 2 KB Data Flash Write-While-Read (WWR) section for non-volatile data storage – 256 bytes TrustRAM with physical protection features • Clock Management – Flexible clock distribution optimized for low power – 32.768 kHz crystal oscillator – 32.768 kHz ultra low-power internal RC oscillator – 0.4 to 32 MHz crystal oscillator – 16/12/8/4 MHz low-power internal RC oscillator – Ultra low-power digital Frequency-Locked Loop (DFLLULP) – 48-96 MHz fractional digital Phase-Locked Loop (FDPLL96M) – One frequency meter • Low Power and Power Management – Active, Idle, Standby with partial or full SRAM retention and off sleep modes: • Active mode (< 25 μA/MHz) • Idle mode (< 10 μA/MHz) with 1.5 μs wake-up time © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1 • Standby with Full SRAM Retention (0.5 μA) with 5.3 μs wake-up time • Off mode (< 100 nA) – Static and dynamic power gating architecture – Sleepwalking peripherals – Two performance levels – Embedded Buck/LDO regulator with on-the-fly selection • Security – Up to four tamper pins for static and dynamic intrusion detections – Data Flash • Optimized for secrets storage • Data Scrambling with user-defined key (optional) • Rapid Tamper erase on scrambling key and on one user-defined row • Silent access for side channel attack resistance – TrustRAM • Address and Data scrambling with user-defined key • Chip-level tamper detection on physical RAM to resist microprobing attacks • Rapid Tamper Erase on scrambling key and RAM data • Silent access for side channel attack resistance • Data remanence prevention – Peripherals • One True Random Generator (TRNG) • AES-128, SHA-256, and GCM cryptography accelerators (optional) • Secure pin multiplexing to isolate on dedicated I/O pins a secured communication with external devices from the non-secure application (optional) – TrustZone for flexible hardware isolation of memories and peripherals (optional) • Up to six regions for the Flash • Up to two regions for the Data Flash • Up to two regions for the SRAM • Individual security attribution for each peripheral, I/O, external interrupt line, and Event System Channel – Secure Boot with SHA-based authentication (optional) – Up to three debug access levels – Up to three Chip Erase commands to erase part of or the entire embedded memories – Unique 128-bit serial number • Advanced Analog and Touch – One 12-bit 1 Msps Analog-to-Digital Converter (ADC) with up to 10 channels – Two Analog Comparators (AC) with window compare function – One 10-bit 350 kSPS Digital-to-Analog Converter (DAC) with external and internal outputs – Three Operational Amplifiers (OPAMP) – One enhanced Peripheral Touch Controller (PTC): • Up to 20 self-capacitance channels • Up to 100 (10 x 10) mutual-capacitance channels • Low-power, high-sensitivity, environmentally robust capacitive touch buttons, sliders, and wheels SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 2 • Hardware noise filtering and noise signal desynchronization for high conducted immunity • Driven Shield Plus for better noise immunity and moisture tolerance • Parallel Acquisition through Polarity control • Supports wake-up on touch from Standby Sleep mode • Communication Interfaces – Up to three Serial Communication Interfaces (SERCOM) that can operate as: • USART with full-duplex and single-wire half-duplex configuration • I2C up to 3.4 Mbit/s (High-Speed mode) on one instance and up to 1 Mbit/s (Fast-mode Plus) on the second instance • Serial Peripheral Interface (SPI) • ISO7816 on one instance • RS-485 on one instance • LIN Slave on one instance • Timers/Output Compare/Input Capture – Three 16-bit Timers/Counters (TC), each configurable as: • One 16-bit TC with two compare/capture channels • One 8-bit TC with two compare/capture channels • One 32-bit TC with two compare/capture channels, by using two TCs – 32-bit Real-Time Counter (RTC) with clock/calendar functions – Watchdog Timer (WDT) with Window mode • Input/Output (I/O) – Up to 25 programmable I/O lines – Eight external interrupts (EIC) – One non-maskable interrupt (NMI) – One Configurable Custom Logic (CCL) that supports: • Combinatorial logic functions, such as AND, NAND, OR, and NOR • Sequential logic functions, such as Flip-Flop and Latches • Qualification and Class-B Support – AEC-Q100 REVH (Grade 1 [-40ºC to +125ºC]) (planned) – Class-B safety library, IEC 60730 (future) • Debugger Development Support – Two-pin Serial Wire Debug (SWD) programming and debugging interface • Packages Type VQFN TQFP SSOP WLCSP(1) Pin Count 24 32 32 24 32 I/O Pins (up to) 17 25 25 17 25 Contact/Lead Pitch 0.5 mm 0.5 mm 0.8 mm 0.65 mm 0.4 mm Dimensions 4x4x0.9 mm 5x5x1 mm 7x7x1.2 mm 8.2x5.3x2.0 mm 2.79x2.79x0.482 mm Note:  1. Contact local sales for availability. SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 3 Table of Contents Features.......................................................................................................................... 1 1. Configuration Summary...........................................................................................14 2. Ordering Information................................................................................................16 3. Block Diagram......................................................................................................... 17 4. Pinouts.....................................................................................................................18 4.1. Multiplexed Signals.................................................................................................................... 19 4.2. Oscillators Pinout....................................................................................................................... 21 4.3. Serial Wire Debug Interface Pinout............................................................................................21 4.4. SERCOM Configurations........................................................................................................... 22 4.5. General Purpose I/O (GPIO) Clusters........................................................................................23 5. Signal Descriptions List .......................................................................................... 24 6. Power Considerations............................................................................................. 26 6.1. Power Supplies.......................................................................................................................... 26 6.2. Power Supply Constraints..........................................................................................................26 6.3. Power-On Reset and Brown-Out Detectors............................................................................... 27 6.4. Voltage Regulator.......................................................................................................................27 6.5. Typical Powering Schematic...................................................................................................... 27 7. Analog Peripherals Considerations......................................................................... 29 7.1. Reference Voltages....................................................................................................................30 7.2. Analog On Demand Feature...................................................................................................... 30 8. Device Startup......................................................................................................... 32 8.1. Clocks Startup............................................................................................................................32 8.2. Initial Instructions Fetching.........................................................................................................32 8.3. I/O Pins.......................................................................................................................................32 8.4. Performance Level Overview..................................................................................................... 32 9. Product Mapping..................................................................................................... 34 10. Memories.................................................................................................................36 10.1. Embedded Memories................................................................................................................. 36 10.2. NVM Rows................................................................................................................................. 38 10.3. Serial Number............................................................................................................................ 44 11. Processor and Architecture..................................................................................... 45 11.1. Cortex-M23 Processor............................................................................................................... 45 11.2. Nested Vector Interrupt Controller..............................................................................................47 11.3. High-Speed Bus System............................................................................................................ 50 SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 4 11.4. SRAM Quality of Service............................................................................................................52 12. Peripherals Configuration Summary........................................................................54 13. SAM L11 Security Features.....................................................................................57 13.1. Features..................................................................................................................................... 57 13.2. ARM TrustZone Technology for ARMv8-M.................................................................................58 13.3. Crypto Acceleration....................................................................................................................69 13.4. True Random Number Generator (TRNG).................................................................................72 13.5. Secure Boot................................................................................................................................72 13.6. Secure Pin Multiplexing on SERCOM........................................................................................72 13.7. Data Flash .................................................................................................................................72 13.8. TrustRAM (TRAM)......................................................................................................................72 14. Boot ROM................................................................................................................73 14.1. Features..................................................................................................................................... 73 14.2. Block Diagram............................................................................................................................74 14.3. Product Dependencies...............................................................................................................74 14.4. Functional Description................................................................................................................74 15. PAC - Peripheral Access Controller.........................................................................96 15.1. Overview.................................................................................................................................... 96 15.2. Features..................................................................................................................................... 96 15.3. Block Diagram............................................................................................................................96 15.4. Product Dependencies...............................................................................................................96 15.5. Functional Description................................................................................................................98 15.6. Register Summary....................................................................................................................102 15.7. Register Description.................................................................................................................103 16. DSU - Device Service Unit.................................................................................... 127 16.1. Overview.................................................................................................................................. 127 16.2. Features................................................................................................................................... 127 16.3. Block Diagram..........................................................................................................................128 16.4. Signal Description.................................................................................................................... 128 16.5. Product Dependencies.............................................................................................................128 16.6. Debug Operation......................................................................................................................130 16.7. Programming............................................................................................................................131 16.8. Security Enforcement...............................................................................................................132 16.9. Device Identification................................................................................................................. 134 16.10. Functional Description..............................................................................................................135 16.11. Register Summary....................................................................................................................141 16.12. Register Description.................................................................................................................143 17. Clock System.........................................................................................................172 17.1. Clock Distribution..................................................................................................................... 172 17.2. Synchronous and Asynchronous Clocks..................................................................................173 17.3. Register Synchronization......................................................................................................... 174 17.4. Enabling a Peripheral...............................................................................................................177 SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 5 17.5. On Demand Clock Requests....................................................................................................177 17.6. Power Consumption vs. Speed................................................................................................178 17.7. Clocks after Reset....................................................................................................................178 18. GCLK - Generic Clock Controller.......................................................................... 179 18.1. Overview.................................................................................................................................. 179 18.2. Features................................................................................................................................... 179 18.3. Block Diagram..........................................................................................................................179 18.4. Signal Description.................................................................................................................... 180 18.5. Product Dependencies.............................................................................................................180 18.6. Functional Description..............................................................................................................181 18.7. Register Summary....................................................................................................................187 18.8. Register Description.................................................................................................................189 19. MCLK – Main Clock...............................................................................................199 19.1. Overview.................................................................................................................................. 199 19.2. Features................................................................................................................................... 199 19.3. Block Diagram..........................................................................................................................199 19.4. Signal Description.................................................................................................................... 199 19.5. Product Dependencies.............................................................................................................199 19.6. Functional Description..............................................................................................................201 19.7. Register Summary....................................................................................................................206 19.8. Register Description.................................................................................................................206 20. FREQM – Frequency Meter.................................................................................. 222 20.1. Overview.................................................................................................................................. 222 20.2. Features................................................................................................................................... 222 20.3. Block Diagram..........................................................................................................................222 20.4. Signal Description.................................................................................................................... 222 20.5. Product Dependencies.............................................................................................................222 20.6. Functional Description..............................................................................................................224 20.7. Register Summary....................................................................................................................227 20.8. Register Description.................................................................................................................227 21. RSTC – Reset Controller.......................................................................................237 21.1. Overview.................................................................................................................................. 237 21.2. Features................................................................................................................................... 237 21.3. Block Diagram..........................................................................................................................237 21.4. Signal Description.................................................................................................................... 237 21.5. Product Dependencies.............................................................................................................237 21.6. Functional Description..............................................................................................................239 21.7. Register Summary....................................................................................................................241 21.8. Register Description.................................................................................................................241 22. PM – Power Manager............................................................................................243 22.1. Overview.................................................................................................................................. 243 22.2. Features................................................................................................................................... 243 22.3. Block Diagram..........................................................................................................................244 SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 6 22.4. Signal Description.................................................................................................................... 244 22.5. Product Dependencies.............................................................................................................244 22.6. Functional Description..............................................................................................................245 22.7. Register Summary....................................................................................................................263 22.8. Register Description.................................................................................................................263 23. OSCCTRL – Oscillators Controller........................................................................271 23.1. Overview.................................................................................................................................. 271 23.2. Features................................................................................................................................... 271 23.3. Block Diagram..........................................................................................................................272 23.4. Signal Description.................................................................................................................... 272 23.5. Product Dependencies.............................................................................................................272 23.6. Functional Description..............................................................................................................274 23.7. Register Summary....................................................................................................................285 23.8. Register Description.................................................................................................................286 24. OSC32KCTRL – 32KHz Oscillators Controller......................................................319 24.1. Overview.................................................................................................................................. 319 24.2. Features................................................................................................................................... 319 24.3. Block Diagram..........................................................................................................................320 24.4. Signal Description.................................................................................................................... 320 24.5. Product Dependencies.............................................................................................................320 24.6. Functional Description..............................................................................................................322 24.7. Register Summary....................................................................................................................327 24.8. Register Description.................................................................................................................327 25. SUPC – Supply Controller.....................................................................................339 25.1. Overview.................................................................................................................................. 339 25.2. Features................................................................................................................................... 339 25.3. Block Diagram..........................................................................................................................340 25.4. Signal Description.................................................................................................................... 340 25.5. Product Dependencies.............................................................................................................340 25.6. Functional Description..............................................................................................................341 25.7. Register Summary....................................................................................................................348 25.8. Register Description.................................................................................................................349 26. WDT – Watchdog Timer........................................................................................ 366 26.1. Overview.................................................................................................................................. 366 26.2. Features................................................................................................................................... 366 26.3. Block Diagram..........................................................................................................................367 26.4. Signal Description.................................................................................................................... 367 26.5. Product Dependencies.............................................................................................................367 26.6. Functional Description..............................................................................................................368 26.7. Register Summary....................................................................................................................374 26.8. Register Description.................................................................................................................374 27. RTC – Real-Time Counter.....................................................................................386 27.1. Overview.................................................................................................................................. 386 SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 7 27.2. Features................................................................................................................................... 386 27.3. Block Diagram..........................................................................................................................387 27.4. Signal Description.................................................................................................................... 388 27.5. Product Dependencies.............................................................................................................388 27.6. Functional Description..............................................................................................................390 27.7. Register Summary - Mode 0 - 32-Bit Counter..........................................................................402 27.8. Register Description - Mode 0 - 32-Bit Counter....................................................................... 403 27.9. Register Summary - Mode 1 - 16-Bit Counter..........................................................................426 27.10. Register Description - Mode 1 - 16-Bit Counter....................................................................... 427 27.11. Register Summary - Mode 2 - Clock/Calendar.........................................................................450 27.12. Register Description - Mode 2 - Clock/Calendar......................................................................451 28. DMAC – Direct Memory Access Controller........................................................... 476 28.1. Overview.................................................................................................................................. 476 28.2. Features................................................................................................................................... 476 28.3. Block Diagram..........................................................................................................................478 28.4. Signal Description.................................................................................................................... 478 28.5. Product Dependencies.............................................................................................................478 28.6. Functional Description..............................................................................................................480 28.7. Register Summary....................................................................................................................500 28.8. Register Description.................................................................................................................501 28.9. Register Summary - SRAM......................................................................................................532 28.10. Register Description - SRAM................................................................................................... 532 29. EIC – External Interrupt Controller........................................................................ 540 29.1. Overview.................................................................................................................................. 540 29.2. Features................................................................................................................................... 540 29.3. Block Diagram..........................................................................................................................540 29.4. Signal Description.................................................................................................................... 541 29.5. Product Dependencies.............................................................................................................541 29.6. Functional Description..............................................................................................................543 29.7. Register Summary....................................................................................................................550 29.8. Register Description.................................................................................................................551 30. NVMCTRL – Nonvolatile Memory Controller.........................................................572 30.1. Overview.................................................................................................................................. 572 30.2. Features................................................................................................................................... 572 30.3. Block Diagram..........................................................................................................................573 30.4. Signal Description.................................................................................................................... 573 30.5. Product Dependencies.............................................................................................................573 30.6. Functional Description..............................................................................................................575 30.7. Register Summary....................................................................................................................586 30.8. Register Description.................................................................................................................587 31. TRAM - TrustRAM................................................................................................. 614 31.1. Overview.................................................................................................................................. 614 31.2. Features................................................................................................................................... 614 31.3. Block Diagram..........................................................................................................................614 SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 8 31.4. Signal Description.................................................................................................................... 614 31.5. Product Dependencies.............................................................................................................615 31.6. Functional Description..............................................................................................................616 31.7. Register Summary....................................................................................................................620 31.8. Register Description.................................................................................................................626 32. PORT - I/O Pin Controller......................................................................................638 32.1. Overview.................................................................................................................................. 638 32.2. Features................................................................................................................................... 638 32.3. Block Diagram..........................................................................................................................639 32.4. Signal Description.................................................................................................................... 639 32.5. Product Dependencies.............................................................................................................639 32.6. Functional Description..............................................................................................................641 32.7. Register Summary....................................................................................................................648 32.8. Register Description.................................................................................................................650 33. EVSYS – Event System........................................................................................ 685 33.1. Overview.................................................................................................................................. 685 33.2. Features................................................................................................................................... 685 33.3. Block Diagram..........................................................................................................................686 33.4. Product Dependencies.............................................................................................................686 33.5. Functional Description..............................................................................................................688 33.6. Register Summary....................................................................................................................695 33.7. Register Description.................................................................................................................698 34. SERCOM – Serial Communication Interface.........................................................724 34.1. Overview.................................................................................................................................. 724 34.2. Features................................................................................................................................... 724 34.3. Block Diagram..........................................................................................................................725 34.4. Signal Description.................................................................................................................... 725 34.5. Product Dependencies.............................................................................................................725 34.6. Functional Description..............................................................................................................727 35. SERCOM USART - SERCOM Synchronous and Asynchronous Receiver and Transmitter.............................................................................................................733 35.1. Overview.................................................................................................................................. 733 35.2. USART Features......................................................................................................................733 35.3. Block Diagram..........................................................................................................................734 35.4. Signal Description.................................................................................................................... 734 35.5. Product Dependencies.............................................................................................................734 35.6. Functional Description..............................................................................................................736 35.7. Register Summary....................................................................................................................751 35.8. Register Description.................................................................................................................752 36. SERCOM SPI – SERCOM Serial Peripheral Interface..........................................778 36.1. Overview.................................................................................................................................. 778 36.2. Features................................................................................................................................... 778 36.3. Block Diagram..........................................................................................................................779 SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 9 36.4. Signal Description.................................................................................................................... 779 36.5. Product Dependencies.............................................................................................................779 36.6. Functional Description..............................................................................................................781 36.7. Register Summary....................................................................................................................790 36.8. Register Description.................................................................................................................791 37. SERCOM I2C – SERCOM Inter-Integrated Circuit................................................ 811 37.1. Overview...................................................................................................................................811 37.2. Features................................................................................................................................... 811 37.3. Block Diagram..........................................................................................................................812 37.4. Signal Description.................................................................................................................... 812 37.5. Product Dependencies.............................................................................................................812 37.6. Functional Description..............................................................................................................814 37.7. Register Summary - I2C Slave.................................................................................................833 37.8. Register Description - I2C Slave...............................................................................................833 37.9. Register Summary - I2C Master...............................................................................................851 37.10. Register Description - I2C Master............................................................................................ 852 38. TC – Timer/Counter...............................................................................................873 38.1. Overview.................................................................................................................................. 873 38.2. Features................................................................................................................................... 873 38.3. Block Diagram..........................................................................................................................874 38.4. Signal Description.................................................................................................................... 874 38.5. Product Dependencies.............................................................................................................875 38.6. Functional Description..............................................................................................................876 38.7. Register Description.................................................................................................................891 39. TRNG – True Random Number Generator............................................................965 39.1. Overview.................................................................................................................................. 965 39.2. Features................................................................................................................................... 965 39.3. Block Diagram..........................................................................................................................965 39.4. Signal Description.................................................................................................................... 965 39.5. Product Dependencies.............................................................................................................965 39.6. Functional Description..............................................................................................................967 39.7. Register Summary....................................................................................................................969 39.8. Register Description.................................................................................................................969 40. CCL – Configurable Custom Logic........................................................................977 40.1. Overview.................................................................................................................................. 977 40.2. Features................................................................................................................................... 977 40.3. Block Diagram..........................................................................................................................978 40.4. Signal Description.................................................................................................................... 978 40.5. Product Dependencies.............................................................................................................978 40.6. Functional Description..............................................................................................................980 40.7. Register Summary....................................................................................................................990 40.8. Register Description.................................................................................................................990 41. ADC – Analog-to-Digital Converter........................................................................995 SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 10 41.1. Overview.................................................................................................................................. 995 41.2. Features................................................................................................................................... 995 41.3. Block Diagram..........................................................................................................................996 41.4. Signal Description.................................................................................................................... 996 41.5. Product Dependencies.............................................................................................................996 41.6. Functional Description..............................................................................................................998 41.7. Register Summary..................................................................................................................1011 41.8. Register Description...............................................................................................................1012 42. AC – Analog Comparators...................................................................................1040 42.1. Overview................................................................................................................................ 1040 42.2. Features................................................................................................................................. 1040 42.3. Block Diagram........................................................................................................................1041 42.4. Signal Description.................................................................................................................. 1041 42.5. Product Dependencies...........................................................................................................1041 42.6. Functional Description............................................................................................................1043 42.7. Register Summary..................................................................................................................1053 42.8. Register Description...............................................................................................................1053 43. DAC – Digital-to-Analog Converter......................................................................1071 43.1. Overview................................................................................................................................ 1071 43.2. Features................................................................................................................................. 1071 43.3. Block Diagram........................................................................................................................1071 43.4. Signal Description.................................................................................................................. 1071 43.5. Product Dependencies...........................................................................................................1071 43.6. Functional Description............................................................................................................1073 43.7. Register Summary..................................................................................................................1078 43.8. Register Description...............................................................................................................1078 44. OPAMP – Operational Amplifier Controller..........................................................1093 44.1. Overview................................................................................................................................ 1093 44.2. Features................................................................................................................................. 1093 44.3. Block Diagram........................................................................................................................1094 44.4. Signal Description.................................................................................................................. 1094 44.5. Product Dependencies...........................................................................................................1095 44.6. Functional Description............................................................................................................1097 44.7. Register Summary.................................................................................................................. 1111 44.8. Register Description................................................................................................................1111 45. PTC - Peripheral Touch Controller.......................................................................1120 45.1. Overview.................................................................................................................................1120 45.2. Features................................................................................................................................. 1120 45.3. Block Diagram........................................................................................................................ 1121 45.4. Signal Description...................................................................................................................1122 45.5. System Dependencies............................................................................................................1122 45.6. Functional Description............................................................................................................1124 46. Electrical Characteristics .................................................................................... 1125 SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 11 46.1. Disclaimer...............................................................................................................................1125 46.2. Thermal Considerations......................................................................................................... 1125 46.3. Absolute Maximum Ratings....................................................................................................1126 46.4. General Operating Ratings.....................................................................................................1126 46.5. Supply Characteristics............................................................................................................1127 46.6. Maximum Clock Frequencies................................................................................................. 1127 46.7. Power Consumption............................................................................................................... 1129 46.8. Wake-Up Time........................................................................................................................1133 46.9. I/O Pin Characteristics............................................................................................................1134 46.10. Injection Current.....................................................................................................................1135 46.11. Analog Characteristics............................................................................................................1136 46.12. NVM Characteristics...............................................................................................................1152 46.13. Oscillators Characteristics......................................................................................................1153 46.14. Timing Characteristics............................................................................................................1160 47. 125°C Electrical Characteristics.......................................................................... 1166 47.1. Disclaimer...............................................................................................................................1166 47.2. General Operating Ratings.....................................................................................................1166 47.3. Power Consumption............................................................................................................... 1166 47.4. Analog Characteristics............................................................................................................1170 47.5. Oscillators Characteristics...................................................................................................... 1183 47.6. Timing Characteristics............................................................................................................ 1186 48. AC and DC Characteristics Graphs..................................................................... 1192 48.1. Typical Power Consumption over Temperature in Sleep Modes - 85°C.................................1192 48.2. Typical Power Consumption over Temperature in Sleep Modes - 125°C...............................1194 49. Packaging Information.........................................................................................1196 49.1. Package Marking Information.................................................................................................1196 49.2. Package Drawings..................................................................................................................1197 49.3. Soldering Profile.....................................................................................................................1204 50. Schematic Checklist............................................................................................ 1205 50.1. Introduction.............................................................................................................................1205 50.2. Power Supply......................................................................................................................... 1205 50.3. External Analog Reference Connections............................................................................... 1207 50.4. External Reset Circuit.............................................................................................................1209 50.5. Unused or Unconnected Pins.................................................................................................1210 50.6. Clocks and Crystal Oscillators................................................................................................1210 50.7. Programming and Debug Ports..............................................................................................1212 50.8. Peripherals Considerations.................................................................................................... 1215 51. Conventions.........................................................................................................1216 51.1. Numerical Notation.................................................................................................................1216 51.2. Memory Size and Type...........................................................................................................1216 51.3. Frequency and Time...............................................................................................................1216 51.4. Registers and Bits.................................................................................................................. 1217 SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 12 52. Acronyms and Abbreviations...............................................................................1218 53. Datasheet Revision History................................................................................. 1221 53.1. Rev A - 09/2017..................................................................................................................... 1221 53.2. Rev B - 6/2018....................................................................................................................... 1221 The Microchip Web Site............................................................................................ 1222 Customer Change Notification Service......................................................................1222 Customer Support..................................................................................................... 1222 Product Identification System....................................................................................1223 Microchip Devices Code Protection Feature............................................................. 1223 Legal Notice...............................................................................................................1223 Trademarks............................................................................................................... 1224 Quality Management System Certified by DNV.........................................................1224 Worldwide Sales and Service....................................................................................1226 SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 13 1. Configuration Summary Table 1-1. SAM L10/L11 Device-specific Features Device Flash + Data Flash Memory (KB) SRAM (KB) Pins SERCOM ADC Channels Analog Comparators Inputs PTC Selfcapacitance/ Mutualcapacitance Channels I/O Pins Tamper Pins Packages SAML10D14 16+2 4 SAML10D15 32+2 8 24 2 5 2 16/64 17 3 VQFN, SSOP SAML10D16 64+2 16 SAML10E14 16+2 4 32 3 10 4 20/100 25 4 VQFN, TQFP, WLCSP SAML10E15 32+2 8 SAML10E16 64+2 16 SAML11D14 16+2 8 SAML11D15 32+2 8 24 2 5 2 16/64 17 3 VQFN, SSOP SAML11D16 64+2 16 SAML11E14 16+2 8 32 3 10 4 20/100 25 4 VQFN, TQFP, WLCSP SAML11E15 32+2 8 SAML11E16 64+2 16 Table 1-2. SAM L10/L11 Family Features Feature SAM L10 Family SAM L11 Family MPU 1 2 TrustZone for ARMv8-M No Yes Secure Boot No Yes TrustRAM (Bytes) 256 256 DMA Channels 8 8 Data Scrambling TrustRAM TrustRAM, Data Flash Event System Channels 8 8 External Interrupt Lines/NMI 8/1 8/1 Brown-out Detection VDDIO and VDDCORE VDDIO and VDDCORE Secure Pin Multiplexing (on SERCOM) No Yes TC/Compare 3 3 RTC 1 1 Watchdog 1 1 DAC Channels 1 1 OPAMP 3 3 CCL Look-up Tables 2 2 Frequency Meter 1 1 Crypto Accelerators No Yes TRNG Yes Yes SAM L10/L11 Family Configuration Summary © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 14 Feature SAM L10 Family SAM L11 Family CRC Yes Yes Debug Access Levels (DAL) 2 3 SAM L10/L11 Family Configuration Summary © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 15 2. Ordering Information ATSAML 11 D 14 A M U T No character = Tray or Tube 16 = 64 KB 15 = 32 KB 14 = 16 KB D = 24 Pins E = 32 Pins 10 = Cortex-M23 CPU 11 = Cortex-M23 CPU with TrustZone Enabled A = TQFP M = VQFN Y = SSOP U = -40 - +85°C Matte Sn Plating F = -40 - +125°C Matte Sn Plating (Flash) SAML = Ultra Low Power Microcontroller U = WLCSP Note:  1. Devices in the WLCSP package include a factory programmed bootloader. Contact your local Microchip sales office for more information. 2. Devices can be factory programmed with securely key provisioned software. Contact your local Microchip sales office for more information. SAM L10/L11 Family Ordering Information © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 16 3. Block Diagram Figure 3-1. SAM L10/L11 Block Diagram 6 x SERCOM 8 x Timer Counter AHB-APB BRIDGE C M M High-Speed Bus Matrix PORT PORT SERIAL SWDIO WIRE S Cortex-M23 PROCESSOR Fmax 32 MHz SWCLK DEVICE SERVICE UNIT AHB-APB BRIDGE A 10-CHANNEL 12-bit ADC 1MSPS AIN[9..0] VREFA AIN[3..0] S SRAM CONTROLLER 16/8/8 KB RAM (SAM L11) - 16/8/4 KB RAM (SAM L10) M 3x TIMER / COUNTER EVENT SYSTEM S 3x SERCOM 2x ANALOG COMPARATORS PERIPHERAL TOUCH CONTROLLER AHB-APB BRIDGE B S PAD[0] WO[1] PAD[1] PAD[2] PAD[3] WO[0] VREFB 2KB Data Flash NVM CONTROLLER M DMA IOBUS DMA DMA DMA S REAL-TIME COUNTER WATCHDOG TIMER RESET OSCILLATORS CONTROLLER XOUT XIN XOUT32 XIN32 OSCULP32K OSC16M XOSC32K XOSC EXTERNAL INTERRUPT CONTROLLER MAIN CLOCKS CONTROLLER EXTINT[7..0] NMI GCLK_IO[4..0] FDPLL96M GENERIC CLOCK CONTROLLER POWER MANAGER RESET CONTROLLER OSC32K CONTROLLER SUPPLY CONTROLLER VREF BOD33 TRNG IN[5..0] CCL OUT[1..0] FREQUENCY METER DMA IN[3:0] VOUT 10-bit DAC 350kSPS DMA 256 Bytes TrustRAM PERIPHERAL ACCESS CONTROLLER DFLLULP OUT[3:0] CMP[1..0] VREFA 8 KB ROM S IDAU TrustZone for ARMv8-M Crypto Accelerators (AES128, SHA256, GCM) Secure Boot 64/32/16 KB Flash with Cache Data Scrambling EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT CRC-32 3x OPAMP OA0OUT / OA2OUT OA[0..2]POS OA[0..2]NEG SAM L11 Added Features MPU Voltage Regulators BOD12 XY[19..0] 128-bit Unique ID Note:  Number of SERCOM instances, PTC/ADC channels, Tamper input pins, and Analog Compare inputs differ on the packages pinout. SAM L10/L11 Family Block Diagram © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 17 4. Pinouts Figure 4-1. SAM L10/L11 24-pin VQFN Pinout 1 2 3 4 5 7 8 9 10 11 12 13 14 15 16 17 18 24 23 22 21 20 19 6 Figure 4-2. SAM L10/L11 24-pin SSOP Pinout 1 2 3 4 5 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 6 Figure 4-3. SAM L10/L11 32-pin VQFN and TQFP Pinout 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 32 31 30 29 28 27 26 25 SAM L10/L11 Family Pinouts © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 18 Figure 4-4. SAM L10/L11 32-pin WLCSP Pinout 4.1 Multiplexed Signals Each pin is controlled by the I/O Pin Controller (PORT) as a general purpose I/O and alternatively can be assigned to one of the peripheral functions: A, B, C, D, E, G, H, or I. The following table describes the peripheral signals multiplexed to the PORT I/O pins. The column “Reset State” indicates the reset state of the line with mnemonics: • "I/O" or "Function" indicates whether the I/O pin resets in I/O mode or in peripheral function mode. • “I” / ”O” / "Hi-Z" indicates whether the I/O is configured as an input, output or is tri-stated. • “PU” / “PD” indicates whether pullup, pulldown or nothing is enabled. Table 4-1. Pinout Multiplexing Pin Pin Name Supply A B(1) C(2)(3) D(2)(3) E G H I Reset State SSOP2 4 VQFN2 4 WLCSP 32 TQFP32 / VQFN3 2 EIC REF ADC AC PTC DAC OPAMP SERCO M SERCO M ALTER NATIVE TC RTC/ Debug AC/ GCLK CCL 5 2 A2 1 PA00 / XIN32 VDDAN A EXTIN T[0] XY[0] OA1NE G SERCO M1/ PAD[0] TC2/ WO[0] I/O, Hi-Z 6 3 A3 2 PA01 / XOUT3 2 VDDAN A EXTIN T[1] XY[1] OA1PO S SERCO M1/ PAD[1] TC2/ WO[1] I/O, Hi-Z 7 4 A4 3 PA02 VDDAN A EXTIN T[2] AIN[0] XY[2] VOUT OA0NE G SERCO M0/ PAD(2] I/O, Hi-Z 8 5 B3 4 PA03 VDDAN A EXTIN T[3] VREFA AIN[1] XY[3] OA2NE G SERCO M0/ PAD[3] I/O, Hi-Z 9 6 B4 5 PA04 VDDAN A EXTIN T[4] VREFB AIN[2] AIN[0] OA2OU T SERCO M0/ PAD[0] TC0/ WO[0] IN[0] I/O, Hi-Z 10 7 A5 6 PA05 VDDAN A EXTIN T[5] AIN[3] AIN[1] XY[4] OA2PO S SERCO M0/ PAD(1] TC0/ WO[1] IN[1] I/O, Hi-Z SAM L10/L11 Family Pinouts © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 19 Pin Pin Name Supply A B(1) C(2)(3) D(2)(3) E G H I Reset State SSOP2 4 VQFN2 4 WLCSP 32 TQFP32 / VQFN3 2 EIC REF ADC AC PTC DAC OPAMP SERCO M SERCO M ALTER NATIVE TC RTC/ Debug AC/ GCLK CCL C4 7 PA06 VDDAN A EXTIN T[6] AIN[4] AIN[2] XY[5] OA0PO S SERCO M0/ PAD[2] TC1/ WO[0] IN[2] I/O, Hi-Z B5 8 PA07 VDDAN A EXTIN T[7] AIN[5] AIN[3] OA0OU T SERCO M0/ PAD[3] TC1/ WO[1] OUT[0] I/O, Hi-Z 11 8 B6 9 VDDAN A - 12 9 C6 10 GNDAN A - 13 10 D4 11 PA08 VDDIO NMI AIN[6] XY[6] SERCO M1/ PAD[0] SERCO M2/ PAD[0] RTC/ IN[0] IN[3] I/O, Hi-Z D6 12 PA09 VDDIO EXTIN T[0] AIN[7] XY[7] SERCO M1/ PAD[1] SERCO M2/ PAD[1] RTC/ IN[1] IN[4] I/O, Hi-Z C5 13 PA10 VDDIO EXTIN T[1] AIN[8] XY[8] SERCO M1/ PAD[2] SERCO M2/ PAD[2] GCLK_I O[4] IN[5] I/O, Hi-Z D5 14 PA11 VDDIO EXTIN T[2] AIN[9] XY[9] SERCO M1/ PAD[3] SERCO M2/ PAD[3] GCLK_I O[3] OUT[1] I/O, Hi-Z 14 11 E6 15 PA14 / XOSC VDDIO EXTIN T[3] XY[10] SERCO M2/ PAD[2] SERCO M0/ PAD[2] TC0/ WO[0] GCLK_I O[0] I/O, Hi-Z 15 12 E5 16 PA15 / XOUT VDDIO EXTIN T[4] XY[11] SERCO M2/ PAD[3] SERCO M0/ PAD[3] TC0/ WO[1] GCLK_I O[1] I/O, Hi-Z 16 13 D3 17 PA16(4) VDDIO EXTIN T[5] XY[12] SERCO M1/ PAD[0] SERCO M0/ PAD[0] RTC/ IN[2] GCLK_I O[2] IN[0] I/O, Hi-Z 17 14 F5 18 PA17(4) VDDIO EXTIN T[6] XY[13] SERCO M1/ PAD[1] SERCO M0/ PAD[1] RTC/ IN[3] GCLK_I O[3] IN[1] I/O, Hi-Z 18 15 E4 19 PA18 VDDIO EXTIN T[7] XY[14] SERCO M1/ PAD[2] SERCO M0/ PAD[2] TC2/ WO[0] RTC/ OUT[0] AC/ CMP[0] IN[2] I/O, Hi-Z 19 16 E3 20 PA19 VDDIO EXTIN T[0] XY[15] SERCO M1/ PAD[3] SERCO M0/ PAD[3] TC2/ WO[1] RTC/ OUT[1] AC/ CMP[1] OUT[0] I/O, Hi-Z 20 17 F4 21 PA22(4) VDDIO EXTIN T[1] XY[16] SERCO M0/ PAD[0] SERCO M2/ PAD[0] TC0/ WO[0] RTC/ OUT[2] GCLK_I O[2] I/O, Hi-Z 21 18 F3 22 PA23(4) VDDIO EXTIN T[2] XY[17] SERCO M0/ PAD[1] SERCO M2/ PAD[1] TC0/ WO[1] RTC/ OUT[3] GCLK_I O[1] I/O, Hi-Z F2 23 PA24 VDDIO EXTIN T[3] SERCO M0/ PAD[2] SERCO M2/ PAD[2] TC1/ WO[0] I/O, Hi-Z E2 24 PA25 VDDIO EXTIN T[4] SERCO M0/ PAD[3] SERCO M2/ PAD[3] TC1/ WO[1] I/O, Hi-Z D2 25 PA27 VDDIO EXTIN T[5] GCLK_I O[0] I/O, Hi-Z 22 19 C2 26 RESET VDDIO I, PU 23 20 E1 27 VDDCO RE - 24 21 D1 28 GND - 1 22 C1 29 VDDOU T - 2 23 B1 30 VDDIO - SAM L10/L11 Family Pinouts © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 20 Pin Pin Name Supply A B(1) C(2)(3) D(2)(3) E G H I Reset State SSOP2 4 VQFN2 4 WLCSP 32 TQFP32 / VQFN3 2 EIC REF ADC AC PTC DAC OPAMP SERCO M SERCO M ALTER NATIVE TC RTC/ Debug AC/ GCLK CCL 3 24 B2 31 PA30 / SWCLK VDDIO EXTIN T[6] XY[18] SERCO M1/ PAD[2] TC1/ WO[0] SWCLK GCLK_I O[0] IN[3] SWCLK , I, PU 4 1 C3 32 PA31 / SWDIO( 4) VDDIO EXTIN T[7] XY[19] SERCO M1/ PAD[3] TC1/ WO[1] OUT[1] I/O, Hi-Z 1. All analog pin functions are on the peripheral function B. The peripheral function B must be selected to disable the digital control of the pin. 2. Refer to SERCOM Configurations to get the list of the supported features for each SERCOM instance. 3. 24-pin packages only have two SERCOM instances: SERCOM0 and SERCOM1. 4. The following pins are High Sink pins and have different properties than standard pins: PA16, PA17, PA22, PA23 and PA31. 4.2 Oscillators Pinout The oscillators are not mapped to the I/O Pin Controller (PORT) functions and their multiplexing is controlled by the Oscillators Controller (OSCCTRL) and 32 kHz Oscillators Controller (OSC32KCTRL) registers. Table 4-2. Oscillator Pinout Oscillator Supply Signal I/O pin XOSC VDDIO XIN PA14 XOUT PA15 XOSC32K VDDANA XIN32 PA00 XOUT32 PA01 To improve the cycle-to-cycle jitter of the XOSC32 oscillator, it is recommended to keep the neighboring pins of XIN32 and the following pins of XOUT32 as static as possible: Table 4-3. XOSC32 Jitter Minimization Package Pin Count Static Signal Recommended 32 PA02, PA03 24 PA02, PA03 4.3 Serial Wire Debug Interface Pinout The SWCLK pin is by default assigned to the SWCLK peripheral function G to allow debugger probe detection. A debugger probe detection (cold-plugging or hot-plugging) will automatically switch the SWDIO I/O pin to the SWDIO function, as long as the SWLCK peripheral function is selected. SAM L10/L11 Family Pinouts © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 21 Table 4-4. Serial Wire Debug Interface Pinout Signal Supply I/O pin SWCLK VDDIO PA30 SWDIO VDDIO PA31 4.4 SERCOM Configurations The following table lists the supported features for each SERCOM instance: Table 4-5. SERCOM Features Summary SERCOM Instance Protocol SERCOM0 SERCOM1 SERCOM2 SPI Yes Yes Yes I 2C (1) Yes High-speed mode (≤ 3,4 Mbit/s) Yes Fast plus Mode (≤ 1 Mbit/s) No USART Yes including: Hardware Handshaking IrDA Yes including: Hardware Handshaking IrDA Yes including: Hardware Handshaking IrDA RS-485 Auto-baud mode LIN Slave ISO7816 USART/SPI Receive Buffer Size Two-level Four-level Two-level Secure Pin Multiplexing (SAM L11 only) No Yes No Note:  1. I2C is not supported on all SERCOM pins. Refer to the SERCOM I2C Pins table for more details. 4.4.1 SERCOM I2C Pins The following table lists the SERCOM pins which support I2C: Table 4-6. SERCOM I2C Pins Pin Name SERCOM0 I2C Pad Name SERCOM1 I2C Pad Name PA16 SERCOM0/PAD[0] SERCOM1/PAD[0] PA17 SERCOM0/PAD[1] SERCOM1/PAD[1] PA22 SERCOM0/PAD[0] N/A PA23 SERCOM0/PAD[1] N/A 4.4.2 Secure Pin Multiplexing (on SERCOM) Pins The Secure Pin Multiplexing feature can be used on dedicated SERCOM I/O pins to isolate a secure communication with external devices from the non-secure application. Refer to 13.6 Secure Pin Multiplexing on SERCOM for more details. The following table lists the SERCOM pins that support the Secure Pin Multiplexing feature: SAM L10/L11 Family Pinouts © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 22 Table 4-7. Secure Pin Multiplexing on SERCOM Pins Pin Name Secure Pin Multiplexing Pad Name PA16 SERCOM1/PAD[0] PA17 SERCOM1/PAD[1] PA18 SERCOM1/PAD[2] PA19 SERCOM1/PAD[3] 4.5 General Purpose I/O (GPIO) Clusters Table 4-8. GPIO Clusters Package Cluster GPIO Supply Pins Connected to the Cluster 32-pin 1 PA00 PA01 PA02 PA03 PA04 PA05 PA06 PA07 VDDANA/GNDANA 2 PA08 PA09 PA10 PA11 PA14 PA15 PA16 PA17 PA18 PA19 PA22 PA23 PA24 PA25 PA27 PA30 PA31 VDDIO/GND 24-pin 1 PA00 PA01 PA02 PA03 PA04 PA05 VDDANA/GND 2 PA08 PA14 PA15 PA16 PA17 PA18 PA19 PA22 PA23 PA30 PA31 VDDIO/GND SAM L10/L11 Family Pinouts © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 23 5. Signal Descriptions List The following table provides details on signal names classified by peripherals. Table 5-1. Signal Descriptions List Signal Name Function Type Generic Clock Generator - GCLK GCLK_IO[4:0] Generators Clock Source (Input) or Generic Clock Signal (Output) Digital I/O Oscillators Control - OSCCTRL XIN Crystal Oscillator or External Clock Input Analog Input (Crystal Oscillator)/Digital Input (External Clock) XOUT Crystal Oscillator Output Analog Output 32 kHz Oscillators Control - OSC32KCTRL XIN32 32.768 kHz Crystal Oscillator or External Clock Input Analog Input (Crystal Oscillator)/Digital Input (External Clock) XOUT32 32.768 kHz Crystal Oscillator Output Analog Output Serial Communication Interface - SERCOMx PAD[3:0] General SERCOM Pins Digital I/O Timer Counter - TCx WO[1:0] Capture Inputs or Waveform Outputs Digital I/O Real Timer Clock - RTC IN[3:0] Tamper Detection Inputs Digital Input OUT[3:0] Tamper Detection Outputs Digital Output Analog Comparators - AC AIN[3:0] AC Comparator Inputs Analog Input CMP[1:0] AC Comparator Outputs Digital Output Analog Digital Converter - ADC AIN[9:0] ADC Input Channels Analog Input VREFA(1) ADC External Reference Voltage A Analog Input VREFB ADC External Reference Voltage B Analog Input Digital Analog Converter - DAC VOUT DAC Voltage Output Analog Output VREFA(1) DAC External Reference Voltage A Analog Input Operational Amplifier - OPAMP OA[2:0]NEG OPAMP Negative Inputs Analog Input OA[2:0]POS OPAMP Positive Inputs Analog Input OA0OUT / OA2OUT OPAMP Outputs Analog Output Peripheral Touch Controller - PTC XY[19:0] X-lines and Y-lines Digital Output (X-line) /Analog I/O (Y-line) Custom Control Logic - CCL IN[5:0] Inputs to lookup table Digital Output OUT[1:0] Outputs from lookup table Digital Input SAM L10/L11 Family Signal Descriptions List © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 24 Signal Name Function Type External Interrupt Controller - EIC EXTINT[7:0] External Interrupts Pins Digital Input NMI Non-Maskable Interrupt Pin Digital Input General Purpose I/O - PORT PA11-PA00 / PA19-PA14 / PA25-PA22 / PA27 / PA31-PA30 General Purpose I/O Pin in Port A Digital I/O Reset Controller - RSTC RESET External Reset Pin (Active Level: LOW) Digital Input Debug Service Unit - DSU SWCLK Serial Wire Clock Digital Input SWDIO Serial Wire Bidirectional Data Pin Digital I/O 1. VREFA is shared between the ADC and DAC peripherals. SAM L10/L11 Family Signal Descriptions List © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 25 6. Power Considerations 6.1 Power Supplies The SAM L10/L11 have three different power supply pins: Table 6-1. SAM L10/L11 Power Supplies Name Associated Ground Powers VDDIO GND OSC16M, XOSC, the internal voltage regulator and BOD12 I/O lines: PA[11:08], PA[19:14], PA[25:22], PA[27] and PA[31:30] Voltage range, nominal: 1.62V - 3.63V, 3.3V VDDANA GNDANA OSCULP32K, XOSC32K, the POR/BOD33, the analog peripherals (ADC, AC, DAC, PTC, OPAMP) I/O lines: PA[07:00] Voltage range, nominal: 1.62V - 3.63V, 3.3V VDDCORE GND Core, embedded memories, peripherals, the FDPLL96M and the DFLLULP Voltage range: 0.9V - 1.2V Figure 6-1. Power Domain Overview VDDCORE VDDOUT VDDIO DAC AC ADC PTC V D D A N A G N D A N A BOD33 POR XOSC32K OSCULP32K OSC16MPA[19:14] VDDANA DFLLULP Digital Logic CPU, Peripherals, Memories VDDCORE XOSC PA[11:08] OPAMP PA[25:22] PA[27] PA[31:30] FDPLL96M VDDIO PA[07:00] BUCK LDO BOD12 GND 6.2 Power Supply Constraints The same voltage source must be applied to both VDDIO and VDDANA. Note:  This common voltage is referred to as VDD in the Data Sheet. The maximum supply falling and rising rates of the different power supplies must not exceed the values described in the Supply Characteristics section of the Electrical Characteristics chapters. SAM L10/L11 Family Power Considerations © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 26 6.3 Power-On Reset and Brown-Out Detectors The SAM L10/L11 embed three features to monitor, warn and reset the device: • A Power-on Reset (POR) on VDD (VDDANA and VDDIO): – Monitoring is always activated, including during device startup or during any sleep modes. – Having VDD below a fixed threshold voltage will reset the whole device. Note:  Refer to 46.11.2 Power-On Reset (POR) Characteristics for the rising and falling threshold voltages. • A Brown-out Detector (BOD33) on VDD (VDDANA and VDDIO): – The BOD33 can monitor VDD continuously (continuous mode) or periodically (sampled mode) with a programmable sample frequency in active mode as in any sleep modes. – A programmable threshold loaded from the NVM User Row is used to trigger an interrupt and/or reset the whole device. • A Brown-out Detector (BOD12) on VDDCORE. Note:  BOD12 is calibrated in production and its calibration parameters are stored in the NVM User Row. These data must not be changed to ensure correct device behavior. 6.4 Voltage Regulator The embedded voltage regulator is used to provide VDDCORE to the device. The SAM L10/L11 Voltage Regulator has three modes: • Linear (LDO) mode: The default mode after reset. • Switching (BUCK) mode: The most power efficient mode when the CPU and peripherals are running (Active mode). Note:  In Active mode, the voltage regulator can be selected on the fly between LDO (low-dropout) type regulator and Buck converter using the Supply Controller (SUPC) • Low-Power mode (LPVREG): The default mode, used when the device is in Standby Sleep mode. 6.5 Typical Powering Schematic The SAM L10/L11 requires a single supply from 1.62V to 3.63V. The following figures show the recommended power supply connections for two voltage regulators use cases: • LDO mode only • LDO/BUCK modes Note:  By default the LDO voltage regulator is enabled after any reset. Switching to BUCK mode is then required to benefit from its power efficiency. SAM L10/L11 Family Power Considerations © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 27 Figure 6-2. Power Supply Connections for Linear (LDO) Mode Only VDDANA VDDIO VDDCORE GND GNDANA VDDOUT (1.62V — 3.63V) Main Supply Note:  Refer to "Schematic Checklist" chapter for additional information. Figure 6-3. Power Supply Connections for Switching (BUCK) / Linear (LDO) Modes VDDANA VDDIO VDDCORE GND GNDANA VDDOUT (1.62V — 3.63V) Main Supply Note:  Refer to "Schematic Checklist" chapter for additional information. SAM L10/L11 Family Power Considerations © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 28 7. Analog Peripherals Considerations This chapter provides a global view of the analog system, which is composed of the following analog peripherals: AC, ADC, DAC, OPAMP. The analog peripherals can be connected to each other as illustrated in the following block diagram. Important:  When an analog peripheral is enabled, each analog output of the peripheral will be prevented from using the alternative functions of the output pads. This is also true even when the peripheral is used for internal purposes. Analog inputs do not interfere with alternate pad functions. Figure 7-1. Analog Signal Components Interconnections OPAMP0 GND DAC/REFBUF OA0TAP ADC OA0NEG shared with DAC Output OA0TAP OA0POS OA0NEG DAC/REFBUF GND VDDANA DAC/REFBUF UG GND OA0OUT OA1TAP OA1POS OA1OUT OA1TAP OA1POS OA1NEG OA0OUT GND DAC/REFBUF UG OPAMP2 GND OA1OUT OA0TAP OA2OUT OA0NEG OA2TAP OA2POS OA2NEG OA1OUT GND UG OA0POS OA1POS OA1NEG OA2NEG DAC/REFBUF R2 R1 R2 R1 R2 R1 + - + - GND VDDANA GND VDDANA GND VDDANA ADC/ AC VDDANA VDDANA DAC output buffer VREFA VOUT DAC Internal Input. INTREF VDDANA ENABLE ENABLE HYSTERESIS HYSTERESIS VDD SCALER BANDGAP + - + - CMP0 CMP1 AIN3 AIN2 AIN1 AIN0 COMP0 COMP1 COMPCTRLn DAC OPAMP2 ADC AIN0 OPAMP01 AIN0 AIN7 INTREF 1/1.6 VDDANA VREFB POST PROCESSING PRESCALER VREFA OPAMP1 + - MUXNEG MUXPOS OPAMP2 ADC OA0POS OA2POS OA1NEG AIN2 AIN5 AIN9 ... OA0OUT Rg_CONN DAC/REFBUF Rg_CONN OA2TAP DAC/REFBUF RES3TAP DAC Output REFBUF R2 R1 OA0OUT RES3TAP DAC/REFBUF DAC GND ... 1/2 VDDANA VDDANA 1/4 VDDIO 1/4 VDDCORE INTREF Temp Sensor 1/4 VDDANA SAM L10/L11 Family Analog Peripherals Considerations © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 29 Note:  Some OPAMP Outputs (OAxOUT) can be connected directly to specific Analog Comparator or ADC Inputs (AINx) if they share the same pad: as an example, OA0OUT can be connected to the Analog Comparator AIN3 or ADC AIN5 input (PA07 pin). 7.1 Reference Voltages Some analog peripherals require a reference voltage for proper operation. Apart from external voltages (that is, VDDANA or VREFx), the device has a DETREF module that provides two different internal voltage references: • BANDGAP: A stable voltage reference, fixed at 1.1V. • INTREF: A variable voltage reference, configured by the Voltage References System Control register in the Supply Controller (SUPC.VREF). The respective reference voltage source must be selected within each dedicated analog peripheral register: • ADC: Reference Control register (ADC.REFCTRL) • DAC: Reference Selection bits in the Control B register (DAC.CTRLB.REFSEL) Note:  AC has a fixed reference voltage to BANDGAP value. 7.2 Analog On Demand Feature The Analog On Demand feature allows the ADC and the AC analog peripherals to automatically enable the OPAMPx only when it is needed, thereby allowing a reduction in power consumption. It also allows the ADC analog block to be powered-off when a conversion is completed. Note:  The Analog On Demand is independent from the On Demand Clock request feature, which is used by peripherals to automatically request a source clock which was previously stopped. OPAMP case The Analog On Demand feature of the OPAMPx is activated by writing a '1' to the OPAMP.OPAMPCTRLx.ONDEMAND bit. In that case, the OPAMPx is automatically enabled when the ADC or the AC requests it (as an input) and is automatically disabled when no more requests are coming from these peripherals. CAUTION The Analog On Demand feature is not fully supported on cascaded OPAMPs. If several OPAMPs are cascaded together, only the OPAMPx that is connected to the ADC or AC can be enabled/disabled automatically. Upstream OPAMPs will not benefit from this feature. In Standby Sleep mode, the Analog On Demand feature is still supported if OPAMP.OPAMPCTRLx.RUNSTDBY=1. If OPAMP.OPAMPCTRLx.RUNSTDBY=0, the OPAMPx will be disabled entering this Sleep mode. ADC case For the ADC peripheral, Analog On Demand feature is enabled by writing the ADC.CTRLA.ONDEMAND bit to '1'. When this feature is activated, the analog block is powered-off when the conversion is complete. In Sleep mode, when an ADC start request is detected, the analog block is powered-on again and the ADC starts a new conversion after the start-up time delay. SAM L10/L11 Family Analog Peripherals Considerations © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 30 Note:  If the OPAMPx is set to accept Analog On Demand requests but the ADC is not, the ADC will send continuous requests to the OPAMPx keeping it enabled until the ADC is switching on another input. AC case For the AC peripheral,there is no explicit ONDEMAND bit. Analog On Demand requests are issued either when the AC is used in Single-Shot mode, or when comparisons are triggered by events from the Event System. Related Links 44. OPAMP – Operational Amplifier Controller 41. ADC – Analog-to-Digital Converter 42. AC – Analog Comparators SAM L10/L11 Family Analog Peripherals Considerations © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 31 8. Device Startup This section summarizes the SAM L10/L11 device startup sequence which starts after device power-up. After power-up, the device is kept in reset until the power has stabilized throughout the device. Once VDDIO/VDDANA and VDDCORE voltages reach a stable value, the internal reset is released. 8.1 Clocks Startup The device selects the OSC16M oscillator which is enabled by default after reset and configured at 4MHz. This 4MHz clock is also the default time base for the Generic Clock Generator 0 which provides the main clock (CLK_MAIN) to the system through the GLCK_MAIN clock. Note:  Other generic clocks are disabled to optimize power consumption. Some synchronous clocks require also to be active after startup. Note:  These active synchronous clocks also receive the 4MHz clock from Generic Clock Generator 0. Refer to the Clock Mask Register section in the Main Clock (MCLK) chapter to obtain the list of clocks that are running by default. 8.2 Initial Instructions Fetching After reset is released, the CPU starts fetching from the Boot ROM. Unless a debugger is connected and places the Boot ROM in a specific mode called Boot Interactive mode, the CPU will jump to the Flash memory loading the Program Counter (PC) and Stack Pointer (SP) values and start fetching flash user code. Before jumping to the Flash, the Boot ROM resets the two first 2kB of SRAM. The Clocks remain unchanged. Note:  SAM L10/L11 Boot Interactive mode allows a debugger to perform several actions on the device such as NVM areas integrity check, chip erase, etc. Refer to 14. Boot ROM for more information. In addition, the SAM L11 Boot ROM has extra security features, such as device integrity checks, memories and peripherals security attributions, and secure boot that can be executed before jumping to the Flash in Secure state. 8.3 I/O Pins After reset, the I/O pins are tri-stated except PA30 pin (configured as an input with pull-up enabled) which is by default assigned to the SWCLK peripheral function to allow debugger probe detection. 8.4 Performance Level Overview The SAM L10/L11 support two different performance levels: PL0 and PL2. The default performance level after reset is PL0. This performance level is aiming for the lowest power consumption by limiting logic speeds and CPU frequency. As a consequence, some peripherals and clock sources will work with limited capabilities. Full device functionality and performance will be ensured with PL2 mode. SAM L10/L11 Family Device Startup © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 32 Please refer to the Electrical Characteristics sections for more information. SAM L10/L11 Family Device Startup © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 33 9. Product Mapping Figure 9-1. SAM L10 Product Mapping AHB-APB Bridge C EVSYS SERCOM0 SERCOM1 SERCOM2 TC0 TC1 TC2 ADC DAC PTC TRNG CCL OPAMP TRAM 0x42000000 0x42000400 0x42000800 0x42000C00 0x42001000 0x42001400 0x42001800 0x42001C00 0x42002000 0x42002400 0x42002800 0x42002C00 0x42003000 0x42003400 0x42003800 0x42FFFFFF Reserved AHB-APB Bridge B Reserved DSU NVMCTRL DMAC HMATRIXHS Reserved 0x41000000 0x41002000 0x41004000 0x41006000 0x41008000 0x41010000 0x41FFFFFF AHB-APB Bridge A PAC PM MCLK RSTC OSCCTRL OSC32KCTRL SUPC GCLK WDT RTC EIC FREQM PORT AC 0x40000000 0x40000400 0x40000800 0x40000C00 0x40001000 0x40001400 0x40001800 0x40001C00 0x40002000 0x40002400 0x40002800 0x40002C00 0x40003000 0x40003400 0x40003800 0x40FFFFFF Reserved Code Flash Reserved 0x00000000 0x00010000 0x00400000 AHB-APB AHB-APB Bridge A AHB-APB Bridge B AHB-APB Bridge C 0x40000000 0x41000000 0x42000000 Global Memory Space Code SRAM Reserved Peripherals Reserved Undefined Cortex-M23 Private Peripheral Bus (PPB) 0x00000000 0x20000000 0x20004000 0x40000000 0x60000000 0x80000000 0xE0000000 0xFFFFFFFF Data Flash 0x00400000 0x00400800 Boot ROM 0x02000000 0x02002000 Reserved 0x60000800 IOBUS Reserved IOBUS PORT 0x60000000 0x60000400 NVM Rows Reserved Reserved User row 0x00804000 0x00806020 0x00806038 0x0080C000 Temperature Log row Software Calibration row Boot Configuration row SAM L10/L11 Family Product Mapping © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 34 Figure 9-2. SAM L11 Product Mapping AHB-APB Bridge C EVSYS SERCOM0 SERCOM1 SERCOM2 TC0 TC1 TC2 ADC DAC PTC TRNG CCL OPAMP TRAM 0x42000000 0x42000400 0x42000800 0x42000C00 0x42001000 0x42001400 0x42001800 0x42001C00 0x42002000 0x42002400 0x42002800 0x42002C00 0x42003000 0x42003400 0x42003800 0x42FFFFFF Reserved AHB-APB Bridge B Reserved DSU NVMCTRL DMAC HMATRIXHS Reserved 0x41000000 0x41002000 0x41004000 0x41006000 0x41008000 0x41010000 0x41FFFFFF AHB-APB Bridge A PAC PM MCLK RSTC OSCCTRL OSC32KCTRL SUPC GCLK WDT RTC EIC FREQM PORT AC 0x40000000 0x40000400 0x40000800 0x40000C00 0x40001000 0x40001400 0x40001800 0x40001C00 0x40002000 0x40002400 0x40002800 0x40002C00 0x40003000 0x40003400 0x40003800 0x40FFFFFF Reserved Code Flash Reserved 0x00000000 0x00010000 0x00400000 AHB-APB AHB-APB Bridge A AHB-APB Bridge B AHB-APB Bridge C 0x40000000 0x41000000 0x42000000 Global Memory Space Code SRAM Reserved Peripherals Reserved Undefined Cortex-M23 Private Peripheral Bus (PPB) 0x00000000 0x20000000 0x20004000 0x40000000 0x60000000 0x80000000 0xE0000000 0xFFFFFFFF Data Flash 0x00400000 0x00400800 Boot ROM 0x02000000 0x02002000 Reserved 0x60000800 IOBUS Reserved IOBUS PORT 0x60000000 0x60000400 NVM Rows Reserved Reserved User row 0x00804000 0x00806020 0x00806038 0x0080C000 Temperature Log row Software Calibration row Boot Configuration row EIC Secure(1) 0x40002A00 PORT Secure(1) 0x40003200 PAC Secure(1) EVSYS Secure(1) NVMCTRL Secure(1) 0x41005000 0x40000200 0x42000200 Note:  1. This peripheral secure memory region will only appear if the peripheral is secured using PAC. Refer to Mix-Secure Peripherals for details. SAM L10/L11 Family Product Mapping © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 35 10. Memories 10.1 Embedded Memories The 32-bit physical memory address space is mapped as follows: Table 10-1. Memory Sizes Memory Base Address Size [KB] SAM L11x16(1) SAM L10x16(1) SAM L11x15(1) SAM L10x15(1) SAM L11x14 (1) SAM L10x14 (1) Flash 0x00000000 64 32 16 16 Data Flash 0x00400000 2 2 2 2 SRAM 0x20000000 16 8 8 4 Boot ROM 0x02000000 8 8 8 8 Note:  1. x = E or D. 10.1.1 Flash SAM L10/L11 devices embed 16 KB, 32 KB or 64 KB of internal Flash mapped at address 0x0000 0000. The Flash has a 512-byte (64 lines of 8 bytes) direct-mapped cache which is disabled by default after power up. The Flash is organized into rows, where each row contains four pages. The Flash has a row-erase and a page-write granularity. Table 10-2. Flash Memory Parameters Device Memory Size [KB] Number of Rows Row size [Bytes] Number of Pages Page size [Bytes] SAM L11x16 / SAM L10x16 (1) 64 256 256 1024 64 SAM L11x15 / SAM L10x15 (1) 32 128 256 512 64 SAM L11x14 / SAM L10x14 (1) 16 64 256 256 64 Note:  1. x = E or D. The Flash is divided in different regions. Each region has a dedicated lock bit preventing from writing and erasing pages on it. Refer to the NVM Memory Organization figures in the NVMCTRL chapter to get the different regions definition. Note:  The regions size is configured by the Boot ROM at device startup by reading the NVM Boot Configuration Row (BOCOR). Please refer to the 14. Boot ROM chapter for more information. Table 10-3. Flash Lock Regions Parameters Device SAM L10 SAM L11 Number of FLASH Lock Regions 2 4 Regions Name Flash Boot / Flash Application Flash Boot Secure / Flash Boot Non-Secure Flash Application Secure / Flash Application Non-Secure SAM L10/L11 Family Memories © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 36 10.1.2 Data Flash SAM L10/L11 devices embed 2 KB of internal Data Flash with Write-While-Read (WWR) capability mapped at address 0x0040 0000. The Data Flash can be programmed or erased while reading the Flash memory. It is not possible to read the Data Flash while writing or erasing the Flash. Note:  The Data Flash memory can be executable but requires more cycles to be read which may affect system performance. The Data Flash cannot be cached. The Data Flash is organized into rows, where each row contains four pages. The Data Flash has a rowerase and a page-write granularity. Table 10-4. Data Flash Memory Parameters Device Memory Size [KB] Number of Rows Row size [Bytes] Number of Pages Page size [Bytes] SAM L10/L11 2 8 256 32 64 The Data Flash is divided into one or two regions. Each region has a dedicated lock bit preventing from writing and erasing pages on it. Refer to the NVM Memory Organization figures in the NVMCTRL chapter to obtain the definitions of the different regions. Note:  The regions size is configured by the Boot ROM at device startup by reading the NVM Boot Configuration Row (BOCOR). Table 10-5. Data Flash Lock Regions Parameters Device SAM L10 SAM L11 Number of Data FLASH Lock Regions 1 2 Regions Name Data Flash Data Flash Secure / Data Flash Non-Secure 10.1.3 SRAM SAM L10/L11 devices embed 4 KB, 8 KB, or 16 KB of internal SRAM mapped at address 0x2000 0000. Table 10-6. SRAM Memory Parameters Device Memory Size [KB] SAM L11x16 / SAM L10x16 (1) 16 SAM L11x15 / SAM L10x15 (1) 8 SAM L11x14 (1) 8 SAM L10x14 (1) 4 Note:  1. x = E or D. SRAM is composed of 4KB sub-blocks which can be retained or not in STANDBY Low-Power mode to optimize power consumption. By default, all sub-blocks are retained, but it is possible to switch them off using the Power Manager (PM). SRAM retention is guaranteed for Watchog, External and System Reset resets. However, the two first 2kB of SRAM are reset by the Boot ROM. SAM L10/L11 Family Memories © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 37 Important:  SRAM retention is not guaranteed after Power Supply Resets (POR, BOD12 and BOD33). 10.1.4 Boot ROM SAM L10/L11 devices embed 8 KB of internal ROM mapped at address 0x0200 0000. Note:  Please refer to 14. Boot ROM for more details. 10.2 NVM Rows SAM L10 and SAM L11 have different Non Volatile Memory (NVM) rows which contain device configuration data that can be used by the system: Table 10-7. NVM Rows Mapping NVM Rows Address User Row (UROW) 0x00804000 Software Calibration Row 0x00806020 Temperature Log Row 0x00806038 Boot Configuration Row (BOCOR) 0x0080C000 10.2.1 NVM User Row (UROW) The Non Volatile Memory User Row (UROW) contains device configuration data that are automatically read at device power-on. This row can be updated using the NVMCTRL peripheral. When writing to the NVM User Row, the new values are not loaded by the other peripherals on the device until a device reset occurs. The NVM User Row can be read at the address 0x00804000. SAM L10 and SAM L11 have different NVM User Row mappings. Related Links 30. NVMCTRL – Nonvolatile Memory Controller 25. SUPC – Supply Controller 25.8.5 BOD33 26. WDT – Watchdog Timer 26.8.1 CTRLA 26.8.2 CONFIG 26.8.3 EWCTRL 10.2.1.1 SAM L10 User Row Table 10-8. SAM L10 UROW Bitfields Definition Bit Pos. Name Usage Factory Setting Related Peripheral Register 2:0 Reserved Reserved Reserved Reserved 5:3 NSULCK NVM UnLock Bits 0x7 NVMCTRL.NSULCK SAM L10/L11 Family Memories © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 38 Bit Pos. Name Usage Factory Setting Related Peripheral Register 6 Reserved Reserved Reserved Reserved 12:7 BOD33 Level BOD33 threshold level at power-on 0x6 SUPC.BOD33 13 BOD33 Disable BOD33 Disable at power-on 0x0 SUPC.BOD33 15:14 BOD33 Action BOD33 Action at power-on 0x1 SUPC.BOD33 24:16 BOD12 Calibration Parameters DO NOT CHANGE(1) 0x08F Reserved 25 WDT_RUNSTDBY WDT Runstdby at power-on 0x0 WDT.CTRLA 26 WDT_ENABLE WDT Enable at power-on 0x0 WDT.CTRLA 27 WDT_ALWAYSON WDT Always-On at power-on 0x0 WDT.CTRLA 31:28 WDT_PER WDT Period at power-on 0xB WDT.CONFIG 35:32 WDT_WINDOW WDT Window mode time-out at power-on 0xB WDT.CONFIG 39:36 WDT_EWOFFSET WDT Early Warning Interrupt Time Offset at power-on 0xB WDT.EWCTRL 40 WDT_WEN WDT Timer Window Mode Enable at power-on 0x0 WDT.CTRLA 41 BOD33_HYST BOD33 Hysteresis configuration at power-on 0x0 SUPC.BOD33 255:42 Reserved Reserved Reserved Reserved CAUTION 1. BOD12 is calibrated in production and its calibration parameters must not be changed to ensure the correct device behavior. Table 10-9. SAM L10 UROW Mapping Offset Bit Pos. Name 0x00 7:0 BOD33 Level - NSULCK Reserved 0x01 15:8 BOD33 Action BOD33 Disable BOD33 Level 0x02 23:16 BOD12 Calibration Parameters 0x03 31:24 WDT_PER WDT_ALWAYS ON WDT_ENABLE WDT_RUNSTD BY BOD12 Calibration Parameters 0x04 39:32 WDT_EWOFFSET WDT_WINDOW 0x05 47:40 Reserved BOD33_HYST WDT_WEN 0x06-0x1F 255:48 Reserved 10.2.1.2 SAM L11 User Row Table 10-10. SAM L11 UROW Bitfields Definition Bit Pos. Name Usage Factory Setting Related Peripheral Register 2:0 SULCK NVM Secure Region UnLock Bits 0x7 NVMCTRL.SULCK 5:3 NSULCK NVM Non-Secure Region UnLock Bits 0x7 NVMCTRL.NSULCK 6 Reserved Reserved Reserved Reserved 12:7 BOD33 Level BOD33 threshold level at power-on. 0x6 SUPC.BOD33 13 BOD33 Disable BOD33 Disable at power-on 0x0 SUPC.BOD33 15:14 BOD33 Action BOD33 Action at power-on 0x1 SUPC.BOD33 24:16 BOD12 Calibration Parameters Do not change(See Note 1 under Caution) 0x08F Reserved SAM L10/L11 Family Memories © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 39 Bit Pos. Name Usage Factory Setting Related Peripheral Register 25 WDT_RUNSTDBY WDT Runstdby at power-on 0x0 WDT.CTRLA 26 WDT_ENABLE WDT Enable at power-on 0x0 WDT.CTRLA 27 WDT_ALWAYSON WDT Always-On at power-on 0x0 WDT.CTRLA 31:28 WDT_PER WDT Period at power-on 0xB WDT.CONFIG 35:32 WDT_WINDOW WDT Window mode time-out at power-on 0xB WDT.CONFIG 39:36 WDT_EWOFFSET WDT Early Warning Interrupt Time Offset at power-on 0xB WDT.EWCTRL 40 WDT_WEN WDT Timer Window Mode Enable at power-on 0x0 WDT.CTRLA 41 BOD33_HYST BOD33 Hysteresis configuration at power-on 0x0 SUPC.BOD33 42 Reserved Reserved Reserved Reserved 43 RXN RAM is eXecute Never 0x1 IDAU.SECCTRL 44 DXN Data Flash is eXecute Never 0x1 NVMCTRL.SECCTRL 63:45 Reserved Reserved Reserved Reserved 71:64 AS Flash Application Secure Size = AS*0x100 0xFF IDAU.SCFGA 77:72 ANSC Flash Application Non-Secure Callable Size = ANSC*0x20 0x0 IDAU.SCFGA 79:78 Reserved Reserved Reserved Reserved 83:80 DS Data Flash Secure Size = DS*0x100 0x8 IDAU.SCFGA 87:84 Reserved Reserved Reserved Reserved 94:88 RS RAM Secure Size = RS*0x80 0x7F IDAU.SCFGR 95 Reserved Reserved Reserved Reserved 96 URWEN User Row Write Enable 0x1 NVMCTRL.SCFGAD 127:97 Reserved Reserved Reserved Reserved 159:128 NONSECA(1) Peripherals Non-Secure Status Fuses for Bridge A 0x0000_0000 PAC.NONSECA 191:160 NONSECB(2, 3) Peripherals Non-Secure Status Fuses for Bridge B 0x0000_0000 PAC.NONSECB 223:192 NONSECC Peripherals Non-Secure Status Fuses for Bridge C 0x0000_0000 PAC.NONSECC 255:224 USERCRC CRC of NVM User Row bits 223:64 0x8433651E Boot ROM Note:  1. The PAC Peripheral is always secured regardless of its bit value 2. The IDAU and NVMCTRL peripherals are always secured regardless of their bit values. 3. The DSU peripheral is always non-secured regardless of its bit value. CAUTION 1. BOD12 is calibrated in production and its calibration parameters must not be changed to ensure the correct device behavior. Table 10-11. SAM L11 UROW Mapping Offset Bit Pos. Name 0x00 7:0 BOD33 Level - NSULCK SULCK 0x01 15:8 BOD33 Action BOD33 Disable BOD33 Level 0x02 23:16 BOD12 Calibration Parameters SAM L10/L11 Family Memories © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 40 Offset Bit Pos. Name 0x03 31:24 WDT_PER WDT_ALWAYS ON WDT_ENABLE WDT_RUNSTD BY BOD12 Calibration Parameters 0x04 39:32 WDT_EWOFFSET WDT_WINDOW 0x05 47:40 Reserved DXN RXN Reserved BOD33_HYST WDT_WEN 0x06 55:48 Reserved 0x07 63:56 Reserved 0x08 71:64 AS 0x09 79:72 Reserved ANSC 0x0A 87:80 Reserved DS 0x0B 95:88 Reserved RS 0x0C 103:96 Reserved URWEN 0x0D-0xF 127:104 Reserved 0x10-0x13 159:128 NONSECA 0x14-0x17 191:160 NONSECB 0x18-0x1B 223:192 NONSECC 0x1C-0x1F 255:224 USERCRC 10.2.2 NVM Software Calibration Area The NVM Software Calibration Area contains calibration data that can be used by some peripherals, such as the ADC. Note:  Calibration data are determined and written during production test and cannot be written. The NVM Software Calibration Area can be read at address 0x00806020. Table 10-12. NVM Software Calibration Bitfields Definition Bit Position Name Description 2:0 ADC LINEARITY ADC Linearity Calibration. Should be written to CALIB register. 5:3 ADC BIASCAL ADC Bias Calibration. Should be written to CALIB register. 8:6 DFLLULP Division Factor in PL0 DFLLULP Division Factor in PL0. Should be written to DFLLULPCTRL register. 11:9 DFLLULP Division Factor in PL2 DFLLULP Division Factor in PL2. Should be written to DFLLULPCTRL register. 127:12 Reserved Reserved Table 10-13. NVM Software Calibration Row Mapping Offset Bit Pos. Name 0x00 7:0 DFLLULP Division Factor in PL0 ADC BIASCAL ADC LINEARITY 0x01 15:8 Reserved DFLLULP Division Factor in PL2 DFLLULP Division Factor in PL0 0x02-0xF 127:16 Reserved 10.2.3 NVM Temperature Log Row The NVM Temperature Log Row contains calibration data that are determined and written during production test and cannot be written. These calibration values are required for calculating the temperature from measuring the temperature sensor in the Supply Controller (SUPC) by the ADC. SAM L10/L11 Family Memories © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 41 The NVM Temperature Log Row can be read at address 0x00806038. Table 10-14. Temperature Log Row Bitfields Definition Bit Position Name Description 7:0 ROOM_TEMP_VAL_INT Integer part of room temperature in °C 11:8 ROOM_TEMP_VAL_DEC Decimal part of room temperature 19:12 HOT_TEMP_VAL_INT Integer part of hot temperature in °C 23:20 HOT_TEMP_VAL_DEC Decimal part of hot temperature 31:24 ROOM_INT1V_VAL 2’s complement of the internal 1V reference drift at room temperature (versus a 1.0 centered value) 39:32 HOT_INT1V_VAL 2’s complement of the internal 1V reference drift at hot temperature (versus a 1.0 centered value) 51:40 ROOM_ADC_VAL Temperature sensor 12bit ADC conversion at room temperature 63:52 HOT_ADC_VAL Temperature sensor 12bit ADC conversion at hot temperature Important:  Hot temperature corresponds to the max operating temperature +/- 5%, so 85°C +/- 5% (package grade 'U') or 125°C +/- 5% (package grade 'F'). Table 10-15. Temperature Log Row Mapping Offset Bit Pos. Name 0x00 7:0 ROOM_TEMP_VAL_INT 0x01 15:8 HOT_TEMP_VAL_INT ROOM_TEMP_VAL_DEC 0x02 23:16 HOT_TEMP_VAL_DEC HOT_TEMP_VAL_INT 0x03 31:24 ROOM_INT1V_VAL 0x04 39:32 HOT_INT1V_VAL 0x05 47:40 ROOM_ADC_VAL 0x06 55:48 HOT_ADC_VAL ROOM_ADC_VAL 0x07 63:56 HOT_ADC_VAL 10.2.4 NVM Boot Configuration Row (BOCOR) The Non-Volatile Memory Boot Configuration Row (BOCOR) contains device configuration data that are automatically read by the Boot ROM program at device startup. This row can be updated using the NVMCTRL peripheral. When writing to the NVM Boot Configuration Row, the new values are not loaded by the other peripherals on the device until a device reset occurs. The NVM Boot Configuration Row can be read at address 0x0080C000. SAM L10 and SAM L11 have different NVM Boot Configuration Row mappings. 10.2.4.1 SAM L10 Boot Configuration Row Table 10-16. SAM L10 BOCOR Bitfields Definition Bit Pos. Name Usage Factory Setting Related Peripheral Register 31:0 Reserved Reserved Reserved Reserved 39:32 BOOTPROT Boot Protection size = BOOTPROT*0x100 0x00 Boot ROM SAM L10/L11 Family Memories © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 42 Bit Pos. Name Usage Factory Setting Related Peripheral Register 95:40 Reserved Reserved Reserved Reserved 127:96 ROMVERSION ROM Code Version Device Dependent Boot ROM 511:128 Reserved Reserved Reserved Reserved 639:512 CRCKEY CRC Key All '1's Boot ROM 2047:640 Reserved Reserved Reserved Reserved Table 10-17. SAM L10 BOCOR Mapping Offset Bit Pos. Name 0x00-0x03 31:0 Reserved 0x04 39:32 BOOTPROT 0x05-0x0B 95:40 Reserved 0x0C-0x0F 127:96 ROMVERSION 0x10-0x3F 511:128 Reserved 0x40-0x4F 639:512 CRCKEY 0x50-0xFF 2047:640 Reserved 10.2.4.2 SAM L11 Boot Configuration Row Table 10-18. SAM L11 BOCOR Bitfields Definition Bit Pos. Name Usage Factory Setting Related Peripheral Register 7:0 Reserved Reserved Reserved Reserved 15:8 BS Boot Flash Secure Size = BS*0x100 0x00 IDAU.SCFGB 21:16 BNSC Boot Flash Non-Secure Callable Size = BNSC*0x20 0x00 IDAU.SCFGB 23:22 Reserved Reserved Reserved Reserved 31:24 BOOTOPT Boot Option 0xA0 Boot ROM 39:32 BOOTPROT Boot Protection size = BOOTPROT*0x100 0x00 IDAU.SCFGB 47:40 Reserved Reserved Reserved Reserved 48 BCWEN Boot Configuration Write Enable 0x1 NVMCTRL.SCFGB 49 BCREN Boot Configuration Read Enable 0x1 NVMCTRL.SCFGB 63:50 Reserved Reserved Reserved Reserved 95:64 BOCORCRC Boot Configuration CRC for bit 63:0 0xC1D7ECC3 Boot ROM 127:96 ROMVERSION ROM Code Version 0x0000003A Boot ROM 255:128 CEKEY0 Chip Erase Key 0 All 1s Boot ROM 383:256 CEKEY1 Chip Erase Key 1 All 1s Boot ROM 511:384 CEKEY2 Chip Erase Key 2 All 1s Boot ROM 639:512 CRCKEY CRC Key All 1s Boot ROM 895:640 BOOTKEY Secure Boot Key All 1s Boot ROM 1791:896 Reserved Reserved Reserved Reserved 2047:1792 BOCORHASH Boot Configuration Row Hash All 1s Boot ROM SAM L10/L11 Family Memories © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 43 Table 10-19. SAM L11 BOCOR Mapping Offset Bit Pos. Name 0x00 7:0 Reserved 0x01 15:8 BS 0x02 23:16 Reserved BNSC 0x03 31:24 BOOTOPT 0x04 39:32 BOOTPROT 0x05 47:40 Reserved 0x06 55:48 Reserved BCREN BCWEN 0x07 63:56 Reserved 0x08-0x0B 95:64 BOCORCRC 0x0C-0x0F 127:96 ROMVERSION 0x10-0x1F 255:128 CEKEY0 0x20-0x2F 383:256 CEKEY1 0x30-0x3F 511:384 CEKEY2 0x40-0x4F 639:512 CRCKEY 0x50-0x6F 895:640 BOOTKEY 0x70-0xDF 1791:896 Reserved 0xE0-0xFF 2047:1792 BOCORHASH 10.3 Serial Number Each device has a unique 128-bit serial number which is a concatenation of four 32-bit words contained at the following addresses of the NVM Rows memory space: • Word 0: 0x0080A00C • Word 1: 0x0080A040 • Word 2: 0x0080A044 • Word 3: 0x0080A048 Note:  The uniqueness of the serial number is only guaranteed when considering all 128 bits. SAM L10/L11 Family Memories © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 44 11. Processor and Architecture 11.1 Cortex-M23 Processor The SAM L10/L11 implement the ARM® Cortex®-M23 processor, based on the ARMv8-M Baseline Architecture, which is the smallest and most energy efficient ARM processor with ARM TrustZone® security technology. TrustZone® for ARMv8-M provides hardware-enforced security isolation between trusted and the untrusted resources on a Cortex™-M23 based device, while maintaining the efficient exception handling. The implemented ARM Cortex-M23 is revision r1p0. The ARM Cortex-M23 core has two bus interfaces: • Single 32-bit AMBA®-5 AHB-Lite system interface that provides connections to peripherals and memories. • Single 32-bit I/O port bus interfacing to the PORT and Crypto Accelerator peripherals with 1-cycle load and store. Note:  For more information refer to http://www.arm.com 11.1.1 Cortex-M23 Configuration This table gives the configuration for the ARM Cortex-M23 processor. Table 11-1. SAM L10/L11 Cortex-M23 Configuration Features Cortex-M23 Configurable Options SAM L10 Implementation SAM L11 Implementation Memory Protection Unit (MPU) Not present, 4, 8, 12, or 16 regions One MPU with 4 regions Two MPUs with 4 regions each (one Secure / one Non-Secure) Security Attribute Unit (SAU) Absent, 4-region, or 8-region Absent Absent Implementation Defined Attribution Unit (IDAU) Present or Absent Absent Present SysTick timer(s) Absent, 1 timer or 2 timers (one Secure and one Non-Secure) One SysTick timer Two timers (One Secure / One Non-Secure) Vector Table Offset Register Present or absent Present (one Vector table) Present (two Vector tables) Reset all registers Present or absent Absent Absent Multiplier Fast (one cycle) or slow (32 cycles) Fast (one cycle) Fast (one cycle) Divider Fast (17 cycles) or slow (34 cycles) Fast (17 cycles) Fast (17 cycles) Interrupts External interrupts 0-240 43(1) 45(1) Instruction fetch width 16-bit only or 32-bit 32-bit 32-bit Single-cycle I/O port Present or absent Present Present Architectural clock gating present Present or absent Present Present Data endianness Little-endian or big-endian Little-endian Little-endian Halt debug support Present or absent Absent Absent Wake-up interrupt controller (WIC) Present or absent Absent Absent Number of breakpoint comparators 0, 1, 2, 3, 4 4 4 Number of watchpoint comparators 0, 1, 2, 3, 4 2 2 SAM L10/L11 Family Processor and Architecture © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 45 Features Cortex-M23 Configurable Options SAM L10 Implementation SAM L11 Implementation Cross Trigger Interface (CTI) Present or absent Absent Absent Micro Trace Buffer (MTB) Present or absent Absent Absent Embedded Trace Macrocell (ETM) Present or absent Absent Absent JTAGnSW debug protocol Selects between JTAG or SerialWire interfaces for the DAP Serial-Wire Serial-Wire Multi-drop for Serial Wire Present or absent Absent Absent Note:  1. Refer to Table 11-3 for more information. For more details, refer to the ARM Cortex-M23 Processor Technical Reference Manual (http:// www.arm.com). 11.1.2 Cortex-M23 Core Peripherals The processor has the following core peripheral: • System Timer (SysTick) – The System Timer is a 24-bit timer clocked by the core frequency. Important:  On SAM L11 devices, there are two System timers, one for Secure state and one for Non-secure state. • Nested Vectored Interrupt Controller (NVIC) – The NVIC is an embedded interrupt controller that supports low latency interrupt processing. Important:  On SAM L11 devices, there are two Vector tables: the Secure Vector table and the Non-Secure Vector table. • System Control Block (SCB) – The System Control Block (SCB) provides system implementation information and system control that includes configuration, control, and reporting of system exceptions • Memory Protection Unit (MPU) – The MPU improves system reliability by defining the memory attributes for different memory regions. Important:  On SAM L11 devices, there are two MPUs: one for the Secure state and one for the Non-secure state. Each MPU can define memory access permissions and attributes independently. • Security Attribution Unit (SAU) – The SAU improves system security by defining security attributes for different regions. SAM L10/L11 Family Processor and Architecture © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 46 Important:  The SAU is absent from SAM L10 and SAM L11 devices. For more details, refer to the ARM Cortex-M23 Processor Technical Reference Manual (http:// www.arm.com). Table 11-2. Cortex-M23 Core Peripherals Address Map Core Peripherals Base Address (SAM L10 and SAM L11) (Non-Secure) Alias Base Address (SAM L11 only) System Timer (SysTick) 0xE000E010 0xE002E010 Nested Vectored Interrupt Controller (NVIC) 0xE000E100 0xE002E100 System Control Block (SCB) 0xE000ED00 0xE002ED00 Memory Protection Unit (MPU) 0xE000ED90 0xE002ED90 11.1.3 Single Cycle I/O Port The device allows direct access to PORT registers. Accesses to the AMBA® AHB-Lite™ and the single cycle I/O interface can be made concurrently, so the Cortex-M23 processor can fetch the next instructions while accessing the I/Os. This enables single cycle I/O access to be sustained for as long as necessary. Note:  The Crypto Accelerator peripheral also benefits from this port. Refer to the 13.3 Crypto Acceleration section for more information. 11.2 Nested Vector Interrupt Controller 11.2.1 Overview The Nested Vectored Interrupt Controller (NVIC) in the SAM L10/L11 supports up to 45 interrupt lines with four different priority levels + 1 Non Maskable Interrupt (NMI) line. For more details, refer to the Cortex-M23 Technical Reference Manual (http://www.arm.com). 11.2.2 Interrupt Line Mapping Each interrupt line is connected to one peripheral instance, as shown in the table below. Each peripheral can have one or more interrupt flags, located in the peripheral’s Interrupt Flag Status and Clear (INTFLAG) register. An interrupt flag is set when the interrupt condition occurs. Each interrupt in the peripheral can be individually enabled by writing a 1 to the corresponding bit in the peripheral’s Interrupt Enable Set (INTENSET) register, and disabled by writing 1 to the corresponding bit in the peripheral’s Interrupt Enable Clear (INTENCLR) register. An interrupt request is generated from the peripheral when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt requests for one peripheral are ORed together on system level, generating one interrupt request for each peripheral. An interrupt request will set the corresponding interrupt pending bit in the NVIC interrupt pending registers (SETPEND/CLRPEND bits in ISPR/ICPR). For the NVIC to activate the interrupt, it must be enabled in the NVIC interrupt enable register (SETENA/ CLRENA bits in ISER/ICER). The NVIC interrupt priority registers IPR0-IPR7 provide a priority field for each interrupt. SAM L10/L11 Family Processor and Architecture © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 47 Table 11-3. Interrupt Line Mapping Module Source NVIC line EIC NMI – External Interrupt Controller NMI NMI PM – Power Manager PLRDY 0 MCLK - Main Clock CKRDY OSCCTRL - Oscillators Controller XOSCRDY XOSCFAIL OSC16MRDY DFLLULPRDY DFLLULPLOCK DFLLULPNOLOCK DPLLLCKR DPLLLCKF DPLLLTO DPLLLDRTO OSC32KCTRL - 32KHz Oscillators Controller XOSC32KRDY CLKFAIL SUPC - Supply Controller BOD33RDY BOD33DET B33SRDY VREGRDY VCORERDY ULPVREFRDY WDT – Watchdog Timer EW 1 RTC – Real Time Counter CMP0 2 CMP1 OVF PER0 PER1 PER2 PER3 PER4 PER5 PER6 PER7 TAMPER EIC – External Interrupt Controller EXTINT 0 3 EXTINT 1 4 EXTINT 2 5 EXTINT 3 6 EXTINT 4..7 7 NSCHK(1) FREQM - Frequency Meter DONE 8 NVMCTRL – Non-Volatile Memory Controller DONE 9 PROGE SAM L10/L11 Family Processor and Architecture © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 48 Module Source NVIC line LOCKE NVME KEYE NSCHK(1) PORT - I/O Pin Controller NSCHK(1) 10 DMAC - Direct Memory Access Controller SUSP 0 11 TERR 0 TCMPL 0 SUSP 1 12 TERR 1 TCMPL 1 SUSP 2 13 TERR 2 TCMPL 2 SUSP 3 14 TERR 3 TCMPL 3 SUSP 4..7 15 TERR 4..7 TCMPL 4..7 EVSYS – Event System EVD 0 16 OVR 0 EVD 1 17 OVR 1 EVD 2 18 OVR 2 EVD 3 19 OVR 3 NSCHK(1) 20 PAC - Peripheral Access Controller ERR 21 SERCOM0 – Serial Communication Interface 0 (Interrupt Sources vary depending on SERCOM mode) Interrupt Bit 0 22 Interrupt Bit 1 23 Interrupt Bit 2 24 Interrupt Bits 3..6 25 SERCOM1 – Serial Communication Interface 1 (Interrupt Sources vary depending on SERCOM mode) Interrupt Bit 0 26 Interrupt Bit 1 27 Interrupt Bit 2 28 Interrupt Bit 3..6 29 SERCOM2 – Serial Communication Interface 2 (Interrupt Sources vary depending on SERCOM mode) Interrupt Bit 0 30 Interrupt Bit 1 31 Interrupt Bit 2 32 Interrupt Bits 3..6 33 TC0 – Timer Counter 0 ERR A 34 MC 0 SAM L10/L11 Family Processor and Architecture © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 49 Module Source NVIC line MC 1 OVF TC1 – Timer Counter 1 ERR A 35 MC 0 MC 1 OVF TC2 – Timer Counter 2 ERR A 36 MC 0 MC 1 OVF ADC – Analog-to-Digital Converter OVERRUN 37 WINMON RESRDY 38 AC – Analog Comparator COMP 0 39 COMP 1 WIN 0 DAC – Digital-to-Analog Converter UNDERRUN 40 EMPTY 41 PTC – Peripheral Touch Controller EOC 42 WCOMP TRNG - True Random Number Generator DATARDY 43 TRAM - Trust RAM DRP 44 ERR Note:  1. NSCHK interrupt sources will not generate any interrupts for SAM L10 devices. 11.3 High-Speed Bus System 11.3.1 Features The High-Speed Bus Matrix has the following features: • 32-bit data bus • Allows concurrent accesses from different masters to different slaves • Operation at a one-to-one clock frequency with the bus masters 11.3.2 Configuration There are two master-to-slave connections to optimize system bandwidth: • Multi-Slave Masters which are connected through the AHB bus matrix Table 11-4. AHB Multi-Slave Masters AHB Multi-Slave Masters Cortex-M23 Processor DSU - Device Service Unit DMAC - Direct Memory Access Controller / Data Access SAM L10/L11 Family Processor and Architecture © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 50 Table 11-5. AHB Slaves AHB Slaves Flash Memory AHB-APB Bridge A AHB-APB Bridge B AHB-APB Bridge C SRAM Port 0 - Cortex-M23 Access SRAM Port 1 - DMAC Access SRAM Port 2 - DSU Access Boot ROM • Privileged SRAM-access Masters which have a direct access to some dedicated SRAM ports Table 11-6. Privileged SRAM-access Masters Privileged SRAM-access Masters DMAC - Fetch 0 Access DMAC - Fetch 1 Access DMAC - Write Back 0 Access DMAC - Write Back 1 Access Note:  Privileged SRAM-access Masters rely on SRAM quality of service to define priority levels (SRAM Port ID). Refer to 11.4 SRAM Quality of Service for more information. SAM L10/L11 Family Processor and Architecture © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 51 Figure 11-1. Master-to-Slave Access Cortex-M23 0 DSU 1 High-Speed Bus SLAVES Flash AHB-APB Bridge A AHB-APB Bridge B AHB-APB Bridge C Multi-Slave MASTERS CM23 DSU SRAM DSU 1 DSU 0 1 2 3 4 5 6 SRAM PORT ID DMAC Data 2 DMAC Data DMAC Fetch 0 DMAC Fetch 1 DMAC WB 0 DMAC WB 1 DMAC Fetch 0 DSU Privileged SRAM-access MASTERS DMAC Fetch 1 DMAC WB 0 DSU DMAC WB 1 Boot ROM 11.4 SRAM Quality of Service To ensure that masters with latency requirements get sufficient priority when accessing RAM, priority levels can be assigned to the masters for different types of access. The Quality of Service (QoS) level is independently selected for each master accessing the RAM. For any access to the RAM, the RAM also receives a QoS level. The QoS levels and their corresponding bit values are shown in the following table. Table 11-7. Quality of Service Value Name Description 0x0 DISABLE Background (no sensitive operation) 0x1 LOW Sensitive Bandwidth 0x2 MEDIUM Sensitive Latency 0x3 HIGH Critical Latency Note:  If a master is configured with QoS level DISABLE (0x0) or LOW (0x1), there will be a minimum latency of one cycle to get RAM access. SAM L10/L11 Family Processor and Architecture © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 52 The priority order for concurrent accesses are decided by two factors: • As first priority, the QoS level for the master. • As a second priority, a static priority given by the port ID. The lowest port ID has the highest static priority. See the tables below for more details. Table 11-8. HS SRAM Port Connections QoS HS SRAM Port Connection Port ID Connection Type QoS default QoS DMAC - Direct Memory Access Controller - Write-Back 1 Access 6 Direct DMAC QOSCTRL.WRBQOS 0x2 DMAC - Direct Memory Access Controller - Write-Back 0 Access 5 Direct DMAC QOSCTRL.WRBQOS 0x2 DMAC - Direct Memory Access Controller - Fetch 1 Access 4 Direct DMAC QOSCTRL.FQOS 0x2 DMAC - Direct Memory Access Controller - Fetch 0 Access 3 Direct DMAC QOSCTRL.FQOS 0x2 DMAC - Direct Memory Access Controller - Data Access 2 Bus Matrix DMAC QOSCTRL.DQOS 0x2 DSU - Device Service Unit 1 Bus Matrix DSU CFG.LQOS 0x2 CM23 - Cortex M23 Processor 0 Bus Matrix 0x41008114, bits[1:0](1) 0x3 Note:  1. The CPU QoS level can be written/read, using 32-bit access only. SAM L10/L11 Family Processor and Architecture © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 53 12. Peripherals Configuration Summary Table 12-1. Peripherals Configuration Summary Peripheral name Base address IRQ line AHB clock APB clock Generic Clock PAC Events DMA Power domain Index Enabled at Reset Index Enabled at Reset Index Index Write Protection at Reset User Generator Sleep Walking Index Name AHB-APB Bridge A 0x40000000 — 0 Y — — — — — — — N/A — PDSW PAC 0x40000000 21: ERR 6 Y 0 Y — 0 N — 49: ERR Y — PDSW PM 0x40000400 0: PLRDY — — 1 Y — 1 N — — N/A — PDAO MCLK 0x40000800 0: CKRDY — — 2 Y — 2 N — — N/A — PDSW RSTC 0x40000C00 — — — 3 Y — 3 N — — N/A — PDAO OSCCTRL 0x40001000 0: XOSCRDY, XOSCFAIL, OSC16MR DY, DFLLULPR DY, DFLLULPL OCK, DFLLULPN OLOCK, DPLLLCKR, DPLLLCKF, DPLLLTO, DPLLLDRT O — — 4 Y 0: FDPLL96M clk source 1: FDPLL96M 32 kHz 2: DFLLULP reference 4 N 0: TUNE 1: CFD Y — PDSW OSC32KCT RL 0x40001400 0: XOSC32KR DY, CLKFAIL — — 5 Y — 5 N — 2: CFD Y — PDAO SUPC 0x40001800 0: BOD33RDY ,BOD33DE T, B33SRDY, VREGRDY, VCORERD Y, ULPVREFR DY — — 6 Y — 6 N — 3: BOD33DET Y — PDAO GCLK 0x40001C00 — — — 7 Y — 7 N — — N/A — PDSW WDT 0x40002000 1: EW — — 8 Y — 8 N — — N/A — PDSW RTC 0x40002400 2: CMP0-1, TAMPER, OVF, PER0-7 — — 9 Y — 9 N 1: TAMPER 4-11 : PER0-7 12-13 : CMP0-1 14 : TAMPER 15 : OVF 16 : PERD Y 1: TIMESTAM P PDAO EIC 0x40002800 3: EXTINT0 4: EXTINT1 5: EXTINT2 6: EXTINT3 7: EXTINT4-7, NSCHK NMI — — 10 Y 3 10 N — 17-24: EXTINT0-7 Y — PDAO FREQM 0x40002C00 8: DONE — — 11 Y 4: FREQM_M SR 5: FREQM_R EF 11 N — — N/A — PDSW PORT 0x40003000 10: NSCHK — — 12 Y — 12 N 3-6 : EV0-3 — Y — PDAO AC 0x40003400 39: COMP0-1, WIN0 — — 13 Y 17 13 N 16-17: SOC0-1 40-41: COMP0-1 42: WIN0 Y — PDAO SAM L10/L11 Family Peripherals Configuration Summary © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 54 Peripheral name Base address IRQ line AHB clock APB clock Generic Clock PAC Events DMA Power domain Index Enabled at Reset Index Enabled at Reset Index Index Write Protection at Reset User Generator Sleep Walking Index Name AHB-APB Bridge B 0x41000000 — 1 Y — — — — — — — N/A — PDSW DSU 0x41002000 — 4 Y 1 Y — 1 Y — — N/A 2-3: DCC0-1 PDSW NVMCTRL 0x41004000 9: DONE, PROGE, LOCKE, NVME, KEYE, NSCHK 7 Y 2 Y — 2 N 2: AUTOW — Y — PDSW DMAC 0x41006000 11: SUSP0, TERR0, TCMPL0 12: SUSP1, TERR1, TCMPL1 13: SUSP2, TERR2, TCMPL2 14: SUSP3, TERR3, TCMPL3 15: SUSP4-7, TERR4-7, TCMPL4-7 3 Y — — — 3 — 7-10: CH0-3 25-28: CH0-3 Y — PDSW HMATRIXH S 0x41008000 — 5 Y — — — 4 N — — N/A — PDSW AHB-APB Bridge C 0x42000000 — 2 Y — — — — — — — N/A — PDSW EVSYS 0x42000000 16: EVD0, OVR0 17: EVD1, OVR1 18: EVD2, OVR2 19: EVD3, OVR3 20: NSCHK — — 0 Y 6: CH0 7: CH1 8: CH2 9: CH3 0 N — — N/A — PDSW SERCOM0 0x42000400 22: bit 0 23: bit 1 24: bit 2 25: bit 3-6 — — 1 Y 11: CORE 10: SLOW 1 N — — N/A 4: RX 5: TX PDSW SERCOM1 0x42000800 26: bit 0 27: bit 1 28: bit 2 29: bit 3-6 — — 2 Y 12: CORE 10: SLOW 2 N — — N/A 6: RX 7: TX PDSW SERCOM2 0x42000C00 30: bit 0 31: bit 1 32: bit 2 33: bit 3-6 — — 3 Y 13: CORE 10: SLOW 3 N — — N/A 8: RX 9: TX PDSW TC0 0x42001000 34: ERR, MC0, MC1, OVF — — 4 Y 14 4 N 11: EVU 29: OVF 30-31: MC0-1 Y 10: OVF 11-12: MC0-1 PDSW TC1 0x42001400 35: ERR, MC0, MC1, OVF — — 5 Y 14 5 N 12: EVU 32: OVF 33-34: MC0-1 Y 13: OVF 14-15: MC0-1 PDSW TC2 0x42001800 36: ERR, MC0, MC1, OVF — — 6 Y 15 6 N 13: EVU 35: OVF 36-37: MC0-1 Y 16: OVF 17-18: MC0-1 PDSW ADC 0x42001C00 37: OVERRUN, WINMON 38:RESRD Y — — 7 Y 16 7 N 14: START 15 : SYNC 38: RESRDY 39: WINMON Y 19: RESRDY PDSW DAC 0x42002000 40: UNDERRU — — 8 Y 18 8 N 18: START 43: EMPTY Y 20: EMPTY PDSW SAM L10/L11 Family Peripherals Configuration Summary © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 55 Peripheral name Base address IRQ line AHB clock APB clock Generic Clock PAC Events DMA Power domain Index Enabled at Reset Index Enabled at Reset Index Index Write Protection at Reset User Generator Sleep Walking Index Name N 41: EMPTY PTC 0x42002400 42: EOC, WCOMP — — 9 Y 19 9 N 19 : STCONV 20 : DSEQR 44: EOC 45: WCOMP Y 21 : EOC 22 : SEQ 23 : WCOMP PDSW TRNG 0x42002800 43: DATARDY — — 10 Y — 10 N — 46 : READY Y — PDSW CCL 0x42002C00 — — — 11 Y 20 11 N 21 : LUTIN0 22 : LUTIN1 47 : LUTOUT0 48 : LUTOUT1 Y — PDSW OPAMP 0x42003000 — — — 12 Y — 12 N — — N/A — PDSW TRAM 0x42003400 44: DRP, ERR 12 Y — — — 13 — — — N/A — PDSW SAM L10/L11 Family Peripherals Configuration Summary © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 56 13. SAM L11 Security Features This chapter provides an overview of the SAM L11 security features. 13.1 Features Security features can be split in two main categories. The first category relates to the ARM TrustZone for Cortex-M technology features: • Flexible hardware isolation of memories and peripherals: – Up to six regions for the Flash – Up to two regions for the Data Flash – Up to two regions for the SRAM – Individual security attribution (secure or non-secure) for each peripheral using the Peripheral Access Controller (PAC) – Mix-secure peripherals which support both secure and non-secure security attributions • Three debug access levels allowing: – The highest debug level with no restrictions in term of memory and peripheral accesses – A restricted debug level with non-secure memory regions access only – The lowest debug level where no access is authorized except with a debugger using a Boot ROM-specific mode • Different chip erase support according to security settings • Security configuration is fully stored in Flash and safely auto-loaded at startup during Boot ROM execution using CRC checks Important:  Debug access levels, such as Chip Erase support are described in the Boot ROM chapter. The second category relates to the extra security features which are not related to ARM TrustZone for Cortex-M technology support: • Built-in cryptographic accelerator accessible through cryptographic libraries stored in ROM – Supporting AES-128 encryption/decryption, SHA-256 authentication, GCM encryption and authentication – Cryptographic libraries are especially designed for side channel and fault injection attacks prevention • One True Random Generator (TRNG) • Secure Boot, which performs integrity check on a configurable portion of the Flash (BS memory area) • Secure Pin Multiplexing to isolate on dedicated SERCOM I/O pins a secured communication with external devices from the non secure application • Data Flash – Optimized for secrets storage – Data Scrambling with user-defined key (optional) SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 57 – Rapid Tamper erase on scrambling key and on one user-defined row – Silent access for side channel attack resistance • TrustRAM – Address and Data scrambling with user-defined key – Chip-level tamper detection on physical RAM to resist microprobing attacks – Rapid Tamper Erase on scrambling key and RAM data – Silent access for side channel attack resistance – Data remanence prevention • Unique 128-bit serial number 13.2 ARM TrustZone Technology for ARMv8-M ARM TrustZone for Cortex-M technology is an optional core extension, which enables the system and the software to be partitioned into Secure and Non-secure domains. Secure software can access both Secure and Non-secure memories and resources, while Non-Secure software can only access Non-secure memories and resources. Figure 13-1. TrustZone for ARMv8-M Non-Secure states Secure Application/Library Secure OS Non-Secure Application Non-Secure OS Secure states If the TrustZone is implemented (SAM L11 devices), the system starts up in Secure state by default. The security state of the processor can be either Secure or Non-secure. Important:  For more details, please refer to TrustZone Technology for ARMv8-M Architecture, which is available on the ARM web site (www.arm.com). 13.2.1 Memory System and Memory Partitioning The memory space is partitioned into Non-Secure and Secure memory regions: • Non-Secure (NS): Non-Secure addresses are used for memory and peripherals accessible by all software, that is, running on the device. • Secure (S): Secure addresses are used for memory and peripherals accessible only by Secure software or masters. SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 58 • Non-Secure Callable (NSC): NSC is a special type of Secure memory location. It allows software to transition from Non-Secure to Secure state. The Cortex-M23 provides two ways for managing the security configurations of the device. The first solution consists in using the Cortex-M23 SAU (Security Attribution Unit), which is a Memory Protection Unit (MPU) like hardware embedded in the core. The role of the SAU is to manage all the Secure and Non-Secure transactions coming from the core. However, using the SAU implies that the security configuration must be propagated somewhere else in the MCU architecture for security awareness. The second approach, which is the one used for SAM L11 devices, is articulated around a centralized Implementation Defined Attribution Unit (IDAU), which is a hardware unit external to the core. For SAM L11 devices, the IDAU is coupled to the Cortex-M23 and manages all the security configurations related to the core. In addition, the IDAU propagates all the security configurations to the memory controllers. The IDAU, Flash, Data Flash and SRAM embedded memories can be split in sub-regions, which are reserved either for the Secure or for the Non-Secure application. Therefore, the SAU is not required and is absent from SAM L10/L11 devices. The peripherals security attribution is managed by the Peripherals Access Controller (PAC). The PAC and each peripheral can be allocated either to the Secure or to the Non-Secure application, with the exception of the PAC, NVMCTRL, and DSU. Note:  1. The PAC and NVMCTRL peripherals are always secured. 2. The DSU peripheral is always non-secured. Both IDAU and PAC security configurations are stored in NVM fuses, which are read after each reset during Boot ROM execution and are loaded after Boot ROM verifications into their respective registers. The peripherals security attribution (using PAC) is locked before exiting the Boot ROM execution sequence, that is, it is not possible to change a peripheral's configuration (Secure or Non-Secure) during application execution. However, the security attribution of each peripheral, excluding the PAC, NVMCTRL, and DSU, can be modified using the NONSECx NVM fused from the User Row (UROW) during application execution, hence it can be considered after any reset. 13.2.2 Memories Security Attribution The IDAU is used to indicate the processor if a particular memory region is Secure (S), Non-secure Callable (NSC), or Non-secure (NS). It can also mark a memory region to be exempted from security checking. Table 13-1. IDAU Memory Attribution Definition Attribute Description Non-Secure Memory can be accessed in Secure or Non-Secure state. Secure Memory can only be accessed in Secure state. It cannot be called from Non-Secure state. Non-Secure callable Memory can only be accessed in Secure state, but can be called from Non-Secure state. Exempt No attribution check will be done, and the operation will take place on the bus Note:  Refer to " SAM L11 Security Attribution" chapter for the detailed SAM L11 memories and peripherals security attribution description. SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 59 The Cortex-M23 will search each access (fetch or data) in the IDAU, which returns the privilege information about that specific address. If the access is not permitted, the CPU enters a HardFault exception. The IDAU memory region's attributes are partly hardwired and partly set by NVM configuration fuses, and are loaded into the IDAU by the Boot ROM before application execution. The IDAU memory region's attributes are blocked for further writes from the application, but their current state can still be read through dedicated IDAU registers. Note:  Refer to the "SAM L11 IDAU Memory Mapping Registers". 13.2.2.1 Flash The SAM L11 Flash can be split in up to six regions: • The first three regions are called BOOT regions and can be configured to support a first-level bootloader for the application. • The other regions are called APPLICATION regions and relate to the application itself. The total size of the BOOT regions is defined by the BOOTPROT fuses from the NVM Boot Configuration Row (BOCOR), the APPLICATION regions total size being the remaining available size of the Flash. Each of these BOOT / APPLICATION global regions can be split in up to three sub-regions: • The Secure sub-region • The Non-Secure Callable (NSC) sub-region • The Non-Secure (NS) sub-region Each sub-region size can be configured using dedicated fuses from the NVM Boot Configuration Row (BOCOR): • BS fuse corresponds to the size of the Secure + NSC sub-regions of the BOOT region • BNSC fuse corresponds to the NSC sub-region size of the BOOT region • AS fuse corresponds to the size of the Secure + NSC sub-regions of the APPLICATION region • ANSC fuse corresponds to the NSC sub-region size of the APPLICATION region SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 60 Figure 13-2. SAM L11 Flash Memory Mapping BS BOOTPROT BNSC AS ANSC Non-Secure Boot Secure Boot Non-Secure Application Non-Secure Callable Boot Secure Application Non-Secure Callable Application Flash 13.2.2.2 Data Flash The SAM L11 Data Flash can be split in up to two regions: • The Secure Data Flash region, with a size defined by the DS fuse from the NVM Boot Configuration Row (BOCOR) • The Non-Secure (NS) Data Flash region Figure 13-3. SAM L11 Data Flash Memory Mapping DS Secure Non-Secure Data Flash 13.2.2.3 SRAM The SAM L11 SRAM can be split in up to two regions: SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 61 • The Secure SRAM region, with a size defined by the RS fuse from the NVM Boot Configuration Row (BOCOR) • The Non-Secure (NS) SRAM region Figure 13-4. SAM L11 SRAM Memory Mapping RS Secure Non-Secure SRAM 13.2.3 SAM L11 Memory Mapping Configuration Summary The table below summarizes the mapping of the SAM L11 memory regions. Table 13-2. SAM L11 Memory Regions Mapping Memory region Base address Size Flash Boot area 0x00000000 BOOTPROT * 256Bytes Flash Secure Boot 0x00000000 BS*256Bytes - BNSC*32Bytes Flash Non-Secure Callable Boot Contiguous to Flash Secure Boot BNSC * 32Bytes Flash Non-Secure Boot (1) BS * 256Bytes Flash Boot remaining size (BOOTPROT * 256Bytes - BS*256Bytes) Flash Appliation area BOOTPROT * 256Bytes Flash size - BOOTPROT * 256Bytes (Flash Boot area) Flash Secure Application BOOTPROT * 256Bytes AS*256Bytes-ANSC*32Bytes Flash Non-Secure Callable Application Contiguous to Flash Secure APPLICATION ANSC * 32Bytes Flash Non-Secure Application (BOOTPROT+AS) * 256Bytes Flash remaining size (Flash size - BOOTPROT*256Bytes - AS*256Bytes) Secure Data Flash 0x00400000 DS * 256Bytes Non-Secure Data Flash Contiguous to Secure Data Flash 2KB - Secure Data Flash size Secure SRAM 0x20000000 RS * 128Bytes Non-Secure SRAM Contiguous to Secure SRAM SRAM size - Secure SRAM size Note:  1. Flash Secure Boot size cannot be null if a Flash Non-Secure Boot size is defined. Here is a typical configuration for a 64KB of Flash, 2KB of Data Flash and 16KB of SRAM: • Flash boot area: – Total Boot area size = 8KB => BOOTPROT = 8192 / 256 = 0x20 – Flash Secure + Non-Secure Callable Boot size = 1KB => BS = 1024 / 256 = 0x4 – Flash Non-Secure Callable Boot size = 32Bytes => BNSC = 32 / 32 = 0x1 – Flash Non-Secure Boot size = 8KB - 1KB = 7KB • Flash Application area: – Total Application area size = 64 KB - 8KB = 56KB SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 62 – Flash Secure + Non-Secure Callable Application size = 16KB => AS = 16 * 1024 / 256 = 0x40 – Flash Non-Secure Callable Application size = 32Bytes => ANSC = 32 / 32 = 0x1 – Flash Non-Secure Application size = 56KB - 16KB = 40KB • Data Flash area: – Data Flash Secure size = 2KB => DS = 2048 / 256 = 0x8 – Data Flash Non-Secure size = 2 KB - 2 KB = 0KB • SRAM Flash area – SRAM Secure size = 4KB => RS = 4096 / 128 = 0x20 – SRAM Non-Secure size = 16KB - 4KB = 12KB 13.2.4 SAM L11 IDAU Memory Mapping Registers The tables below summarizes the mapping of the SAM L11 IDAU memory regions. Table 13-3. SAM L11 IDAU Memory Register Address Registers Address SECCTRL 0x41000001 SCFGB 0x41000004 SCFGA 0x41000008 SCFGR 0x4100000C Table 13-4. SAM L11 IDAU SECCTRL Register (8-bit) Bit Position Name 7:0 Reserved RXN (Bit 2) Reserved Table 13-5. SAM L11 IDAU SCFGB Register (32-bit) Bit Position Name 7:0 BS 15:8 Reserved BNSC (bit 8-13) 23:16 BOOTPROT 31:24 Reserved Table 13-6. SAM L11 IDAU SCFGA Register (32-bit) Bit Position Name 7:0 AS 15:8 Reserved ANSC (bit 8-13) 23:16 Reserved DS (bit 16-19) 31:24 Reserved Table 13-7. SAM L11IDAU SCFGR Register (8-bit) Bit Position Name 7:0 Reserved RS (bit 0-6) 13.2.5 Peripherals Security Attribution In addition to generic protection features, the Peripheral Access Controller (PAC) configures the security privileges for each individual peripheral in the system. SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 63 Each peripheral can only be configured either in Secure or in Non-Secure mode. The PAC NONSECx registers (Read Only) contain one bit per peripheral for that purpose, which is the image of the NONSECx fuses from the NVM User row (UROW). During Boot ROM execution, the NONSECx fuses from the NVM User row are copied in the PAC peripheral NONSECx registers so that they can be read by the application. All peripherals are marked as "exempt" in the memory map, meaning that all bus transactions are propagated. As a consequence, any illegal accesses are reported back to the PAC and trigger an interrupt if enabled. The security configuration (Secure or Non-Secure) is propagated to each individual peripheral, thus it is the responsibility of the peripheral to grant or not the access with the following rules: • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0), a PAC error is triggered Important:  These rules do not apply to the specific peripherals called Mix-Secure peripherals. Note:  The Secure application will usually provide an API for the Non-Secure application using the NonSecure Callable region (NSC) to allow the Non-Secure application to request specific resources. Table 13-8. Peripheral PAC Security Attribution (Excluding Mix-Secure Peripherals) Mode Secure Master Access Non-Secure Master Access Non-Secure Read / Write Read / Write Secure Read / Write Discarded (Write ignored / Read 0x0) PAC Error is generated 13.2.5.1 SAM L11 Peripherals Configuration Example Below is a typical configuration examples where all peripherals except the ADC, TC0, and Event System (EVSYS) are reserved to the Secure application: • Secure/Non-Secure Peripherals PAC configuration: – PAC.NONSECA=PAC.NONSECB=0x0000_0000 – PAC.NONSECC=0x0000_00091 (ADC, TC0 and EVSYS available for the Non-Secure application) 13.2.6 SAM L11 Memory Space Security Attribution This table provides the security attributions of the SAM L11 memory space: SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 64 Table 13-9. SAM L11 Memory Space Security Attributions Memory region Attribute Flash Secure Boot Secure Flash Non-Secure Callable Boot Non-secure callable Flash Non-Secure Boot Non-secure Flash Secure Application Secure Flash Non-Secure Callable Application Non-secure callable Flash Non-Secure Application Non-secure Secure Data Flash Secure Non-Secure Data Flash Non-secure NVM User Rows Secure (R/W access) Non-Secure (Discarded for BOCOR, Read-only for the others) Boot ROM Secure Execute-only for CRYA functions Hardfault generated if not Secure SRAM Secure Non-Secure SRAM Non-secure Peripherals Exempt IOBUS Exempt Others (Reserved, Undefined...) Secure 13.2.7 Cortex-M23 Test Target Instructions Software may check the privilege state of a memory location by using the Cortex-M23 Test Target instructions: TT, TTT, TTA, and TTAT. The memory location is referenced using the Cortex-M23 IREGION bitfield, which specifies the IDAU region number (see the ARMv8-M Architecture Reference Manual for more information). Table 13-10. SAM L11 IDAU Region Number for TT, TTT, TTA and TTAT Cortex-M23 Instructions Memory Region IDAU Region Number for TTx Instructions (IREGION bits) Flash Secure BOOT 0x01 Flash Non-Secure Callable BOOT 0x02 Flash Non-Secure BOOT 0x03 Flash Secure APPLICATION 0x04 Flash Non-Secure Callable APPLICATION 0x05 Flash Non-Secure APPLICATION 0x06 Secure Data Flash 0x07 Non-Secure Data Flash 0x08 NVM User Rows 0x00 (invalid) Boot ROM 0x09 Secure SRAM 0x0A Non-Secure SRAM 0x0B Peripherals 0x00 (invalid) SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 65 Memory Region IDAU Region Number for TTx Instructions (IREGION bits) IOBUS 0x00 (invalid) Others (Reserved, Undefined...) 0x00 (invalid) 13.2.8 Mix-Secure Peripherals There are five Mix-Secure peripherals that allow internal resources to be shared between the Secure and Non-Secure applications: • The PAC controller which manages peripherals security attribution (Secure or Non-Secure). • The Flash memory controller (NVMCTRL) which supports Secure and Non-Secure Flash regions programming. • The I/O controller (PORT) which allows to individually allocate each I/O to the Secure or NonSecure applications. • The External Interrupt Controller (EIC) which allows to individually assign each external interrupt to the Secure or Non-Secure applications. • The Event System (EVSYS) allows to individually assign each event channel to the Secure or NonSecure applications. When a Mix-Secure peripheral is configured as Secure in the PAC, its register map is automatically duplicated in a Secure and Non-Secure alias: • The Non-Secure alias is at the peripheral base address. • The Secure alias is located at the peripheral base address: – + 0x200 offset for the PAC, EIC, PORT and EVSYS peripherals Non-Secure Alias Secure Alias Registers Table Mix-Secure Peripheral (Not PAC Secured) Base Address Base Address Base Address + 0x200 Mix-Secure Peripheral (PAC Secured) PAC, PORT, EIC and EVSYS Cases – + 0x1000 offset for the NVMCTRL peripheral. SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 66 Non-Secure Alias Secure Alias Registers Table Mix-Secure Peripheral (PAC Secured) Mix-Secure Peripheral (Not PAC Secured) Base Address Base Address Base Address + 0x1000 NVMCTRL Case The Secure alias has the following characteristics: • All of the peripheral registers are available for the Secure application through the Secure alias • When an internal resource becomes available to the Non-Secure application, the corresponding registers (called Mix-Secure registers) or bitfields in registers are still accessible through this Secure alias by the Secure application • Non-Secure accesses to this Secure alias are discarded (Write is ignored, Read is 0x0) and a PAC error is triggered The Non-Secure alias has the following characteristics: • Only a restricted set of registers are available for the Non-Secure application through the NonSecure alias • It is the responsibility of the Secure application to assign some resources to the Non-Secure application. This is done by setting the corresponding bits in the NONSECx registers of the MixSecure peripheral. – When an internal resource becomes available for the Non-Secure application, the corresponding registers (called Mix-Secure and Write-Mix-Secure registers) or bitfields in the registers are accessible through the Non-Secure alias by the Non-Secure application – Non-Secure accesses to Secure resources (registers, bitfields) are silently discarded (Write is ignored, Read is 0x0) and no error is generated • Secure accesses to the Non-Secure alias are silently discarded (Write is ignored, Read is 0x0) and no error is generated SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 67 Registers Table Non-Secure OS Base Address Base Address + 0x200 or 0x1000 Non-Secure Alias Base Address Base Address + 0x200 or 0x1000 Secure Alias Secure Alias Non-Secure registers Non-Secure registers Secure registers Write-Secure registers Mix-Secure registers Write-Mix-Secure registers Non-Secure registers Secure registers Write-Secure registers Mix-Secure registers Write-Mix-Secure registers Non-Secure registers Mix-Secure registers Write-Mix-Secure registers + Some registers/bitfields assigned to Non-Secure Accesses No registers/bitfields assigned to Non-Secure Accesses Mix-Secure Peripheral Write-Secure registers + Non-Secure Alias + Write-Secure registers Mix-Secure peripherals have always the following registers: • NONSEC register is a generic register that tells the Non-Secure application which resources inside a Mix-Secure peripheral can be used • NSCHK register is a register allowing the Non-Secure application to be notified when the security configuration of a Mix-Secure peripheral is being modified during application execution Important:  It is recommended that the Non-Secure application first copy the content of NONSEC register inside NSCHK register, and then enable the NSCHK interrupt flags. Once done, any changes to the NONSEC register by the Secure application will trigger an interrupt so that Non-Secure application can take appropriate actions. This mechanism allows the Secure application to dynamically change the security attribution of a Mix-Secure peripheral and avoid illegal accesses from the Non-Secure application. The interrupt handler should always copy the NONSEC register to NSCHK register before exiting it. Mix-Secure peripherals can have five type of registers: • Non-Secure: these registers will always be available in both the Secure and Non-Secure aliases • Secure: these registers will never be available in the Non-Secure alias and always available in the Secure alias • Write-Secure: these are registers than can: – Be written or read by the Secure application only in the Secure alias – Only read by the Non-Secure application in Non-Secure alias. Write is forbidden. • Mix-Secure registers : these ones are used when a resource can be allocated to either the Secure and Non-Secure alias – Note that, in some cases, the Mix-Secure properties apply to a bitfield only (like one I/O bit in the PORT peripheral register) • Write-Mix-Secure registers (NVMCTRL peripheral only): these are Mix-Secure registers, which: – can be written or read by the Secure application only in the Secure alias – can only be read by the Non-Secure application in Non-Secure alias except if Non-Secure writes are authorized in NVMCTRL.NONSEC register SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 68 Table 13-11. SAM L11 Mix-Secure Peripheral Registers Access Mix-Secure Peripheral Register Secure Master Access Non-Secure Master Access Secure Alias Non-Secure Alias Secure Alias Non-Secure Alias Non-Secure Read / Write Discarded (Write ignored / Read 0x0) No Error is generated Discarded (Write ignored / Read 0x0) PAC Error is generated Read / Write Secure Discarded (Write ignored / Read 0x0) No Error is generated Write-Secure Read-only (Write ignored) No Error is generated Mix-Secure Read/Write if the resource is available for the NonSecure Application Discarded if not (Write ignored / Read 0x0) and no error is generated Write-Mix-Secure Read /Write if the resource is available for the NonSecure Application Read-only if not (Write ignored) and no error is generated 13.3 Crypto Acceleration 13.3.1 Overview The SAM L11 product embeds a hardware/software cryptographic accelerator (CRYA) which supports Advanced Encryption Standard (AES) encryption and decryption, Secure Hash Algorithm 2 (SHA-256) authentication, and Galois Counter Mode (GCM) encryption and authentication through a set of APIs, which are only accessible once the Boot ROM has completed. Note:  The CRYA cryptographic accelerator is mapped as a slave on the IOBUS port and is driven by the CPU using assembly code (located in ROM). The Advanced Encryption Standard (AES) is compliant with the American FIPS (Federal Information Processing Standard) Publication 197 specification. The AES operates on a 128-bit block of input data. The key size used for an AES cipher specifies the number of repetitions of transformation rounds that convert the input plaintext, into the final output, called the ciphertext. The AES works on a symmetric-key algorithm, meaning the same key is used for both encrypting and decrypting the data. The SHA-256 is a cryptographic hash function that creates a 256-bit hash of a data block. The data block is processed in chunks of 512 bits. The GCM is a mode of operation for AES that combines the CTR (Counter) mode of operation with an authentication hash function. For detail algorithm specification, refer to following standards and specification: • AES: FIPS Publication 197, Advanced Encryption Standard (AES) • SHA: FIPS Pub 180-4, The Secure Hash Standard • GCM: NIST Special Publication 800-38D Recommendation 13.3.2 Features • Advanced Encryption Standard (AES), compliant with FIPS Publication 197 – Encryption with 128-bit cryptographic key – Decryption with 128-bit cryptographic key SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 69 – Countermeasures against side-channel attacks for AES • Secure Hash Algorithm 2 (SHA-256), compliant with FIPS Pub 180-4 – Accelerates message schedule and inner compression loop • Galois Counter Mode (GCM) encryption using AES engine and authentication – Accelerates the GF(2128) multiplication for AES-GCM hash function 13.3.3 CRYA APIs The CRYA APIs which are located in a dedicated Boot ROM area are only accessible from the user application after the Boot ROM has completed. This area is an execute-only area, meaning the CPU cannot do any loads, but can call the APIs. The Boot ROM memory space is a secure area, only the secure application can directly call these APIs. Table 13-12. CRYA APIs Addresses CRYA API Address AES Encryption 0x02001904 AES Decryption 0x02001908 SHA Process 0x02001900 GCM Process 0x0200190C 13.3.3.1 AES API The AES software has two function routines to do encryption and decryption on a 128 bit block of input data. The AES encryption function entry point is located at the Boot ROM address 0x02001904 and the encryption function parameters are: • Src[in] : a pointer to a 128-bit data block to be encrypted • Dst[out]: a pointer to 128 bit encrypted data • Keys[in]: a pointer to 128 bit key • Length[in]: Number of 32-bit words comprising the Key, 4 for 128 bits key The AES decryption function entry point is located at the Boot ROM address 0x02001908 and the decryption function parameters are: • Src[in] : a pointer to a 128-bit data block to be decrypted • Dst[out]: a pointer to 128 bit decrypted data • Keys[in]: a pointer to 128 bit key • Length[in]: Number of 32-bit words comprising the Key, 4 for 128 bits key The APIs are: /* Type definition for CRYA AES functions. */ typedef void (*crya_aes_encrypt_t) (const uint8_t *keys, uint32_t key_len, const uint8_t *src, uint8_t *dst); typedef void (*crya_aes_decrypt_t) (const uint8_t *keys, uint32_t key_len, const uint8_t *src, uint8_t *dst); /* AES encrypt function * \param keys[in]: A pointer to 128-bit key * \param key_len[in]: Number of 32-bit words comprising the key, 4 for 128-bit key * \param src[in]: A pointer to a 128-bit data block to be encrypted SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 70 * \param dst[out]: A pointer to a 128-bit encrypted data */ #define secure_crya_aes_encrypt ((crya_aes_encrypt_t ) (0x02001904 | 0x1)) /* AES decrypt function * \param keys[in]: A pointer to 128-bit key * \param key_len[in]: Number of 32-bit words comprising the key, 4 for 128-bit key * \param src[in]: A pointer to a 128-bit data block to be decrypted * \param dst[out]: A pointer to a 128-bit decrypted data */ #define secure_crya_aes_decrypt ((crya_aes_decrypt_t ) (0x02001908 | 0x1)) 13.3.3.2 SHA API The SHA software function can update the hash value based on the 512-bit data. It is assumed that the message is already preprocessed properly for the SHA algorithm, so that the SHA software can work directly on 512-bit portions. The SHA function entry point is located at the Boot ROM address 0x02001900 and has three parameters: • [In/out]: A pointer to a hash location (hash input and output) • [In]: A pointer to a 512-bit data block • [In]: A pointer to a RAM buffer (256B needed for internal algorithm) The updated hash value is put at first parameter after the function exit. The API is: /* Type definition for CRYA SHA function. */ typedef void (*crya_sha_process_t) (uint32_t hash_in_out[8], const uint8_t data[64], uint32_t ram_buf[64]); /* CRYA SHA function * \param hash_in_out[In/out]: A pointer to a hash location (hash input and output) * \param data[In]: A pointer to a 512 bit data block * \param ram_buf[In]: A pointer to a RAM buffer (256B needed for internal algorithm) */ #define crya_sha_process ((crya_sha_process_t ) (0x02001900 | 0x1)) Code example of using CRYA SHA software: void sha256_process(uint32_t hash[8], const uint8_t data[64]) { uint32_t ram_buf[64]; /* 256 bytes needed for message schedule table */ /* Pointer to CRYA SHA function in ROM */ static void (*crya_sha_process)(uint32_t hash_in_out[8], const uint8_t data[64], uint32_t ram_buf[64]); crya_sha_process = (void (*)(uint32_t *, const uint8_t *, uint32_t *)) *((uint32_t*)0x02001900); crya_sha_process (hash, data, ram_buf); } 13.3.3.3 GCM API The GCM function entry point is is located at the Boot ROM address 0x0200190C and the function parameters are: • Block1[in]: a pointer to 128-bit data blocks that are to be multiplied • Block2[in]: a pointer to 128-bit data blocks that are to be multiplied • dst[out]: a pointer to a location for storing the result SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 71 The API is: /* Type definition for GF(2^128) multiplication */ typedef void (*crya_gf_mult128_t) (const uint32_t *block1, const uint32_t *block2, uint32_t *dst); /* GF(2^128) multiplication. * * \param block1[In]: A pointer to 128-bit data blocks that are to be multiplied * \param block2[In]: A pointer to 128-bit data blocks that are to be multiplied * \param dst[out]: A pointer to a location for storing the result */ #define secure_crya_gf_mult128 ((crya_gf_mult128_t ) (0x0200190C | 0x1)) 13.4 True Random Number Generator (TRNG) Refer to TRNG - True Random Number Generator for more information. 13.5 Secure Boot A Secure Boot with SHA-based authentication on a configurable portion on the Flash (BS memory area) is available with verification mechanisms allowing to reset and restart the authentication process in case of a failure. Refer to 14. Boot ROM for more information. 13.6 Secure Pin Multiplexing on SERCOM The Secure Pin Multiplexing feature can be used on dedicated SERCOM I/O pins to isolate a secured communication with external devices from the non-secure application. To benefit from this feature, the security attribution of the SERCOM must be set as secured using the PAC peripheral. When this operation occurs: • The secured SERCOM instances becomes mapped only on a specific set of I/Os • All of the alternate I/O pins of the secured SERCOM instance are kept in a Hi-Z configuration • The PTC cannot enable PTC lines mapped to any of the secured SERCOM instance I/O pins • The CCL I/Os mapped to the secured SERCOM instance I/O pins are set to '0' Refer to 4.4.2 Secure Pin Multiplexing (on SERCOM) Pins to obtain the list of pins supporting that feature. 13.7 Data Flash Refer to 30. NVMCTRL – Nonvolatile Memory Controller to get all security features related to the Data Flash. 13.8 TrustRAM (TRAM) Refer to TRAM - TrustRAM to get all security features related to the TrustRAM. SAM L10/L11 Family SAM L11 Security Features © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 72 14. Boot ROM The Boot ROM allows to ensure the integrity of the device at boot. The Boot ROM features Boot Interactive mode, which allows the user to perform several actions on the device, such as NVM areas integrity check and chip erase via a debugger connection. Unless a debugger is connected and places the Boot ROM in Boot Interactive mode, the CPU will jump to the Flash memory, loading the Program Counter (PC) and Stack Pointer (SP) values, and will start fetching Flash user code. Note:  Before jumping to the Flash, the Boot ROM resets the two first 2kB of SRAM. The Clocks remain unchanged. In addition, the SAM L11 Boot ROM has extra security features, such as device integrity checks, memories/peripherals security attributions, and secure boot, which can be executed before jumping to the Flash in Secure state. For security reasons, while the Boot ROM is executing, no debug is possible except when entering a specific Boot ROM mode called CPU Park mode. Related Links 13.1 Features 14.1 Features • Command interface for the host debugger supporting: – Chip erase commands to provide secure transitions between the different Debug Access Levels (DAL) – Device integrity check of the NVM memory regions – Debugger read access of the NVM rows • CPU Park mode to get access for a debugger to the resources of the device depending on Debug Access Level (DAL) • SAM L11 Added features: – Device integrity checks – Memory and peripheral security attributions from user configuration stored in NVM rows – Secure Boot on Flash BS Memory Area Related Links 13.1 Features SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 73 14.2 Block Diagram Figure 14-1. Boot ROM Block Diagram Boot ROM DSU Device Service Unit Host Debugger SWD Serial Wire Debug BCC Boot Communication Channels NVMCTRL IDAU (SAM L11) CRYA PAC TRNG Related Links 13.1 Features 14.3 Product Dependencies In order to use this module, other parts of the system must be configured correctly, as described below. Related Links 13.1 Features 14.3.1 Clocks The device selects the OSC16M oscillator which is enabled by default after reset and configured at 4 MHz. 14.3.2 NVM User (UROW) and Boot Configuration (BOCOR) rows The Boot ROM reads the different NVM rows during its execution. The relevant fuses must be set appropriately by any configuration tools supported the device in order to operate correctly. Refer to the 10.2 NVM Rows section for additional information. 14.3.3 Debug Operations For security reasons, no debug is possible during the Boot ROM execution except when entering the Boot ROM CPU Park mode. 14.4 Functional Description Related Links 13.1 Features 14.4.1 SAM L10 Boot ROM Flow The SAM L10 Boot ROM checks firstly if a debugger is present to enter the Boot Interactive mode which allows the user to perform specific tasks via a debugger connection. SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 74 Before jumping to the application, the Boot ROM can also enter in a specific mode called CPU Park to allow the debugger to get access to the resources of the device depending on Debug Access Level (DAL). Note:  Boot Interactive and CPU Park modes are described later on. Figure 14-2. SAM L10 Boot ROM Flow Wait for Debugger Command Start Application CPU Park Mode System RESET Is Debugger Connected ? Interactive Boot Mode RESET Is Debugger Connected AND BREXT ==1 ? BREXT == 1 BREXT == 0 Yes "Init" Command If no debugger is connected: automatic exit from Boot interactive mode No "Exit" command No Yes 14.4.1.1 Typical Boot Timings The delay is given from the release of the CPU reset to the execution of the first instruction of the user code: Table 14-1. SAM L10 Typical Boot Timing Time to reach User Code 1.33 ms 14.4.2 SAM L11 Boot ROM Flow The SAM L11 Boot ROM sequence consists in performing several security tasks (integrity checks, memories and peripherals security attribution, secure boot...) before starting the application. The Boot ROM checks firstly if a debugger is present to enter the Boot Interactive mode which allows the user to perform specific tasks via a debugger connection. Before jumping to the application in Secure state, the Boot ROM can also enter in a specific mode called CPU Park to allow the debugger to get access to the resources of the device depending on Debug Access Level (DAL). Note:  Boot Interactive and CPU Park modes are described later on. SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 75 Figure 14-3. SAM L11 Boot ROM Flow Device Integrity Checks Wait for Debugger Command Apply Memories & Peripherals Security Settings Start Application IS Debugger Connected AND BREXT == 1? CPU Park Mode System RESET Is Debugger Connected ? Boot Interactive Mode BS and BOCOR Verifications Bootloader Authentication BOOTOPT>0 ? RESET No BREXT == 1 Yes BREXT == 0 Yes OK "Init" Command Not OK OK No "Exit" Command No Yes If no debugger is connected: automatic exit from Boot interactive mode OK 14.4.2.1 Device Integrity Checks For SAM L11 devices, the Boot ROM performs security checks on two CRCs: • The User Row CRC (USERCRC) which is located in the NVM User Row (UROW) at: [0x80401C: 0x80401F]: UROW Offset Bit Position Name 0x1C-0x1F 255:224 USERCRC • The Boot Configuration Row CRC (BOCORCRC) which is located in the NVM Boot Configuration Row (BOCOR) at: [0x80C008:0x80C00B]: BCOR Offset Bit Position Name 0x08-0x0B 95:64 BOCORCRC 14.4.2.1.1 User Row CRC (USER CRC) USERCRC allows to check the following fuses parameters integrity: • AS, ANSC, DS, RS SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 76 • URWEN • NONSECA, NONSECB, NONSECC USERCRC is the CRC of the NVM User row area which starts from 0x00804008 and finish at 0x0080401B (bit 64 to bit 223): Table 14-2. SAM L11 UROW Area Computed in USERCRC Offset Bit Pos. Name 0x08 71:64 AS 0x09 79:72 Reserved ANSC 0x0A 87:80 Reserved DS 0x0B 95:88 Reserved RS 0x0C 103:96 Reserved URWEN 0x0D-0xF 127:104 Reserved 0x10-0x13 159:128 NONSECA 0x14-0x17 191:160 NONSECB 0x18-0x1B 223:192 NONSECC 14.4.2.1.2 Boot Configuration Row CRC (BOCORCRC) BOCORCRC allows to check the following fuses parameters integrity: • BS, BNSC • BOOTOPT • BOOTPROT, BCWEN, BCREN BOCORCRC is the CRC of the NVM Boot Configuration row area, which starts from 0x0080C000 and finish at 0x00800C007 (bit 0 to bit 63). Table 14-3. SAM L11 BOCOR Area Computed in BOCORCRC Offset Bit Pos. Name 0x00 7:0 Reserved 0x01 15:8 BS 0x02 23:16 Reserved BNSC 0x03 31:24 BOOTOPT 0x04 39:32 BOOTPROT 0x05 47:40 Reserved 0x06 55:48 Reserved BCREN BCWEN 0x07 63:56 Reserved If one of the checks fails, the Boot ROM will report the error to the DSU peripheral and will enter the Boot Interactive mode: • This will allow, if a debugger is connected, to put the device in the highest debug access level mode (DAL = 2) by issuing a Chip Erase command . Once in that mode, it is possible for a programming tool to reprogram the NVM Rows. • When the check fails and no debugger is connected, the part will reset and restart the check sequence again. Note:  Boot Interactive mode is described later in this chapter. SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 77 14.4.2.1.3 CRC Computation and Programming The CRCs needs to be recalculated and updated in their respective NVM row as soon as a data from any of the checked regions is changed. Important:  USERCRC and BOCORCRC CRCs programming must be done by any programming tool supporting the SAM L11 devices. The algorithm is a CRC-32 module embedded in the DSU peripheral and that uses for both CRC calculation with the following parameters: • Width = 32 bits • Polynomial = 0x04C11DB7 (Poly) • Initial Value = 0xFFFFFFFF (Init) • Input Data is reflected (RefIn) • Output Data is reflected (RefOut) • No XOR is performed on the output CRC (XorOut) Example: the DSU CRC of 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39 is 0x340BC6D9 14.4.2.2 Memories and Peripherals Configurations Initialization For SAM L11 devices, memories and peripherals security attributions are done by reading the different fuses values from the NVM User (UROW) and Boot Configuration (BOCOR) rows. The Boot ROM is responsible for setting these attributions on the different concerned memory and peripheral controllers: • Set memory security attribution according to AS, ANSC, DS, RS, BS, BSNC and BOOTPROT fuses • Set peripherals security attribution according to NONSECA, NONSECB and NONSECC fuses Important:  The Boot ROM does not perform any consistency checks on the configured memory attributions (e.g setting BS>BOOTPROT will not trigger any errors during Boot ROM execution). 14.4.2.3 Secure Boot Depending on the BOOTOPT fuse value (from BOCOR NVM row), the following secure boot integrity checks will be performed on: • The Flash BS memory area which is composed by: – The Flash Secure BOOT memory region – The Flash Non-Secure Callable BOOT memory region • And the NVM Boot Configuration row (BOCOR) Table 14-4. Secure Boot Options BOOTOPT Verified Areas Verification Method 0 None - 1 Flash BS Memory Region + NVM BOCOR row SHA-256 SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 78 BOOTOPT Verified Areas Verification Method 2 or 3 Flash BS Memory Region + NVM BOCOR row SHA-256 with BOOTKEY (defined in BOCOR) Other Values None - If the verification fails, the Boot ROM will report the error to the DSU peripheral and will enter the Boot Interactive mode. This will allow, if a debugger is connected, to put the device in the highest debug level access mode (DAL = 2) by issuing a Chip Erase command. Once in that mode, it is possible for a programming tool to reprogram the different memory regions and/or NVM rows. When verification fails and no debugger is connected, the part will reset and restart the integrity checks sequences again. 14.4.2.3.1 Hash algorithm (SHA-256) Verification Method The verifications are done using the standard SHA256 hash algorithm. Both Flash BS region and NVM BOCOR row hashes are computed on the defined memory/row area and compared to their expected reference hash value. Note:  The hash consists of 256 bits, i.e. 32 bytes. SHA256 with BOOTKEY Variant To prevent unauthorized change of the bootloader code, the hash computation can be slightly modified to require a key to produce a valid hash. When SHA with BOOTKEY is selected (BOOTOPT=2 or =3), the hash computation (for both Flash BS region and NVM BOCOR row) starts by processing the secure boot key (BOOTKEY) data twice, then proceeds with the rest of data. This secure boot key (BOOTKEY) is located in the NVM Boot Configuration row (BOCOR) at [0x80C0050:0x80C006F]: BOCOR Offset Bit Position Name 0x50-0x6F 895:640 BOOTKEY 14.4.2.3.2 BS Verification When BOOTOPT>0, the bootloader authentication starts allowing a secure bootloader code to be protected against inadvertent or malicious changes. The hash is computed on the Flash Secure BOOT and Flash Non-Secure Callable BOOT (BNSC) regions. The hash reference value for this area is stored at the end of the Secure BOOT area, just before the NonSecure Callable BOOT (BNSC) one. Note:  The last 256 bits where the hash is stored are not included in the hash computation. SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 79 Figure 14-4. BS Hash location in BS memory area Flash Secure BOOT 0x00000000 Flash Non-Secure Callable BOOT BS Reference Hash : 256bits (32 bytes) BNSC BS * Granularity BS Important:  The Non-Secure BOOT region as well as Secure or Non-Secure APPLICATION regions are not part of the Secure Boot verification. So if an authentication of one of these memory regions is required, it must be handled by the user code itself. 14.4.2.3.3 BOCOR Verification When BOOTOPT>0, the hash for the NVM BOCOR row is computed on the whole NVM BOCOR row excluding BOCORHASH fuse value which is the fuse where to store the hash reference value [0x80C00E0:0x80C00FF]: BOCOR Offset Bit Position Name 0xE0-0xFF 2047:1792 BOCORHASH 14.4.2.4 Typical Boot Timings Depending on the boot authentication options, the Boot ROM will require a certain time to complete its different tasks. The delay is given from the release of the CPU reset to the execution of the first instruction of the user code. Table 14-5. SAM L11 Typical Boot Timings Boot options Time to reach User Code BOOTOPT=0 2.30 ms BOOTOPT=1, BS=0x40 207 ms BOOTOPT=1, BS=0x80 409 ms BOOTOPT=2, BS=0x40 209 ms BOOTOPT=2, BS=0x80 411 ms 14.4.3 Debug Access Levels The SAM L10 has only two debug access levels (DAL): • DAL2: Highest debug level access with no restrictions in term of memory and peripheral accesses. • DAL0: No access is authorized except with a debugger using the Boot ROM Interactive mode. SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 80 The possible transitions between each debug access level are described below: Figure 14-5. SAM L10 Debug Access Levels Transitions DAL0 1) Program NVM regions 2) Send SDAL0 command (NVMCTRL) Delivered parts DAL2 ChipErase No key required After Reset The SAM L11 has three possible debug access levels (DAL): • DAL2: Highest debug level access with no restrictions in term of memory and peripheral accesses. • DAL1: Access is limited to the Non-Secure memory regions. Secure memory regions accesses are forbidden. • DAL0: No access is authorized except with a debugger using the Boot ROM Interactive mode. The possible transitions between each debug access level are described below: Figure 14-6. SAM L11 Debug Access Levels Transitions DAL0 1) Program NVM regions 2) Send SDAL0 command (NVMCTRL) DAL2 DAL1 Delivered parts 1) Program NVM regions 2) Send SDAL1 command (NVMCTRL) ChipErase_ALL with CEKEY2 key ChipErase_NS with CEKEY0 key ChipErase_S with CEKEY1 key After Reset After Reset Decreasing the Debug Level Access is done using the NVMCTRL peripheral command from the debugger or the CPU. Note:  Refer to 30. NVMCTRL – Nonvolatile Memory Controller for more information. For security reasons, increasing the Debug Level Access is only possible during Boot ROM execution and will be always preceded by a specific chip erase depending on the Debug Access Level. 14.4.4 Chip Erase The chip erase commands allow to erase memories of the device and provide secure transitions between the different Debug Access Levels. SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 81 Important:  Chip Erase commands are only issued using the Boot ROM Interactive mode (CMD_CE0, CMD_CE1, CMD_CE2 and CMD_CHIPERASE commands). For SAM L10, the chip erase command does not require a key. For SAM L11, the chip erase commands are protected with keys (CEKEYx) defined in the NVM BOCOR row. Note:  The chip erase keys can only be read if BOCOR.BCREN=1. By default, the devices are delivered with these keys set at “All 1s”. Important:  If the key is set at “All 0s”, the corresponding chip erase command is disabled and it will be impossible for the debugger to use it. The following table gives the effect of the Chip Erase commands on the different memories: Table 14-6. Chip Erase Commands Effects SAM L11 SAM L10 Boot ROM Command ChipErase_NS (CE0) ChipErase_S (CE1) ChipErase_ALL (CE2) ChipErase (CHIPERASE) Key Requirement Yes (CEKEY0) Yes (CEKEY1) Yes (CEKEY2) No Flash BOOT area BOOTPROT (BS+BNSC+BNS) No No Yes No Flash Secure APPLICATION (AS) No Yes Yes Yes Flash Non-secure APPLICATION Yes Yes Yes - Secure Data Flash (DS) No Yes Yes Yes Non-Secure Data Flash Yes Yes Yes - NVM User Row (UROW) No No Yes No NVM Boot Configuration Row (BOCOR) No No Yes No Volatile Memories Yes Yes Yes Yes Debugger Access Level after reset 2 (if DAL was 2) else 1 2 (if DAL was 2 or BS==0) else 1 2 2 Note:  Only the ChipErase_ALL (CE2) command affects rows belonging to the BOOT area (BOOTPROT fuse bits) 14.4.5 Boot ROM Interactive Mode The interactive mode allows the user to perform several actions on the device during the Boot ROM execution via a debugger connection. The debugger communicates with the device using the DSU Boot Communication Channels (BCC). This communication is bi-directional and allows the debugger to post commands and receive status from the Boot ROM. Note:  Refer to Device Service Unit for more information on BCC. SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 82 14.4.5.1 Enter Interactive Mode (CMD_INIT) This command allows launching the Boot Interactive command mode of the Boot ROM. To reach interactive mode, the debugger will trigger a “cold plugging” sequence as described in DSU chapter. Important:  Debugger must not clear DSU.STATUSA.BREXT bit before clearing DSU.STATUSA.CRSTEXT bit. When CRSTEXT is cleared, CPU starts Boot ROM Interactive mode execution. After a small delay (5ms advised), the debugger must check if the Boot ROM has not flagged any errors by checking the BCC1D bit in DSU.STATUSB register. If no error is reported, the debugger writes the CMD_INIT command to DSU.BCC0 register to request Boot ROM Interactive mode entry. When command is successful, Boot ROM will place the “SIG_COMM” status in DSU.BCC1 register. SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 83 14.4.5.1.1 CMD_INIT Figure 14-7. CMD_INIT Flow diagram Boot ROM in interactive mode Debugger idle CPU in reset Debugger triggers interactive mode entry CPU executes Boot ROM BCC1 Dev to Dbg BCC0 Dbg to Dev Boot Communication Channels Error code Sanity checks Wait for command CMD_INIT Signal command mode entry SIG_COMM Boot ROM Debugger Cold Plugging Sequence Check if error flagged after (DSU CPU (DSU CPU reset extension) 5 ms from CPU release Check status after command Debugger clears CRSTEXT If error Get command code 14.4.5.2 Exit Interactive Mode (CMD_EXIT) This command allows exiting the Boot Interactive mode. Exiting the Boot Interactive mode allows to jump to one of the following: • The Application • The CPU Park Mode SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 84 14.4.5.2.1 CMD_EXIT Figure 14-8. CMD_EXIT to APP flow diagram CPU executes application Debugger idle CPU in reset Debugger triggers exit to app CPU executes Boot ROM BCC1 Device to Dbg BCC0 Dbg to Device Boot Communication Channels Error code Sanity checks Wait for command CMD_EXIT Signal command mode entry SIG_BOOTOK Boot ROM Debugger Cold Plugging Sequence Check if error flagged after 5 ms from CPU release (DSU CPU reset extension) Check status after command Debugger clears CRSTEXT If error Debugger clears BREXT Get command code SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 85 Figure 14-9. CMD_EXIT to Park mode flow diagram CPU parked in a while loop waits for BREXT cleared Debugger idle CPU in reset Debugger triggers interactive mode entry CPU executes Boot ROM BCC1 Device to Dbg BCC0 Dbg to Device Boot Communication Channels Error code Sanity checks Wait for command CMD_EXIT Signal command mode entry SIG_BOOTOK Boot ROM Debugger NOTE : debugger does not clear BREXT before CRSTEXT Cold Plugging Sequence Check if error flagged after 5 ms from CPU release (DSU CPU reset extension Check status after command Debugger clears CRSTEXT If error Get command code 14.4.5.3 System Reset Request (CMD_RESET) This command allows resetting the system using a system reset request. Since the reset is executed immediately after receiving the command, no reply is sent to the debugger. After reset, the CPU executes the Boot ROM code from the beginning 14.4.5.4 Chip Erase (CMD_CHIPERASE) - SAM L10 only CMD_CHIPERASE command erases the entire device except BOOT area, and reverts to Debug Access Level 2. SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 86 14.4.5.4.1 CMD_CHIPERASE (SAM L10 only) Figure 14-10. CMD_CHIPERASE Flow diagram Debugger idle Debugger requests Chip Erase BCC1 Dev to Dbg BCC0 Dbg to Dev Boot Communication Channels Wait for command CMD_CHIPERASE Boot ROM Debugger Boot ROM in interactive mode SAM L10 ? Boot ROM in interactive mode SIG_CMD_VALID Erase targeted memories SIG_CMD_SUCCESS On error, one of SIG_CE_x is reported Debugger polls for status update on BCC1 Get data Get command code 14.4.5.5 Chip Erase (CMD_CEx) - SAM L11 only CMD_CEx commands are used to erase specific part of the device and to increase the Debug Access Level. SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 87 14.4.5.5.1 CMD_CEx (SAM L11 only) Figure 14-11. CMD_CEx Flow diagram Debugger idle Debugger requests Chip Erase 0 / 1 / 2 BCC1 Dev to Dbg BCC0 Dbg to Dev Boot Communication Channels Wait for command CMD_CEx Get 128 bits key as 4x32bits words CEx_Keyword0 Boot ROM Debugger Boot ROM in interactive mode SAML11 ? CEx_Keyword1 CEx_Keyword2 CEx_Keyword3 Boot ROM in interactive mode Verify key SIG_CMD_VALID NOTE : debugger polls the BCC0D bit to know when bootrom has read the word before sending the next ChipErase_x disabled? SIG_CMD_INVALID Key matches BOCOR key? SIG_CMD_BADKEY NOTE : a 100us delay is inserted before sending BADKEY status Erase targeted memories SIG_CMD_SUCCESS On error, one of SIG_CE_x is reported Debugger polls for status update on BCC1 Get data Get command code Get keyword 0 Get keyword 3 Get keyword 1 Get keyword 2 Ce disabled Ce not disabled keys don't match Keys match 14.4.5.6 NVM Memory Regions Integrity Checks (CMD_CRC) The Boot ROM provides a way to check the integrity of the embedded non-volatile memories which may be of interest in case of a failure analysis. This requires the user to place tables describing the memory area to be checked with their expected CRC values. Note:  During this integrity check process, the debugger sends the CRC table address to the device. SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 88 Important:  The table(s) must be programmed by the programming tool in addition to the application binaries. 14.4.5.6.1 CRC Table format Table 14-7. CRC Table Fields Description Description Header Start Address (1) Size in bytes (2) Expected value (3) Field HDR ADDR SIZE REFVAL Offset 0x0 0x4 0x8 0xC Value 0x43524349 0x00000000 0x100 0xAABBCCDD Note 1: ADDR must be a multiple of 4 (Only ADDR[31:2] are used). Note 2: SIZE must be a multiple of 4 (Only SIZE[31:2] are used). Note 3: The expected value is the computed CRC32 value of the memory target. 14.4.5.6.2 Requirements • Each table occupies 16 bytes in memory. • The table must start at a 16byte aligned address. (i.e. 0xXXXXXXX0) • The table must be placed in the same memory region as its target memory range. (i.e. a table placed in the Secure APPLICATION region can only target Secure APPLICATION memory addresses). Note: There are two exceptions to this rule: • For SAM L10: all non-volatile memories are considered as a single region (e.g. a table located in Data Flash can target main array) • For SAM L11: ANSC and BNSC regions are considered to belong to the same region as their “parent” region: AS for ANSC and BS for BNSC. 14.4.5.6.3 CRC Command Key The CRC command (CMD_ CRC) requires an access key (CRCKEY) which is in the NVM BOCOR row at: [0x80C040:0x80C04F]: BOCOR Offset Bit Position Name 0x40-0x4F 639:512 CRCKEY Just like the ChipErase keys, the key can be set to all 0s to prevent any access to the command. SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 89 14.4.5.6.4 CMD_CRC Figure 14-12. CMD_CRC Flow diagram Debugger idle Debugger requests CRC of a table BCC1 Dev to Dbg BCC0 Dbg to Dev Boot Communication Channels Wait for command CMD_CRC Get 128 bits key as 4x32bits words CRC_Keyword0 Boot ROM Debugger Boot ROM in interactive mode Internal checks CRC_Keyword1 CRC_Keyword2 CRC_Keyword3 Boot ROM in interactive mode Verify key SIG_CMD_VALID NOTE : debugger polls the BCC0D bit to know when Boot ROM has read the word before sending the next CRC command disabled? SIG_CMD_INVALID Key matches BOCOR key? SIG_CMD_BADKEY NOTE : a 100us delay is inserted before sending BADKEY status Signal crc start SIG_CMD_VALID Debugger polls for status update on BCC1 Process CRC table SIG_CMD_BADTBL Check CRC of target area SIG_CMD_SUCCESS SIG_CMD_FAIL Debugger polls for status update on BCC1 Wait for table address CRC Table Address Send CRC table address Get data Get command code Get keyword 0 Get keyword 3 Get keyword 1 Get keyword 2 Crc disabled Crc not disabled keys don't match Keys match Read Status Table incorrect Crc ok Crc fail Read Status Get table address SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 90 14.4.5.7 Random Session Key Generation (CMD_DCEK) - SAM L11 only This command allows using a challenge-response scheme to prevent exposure of the keys in clear text on the debugger communication lines. The different keys sent by the debugger during the Boot ROM for Chip Erase (CMD_CEx) and CRC (CMD_CRC) commands execution are: • CRCKEY for CMD_CRC command • CEKEYx for CMD_CEx commands Note:  The CMD_DCEK command has no effect on the SAM L10, the key derivation will not be enabled. The random challenge value is generated using the TRNG of the device. It is generated once the CMD_DCEK is received and communicated to the debugger. The next CMD_CEx or CMD_CRC commands will expect the key value to be replaced by the computed response corresponding to the challenge. The challenge value is valid only for the next CMD_CEx/ CMD_CRC command. Before sending a new CMD_CEx/ CMD_CRC command, a CMD_DCEK shall be used to re-enable the challenge-response scheme a get a new challenge value. On the debugger side, the response shall be computed using the following algorithm: Figure 14-13. Debugger Algorithm Where KeyIndex is: • 0 for ChipErase_NS • 1 for ChipErase_S • 2 for ChipErase_ALL • 3 for CRC Command Note:  SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 91 • HMAC is described in FIPS PUB 198-1. • The hash used for HMAC is SHA256. • The output of the HMAC-SHA256 is truncated to obtain an HMAC-SHA256-128 as explained in RFC4868. 14.4.5.7.1 CMD_DCEK (SAM L11 only) Figure 14-14. CMD_DCEK Flow diagram Debugger idle Debugger requests key derivation BCC1 Dev to Dbg BCC0 Dbg to Dev Boot Communication Channels Wait for command CMD_DCEK Send 128 bits random number as 4x32bits words RandomDat0 Boot ROM Debugger Boot ROM in interactive mode Generate random data RandomDat1 RandomDat2 RandomDat3 Boot ROM in interactive mode Set key derivation on Set key derivation on Get data Get data Get data Get data Get command code 14.4.5.8 NVM Rows Content Checks (CMD_RAUX) The Boot ROM provides a way to check the content of the NVM rows. When device is secured (DAL0), the fuse configuration can still be read by the debugger using the Read Auxiliary command (CMD_RAUX). SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 92 The following areas are accessible: Table 14-8. Accessible Memory Range by Read Auxiliary Row Command Area Start address End address User row (UROW) 0x00804000 0x0080401F Software Calibration row 0x00806020 0x0080602F Temperature Log row 0x00806038 0x0080603F Boot Configuration row (BOCOR) 0x0080C000 0x0080C0FF 14.4.5.8.1 CMD_RAUX Figure 14-15. CMD_RAUX Flow diagram Debugger idle Debugger requests a word in AUX address space BCC1 Dev to Dbg BCC0 Dbg to Dev Boot Communication Channels Wait for command CMD_RAUX Boot ROM Debugger Boot ROM in interactive mode Address in allowed range ? Boot ROM in interactive mode Send value DATA_VALUE Debugger polls for status update on BCC1 SIG_ARG_VALID Wait for address Target Address Wait for address Debugger exits read loop out of range Address (eg 0x0) Address in allowed range ? SIG_ARG_INVALID Debugger polls for status update on BCC1 Get status Get command code Get Value Yes Get address No Get status Note: After the CMD_RAUX is sent, the debugger can read multiple data, the read loop is exit when an out of range address is sent. SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 93 14.4.5.9 Boot Interactive Mode Commands Table 14-9. Boot Interactive Mode Commands Command Name Description Command prefix Command CMD_INIT Entering Interactive Mode 0x444247 55 CMD_EXIT Exit Interactive Mode 0x444247 AA CMD_RESET System Reset Request 0x444247 52 CMD_CE0 ChipErase_NS for SAM L11 0x444247 E0 CMD_CE1 ChipErase_S for SAM L11 0x444247 E1 CMD_CE2 ChipErase_ALL for SAM L11 0x444247 E2 CMD_CHIPERASE ChipErase for SAM L10 0x444247 E3 CMD_CRC NVM Memory Regions Integrity Checks 0x444247 C0 CMD_DCEK Random Session Key Generation for SAM L11 0x444247 44 CMD_RAUX NVM Rows Integrity Checks 0x444247 4C 14.4.5.10 Boot Interactive Mode Status Table 14-10. Boot Interactive Mode Status Status Name Description Status prefix Status coding SIG_NO No Error 0xEC0000 00 SIG_SAN_FFF Fresh from factory error 0xEC0000 10 SIG_SAN_UROW UROW checksum error 0xEC0000 11 SIG_SAN_SECEN SECEN parameter error 0xEC0000 12 SIG_SAN_BOCOR BOCOR checksum error 0xEC0000 13 SIG_SAN_BOOTPROT BOOTPROT parameter error 0xEC0000 14 SIG_SAN_NOSECREG No secure register parameter error 0xEC0000 15 SIG_COMM Debugger start communication command 0xEC0000 20 SIG_CMD_SUCCESS Debugger command success 0xEC0000 21 SIG_CMD_FAIL Debugger command fail 0xEC0000 22 SIG_CMD_BADKEY Debugger bad key 0xEC0000 23 SIG_CMD_VALID Valid command 0xEC0000 24 SIG_CMD_INVALID Invalid command 0xEC0000 25 SIG_ARG_VALID Valid argument 0xEC0000 26 SIG_ARG_INVALID Invalid argument 0xEC0000 27 SIG_CE_CVM Chip erase error: CVM 0xEC0000 30 SIG_CE_ARRAY_ERASEFAIL Chip erase error: array erase fail 0xEC0000 31 SIG_CE_ARRAY_NVME Chip erase error: array NVME 0xEC0000 32 SIG_CE_DATA_ERASEFAIL Chip erase error: data erase fail 0xEC0000 33 SIG_CE_DATA_NVME Chip erase error: data NVME 0xEC0000 34 SIG_CE_BCUR Chip erase error: BOCOR, UROW 0xEC0000 35 SIG_CE_BC Chip erase error: BC check 0xEC0000 36 SIG_BOOT_OPT BOOTOPT parameter error 0xEC0000 40 SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 94 Status Name Description Status prefix Status coding SIG_BOOT_ERR Boot image hash verify fail 0xEC0000 41 SIG_BOCOR_HASH BOCOR hash error 0xEC0000 42 SIG_CRC_BADTBL Bad CRC table 0xEC0000 50 SIG_SECEN0_ERR PAC or IDAU cfg check failure 0xEC0000 60 SIG_SECEN1_ERR PAC or IDAU cfg check failure 0xEC0000 61 SIG_EXIT_ERR Exit: BC or check error 0xEC0000 70 SIG_HARDFAULT Hardfault error 0xEC0000 F0 SIG_BOOTOK Boot ROM ok to exit 0xEC0000 39 14.4.6 CPU Park mode This mode allows the debugger to get access to the resources of the device during Boot ROM execution while the CPU is trapped in a while loop. The debug access level when entering that mode corresponds to the DAL value which is programmed in the device. Important:  This mode is the recommended way to enter a debugging session in a safe way even if it is also possible to launch a debug session when the application is running. This mode is reached by sending the Exit command (CMD_EXIT) without clearing the DSU.STATUSA.BREXT bit to the Boot ROM. As soon as the BREXT bit is cleared, the device exits this state and performs a system reset. At this point, the MPU is still enabled and prevents software execution elsewhere than in Boot ROM region. If the host needs to run software on the device, MPU shall be disabled by accessing the Cortex-M23 MPU CTRL register with the debugger. SAM L10/L11 Family Boot ROM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 95 15. PAC - Peripheral Access Controller 15.1 Overview The Peripheral Access Controller provides an interface for the locking and unlocking and for managing security attribution of peripheral registers within the device. It reports all violations that could happen when accessing a peripheral: write protected access, illegal access, enable protected access, access when clock synchronization or software reset is on-going. These errors are reported in a unique interrupt flag for a peripheral. The PAC module also reports errors occurring at the slave bus level, when an access to a non-existing address is detected. 15.2 Features • Manages write protection access and reports access errors for the peripheral modules or bridges. • Manages security attribution for the peripheral modules (SAM L11) 15.3 Block Diagram Figure 15-1. PAC Block Diagram INTFLAG PERIPHERAL m PERIPHERAL 0 BUSn BUS0 Peripheral ERROR Peripheral ERROR WRITE CONTROL WRITE CONTROL PAC CONTROL PERIPHERAL m PERIPHERAL 0 SLAVEs PAC IRQ APB Slave ERROR 15.4 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 15.4.1 IO Lines Not applicable. 15.4.2 Power Management The PAC can continue to operate in any Sleep mode where the selected source clock is running. The PAC interrupts can be used to wake up the device from Sleep modes. The events can trigger other operations in the system without exiting sleep modes. SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 96 Related Links 22. PM – Power Manager 15.4.3 Clocks The PAC bus clock (CLK_PAC_APB) can be enabled and disabled in the Main Clock module. The default state of CLK_PAC_APB can be found in the related links. Related Links 19. MCLK – Main Clock 19.6.2.6 Peripheral Clock Masking 15.4.4 DMA Not applicable. 15.4.5 Interrupts The interrupt request line is connected to the Interrupt Controller. Using the PAC interrupt requires the Interrupt Controller to be configured first. Table 15-1. Interrupt Lines Instances NVIC Line PAC ERR 15.4.6 Events The events are connected to the Event System, which may need configuration. Related Links 33. EVSYS – Event System 15.4.7 Debug Operation When the CPU is halted in Debug mode, write protection of all peripherals is disabled and the PAC continues normal operation. 15.4.8 Register Access Protection All registers with write-access can be write-protected optionally by the Peripheral Access Controller (PAC), except for the following registers: • Write Control (WRCTRL) register • AHB Slave Bus Interrupt Flag Status and Clear (INTFLAGAHB) register • Peripheral Interrupt Flag Status and Clear n (INTFLAG A/B/C...) registers Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. PAC write-protection does not apply to accesses through an external debugger. 15.4.9 SAM L11 TrustZone Specific Register Access Protection All PAC registers can only be accessed in the secure alias, with the following exceptions: • Write Control (WRCTRL) register is also accessible in the Non-Secure Alias, but only for write protection requests on non-secured peripherals. • Peripheral Write Protection Status (STATUSn) registers are also accessible in the Non-Secure Alias, but they will only report information on non-secured peripherals. SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 97 Note:  Refer to the Mix-Secure Peripherals section in the SAM L11 Security Features chapter for more information. 15.5 Functional Description 15.5.1 Principle of Operation The Peripheral Access Control module allows the user to set a write protection or security attribution on peripheral modules and generate an interrupt in case of a peripheral access violation. The peripheral’s protection can be set, cleared or locked at the user discretion. A set of Interrupt Flag and Status registers informs the user on the status of the violation in the peripherals. In addition, slaves bus errors can be also reported in the cases where reserved area is accessed by the application. 15.5.2 Basic Operation 15.5.2.1 Initialization After reset, the PAC is enabled. 15.5.2.2 Initialization, Enabling and Resetting The PAC is always enabled after reset. Only a hardware reset will reset the PAC module. 15.5.2.3 Operations The PAC module allows the user to set, clear or lock the write protection status and security attribution of all peripherals on all Peripheral Bridges. If a peripheral register violation occurs, the Peripheral Interrupt Flag n registers (INTFLAGn) are updated to inform the user on the status of the violation in the peripherals connected to the Peripheral Bridge n (n = A,B,C ...). The corresponding Peripheral Write Control Status n register (STATUSn) gives the state of the write protection for all peripherals connected to the corresponding Peripheral Bridge n. The corresponding Peripheral Non-Secure Status n register (NONSECn) gives the state of the security attribution for all peripherals connected to the corresponding Peripheral Bridge n. Refer to 15.5.2.4 Peripheral Access Errors for details. The PAC module also report the errors occurring at slave bus level when an access to reserved area is detected. AHB Slave Bus Interrupt Flag register (INTFLAGAHB) informs the user on the status of the violation in the corresponding slave. Refer to the 15.5.2.9 AHB Slave Bus Errors for details. 15.5.2.4 Peripheral Access Errors The following events will generate a Peripheral Access Error: • Protected write: To avoid unexpected writes to a peripheral's registers, each peripheral can be write protected. Only the registers denoted as “PAC Write-Protection” in the module’s datasheet can be protected. If a peripheral is not write protected, write data accesses are performed normally. If a peripheral is write protected and if a write access is attempted, data will not be written and peripheral returns an access error. The corresponding interrupt flag bit in the INTFLAGn register will be set. • Illegal access: Access to an unimplemented register within the module. • Synchronized write error: For write-synchronized registers an error will be reported if the register is written while a synchronization is ongoing. When any of the INTFLAGn registers bit are set, an interrupt will be requested if the PAC interrupt enable bit is set. SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 98 15.5.2.5 Write Access Protection Management Peripheral access control can be enabled or disabled by writing to the WRCTRL register. The data written to the WRCTRL register is composed of two fields; WRCTRL.PERID and WRCTRL.KEY. The WRCTRL.PERID is an unique identifier corresponding to a peripheral. The WRCTRL.KEY is a key value that defines the operation to be done on the control access bit. These operations can be “clear protection”, “set protection” and “set and lock protection bit”. The “clear protection” operation will remove the write access protection for the peripheral selected by WRCTRL.PERID. Write accesses are allowed for the registers in this peripheral. The “set protection” operation will set the write access protection for the peripheral selected by WRCTRL.PERID. Write accesses are not allowed for the registers with write protection property in this peripheral. The “set and lock protection” operation will set the write access protection for the peripheral selected by WRCTRL.PERID and locks the access rights of the selected peripheral registers. The write access protection will only be cleared by a hardware reset. The peripheral access control status can be read from the corresponding STATUSn register. 15.5.2.6 Write Access Protection Management Errors Only word-wise writes to the WRCTRL register will effectively change the access protection. Other type of accesses will have no effect and will cause a PAC write access error. This error is reported in the INTFLAGn.PAC bit corresponding to the PAC module. PAC also offers an additional safety feature for correct program execution with an interrupt generated on double write clear protection or double write set protection. If a peripheral is write protected and a subsequent set protection operation is detected then the PAC returns an error, and similarly for a double clear protection operation. In addition, an error is generated when writing a “set and lock” protection to a write-protected peripheral or when a write access is done to a locked set protection. This can be used to ensure that the application follows the intended program flow by always following a write protect with an unprotect and conversely. However in applications where a write protected peripheral is used in several contexts, e.g. interrupt, care should be taken so that either the interrupt can not happen while the main application or other interrupt levels manipulates the write protection status or when the interrupt handler needs to unprotect the peripheral based on the current protection status by reading the STATUS register. The errors generated while accessing the PAC module registers (eg. key error, double protect error...) will set the INTFLAGn.PAC flag. 15.5.2.7 SAM L11 Security Attribution Management The peripheral security attribution status can be read from the corresponding NONSECn register. 15.5.2.8 SAM L11 Security Attribution Management Errors The errors generated while accessing the PAC module registers (e.g., key error, double protect error...) will set the INTFLAGn.PAC flag. 15.5.2.9 AHB Slave Bus Errors The PAC module reports errors occurring at the AHB Slave bus level. These errors are generated when an access is performed at an address where no slave (bridge or peripheral) is mapped or where nonsecure accesses are prohibited. These errors are reported in the corresponding bits of the INTFLAGAHB register. SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 99 15.5.2.10 Generating Events The PAC module can also generate an event when any of the Interrupt Flag registers bit are set. To enable the PAC event generation, the control bit EVCTRL.ERREO must be set a '1'. 15.5.3 DMA Operation Not applicable. 15.5.4 Interrupts The PAC has the following interrupt source: • Error (ERR): Indicates that a peripheral access violation occurred in one of the peripherals controlled by the PAC module, or a bridge error occurred in one of the bridges reported by the PAC – This interrupt is a synchronous wake-up source. Each interrupt source has an interrupt flag associated with it. The interrupt flag in the Interrupt Flag Status and Clear (INTFLAGAHB and INTFLAGn) registers is set when the interrupt condition occurs. Each interrupt can be individually enabled by writing a '1' to the corresponding bit in the Interrupt Enable Set (INTENSET) register, and disabled by writing a '1' to the corresponding bit in the Interrupt Enable Clear (INTENCLR) register. An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until the interrupt flag is cleared, the interrupt is disabled, or the PAC is reset. All interrupt requests from the peripheral are ORed together on system level to generate one combined interrupt request to the NVIC. The user must read the INTFLAGAHB and INTFLAGn registers to determine which interrupt condition is present. Note that interrupts must be globally enabled for interrupt requests to be generated. Related Links 22.6.3.3 Sleep Mode Controller 15.5.5 Events The PAC can generate the following output event: • Error (ERR): Generated when one of the interrupt flag registers bits is set Writing a '1' to an Event Output bit in the Event Control Register (EVCTRL.ERREO) enables the corresponding output event. Writing a '0' to this bit disables the corresponding output event. 15.5.6 Sleep Mode Operation In Sleep mode, the PAC is kept enabled if an available bus master (CPU, DMA) is running. The PAC will continue to catch access errors from the module and generate interrupts or events. 15.5.7 SAM L11 Secure and Non-Secure Read/Write Accesses Non-Secure write to EVCTRL, INTENCLR, INTENSET, INTFLAGAHB, INTFLAGx, and NONSECx registers is prohibited. Non-Secure read to EVCTRL, INTENCLR, INTENSET, INTFLAGAHB, and INTFLAGx registers will return zero with no error resulting. Non-secure write to a bit of STATUSx registers (by writing to the WRCTRL register) is prohibited if the corresponding bit in NONSECx is zero. STATUSx bits relating to secure peripherals (i.e., the corresponding bits in NONSECx are zero), read as zero in Non-Secure mode, with no error resulting. SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 100 15.5.8 Synchronization Not applicable. SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 101 15.6 Register Summary Important:  For SAM L11, the PAC register map is automatically duplicated in a Secure and Non-Secure alias: • The Non-Secure alias is at the peripheral base address • The Secure alias is located at the peripheral base address + 0x200 Refer to Mix-Secure Peripherals for more information on register access rights Offset Name Bit Pos. 0x00 WRCTRL 7:0 PERID[7:0] 15:8 PERID[15:8] 23:16 KEY[7:0] 31:24 0x04 EVCTRL 7:0 ERREO 0x05 ... 0x07 Reserved 0x08 INTENCLR 7:0 ERR 0x09 INTENSET 7:0 ERR 0x0A ... 0x0F Reserved 0x10 INTFLAGAHB 7:0 BROM HSRAMDSU HSRAMDMA C HSRAMCPU HPB2 HPB1 HPB0 FLASH 15:8 23:16 31:24 0x14 INTFLAGA 7:0 GCLK SUPC OSC32KCTR L OSCCTRL RSTC MCLK PM PAC 15:8 AC PORT FREQM EIC RTC WDT 23:16 31:24 0x18 INTFLAGB 7:0 Reserved DMAC NVMCTRL DSU IDAU 15:8 23:16 31:24 0x1C INTFLAGC 7:0 ADC TC2 TC1 TC0 SERCOM2 SERCOM1 SERCOM0 EVSYS 15:8 TRAM OPAMP CCL TRNG PTC DAC 23:16 31:24 0x20 ... 0x33 Reserved SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 102 Offset Name Bit Pos. 0x34 STATUSA 7:0 GCLK SUPC OSC32KCTR L OSCCTRL RSTC MCLK PM PAC 15:8 AC PORT FREQM EIC RTC WDT 23:16 31:24 0x38 STATUSB 7:0 Reserved DMAC NVMCTRL DSU IDAU 15:8 23:16 31:24 0x3C STATUSC 7:0 ADC TC2 TC1 TC0 SERCOM2 SERCOM1 SERCOM0 EVSYS 15:8 TRAM OPAMP CCL TRNG PTC DAC 23:16 31:24 0x40 ... 0x53 Reserved 0x54 NONSECA 7:0 GCLK SUPC OSC32KCTR L OSCCTRL RSTC MCLK PM PAC 15:8 AC PORT FREQM EIC RTC WDT 23:16 31:24 0x58 NONSECB 7:0 HMATRIXHS DMAC NVMCTRL DSU IDAU 15:8 23:16 31:24 0x5C NONSECC 7:0 ADC TC2 TC1 TC0 SERCOM2 SERCOM1 SERCOM0 EVSYS 15:8 TRAM OPAMP CCL TRNG PTC DAC 23:16 31:24 15.7 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to the related links. On SAM L11 devices, the Mix-Secure peripheral has different types of registers (Non-Secure, Secure, Write-Secure, Mix-Secure, and Write-Mix-Secure) with different access permissions for each bitfield. Refer to Mix-Secure Peripherals for more details. In the following register descriptions, the access permissions are specified as shown in the following figure. SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 103 Bit 7 6 5 4 3 2 1 0 CMD[7:0] Access R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW TrustZone Non-Protected Devices Access TrustZone Protected Devices Non-Secure Access TrustZone Protected Devices Secure Access SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 104 15.7.1 Write Control Name:  WRCTRL Offset:  0x00 Reset:  0x00000000 Property:  – Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 KEY[7:0] Access RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 PERID[15:8] Access RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 PERID[7:0] Access RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW Reset 0 0 0 0 0 0 0 0 Bits 23:16 – KEY[7:0] Peripheral Access Control Key These bits define the peripheral access control key: Value Name Description 0x0 OFF No action 0x1 CLEAR Clear the peripheral write control 0x2 SET Set the peripheral write control 0x3 LOCK Set and lock the peripheral write control until the next hardware reset Bits 15:0 – PERID[15:0] Peripheral Identifier The PERID represents the peripheral whose control is changed using the WRCTRL.KEY. The Peripheral Identifier is calculated by the following formula: ܲܧܴܦܫ = 32* BridgeNumber + N Where BridgeNumber represents the Peripheral Bridge Number (0 for Peripheral Bridge A, 1 for Peripheral Bridge B, etc.). N represents the peripheral index from the respective Peripheral Bridge Number, which can be retrieved in the Peripherals Configuration Summary table: SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 105 Table 15-2. PERID Values Peripheral Bridge Name BridgeNumber PERID Values A 0 0+N B 1 32+N C 2 64+N SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 106 15.7.2 Event Control Name:  EVCTRL Offset:  0x04 Reset:  0x00 Property:  Secure Bit 7 6 5 4 3 2 1 0 ERREO Access RW/-/RW Reset 0 Bit 0 – ERREO Peripheral Access Error Event Output This bit indicates if the Peripheral Access Error Event Output is enabled or disabled. When enabled, an event will be generated when one of the interrupt flag registers bits (INTFLAGAHB, INTFLAGn) is set: Value Description 0 Peripheral Access Error Event Output is disabled. 1 Peripheral Access Error Event Output is enabled. SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 107 15.7.3 Interrupt Enable Clear Name:  INTENCLR Offset:  0x08 Reset:  0x00 Property:  PAC Write-Protection, Secure This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 7 6 5 4 3 2 1 0 ERR Access RW/-/RW Reset 0 Bit 0 – ERR Peripheral Access Error Interrupt Disable This bit indicates that the Peripheral Access Error Interrupt is enabled and an interrupt request will be generated when one of the interrupt flag registers bits (INTFLAGAHB, INTFLAGn) is set: Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Peripheral Access Error interrupt Enable bit and disables the corresponding interrupt request. Value Description 0 Peripheral Access Error interrupt is disabled. 1 Peripheral Access Error interrupt is enabled. SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 108 15.7.4 Interrupt Enable Set Name:  INTENSET Offset:  0x09 Reset:  0x00 Property:  PAC Write-Protection, Secure This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENCLR). Bit 7 6 5 4 3 2 1 0 ERR Access RW/-/RW Reset 0 Bit 0 – ERR Peripheral Access Error Interrupt Enable This bit indicates that the Peripheral Access Error Interrupt is enabled and an interrupt request will be generated when one of the interrupt flag registers bits (INTFLAGAHB, INTFLAGn) is set: Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Peripheral Access Error interrupt Enable bit and enables the corresponding interrupt request. Value Description 0 Peripheral Access Error interrupt is disabled. 1 Peripheral Access Error interrupt is enabled. SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 109 15.7.5 AHB Slave Bus Interrupt Flag Status and Clear Name:  INTFLAGAHB Offset:  0x10 Reset:  0x000000 Property:  Secure This flag is cleared by writing a '1' to the flag. This flag is set when an access error is detected by the SLAVE n, and will generate an interrupt request if INTENCLR/SET.ERR is '1'. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the corresponding INTFLAGAHB interrupt flag. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 BROM HSRAMDSU HSRAMDMAC HSRAMCPU HPB2 HPB1 HPB0 FLASH Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 0 0 0 Bit 7 – BROM Interrupt Flag for Boot ROM Bit 6 – HSRAMDSU Interrupt Flag for SLAVE HS SRAM Port 2 - DSU Access Bit 5 – HSRAMDMAC Interrupt Flag for SLAVE HS SRAM Port 1 - DMAC Access Bit 4 – HSRAMCPU Interrupt Flag for SLAVE HS SRAM Port 0 - CPU Access Bit 3 – HPB2 Interrupt Flag for SLAVE AHB-APB Bridge C Bit 2 – HPB1 Interrupt Flag for SLAVE AHB-APB Bridge B Bit 1 – HPB0 Interrupt Flag for SLAVE AHB-APB Bridge A Bit 0 – FLASH Interrupt Flag for SLAVE FLASH SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 110 15.7.6 Peripheral Interrupt Flag Status and Clear A Name:  INTFLAGA Offset:  0x14 Reset:  0x000000 Property:  Secure This flag is cleared by writing a one to the flag. This flag is set when a Peripheral Access Error occurs while accessing the peripheral associated with the respective INTFLAGA bit, and will generate an interrupt request if INTENCLR/SET.ERR is one. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the corresponding INTFLAGA interrupt flag. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 AC PORT FREQM EIC RTC WDT Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 GCLK SUPC OSC32KCTRL OSCCTRL RSTC MCLK PM PAC Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 0 0 0 Bit 13 – AC Interrupt Flag for AC Bit 12 – PORT Interrupt Flag for PORT Bit 11 – FREQM Interrupt Flag for FREQM Bit 10 – EIC Interrupt Flag for EIC Bit 9 – RTC Interrupt Flag for RTC Bit 8 – WDT Interrupt Flag for WDT Bit 7 – GCLK Interrupt Flag for GCLK Bit 6 – SUPC Interrupt Flag for SUPC SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 111 Bit 5 – OSC32KCTRL Interrupt Flag for OSC32KCTRL Bit 4 – OSCCTRL Interrupt Flag for OSCCTRL Bit 3 – RSTC Interrupt Flag for RSTC Bit 2 – MCLK Interrupt Flag for MCLK Bit 1 – PM Interrupt Flag for PM Bit 0 – PAC Interrupt Flag for PAC SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 112 15.7.7 Peripheral Interrupt Flag Status and Clear B Name:  INTFLAGB Offset:  0x18 Reset:  0x000000 Property:  Secure This flag is cleared by writing a '1' to the flag. This flag is set when a Peripheral Access Error occurs while accessing the peripheral associated with the respective INTFLAGB bit, and will generate an interrupt request if INTENCLR/SET.ERR is '1'. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the corresponding INTFLAGB interrupt flag. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 Reserved DMAC NVMCTRL DSU IDAU Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 Bit 4 – Reserved Reserved Bit 3 – DMAC Interrupt Flag for DMAC Bit 2 – NVMCTRL Interrupt Flag for NVMCTRL Bit 1 – DSU Interrupt Flag for DSU Bit 0 – IDAU Interrupt Flag for IDAU SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 113 15.7.8 Peripheral Interrupt Flag Status and Clear C Name:  INTFLAGC Offset:  0x1C Reset:  0x000000 Property:  Secure This flag is cleared by writing a one to the flag. This flag is set when a Peripheral Access Error occurs while accessing the peripheral associated with the respective INTFLAGC bit, and will generate an interrupt request if INTENCLR/SET.ERR is one. Writing a zero to this bit has no effect. Writing a one to this bit will clear the corresponding INTFLAGC interrupt flag. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 TRAM OPAMP CCL TRNG PTC DAC Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 ADC TC2 TC1 TC0 SERCOM2 SERCOM1 SERCOM0 EVSYS Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 0 0 0 Bit 13 – TRAM Interrupt Flag for TRAM Bit 12 – OPAMP Interrupt Flag for OPAMP Bit 11 – CCL Interrupt Flag for CCL Bit 10 – TRNG Interrupt Flag for TRNG Bit 9 – PTC Interrupt Flag for PTC Bit 8 – DAC Interrupt Flag for DAC Bit 7 – ADC Interrupt Flag for ADC Bits 4, 5, 6 – TC Interrupt Flag for TCn [n = 2..0] SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 114 Bits 1, 2, 3 – SERCOM Interrupt Flag for SERCOMn [n = 2..0] Bit 0 – EVSYS Interrupt Flag for EVSYS SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 115 15.7.9 Peripheral Write Protection Status A Name:  STATUSA Offset:  0x34 Reset:  0x000000 Property:  Mix-Secure Reading STATUSA register returns peripheral write protection status: Value Description 0 Peripheral is not write protected. 1 Peripheral is write protected. Important:  For SAM L11 Non-Secure accesses, read accesses (R*) are allowed only if the peripheral security attribution for the corresponding peripheral is set as Non-Secured in the NONSECx register. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 AC PORT FREQM EIC RTC WDT Access R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R Reset 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 GCLK SUPC OSC32KCTRL OSCCTRL RSTC MCLK PM PAC Access R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R Reset 0 0 0 0 0 0 0 0 Bit 13 – AC Peripheral AC Write Protection Status Bit 12 – PORT Peripheral PORT Write Protection Status Bit 11 – FREQM Peripheral FREQM Write Protection Status Bit 10 – EIC Peripheral EIC Write Protection Status Bit 9 – RTC Peripheral RTC Write Protection Status SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 116 Bit 8 – WDT Peripheral WDT Write Protection Status Bit 7 – GCLK Peripheral GCLK Write Protection Status Bit 6 – SUPC Peripheral SUPC Write Protection Status Bit 5 – OSC32KCTRL Peripheral OSC32KCTRL Write Protection Status Bit 4 – OSCCTRL Peripheral OSCCTRL Write Protection Status Bit 3 – RSTC Peripheral RSTC Write Protection Status Bit 2 – MCLK Peripheral MCLK Write Protection Status Bit 1 – PM Peripheral PM Write Protection Status Bit 0 – PAC Peripheral PAC Write Protection Status SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 117 15.7.10 Peripheral Write Protection Status B Name:  STATUSB Offset:  0x38 Reset:  0x000000 Property:  Mix-Secure Reading the STATUSB register returns the peripheral write protection status: Value Description 0 Peripheral is not write protected. 1 Peripheral is write protected. Important:  For SAM L11 Non-Secure accesses, read accesses (R*) are allowed only if the peripheral security attribution for the corresponding peripheral is set as Non-Secured in the NONSECx register. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 Reserved DMAC NVMCTRL DSU IDAU Access R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R Reset 0 0 0 0 0 Bit 4 – Reserved Reserved Bit 3 – DMAC Peripheral DMAC Write Protection Status Bit 2 – NVMCTRL Peripheral NVMCTRL Write Protection Status Bit 1 – DSU Peripheral DSU Write Protection Status Bit 0 – IDAU Peripheral IDAU Write Protection Status SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 118 15.7.11 Peripheral Write Protection Status C Name:  STATUSC Offset:  0x3C Reset:  0x000000 Property:  Mix-Secure Reading the STATUSC register returns the peripheral write protection status: Value Description 0 Peripheral is not write protected. 1 Peripheral is write protected. Important:  For SAM L11 Non-Secure accesses, read accesses (R*) are allowed only if the peripheral security attribution for the corresponding peripheral is set as Non-Secured in the NONSECx register. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 TRAM OPAMP CCL TRNG PTC DAC Access R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R Reset 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 ADC TC2 TC1 TC0 SERCOM2 SERCOM1 SERCOM0 EVSYS Access R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R Reset 0 0 0 0 0 0 0 0 Bit 13 – TRAM Peripheral TRAM Write Protection Status Bit 12 – OPAMP Peripheral OPAMP Write Protection Status Bit 11 – CCL Peripheral CCL Write Protection Status Bit 10 – TRNG Peripheral TRNG Write Protection Status Bit 9 – PTC Peripheral PTC Write Protection Status SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 119 Bit 8 – DAC Peripheral DAC Write Protection Status Bit 7 – ADC Peripheral ADC Write Protection Status Bits 4, 5, 6 – TC Peripheral TCn Write Protection Status [n = 2..0] Bits 1, 2, 3 – SERCOM Peripheral SERCOMn Write Protection Status [n = 2..0] Bit 0 – EVSYS Peripheral EVSYS Write Protection Status SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 120 15.7.12 Peripheral Non-Secure Status - Bridge A Name:  NONSECA Offset:  0x54 Reset:  x initially determined from NVM User Row after reset Property:  Write-Secure Important:  This register is only available for SAM L11 and has no effect for SAM L10. Reading NONSEC register returns peripheral security attribution status: Value Description 0 Peripheral is secured. 1 Peripheral is non-secured. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 AC PORT FREQM EIC RTC WDT Access R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R Reset x x x x x x Bit 7 6 5 4 3 2 1 0 GCLK SUPC OSC32KCTRL OSCCTRL RSTC MCLK PM PAC Access R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R Reset x x x x x x x 0 Bit 13 – AC Peripheral AC Non-Secure Bit 12 – PORT Peripheral PORT Non-Secure Bit 11 – FREQM Peripheral FREQM Non-Secure Bit 10 – EIC Peripheral EIC Non-Secure Bit 9 – RTC Peripheral RTC Non-Secure SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 121 Bit 8 – WDT Peripheral WDT Non-Secure Bit 7 – GCLK Peripheral GCLK Non-Secure Bit 6 – SUPC Peripheral SUPC Non-Secure Bit 5 – OSC32KCTRL Peripheral OSC32KCTRL Non-Secure Bit 4 – OSCCTRL Peripheral OSCCTRL Non-Secure Bit 3 – RSTC Peripheral RSTC Non-Secure Bit 2 – MCLK Peripheral MCLK Non-Secure Bit 1 – PM Peripheral PM Non-Secure Bit 0 – PAC Peripheral PAC Non-Secure The PAC Peripheral is always secured. SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 122 15.7.13 Peripheral Non-Secure Status - Bridge B Name:  NONSECB Offset:  0x58 Reset:  x initially determined from NVM User Row after reset Property:  Write-Secure Important:  This register is only available for SAM L11 and has no effect for SAM L10. Reading NONSEC register returns peripheral security attribution status: Value Description 0 Peripheral is secured. 1 Peripheral is non-secured. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 HMATRIXHS DMAC NVMCTRL DSU IDAU Access R/R/R R/R/R R/R/R R/R/R R/R/R Reset x x 0 1 0 Bit 4 – HMATRIXHS Peripheral HMATRIXHS Non-Secure Bit 3 – DMAC Peripheral DMAC Non-Secure Bit 2 – NVMCTRL Peripheral NVMCTRL Non-Secure The NVMCTRL Peripheral is always secured. Bit 1 – DSU Peripheral DSU Non-Secure The DSU Peripheral is always non-secured. SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 123 Bit 0 – IDAU Peripheral IDAU Non-Secure The IDAU Peripheral is always secured. SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 124 15.7.14 Peripheral Non-Secure Status - Bridge C Name:  NONSECC Offset:  0x5C Reset:  x initially determined from NVM User Row after reset Property:  Write-Secure Important:  This register is only available for SAM L11 and has no effect for SAM L10. Reading NONSEC register returns peripheral Security Attribution status: Value Description 0 Peripheral is secured. 1 Peripheral is non-secured. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 TRAM OPAMP CCL TRNG PTC DAC Access R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R Reset x x x x x x Bit 7 6 5 4 3 2 1 0 ADC TC2 TC1 TC0 SERCOM2 SERCOM1 SERCOM0 EVSYS Access R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R Reset x x x x x x x x Bit 13 – TRAM Peripheral TRAM Non-Secure Bit 12 – OPAMP Peripheral OPAMP Non-Secure Bit 11 – CCL Peripheral CCL Non-Secure Bit 10 – TRNG Peripheral TRNG Non-Secure Bit 9 – PTC Peripheral PTC Non-Secure SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 125 Bit 8 – DAC Peripheral DAC Non-Secure Bit 7 – ADC Peripheral ADC Non-Secure Bits 4, 5, 6 – TC Peripheral TCn Non-Secure [n = 2..0] Bits 1, 2, 3 – SERCOM Peripheral SERCOMn Non-Secure [n = 2..0] Bit 0 – EVSYS Peripheral EVSYS Non-Secure SAM L10/L11 Family PAC - Peripheral Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 126 16. DSU - Device Service Unit 16.1 Overview The Device Service Unit (DSU) provides a means to detect debugger probes. This enables the ARM Debug Access Port (DAP) to have control over multiplexed debug pads and CPU reset. The DSU also provides system-level services to debug adapters in an ARM debug system. It implements a CoreSight Debug ROM that provides device identification as well as identification of other debug components within the system. Hence, it complies with the ARM Peripheral Identification specification. The DSU also provides system services to applications that need memory testing, as required for IEC60730 Class B compliance, for example. The DSU can be accessed simultaneously by a debugger and the CPU, as it is connected on the High-Speed Bus Matrix. It implements communication channels between the device and external tools which can be used at boot time to make use of Boot ROM services. For security reasons, some of the DSU features will be limited or unavailable when the Debug Access Level (DAL) is less than 0x2. Related Links 30. NVMCTRL – Nonvolatile Memory Controller 16.2 Features • CPU reset extension • Debugger probe detection (Cold- and Hot-Plugging) • 32-bit cyclic redundancy check (CRC32) of any memory accessible through the bus matrix • ARM® CoreSight™ compliant device identification • Two debug communications channels • Two Boot communications channels • Debug access port security filter • Onboard memory built-in self-test (MBIST) SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 127 16.3 Block Diagram Figure 16-1. DSU Block Diagram DSU SWCLK CORESIGHT ROM DAP SECURITY FILTER CRC-32 MBIST RESET CPU DAP SWDIO NVMCTRL DBG HIGH-SPEED BUS MATRIX debugger_present D GG R RO INTERFACE AHB-AP cpu_reset_extension AHB-APB BRIDGE B PORT 16.4 Signal Description The DSU uses three signals to function. Signal Name Type Description RESET Digital Input External reset SWCLK Digital Input SW clock SWDIO Digital I/O SW bidirectional data pin 16.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 16.5.1 I/O Lines The SWCLK pin is by default assigned to the DSU module to allow debugger probe detection and to stretch the CPU reset phase. For more information, refer to 16.6.3 Debugger Probe Detection. The HotPlugging feature depends on the PORT configuration. If the SWCLK pin function is changed in the PORT or if the PORT_MUX is disabled, the Hot-Plugging feature is disabled until a power-reset or an external reset is performed. 16.5.2 Power Management The DSU will continue to operate in Idle mode. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 128 Related Links 22. PM – Power Manager 16.5.3 Clocks The DSU bus clocks (CLK_DSU_APB and CLK_DSU_AHB) can be enabled and disabled by the Main Clock Controller. Related Links 22. PM – Power Manager 19. MCLK – Main Clock 19.6.2.6 Peripheral Clock Masking 16.5.4 DMA The DMA request lines are connected to the DMA Controller (DMAC). To use DMA requests with this peripheral, the DMAC must be configured first. Refer to 28. DMAC – Direct Memory Access Controller for details. The CFG.DCCDMALEVEL bitfield must be configured depending on the DMA channels access modes (read or write for DCC0 and DCC1). 16.5.5 Interrupts Not applicable. 16.5.6 Events Not applicable. 16.5.7 Register Access Protection Registers with write-access can be optionally write-protected by the Peripheral Access Controller (PAC), except for the following: • Debug Communication Channel 0 register (DCC0) • Debug Communication Channel 1 register (DCC1) • Boot Communication Channel 0 register (BCC0) • Boot Communication Channel 1 register (BCC1) Note:  Optional write-protection is indicated by the "PAC Write-Protection" property in the register description. Write-protection does not apply for accesses through an external debugger. Related Links 15. PAC - Peripheral Access Controller 16.5.8 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 129 Refer to Peripherals Security Attribution for more information. 16.5.9 Analog Connections Not applicable. 16.6 Debug Operation 16.6.1 Principle of Operation The DSU provides basic services to allow on-chip debug using the ARM Debug Access Port and the ARM processor debug resources: • CPU reset extension • Debugger probe detection • Boot Communication Channels For more details on the ARM debug components, refer to the ARM Debug Interface v5 Architecture Specification. 16.6.2 CPU Reset Extension “CPU reset extension” refers to the extension of the reset phase of the CPU core after the external reset is released. This ensures that the CPU is not executing code at startup while a debugger connects to the system. It is detected on a RESET release event when SWCLK is low. At startup, SWCLK is internally pulled up to avoid false detection of a debugger if SWCLK is left unconnected. When the CPU is held in the reset extension phase, the CPU Reset Extension bit of the Status A register (STATUSA.CRSTEXT) is set. To release the CPU, write a '1' to STATUSA.CRSTEXT. STATUSA.CRSTEXT will then be set to zero. Writing a '0' to STATUSA.CRSTEXT has no effect. Releasing the "CPU reset extension" is possible for all DAL levels. The CPU then executes the Boot ROM that offers basic failure analysis services and security checks. It is not possible to access the bus system until the Boot ROM has performed these security checks. Note:  Refer to 14. Boot ROM for more information. Figure 16-2. Typical CPU Reset Extension Set and Clear Timing Diagram DSU CRSTEXT Clear SWCLK CPU reset extension CPU_STATE reset running RESET SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 130 16.6.3 Debugger Probe Detection 16.6.3.1 Cold Plugging Cold-Plugging is the detection of a debugger when the system is in reset. Cold-Plugging is detected when the CPU reset extension is requested, as described above. 16.6.3.2 Hot Plugging Hot-Plugging is the detection of a debugger probe when the system is not in reset. Hot-Plugging is not possible under reset because the detector is reset when POR or RESET are asserted. Hot-Plugging is active when a SWCLK falling edge is detected. The SWCLK pad is multiplexed with other functions and the user must ensure that its default function is assigned to the debug system. If the SWCLK function is changed, the Hot-Plugging feature is disabled until a power-reset or external reset occurs. Availability of the Hot-Plugging feature can be read from the Hot-Plugging Enable bit of the Status B register (STATUSB.HPE). Figure 16-3. Hot-Plugging Detection Timing Diagram SWCLK Hot-Plugging CPU_STATE reset running RESET The presence of a debugger probe is detected when either Hot-Plugging or Cold-Plugging is detected. Once detected, the Debugger Present bit of the Status B register (STATUSB.DBGPRES) is set. For security reasons, Hot-Plugging is not available when DAL equals to 0x0. This detection requires that pads are correctly powered. Thus, at cold startup, this detection cannot be done until POR is released. If DAL equals 0x0, Cold-Plugging is the only way to detect a debugger probe, and so the external reset timing must be longer than the POR timing. If external reset is de-asserted before POR release, the user must retry the procedure above until it gets connected to the device. Related Links 30. NVMCTRL – Nonvolatile Memory Controller 16.6.4 Boot Communication Channels Boot Communication Channels allow communication between a debug adapter and the CPU executing the Boot ROM at startup. The Boot ROM implements system level commands. Refer to 14. Boot ROM for more information. 16.7 Programming Programming the Flash or RAM memories is only possible when the debugger access level is sufficient to access the desired resource: If DAL is equal to: • 0x2: debugger can access secured and non-secure areas • 0x1 (SAM L11 only): debugger can access only non-secure areas, refer to Table 16-4. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 131 • 0x0: debugger can only access the DSU external address space making it possible to communicate with the Boot ROM after reset. A typical programming procedure when DAL=0x2 is as follows: 1. At power up, RESET is driven low by a debugger. The on-chip regulator holds the system in a POR state until the input supply is above the POR threshold. The system continues to be held in this static state until the internally regulated supplies have reached a safe operating state. 2. The Power Manager (PM) starts, clocks are switched to the slow clock (Core Clock, System Clock, Flash Clock and any Bus Clocks that do not have clock gate control). Internal resets are maintained due to the external reset. 3. The debugger maintains a low level on SWCLK. RESET is released, resulting in a debugger ColdPlugging procedure. 4. The debugger generates a clock signal on the SWCLK pin, the Debug Access Port (DAP) receives a clock. 5. The CPU executes the Boot ROM. 6. It is recommended to issue a Chip-Erase (supported by the Boot ROM) to ensure that the Flash is fully erased prior to programming. 7. If the operation issued above was accepted and has completed successfully then DAL equals 0x2 thus programming is available through the AHB-AP. 8. After the operation is completed, the chip can be restarted either by asserting RESET, toggling power, or sending a command to the Boot ROM to jump to the NVM code. Make sure that the SWCLK pin is high when releasing RESET to prevent entering again the cold-plugging procedure with the Boot ROM stalling the CPU. Related Links 30. NVMCTRL – Nonvolatile Memory Controller 16.8 Security Enforcement Security enforcement aims at protecting intellectual property, which includes: • Restricts access to internal memories from external tools depending on the debugger access level. • Restricts access to a portion of the DSU address space from non-secure AHB masters depending on the debugger access level. The DAL setting can be locked or reverted using Boot ROM commands depending on the Boot ROM user configuration. When DAL is equal to 0x0, read/write accesses using the AHB-AP are limited to the DSU external address range and DSU commands are restricted. When issuing a Boot ROM Chip-Erase, sensitive information is erased from volatile memory and Flash. Refer to 14. Boot ROM more information about the Boot ROM features. The DSU implements a security filter that monitors the AHB transactions generated by the ARM AHB-AP inside the DAP. If DAL=0x0, then AHB-AP read/write accesses outside the DSU external address range are discarded, causing an error response that sets the ARM AHB-AP sticky error bits (refer to the "ARM Debug Interface v5 Architecture Specification", which is available for download at http://www.arm.com). For security reasons, DSU features have limitations when used from a debug adapter. To differentiate external accesses from internal ones, the first 0x100 bytes of the DSU register map have been replicated at offset 0x100: • The first 0x100 bytes form the internal address range • The next 0x1F00 bytes form the external address range SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 132 When the device is protected, the DAP can only issue MEM-AP accesses in the DSU address range limited to the 0x100- 0x2000 offset range. The DSU operating registers are located in the 0x00-0xFF area and mirrored to 0x100-0x1FF to differentiate accesses coming from a debugger and the CPU. If the device is protected and an access is issued in the region 0x100-0x1FF, it is subject to security restrictions. For more information, refer to the Table 16-2. Figure 16-4. APB Memory Mapping 0x0000 0x00FF 0x0100 0x01FF 0x1000 0x1FFF DSU operating registers Mirrored DSU operating registers DSU CoreSight ROM Empty Internal address range (cannot be accessed from debug tools when STATUSB.DAL<0x2 and cannot be accessed by a non-secure AHB master) External address range (can be accessed from debug tools with some restrictions, can be accessed by a non-secure AHB master) The DSU filters-out DAP transactions depending on the DAL setting and routes DAP transactions: • In the PPB or IOBUS space to the CPU debug port • Outside the PPB space and outside the IOBUS space to the DSU master port Table 16-1. DAP access rights depending on DAL: DAP access to SAM L11 SAM L10 DAL=0 DAL=1 DAL=2 DAL=0 DAL=2 PPB or IOBUS No Yes (see Note 1) Yes No Yes DSU internal address space No No (see Note 2) Yes No Yes DSU external address space Yes Yes Yes Yes Yes Other secure areas No No Yes No Yes Other non-secure areas No Yes Yes No Yes Note:  1. Refer to ARMv8-M debug documentation for detailed information on PPB and IOBUS access restrictions. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 133 2. When DAL=1 DAP transfers are always non-secure. The DSU internal address space can only be accessed by secure masters. Some features not activated by APB transactions are not available when the device is protected: Table 16-2. Feature Availability Under Protection Features Availability when DAL equals to 0x0 0x1 (SAM L11 only) 0x2 CPU Reset Extension Yes Yes Yes Clear CPU Reset extension Yes Yes Yes Debugger Cold-Plugging Yes Yes Yes Debugger Hot-Plugging No Yes Yes 16.9 Device Identification Device identification relies on the ARM CoreSight component identification scheme, which allows the chip to be identified as a SAM device implementing a DSU. The DSU contains identification registers to differentiate the device. 16.9.1 CoreSight Identification A system-level ARM® CoreSight™ ROM table is present in the device to identify the vendor and the chip identification method. Its address is provided in the MEM-AP BASE register inside the ARM Debug Access Port. The CoreSight ROM implements a 64-bit conceptual ID composed as follows from the PID0 to PID7 CoreSight ROM Table registers: Figure 16-5. Conceptual 64-bit Peripheral ID Table 16-3. Conceptual 64-Bit Peripheral ID Bit Descriptions Field Size Description Location JEP-106 CC code 4 Continuation code: 0x0 PID4 JEP-106 ID code 7 Device ID: 0x1F PID1+PID2 4KB count 4 Indicates that the CoreSight component is a ROM: 0x0 PID4 RevAnd 4 Not used; read as 0 PID3 CUSMOD 4 Not used; read as 0 PID3 SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 134 Field Size Description Location PARTNUM 12 Contains 0xCD0 to indicate that DSU is present PID0+PID1 REVISION 4 DSU revision (starts at 0x0 and increments by 1 at both major and minor revisions). Identifies DSU identification method variants. If 0x0, this indicates that device identification can be completed by reading the Device Identification register (DID) PID2 For more information, refer to the ARM Debug Interface Version 5 Architecture Specification. 16.9.2 Chip Identification Method The DSU DID register identifies the device by implementing the following information: • Processor identification • Product family identification • Product series identification • Device select 16.10 Functional Description 16.10.1 Principle of Operation The DSU provides memory services, such as CRC32 or MBIST that require almost the same interface. Hence, the Address, Length and Data registers (ADDR, LENGTH, DATA) are shared. These shared registers must be configured first; then a command can be issued by writing the Control register. When a command is ongoing, other commands are discarded until the current operation is completed. Hence, the user must wait for the STATUSA.DONE bit to be set prior to issuing another one. 16.10.2 Basic Operation 16.10.2.1 Initialization The module is enabled by enabling its clocks. For more details, refer to 16.5.3 Clocks. The DSU registers can be PAC write-protected. Related Links 15. PAC - Peripheral Access Controller 16.10.2.2 Operation From a Debug Adapter Debug adapters should access the DSU registers in the external address range [0x100 – 0x1FFF]. If STATUSB.DAL is equal to 0x0, accessing the first 0x100 bytes causes the DSU security filter to return an error to the DAP. (SAM L11 only): If STATUSB.DAL is equal to 0x1, debug accesses will go through the DSU security filter but will be forced as non-secure, therefore the DSU internal address space will not be accessible and any access in this case is discarded (writes are ignored, reads return 0) and raise STATUSA.PERR. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 135 Table 16-4. DAP transaction authorizations and error response types DAL Debugger Access Type DAP transaction allowed? DSU internal address space DSU external address space Other than PPB PPB 0 Secure No (Bus Error) Yes No (Bus Error) No (Bus Error) 0 Non-Secure No (Bus Error) Yes No (Bus Error) No (Bus Error) 1 (SAM L11 only) Secure No (PERR) Yes Yes (NS,PERR) Yes (ARMv8M) 1 (SAM L11 only) Non-Secure No (PERR) Yes Yes (NS,PERR) Yes (ARMv8M) 2 Secure Yes Yes Yes Yes 2 Non-Secure No (PERR) Yes Yes Yes Bus Error: A Bus Error is sent back to the DAP setting its sticky bit error. PERR: No bus error, STATUSA.PERR rises, writes are discarded, reads always return 0 NS, PERR: Access forced to non-secure, secure violations are reported in STATUSA.PERR. Note:  Refer to the ARM Debug Interface Architecture Specification for details. Related Links 30. NVMCTRL – Nonvolatile Memory Controller 16.10.2.3 Operation From the CPU Only secure masters can access the DSU internal address space. Attempting to access the internal address space from a non-secure AHB master will report a PAC error, such accesses are discarded. The external address space can be accessed by either secure or non-secure AHB masters. The user should access DSU registers in the internal address range (0x0 – 0xFF) to avoid external security restrictions. Refer to 16.8 Security Enforcement. 16.10.3 32-bit Cyclic Redundancy Check CRC32 The DSU unit provides support for calculating a cyclic redundancy check (CRC32) value for a memory area (including Flash and AHB RAM). When the CRC32 command is issued from: • The internal range from a secure AHB master, the CRC32 can be operated at any memory location • The external range, the CRC32 operation is not available The algorithm employed is the industry standard CRC32 algorithm using the generator polynomial 0xEDB88320 (reversed representation). 16.10.3.1 Starting CRC32 Calculation CRC32 calculation for a memory range is started after writing the start address into the Address register (ADDR) and the size of the memory range into the Length register (LENGTH). Both must be wordaligned. The initial value used for the CRC32 calculation must be written to the Data register (DATA). This value will usually be 0xFFFFFFFF, but can be, for example, the result of a previous CRC32 calculation if generating a common CRC32 of separate memory blocks. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 136 Once completed, the calculated CRC32 value can be read out of the Data register. The read value must be complemented to match standard CRC32 implementations or kept non-inverted if used as starting point for subsequent CRC32 calculations. The actual test is started by writing a '1' in the 32-bit Cyclic Redundancy Check bit of the Control register (CTRL.CRC). A running CRC32 operation can be canceled by resetting the module (writing '1' to CTRL.SWRST). Related Links 30. NVMCTRL – Nonvolatile Memory Controller 16.10.3.2 Interpreting the Results The user should monitor the Status A register. When the operation is completed, STATUSA.DONE is set. Then the Bus Error bit of the Status A register (STATUSA.BERR) must be read to ensure that no bus error occurred. 16.10.4 Debug Communication Channels The Debug Communication Channels (DCCO and DCC1) consist of a pair of registers with associated handshake logic, accessible by both CPU and debugger with no security restriction. The registers can be used to exchange data between the CPU and the debugger, during run time as well as in debug mode. This enables the user to build a custom debug protocol using only these registers. The DCC0 and DCC1 registers are always accessible from the external address space. When the device starts with the cold-plugging procedure, a specific Boot ROM command is needed to exit the Boot ROM main routine. Important:  This command is allowed only when DAL=0x2, otherwise the device must be reset to leave the cold plugging state to let the CPU exit the Boot ROM routine and execute the user code. Two Debug Communication Channel status bits in the Status B registers (STATUS.DCCDx) indicate whether a new value has been written in DCC0 or DCC1. These bits, DCC0D and DCC1D, are located in the STATUSB registers. They are automatically set on write and cleared on read. Note:  The DCC0 and DCC1 registers are shared with the on-board memory testing logic (MBIST). Accordingly, DCC0 and DCC1 must not be used while performing MBIST operations. Note:  The DCC0 and DCC1 registers are shared with the BCC0 and BCC1 registers therefore mixing DCC and BCC communication is not recommended. Related Links 30. NVMCTRL – Nonvolatile Memory Controller 16.10.5 Boot Communication Channels The Boot Communication Channels (BCC0 and BCC1) consist of a pair of registers with associated handshake logic, accessible by both CPU and debugger with no security restriction. The registers are intended to communicate with the CPU while executing the Boot ROM which implements security and failure analysis commands and therefore must not be used for another purpose. Note:  The BCC0 and BCC registers values are not reset except in case of POR or BOD resets. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 137 Two Boot Communication Channel status bits in the Status B registers (STATUS.BCCDx) indicate whether a new value has been written in BCC0 or BCC1. These bits, BCC0D and BCC1D, are located in the STATUSB registers. They are automatically set on write and cleared on read. Note:  The DCC0 and DCC1 registers are shared with the BCC0 and BCC1 registers therefore using DCC is not recommended while the Boot ROM is being executed. 16.10.6 Testing of On-Board Memories MBIST The DSU implements a feature for automatic testing of memory also known as MBIST (memory built-in self test). This is primarily intended for production test of on-board memories. MBIST cannot be operated from the external address range when DAL<0x2. If an MBIST command is issued when the device is protected, it is filtered-out, a protection error is reported in the Protection Error bit in the Status A register (STATUSA.PERR) and STATUSA.DONE don't rise. 1. Algorithm The algorithm used for testing is a type of March algorithm called "March LR". This algorithm is able to detect a wide range of memory defects, while still keeping a linear run time. The algorithm is: 1.1. Write entire memory to '0', in any order. 1.2. Bit for bit read '0', write '1', in descending order. 1.3. Bit for bit read '1', write '0', read '0', write '1', in ascending order. 1.4. Bit for bit read '1', write '0', in ascending order. 1.5. Bit for bit read '0', write '1', read '1', write '0', in ascending order. 1.6. Read '0' from entire memory, in ascending order. The specific implementation used has a run time which depends on the CPU clock frequency and the number of bytes tested in the RAM. The detected faults are: – Address decoder faults – Stuck-at faults – Transition faults – Coupling faults – Linked Coupling faults 2. Starting MBIST To test a memory, you need to write the start address of the memory to the ADDR.ADDR bit field, and the size of the memory into the Length register. For best test coverage, an entire physical memory block should be tested at once. It is possible to test only a subset of a memory, but the test coverage will then be somewhat lower. The actual test is started by writing a '1' to CTRL.MBIST. A running MBIST operation can be canceled by writing a '1' to CTRL.SWRST. 3. Interpreting the Results The tester should monitor the STATUSA register. When the operation is completed, STATUSA.DONE is set. There are two different modes: – ADDR.AMOD=0: exit-on-error (default) In this mode, the algorithm terminates either when a fault is detected or on successful completion. In both cases, STATUSA.DONE is set. If an error was detected, STATUSA.FAIL will be set. User then can read the DATA and ADDR registers to locate the fault. – ADDR.AMOD=1: pause-on-error SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 138 In this mode, the MBIST algorithm is paused when an error is detected. In such a situation, only STATUSA.FAIL is asserted. The state machine waits for user to clear STATUSA.FAIL by writing a '1' in STATUSA.FAIL to resume. Prior to resuming, user can read the DATA and ADDR registers to locate the fault. 4. Locating Faults If the test stops with STATUSA.FAIL set, one or more bits failed the test. The test stops at the first detected error. The position of the failing bit can be found by reading the following registers: – ADDR: Address of the word containing the failing bit – DATA: contains data to identify which bit failed, and during which phase of the test it failed. The DATA register will in this case contains the following bit groups: Figure 16-6. DATA bits Description When MBIST Operation Returns an Error Bit Bit Bit Bit phase bit_index 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 6 5 4 3 2 1 0 • bit_index: contains the bit number of the failing bit • phase: indicates which phase of the test failed and the cause of the error, as listed in the following table. Table 16-5. MBIST Operation Phases Phase Test actions 0 Write all bits to zero. This phase cannot fail. 1 Read '0', write '1', increment address 2 Read '1', write '0' 3 Read '0', write '1', decrement address 4 Read '1', write '0', decrement address 5 Read '0', write '1' 6 Read '1', write '0', decrement address 7 Read all zeros. bit_index is not used SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 139 Table 16-6. AMOD Bit Descriptions for MBIST AMOD[1:0] Description 0x0 Exit on Error 0x1 Pause on Error 0x2, 0x3 Reserved Related Links 30. NVMCTRL – Nonvolatile Memory Controller 16.10.7 System Services Availability when Accessed Externally External access: Access performed in the DSU address offset 0x100-0x1FFF range. Internal access: Access performed in the DSU address offset 0x0-0xFF range. Table 16-7. Available Features when Operated From The External Address Range and Device is Protected Features Availability From The External Address Range when DAL<2 CRC32 No CoreSight Compliant Device identification Yes Debug communication channels Yes Boot communication channels Yes Testing of onboard memories (MBIST) No SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 140 16.11 Register Summary Offset Name Bit Pos. 0x00 CTRL 7:0 MBIST CRC SWRST 0x01 STATUSA 7:0 BREXT PERR FAIL BERR CRSTEXT DONE 0x02 STATUSB 7:0 BCCDx BCCDx DCCDx DCCDx HPE DBGPRES DAL[1:0] 0x03 Reserved 0x04 ADDR 7:0 ADDR[5:0] AMOD[1:0] 15:8 ADDR[13:6] 23:16 ADDR[21:14] 31:24 ADDR[29:22] 0x08 LENGTH 7:0 LENGTH[5:0] 15:8 LENGTH[13:6] 23:16 LENGTH[21:14] 31:24 LENGTH[29:22] 0x0C DATA 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x10 DCC0 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x14 DCC1 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x18 DID 7:0 DEVSEL[7:0] 15:8 DIE[3:0] REVISION[3:0] 23:16 FAMILY[0:0] SERIES[5:0] 31:24 PROCESSOR[3:0] FAMILY[4:1] 0x1C CFG 7:0 DCCDMALEVEL[1:0] LQOS[1:0] 15:8 23:16 31:24 0x20 BCC0 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x24 BCC1 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x28 ... 0x0FFF Reserved SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 141 Offset Name Bit Pos. 0x1000 ENTRY0 7:0 FMT EPRES 15:8 ADDOFF[3:0] 23:16 ADDOFF[11:4] 31:24 ADDOFF[19:12] 0x1004 ENTRY1 7:0 FMT EPRES 15:8 ADDOFF[3:0] 23:16 ADDOFF[11:4] 31:24 ADDOFF[19:12] 0x1008 END 7:0 END[7:0] 15:8 END[15:8] 23:16 END[23:16] 31:24 END[31:24] 0x100C ... 0x1FCB Reserved 0x1FCC MEMTYPE 7:0 SMEMP 15:8 23:16 31:24 0x1FD0 PID4 7:0 FKBC[3:0] JEPCC[3:0] 15:8 23:16 31:24 0x1FD4 ... 0x1FDF Reserved 0x1FE0 PID0 7:0 PARTNBL[7:0] 15:8 23:16 31:24 0x1FE4 PID1 7:0 JEPIDCL[3:0] PARTNBH[3:0] 15:8 23:16 31:24 0x1FE8 PID2 7:0 REVISION[3:0] JEPU JEPIDCH[2:0] 15:8 23:16 31:24 0x1FEC PID3 7:0 REVAND[3:0] CUSMOD[3:0] 15:8 23:16 31:24 0x1FF0 CID0 7:0 PREAMBLEB0[7:0] 15:8 23:16 31:24 SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 142 Offset Name Bit Pos. 0x1FF4 CID1 7:0 CCLASS[3:0] PREAMBLE[3:0] 15:8 23:16 31:24 0x1FF8 CID2 7:0 PREAMBLEB2[7:0] 15:8 23:16 31:24 0x1FFC CID3 7:0 PREAMBLEB3[7:0] 15:8 23:16 31:24 16.12 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to 16.5.7 Register Access Protection. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 143 16.12.1 Control Name:  CTRL Offset:  0x0000 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 MBIST CRC SWRST Access W W W Reset 0 0 0 Bit 3 – MBIST Memory Built-In Self-Test Writing a '0' to this bit has no effect. Writing a '1' to this bit starts the memory BIST algorithm. Bit 2 – CRC 32-bit Cyclic Redundancy Check Writing a '0' to this bit has no effect. Writing a '1' to this bit starts the cyclic redundancy check algorithm. Bit 0 – SWRST Software Reset Writing a '0' to this bit has no effect. Writing a '1' to this bit resets the module. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 144 16.12.2 Status A Name:  STATUSA Offset:  0x0001 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 BREXT PERR FAIL BERR CRSTEXT DONE Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 5 – BREXT Boot ROM Phase Extension Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Boot ROM Phase Extension bit. This bit is set when a debug adapter Cold-Plugging is detected, which extends the Boot ROM phase. Bit 4 – PERR Protection Error Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Protection Error bit. This bit is set upon access to: • A reserved address • CTRL, ADDR, LENGTH, DATA, CFG from the external address space when DAL<2 • The internal address space with a Non-Secure access (security violation) (SAM L11 only) Bit 3 – FAIL Failure Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Failure bit. This bit is set when a DSU operation failure is detected. Bit 2 – BERR Bus Error Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Bus Error bit. This bit is set when a bus error is detected. Bit 1 – CRSTEXT CPU Reset Phase Extension Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the CPU Reset Phase Extension bit. This bit is set when a debug adapter Cold-Plugging is detected, which extends the CPU reset phase. Bit 0 – DONE Done Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Done bit. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 145 This bit is set when a DSU operation is completed. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 146 16.12.3 Status B Name:  STATUSB Offset:  0x0002 Reset:  0xX Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 BCCDx BCCDx DCCDx DCCDx HPE DBGPRES DAL[1:0] Access R R R R R R R R Reset 0 0 0 0 1 0 0 x Bits 7,6 – BCCDx BOOT Communication Channel x Dirty [x=1..0] Writing a '0' to this bit has no effect. Writing a '1' to this bit has no effect. This bit is set when BCCx is written. This bit is cleared when BCCx is read. Bits 5,4 – DCCDx Debug Communication Channel x Dirty [x=1..0] Writing a '0' to this bit has no effect. Writing a '1' to this bit has no effect. This bit is set when DCCx is written. This bit is cleared when DCCx is read. Bit 3 – HPE Hot-Plugging Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit has no effect. This bit is set when Hot-Plugging is enabled. This bit is cleared when Hot-Plugging is disabled. This is the case when the SWCLK function is changed. Only a power-reset or a external reset can set it again. Bit 2 – DBGPRES Debugger Present Writing a '0' to this bit has no effect. Writing a '1' to this bit has no effect. This bit is set when a debugger probe is detected. This bit is never cleared. Bits 1:0 – DAL[1:0] Debugger Access Level Indicates the debugger access level: • 0x0: Debugger can only access the DSU external address space. • 0x1: Debugger can access only Non-Secure regions (SAM L11 only). • 0x2: Debugger can access secure and Non-Secure regions. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 147 Writing in this bitfield has no effect. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 148 16.12.4 Address Name:  ADDR Offset:  0x0004 Reset:  0x00000000 Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 ADDR[29:22] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 ADDR[21:14] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 ADDR[13:6] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 ADDR[5:0] AMOD[1:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:2 – ADDR[29:0] Address Initial word start address needed for memory operations. Bits 1:0 – AMOD[1:0] Address Mode The functionality of these bits is dependent on the operation mode. Bit description when testing on-16.10.6 Testing of On-Board Memories MBISTboard memories (MBIST): refer to SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 149 16.12.5 Length Name:  LENGTH Offset:  0x0008 Reset:  0x00000000 Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 LENGTH[29:22] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 LENGTH[21:14] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 LENGTH[13:6] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 LENGTH[5:0] Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bits 31:2 – LENGTH[29:0] Length Length in words needed for memory operations. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 150 16.12.6 Data Name:  DATA Offset:  0x000C Reset:  0x00000000 Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 DATA[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DATA[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DATA[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DATA[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – DATA[31:0] Data Memory operation initial value or result value. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 151 16.12.7 Debug Communication Channel 0 Name:  DCC0 Offset:  0x0010 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 DATA[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DATA[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DATA[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DATA[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – DATA[31:0] Data Data register. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 152 16.12.8 Debug Communication Channel 1 Name:  DCC1 Offset:  0x0014 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 DATA[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DATA[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DATA[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DATA[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – DATA[31:0] Data Data register. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 153 16.12.9 Device Identification Name:  DID Offset:  0x0018 Reset:  see related links Property:  PAC Write-Protection The information in this register is related to the 2. Ordering Information. Bit 31 30 29 28 27 26 25 24 PROCESSOR[3:0] FAMILY[4:1] Access R R R R R R R R Reset p p p p f f f f Bit 23 22 21 20 19 18 17 16 FAMILY[0:0] SERIES[5:0] Access R R R R R R R Reset f s s s s s s Bit 15 14 13 12 11 10 9 8 DIE[3:0] REVISION[3:0] Access R R R R R R R R Reset d d d d r r r r Bit 7 6 5 4 3 2 1 0 DEVSEL[7:0] Access R R R R R R R R Reset x x x x x x x x Bits 31:28 – PROCESSOR[3:0] Processor The value of this field defines the processor used on the device. Bits 27:23 – FAMILY[4:0] Product Family The value of this field corresponds to the Product Family part of the ordering code. Bits 21:16 – SERIES[5:0] Product Series The value of this field corresponds to the Product Series part of the ordering code. Bits 15:12 – DIE[3:0] Die Number Identifies the die family. Bits 11:8 – REVISION[3:0] Revision Number Identifies the die revision number. 0x0=rev.A, 0x1=rev.B etc. Note:  The device variant (last letter of the ordering number) is independent of the die revision (DSU.DID.REVISION): The device variant denotes functional differences, whereas the die revision marks evolution of the die. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 154 Bits 7:0 – DEVSEL[7:0] Device Selection This bit field identifies a device within a product family and product series. Refer to 2. Ordering Information for device configurations and corresponding values for Flash memory density, pin count, and device variant. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 155 16.12.10 Configuration Name:  CFG Offset:  0x001C Reset:  0x0000000 Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 DCCDMALEVEL[1:0] LQOS[1:0] Access RW RW RW RW Reset 0 0 0 2 Bits 3:2 – DCCDMALEVEL[1:0] DMA TriggerLevel 0x0X: DCC1 trigger is the image of STATUSB.DCC1D, this signals to the DMA that a data is available for read, this is the correct configuration for a channel that reads DCC1. 0x1X: DCC1 trigger is the image of STATUSB.DCC1D inverted, this signals to the DMA that DCC1 is ready for write, this is the correct configuration for a channel that writes DCC1 0xX0: DCC0 trigger is the image of STATUSB.DCC0D, this signals to the DMA that a data is available for read, this is the correct configuration for a channel that reads DCC0. 0xX1: DCC0 trigger is the image of STATUSB.DCC0D inverted, this signals to the DMA that DCC0 is ready for write, this is the correct configuration for a channel that writes DCC0 Bits 1:0 – LQOS[1:0] Latency Quality Of Service Defines the latency quality of service required when accessing the RAM: 0: Background Transfers 1: Bandwidth Sensitive 2: Latency sensitive 3: Latency critical SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 156 16.12.11 Boot Communication Channel 0 Name:  BCC0 Offset:  0x0020 Reset:  N/A Property:  - Bit 31 30 29 28 27 26 25 24 DATA[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DATA[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DATA[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DATA[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – DATA[31:0] Data Data register. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 157 16.12.12 Boot Communication Channel 1 Name:  BCC1 Offset:  0x0024 Reset:  N/A Property:  - Bit 31 30 29 28 27 26 25 24 DATA[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DATA[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DATA[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DATA[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – DATA[31:0] Data Data register. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 158 16.12.13 CoreSight ROM Table Entry 0 Name:  ENTRY0 Offset:  0x1000 Reset:  0xXXXXX00X Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 ADDOFF[19:12] Access R R R R R R R R Reset x x x x x x x x Bit 23 22 21 20 19 18 17 16 ADDOFF[11:4] Access R R R R R R R R Reset x x x x x x x x Bit 15 14 13 12 11 10 9 8 ADDOFF[3:0] Access R R R R Reset x x x x Bit 7 6 5 4 3 2 1 0 FMT EPRES Access R R Reset 1 x Bits 31:12 – ADDOFF[19:0] Address Offset The base address of the component, relative to the base address of this ROM table. Bit 1 – FMT Format Always reads as '1', indicating a 32-bit ROM table. Bit 0 – EPRES Entry Present This bit indicates whether an entry is present at this location in the ROM table. This bit is set at power-up if the device is not protected indicating that the entry is not present. This bit is cleared at power-up if the device is not protected indicating that the entry is present. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 159 16.12.14 CoreSight ROM Table Entry 1 Name:  ENTRY1 Offset:  0x1004 Reset:  0xXXXXX00X Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 ADDOFF[19:12] Access R R R R R R R R Reset x x x x x x x x Bit 23 22 21 20 19 18 17 16 ADDOFF[11:4] Access R R R R R R R R Reset x x x x x x x x Bit 15 14 13 12 11 10 9 8 ADDOFF[3:0] Access R R R R Reset x x x x Bit 7 6 5 4 3 2 1 0 FMT EPRES Access R R Reset 1 x Bits 31:12 – ADDOFF[19:0] Address Offset The base address of the component, relative to the base address of this ROM table. Bit 1 – FMT Format Always read as '1', indicating a 32-bit ROM table. Bit 0 – EPRES Entry Present This bit indicates whether an entry is present at this location in the ROM table. This bit is set at power-up if the device is not protected indicating that the entry is not present. This bit is cleared at power-up if the device is not protected indicating that the entry is present. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 160 16.12.15 CoreSight ROM Table End Name:  END Offset:  0x1008 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 END[31:24] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 END[23:16] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 END[15:8] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 END[7:0] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bits 31:0 – END[31:0] End Marker Indicates the end of the CoreSight ROM table entries. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 161 16.12.16 CoreSight ROM Table Memory Type Name:  MEMTYPE Offset:  0x1FCC Reset:  0x0000000x Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 SMEMP Access R Reset x Bit 0 – SMEMP System Memory Present This bit indicates whether system memory is present on the bus that connects to the ROM table. This bit is set at power-up if the device is not protected, indicating that the system memory is accessible from a debug adapter. This bit is cleared at power-up if the device is protected, indicating that the system memory is not accessible from a debug adapter. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 162 16.12.17 Peripheral Identification 4 Name:  PID4 Offset:  0x1FD0 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 FKBC[3:0] JEPCC[3:0] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bits 7:4 – FKBC[3:0] 4KB Count These bits will always return zero when read, indicating that this debug component occupies one 4KB block. Bits 3:0 – JEPCC[3:0] JEP-106 Continuation Code These bits will always return zero when read. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 163 16.12.18 Peripheral Identification 0 Name:  PID0 Offset:  0x1FE0 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 PARTNBL[7:0] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bits 7:0 – PARTNBL[7:0] Part Number Low These bits will always return 0xD0 when read, indicating that this device implements a DSU module instance. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 164 16.12.19 Peripheral Identification 1 Name:  PID1 Offset:  0x1FE4 Reset:  0x000000FC Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 JEPIDCL[3:0] PARTNBH[3:0] Access R R R R R R R R Reset 1 1 1 1 1 1 0 0 Bits 7:4 – JEPIDCL[3:0] Low part of the JEP-106 Identity Code These bits will always return 0xF when read (JEP-106 identity code is 0x1F). Bits 3:0 – PARTNBH[3:0] Part Number High These bits will always return 0xC when read, indicating that this device implements a DSU module instance. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 165 16.12.20 Peripheral Identification 2 Name:  PID2 Offset:  0x1FE8 Reset:  0x00000019 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 REVISION[3:0] JEPU JEPIDCH[2:0] Access R R R R R R R R Reset 0 0 0 1 1 0 0 1 Bits 7:4 – REVISION[3:0] Revision Number Revision of the peripheral. Starts at 0x0 and increments by one at both major and minor revisions. Bit 3 – JEPU JEP-106 Identity Code is used This bit will always return one when read, indicating that JEP-106 code is used. Bits 2:0 – JEPIDCH[2:0] JEP-106 Identity Code High These bits will always return 0x1 when read, indicating an Atmel device (Atmel JEP-106 identity code is 0x1F). SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 166 16.12.21 Peripheral Identification 3 Name:  PID3 Offset:  0x1FEC Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 REVAND[3:0] CUSMOD[3:0] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bits 7:4 – REVAND[3:0] Revision Number These bits will always return 0x0 when read. Bits 3:0 – CUSMOD[3:0] ARM CUSMOD These bits will always return 0x0 when read. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 167 16.12.22 Component Identification 0 Name:  CID0 Offset:  0x1FF0 Reset:  0x0000000D Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 PREAMBLEB0[7:0] Access R R R R R R R R Reset 0 0 0 0 1 1 0 1 Bits 7:0 – PREAMBLEB0[7:0] Preamble Byte 0 These bits will always return 0x0000000D when read. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 168 16.12.23 Component Identification 1 Name:  CID1 Offset:  0x1FF4 Reset:  0x00000010 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 CCLASS[3:0] PREAMBLE[3:0] Access R R R R R R R R Reset 0 0 0 1 0 0 0 0 Bits 7:4 – CCLASS[3:0] Component Class These bits will always return 0x1 when read indicating that this ARM CoreSight component is ROM table (refer to the ARM Debug Interface v5 Architecture Specification at http://www.arm.com). Bits 3:0 – PREAMBLE[3:0] Preamble These bits will always return 0x00 when read. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 169 16.12.24 Component Identification 2 Name:  CID2 Offset:  0x1FF8 Reset:  0x00000005 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 PREAMBLEB2[7:0] Access R R R R R R R R Reset 0 0 0 0 0 1 0 1 Bits 7:0 – PREAMBLEB2[7:0] Preamble Byte 2 These bits will always return 0x00000005 when read. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 170 16.12.25 Component Identification 3 Name:  CID3 Offset:  0x1FFC Reset:  0x000000B1 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 PREAMBLEB3[7:0] Access R R R R R R R R Reset 1 0 1 1 0 0 0 1 Bits 7:0 – PREAMBLEB3[7:0] Preamble Byte 3 These bits will always return 0x000000B1 when read. SAM L10/L11 Family DSU - Device Service Unit © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 171 17. Clock System This chapter summarizes the clock distribution and terminology in the SAM L10/L11 device. This document will not explain every detail of its configuration, hence for in-depth details, refer to the respective peripherals descriptions and the Generic Clock documentation. 17.1 Clock Distribution Figure 17-1. Clock Distribution GCLK Generator 0 OSCCTRL GCLK GCLK Generator 1 GCLK Generator x Peripheral Channel 0 (FDPLL96M Ref) Peripheral Channel 1 (FDPLL96M 32k Ref) Peripheral z Peripheral 0 Syncronous Clock Controller MCLK AHB/APB System Clocks GCLK_MAIN OSC16M DFLLULP XOSC Generic Clocks OSCK32CTRL OSCULP32K XOSC32K FDPLL96M Peripheral Channel 3 GCLK_DPLL Peripheral Channel y GCLK_DPLL_32K GCLK_DPLL GCLK_DPLL_32K RTC CLK_RTC_OSC CLK_WDT_OSC Peripheral Channel 2 (DFLLULP Ref) WDT 32kHz 32kHz CLK_ULP32K EIC OPAMP GCLK_DFLLULP GCLK_DFLLULP CLK_ULP32K CLK_DFLLULP CLK_MAIN The SAM L10/L11 clock system consists of these features: • Clock sources, that is oscillators controlled by OSCCTRL and OSC32KCTRL – A clock source provides a time base that is used by other components, such as Generic Clock Generators. Example clock sources are the internal 16MHz oscillator (OSC16M), external crystal oscillator (XOSC) and the Fractional Digital Phase Locked Loop (FDPLL96M). • Generic Clock Controller (GCLK), which generates, controls and distributes the asynchronous clock consisting of: – Generic Clock Generators: These are programmable prescalers that can use any of the system clock sources as a time base. The Generic Clock Generator 0 generates the clock signal GCLK_MAIN, which is used by the Power Manager and the Main Clock (MCLK) module, which in turn generates synchronous clocks. – Generic Clocks: These are clock signals generated by Generic Clock Generators and output by the Peripheral Channels, and serve as clocks for the peripherals of the system. Multiple instances of a peripheral will typically have a separate Generic Clock for each instance. SAM L10/L11 Family Clock System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 172 Generic Clock 0 serves as the clock source for the FDPLL96M clock input (when multiplying another clock source). • Main Clock Controller (MCLK) – The MCLK generates and controls the synchronous clocks on the system. This includes the CPU, bus clocks (APB, AHB) as well as the synchronous (to the CPU) user interfaces of the peripherals. It contains clock masks that can turn on/off the user interface of a peripheral as well as prescalers for the CPU and bus clocks. The figure below illustrates an example, where SERCOM0 is clocked by the FDPLL96M in Open Loop mode. The FDPLL96M is enabled, the Generic Clock Generator 1 uses the FDPLL96M as its clock source and feeds into Peripheral Channel 11. The Generic Clock 10, also called GCLK_SERCOM0_CORE, is connected to SERCOM0. The SERCOM0 interface, clocked by CLK_SERCOM0_APB, has been unmasked in the APBC Mask register in the MCLK. Figure 17-2. Example of SERCOM Clock OSCCTRL FDPLL96M Generic Clock Generator 1 Peripheral Channel 11 SERCOM 0 Syncronous Clock Controller MCLK CLK_SERCOM0_APB GCLK_SERCOM0_CORE GCLK To customize the clock distribution, refer to these registers and bit fields: • The source oscillator for a generic clock generator 'n' is selected by writing to the Source bit field in the Generator Control n register (GCLK.GENCTRLn.SRC). • A Peripheral Channel m can be configured to use a specific Generic Clock Generator by writing to the Generic Clock Generator bit field in the respective Peripheral Channel m register (GCLK.PCHCTRLm.GEN) • The Peripheral Channel number, m, is fixed for a given peripheral. See the Mapping table in the description of GCLK.PCHCTRLm. • The AHB clocks are enabled and disabled by writing to the respective bit in the AHB Mask register (MCLK.AHBMASK). • The APB clocks are enabled and disabled by writing to the respective bit in the APB x Mask registers (MCLK.APBxMASK). 17.2 Synchronous and Asynchronous Clocks As the CPU and the peripherals can be in different clock domains, that is, they are clocked from different clock sources and with different clock speeds, some peripheral accesses by the CPU need to be synchronized. In this case the peripheral includes a Synchronization Busy (SYNCBUSY) register that can be used to check if a sync operation is in progress. For a general description, see 17.3 Register Synchronization. Some peripherals have specific properties described in their individual “Synchronization” sub-sections. SAM L10/L11 Family Clock System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 173 In the data sheet, references to Synchronous Clocks are referring to the CPU and bus clocks (MCLK), while asynchronous clocks are generated by the Generic Clock Controller (GCLK). 17.3 Register Synchronization 17.3.1 Overview All peripherals are composed of one digital bus interface connected to the APB or AHB bus and running from a corresponding clock in the Main Clock domain, and one peripheral core running from the peripheral Generic Clock (GCLK). Communication between these clock domains must be synchronized. This mechanism is implemented in hardware, so the synchronization process takes place even if the peripheral generic clock is running from the same clock source and on the same frequency as the bus interface. All registers in the bus interface are accessible without synchronization. All registers in the peripheral core are synchronized when written. Some registers in the peripheral core are synchronized when read. Each individual register description will have the properties "Read-Synchronized" and/or "WriteSynchronized" if a register is synchronized. As shown in the figure below, each register that requires synchronization has its individual synchronizer and its individual synchronization status bit in the Synchronization Busy register (SYNCBUSY). Note:  For registers requiring both read- and write-synchronization, the corresponding bit in SYNCBUSY is shared. SAM L10/L11 Family Clock System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 174 Figure 17-3. Register Synchronization Overview Synchronous Domain (CLK_APB) Asynchronous Domain (GCLK ) Non Sync’d reg Periperal Bus Write-Sync’d reg SYNCBUSY R/W-Sync’d reg Sync Sync Read-Sync’d reg Sync Write-only register Read-only register R/W register Write-Sync’d reg Sync R/W register Non Sync’d reg Read-only register Sync INTFLAG 17.3.2 General Write Synchronization Write-Synchronization is triggered by writing to a register in the peripheral clock domain (GCLK). The respective bit in the Synchronization Busy register (SYNCBUSY) will be set when the writesynchronization starts and cleared when the write-synchronization is complete. Refer also to17.3.7 Synchronization Delay. When write-synchronization is ongoing for a register, any subsequent write attempts to this register will be discarded, and an error will be reported though the Peripheral Access Controller (PAC). Example: REGA, REGB are 8-bit core registers. REGC is a 16-bit core register. Offset Register 0x00 REGA 0x01 REGB 0x02 REGC 0x03 Synchronization is per register, so multiple registers can be synchronized in parallel. Consequently, after REGA (8-bit access) was written, REGB (8-bit access) can be written immediately without error. SAM L10/L11 Family Clock System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 175 REGC (16-bit access) can be written without affecting REGA or REGB. If REGC is written to in two consecutive 8-bit accesses without waiting for synchronization, the second write attempt will be discarded and an error is generated through the PAC. A 32-bit access to offset 0x00 will write all three registers. Note that REGA, REGB and REGC can be updated at different times because of independent write synchronization. 17.3.3 General Read Synchronization Read-synchronized registers are synchronized each time the register value is updated but the corresponding SYNCBUSY bits are not set. Reading a read-synchronized register does not start a new synchronization, it returns the last synchronized value. Note:  The corresponding bits in SYNCBUSY will automatically be set when the device wakes up from sleep because read-synchronized registers need to be synchronized. Therefore reading a readsynchronized register before its corresponding SYNCBUSY bit is cleared will return the last synchronized value before sleep mode. Moreover, if a register is also write-synchronized, any write access while the SYNCBUSY bit is set will be discarded and generate an error. 17.3.4 Completion of Synchronization In order to check if synchronization is complete, the user can either poll the relevant bits in SYNCBUSY or use the Synchronisation Ready interrupt (if available). The Synchronization Ready interrupt flag will be set when all ongoing synchronizations are complete, i.e. when all bits in SYNCBUSY are '0'. 17.3.5 Write Synchronization for CTRLA.ENABLE Setting the Enable bit in a module's Control A register (CTRLA.ENABLE) will trigger write-synchronization and set SYNCBUSY.ENABLE. CTRLA.ENABLE will read its new value immediately after being written. SYNCBUSY.ENABLE will be cleared by hardware when the operation is complete. The Synchronization Ready interrupt (if available) cannot be used to enable write-synchronization. 17.3.6 Write-Synchronization for Software Reset Bit Setting the Software Reset bit in CTRLA (CTRLA.SWRST=1) will trigger write-synchronization and set SYNCBUSY.SWRST. When writing a ‘1’ to the CTRLA.SWRST bit it will immediately read as ‘1’. CTRL.SWRST and SYNCBUSY.SWRST will be cleared by hardware when the peripheral has been reset. Writing a '0' to the CTRL.SWRST bit has no effect. The Ready interrupt (if available) cannot be used for Software Reset write-synchronization. Note:  Not all peripherals have the SWRST bit in the respective CTRLA register. 17.3.7 Synchronization Delay The synchronization will delay write and read accesses by a certain amount. This delay D is within the range of: 5×PGCLK + 2×PAPB < D < 6×PGCLK + 3×PAPB Where PGCLK is the period of the generic clock and PAPB is the period of the peripheral bus clock. A normal peripheral bus register access duration is 2×PAPB. SAM L10/L11 Family Clock System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 176 17.4 Enabling a Peripheral In order to enable a peripheral that is clocked by a Generic Clock, the following parts of the system needs to be configured: • A running Clock Source • A clock from the Generic Clock Generator must be configured to use one of the running Clock Sources, and the Generator must be enabled. • The Peripheral Channel that provides the Generic Clock signal to the peripheral must be configured to use a running Generic Clock Generator, and the Generic Clock must be enabled. • The user interface of the peripheral needs to be unmasked in the Main Clock Controller (MCLK). If this is not done the peripheral registers will read all '0's and any writing attempts to the peripheral will be discarded. 17.5 On Demand Clock Requests Figure 17-4. Clock Request Routing FDPLL96M Generic Clock Generator Clock request Generic Clock Periph. Channel Clock request Peripheral Clock request ENABLE RUNSTDBY ONDEMAND CLKEN RUNSTDBY ENABLE RUNSTDBY GENEN All clock sources in the system can be run in an on-demand mode: the clock source is in a stopped state unless a peripheral is requesting the clock source. Clock requests propagate from the peripheral, via the GCLK, to the clock source. If one or more peripheral is using a clock source, the clock source will be started/kept running. As soon as the clock source is no longer needed and no peripheral has an active request, the clock source will be stopped until requested again. The clock request can reach the clock source only if the peripheral, the generic clock and the clock from the Generic Clock Generator in-between are enabled. The time taken from a clock request being asserted to the clock source being ready is dependent on the clock source startup time, clock source frequency as well as the divider used in the Generic Clock Generator. The total startup time Tstart from a clock request until the clock is available for the peripheral is between: Tstart_max = Clock source startup time + 2 × clock source periods + 2 × divided clock source periods Tstart_min = Clock source startup time + 1 × clock source period + 1 × divided clock source period The time between the last active clock request stopped and the clock is shut down, Tstop, is between: Tstop_min = 1 × divided clock source period + 1 × clock source period Tstop_max = 2 × divided clock source periods + 2 × clock source periods The On-Demand function can be disabled individually for each clock source by clearing the ONDEMAND bit located in each clock source controller. Consequently, the clock will always run whatever the clock request status is. This has the effect of removing the clock source startup time at the cost of power consumption. The clock request mechanism can be configured to work in standby mode by setting the RUNSDTBY bits of the modules (see Figure 17-4). SAM L10/L11 Family Clock System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 177 17.6 Power Consumption vs. Speed When targeting for either a low-power or a fast acting system, some considerations have to be taken into account due to the nature of the asynchronous clocking of the peripherals: If clocking a peripheral with a very low clock, the active power consumption of the peripheral will be lower. At the same time the synchronization to the synchronous (CPU) clock domain is dependent on the peripheral clock speed, and will take longer with a slower peripheral clock. This will cause worse response times and longer synchronization delays. 17.7 Clocks after Reset On any Reset the synchronous clocks start to their initial state: • OSC16M is enabled and configured to run at 4MHz • Generic Clock Generator 0 uses OSC16M as source and generates GCLK_MAIN and CLK_MAIN • CPU and BUS clocks are undivided On a Power-on Reset, the 32KHz clock sources are reset and the GCLK module starts to its initial state: • All Generic Clock Generators are disabled except Generator 0 • All Peripheral Channels in GCLK are disabled. On a User Reset the GCLK module starts to its initial state, except for: • Generic Clocks that are write-locked, i.e., the according WRTLOCK is set to 1 prior to Reset SAM L10/L11 Family Clock System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 178 18. GCLK - Generic Clock Controller 18.1 Overview Depending on the application, peripherals may require specific clock frequencies to operate correctly. The Generic Clock controller (GCLK) features 5 Generic Clock Generators 0..4 that can provide a wide range of clock frequencies. Generators can be set to use different external and internal oscillators as source. The clock of each Generator can be divided. The outputs from the Generators are used as sources for the Peripheral Channels, which provide the Generic Clock (GCLK_PERIPH) to the peripheral modules, as shown in Figure 18-2. The number of Peripheral Clocks depends on how many peripherals the device has. Note:  The Generator 0 is always the direct source of the GCLK_MAIN signal. 18.2 Features • Provides a device-defined, configurable number of Peripheral Channel clocks • Wide frequency range: – Various clock sources – Embedded dividers 18.3 Block Diagram The generation of Peripheral Clock signals (GCLK_PERIPH) and the Main Clock (GCLK_MAIN) can be seen in Device Clocking Diagram. Figure 18-1. Device Clocking Diagram GCLK_IO Generic Clock Generator OSC16M OSCCTRL Clock Divider & Masker Clock Gate Peripheral Channel GCLK_PERIPH PERIPHERAL GENERIC CLOCK CONTROLLER MCLK GCLK_MAIN DFLLULP XOSC OSC32CTRL OSCULP32K XOSC32K FDPLL96M CLK_DFLLULP CLK_MAIN The GCLK block diagram is shown below: SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 179 Figure 18-2. Generic Clock Controller Block Diagram Generic Clock Generator 0 GCLK_IO[0] (I/O input) Clock Divider & Masker Clock Sources GCLKGEN[0] GCLK_IO[1] (I/O input) GCLKGEN[1] GCLK_IO[n] (I/O input) GCLKGEN[n] Clock Gate Peripheral Channel 0 GCLK_PERIPH[0] Clock Gate Peripheral Channel 1 Clock Gate Peripheral Channel n GCLKGEN[n:0] GCLK_MAIN GCLK_IO[1] (I/O output) GCLK_IO[0] (I/O output) GCLK_IO[n] (I/O output) Generic Clock Generator 1 Clock Divider & Masker Generic Clock Generator n Clock Divider & Masker GCLK_PERIPH[1] GCLK_PERIPH[n] 18.4 Signal Description Table 18-1. GCLK Signal Description Signal Name Type Description GCLK_IO[4:0] Digital I/O Clock source for Generators when input Generic Clock signal when output Note:  One signal can be mapped on several pins. 18.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 18.5.1 I/O Lines Using the GCLK I/O lines requires the I/O pins to be configured. Related Links 32. PORT - I/O Pin Controller 18.5.2 Power Management The GCLK can operate in sleep modes, if required. Refer to the sleep mode description in the Power Manager (PM) section. Related Links 22. PM – Power Manager 18.5.3 Clocks The GCLK bus clock (CLK_GCLK_APB) can be enabled and disabled in the Main Clock Controller. SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 180 Related Links 19.6.2.6 Peripheral Clock Masking 24. OSC32KCTRL – 32KHz Oscillators Controller 18.5.4 DMA Not applicable. 18.5.5 Interrupts Not applicable. 18.5.6 Events Not applicable. 18.5.7 Debug Operation When the CPU is halted in debug mode the GCLK continues normal operation. If the GCLK 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. 18.5.8 Register Access Protection All registers with write-access can be optionally write-protected by the Peripheral Access Controller (PAC). Note:  Optional write-protection is indicated by the "PAC Write-Protection" property in the register description. Write-protection does not apply for accesses through an external debugger. Related Links 15. PAC - Peripheral Access Controller 18.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 18.5.10 Analog Connections Not applicable. 18.6 Functional Description 18.6.1 Principle of Operation The GCLK module is comprised of five Generic Clock Generators (Generators) sourcing up to 64 Peripheral Channels and the Main Clock signal CLK_MAIN. SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 181 A clock source selected as input to a Generator can either be used directly, or it can be prescaled in the Generator. A generator output is used by one or more Peripheral Channels to provide a peripheral generic clock signal (GCLK_PERIPH) to the peripherals. 18.6.2 Basic Operation 18.6.2.1 Initialization Before a Generator is enabled, the corresponding clock source should be enabled. The Peripheral clock must be configured as outlined by the following steps: 1. The Generator must be enabled (GENCTRLn.GENEN=1) and the division factor must be set (GENTRLn.DIVSEL and GENCTRLn.DIV) by performing a single 32-bit write to the Generator Control register (GENCTRLn). 2. The Generic Clock for a peripheral must be configured by writing to the respective Peripheral Channel Control register (PCHCTRLm). The Generator used as the source for the Peripheral Clock must be written to the GEN bit field in the Peripheral Channel Control register (PCHCTRLm.GEN). Note:  Each Generator n is configured by one dedicated register GENCTRLn. Note:  Each Peripheral Channel m is configured by one dedicated register PCHCTRLm. 18.6.2.2 Enabling, Disabling, and Resetting The GCLK module has no enable/disable bit to enable or disable the whole module. The GCLK is reset by setting the Software Reset bit in the Control A register (CTRLA.SWRST) to 1. All registers in the GCLK will be reset to their initial state, except for Peripheral Channels and associated Generators that have their Write Lock bit set to 1 (PCHCTRLm.WRTLOCK). For further details, refer to 18.6.3.4 Configuration Lock. 18.6.2.3 Generic Clock Generator Each Generator (GCLK_GEN) can be set to run from one of eight different clock sources except GCLK_GEN[1], which can be set to run from one of seven sources. GCLK_GEN[1] is the only Generator that can be selected as source to others Generators. Each generator GCLK_GEN[x] can be connected to one specific pin GCLK_IO[x]. A pin GCLK_IO[x] can be set either to act as source to GCLK_GEN[x] or to output the clock signal generated by GCLK_GEN[x]. The selected source can be divided. Each Generator can be enabled or disabled independently. Each GCLK_GEN clock signal can then be used as clock source for Peripheral Channels. Each Generator output is allocated to one or several Peripherals. GCLK_GEN[0] is used as GCLK_MAIN for the synchronous clock controller inside the Main Clock Controller. Refer to the Main Clock Controller description for details on the synchronous clock generation. SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 182 Figure 18-3. Generic Clock Generator Related Links 19. MCLK – Main Clock 18.6.2.4 Enabling a Generator A Generator is enabled by writing a '1' to the Generator Enable bit in the Generator Control register (GENCTRLn.GENEN=1). 18.6.2.5 Disabling a Generator A Generator is disabled by writing a '0' to GENCTRLn.GENEN. When GENCTRLn.GENEN=0, the GCLK_GEN[n] clock is disabled and gated. 18.6.2.6 Selecting a Clock Source for the Generator Each Generator can individually select a clock source by setting the Source Select bit group in the Generator Control register (GENCTRLn.SRC). Changing from one clock source, for example A, to another clock source, B, can be done on the fly: If clock source B is not ready, the Generator will continue using clock source A. As soon as source B is ready, the Generator will switch to it. During the switching operation, the Generator maintains clock requests to both clock sources A and B, and will release source A as soon as the switch is done. The according bit in SYNCBUSY register (SYNCBUSY.GENCTRLn) will remain '1' until the switch operation is completed. The available clock sources are device dependent (usually the oscillators, RC oscillators, DPLL, and DFLLULP). Only Generator 1 can be used as a common source for all other generators. 18.6.2.7 Changing the Clock Frequency The selected source for a Generator can be divided by writing a division value in the Division Factor bit field of the Generator Control register (GENCTRLn.DIV). How the actual division factor is calculated is depending on the Divide Selection bit (GENCTRLn.DIVSEL). If GENCTRLn.DIVSEL=0 and GENCTRLn.DIV is either 0 or 1, the output clock will be undivided. Note:  The number of available DIV bits may vary from Generator to Generator. 18.6.2.8 Duty Cycle When dividing a clock with an odd division factor, the duty-cycle will not be 50/50. Setting the Improve Duty Cycle bit of the Generator Control register (GENCTRLn.IDC) will result in a 50/50 duty cycle. 18.6.2.9 External Clock The output clock (GCLK_GEN) of each Generator can be sent to I/O pins (GCLK_IO). SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 183 If the Output Enable bit in the Generator Control register is set (GENCTRLn.OE = 1) and the generator is enabled (GENCTRLn.GENEN=1), the Generator requests its clock source and the GCLK_GEN clock is output to an I/O pin. Note:  The I/O pin (GCLK/IO[n]) must first be configured as output by writing the corresponding PORT registers. If GENCTRLn.OE is 0, the according I/O pin is set to an Output Off Value, which is selected by GENCTRLn.OOV: If GENCTRLn.OOV is '0', the output clock will be low. If this bit is '1', the output clock will be high. In Standby mode, if the clock is output (GENCTRLn.OE=1), the clock on the I/O pin is frozen to the OOV value if the Run In Standby bit of the Generic Control register (GENCTRLn.RUNSTDBY) is zero. Note:  With GENCTRLn.OE=1 and RUNSTDBY=0, entering the Standby mode can take longer due to a clock source dependent delay between turning off Power Domain PDSW. The maximum delay can be equal to the clock source period multiplied by the division factor. If GENCTRLn.RUNSTDBY is '1', the GCLKGEN clock is kept running and output to the I/O pin. Related Links 22.6.3.5 Power Domain Controller 18.6.3 Peripheral Clock Figure 18-4. Peripheral Clock 18.6.3.1 Enabling a Peripheral Clock Before a Peripheral Clock is enabled, one of the Generators must be enabled (GENCTRLn.GENEN) and selected as source for the Peripheral Channel by setting the Generator Selection bits in the Peripheral Channel Control register (PCHCTRL.GEN). Any available Generator can be selected as clock source for each Peripheral Channel. When a Generator has been selected, the peripheral clock is enabled by setting the Channel Enable bit in the Peripheral Channel Control register, PCHCTRLm.CHEN = 1. The PCHCTRLm.CHEN bit must be synchronized to the generic clock domain. PCHCTRLm.CHEN will continue to read as its previous state until the synchronization is complete. 18.6.3.2 Disabling a Peripheral Clock A Peripheral Clock is disabled by writing PCHCTRLm.CHEN=0. The PCHCTRLm.CHEN bit must be synchronized to the Generic Clock domain. PCHCTRLm.CHEN will stay in its previous state until the synchronization is complete. The Peripheral Clock is gated when disabled. Related Links 18.8.4 PCHCTRLm SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 184 18.6.3.3 Selecting the Clock Source for a Peripheral When changing a peripheral clock source by writing to PCHCTRLm.GEN, the peripheral clock must be disabled before re-enabling it with the new clock source setting. This prevents glitches during the transition: 1. Disable the Peripheral Channel by writing PCHCTRLm.CHEN=0 2. Assert that PCHCTRLm.CHEN reads '0' 3. Change the source of the Peripheral Channel by writing PCHCTRLm.GEN 4. Re-enable the Peripheral Channel by writing PCHCTRLm.CHEN=1 Related Links 18.8.4 PCHCTRLm 18.6.3.4 Configuration Lock The peripheral clock configuration can be locked for further write accesses by setting the Write Lock bit in the Peripheral Channel Control register PCHCTRLm.WRTLOCK=1). All writing to the PCHCTRLm register will be ignored. It can only be unlocked by a Power Reset. The Generator source of a locked Peripheral Channel will be locked, too: The corresponding GENCTRLn register is locked, and can be unlocked only by a Power Reset. There is one exception concerning the Generator 0. As it is used as GCLK_MAIN, it cannot be locked. It is reset by any Reset and will start up in a known configuration. The software reset (CTRLA.SWRST) can not unlock the registers. In case of an external Reset, the Generator source will be disabled. Even if the WRTLOCK bit is written to '1' the peripheral channels are disabled (PCHCTRLm.CHEN set to '0') until the Generator source is enabled again. Then, the PCHCTRLm.CHEN are set to '1' again. Related Links 18.8.1 CTRLA 18.6.4 Additional Features 18.6.4.1 Peripheral Clock Enable after Reset The Generic Clock Controller must be able to provide a generic clock to some specific peripherals after a Reset. That means that the configuration of the Generators and Peripheral Channels after Reset is device-dependent. Refer to GENCTRLn.SRC for details on GENCTRLn reset. Refer to PCHCTRLm.SRC for details on PCHCTRLm reset. 18.6.5 Sleep Mode Operation 18.6.5.1 SleepWalking The GCLK module supports the SleepWalking feature. If the system is in a sleep mode where the Generic Clocks are stopped, a peripheral that needs its clock in order to execute a process must request it from the Generic Clock Controller. The Generic Clock Controller receives this request, determines which Generic Clock Generator is involved and which clock source needs to be awakened. It then wakes up the respective clock source, enables the Generator and Peripheral Channel stages successively, and delivers the clock to the peripheral. SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 185 The RUNSTDBY bit in the Generator Control register controls clock output to pin during standby sleep mode. If the bit is cleared, the Generator output is not available on pin. When set, the GCLK can continuously output the generator output to GCLK_IO. Refer to 18.6.2.9 External Clock for details. Related Links 22. PM – Power Manager 18.6.5.2 Minimize Power Consumption in Standby The following table identifies when a Clock Generator is off in Standby Mode, minimizing the power consumption: Table 18-2. Clock Generator n Activity in Standby Mode Request for Clock n present GENCTRLn.RUNSTDBY GENCTRLn.OE Clock Generator n yes - - active no 1 1 active no 1 0 OFF no 0 1 OFF no 0 0 OFF 18.6.5.3 Entering Standby Mode There may occur a delay when the device is put into Standby, until the power is turned off. This delay is caused by running Clock Generators: if the Run in Standby bit in the Generator Control register (GENCTRLn.RUNSTDBY) is '0', GCLK must verify that the clock is turned of properly. The duration of this verification is frequency-dependent. Related Links 22. PM – Power Manager 18.6.6 Synchronization Due to asynchronicity between the main clock domain and the peripheral clock domains, some registers need to be synchronized when written or read. An exception is the Channel Enable bit in the Peripheral Channel Control registers (PCHCTRLm.CHEN). When changing this bit, the bit value must be read-back to ensure the synchronization is complete and to assert glitch free internal operation. Note that changing the bit value under ongoing synchronization will not generate an error. The following registers are synchronized when written: • Generic Clock Generator Control register (GENCTRLn) • Control A register (CTRLA) Required write-synchronization is denoted by the "Write-Synchronized" property in the register description. Related Links 18.8.1 CTRLA 18.8.4 PCHCTRLm SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 186 18.7 Register Summary Offset Name Bit Pos. 0x00 CTRLA 7:0 SWRST 0x01 ... 0x03 Reserved 0x04 SYNCBUSY 7:0 GENCTRL4 GENCTRL3 GENCTRL2 GENCTRL1 GENCTRL0 SWRST 15:8 23:16 31:24 0x08 ... 0x1F Reserved 0x20 GENCTRL0 7:0 SRC[4:0] 15:8 RUNSTDBY DIVSEL OE OOV IDC GENEN 23:16 DIV[7:0] 31:24 DIV[15:8] 0x24 GENCTRL1 7:0 SRC[4:0] 15:8 RUNSTDBY DIVSEL OE OOV IDC GENEN 23:16 DIV[7:0] 31:24 DIV[15:8] 0x28 GENCTRL2 7:0 SRC[4:0] 15:8 RUNSTDBY DIVSEL OE OOV IDC GENEN 23:16 DIV[7:0] 31:24 DIV[15:8] 0x2C GENCTRL3 7:0 SRC[4:0] 15:8 RUNSTDBY DIVSEL OE OOV IDC GENEN 23:16 DIV[7:0] 31:24 DIV[15:8] 0x30 GENCTRL4 7:0 SRC[4:0] 15:8 RUNSTDBY DIVSEL OE OOV IDC GENEN 23:16 DIV[7:0] 31:24 DIV[15:8] 0x34 ... 0x7F Reserved 0x80 PCHCTRL0 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0x84 PCHCTRL1 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0x88 PCHCTRL2 7:0 WRTLOCK CHEN GEN[2:0] SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 187 Offset Name Bit Pos. 15:8 23:16 31:24 0x8C PCHCTRL3 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0x90 PCHCTRL4 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0x94 PCHCTRL5 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0x98 PCHCTRL6 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0x9C PCHCTRL7 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0xA0 PCHCTRL8 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0xA4 PCHCTRL9 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0xA8 PCHCTRL10 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0xAC PCHCTRL11 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0xB0 PCHCTRL12 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0xB4 PCHCTRL13 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 188 Offset Name Bit Pos. 31:24 0xB8 PCHCTRL14 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0xBC PCHCTRL15 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0xC0 PCHCTRL16 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0xC4 PCHCTRL17 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0xC8 PCHCTRL18 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0xCC PCHCTRL19 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 0xD0 PCHCTRL20 7:0 WRTLOCK CHEN GEN[2:0] 15:8 23:16 31:24 18.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to 18.5.8 Register Access Protection. Some registers are synchronized when read and/or written. Synchronization is denoted by the "WriteSynchronized" or the "Read-Synchronized" property in each individual register description. For details, refer to 18.6.6 Synchronization. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 189 • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 190 18.8.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized Bit 7 6 5 4 3 2 1 0 SWRST Access R/W Reset 0 Bit 0 – SWRST Software Reset Writing a zero to this bit has no effect. Setting this bit to 1 will reset all registers in the GCLK to their initial state after a Power Reset, except for generic clocks and associated Generators that have their WRTLOCK bit in PCHCTRLm set to 1. Refer to GENCTRL Reset Value for details on GENCTRL register reset. Refer to PCHCTRL Reset Value for details on PCHCTRL register reset. Due to synchronization, there is a waiting period between setting CTRLA.SWRST and a completed Reset. CTRLA.SWRST and SYNCBUSY.SWRST will both be cleared when the reset is complete. Value Description 0 There is no Reset operation ongoing. 1 A Reset operation is ongoing. SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 191 18.8.2 Synchronization Busy Name:  SYNCBUSY Offset:  0x04 Reset:  0x00000000 Property:  – Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 GENCTRL4 GENCTRL3 GENCTRL2 GENCTRL1 GENCTRL0 SWRST Access R R R R R R Reset 0 0 0 0 0 0 Bits 2, 3, 4, 5, 6 – GENCTRL Generator Control n Synchronization Busy This bit is cleared when the synchronization of the Generator Control n register (GENCTRLn) between clock domains is complete, or when clock switching operation is complete. This bit is set when the synchronization of the Generator Control n register (GENCTRLn) between clock domains is started. Bit 0 – SWRST Software Reset Synchronization Busy This bit is cleared when the synchronization of the CTRLA.SWRST register bit between clock domains is complete. This bit is set when the synchronization of the CTRLA.SWRST register bit between clock domains is started. SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 192 18.8.3 Generator Control Name:  GENCTRLn Offset:  0x20 + n*0x04 [n=0..4] Reset:  0x00000105 Property:  PAC Write-Protection, Write-Synchronized GENCTRLn controls the settings of Generic Generator n (n=0..4). The reset value is 0x00000105 for Generator n=0, else 0x00000000 Bit 31 30 29 28 27 26 25 24 DIV[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DIV[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 RUNSTDBY DIVSEL OE OOV IDC GENEN Access Reset 0 0 0 0 0 1 Bit 7 6 5 4 3 2 1 0 SRC[4:0] Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bits 31:16 – DIV[15:0] Division Factor These bits represent a division value for the corresponding Generator. The actual division factor is dependent on the state of DIVSEL. The number of relevant DIV bits for each Generator can be seen in this table. Written bits outside of the specified range will be ignored. Table 18-3. Division Factor Bits Generic Clock Generator Division Factor Bits Generator 0 8 division factor bits - DIV[7:0] Generator 1 16 division factor bits - DIV[15:0] Generator 2 - 4 8 division factor bits - DIV[7:0] Bit 13 – RUNSTDBY Run in Standby This bit is used to keep the Generator running in Standby as long as it is configured to output to a dedicated GCLK_IO pin. If GENCTRLn.OE is zero, this bit has no effect and the generator will only be running if a peripheral requires the clock. SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 193 Value Description 0 The Generator is stopped in Standby and the GCLK_IO pin state (one or zero) will be dependent on the setting in GENCTRL.OOV. 1 The Generator is kept running and output to its dedicated GCLK_IO pin during Standby mode. Bit 12 – DIVSEL Divide Selection This bit determines how the division factor of the clock source of the Generator will be calculated from DIV. If the clock source should not be divided, DIVSEL must be 0 and the GENCTRLn.DIV value must be either 0 or 1. Value Description 0 The Generator clock frequency equals the clock source frequency divided by GENCTRLn.DIV. 1 The Generator clock frequency equals the clock source frequency divided by 2^(N+1), where N is the Division Factor Bits for the selected generator (refer to GENCTRLn.DIV). Bit 11 – OE Output Enable This bit is used to output the Generator clock output to the corresponding pin (GCLK_IO), as long as GCLK_IO is not defined as the Generator source in the GENCTRLn.SRC bit field. Value Description 0 No Generator clock signal on pin GCLK_IO. 1 The Generator clock signal is output on the corresponding GCLK_IO, unless GCLK_IO is selected as a generator source in the GENCTRLn.SRC bit field. Bit 10 – OOV Output Off Value This bit is used to control the clock output value on pin (GCLK_IO) when the Generator is turned off or the OE bit is zero, as long as GCLK_IO is not defined as the Generator source in the GENCTRLn.SRC bit field. Value Description 0 The GCLK_IO will be LOW when generator is turned off or when the OE bit is zero. 1 The GCLK_IO will be HIGH when generator is turned off or when the OE bit is zero. Bit 9 – IDC Improve Duty Cycle This bit is used to improve the duty cycle of the Generator output to 50/50 for odd division factors. Value Description 0 Generator output clock duty cycle is not balanced to 50/50 for odd division factors. 1 Generator output clock duty cycle is 50/50. Bit 8 – GENEN Generator Enable This bit is used to enable and disable the Generator. Value Description 0 Generator is disabled. 1 Generator is enabled. Bits 4:0 – SRC[4:0] Generator Clock Source Selection These bits select the Generator clock source, as shown in this table. SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 194 Table 18-4. Generator Clock Source Selection Value Name Description 0x00 XOSC XOSC oscillator output 0x01 GCLK_IN Generator input pad (GCLK_IO) 0x02 GCLK_GEN1 Generic clock generator 1 output 0x03 OSCULP32K OSCULP32K oscillator output 0x04 XOSC32K XOSC32K oscillator output 0x05 OSC16M OSC16M oscillator output 0x06 DFLLULP DFLLULP ultra low power output 0x07 FDPLL96M FDPLL96M output 0x08-0x1F Reserved Reserved for future use A Power Reset will reset all GENCTRLn registers. the Reset values of the GENCTRLn registers are shown in table below. Table 18-5. GENCTRLn Reset Value after a Power Reset GCLK Generator Reset Value after a Power Reset 0 0x00000105 others 0x00000000 A User Reset will reset the associated GENCTRL register unless the Generator is the source of a locked Peripheral Channel (PCHCTRLm.WRTLOCK=1). The reset values of the GENCTRL register are as shown in the table below. Table 18-6. GENCTRLn Reset Value after a User Reset GCLK Generator Reset Value after a User Reset 0 0x00000105 others No change if the generator is used by a Peripheral Channel m with PCHCTRLm.WRTLOCK=1 else 0x00000000 Related Links 18.8.4 PCHCTRLm SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 195 18.8.4 Peripheral Channel Control Name:  PCHCTRLm Offset:  0x80 + m*0x04 [m=0..20] Reset:  0x00000000 Property:  PAC Write-Protection PCHTRLm controls the settings of Peripheral Channel number m (m=0..20). Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 WRTLOCK CHEN GEN[2:0] Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 7 – WRTLOCK Write Lock After this bit is set to '1', further writes to the PCHCTRLm register will be discarded. The control register of the corresponding Generator n (GENCTRLn), as assigned in PCHCTRLm.GEN, will also be locked. It can only be unlocked by a Power Reset. Note that Generator 0 cannot be locked. Value Description 0 The Peripheral Channel register and the associated Generator register are not locked 1 The Peripheral Channel register and the associated Generator register are locked Bit 6 – CHEN Channel Enable This bit is used to enable and disable a Peripheral Channel. Value Description 0 The Peripheral Channel is disabled 1 The Peripheral Channel is enabled Bits 2:0 – GEN[2:0] Generator Selection This bit field selects the Generator to be used as the source of a peripheral clock, as shown in the table below: SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 196 Table 18-7. Generator Selection Value Description 0x0 Generic Clock Generator 0 0x1 Generic Clock Generator 1 0x2 Generic Clock Generator 2 0x3 Generic Clock Generator 3 0x4 Generic Clock Generator 4 0x5 Generic Clock Generator 5 0x6 Generic Clock Generator 6 0x7 Generic Clock Generator 7 0xA Generic Clock Generator 10 0xB Generic Clock Generator 11 Table 18-8. Reset Value after a User Reset or a Power Reset Reset PCHCTRLm.GEN PCHCTRLm.CHEN PCHCTRLm.WRTLOCK Power Reset 0x0 0x0 0x0 User Reset If WRTLOCK = 0 : 0x0 If WRTLOCK = 1: no change If WRTLOCK = 0 : 0x0 If WRTLOCK = 1: no change No change A Power Reset will reset all the PCHCTRLm registers. A User Reset will reset a PCHCTRL if WRTLOCK=0, or else, the content of that PCHCTRL remains unchanged. The PCHCTRL register Reset values are shown in the table below, PCHCTRLm Mapping. Table 18-9. PCHCTRLm Mapping index(m) Name Description 0 GCLK_DPLL FDPLL96M input clock source for reference 1 GCLK_DPLL_32K FDPLL96M 32 kHz clock for FDPLL96M internal clock timer 2 GCLK_DFLLULP DFLLULP clock for DFLLULP 3 GCLK_EIC EIC 4 GCLK_FREQM_MSR FREQM Measure 5 GCLK_FREQM_REF FREQM Reference 6 GCLK_EVSYS_CHANNEL_0 EVSYS_CHANNEL_0 7 GCLK_EVSYS_CHANNEL_1 EVSYS_CHANNEL_1 8 GCLK_EVSYS_CHANNEL_2 EVSYS_CHANNEL_2 SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 197 index(m) Name Description 9 GCLK_EVSYS_CHANNEL_3 EVSYS_CHANNEL_3 10 GCLK_SERCOM[0,1,2]_SLOW SERCOM[0,1,2]_SLOW 11 GCLK_SERCOM0_CORE SERCOM0_CORE 12 GCLK_SERCOM1_CORE SERCOM1_CORE 13 GCLK_SERCOM2_CORE SERCOM2_CORE 14 GCLK_TC0, GCLK_TC1 TC0,TC1 15 GCLK_TC2 TC2 16 GCLK_ADC ADC 17 GCLK_AC AC 18 GCLK_DAC DAC 19 GCLK_PTC PTC 20 GCLK_CCL CCL SAM L10/L11 Family GCLK - Generic Clock Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 198 19. MCLK – Main Clock 19.1 Overview The Main Clock (MCLK) controls the synchronous clock generation of the device. Using a clock provided by the Generic Clock Module (GCLK_MAIN) or the DFLLULP (CLK_DFLLULP), the Main Clock Controller provides synchronous system clocks to the CPU and the modules connected to the AHBx and the APBx bus. The synchronous system clocks are divided into a number of clock domains. Each clock domain can run at different frequencies, enabling the user to save power by running peripherals at a relatively low clock frequency, while maintaining high CPU performance or vice versa. In addition, the clock can be masked for individual modules, enabling the user to minimize power consumption. 19.2 Features • Generates CPU, AHB, and APB system clocks – Clock source and division factor from GCLK – Clock prescaler with 1x to 128x division • Safe run-time clock switching from GCLK • Module-level clock gating through maskable peripheral clocks 19.3 Block Diagram Figure 19-1. MCLK Block Diagram MAIN CLOCK CONTROLLER CPU GCLK GCLK_MAIN PERIPHERALS CLK_APBx CLK_AHBx CLK_CPU DFLLULP CLK_DFLLULP CLK_MAIN CKSEL 19.4 Signal Description Not applicable. 19.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 19.5.1 I/O Lines Not applicable. 19.5.2 Power Management The MCLK will operate in all sleep modes if a synchronous clock is required in these modes. Related Links SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 199 22. PM – Power Manager 19.5.3 Clocks The MCLK bus clock (CLK_MCLK_APB) can be enabled and disabled in the Main Clock module, and the default state of CLK_MCLK_APB can be found in the Peripheral Clock Masking section. If this clock is disabled, it can only be re-enabled by a reset. The Generic Clock GCLK_MAIN or the DFLLULP Clock CLK_DFLLULP is required to generate the Main Clocks. GCLK_MAIN is configured in the Generic Clock Controller, and can be re-configured by the user if needed. CLK_DFLLULP is configured in the Oscillators Controller (OSCCTRL). Related Links 18. GCLK - Generic Clock Controller 19.6.2.6 Peripheral Clock Masking 19.5.3.1 Main Clock The main clock CLK_MAIN is the common source for the synchronous clocks. This is fed into the common 8-bit prescaler that is used to generate synchronous clocks to the CPU, AHBx, and APBx modules. 19.5.3.2 CPU Clock The CPU clock (CLK_CPU) is routed to the CPU. Halting the CPU clock inhibits the CPU from executing instructions. 19.5.3.3 APBx and AHBx Clock The APBx clocks (CLK_APBx) and the AHBx clocks (CLK_AHBx) are the root clock source used by modules requiring a clock on the APBx and the AHBx bus. These clocks are always synchronous to the CPU clock, and can run even when the CPU clock is turned off in sleep mode. A clock gater is inserted after the common APB clock to gate any APBx clock of a module on APBx bus, as well as the AHBx clock. 19.5.3.4 Clock Domains The device has these synchronous clock domains: • CPU synchronous clock domain (CPU Clock Domain). Frequency is fCPU. See also the related links for the clock domain partitioning. Related Links 19.6.2.6 Peripheral Clock Masking 19.5.4 DMA Not applicable. 19.5.5 Interrupts The interrupt request line is connected to the Interrupt Controller. Using the MCLK interrupt requires the Interrupt Controller to be configured first. 19.5.6 Events Not applicable. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 200 19.5.7 Debug Operation When the CPU is halted in debug mode, the MCLK continues normal operation. In sleep mode, the clocks generated from the MCLK are kept running to allow the debugger accessing any module. As a consequence, power measurements are incorrect in debug mode. 19.5.8 Register Access Protection All registers with write-access can be write-protected optionally by the Peripheral Access Controller (PAC), except for the following registers: • Interrupt Flag register (INTFLAG) Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. PAC write-protection does not apply to accesses through an external debugger. Related Links 15. PAC - Peripheral Access Controller 19.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 19.5.10 Analog Connections Not applicable. 19.6 Functional Description 19.6.1 Principle of Operation The CLK_MAIN clock signal from the GCLK module or the DFLLULP is the source for the main clock, which in turn is the common root for the synchronous clocks for the CPU, APBx, and AHBx modules. The CLK_MAIN is divided by an 8-bit prescaler. Each of the derived clocks can run from any divided or undivided main clock, ensuring synchronous clock sources for each clock domain. The clock domain (CPU) can be changed on the fly to respond to variable load in the application. The clocks for each module in a clock domain can be masked individually to avoid power consumption in inactive modules. Depending on the sleep mode, some clock domains can be turned off. 19.6.2 Basic Operation 19.6.2.1 Initialization After a Reset, the default clock source of the CLK_MAIN clock (GCLK_MAIN) is started and calibrated before the CPU starts running. The GCLK_MAIN clock is selected as the main clock without any prescaler division. By default, only the necessary clocks are enabled. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 201 Related Links 19.6.2.6 Peripheral Clock Masking 19.6.2.2 Enabling, Disabling, and Resetting The MCLK module is always enabled and cannot be reset. 19.6.2.3 Selecting the Main Clock Source Refer to the Generic Clock Controller description for details on how to configure the clock source of the GCLK_MAIN clock. Refer to the Oscillators Controller (OSCCTRL) description for details on how to configure the clock source of the CLK_DFLLULP clock. Related Links 18. GCLK - Generic Clock Controller 19.6.2.4 Selecting the Synchronous Clock Division Ratio The main clock CLK_MAIN 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 domain by writing the Division (DIV) bits in the CPU Clock Division register CPUDIV, resulting in a CPU clock domain frequency determined by this equation: = ܷܲܥ݂ ݂݉ܽ݅݊ ܸܫܦܷܲܥ If the application attempts to write forbidden values in CPUDIV register, registers are written but these bad values are not used and a violation is reported to the PAC module. Division bits (DIV) can be written without halting or disabling peripheral modules. Writing DIV bits allows a new clock setting to be written to all synchronous clocks belonging to the corresponding clock domain at the same time. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 202 Figure 19-2. Synchronous Clock Selection and Prescaler Prescaler Sleep Controller Sleep mode CLK_AHBx Clock gate CLK_APBx Clock gate APBxDIV AHBxDIV clk_ahb_ip0 clk_ahb_ip1 clk_ahb_ipn clk_apb_ip0 clk_apb_ip1 clk_apb_ipn APBxMASK AHBMASK CPUDIV CLK_CPU GCLK Clock gate Clock gate Clock gate Clock gate Clock gate CLK_MAIN DFLLULP CKSEL Related Links 15. PAC - Peripheral Access Controller 19.6.2.5 Clock Ready Flag There is a slight delay between writing to CPUDIV until the new clock settings become effective. During this interval, the Clock Ready flag in the Interrupt Flag Status and Clear register (INTFLAG.CKRDY) will return zero when read. If CKRDY in the INTENSET register is set to '1', the Clock Ready interrupt will be triggered when the new clock setting is effective. The clock settings (CLKCFG) must not be re-written while INTFLAG. CKRDY reads '0'. The system may become unstable or hang, and a violation is reported to the PAC module. Related Links 15. PAC - Peripheral Access Controller 19.6.2.6 Peripheral Clock Masking It is possible to disable/enable the AHB or APB clock for a peripheral by writing the corresponding bit in the Clock Mask registers (APBxMASK) to '0'/'1'. The default state of the peripheral clocks is shown here. Table 19-1. Peripheral Clock Default State CPU Clock Domain Peripheral Clock Default State CLK_AC_APB Enabled CLK_ADC_APB Enabled SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 203 CPU Clock Domain Peripheral Clock Default State CLK_BRIDGE_A_AHB Enabled CLK_BRIDGE_B_AHB Enabled CLK_BRIDGE_C_AHB Enabled CLK_CCL_APB Enabled CLK_DAC_APB Enabled CLK_DMAC_AHB Enabled CLK_DSU_AHB Enabled CLK_DSU_APB Enabled CLK_EIC_APB Enabled CLK_EVSYS_APB Enabled CLK_FREQM_APB Enabled CLK_GCLK_APB Enabled CLK_HMATRIXHS_AHB Enabled CLK_MCLK_APB Enabled CLK_NVMCTRL_AHB Enabled CLK_NVMCTRL_APB Enabled CLK_OPAMP_APB Enabled CLK_OSCCTRL_APB Enabled CLK_OSC32CTRL_APB Enabled CLK_PAC_AHB Enabled CLK_PAC_APB Enabled CLK_PORT_APB Enabled CLK_PM_APB Enabled CLK_PTC_APB Enabled CLK_RSTC_APB Enabled CLK_RTC_APB Enabled CLK_SERCOM0_APB Enabled CLK_SERCOM1_APB Enabled CLK_SERCOM2_APB(1) Enabled CLK_SUPC_APB Enabled CLK_TC0_APB Enabled CLK_TC1_APB Enabled CLK_TC2_APB Enabled CLK_TRAM_AHB Enabled CLK_WDT_APB Enabled When the APB clock is not provided to a module, its registers cannot be read or written. The module can be re-enabled later by writing the corresponding mask bit to '1'. A module may be connected to several clock domains (for instance, AHB and APB), in which case it will have several mask bits. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 204 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 NVM Controller (NVMCTRL) will cause a problem if the CPU needs to read from the Flash Memory. Switching off the clock to the MCLK module (which contains the mask registers) or the corresponding APBx bridge, will make it impossible to write the mask registers again. In this case, they can only be re-enabled by a system reset. 19.6.3 DMA Operation Not applicable. 19.6.4 Interrupts The peripheral has the following interrupt sources: • Clock Ready (CKRDY): indicates that CPU clocks are ready. This interrupt is a synchronous wakeup source. Each interrupt source has an interrupt flag associated with it. The interrupt flag in the Interrupt Flag Status and Clear (INTFLAG) register is set when the interrupt condition occurs. Each interrupt can be enabled individually by writing a '1' to the corresponding enabling bit in the Interrupt Enable Set (INTENSET) register, and disabled by writing a '1' to the corresponding clearing bit in the Interrupt Enable Clear (INTENCLR) register. An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until the interrupt flag is cleared, the interrupt is disabled or the peripheral is reset. An interrupt flag is cleared by writing a '1' to the corresponding bit in the INTFLAG register. Each peripheral can have one interrupt request line per interrupt source or one common interrupt request line for all the interrupt sources.If the peripheral has one common interrupt request line for all the interrupt sources, the user must read the INTFLAG register to determine which interrupt condition is present. Related Links 22. PM – Power Manager 22.6.3.3 Sleep Mode Controller 19.6.5 Events Not applicable. 19.6.6 Sleep Mode Operation In all IDLE sleep modes, the MCLK is still running on the selected main clock. In STANDBY sleep mode, the MCLK is frozen if no synchronous clock is required. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 205 19.7 Register Summary Offset Name Bit Pos. 0x00 CTRLA 7:0 CKSEL 0x01 INTENCLR 7:0 CKRDY 0x02 INTENSET 7:0 CKRDY 0x03 INTFLAG 7:0 CKRDY 0x04 Reserved 0x05 CPUDIV 7:0 CPUDIV[7:0] 0x06 ... 0x0F Reserved 0x10 AHBMASK 7:0 NVMCTRL PAC Reserved DSU DMAC APBC APBB APBA 15:8 TRAM Reserved Reserved Reserved Reserved 23:16 31:24 0x14 APBAMASK 7:0 GCLK SUPC OSC32KCTR L OSCCTRL RSTC MCLK PM PAC 15:8 Reserved AC PORT FREQM EIC RTC WDT 23:16 31:24 0x18 APBBMASK 7:0 HMATRIXHS NVMCTRL DSU IDAU 15:8 23:16 31:24 0x1C APBCMASK 7:0 ADC TC2 TC1 TC0 SERCOM2 SERCOM1 SERCOM0 EVSYS 15:8 OPAMP CCL TRNG PTC DAC 23:16 31:24 19.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16-, and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers can be write-protected optionally by the Peripheral Access Controller (PAC). This is denoted by the property "PAC Write-Protection" in each individual register description. Refer to the 19.5.8 Register Access Protection for details. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 206 Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 207 19.8.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 CKSEL Access R/W Reset 0 Bit 2 – CKSEL Main Clock Select Value Description 0 The GCLKMAIN clock is selected for the main clock. 1 The DFLLULP clock is selected for the main clock. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 208 19.8.2 Interrupt Enable Clear Name:  INTENCLR Offset:  0x01 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set (INTENSET) register. Bit 7 6 5 4 3 2 1 0 CKRDY Access R/W Reset 0 Bit 0 – CKRDY Clock Ready Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Clock Ready Interrupt Enable bit and the corresponding interrupt request. Value Description 0 The Clock Ready interrupt is enabled and will generate an interrupt request when the Clock Ready Interrupt Flag is set. 1 The Clock Ready interrupt is disabled. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 209 19.8.3 Interrupt Enable Set Name:  INTENSET Offset:  0x02 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear (INTENCLR) register. Bit 7 6 5 4 3 2 1 0 CKRDY Access R/W Reset 0 Bit 0 – CKRDY Clock Ready Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Clock Ready Interrupt Enable bit and enable the Clock Ready interrupt. Value Description 0 The Clock Ready interrupt is disabled. 1 The Clock Ready interrupt is enabled. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 210 19.8.4 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x03 Reset:  0x01 Property:  – Bit 7 6 5 4 3 2 1 0 CKRDY Access R/W Reset 1 Bit 0 – CKRDY Clock Ready This flag is cleared by writing a '1' to the flag. This flag is set when the synchronous CPU, APBx, and AHBx clocks have frequencies as indicated in the CLKCFG registers and will generate an interrupt if INTENCLR/SET.CKRDY is '1'. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Clock Ready interrupt flag. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 211 19.8.5 CPU Clock Division Name:  CPUDIV Offset:  0x05 Reset:  0x01 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 CPUDIV[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 1 Bits 7:0 – CPUDIV[7:0] CPU Clock Division Factor These bits define the division ratio of the main clock prescaler related to the CPU clock domain. Frequencies must never exceed the specified maximum frequency for each clock domain. Value Name Description 0x01 DIV1 Divide by 1 0x02 DIV2 Divide by 2 0x04 DIV4 Divide by 4 0x08 DIV8 Divide by 8 0x10 DIV16 Divide by 16 0x20 DIV32 Divide by 32 0x40 DIV64 Divide by 64 0x80 DIV128 Divide by 128 others - Reserved SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 212 19.8.6 AHB Mask Name:  AHBMASK Offset:  0x10 Reset:  0x000001FFF Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 TRAM Reserved Reserved Reserved Reserved Access R/W R/W R/W R/W R/W Reset 1 1 1 1 1 Bit 7 6 5 4 3 2 1 0 NVMCTRL PAC Reserved DSU DMAC APBC APBB APBA Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 1 1 1 1 1 1 1 1 Bit 12 – TRAM TRAM AHB Clock Enable Value Description 0 The AHB clock for the TRAM is stopped 1 The AHB clock for the TRAM is enabled Bit 11 – Reserved Must Be Set to 1 Bit 11 must always be set to ‘1’ when programming the AHBMASK register. Bit 10 – Reserved Must Be Set to 1 Bit 10 must always be set to ‘1’ when programming the AHBMASK register. Bit 9 – Reserved Must Be Set to 1 Bit 9 must always be set to ‘1’ when programming the AHBMASK register. Bit 8 – Reserved Must Be Set to 1 Bit 8 must always be set to ‘1’ when programming the AHBMASK register. Bit 7 – NVMCTRL NVMCTRL AHB Clock Enable SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 213 Value Description 0 The AHB clock for the NVMCTRL is stopped 1 The AHB clock for the NVMCTRL is enabled Bit 6 – PAC PAC AHB Clock Enable Value Description 0 The AHB clock for the PAC is stopped. 1 The AHB clock for the PAC is enabled. Bit 5 – Reserved Must Be Set to 1 Bit 5 must always be set to ‘1’ when programming the AHBMASK register. Bit 4 – DSU DSU AHB Clock Enable Value Description 0 The AHB clock for the DSU is stopped. 1 The AHB clock for the DSU is enabled. Bit 3 – DMAC DMAC AHB Clock Enable Value Description 0 The AHB clock for the DMAC is stopped. 1 The AHB clock for the DMAC is enabled. Bit 2 – APBC APBC AHB Clock Enable Value Description 0 The AHB clock for the APBC is stopped. 1 The AHB clock for the APBC is enabled Bit 1 – APBB APBB AHB Clock Enable Value Description 0 The AHB clock for the APBB is stopped. 1 The AHB clock for the APBB is enabled. Bit 0 – APBA APBA AHB Clock Enable Value Description 0 The AHB clock for the APBA is stopped. 1 The AHB clock for the APBA is enabled. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 214 19.8.7 APBA Mask Name:  APBAMASK Offset:  0x14 Reset:  0x000007FFF Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Reserved AC PORT FREQM EIC RTC WDT Access R/W R/W R/W R/W R/W R/W R/W Reset 1 1 1 1 1 1 1 Bit 7 6 5 4 3 2 1 0 GCLK SUPC OSC32KCTRL OSCCTRL RSTC MCLK PM PAC Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 1 1 1 1 1 1 1 1 Bit 14 – Reserved For future use Reserved bits are unused and reserved for future use. For compatibility with future devices, always write reserved bits to their reset value. If no reset value is given, write 0. Bit 13 – AC AC APBA Clock Enable Value Description 0 The APBA clock for the AC is stopped. 1 The APBA clock for the AC is enabled. Bit 12 – PORT PORT APBA Clock Enable Value Description 0 The APBA clock for the PORT is stopped. 1 The APBA clock for the PORT is enabled. Bit 11 – FREQM FREQM APBA Clock Enable Value Description 0 The APBA clock for the FREQM is stopped. 1 The APBA clock for the FREQM is enabled. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 215 Bit 10 – EIC EIC APBA Clock Enable Value Description 0 The APBA clock for the EIC is stopped. 1 The APBA clock for the EIC is enabled. Bit 9 – RTC RTC APBA Clock Enable Value Description 0 The APBA clock for the RTC is stopped. 1 The APBA clock for the RTC is enabled. Bit 8 – WDT WDT APBA Clock Enable Value Description 0 The APBA clock for the WDT is stopped. 1 The APBA clock for the WDT is enabled. Bit 7 – GCLK GCLK APBA Clock Enable Value Description 0 The APBA clock for the GCLK is stopped. 1 The APBA clock for the GCLK is enabled. Bit 6 – SUPC SUPC APBA Clock Enable Value Description 0 The APBA clock for the SUPC is stopped. 1 The APBA clock for the SUPC is enabled. Bit 5 – OSC32KCTRL OSC32KCTRL APBA Clock Enable Value Description 0 The APBA clock for the OSC32KCTRL is stopped. 1 The APBA clock for the OSC32KCTRL is enabled. Bit 4 – OSCCTRL OSCCTRL APBA Clock Enable Value Description 0 The APBA clock for the OSCCTRL is stopped. 1 The APBA clock for the OSCCTRL is enabled. Bit 3 – RSTC RSTC APBA Clock Enable Value Description 0 The APBA clock for the RSTC is stopped. 1 The APBA clock for the RSTC is enabled. Bit 2 – MCLK MCLK APBA Clock Enable Value Description 0 The APBA clock for the MCLK is stopped. 1 The APBA clock for the MCLK is enabled. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 216 Bit 1 – PM PM APBA Clock Enable Value Description 0 The APBA clock for the PM is stopped. 1 The APBA clock for the PM is enabled. Bit 0 – PAC PAC APBA Clock Enable Value Description 0 The APBA clock for the PAC is stopped. 1 The APBA clock for the PAC is enabled. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 217 19.8.8 APBB Mask Name:  APBBMASK Offset:  0x18 Reset:  0x00000017 Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 HMATRIXHS NVMCTRL DSU IDAU Access R/W R/W R/W R/W Reset 1 1 1 1 Bit 4 – HMATRIXHS HMATRIXHS APBB Clock Enable Value Description 0 The APBB clock for the HMATRIXHS is stopped 1 The APBB clock for the HMATRIXHS is enabled Bit 2 – NVMCTRL NVMCTRL APBB Clock Enable Value Description 0 The APBB clock for the NVMCTRL is stopped 1 The APBB clock for the NVMCTRL is enabled Bit 1 – DSU DSU APBB Clock Enable Value Description 0 The APBB clock for the DSU is stopped 1 The APBB clock for the DSU is enabled Bit 0 – IDAU IDAU APBB Clock Enable Value Description 0 The APBB clock for the IDAU is stopped 1 The APBB clock for the IDAU is enabled SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 218 19.8.9 APBC Mask Name:  APBCMASK Offset:  0x1C Reset:  0x00001FFF for 32-pin packages / 0x00001FF7 for 24-pin packages Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 OPAMP CCL TRNG PTC DAC Access R/W R R R R Reset 1 1 1 1 1 Bit 7 6 5 4 3 2 1 0 ADC TC2 TC1 TC0 SERCOM2 SERCOM1 SERCOM0 EVSYS Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 1 1 1 1 1 1 1 1 Bit 12 – OPAMP OPAMP APBC Clock Enable Value Description 0 The APBC clock for the OPAMP is stopped. 1 The APBC clock for the OPAMP is enabled. Bit 11 – CCL CCL APBC Mask Clock Enable Value Description 0 The APBC clock for the CCL is stopped. 1 The APBC clock for the CCL is enabled. Bit 10 – TRNG TRNG APBC Mask Clock Enable Value Description 0 The APBC clock for the TRNG is stopped. 1 The APBC clock for the TRNG is enabled. Bit 9 – PTC PTC APBC Mask Clock Enable Value Description 0 The APBC clock for the PTC is stopped. 1 The APBC clock for the PTC is enabled. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 219 Bit 8 – DAC DAC APBC Mask Clock Enable Value Description 0 The APBC clock for the DAC is stopped. 1 The APBC clock for the DAC is enabled. Bit 7 – ADC ADC APBC Mask Clock Enable Value Description 0 The APBC clock for the ADC is stopped. 1 The APBC clock for the ADC is enabled. Bit 6 – TC2 TC2 APBC Mask Clock Enable Value Description 0 The APBC clock for the TC2 is stopped. 1 The APBC clock for the TC2 is enabled. Bit 5 – TC1 TC1 APBC Mask Clock Enable Value Description 0 The APBC clock for the TC1 is stopped. 1 The APBC clock for the TC1 is enabled. Bit 4 – TC0 TC0 APBC Mask Clock Enable Value Description 0 The APBC clock for the TC0 is stopped. 1 The APBC clock for the TC0 is enabled. Bit 3 – SERCOM2 SERCOM2 APBC Mask Clock Enable SERCOM2 Peripheral Clock is disabled for all 24-pin packages as SERCOM2 is not present. Value Description 0 The APBC clock for the SERCOM2 is stopped. 1 The APBC clock for the SERCOM2 is enabled. Bit 2 – SERCOM1 SERCOM1 APBC Mask Clock Enable Value Description 0 The APBC clock for the SERCOM1 is stopped. 1 The APBC clock for the SERCOM1 is enabled. Bit 1 – SERCOM0 SERCOM0 APBC Mask Clock Enable Value Description 0 The APBC clock for the SERCOM0 is stopped. 1 The APBC clock for the SERCOM0 is enabled. Bit 0 – EVSYS EVSYS APBC Clock Enable SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 220 Value Description 0 The APBC clock for the EVSYS is stopped. 1 The APBC clock for the EVSYS is enabled. SAM L10/L11 Family MCLK – Main Clock © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 221 20. FREQM – Frequency Meter 20.1 Overview The Frequency Meter (FREQM) can be used to accurately measure the frequency of a clock by comparing it to a known reference clock. 20.2 Features • Ratio can be measured with 24-bit accuracy • Accurately measures the frequency of an input clock with respect to a reference clock • Reference clock can be selected from the available GCLK_FREQM_REF sources • Measured clock can be selected from the available GCLK_FREQM_MSR sources 20.3 Block Diagram Figure 20-1. FREQM Block Diagram ENABLE VALUE REFNUM INTFLAG GCLK_FREQM_REF GCLK_FREQM_MSR DONE START COUNTER TIMER CLK_MSR CLK_REF_MUX EN EN DIVREF DIV8 20.4 Signal Description Not applicable. 20.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 20.5.1 I/O Lines The GCLK I/O lines (GCLK_IO[7:0]) can be used as measurement or reference clock sources. This requires the I/O pins to be configured. SAM L10/L11 Family FREQM – Frequency Meter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 222 20.5.2 Power Management The FREQM will continue to operate in idle sleep mode where the selected source clock is running. The FREQM’s interrupts can be used to wake up the device from idle sleep mode. Refer to the Power Manager chapter for details on the different sleep modes. Related Links 22. PM – Power Manager 20.5.3 Clocks The clock for the FREQM bus interface (CLK_APB_FREQM) is enabled and disabled by the Main Clock Controller, the default state of CLK_APB_FREQM can be found in Peripheral Clock Masking. Two generic clocks are used by the FREQM: Reference Clock (GCLK_FREQM_REF) and Measurement Clock (GCLK_FREQM_MSR). GCLK_FREQM_REF is required to clock the internal reference timer, which acts as the frequency reference. GCLK_FREQM_MSR is required to clock a ripple counter for frequency measurement. These clocks must be configured and enabled in the generic clock controller before using the FREQM. Related Links 19. MCLK – Main Clock 19.6.2.6 Peripheral Clock Masking 18. GCLK - Generic Clock Controller 20.5.4 DMA Not applicable. 20.5.5 Interrupts The interrupt request line is connected to the interrupt controller. Using FREQM interrupt requires the interrupt controller to be configured first. 20.5.6 Events Not applicable 20.5.7 Debug Operation When the CPU is halted in debug mode the FREQM continues its normal operation. The FREQM cannot be halted when the CPU is halted in debug mode. If the FREQM is configured in a way that requires it to be periodically serviced by the CPU, improper operation or data loss may result during debugging. 20.5.8 Register Access Protection All registers with write-access can be write-protected optionally by the Peripheral Access Controller (PAC), except the following registers: • Control B register (CTRLB) • Interrupt Flag Status and Clear register (INTFLAG) • Status register (STATUS) Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. Write-protection does not apply to accesses through an external debugger. SAM L10/L11 Family FREQM – Frequency Meter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 223 Related Links 15. PAC - Peripheral Access Controller 20.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 20.6 Functional Description 20.6.1 Principle of Operation FREQM counts the number of periods of the measured clock (GCLK_FREQM_MSR) with respect to the reference clock (GCLK_FREQM_REF). The measurement is done for a period of REFNUM/fCLK_REF and stored in the Value register (VALUE.VALUE). REFNUM is the number of Reference clock cycles selected in the Configuration A register (CFGA.REFNUM). The frequency of the measured clock, ݂CLK_MSR, is calculated by ݂CLK_MSR = VALUE REFNUM ݂CLK_REF 20.6.2 Basic Operation 20.6.2.1 Initialization Before enabling FREQM, the device and peripheral must be configured: • Each of the generic clocks (GCLK_FREQM_REF and GCLK_FREQM_MSR) must be configured and enabled. • Important:  The reference clock must be slower than the measurement clock. • Write the number of Reference clock cycles for which the measurement is to be done in the Configuration A register (CFGA.REFNUM). This must be a non-zero number. The following register is enable-protected, meaning that it can only be written when the FREQM is disabled (CTRLA.ENABLE=0): • Configuration A register (CFGA) Enable-protection is denoted by the "Enable-Protected" property in the register description. Related Links 18. GCLK - Generic Clock Controller SAM L10/L11 Family FREQM – Frequency Meter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 224 20.6.2.2 Enabling, Disabling and Resetting The FREQM is enabled by writing a '1' to the Enable bit in the Control A register (CTRLA.ENABLE). The peripheral is disabled by writing CTRLA.ENABLE=0. The FREQM is reset by writing a '1' to the Software Reset bit in the Control A register (CTRLA.SWRST). On software reset, all registers in the FREQM will be reset to their initial state, and the FREQM will be disabled. Then ENABLE and SWRST bits are write-synchronized. Related Links 20.6.7 Synchronization 20.6.2.3 Measurement In the Configuration A register, the Number of Reference Clock Cycles field (CFGA.REFNUM) selects the duration of the measurement. The measurement is given in number of GCLK_FREQM_REF periods. Note:  The REFNUM field must be written before the FREQM is enabled. After the FREQM is enabled, writing a '1' to the START bit in the Control B register (CTRLB.START) starts the measurement. The BUSY bit in Status register (STATUS.BUSY) is set when the measurement starts, and cleared when the measurement is complete. There is also an interrupt request for Measurement Done: When the Measurement Done bit in Interrupt Enable Set register (INTENSET.DONE) is '1' and a measurement is finished, the Measurement Done bit in the Interrupt Flag Status and Clear register (INTFLAG.DONE) will be set and an interrupt request is generated. The result of the measurement can be read from the Value register (VALUE.VALUE). The frequency of the measured clock GCLK_FREQM_MSR is then: ݂CLK_MSR = VALUE REFNUM ݂CLK_REF Note:  In order to make sure the measurement result (VALUE.VALUE[23:0]) is valid, the overflow status (STATUS.OVF) should be checked. In case an overflow condition occurred, indicated by the Overflow bit in the STATUS register (STATUS.OVF), either the number of reference clock cycles must be reduced (CFGA.REFNUM), or a faster reference clock must be configured. Once the configuration is adjusted, clear the overflow status by writing a '1' to STATUS.OVF. Then another measurement can be started by writing a '1' to CTRLB.START. 20.6.3 DMA Operation Not applicable. 20.6.4 Interrupts The FREQM has one interrupt source: • DONE: A frequency measurement is done. The interrupt flag in the Interrupt Flag Status and Clear (20.8.6 INTFLAG) register is set when the interrupt condition occurs. The interrupt can be enabled by writing a '1' to the corresponding bit in the Interrupt Enable Set (20.8.5 INTENSET) register, and disabled by writing a '1' to the corresponding bit in the Interrupt Enable Clear (20.8.4 INTENCLR) register. An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until the interrupt flag is cleared, the interrupt is disabled, or the SAM L10/L11 Family FREQM – Frequency Meter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 225 FREQM is reset. See 20.8.6 INTFLAG for details on how to clear interrupt flags. All interrupt requests from the peripheral are ORed together on system level to generate one combined interrupt request to the NVIC. The user must read the 20.8.6 INTFLAG register to determine which interrupt condition is present. This interrupt is a synchronous wake-up source. Note that interrupts must be globally enabled for interrupt requests to be generated. 20.6.5 Events Not applicable. 20.6.6 Sleep Mode Operation The FREQM will continue to operate in idle sleep mode where the selected source clock is running. The FREQM’s interrupts can be used to wake up the device from idle sleep mode. For lowest chip power consumption in sleep modes, FREQM should be disabled before entering a sleep mode. Related Links 22. PM – Power Manager 20.6.7 Synchronization Due to asynchronicity between the main clock domain and the peripheral clock domains, some registers need to be synchronized when written or read. The following bits and registers are write-synchronized: • Software Reset bit in Control A register (CTRLA.SWRST) • Enable bit in Control A register (CTRLA.ENABLE) Required write-synchronization is denoted by the "Write-Synchronized" property in the register description. SAM L10/L11 Family FREQM – Frequency Meter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 226 20.7 Register Summary Offset Name Bit Pos. 0x00 CTRLA 7:0 ENABLE SWRST 0x01 CTRLB 7:0 START 0x02 CFGA 7:0 REFNUM[7:0] 15:8 DIVREF 0x04 ... 0x07 Reserved 0x08 INTENCLR 7:0 DONE 0x09 INTENSET 7:0 DONE 0x0A INTFLAG 7:0 DONE 0x0B STATUS 7:0 OVF BUSY 0x0C SYNCBUSY 7:0 ENABLE SWRST 15:8 23:16 31:24 0x10 VALUE 7:0 VALUE[7:0] 15:8 VALUE[15:8] 23:16 VALUE[23:16] 31:24 20.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16-, and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers require synchronization when read and/or written. Synchronization is denoted by the "Read-Synchronized" and/or "Write-Synchronized" property in each individual register description. Some registers are enable-protected, meaning they can only be written when the module is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family FREQM – Frequency Meter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 227 20.8.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized, Read-Synchronized Bit 7 6 5 4 3 2 1 0 ENABLE SWRST Access R/W R/W Reset 0 0 Bit 1 – ENABLE Enable Due to synchronization there is delay from writing CTRLA.ENABLE until the peripheral is enabled/ disabled. The value written to CTRLA.ENABLE will read back immediately and the ENABLE bit in the Synchronization Busy register (SYNCBUSY.ENABLE) will be set. SYNCBUSY.ENABLE will be cleared when the operation is complete. This bit is not enable-protected. Value Description 0 The peripheral is disabled. 1 The peripheral is enabled. Bit 0 – SWRST Software Reset Writing a '0' to this bit has no effect. Writing a '1' to this bit resets all registers in the FREQM to their initial state, and the FREQM will be disabled. Writing a '1' to this bit will always take precedence, meaning that all other writes in the same write-operation will be discarded. Due to synchronization there is a delay from writing CTRLA.SWRST until the Reset is complete. CTRLA.SWRST and SYNCBUSY.SWRST will both be cleared when the Reset is complete. This bit is not enable-protected. Value Description 0 There is no ongoing Reset operation. 1 The Reset operation is ongoing. SAM L10/L11 Family FREQM – Frequency Meter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 228 20.8.2 Control B Name:  CTRLB Offset:  0x01 Reset:  0x00 Property:  – Bit 7 6 5 4 3 2 1 0 START Access W Reset 0 Bit 0 – START Start Measurement Value Description 0 Writing a '0' has no effect. 1 Writing a '1' starts a measurement. SAM L10/L11 Family FREQM – Frequency Meter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 229 20.8.3 Configuration A Name:  CFGA Offset:  0x02 Reset:  0x0000 Property:  PAC Write-Protection, Enable-protected Bit 15 14 13 12 11 10 9 8 DIVREF Access R/W Reset 0 Bit 7 6 5 4 3 2 1 0 REFNUM[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 – DIVREF Divide Reference Clock Divides the reference clock by 8 Value Description 0 The reference clock is divided by 1. 1 The reference clock is divided by 8. Bits 7:0 – REFNUM[7:0] Number of Reference Clock Cycles Selects the duration of a measurement in number of CLK_FREQM_REF cycles. This must be a non-zero value, i.e. 0x01 (one cycle) to 0xFF (255 cycles). SAM L10/L11 Family FREQM – Frequency Meter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 230 20.8.4 Interrupt Enable Clear Name:  INTENCLR Offset:  0x08 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DONE Access R/W Reset 0 Bit 0 – DONE Measurement Done Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Measurement Done Interrupt Enable bit, which disables the Measurement Done interrupt. Value Description 0 The Measurement Done interrupt is disabled. 1 The Measurement Done interrupt is enabled. SAM L10/L11 Family FREQM – Frequency Meter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 231 20.8.5 Interrupt Enable Set Name:  INTENSET Offset:  0x09 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DONE Access R/W Reset 0 Bit 0 – DONE Measurement Done Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Measurement Done Interrupt Enable bit, which enables the Measurement Done interrupt. Value Description 0 The Measurement Done interrupt is disabled. 1 The Measurement Done interrupt is enabled. SAM L10/L11 Family FREQM – Frequency Meter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 232 20.8.6 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x0A Reset:  0x00 Property:  – Bit 7 6 5 4 3 2 1 0 DONE Access R/W Reset 0 Bit 0 – DONE Mesurement Done This flag is cleared by writing a '1' to it. This flag is set when the STATUS.BUSY bit has a one-to-zero transition. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the DONE interrupt flag. SAM L10/L11 Family FREQM – Frequency Meter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 233 20.8.7 Status Name:  STATUS Offset:  0x0B Reset:  0x00 Property:  – Bit 7 6 5 4 3 2 1 0 OVF BUSY Access R/W R Reset 0 0 Bit 1 – OVF Sticky Count Value Overflow This bit is cleared by writing a '1' to it. This bit is set when an overflow condition occurs to the value counter. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the OVF status. Bit 0 – BUSY FREQM Status Value Description 0 No ongoing frequency measurement. 1 Frequency measurement is ongoing. SAM L10/L11 Family FREQM – Frequency Meter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 234 20.8.8 Synchronization Busy Name:  SYNCBUSY Offset:  0x0C Reset:  0x00000000 Property:  – Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 ENABLE SWRST Access R R Reset 0 0 Bit 1 – ENABLE Enable This bit is cleared when the synchronization of CTRLA.ENABLE is complete. This bit is set when the synchronization of CTRLA.ENABLE is started. Bit 0 – SWRST Synchronization Busy This bit is cleared when the synchronization of CTRLA.SWRST is complete. This bit is set when the synchronization of CTRLA.SWRST is started. SAM L10/L11 Family FREQM – Frequency Meter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 235 20.8.9 Value Name:  VALUE Offset:  0x10 Reset:  0x00000000 Property:  – Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 VALUE[23:16] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 VALUE[15:8] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 VALUE[7:0] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bits 23:0 – VALUE[23:0] Measurement Value Result from measurement. SAM L10/L11 Family FREQM – Frequency Meter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 236 21. RSTC – Reset Controller 21.1 Overview The Reset Controller (RSTC) manages the reset of the microcontroller. It issues a microcontroller reset, sets the device to its initial state and allows the reset source to be identified by software. 21.2 Features • Reset the microcontroller and set it to an initial state according to the reset source • Reset cause register for reading the reset source from the application code • Multiple reset sources – Power supply reset sources: POR, BOD12, BOD33 – User reset sources: External reset (RESET), Watchdog reset, and System Reset Request 21.3 Block Diagram Figure 21-1. Reset System RESET CONTROLLER BODCORE BODVDD POR WDT RESET RESET SOURCES RTC 32kHz clock sources WDT with ALWAYSON GCLK with WRTLOCK Debug Logic CPU Other Modules RCAUSE 21.4 Signal Description Signal Name Type Description RESET Digital input External reset One signal can be mapped on several pins. 21.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. SAM L10/L11 Family RSTC – Reset Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 237 21.5.1 I/O Lines Not applicable. 21.5.2 Power Management The Reset Controller module is always on. 21.5.3 Clocks The RSTC bus clock (CLK_RSTC_APB) can be enabled and disabled in the Main Clock Controller. Related Links 19. MCLK – Main Clock 19.6.2.6 Peripheral Clock Masking 21.5.4 DMA Not applicable. 21.5.5 Interrupts Not applicable. 21.5.6 Events Not applicable. 21.5.7 Debug Operation When the CPU is halted in debug mode, the RSTC continues normal operation. 21.5.8 Register Access Protection All registers with write-access can be optionally write-protected by the Peripheral Access Controller (PAC). Note:  Optional write-protection is indicated by the "PAC Write-Protection" property in the register description. Write-protection does not apply for accesses through an external debugger. 21.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 21.5.10 Analog Connections Not applicable. SAM L10/L11 Family RSTC – Reset Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 238 21.6 Functional Description 21.6.1 Principle of Operation The Reset Controller collects the various Reset sources and generates Reset for the device. 21.6.2 Basic Operation 21.6.2.1 Initialization After a power-on Reset, the RSTC is enabled and the Reset Cause (RCAUSE) register indicates the POR source. 21.6.2.2 Enabling, Disabling, and Resetting The RSTC module is always enabled. 21.6.2.3 Reset Causes and Effects The latest Reset cause is available in RCAUSE register, and can be read during the application boot sequence in order to determine proper action. These are the groups of Reset sources: • Power supply Reset: Resets caused by an electrical issue. It covers POR and BODs Resets • User Reset: Resets caused by the application. It covers external Resets, system Reset requests and watchdog Resets The following table lists the parts of the device that are reset, depending on the Reset type. Table 21-1. Effects of the Different Reset Causes Power Supply Reset User Reset POR, BOD33, BOD12 External Reset WDT Reset, System Reset Request RTC, OSC32KCTRL, RSTC Y N N GCLK with WRTLOCK Y N N Debug logic Y Y N Others Y Y Y The external Reset is generated when pulling the RESET pin low. The POR, BOD12, and BOD33 Reset sources are generated by their corresponding module in the Supply Controller Interface (SUPC). The WDT Reset is generated by the Watchdog Timer. The System Reset Request is a Reset generated by the CPU when asserting the SYSRESETREQ bit located in the Reset Control register of the CPU (for details refer to the ARM® Cortex™ Technical Reference Manual on http://www.arm.com). Note:  Refer to the Timing Characteristics section of the Electrical Characteristics chapter. Related Links 26. WDT – Watchdog Timer 25. SUPC – Supply Controller SAM L10/L11 Family RSTC – Reset Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 239 46.14.1 External Reset Pin 21.6.3 Additional Features Not applicable. 21.6.4 DMA Operation Not applicable. 21.6.5 Interrupts Not applicable. 21.6.6 Events Not applicable. 21.6.7 Sleep Mode Operation The RSTC module is active in all sleep modes. SAM L10/L11 Family RSTC – Reset Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 240 21.7 Register Summary Offset Name Bit Pos. 0x00 RCAUSE 7:0 SYST WDT EXT BOD33 BOD12 POR 21.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to 21.5.8 Register Access Protection. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family RSTC – Reset Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 241 21.8.1 Reset Cause Name:  RCAUSE Offset:  0x00 Property:  – When a Reset occurs, the bit corresponding to the Reset source is set to '1' and all other bits are written to '0'. Bit 7 6 5 4 3 2 1 0 SYST WDT EXT BOD33 BOD12 POR Access R R R R R R Reset x x x x x x Bit 6 – SYST System Reset Request This bit is set if a System Reset Request has occurred. Refer to the Cortex processor documentation for more details. Bit 5 – WDT Watchdog Reset This bit is set if a Watchdog Timer Reset has occurred. Bit 4 – EXT External Reset This bit is set if an external Reset has occurred. Bit 2 – BOD33  Brown Out 33 Detector Reset This bit is set if a BOD33 Reset has occurred. Bit 1 – BOD12  Brown Out 12 Detector Reset This bit is set if a BOD12 Reset has occurred. Bit 0 – POR Power On Reset This bit is set if a POR has occurred. SAM L10/L11 Family RSTC – Reset Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 242 22. PM – Power Manager 22.1 Overview The Power Manager (PM) controls the sleep modes and the power domain gating of the device. Various sleep modes are provided in order to fit power consumption requirements. This enables the PM to stop unused modules in order to save power. In active mode, the CPU is executing application code. When the device enters a sleep mode, program execution is stopped and some modules and clock domains are automatically switched off by the PM according to the sleep mode. The application code decides which sleep mode to enter and when. Interrupts from enabled peripherals and all enabled reset sources can restore the device from a sleep mode to active mode. Performance level technique consists of adjusting the regulator output voltage to reduce power consumption. The user can select on the fly the performance level configuration which best suits the application. The power domain gating technique enables the PM to turn off unused power domain supplies individually, while keeping others powered up. Based on activity monitoring, power domain gating is managed automatically by hardware without software intervention. This technique is transparent for the application while minimizing the static consumption. The user can also manually control which power domains will be turned on and off in standby sleep mode. The internal state of the logic is retained (retention state) allowing the application context to be kept in non-active states. 22.2 Features • Power management control – Sleep modes: Idle, Standby, and Off – Performance levels: PL0 and PL2 – SleepWalking available in Standby mode. – Full retention state in Standby mode • Power Domain Control – Standby Sleep Mode with static power gating – SleepWalking extension to power gating – SRAM sub-blocks retention in Standby mode SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 243 22.3 Block Diagram Figure 22-1. PM Block Diagram SLEEP MODE CONTROLLER PERFORMANCE LEVEL CONTROLLER SUPPLY CONTROLLER MAIN CLOCK CONTROLLER SLEEPCFG PLCF POWER DOMAIN CONTROLLER POWER MANAGER STDBYCFG POWER LEVEL SWITCHES FOR POWER DOMAINS 22.4 Signal Description Not applicable. 22.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 22.5.1 I/O Lines Not applicable. 22.5.2 Clocks The PM bus clock (CLK_PM_APB) can be enabled and disabled in the Main Clock module. If this clock is disabled, it can only be re-enabled by a system reset. 22.5.3 DMA Not applicable. 22.5.4 Interrupts The interrupt request line is connected to the interrupt controller. Using the PM interrupt requires the interrupt controller to be configured first. 22.5.5 Events Not applicable. 22.5.6 Debug Operation When the CPU is halted in debug mode, the PM continues normal operation. If standby sleep mode is requested by the system while in debug mode, the power domains are not turned off. As a consequence, power measurements while in debug mode are not relevant. If OFF sleep mode is requested by the system while in debug mode, the core domains are kept on, and the debug modules are kept running to allow the debugger to access internal registers. When exiting the OFF mode upon a reset condition, the core domains are reset except the debug logic, allowing users to keep using their current debug session. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 244 Hot plugging in standby mode is supported except if the power domain PDSW is in retention state. Cold plugging in OFF mode is supported as long as the reset duration is superior to (Tmin). 22.5.7 Register Access Protection Registers with write-access can be write-protected optionally by the peripheral access controller (PAC). PAC Write-Protection is not available for the following registers: • Interrupt Flag register (INTFLAG). Optional PAC Write-Protection is denoted by the "PAC Write-Protection" property in each individual register description. Write-protection does not apply to accesses through an external debugger. Related Links 15. PAC - Peripheral Access Controller 22.5.8 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 22.5.9 Analog Connections Not applicable. 22.6 Functional Description 22.6.1 Terminology The following is a list of terms used to describe the Power Managemement features of this microcontroller. 22.6.1.1 Performance Levels To help balance between performance and power consumption, the device has two performance levels. Each of the performance levels has a maximum operating frequency and a corresponding maximum consumption in µA/MHz. It is the application's responsibility to configure the appropriate PL depending on the application activity level. When the application selects a new PL, the voltage applied on the full logic area moves from one value to another. This voltage scaling technique allows to reduce the active power consumption while decreasing the maximum frequency of the device. 22.6.1.1.1 PL0 Performance Level 0 (PL0) provides the maximum energy efficiency configuration. Refer to the Electrical Characteristics chapters for details on energy consumption and maximum operating frequency. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 245 22.6.1.1.2 PL2 Performance Level 2 (PL2) provides the maximum operating frequency. Refer to the Electrical Characteristics chapters for details on energy consumption and maximum operating frequency. 22.6.1.2 Power Domains In addition to the supply domains, such as VDDIO and VDDANA, the device provides these power domains: • PDSW • PDAO The PDSW is a "switchable power domain". In standby sleep mode, it can be turned off to save leakage consumption according to user configuration. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 246 Figure 22-2. Power Domain Partitioning PDAO (Power Domain Always On) PDSW (Power Domain Switchable) 6 x SERCOM 8 x Timer Counter AHB-APB BRIDGE C M M High-Speed Bus Matrix PORT PORT SERIAL SWDIO WIRE S Cortex-M23 PROCESSOR Fmax 32 MHz SWCLK DEVICE SERVICE UNIT AHB-APB BRIDGE A 10-CHANNEL 12-bit ADC 1MSPS AIN[9..0] VREFA AIN[3..0] S SRAM CONTROLLER 16/8/8 KB RAM (SAM L11) - 16/8/4 KB RAM (SAM L10) M 3x TIMER / COUNTER EVENT SYSTEM S 3x SERCOM 2x ANALOG COMPARATORS PERIPHERAL TOUCH CONTROLLER AHB-APB BRIDGE B S PAD[0] WO[1] PAD[1] PAD[2] PAD[3] WO[0] VREFB 2KB Data Flash NVM CONTROLLER M DMA IOBUS DMA DMA DMA S REAL-TIME COUNTER WATCHDOG TIMER RESET OSCILLATORS CONTROLLER XOUT XIN XOUT32 XIN32 OSCULP32K OSC16M XOSC32K XOSC EXTERNAL INTERRUPT CONTROLLER MAIN CLOCKS CONTROLLER EXTINT[7..0] NMI GCLK_IO[4..0] FDPLL96M GENERIC CLOCK CONTROLLER POWER MANAGER RESET CONTROLLER OSC32K CONTROLLER SUPPLY CONTROLLER VREF BOD33 TRNG IN[5..0] CCL OUT[1..0] FREQUENCY METER DMA IN[3:0] VOUT 10-bit DAC 350kSPS DMA 256 Bytes TrustRAM PERIPHERAL ACCESS CONTROLLER DFLLULP OUT[3:0] CMP[1..0] VREFA 8 KB ROM S IDAU TrustZone for ARMv8-M Crypto Accelerators (AES128, SHA256, GCM) Bootloader Authentication 64/32/16 KB Flash with Cache Data Scrambling EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT EVENT CRC-32 3x OPAMP OA[0..2]POS OA[0..2]NEG SAM L11 Added Features MPU Voltage Regulators BOD12 XY[19..0] OA0OUT / OA2OUT SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 247 22.6.1.2.1 PDSW - Power Domain Switchable PDSW is the switchable power domain. It contains the Event System, Generic Clock Controller, Main Clock Controller, Oscillator Controller, Non-Volatile Memory Controller, DMA Controller, the Device Service Unit, and the ARM core. PDSW also contains a number of peripherals that allow the device to wake up from an interrupt: SERCOM, Timer, ADC, DAC, OPAMP, CCL, PTC. 22.6.1.2.2 PDAO - Power Domain Always On PDAO contains all controllers located in the always-on domain. It is powered when in Active, Idle, or Standby mode. 22.6.1.3 Sleep Modes The device can be set in a sleep mode. In sleep mode, the CPU is stopped and the peripherals are either active or idle, according to the sleep mode depth: • Idle sleep mode: The CPU is stopped. Synchronous clocks are stopped except when requested. The logic is retained. • Standby sleep mode: The CPU is stopped as well as the peripherals. The logic is retained, and power domain gating can be used to reduce power consumption further. • Off sleep mode: The entire device is powered off. 22.6.1.4 Power Domain States and Gating In Standby sleep mode, the Power Domain Gating technique allows for selecting the state of PDSW power domain automatically (e.g. for executing sleepwalking tasks) or manually: Active State The power domain is powered according to the performance level Retention State The main voltage supply for the power domain is switched off, while maintaining a secondary low-power supply for sequential cells. The logic context is restored when waking up. 22.6.2 Principle of Operation In active mode, all clock domains and power domains are active, allowing software execution and peripheral operation. The PM Sleep Mode Controller allows to save power by choosing between different sleep modes depending on application requirements, see 22.6.3.3 Sleep Mode Controller. The PM Performance Level Controller allows to optimize either for low power consumption or high performance. The PM Power Domain Controller allows to reduce the power consumption in standby mode even further. 22.6.3 Basic Operation 22.6.3.1 Initialization After a Power-on Reset (POR), the PM is enabled, the device is in Active mode, the performance level is PL0 (the lowest power consumption) and all the power domains are in active state. 22.6.3.2 Enabling, Disabling and Resetting The PM is always enabled and can not be reset. 22.6.3.3 Sleep Mode Controller Sleep mode is entered by executing the Wait For Interrupt instruction (WFI). The Sleep Mode bits in the Sleep Configuration register (SLEEPCFG.SLEEPMODE) select the level of the sleep mode. Note:  A small latency happens between the store instruction and actual writing of the SLEEPCFG register due to bridges. Software must ensure that the SLEEPCFG register reads the desired value before issuing a WFI instruction. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 248 Note:  After power-up, the MAINVREG low power mode takes some time to stabilize. Once stabilized, the SUPC->STATUS.ULPVREFRDY bit is set. Before entering Standby, software must ensure that the SUPC->STATUS.ULPVREFRDY bit is set. Table 22-1. Sleep Mode Entry and Exit Table Mode Mode Entry Wake-Up Sources IDLE SLEEPCFG.SLEEPMODE = IDLE _n Synchronous (2) (APB, AHB), asynchronous (1) STANDBY SLEEPCFG.SLEEPMODE = STANDBY Synchronous(3), Asynchronous OFF SLEEPCFG.SLEEPMODE = OFF External Reset Note:  1. Asynchronous: interrupt generated on generic clock, external clock, or external event. 2. Synchronous: interrupt generated on the APB clock. 3. Synchronous interrupt only for peripherals configured to run in standby. Note:  The type of wake-up sources (synchronous or asynchronous) is given in each module interrupt section. The sleep modes (idle, standby, and off) and their effect on the clocks activity, the regulator and the NVM state are described in the table and the sections below. Refer to Power Domain Controller for the power domain gating effect. Table 22-2. Sleep Mode Overview Mode Main clock CPU AHBx and APBx clock GCLK clocks Oscillators Regulator NVM ONDEMAND = 0 ONDEMAND = 1 Active Run Run Run Run(3) Run Run if requested MAINVREG active IDLE Run Stop Stop(1) Run(3) Run Run if requested MAINVREG active STANDBY Stop(1) Stop Stop(1) Stop(1) Run if requested or RUNSTDBY=1 Run if requested MAINVREG in low power mode Ultra Low- power OFF Stop Stop Stop OFF OFF OFF OFF OFF Note:  1. Running if requested by peripheral during SleepWalking. 2. Running during SleepWalking. 3. Following On-Demand Clock Request principle. 22.6.3.3.1 IDLE Mode IDLE mode allows power optimization with the fastest wake-up time. The CPU is stopped, and peripherals are still working. As in Active mode, the AHBx and APBx clocks for peripheral are still provided if requested. As the main clock source is still running, wake-up time is very fast. • Entering Idle mode: The Idle mode is entered by executing the WFI instruction. Additionally, if the SLEEPONEXIT bit in the Cortex System Control register (SCR) is set, the Idle mode will be entered when the CPU exits the lowest priority ISR (Interrupt Service Routine, refer to the ARM Cortex SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 249 documentation for details). This mechanism can be useful for applications that only require the processor to run when an interrupt occurs. Before entering the Idle mode, the user must select the Idle Sleep mode in the Sleep Configuration register (SLEEPCFG.SLEEPMODE=IDLE). • Exiting Idle mode: The processor wakes the system up when it detects any non-masked interrupt with sufficient priority to cause exception entry. The system goes back to the Active mode. The CPU and affected modules are restarted. GCLK clocks, regulators and RAM are not affected by the Idle Sleep mode and operate in normal mode. 22.6.3.3.2 STANDBY Mode The Standby mode is the lowest power configuration while keeping the state of the logic and the content of the RAM. In this mode, all clocks are stopped except those configured to be running sleepwalking tasks. The clocks can also be active on request or at all times, depending on their on-demand and run-in-standby settings. Either synchronous (CLK_APBx or CLK_AHBx) or generic (GCLK_x) clocks or both can be involved in sleepwalking tasks. This is the case when for example the SERCOM RUNSTDBY bit is written to '1'. • Entering Standby mode: This mode is entered by executing the WFI instruction after writing the Sleep Mode bit in the Sleep Configuration register (SLEEPCFG.SLEEPMODE=STANDBY). The SLEEPONEXIT feature is also available as in Idle mode. • Exiting Standby mode: Any peripheral able to generate an asynchronous interrupt can wake up the system. For example, a peripheral running on a GCLK clock can trigger an interrupt. When the enabled asynchronous wake-up event occurs and the system is woken up, the device will either execute the interrupt service routine or continue the normal program execution according to the Priority Mask Register (PRIMASK) configuration of the CPU. Refer to 22.6.3.5 Power Domain Controller for the RAM state. The regulator operates in Low-Power mode by default and switches automatically to the normal mode in case of a sleepwalking task requiring more power. It returns automatically to low power mode when the sleepwalking task is completed. 22.6.3.3.3 OFF Mode In Off mode, the device is entirely powered-off. • Entering Off mode: This mode is entered by selecting the Off mode in the Sleep Configuration register by writing the Sleep Mode bits (SLEEPCFG.SLEEPMODE=OFF), and subsequent execution of the WFI instruction. • Exiting Off mode: This mode is left by pulling the RESET pin low, or when a power Reset is done. 22.6.3.4 Performance Level The application can change the performance level on the fly writing to the by Performance Level Select bit in the Performance Level Configuration register (PLCFG.PLSEL). When changing to a lower performance level, the bus frequency must be reduced before writing PLCFG.PLSEL in order to avoid exceeding the limit of the target performance level. When changing to a higher performance level, the bus frequency can be increased only after the Performance Level Ready flag in the Interrupt Flag Status and Clear (INTFLAG.PLRDY) bit set to '1', indicating that the performance level transition is complete. After a reset, the device starts in the lowest PL (lowest power consumption and lowest max frequency). The application can then switch to another PL at anytime without any stop in the code execution. As shown in Figure 22-3, performance level transition is possible only when the device is in active mode. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 250 The Performance Level Disable bit in the Performance Level Configuration register (PLCFG.PLDIS) can be used to freeze the performance level to PL0. This disables the performance level hardware mechanism in order to reduce both the power consumption and the wake-up startup time from standby sleep mode. Note:  This bit PLCFG.PLDIS must be changed only when the current performance level is PL0. Any attempt to modify this bit while the performance level is not PL0 is discarded and a violation is reported to the PAC module. Any attempt to change the performance level to PLn (with n>0) while PLCFG.PLDIS=1 is discarded and a violation is reported to the PAC module. Figure 22-3. Sleep Modes and Performance Level Transitions ACTIVE PLn IDLE PLn SLEEPCFG. IDLE IRQ SLEEPCFG. STANDBY IRQ OFF ACTIVE PL0 RESET PLCFG.PLSEL STANDBY ext reset SLEEPCFG. OFF 22.6.3.5 Power Domain Controller The Power Domain Controller provides several ways of how power domains are handled while the device is in Standby mode or entering Standby mode: • Default operation - all peripherals idle When entering Standby mode, the power domain PDSW is set in retention state. This allows for very low power consumption while retaining all the logic content of these power domains. When exiting Standby mode, all power domains are set back to active state. • Default operation - Standby Sleep Mode with static power gating SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 251 Static Power Domain Gating is a technique that allows to automatically turn off the PDSW power domain supply when not used while keeping PDAO powered up. • SleepWalking extension to power gating (SleepWalking with dynamic power gating) SleepWalking is the capability for a device in Standby Sleep mode, to temporarily wake-up clocks for a peripheral to perform a task without waking-up the CPU. The SleepWalking feature has been expanded to control power gating in addition to clock gating. The power domain PDSW can be automatically controlled (active or retention state) depending on peripheral requirements (PDCFG bit from the STDBYCFG register). The static and dynamic power gating features are fully transparent for the user. Table 22-3. Sleep Modes versus Power Domain States Overview Power Domain State Sleep Mode PDSW PDAO Active active active Idle active active Standby - At least one peripheral from PDSW with RUNSTDBY = 1 OR PDCFG = 1 active (1) active Standby - No peripheral from PDSW with RUNSTDBY = 1 retention active Off off off Note:  1. PDSW can be switched automatically in retention mode if the dynamic power gating feature is enabled. 22.6.3.6 Regulators, RAMs, and NVM State in Sleep Mode By default, in Standby Sleep mode, the RAMs, NVM, and regulators are automatically set in Low-Power mode to reduce power consumption: • The RAM is in Low-Power mode if its power domain is in retention or off state. • Non-Volatile Memory - the NVM is located in the power domain PDSW. By default, the NVM is automatically set in low power mode in these conditions: – When the power domain PDSW is in retention or off state. – When the device is in Standby Sleep mode and the NVM is not accessed. This behavior can be changed by software by configuring the SLEEPPRM bit group of the CTRLB register in the NVMCTRL peripheral. – When the device is in Idle Sleep mode and the NVM is not accessed. This behavior can be changed by software by configuring the SLEEPPRM bit group of the CTRLB register in the NVMCTRL peripheral. • Regulators: by default, in Standby Sleep mode, the PM analyzes the device activity to use either the main or the low-power voltage regulator to supply the VDDCORE. GCLK clocks, regulators and RAM are not affected in Idle Sleep mode and will operate as normal. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 252 Table 22-4. Regulators, RAMs, and NVM state in Sleep Mode Sleep Mode PDSW SRAM Mode(1) NVM Regulators VDDCORE main ULP Active active normal normal on on Idle active auto(2) on on on Standby - PDSW in Active mode active normal(6) auto(2) auto(3) on(5) Standby - PDSW in Retention mode retention low power(6) low power auto(4) on(5) OFF off off off off off Note:  1. RAMs mode by default: STDBYCFG.BBIAS bits are set to their default value. 2. auto: by default, NVM is in low-power mode if not accessed. 3. auto: by default, the main voltage regulator is on if GCLK, APBx, or AHBx clock is running during SleepWalking. 4. auto: by default ULP regulator is selected in retention, but main regulator will be selected if VREG RUNSTDBY register bit in Supply Controller is set to 1. 5. on: low power voltage reference must be ready, and this is confirmed if STATUS.ULPVREFRDY register bit in SUPC equals to 1 6. SRAM can be partially retained in STANDBY using SRAM Power Switch Related Links 22.6.4.4 Regulator Automatic Low Power Mode 22.6.4 Advanced Features 22.6.4.1 Power Domain Configuration When entering Standby Sleep mode, a power domain is set automatically to retention state if no activity is required in it, refer to 22.6.3.5 Power Domain Controller for details. This behavior can be changed by writing the Power Domain Configuration bit group in the Standby Configuration register (STDBYCFG.PDCFG). For example, all power domains can be forced to remain in active state during Standby Sleep mode, this will accelerate wake-up time. 22.6.4.2 RAM Automatic Low Power Mode The RAM is by default put in Low-Power mode (back-biased) if its power domain is in retention state and the device is in Standby Sleep mode. This behavior can be changed by configuring BBIASxx bit groups in the Standby Configuration register (STDBYCFG.BBIASxx), refer to the table below for details. Note:  in Standby Sleep mode, the DMAC can access the SRAM in Standby Sleep mode only when the power domain PDSW is not in retention and PM.STDBYCFG.BBIASxx=0x0. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 253 Table 22-5. RAM Back-Biasing Mode STBYCDFG.BBIASxx config RAM 0x0 Retention Back Biasing mode RAM is back-biased if its power domain is in retention state 0x1 Standby Back Biasing mode RAM is back-biased if the device is in Standby Sleep mode 22.6.4.3 SRAM Power Switch Configuration The SRAM is divided in sub-blocks which can be retained or not in STANDBY low power mode to optimize power consumption. By default, all sub-blocks are retained but it is possible to switch them off depending on SRAM memory size. This behavior can be changed by configuring RAMPSWC bit groups in the Power Configuration register (PWCFG). This configuration takes effect immediately. So, this is the responsibility of the user to ensure that no access is performed on OFF RAM. When a SRAM sub-block is switched ON, the user has to wait 1 us before accessing it. The first sub-block to be switched off is always at the top of the SRAM block memory and this is the same for the next ones. 22.6.4.4 Regulator Automatic Low Power Mode In standby mode, the PM selects either the main or the low power voltage regulator to supply the VDDCORE. If switchable power domain is in retention state, the low power voltage regulator is used. If a sleepwalking task is working on either asynchronous clocks (generic clocks) or synchronous clock (APB/AHB clocks), the main voltage regulator is used. This behavior can be changed by writing the Voltage Regulator Standby Mode bits in the Standby Configuration register (STDBYCFG.VREGSMOD). Refer to the following table for details. Table 22-6. Regulator State in Sleep Mode Sleep Modes STDBYCFG. VREGSMOD SleepWalking(1) Regulator state for VDDCORE Active - - main voltage regulator Idle - - main voltage regulator Standby (active) 0x0: AUTO NO low power regulator YES main voltage regulator 0x1: PERFORMANCE - main voltage regulator 0x2: LP(2) - (2) low power regulator Standby (retention) - - low power regulator Note:  1. SleepWalking is running on GCLK clock or synchronous clock. This is not related to XOSC32K or OSCULP32K clocks. 2. Must only be used when SleepWalking is running on GCLK with 32KHz source. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 254 22.6.4.5 SleepWalking and Performance Level SleepWalking is the capability for a device to temporarily wake up clocks for a peripheral to perform a task without waking up the CPU from STANDBY sleep mode. At the end of the sleepwalking task, the device can either be woken up by an interrupt (from a peripheral involved in SleepWalking) or enter again into STANDBY sleep mode. In this device, SleepWalking is supported only on GCLK clocks by using the on-demand clock principle of the clock sources. In standby mode, when SleepWalking is ongoing, the performance level used to execute the sleepwalking task is the current configured performance level (used in active mode), and the main voltage regulator used to execute the SleepWalking task is the selected regulator used in active mode (LDO or Buck converter). These are illustrated in the figure below. Figure 22-4. Operating Conditions and SleepWalking ACTIVE ACTIVE RESET IDLE ACTIVE IDLE STANDBY PL0 PL2 SLEEP PL2 WALKING STANDBY PL0 WALKING IDLE LDO BUCK RESET VREG.SEL LDO BUCK Regulator modes LP VREG SLEEP Sleep Mode Performance Level SUPC 22.6.4.6 Wake-Up Time The total wake-up time depends on the following: • Latency due to Power Domain Gating: Usually, wake-up time is measured with the assumption that the power domain is already in active state. When using Power Domain Gating, changing a power domain from retention to active state will take a certain time, refer to Electrical Characteristics. If power domain was already in active state in standby sleep mode, this latency is zero. If wake-up time is critical for the application, power domain can be forced to active state in Standby Sleep mode, refer to 22.6.4.1 Power Domain Configuration for details. • Latency due to Performance Level and Regulator effect: Performance Level has to be taken into account for the global wake-up time. As example, if PL2 is selected and the device is in Standby Sleep mode, the voltage level supplied by the ULP voltage regulator is lower than the one used in Active mode. When the device wakes up, it takes a certain SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 255 amount of time for the main regulator to transition to the voltage level corresponding to PL2, causing additional wake-up time. • Latency due to the CPU clock source wake-up time. • Latency due to the NVM memory access. • Latency due to Switchable Power Domain back-bias wake-up time: If back-bias is enabled, and the device wakes up from retention, it takes a certain amount of time for the regulator to settle. Figure 22-5. Total Wake-up Time from Standby Sleep Mode Low Power mode PDSW active retention active IRQ from module WFI instruction CPU state run standby sleep mode run interrupt handler VDDCORE Main regulator Main regulator 1 CLK_CPU ON OFF ON 2 3 4 Normal mode 1: latency due to power domain gating 2: latency due to regulator wakeup time 3: latency due to clock source wakeup time 4: latency due to flash memory code access Main regulator Normal mode 22.6.5 Standby with Static Power Domain Gating in Details In Standby Sleep mode, the switchable power domain (PDSW) of a peripheral can remain in active state to perform the peripheral's tasks. This Static Power Domain Gating feature is supported by all peripherals. For some peripherals it must be enabled by writing a Run in Standby bit in the respective Control A register (CTRLA.RUNSTDBY) to '1'. Refer to each peripheral chapter for details. The following examples illustrate Standby with static Power Domain Gating: TC0 Standby with Static Power Domain Gating TC0 peripheral is used in counter operation mode. An interrupt is generated to wake-up the device based on the TC0 peripheral configuration. To make the TC0 peripheral continue to run in Standby Sleep mode, the RUNSTDBY bit is written to '1'. • Entering Standby mode: As shown in Figure 22-6, PDSW remains active. Refer to 22.6.3.5 Power Domain Controller for details. • Exiting Standby mode: When conditions are met, the TC0 peripheral generates an interrupt to wake-up the device, and the CPU is able to operate normally and execute the TC0 interrupt handler accordingly. • Wake-up time: – The required time to set PDSW to active state has to be considered for the global wake-up time, refer to 22.6.4.6 Wake-Up Time for details. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 256 – In this case, the VDDCORE voltage is still supplied by the main voltage regulator, refer to 22.6.4.4 Regulator Automatic Low Power Mode for details. Thus, global wake-up time is not affected by the regulator. Figure 22-6. TC0 in Standby with Static Power Domain Gating PDSW TC0 PM PDAO Main Supply active state active state RUNSTDBY active PDAO PDSW active IRQ IRQ from TC0 WFI instruction CPU state run standby sleep mode run interrupt handler CPU GCLK GCLK_TC0 EIC in Standby with Static Power Domain Gating In this example, EIC peripheral is used to detect an edge condition to generate interrupt to the CPU. An External interrupt pin is filtered by the CLK_ULP32K clock, GCLK peripheral is not used. Refer to Chapter 29. EIC – External Interrupt Controller for details. The EIC peripheral is located in the power domain PDAO (which is not switchable), and there is no RUNSTDBY bit in the EIC peripheral. • Entering Standby mode: As shown in Figure 22-7, the switchable power domain is set in retention state by the Power Manager peripheral. The low power regulator supplies the VDDCORE voltage level. • Exiting Standby mode: When conditions are met, the EIC peripheral generates an interrupt to wake the device up. Successively, the PM peripheral sets PDSW to active state, and the main voltage regulator restarts. Once PDSW is in active state and the main voltage regulator is ready, the CPU is able to operate normally and execute the EIC interrupt handler accordingly. • Wake-up time: – The required time to set the switchable power domains to active state has to be considered for the global wake-up time, refer to 22.6.4.6 Wake-Up Time for details. – When in standby Sleep mode, the GCLK peripheral is not used, allowing the VDDCORE to be supplied by the low power regulator to reduce consumption, see 22.6.4.4 Regulator Automatic Low Power Mode. Consequently, main voltage regulator wake-up time has to be considered for the global wake-up time as shown in Figure 22-7. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 257 Figure 22-7. EIC in Standby with Static Power Domain Gating CPU PDSW EIC PM PDAO Main Supply retention state active state PDSW active active IRQ retention WFI instruction OSCULP32K PDAO active IRQ from EIC VDDCORE WFI instruction CPU state run standby sleep mode run interrupt handler CLK_CPU ON OFF ON clock startup Low Power regulator Main regulator PL2 Main regulator PL2 22.6.6 Sleepwalking with Dynamic Power Domain Gating in Details To reduce power consumption even further, Sleepwalking with dynamic Power Domain Gating (also referred to as "Dynamic Sleepwalking") is used to turn power domain state from retention to active and vice-versa, based on event or DMA trigger. 22.6.6.1 Dynamic SleepWalking based on Event To enable SleepWalking with dynamic power domain gating, the Dynamic Power Gating for Power Domain SW bit in the Standby Configuration register (STDBYCFG.DPGPDSW) has to be written to '1'. When in retention state, a power domain can be automatically set to active state by the PM if an event is directed to this power domain. In this device, this concerns the event users located in power domain PDSW. • When PDSW is in retention state, dynamic SleepWalking can be triggered by: – AC output event – RTC output event – EIC output event (if using the CLK_ULP32K clock and debouncing is enabled) Refer also to 22.6.1.2 Power Domains. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 258 Dynamic SleepWalking based on event is illustrated in the following example: Figure 22-8. Dynamic SleepWalking based on Event: AC Periodic Comparison PDSW active retention active IRQ from AC WFI instruction CPU state run standby sleep mode run interrupt handler AC conversion NO YES NO YES dynamic power sleepwalking CPU PDSW PM PDAO Main Supply active state IRQ DPGPDSW OSCULP32K RTC EVSYS AC_COMPX RTC_PERX RTC_perx dynamic power sleepwalking active PDAO active AC RUNSTDBY The Analog Comparator (AC) peripheral is used in single shot mode to monitor voltage levels on input pins. A comparator interrupt, based on the AC peripheral configuration, is generated to wake up the device. In the GCLK module, the AC generic clock (GCLK_AC) source is routed a 32.768kHz oscillator (for low power applications, OSC32KULP is recommended). RTC and EVSYS modules are configured to generate periodic events to the AC. To make the comparator continue to run in standby sleep mode, the RUNSTDBY bit is written to '1'. To enable the dynamic SleepWalking for PDSW power domain, STDBYCFG.PDSW must be written to '1'. Entering standby mode: The Power Manager sets the PDSW power domain in retention state. The AC comparators, COMPx, are OFF. The GCLK_AC clock is stopped. The VDDCORE is supplied by the low power regulator. Dynamic SleepWalking: The RTC event (RTC_PERX) is routed by the Event System to the Analog Comparator to trigger a single-shot measurement. This event is detected by the Power Manager, which sets the PDSW power domain to active state and starts the main voltage regulator. After enabling the AC comparator and starting the GCLK_AC, the single-shot measurement can be performed during Sleep mode (sleepwalking task), refer to 42.6.14.2 Single-Shot Measurement during Sleep for details. At the end of the conversion, if conditions to generate an interrupt are not met, the GCLK_AC clock is stopped again, as well as the AC comparator. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 259 The low-power regulator starts again and the PDSW power domain is set back to retention state by the PM. During this dynamic SleepWalking period, the CPU is still sleeping. Exiting standby mode: during the dynamic SleepWalking sequence, if conditions are met, the AC module generates an interrupt to wake up the device. Related Links 27. RTC – Real-Time Counter 33. EVSYS – Event System 22.6.6.2 Dynamic SleepWalking Based on Peripheral DMA Trigger To enable this advanced feature, the Dynamic Power Gating for Power Domain SW bit in the Standby Configuration register (STDBYCFG.DPGPDSW) have to be written to '1'. When in retention state, the power domain PDSW (containing the DMAC) can be automatically set to active state if the PM detects a valid DMA trigger that is coming from a peripheral located in PDAO. A peripheral DMA trigger is valid if the corresponding DMA channel is enabled and its Run in Standby bit (RUNSTDBY) is written to '1'. This is illustrated in the following example: Figure 22-9. Dynamic Sleepwalking based on Peripheral DMA Trigger PM PDAO Main Supply active state DPGPDSW OSCULP32K RTC dma_dreq_timestamp PDSW active retention active IRQ from DMAC WFI instruction CPU state run standby sleep mode run interrupt handler RTC_perx dynamic power sleepwalking active DMA_REQ DMA transfer NO YES NO YES dynamic power sleepwalking active DMA_REQ PDAO active CPU PDSW DMAC IRQ RAM DMA destination RUNSTDBY SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 260 The DMAC is configured to operate in standby sleep mode by using its respective RUNSTDBY bit. A DMAC channel is configured to set the DMA destination. The Run in Standby bit of this DMAC channel is written to '1' to allow it running in Standby Sleep mode. Entering Standby mode: The Power Manager peripheral sets PDSW to retention state. The VDDCORE is supplied by the low-power regulator. Dynamic SleepWalking: based on RTC conditions, an RTC output signal (DMA request for timestamp) triggers DMAC to put timestamp value at configured DMA destination. This event is detected by the Power Manager which sets the PDSW power domain to active state and starts the main voltage regulator. This DMA transfer request is detected by the PM, which sets PDSW (containing the DMAC) to active state. The DMAC requests the CLK_DMAC_AHB clock and transfer the timestamp value to the memory. When the DMA beat transfer is completed, the CLK_DMAC_AHB clock is stopped again. The low-power regulator starts again and the PDSW power domain is set back to retention state by the PM. Note that during this dynamic SleepWalking period, the CPU is still sleeping. Exiting Standby mode: during SleepWalking with Dynamic Power Gating sequence, if conditions are met, the DMAC generates an interrupt to wake up the device. Related Links 27. RTC – Real-Time Counter 33. EVSYS – Event System 22.6.7 DMA Operation Not applicable. 22.6.8 Interrupts The peripheral has the following interrupt sources: • Performance Level Ready (PLRDY) This interrupt is a synchronous wake-up source. See Table 22-1 for details. Each interrupt source has an interrupt flag associated with it. The interrupt flag in the Interrupt Flag Status and Clear (INTFLAG) register is set when the interrupt condition occurs. Each interrupt can be individually enabled by writing a '1' to the corresponding bit in the Interrupt Enable Set (INTENSET) register, and disabled by writing a '1' to the corresponding bit in the Interrupt Enable Clear (INTENCLR) register. An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until the interrupt flag is cleared, the interrupt is disabled or the peripheral is reset. An interrupt flag is cleared by writing a '1' to the corresponding bit in the INTFLAG register. Each peripheral can have one interrupt request line per interrupt source or one common interrupt request line for all the interrupt sources. Refer to the Nested Vector Interrupt Controller (NVIC) for details. If the peripheral has one common interrupt request line for all the interrupt sources, the user must read the INTFLAG register to determine which interrupt condition is present. 22.6.9 Events Not applicable. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 261 22.6.10 Sleep Mode Operation The Power Manager is always active. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 262 22.7 Register Summary Offset Name Bit Pos. 0x01 SLEEPCFG 7:0 SLEEPMODE[2:0] 0x02 PLCFG 7:0 PLDIS PLSEL[1:0] 0x03 PWCFG 7:0 RAMPSWC[1:0] 0x04 INTENCLR 7:0 PLRDY 0x05 INTENSET 7:0 PLRDY 0x06 INTFLAG 7:0 PLRDY 0x07 Reserved 0x08 STDBYCFG 7:0 VREGSMOD[1:0] DPGPDSW PDCFG 15:8 BBIASTR BBIASHS 22.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to 22.5.7 Register Access Protection. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 263 22.8.1 Sleep Configuration Name:  SLEEPCFG Offset:  0x01 Reset:  0x2 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 SLEEPMODE[2:0] Access R/W R/W R/W Reset 0 0 0 Bits 2:0 – SLEEPMODE[2:0] Sleep Mode Note:  A small latency happens between the store instruction and actual writing of the SLEEPCFG register due to bridges. Software has to make sure the SLEEPCFG register reads the wanted value before issuing WFI instruction. Value Name Definition 0x0 Reserved Reserved 0x1 Reserved Reserved 0x2 IDLE CPU, AHBx, and APBx clocks are OFF 0x3 Reserved Reserved 0x4 STANDBY ALL clocks are OFF, unless requested by sleepwalking peripheral 0x5 Reserved Reserved 0x6 OFF All power domains are powered OFF 0x7 Reserved Reserved SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 264 22.8.2 Performance Level Configuration Name:  PLCFG Offset:  0x02 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 PLDIS PLSEL[1:0] Access R/W R/W R/W Reset 0 0 0 Bit 7 – PLDIS Performance Level Disable Disabling the automatic PL selection forces the device to run in PL0 , reducing the power consumption and the wake-up time from standby sleep mode. Changing this bit when the current performance level is not PL0 is discarded and a violation is reported to the PAC module. Value Description 0 The Performance Level mechanism is enabled. 1 The Performance Level mechanism is disabled. Bits 1:0 – PLSEL[1:0] Performance Level Select Value Name Definition 0x0 PL0 Performance Level 0 0x1 Reserved Reserved 0x2 PL2 Performance Level 2 0x3 Reserved Reserved SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 265 22.8.3 Power Configuration Name:  PWCFG Offset:  0x03 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 RAMPSWC[1:0] Access R/W R/W Reset 0 0 Bits 1:0 – RAMPSWC[1:0] RAM Power Switch Configuration Value Name Definition 0x0 16KB 16KB Available 0x1 12KB 12KB Available 0x2 8KB 8KB Available 0x3 4KB 4KB Available SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 266 22.8.4 Interrupt Enable Clear Name:  INTENCLR Offset:  0x04 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set (INTENSET) register. Bit 7 6 5 4 3 2 1 0 PLRDY Access R/W Reset 0 Bit 0 – PLRDY Performance Level Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Performance Ready Interrupt Enable bit and the corresponding interrupt request. Value Description 0 The Performance Ready interrupt is disabled. 1 The Performance Ready interrupt is enabled and will generate an interrupt request when the Performance Ready Interrupt Flag is set. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 267 22.8.5 Interrupt Enable Set Name:  INTENSET Offset:  0x05 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear (INTENCLR) register. Bit 7 6 5 4 3 2 1 0 PLRDY Access R/W Reset 0 Bit 0 – PLRDY Performance Level Ready Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Performance Ready Interrupt Enable bit and enable the Performance Ready interrupt. Value Description 0 The Performance Ready interrupt is disabled. 1 The Performance Ready interrupt is enabled. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 268 22.8.6 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x06 Reset:  0x00 Property:  – Bit 7 6 5 4 3 2 1 0 PLRDY Access R/W Reset 0 Bit 0 – PLRDY Performance Level Ready This flag is set when the performance level is ready and will generate an interrupt if INTENCLR/ SET.PLRDY is '1'. Writing a '1' to this bit has no effect. Writing a '1' to this bit clears the Performance Ready interrupt flag. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 269 22.8.7 Standby Configuration Name:  STDBYCFG Offset:  0x08 Reset:  0x0000 Property:  PAC Write-Protection Bit 15 14 13 12 11 10 9 8 BBIASTR BBIASHS Access R/W R/W Reset 0 0 Bit 7 6 5 4 3 2 1 0 VREGSMOD[1:0] DPGPDSW PDCFG Access R R R/W R/W Reset 0 0 0 0 Bit 12 – BBIASTR Back Bias for Trust RAM Refer to 22.6.4.2 RAM Automatic Low Power Mode for details. Value Description 0 Retention Back Biasing mode 1 Standby Back Biasing mode Bit 10 – BBIASHS Back Bias for HMCRAMCHS Refer to 22.6.4.2 RAM Automatic Low Power Mode for details. Value Description 0 Retention Back Biasing mode 1 Standby Back Biasing mode Bits 7:6 – VREGSMOD[1:0] VREG Switching Mode Refer to 22.6.4.4 Regulator Automatic Low Power Mode for details. Value Name Description 0x0 AUTO Automatic Mode 0x1 PERFORMANCE Performance oriented 0x2 LP Low Power consumption oriented Bit 4 – DPGPDSW Dynamic Power Gating for Switchable Power Domain Value Description 0 Dynamic SleepWalking for switchable power domain is disabled 1 Dynamic SleepWalking for switchable power domain PDSW is enabled Bit 0 – PDCFG Power Domain Configuration Value Name Description 0x0 DEFAULT In standby mode, all power domain switching are handled by hardware. 0x1 PDSW In standby mode, PDSW is forced ACTIVE. SAM L10/L11 Family PM – Power Manager © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 270 23. OSCCTRL – Oscillators Controller 23.1 Overview The Oscillators Controller (OSCCTRL) provides a user interface to the XOSC, OSC16M, DFLLULP and FDPLL96M. Through the interface registers, it is possible to enable, disable, calibrate, and monitor the OSCCTRL oscillators. All oscillators statuses are collected in the Status register (STATUS). They can additionally trigger interrupts upon status changes via the INTENSET, INTENCLR, and INTFLAG registers. 23.2 Features • 0.4-32MHz Crystal Oscillator (XOSC) – Tunable gain control – Programmable start-up time – Crystal or external input clock on XIN I/O – Clock failure detection with safe clock switch – Clock failure event output • 16MHz Internal Oscillator (OSC16M) – Fast startup – 4/8/12/16MHz output frequencies available • Ultra Low-Power Digital Frequency Locked Loop (DFLLULP) – Operates as a frequency multiplier against a known frequency in closed loop mode – Optional frequency dithering • Fractional Digital Phase Locked Loop (FDPLL96M) – 32 MHz to 96 MHz output frequency – 32 kHz to 2MHz reference clock – A selection of sources for the reference clock – Adjustable proportional integral controller – Fractional part used to achieve 1/16th of reference clock step SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 271 23.3 Block Diagram Figure 23-1. OSCCTRL Block Diagram OSCILLATORS CONTROL STATUS INTERRUPTS GENERATOR Interrupts OSCCTRL XINXOUT XOSC OSC16M FDPLL96M CLK_XOSC CLK_OSC16M CLK_DPLL CFD CFD Event register DFLLULP CLK_DFLLULP 23.4 Signal Description Signal Description Type XIN Multipurpose Crystal Oscillator or external clock generator input Analog input XOUT Multipurpose Crystal Oscillator output Analog output The I/O lines are automatically selected when XOSC is enabled. 23.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 23.5.1 I/O Lines I/O lines are configured by OSCCTRL when XOSC is enabled, and need no user configuration. 23.5.2 Power Management The OSCCTRL can continue to operate in any sleep mode where the selected source clock is running. The OSCCTRL interrupts can be used to wake up the device from sleep modes. The events can trigger other operations in the system without exiting sleep modes. Related Links 22. PM – Power Manager 23.5.3 Clocks The OSCCTRL gathers controls for all device oscillators and provides clock sources to the Generic Clock Controller (GCLK). The available clock sources are XOSC, OSC16M, DFLLULP and FDPLL96M. The OSCCTRL bus clock (CLK_OSCCTRL_APB) can be enabled and disabled in the Main Clock module (MCLK). SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 272 The control logic uses the oscillator output, which is also asynchronous to the user interface clock (CLK_OSCCTRL_APB). Due to this asynchronicity, writes to certain registers will require synchronization between the clock domains. Refer to 23.6.11 Synchronization for further details. A generic clock (GCLK_DFLLULP) is required to clock the DFLLULP tuner in closed-loop operation. This clock must be configured and enabled in the generic clock controller before using the DFLLULP tuner. Refer to the Generic Clock Controller (GCLK) chapter for details. Related Links 19. MCLK – Main Clock 19.6.2.6 Peripheral Clock Masking 23.5.4 DMA Not applicable. 23.5.5 Interrupts The interrupt request line is connected to the Interrupt Controller. Using the OSCCTRL interrupts requires the interrupt controller to be configured first. 23.5.6 Events The events of this peripheral are connected to the Event System. Related Links 33. EVSYS – Event System 23.5.7 Debug Operation When the CPU is halted in debug mode the OSCCTRL continues normal operation. If the OSCCTRL 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.5.8 Register Access Protection All registers with write-access can be write-protected optionally by the Peripheral Access Controller (PAC), except for the following registers: • Interrupt Flag Status and Clear register (INTFLAG) Note:  Optional write-protection is indicated by the "PAC Write-Protection" property in the register description. Write-protection does not apply for accesses through an external debugger. 23.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 273 23.5.10 Analog Connections The 0.4-32MHz crystal must be connected between the XIN and XOUT pins, along with any required load capacitors. 23.6 Functional Description 23.6.1 Principle of Operation XOSC, OSC16M, and FDPLL96M. are configured via OSCCTRL control registers. Through this interface, the oscillators are enabled, disabled, or have their calibration values updated. The Status register gathers different status signals coming from the oscillators controlled by the OSCCTRL. The status signals can be used to generate system interrupts, and in some cases wake the system from Sleep mode, provided the corresponding interrupt is enabled. 23.6.2 External Multipurpose Crystal Oscillator (XOSC) Operation The XOSC can operate in two different modes: • External clock, with an external clock signal connected to the XIN pin • Crystal oscillator, with an external 0.4-32MHz crystal The XOSC can be used as a clock source for generic clock generators. This is configured by the Generic Clock Controller. At reset, the XOSC is disabled, and the XIN/XOUT pins can be used as General Purpose I/O (GPIO) pins or by other peripherals in the system. When XOSC is enabled, the operating mode determines the GPIO usage. When in crystal oscillator mode, the XIN and XOUT pins are controlled by the OSCCTRL, and GPIO functions are overridden on both pins. When in external clock mode, only the XIN pin will be overridden and controlled by the OSCCTRL, while the XOUT pin can still be used as a GPIO pin. The XOSC is enabled by writing a '1' to the Enable bit in the External Multipurpose Crystal Oscillator Control register (XOSCCTRL.ENABLE). To enable XOSC as an external crystal oscillator, the XTAL Enable bit (XOSCCTRL.XTALEN) must be written to '1'. If XOSCCTRL.XTALEN is zero, the external clock input on XIN will be enabled. When in crystal oscillator mode (XOSCCTRL.XTALEN=1), the External Multipurpose Crystal Oscillator Gain (XOSCCTRL.GAIN) must be set to match the external crystal oscillator frequency. If the External Multipurpose Crystal Oscillator Automatic Amplitude Gain Control (XOSCCTRL.AMPGC) is '1', the oscillator amplitude will be automatically adjusted, and in most cases result in a lower power consumption. The XOSC will behave differently in different sleep modes, based on the settings of XOSCCTRL.RUNSTDBY, XOSCCTRL.ONDEMAND, and XOSCCTRL.ENABLE. If XOSCCTRL.ENABLE=0, the XOSC will be always stopped. For XOSCCTRL.ENABLE=1, this table is valid: Table 23-1. XOSC Sleep Behavior CPU Mode XOSCCTRL.RUNST DBY XOSCCTRL.ONDEM AND Sleep Behavior Active or Idle - 0 Always run Active or Idle - 1 Run if requested by peripheral SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 274 CPU Mode XOSCCTRL.RUNST DBY XOSCCTRL.ONDEM AND Sleep Behavior Standby 1 0 Always run Standby 1 1 Run if requested by peripheral Standby 0 - Run if requested by peripheral After a hard reset, or when waking up from a sleep mode where the XOSC was disabled, the XOSC will need a certain amount of time to stabilize on the correct frequency. This start-up time can be configured by changing the Oscillator Start-Up Time bit group (XOSCCTRL.STARTUP) in the External Multipurpose Crystal Oscillator Control register. During the start-up time, the oscillator output is masked to ensure that no unstable clock propagates to the digital logic. The External Multipurpose Crystal Oscillator Ready bit in the Status register (STATUS.XOSCRDY) is set once the external clock or crystal oscillator is stable and ready to be used as a clock source. An interrupt is generated on a zero-to-one transition on STATUS.XOSCRDY if the External Multipurpose Crystal Oscillator Ready bit in the Interrupt Enable Set register (INTENSET.XOSCRDY) is set. Related Links 18. GCLK - Generic Clock Controller 23.6.3 Clock Failure Detection Operation The Clock Failure Detector (CFD) enables the user to monitor the external clock or crystal oscillator signal provided by the external oscillator (XOSC). The CFD detects failing operation of the XOSC clock with reduced latency, and allows to switch to a safe clock source in case of clock failure. The user can also switch from the safe clock back to XOSC in case of recovery. The safe clock is derived from the OSC16M oscillator with a configurable prescaler. This allows to configure the safe clock in order to fulfill the operative conditions of the microcontroller. In sleep modes, CFD operation is automatically disabled when the external oscillator is not requested to run by a peripheral. See the Sleep Behavior table above when this is the case. The user interface registers allow to enable, disable, and configure the CFD. The Status register provides status flags on failure and clock switch conditions. The CFD can optionally trigger an interrupt or an event when a failure is detected. Clock Failure Detection The CFD is disabled at reset. The CFD does not monitor the XOSC clock when the oscillator is disabled (XOSCCTRL.ENABLE=0). Before starting CFD operation, the user must start and enable the safe clock source (OSC16M oscillator). CFD operation is started by writing a '1' to the CFD Enable bit in the External Oscillator Control register (XOCCTRL.CFDEN). After starting or restarting the XOSC, the CFD does not detect failure until the startup time has elapsed. The start-up time is configured by the Oscillator Start-Up Time in the External Multipurpose Crystal Oscillator Control register (XOSCCTRL.STARTUP). Once the XOSC Start-Up Time is elapsed, the XOSC clock is constantly monitored. During a period of 4 safe clocks (monitor period), the CFD watches for a clock activity from the XOSC. There must be at least one rising and one falling XOSC clock edge during 4 safe clock periods to meet non-failure conditions. If no or insufficient activity is detected, the failure status is asserted: The Clock Failure Detector status bit in the Status register (STATUS.CLKFAIL) and the Clock Failure Detector SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 275 interrupt flag bit in the Interrupt Flag register (INTFLAG.CLKFAIL) are set. If the CLKFAIL bit in the Interrupt Enable Set register (INTENSET.CLKFAIL) is set, an interrupt is generated as well. If the Event Output enable bit in the Event Control register (EVCTRL.CFDEO) is set, an output event is generated, too. After a clock failure was issued the monitoring of the XOSC clock is continued, and the Clock Failure Detector status bit in the Status register (STATUS.CLKFAIL) reflects the current XOSC activity. Clock Switch When a clock failure is detected, the XOSC clock is replaced by the safe clock in order to maintain an active clock during the XOSC clock failure. The safe clock source is the OSC16M oscillator clock. The safe clock source can be scaled down by a configurable prescaler to ensure that the safe clock frequency does not exceed the operating conditions selected by the application. When the XOSC clock is switched to the safe clock, the Clock Switch bit in the Status register (STATUS.CLKSW) is set. When the CFD has switched to the safe clock, the XOSC is not disabled. If desired, the application must take the necessary actions to disable the oscillator. The application must also take the necessary actions to configure the system clocks to continue normal operations. If the application can recover the XOSC, the application can switch back to the XOSC clock by writing a '1' to Switch Back Enable bit in the Clock Failure Control register (XOSCCTRL.SWBACK). Once the XOSC clock is switched back, the Switch Back bit (XOSCCTRL.SWBACK) is cleared by hardware. Prescaler The CFD has an internal configurable prescaler to generate the safe clock from the OSC16M oscillator. The prescaler size allows to scale down the OSC16M oscillator so the safe clock frequency is not higher than the XOSC clock frequency monitored by the CFD. The division factor is 2^P, with P being the value of the CFD Prescaler bits in the CFD Prescaler Register (CFDPRESC.CFDPRESC). Example 23-1.  For an external crystal oscillator at 0.4 MHz and the OSC16M frequency at 16 MHz, the CFDPRESC.CFDPRESC value should be set scale down by more than factor 16/0.4=80, for example 128, for a safe clock of adequate frequency. Event If the Event Output Enable bit in the Event Control register (EVCTRL.CFDEO) is set, the CFD clock failure will be output on the Event Output. When the CFD is switched to the safe clock, the CFD clock failure will not be output on the Event Output. Sleep Mode The CFD is halted depending on configuration of the XOSC and the peripheral clock request. For further details, refer to the Sleep Behavior table above. The CFD interrupt can be used to wake up the device from sleep modes. 23.6.4 16MHz Internal Oscillator (OSC16M) Operation The OSC16M is an internal oscillator operating in open-loop mode and generating 4, 8, 12, or 16MHz frequency. The OSC16M frequency is selected by writing to the Frequency Select field in the OSC16M register (OSC16MCTRL.FSEL). OSC16M is enabled by writing '1' to the Oscillator Enable bit in the OSC16M Control register (OSC16MCTRL.ENABLE), and disabled by writing a '0' to this bit. Frequency selection must be done when OSC16M is disabled. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 276 After enabling OSC16M, the OSC16M clock is output as soon as the oscillator is ready (STATUS.OSC16MRDY=1). User must ensure that the OSC16M is fully disabled before enabling it by reading STATUS.OSC16MRDY=0. After reset, OSC16M is enabled and serves as the default clock source at 4MHz. OSC16M will behave differently in different sleep modes based on the settings of OSC16MCTRL.RUNSTDBY, OSC16MCTRL.ONDEMAND, and OSC16MCTRL.ENABLE. If OSC16MCTRL.ENABLE=0, the OSC16M will be always stopped. For OSC16MCTRL.ENABLE=1, this table is valid: Table 23-2. OSC16M Sleep Behavior CPU Mode OSC16MCTRL.RUN STDBY OSC16MCTRL.OND EMAND Sleep Behavior Active or Idle - 0 Always run Active or Idle - 1 Run if requested by peripheral Standby 1 0 Always run Standby 1 1 Run if requested by peripheral Standby 0 - Run if requested by peripheral OSC16M is used as a clock source for the generic clock generators. This is configured by the Generic Clock Generator Controller. Related Links 18. GCLK - Generic Clock Controller 23.6.5 Ultra Low-Power Digital Frequency Locked Loop (DFLLULP) Operation The Ultra Low-Power Digital Frequency Locked Loop (DFLLULP) is an internal oscillator that can output a selectable frequency based on user inputs. The frequency is a multiplication ratio relative to a given reference clock using the tuning feature. The oscillator has to be enabled for the tuner to work. Figure 23-2. Block Diagram 23.6.5.1 Basic Operation 23.6.5.1.1 Initialization The following bits are enable-protected, meaning that they can only be written when the DFLLULP is disabled (DFLLULPCTRL.ENABLE is zero): • Binary Search Enable bit in Control register (DFLLULPCTRL.BINSE) • Safe Mode bit in Control register (DFLLULPCTRL.SAFE) • Dither Mode bit in Control register (DFLLULPCTRL.DITHER) • Division Factor bits in Control register (DFLLULPCTRL.DIV) The following registers are enable-protected: • Dither Control register (DFLLULPDITHER) • Target Ratio register (DFLLULPRATIO) Enable-protected bits in the DFLLULPCTRL register can be written at the same time as DFLLULPCTRL.ENABLE is written to one, but not at the same time as DFLLULPCTRL.ENABLE is written to zero. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 277 Enable-protection is denoted by the Enable-Protected property in the register description. 23.6.5.1.2 Enabling and Disabling The DFLLULP is enabled by writing a one to the Enable bit in the Control register (DFLLULPCTRL.ENABLE). The DFLLULP is disabled by writing a zero to DFLLULPCTRL.ENABLE. 23.6.5.1.3 Closed Loop Mode In closed loop mode the frequency is controlled by a tuner which measures the ratio between the DFLLULP output frequency and reference clock frequency. The reference clock is provided by a generic clock. The target ratio is written to the RATIO field in the Target Ratio Register (DFLLULPRATIO). When the oscillator is enabled, the output frequency will be tuned to the target frequency. When the tuning is finished, the Lock bit in the OSCCTRL Status Register will be set (STATUS.DFLLULPLOCK). The No Lock bit in the Status register (STATUS.DFLLULPNOLOCK) will be set to indicate whether a frequency lock is achieved or not. The No Lock bit should be checked after the Lock bit has been set. Lock status is cleared only if the tuner is disabled or a new value is written to DFLLULPDLY. The DFLLULP will attempt to track any variation in the internal oscillator or reference clock, and will not release the lock. No Lock may be set after lock is achieved if the tuner ever reaches the minimum or maximum delay value. Tuning starts from the delay value in DFLLULPDLY.DELAY. A write to DFLLULPDLY.DELAY while tuning is in progress will restart tuning from the newly written value. The tuned delay value can be read back from DFLLULPDLY.DELAY after requesting a synchronization via the Read Request bit in the DFLLULPRREQ register. The accuracy of the tuner frequency comparison is limited by the inverse of the target ratio (1/RATIO). Larger ratios, i.e. much slower reference clocks will give better results. 23.6.5.1.4 Binary Search By default, the tuner starts from the current value of the DFLLULPDLY register and increments or decrements every reference clock period. This linear search can take up to a maximum of 256 reference clock cycles before lock. To speed up the time to lock, binary search can be enabled by writing one to the Binary Search Enable bit in the Control register (DFLLULPCTRL.BINSE). Binary search takes a maximum of 8 reference clock cycles to lock. After 8 reference clock cycles the tuner will operate in normal linear mode to track any changes in the frequency. Note that neither search algorithm is guaranteed to lock if the target ratio is outside of the oscillator tunable range. Binary search will induce large swings in the oscillator frequency. If this is not desirable, an optional safe mode can be used to mask the output clock until the search is complete. Safe mode is enabled by writing a one to the Safe Mode bit in the Control register (DFLLULPCTRL.SAFE). The binary search is re-triggered if there is a write to DFLLULPDLY, or if the tuner is disabled and re-enabled. Ondemand or sleep modes will not retrigger the binary search. If binary search will be used with ondemand behavior, it is recommended to first enable the tuner with DFLLULPCTRL.ONDEMAND=0 and then set DFLLULPCTRL.ONDEMAND=1 after the tuner has locked. This will ensure that each request will start from the locked state. 23.6.5.1.5 Dithering Dithering operation can improve the precision of the closed-loop tuner. Dithering works on two aspects: the delay step size and the comparator resolution. Normally the delay can only be changed in steps of one unit of the 8-bit delay field every reference clock period, for a total of 256 steps. Dithering allows for 8-bits of fractional delay value by automatically changing between DELAY and DELAY+1 values with a weight determined by the tuner. This also has the effect of smoothing the frequency over time. Dithering is therefore equivalent to 16-bits of delay value. If this full range is not needed, the step size can be increased by writing the Step Size field in the Dithering register (DFLLULPDITHER.STEP). By default the frequency comparator resolution is limited to 1/RATIO over a single reference clock period. In dithering operation, the comparator resolution can be made finer by comparing over multiple reference clock SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 278 periods. This behavior is controlled by the Period field in the Dithering register (DFLLULPDITHER.PER). The fine control offered by dithering means that the tuner will take longer to adjust to coarse changes in the frequency. When dithering mode is active, the tuner will attempt to get close to the final locked value before starting the dithering engine. Dithering mode can be restarted if there is a write to DFLLULPDLY, or if the tuner is disabled and re-enabled. 23.6.6 Event Triggered Tuning The EVCTRL.TUNEEI and EVCTRL.TUNEINV control bits allow to start a tuning sequence on an incoming event or inverted event. On an incoming rising or falling edge of the event input, the DFLLULP close loop tuner unlock and start over a frequency tuning, depending on the configuration of the DFLLULP registers, until the tuner achieves a new lock. 23.6.7 Digital Phase Locked Loop (DPLL) Operation The task of the DPLL is to maintain coherence between the input (reference) signal and the respective output frequency, CLK_DPLL, via phase comparison. The DPLL controller supports three independent sources of reference clocks: • XOSC32K: this clock is provided by the 32K External Crystal Oscillator (XOSC32K). • XOSC: this clock is provided by the External Multipurpose Crystal Oscillator (XOSC). • GCLK: this clock is provided by the Generic Clock Controller. When the controller is enabled, the relationship between the reference clock frequency and the output clock frequency is: ݂CK = ݂CKR × LDR + 1 + LDRFRAC 16 × 1 2 PRESC Where fCK is the frequency of the DPLL output clock, LDR is the loop divider ratio integer part, LDRFRAC is the loop divider ratio fractional part, fCKR is the frequency of the selected reference clock, and PRESC is the output prescaler value. Figure 23-3. DPLL Block Diagram XIN XOUT XOSC XIN32 XOUT32 XOSC32K GCLK_DPLL DIVIDER DPLLCTRLB.DIV DPLLCTRLB.REFCLK TDC DIGITAL FILTER DPLLCTRLB.FILTER DCO CKDIV4 CKDIV2 CKDIV1 DPLLPRESC CLK_DPLL RATIO DPLLRATIO CK CKR CG When the controller is disabled, the output clock is low. If the Loop Divider Ratio Fractional part bit field in the DPLL Ratio register (DPLLRATIO.LDRFRAC) is zero, the DPLL works in integer mode. Otherwise, the fractional mode is activated. Note that the fractional part has a negative impact on the jitter of the DPLL. Example (integer mode only): assuming FCKR = 32kHz and FCK = 48MHz, the multiplication ratio is 1500. It means that LDR shall be set to 1499. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 279 Example (fractional mode): assuming FCKR = 32kHz and FCK = 48.006MHz, the multiplication ratio is 1500.1875 (1500 + 3/16). Thus LDR is set to 1499 and LDRFRAC to 3. Related Links 18. GCLK - Generic Clock Controller 24. OSC32KCTRL – 32KHz Oscillators Controller 23.6.7.1 Basic Operation 23.6.7.1.1 Initialization, Enabling, Disabling, and Resetting The DPLLC is enabled by writing a '1' to the Enable bit in the DPLL Control A register (DPLLCTRLA.ENABLE). The DPLLC is disabled by writing a zero to this bit. The DPLLSYNCBUSY.ENABLE is set when the DPLLCTRLA.ENABLE bit is modified. It is cleared when the DPLL output clock CK has sampled the bit at the high level after enabling the DPLL. When disabling the DPLL, DPLLSYNCBUSY.ENABLE is cleared when the output clock is no longer running. Figure 23-4. Enable Synchronization Busy Operation ENABLE CK SYNCBUSY.ENABLE CLK_APB_OSCCTRL The frequency of the DPLL output clock CK is stable when the module is enabled and when the Lock bit in the DPLL Status register is set (DPLLSTATUS.LOCK). When the Lock Time bit field in the DPLL Control B register (DPLLCTRLB.LTIME) is non-zero, a user defined lock time is used to validate the lock operation. In this case the lock time is constant. If DPLLCTRLB.LTIME=0, the lock signal is linked with the status bit of the DPLL, and the lock time varies depending on the filter selection and the final target frequency. Note:  GCLK_DPLL_32K is responsible for counting the user defined lock time (LTIME different from 0x0), hence must be enabled. When the Wake Up Fast bit (DPLLCTRLB.WUF) is set, the wake up fast mode is activated. In this mode the clock gating cell is enabled at the end of the startup time. At this time the final frequency is not stable, as it is still during the acquisition period, but it allows to save several milliseconds. After first acquisition, the Lock Bypass bit (DPLLCTRLB.LBYPASS) indicates if the lock signal is discarded from the control of the clock gater (CG) generating the output clock CLK_DPLL. Table 23-3. CLK_DPLL Behavior from Startup to First Edge Detection WUF LTIME CLK_DPLL Behavior 0 0 Normal Mode: First Edge when lock is asserted 0 Not Equal To Zero Lock Timer Timeout mode: First Edge when the timer down-counts to 0. 1 X Wake Up Fast Mode: First Edge when CK is active (startup time) SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 280 Table 23-4. CLK_DPLL Behavior after First Edge Detection LBYPASS CLK_DPLL Behavior 0 Normal Mode: the CLK_DPLL is turned off when lock signal is low. 1 Lock Bypass Mode: the CLK_DPLL is always running, lock is irrelevant. Figure 23-5. CK and CLK_DPLL Output from DPLL Off Mode to Running Mode CKR ENABLE CK LOCK tstartup_time tlock_time CK STABLE CLK_DPLL 23.6.7.1.2 Reference Clock Switching When a software operation requires reference clock switching, the recommended procedure is to turn the DPLL into the standby mode, modify the DPLLCTRLB.REFCLK to select the desired reference source, and activate the DPLL again. 23.6.7.1.3 Output Clock Prescaler The DPLL controller includes an output prescaler. This prescaler provides three selectable output clocks CK, CKDIV2 and CKDIV4. The Prescaler bit field in the DPLL Prescaler register (DPLLPRESC.PRESC) is used to select a new output clock prescaler. When the prescaler field is modified, the DPLLSYNCBUSY.DPLLPRESC bit is set. It will be cleared by hardware when the synchronization is over. Figure 23-6. Output Clock Switching Operation CKR PRESC CLK_DPLL DPLL_LOCK 0 1 CK STABLE CK SWITCHING CK STABLE SYNCBUSY.PRESC CK CKDIV2 23.6.7.1.4 Loop Divider Ratio Updates The DPLL Controller supports on-the-fly update of the DPLL Ratio Control (DPLLRATIO) register, allowing to modify the loop divider ratio and the loop divider ratio fractional part when the DPLL is enabled. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 281 STATUS.DPLLLDRTO is set when the DPLLRATIO register has been modified and the DPLL analog cell has successfully sampled the updated value. At that time the DPLLSTATUS.LOCK bit is cleared and set again by hardware when the output frequency reached a stable state. Figure 23-7. RATIOCTRL register update operation CKR LDR LDRFRAC CK CLK_DPLL mult0 mult1 LOCK LOCKL 23.6.7.1.5 Digital Filter Selection The PLL digital filter (PI controller) is automatically adjusted in order to provide a good compromise between stability and jitter. Nevertheless a software operation can override the filter setting using the Filter bit field in the DPLL Control B register (DPLLCTRLB.FILTER). The Low Power Enable bit (DPLLCTRLB.LPEN) can be use to bypass the Time to Digital Converter (TDC) module. 23.6.8 DMA Operation Not applicable. 23.6.9 Interrupts The OSCCTRL has the following interrupt sources: • XOSCRDY - Multipurpose Crystal Oscillator Ready: A 0-to-1 transition on the STATUS.XOSCRDY bit is detected • CLKFAIL - Clock Failure. A 0-to-1 transition on the STATUS.CLKFAIL bit is detected • OSC16MRDY - 16MHz Internal Oscillator Ready: A 0-to-1 transition on the STATUS.OSC16MRDY bit is detected • DFLLULP-related: – DFLLULPRDY - DFLLULP Ready: A 0-to1 transition of the STATUS.DFLLULPRDY bit is detected. – DFLLULPLOCK - DFLLULP Lock: A 0-to-1 transition of the STATUS.DFLLULPLOCK bit is detected. – DFLLULPNOLOCK - DFLLULP No Lock: A 0-to-1 transition of the STATUS.DFLLULPNOLOCK bit is detected. • DPLL-related: – DPLLLOCKR - DPLL Lock Rise: A 0-to-1 transition of the STATUS.DPLLLOCKR bit is detected – DPLLLOCKF - DPLL Lock Fall: A 0-to-1 transition of the STATUS.DPLLLOCKF bit is detected – DPLLLTTO - DPLL Lock Timer Time-out: A 0-to-1 transition of the STATUS.DPLLLTTO bit is detected – DPLLLDRTO - DPLL Loop Divider Ratio Update Complete. A 0-to-1 transition of the STATUS.DPLLLDRTO bit is detected SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 282 All these interrupts are synchronous wake-up source. Each interrupt source has an interrupt flag associated with it. The interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG) is set when the interrupt condition occurs. Each interrupt can be individually enabled by writing a '1' to the corresponding bit in the Interrupt Enable Set register (INTENSET), and disabled by writing a '1' to the corresponding bit in the Interrupt Enable Clear register (INTENCLR). An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until the interrupt flag is cleared, the interrupt is disabled, or the OSCCTRL is reset. See the INTFLAG register for details on how to clear interrupt flags. The OSCCTRL has one common interrupt request line for all the interrupt sources. The user must read the INTFLAG register to determine which interrupt condition is present. Refer to the INTFLAG register for details. Note:  The interrupts must be globally enabled for interrupt requests to be generated. 23.6.10 Events The CFD can generate the following output event: • Clock Failure (CLKFAIL): Generated when the Clock Failure status bit is set in the Status register (STATUS.CLKFAIL). The CFD event is not generated when the Clock Switch bit (STATUS.CLKSW) in the Status register is set. Writing a '1' to an Event Output bit in the Event Control register (EVCTRL.CFDEO) enables the CFD output event. Writing a '0' to this bit disables the CFD output event. Refer to the Event System chapter for details on configuring the event system. The DFLLULP can take the following actions on an input event: • Unlock the DFLLULP close loop tuner and start over a frequency tuning, depending on the settings of the DFLLULP registers, until the tuner achieves a new lock. Writing a '1' to the Event Input Enable bit in the Event Control register (EVCTRL.TUNEEI) enables the corresponding action on input event. Writing a '0' to this bit disables the corresponding action on input event. Refer to the Event System chapter for details on configuring the event system. 23.6.11 Synchronization DFLLULP Due to the asynchronicity between the main clock domain (CLK_OSCCTRL_APB) and the internal clock domain, some registers are synchronized when written. When a write-synchronized register is written, the corresponding bit in the Synchronization Busy register (DFLLULPSYNCBUSY) is set immediately. When the write-synchronization is complete, this bit is cleared. Reading a write-synchronized register while the synchronization is ongoing will return the value written, and not the current value in the peripheral clock domain. To read the current value in the peripheral clock domain after writing a register, the user must wait for the corresponding DFLLULPSYNCBUSY bit to be cleared before reading the value. If a register is written while the corresponding bit in DFLLULPSYNCBUSY is one, the write is discarded and an error is generated. The following bits and registers are write-synchronized: • Delay Value register (DFLLULPDLY) Write-synchronization is denoted by the Write-Synchronized property in the register description. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 283 FDPLL96M Due to the multiple clock domains, some registers in the FDPLL96M must be synchronized when accessed. When executing an operation that requires synchronization, the relevant synchronization bit in the Synchronization Busy register (DPLLSYNCBUSY) will be set immediately, and cleared when synchronization is complete. The following bits need synchronization when written: • Enable bit in control register A (DPLLCTRLA.ENABLE) • DPLL Ratio register (DPLLRATIO) • DPLL Prescaler register (DPLLPRESC) SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 284 23.7 Register Summary Offset Name Bit Pos. 0x00 EVCTRL 7:0 TUNEINV TUNEEI CFDEO 0x01 ... 0x03 Reserved 0x04 INTENCLR 7:0 OSC16MRDY CLKFAIL XOSCRDY 15:8 DFLLULPNOL OCK DFLLULPLOC K DFLLULPRDY 23:16 DPLLLDRTO DPLLLTO DPLLLCKF DPLLLCKR 31:24 0x08 INTENSET 7:0 OSC16MRDY CLKFAIL XOSCRDY 15:8 DFLLULPNOL OCK DFLLULPLOC K DFLLULPRDY 23:16 DPLLLDRTO DPLLLTO DPLLLCKF DPLLLCKR 31:24 0x0C INTFLAG 7:0 OSC16MRDY CLKFAIL XOSCRDY 15:8 DFLLULPNOL OCK DFLLULPLOC K DFLLULPRDY 23:16 DPLLLDRTO DPLLLTO DPLLLCKF DPLLLCKR 31:24 0x10 STATUS 7:0 OSC16MRDY CLKSW CLKFAIL XOSCRDY 15:8 DFLLULPNOL OCK DFLLULPLOC K DFLLULPRDY 23:16 DPLLLDRTO DPLLLTO DPLLLCKF DPLLLCKR 31:24 0x14 XOSCCTRL 7:0 ONDEMAND RUNSTDBY SWBACK CFDEN XTALEN ENABLE 15:8 STARTUP[3:0] AMPGC GAIN[2:0] 0x16 CFDPRESC 7:0 CFDPRESC[2:0] 0x17 Reserved 0x18 OSC16MCTRL 7:0 ONDEMAND RUNSTDBY FSEL[1:0] ENABLE 0x19 ... 0x1B Reserved 0x1C DFLLULPCTRL 7:0 ONDEMAND RUNSTDBY DITHER SAFE BINSE ENABLE 15:8 DIV[2:0] 0x1E DFLLULPDITHER 7:0 PER[2:0] STEP[2:0] 0x1F DFLLULPRREQ 7:0 RREQ 0x20 DFLLULPDLY 7:0 DELAY[7:0] 15:8 23:16 31:24 0x24 DFLLULPRATIO 7:0 RATIO[7:0] 15:8 RATIO[10:8] 23:16 31:24 SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 285 Offset Name Bit Pos. 0x28 DFLLULPSYNCBU SY 7:0 DELAY ENABLE 15:8 23:16 31:24 0x2C DPLLCTRLA 7:0 ONDEMAND RUNSTDBY ENABLE 0x2D ... 0x2F Reserved 0x30 DPLLRATIO 7:0 LDR[7:0] 15:8 LDR[11:8] 23:16 LDRFRAC[3:0] 31:24 0x34 DPLLCTRLB 7:0 REFCLK[1:0] WUF LPEN FILTER[1:0] 15:8 LBYPASS LTIME[2:0] 23:16 DIV[7:0] 31:24 DIV[10:8] 0x38 DPLLPRESC 7:0 PRESC[1:0] 0x39 ... 0x3B Reserved 0x3C DPLLSYNCBUSY 7:0 DPLLPRESC DPLLRATIO ENABLE 0x3D ... 0x3F Reserved 0x40 DPLLSTATUS 7:0 CLKRDY LOCK 23.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16-, and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Write-protection is denoted by the "PAC Write-Protection" property in each individual register description. Refer to the 23.5.8 Register Access Protection section and the PAC - Peripheral Access Controller chapter for details. Some registers require synchronization when read and/or written. Synchronization is denoted by the "Read-Synchronized" or "Write-Synchronized" property in each individual register description. Refer to the section on Synchronization for details. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 286 23.8.1 Event Control Name:  EVCTRL Offset:  0x00 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 TUNEINV TUNEEI CFDEO Access R/W R/W R/W Reset 0 0 0 Bit 2 – TUNEINV Tune Event Input Invert This bit is used to invert the input event of the DFLLULP tuner. Value Description 0 Tune event input source is not inverted. 1 Tune event input source is inverted. Bit 1 – TUNEEI Tune Event Input Enable This bit is used to enable the input event of the DFLLULP tuner. Value Description 0 A new closed loop tuning will not be triggered on any incoming event. 1 A new closed loop tuning will be triggered on any incoming event. Bit 0 – CFDEO Clock Failure Detector Event Output Enable This bit indicates whether the Clock Failure detector event output is enabled or not and an output event will be generated when the Clock Failure detector detects a clock failure Value Description 0 Clock Failure detector event output is disabled and no event will be generated. 1 Clock Failure detector event output is enabled and an event will be generated. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 287 23.8.2 Interrupt Enable Clear Name:  INTENCLR Offset:  0x04 Reset:  0x00000000 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 DPLLLDRTO DPLLLTO DPLLLCKF DPLLLCKR Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DFLLULPNOLO CK DFLLULPLOCK DFLLULPRDY Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 OSC16MRDY CLKFAIL XOSCRDY Access R/W R/W R/W Reset 0 0 0 Bit 19 – DPLLLDRTO DPLL Loop Divider Ratio Update Complete Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the DPLL Loop Divider Ratio Update Complete Interrupt Enable bit, which disables the DPLL Loop Divider Ratio Update Complete interrupt. Value Description 0 The DPLL Loop Divider Ratio Update Complete interrupt is disabled. 1 The DPLL Loop Divider Ratio Update Complete interrupt is enabled, and an interrupt request will be generated when the DPLL Loop Divider Ratio Update Complete Interrupt flag is set. Bit 18 – DPLLLTO DPLL Lock Timeout Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the DPLL Lock Timeout Interrupt Enable bit, which disables the DPLL Lock Timeout interrupt. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 288 Value Description 0 The DPLL Lock Timeout interrupt is disabled. 1 The DPLL Lock Timeout interrupt is enabled, and an interrupt request will be generated when the DPLL Lock Timeout Interrupt flag is set. Bit 17 – DPLLLCKF DPLL Lock Fall Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the DPLL Lock Fall Interrupt Enable bit, which disables the DPLL Lock Fall interrupt. Value Description 0 The DPLL Lock Fall interrupt is disabled. 1 The DPLL Lock Fall interrupt is enabled, and an interrupt request will be generated when the DPLL Lock Fall Interrupt flag is set. Bit 16 – DPLLLCKR DPLL Lock Rise Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the DPLL Lock Rise Interrupt Enable bit, which disables the DPLL Lock Rise interrupt. Value Description 0 The DPLL Lock Rise interrupt is disabled. 1 The DPLL Lock Rise interrupt is enabled, and an interrupt request will be generated when the DPLL Lock Rise Interrupt flag is set. Bit 10 – DFLLULPNOLOCK DFLLULP No Lock Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the DFLLULP No Lock interrupt Enable bit, which disables the DFLLULP No Lock interrupt. Value Description 0 The DFLLULP No Lock is disabled. 1 The DFLLULP No Lock interrupt is enabled, and an interrupt request will be generated when the DFLLULP No Lock Interrupt flag is set. Bit 9 – DFLLULPLOCK DFLLULP Lock Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the DFLLULP Lock Interrupt Enable bit, which disables the DFLLULP Lock interrupt. Value Description 0 The DFLLULP Lock interrupt is disabled. 1 The DFLLULP Lock interrupt is enabled, and an interrupt request will be generated when the DFLLULP Lock Interrupt flag is set. Bit 8 – DFLLULPRDY DFLLULP Ready interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the DFLLULP Ready Interrupt Enable bit, which disables the DFLLULP Ready interrupt. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 289 Value Description 0 The DFLLULP Ready interrupt is disabled. 1 The DFLLULP Ready interrupt is enabled, and an interrupt request will be generated when the DFLLULP Ready Interrupt flag is set. Bit 4 – OSC16MRDY OSC16M Ready Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the OSC16M Ready Interrupt Enable bit, which disables the OSC16M Ready interrupt. Value Description 0 The OSC16M Ready interrupt is disabled. 1 The OSC16M Ready interrupt is enabled, and an interrupt request will be generated when the OSC16M Ready Interrupt flag is set. Bit 1 – CLKFAIL Clock Failure Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the XOSC Clock Failure Interrupt Enable bit, which disables the XOSC Clock Failure interrupt. Value Description 0 The XOSC Clock Failure interrupt is disabled. 1 The XOSC Clock Failure interrupt is enabled, and an interrupt request will be generated when the XOSC Clock Failure Interrupt flag is set. Bit 0 – XOSCRDY XOSC Ready Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the XOSC Ready Interrupt Enable bit, which disables the XOSC Ready interrupt. Value Description 0 The XOSC Ready interrupt is disabled. 1 The XOSC Ready interrupt is enabled, and an interrupt request will be generated when the XOSC Ready Interrupt flag is set. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 290 23.8.3 Interrupt Enable Set Name:  INTENSET Offset:  0x08 Reset:  0x00000000 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear register (INTENCLR). Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 DPLLLDRTO DPLLLTO DPLLLCKF DPLLLCKR Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DFLLULPNOLO CK DFLLULPLOCK DFLLULPRDY Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 OSC16MRDY CLKFAIL XOSCRDY Access R/W R/W R/W Reset 0 0 0 Bit 19 – DPLLLDRTO DPLL Loop Divider Ratio Update Complete Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the DPLL Loop Ratio Update Complete Interrupt Enable bit, which enables the DPLL Loop Ratio Update Complete interrupt. Value Description 0 The DPLL Loop Divider Ratio Update Complete interrupt is disabled. 1 The DPLL Loop Ratio Update Complete interrupt is enabled, and an interrupt request will be generated when the DPLL Loop Ratio Update Complete Interrupt flag is set. Bit 18 – DPLLLTO DPLL Lock Timeout Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the DPLL Lock Timeout Interrupt Enable bit, which enables the DPLL Lock Timeout interrupt. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 291 Value Description 0 The DPLL Lock Timeout interrupt is disabled. 1 The DPLL Lock Timeout interrupt is enabled, and an interrupt request will be generated when the DPLL Lock Timeout Interrupt flag is set. Bit 17 – DPLLLCKF DPLL Lock Fall Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the DPLL Lock Fall Interrupt Enable bit, which enables the DPLL Lock Fall interrupt. Value Description 0 The DPLL Lock Fall interrupt is disabled. 1 The DPLL Lock Fall interrupt is enabled, and an interrupt request will be generated when the DPLL Lock Fall Interrupt flag is set. Bit 16 – DPLLLCKR DPLL Lock Rise Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the DPLL Lock Rise Interrupt Enable bit, which enables the DPLL Lock Rise interrupt. Value Description 0 The DPLL Lock Rise interrupt is disabled. 1 The DPLL Lock Rise interrupt is enabled, and an interrupt request will be generated when the DPLL Lock Rise Interrupt flag is set. Bit 10 – DFLLULPNOLOCK DFLLULP No Lock Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the DFLLULP No Lock interrupt Enable bit, which enables the DFLLULP No Lock interrupt. Value Description 0 The DFLLULP No Lock is disabled. 1 The DFLL No Lock interrupt is enabled, and an interrupt request will be generated when the DFLL No Lock Interrupt flag is set. Bit 9 – DFLLULPLOCK DFLLULP Lock Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the DFLLULP Lock Interrupt Enable bit, which enables the DFLLULP Lock interrupt. Value Description 0 The DFLLULP Lock interrupt is disabled. 1 The DFLLULP Lock interrupt is enabled, and an interrupt request will be generated when the DFLL Lock Interrupt flag is set. Bit 8 – DFLLULPRDY DFLLULP Ready interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the DFLLULP Ready Interrupt Enable bit, which enables the DFLLULP Ready interrupt. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 292 Value Description 0 The DFLLULP Ready interrupt is disabled. 1 The DFLLULP Ready interrupt is enabled, and an interrupt request will be generated when the DFLLULP Ready Interrupt flag is set. Bit 4 – OSC16MRDY OSC16M Ready Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the OSC16M Ready Interrupt Enable bit, which enables the OSC16M Ready interrupt. Value Description 0 The OSC16M Ready interrupt is disabled. 1 The OSC16M Ready interrupt is enabled, and an interrupt request will be generated when the OSC16M Ready Interrupt flag is set. Bit 1 – CLKFAIL XOSC Clock Failure Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the XOSC Clock Failure Interrupt Enable bit, which enables the XOSC Clock Failure Interrupt. Value Description 0 The XOSC Clock Failure Interrupt is disabled. 1 The XOSC Clock Failure Interrupt is enabled, and an interrupt request will be generated when the XOSC Clock Failure Interrupt flag is set. Bit 0 – XOSCRDY XOSC Ready Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the XOSC Ready Interrupt Enable bit, which enables the XOSC Ready interrupt. Value Description 0 The XOSC Ready interrupt is disabled. 1 The XOSC Ready interrupt is enabled, and an interrupt request will be generated when the XOSC Ready Interrupt flag is set. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 293 23.8.4 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x0C Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 DPLLLDRTO DPLLLTO DPLLLCKF DPLLLCKR Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DFLLULPNOLO CK DFLLULPLOCK DFLLULPRDY Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 OSC16MRDY CLKFAIL XOSCRDY Access R/W R/W R/W Reset 0 0 0 Bit 19 – DPLLLDRTO DPLL Loop Divider Ratio Update Complete This flag is cleared by writing '1' to it. This flag is set on a high to low transition of the DPLL Loop Divider Ratio Update Complete bit in the Status register (STATUS.DPLLLDRTO) and will generate an interrupt request if INTENSET.DPLLLDRTO is '1'. Writing '0' to this bit has no effect. Writing '1' to this bit clears the DPLL Loop Divider Ratio Update Complete interrupt flag. Bit 18 – DPLLLTO DPLL Lock Timeout This flag is cleared by writing '1' to it. This flag is set on 0-to-1 transition of the DPLL Lock Timeout bit in the Status register (STATUS.DPLLLTO) and will generate an interrupt request if INTENSET.DPLLLTO is '1'. Writing '0' to this bit has no effect. Writing '1' to this bit clears the DPLL Lock Timeout interrupt flag. Bit 17 – DPLLLCKF DPLL Lock Fall This flag is cleared by writing '1' to it. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 294 This flag is set on 0-to-1 transition of the DPLL Lock Fall bit in the Status register (STATUS.DPLLLCKF) and will generate an interrupt request if INTENSET.DPLLLCKF is '1'. Writing '0' to this bit has no effect. Writing '1' to this bit clears the DPLL Lock Fall interrupt flag. Bit 16 – DPLLLCKR DPLL Lock Rise This flag is cleared by writing '1' to it. This flag is set on 0-to-1 transition of the DPLL Lock Rise bit in the Status register (STATUS.DPLLLCKR) and will generate an interrupt request if INTENSET.DPLLLCKR is '1'. Writing '0' to this bit has no effect. Writing '1' to this bit clears the DPLL Lock Rise interrupt flag. Bit 10 – DFLLULPNOLOCK DFLLULP No Lock This flag is cleared by writing '1' to it. This flag is set on 0-to-1 transition of the DFLLULP No Lock bit in the Status register (STATUS.DFLLULPNOLOCK) and will generate an interrupt request if INTENSET.DFLLULPNOLOCK is '1'. Writing '0' to this bit has no effect. Writing '1' to this bit clears the DFLLULP No Lock interrupt flag. Bit 9 – DFLLULPLOCK DFLLULP Lock This flag is cleared by writing '1' to it. This flag is set on 0-to-1 transition of the DFLLULP Lock bit in the Status register (STATUS.DFLLULPLOCK) and will generate an interrupt request if INTENSET.DFLLULPLOCK is '1'. Writing '0' to this bit has no effect. Writing '1' to this bit clears the DFLLULP Lock interrupt flag. Bit 8 – DFLLULPRDY DFLLULP Ready This flag is cleared by writing '1' to it. This flag is set on 0-to-1 transition of the DFLLULP Ready bit in the Status register (STATUS.DFLLULPREADY) and will generate an interrupt request if INTENSET.DFLLULPREADY is '1'. Writing '0' to this bit has no effect. Writing '1' to this bit clears the DFLLULP Ready interrupt flag. Bit 4 – OSC16MRDY OSC16M Ready This flag is cleared by writing '1' to it. This flag is set on 0-to-1 transition of the OSC16M Ready bit in the Status register (STATUS.OSC16MRDY) and will generate an interrupt request if INTENSET.OSC16MRDY is '1'. Writing '0' to this bit has no effect. Writing '1' to this bit clears the OSC16M Ready interrupt flag. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 295 Bit 1 – CLKFAIL XOSC Failure Detection This flag is cleared by writing '1' to it. This flag is set on a 0-to-1 transition of the XOSC Clock Failure bit in the Status register (STATUS.CLKFAIL) and will generate an interrupt request if INTENSET.CLKFAIL is '1'. Writing '0' to this bit has no effect. Writing '1' to this bit clears the XOSC Clock Fail interrupt flag. Bit 0 – XOSCRDY XOSC Ready This flag is cleared by writing '1' to it. This flag is set on a 0-to-1 transition of the XOSC Ready bit in the Status register (STATUS.XOSCRDY) and will generate an interrupt request if INTENSET.XOSCRDY is '1'. Writing '0' to this bit has no effect. Writing '1' to this bit clears the XOSC Ready interrupt flag. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 296 23.8.5 Status Name:  STATUS Offset:  0x10 Reset:  0x00000100 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 DPLLLDRTO DPLLLTO DPLLLCKF DPLLLCKR Access R R R R Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DFLLULPNOLO CK DFLLULPLOCK DFLLULPRDY Access R R R Reset 0 0 1 Bit 7 6 5 4 3 2 1 0 OSC16MRDY CLKSW CLKFAIL XOSCRDY Access R R R R Reset 0 0 0 0 Bit 19 – DPLLLDRTO DPLL Loop Divider Ratio Update Complete Value Description 0 DPLL Loop Divider Ratio Update Complete not detected. 1 DPLL Loop Divider Ratio Update Complete detected. Bit 18 – DPLLLTO DPLL Lock Timeout Value Description 0 DPLL Lock time-out not detected. 1 DPLL Lock time-out detected. Bit 17 – DPLLLCKF DPLL Lock Fall Value Description 0 DPLL Lock fall edge not detected. 1 DPLL Lock fall edge detected. Bit 16 – DPLLLCKR DPLL Lock Rise SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 297 Value Description 0 DPLL Lock rise edge not detected. 1 DPLL Lock rise edge detected. Bit 10 – DFLLULPNOLOCK DFLLULP No Lock Value Description 0 DFLLULP Tuner no lock state is not detected. 1 DFLLULP Tuner no lock state is detected. Bit 9 – DFLLULPLOCK DFLLULP Lock Value Description 0 DFLLULP Tuner lock state is not detected. 1 DFLLULP Tuner lock state is detected. Bit 8 – DFLLULPRDY DFLLULP Ready Value Description 0 DFLLULP is not ready. 1 DFLLULP is stable and ready to be used as a clock source. Bit 4 – OSC16MRDY OSC16M Ready Value Description 0 OSC16M is not ready. 1 OSC16M is stable and ready to be used as a clock source. Bit 2 – CLKSW XOSC Clock Switch Value Description 0 XOSC is not switched and provides the external clock or crystal oscillator clock. 1 XOSC is switched and provides the safe clock. Bit 1 – CLKFAIL XOSC Clock Failure Value Description 0 No XOSC failure detected. 1 A XOSC failure was detected. Bit 0 – XOSCRDY XOSC Ready Value Description 0 XOSC is not ready. 1 XOSC is stable and ready to be used as a clock source. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 298 23.8.6 External Multipurpose Crystal Oscillator (XOSC) Control Name:  XOSCCTRL Offset:  0x14 Reset:  0x0080 Property:  PAC Write-Protection Bit 15 14 13 12 11 10 9 8 STARTUP[3:0] AMPGC GAIN[2:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 ONDEMAND RUNSTDBY SWBACK CFDEN XTALEN ENABLE Access R/W R/W R/W R/W R/W R/W Reset 1 0 0 0 0 0 Bits 15:12 – STARTUP[3:0] Start-Up Time These bits select start-up time for the oscillator. The OSCULP32K oscillator is used to clock the start-up counter. Table 23-5. Start-Up Time for External Multipurpose Crystal Oscillator STARTUP[3:0] Number of OSCULP32K Clock Cycles Number of XOSC Clock Cycles Approximate Equivalent Time [µs] 0x0 1 3 31 0x1 2 3 61 0x2 4 3 122 0x3 8 3 244 0x4 16 3 488 0x5 32 3 977 0x6 64 3 1953 0x7 128 3 3906 0x8 256 3 7813 0x9 512 3 15625 0xA 1024 3 31250 0xB 2048 3 62500µs 0xC 4096 3 125000 0xD 8192 3 250000 SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 299 STARTUP[3:0] Number of OSCULP32K Clock Cycles Number of XOSC Clock Cycles Approximate Equivalent Time [µs] 0xE 16384 3 500000 0xF 32768 3 1000000 Note:  1. Actual startup time is 1 OSCULP32K cycle + 3 XOSC cycles. 2. The given time neglects the three XOSC cycles before OSCULP32K cycle. Bit 11 – AMPGC Automatic Amplitude Gain Control Note:  This bit must be set only after the XOSC has settled, indicated by the XOSC Ready flag in the Status register (STATUS.XOSCRDY). Value Description 0 The automatic amplitude gain control is disabled. 1 The automatic amplitude gain control is enabled. Amplitude gain will be automatically adjusted during Crystal Oscillator operation. Bits 10:8 – GAIN[2:0] Oscillator Gain These bits select the gain for the oscillator. The listed maximum frequencies are recommendations, and might vary based on capacitive load and crystal characteristics. Those bits must be properly configured even when the Automatic Amplitude Gain Control is active. Value Recommended Max Frequency [MHz] 0x0 2 0x1 4 0x2 8 0x3 16 0x4 30 0x5-0x7 Reserved Bit 7 – ONDEMAND On Demand Control The On Demand operation mode allows the oscillator to be enabled or disabled, depending on peripheral clock requests. If the ONDEMAND bit has been previously written to '1', the oscillator will be running only when requested by a peripheral. If there is no peripheral requesting the oscillator’s clock source, the oscillator will be in a disabled state. If On Demand is disabled, the oscillator will always be running when enabled. In standby sleep mode, the On Demand operation is still active. Value Description 0 The oscillator is always on, if enabled. 1 The oscillator is enabled when a peripheral is requesting the oscillator to be used as a clock source. The oscillator is disabled if no peripheral is requesting the clock source. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 300 Bit 6 – RUNSTDBY Run in Standby This bit controls how the XOSC behaves during Standby Sleep mode, together with the ONDEMAND bit: Value Description 0 The XOSC is not running in Standby sleep mode if no peripheral requests the clock. 1 The XOSC is running in Standby sleep mode. If ONDEMAND=1, the XOSC will be running when a peripheral is requesting the clock. If ONDEMAND=0, the clock source will always be running in Standby sleep mode. Bit 4 – SWBACK Clock Switch Back This bit controls the XOSC output switch back to the external clock or crystal oscillator in case of clock recovery: Value Description 0 The clock switch back is disabled. 1 The clock switch back is enabled. This bit is reset once the XOSC output clock is switched back to the external clock or crystal oscillator. Bit 3 – CFDEN Clock Failure Detector Enable This bit controls the clock failure detector: Value Description 0 The Clock Failure Detector is disabled. 1 the Clock Failure Detector is enabled. Bit 2 – XTALEN Crystal Oscillator Enable This bit controls the connections between the I/O pads and the external clock or crystal oscillator: Value Description 0 External clock connected on XIN. XOUT can be used as general-purpose I/O. 1 Crystal connected to XIN/XOUT. Bit 1 – ENABLE Oscillator Enable Value Description 0 The oscillator is disabled. 1 The oscillator is enabled. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 301 23.8.7 Clock Failure Detector Prescaler Name:  CFDPRESC Offset:  0x16 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 CFDPRESC[2:0] Access R/W R/W R/W Reset 0 0 0 Bits 2:0 – CFDPRESC[2:0] Clock Failure Detector Prescaler These bits select the prescaler for the clock failure detector. The OSC16M oscillator is used to clock the CFD prescaler. The CFD safe clock frequency is the OSC16M frequency divided by 2^CFDPRESC. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 302 23.8.8 16MHz Internal Oscillator (OSC16M) Control Name:  OSC16MCTRL Offset:  0x18 Reset:  0x82 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 ONDEMAND RUNSTDBY FSEL[1:0] ENABLE Access R/W R/W R/W R/W R/W Reset 1 0 0 0 1 Bit 7 – ONDEMAND On Demand Control The On Demand operation mode allows the oscillator to be enabled or disabled depending on peripheral clock requests. If the ONDEMAND bit has been previously written to '1', the oscillator will only be running when requested by a peripheral. If there is no peripheral requesting the oscillator’s clock source, the oscillator will be in a disabled state. If On Demand is disabled the oscillator will always be running when enabled. In standby sleep mode, the On Demand operation is still active. Value Description 0 The oscillator is always on, if enabled. 1 The oscillator is enabled when a peripheral is requesting the oscillator to be used as a clock source. The oscillator is disabled if no peripheral is requesting the clock source. Bit 6 – RUNSTDBY Run in Standby This bit controls how the OSC16M behaves during standby sleep mode. Value Description 0 The OSC16M is disabled in standby sleep mode if no peripheral requests the clock. 1 The OSC16M is not stopped in standby sleep mode. If ONDEMAND=1, the OSC16M will be running when a peripheral is requesting the clock. If ONDEMAND=0, the clock source will always be running in standby sleep mode. Bits 3:2 – FSEL[1:0] Oscillator Frequency Selection These bits control the oscillator frequency range. Value Description 0x00 4MHz 0x01 8MHz 0x10 12MHz 0x11 16MHz Bit 1 – ENABLE Oscillator Enable SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 303 Value Description 0 The oscillator is disabled. 1 The oscillator is enabled. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 304 23.8.9 DFLLULP Control Name:  DFLLULPCTRL Offset:  0x1C Reset:  0x0000 Property:  PAC Write-Protection, Enable-Protected, Write-synchronized Bit 15 14 13 12 11 10 9 8 DIV[2:0] Access R R R R R R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 ONDEMAND RUNSTDBY DITHER SAFE BINSE ENABLE Access R/W R/W R/W R/W R/W R/W R Reset 0 0 0 0 0 0 0 Bits 10:8 – DIV[2:0] Division Factor This field defines the division factor for the output frequency of the DFLLULP. This value from production test, which depends on PL0 or PL2 mode, must be copied from the NVM software calibration row into the DFLLULPCTRL register by software. The value must be changed before switching on a new Performance Level mode (PL0 or PL2). These bits are not synchronized. Value Name Description 0x0 DIV1 Frequency divided by 1 0x1 DIV2 Frequency divided by 2 0x2 DIV4 Frequency divided by 4 0x3 DIV8 Frequency divided by 8 0x4 DIV16 Frequency divided by 16 0x5 DIV32 Frequency divided by 32 0x6 - 0x7 - Reserved Bit 7 – ONDEMAND On Demand The On Demand operation mode allows the oscillator to be enabled or disabled, depending on peripheral clock requests. If the ONDEMAND bit has been previously written to '1', the oscillator will be running only when requested by a peripheral. If there is no peripheral requesting the oscillator’s clock source, the oscillator will be in a disabled state. If On Demand is disabled, the oscillator will always be running when enabled. In standby sleep mode, the On Demand operation is still active. This bit is not enabled-protected. This bit is not synchronized. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 305 Bit 6 – RUNSTDBY Run in Standby This bit controls how the DFLLULP behaves during standby sleep mode, together with the ONDEMAND bit. This bit is not enabled-protected. This bit is not synchronized Bit 5 – DITHER Tuner Dither Mode This bit is not synchronized. Value Description 0 The dither mode is disabled. 1 The dither mode is enabled if tuning is enabled (DFLLULPCTRL.TUNE = 1). Bit 4 – SAFE Tuner Safe Mode This bit is not synchronized. Value Description 0 The clock output is not masked while binary search tuning is ongoing. 1 The clock output is masked while binary search tuning is ongoing (DFLLULPCTRL.BINSE = 1). Bit 3 – BINSE Binary Search Enable This bit is not synchronized. Value Description 0 Binary search tuning is disabled. Maximum number of reference clock cycles to acquire lock is 256. 1 Binary search tuning is enabled. Maximum number of reference clock cycles to acquire lock is 8. Bit 1 – ENABLE Enable This bit is not enable-protected. Value Description 0 The DFLLULP is disabled. 1 The DFLLULP is enabled. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 306 23.8.10 DFLLULP Dither Control Name:  DFLLULPDITHER Offset:  0x1E Reset:  0x00 Property:  PAC Write-Protection, Enable-Protected Bit 7 6 5 4 3 2 1 0 PER[2:0] STEP[2:0] Access R R/W R/W R/W R R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 6:4 – PER[2:0] Dither Period These bits define the number of reference clock periods over which dithering is applied. Value Name Description 0x0 PER1 Dither over 1 reference clock period 0x1 PER2 Dither over 2 reference clock periods 0x2 PER4 Dither over 4 reference clock periods 0x3 PER8 Dither over 8 reference clock periods 0x4 PER16 Dither over 16 reference clock periods 0x5 PER32 Dither over 32 reference clock periods 0x6 - 0x7 - Reserved Bits 2:0 – STEP[2:0] Dither Step This field defines the dithering step size. Value Name Description 0x0 STEP1 Dither step = 1 0x1 STEP2 Dither step = 2 0x2 STEP4 Dither step = 4 0x3 STEP8 Dither step = 8 0x4 - 0x7 - Reserved SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 307 23.8.11 DFLLULP Read Request Name:  DFLLULPRREQ Offset:  0x1F Reset:  0x00 Property:  - Bit 7 6 5 4 3 2 1 0 RREQ Access R/W R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 7 – RREQ Read Request Writing a zero to this bit has no effect. Writing a one to this bit requests synchronization of the DFLLULPDLY register with the current oscillator delay value and sets the Delay Busy bit in the Synchronization Busy register (DFLLULPSYNCBUSY.DELAY). This bit is cleared automatically when synchronization is complete. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 308 23.8.12 DFLLULP Delay Value Name:  DFLLULPDLY Offset:  0x20 Reset:  0x00000080 Property:  PAC Write-Protection, Write-Synchronized Bit 31 30 29 28 27 26 25 24 Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DELAY[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 1 0 0 0 0 0 0 0 Bits 7:0 – DELAY[7:0] Delay Value Writing a value to this field sets the oscillator delay. A small value will produce a fast clock and a large value will produce a slow clock. If the tuner is enabled, writing to this field will cause the tuner to start tuning from the written value. Reading this value will return the last written delay or the oscillator delay when a synchronization was requested from the DFLLULPRREQ register. Writing a value to this register while a write synchronization or a read request synchronization is on-going will have no effect and produce a PAC error. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 309 23.8.13 DFLLULP Target Ratio Name:  DFLLULPRATIO Offset:  0x24 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 RATIO[10:8] Access R R R R R R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 RATIO[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 1 0 0 0 0 0 0 0 Bits 10:0 – RATIO[10:0] Target Tuner Ratio Writing a value to this field sets the target ratio between the DFLLULP output clock and the reference clock. The DFLLULPDLY.DELAY value will be updated in such a way that the target ratio and the actual ratio are as close as possible. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 310 23.8.14 DFLLULP Synchronization Busy Name:  DFLLULPSYNCBUSY Offset:  0x28 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DELAY ENABLE Access R R R R R R R Reset 0 0 0 0 0 0 0 Bit 3 – DELAY Delay Register Synchronization Busy This bit is cleared when the synchronization of DFLLULPDLY is complete. This bit is set when the synchronization of DFLLULPDLY is started. Writing this bit has no effect. Bit 1 – ENABLE Enable Bit Synchronization Busy This bit is cleared when the synchronization of DFLLULPCTRL.ENABLE is complete. This bit is set when the synchronization of DFLLULPCTRL.ENABLE is started. Writing this bit has no effect. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 311 23.8.15 DPLL Control A Name:  DPLLCTRLA Offset:  0x2C Reset:  0x80 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 ONDEMAND RUNSTDBY ENABLE Access R/W R/W R/W Reset 1 0 0 Bit 7 – ONDEMAND On Demand Clock Activation The On Demand operation mode allows the DPLL to be enabled or disabled depending on peripheral clock requests. If the ONDEMAND bit has been previously written to '1', the DPLL will only be running when requested by a peripheral. If there is no peripheral requesting the DPLL’s clock source, the DPLL will be in a disabled state. If On Demand is disabled the DPLL will always be running when enabled. In standby sleep mode, the On Demand operation is still active. Value Description 0 The DPLL is always on, if enabled. 1 The DPLL is enabled when a peripheral is requesting the DPLL to be used as a clock source. The DPLL is disabled if no peripheral is requesting the clock source. Bit 6 – RUNSTDBY Run in Standby This bit controls how the DPLL behaves during standby sleep mode: Value Description 0 The DPLL is disabled in standby sleep mode if no peripheral requests the clock. 1 The DPLL is not stopped in standby sleep mode. If ONDEMAND=1, the DPLL will be running when a peripheral is requesting the clock. If ONDEMAND=0, the clock source will always be running in standby sleep mode. Bit 1 – ENABLE DPLL Enable, Write-Synchronized (ENABLE) The software operation of enabling or disabling the DPLL takes a few clock cycles, so the DPLLSYNCBUSY.ENABLE status bit indicates when the DPLL is successfully enabled or disabled. Value Description 0 The DPLL is disabled. 1 The DPLL is enabled. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 312 23.8.16 DPLL Ratio Control Name:  DPLLRATIO Offset:  0x30 Reset:  0x00000000 Property:  PAC Write-Protection, Write-Synchronized Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 LDRFRAC[3:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 LDR[11:8] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 6 5 4 3 2 1 0 LDR[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 19:16 – LDRFRAC[3:0] Loop Divider Ratio Fractional Part Writing these bits selects the fractional part of the frequency multiplier. Due to synchronization there is a delay between writing these bits and the effect on the DPLL output clock. The value written will read back immediately and the DPLLRATIO bit in the DPLL Synchronization Busy register (DPLLSYNCBUSY.DPLLRATIO) will be set. DPLLSYNCBUSY.DPLLRATIO will be cleared when the operation is completed. Bits 11:0 – LDR[11:0] Loop Divider Ratio Writing these bits selects the integer part of the frequency multiplier. The value written to these bits will read back immediately, and the DPLLRATIO bit in the DPLL Synchronization busy register (DPLLSYNCBUSY.DPLLRATIO), will be set. DPLLSYNCBUSY.DPLLRATIO will be cleared when the operation is completed. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 313 23.8.17 DPLL Control B Name:  DPLLCTRLB Offset:  0x34 Reset:  0x00000000 Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 DIV[10:8] Access R/W R/W R/W Reset 0 0 0 Bit 23 22 21 20 19 18 17 16 DIV[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 LBYPASS LTIME[2:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 6 5 4 3 2 1 0 REFCLK[1:0] WUF LPEN FILTER[1:0] Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bits 26:16 – DIV[10:0] Clock Divider These bits set the XOSC clock division factor and can be calculated with following formula: = ܸܫܦf ܥܱ݂ܵܺ 1ܸ + ܫܦ ݔ2 Bit 12 – LBYPASS Lock Bypass Value Description 0 DPLL Lock signal drives the DPLL controller internal logic. 1 DPLL Lock signal is always asserted. Bits 10:8 – LTIME[2:0] Lock Time These bits select the lock time-out value: Note:  GCLK_DPLL_32K is responsible for counting the user defined lock time (LTIME different from 0x0), hence must be enabled. Value Name Description 0x0 Default No time-out. Automatic lock. 0x1 Reserved 0x2 Reserved 0x3 Reserved SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 314 Value Name Description 0x4 8MS Time-out if no lock within 8ms 0x5 9MS Time-out if no lock within 9ms 0x6 10MS Time-out if no lock within 10ms 0x7 11MS Time-out if no lock within 11ms Bits 5:4 – REFCLK[1:0] Reference Clock Selection Write these bits to select the DPLL clock reference: Value Name Description 0x0 XOSC32K XOSC32K clock reference 0x1 XOSC XOSC clock reference 0x2 GCLK GCLK_DPLL clock reference 0x3 Reserved - Bit 3 – WUF Wake Up Fast Value Description 0 DPLL clock is output after startup and lock time. 1 DPLL clock is output after startup time. Bit 2 – LPEN Low-Power Enable Value Description 0 The low-power mode is disabled. Time to Digital Converter is enabled. 1 The low-power mode is enabled. Time to Digital Converter is disabled. This will improve power consumption but increase the output jitter. Bits 1:0 – FILTER[1:0] Proportional Integral Filter Selection These bits select the DPLL filter type: Value Name Description 0x0 DEFAULT Default filter mode 0x1 LBFILT Low bandwidth filter 0x2 HBFILT High bandwidth filter 0x3 HDFILT High damping filter SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 315 23.8.18 DPLL Prescaler Name:  DPLLPRESC Offset:  0x38 Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized Bit 7 6 5 4 3 2 1 0 PRESC[1:0] Access R/W R/W Reset 0 0 Bits 1:0 – PRESC[1:0] Output Clock Prescaler These bits define the output clock prescaler setting. Value Name Description 0x0 DIV1 DPLL output is divided by 1 0x1 DIV2 DPLL output is divided by 2 0x2 DIV4 DPLL output is divided by 4 0x3 Reserved SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 316 23.8.19 DPLL Synchronization Busy Name:  DPLLSYNCBUSY Offset:  0x3C Reset:  0x00 Property:  – Bit 7 6 5 4 3 2 1 0 DPLLPRESC DPLLRATIO ENABLE Access R R R Reset 0 0 0 Bit 3 – DPLLPRESC DPLL Prescaler Synchronization Status Value Description 0 The DPLLRESC register has been synchronized. 1 The DPLLRESC register value has changed and its synchronization is in progress. Bit 2 – DPLLRATIO DPLL Loop Divider Ratio Synchronization Status Value Description 0 The DPLLRATIO register has been synchronized. 1 The DPLLRATIO register value has changed and its synchronization is in progress. Bit 1 – ENABLE DPLL Enable Synchronization Status Value Description 0 The DPLLCTRLA.ENABLE bit has been synchronized. 1 The DPLLCTRLA.ENABLE bit value has changed and its synchronization is in progress. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 317 23.8.20 DPLL Status Name:  DPLLSTATUS Offset:  0x40 Reset:  0x00 Property:  – Bit 7 6 5 4 3 2 1 0 CLKRDY LOCK Access R R Reset 0 0 Bit 1 – CLKRDY DPLL Clock Ready Value Description 0 The DPLL output clock is off. 1 The DPLL output clock in on. Bit 0 – LOCK DPLL Lock Value Description 0 The DPLL Lock signal is cleared, when the DPLL is disabled or when the DPLL is trying to reach the target frequency. 1 The DPLL Lock signal is asserted when the desired frequency is reached. SAM L10/L11 Family OSCCTRL – Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 318 24. OSC32KCTRL – 32KHz Oscillators Controller 24.1 Overview The 32KHz Oscillators Controller (OSC32KCTRL) provides a user interface to the 32.768kHz oscillators: XOSC32K and OSCULP32K. The OSC32KCTRL sub-peripherals can be enabled, disabled, calibrated, and monitored through interface registers. All sub-peripheral statuses are collected in the Status register (STATUS). They can additionally trigger interrupts upon status changes via the INTENSET, INTENCLR, and INTFLAG registers. 24.2 Features • 32.768 kHz Crystal Oscillator (XOSC32K) – Programmable start-up time – Crystal or external input clock on XIN32 I/O – Clock failure detection with safe clock switch – Clock failure event output • 32.768 kHz Ultra Low-Power Internal Oscillator (OSCULP32K) – Ultra low-power, always-on oscillator – Frequency fine tuning • Calibration value loaded from Flash factory calibration at reset • 1.024 kHz clock outputs available SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 319 24.3 Block Diagram Figure 24-1. OSC32KCTRL Block Diagram STATUS register INTERRUPTS GENERATOR Interrupts OSC32KCTRL 32K OSCILLATORS CONTROL XOUT32 XIN32 CLK_XOSC32K CLK_OSCULP32K CFD Event XOSC32K OSCULP32K CFD ULP32KSW 24.4 Signal Description Signal Description Type XIN32 Analog Input 32.768 kHz Crystal Oscillator or external clock input XOUT32 Analog Output 32.768 kHz Crystal Oscillator output The I/O lines are automatically selected when XOSC32K is enabled. Note:  The signal of the external crystal oscillator may affect the jitter of neighboring pads. 24.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 24.5.1 I/O Lines I/O lines are configured by OSC32KCTRL when XOSC32K is enabled, and need no user configuration. 24.5.2 Power Management The OSC32KCTRL will continue to operate in any sleep mode where a 32KHz oscillator is running as source clock. The OSC32KCTRL interrupts can be used to wake up the device from sleep modes. Related Links 22. PM – Power Manager SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 320 24.5.3 Clocks The OSC32KCTRL gathers controls for all 32KHz oscillators and provides clock sources to the Generic Clock Controller (GCLK), Real-Time Counter (RTC), and Watchdog Timer (WDT). The available clock sources are: XOSC32K and OSCULP32K. The OSC32KCTRL bus clock (CLK_OSC32KCTRL_APB) can be enabled and disabled in the Main Clock module (MCLK). Related Links 19.6.2.6 Peripheral Clock Masking 24.5.4 Interrupts The interrupt request lines are connected to the interrupt controller. Using the OSC32KCTRL interrupts requires the interrupt controller to be configured first. 24.5.5 Events The events of this peripheral are connected to the Event System. Related Links 33. EVSYS – Event System 24.5.6 Debug Operation When the CPU is halted in debug mode, OSC32KCTRL will continue normal operation. If OSC32KCTRL 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. 24.5.7 Register Access Protection All registers with write-access can be write-protected optionally by the Peripheral Access Controller (PAC), except for the following registers: • Interrupt Flag Status and Clear (INTFLAG) register Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. PAC write-protection does not apply to accesses through an external debugger. Related Links 15. PAC - Peripheral Access Controller 24.5.8 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 321 24.5.9 Analog Connections The external 32.768kHz crystal must be connected between the XIN32 and XOUT32 pins, along with any required load capacitors. For details on recommended oscillator characteristics and capacitor load, refer to the related links. 24.6 Functional Description 24.6.1 Principle of Operation XOSC32K and OSCULP32K are configured via OSC32KCTRL control registers. Through this interface, the sub-peripherals are enabled, disabled, or have their calibration values updated. The STATUS register gathers different status signals coming from the sub-peripherals of OSC32KCTRL. The status signals can be used to generate system interrupts, and in some cases wake up the system from standby mode, provided the corresponding interrupt is enabled. 24.6.2 32KHz External Crystal Oscillator (XOSC32K) Operation The XOSC32K can operate in two different modes: • External clock, with an external clock signal connected to XIN32 • Crystal oscillator, with an external 32.768kHz crystal connected between XIN32 and XOUT32 At reset, the XOSC32K is disabled, and the XIN32/XOUT32 pins can either be used as General Purpose I/O (GPIO) pins or by other peripherals in the system. When XOSC32K is enabled, the operating mode determines the GPIO usage. When in crystal oscillator mode, the XIN32 and XOUT32 pins are controlled by the OSC32KCTRL, and GPIO functions are overridden on both pins. When in external clock mode, the only XIN32 pin will be overridden and controlled by the OSC32KCTRL, while the XOUT32 pin can still be used as a GPIO pin. The XOSC32K is enabled by writing a '1' to the Enable bit in the 32KHz External Crystal Oscillator Control register (XOSC32K.ENABLE=1). The XOSC32K is disabled by writing a '0' to the Enable bit in the 32KHz External Crystal Oscillator Control register (XOSC32K.ENABLE=0). To enable the XOSC32K as a crystal oscillator, the XTALEN bit in the 32KHz External Crystal Oscillator Control register must be set (XOSC32K.XTALEN=1). If XOSC32K.XTALEN is '0', the external clock input will be enabled. The XOSC32K 32.768kHz output is enabled by setting the 32KHz Output Enable bit in the 32KHz External Crystal Oscillator Control register (XOSC32K.EN32K=1). The XOSC32K also has a 1.024kHz clock output, which can only be used by the RTC. This clock output is enabled by setting the 1KHz Output Enable bit in the 32KHz External Crystal Oscillator Control register (XOSC32K.EN1K=1). It is also possible to lock the XOSC32K configuration by setting the Write Lock bit in the 32KHz External Crystal Oscillator Control register (XOSC32K.WRTLOCK=1). If set, the XOSC32K configuration is locked until a Power-On Reset (POR) is detected. The XOSC32K will behave differently in different sleep modes based on the settings of XOSC32K.RUNSTDBY, XOSC32K.ONDEMAND, and XOSC32K.ENABLE. If XOSC32KCTRL.ENABLE=0, the XOSC32K will be always stopped. For XOS32KCTRL.ENABLE=1, this table is valid: SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 322 Table 24-1. XOSC32K Sleep Behavior CPU Mode XOSC32K. RUNSTDBY XOSC32K. ONDEMAND Sleep Behavior of XOSC32K and CFD Active or Idle - 0 Always run Active or Idle - 1 Run if requested by peripheral Standby 1 0 Always run Standby 1 1 Run if requested by peripheral Standby 0 - Run if requested by peripheral As a crystal oscillator usually requires a very long start-up time, the 32KHz External Crystal Oscillator will keep running across resets when XOSC32K.ONDEMAND=0, except for power-on reset (POR). After a reset or when waking up from a sleep mode where the XOSC32K was disabled, the XOSC32K will need a certain amount of time to stabilize on the correct frequency. This start-up time can be configured by changing the Oscillator Start-Up Time bit group (XOSC32K.STARTUP) in the 32KHz External Crystal Oscillator Control register. During the start-up time, the oscillator output is masked to ensure that no unstable clock propagates to the digital logic. Once the external clock or crystal oscillator is stable and ready to be used as a clock source, the XOSC32K Ready bit in the Status register is set (STATUS.XOSC32KRDY=1). The transition of STATUS.XOSC32KRDY from '0' to '1' generates an interrupt if the XOSC32K Ready bit in the Interrupt Enable Set register is set (INTENSET.XOSC32KRDY=1). The XOSC32K can be used as a source for Generic Clock Generators (GCLK) or for the Real-Time Counter (RTC). Before enabling the GCLK or the RTC module, the corresponding oscillator output must be enabled (XOSC32K.EN32K or XOSC32K.EN1K) in order to ensure proper operation. In the same way, the GCLK or RTC modules must be disabled before the clock selection is changed. For details on RTC clock configuration, refer also to 24.6.6 Real-Time Counter Clock Selection. Related Links 18. GCLK - Generic Clock Controller 27. RTC – Real-Time Counter 24.6.3 Clock Failure Detection Operation The Clock Failure Detector (CFD) allows the user to monitor the external clock or crystal oscillator signal provided by the external oscillator (XOSC32K). The CFD detects failing operation of the XOSC32K clock with reduced latency, and allows to switch to a safe clock source in case of clock failure. The user can also switch from the safe clock back to XOSC32K in case of recovery. The safe clock is derived from the OSCULP32K oscillator with a configurable prescaler. This allows to configure the safe clock in order to fulfill the operative conditions of the microcontroller. In sleep modes, CFD operation is automatically disabled when the external oscillator is not requested to run by a peripheral. See the Sleep Behavior table above when this is the case. The user interface registers allow to enable, disable, and configure the CFD. The Status register provides status flags on failure and clock switch conditions. The CFD can optionally trigger an interrupt or an event when a failure is detected. SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 323 Clock Failure Detection The CFD is reset only at power-on (POR). The CFD does not monitor the XOSC32K clock when the oscillator is disabled (XOSC32K.ENABLE=0). Before starting CFD operation, the user must start and enable the safe clock source (OSCULP32K oscillator). CFD operation is started by writing a '1' to the CFD Enable bit in the External Oscillator Control register (CFDCTRL.CFDEN). After starting or restarting the XOSC32K, the CFD does not detect failure until the start-up time has elapsed. The start-up time is configured by the Oscillator Start-Up Time in the External Multipurpose Crystal Oscillator Control register (XOSC32K.STARTUP). Once the XOSC32K Start-Up Time is elapsed, the XOSC32K clock is constantly monitored. During a period of 4 safe clocks (monitor period), the CFD watches for a clock activity from the XOSC32K. There must be at least one rising and one falling XOSC32K clock edge during 4 safe clock periods to meet non-failure conditions. If no or insufficient activity is detected, the failure status is asserted: The Clock Failure Detector status bit in the Status register (STATUS.CLKFAIL) and the Clock Failure Detector interrupt flag bit in the Interrupt Flag register (INTFLAG.CLKFAIL) are set. If the CLKFAIL bit in the Interrupt Enable Set register (INTENSET.CLKFAIL) is set, an interrupt is generated as well. If the Event Output enable bit in the Event Control register (EVCTRL.CFDEO) is set, an output event is generated, too. After a clock failure was issued the monitoring of the XOSC32K clock is continued, and the Clock Failure Detector status bit in the Status register (STATUS.CLKFAIL) reflects the current XOSC32K activity. Clock Switch When a clock failure is detected, the XOSC32K clock is replaced by the safe clock in order to maintain an active clock during the XOSC32K clock failure. The safe clock source is the OSCULP32K oscillator clock. Both 32KHz and 1KHz outputs of the XOSC32K are replaced by the respective OSCULP32K 32KHz and 1KHz outputs. The safe clock source can be scaled down by a configurable prescaler to ensure that the safe clock frequency does not exceed the operating conditions selected by the application. When the XOSC32K clock is switched to the safe clock, the Clock Switch bit in the Status register (STATUS.CLKSW) is set. When the CFD has switched to the safe clock, the XOSC32K is not disabled. If desired, the application must take the necessary actions to disable the oscillator. The application must also take the necessary actions to configure the system clocks to continue normal operations. In the case the application can recover the XOSC32K, the application can switch back to the XOSC32K clock by writing a '1' to Switch Back Enable bit in the Clock Failure Control register (CFDCTRL.SWBACK). Once the XOSC32K clock is switched back, the Switch Back bit (CFDCTRL.SWBACK) is cleared by hardware. Prescaler The CFD has an internal configurable prescaler to generate the safe clock from the OSCULP32K oscillator. The prescaler size allows to scale down the OSCULP32K oscillator so the safe clock frequency is not higher than the XOSC32K clock frequency monitored by the CFD. The maximum division factor is 2. The prescaler is applied on both outputs (32KHz and 1KHz) of the safe clock. Example 24-1.  For an external crystal oscillator at 32KHz and the OSCULP32K frequency is 32KHz, the XOSC32K.CFDPRESC should be set to 0 for a safe clock of equal frequency. SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 324 Event If the Event Output Enable bit in the Event Control register (EVCTRL.CFDEO) is set, the CFD clock failure will be output on the Event Output. When the CFD is switched to the safe clock, the CFD clock failure will not be output on the Event Output. Sleep Mode The CFD is halted depending on configuration of the XOSC32K and the peripheral clock request. For further details, refer to the Sleep Behavior table above. The CFD interrupt can be used to wake up the device from sleep modes. 24.6.4 32 kHz Ultra Low-Power Internal Oscillator (OSCULP32K) Operation The OSCULP32K provides a tunable, low-speed, and ultra low-power clock source. The OSCULP32K is factory-calibrated under typical voltage and temperature conditions. The OSCULP32K is enabled by default after a Power-on Reset (POR), and will always run except during POR. The frequency of the OSCULP32K Oscillator is controlled by the value in the Calibration bits in the 32 kHz Ultra Low-Power Internal Oscillator Control register (OSCULP32K.CALIB). This data is used to compensate for process variations. OSCULP32K.CALIB is automatically loaded from Flash Factory Calibration during start-up. The calibration value can be overridden by the user by writing to OSCULP32K.CALIB. Users can lock the OSCULP32K configuration by setting the Write Lock bit in the 32 kHz Ultra Low-Power Internal Oscillator Control register (OSCULP32K.WRTLOCK = 1). If set, the OSCULP32K configuration is locked until POR is detected. The OSCULP32K can be used as a source for Generic Clock Generators (GCLK) or for the Real-Time Counter (RTC). To ensure proper operation, the GCLK or RTC modules must be disabled before the clock selection is changed. OSCULP32K Clock Switch The Clock switch operation requires the XOSC32K to be enabled (XOSC32K.ENABLE=1 and STATUS.XOSC32KRDY = 1). When the OSCULP32K Clock Switch Enable bit (OSCULP32K.ULP32KSW) is set, the CLK_OSCULP32K clock is switched to the XOSC32K Clock Oscillator. When the clock switch process is complete, the OSCULP32K Clock Switch bit in Status register (STATUS.ULP32KSW) is set. The OSCULP32K oscillator is shut off, and the XOSC32K oscillator becomes always running. The CFD feature is also disabled by hardware. When set, the OSCULP32K.ULP32KSW can be reset only by POR operation. Related Links 27. RTC – Real-Time Counter 24.6.6 Real-Time Counter Clock Selection 18. GCLK - Generic Clock Controller 24.6.5 Watchdog Timer Clock Selection The Watchdog Timer (WDT) uses the internal 1.024kHz OSCULP32K output clock. This clock is running all the time and internally enabled when requested by the WDT module. Related Links 26. WDT – Watchdog Timer SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 325 24.6.6 Real-Time Counter Clock Selection Before enabling the RTC module, the RTC clock must be selected first. All oscillator outputs are valid as RTC clock. The selection is done in the RTC Control register (RTCCTRL). To ensure a proper operation, it is highly recommended to disable the RTC module first, before the RTC clock source selection is changed. Related Links 27. RTC – Real-Time Counter 24.6.7 Interrupts The OSC32KCTRL has the following interrupt sources: • XOSC32KRDY - 32KHz Crystal Oscillator Ready: A 0-to-1 transition on the STATUS.XOSC32KRDY bit is detected • CLKFAIL - Clock Failure Detector: A 0-to-1 transition on the STATUS.CLKFAIL bit is detected All these interrupts are synchronous wake-up source. Each interrupt source has an interrupt flag associated with it. The interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG) is set when the interrupt condition occurs. Each interrupt can be enabled individually by setting the corresponding bit in the Interrupt Enable Set register (INTENSET), and disabled by setting the corresponding bit in the Interrupt Enable Clear register (INTENCLR). An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until the interrupt flag is cleared, the interrupt is disabled or the OSC32KCTRL is reset. See the INTFLAG register for details on how to clear interrupt flags. The OSC32KCTRL has one common interrupt request line for all the interrupt sources. The user must read the INTFLAG register to determine which interrupt condition is present. Refer to the INTFLAG register for details. Note:  Interrupts must be globally enabled for interrupt requests to be generated. Related Links 22. PM – Power Manager 24.6.8 Events The CFD can generate the following output event: • Clock Failure Detector (CLKFAIL): Generated when the Clock Failure Detector status bit is set in the Status register (STATUS.CLKFAIL). The CFD event is not generated when the Clock Switch bit (STATUS.SWBACK) in the Status register is set. Writing a '1' to an Event Output bit in the Event Control register (EVCTRL.CFDEO) enables the CFD output event. Writing a '0' to this bit disables the CFD output event. Refer to the Event System chapter for details on configuring the event system. SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 326 24.7 Register Summary Offset Name Bit Pos. 0x00 INTENCLR 7:0 CLKFAIL XOSC32KRD Y 15:8 23:16 31:24 0x04 INTENSET 7:0 CLKFAIL XOSC32KRD Y 15:8 23:16 31:24 0x08 INTFLAG 7:0 CLKFAIL XOSC32KRD Y 15:8 23:16 31:24 0x0C STATUS 7:0 ULP32KSW CLKSW CLKFAIL XOSC32KRD Y 15:8 23:16 31:24 0x10 RTCCTRL 7:0 RTCSEL[2:0] 0x11 ... 0x13 Reserved 0x14 XOSC32K 7:0 ONDEMAND RUNSTDBY EN1K EN32K XTALEN ENABLE 15:8 WRTLOCK STARTUP[2:0] 0x16 CFDCTRL 7:0 CFDPRESC SWBACK CFDEN 0x17 EVCTRL 7:0 CFDEO 0x18 ... 0x1B Reserved 0x1C OSCULP32K 7:0 ULP32KSW 15:8 WRTLOCK CALIB[4:0] 23:16 31:24 24.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16-, and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register and the 8-bit halves of a 16-bit register can be accessed directly. All registers with write-access can be write-protected optionally by the peripheral access controller (PAC). Optional Write-Protection by the Peripheral Access Controller (PAC) is denoted by the "PAC Write- SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 327 Protection" property in the register description. Write-protection does not apply to accesses through an external debugger. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. Related Links 15. PAC - Peripheral Access Controller SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 328 24.8.1 Interrupt Enable Clear Name:  INTENCLR Offset:  0x00 Reset:  0x00000000 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 CLKFAIL XOSC32KRDY Access R/W R/W Reset 0 0 Bit 2 – CLKFAIL XOSC32K Clock Failure Detection Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the XOSC32K Clock Failure Interrupt Enable bit, which disables the XOSC32K Clock Failure interrupt. Value Description 0 The XOSC32K Clock Failure Detection is disabled. 1 The XOSC32K Clock Failure Detection is enabled. An interrupt request will be generated when the XOSC32K Clock Failure Detection interrupt flag is set. Bit 0 – XOSC32KRDY XOSC32K Ready Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the XOSC32K Ready Interrupt Enable bit, which disables the XOSC32K Ready interrupt. Value Description 0 The XOSC32K Ready interrupt is disabled. 1 The XOSC32K Ready interrupt is enabled. SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 329 24.8.2 Interrupt Enable Set Name:  INTENSET Offset:  0x04 Reset:  0x00000000 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear register (INTENCLR). Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 CLKFAIL XOSC32KRDY Access R/W R/W Reset 0 0 Bit 2 – CLKFAIL XOSC32K Clock Failure Detection Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the XOSC32K Clock Failure Interrupt Enable bit, which enables the XOSC32K Clock Failure interrupt. Value Description 0 The XOSC32K Clock Failure Detection is disabled. 1 The XOSC32K Clock Failure Detection is enabled. An interrupt request will be generated when the XOSC32K Clock Failure Detection interrupt flag is set. Bit 0 – XOSC32KRDY XOSC32K Ready Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the XOSC32K Ready Interrupt Enable bit, which enables the XOSC32K Ready interrupt. Value Description 0 The XOSC32K Ready interrupt is disabled. 1 The XOSC32K Ready interrupt is enabled. SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 330 24.8.3 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x08 Reset:  0x00000000 Property:  – Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 CLKFAIL XOSC32KRDY Access R/W R/W Reset 0 0 Bit 2 – CLKFAIL XOSC32K Clock Failure Detection This flag is cleared by writing a '1' to it. This flag is set on a zero-to-one transition of the XOSC32K Clock Failure Detection bit in the Status register (STATUS.CLKFAIL) and will generate an interrupt request if INTENSET.CLKFAIL is '1'. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the XOSC32K Clock Failure Detection flag. Bit 0 – XOSC32KRDY XOSC32K Ready This flag is cleared by writing a '1' to it. This flag is set by a zero-to-one transition of the XOSC32K Ready bit in the Status register (STATUS.XOSC32KRDY), and will generate an interrupt request if INTENSET.XOSC32KRDY=1. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the XOSC32K Ready interrupt flag. SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 331 24.8.4 Status Name:  STATUS Offset:  0x0C Reset:  0x00000000 Property:  – Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 ULP32KSW CLKSW CLKFAIL XOSC32KRDY Access R R R R Reset 0 0 0 0 Bit 4 – ULP32KSW OSCULP32K Clock Switch Value Description 0 OSCULP32K is not switched and provided by the ULP32K oscillator. 1 OSCULP32K is switched to be provided by the XOSC32K clock. Bit 3 – CLKSW XOSC32K Clock Switch Value Description 0 XOSC32K is not switched and provided the crystal oscillator. 1 XOSC32K is switched to be provided by the safe clock. Bit 2 – CLKFAIL XOSC32K Clock Failure Detector Value Description 0 XOSC32K is passing failure detection. 1 XOSC32K is not passing failure detection. Bit 0 – XOSC32KRDY XOSC32K Ready Value Description 0 XOSC32K is not ready. 1 XOSC32K is stable and ready to be used as a clock source. SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 332 24.8.5 RTC Clock Selection Control Name:  RTCCTRL Offset:  0x10 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 RTCSEL[2:0] Access R/W R/W R/W Reset 0 0 0 Bits 2:0 – RTCSEL[2:0] RTC Clock Selection These bits select the source for the RTC. Value Name Description 0x0 ULP1K 1.024kHz from 32KHz internal ULP oscillator 0x1 ULP32K 32.768kHz from 32KHz internal ULP oscillator 0x2, 0x3 Reserved - 0x4 XOSC1K 1.024kHz from 32KHz external oscillator 0x5 XOSC32K 32.768kHz from 32KHz external crystal oscillator 0x6 Reserved 0x7 Reserved SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 333 24.8.6 32KHz External Crystal Oscillator (XOSC32K) Control Name:  XOSC32K Offset:  0x14 Reset:  0x00000080 Property:  PAC Write-Protection Bit 15 14 13 12 11 10 9 8 WRTLOCK STARTUP[2:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 6 5 4 3 2 1 0 ONDEMAND RUNSTDBY EN1K EN32K XTALEN ENABLE Access R/W R/W R/W R/W R/W R/W Reset 1 0 0 0 0 0 Bit 12 – WRTLOCK Write Lock This bit locks the XOSC32K register for future writes, effectively freezing the XOSC32K configuration. Value Description 0 The XOSC32K configuration is not locked. 1 The XOSC32K configuration is locked. Bits 10:8 – STARTUP[2:0] Oscillator Start-Up Time These bits select the start-up time for the oscillator. The OSCULP32K oscillator is used to clock the start-up counter. Table 24-2. Start-Up Time for 32KHz External Crystal Oscillator STARTUP[2:0] Number of OSCULP32K Clock Cycles Number of XOSC32K Clock Cycles Approximate Equivalent Time [s] 0x0 2048 3 0.06 0x1 4096 3 0.13 0x2 16384 3 0.5 0x3 32768 3 1 0x4 65536 3 2 0x5 131072 3 4 0x6 262144 3 8 0x7 - - Reserved Note:  1. Actual Start-Up time is 1 OSCULP32K cycle + 3 XOSC32K cycles. 2. The given time assumes an XTAL frequency of 32.768kHz. SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 334 Bit 7 – ONDEMAND On Demand Control This bit controls how the XOSC32K behaves when a peripheral clock request is detected. For details, refer to XOSC32K Sleep Behavior. Bit 6 – RUNSTDBY Run in Standby This bit controls how the XOSC32K behaves during standby sleep mode. For details, refer to XOSC32K Sleep Behavior. Bit 4 – EN1K 1KHz Output Enable Value Description 0 The 1KHz output is disabled. 1 The 1KHz output is enabled. Bit 3 – EN32K 32KHz Output Enable Value Description 0 The 32KHz output is disabled. 1 The 32KHz output is enabled. Bit 2 – XTALEN Crystal Oscillator Enable This bit controls the connections between the I/O pads and the external clock or crystal oscillator. Value Description 0 External clock connected on XIN32. XOUT32 can be used as general-purpose I/O. 1 Crystal connected to XIN32/XOUT32. Bit 1 – ENABLE Oscillator Enable Value Description 0 The oscillator is disabled. 1 The oscillator is enabled. SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 335 24.8.7 Clock Failure Detector Control Name:  CFDCTRL Offset:  0x16 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 CFDPRESC SWBACK CFDEN Access R/W R/W R/W Reset 0 0 0 Bit 2 – CFDPRESC Clock Failure Detector Prescaler This bit selects the prescaler for the Clock Failure Detector. Value Description 0 The CFD safe clock frequency is the OSCULP32K frequency 1 The CFD safe clock frequency is the OSCULP32K frequency divided by 2 Bit 1 – SWBACK Clock Switch Back This bit clontrols the XOSC32K output switch back to the external clock or crystal scillator in case of clock recovery. Value Description 0 The clock switch is disabled. 1 The clock switch is enabled. This bit is reset when the XOSC32K output is switched back to the external clock or crystal oscillator. Bit 0 – CFDEN Clock Failure Detector Enable This bit selects the Clock Failure Detector state. Value Description 0 The CFD is disabled. 1 The CFD is enabled. SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 336 24.8.8 Event Control Name:  EVCTRL Offset:  0x17 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 CFDEO Access R/W Reset 0 Bit 0 – CFDEO Clock Failure Detector Event Out Enable This bit controls whether the Clock Failure Detector event output is enabled and an event will be generated when the CFD detects a clock failure. Value Description 0 Clock Failure Detector Event output is disabled, no event will be generated. 1 Clock Failure Detector Event output is enabled, an event will be generated. SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 337 24.8.9 32KHz Ultra Low-Power Internal Oscillator (OSCULP32K) Control Name:  OSCULP32K Offset:  0x1C Reset:  0x0000XX06 Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 WRTLOCK CALIB[4:0] Access R/W R/W R/W R/W R/W R/W Reset 0 x x x x x Bit 7 6 5 4 3 2 1 0 ULP32KSW Access R/W Reset 0 Bit 15 – WRTLOCK Write Lock This bit locks the OSCULP32K register for future writes to fix the OSCULP32K configuration. Value Description 0 The OSCULP32K configuration is not locked. 1 The OSCULP32K configuration is locked. Bits 12:8 – CALIB[4:0] Oscillator Calibration These bits control the oscillator calibration. These bits are loaded from Flash Calibration at startup. Bit 5 – ULP32KSW OSCULP32K Clock Switch Enable Value Description 0 OSCULP32K is not switched and provided by the ULP32K oscillator. 1 OSCULP32K is switched to be provided by the XOSC32K oscillator. SAM L10/L11 Family OSC32KCTRL – 32KHz Oscillators Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 338 25. SUPC – Supply Controller 25.1 Overview The Supply Controller (SUPC) manages the voltage reference and power supply of the device. The SUPC controls the voltage regulators for the core (VDDCORE) domain. It sets the voltage regulators according to the sleep modes, or the user configuration. In active mode, the voltage regulators can be selected on the fly between LDO (low-dropout) type regulator or Buck converter. The SUPC embeds two Brown-Out Detectors. BOD33 monitors the voltage applied to the device (VDD) and BOD12 monitors the internal voltage to the core (VDDCORE). The BOD can monitor the supply voltage continuously (continuous mode) or periodically (sampling mode). The SUPC generates also a selectable reference voltage and a voltage dependent on the temperature which can be used by analog modules like the ADC or DAC. 25.2 Features • Voltage Regulator System – Main voltage regulator: LDO or Buck Converter in active mode (MAINVREG) – Low-Power voltage regulator in Standby mode (LPVREG) – Adjustable VDDCORE to the Sleep mode or the performance level – Controlled VDDCORE voltage slope when changing VDDCORE • Voltage Reference System – Reference voltage for ADC and DAC – Temperature sensor • 3.3V Brown-Out Detector (BOD33) – Programmable threshold – Threshold value loaded from NVM User Row at startup – Triggers resets or interrupts or event. Action loaded from NVM User Row – Operating modes: • Continuous mode • Sampled mode for low power applications with programmable sample frequency – Hysteresis value from Flash User Calibration • 1.2V Brown-Out Detector (BOD12) – Internal non-configurable Brown-Out Detector SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 339 25.3 Block Diagram Figure 25-1. SUPC Block Diagram LDO Buck Converter LP VREG VDDCORE BOD12 VDD BOD33 BOD33 BOD12 VREG Core domain PM performance level sleep mode VREF VREF temperature sensor reference voltage Main VREG 25.4 Signal Description Not appclicable. 25.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 25.5.1 I/O Lines Not applicable. 25.5.2 Power Management The SUPC can operate in all sleep modes. Related Links 22. PM – Power Manager 25.5.3 Clocks The SUPC bus clock (CLK_SUPC_APB) can be enabled and disabled in the Main Clock module. A 32KHz clock, asynchronous to the user interface clock (CLK_SUPC_APB), is required to run BOD33 and BOD12 in sampled mode. Due to this asynchronicity, writing to certain registers will require synchronization between the clock domains. Refer to 25.6.6 Synchronization for further details. Related Links 24. OSC32KCTRL – 32KHz Oscillators Controller 19.6.2.6 Peripheral Clock Masking 25.5.4 DMA Not applicable. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 340 25.5.5 Interrupts The interrupt request lines are connected to the interrupt controller. Using the SUPC interrupts requires the interrupt controller to be configured first. 25.5.6 Events The events are connected to the Event System. Refer to the Event System section for details on how to configure the Event System. 25.5.7 Debug Operation When the CPU is halted in debug mode, the SUPC continues normal operation. If the SUPC 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. If debugger cold-plugging is detected by the system, BOD33 and BOD12 resets will be masked. The BOD resets keep running under hot-plugging. This allows to correct a BOD33 user level too high for the available supply. 25.5.8 Register Access Protection Registers with write-access can be write-protected optionally by the peripheral access controller (PAC). Note:  Not all registers with write-access can be write-protected. PAC Write-Protection is not available for the following registers: • Interrupt Flag Status and Clear register (INTFLAG) Optional PAC Write-Protection is denoted by the "PAC Write-Protection" property in each individual register description. Related Links 15. PAC - Peripheral Access Controller 25.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 25.5.10 Analog Connections Not applicable. 25.6 Functional Description 25.6.1 Voltage Regulator System Operation 25.6.1.1 Enabling, Disabling, and Resetting The LDO main voltage regulator is enabled after any Reset. The main voltage regulator (MAINVREG) can be disabled by writing the Enable bit in the VREG register (VREG.ENABLE) to zero. The main SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 341 voltage regulator output supply level is automatically defined by the performance level or the sleep mode selected in the Power Manager module. Related Links 22. PM – Power Manager 25.6.1.2 Initialization After a Reset, the LDO voltage regulator supplying VDDCORE is enabled. 25.6.1.3 Selecting a Voltage Regulator In Active mode, the type of the main voltage regulator supplying VDDCORE can be switched on the fly. The two alternatives are a LDO regulator and a Buck converter. The main voltage regulator switching sequences are as follows: • The user changes the value of the Voltage Regulator Selection bit in the Voltage Regulator System Control register (VREG.SEL) • The start of the switching sequence is indicated by clearing the Voltage Regulator Ready bit in the STATUS register (STATUS.VREGRDY=0) • Once the switching sequence is completed, STATUS.VREGRDY will read '1' The Voltage Regulator Ready (VREGRDY) interrupt can also be used to detect a zero-to-one transition of the STATUS.VREGRDY bit. 25.6.1.4 Voltage Scaling Control The VDDCORE supply will change under certain circumstances: • When a new performance level (PL) is set • When the Standby Sleep mode is entered or left • When a sleepwalking task is requested in Standby Sleep mode To prevent high peak current on the main power supply and to have a smooth transition of VDDCORE, both the voltage scaling step size and the voltage scaling frequency can be controlled: VDDCORE is changed by the selected step size of the selected period until the target voltage is reached. The Voltage Scaling Voltage Step field is in the VREG register, VREG.VSVSTEP. The Voltage Scaling Period field is VREG.VSPER. The following waveform shows an example of changing performance level from PL0 to PL2. VDDCORE time V(PL0) V(PL2) VSVSTEP VSPER Setting VREG.VSVSTEP to the maximum value allows to transition in one voltage step. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 342 The STATUS.VCORERDY bit is set to '1' as soon as the VDDCORE voltage has reached the target voltage. During voltage transition, STATUS.VCORERDY will read '0'. The Voltage Ready interrupt (VCORERDY) can be used to detect a 0-to-1 transition of STATUS.VCORERDY, see also 25.6.4 Interrupts. When entering the Standby Sleep mode and when no sleepwalking task is requested, the VDDCORE Voltage scaling control is not used. 25.6.1.5 Sleep Mode Operation In Standby mode, the low-power voltage regulator (LPVREG) is used to supply VDDCORE. When the Run in Standby bit in the VREG register (VREG.RUNSTDBY) is written to '1', VDDCORE is supplied by the main voltage regulator. Depending on the Standby in PL0 bit in the Voltage Regulator register (VREG.STDBYPL0), the VDDCORE level is either set to the PL0 voltage level, or remains in the current performance level. Table 25-1. VDDCORE Level in Standby Mode VREG.RUNSTDBY VREG.STDBYPL0 VDDCORE Supply in Standby Mode 0 - LPVREG 1 0 MAINVREG in current performance level(1) 1 1 MAINVREG in PL0 Note:  1. When the device is in PL0 but VREG.STDBYPL0=0, the MAINVREG is operating in normal power mode. To minimize power consumption, operate MAINVREG in PL0 mode by selecting VREG.STDBYPL0=1. By writing the Low-Power mode Efficiency bit in the VREG register (VREG.LPEFF) to '1', the efficiency of the regulator in LPVREG can be improved when the application uses a limited VDD range (2.5 to 3.63V). It is also possible to use the BOD33 in order to monitor the VDD and change this LPEFF value on the fly according to VDD level. Related Links 22.6.3.3 Sleep Mode Controller 25.6.2 Voltage Reference System Operation The reference voltages are generated by a functional block DETREF inside of the SUPC. DETREF is providing a fixed-voltage source, BANDGAP=1.1V, and a variable voltage, INTREF. 25.6.2.1 Initialization The voltage reference output and the temperature sensor are disabled after any Reset. 25.6.2.2 Enabling, Disabling, and Resetting The voltage reference output is enabled/disabled by setting/clearing the Voltage Reference Output Enable bit in the Voltage Reference register (VREF.VREFOE). The temperature sensor is enabled/disabled by setting/clearing the Temperature Sensor Enable bit in the Voltage Reference register (VREF.TSEN). Note:  When VREF.ONDEMAND=0, it is not recommended to enable both voltage reference output and temperature sensor at the same time - only the voltage reference output will be present at both ADC inputs. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 343 25.6.2.3 Selecting a Voltage Reference The Voltage Reference Selection bit field in the VREF register (VREF.SEL) selects the voltage of INTREF to be applied to analog modules, e.g. the ADC. 25.6.2.4 Sleep Mode Operation The Voltage Reference output and the Temperature Sensor output behavior during sleep mode can be configured using the Run in Standby bit and the On Demand bit in the Voltage Reference register (VREF.RUNSTDBY, VREF.ONDEMAND), see the following table: Table 25-2. VREF Sleep Mode Operation VREF.ONDEMAND VREF.RUNSTDBY Voltage Reference Sleep behavior - - Disable 0 0 Always run in all sleep modes except standby sleep mode 0 1 Always run in all sleep modes including standby sleep mode 1 0 Only run if requested by the ADC, in all sleep modes except standby sleep mode 1 1 Only run if requested by the ADC, in all sleep modes including standby sleep mode 25.6.3 Brown-Out Detectors 25.6.3.1 Initialization Before a Brown-Out Detector (BOD33) is enabled, it must be configured, as outlined by the following: • Set the BOD threshold level (BOD33.LEVEL) • Set the configuration in Active, Standby (BOD33.ACTION, BOD33.STDBYCFG) • Set the prescaling value if the BOD will run in sampling mode (BOD33.PSEL) • Set the action and hysteresis (BOD33.ACTION and BOD33.HYST) The BOD33 register is Enable-Protected, meaning that they can only be written when the BOD is disabled (BOD33.ENABLE=0 and STATUS.B33SRDY=0). As long as the Enable bit is '1', any writes to Enable-Protected registers will be discarded, and an APB error will be generated. The Enable bits are not Enable-Protected. 25.6.3.2 Enabling, Disabling, and Resetting After power or user reset, the BOD33 and BOD12 register values are loaded from the NVM User Page. The BOD33 is enabled by writing a '1' to the Enable bit in the BOD control register (BOD33.ENABLE). The BOD33 is disabled by writing a '0' to the BOD33.ENABLE. 25.6.3.3 3.3V Brown-Out Detector (BOD33) The 3.3V Brown-Out Detector (BOD33) is able to monitor the VDD supply and compares the voltage with the brown-out threshold level set in the BOD33 Level field (BOD33.LEVEL) in the BOD33 register. When VDD crosses below the brown-out threshold level, the BOD33 can generate either an interrupt or a Reset, depending on the BOD33 Action bit field (BOD33.ACTION). The BOD33 detection status can be read from the BOD33 Detection bit in the Status register (STATUS.BOD33DET). At start-up or at Power-On Reset (POR), the BOD33 register values are loaded from the NVM User Row. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 344 25.6.3.4 1.2V Brown-Out Detector (BOD12) The BOD12 is calibrated in production and its calibration configuration is stored in the NVM User Row. This configuration must not be changed to assure the correct behavior of the BOD12. The BOD12 generates a reset when 1.2V crosses below the preset brown-out level. The BOD12 is always disabled in Standby Sleep mode. 25.6.3.5 Continuous Mode Continuous mode is the default mode for BOD33. The BOD33 is continuously monitoring the VDD supply voltage if it is enabled (BOD33.ENABLE=1) and if the BOD33 Configuration bit in the BOD33 register is cleared (BOD33.ACTCFG=0 for active mode, BOD33.STDBYCFG=0 for standby mode). 25.6.3.6 Sampling Mode The Sampling Mode is a low-power mode where the BOD33 is being repeatedly enabled on a sampling clock’s ticks. The BOD33 will monitor the supply voltage for a short period of time and then go to a lowpower disabled state until the next sampling clock tick. Sampling mode is enabled in Active mode for BOD33 by writing the ACTCFG bit (BOD33.ACTCFG=1). Sampling mode is enabled in Standby mode by writing to the STDBYCFG bit (BOD33.STBYCFG=1). The frequency of the clock ticks (Fclksampling) is controlled by the Prescaler Select bit groups in the BOD33 register (BOD33.PSEL). = ݈݃݊݅݌݉ܽݏ݈݇ܿܨ ݎ݈݁ܽܿݏ݁ݎ݌݈݇ܿܨ 2 PSEL + 1 The prescaler signal (Fclkprescaler) is a 1KHz clock, output by the 32KHz Ultra Low Power Oscillator OSCULP32K. As the sampling clock is different from the APB clock domain, synchronization among the clocks is necessary. See also 25.6.6 Synchronization. 25.6.3.7 Hysteresis A hysteresis on the trigger threshold of a BOD will reduce the sensitivity to ripples on the monitored voltage: instead of switching RESET at each crossing of VBOD, the thresholds for switching RESET on and off are separated (VBOD- and VBOD+, respectively). Figure 25-2. BOD Hysteresis Principle Hysteresis OFF: VCC RESET VBOD Hysteresis ON: VCC RESET VBODVBOD+ Enabling the BOD33 hysteresis by writing the Hysteresis bit in the BOD33 register (BOD33.HYST) to '1' will add hysteresis to the BOD33 threshold level. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 345 The hysteresis functionality can be used in both Continuous and Sampling Mode. 25.6.3.8 Sleep Mode Operation 25.6.3.8.1 Standby Mode The BOD33 can be used in standby mode if the BOD is enabled and the corresponding Run in Standby bit is written to '1' (BOD33.RUNSTDBY). The BOD33 can be configured to work in either Continuous or Sampling Mode by writing a '1' to the Configuration in Standby Sleep Mode bit (BOD33.STDBYCFG). 25.6.4 Interrupts The SUPC has the following interrupt sources, which are either synchronous or asynchronous wake-up sources: • VDDCORE Voltage Ready (VCORERDY), asynchronous • Voltage Regulator Ready (VREGRDY) asynchronous • BOD33 Ready (BOD33RDY), synchronous • BOD33 Detection (BOD33DET), asynchronous • BOD33 Synchronization Ready (B33SRDY), synchronous Each interrupt source has an interrupt flag associated with it. The interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG) is set when the interrupt condition occurs. Each interrupt can be individually enabled by writing a '1' to the corresponding bit in the Interrupt Enable Set register (INTENSET), and disabled by writing a '1' to the corresponding bit in the Interrupt Enable Clear register (INTENCLR). An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until either the interrupt flag is cleared, the interrupt is disabled, or the SUPC is reset. See the INTFLAG register for details on how to clear interrupt flags. The SUPC has one common interrupt request line for all the interrupt sources. The user must read the INTFLAG register to determine which interrupt condition is present. Note:  Interrupts must be globally enabled for interrupt requests to be generated. Related Links 22.6.3.3 Sleep Mode Controller 25.6.5 Events The SUPC can gemerate the following output event: • BOD12 Detection (BOD12DET): Generated when the VDDCORE crosses below the brown-out threshold level. • BOD33 Detection (BOD33DET): Generated when the VDD crosses below the brown-out threshold level. Writing a one to an Event Output bit in the Event Control Register (EVCTRL.xxEO) enables the corresponding output event. Writing a zero to this bit disables the corresponding output event. Refer to the Event System chapter for details on configuring the event system. 25.6.6 Synchronization The prescaler counters that are used to trigger brown-out detections operate asynchronously from the peripheral bus. As a consequence, the BOD33 Enable bit (BOD33.ENABLE) need synchronization when written. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 346 The Write-Synchronization of the Enable bit is triggered by writing a '1' to the Enable bit of the BOD33 Control register. The Synchronization Ready bit (STATUS.B33SRDY) in the STATUS register will be cleared when the Write-Synchronization starts, and set again when the Write-Synchronization is complete. Writing to the same register while the Write-Synchronization is ongoing (STATUS.B33SRDY is '0') will generate a PAC error without stalling the APB bus. 25.6.7 Low Power VREF in Active Mode During active functional mode, the brownout detector BOD33 and the main voltage regulator (VREG) can reduce their power consumption by using the low power voltage reference (ULPVREF). The low power voltage reference is ready and can be selected when ULPVREFRDY bit in STATUS register is high. The ULPVREF Ready (ULPVREFRDY) interrupt can also be used to detect a zero-to-one transition of the STATUS.ULPVREFRDY bit. Writing the VREF bit in the BOD33 register to '1' selects ULPVREF as voltage reference for the BOD33. If the chip operated in PL0 ((PM->PLCFG.PLSEL=0) or Performance Level is disabled (PM- >PLCFG.PLDIS=1), writing the VREFSEL bit in the VREG register to '1' selects ULPVREF as voltage reference for the main voltage regulator. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 347 25.7 Register Summary Offset Name Bit Pos. 0x00 INTENCLR 7:0 B33SRDY BOD33DET BOD33RDY 15:8 ULPVREFRD Y VCORERDY VREGRDY 23:16 31:24 0x04 INTENSET 7:0 B33SRDY BOD33DET BOD33RDY 15:8 ULPVREFRD Y VCORERDY VREGRDY 23:16 31:24 0x08 INTFLAG 7:0 B33SRDY BOD33DET BOD33RDY 15:8 ULPVREFRD Y VCORERDY VREGRDY 23:16 31:24 0x0C STATUS 7:0 B33SRDY BOD33DET BOD33RDY 15:8 ULPVREFRD Y VCORERDY VREGRDY 23:16 31:24 0x10 BOD33 7:0 RUNSTDBY STDBYCFG ACTION[1:0] HYST ENABLE 15:8 PSEL[3:0] VREFSEL ACTCFG 23:16 LEVEL[5:0] 31:24 0x14 ... 0x17 Reserved 0x18 VREG 7:0 RUNSTDBY STDBYPL0 SEL ENABLE 15:8 VREFSEL LPEFF 23:16 VSVSTEP[3:0] 31:24 VSPER[7:0] 0x1C VREF 7:0 ONDEMAND RUNSTDBY VREFOE TSEN 15:8 23:16 SEL[3:0] 31:24 0x20 ... 0x2B Reserved 0x2C EVCTRL 7:0 BOD33DETE O 15:8 23:16 31:24 SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 348 25.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16-, and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). PAC Writeprotection is denoted by the "PAC Write-Protection" property in each individual register description. Refer to 25.5.8 Register Access Protection for details. Some registers require synchronization when read and/or written. Synchronization is denoted by the "Write-Synchronized" or the "Read-Synchronized" property in each individual register description. Refer to 25.6.6 Synchronization for details. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 349 25.8.1 Interrupt Enable Clear Name:  INTENCLR Offset:  0x00 Reset:  0x00000000 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 ULPVREFRDY VCORERDY VREGRDY Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 B33SRDY BOD33DET BOD33RDY Access R/W R/W R/W Reset 0 0 0 Bit 11 – ULPVREFRDY Low Power Voltage Reference Ready Interrupt Enable Writing a '0' to this bit has no effect. The ULPVREFRDY bit will clear on a zero-to-one transition of the Low Power Voltage Reference Ready bit in the Status register (STATUS.ULPVREFRDY). Value Description 0 The Low Power Ready interrupt is disabled. 1 The Low Power Ready interrupt is enabled and an interrupt request will be generated when the ULPVREFRDY Interrupt Flag is set. Bit 10 – VCORERDY VDDCORE Voltage Ready Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the VDDCORE Ready Interrupt Enable bit, which disables the VDDCORE Ready interrupt. Value Description 0 The VDDCORE Ready interrupt is disabled. 1 The VDDCORE Ready interrupt is enabled and an interrupt request will be generated when the VCORERDY Interrupt Flag is set. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 350 Bit 8 – VREGRDY Voltage Regulator Ready Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Voltage Regulator Ready Interrupt Enable bit, which disables the Voltage Regulator Ready interrupt. Value Description 0 The Voltage Regulator Ready interrupt is disabled. 1 The Voltage Regulator Ready interrupt is enabled and an interrupt request will be generated when the Voltage Regulator Ready Interrupt Flag is set. Bit 2 – B33SRDY  BOD33 Synchronization Ready Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the BOD33 Synchronization Ready Interrupt Enable bit, which disables the BOD33 Synchronization Ready interrupt. Value Description 0 The BOD33 Synchronization Ready interrupt is disabled. 1 The BOD33 Synchronization Ready interrupt is enabled, and an interrupt request will be generated when the BOD33 Synchronization Ready Interrupt flag is set. Bit 1 – BOD33DET  BOD33 Detection Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the BOD33 Detection Interrupt Enable bit, which disables the BOD33 Detection interrupt. Value Description 0 The BOD33 Detection interrupt is disabled. 1 The BOD33 Detection interrupt is enabled, and an interrupt request will be generated when the BOD33 Detection Interrupt flag is set. Bit 0 – BOD33RDY  BOD33 Ready Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the BOD33 Ready Interrupt Enable bit, which disables the BOD33 Ready interrupt. Value Description 0 The BOD33 Ready interrupt is disabled. 1 The BOD33 Ready interrupt is enabled, and an interrupt request will be generated when the BOD33 Ready Interrupt flag is set. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 351 25.8.2 Interrupt Enable Set Name:  INTENSET Offset:  0x04 Reset:  0x00000000 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear register (INTENCLR). Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 ULPVREFRDY VCORERDY VREGRDY Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 B33SRDY BOD33DET BOD33RDY Access R/W R/W R/W Reset 0 0 0 Bit 11 – ULPVREFRDY Low Power Voltage Reference Ready Interrupt Enable Writing a '0' to this bit has no effect. The ULPVREFRDY bit is set on a zero-to-one transition of the Low Power Voltage Reference Ready bit in the Status register (STATUS.ULPVREFRDY). Value Description 0 The Low Power Ready interrupt is disabled. 1 The Low Power Ready interrupt is enabled and an interrupt request will be generated when the ULPVREFRDY Interrupt Flag is set. Bit 10 – VCORERDY VDDCORE Voltage Ready Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the VDDCORE Ready Interrupt Enable bit, which enables the VDDCORE Ready interrupt. Value Description 0 The VDDCORE Ready interrupt is disabled. 1 The VDDCORE Ready interrupt is enabled and an interrupt request will be generated when the VCORERDY Interrupt Flag is set. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 352 Bit 8 – VREGRDY Voltage Regulator Ready Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Voltage Regulator Ready Interrupt Enable bit, which enables the Voltage Regulator Ready interrupt. Value Description 0 The Voltage Regulator Ready interrupt is disabled. 1 The Voltage Regulator Ready interrupt is enabled and an interrupt request will be generated when the Voltage Regulator Ready Interrupt Flag is set. Bit 2 – B33SRDY  BOD33 Synchronization Ready Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the BOD33 Synchronization Ready Interrupt Enable bit, which enables the BOD33 Synchronization Ready interrupt. Value Description 0 The BOD33 Synchronization Ready interrupt is disabled. 1 The BOD33 Synchronization Ready interrupt is enabled, and an interrupt request will be generated when the BOD33 Synchronization Ready Interrupt flag is set. Bit 1 – BOD33DET  BOD33 Detection Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the BOD33 Detection Interrupt Enable bit, which enables the BOD33 Detection interrupt. Value Description 0 The BOD33 Detection interrupt is disabled. 1 The BOD33 Detection interrupt is enabled, and an interrupt request will be generated when the BOD33 Detection Interrupt flag is set. Bit 0 – BOD33RDY  BOD33 Ready Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the BOD33 Ready Interrupt Enable bit, which enables the BOD33 Ready interrupt. Value Description 0 The BOD33 Ready interrupt is disabled. 1 The BOD33 Ready interrupt is enabled, and an interrupt request will be generated when the BOD33 Ready Interrupt flag is set. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 353 25.8.3 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x08 Reset:  x initially determined from NVM User Row after reset Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 ULPVREFRDY VCORERDY VREGRDY Access R/W R/W R/W Reset 0 0 1 Bit 7 6 5 4 3 2 1 0 B33SRDY BOD33DET BOD33RDY Access R/W R/W R/W Reset 0 0 x Bit 11 – ULPVREFRDY Low Power Voltage Reference Ready Interrupt Enable Writing a '0' to this bit has no effect. The ULPVREFRDY bit will clear on a zero-to-one transition of the Low Power Voltage Reference Ready bit in the Status register (STATUS.ULPVREFRDY) and will generate an interrupt request if INTENSET.ULPVREFRDY=1. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the ULPVREFRDY interrupt flag. Bit 10 – VCORERDY VDDCORE Voltage Ready This flag is cleared by writing a '1 to it. This flag is set on a zero-to-one transition of the VDDCORE Ready bit in the Status register (STATUS.VCORERDY) and will generate an interrupt request if INTENSET.VCORERDY=1. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the VCORERDY interrupt flag. Bit 8 – VREGRDY Voltage Regulator Ready This flag is cleared by writing a '1' to it. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 354 This flag is set on a zero-to-one transition of the Voltage Regulator Ready bit in the Status register (STATUS.VREGRDY) and will generate an interrupt request if INTENSET.VREGRDY=1. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the VREGRDY interrupt flag. Bit 2 – B33SRDY  BOD33 Synchronization Ready This flag is cleared by writing a '1' to it. This flag is set on a zero-to-one transition of the BOD33 Synchronization Ready bit in the Status register (STATUS.B33SRDY) and will generate an interrupt request if INTENSET.B33SRDY=1. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the BOD33 Synchronization Ready interrupt flag. Bit 1 – BOD33DET  BOD33 Detection This flag is cleared by writing a '1' to it. This flag is set on a zero-to-one transition of the BOD33 Detection bit in the Status register (STATUS.BOD33DET) and will generate an interrupt request if INTENSET.BOD33DET=1. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the BOD33 Detection interrupt flag. Bit 0 – BOD33RDY  BOD33 Ready This flag is cleared by writing a '1' to it. This flag is set on a zero-to-one transition of the BOD33 Ready bit in the Status register (STATUS.BOD33RDY) and will generate an interrupt request if INTENSET.BOD33RDY=1. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the BOD33 Ready interrupt flag. The BOD33 can be enabled. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 355 25.8.4 Status Name:  STATUS Offset:  0x0C Reset:  x,y initially determined from NVM User Row after reset Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 ULPVREFRDY VCORERDY VREGRDY Access R R R Reset x 1 1 Bit 7 6 5 4 3 2 1 0 B33SRDY BOD33DET BOD33RDY Access R R R Reset 0 0 y Bit 12 – ULPVREFRDY Low Power Voltage Reference Ready Value Description 0 The ULPVREF voltage is not as expected. 1 The ULPVREF voltage is the target voltage. Bit 10 – VCORERDY VDDCORE Voltage Ready Value Description 0 The VDDCORE voltage is not as expected. 1 The VDDCORE voltage is the target voltage. Bit 8 – VREGRDY Voltage Regulator Ready Value Description 0 The selected voltage regulator in VREG.SEL is not ready. 1 The voltage regulator selected in VREG.SEL is ready and the core domain is supplied by this voltage regulator. Bit 2 – B33SRDY  BOD33 Synchronization Ready SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 356 Value Description 0 BOD33 synchronization is ongoing. 1 BOD33 synchronization is complete. Bit 1 – BOD33DET  BOD33 Detection Value Description 0 No BOD33 detection. 1 BOD33 has detected that the I/O power supply is going below the BOD33 reference value. Bit 0 – BOD33RDY  BOD33 Ready The BOD33 can be enabled at start-up from NVM User Row. Value Description 0 BOD33 is not ready. 1 BOD33 is ready. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 357 25.8.5 3.3V Brown-Out Detector (BOD33) Control Name:  BOD33 Offset:  0x10 Reset:  x initially determined from NVM User Row after reset Property:  Write-Synchronized, Enable-Protected, PAC Write-Protection Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 LEVEL[5:0] Access R/W R/W R/W R/W R/W R/W Reset x x x x x x Bit 15 14 13 12 11 10 9 8 PSEL[3:0] VREFSEL ACTCFG Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 RUNSTDBY STDBYCFG ACTION[1:0] HYST ENABLE Access R/W R/W R/W R/W R/W R/W Reset 0 0 x x x x Bits 21:16 – LEVEL[5:0]  BOD33 Threshold Level on VDD These bits set the triggering voltage threshold for the BOD33 when the BOD33 monitors the VDD. These bits are loaded from NVM User Row at start-up. This bit field is not synchronized. Bits 15:12 – PSEL[3:0] Prescaler Select Selects the prescaler divide-by output for the BOD33 sampling mode. The input clock comes from the OSCULP32K 1KHz output. Value Name Description 0x0 DIV2 Divide clock by 2 0x1 DIV4 Divide clock by 4 0x2 DIV8 Divide clock by 8 0x3 DIV16 Divide clock by 16 0x4 DIV32 Divide clock by 32 0x5 DIV64 Divide clock by 64 0x6 DIV128 Divide clock by 128 0x7 DIV256 Divide clock by 256 0x8 DIV512 Divide clock by 512 0x9 DIV1024 Divide clock by 1024 SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 358 Value Name Description 0xA DIV2048 Divide clock by 2048 0xB DIV4096 Divide clock by 4096 0xC DIV8192 Divide clock by 8192 0xD DIV16384 Divide clock by 16384 0xE DIV32768 Divide clock by 32768 0xF DIV65536 Divide clock by 65536 Bit 11 – VREFSEL  BOD33 Voltage Reference Selection This bit is not synchronized. Value Description 0 Selects VREF for the BOD33. 1 Selects ULPVREF for the BOD33. Bit 8 – ACTCFG  BOD33 Configuration in Active Sleep Mode This bit is not synchronized. Value Description 0 In active mode, the BOD33 operates in continuous mode. 1 In active mode, the BOD33 operates in sampling mode. Bit 6 – RUNSTDBY Run in Standby This bit is not synchronized. Value Description 0 In standby sleep mode, the BOD33 is disabled. 1 In standby sleep mode, the BOD33 is enabled. Bit 5 – STDBYCFG  BOD33 Configuration in Standby Sleep Mode If the RUNSTDBY bit is set to '1', the STDBYCFG bit sets the BOD33 configuration in standby sleep mode. This bit is not synchronized. Value Description 0 In standby sleep mode, the BOD33 is enabled and configured in continuous mode. 1 In standby sleep mode, the BOD33 is enabled and configured in sampling mode. Bits 4:3 – ACTION[1:0]  BOD33 Action These bits are used to select the BOD33 action when the supply voltage crosses below the BOD33 threshold. These bits are loaded from NVM User Row at start-up. This bit field is not synchronized. Value Name Description 0x0 NONE No action 0x1 RESET The BOD33 generates a reset SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 359 Value Name Description 0x2 INT The BOD33 generates an interrupt 0x3 - Reserved Bit 2 – HYST Hysteresis This bit indicates whether hysteresis is enabled for the BOD33 threshold voltage. This bit is loaded from NVM User Row at start-up. This bit is not synchronized. Value Description 0 No hysteresis. 1 Hysteresis enabled. Bit 1 – ENABLE Enable This bit is loaded from NVM User Row at start-up. This bit is not enable-protected. Value Description 0 BOD33 is disabled. 1 BOD33 is enabled. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 360 25.8.6 Voltage Regulator System (VREG) Control Name:  VREG Offset:  0x18 Reset:  0x00000002 Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 VSPER[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 VSVSTEP[3:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 VREFSEL LPEFF Access R/W R/W Reset 0 0 Bit 7 6 5 4 3 2 1 0 RUNSTDBY STDBYPL0 SEL ENABLE Access R/W R/W R/W R/W Reset 0 1 0 1 Bits 31:24 – VSPER[7:0] Voltage Scaling Period This bitfield sets the period between the voltage steps when the VDDCORE voltage is changing in µs. If VSPER=0, the period between two voltage steps is 1µs. Bits 19:16 – VSVSTEP[3:0] Voltage Scaling Voltage Step This field sets the voltage step height when the VDDCORE voltage is changing to reach the target VDDCORE voltage. The voltage step is equal to 2VSVSTEP* min_step. See the Electrical Characteristics chapters for the min_step voltage level. Bit 9 – VREFSEL Voltage Regulator Voltage Reference Selection This bit provides support of using ULPVREF during active function mode. Value Description 0 Selects VREF for the voltage regulator. 1 Selects ULPVREF for the voltage regulator. Bit 8 – LPEFF Low power Mode Efficiency SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 361 Value Description 0 The voltage regulator in Low power mode has the default efficiency and supports the whole VDD range (1.62V to 3.63V). 1 The voltage regulator in Low power mode has the highest efficiency and supports a limited VDD range (2.5V to 3.63V). Bit 6 – RUNSTDBY Run in Standby Value Description 0 The voltage regulator is in low power mode in Standby sleep mode. 1 The voltage regulator is in normal mode in Standby sleep mode. Bit 5 – STDBYPL0 Standby in PL0 This bit selects the performance level (PL) of the main voltage regulator for the Standby sleep mode. This bit is only considered when RUNSTDBY=1. Value Description 0 In Standby sleep mode, the voltage regulator remains in the current performance level. 1 In Standby sleep mode, the voltage regulator is used in PL0. Bit 2 – SEL Voltage Regulator Selection Value Description 0 The voltage regulator in active mode is a LDO voltage regulator. 1 The voltage regulator in active mode is a buck converter. Bit 1 – ENABLE Enable Value Description 0 The voltage regulator is disabled. 1 The voltage regulator is enabled. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 362 25.8.7 Voltage References System (VREF) Control Name:  VREF Offset:  0x1C Reset:  0x00000000 Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 SEL[3:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 ONDEMAND RUNSTDBY VREFOE TSEN Access R/W R/W R/W R/W Reset 0 0 0 0 Bits 19:16 – SEL[3:0] Voltage Reference Selection These bits select the Voltage Reference for the ADC/DAC. Value Name Description 0x0 1V0 1.0V voltage reference typical value 0x1 1V1 1.1V voltage reference typical valueThe 1.1V voltage reference typical value must be selected for DAC use. Other values are not permitted. 0x2 1V2 1.2V voltage reference typical value 0x3 1V25 1.25V voltage reference typical value 0x4 2V0 2.0V voltage reference typical value 0x5 2V2 2.2V voltage reference typical value 0x6 2V4 2.4V voltage reference typical value 0x7 2V5 2.5V voltage reference typical value Others Reserved Bit 7 – ONDEMAND On Demand Control The On Demand operation mode allows to enable or disable the voltage reference depending on peripheral requests. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 363 Value Description 0 The voltage reference is always on, if enabled. 1 The voltage reference is enabled when a peripheral is requesting it. The voltage reference is disabled if no peripheral is requesting it. Bit 6 – RUNSTDBY Run In Standby The bit controls how the voltage reference behaves during standby sleep mode. Value Description 0 The voltage reference is halted during standby sleep mode. 1 The voltage reference is not stopped in standby sleep mode. If VREF.ONDEMAND=1, the voltage reference will be running when a peripheral is requesting it. If VREF.ONDEMAND=0, the voltage reference will always be running in standby sleep mode. Bit 2 – VREFOE Voltage Reference Output Enable Value Description 0 The Voltage Reference output (INTREF) is not available as an ADC input channel. 1 The Voltage Reference output (INTREF) is routed to an ADC input channel. Bit 1 – TSEN Temperature Sensor Enable Value Description 0 Temperature Sensor is disabled. 1 Temperature Sensor is enabled and routed to an ADC input channel. SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 364 25.8.8 Event Control Name:  EVCTRL Offset:  0x2C Reset:  0x0000000 Property:  Enable-Protected, PAC Write-Protection Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 BOD33DETEO Access R/W Reset 0 Bit 1 – BOD33DETEO BOD33 Detection Event Output Enable Value Description 0 BOD33 detection event output is disabled and event will not be generated 1 BOD33 detection event output is enabled and event will be generated SAM L10/L11 Family SUPC – Supply Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 365 26. WDT – Watchdog Timer 26.1 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 configured to a predefined time-out period, and is constantly running when enabled. If the WDT is not cleared within the time-out period, it will issue a system reset. An early-warning interrupt is available to indicate an upcoming watchdog time-out condition. The window mode makes it possible to define a time slot (or window) inside the total time-out period during which the WDT must be cleared. If the WDT is cleared 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 the WDT to be cleared frequently. When enabled, the WDT will run in active mode and all sleep modes. It is asynchronous and runs from a CPU-independent clock source. The WDT will continue operation and issue a system reset or interrupt even if the main clocks fail. 26.2 Features • Issues a system reset if the Watchdog Timer is not cleared before its time-out period • Early Warning interrupt generation • Asynchronous operation from dedicated oscillator • Two types of operation – Normal – Window mode • Selectable time-out periods – From 8 cycles to 16,384 cycles in Normal mode – From 16 cycles to 32,768 cycles in Window mode • Always-On capability SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 366 26.3 Block Diagram Figure 26-1. WDT Block Diagram 0xA5 CLEAR COUNT 0 CLK_WDT_OSC OSC32KCTRL PER/WINDOWS/EWOFFSET Early Warning Interrupt Reset 26.4 Signal Description Not applicable. 26.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 26.5.1 I/O Lines Not applicable. 26.5.2 Power Management The WDT can continue to operate in any sleep modes where the selected source clock is running. The WDT interrupts can be used to wake up the device from sleep modes. The events can trigger other operations in the system without exiting sleep modes. Related Links 22. PM – Power Manager 26.5.3 Clocks The WDT bus clock (CLK_WDT_APB) can be enabled and disabled (masked) in the Main Clock module (MCLK). A 1.024 kHz oscillator clock (CLK_WDT_OSC) is required to clock the WDT internal counter. The CLK_WDT_OSC CLOCK is sourced from the clock of the internal Ultra Low-Power Oscillator (OSCULP32K). Due to ultra low-power design, the oscillator is not accurate, hence the exact time-out period may vary from device-to-device. This variation must be considered when designing software that uses the WDT to ensure that the time-out periods used are valid for all devices. SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 367 The counter clock CLK_WDT_OSC is asynchronous to the bus clock (CLK_WDT_APB). Due to this asynchronicity, writing to certain registers will require synchronization between the clock domains. Refer to 26.6.7 Synchronization for further details. Related Links 19.6.2.6 Peripheral Clock Masking 24. OSC32KCTRL – 32KHz Oscillators Controller 26.5.4 DMA Not applicable. 26.5.5 Interrupts The interrupt request line is connected to the interrupt controller. Using the WDT interrupt(s) requires the interrupt controller to be configured first. 26.5.6 Events Not applicable. 26.5.7 Debug Operation When the CPU is halted in debug mode the WDT will halt normal operation. 26.5.8 Register Access Protection All registers with write-access can be write-protected optionally by the Peripheral Access Controller (PAC), except for the following registers: • Interrupt Flag Status and Clear (INTFLAG) register Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. PAC write-protection does not apply to accesses through an external debugger. 26.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 26.5.10 Analog Connections Not applicable. 26.6 Functional Description 26.6.1 Principle of Operation The Watchdog Timer (WDT) is a system for monitoring correct program operation, making it possible to recover from error situations such as runaway code, by issuing a Reset. When enabled, the WDT is a SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 368 constantly running timer that is configured to a predefined time-out period. Before the end of the time-out period, the WDT should be set back, or else, a system Reset is issued. The WDT has two modes of operation, Normal mode and Window mode. Both modes offer the option of Early Warning interrupt generation. The description for each of the basic modes is given below. The settings in the Control A register (CTRLA) and the Interrupt Enable register (handled by INTENCLR/ INTENSET) determine the mode of operation: Table 26-1. WDT Operating Modes CTRLA.ENABLE CTRLA.WEN Interrupt Enable Mode 0 x x Stopped 1 0 0 Normal mode 1 0 1 Normal mode with Early Warning interrupt 1 1 0 Window mode 1 1 1 Window mode with Early Warning interrupt 26.6.2 Basic Operation 26.6.2.1 Initialization The following bits are enable-protected, meaning that they can only be written when the WDT is disabled (CTRLA.ENABLE=0): • Control A register (CTRLA), except the Enable bit (CTRLA.ENABLE) • Configuration register (CONFIG) • Early Warning Interrupt Control register (EWCTRL) Enable-protected bits in the CTRLA register can be written at the same time as CTRLA.ENABLE is written to '1', but not at the same time as CTRLA.ENABLE is written to '0'. The WDT can be configured only while the WDT is disabled. The WDT is configured by defining the required Time-Out Period bits in the Configuration register (CONFIG.PER). If Window mode operation is desired, the Window Enable bit in the Control A register must be set (CTRLA.WEN=1) and the Window Period bits in the Configuration register (CONFIG.WINDOW) must be defined. Enable-protection is denoted by the "Enable-Protected" property in the register description. 26.6.2.2 Configurable Reset Values After a Power-on Reset, some registers will be loaded with initial values from the NVM User Row. This includes the following bits and bit groups: • Enable bit in the Control A register, CTRLA.ENABLE • Always-On bit in the Control A register, CTRLA.ALWAYSON • Run In Standby Enable bit in the Control A register (CTRLA.RUNSTDBY) • Watchdog Timer Windows Mode Enable bit in the Control A register, CTRLA.WEN • Watchdog Timer Windows Mode Time-Out Period bits in the Configuration register, CONFIG.WINDOW • Time-Out Period bits in the Configuration register, CONFIG.PER • Early Warning Interrupt Time Offset bits in the Early Warning Interrupt Control register, EWCTRL.EWOFFSET SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 369 26.6.2.3 Enabling, Disabling, and Resetting The WDT is enabled by writing a '1' to the Enable bit in the Control A register (CTRLA.ENABLE). The WDT is disabled by writing a '0' to CTRLA.ENABLE. The WDT can be disabled only if the Always-On bit in the Control A register (CTRLA.ALWAYSON) is '0'. 26.6.2.4 Normal Mode In Normal mode operation, the length of a time-out period is configured in CONFIG.PER. The WDT is enabled by writing a '1' to the Enable bit in the Control A register (CTRLA.ENABLE). Once enabled, the WDT will issue a system reset if a time-out occurs. This can be prevented by clearing the WDT at any time during the time-out period. The WDT is cleared and a new WDT time-out period is started by writing 0xA5 to the Clear register (CLEAR). Writing any other value than 0xA5 to CLEAR will issue an immediate system reset. There are 12 possible WDT time-out (TOWDT) periods, selectable from 8ms to 16s. By default, the early warning interrupt is disabled. If it is desired, the Early Warning Interrupt Enable bit in the Interrupt Enable register (INTENSET.EW) must be written to '1'. The Early Warning Interrupt is disabled again by writing a '1' to the Early Warning Interrupt bit in the Interrupt Enable Clear register (INTENCLR.EW). If the Early Warning Interrupt is enabled, an interrupt is generated prior to a WDT time-out condition. In Normal mode, the Early Warning Offset bits in the Early Warning Interrupt Control register, EWCTRL.EWOFFSET, define the time when the early warning interrupt occurs. The Normal mode operation is illustrated in the figure Normal-Mode Operation. Figure 26-2. Normal-Mode Operation 5 10 15 20 25 30 35 WDT Timeout Early Warning Interrupt Timely WDT Clear t[ms] TOWDT System Reset WDT Count PER[3:0] = 1 EWOFFSET[3:0] = 0 26.6.2.5 Window Mode In Window mode operation, the WDT uses two different time specifications: the WDT can only be cleared by writing 0xA5 to the CLEAR register after the closed window time-out period (TOWDTW), during the subsequent Normal time-out period (TOWDT). If the WDT is cleared before the time window opens (before TOWDTW is over), the WDT will issue a system reset. Both parameters TOWDTW and TOWDT are periods in a range from 8ms to 16s, so the total duration of the WDT time-out period is the sum of the two parameters. The closed window period is defined by the Window Period bits in the Configuration register (CONFIG.WINDOW), and the open window period is defined by the Period bits in the Configuration register (CONFIG.PER). By default, the Early Warning interrupt is disabled. If it is desired, the Early Warning Interrupt Enable bit in the Interrupt Enable register (INTENSET.EW) must be written to '1'. The Early Warning Interrupt is SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 370 disabled again by writing a '1' to the Early Warning Interrupt bit in the Interrupt Enable Clear (INTENCLR.EW) register. If the Early Warning interrupt is enabled in Window mode, the interrupt is generated at the start of the open window period, i.e. after TOWDTW. The Window mode operation is illustrated in figure Window-Mode Operation. Figure 26-3. Window-Mode Operation 5 10 15 20 25 30 35 WDT Timeout Early Warning Interrupt Timely WDT Clear t[ms] TOWDT System Reset WDT Count PER[3:0] = 0 WINDOW[3:0] = 0 TOWDTW Early WDT Clear Closed Open 26.6.3 DMA Operation Not applicable. 26.6.4 Interrupts The WDT has the following interrupt source: • Early Warning (EW): Indicates that the counter is approaching the time-out condition. – This interrupt is an asynchronous wake-up source. Each interrupt source has an interrupt flag associated with it. The interrupt flag in the Interrupt Flag Status and Clear (INTFLAG) register is set when the interrupt condition occurs. Each interrupt can be individually enabled by writing a '1' to the corresponding bit in the Interrupt Enable Set (INTENSET) register, and disabled by writing a '1' to the corresponding bit in the Interrupt Enable Clear (INTENCLR) register. An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until the interrupt flag is cleared, the interrupt is disabled, or the WDT is reset. See the 26.8.6 INTFLAG register description for details on how to clear interrupt flags. All interrupt requests from the peripheral are ORed together on system level to generate one combined interrupt request to the NVIC. The user must read the INTFLAG register to determine which interrupt condition is present. Note:  Interrupts must be globally enabled for interrupt requests to be generated. Related Links 22. PM – Power Manager 22.6.3.3 Sleep Mode Controller 26.6.5 Events Not applicable. SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 371 26.6.6 Sleep Mode Operation The Run-In-Standby bit in Control A (CTRLA.RUNSTDBY) control the behavior of the WDT during standby sleep mode. When the bit is zero, the watchdog is disabled during sleep, but maintains its current configuration. When CTRLA.RUNSTDBY is '1', the WDT continues to operate during sleep. Related Links 26.8.1 CTRLA 26.6.7 Synchronization Due to asynchronicity between the main clock domain and the peripheral clock domains, some registers need to be synchronized when written or read. The following registers are synchronized when written: • Enable bit in Control A register (CTRLA.ENABLE) • Window Enable bit in Control A register (CTRLA.WEN) • Run-In-Standby bit in Control A register (CTRLA.RUNSTDBY) • Always-On bit in control Control A (CTRLA.ALWAYSON) • Watchdog Clear register (CLEAR) Required write-synchronization is denoted by the "Write-Synchronized" property in the register description. Required read-synchronization is denoted by the "Read-Synchronized" property in the register description. 26.6.8 Additional Features 26.6.8.1 Always-On Mode The Always-On mode is enabled by setting the Always-On bit in the Control A register (CTRLA.ALWAYSON=1). When the Always-On mode is enabled, the WDT runs continuously, regardless of the state of CTRLA.ENABLE. Once written, the Always-On bit can only be cleared by a power-on reset. The Configuration (CONFIG) and Early Warning Control (EWCTRL) registers are read-only registers while the CTRLA.ALWAYSON bit is set. Thus, the time period configuration bits (CONFIG.PER, CONFIG.WINDOW, EWCTRL.EWOFFSET) of the WDT cannot be changed. Enabling or disabling Window mode operation by writing the Window Enable bit (CTRLA.WEN) is allowed while in Always-On mode, but note that CONFIG.PER cannot be changed. The Interrupt Clear and Interrupt Set registers are accessible in the Always-On mode. The Early Warning interrupt can still be enabled or disabled while in the Always-On mode, but note that EWCTRL.EWOFFSET cannot be changed. Table WDT Operating Modes With Always-On shows the operation of the WDT for CTRLA.ALWAYSON=1. Table 26-2. WDT Operating Modes With Always-On WEN Interrupt Enable Mode 0 0 Always-on and normal mode 0 1 Always-on and normal mode with Early Warning interrupt SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 372 WEN Interrupt Enable Mode 1 0 Always-on and window mode 1 1 Always-on and window mode with Early Warning interrupt 26.6.8.2 Early Warning The Early Warning interrupt notifies that the WDT is approaching its time-out condition. The Early Warning interrupt behaves differently in Normal mode and in Window mode. In Normal mode, the Early Warning interrupt generation is defined by the Early Warning Offset in the Early Warning Control register (EWCTRL.EWOFFSET). The Early Warning Offset bits define the number of CLK_WDT_OSC clocks before the interrupt is generated, relative to the start of the watchdog time-out period. The user must take caution when programming the Early Warning Offset bits. If these bits define an Early Warning interrupt generation time greater than the watchdog time-out period, the watchdog time-out system reset is generated prior to the Early Warning interrupt. Consequently, the Early Warning interrupt will never be generated. In window mode, the Early Warning interrupt is generated at the start of the open window period. In a typical application where the system is in sleep mode, the Early Warning interrupt can be used to wake up and clear the Watchdog Timer, after which the system can perform other tasks or return to sleep mode. If the WDT is operating in Normal mode with CONFIG.PER = 0x2 and EWCTRL.EWOFFSET = 0x1, the Early Warning interrupt is generated 16 CLK_WDT_OSC clock cycles after the start of the time-out period. The time-out system reset is generated 32 CLK_WDT_OSC clock cycles after the start of the watchdog timeout period. SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 373 26.7 Register Summary Offset Name Bit Pos. 0x00 CTRLA 7:0 ALWAYSON RUNSTDBY WEN ENABLE 0x01 CONFIG 7:0 WINDOW[3:0] PER[3:0] 0x02 EWCTRL 7:0 EWOFFSET[3:0] 0x03 Reserved 0x04 INTENCLR 7:0 EW 0x05 INTENSET 7:0 EW 0x06 INTFLAG 7:0 EW 0x07 Reserved 0x08 SYNCBUSY 7:0 CLEAR ALWAYSON RUNSTDBY WEN ENABLE 15:8 23:16 31:24 0x0C CLEAR 7:0 CLEAR[7:0] 26.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to 26.5.8 Register Access Protection. Some registers are synchronized when read and/or written. Synchronization is denoted by the "WriteSynchronized" or the "Read-Synchronized" property in each individual register description. For details, refer to 26.6.7 Synchronization. Some registers are enable-protected, meaning they can only be written when the peripheral is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 374 26.8.1 Control A Name:  CTRLA Offset:  0x00 Reset:  x initially determined from NVM User Row after reset Property:  PAC Write-Protection, Write-Synchronized Bit 7 6 5 4 3 2 1 0 ALWAYSON RUNSTDBY WEN ENABLE Access R/W R/W R/W R/W Reset x x x x Bit 7 – ALWAYSON Always-On This bit allows the WDT to run continuously. After being set, this bit cannot be written to '0', and the WDT will remain enabled until a power-on Reset is received. When this bit is '1', the Control A register (CTRLA), the Configuration register (CONFIG) and the Early Warning Control register (EWCTRL) will be read-only, and any writes to these registers are not allowed. Writing a '0' to this bit has no effect. This bit is not Enable-Protected. This bit is loaded from NVM User Row at start-up. Value Description 0 The WDT is enabled and disabled through the ENABLE bit. 1 The WDT is enabled and can only be disabled by a power-on reset (POR). Bit 6 – RUNSTDBY Run in Standby This bit controls the behavior of the watchdog during standby sleep mode. This bit can only be written when CTRLA.ENABLE is zero or CTRLA.ALWAYSON is one: • When CTRLA.ALWAYSON=0, this bit is enable-protected by CTRLA.ENABLE. • When CTRLA.ALWAYSON=1, this bit is not enable-protected by CTRLA.ENABLE. These bits are loaded from NVM User Row at startup. Value Description 0 The WDT is disabled during standby sleep. 1 The WDT is enabled continues to operate during standby sleep. Bit 2 – WEN Watchdog Timer Window Mode Enable This bit enables Window mode. It can only be written if the peripheral is disabled unless CTRLA.ALWAYSON=1. The initial value of this bit is loaded from Flash Calibration. This bit is loaded from NVM User Row at startup. Value Description 0 Window mode is disabled (normal operation). 1 Window mode is enabled. SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 375 Bit 1 – ENABLE Enable This bit enables or disables the WDT. It can only be written if CTRLA.ALWAYSON=0. Due to synchronization, there is delay between writing CTRLA.ENABLE until the peripheral is enabled/ disabled. The value written to CTRLA.ENABLE will read back immediately, and the Enable bit in the Synchronization Busy register (SYNCBUSY.ENABLE) will be set. SYNCBUSY.ENABLE will be cleared when the operation is complete. This bit is not Enable-Protected. This bit is loaded from NVM User Row at startup. Value Description 0 The WDT is disabled. 1 The WDT is enabled. SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 376 26.8.2 Configuration Name:  CONFIG Offset:  0x01 Reset:  x initially determined from NVM User Row after reset Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 WINDOW[3:0] PER[3:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset x x x x x x x x Bits 7:4 – WINDOW[3:0] Window Mode Time-Out Period In Window mode, these bits determine the watchdog closed window period as a number of cycles of the 1.024kHz CLK_WDT_OSC clock. These bits are loaded from NVM User Row at start-up. Value Name Description 0x0 CYC8 8 clock cycles 0x1 CYC16 16 clock cycles 0x2 CYC32 32 clock cycles 0x3 CYC64 64 clock cycles 0x4 CYC128 128 clock cycles 0x5 CYC256 256 clock cycles 0x6 CYC512 512 clock cycles 0x7 CYC1024 1024 clock cycles 0x8 CYC2048 2048 clock cycles 0x9 CYC4096 4096 clock cycles 0xA CYC8192 8192 clock cycles 0xB CYC16384 16384 clock cycles 0xC-0xF Reserved Reserved Bits 3:0 – PER[3:0]  Time-Out Period These bits determine the watchdog time-out period as a number of 1.024kHz CLK_WDTOSC clock cycles. In Window mode operation, these bits define the open window period. These bits are loaded from NVM User Row at startup. Value Name Description 0x0 CYC8 8 clock cycles 0x1 CYC16 16 clock cycles 0x2 CYC32 32 clock cycles 0x3 CYC64 64 clock cycles 0x4 CYC128 128 clock cycles 0x5 CYC256 256 clock cycles 0x6 CYC512 512 clock cycles 0x7 CYC1024 1024 clock cycles 0x8 CYC2048 2048 clock cycles SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 377 Value Name Description 0x9 CYC4096 4096 clock cycles 0xA CYC8192 8192 clock cycles 0xB CYC16384 16384 clock cycles 0xC - 0xF - Reserved SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 378 26.8.3 Early Warning Control Name:  EWCTRL Offset:  0x02 Reset:  x initially determined from NVM User Row after reset Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 EWOFFSET[3:0] Access R/W R/W R/W R/W Reset x x x x Bits 3:0 – EWOFFSET[3:0] Early Warning Interrupt Time Offset These bits determine the number of GCLK_WDT clock cycles between the start of the watchdog time-out period and the generation of the Early Warning interrupt. These bits are loaded from NVM User Row at start-up. Value Name Description 0x0 CYC8 8 clock cycles 0x1 CYC16 16 clock cycles 0x2 CYC32 32 clock cycles 0x3 CYC64 64 clock cycles 0x4 CYC128 128 clock cycles 0x5 CYC256 256 clock cycles 0x6 CYC512 512 clock cycles 0x7 CYC1024 1024 clock cycles 0x8 CYC2048 2048 clock cycles 0x9 CYC4096 4096 clock cycles 0xA CYC8192 8192 clock cycles 0xB - 0xF Reserved Reserved SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 379 26.8.4 Interrupt Enable Clear Name:  INTENCLR Offset:  0x04 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set (INTENSET) register. Bit 7 6 5 4 3 2 1 0 EW Access R/W Reset 0 Bit 0 – EW Early Warning Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Early Warning Interrupt Enable bit, which disables the Early Warning interrupt. Value Description 0 The Early Warning interrupt is disabled. 1 The Early Warning interrupt is enabled. SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 380 26.8.5 Interrupt Enable Set Name:  INTENSET Offset:  0x05 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear (INTENCLR) register. Bit 7 6 5 4 3 2 1 0 EW Access R/W Reset 0 Bit 0 – EW Early Warning Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit sets the Early Warning Interrupt Enable bit, which enables the Early Warning interrupt. Value Description 0 The Early Warning interrupt is disabled. 1 The Early Warning interrupt is enabled. SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 381 26.8.6 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x06 Reset:  0x00 Property:  N/A Bit 7 6 5 4 3 2 1 0 EW Access R/W Reset 0 Bit 0 – EW Early Warning This flag is cleared by writing a '1' to it. This flag is set when an Early Warning interrupt occurs, as defined by the EWOFFSET bit group in EWCTRL. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Early Warning interrupt flag. SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 382 26.8.7 Synchronization Busy Name:  SYNCBUSY Offset:  0x08 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 CLEAR ALWAYSON RUNSTDBY WEN ENABLE Access R R R R R Reset 0 0 0 0 0 Bit 5 – CLEAR Clear Synchronization Busy Value Description 0 Write synchronization of the CLEAR register is complete. 1 Write synchronization of the CLEAR register is ongoing. Bit 4 – ALWAYSON Always-On Synchronization Busy Value Description 0 Write synchronization of the CTRLA.ALWAYSON bit is complete. 1 Write synchronization of the CTRLA.ALWAYSON bit is ongoing. Bit 3 – RUNSTDBY Run-In-Standby Synchronization Busy Value Description 0 Write synchronization of the CTRLA.RUNSTDBY bit is complete. 1 Write synchronization of the CTRLA.RUNSTDBY bit is ongoing. Bit 2 – WEN Window Enable Synchronization Busy Value Description 0 Write synchronization of the CTRLA.WEN bit is complete. 1 Write synchronization of the CTRLA.WEN bit is ongoing. SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 383 Bit 1 – ENABLE Enable Synchronization Busy Value Description 0 Write synchronization of the CTRLA.ENABLE bit is complete. 1 Write synchronization of the CTRLA.ENABLE bit is ongoing. SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 384 26.8.8 Clear Name:  CLEAR Offset:  0x0C Reset:  0x00 Property:  Write-Synchronized Bit 7 6 5 4 3 2 1 0 CLEAR[7:0] Access W W W W W W W W Reset 0 0 0 0 0 0 0 0 Bits 7:0 – CLEAR[7:0] Watchdog Clear In Normal mode, writing 0xA5 to this register during the watchdog time-out period will clear the Watchdog Timer and the watchdog time-out period is restarted. In Window mode, any writing attempt to this register before the time-out period started (i.e., during TOWDTW) will issue an immediate system Reset. Writing 0xA5 during the time-out period TOWDT will clear the Watchdog Timer and the complete time-out sequence (first TOWDTW then TOWDT) is restarted. In both modes, writing any other value than 0xA5 will issue an immediate system Reset. SAM L10/L11 Family WDT – Watchdog Timer © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 385 27. RTC – Real-Time Counter 27.1 Overview The Real-Time Counter (RTC) is a 32-bit counter with a 10-bit programmable prescaler that typically runs continuously to keep track of time. The RTC can wake up the device from sleep modes using the alarm/ compare wake up, periodic wake up, or overflow wake up mechanisms, or from the wake inputs. The RTC can generate periodic peripheral events from outputs of the prescaler, as well as alarm/compare interrupts and peripheral events, which can trigger at any counter value. Additionally, the timer can trigger an overflow interrupt and peripheral event, and can be reset on the occurrence of an alarm/compare match. This allows periodic interrupts and peripheral events at very long and accurate intervals. The 10-bit programmable prescaler can scale down the clock source. By this, a wide range of resolutions and time-out periods can be configured. With a 32.768kHz clock source, the minimum counter tick interval is 30.5µs, and time-out periods can range up to 36 hours. For a counter tick interval of 1s, the maximum time-out period is more than 136 years. 27.2 Features • 32-bit counter with 10-bit prescaler • Multiple clock sources • 32-bit or 16-bit counter mode • One 32-bit or two 16-bit compare values • Clock/Calendar mode – Time in seconds, minutes, and hours (12/24) – Date in day of month, month, and year – Leap year correction • Digital prescaler correction/tuning for increased accuracy • Overflow, alarm/compare match and prescaler interrupts and events – Optional clear on alarm/compare match • 2 general purpose registers • Tamper Detection – Timestamp on event or up to 5 inputs with debouncing – Active layer protection SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 386 27.3 Block Diagram Figure 27-1. RTC Block Diagram (Mode 0 — 32-Bit Counter) OVF MATCHCLR CMPn OSC32KCTRL CLK_RTC_OSC PRESCALER CLK_RTC_CNT Periodic Events COUNT COMPn = 0x00000000 Figure 27-2. RTC Block Diagram (Mode 1 — 16-Bit Counter) CLK_RTC_OSC CLK_RTC_CNT OSC32KCTRL PRESCALER COMPn PER COUNT 0x0000 Periodic Events CMPn OVF Figure 27-3. RTC Block Diagram (Mode 2 — Clock/Calendar) CLK_RTC_OSC CLK_RTC_CNT OSC32KCTRL PRESCALER Periodic Events MASKn CLOCK ALARMn 0x00000000 OVF MATCHCLR ALARMn SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 387 Figure 27-4. RTC Block Diagram (Tamper Detection Use Case) PRESCALER TIMESTAMP CAPTURE IN2 IN1 IN0 OUT0 Tamper Input [0..n] PCB Active Layer Protection TAMPEVT TAMPER OUT1 OUT2 ALARM Pseudo-Random Bitstream DEBOUNCE DEBOUNCE DEBOUNCE FREQCORR CLOCK TrustRAM shield OUT3 SEPTO SEPTO SEPTO Related Links 27.6.2.3 32-Bit Counter (Mode 0) 27.6.2.4 16-Bit Counter (Mode 1) 27.6.2.5 Clock/Calendar (Mode 2) 27.6.8.4 Tamper Detection 27.4 Signal Description Table 27-1. Signal Description Signal Description Type INn [n=0..4] Tamper Detection Input Digital input OUT Tamper Detection Output Digital output One signal can be mapped to one of several pins. Related Links 4.1 Multiplexed Signals 27.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 27.5.1 I/O Lines For more information on I/O configurations, refer to the "RTC Pinout" section. Related Links: I/O Multiplexing and Considerations 27.5.2 Power Management The RTC will continue to operate in any sleep mode where the selected source clock is running. The RTC interrupts can be used to wake up the device from sleep modes. Events connected to the event system can trigger other operations in the system without exiting sleep modes. Refer to the Power Manager for details on the different sleep modes. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 388 The RTC will be reset only at power-on (POR) or by setting the Software Reset bit in the Control A register (CTRLA.SWRST=1). Related Links 22. PM – Power Manager 27.5.3 Clocks The RTC bus clock (CLK_RTC_APB) can be enabled and disabled in the Main Clock module MCLK, and the default state of CLK_RTC_APB can be found in Peripheral Clock Masking section. A 32KHz or 1KHz oscillator clock (CLK_RTC_OSC) is required to clock the RTC. This clock must be configured and enabled in the 32KHz oscillator controller (OSC32KCTRL) before using the RTC. This oscillator clock is asynchronous to the bus clock (CLK_RTC_APB). Due to this asynchronicity, writing to certain registers will require synchronization between the clock domains. Refer to 27.6.7 Synchronization for further details. Related Links 24. OSC32KCTRL – 32KHz Oscillators Controller 19.6.2.6 Peripheral Clock Masking 27.5.4 DMA The DMA request lines (or line if only one request) are connected to the DMA Controller (DMAC). Using the RTC DMA requests requires the DMA Controller to be configured first. Related Links 28. DMAC – Direct Memory Access Controller 27.5.5 Interrupts The interrupt request line is connected to the Interrupt Controller. Using the RTC interrupt requires the Interrupt Controller to be configured first. 27.5.6 Events The events are connected to the Event System. Related Links 33. EVSYS – Event System 27.5.7 Debug Operation When the CPU is halted in debug mode the RTC will halt normal operation. The RTC can be forced to continue operation during debugging. Refer to 27.8.7 DBGCTRL for details. 27.5.8 Register Access Protection All registers with write-access are optionally write-protected by the peripheral access controller (PAC), except the following registers: • Interrupt Flag Status and Clear (INTFLAG) register Write-protection is denoted by the "PAC Write-Protection" property in the register description. Write-protection does not apply to accesses through an external debugger. Refer to the PAC - Peripheral Access Controller for details. Related Links SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 389 15. PAC - Peripheral Access Controller 27.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 27.5.10 Analog Connections A 32.768kHz crystal can be connected to the XIN32 and XOUT32 pins, along with any required load capacitors. See the Electrical Characteristics Chapters for details on recommended crystal characteristics and load capacitors. 27.6 Functional Description 27.6.1 Principle of Operation The RTC keeps track of time in the system and enables periodic events, as well as interrupts and events at a specified time. The RTC consists of a 10-bit prescaler that feeds a 32-bit counter. The actual format of the 32-bit counter depends on the RTC operating mode. The RTC can function in one of these modes: • Mode 0 - COUNT32: RTC serves as 32-bit counter • Mode 1 - COUNT16: RTC serves as 16-bit counter • Mode 2 - CLOCK: RTC serves as clock/calendar with alarm functionality 27.6.2 Basic Operation 27.6.2.1 Initialization The following bits are enable-protected, meaning that they can only be written when the RTC is disabled (CTRLA.ENABLE=0): • Operating Mode bits in the Control A register (CTRLA.MODE) • Prescaler bits in the Control A register (CTRLA.PRESCALER) • Clear on Match bit in the Control A register (CTRLA.MATCHCLR) • Clock Representation bit in the Control A register (CTRLA.CLKREP) The following registers are enable-protected: • Control B register (CTRLB) • Event Control register (EVCTRL) • Tamper Control register (TAMPCTRL) • Tamper Control B register (TAMPCTRLB) Enable-protected bits and registers can be changed only when the RTC is disabled (CTRLA.ENABLE=0). If the RTC is enabled (CTRLA.ENABLE=1), these operations are necessary: first write SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 390 CTRLA.ENABLE=0 and check whether the write synchronization has finished, then change the desired bit field value. Enable-protected bits in CTRLA register can be written at the same time as CTRLA.ENABLE is written to '1', but not at the same time as CTRLA.ENABLE is written to '0'. Enable-protection is denoted by the "Enable-Protected" property in the register description. The RTC prescaler divides the source clock for the RTC counter. Note:  In Clock/Calendar mode, the prescaler must be configured to provide a 1Hz clock to the counter for correct operation. The frequency of the RTC clock (CLK_RTC_CNT) is given by the following formula: ݂CLK_RTC_CNT = ݂CLK_RTC_OSC 2 PRESCALER The frequency of the oscillator clock, CLK_RTC_OSC, is given by fCLK_RTC_OSC, and fCLK_RTC_CNT is the frequency of the internal prescaled RTC clock, CLK_RTC_CNT. 27.6.2.2 Enabling, Disabling, and Resetting The RTC is enabled by setting the Enable bit in the Control A register (CTRLA.ENABLE=1). The RTC is disabled by writing CTRLA.ENABLE=0. The RTC is reset by setting the Software Reset bit in the Control A register (CTRLA.SWRST=1). All registers in the RTC, except DEBUG, will be reset to their initial state, and the RTC will be disabled. The RTC must be disabled before resetting it. 27.6.2.3 32-Bit Counter (Mode 0) When the RTC Operating Mode bits in the Control A register (CTRLA.MODE) are written to 0x0, the counter operates in 32-bit Counter mode. The block diagram of this mode is shown in Figure 27-1. When the RTC is enabled, the counter will increment on every 0-to-1 transition of CLK_RTC_CNT. The counter will increment until it reaches the top value of 0xFFFFFFFF, and then wrap to 0x00000000. This sets the Overflow Interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG.OVF). The RTC counter value can be read from or written to the Counter Value register (COUNT) in 32-bit format. The counter value is continuously compared with the 32-bit Compare register (COMP0). When a compare match occurs, the Compare 0 Interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG.CMP0) is set on the next 0-to-1 transition of CLK_RTC_CNT. If the Clear on Match bit in the Control A register (CTRLA.MATCHCLR) is '1', the counter is cleared on the next counter cycle when a compare match with COMP0 occurs. This allows the RTC to generate periodic interrupts or events with longer periods than the prescaler events. Note that when CTRLA.MATCHCLR is '1', INTFLAG.CMP0 and INTFLAG.OVF will both be set simultaneously on a compare match with COMP0. 27.6.2.4 16-Bit Counter (Mode 1) When the RTC Operating Mode bits in the Control A register (CTRLA.MODE) are written to 0x1, the counter operates in 16-bit Counter mode as shown in Figure 27-2. When the RTC is enabled, the counter will increment on every 0-to-1 transition of CLK_RTC_CNT. In 16-bit Counter mode, the 16-bit Period register (PER) holds the maximum value of the counter. The counter will increment until it reaches the PER value, and then wrap to 0x0000. This sets the Overflow Interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG.OVF). The RTC counter value can be read from or written to the Counter Value register (COUNT) in 16-bit format. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 391 The counter value is continuously compared with the 16-bit Compare registers (COMPn, n=0..1). When a compare match occurs, the Compare n Interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG.CMPn, n=0..1) is set on the next 0-to-1 transition of CLK_RTC_CNT. 27.6.2.5 Clock/Calendar (Mode 2) When the RTC Operating Mode bits in the Control A register (CTRLA.MODE) are written to 0x2, the counter operates in Clock/Calendar mode, as shown in Figure 27-3. When the RTC is enabled, the counter will increment on every 0-to-1 transition of CLK_RTC_CNT. The selected clock source and RTC prescaler must be configured to provide a 1Hz clock to the counter for correct operation in this mode. The time and date can be read from or written to the Clock Value register (CLOCK) in a 32-bit time/date format. Time is represented as: • Seconds • Minutes • Hours Hours can be represented in either 12- or 24-hour format, selected by the Clock Representation bit in the Control A register (CTRLA.CLKREP). This bit can be changed only while the RTC is disabled. The date is represented in this form: • Day as the numeric day of the month (starting at 1) • Month as the numeric month of the year (1 = January, 2 = February, etc.) • Year as a value from 0x00 to 0x3F. This value must be added to a user-defined reference year. The reference year must be a leap year (2016, 2020 etc). Example: the year value 0x2D, added to a reference year 2016, represents the year 2061. The RTC will increment until it reaches the top value of 23:59:59 December 31 of year value 0x3F, and then wrap to 00:00:00 January 1 of year value 0x00. This will set the Overflow Interrupt flag in the Interrupt Flag Status and Clear registers (INTFLAG.OVF). The clock value is continuously compared with the 32-bit Alarm register (ALARM0). When an alarm match occurs, the Alarm 0 Interrupt flag in the Interrupt Flag Status and Clear registers (INTFLAG.ALARM0) is set on the next 0-to-1 transition of CLK_RTC_CNT. E.g. For a 1Hz clock counter, it means the Alarm 0 Interrupt flag is set with a delay of 1s after the occurrence of alarm match. A valid alarm match depends on the setting of the Alarm Mask Selection bits in the Alarm 0 Mask register (MASK0.SEL). These bits determine which time/date fields of the clock and alarm values are valid for comparison and which are ignored. If the Clear on Match bit in the Control A register (CTRLA.MATCHCLR) is set, the counter is cleared on the next counter cycle when an alarm match with ALARM0 occurs. This allows the RTC to generate periodic interrupts or events with longer periods than it would be possible with the prescaler events only (see 27.6.8.1 Periodic Intervals). Note:  When CTRLA.MATCHCLR is 1, INTFLAG.ALARM0 and INTFLAG.OVF will both be set simultaneously on an alarm match with ALARM0. 27.6.3 DMA Operation The RTC generates the following DMA request: • Tamper (TAMPER): The request is set on capture of the timestamp. The request is cleared when the Timestamp register is read. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 392 If the CPU accesses the registers which are source for DMA request set/clear condition, the DMA request can be lost or the DMA transfer can be corrupted, if enabled. 27.6.4 Interrupts The RTC has the following interrupt sources: • Overflow (OVF): Indicates that the counter has reached its top value and wrapped to zero. • Tamper (TAMPER): Indicates detection of valid signal on a tamper input pin or tamper event input. • Compare (CMPn): Indicates a match between the counter value and the compare register. • Alarm (ALARMn): Indicates a match between the clock value and the alarm register. • Period n (PERn): The corresponding bit in the prescaler has toggled. Refer to 27.6.8.1 Periodic Intervals for details. Each interrupt source has an interrupt flag associated with it. The interrupt flag in the Interrupt Flag Status and Clear (INTFLAG) register is set when the interrupt condition occurs. Each interrupt can be individually enabled by setting the corresponding bit in the Interrupt Enable Set register (INTENSET=1), and disabled by setting the corresponding bit in the Interrupt Enable Clear register (INTENCLR=1). An interrupt request is generated when the interrupt flag is raised and the corresponding interrupt is enabled. The interrupt request remains active until either the interrupt flag is cleared, the interrupt is disabled or the RTC is reset. See the description of the INTFLAG registers for details on how to clear interrupt flags. All interrupt requests from the peripheral are ORed together on system level to generate one combined interrupt request to the NVIC. Refer to the Nested Vector Interrupt Controller for details. The user must read the INTFLAG register to determine which interrupt condition is present. Note:  Interrupts must be globally enabled for interrupt requests to be generated. Refer to the Nested Vector Interrupt Controller for details. 27.6.5 Events The RTC can generate the following output events: • Overflow (OVF): Generated when the counter has reached its top value and wrapped to zero. • Tamper (TAMPER): Generated on detection of valid signal on a tamper input pin or tamper event input. • Compare (CMPn): Indicates a match between the counter value and the compare register. • Alarm (ALARM): Indicates a match between the clock value and the alarm register. • Period n (PERn): The corresponding bit in the prescaler has toggled. Refer to 27.6.8.1 Periodic Intervals for details. • Periodic Daily (PERD): Generated when the COUNT/CLOCK has incremented at a fixed period of time. Setting the Event Output bit in the Event Control Register (EVCTRL.xxxEO=1) enables the corresponding output event. Writing a zero to this bit disables the corresponding output event. Refer to the EVSYS - Event System for details on configuring the event system. The RTC can take the following actions on an input event: • Tamper (TAMPEVT): Capture the RTC counter to the timestamp register. See Tamper Detection. Writing a one to an Event Input bit into the Event Control register (EVCTRL.xxxEI) enables the corresponding action on input event. Writing a zero to this bit disables the corresponding action on input event. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 393 Related Links 33. EVSYS – Event System 27.6.6 Sleep Mode Operation The RTC will continue to operate in any sleep mode where the source clock is active. The RTC interrupts can be used to wake up the device from a sleep mode. RTC events can trigger other operations in the system without exiting the sleep mode. An interrupt request will be generated after the wake-up if the Interrupt Controller is configured accordingly. Otherwise the CPU will wake up directly, without triggering any interrupt. In this case, the CPU will continue executing right from the first instruction that followed the entry into sleep. The periodic events can also wake up the CPU through the interrupt function of the Event System. In this case, the event must be enabled and connected to an event channel with its interrupt enabled. See Event System for more information. 27.6.7 Synchronization Due to asynchronicity between the main clock domain and the peripheral clock domains, some registers need to be synchronized when written or read. The following bits are synchronized when written: • Software Reset bit in Control A register, CTRLA.SWRST • Enable bit in Control A register, CTRLA.ENABLE • Count Read Synchronization bit in Control A register (CTRLA.COUNTSYNC) • Clock Read Synchronization bit in Control A register (CTRLA.COUNTSYNC) The following registers are synchronized when written: • Counter Value register, COUNT • Clock Value register, CLOCK • Counter Period register, PER • Compare n Value registers, COMPn • Alarm n Value registers, ALARMn • Frequency Correction register, FREQCORR • Alarm n Mask register, MASKn • The General Purpose n registers (GPn) The following registers are synchronized when read: • The Counter Value register, COUNT, if the Counter Read Sync Enable bit in CTRLA (CTRLA.COUNTSYNC) is '1' • The Clock Value register, CLOCK, if the Clock Read Sync Enable bit in CTRLA (CTRLA.CLOCKSYNC) is '1' • The Timestamp Value register (TIMESTAMP) Required write-synchronization is denoted by the "Write-Synchronized" property in the register description. Required read-synchronization is denoted by the "Read-Synchronized" property in the register description. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 394 27.6.8 Additional Features 27.6.8.1 Periodic Intervals The RTC prescaler can generate interrupts and events at periodic intervals, allowing flexible system tick creation. Any of the upper eight bits of the prescaler (bits 2 to 9) can be the source of an interrupt/event. When one of the eight Periodic Event Output bits in the Event Control register (EVCTRL.PEREO[n=0..7]) is '1', an event is generated on the 0-to-1 transition of the related bit in the prescaler, resulting in a periodic event frequency of: ݂PERIODIC(n) = ݂CLK_RTC_OSC 2 n+3 fCLK_RTC_OSC is the frequency of the internal prescaler clock CLK_RTC_OSC, and n is the position of the EVCTRL.PEREOn bit. For example, PER0 will generate an event every eight CLK_RTC_OSC cycles, PER1 every 16 cycles, etc. This is shown in the figure below. Periodic events are independent of the prescaler setting used by the RTC counter, except if CTRLA.PRESCALER is zero. Then, no periodic events will be generated. Figure 27-5. Example Periodic Events CLK_RTC_OSC PER0 PER1 PER2 PER3 27.6.8.2 Frequency Correction The RTC Frequency Correction module employs periodic counter corrections to compensate for a tooslow or too-fast oscillator. Frequency correction requires that CTRLA.PRESCALER is greater than 1. The digital correction circuit adds or subtracts cycles from the RTC prescaler to adjust the frequency in approximately 1ppm steps. Digital correction is achieved by adding or skipping a single count in the prescaler once every 8192 CLK_RTC_OSC cycles. The Value bit group in the Frequency Correction register (FREQCORR.VALUE) determines the number of times the adjustment is applied over 128 of these periods. The resulting correction is as follows: Correction in ppm = FREQCORR.VALUE 8192 ڄ 128 ڄ 106 ppm This results in a resolution of 0.95367ppm. The Sign bit in the Frequency Correction register (FREQCORR.SIGN) determines the direction of the correction. A positive value will add counts and increase the period (reducing the frequency), and a negative value will reduce counts per period (speeding up the frequency). Digital correction also affects the generation of the periodic events from the prescaler. When the correction is applied at the end of the correction cycle period, the interval between the previous periodic event and the next occurrence may also be shortened or lengthened depending on the correction value. 27.6.8.3 General Purpose Registers The RTC includes four General Purpose registers (GPn). These registers are reset only when the RTC is reset or when tamper detection occurs while CTRLA.GPTRST=1, and remain powered while the RTC is powered. They can be used to store user-defined values while other parts of the system are powered off. The general purpose registers 2*n and 2*n+1 are enabled by writing a '1' to the General Purpose Enable bit n in the Control B register (CTRLB.GPnEN). SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 395 The GP registers share internal resources with the COMPARE/ALARM features. Each COMPARE/ ALARM register have a separate read buffer and write buffer. When the general purpose feature is enabled the even GP uses the read buffer while the odd GP uses the write buffer. When the COMPARE/ALARM register is written, the write buffer hold temporarily the COMPARE/ALARM value until the synchronisation is complete (bit SYNCBUSY.COMPn going to 0). After the write is completed the write buffer can be used as a odd general purpose register whithout affecting the COMPARE/ALARM function. If the COMPARE/ALARM function is not used, the read buffer can be used as an even general purpose register. In this case writing the even GP will temporarirely use the write buffer until the synchronisation is complete (bit SYNCBUSY.GPn going to 0). Thus an even GP must be written before writing the odd GP. Changing or writing an even GP needs to temporarily save the value of the odd GP. Before using an even GP, the associated COMPARE/ALARM feature must be disabled by writing a '1' to the General Purpose Enable bit in the Control B register (CTRLB.GPnEN). To re-enable the compare/ alarm, CTRLB.GPnEN must be written to zero and the associated COMPn/ALARMn must be written with the correct value. An example procedure to write the general purpose registers GP0 and GP1 is: 1. Wait for any ongoing write to COMP0 to complete (SYNCBUSY.COMP0 = 0). If the RTC is operating in Mode 1, wait for any ongoing write to COMP1 to complete as well (SYNCBUSY.COMP1 = 0). 2. Write CTRLB.GP0EN = 1 if GP0 is needed. 3. Write GP0 if needed. 4. Wait for any ongoing write to GP0 to complete (SYNCBUSY.GP0 = 0). Note that GP1 will also show as busy when GP0 is busy. 5. Write GP1 if needed. The following table provides the correspondence of General Purpose Registers and the COMPARE/ ALARM read or write buffer in all RTC modes. Table 27-2. General Purpose Registers Versus Compare/Alarm Registers: n in 0, 2, 4, 6... Register Mode 0 Mode 1 Mode 2 Write Before GPn COMPn/2 write buffer (COMPn , COMPn +1) write buffer ALARMn/2 write buffer GPn+1 GPn+1 COMPn/2 read buffer (COMPn , COMPn +1) read buffer ALARMn/2 read buffer - 27.6.8.4 Tamper Detection The RTC provides four tamper channels that can be used for tamper detection. The action of each tamper channel is configured using the Input n Action bits in the Tamper Control register (TAMPCTRL.INnACT): • Off: Detection for tamper channel n is disabled. • Wake: A transition on INn input (tamper channel n) matching TAMPCTRL.TAMPLVLn will be detected and the tamper interrupt flag (INTFLAG.TAMPER) will be set. The RTC value will not be captured in the TIMESTAMP register. • Capture: A transition on INn input (tamper channel n) matching TAMPCTRL.TAMPLVLn will be detected and the tamper interrupt flag (INTFLAG.TAMPER) will be set. The RTC value will be captured in the TIMESTAMP register. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 396 • Active Layer Protection: A mismatch of an internal RTC signal routed between INn and OUTn pins will be detected and the tamper interrupt flag (INTFLAG.TAMPER) will be set. The RTC value will be captured in the TIMESTAMP register. In order to determine which tamper source caused a tamper event, the Tamper ID register (TAMPID) provides the detection status of each tamper channel. These bits remain active until cleared by software. A single interrupt request (TAMPER) is available for all tamper channels. The RTC also supports an input event (TAMPEVT) for generating a tamper condition within the Event System. The tamper input event is enabled by the Tamper Input Event Enable bit in the Event Control register (EVCTRL.TAMPEVEI). Up to four polarity external inputs (INn) can be used for tamper detection. The polarity for each input is selected with the Tamper Level bits in the Tamper Control register (TAMPCTRL.TAMPLVLn). Separate debouncers are embedded for each external input. The debouncer for each input is enabled/ disabled with the Debounce Enable bits in the Tamper Control register (TAMPCTRL.DEBNCn). The debouncer configuration is fixed for all inputs as set by the Control B register (CTRLB). The debouncing period duration is configurable using the Debounce Frequency field in the Control B register (CTRLB.DEBF). The period is set for all debouncers (i.e., the duration cannot be adjusted separately for each debouncer). When TAMPCTRL.DEBNCn = 0, INn is detected asynchronously. See Figure 27-6 for an example. When TAMPCTRL.DEBNCn = 1, the detection time depends on whether the debouncer operates synchronously or asynchronously, and whether majority detection is enabled or not. Refer to the table below for more details. Synchronous versus asynchronous stability debouncing is configured by the Debounce Asynchronous Enable bit in the Control B register (CTRLB.DEBASYNC): • Synchronous (CTRLB.DEBASYNC = 0): INn is synchronized in two CLK_RTC periods and then must remain stable for four CLK_RTC_DEB periods before a valid detection occurs. See Figure 27-7 for an example. • Asynchronous (CTRLB.DEBASYNC = 1): The first edge on INn is detected. Further detection is blanked until INn remains stable for four CLK_RTC_DEB periods. See Figure 27-8 for an example. Majority debouncing is configured by the Debounce Majority Enable bit in the Control B register (CTRLB.DEBMAJ). INn must be valid for two out of three CLK_RTC_DEB periods. See Figure 27-9 for an example. Table 27-3. Debouncer Configuration TAMPCTRL. DEBNCn CTRLB. DEBMAJ CTRLB. DEBASYNC Description 0 X X Detect edge on INn with no debouncing. Every edge detected is immediately triggered. 1 0 0 Detect edge on INn with synchronous stability debouncing. Edge detected is only triggered when INn is stable for 4 consecutive CLK_RTC_DEB periods. 1 0 1 Detect edge on INn with asynchronous stability debouncing. First detected edge is triggered immediately. All subsequent detected edges are SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 397 TAMPCTRL. DEBNCn CTRLB. DEBMAJ CTRLB. DEBASYNC Description ignored until INn is stable for 4 consecutive CLK_RTC_DEB periods. 1 1 X Detect edge on INn with majority debouncing. Pin INn is sampled for 3 consecutive CLK_RTC_DEB periods. Signal level is determined by majority-rule (LLL, LLH, LHL, HLL = '0' and LHH, HLH, HHL, HHH = '1'). Figure 27-6. Edge Detection with Debouncer Disabled CLK_RTC CLK_RTC_DEB IN OUT NE NE PE TAMLVL=0 CLK_RTC CLK_RTC_DEB IN OUT NE NE PE TAMLVL=1 PE NE PE PE NE PE Figure 27-7. Edge Detection with Synchronous Stability Debouncing OUT TAMLVL=0 CLK_RTC CLK_RTC_DEB IN OUT NE NE PE TAMLVL=1 PE NE PE Whenever an edge is detected, input must be stable for 4 consecutive CLK_RTC_DEB in order for edge to be considered valid CLK_RTC CLK_RTC_DEB IN NE NE PEPE NE PE Whenever an edge is detected, input must be stable for 4 consecutive CLK_RTC_DEB in order for edge to be considered valid SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 398 Figure 27-8. Edge Detection with Asynchronous Stability Debouncing CLK_RTC CLK_RTC_DEB IN OUT Once a new edge is detected, ignore subsequent edges until input is stable for 4 consecutive CLK_RTC_DEB NE NE PE TAMLVL=0 CLK_RTC CLK_RTC_DEB IN OUT Once a new edge is detected, ignore subsequent edges until input is stable for 4 consecutive CLK_RTC_DEB NE NE PE TAMLVL=1 PE NE PE PE NE PE Figure 27-9. Edge Detection with Majority Debouncing CLK_RTC CLK_RTC_DEB IN IN shift 0 IN shift 1 IN shift 2 MAJORITY3 OUT CLK_RTC CLK_RTC_DEB IN IN shift 0 IN shift 1 IN shift 2 MAJORITY3 OUT 11 1 0 0 0 TAMLVL=1 TAMLVL=0 0-to-1 transition 1-to-0 transition NE NE PEPE NE PE 0 0 0 11 1 11 1 11 1 0 0 0 NE NE PEPE NE PE 0 0 0 11 1 11 1 SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 399 Related Links 27.3 Block Diagram 27.6.8.4.1 Timestamp 27.6.8.4.2 Active Layer Protection 27.6.8.4.1 Timestamp As part of tamper detection the RTC can capture the counter value (COUNT/CLOCK) into the TIMESTAMP register. Three CLK_RTC periods are required to detect the tampering condition and capture the value. The TIMESTAMP value can be read once the Tamper flag in the Interrupt Flag register (INTFLAG.TAMPER) is set. If the DMA Enable bit in the Control B register (CTRLB.DMAEN) is ‘1’, a DMA request will be triggered by the timestamp. In order to determine which tamper source caused a capture, the Tamper ID register (TAMPID) provides the detection status of each tamper channel and the tamper input event. A DMA transfer can then read both TIMESTAMP and TAMPID in succession. A new timestamp value cannot be captured until the Tamper flag is cleared, either by reading the timestamp or by writing a ‘1’ to INTFLAG.TAMPER. If several tamper conditions occur in a short window before the flag is cleared, only the first timestamp may be logged. However, the detection of each tamper will still be recorded in TAMPID. The Tamper Input Event (TAMPEVT) will always perform a timestamp capture. To capture on the external inputs (INn), the corresponding Input Action field in the Tamper Control register (TAMPCTRL.INnACT) must be written to ‘1’. If an input is set for wake functionality it does not capture the timestamp; however the Tamper flag and TAMPID will still be updated. Related Links 27.6.8.4 Tamper Detection 27.6.8.4.2 Active Layer Protection The RTC provides a mean of detecting broken traces on the PCB , also known as Active layer Protection. In this mode, a generated internal RTC signal can be directly routed over critical components on the board using RTC OUT output pin to one RTC INn input pin. A tamper condition is detected if there is a mismatch on the generated RTC signal. The Active Layer Protection mode and the generation of the RTC signal is enabled by setting the RTCOUT bit in the Control B register (CTRLB.RTCOUT). Enabling active layer protection requires the following steps: • Enable the RTC prescaler output by writing a one to the RTC Out bit in the Control B register (CTRLB.RTCOUT). The I/O pins must also be configured to correctly route the signal to the external pins. • Select the frequency of the output signal by configuring the RTC Active Layer Frequency field in the Control B register (CTRLB.ACTF). GCLK_RTC_OUT = CLK_RTC 2 CTRLB.ACTF +1 • Enable the tamper input n (INn) in active layer mode by writing 3 to the corresponding Input Action field in the Tamper Control register (TAMPCTRL.INnACT). When active layer protection is enabled and INn and OUTn pin are used, the value of INn is sampled on the falling edge of CLK_RTC and compared to the expected value of OUTn. Therefore up to one half of a CLK_RTC period is available for propagation delay through the trace. • Enable Acitive Layer Protection by setting CTRLB.RTCOUT bit. Related Links SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 400 27.6.8.4 Tamper Detection SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 401 27.7 Register Summary - Mode 0 - 32-Bit Counter Offset Name Bit Pos. 0x00 CTRLA 7:0 MATCHCLR MODE[1:0] ENABLE SWRST 15:8 COUNTSYNC GPTRST PRESCALER[3:0] 0x02 CTRLB 7:0 DMAEN RTCOUT DEBASYNC DEBMAJ GP0EN 15:8 SEPTO ACTF[2:0] DEBF[2:0] 0x04 EVCTRL 7:0 PEREO7 PEREO6 PEREO5 PEREO4 PEREO3 PEREO2 PEREO1 PEREO0 15:8 OVFEO TAMPEREO CMPEO0 23:16 TAMPEVEI 31:24 PERDEO 0x08 INTENCLR 7:0 PER7 PER6 PER5 PER4 PER3 PER2 PER1 PER0 15:8 OVF TAMPER CMP0 0x0A INTENSET 7:0 PER7 PER6 PER5 PER4 PER3 PER2 PER1 PER0 15:8 OVF TAMPER CMP0 0x0C INTFLAG 7:0 PER7 PER6 PER5 PER4 PER3 PER2 PER1 PER0 15:8 OVF TAMPER CMP0 0x0E DBGCTRL 7:0 DBGRUN 0x0F Reserved 0x10 SYNCBUSY 7:0 COMP0 COUNT FREQCORR ENABLE SWRST 15:8 COUNTSYNC 23:16 GPn[1:0] 31:24 0x14 FREQCORR 7:0 SIGN VALUE[6:0] 0x15 ... 0x17 Reserved 0x18 COUNT 7:0 COUNT[7:0] 15:8 COUNT[15:8] 23:16 COUNT[23:16] 31:24 COUNT[31:24] 0x1C ... 0x1F Reserved 0x20 COMP 7:0 COMP[7:0] 15:8 COMP[15:8] 23:16 COMP[23:16] 31:24 COMP[31:24] 0x24 ... 0x3F Reserved 0x40 GP0 7:0 GP[7:0] 15:8 GP[15:8] 23:16 GP[23:16] 31:24 GP[31:24] 0x44 GP1 7:0 GP[7:0] SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 402 Offset Name Bit Pos. 15:8 GP[15:8] 23:16 GP[23:16] 31:24 GP[31:24] 0x48 ... 0x5F Reserved 0x60 TAMPCTRL 7:0 IN3ACT[1:0] IN2ACT[1:0] IN1ACT[1:0] IN0ACT[1:0] 15:8 23:16 TAMLVL3 TAMLVL2 TAMLVL1 TAMLVL0 31:24 DEBNC3 DEBNC2 DEBNC1 DEBNC0 0x64 TIMESTAMP 7:0 COUNT[7:0] 15:8 COUNT[15:8] 23:16 COUNT[23:16] 31:24 COUNT[31:24] 0x68 TAMPID 7:0 TAMPID3 TAMPID2 TAMPID1 TAMPID0 15:8 23:16 31:24 TAMPEVT 0x6C TAMPCTRLB 7:0 ALSI3 ALSI2 ALSI1 ALSI0 15:8 23:16 31:24 27.8 Register Description - Mode 0 - 32-Bit Counter This Register Description section is valid if the RTC is in COUNT32 mode (CTRLA.MODE=0). Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16-, and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers require synchronization when read and/or written. Synchronization is denoted by the "Read-Synchronized" and/or "Write-Synchronized" property in each individual register description. Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. Some registers are enable-protected, meaning they can only be written when the module is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 403 27.8.1 Control A in COUNT32 mode (CTRLA.MODE=0) Name:  CTRLA Offset:  0x00 Reset:  0x0000 Property:  PAC Write-Protection, Enable-Protected, Write-Synchronized Bit 15 14 13 12 11 10 9 8 COUNTSYNC GPTRST PRESCALER[3:0] Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 MATCHCLR MODE[1:0] ENABLE SWRST Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 15 – COUNTSYNC COUNT Read Synchronization Enable The COUNT register requires synchronization when reading. Disabling the synchronization will prevent reading valid values from the COUNT register. This bit is not enable-protected. Value Description 0 COUNT read synchronization is disabled 1 COUNT read synchronization is enabled Bit 14 – GPTRST GP Registers Reset On Tamper Enable Only GP registers enabled by the CTRLB.GPnEN bits are affected. This bit can be written only when the peripheral is disabled. This bit is not synchronized. Bits 11:8 – PRESCALER[3:0] Prescaler These bits define the prescaling factor for the RTC clock source (GCLK_RTC) to generate the counter clock (CLK_RTC_CNT). Periodic events and interrupts are not available when the prescaler is off. These bits are not synchronized. Value Name Description 0x0 OFF CLK_RTC_CNT = GCLK_RTC/1 0x1 DIV1 CLK_RTC_CNT = GCLK_RTC/1 0x2 DIV2 CLK_RTC_CNT = GCLK_RTC/2 0x3 DIV4 CLK_RTC_CNT = GCLK_RTC/4 0x4 DIV8 CLK_RTC_CNT = GCLK_RTC/8 0x5 DIV16 CLK_RTC_CNT = GCLK_RTC/16 0x6 DIV32 CLK_RTC_CNT = GCLK_RTC/32 0x7 DIV64 CLK_RTC_CNT = GCLK_RTC/64 0x8 DIV128 CLK_RTC_CNT = GCLK_RTC/128 0x9 DIV256 CLK_RTC_CNT = GCLK_RTC/256 0xA DIV512 CLK_RTC_CNT = GCLK_RTC/512 SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 404 Value Name Description 0xB DIV1024 CLK_RTC_CNT = GCLK_RTC/1024 0xC-0xF - Reserved Bit 7 – MATCHCLR Clear on Match This bit defines if the counter is cleared or not on a match. This bit is not synchronized. Value Description 0 The counter is not cleared on a Compare/Alarm 0 match 1 The counter is cleared on a Compare/Alarm 0 match Bits 3:2 – MODE[1:0] Operating Mode This bit group defines the operating mode of the RTC. This bit is not synchronized. Value Name Description 0x0 COUNT32 Mode 0: 32-bit counter 0x1 COUNT16 Mode 1: 16-bit counter 0x2 CLOCK Mode 2: Clock/calendar 0x3 - Reserved Bit 1 – ENABLE Enable Due to synchronization there is a delay between writing CTRLA.ENABLE and until the peripheral is enabled/disabled. The value written to CTRLA.ENABLE will read back immediately and the Enable bit in the Synchronization Busy register (SYNCBUSY.ENABLE) will be set. SYNCBUSY.ENABLE will be cleared when the operation is complete. Value Description 0 The peripheral is disabled 1 The peripheral is enabled Bit 0 – SWRST Software Reset Writing a '0' to this bit has no effect. Writing a '1' to this bit resets all registers in the RTC (except DBGCTRL) to their initial state, and the RTC will be disabled. Writing a '1' to CTRLA.SWRST will always take precedence, meaning that all other writes in the same write-operation will be discarded. Due to synchronization there is a delay between writing CTRLA.SWRST and until the reset is complete. CTRLA.SWRST will be cleared when the reset is complete. Value Description 0 There is not reset operation ongoing 1 The reset operation is ongoing SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 405 27.8.2 Control B in COUNT32 mode (CTRLA.MODE=0) Name:  CTRLB Offset:  0x02 Reset:  0x0000 Property:  PAC Write-Protection, Enable-Protected Bit 15 14 13 12 11 10 9 8 SEPTO ACTF[2:0] DEBF[2:0] Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DMAEN RTCOUT DEBASYNC DEBMAJ GP0EN Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 15 – SEPTO Separate Tamper Outputs Value Description 0 IN[n] is compared to OUT[0]. 1 IN[n] is compared to OUT[n]. Bits 14:12 – ACTF[2:0] Active Layer Frequency These bits define the prescaling factor for the RTC clock output (OUT) used during active layer protection in terms of the CLK_RTC. Value Name Description 0x0 DIV2 CLK_RTC_OUT = CLK_RTC / 2 0x1 DIV4 CLK_RTC_OUT = CLK_RTC / 4 0x2 DIV8 CLK_RTC_OUT = CLK_RTC / 8 0x3 DIV16 CLK_RTC_OUT = CLK_RTC / 16 0x4 DIV32 CLK_RTC_OUT = CLK_RTC / 32 0x5 DIV64 CLK_RTC_OUT = CLK_RTC / 64 0x6 DIV128 CLK_RTC_OUT = CLK_RTC / 128 0x7 DIV256 CLK_RTC_OUT = CLK_RTC / 256 Bits 10:8 – DEBF[2:0] Debounce Frequency These bits define the prescaling factor for the input debouncers in terms of the CLK_RTC. Value Name Description 0x0 DIV2 CLK_RTC_DEB = CLK_RTC / 2 0x1 DIV4 CLK_RTC_DEB = CLK_RTC / 4 0x2 DIV8 CLK_RTC_DEB = CLK_RTC / 8 0x3 DIV16 CLK_RTC_DEB = CLK_RTC / 16 0x4 DIV32 CLK_RTC_DEB = CLK_RTC / 32 0x5 DIV64 CLK_RTC_DEB = CLK_RTC / 64 0x6 DIV128 CLK_RTC_DEB = CLK_RTC / 128 0x7 DIV256 CLK_RTC_DEB = CLK_RTC / 256 SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 406 Bit 7 – DMAEN DMA Enable The RTC can trigger a DMA request when the timestamp is ready in the TIMESTAMP register. Value Description 0 Tamper DMA request is disabled. Reading TIMESTAMP has no effect on INTFLAG.TAMPER. 1 Tamper DMA request is enabled. Reading TIMESTAMP will clear INTFLAG.TAMPER. Bit 6 – RTCOUT RTC Output Enable Value Description 0 The RTC active layer output is disabled. 1 The RTC active layer output is enabled. Bit 5 – DEBASYNC Debouncer Asynchronous Enable Value Description 0 The tamper input debouncers operate synchronously. 1 The tamper input debouncers operate asynchronously. Bit 4 – DEBMAJ Debouncer Majority Enable Value Description 0 The tamper input debouncers match three equal values. 1 The tamper input debouncers match majority two of three values. Bit 0 – GP0EN General Purpose 0 Enable Value Description 0 COMP0 compare function enabled. GP0/GP1 disabled. 1 COMP0 compare function disabled. GP0/GP1 enabled. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 407 27.8.3 Event Control in COUNT32 mode (CTRLA.MODE=0) Name:  EVCTRL Offset:  0x04 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 PERDEO Access R/W Reset 0 Bit 23 22 21 20 19 18 17 16 TAMPEVEI Access R/W Reset 0 Bit 15 14 13 12 11 10 9 8 OVFEO TAMPEREO CMPEO0 Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 PEREO7 PEREO6 PEREO5 PEREO4 PEREO3 PEREO2 PEREO1 PEREO0 Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 24 – PERDEO Periodic Interval Daily Event Output Enable Value Description 0 Periodic Daily event is disabled and will not be generated. 1 Periodic Daily event is enabled and will be generated. The event occurs at the overflow of the RTC counter (i.e., when the RTC counter goes from 0xFFFF to 0x0000). Bit 16 – TAMPEVEI Tamper Event Input Enable Value Description 0 Tamper event input is disabled and incoming events will be ignored. 1 Tamper event input is enabled and incoming events will capture the COUNT value. Bit 15 – OVFEO Overflow Event Output Enable Value Description 0 Overflow event is disabled and will not be generated. 1 Overflow event is enabled and will be generated for every overflow. Bit 14 – TAMPEREO Tamper Event Output Enable SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 408 Value Description 0 Tamper event output is disabled and will not be generated. 1 Tamper event output is enabled and will be generated for every tamper input. Bit 8 – CMPEO0 Compare 0 Event Output Enable Value Description 0 Compare 0 event is disabled and will not be generated. 1 Compare 0 event is enabled and will be generated for every compare match. Bits 0, 1, 2, 3, 4, 5, 6, 7 – PEREOn Periodic Interval n Event Output Enable [n = 7..0] Value Description 0 Periodic Interval n event is disabled and will not be generated. 1 Periodic Interval n event is enabled and will be generated. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 409 27.8.4 Interrupt Enable Clear in COUNT32 mode (CTRLA.MODE=0) Name:  INTENCLR Offset:  0x08 Reset:  0x0000 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set (INTENSET) register. Bit 15 14 13 12 11 10 9 8 OVF TAMPER CMP0 Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 PER7 PER6 PER5 PER4 PER3 PER2 PER1 PER0 Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 – OVF Overflow Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Overflow Interrupt Enable bit, which disables the Overflow interrupt. Value Description 0 The Overflow interrupt is disabled. 1 The Overflow interrupt is enabled. Bit 14 – TAMPER Tamper Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this but will clear the Tamper Interrupt Enable bit, which disables the Tamper interrupt. Value Description 0 The Tamper interrupt is disabled. 1 The Tamper interrupt is enabled. Bit 8 – CMP0 Compare 0 Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Compare 0 Interrupt Enable bit, which disables the Compare 0 interrupt. Value Description 0 The Compare 0 interrupt is disabled. 1 The Compare 0 interrupt is enabled. Bits 0, 1, 2, 3, 4, 5, 6, 7 – PERn Periodic Interval n Interrupt Enable [n = 7..0] Writing a '0' to this bit has no effect. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 410 Writing a '1' to this bit will clear the Periodic Interval n Interrupt Enable bit, which disables the Periodic Interval n interrupt. Value Description 0 Periodic Interval n interrupt is disabled. 1 Periodic Interval n interrupt is enabled. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 411 27.8.5 Interrupt Enable Set in COUNT32 mode (CTRLA.MODE=0) Name:  INTENSET Offset:  0x0A Reset:  0x0000 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear (INTENCLR) register. Bit 15 14 13 12 11 10 9 8 OVF TAMPER CMP0 Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 PER7 PER6 PER5 PER4 PER3 PER2 PER1 PER0 Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 – OVF Overflow Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Overflow Interrupt Enable bit, which enables the Overflow interrupt. Value Description 0 The Overflow interrupt is disabled. 1 The Overflow interrupt is enabled. Bit 14 – TAMPER Tamper Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Tamper Interrupt Enable bit, which enables the Tamper interrupt. Value Description 0 The Tamper interrupt is disabled. 1 The Tamper interrupt is enabled. Bit 8 – CMP0 Compare 0 Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Compare 0 Interrupt Enable bit, which enables the Compare 0 interrupt. Value Description 0 The Compare 0 interrupt is disabled. 1 The Compare 0 interrupt is enabled. Bits 0, 1, 2, 3, 4, 5, 6, 7 – PERn Periodic Interval n Interrupt Enable [n = 7..0] Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Periodic Interval n Interrupt Enable bit, which enables the Periodic Interval n interrupt. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 412 Value Description 0 Periodic Interval n interrupt is disabled. 1 Periodic Interval n interrupt is enabled. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 413 27.8.6 Interrupt Flag Status and Clear in COUNT32 mode (CTRLA.MODE=0) Name:  INTFLAG Offset:  0x0C Reset:  0x0000 Property:  - Bit 15 14 13 12 11 10 9 8 OVF TAMPER CMP0 Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 PER7 PER6 PER5 PER4 PER3 PER2 PER1 PER0 Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 – OVF Overflow This flag is cleared by writing a '1' to the flag. This flag is set on the next CLK_RTC_CNT cycle after an overflow condition occurs, and an interrupt request will be generated if INTENCLR/SET.OVF is '1'. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Overflow interrupt flag. Bit 14 – TAMPER Tamper event This flag is set after a damper condition occurs, and an interrupt request will be generated if INTENCLR.TAMPER/INTENSET.TAMPER is '1'. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Tamper interrupt flag. Bit 8 – CMP0 Compare 0 This flag is cleared by writing a '1' to the flag. This flag is set on the next CLK_RTC_CNT cycle after a match with the compare condition, and an interrupt request will be generated if INTENCLR/SET.COMP0 is one. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Compare 0 interrupt flag. Bits 0, 1, 2, 3, 4, 5, 6, 7 – PERn Periodic Interval n [n = 7..0] This flag is cleared by writing a '1' to the flag. This flag is set on the 0-to-1 transition of prescaler bit [n+2], and an interrupt request will be generated if INTENCLR/SET.PERn is one. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Periodic Interval n interrupt flag. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 414 27.8.7 Debug Control Name:  DBGCTRL Offset:  0x0E Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DBGRUN Access R/W Reset 0 Bit 0 – DBGRUN Debug Run This bit is not reset by a software reset. This bit controls the functionality when the CPU is halted by an external debugger. Value Description 0 The RTC is halted when the CPU is halted by an external debugger. 1 The RTC continues normal operation when the CPU is halted by an external debugger. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 415 27.8.8 Synchronization Busy in COUNT32 mode (CTRLA.MODE=0) Name:  SYNCBUSY Offset:  0x10 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 GPn[1:0] Access R R Reset 0 0 Bit 15 14 13 12 11 10 9 8 COUNTSYNC Access R Reset 0 Bit 7 6 5 4 3 2 1 0 COMP0 COUNT FREQCORR ENABLE SWRST Access R R R R R Reset 0 0 0 0 0 Bits 17:16 – GPn[1:0] General Purpose n Synchronization Busy Status Value Description 0 Write synchronization for GPn register is complete. 1 Write synchronization for GPn register is ongoing. Bit 15 – COUNTSYNC Count Read Sync Enable Synchronization Busy Status Value Description 0 Write synchronization for CTRLA.COUNTSYNC bit is complete. 1 Write synchronization for CTRLA.COUNTSYNC bit is ongoing. Bit 5 – COMP0 Compare 0 Synchronization Busy Status Value Description 0 Write synchronization for COMP0 register is complete. 1 Write synchronization for COMP0 register is ongoing. Bit 3 – COUNT Count Value Synchronization Busy Status Value Description 0 Read/write synchronization for COUNT register is complete. 1 Read/write synchronization for COUNT register is ongoing. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 416 Bit 2 – FREQCORR Frequency Correction Synchronization Busy Status Value Description 0 Write synchronization for FREQCORR register is complete. 1 Write synchronization for FREQCORR register is ongoing. Bit 1 – ENABLE Enable Synchronization Busy Status Value Description 0 Write synchronization for CTRLA.ENABLE bit is complete. 1 Write synchronization for CTRLA.ENABLE bit is ongoing. Bit 0 – SWRST Software Reset Synchronization Busy Status Value Description 0 Write synchronization for CTRLA.SWRST bit is complete. 1 Write synchronization for CTRLA.SWRST bit is ongoing. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 417 27.8.9 Frequency Correction Name:  FREQCORR Offset:  0x14 Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized Bit 7 6 5 4 3 2 1 0 SIGN VALUE[6:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 – SIGN Correction Sign Value Description 0 The correction value is positive, i.e., frequency will be decreased. 1 The correction value is negative, i.e., frequency will be increased. Bits 6:0 – VALUE[6:0] Correction Value These bits define the amount of correction applied to the RTC prescaler. Value Description 0 Correction is disabled and the RTC frequency is unchanged. 1 - 127 The RTC frequency is adjusted according to the value. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 418 27.8.10 Counter Value in COUNT32 mode (CTRLA.MODE=0) Name:  COUNT Offset:  0x18 Reset:  0x00000000 Property:  PAC Write-Protection, Write-Synchronized, Read-Synchronized Bit 31 30 29 28 27 26 25 24 COUNT[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 COUNT[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 COUNT[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 COUNT[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – COUNT[31:0] Counter Value These bits define the value of the 32-bit RTC counter in mode 0. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 419 27.8.11 Compare 0 Value in COUNT32 mode (CTRLA.MODE=0) Name:  COMP Offset:  0x20 Reset:  0x00000000 Property:  PAC Write-Protection, Write-Synchronized Bit 31 30 29 28 27 26 25 24 COMP[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 COMP[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 COMP[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 COMP[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – COMP[31:0] Compare Value The 32-bit value of COMP0 is continuously compared with the 32-bit COUNT value. When a match occurs, the Compare 0 interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG.CMP0) is set on the next counter cycle, and the counter value is cleared if CTRLA.MATCHCLR is '1'. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 420 27.8.12 General Purpose n Name:  GP Offset:  0x40 + n*0x04 [n=0..1] Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 GP[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 GP[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 GP[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 GP[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – GP[31:0] General Purpose These bits are for user-defined general purpose use, see 27.6.8.3 General Purpose Registers. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 421 27.8.13 Tamper Control Name:  TAMPCTRL Offset:  0x60 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 DEBNC3 DEBNC2 DEBNC1 DEBNC0 Access Reset 0 0 0 0 Bit 23 22 21 20 19 18 17 16 TAMLVL3 TAMLVL2 TAMLVL1 TAMLVL0 Access Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 IN3ACT[1:0] IN2ACT[1:0] IN1ACT[1:0] IN0ACT[1:0] Access Reset 0 0 0 0 0 0 0 0 Bits 24, 25, 26, 27 – DEBNC Debounce Enable of Tamper Input INn Value Description 0 Debouncing is disabled for Tamper input INn 1 Debouncing is enabled for Tamper input INn Bits 16, 17, 18, 19 – TAMLVL Tamper Level Select of Tamper Input INn Value Description 0 A falling edge condition will be detected on Tamper input INn. 1 A rising edge condition will be detected on Tamper input INn. Bits 0:1, 2:3, 4:5, 6:7 – INACT Tamper Channel n Action These bits determine the action taken by Tamper Channel n. Value Name Description 0x0 OFF Off (Disabled) 0x1 WAKE Wake and set Tamper flag 0x2 CAPTURE Capture timestamp and set Tamper flag 0x3 ACTL Compare RTC signal routed between INn and OUT pins . When a mismatch occurs, capture timestamp and set Tamper flag SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 422 27.8.14 Timestamp Name:  TIMESTAMP Offset:  0x64 Reset:  0x0 Property:  Read-Only Bit 31 30 29 28 27 26 25 24 COUNT[31:24] Access RO RO RO RO RO RO RO RO Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 COUNT[23:16] Access RO RO RO RO RO RO RO RO Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 COUNT[15:8] Access RO RO RO RO RO RO RO RO Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 COUNT[7:0] Access RO RO RO RO RO RO RO RO Reset 0 0 0 0 0 0 0 0 Bits 31:0 – COUNT[31:0] Count Timestamp Value The 32-bit value of COUNT is captured by the TIMESTAMP when a tamper condition occurs SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 423 27.8.15 Tamper ID Name:  TAMPID Offset:  0x68 Reset:  0x00000000 Bit 31 30 29 28 27 26 25 24 TAMPEVT Access R/W Reset 0 Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 TAMPID3 TAMPID2 TAMPID1 TAMPID0 Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 31 – TAMPEVT Tamper Event Detected Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the tamper detection bit. Value Description 0 A tamper input event has not been detected 1 A tamper input event has been detected Bits 0, 1, 2, 3 – TAMPID Tamper on Channel n Detected Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the tamper detection bit. Value Description 0 A tamper condition has not been detected on Channel n 1 A tamper condition has been detected on Channel n SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 424 27.8.16 Tamper Control B Name:  TAMPCTRLB Offset:  0x6C Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 ALSI3 ALSI2 ALSI1 ALSI0 Access R/W R/W R/W R/W Reset 0 0 0 0 Bits 0, 1, 2, 3 – ALSI Active Layer Internal Select n Value Description 0 Active layer Protection is monitoring the RTC signal using INn and OUTn tamper pins 1 Active layer Protection is monitoring the RTC signal on the TrustRAM shield SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 425 27.9 Register Summary - Mode 1 - 16-Bit Counter Offset Name Bit Pos. 0x00 CTRLA 7:0 MODE[1:0] ENABLE SWRST 15:8 COUNTSYNC GPTRST PRESCALER[3:0] 0x02 CTRLB 7:0 DMAEN RTCOUT DEBASYNC DEBMAJ GP0EN 15:8 SEPTO ACTF[2:0] DEBF[2:0] 0x04 EVCTRL 7:0 PEREO7 PEREO6 PEREO5 PEREO4 PEREO3 PEREO2 PEREO1 PEREO0 15:8 OVFEO TAMPEREO CMPEO1 CMPEO0 23:16 TAMPEVEI 31:24 PERDEO 0x08 INTENCLR 7:0 PER7 PER6 PER5 PER4 PER3 PER2 CMP1 CMP0 15:8 OVF TAMPER 0x0A INTENSET 7:0 PER7 PER6 PER5 PER4 PER3 PER2 CMP1 CMP0 15:8 OVF TAMPER 0x0C INTFLAG 7:0 PER7 PER6 PER5 PER4 PER3 PER2 CMP1 CMP0 15:8 OVF TAMPER 0x0E DBGCTRL 7:0 DBGRUN 0x0F Reserved 0x10 SYNCBUSY 7:0 COMP1 COMP0 PER COUNT FREQCORR ENABLE SWRST 15:8 COUNTSYNC 23:16 GPn[1:0] 31:24 0x14 FREQCORR 7:0 SIGN VALUE[6:0] 0x15 ... 0x17 Reserved 0x18 COUNT 7:0 COUNT[7:0] 15:8 COUNT[15:8] 0x1A ... 0x1B Reserved 0x1C PER 7:0 PER[7:0] 15:8 PER[15:8] 0x1E ... 0x1F Reserved 0x20 COMP0 7:0 COMP[7:0] 15:8 COMP[15:8] 0x22 COMP1 7:0 COMP[7:0] 15:8 COMP[15:8] 0x24 ... 0x3F Reserved 0x40 GP0 7:0 GP[7:0] 15:8 GP[15:8] 23:16 GP[23:16] SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 426 Offset Name Bit Pos. 31:24 GP[31:24] 0x44 GP1 7:0 GP[7:0] 15:8 GP[15:8] 23:16 GP[23:16] 31:24 GP[31:24] 0x48 ... 0x5F Reserved 0x60 TAMPCTRL 7:0 IN3ACT[1:0] IN2ACT[1:0] IN1ACT[1:0] IN0ACT[1:0] 15:8 23:16 TAMLVL3 TAMLVL2 TAMLVL1 TAMLVL0 31:24 DEBNC3 DEBNC2 DEBNC1 DEBNC0 0x64 TIMESTAMP 7:0 COUNT[7:0] 15:8 COUNT[15:8] 23:16 31:24 0x68 TAMPID 7:0 TAMPID3 TAMPID2 TAMPID1 TAMPID0 15:8 23:16 31:24 TAMPEVT 0x6C TAMPCTRLB 7:0 ALSI3 ALSI2 ALSI1 ALSI0 15:8 23:16 31:24 27.10 Register Description - Mode 1 - 16-Bit Counter This Register Description section is valid if the RTC is in COUNT16 mode (CTRLA.MODE=1). Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16-, and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers require synchronization when read and/or written. Synchronization is denoted by the "Read-Synchronized" and/or "Write-Synchronized" property in each individual register description. Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. Some registers are enable-protected, meaning they can only be written when the module is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 427 Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 428 27.10.1 Control A in COUNT16 mode (CTRLA.MODE=1) Name:  CTRLA Offset:  0x00 Reset:  0x0000 Property:  PAC Write-Protection, Enable-Protected, Write-Synchronized Bit 15 14 13 12 11 10 9 8 COUNTSYNC GPTRST PRESCALER[3:0] Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 MODE[1:0] ENABLE SWRST Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 15 – COUNTSYNC COUNT Read Synchronization Enable The COUNT register requires synchronization when reading. Disabling the synchronization will prevent reading valid values from the COUNT register. This bit is not enable-protected. Value Description 0 COUNT read synchronization is disabled 1 COUNT read synchronization is enabled Bit 14 – GPTRST GP Registers Reset On Tamper Enable Only GP registers enabled by the CTRLB.GPnEN bits are affected. This bit can be written only when the peripheral is disabled. This bit is not synchronized. Value Description 0 GPn registers will not reset when a tamper condition occurs. 1 GPn registers will reset when a tamper condition occurs. Bits 11:8 – PRESCALER[3:0] Prescaler These bits define the prescaling factor for the RTC clock source (GCLK_RTC) to generate the counter clock (CLK_RTC_CNT). Periodic events and interrupts are not available when the prescaler is off. These bits are not synchronized. Value Name Description 0x0 OFF CLK_RTC_CNT = GCLK_RTC/1 0x1 DIV1 CLK_RTC_CNT = GCLK_RTC/1 0x2 DIV2 CLK_RTC_CNT = GCLK_RTC/2 0x3 DIV4 CLK_RTC_CNT = GCLK_RTC/4 0x4 DIV8 CLK_RTC_CNT = GCLK_RTC/8 0x5 DIV16 CLK_RTC_CNT = GCLK_RTC/16 0x6 DIV32 CLK_RTC_CNT = GCLK_RTC/32 0x7 DIV64 CLK_RTC_CNT = GCLK_RTC/64 SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 429 Value Name Description 0x8 DIV128 CLK_RTC_CNT = GCLK_RTC/128 0x9 DIV256 CLK_RTC_CNT = GCLK_RTC/256 0xA DIV512 CLK_RTC_CNT = GCLK_RTC/512 0xB DIV1024 CLK_RTC_CNT = GCLK_RTC/1024 0xC-0xF - Reserved Bits 3:2 – MODE[1:0] Operating Mode This field defines the operating mode of the RTC. This bit is not synchronized. Value Name Description 0x0 COUNT32 Mode 0: 32-bit counter 0x1 COUNT16 Mode 1: 16-bit counter 0x2 CLOCK Mode 2: Clock/calendar 0x3 - Reserved Bit 1 – ENABLE Enable Due to synchronization there is delay from writing CTRLA.ENABLE until the peripheral is enabled/ disabled. The value written to CTRLA.ENABLE will read back immediately and the Enable bit in the Synchronization Busy register (SYNCBUSY.ENABLE) will be set. SYNCBUSY.ENABLE will be cleared when the operation is complete. Value Description 0 The peripheral is disabled 1 The peripheral is enabled Bit 0 – SWRST Software Reset Writing a '0' to this bit has no effect. Writing a '1' to this bit resets all registers in the RTC (except DBGCTRL) to their initial state, and the RTC will be disabled. Writing a '1' to CTRLA.SWRST will always take precedence, meaning that all other writes in the same write-operation will be discarded. Due to synchronization there is a delay from writing CTRLA.SWRST until the reset is complete. CTRLA.SWRST will be cleared when the reset is complete. Value Description 0 There is not reset operation ongoing 1 The reset operation is ongoing SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 430 27.10.2 Control B in COUNT16 mode (CTRLA.MODE=1) Name:  CTRLB Offset:  0x02 Reset:  0x0000 Property:  PAC Write-Protection, Enable-Protected Bit 15 14 13 12 11 10 9 8 SEPTO ACTF[2:0] DEBF[2:0] Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DMAEN RTCOUT DEBASYNC DEBMAJ GP0EN Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 15 – SEPTO Separate Tamper Outputs Value Description 0 IN[n] is compared to OUT[0] (backward-compatible). 1 IN[n] is compared to OUT[n]. Bits 14:12 – ACTF[2:0] Active Layer Frequency These bits define the prescaling factor for the RTC clock output (OUT) used during active layer protection in terms of the CLK_RTC. Value Name Description 0x0 DIV2 CLK_RTC_OUT = CLK_RTC / 2 0x1 DIV4 CLK_RTC_OUT = CLK_RTC / 4 0x2 DIV8 CLK_RTC_OUT = CLK_RTC / 8 0x3 DIV16 CLK_RTC_OUT = CLK_RTC / 16 0x4 DIV32 CLK_RTC_OUT = CLK_RTC / 32 0x5 DIV64 CLK_RTC_OUT = CLK_RTC / 64 0x6 DIV128 CLK_RTC_OUT = CLK_RTC / 128 0x7 DIV256 CLK_RTC_OUT = CLK_RTC / 256 Bits 10:8 – DEBF[2:0] Debounce Frequency These bits define the prescaling factor for the input debouncers in terms of the CLK_RTC. Value Name Description 0x0 DIV2 CLK_RTC_DEB = CLK_RTC / 2 0x1 DIV4 CLK_RTC_DEB = CLK_RTC / 4 0x2 DIV8 CLK_RTC_DEB = CLK_RTC / 8 0x3 DIV16 CLK_RTC_DEB = CLK_RTC / 16 0x4 DIV32 CLK_RTC_DEB = CLK_RTC / 32 0x5 DIV64 CLK_RTC_DEB = CLK_RTC / 64 0x6 DIV128 CLK_RTC_DEB = CLK_RTC / 128 0x7 DIV256 CLK_RTC_DEB = CLK_RTC / 256 SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 431 Bit 7 – DMAEN DMA Enable The RTC can trigger a DMA request when the timestamp is ready in the TIMESTAMP register. Value Description 0 Tamper DMA request is disabled. Reading TIMESTAMP has no effect on INTFLAG.TAMPER. 1 Tamper DMA request is enabled. Reading TIMESTAMP will clear INTFLAG.TAMPER. Bit 6 – RTCOUT RTC Output Enable Value Description 0 The RTC active layer output is disabled. 1 The RTC active layer output is enabled. Bit 5 – DEBASYNC Debouncer Asynchronous Enable Value Description 0 The tamper input debouncers operate synchronously. 1 The tamper input debouncers operate asynchronously. Bit 4 – DEBMAJ Debouncer Majority Enable Value Description 0 The tamper input debouncers match three equal values. 1 The tamper input debouncers match majority two of three values. Bit 0 – GP0EN General Purpose 0 Enable Value Description 0 COMP0 compare function enabled. GP0/GP1 disabled. 1 COMP0 compare function disabled. GP0/GP1 enabled. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 432 27.10.3 Event Control in COUNT16 mode (CTRLA.MODE=1) Name:  EVCTRL Offset:  0x04 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 PERDEO Access R/W Reset 0 Bit 23 22 21 20 19 18 17 16 TAMPEVEI Access R/W Reset 0 Bit 15 14 13 12 11 10 9 8 OVFEO TAMPEREO CMPEO1 CMPEO0 Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 6 5 4 3 2 1 0 PEREO7 PEREO6 PEREO5 PEREO4 PEREO3 PEREO2 PEREO1 PEREO0 Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 24 – PERDEO Periodic Interval Daily Event Output Enable Value Description 0 Periodic Daily event is disabled and will not be generated. 1 Periodic Daily event is enabled and will be generated. The event occurs at the overflow of the RTC counter (i.e., when the RTC counter goes from 0xFFFF to 0x0000). Bit 16 – TAMPEVEI Tamper Event Input Enable Value Description 0 Tamper event input is disabled, and incoming events will be ignored 1 Tamper event input is enabled, and incoming events will capture the COUNT value Bit 15 – OVFEO Overflow Event Output Enable Value Description 0 Overflow event is disabled and will not be generated. 1 Overflow event is enabled and will be generated for every overflow. Bit 14 – TAMPEREO Tamper Event Output Enable SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 433 Value Description 0 Tamper event output is disabled, and will not be generated. 1 Tamper event output is enabled, and will be generated for every tamper input. Bits 8, 9 – CMPEOn Compare n Event Output Enable [n = 1..0] Value Description 0 Compare n event is disabled and will not be generated. 1 Compare n event is enabled and will be generated for every compare match. Bits 0, 1, 2, 3, 4, 5, 6, 7 – PEREOn Periodic Interval n Event Output Enable [n = 7..0] Value Description 0 Periodic Interval n event is disabled and will not be generated. 1 Periodic Interval n event is enabled and will be generated. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 434 27.10.4 Interrupt Enable Clear in COUNT16 mode (CTRLA.MODE=1) Name:  INTENCLR Offset:  0x08 Reset:  0x0000 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set (INTENSET) register. Bit 15 14 13 12 11 10 9 8 OVF TAMPER Access R/W R/W Reset 0 0 Bit 7 6 5 4 3 2 1 0 PER7 PER6 PER5 PER4 PER3 PER2 CMP1 CMP0 Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 – OVF Overflow Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Overflow Interrupt Enable bit, which disables the Overflow interrupt. Value Description 0 The Overflow interrupt is disabled. 1 The Overflow interrupt is enabled. Bit 14 – TAMPER Tamper Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Tamper Interrupt Enable bit, which disables the Tamper interrupt. Value Description 0 The Tamper interrupt is disabled. 1 The Tamper interrupt is enabled. Bits 0, 1 – CMPn Compare n Interrupt Enable [n = 1..0] Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Compare n Interrupt Enable bit, which disables the Compare n interrupt. Value Description 0 The Compare n interrupt is disabled. 1 The Compare n interrupt is enabled. Bits 0, 1, 2, 3, 4, 5, 6, 7 – PERn Periodic Interval n Interrupt Enable [n = 7..0] Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Periodic Interval n Interrupt Enable bit, which disables the Periodic Interval n interrupt. Value Description 0 Periodic Interval n interrupt is disabled. 1 Periodic Interval n interrupt is enabled. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 435 27.10.5 Interrupt Enable Set in COUNT16 mode (CTRLA.MODE=1) Name:  INTENSET Offset:  0x0A Reset:  0x0000 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear (INTENCLR) register. Bit 15 14 13 12 11 10 9 8 OVF TAMPER Access R/W R/W Reset 0 0 Bit 7 6 5 4 3 2 1 0 PER7 PER6 PER5 PER4 PER3 PER2 CMP1 CMP0 Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 – OVF Overflow Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Overflow Interrupt Enable bit, which enables the Overflow interrupt. Value Description 0 The Overflow interrupt is disabled. 1 The Overflow interrupt is enabled. Bit 14 – TAMPER Tamper Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Tamper Interrupt Enable bit, which enables the Tamper interrupt. Value Description 0 The Tamper interrupt is disabled. 1 The Tamper interrupt is enabled. Bits 0, 1 – CMPn Compare n Interrupt Enable [n = 1..0] Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Compare n Interrupt Enable bit, which and enables the Compare n interrupt. Value Description 0 The Compare n interrupt is disabled. 1 The Compare n interrupt is enabled. Bits 0, 1, 2, 3, 4, 5, 6, 7 – PERn Periodic Interval n Interrupt Enable [n = 7..0] Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Periodic Interval n Interrupt Enable bit, which enables the Periodic Interval n interrupt. Value Description 0 Periodic Interval n interrupt is disabled. 1 Periodic Interval n interrupt is enabled. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 436 27.10.6 Interrupt Flag Status and Clear in COUNT16 mode (CTRLA.MODE=1) Name:  INTFLAG Offset:  0x0C Reset:  0x0000 Property:  - Bit 15 14 13 12 11 10 9 8 OVF TAMPER Access R/W R/W Reset 0 0 Bit 7 6 5 4 3 2 1 0 PER7 PER6 PER5 PER4 PER3 PER2 CMP1 CMP0 Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 – OVF Overflow This flag is cleared by writing a '1' to the flag. This flag is set on the next CLK_RTC_CNT cycle after an overflow condition occurs, and an interrupt request will be generated if INTENCLR/SET.OVF is '1'. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Overflow interrupt flag. Bit 14 – TAMPER Tamper This flag is set after a tamper condition occurs, and an interrupt request will be generated if INTENCLR.TAMPER/ INTENSET.TAMPER is one. Writing a '0' to this bit has no effect. Writing a one to this bit clears the Tamper interrupt flag. Bits 0, 1 – CMPn Compare n [n = 1..0] This flag is cleared by writing a '1' to the flag. This flag is set on the next CLK_RTC_CNT cycle after a match with the compare condition, and an interrupt request will be generated if INTENCLR/SET.COMPn is one. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Compare n interrupt flag. Bits 0, 1, 2, 3, 4, 5, 6, 7 – PERn Periodic Interval n [n = 7..0] This flag is cleared by writing a '1' to the flag. This flag is set on the 0-to-1 transition of prescaler bit [n+2], and an interrupt request will be generated if INTENCLR/SET.PERx is one. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Periodic Interval n interrupt flag. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 437 27.10.7 Debug Control Name:  DBGCTRL Offset:  0x0E Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DBGRUN Access R/W Reset 0 Bit 0 – DBGRUN Debug Run This bit is not reset by a software reset. This bit controls the functionality when the CPU is halted by an external debugger. Value Description 0 The RTC is halted when the CPU is halted by an external debugger. 1 The RTC continues normal operation when the CPU is halted by an external debugger. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 438 27.10.8 Synchronization Busy in COUNT16 mode (CTRLA.MODE=1) Name:  SYNCBUSY Offset:  0x10 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 GPn[1:0] Access R R Reset 0 0 Bit 15 14 13 12 11 10 9 8 COUNTSYNC Access R Reset 0 Bit 7 6 5 4 3 2 1 0 COMP1 COMP0 PER COUNT FREQCORR ENABLE SWRST Access R/W R/W R R R R R Reset 0 0 0 0 0 0 0 Bits 17:16 – GPn[1:0] General Purpose n Synchronization Busy Status Value Description 0 Write synchronization for GPn register is complete. 1 Write synchronization for GPn register is ongoing. Bit 15 – COUNTSYNC Count Read Sync Enable Synchronization Busy Status Value Description 0 Write synchronization for CTRLA.COUNTSYNC bit is complete. 1 Write synchronization for CTRLA.COUNTSYNC bit is ongoing. Bits 5, 6 – COMPn Compare n Synchronization Busy Status [n = 1..0] Value Description 0 Write synchronization for COMPn register is complete. 1 Write synchronization for COMPn register is ongoing. Bit 4 – PER Period Synchronization Busy Status Value Description 0 Write synchronization for PER register is complete. 1 Write synchronization for PER register is ongoing. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 439 Bit 3 – COUNT Count Value Synchronization Busy Status Value Description 0 Read/write synchronization for COUNT register is complete. 1 Read/write synchronization for COUNT register is ongoing. Bit 2 – FREQCORR Frequency Correction Synchronization Busy Status Value Description 0 Write synchronization for FREQCORR register is complete. 1 Write synchronization for FREQCORR register is ongoing. Bit 1 – ENABLE Enable Synchronization Busy Status Value Description 0 Write synchronization for CTRLA.ENABLE bit is complete. 1 Write synchronization for CTRLA.ENABLE bit is ongoing. Bit 0 – SWRST Software Reset Synchronization Busy Status Value Description 0 Write synchronization for CTRLA.SWRST bit is complete. 1 Write synchronization for CTRLA.SWRST bit is ongoing. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 440 27.10.9 Frequency Correction Name:  FREQCORR Offset:  0x14 Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized Bit 7 6 5 4 3 2 1 0 SIGN VALUE[6:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 – SIGN Correction Sign Value Description 0 The correction value is positive, i.e., frequency will be decreased. 1 The correction value is negative, i.e., frequency will be increased. Bits 6:0 – VALUE[6:0] Correction Value These bits define the amount of correction applied to the RTC prescaler. Value Description 0 Correction is disabled and the RTC frequency is unchanged. 1 - 127 The RTC frequency is adjusted according to the value. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 441 27.10.10 Counter Value in COUNT16 mode (CTRLA.MODE=1) Name:  COUNT Offset:  0x18 Reset:  0x0000 Property:  PAC Write-Protection, Write-Synchronized, Read-Synchronized Bit 15 14 13 12 11 10 9 8 COUNT[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 COUNT[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 15:0 – COUNT[15:0] Counter Value These bits define the value of the 16-bit RTC counter in COUNT16 mode (CTRLA.MODE=1). SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 442 27.10.11 Counter Period in COUNT16 mode (CTRLA.MODE=1) Name:  PER Offset:  0x1C Reset:  0x0000 Property:  PAC Write-Protection, Write-Synchronized Bit 15 14 13 12 11 10 9 8 PER[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 PER[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 15:0 – PER[15:0] Counter Period These bits define the value of the 16-bit RTC period in COUNT16 mode (CTRLA.MODE=1). SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 443 27.10.12 Compare n Value in COUNT16 mode (CTRLA.MODE=1) Name:  COMP Offset:  0x20 + n*0x02 [n=0..1] Reset:  0x0000 Property:  PAC Write-Protection, Write-Synchronized Bit 15 14 13 12 11 10 9 8 COMP[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 COMP[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 15:0 – COMP[15:0] Compare Value The 16-bit value of COMPn is continuously compared with the 16-bit COUNT value. When a match occurs, the Compare n interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG.CMPn) is set on the next counter cycle. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 444 27.10.13 General Purpose n Name:  GP Offset:  0x40 + n*0x04 [n=0..1] Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 GP[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 GP[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 GP[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 GP[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – GP[31:0] General Purpose These bits are for user-defined general purpose use, see 27.6.8.3 General Purpose Registers. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 445 27.10.14 Tamper Control Name:  TAMPCTRL Offset:  0x60 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 DEBNC3 DEBNC2 DEBNC1 DEBNC0 Access Reset 0 0 0 0 Bit 23 22 21 20 19 18 17 16 TAMLVL3 TAMLVL2 TAMLVL1 TAMLVL0 Access Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 IN3ACT[1:0] IN2ACT[1:0] IN1ACT[1:0] IN0ACT[1:0] Access Reset 0 0 0 0 0 0 0 0 Bits 24, 25, 26, 27 – DEBNC Debounce Enable of Tamper Input INn Value Description 0 Debouncing is disabled for Tamper input INn 1 Debouncing is enabled for Tamper input INn Bits 16, 17, 18, 19 – TAMLVL Tamper Level Select of Tamper Input INn Value Description 0 A falling edge condition will be detected on Tamper input INn. 1 A rising edge condition will be detected on Tamper input INn. Bits 0:1, 2:3, 4:5, 6:7 – INACT Tamper Channel n Action These bits determine the action taken by Tamper Channel n. Value Name Description 0x0 OFF Off (Disabled) 0x1 WAKE Wake and set Tamper flag 0x2 CAPTURE Capture timestamp and set Tamper flag 0x3 ACTL Compare RTC signal routed between INn and OUT pins . When a mismatch occurs, capture timestamp and set Tamper flag SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 446 27.10.15 Timestamp Name:  TIMESTAMP Offset:  0x64 Reset:  0x0000 Property:  Read-Only Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 COUNT[15:8] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 COUNT[7:0] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bits 15:0 – COUNT[15:0] Count Timestamp Value The 16-bit value of COUNT is captured by the TIMESTAMP when a tamper condition occurs. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 447 27.10.16 Tamper ID Name:  TAMPID Offset:  0x68 Reset:  0x00000000 Bit 31 30 29 28 27 26 25 24 TAMPEVT Access R/W Reset 0 Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 TAMPID3 TAMPID2 TAMPID1 TAMPID0 Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 31 – TAMPEVT Tamper Event Detected Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the tamper detection bit. Value Description 0 A tamper input event has not been detected 1 A tamper input event has been detected Bits 0, 1, 2, 3 – TAMPID Tamper on Channel n Detected Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the tamper detection bit. Value Description 0 A tamper condition has not been detected on Channel n 1 A tamper condition has been detected on Channel n SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 448 27.10.17 Tamper Control B Name:  TAMPCTRLB Offset:  0x6C Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 ALSI3 ALSI2 ALSI1 ALSI0 Access R/W R/W R/W R/W Reset 0 0 0 0 Bits 0, 1, 2, 3 – ALSI Active Layer Internal Select n Value Description 0 Active layer Protection is monitoring the RTC signal using INn and OUTn tamper pins 1 Active layer Protection is monitoring the RTC signal on the TrustRAM shield SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 449 27.11 Register Summary - Mode 2 - Clock/Calendar Offset Name Bit Pos. 0x00 CTRLA 7:0 MATCHCLR CLKREP MODE[1:0] ENABLE SWRST 15:8 CLOCKSYNC GPTRST PRESCALER[3:0] 0x02 CTRLB 7:0 DMAEN RTCOUT DEBASYNC DEBMAJ GP0EN 15:8 SEPTO ACTF[2:0] DEBF[2:0] 0x04 EVCTRL 7:0 PEREO7 PEREO6 PEREO5 PEREO4 PEREO3 PEREO2 PEREO1 PEREO0 15:8 OVFEO TAMPEREO ALARMEO 23:16 TAMPEVEI 31:24 PERDEO 0x08 INTENCLR 7:0 PER7 PER6 PER5 PER4 PER3 PER2 PER1 PER0 15:8 OVF TAMPER ALARM0 0x0A INTENSET 7:0 PER7 PER6 PER5 PER4 PER3 PER2 PER1 PER0 15:8 OVF TAMPER ALARM0 0x0C INTFLAG 7:0 PER7 PER6 PER5 PER4 PER3 PER2 PER1 PER0 15:8 OVF TAMPER ALARM0 0x0E DBGCTRL 7:0 DBGRUN 0x0F Reserved 0x10 SYNCBUSY 7:0 ALARM0 CLOCK FREQCORR ENABLE SWRST 15:8 CLOCKSYNC MASK0 23:16 GPn[1:0] 31:24 0x14 FREQCORR 7:0 SIGN VALUE[6:0] 0x15 ... 0x17 Reserved 0x18 CLOCK 7:0 MINUTE[1:0] SECOND[5:0] 15:8 HOUR[3:0] MINUTE[5:2] 23:16 MONTH[1:0] DAY[4:0] HOUR[4:4] 31:24 YEAR[5:0] MONTH[3:2] 0x1C ... 0x1F Reserved 0x20 ALARM 7:0 MINUTE[1:0] SECOND[5:0] 15:8 HOUR[3:0] MINUTE[5:2] 23:16 MONTH[1:0] DAY[4:0] HOUR[4:4] 31:24 YEAR[5:0] MONTH[3:2] 0x24 MASK 7:0 SEL[2:0] 0x25 ... 0x3F Reserved 0x40 GP0 7:0 GP[7:0] 15:8 GP[15:8] 23:16 GP[23:16] 31:24 GP[31:24] SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 450 Offset Name Bit Pos. 0x44 GP1 7:0 GP[7:0] 15:8 GP[15:8] 23:16 GP[23:16] 31:24 GP[31:24] 0x48 ... 0x5F Reserved 0x60 TAMPCTRL 7:0 IN3ACT[1:0] IN2ACT[1:0] IN1ACT[1:0] IN0ACT[1:0] 15:8 23:16 TAMLVL3 TAMLVL2 TAMLVL1 TAMLVL0 31:24 DEBNC3 DEBNC2 DEBNC1 DEBNC0 0x64 TIMESTAMP 7:0 MINUTE[1:0] SECOND[5:0] 15:8 HOUR[3:0] MINUTE[5:2] 23:16 MONTH[1:0] DAY[4:0] HOUR[4:4] 31:24 YEAR[5:0] MONTH[3:2] 0x68 TAMPID 7:0 TAMPID3 TAMPID2 TAMPID1 TAMPID0 15:8 23:16 31:24 TAMPEVT 0x6C TAMPCTRLB 7:0 ALSI3 ALSI2 ALSI1 ALSI0 15:8 23:16 31:24 27.12 Register Description - Mode 2 - Clock/Calendar This Register Description section is valid if the RTC is in Clock/Calendar mode (CTRLA.MODE=2). Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16-, and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers require synchronization when read and/or written. Synchronization is denoted by the "Read-Synchronized" and/or "Write-Synchronized" property in each individual register description. Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. Some registers are enable-protected, meaning they can only be written when the module is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 451 Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 452 27.12.1 Control A in Clock/Calendar mode (CTRLA.MODE=2) Name:  CTRLA Offset:  0x00 Reset:  0x0000 Property:  PAC Write-Protection, Enable-Protected, Write-Synchronized Bit 15 14 13 12 11 10 9 8 CLOCKSYNC GPTRST PRESCALER[3:0] Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 MATCHCLR CLKREP MODE[1:0] ENABLE SWRST Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 15 – CLOCKSYNC CLOCK Read Synchronization Enable The CLOCK register requires synchronization when reading. Disabling the synchronization will prevent reading valid values from the CLOCK register. This bit is not enable-protected. Value Description 0 CLOCK read synchronization is disabled 1 CLOCK read synchronization is enabled Bit 14 – GPTRST GP Registers Reset On Tamper Enable Only GP registers enabled by the CTRLB.GPnEN bits are affected. This bit can be written only when the peripheral is disabled. This bit is not synchronized. Bits 11:8 – PRESCALER[3:0] Prescaler These bits define the prescaling factor for the RTC clock source (GCLK_RTC) to generate the counter clock (CLK_RTC_CNT). Periodic events and interrupts are not available when the prescaler is off. These bits are not synchronized. Value Name Description 0x0 OFF CLK_RTC_CNT = GCLK_RTC/1 0x1 DIV1 CLK_RTC_CNT = GCLK_RTC/1 0x2 DIV2 CLK_RTC_CNT = GCLK_RTC/2 0x3 DIV4 CLK_RTC_CNT = GCLK_RTC/4 0x4 DIV8 CLK_RTC_CNT = GCLK_RTC/8 0x5 DIV16 CLK_RTC_CNT = GCLK_RTC/16 0x6 DIV32 CLK_RTC_CNT = GCLK_RTC/32 0x7 DIV64 CLK_RTC_CNT = GCLK_RTC/64 0x8 DIV128 CLK_RTC_CNT = GCLK_RTC/128 0x9 DIV256 CLK_RTC_CNT = GCLK_RTC/256 0xA DIV512 CLK_RTC_CNT = GCLK_RTC/512 SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 453 Value Name Description 0xB DIV1024 CLK_RTC_CNT = GCLK_RTC/1024 0xC-0xF - Reserved Bit 7 – MATCHCLR Clear on Match This bit is valid only in Mode 0 (COUNT32) and Mode 2 (CLOCK). This bit can be written only when the peripheral is disabled. This bit is not synchronized. Value Description 0 The counter is not cleared on a Compare/Alarm 0 match 1 The counter is cleared on a Compare/Alarm 0 match Bit 6 – CLKREP Clock Representation This bit is valid only in Mode 2 and determines how the hours are represented in the Clock Value (CLOCK) register. This bit can be written only when the peripheral is disabled. This bit is not synchronized. Value Description 0 24 Hour 1 12 Hour (AM/PM) Bits 3:2 – MODE[1:0] Operating Mode This field defines the operating mode of the RTC. This bit is not synchronized. Value Name Description 0x0 COUNT32 Mode 0: 32-bit counter 0x1 COUNT16 Mode 1: 16-bit counter 0x2 CLOCK Mode 2: Clock/calendar 0x3 - Reserved Bit 1 – ENABLE Enable Due to synchronization there is delay from writing CTRLA.ENABLE until the peripheral is enabled/ disabled. The value written to CTRLA.ENABLE will read back immediately and the Enable bit in the Synchronization Busy register (SYNCBUSY.ENABLE) will be set. SYNCBUSY.ENABLE will be cleared when the operation is complete. Value Description 0 The peripheral is disabled 1 The peripheral is enabled Bit 0 – SWRST Software Reset Writing a '0' to this bit has no effect. Writing a '1' to this bit resets all registers in the RTC, except DBGCTRL, to their initial state, and the RTC will be disabled. Writing a '1' to CTRLA.SWRST will always take precedence, meaning that all other writes in the same write-operation will be discarded. Due to synchronization there is a delay from writing CTRLA.SWRST until the reset is complete. CTRLA.SWRST will be cleared when the reset is complete. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 454 Value Description 0 There is not reset operation ongoing 1 The reset operation is ongoing SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 455 27.12.2 Control B in Clock/Calendar mode (CTRLA.MODE=2) Name:  CTRLB Offset:  0x2 Reset:  0x0000 Property:  PAC Write-Protection, Enable-Protected Bit 15 14 13 12 11 10 9 8 SEPTO ACTF[2:0] DEBF[2:0] Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DMAEN RTCOUT DEBASYNC DEBMAJ GP0EN Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 15 – SEPTO Separate Tamper Outputs Value Description 0 IN[n] is compared tp OUT[0] (backward-compatible). 1 IN[n] is compared tp OUT[n]. Bits 14:12 – ACTF[2:0] Active Layer Frequency These bits define the prescaling factor for the RTC clock output (OUT) used during active layer protection in terms of the CLK_RTC. Value Name Description 0x0 DIV2 CLK_RTC_OUT = CLK_RTC / 2 0x1 DIV4 CLK_RTC_OUT = CLK_RTC / 4 0x2 DIV8 CLK_RTC_OUT = CLK_RTC / 8 0x3 DIV16 CLK_RTC_OUT = CLK_RTC / 16 0x4 DIV32 CLK_RTC_OUT = CLK_RTC / 32 0x5 DIV64 CLK_RTC_OUT = CLK_RTC / 64 0x6 DIV128 CLK_RTC_OUT = CLK_RTC / 128 0x7 DIV256 CLK_RTC_OUT = CLK_RTC / 256 Bits 10:8 – DEBF[2:0] Debounce Frequency These bits define the prescaling factor for the input debouncers in terms of the CLK_RTC. Value Name Description 0x0 DIV2 CLK_RTC_DEB = CLK_RTC / 2 0x1 DIV4 CLK_RTC_DEB = CLK_RTC / 4 0x2 DIV8 CLK_RTC_DEB = CLK_RTC / 8 0x3 DIV16 CLK_RTC_DEB = CLK_RTC / 16 0x4 DIV32 CLK_RTC_DEB = CLK_RTC / 32 0x5 DIV64 CLK_RTC_DEB = CLK_RTC / 64 0x6 DIV128 CLK_RTC_DEB = CLK_RTC / 128 0x7 DIV256 CLK_RTC_DEB = CLK_RTC / 256 SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 456 Bit 7 – DMAEN DMA Enable The RTC can trigger a DMA request when the timestamp is ready in the TIMESTAMP register. Value Description 0 Tamper DMA request is disabled. Reading TIMESTAMP has no effect on INTFLAG.TAMPER. 1 Tamper DMA request is enabled. Reading TIMESTAMP will clear INTFLAG.TAMPER. Bit 6 – RTCOUT RTC Out Enable Value Description 0 The RTC active layer output is disabled. 1 The RTC active layer output is enabled. Bit 5 – DEBASYNC Debouncer Asynchronous Enable Value Description 0 The tamper input debouncers operate synchronously. 1 The tamper input debouncers operate asynchronously. Bit 4 – DEBMAJ Debouncer Majority Enable Value Description 0 The tamper input debouncers match three equal values. 1 The tamper input debouncers match majority two of three values. Bit 0 – GP0EN General Purpose 0 Enable Value Description 0 COMP0 compare function enabled. GP0 disabled. 1 COMP0 compare function disabled. GP0 enabled. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 457 27.12.3 Event Control in Clock/Calendar mode (CTRLA.MODE=2) Name:  EVCTRL Offset:  0x04 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 PERDEO Access R/W Reset 0 Bit 23 22 21 20 19 18 17 16 TAMPEVEI Access R/W Reset 0 Bit 15 14 13 12 11 10 9 8 OVFEO TAMPEREO ALARMEO Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 PEREO7 PEREO6 PEREO5 PEREO4 PEREO3 PEREO2 PEREO1 PEREO0 Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 24 – PERDEO Periodic Interval Daily Event Output Enable Value Description 0 Periodic Daily event is disabled and will not be generated. 1 Periodic Daily event is enabled and will be generated. The event occurs at the last second of each day depending on the CTRLA.CLKREP bit: • If CLKREP = 0, the event will occur at 23:59:59 • If CLKREP = 1, the event will occur at 11:59:59, PM = 1 Bit 16 – TAMPEVEI Tamper Event Input Enable Value Description 0 Tamper event input is disabled, and incoming events will be ignored. 1 Tamper event input is enabled, and all incoming events will capture the CLOCK value. Bit 15 – OVFEO Overflow Event Output Enable Value Description 0 Overflow event is disabled and will not be generated. 1 Overflow event is enabled and will be generated for every overflow. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 458 Bit 14 – TAMPEREO Tamper Event Output Enable Value Description 0 Tamper event output is disabled, and will not be generated 1 Tamper event output is enabled, and will be generated for every tamper input. Bit 8 – ALARMEO Alarm 0 Event Output Enable Value Description 0 Alarm 0 event is disabled and will not be generated. 1 Alarm 0 event is enabled and will be generated for every compare match. Bits 0, 1, 2, 3, 4, 5, 6, 7 – PEREOn Periodic Interval n Event Output Enable [n = 7..0] Value Description 0 Periodic Interval n event is disabled and will not be generated. 1 Periodic Interval n event is enabled and will be generated. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 459 27.12.4 Interrupt Enable Clear in Clock/Calendar mode (CTRLA.MODE=2) Name:  INTENCLR Offset:  0x08 Reset:  0x0000 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set (INTENSET) register. Bit 15 14 13 12 11 10 9 8 OVF TAMPER ALARM0 Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 PER7 PER6 PER5 PER4 PER3 PER2 PER1 PER0 Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 – OVF Overflow Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Overflow Interrupt Enable bit, which disables the Overflow interrupt. Value Description 0 The Overflow interrupt is disabled. 1 The Overflow interrupt is enabled. Bit 14 – TAMPER Tamper Interrupt Enable Bit 8 – ALARM0 Alarm 0 Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Alarm 0 Interrupt Enable bit, which disables the Alarm interrupt. Value Description 0 The Alarm 0 interrupt is disabled. 1 The Alarm 0 interrupt is enabled. Bits 0, 1, 2, 3, 4, 5, 6, 7 – PERn Periodic Interval n Interrupt Enable [n = 7..0] Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Periodic Interval n Interrupt Enable bit, which disables the Periodic Interval n interrupt. Value Description 0 Periodic Interval n interrupt is disabled. 1 Periodic Interval n interrupt is enabled. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 460 27.12.5 Interrupt Enable Set in Clock/Calendar mode (CTRLA.MODE=2) Name:  INTENSET Offset:  0x0A Reset:  0x0000 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear (INTENCLR) register. Bit 15 14 13 12 11 10 9 8 OVF TAMPER ALARM0 Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 PER7 PER6 PER5 PER4 PER3 PER2 PER1 PER0 Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 – OVF Overflow Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Overflow Interrupt Enable bit, which enables the Overflow interrupt. Value Description 0 The Overflow interrupt is disabled. 1 The Overflow interrupt is enabled. Bit 14 – TAMPER Tamper Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Tamper Interrupt Enable bit, which enables the Tamper interrupt. Value Description 0 The Tamper interrupt it disabled. 1 The Tamper interrupt is enabled. Bit 8 – ALARM0 Alarm 0 Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Alarm 0 Interrupt Enable bit, which enables the Alarm 0 interrupt. Value Description 0 The Alarm 0 interrupt is disabled. 1 The Alarm 0 interrupt is enabled. Bits 0, 1, 2, 3, 4, 5, 6, 7 – PERn Periodic Interval n Interrupt Enable [n = 7..0] Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Periodic Interval n Interrupt Enable bit, which enables the Periodic Interval n interrupt. Value Description 0 Periodic Interval n interrupt is disabled. 1 Periodic Interval n interrupt is enabled. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 461 27.12.6 Interrupt Flag Status and Clear in Clock/Calendar mode (CTRLA.MODE=2) Name:  INTFLAG Offset:  0x0C Reset:  0x0000 Property:  - Bit 15 14 13 12 11 10 9 8 OVF TAMPER ALARM0 Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 PER7 PER6 PER5 PER4 PER3 PER2 PER1 PER0 Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 – OVF Overflow This flag is cleared by writing a '1' to the flag. This flag is set on the next CLK_RTC_CNT cycle after an overflow condition occurs, and an interrupt request will be generated if INTENCLR/SET.OVF is '1'. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Overflow interrupt flag. Bit 14 – TAMPER Tamper This flag is set after a tamper condition occurs, and an interrupt request will be generated if INTENCLR.TAMPER/INTENSET.TAMPER is '1'. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Tamper interrupt flag. Bit 8 – ALARM0 Alarm 0 This flag is cleared by writing a '1' to the flag. This flag is set on the next CLK_RTC_CNT cycle after a match with the compare condition, and an interrupt request will be generated if INTENCLR/SET.ALARM0 is one. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Alarm 0 interrupt flag. Bits 0, 1, 2, 3, 4, 5, 6, 7 – PERn Periodic Interval n [n = 7..0] This flag is cleared by writing a '1' to the flag. This flag is set on the 0-to-1 transition of prescaler bit [n+2], and an interrupt request will be generated if INTENCLR/SET.PERx is '1'. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Periodic Interval n interrupt flag. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 462 27.12.7 Debug Control Name:  DBGCTRL Offset:  0x0E Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DBGRUN Access R/W Reset 0 Bit 0 – DBGRUN Debug Run This bit is not reset by a software reset. This bit controls the functionality when the CPU is halted by an external debugger. Value Description 0 The RTC is halted when the CPU is halted by an external debugger. 1 The RTC continues normal operation when the CPU is halted by an external debugger. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 463 27.12.8 Synchronization Busy in Clock/Calendar mode (CTRLA.MODE=2) Name:  SYNCBUSY Offset:  0x10 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 GPn[1:0] Access R R Reset 0 0 Bit 15 14 13 12 11 10 9 8 CLOCKSYNC MASK0 Access R R Reset 0 0 Bit 7 6 5 4 3 2 1 0 ALARM0 CLOCK FREQCORR ENABLE SWRST Access R R R R R Reset 0 0 0 0 0 Bits 17:16 – GPn[1:0] General Purpose n Synchronization Busy Status Value Description 0 Write synchronization for GPn register is complete. 1 Write synchronization for GPn register is ongoing. Bit 15 – CLOCKSYNC Clock Read Sync Enable Synchronization Busy Status Value Description 0 Write synchronization for CTRLA.CLOCKSYNC bit is complete. 1 Write synchronization for CTRLA.CLOCKSYNC bit is ongoing. Bit 11 – MASK0 Mask 0 Synchronization Busy Status Value Description 0 Write synchronization for MASK0 register is complete. 1 Write synchronization for MASK0 register is ongoing. Bit 5 – ALARM0 Alarm 0 Synchronization Busy Status Value Description 0 Write synchronization for ALARM0 register is complete. 1 Write synchronization for ALARM0 register is ongoing. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 464 Bit 3 – CLOCK Clock Register Synchronization Busy Status Value Description 0 Read/write synchronization for CLOCK register is complete. 1 Read/write synchronization for CLOCK register is ongoing. Bit 2 – FREQCORR Frequency Correction Synchronization Busy Status Value Description 0 Write synchronization for FREQCORR register is complete. 1 Write synchronization for FREQCORR register is ongoing. Bit 1 – ENABLE Enable Synchronization Busy Status Value Description 0 Write synchronization for CTRLA.ENABLE bit is complete. 1 Write synchronization for CTRLA.ENABLE bit is ongoing. Bit 0 – SWRST Software Reset Synchronization Busy Status Value Description 0 Write synchronization for CTRLA.SWRST bit is complete. 1 Write synchronization for CTRLA.SWRST bit is ongoing. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 465 27.12.9 Frequency Correction Name:  FREQCORR Offset:  0x14 Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized Bit 7 6 5 4 3 2 1 0 SIGN VALUE[6:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 – SIGN Correction Sign Value Description 0 The correction value is positive, i.e., frequency will be decreased. 1 The correction value is negative, i.e., frequency will be increased. Bits 6:0 – VALUE[6:0] Correction Value These bits define the amount of correction applied to the RTC prescaler. Value Description 0 Correction is disabled and the RTC frequency is unchanged. 1 - 127 The RTC frequency is adjusted according to the value. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 466 27.12.10 Clock Value in Clock/Calendar mode (CTRLA.MODE=2) Name:  CLOCK Offset:  0x18 Reset:  0x00000000 Property:  PAC Write-Protection, Write-Synchronized, Read-Synchronized Bit 31 30 29 28 27 26 25 24 YEAR[5:0] MONTH[3:2] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 MONTH[1:0] DAY[4:0] HOUR[4:4] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 HOUR[3:0] MINUTE[5:2] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 MINUTE[1:0] SECOND[5:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:26 – YEAR[5:0] Year The year offset with respect to the reference year (defined in software). The year is considered a leap year if YEAR[1:0] is zero. Bits 25:22 – MONTH[3:0] Month 1 – January 2 – February ... 12 – December Bits 21:17 – DAY[4:0] Day Day starts at 1 and ends at 28, 29, 30, or 31, depending on the month and year. Bits 16:12 – HOUR[4:0] Hour When CTRLA.CLKREP=0, the Hour bit group is in 24-hour format, with values 0-23. When CTRLA.CLKREP=1, HOUR[3:0] has values 1-12, and HOUR[4] represents AM (0) or PM (1). Bits 11:6 – MINUTE[5:0] Minute 0 – 59 SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 467 Bits 5:0 – SECOND[5:0] Second 0 – 59 SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 468 27.12.11 Alarm Value in Clock/Calendar mode (CTRLA.MODE=2) Name:  ALARM Offset:  0x20 Reset:  0x00000000 Property:  PAC Write-Protection, Write-Synchronized The 32-bit value of ALARM is continuously compared with the 32-bit CLOCK value, based on the masking set by MASK.SEL. When a match occurs, the Alarm n interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG.ALARM) is set on the next counter cycle, and the counter is cleared if CTRLA.MATCHCLR is '1'. Bit 31 30 29 28 27 26 25 24 YEAR[5:0] MONTH[3:2] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 MONTH[1:0] DAY[4:0] HOUR[4:4] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 HOUR[3:0] MINUTE[5:2] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 MINUTE[1:0] SECOND[5:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:26 – YEAR[5:0] Year The alarm year. Years are only matched if MASK.SEL is 6 Bits 25:22 – MONTH[3:0] Month The alarm month. Months are matched only if MASK.SEL is greater than 4. Bits 21:17 – DAY[4:0] Day The alarm day. Days are matched only if MASK.SEL is greater than 3. Bits 16:12 – HOUR[4:0] Hour The alarm hour. Hours are matched only if MASK.SEL is greater than 2. Bits 11:6 – MINUTE[5:0] Minute The alarm minute. Minutes are matched only if MASK.SEL is greater than 1. Bits 5:0 – SECOND[5:0] Second The alarm second. Seconds are matched only if MASK.SEL is greater than 0. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 469 27.12.12 Alarm Mask in Clock/Calendar mode (CTRLA.MODE=2) Name:  MASK Offset:  0x24 Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized Bit 7 6 5 4 3 2 1 0 SEL[2:0] Access R/W R/W R/W Reset 0 0 0 Bits 2:0 – SEL[2:0] Alarm Mask Selection These bits define which bit groups of ALARM are valid. Value Name Description 0x0 OFF Alarm Disabled 0x1 SS Match seconds only 0x2 MMSS Match seconds and minutes only 0x3 HHMMSS Match seconds, minutes, and hours only 0x4 DDHHMMSS Match seconds, minutes, hours, and days only 0x5 MMDDHHMMSS Match seconds, minutes, hours, days, and months only 0x6 YYMMDDHHMMSS Match seconds, minutes, hours, days, months, and years 0x7 - Reserved SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 470 27.12.13 General Purpose n Name:  GP Offset:  0x40 + n*0x04 [n=0..1] Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 GP[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 GP[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 GP[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 GP[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – GP[31:0] General Purpose These bits are for user-defined general purpose use, see 27.6.8.3 General Purpose Registers. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 471 27.12.14 Tamper Control Name:  TAMPCTRL Offset:  0x60 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 DEBNC3 DEBNC2 DEBNC1 DEBNC0 Access Reset 0 0 0 0 Bit 23 22 21 20 19 18 17 16 TAMLVL3 TAMLVL2 TAMLVL1 TAMLVL0 Access Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 IN3ACT[1:0] IN2ACT[1:0] IN1ACT[1:0] IN0ACT[1:0] Access Reset 0 0 0 0 0 0 0 0 Bits 24, 25, 26, 27 – DEBNC Debounce Enable of Tamper Input INn Value Description 0 Debouncing is disabled for Tamper input INn 1 Debouncing is enabled for Tamper input INn Bits 16, 17, 18, 19 – TAMLVL Tamper Level Select of Tamper Input INn Value Description 0 A falling edge condition will be detected on Tamper input INn. 1 A rising edge condition will be detected on Tamper input INn. Bits 0:1, 2:3, 4:5, 6:7 – INACT Tamper Channel n Action These bits determine the action taken by Tamper Channel n. Value Name Description 0x0 OFF Off (Disabled) 0x1 WAKE Wake and set Tamper flag 0x2 CAPTURE Capture timestamp and set Tamper flag 0x3 ACTL Compare RTC signal routed between INn and OUT pins . When a mismatch occurs, capture timestamp and set Tamper flag SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 472 27.12.15 Timestamp Value Name:  TIMESTAMP Offset:  0x64 Reset:  0 Property:  R Bit 31 30 29 28 27 26 25 24 YEAR[5:0] MONTH[3:2] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 MONTH[1:0] DAY[4:0] HOUR[4:4] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 HOUR[3:0] MINUTE[5:2] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 MINUTE[1:0] SECOND[5:0] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bits 31:26 – YEAR[5:0] Year The year value is captured by the TIMESTAMP when a tamper condition occurs. Bits 25:22 – MONTH[3:0] Month The month value is captured by the TIMESTAMP when a tamper condition occurs. Bits 21:17 – DAY[4:0] Day The day value is captured by the TIMESTAMP when a tamper condition occurs. Bits 16:12 – HOUR[4:0] Hour The hour value is captured by the TIMESTAMP when a tamper condition occurs. Bits 11:6 – MINUTE[5:0] Minute The minute value is captured by the TIMESTAMP when a tamper condition occurs. Bits 5:0 – SECOND[5:0] Second The second value is captured by the TIMESTAMP when a tamper condition occurs. SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 473 27.12.16 Tamper ID Name:  TAMPID Offset:  0x68 Reset:  0x00000000 Bit 31 30 29 28 27 26 25 24 TAMPEVT Access R/W Reset 0 Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 TAMPID3 TAMPID2 TAMPID1 TAMPID0 Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 31 – TAMPEVT Tamper Event Detected Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the tamper detection bit. Value Description 0 A tamper input event has not been detected 1 A tamper input event has been detected Bits 0, 1, 2, 3 – TAMPID Tamper on Channel n Detected Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the tamper detection bit. Value Description 0 A tamper condition has not been detected on Channel n 1 A tamper condition has been detected on Channel n SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 474 27.12.17 Tamper Control B Name:  TAMPCTRLB Offset:  0x6C Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 ALSI3 ALSI2 ALSI1 ALSI0 Access R/W R/W R/W R/W Reset 0 0 0 0 Bits 0, 1, 2, 3 – ALSI Active Layer Internal Select n Value Description 0 Active layer Protection is monitoring the RTC signal using INn and OUTn tamper pins 1 Active layer Protection is monitoring the RTC signal on the TrustRAM shield SAM L10/L11 Family RTC – Real-Time Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 475 28. DMAC – Direct Memory Access Controller 28.1 Overview The Direct Memory Access Controller (DMAC) contains both a Direct Memory Access engine and a Cyclic Redundancy Check (CRC) engine. The DMAC can transfer data between memories and peripherals, and thus off-load these tasks from the CPU. It enables high data transfer rates with minimum CPU intervention, and frees up CPU time. With access to all peripherals, the DMAC can handle automatic transfer of data between communication modules. The DMA part of the DMAC has several DMA channels which all can receive different types of transfer triggers to generate transfer requests from the DMA channels to the arbiter, see also the Block Diagram. The arbiter will grant one DMA channel at a time to act as the active channel. When an active channel has been granted, the fetch engine of the DMAC will fetch a transfer descriptor from the SRAM and store it in the internal memory of the active channel, which will execute the data transmission. An ongoing data transfer of an active channel can be interrupted by a higher prioritized DMA channel. The DMAC will write back the updated transfer descriptor from the internal memory of the active channel to SRAM, and grant the higher prioritized channel to start transfer as the new active channel. Once a DMA channel is done with its transfer, interrupts and events can be generated optionally. The DMAC has four bus interfaces: • The data transfer bus is used for performing the actual DMA transfer. • The AHB/APB Bridge bus is used when writing and reading the I/O registers of the DMAC. • The descriptor fetch bus is used by the fetch engine to fetch transfer descriptors before data transfer can be started or continued. • The write-back bus is used to write the transfer descriptor back to SRAM. All buses are AHB master interfaces but the AHB/APB Bridge bus, which is an APB slave interface. The CRC engine can be used by software to detect an accidental error in the transferred data and to take corrective action, such as requesting the data to be sent again or simply not using the incorrect data. 28.2 Features • Data transfer from: – Peripheral to peripheral – Peripheral to memory – Memory to peripheral – Memory to memory • Transfer trigger sources – Software – Events from Event System – Dedicated requests from peripherals • SRAM based transfer descriptors – Single transfer using one descriptor – Multi-buffer or circular buffer modes by linking multiple descriptors SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 476 • Up to 8 channels – Enable 8 independent transfers – Automatic descriptor fetch for each channel – Suspend/resume operation support for each channel • Flexible arbitration scheme – 4 configurable priority levels for each channel – Fixed or round-robin priority scheme within each priority level • From 1 to 256KB data transfer in a single block transfer • Multiple addressing modes – Static – Configurable increment scheme • Optional interrupt generation – On block transfer complete – On error detection – On channel suspend • 4 event inputs – One event input for each of the 4 least significant DMA channels – Can be selected to trigger normal transfers, periodic transfers or conditional transfers – Can be selected to suspend or resume channel operation • 4 event outputs – One output event for each of the 4 least significant DMA channels – Selectable generation on AHB, block, or transaction transfer complete • Error management supported by write-back function – Dedicated Write-Back memory section for each channel to store ongoing descriptor transfer • CRC polynomial software selectable to – CRC-16 (CRC-CCITT) – CRC-32 (IEEE® 802.3) SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 477 28.3 Block Diagram Figure 28-1. DMAC Block Diagram HIGH SPEED BUS MATRIX AHB/APB Bridge CPU SRAM S S M M Events Channel 0 Channel 1 Channel n Arbiter DMA Channels MASTER Active Channel CRC Engine n Fetch Engine Interrupt / Events DMAC Interrupts Transfer Triggers n Data Transfer Write-back Descriptor Fetch 28.4 Signal Description Not applicable. 28.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 28.5.1 I/O Lines Not applicable. 28.5.2 Power Management The DMAC will continue to operate in any sleep mode where the selected source clock is running. The DMAC’s interrupts can be used to wake up the device from sleep modes. Events connected to the event system can trigger other operations in the system without exiting sleep modes. On hardware or software reset, all registers are set to their reset value. Related Links 22. PM – Power Manager 28.5.3 Clocks The DMAC bus clock (CLK_DMAC_APB) must be configured and enabled in the Main Clock module before using the DMAC. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 478 This bus clock (CLK_DMAC_APB) is always synchronous to the module clock (CLK_DMAC_AHB), but can be divided by a prescaler and may run even when the module clock is turned off. Related Links 19.6.2.6 Peripheral Clock Masking 28.5.4 DMA Not applicable. 28.5.5 Interrupts The interrupt request line is connected to the interrupt controller. Using the DMAC interrupt requires the interrupt controller to be configured first. 28.5.6 Events The events are connected to the event system. Related Links 33. EVSYS – Event System 28.5.7 Debug Operation When the CPU is halted in debug mode the DMAC will halt normal operation. The DMAC can be forced to continue operation during debugging. Refer to 28.8.6 DBGCTRL for details. 28.5.8 Register Access Protection All registers with write-access can be write-protected optionally by the Peripheral Access Controller (PAC), except for the following registers: • Interrupt Pending register (INTPEND) • Channel ID register (CHID) • Channel Interrupt Flag Status and Clear register (CHINTFLAG) Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. PAC write-protection does not apply to accesses through an external debugger. Related Links 15. PAC - Peripheral Access Controller 28.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 28.5.10 Analog Connections Not applicable. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 479 28.6 Functional Description 28.6.1 Principle of Operation The DMAC consists of a DMA module and a CRC module. 28.6.1.1 DMA The DMAC can transfer data between memories and peripherals without interaction from the CPU. The data transferred by the DMAC are called transactions, and these transactions can be split into smaller data transfers. The following figure shows the relationship between the different transfer sizes: Figure 28-2. DMA Transfer Sizes DMA transaction Block transfer Link Enabled Burst transfer Link Enabled Link Enabled Beat transfer • Beat transfer: The size of one data transfer bus access, and the size is selected by writing the Beat Size bit group in the Block Transfer Control register (BTCTRL.BEATSIZE) • Block transfer: The amount of data one transfer descriptor can transfer, and the amount can range from 1 to 64k beats. A block transfer can be interrupted. • Transaction: The DMAC can link several transfer descriptors by having the first descriptor pointing to the second and so forth, as shown in the figure above. A DMA transaction is the complete transfer of all blocks within a linked list. A transfer descriptor describes how a block transfer should be carried out by the DMAC, and it must remain in SRAM. For further details on the transfer descriptor refer to 28.6.2.3 Transfer Descriptors. The figure above shows several block transfers linked together, which are called linked descriptors. For further information about linked descriptors, refer to 28.6.3.1 Linked Descriptors. A DMA transfer is initiated by an incoming transfer trigger on one of the DMA channels. This trigger can be configured to be either a software trigger, an event trigger, or one of the dedicated peripheral triggers. The transfer trigger will result in a DMA transfer request from the specific channel to the arbiter. If there are several DMA channels with pending transfer requests, the arbiter chooses which channel is granted access to become the active channel. The DMA channel granted access as the active channel will carry out the transaction as configured in the transfer descriptor. A current transaction can be interrupted by a higher prioritized channel, but will resume the block transfer when the according DMA channel is granted access as the active channel again. For each beat transfer, an optional output event can be generated. For each block transfer, optional interrupts and an optional output event can be generated. When a transaction is completed, dependent of the configuration, the DMA channel will either be suspended or disabled. 28.6.1.2 CRC The internal CRC engine supports two commonly used CRC polynomials: CRC-16 (CRC-CCITT) and CRC-32 (IEEE 802.3). It can be used on a selectable DMA channel, or on the I/O interface. Refer to 28.6.3.7 CRC Operation for details. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 480 28.6.2 Basic Operation 28.6.2.1 Initialization The following DMAC registers are enable-protected, meaning that they can only be written when the DMAC is disabled (CTRL.DMAENABLE=0): • Descriptor Base Memory Address register (BASEADDR) • Write-Back Memory Base Address register (WRBADDR) The following DMAC bit is enable-protected, meaning that it can only be written when both the DMAC and CRC are disabled (CTRL.DMAENABLE=0 and CTRL.CRCENABLE=0): • Software Reset bit in Control register (CTRL.SWRST) The following DMA channel register is enable-protected, meaning that it can only be written when the corresponding DMA channel is disabled (CHCTRLA.ENABLE=0): • Channel Control B (CHCTRLB) register, except the Command bit (CHCTRLB.CMD) and the Channel Arbitration Level bit (CHCTRLB.LVL) The following DMA channel bit is enable-protected, meaning that it can only be written when the corresponding DMA channel is disabled: • Channel Software Reset bit in Channel Control A register (CHCTRLA.SWRST) The following CRC registers are enable-protected, meaning that they can only be written when the CRC is disabled (CTRL.CRCENABLE=0): • CRC Control register (CRCCTRL) • CRC Checksum register (CRCCHKSUM) Enable-protection is denoted by the "Enable-Protected" property in the register description. Before the DMAC is enabled it must be configured, as outlined by the following steps: • The SRAM address of where the descriptor memory section is located must be written to the Description Base Address (BASEADDR) register • The SRAM address of where the write-back section should be located must be written to the WriteBack Memory Base Address (WRBADDR) register • Priority level x of the arbiter can be enabled by setting the Priority Level x Enable bit in the Control register (CTRL.LVLENx=1) Before a DMA channel is enabled, the DMA channel and the corresponding first transfer descriptor must be configured, as outlined by the following steps: • DMA channel configurations – The channel number of the DMA channel to configure must be written to the Channel ID (CHID) register – Trigger action must be selected by writing the Trigger Action bit group in the Channel Control B register (CHCTRLB.TRIGACT) – Trigger source must be selected by writing the Trigger Source bit group in the Channel Control B register (CHCTRLB.TRIGSRC) • Transfer Descriptor – The size of each access of the data transfer bus must be selected by writing the Beat Size bit group in the Block Transfer Control register (BTCTRL.BEATSIZE) SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 481 – The transfer descriptor must be made valid by writing a one to the Valid bit in the Block Transfer Control register (BTCTRL.VALID) – Number of beats in the block transfer must be selected by writing the Block Transfer Count (BTCNT) register – Source address for the block transfer must be selected by writing the Block Transfer Source Address (SRCADDR) register – Destination address for the block transfer must be selected by writing the Block Transfer Destination Address (DSTADDR) register If CRC calculation is needed, the CRC engine must be configured before it is enabled, as outlined by the following steps: • The CRC input source must selected by writing the CRC Input Source bit group in the CRC Control register (CRCCTRL.CRCSRC) • The type of CRC calculation must be selected by writing the CRC Polynomial Type bit group in the CRC Control register (CRCCTRL.CRCPOLY) • If I/O is selected as input source, the beat size must be selected by writing the CRC Beat Size bit group in the CRC Control register (CRCCTRL.CRCBEATSIZE) 28.6.2.2 Enabling, Disabling, and Resetting The DMAC is enabled by writing the DMA Enable bit in the Control register (CTRL.DMAENABLE) to '1'. The DMAC is disabled by writing a '0' to CTRL.DMAENABLE. A DMA channel is enabled by writing the Enable bit in the Channel Control A register (CHCTRLA.ENABLE) to '1', after writing the corresponding channel id to the Channel ID bit group in the Channel ID register (CHID.ID). A DMA channel is disabled by writing a '0' to CHCTRLA.ENABLE. The CRC is enabled by writing a '1' to the CRC Enable bit in the Control register (CTRL.CRCENABLE). The CRC is disabled by writing a '0' to CTRL.CRCENABLE. The DMAC is reset by writing a '1' to the Software Reset bit in the Control register (CTRL.SWRST) while the DMAC and CRC are disabled. All registers in the DMAC except DBGCTRL will be reset to their initial state. A DMA channel is reset by writing a '1' to the Software Reset bit in the Channel Control A register (CHCTRLA.SWRST), after writing the corresponding channel id to the Channel ID bit group in the Channel ID register (CHID.ID). The channel registers will be reset to their initial state. The corresponding DMA channel must be disabled in order for the reset to take effect. 28.6.2.3 Transfer Descriptors Together with the channel configurations the transfer descriptors decides how a block transfer should be executed. Before a DMA channel is enabled (CHCTRLA.ENABLE is written to one), and receives a transfer trigger, its first transfer descriptor has to be initialized and valid (BTCTRL.VALID). The first transfer descriptor describes the first block transfer of a transaction. All transfer descriptors must reside in SRAM. The addresses stored in the Descriptor Memory Section Base Address (BASEADDR) and Write-Back Memory Section Base Address (WRBADDR) registers tell the DMAC where to find the descriptor memory section and the write-back memory section. The descriptor memory section is where the DMAC expects to find the first transfer descriptors for all DMA channels. As BASEADDR points only to the first transfer descriptor of channel 0 (see figure below), all first transfer descriptors must be stored in a contiguous memory section, where the transfer descriptors must be ordered according to their channel number. For further details on linked descriptors, refer to 28.6.3.1 Linked Descriptors. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 482 The write-back memory section is the section where the DMAC stores the transfer descriptors for the ongoing block transfers. WRBADDR points to the ongoing transfer descriptor of channel 0. All ongoing transfer descriptors will be stored in a contiguous memory section where the transfer descriptors are ordered according to their channel number. The figure below shows an example of linked descriptors on DMA channel 0. For further details on linked descriptors, refer to 28.6.3.1 Linked Descriptors. Figure 28-3. Memory Sections Channel 0 – Descriptor n-1 Channel 0 – Last Descriptor DESCADDR DESCADDR Device Memory Space BASEADDR Channel 0 – First Descriptor Channel 1 – First Descriptor Channel 2 – First Descriptor Channel n – First Descriptor Descriptor Section WRBADDR Channel 0 Ongoing Descriptor Channel 1 Ongoing Descriptor Channel 2 Ongoing Descriptor Channel n Ongoing Descriptor Write-Back Section Undefined Undefined Undefined Undefined Undefined SRCADDR DSTADDR BTCTRL DESCADDR BTCNT SRCADDR DSTADDR BTCTRL DESCADDR BTCNT SRCADDR DSTADDR BTCTRL 0x00000000 BTCNT The size of the descriptor and write-back memory sections is dependent on the number of the most significant enabled DMA channel m, as shown below: 1 ݉ + ڄ 128bits݁ = ݖ݅ܵ For memory optimization, it is recommended to always use the less significant DMA channels if not all channels are required. The descriptor and write-back memory sections can either be two separate memory sections, or they can share memory section (BASEADDR=WRBADDR). The benefit of having them in two separate sections, is that the same transaction for a channel can be repeated without having to modify the first transfer descriptor. The benefit of having descriptor memory and write-back memory in the same section is that it requires less SRAM. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 483 28.6.2.4 Arbitration If a DMA channel is enabled and not suspended when it receives a transfer trigger, it will send a transfer request to the arbiter. When the arbiter receives the transfer request it will include the DMA channel in the queue of channels having pending transfers, and the corresponding Pending Channel x bit in the Pending Channels registers (PENDCH.PENDCHx) will be set. Depending on the arbitration scheme, the arbiter will choose which DMA channel will be the next active channel. The active channel is the DMA channel being granted access to perform its next transfer. When the arbiter has granted a DMA channel access to the DMAC, the corresponding bit PENDCH.PENDCHx will be cleared. See also the following figure. If the upcoming transfer is the first for the transfer request, the corresponding Busy Channel x bit in the Busy Channels register will be set (BUSYCH.BUSYCHx=1), and it will remain '1' for the subsequent granted transfers. When the channel has performed its granted transfer(s) it will be either fed into the queue of channels with pending transfers, set to be waiting for a new transfer trigger, suspended, or disabled. This depends on the channel and block transfer configuration. If the DMA channel is fed into the queue of channels with pending transfers, the corresponding BUSYCH.BUSYCHx will remain '1'. If the DMA channel is set to wait for a new transfer trigger, suspended, or disabled, the corresponding BUSYCH.BUSYCHx will be cleared. If a DMA channel is suspended while it has a pending transfer, it will be removed from the queue of pending channels, but the corresponding PENDCH.PENDCHx will remain set. When the same DMA channel is resumed, it will be added to the queue of pending channels again. If a DMA channel gets disabled (CHCTRLA.ENABLE=0) while it has a pending transfer, it will be removed from the queue of pending channels, and the corresponding PENDCH.PENDCHx will be cleared. Figure 28-4. Arbiter Overview Channel 0 Channel N Active Channel Priority decoder Active.LVLEXx PRICTRLx.LVLPRI Arbiter CTRL.LVLENx Burst Done Transfer Request Channel Number Level Enable Channel Burst Done Channel Priority Level Channel Pending Channel Suspend Channel Burst Done Channel Priority Level Channel Pending Channel Suspend Priority Levels When a channel level is pending or the channel is transferring data, the corresponding Level Executing bit is set in the Active Channel and Levels register (ACTIVE.LVLEXx). Each DMA channel supports a 4-level priority scheme. The priority level for a channel is configured by writing to the Channel Arbitration Level bit group in the Channel Control B register (CHCTRLB.LVL). As long as all priority levels are enabled, a channel with a higher priority level number will have priority over a channel with a lower priority level number. Each priority level x is enabled by setting the corresponding Priority Level x Enable bit in the Control register (CTRL.LVLENx=1). SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 484 Within each priority level the DMAC's arbiter can be configured to prioritize statically or dynamically: Static Arbitration within a priority level is selected by writing a '0' to the Level x Round-Robin Scheduling Enable bit in the Priority Control 0 register (PRICTRL0.RRLVLENx). When static arbitration is selected, the arbiter will prioritize a low channel number over a high channel number as shown in the figure below. When using the static arbitration there is a risk of high channel numbers never being granted access as the active channel. This can be avoided using a dynamic arbitration scheme. Figure 28-5. Static Priority Scheduling Highest Channel Lowest Channel Highest Priority Channel N Lowest Priority Channel 0 Channel x+1 Channel x . . . . . . Dynamic Arbitration within a priority level is selected by writing a '1' to PRICTRL0.RRLVLENx. The dynamic arbitration scheme in the DMAC is round-robin. With the round-robin scheme, the channel number of the last channel being granted access will have the lowest priority the next time the arbiter has to grant access to a channel within the same priority level, as shown in Figure 28-6. The channel number of the last channel being granted access as the active channel is stored in the Level x Channel Priority Number bit group in the Priority Control 0 register (PRICTRL0.LVLPRIx) for the corresponding priority level. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 485 Figure 28-6. Dynamic (Round-Robin) Priority Scheduling Channel N Channel N Channel 0 Channel x Channel x+1 Channel x last acknowledge request Channel (x+1) last acknowledge request Channel 0 Channel x Channel x+1 Channel x+2 Lowest Priority Highest Priority Highest Priority Lowest Priority . . . . . . 28.6.2.5 Data Transmission Before the DMAC can perform a data transmission, a DMA channel has to be configured and enabled, its corresponding transfer descriptor has to be initialized, and the arbiter has to grant the DMA channel access as the active channel. Once the arbiter has granted a DMA channel access as the active channel (refer to DMA Block Diagram section) the transfer descriptor for the DMA channel will be fetched from SRAM using the fetch bus, and stored in the internal memory for the active channel. For a new block transfer, the transfer descriptor will be fetched from the descriptor memory section (BASEADDR); For an ongoing block transfer, the descriptor will be fetched from the write-back memory section (WRBADDR). By using the data transfer bus, the DMAC will read the data from the current source address and write it to the current destination address. For further details on how the current source and destination addresses are calculated, refer to the section on Addressing. The arbitration procedure is performed after each transfer. If the current DMA channel is granted access again, the block transfer counter (BTCNT) of the internal transfer descriptor will be decremented by the number of beats in a transfer, the optional output event Beat will be generated if configured and enabled, and the active channel will perform a new transfer. If a different DMA channel than the current active channel is granted access, the block transfer counter value will be written to the write-back section before the transfer descriptor of the newly granted DMA channel is fetched into the internal memory of the active channel. When a block transfer has come to its end (BTCNT is zero), the Valid bit in the Block Transfer Control register will be cleared (BTCTRL.VALID=0) before the entire transfer descriptor is written to the writeback memory. The optional interrupts, Channel Transfer Complete and Channel Suspend, and the optional output event Block, will be generated if configured and enabled. After the last block transfer in a transaction, the Next Descriptor Address register (DESCADDR) will hold the value 0x00000000, and the DMA channel will either be suspended or disabled, depending on the configuration in the Block Action bit group in the Block Transfer Control register (BTCTRL.BLOCKACT). If the transaction has further block transfers pending, DESCADDR will hold the SRAM address to the next transfer descriptor to be fetched. The DMAC will fetch the next descriptor into the internal memory of the active channel and write its content to the write-back section for the channel, before the arbiter gets to choose the next active channel. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 486 28.6.2.6 Transfer Triggers and Actions A DMA transfer through a DMA channel can be started only when a DMA transfer request is detected, and the DMA channel has been granted access to the DMA. A transfer request can be triggered from software, from a peripheral, or from an event. There are dedicated Trigger Source selections for each DMA Channel Control B (CHCTRLB.TRIGSRC). The trigger actions are available in the Trigger Action bit group in the Channel Control B register (CHCTRLB.TRIGACT). By default, a trigger generates a request for a block transfer operation. If a single descriptor is defined for a channel, the channel is automatically disabled when a block transfer has been completed. If a list of linked descriptors is defined for a channel, the channel is automatically disabled when the last descriptor in the list is executed. If the list still has descriptors to execute, the channel will be waiting for the next block transfer trigger. When enabled again, the channel will wait for the next block transfer trigger. The trigger actions can also be configured to generate a request for a beat transfer (CHCTRLB.TRIGACT=0x2) or transaction transfer (CHCTRLB.TRIGACT=0x3) instead of a block transfer (CHCTRLB.TRIGACT=0x0). Figure 28-7 shows an example where triggers are used with two linked block descriptors. Figure 28-7. Trigger Action and Transfers CHENn Trigger PENDCHn BUSYCHn Data Transfer CHENn Trigger PENDCHn BUSYCHn Data Transfer CHENn Trigger PENDCHn BUSYCHn Data Transfer Block Transfer Block Transfer Block Transfer Block Transfer Block Transfer Block Transfer Trigger Lost Trigger Lost Trigger Lost Transaction Trigger Action Block Trigger Action Beat Trigger Action BEAT BEAT BEAT BEAT BEAT BEAT BEAT BEAT BEAT BEAT BEAT BEAT BEAT BEAT BEAT BEAT BEAT BEAT If the trigger source generates a transfer request for a channel during an ongoing transfer, the new transfer request will be kept pending (CHSTATUS.PEND=1), and the new transfer can start after the SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 487 ongoing one is done. Only one pending transfer can be kept per channel. If the trigger source generates more transfer requests while one is already pending, the additional ones will be lost. All channels pending status flags are also available in the Pending Channels register (PENDCH). When the transfer starts, the corresponding Channel Busy status flag is set in Channel Status register (CHSTATUS.BUSY). When the trigger action is complete, the Channel Busy status flag is cleared. All channel busy status flags are also available in the Busy Channels register (BUSYCH) in DMAC. 28.6.2.7 Addressing Each block transfer needs to have both a source address and a destination address defined. The source address is set by writing the Transfer Source Address (SRCADDR) register, the destination address is set by writing the Transfer Destination Address (SRCADDR) register. The addressing of this DMAC module can be static or incremental, for either source or destination of a block transfer, or both. Incrementation for the source address of a block transfer is enabled by writing the Source Address Incrementation Enable bit in the Block Transfer Control register (BTCTRL.SRCINC=1). The step size of the incrementation is configurable and can be chosen by writing the Step Selection bit in the Block Transfer Control register (BTCTRL.STEPSEL=1) and writing the desired step size in the Address Increment Step Size bit group in the Block Transfer Control register (BTCTRL.STEPSIZE). If BTCTRL.STEPSEL=0, the step size for the source incrementation will be the size of one beat. When source address incrementation is configured (BTCTRL.SRCINC=1), SRCADDR is calculated as follows: If BTCTRL.STEPSEL=1: 2 ڄ 1 + ܧܼܫܵܶܣܧܤ ڄ ܶܰܥܶܤ + ܴܶܣܶܵSRCADDR = SRCADDR STEPSIZE If BTCTRL.STEPSEL=0: 1 + ܧܼܫܵܶܣܧܤ ڄ ܶܰܥܶܤ + ܴܶܣܶܵSRCADDR = SRCADDR • SRCADDRSTART is the source address of the first beat transfer in the block transfer • BTCNT is the initial number of beats remaining in the block transfer • BEATSIZE is the configured number of bytes in a beat • STEPSIZE is the configured number of beats for each incrementation The following figure shows an example where DMA channel 0 is configured to increment the source address by one beat after each beat transfer (BTCTRL.SRCINC=1), and DMA channel 1 is configured to increment the source address by two beats (BTCTRL.SRCINC=1, BTCTRL.STEPSEL=1, and BTCTRL.STEPSIZE=0x1). As the destination address for both channels are peripherals, destination incrementation is disabled (BTCTRL.DSTINC=0). SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 488 Figure 28-8. Source Address Increment SRC Data Buffer a b c d e f Incrementation for the destination address of a block transfer is enabled by setting the Destination Address Incrementation Enable bit in the Block Transfer Control register (BTCTRL.DSTINC=1). The step size of the incrementation is configurable by clearing BTCTRL.STEPSEL=0 and writing BTCTRL.STEPSIZE to the desired step size. If BTCTRL.STEPSEL=1, the step size for the destination incrementation will be the size of one beat. When the destination address incrementation is configured (BTCTRL.DSTINC=1), DSTADDR must be set and calculated as follows: zero is STEPSEL.BTCTRL where ܧܼܫܵܲܧܶܵ2 • 1 + ܧܼܫܵܶܣܧܤ • ܶܰܥܶܤ + ܴܶܣܴܶܵܦܦܣܶܵܦ = ܴܦܦܣܶܵܦ one is STEPSEL.BTCTRL where 1 + ܧܼܫܵܶܣܧܤ • ܶܰܥܶܤ + ܴܶܣܴܶܵܦܦܣܶܵܦ = ܴܦܦܣܶܵܦ • DSTADDRSTART is the destination address of the first beat transfer in the block transfer • BTCNT is the initial number of beats remaining in the block transfer • BEATSIZE is the configured number of bytes in a beat • STEPSIZE is the configured number of beats for each incrementation The followiong figure shows an example where DMA channel 0 is configured to increment destination address by one beat (BTCTRL.DSTINC=1) and DMA channel 1 is configured to increment destination address by two beats (BTCTRL.DSTINC=1, BTCTRL.STEPSEL=0, and BTCTRL.STEPSIZE=0x1). As the source address for both channels are peripherals, source incrementation is disabled (BTCTRL.SRCINC=0). SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 489 Figure 28-9. Destination Address Increment DST Data Buffer a b c d 28.6.2.8 Error Handling If a bus error is received from an AHB slave during a DMA data transfer, the corresponding active channel is disabled and the corresponding Channel Transfer Error Interrupt flag in the Channel Interrupt Status and Clear register (CHINTFLAG.TERR) is set. If enabled, the optional transfer error interrupt is generated. The transfer counter will not be decremented and its current value is written-back in the writeback memory section before the channel is disabled. When the DMAC fetches an invalid descriptor (BTCTRL.VALID=0) or when the channel is resumed and the DMA fetches the next descriptor with null address (DESCADDR=0x00000000), the corresponding channel operation is suspended, the Channel Suspend Interrupt Flag in the Channel Interrupt Flag Status and Clear register (CHINTFLAG.SUSP) is set, and the Channel Fetch Error bit in the Channel Status register (CHSTATUS.FERR) is set. If enabled, the optional suspend interrupt is generated. 28.6.3 Additional Features 28.6.3.1 Linked Descriptors A transaction can consist of either a single block transfer or of several block transfers. When a transaction consists of several block transfers it is done with the help of linked descriptors. Figure 28-3 illustrates how linked descriptors work. When the first block transfer is completed on DMA channel 0, the DMAC fetches the next transfer descriptor, which is pointed to by the value stored in the Next Descriptor Address (DESCADDR) register of the first transfer descriptor. Fetching the next transfer descriptor (DESCADDR) is continued until the last transfer descriptor. When the block transfer for the last transfer descriptor is executed and DESCADDR=0x00000000, the transaction is terminated. For further details on how the next descriptor is fetched from SRAM, refer to section 28.6.2.5 Data Transmission. 28.6.3.1.1 Adding Descriptor to the End of a List To add a new descriptor at the end of the descriptor list, create the descriptor in SRAM, with DESCADDR=0x00000000 indicating that it is the new last descriptor in the list, and modify the DESCADDR value of the current last descriptor to the address of the newly created descriptor. 28.6.3.1.2 Modifying a Descriptor in a List In order to add descriptors to a linked list, the following actions must be performed: 1. Enable the Suspend interrupt for the DMA channel. 2. Enable the DMA channel. 3. Reserve memory space in SRAM to configure a new descriptor. 4. Configure the new descriptor: SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 490 – Set the next descriptor address (DESCADDR) – Set the destination address (DSTADDR) – Set the source address (SRCADDR) – Configure the block transfer control (BTCTRL) including • Optionally enable the Suspend block action • Set the descriptor VALID bit 5. Clear the VALID bit for the existing list and for the descriptor which has to be updated. 6. Read DESCADDR from the Write-Back memory. – If the DMA has not already fetched the descriptor which requires changes (i.e., DESCADDR is wrong): • Update the DESCADDR location of the descriptor from the List • Optionally clear the Suspend block action • Set the descriptor VALID bit to '1' • Optionally enable the Resume software command – If the DMA is executing the same descriptor as the one which requires changes: • Set the Channel Suspend software command and wait for the Suspend interrupt • Update the next descriptor address (DESCRADDR) in the write-back memory • Clear the interrupt sources and set the Resume software command • Update the DESCADDR location of the descriptor from the List • Optionally clear the Suspend block action • Set the descriptor VALID bit to '1' 7. Go to step 4 if needed. 28.6.3.1.3 Adding a Descriptor Between Existing Descriptors To insert a new descriptor 'C' between two existing descriptors ('A' and 'B'), the descriptor currently executed by the DMA must be identified. 1. If DMA is executing descriptor B, descriptor C cannot be inserted. 2. If DMA has not started to execute descriptor A, follow the steps: 2.1. Set the descriptor A VALID bit to '0'. 2.2. Set the DESCADDR value of descriptor A to point to descriptor C instead of descriptor B. 2.3. Set the DESCADDR value of descriptor C to point to descriptor B. 2.4. Set the descriptor A VALID bit to '1'. 3. If DMA is executing descriptor A: 3.1. Apply the software suspend command to the channel and 3.2. Perform steps 2.1 through 2.4. 3.3. Apply the software resume command to the channel. 28.6.3.2 Channel Suspend The channel operation can be suspended at any time by software by writing a '1' to the Suspend command in the Command bit field of Channel Control B register (CHCTRLB.CMD). After the ongoing burst transfer is completed, the channel operation is suspended and the suspend command is automatically cleared. When suspended, the Channel Suspend Interrupt flag in the Channel Interrupt Status and Clear register is set (CHINTFLAG.SUSP=1) and the optional suspend interrupt is generated. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 491 By configuring the block action to suspend by writing Block Action bit group in the Block Transfer Control register (BTCTRL.BLOCKACT is 0x2 or 0x3), the DMA channel will be suspended after it has completed a block transfer. The DMA channel will be kept enabled and will be able to receive transfer triggers, but it will be removed from the arbitration scheme. If an invalid transfer descriptor (BTCTRL.VALID=0) is fetched from SRAM, the DMA channel will be suspended, and the Channel Fetch Error bit in the Channel Status register(CHASTATUS.FERR) will be set. Note:  Only enabled DMA channels can be suspended. If a channel is disabled when it is attempted to be suspended, the internal suspend command will be ignored. For more details on transfer descriptors, refer to section 28.6.2.3 Transfer Descriptors. 28.6.3.3 Channel Resume and Next Suspend Skip A channel operation can be resumed by software by setting the Resume command in the Command bit field of the Channel Control B register (CHCTRLB.CMD). If the channel is already suspended, the channel operation resumes from where it previously stopped when the Resume command is detected. When the Resume command is issued before the channel is suspended, the next suspend action is skipped and the channel continues the normal operation. Figure 28-10. Channel Suspend/Resume Operation CHENn Memory Descriptor Transfer Resume Command Descriptor 0 (suspend disabled) Fetch Block Transfer 0 Descriptor 1 (suspend enabled) Block Transfer 1 Suspend skipped Descriptor 2 (suspend enabled) Block Transfer 2 Channel suspended Descriptor 3 (last) Block Transfer 3 28.6.3.4 Event Input Actions The event input actions are available only on the four least significant DMA channels. For details on channels with event input support, refer to the in the Event system documentation. Before using event input actions, the event controller must be configured first according to the following table, and the Channel Event Input Enable bit in the Channel Control B register (CHCTRLB.EVIE) must be written to '1'. Refer also to 28.6.6 Events. Table 28-1. Event Input Action Action CHCTRLB.EVACT CHCTRLB.TRGSRC None NOACT - Normal Transfer TRIG DISABLE Conditional Transfer on Strobe TRIG any peripheral Conditional Transfer CTRIG Conditional Block Transfer CBLOCK Channel Suspend SUSPEND Channel Resume RESUME Skip Next Block Suspend SSKIP SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 492 Normal Transfer The event input is used to trigger a beat or burst transfer on peripherals. The event is acknowledged as soon as the event is received. When received, both the Channel Pending status bit in the Channel Status register (CHSTATUS.PEND) and the corresponding Channel n bit in the Pending Channels register (28.8.13 PENDCH.PENDCHn) are set. If the event is received while the channel is pending, the event trigger is lost. The figure below shows an example where beat transfers are enabled by internal events. Figure 28-11. Beat Event Trigger Action CHENn Peripheral Trigger Event PENDCHn BUSYCHn Data Transfer Trigger Lost Block Transfer BEAT BEAT BEAT BEAT BEAT BEAT Block Transfer Conditional Transfer on Strobe The event input is used to trigger a transfer on peripherals with pending transfer requests. This event action is intended to be used with peripheral triggers, e.g. for timed communication protocols or periodic transfers between peripherals: only when the peripheral trigger coincides with the occurrence of a (possibly cyclic) event the transfer is issued. The event is acknowledged as soon as the event is received. The peripheral trigger request is stored internally when the previous trigger action is completed (i.e. the channel is not pending) and when an active event is received. If the peripheral trigger is active, the DMA will wait for an event before the peripheral trigger is internally registered. When both event and peripheral transfer trigger are active, both CHSTATUS.PEND and 28.8.13 PENDCH.PENDCHn are set. A software trigger will now trigger a transfer. The figure below shows an example where the peripheral beat transfer is started by a conditional strobe event action. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 493 Figure 28-12. Periodic Event with Beat Peripheral Triggers Event Peripheral Trigger PENDCHn Data Transfer Trigger Lost Trigger Lost Block Transfer BEAT Conditional Transfer The event input is used to trigger a conditional transfer on peripherals with pending transfer requests. As example, this type of event can be used for peripheral-to-peripheral transfers, where one peripheral is the source of event and the second peripheral is the source of the trigger. Each peripheral trigger is stored internally when the event is received. When the peripheral trigger is stored internally, the Channel Pending status bit is set (CHSTATUS.PEND), the respective Pending Channel n Bit in the Pending Channels register is set (28.8.13 PENDCH.PENDCHn), and the event is acknowledged. A software trigger will now trigger a transfer. The figure below shows an example where conditional event is enabled with peripheral beat trigger requests. Figure 28-13. Conditional Event with Beat Peripheral Triggers Event Peripheral Trigger PENDCHn Data Transfer Block Transfer BEAT BEAT Conditional Block Transfer The event input is used to trigger a conditional block transfer on peripherals. Before starting transfers within a block, an event must be received. When received, the event is acknowledged when the block transfer is completed. A software trigger will trigger a transfer. The figure below shows an example where conditional event block transfer is started with peripheral beat trigger requests. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 494 Figure 28-14. Conditional Block Transfer with Beat Peripheral Triggers BEAT BEAT Block Transfer BEAT BEAT Block Transfer Data Transfer Peripheral Trigger Event PENDCHn Channel Suspend The event input is used to suspend an ongoing channel operation. The event is acknowledged when the current AHB access is completed. For further details on Channel Suspend, refer to 28.6.3.2 Channel Suspend. Channel Resume The event input is used to resume a suspended channel operation. The event is acknowledged as soon as the event is received and the Channel Suspend Interrupt Flag (CHINTFLAG.SUSP) is cleared. For further details refer to 28.6.3.2 Channel Suspend. Skip Next Block Suspend This event can be used to skip the next block suspend action. If the channel is suspended before the event rises, the channel operation is resumed and the event is acknowledged. If the event rises before a suspend block action is detected, the event is kept until the next block suspend detection. When the block transfer is completed, the channel continues the operation (not suspended) and the event is acknowledged. 28.6.3.5 Event Output Selection Event output selection is available only for the four least significant DMA channels. The pulse width of an event output from a channel is one AHB clock cycle. The output of channel events is enabled by writing a '1' to the Channel Event Output Enable bit in the Control B register (CHCTRLB.EVOE). The event output cause is selected by writing to the Event Output Selection bits in the Block Transfer Control register (BTCTRL.EVOSEL). It is possible to generate events after each block transfer (BTCTRL.EVOSEL=0x1) or beat transfer (BTCTRL.EVOSEL=0x3). To enable an event being generated when a transaction is complete, the block event selection must be set in the last transfer descriptor only. The figure Figure 28-15 shows an example where the event output generation is enabled in the first block transfer, and disabled in the second block. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 495 Figure 28-15. Event Output Generation Beat Event Output Data Transfer Event Output Data Transfer Event Output Block Transfer BEAT Block Event Output Block Transfer Block Transfer Block Transfer BEAT BEAT BEAT BEAT BEAT BEAT BEAT 28.6.3.6 Aborting Transfers Transfers on any channel can be aborted gracefully by software by disabling the corresponding DMA channel. It is also possible to abort all ongoing or pending transfers by disabling the DMAC. When a DMA channel disable request or DMAC disable request is detected: • Ongoing transfers of the active channel will be disabled when the ongoing beat transfer is completed and the write-back memory section is updated. This prevents transfer corruption before the channel is disabled. • All other enabled channels will be disabled in the next clock cycle. The corresponding Channel Enable bit in the Channel Control A register is cleared (CHCTRLA.ENABLE=0) when the channel is disabled. The corresponding DMAC Enable bit in the Control register is cleared (CTRL.DMAENABLE=0) when the entire DMAC module is disabled. 28.6.3.7 CRC Operation A cyclic redundancy check (CRC) is an error detection technique used to find errors in data. It is commonly used to determine whether the data during a transmission, or data present in data and program memories has been corrupted or not. 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 data is received, 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. The CRC engine in DMAC supports two commonly used CRC polynomials: CRC-16 (CRC-CCITT) and CRC-32 (IEEE 802.3). Typically, applying CRC-n (CRC-16 or CRC-32) to a data block of arbitrary length will detect any single alteration that is ≤n bits in length, and will detect the fraction 1-2-n of all longer error bursts. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 496 • CRC-16: – Polynomial: x16+ x12+ x5+ 1 – Hex value: 0x1021 • CRC-32: – Polynomial: x32+x26+ x23+ x22+x16+ x12+ x11+ x10+ x8+ x7+ x5+ x4+ x2+ x + 1 – Hex value: 0x04C11DB7 The data source for the CRC engine can either be one of the DMA channels or the APB bus interface, and must be selected by writing to the CRC Input Source bits in the CRC Control register (CRCCTRL.CRCSRC). The CRC engine then takes data input from the selected source and generates a checksum based on these data. The checksum is available in the CRC Checksum register (CRCCHKSUM). When CRC-32 polynomial is used, the final checksum read is bit reversed and complemented, as shown in Figure 28-16. The CRC polynomial is selected by writing to the CRC Polynomial Type bit in the CRC Control register (CRCCTRL.CRCPOLY), the default is CRC-16. The CRC engine operates on byte only. When the DMA is used as data source for the CRC engine, the DMA channel beat size setting will be used. When used with APB bus interface, the application must select the CRC Beat Size bit field of CRC Control register (CRCCTRL.CRCBEATSIZE). 8-, 16-, or 32-bit bus transfer access type is supported. The corresponding number of bytes will be written in the CRCDATAIN register and the CRC engine will operate on the input data in a byte by byte manner. Figure 28-16. CRC Generator Block Diagram 8 16 8 32 Checksum read crc32 CRCCTRL CHECKSUM bit-reverse + complement CRC-16 CRC-32 DMAC Channels CRCDATAIN SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 497 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 engine 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 also be generated on SRAM, Flash, 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 (CRCDATAIN) register in the CRC engine. CRC using the I/O interface Before using the CRC engine with the I/O interface, the application must set the CRC Beat Size bits in the CRC Control register (CRCCTRL.CRCBEATSIZE). 8/16/32-bit bus transfer type can be selected. CRC can be performed on any data by loading them into the CRC engine using the CPU and writing the data to the CRCDATAIN 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. This means if a 32-bit data is written to the CRCDATAIN register the CRC engine takes four cycles to calculate the CRC. The CRC complete is signaled by a set CRCBUSY bit in the CRCSTATUS register. New data can be written only when CRCBUSY flag is not set. 28.6.4 DMA Operation Not applicable. 28.6.5 Interrupts The DMAC channels have the following interrupt sources: • Transfer Complete (TCMPL): Indicates that a block transfer is completed on the corresponding channel. Refer to 28.6.2.5 Data Transmission for details. • Transfer Error (TERR): Indicates that a bus error has occurred during a burst transfer, or that an invalid descriptor has been fetched. Refer to 28.6.2.8 Error Handling for details. • Channel Suspend (SUSP): Indicates that the corresponding channel has been suspended. Refer to 28.6.3.2 Channel Suspend and 28.6.2.5 Data Transmission for details. Each interrupt source has an interrupt flag associated with it. The interrupt flag in the Channel Interrupt Flag Status and Clear (CHINTFLAG) register is set when the interrupt condition occurs. Each interrupt can be individually enabled by setting the corresponding bit in the Channel Interrupt Enable Set register (CHINTENSET=1), and disabled by setting the corresponding bit in the Channel Interrupt Enable Clear register (CHINTENCLR=1). An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until the interrupt flag is cleared, the interrupt is disabled, the DMAC is reset or the corresponding DMA channel is reset. See CHINTFLAG for details on how to clear interrupt flags. All interrupt requests are ORed together on system level to generate one combined interrupt request to the NVIC. The user must read the Channel Interrupt Status (INTSTATUS) register to identify the channels with pending interrupts and must read the Channel Interrupt Flag Status and Clear (CHINTFLAG) register to determine which interrupt condition is present for the corresponding channel. It is also possible to read the Interrupt Pending register (INTPEND), which provides the lowest channel number with pending interrupt and the respective interrupt flags. Note:  Interrupts must be globally enabled for interrupt requests to be generated. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 498 28.6.6 Events The DMAC can generate the following output events: • Channel (CH): Generated when a block transfer for a given channel has been completed, or when a beat transfer within a block transfer for a given channel has been completed. Refer to Event Output Selection for details. Setting the Channel Control B Event Output Enable bit (CHCTRLB.EVOE=1) enables the corresponding output event configured in the Event Output Selection bit group in the Block Transfer Control register (BTCTRL.EVOSEL). Clearing CHCTRLB.EVOE=0 disables the corresponding output event. The DMAC can take the following actions on an input event: • Transfer and Periodic Transfer Trigger (TRIG): normal transfer or periodic transfers on peripherals are enabled • Conditional Transfer Trigger (CTRIG): conditional transfers on peripherals are enabled • Conditional Block Transfer Trigger (CBLOCK): conditional block transfers on peripherals are enabled • Channel Suspend Operation (SUSPEND): suspend a channel operation • Channel Resume Operation (RESUME): resume a suspended channel operation • Skip Next Block Suspend Action (SSKIP): skip the next block suspend transfer condition • Increase Priority (INCPRI): increase channel priority Setting the Channel Control B Event Input Enable bit (CHCTRLB.EVIE=1) enables the corresponding action on input event. Clearing this bit disables the corresponding action on input event. Note that several actions can be enabled for incoming events. If several events are connected to the peripheral, any enabled action will be taken for any of the incoming events. For further details on event input actions, refer to Event Input Actions. Note:  Event input and outputs are not available for every channel. Refer to 28.2 Features for more information. Related Links 33. EVSYS – Event System 28.6.7 Sleep Mode Operation Each DMA channel can be configured to operate in any sleep mode. To be able to run in standby, the RUNSTDBY bit in Channel Control A register (CHCTRLA.RUNSTDBY) must be written to '1'. The DMAC can wake up the device using interrupts from any sleep mode or perform actions through the Event System. For channels with CHCTRLA.RUNSTDBY = 0, it is up to software to stop DMA transfers on these channels and wait for completion before going to standby mode using the following sequence: 1. Suspend the DMAC channels for which CHCTRLA.RUNSTDBY = 0. 2. Check the SYNCBUSY bits of registers accessed by the DMAC channels being suspended. 3. Go to sleep. 4. When the device wakes up, resume the suspended channels. 28.6.8 Synchronization Not applicable. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 499 28.7 Register Summary Offset Name Bit Pos. 0x00 CTRL 7:0 CRCENABLE DMAENABLE SWRST 15:8 LVLENx3 LVLENx2 LVLENx1 LVLENx0 0x02 CRCCTRL 7:0 CRCPOLY[1:0] CRCBEATSIZE[1:0] 15:8 CRCSRC[5:0] 0x04 CRCDATAIN 7:0 CRCDATAIN[7:0] 15:8 CRCDATAIN[15:8] 23:16 CRCDATAIN[23:16] 31:24 CRCDATAIN[31:24] 0x08 CRCCHKSUM 7:0 CRCCHKSUM[7:0] 15:8 CRCCHKSUM[15:8] 23:16 CRCCHKSUM[23:16] 31:24 CRCCHKSUM[31:24] 0x0C CRCSTATUS 7:0 CRCZERO CRCBUSY 0x0D DBGCTRL 7:0 DBGRUN 0x0E QOSCTRL 7:0 DQOS[1:0] FQOS[1:0] WRBQOS[1:0] 0x0F Reserved 0x10 SWTRIGCTRL 7:0 SWTRIGn[6:0] 15:8 23:16 31:24 0x14 PRICTRL0 7:0 RRLVLEN0 LVLPRI0[3:0] 15:8 RRLVLEN1 LVLPRI1[3:0] 23:16 RRLVLEN2 LVLPRI2[3:0] 31:24 RRLVLEN3 LVLPRI3[3:0] 0x18 ... 0x1F Reserved 0x20 INTPEND 7:0 ID[3:0] 15:8 PEND BUSY FERR SUSP TCMPL TERR 0x22 ... 0x23 Reserved 0x24 INTSTATUS 7:0 CHINTn[6:0] 15:8 23:16 31:24 0x28 BUSYCH 7:0 BUSYCHn[6:0] 15:8 23:16 31:24 0x2C PENDCH 7:0 PENDCH7 PENDCH6 PENDCH5 PENDCH4 PENDCH3 PENDCH2 PENDCH1 PENDCH0 15:8 23:16 SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 500 Offset Name Bit Pos. 31:24 0x30 ACTIVE 7:0 LVLEXx LVLEXx LVLEXx LVLEXx 15:8 ABUSY ID[4:0] 23:16 BTCNT[7:0] 31:24 BTCNT[15:8] 0x34 BASEADDR 7:0 BASEADDR[7:0] 15:8 BASEADDR[13:8] 23:16 31:24 0x38 WRBADDR 7:0 WRBADDR[7:0] 15:8 WRBADDR[13:8] 23:16 31:24 0x3C ... 0x3E Reserved 0x3F CHID 7:0 ID[3:0] 0x40 CHCTRLA 7:0 RUNSTDBY ENABLE SWRST 0x41 ... 0x43 Reserved 0x44 CHCTRLB 7:0 LVL[1:0] EVOE EVIE EVACT[2:0] 15:8 TRIGSRC[4:0] 23:16 TRIGACT[1:0] 31:24 CMD[1:0] 0x48 ... 0x4B Reserved 0x4C CHINTENCLR 7:0 SUSP TCMPL TERR 0x4D CHINTENSET 7:0 SUSP TCMPL TERR 0x4E CHINTFLAG 7:0 SUSP TCMPL TERR 0x4F CHSTATUS 7:0 FERR BUSY PEND 28.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to 28.5.8 Register Access Protection. Some registers are enable-protected, meaning they can only be written when the peripheral is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 501 • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 502 28.8.1 Control Name:  CTRL Offset:  0x00 Reset:  0x00X0 Property:  PAC Write-Protection, Enable-Protected Bit 15 14 13 12 11 10 9 8 LVLENx3 LVLENx2 LVLENx1 LVLENx0 Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 6 5 4 3 2 1 0 CRCENABLE DMAENABLE SWRST Access R/W R/W R/W Reset 0 0 0 Bits 8, 9, 10, 11 – LVLENx Priority Level x Enable When this bit is set, all requests with the corresponding level will be fed into the arbiter block. When cleared, all requests with the corresponding level will be ignored. For details on arbitration schemes, refer to the Arbitration section. These bits are not enable-protected. Value Description 0 Transfer requests for Priority level x will not be handled. 1 Transfer requests for Priority level x will be handled. Bit 2 – CRCENABLE CRC Enable Writing a '0' to this bit will disable the CRC calculation when the CRC Status Busy flag is cleared (CRCSTATUS. CRCBUSY). The bit is zero when the CRC is disabled. Writing a '1' to this bit will enable the CRC calculation. Value Description 0 The CRC calculation is disabled. 1 The CRC calculation is enabled. Bit 1 – DMAENABLE DMA Enable Setting this bit will enable the DMA module. Writing a '0' to this bit will disable the DMA module. When writing a '0' during an ongoing transfer, the bit will not be cleared until the internal data transfer buffer is empty and the DMA transfer is aborted. The internal data transfer buffer will be empty once the ongoing burst transfer is completed. This bit is not enable-protected. Value Description 0 The peripheral is disabled. 1 The peripheral is enabled. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 503 Bit 0 – SWRST Software Reset Writing a '0' to this bit has no effect. Writing a '1' to this bit when both the DMAC and the CRC module are disabled (DMAENABLE and CRCENABLE are '0') resets all registers in the DMAC (except DBGCTRL) to their initial state. If either the DMAC or CRC module is enabled, the Reset request will be ignored and the DMAC will return an access error. Value Description 0 There is no Reset operation ongoing. 1 A Reset operation is ongoing. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 504 28.8.2 CRC Control Name:  CRCCTRL Offset:  0x02 Reset:  0x0000 Property:  PAC Write-Protection, Enable-Protected Bit 15 14 13 12 11 10 9 8 CRCSRC[5:0] Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 CRCPOLY[1:0] CRCBEATSIZE[1:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bits 13:8 – CRCSRC[5:0] CRC Input Source These bits select the input source for generating the CRC, as shown in the table below. The selected source is locked until either the CRC generation is completed or the CRC module is disabled. This means the CRCSRC cannot be modified when the CRC operation is ongoing. The lock is signaled by the CRCBUSY status bit. CRC generation complete is generated and signaled from the selected source when used with the DMA channel. Value Name Description 0x00 NOACT No action 0x01 IO I/O interface 0x02-0x 1F - Reserved 0x20 CHN DMA channel 0 0x21 CHN DMA channel 1 0x22 CHN DMA channel 2 0x23 CHN DMA channel 3 0x24 CHN DMA channel 4 0x25 CHN DMA channel 5 0x26 CHN DMA channel 6 0x27 CHN DMA channel 7 0x28 CHN DMA channel 8 0x29 CHN DMA channel 9 0x2A CHN DMA channel 10 0x2B CHN DMA channel 11 0x2C CHN DMA channel 12 0x2D CHN DMA channel 13 0x2E CHN DMA channel 14 0x2F CHN DMA channel 15 0x30 CHN DMA channel 16 0x31 CHN DMA channel 17 0x32 CHN DMA channel 18 SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 505 Value Name Description 0x33 CHN DMA channel 19 0x34 CHN DMA channel 20 0x35 CHN DMA channel 21 0x36 CHN DMA channel 22 0x37 CHN DMA channel 23 0x38 CHN DMA channel 24 0x39 CHN DMA channel 25 0x3A CHN DMA channel 26 0x3B CHN DMA channel 27 0x3C CHN DMA channel 28 0x3D CHN DMA channel 29 0x3E CHN DMA channel 30 0x3F CHN DMA channel 31 Bits 3:2 – CRCPOLY[1:0] CRC Polynomial Type These bits define the size of the data transfer for each bus access when the CRC is used with I/O interface, as shown in the table below. Value Name Description 0x0 CRC16 CRC-16 (CRC-CCITT) 0x1 CRC32 CRC32 (IEEE 802.3) 0x2-0x3 Reserved Bits 1:0 – CRCBEATSIZE[1:0] CRC Beat Size These bits define the size of the data transfer for each bus access when the CRC is used with I/O interface. Value Name Description 0x0 BYTE 8-bit bus transfer 0x1 HWORD 16-bit bus transfer 0x2 WORD 32-bit bus transfer 0x3 Reserved SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 506 28.8.3 CRC Data Input Name:  CRCDATAIN Offset:  0x04 Reset:  0x00000000 Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 CRCDATAIN[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 CRCDATAIN[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 CRCDATAIN[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 CRCDATAIN[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – CRCDATAIN[31:0] CRC Data Input These bits store the data for which the CRC checksum is computed. A new CRC Checksum is ready (CRCBEAT+ 1) clock cycles after the CRCDATAIN register is written. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 507 28.8.4 CRC Checksum Name:  CRCCHKSUM Offset:  0x08 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected The CRCCHKSUM represents the 16- or 32-bit checksum value and the generated CRC. The register is reset to zero by default, but it is possible to reset all bits to one by writing the CRCCHKSUM register directly. It is possible to write this register only when the CRC module is disabled. If CRC-32 is selected and the CRC Status 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 CRCCHKSUM. If CRC-16 is selected or the CRC Status Busy flag is set (i.e., CRC generation is ongoing), CRCCHKSUM will contain the actual content. Bit 31 30 29 28 27 26 25 24 CRCCHKSUM[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 CRCCHKSUM[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 CRCCHKSUM[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 CRCCHKSUM[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – CRCCHKSUM[31:0] CRC Checksum These bits store the generated CRC result. The 16 MSB bits are always read zero when CRC-16 is enabled. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 508 28.8.5 CRC Status Name:  CRCSTATUS Offset:  0x0C Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 CRCZERO CRCBUSY Access R R/W Reset 0 0 Bit 1 – CRCZERO CRC Zero This bit is cleared when a new CRC source is selected. This bit is set when the CRC generation is complete and the CRC Checksum is zero. 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 CRCCHKSUM to read out different versions of the checksum. Bit 0 – CRCBUSY CRC Module Busy This flag is cleared by writing a one to it when used with I/O interface. When used with a DMA channel, the bit is set when the corresponding DMA channel is enabled, and cleared when the corresponding DMA channel is disabled. This register bit cannot be cleared by the application when the CRC is used with a DMA channel. This bit is set when a source configuration is selected and as long as the source is using the CRC module. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 509 28.8.6 Debug Control Name:  DBGCTRL Offset:  0x0D Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DBGRUN Access R/W Reset 0 Bit 0 – DBGRUN Debug Run This bit is not reset by a software reset. This bit controls the functionality when the CPU is halted by an external debugger. Value Description 0 The DMAC is halted when the CPU is halted by an external debugger. 1 The DMAC continues normal operation when the CPU is halted by an external debugger. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 510 28.8.7 Quality of Service Control Name:  QOSCTRL Offset:  0x0E Reset:  0x2A Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DQOS[1:0] FQOS[1:0] WRBQOS[1:0] Access R/W R/W R/W R/W R/W R/W Reset 1 0 1 0 1 0 Bits 5:4 – DQOS[1:0] Data Transfer Quality of Service These bits define the memory priority access during the data transfer operation. DQOS[1:0] Name Description 0x0 DISABLE Background (no sensitive operation) 0x1 LOW Sensitive Bandwidth 0x2 MEDIUM Sensitive Latency 0x3 HIGH Critical Latency Bits 3:2 – FQOS[1:0] Fetch Quality of Service These bits define the memory priority access during the fetch operation. FQOS[1:0] Name Description 0x0 DISABLE Background (no sensitive operation) 0x1 LOW Sensitive Bandwidth 0x2 MEDIUM Sensitive Latency 0x3 HIGH Critical Latency Bits 1:0 – WRBQOS[1:0] Write-Back Quality of Service These bits define the memory priority access during the write-back operation. WRBQOS[1:0] Name Description 0x0 DISABLE Background (no sensitive operation) 0x1 LOW Sensitive Bandwidth 0x2 MEDIUM Sensitive Latency 0x3 HIGH Critical Latency SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 511 28.8.8 Software Trigger Control Name:  SWTRIGCTRL Offset:  0x10 Reset:  0x00000000 Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 SWTRIGn[6:0] Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bits 6:0 – SWTRIGn[6:0] Channel n Software Trigger [n = 7..0] This bit is cleared when the Channel Pending bit in the Channel Status register (CHSTATUS.PEND) for the corresponding channel is either set, or by writing a '1' to it. This bit is set if CHSTATUS.PEND is already '1' when writing a '1' to that bit. Writing a '0' to this bit will clear the bit. Writing a '1' to this bit will generate a DMA software trigger on channel x, if CHSTATUS.PEND=0 for channel x. CHSTATUS.PEND will be set and SWTRIGn will remain cleared. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 512 28.8.9 Priority Control 0 Name:  PRICTRL0 Offset:  0x14 Reset:  0x00000000 Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 RRLVLEN3 LVLPRI3[3:0] Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 RRLVLEN2 LVLPRI2[3:0] Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 RRLVLEN1 LVLPRI1[3:0] Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 RRLVLEN0 LVLPRI0[3:0] Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 31 – RRLVLEN3 Level 3 Round-Robin Arbitration Enable This bit controls which arbitration scheme is selected for DMA channels with priority level 3. For details on arbitration schemes, refer to 28.6.2.4 Arbitration. Value Description 0 Static arbitration scheme for channels with level 3 priority. 1 Round-robin arbitration scheme for channels with level 3 priority. Bits 27:24 – LVLPRI3[3:0] Level 3 Channel Priority Number When round-robin arbitration is enabled (PRICTRL0.RRLVLEN3=1) for priority level 3, this register holds the channel number of the last DMA channel being granted access as the active channel with priority level 3. When static arbitration is enabled (PRICTRL0.RRLVLEN3=0) for priority level 3, and the value of this bit group is non-zero, it will not affect the static priority scheme. This bit group is not reset when round-robin arbitration gets disabled (PRICTRL0.RRLVLEN3 written to '0'). Bit 23 – RRLVLEN2 Level 2 Round-Robin Arbitration Enable This bit controls which arbitration scheme is selected for DMA channels with priority level 2. For details on arbitration schemes, refer to 28.6.2.4 Arbitration. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 513 Value Description 0 Static arbitration scheme for channels with level 2 priority. 1 Round-robin arbitration scheme for channels with level 2 priority. Bits 19:16 – LVLPRI2[3:0] Level 2 Channel Priority Number When round-robin arbitration is enabled (PRICTRL0.RRLVLEN2=1) for priority level 2, this register holds the channel number of the last DMA channel being granted access as the active channel with priority level 2. When static arbitration is enabled (PRICTRL0.RRLVLEN2=0) for priority level 2, and the value of this bit group is non-zero, it will not affect the static priority scheme. This bit group is not reset when round-robin arbitration gets disabled (PRICTRL0.RRLVLEN2 written to '0'). Bit 15 – RRLVLEN1 Level 1 Round-Robin Scheduling Enable For details on arbitration schemes, refer to 28.6.2.4 Arbitration. Value Description 0 Static arbitration scheme for channels with level 1 priority. 1 Round-robin arbitration scheme for channels with level 1 priority. Bits 11:8 – LVLPRI1[3:0] Level 1 Channel Priority Number When round-robin arbitration is enabled (PRICTRL0.RRLVLEN1=1) for priority level 1, this register holds the channel number of the last DMA channel being granted access as the active channel with priority level 1. When static arbitration is enabled (PRICTRL0.RRLVLEN1=0) for priority level 1, and the value of this bit group is non-zero, it will not affect the static priority scheme. This bit group is not reset when round-robin arbitration gets disabled (PRICTRL0.RRLVLEN1 written to '0'). Bit 7 – RRLVLEN0 Level 0 Round-Robin Scheduling Enable For details on arbitration schemes, refer to 28.6.2.4 Arbitration. Value Description 0 Static arbitration scheme for channels with level 0 priority. 1 Round-robin arbitration scheme for channels with level 0 priority. Bits 3:0 – LVLPRI0[3:0] Level 0 Channel Priority Number When round-robin arbitration is enabled (PRICTRL0.RRLVLEN0=1) for priority level 0, this register holds the channel number of the last DMA channel being granted access as the active channel with priority level 0. When static arbitration is enabled (PRICTRL0.RRLVLEN0=0) for priority level 0, and the value of this bit group is non-zero, it will not affect the static priority scheme. This bit group is not reset when round-robin arbitration gets disabled (PRICTRL0.RRLVLEN0 written to '0'). SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 514 28.8.10 Interrupt Pending Name:  INTPEND Offset:  0x20 Reset:  0x0000 Property:  - This register allows the user to identify the lowest DMA channel with pending interrupt. Bit 15 14 13 12 11 10 9 8 PEND BUSY FERR SUSP TCMPL TERR Access R R R R/W R/W R/W Reset 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 ID[3:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 15 – PEND Pending This bit will read '1' when the channel selected by Channel ID field (ID) is pending. Bit 14 – BUSY Busy This bit will read '1' when the channel selected by Channel ID field (ID) is busy. Bit 13 – FERR Fetch Error This bit will read '1' when the channel selected by Channel ID field (ID) fetched an invalid descriptor. Bit 10 – SUSP Channel Suspend This bit will read '1' when the channel selected by Channel ID field (ID) has pending Suspend interrupt. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Channel ID (ID) Suspend interrupt flag. Bit 9 – TCMPL Transfer Complete This bit will read '1' when the channel selected by Channel ID field (ID) has pending Transfer Complete interrupt. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Channel ID (ID) Transfer Complete interrupt flag. Bit 8 – TERR Transfer Error This bit is read one when the channel selected by Channel ID field (ID) has pending Transfer Error interrupt. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Channel ID (ID) Transfer Error interrupt flag. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 515 Bits 3:0 – ID[3:0] Channel ID These bits store the lowest channel number with pending interrupts. The number is valid if Suspend (SUSP), Transfer Complete (TCMPL) or Transfer Error (TERR) bits are set. The Channel ID field is refreshed when a new channel (with channel number less than the current one) with pending interrupts is detected, or when the application clears the corresponding channel interrupt sources. When no pending channels interrupts are available, these bits will always return zero value when read. When the bits are written, indirect access to the corresponding Channel Interrupt Flag register is enabled. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 516 28.8.11 Interrupt Status Name:  INTSTATUS Offset:  0x24 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 CHINTn[6:0] Access R R R R R R R Reset 0 0 0 0 0 0 0 Bits 6:0 – CHINTn[6:0] Channel n Pending Interrupt [n=7..0] This bit is set when Channel n has a pending interrupt/the interrupt request is received. This bit is cleared when the corresponding Channel n interrupts are disabled or the interrupts sources are cleared. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 517 28.8.12 Busy Channels Name:  BUSYCH Offset:  0x28 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 BUSYCHn[6:0] Access R R R R R R R Reset 0 0 0 0 0 0 0 Bits 6:0 – BUSYCHn[6:0] Busy Channel n [x=7..0] This bit is cleared when the channel trigger action for DMA channel n is complete, when a bus error for DMA channel n is detected, or when DMA channel n is disabled. This bit is set when DMA channel n starts a DMA transfer. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 518 28.8.13 Pending Channels Name:  PENDCH Offset:  0x2C Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 PENDCH7 PENDCH6 PENDCH5 PENDCH4 PENDCH3 PENDCH2 PENDCH1 PENDCH0 Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bits 0, 1, 2, 3, 4, 5, 6, 7 – PENDCH Pending Channel n [n=7..0] This bit is cleared when trigger execution defined by channel trigger action settings for DMA channel n is started, when a bus error for DMA channel n is detected or when DMA channel n is disabled. For details on trigger action settings, refer to TRIGACT bit in 28.8.19 CHCTRLB. This bit is set when a transfer is pending on DMA channel n. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 519 28.8.14 Active Channel and Levels Name:  ACTIVE Offset:  0x30 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 BTCNT[15:8] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 BTCNT[7:0] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 ABUSY ID[4:0] Access R R R R R R Reset 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 LVLEXx LVLEXx LVLEXx LVLEXx Access R R R R Reset 0 0 0 0 Bits 31:16 – BTCNT[15:0] Active Channel Block Transfer Count These bits hold the 16-bit block transfer count of the ongoing transfer. This value is stored in the active channel and written back in the corresponding Write-Back channel memory location when the arbiter grants a new channel access. The value is valid only when the active channel active busy flag (ABUSY) is set. Bit 15 – ABUSY Active Channel Busy This bit is cleared when the active transfer count is written back in the write-back memory section. This bit is set when the next descriptor transfer count is read from the write-back memory section. Bits 12:8 – ID[4:0] Active Channel ID These bits hold the channel index currently stored in the active channel registers. The value is updated each time the arbiter grants a new channel transfer access request. Bits 3,2,1,0 – LVLEXx Level x Channel Trigger Request Executing [x=3..0] This bit is set when a level-x channel trigger request is executing or pending. This bit is cleared when no request is pending or being executed. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 520 28.8.15 Descriptor Memory Section Base Address Name:  BASEADDR Offset:  0x34 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 BASEADDR[13:8] Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 BASEADDR[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 13:0 – BASEADDR[13:0] Descriptor Memory Base Address These bits store the Descriptor memory section base address. The value must be 128-bit aligned. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 521 28.8.16 Write-Back Memory Section Base Address Name:  WRBADDR Offset:  0x38 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 WRBADDR[13:8] Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 WRBADDR[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 13:0 – WRBADDR[13:0] Write-Back Memory Base Address These bits store the Write-Back memory base address. The value must be 128-bit aligned. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 522 28.8.17 Channel ID Name:  CHID Offset:  0x3F Reset:  0x00 Property:  - Bit 7 6 5 4 3 2 1 0 ID[3:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bits 3:0 – ID[3:0] Channel ID These bits define the channel number that will be affected by the channel registers (CH*). Before reading or writing a channel register, the channel ID bit group must be written first. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 523 28.8.18 Channel Control A Name:  CHCTRLA Offset:  0x40 Reset:  0x00 Property:  PAC Write-Protection, Enable-Protected This register affects the DMA channel that is selected in the Channel ID register (CHID.ID). Bit 7 6 5 4 3 2 1 0 RUNSTDBY ENABLE SWRST Access R R/W R R R R R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 6 – RUNSTDBY Channel run in standby This bit is used to keep the DMAC channel running in standby mode. This bit is not enable-protected. Value Description 0 The DMAC channel is halted in standby. 1 The DMAC channel continues to run in standby. Bit 1 – ENABLE Channel Enable Writing a '0' to this bit during an ongoing transfer, the bit will not be cleared until the internal data transfer buffer is empty and the DMA transfer is aborted. The internal data transfer buffer will be empty once the ongoing burst transfer is completed. Writing a '1' to this bit will enable the DMA channel. This bit is not enable-protected. Value Description 0 DMA channel is disabled. 1 DMA channel is enabled. Bit 0 – SWRST Channel Software Reset Writing a '0' to this bit has no effect. Writing a '1' to this bit resets the channel registers to their initial state. The bit can be set when the channel is disabled (ENABLE=0). Writing a '1' to this bit will be ignored as long as ENABLE=1. This bit is automatically cleared when the reset is completed. Value Description 0 There is no reset operation ongoing. 1 The reset operation is ongoing. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 524 28.8.19 Channel Control B Name:  CHCTRLB Offset:  0x44 [ID-00001ece] Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected This register affects the DMA channel that is selected in the Channel ID register (CHID.ID). Bit 31 30 29 28 27 26 25 24 CMD[1:0] Access R/W R/W Reset 0 0 Bit 23 22 21 20 19 18 17 16 TRIGACT[1:0] Access R/W R/W Reset 0 0 Bit 15 14 13 12 11 10 9 8 TRIGSRC[4:0] Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 LVL[1:0] EVOE EVIE EVACT[2:0] Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bits 25:24 – CMD[1:0] Software Command These bits define the software commands. Refer to 28.6.3.2 Channel Suspend and 28.6.3.3 Channel Resume and Next Suspend Skip. These bits are not enable-protected. CMD[1:0] Name Description 0x0 NOACT No action 0x1 SUSPEND Channel suspend operation 0x2 RESUME Channel resume operation 0x3 - Reserved Bits 23:22 – TRIGACT[1:0] Trigger Action These bits define the trigger action used for a transfer. TRIGACT[1:0] Name Description 0x0 BLOCK One trigger required for each block transfer 0x1 - Reserved SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 525 TRIGACT[1:0] Name Description 0x2 BEAT One trigger required for each beat transfer 0x3 TRANSACTION One trigger required for each transaction Bits 12:8 – TRIGSRC[4:0] Trigger Source These bits define the peripheral trigger which is source of the transfer. For details on trigger selection and trigger modes, refer to Transfer Triggers and Actions and CHCTRLB.TRIGACT. Value Name Description 0x00 DISABLE Only software/event triggers 0x01 RTC TIMESTAMP RTC Timestamp Trigger 0x02 DSU DCC0 ID for DCC0 register 0x03 DSU DCC1 ID for DCC1 register 0x04 SERCOM0 RX SERCOM0 RX Trigger 0x05 SERCOM0 TX SERCOM0 TX Trigger 0x06 SERCOM1 RX SERCOM1 RX Trigger 0x07 SERCOM1 TX SERCOM1 TX Trigger 0x08 SERCOM2 RX SERCOM2 RX Trigger 0x09 SERCOM2 TX SERCOM2 TX Trigger 0x0A TC0 OVF TC0 Overflow Trigger 0x0B TC0 MC0 TC0 Match/Compare 0 Trigger 0x0C TC0 MC1 TC0 Match/Compare 1 Trigger 0x0D TC1 OVF TC1 Overflow Trigger 0x0E TC1 MC0 TC1 Match/Compare 0 Trigger 0x0F TC1 MC1 TC1 Match/Compare 1 Trigger 0x10 TC2 OVF TC2 Overflow Trigger 0x11 TC2 MC0 TC2 Match/Compare 0 Trigger 0x12 TC2 MC1 TC2 Match/Compare 1 Trigger 0x13 ADC RESRDY ADC Result Ready Trigger 0x14 DAC EMPTY DAC Empty Trigger 0x15 PTC EOC PTC End of Conversion Trigger 0x16 PTC SEQ PTC Sequence Trigger 0x17 PTC WCOMP PTC Window Compare Trigger Bits 6:5 – LVL[1:0] Channel Arbitration Level These bits define the arbitration level used for the DMA channel, where a high level has priority over a low level. For further details on arbitration schemes, refer to 28.6.2.4 Arbitration. These bits are not enable-protected. TRIGACT[1:0] Name Description 0x0 LVL0 Channel Priority Level 0 0x1 LVL1 Channel Priority Level 1 0x2 LVL2 Channel Priority Level 2 0x3 LVL3 Channel Priority Level 3 SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 526 Bit 4 – EVOE Channel Event Output Enable This bit indicates if the Channel event generation is enabled. The event will be generated for every condition defined in the descriptor Event Output Selection (BTCTRL.EVOSEL). This bit is available only for the four least significant DMA channels. Refer to table: User Multiplexer Selection and Event Generator Selection of the Event System for details. Value Description 0 Channel event generation is disabled. 1 Channel event generation is enabled. Bit 3 – EVIE Channel Event Input Enable This bit is available only for the four least significant DMA channels. Refer to table: User Multiplexer Selection and Event Generator Selection of the Event System for details. Value Description 0 Channel event action will not be executed on any incoming event. 1 Channel event action will be executed on any incoming event. Bits 2:0 – EVACT[2:0] Event Input Action These bits define the event input action, as shown below. The action is executed only if the corresponding EVIE bit in the CHCTRLB register of the channel is set. These bits are available only for the four least significant DMA channels. Refer to table: User Multiplexer Selection and Event Generator Selection of the Event System for details. EVACT[2:0] Name Description 0x0 NOACT No action 0x1 TRIG Normal Transfer and Conditional Transfer on Strobe trigger 0x2 CTRIG Conditional transfer trigger 0x3 CBLOCK Conditional block transfer 0x4 SUSPEND Channel suspend operation 0x5 RESUME Channel resume operation 0x6 SSKIP Skip next block suspend action 0x7 - Reserved Related Links 33.7.8 CHANNEL SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 527 28.8.20 Channel Interrupt Enable Clear Name:  CHINTENCLR Offset:  0x4C Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Channel Interrupt Enable Set (CHINTENSET) register. This register affects the DMA channel that is selected in the Channel ID register (CHID.ID). Bit 7 6 5 4 3 2 1 0 SUSP TCMPL TERR Access R/W R/W R/W Reset 0 0 0 Bit 2 – SUSP Channel Suspend Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Channel Suspend Interrupt Enable bit, which disables the Channel Suspend interrupt. Value Description 0 The Channel Suspend interrupt is disabled. 1 The Channel Suspend interrupt is enabled. Bit 1 – TCMPL Channel Transfer Complete Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Channel Transfer Complete Interrupt Enable bit, which disables the Channel Transfer Complete interrupt. Value Description 0 The Channel Transfer Complete interrupt is disabled. When block action is set to none, the TCMPL flag will not be set when a block transfer is completed. 1 The Channel Transfer Complete interrupt is enabled. Bit 0 – TERR Channel Transfer Error Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Channel Transfer Error Interrupt Enable bit, which disables the Channel Transfer Error interrupt. Value Description 0 The Channel Transfer Error interrupt is disabled. 1 The Channel Transfer Error interrupt is enabled. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 528 28.8.21 Channel Interrupt Enable Set Name:  CHINTENSET Offset:  0x4D Reset:  0x00 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Channel Interrupt Enable Clear (CHINTENCLR) register. This register affects the DMA channel that is selected in the Channel ID register (CHID.ID). Bit 7 6 5 4 3 2 1 0 SUSP TCMPL TERR Access R/W R/W R/W Reset 0 0 0 Bit 2 – SUSP Channel Suspend Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Channel Suspend Interrupt Enable bit, which enables the Channel Suspend interrupt. Value Description 0 The Channel Suspend interrupt is disabled. 1 The Channel Suspend interrupt is enabled. Bit 1 – TCMPL Channel Transfer Complete Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Channel Transfer Complete Interrupt Enable bit, which enables the Channel Transfer Complete interrupt. Value Description 0 The Channel Transfer Complete interrupt is disabled. 1 The Channel Transfer Complete interrupt is enabled. Bit 0 – TERR Channel Transfer Error Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Channel Transfer Error Interrupt Enable bit, which enables the Channel Transfer Error interrupt. Value Description 0 The Channel Transfer Error interrupt is disabled. 1 The Channel Transfer Error interrupt is enabled. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 529 28.8.22 Channel Interrupt Flag Status and Clear Name:  CHINTFLAG Offset:  0x4E Reset:  0x00 Property:  - This register affects the DMA channel that is selected in the Channel ID register (CHID.ID). Bit 7 6 5 4 3 2 1 0 SUSP TCMPL TERR Access R/W R/W R/W Reset 0 0 0 Bit 2 – SUSP Channel Suspend This flag is cleared by writing a '1' to it. This flag is set when a block transfer with suspend block action is completed, when a software suspend command is executed, when a suspend event is received or when an invalid descriptor is fetched by the DMA. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Channel Suspend interrupt flag for the corresponding channel. For details on available software commands, refer to CHCTRLB.CMD. For details on available event input actions, refer to CHCTRLB.EVACT. For details on available block actions, refer to BTCTRL.BLOCKACT. Bit 1 – TCMPL Channel Transfer Complete This flag is cleared by writing a '1' to it. This flag is set when a block transfer is completed and the corresponding interrupt block action is enabled. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Transfer Complete interrupt flag for the corresponding channel. Bit 0 – TERR Channel Transfer Error This flag is cleared by writing a '1' to it. This flag is set when a bus error is detected during a beat transfer or when the DMAC fetches an invalid descriptor. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Transfer Error interrupt flag for the corresponding channel. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 530 28.8.23 Channel Status Name:  CHSTATUS Offset:  0x4F Reset:  0x00 Property:  - This register affects the DMA channel that is selected in the Channel ID register (CHID.ID). Bit 7 6 5 4 3 2 1 0 FERR BUSY PEND Access R R R Reset 0 0 0 Bit 2 – FERR Channel Fetch Error This bit is cleared when a software resume command is executed. This bit is set when an invalid descriptor is fetched. Bit 1 – BUSY Channel Busy This bit is cleared when the channel trigger action is completed, when a bus error is detected or when the channel is disabled. This bit is set when the DMA channel starts a DMA transfer. Bit 0 – PEND Channel Pending This bit is cleared when the channel trigger action is started, when a bus error is detected or when the channel is disabled. For details on trigger action settings, refer to CHCTRLB.TRIGACT. This bit is set when a transfer is pending on the DMA channel, as soon as the transfer request is received. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 531 28.9 Register Summary - SRAM Offset Name Bit Pos. 0x00 BTCTRL 7:0 BLOCKACT[1:0] EVOSEL[1:0] VALID 15:8 STEPSIZE[2:0] STEPSEL DSTINC SRCINC BEATSIZE[1:0] 0x02 BTCNT 7:0 BTCNT[7:0] 15:8 BTCNT[15:8] 0x04 SRCADDR 7:0 SRCADDR[7:0] 15:8 SRCADDR[15:8] 23:16 SRCADDR[23:16] 31:24 SRCADDR[31:24] 0x08 DSTADDR 7:0 DSTADDR[7:0] 15:8 DSTADDR[15:8] 23:16 DSTADDR[23:16] 31:24 DSTADDR[31:24] 0x0C DESCADDR 7:0 DESCADDR[7:0] 15:8 DESCADDR[15:8] 23:16 DESCADDR[23:16] 31:24 DESCADDR[31:24] 28.10 Register Description - SRAM Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to 28.5.8 Register Access Protection. Some registers are enable-protected, meaning they can only be written when the peripheral is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 532 28.10.1 Block Transfer Control Name:  BTCTRL Offset:  0x00 Property:  - The BTCTRL register offset is relative to (BASEADDR or WRBADDR) + Channel Number * 0x10 Bit 15 14 13 12 11 10 9 8 STEPSIZE[2:0] STEPSEL DSTINC SRCINC BEATSIZE[1:0] Access Reset Bit 7 6 5 4 3 2 1 0 BLOCKACT[1:0] EVOSEL[1:0] VALID Access Reset Bits 15:13 – STEPSIZE[2:0] Address Increment Step Size These bits select the address increment step size. The setting apply to source or destination address, depending on STEPSEL setting. Value Name Description 0x0 X1 Next ADDR = ADDR + (Beat size in byte) * 1 0x1 X2 Next ADDR = ADDR + (Beat size in byte) * 2 0x2 X4 Next ADDR = ADDR + (Beat size in byte) * 4 0x3 X8 Next ADDR = ADDR + (Beat size in byte) * 8 0x4 X16 Next ADDR = ADDR + (Beat size in byte) * 16 0x5 X32 Next ADDR = ADDR + (Beat size in byte) * 32 0x6 X64 Next ADDR = ADDR + (Beat size in byte) * 64 0x7 X128 Next ADDR = ADDR + (Beat size in byte) * 128 Bit 12 – STEPSEL Step Selection This bit selects if source or destination addresses are using the step size settings. Value Name Description 0x0 DST Step size settings apply to the destination address 0x1 SRC Step size settings apply to the source address Bit 11 – DSTINC Destination Address Increment Enable Writing a '0' to this bit will disable the destination address incrementation. The address will be kept fixed during the data transfer. Writing a '1' to this bit will enable the destination address incrementation. By default, the destination address is incremented by 1. If the STEPSEL bit is cleared, flexible step-size settings are available in the STEPSIZE register. Value Description 0 The Destination Address Increment is disabled. 1 The Destination Address Increment is enabled. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 533 Bit 10 – SRCINC Source Address Increment Enable Writing a '0' to this bit will disable the source address incrementation. The address will be kept fixed during the data transfer. Writing a '1' to this bit will enable the source address incrementation. By default, the source address is incremented by 1. If the STEPSEL bit is set, flexible step-size settings are available in the STEPSIZE register. Value Description 0 The Source Address Increment is disabled. 1 The Source Address Increment is enabled. Bits 9:8 – BEATSIZE[1:0] Beat Size These bits define the size of one beat. A beat is the size of one data transfer bus access, and the setting apply to both read and write accesses. Value Name Description 0x0 BYTE 8-bit bus transfer 0x1 HWORD 16-bit bus transfer 0x2 WORD 32-bit bus transfer other Reserved Bits 4:3 – BLOCKACT[1:0] Block Action These bits define what actions the DMAC should take after a block transfer has completed. BLOCKACT[1:0] Name Description 0x0 NOACT Channel will be disabled if it is the last block transfer in the transaction 0x1 INT Channel will be disabled if it is the last block transfer in the transaction and block interrupt 0x2 SUSPEND Channel suspend operation is completed 0x3 BOTH Both channel suspend operation and block interrupt Bits 2:1 – EVOSEL[1:0] Event Output Selection These bits define the event output selection. EVOSEL[1:0] Name Description 0x0 DISABLE Event generation disabled 0x1 BLOCK Event strobe when block transfer complete 0x2 Reserved 0x3 BEAT Event strobe when beat transfer complete Bit 0 – VALID Descriptor Valid Writing a '0' to this bit in the Descriptor or Write-Back memory will suspend the DMA channel operation when fetching the corresponding descriptor. The bit is automatically cleared in the Write-Back memory section when channel is aborted, when an error is detected during the block transfer, or when the block transfer is completed. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 534 Value Description 0 The descriptor is not valid. 1 The descriptor is valid. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 535 28.10.2 Block Transfer Count Name:  BTCNT Offset:  0x02 Property:  - The BTCNT register offset is relative to (BASEADDR or WRBADDR) + Channel Number * 0x10 Bit 15 14 13 12 11 10 9 8 BTCNT[15:8] Access Reset Bit 7 6 5 4 3 2 1 0 BTCNT[7:0] Access Reset Bits 15:0 – BTCNT[15:0] Block Transfer Count This bit group holds the 16-bit block transfer count. During a transfer, the internal counter value is decremented by one after each beat transfer. The internal counter is written to the corresponding write-back memory section for the DMA channel when the DMA channel loses priority, is suspended or gets disabled. The DMA channel can be disabled by a complete transfer, a transfer error or by software. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 536 28.10.3 Block Transfer Source Address Name:  SRCADDR Offset:  0x04 Property:  - The SRCADDR register offset is relative to (BASEADDR or WRBADDR) + Channel Number * 0x10 Bit 31 30 29 28 27 26 25 24 SRCADDR[31:24] Access Reset Bit 23 22 21 20 19 18 17 16 SRCADDR[23:16] Access Reset Bit 15 14 13 12 11 10 9 8 SRCADDR[15:8] Access Reset Bit 7 6 5 4 3 2 1 0 SRCADDR[7:0] Access Reset Bits 31:0 – SRCADDR[31:0] Transfer Source Address This bit group holds the source address corresponding to the last beat transfer address in the block transfer. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 537 28.10.4 Block Transfer Destination Address Name:  DSTADDR Offset:  0x08 Property:  - The DSTADDR register offset is relative to (BASEADDR or WRBADDR) + Channel Number * 0x10 Bit 31 30 29 28 27 26 25 24 DSTADDR[31:24] Access Reset Bit 23 22 21 20 19 18 17 16 DSTADDR[23:16] Access Reset Bit 15 14 13 12 11 10 9 8 DSTADDR[15:8] Access Reset Bit 7 6 5 4 3 2 1 0 DSTADDR[7:0] Access Reset Bits 31:0 – DSTADDR[31:0] Transfer Destination Address This bit group holds the destination address corresponding to the last beat transfer address in the block transfer. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 538 28.10.5 Next Descriptor Address Name:  DESCADDR Offset:  0x0C Property:  - The DESCADDR register offset is relative to (BASEADDR or WRBADDR) + Channel Number * 0x10 Bit 31 30 29 28 27 26 25 24 DESCADDR[31:24] Access Reset Bit 23 22 21 20 19 18 17 16 DESCADDR[23:16] Access Reset Bit 15 14 13 12 11 10 9 8 DESCADDR[15:8] Access Reset Bit 7 6 5 4 3 2 1 0 DESCADDR[7:0] Access Reset Bits 31:0 – DESCADDR[31:0] Next Descriptor Address This bit group holds the SRAM address of the next descriptor. The value must be 128-bit aligned. If the value of this SRAM register is 0x00000000, the transaction will be terminated when the DMAC tries to load the next transfer descriptor. SAM L10/L11 Family DMAC – Direct Memory Access Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 539 29. EIC – External Interrupt Controller 29.1 Overview The External Interrupt Controller (EIC) allows external pins to be configured as interrupt lines. Each interrupt line can be individually masked and can generate an interrupt on rising, falling, or both edges, or on high or low levels. Each external pin has a configurable filter to remove spikes. Each external pin can also be configured to be asynchronous in order to wake up the device from sleep modes where all clocks have been disabled. External pins can also generate an event. Each external pin can be defined as secured or non-secured, where secured pins can only be handled by secure accesses. A separate non-maskable interrupt (NMI) is also supported. It has properties similar to the other external interrupts, but is connected to the NMI request of the CPU, enabling it to interrupt any other interrupt mode. 29.2 Features • Up to 8 external pins (EXTINTx), plus one non-maskable pin (NMI) • Dedicated, individually maskable interrupt for each pin • Interrupt on rising, falling, or both edges • Synchronous or asynchronous edge detection mode • Interrupt pin debouncing • Interrupt on high or low levels • Asynchronous interrupts for sleep modes without clock • Filtering of external pins • Event generation from EXTINTx • Selectable secured or non-secured attribution for each individual external pin (SAM L11) 29.3 Block Diagram Figure 29-1. EIC Block Diagram Filter Edge/Level Detection Interrupt Wake Event FILTENx EXTINTx intreq_extint inwake_extint evt_extint Filter Edge/Level Detection Interrupt Wake NMIFILTEN NMISENSE[2:0] NMI intreq_nmi inwake_nmi SENSEx[2:0] SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 540 29.4 Signal Description Signal Name Type Description EXTINT[7..0] Digital Input External interrupt pin NMI Digital Input Non-maskable interrupt pin One signal may be available on several pins. 29.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 29.5.1 I/O Lines Using the EIC’s I/O lines requires the I/O pins to be configured. Related Links 32. PORT - I/O Pin Controller 29.5.2 Power Management All interrupts are available down to STANDBY sleep mode, but the EIC can be configured to automatically mask some interrupts in order to prevent device wake-up. The EIC will continue to operate in any sleep mode where the selected source clock is running. The EIC’s interrupts can be used to wake up the device from sleep modes. Events connected to the Event System can trigger other operations in the system without exiting sleep modes. Related Links 22. PM – Power Manager 29.5.3 Clocks The EIC bus clock (CLK_EIC_APB) can be enabled and disabled by the Main Clock Controller, the default state of CLK_EIC_APB can be found in the Peripheral Clock Masking section. Some optional functions need a peripheral clock, which can either be a generic clock (GCLK_EIC, for wider frequency selection) or a Ultra Low-Power 32 KHz clock (CLK_ULP32K, for highest power efficiency). One of the clock sources must be configured and enabled before using the peripheral: GCLK_EIC is configured and enabled in the Generic Clock Controller. CLK_ULP32K is provided by the internal Ultra Low-Power (OSCULP32K) Oscillator in the OSC32KCTRL module. Both GCLK_EIC and CLK_ULP32K are asynchronous to the user interface clock (CLK_EIC_APB). Due to this asynchronicity, writes to certain registers will require synchronization between the clock domains. Refer to Synchronization for further details. Related Links 19. MCLK – Main Clock 19.6.2.6 Peripheral Clock Masking 18. GCLK - Generic Clock Controller 24. OSC32KCTRL – 32KHz Oscillators Controller SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 541 29.5.4 DMA Not applicable. 29.5.5 Interrupts There are several interrupt request lines, at least one for the external interrupts (EXTINT) and one for non-maskable interrupt (NMI). The EXTINT interrupt request line is connected to the interrupt controller. Using the EIC interrupt requires the interrupt controller to be configured first. The NMI interrupt request line is also connected to the interrupt controller, but does not require the interrupt to be configured. 29.5.6 Events The events are connected to the Event System. Using the events requires the Event System to be configured first. Related Links 33. EVSYS – Event System 29.5.7 Debug Operation When the CPU is halted in debug mode, the EIC continues normal operation. If the EIC 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. 29.5.8 Register Access Protection All registers with write-access can be write-protected optionally by the Peripheral Access Controller (PAC), except for the following registers: • Interrupt Flag Status and Clear register (INTFLAG) • Non-Maskable Interrupt Flag Status and Clear register (NMIFLAG) Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. PAC write-protection does not apply to accesses through an external debugger. Related Links 15. PAC - Peripheral Access Controller 29.5.9 SAM L11 TrustZone Specific Register Access Protection When the EIC is not PAC secured, non-secure and secure code can both access all functionalities. When the EIC is PAC secured, all registers are by default available in the secure alias only. A PAC secured EIC can open up individual external interrupts for non-secure access. This is done using the NONSEC and the NONSECNMI registers. When an external interrupt has been set as non-secure, it can be handled from non-secure code, using the EIC module non-secure alias. Since only Secured code has the rights to modify the NONSEC register, an interrupt-based mechanism has been added to let Non Secured code know when these registers have been changed by Secured code. A single flag called NSCHK in the INTFLAG register will rise should changes, conditioned by the NSCHK register, occur in the NONSEC or NONSECNMI registers. • EIC Security Attribution registers (NONSEC and NONSECNMI) can only be written in the secure alias, otherwise a PAC error results. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 542 • The configuration of secured external interrupts can only be changed in the secure alias. Attempt to change the configuration in non-secure mode is silently ignored. Affected configuration registers are: CTRLA, NMICTRL, NMIFLAG, EVCTRL, INTENCLR, INTENSET, INTFLAG, ASYNCH, CONFIGn, DEBOUNCEN, DPRESCALER. Note:  Refer to the Mix-Secure Peripherals section in the SAM L11 Security Features chapter for more information. 29.5.10 Analog Connections Not applicable. 29.6 Functional Description 29.6.1 Principle of Operation The EIC detects edge or level condition to generate interrupts to the CPU interrupt controller or events to the Event System. Each external interrupt pin (EXTINT) can be filtered using majority vote filtering, clocked by GCLK_EIC or by CLK_ULP32K. 29.6.2 Basic Operation 29.6.2.1 Initialization The EIC must be initialized in the following order: 1. Enable CLK_EIC_APB 2. If required, configure the NMI by writing the Non-Maskable Interrupt Control register (29.8.2 NMICTRL) 3. Enable GCLK_EIC or CLK_ULP32K when one of the following configuration is selected: – the NMI uses edge detection or filtering. – one EXTINT uses filtering. – one EXTINT uses synchronous edge detection. – one EXTINT uses debouncing. GCLK_EIC is used when a frequency higher than 32KHz is required for filtering. CLK_ULP32K is recommended when power consumption is the priority. For CLK_ULP32K write a '1' to the Clock Selection bit in the Control A register (CTRLA.CKSEL). 4. Configure the EIC input sense and filtering by writing the Configuration n register (CONFIG). 5. Optionally, enable the asynchronous mode. 6. Optionally, enable the debouncer mode. 7. Enable the EIC by writing a ‘1’ to CTRLA.ENABLE. The following bits are enable-protected, meaning that it can only be written when the EIC is disabled (CTRLA.ENABLE=0): • Clock Selection bit in Control A register (CTRLA.CKSEL) The following registers are enable-protected: • Event Control register (29.8.5 EVCTRL) • Configuration n register (CONFIG). • External Interrupt Asynchronous Mode register (29.8.9 ASYNCH) SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 543 • Debouncer Enable register (29.8.11 DEBOUNCEN) • Debounce Prescaler register (29.8.12 DPRESCALER) Enable-protected bits in the CTRLA register can be written at the same time when setting CTRLA.ENABLE to '1', but not at the same time as CTRLA.ENABLE is being cleared. Enable-protection is denoted by the "Enable-Protected" property in the register description. 29.6.2.2 Enabling, Disabling, and Resetting The EIC is enabled by writing a '1' the Enable bit in the Control A register (CTRLA.ENABLE). The EIC is disabled by writing CTRLA.ENABLE to '0'. The EIC is reset by setting the Software Reset bit in the Control register (CTRLA.SWRST). All registers in the EIC will be reset to their initial state, and the EIC will be disabled. Refer to the CTRLA register description for details. 29.6.3 External Pin Processing Each external pin can be configured to generate an interrupt/event on edge detection (rising, falling or both edges) or level detection (high or low). The sense of external interrupt pins is configured by writing the Input Sense x bits in the Config n register (CONFIG.SENSEx). The corresponding interrupt flag (INTFLAG.EXTINT[x]) in the Interrupt Flag Status and Clear register (29.8.8 INTFLAG) is set when the interrupt condition is met. When the interrupt flag has been cleared in edge-sensitive mode, INTFLAG.EXTINT[x] will only be set if a new interrupt condition is met. In level-sensitive mode, when interrupt has been cleared, INTFLAG.EXTINT[x] will be set immediately if the EXTINTx pin still matches the interrupt condition. Each external pin can be filtered by a majority vote filtering, clocked by GCLK_EIC or CLK_ULP32K. Filtering is enabled if bit Filter Enable x in the Configuration n register (CONFIG.FILTENx) is written to '1'. The majority vote filter samples the external pin three times with GCLK_EIC or CLK_ULP32K and outputs the value when two or more samples are equal. Table 29-1. Majority Vote Filter Samples [0, 1, 2] Filter Output [0,0,0] 0 [0,0,1] 0 [0,1,0] 0 [0,1,1] 1 [1,0,0] 0 [1,0,1] 1 [1,1,0] 1 [1,1,1] 1 When an external interrupt is configured for level detection and when filtering is disabled, detection is done asynchronously. Level detection and asynchronous edge detection does not require GCLK_EIC or CLK_ULP32K, but interrupt and events can still be generated. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 544 If filtering or synchronous edge detection or debouncing is enabled, the EIC automatically requests GCLK_EIC or CLK_ULP32K to operate. The selection between these two clocks is done by writing the Clock Selection bits in the Control A register (CTRLA.CKSEL). GCLK_EIC must be enabled in the GCLK module. In these modes the external pin is sampled at the EIC clock rate, thus pulses with duration lower than two EIC clock periods may not be properly detected. Figure 29-2. Interrupt Detection Latency by modes (Rising Edge) intreq_extint[x] (edge detection / filter) intreq_extint[x] (edge detection / no filter) intreq_extint[x] (level detection / filter) intreq_extint[x] (level detection / no filter) EXTINTx CLK_EIC_APB GCLK_EIC clear INTFLAG.EXTINT[x] No interrupt No interrupt The detection latency depends on the detection mode. Table 29-2. Detection Latency Detection mode Latency (worst case) Level without filter Five CLK_EIC_APB periods Level with filter Four GCLK_EIC/CLK_ULP32K periods + five CLK_EIC_APB periods Edge without filter Four GCLK_EIC/CLK_ULP32K periods + five CLK_EIC_APB periods Edge with filter Six GCLK_EIC/CLK_ULP32K periods + five CLK_EIC_APB periods Related Links 18. GCLK - Generic Clock Controller 29.6.4 Additional Features 29.6.4.1 Non-Maskable Interrupt (NMI) The non-maskable interrupt pin can also generate an interrupt on edge or level detection, but it is configured with the dedicated NMI Control register (NMICTRL). To select the sense for NMI, write to the NMISENSE bit group in the NMI Control register (NMICTRL.NMISENSE). NMI filtering is enabled by writing a '1' to the NMI Filter Enable bit (NMICTRL.NMIFILTEN). If edge detection or filtering is required, enable GCLK_EIC or CLK_ULP32K. NMI detection is enabled only by the NMICTRL.NMISENSE value, and the EIC is not required to be enabled. When an NMI is detected, the non-maskable interrupt flag in the NMI Flag Status and Clear register is set (NMIFLAG.NMI). NMI interrupt generation is always enabled, and NMIFLAG.NMI generates an interrupt request when set. 29.6.4.2 Asynchronous Edge Detection Mode (No Debouncing) The EXTINT edge detection can be operated synchronously or asynchronously, selected by the Asynchronous Control Mode bit for external pin x in the External Interrupt Asynchronous Mode register SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 545 (ASYNCH.ASYNCH[x]). The EIC edge detection is operated synchronously when the Asynchronous Control Mode bit (ASYNCH.ASYNCH[x]) is '0' (default value). It is operated asynchronously when ASYNCH.ASYNCH[x] is written to '1'. In Synchronous Edge Detection Mode, the external interrupt (EXTINT) or the non-maskable interrupt (NMI) pins are sampled using the EIC clock as defined by the Clock Selection bit in the Control A register (CTRLA.CKSEL). The External Interrupt flag (INTFLAG.EXTINT[x]) or Non-Maskable Interrupt flag (NMIFLAG.NMI) is set when the last sampled state of the pin differs from the previously sampled state. In this mode, the EIC clock is required. The Synchronous Edge Detection Mode can be used in Idle and Standby sleep modes. In Asynchronous Edge Detection Mode, the external interrupt (EXTINT) pins or the non-maskable interrupt (NMI) pins set the External Interrupt flag or Non-Maskable Interrupt flag (INTFLAG.EXTINT[x] or NMIFLAG) directly. In this mode, the EIC clock is not requested. The asynchronous edge detection mode can be used in Idle and Standby sleep modes. 29.6.4.3 Interrupt Pin Debouncing The external interrupt pin (EXTINT) edge detection can use a debouncer to improve input noise immunity. When selected, the debouncer can work in the synchronous mode or the asynchronous mode, depending on the configuration of the ASYNCH.ASYNCH[x] bit for the pin. The debouncer uses the EIC clock as defined by the bit CTRLA.CKSEL to clock the debouncing circuitry. The debouncing time frame is set with the debouncer prescaler DPRESCALER.DPRESCALERn, which provides the low frequency clock tick that is used to reject higher frequency signals. The debouncing mode for pin EXTINT x can be selected only if the Sense bits in the Configuration y register (CONFIGy.SENSEx) are set to RISE, FALL or BOTH. If the debouncing mode for pin EXTINT x is selected, the filter mode for that pin (CONFIGy.FILTENx) can not be selected. The debouncer manages an internal “valid pin state” that depends on the external interrupt (EXTINT) pin transitions, the debouncing mode and the debouncer prescaler frequency. The valid pin state reflects the pin value after debouncing. The external interrupt pin (EXTINT) is sampled continously on EIC clock. The sampled value is evaluated on each low frequency clock tick to detect a transitional edge when the sampled value is different of the current valid pin state. The sampled value is evaluated on each EIC clock when DPRESCALER.TICKON=0 or on each low frequency clock tick when DPRESCALER.TICKON=1, to detect a bounce when the sampled value is equal to the current valid pin state. Transitional edge detection increments the transition counter of the EXTINT pin, while bounce detection resets the transition counter. The transition counter must exceed the transition count threshold as defined by the DPRESCALER.STATESn bitfield. In the synchronous mode the threshold is 4 when DPRESCALER.STATESn=0 or 8 when DPRESCALER.STATESn=1. In the asynchronous mode the threshold is 4. The valid pin state for the pins can be accessed by reading the register PINSTATE for both synchronous or asynchronous debouncing mode. Synchronous edge detection In this mode the external interrupt (EXTINT) pin is sampled continously on EIC clock. 1. A pin edge transition will be validated when the sampled value is consistently different of the current valid pin state for 4 (or 8 depending on bit DPRESCALER.STATESn) consecutive ticks of the low frequency clock. 2. Any pin sample, at the low frequency clock tick rate, with a value opposite to the current valid pin state will increment the transition counter. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 546 3. Any pin sample, at EIC clock rate (when DPRESCALER.TICKON=0) or the low frequency clock tick (when DPRESCALER.TICKON=1), with a value identical to the current valid pin state will return the transition counter to zero. 4. When the transition counter meets the count threshold, the pin edge transition is validated and the pin state PINSTATE.PINSTATE[x] is changed to the detected level. 5. The external interrupt flag (INTFLAG.EXTINT[x]) is set when the pin state PINSTATE.PINSTATE[x] is changed. Figure 29-3. EXTINT Pin Synchronous Debouncing (Rising Edge) CLK_EIC CLK_PRESCALER EXTINTx PIN_STATE INTGLAG TRANSITIONLOW HIGH Set INTFLAG In the synchronous edge detection mode, the EIC clock is required. The synchronous edge detection mode can be used in Idle and Standby sleep modes. Asynchronous edge detection In this mode, the external interrupt (EXTINT) pin directly drives an asynchronous edges detector which triggers any rising or falling edge on the pin: 1. Any edge detected that indicates a transition from the current valid pin state will immediately set the valid pin state PINSTATE.PINSTATE[x] to the detected level. 2. The external interrupt flag (INTFLAG.EXTINT[x] is immediately changed. 3. The edge detector will then be idle until no other rising or falling edge transition is detected during 4 consecutive ticks of the low frequency clock. 4. Any rising or falling edge transition detected during the idle state will return the transition counter to 0. 5. After 4 consecutive ticks of the low frequency clock without bounce detected, the edge detector is ready for a new detection. Figure 29-4. EXTINT Pin Asynchronous Debouncing (Rising Edge) CLK_EIC CLK_PRESCALER EXTINTx PIN_STATE INTGLAG LOW TRANSITION HIGH Set INTFLAG In this mode, the EIC clock is requested. The asynchronous edge detection mode can be used in Idle and Standby sleep modes. 29.6.5 DMA Operation Not applicable. 29.6.6 Interrupts The EIC has the following interrupt sources: SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 547 • External interrupt pins (EXTINTx). See 29.6.2 Basic Operation. • Non-maskable interrupt pin (NMI). See 29.6.4 Additional Features. • Non-secure check interrupt pin (NSCHK). See 29.8.8 INTFLAG Each interrupt source has an associated interrupt flag. The interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG) is set when an interrupt condition occurs (NMIFLAG for NMI). Each interrupt, except NMI, can be individually enabled by setting the corresponding bit in the Interrupt Enable Set register (INTENSET=1), and disabled by setting the corresponding bit in the Interrupt Enable Clear register (INTENCLR=1). An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until the interrupt flag is cleared, the interrupt is disabled, or the EIC is reset. See the INTFLAG register for details on how to clear interrupt flags. The EIC has at least one common interrupt request line for all the interrupt sources, and one interrupt request line for the NMI. The user must read the INTFLAG (or NMIFLAG) register to determine which interrupt condition is present. Note:  Interrupts must be globally enabled for interrupt requests to be generated. 29.6.7 Events The EIC can generate the following output events: • External event from pin (EXTINTx). Setting an Event Output Control register (EVCTRL.EXTINTEO) enables the corresponding output event. Clearing this bit disables the corresponding output event. Refer to Event System for details on configuring the Event System. When the condition on pin EXTINTx matches the configuration in the CONFIGn register, the corresponding event is generated, if enabled. 29.6.8 Sleep Mode Operation In sleep modes, an EXTINTx pin can wake up the device if the corresponding condition matches the configuration in the CONFIG register, and the corresponding bit in the Interrupt Enable Set register (29.8.7 INTENSET) is written to '1'. Figure 29-5. Wake-up Operation Example (High-Level Detection, No Filter, Interrupt Enable Set) CLK_EIC_APB EXTINTx intwake_extint[x] intreq_extint[x] wake from sleep mode clear INTFLAG.EXTINT[x] 29.6.9 SAM L11 Secure Access Rights Non-secure write to CTRLA register or DPRESCALER register is prohibited. Non-secure read to CTRLA or DPRESCALER register or SYNCBUSY register will return zero with no error resulting. Non-secure write to a bit of EVCTRL, ASYNCH, DEBOUNCEN, INTENCLR, INTENSET, INTFLAG and CONFIG registers is prohibited if the related bit of NONSEC.EXTINT is zero. Non-secure write to NMICTRL and NMIFLAG registers is prohibited if NONSECNMI.NMI is zero. Bits relating to secure EXTINT read as zero in non-secure mode with no error resulting. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 548 29.6.10 Synchronization Due to asynchronicity between the main clock domain and the peripheral clock domains, some registers need to be synchronized when written or read. The following bits are synchronized when written: • Software Reset bit in control register (CTRLA.SWRST) • Enable bit in control register (CTRLA.ENABLE) Required write-synchronization is denoted by the "Write-Synchronized" property in the register description. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 549 29.7 Register Summary Important:  For SAM L11, the EIC register map is automatically duplicated in a Secure and Non-Secure alias: • The Non-Secure alias is at the peripheral base address • The Secure alias is located at the peripheral base address + 0x200 Refer to Mix-Secure Peripherals for more information on register access rights Offset Name Bit Pos. 0x00 CTRLA 7:0 CKSEL ENABLE SWRST 0x01 NMICTRL 7:0 NMIASYNCH NMIFILTEN NMISENSE[2:0] 0x02 NMIFLAG 7:0 NMI 15:8 0x04 SYNCBUSY 7:0 ENABLE SWRST 15:8 23:16 31:24 0x08 EVCTRL 7:0 EXTINTEO[7:0] 15:8 23:16 31:24 0x0C INTENCLR 7:0 EXTINT[7:0] 15:8 23:16 31:24 NSCHK 0x10 INTENSET 7:0 EXTINT[7:0] 15:8 23:16 31:24 NSCHK 0x14 INTFLAG 7:0 EXTINT[7:0] 15:8 23:16 31:24 NSCHK 0x18 ASYNCH 7:0 ASYNCH[7:0] 15:8 23:16 31:24 0x1C CONFIG 7:0 FILTENx SENSEx[2:0] FILTENx SENSEx[2:0] 15:8 FILTENx SENSEx[2:0] FILTENx SENSEx[2:0] 23:16 FILTENx SENSEx[2:0] FILTENx SENSEx[2:0] 31:24 FILTENx SENSEx[2:0] FILTENx SENSEx[2:0] 0x20 ... 0x2F Reserved SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 550 Offset Name Bit Pos. 0x30 DEBOUNCEN 7:0 DEBOUNCEN[7:0] 15:8 23:16 31:24 0x34 DPRESCALER 7:0 STATES PRESCALER[2:0] 15:8 23:16 TICKON 31:24 0x38 PINSTATE 7:0 PINSTATE[7:0] 15:8 23:16 31:24 0x3C NSCHK 7:0 EXTINT[7:0] 15:8 23:16 31:24 NMI 0x40 NONSEC 7:0 EXTINT[7:0] 15:8 23:16 31:24 NMI 29.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16-, and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers require synchronization when read and/or written. Synchronization is denoted by the "Read-Synchronized" and/or "Write-Synchronized" property in each individual register description. Some registers are enable-protected, meaning they can only be written when the module is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. On SAM L11 devices, the Mix-Secure peripheral has different types of registers (Non-Secure, Secure, Write-Secure, Mix-Secure, and Write-Mix-Secure) with different access permissions for each bitfield. Refer to Mix-Secure Peripherals for more details. In the following register descriptions, the access permissions are specified as shown in the following figure. Bit 7 6 5 4 3 2 1 0 CMD[7:0] Access R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW TrustZone Non-Protected Devices Access TrustZone Protected Devices Non-Secure Access TrustZone Protected Devices Secure Access SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 551 29.8.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00 Property:  PAC Write-Protection, Secure Bit 7 6 5 4 3 2 1 0 CKSEL ENABLE SWRST Access RW/-/RW RW/-/RW W/-/W Reset 0 0 0 Bit 4 – CKSEL Clock Selection The EIC can be clocked either by GCLK_EIC (when a frequency higher than 32KHz is required for filtering) or by CLK_ULP32K (when power consumption is the priority). This bit is not Write-Synchronized. Value Description 0 The EIC is clocked by GCLK_EIC. 1 The EIC is clocked by CLK_ULP32K. Bit 1 – ENABLE Enable Due to synchronization there is a delay between writing to CTRLA.ENABLE until the peripheral is enabled/disabled. The value written to CTRLA.ENABLE will read back immediately and the Enable bit in the Synchronization Busy register will be set (SYNCBUSY.ENABLE=1). SYNCBUSY.ENABLE will be cleared when the operation is complete. This bit is not Enable-Protected. This bit is Write-Synchronized. Value Description 0 The EIC is disabled. 1 The EIC is enabled. Bit 0 – SWRST Software Reset Writing a '0' to this bit has no effect. Writing a '1' to this bit resets all registers in the EIC to their initial state, and the EIC will be disabled. Writing a '1' to CTRLA.SWRST will always take precedence, meaning that all other writes in the same write operation will be discarded. Due to synchronization there is a delay from writing CTRLA.SWRST until the Reset is complete. CTRLA.SWRST and SYNCBUSY.SWRST will both be cleared when the Reset is complete. This bit is not Enable-Protected. This bit is Write-Synchronized. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 552 Value Description 0 There is no ongoing reset operation. 1 The reset operation is ongoing. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 553 29.8.2 Non-Maskable Interrupt Control Name:  NMICTRL Offset:  0x01 Reset:  0x00 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the NMI interrupt is set as Non-Secure in the NONSEC register (NONSEC.NMI bit). Bit 7 6 5 4 3 2 1 0 NMIASYNCH NMIFILTEN NMISENSE[2:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 Bit 4 – NMIASYNCH Non-Maskable Interrupt Asynchronous Edge Detection Mode The NMI edge detection can be operated synchronously or asynchronously to the EIC clock. Value Description 0 The NMI edge detection is synchronously operated. 1 The NMI edge detection is asynchronously operated. Bit 3 – NMIFILTEN Non-Maskable Interrupt Filter Enable Value Description 0 NMI filter is disabled. 1 NMI filter is enabled. Bits 2:0 – NMISENSE[2:0] Non-Maskable Interrupt Sense Configuration These bits define on which edge or level the NMI triggers. Value Name Description 0x0 NONE No detection 0x1 RISE Rising-edge detection 0x2 FALL Falling-edge detection 0x3 BOTH Both-edge detection 0x4 HIGH High-level detection 0x5 LOW Low-level detection 0x6 - 0x7 - Reserved SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 554 29.8.3 Non-Maskable Interrupt Flag Status and Clear Name:  NMIFLAG Offset:  0x02 Reset:  0x0000 Property:  Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the NMI interrupt is set as Non-Secure in the NONSEC register (NONSEC.NMI bit). Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 NMI Access RW/RW*/RW Reset 0 Bit 0 – NMI Non-Maskable Interrupt This flag is cleared by writing a '1' to it. This flag is set when the NMI pin matches the NMI sense configuration, and will generate an interrupt request. Writing a '0' to this bit has no effect. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 555 29.8.4 Synchronization Busy Name:  SYNCBUSY Offset:  0x04 Reset:  0x00000000 Property:  Secure Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 ENABLE SWRST Access R/-/R R/-/R Reset 0 0 Bit 1 – ENABLE Enable Synchronization Busy Status Value Description 0 Write synchronization for CTRLA.ENABLE bit is complete. 1 Write synchronization for CTRLA.ENABLE bit is ongoing. Bit 0 – SWRST Software Reset Synchronization Busy Status Value Description 0 Write synchronization for CTRLA.SWRST bit is complete. 1 Write synchronization for CTRLA.SWRST bit is ongoing. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 556 29.8.5 Event Control Name:  EVCTRL Offset:  0x08 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the external interrupt x (EXTINTx) is set as Non-Secure in the NONSEC register (NONSEC.EXTINTx bit). Some restrictions apply for the Non-Secure accesses to an EnabledProtected register as it will not be possible for the Non-Secure to configure it once this register is enabled by the Secure application. This will require some veneers to be implemented on Secure side. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 EXTINTEO[7:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bits 7:0 – EXTINTEO[7:0] External Interrupt Event Output Enable The bit x of EXTINTEO enables the event associated with the EXTINTx pin. Value Description 0 Event from pin EXTINTx is disabled. 1 Event from pin EXTINTx is enabled and will be generated when EXTINTx pin matches the external interrupt sensing configuration. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 557 29.8.6 Interrupt Enable Clear Name:  INTENCLR Offset:  0x0C Reset:  0x00000000 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the external interrupt x (EXTINTx) is set as Non-Secure in the NONSEC register (NONSEC.EXTINTx bit). This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 31 30 29 28 27 26 25 24 NSCHK Access RW/RW/RW Reset 0 Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 EXTINT[7:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 31 – NSCHK Non-secure Check Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the NSCHK Interrupt Enable bit. Bits 7:0 – EXTINT[7:0] External Interrupt Enable The bit x of EXTINT enables the interrupt associated with the EXTINTx pin. Writing a '0' to bit x has no effect. Value Description 0 The external interrupt x is disabled. 1 The external interrupt x is enabled. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 558 29.8.7 Interrupt Enable Set Name:  INTENSET Offset:  0x10 Reset:  0x00000000 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the external interrupt x (EXTINTx) is set as Non-Secure in the NONSEC register (NONSEC.EXTINTx bit). This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear (INTENCLR) register. Bit 31 30 29 28 27 26 25 24 NSCHK Access RW/RW/RW Reset 0 Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 EXTINT[7:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 31 – NSCHK Non-secure Check Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the NSCHK Interrupt Enable bit. Bits 7:0 – EXTINT[7:0] External Interrupt Enable The bit x of EXTINT enables the interrupt associated with the EXTINTx pin. Writing a '0' to bit x has no effect. Writing a '1' to bit x will set the External Interrupt Enable bit x, which enables the external interrupt EXTINTx. Value Description 0 The external interrupt x is disabled. 1 The external interrupt x is enabled. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 559 29.8.8 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x14 Reset:  0x00000000 Property:  Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the external interrupt x (EXTINTx) is set as Non-Secure in the NONSEC register (NONSEC.EXTINTx bit). Bit 31 30 29 28 27 26 25 24 NSCHK Access RW/RW/RW Reset 0 Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 EXTINT[7:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 31 – NSCHK Non-secure Check Interrupt The flag is cleared by writing a '1' to it. This flag is set when write to either NONSEC and NSCHK register and if the related bit of NSCHK is enabled and the related bit of NONSEC is zero. Bits 7:0 – EXTINT[7:0] External Interrupt The flag bit x is cleared by writing a '1' to it. This flag is set when EXTINTx pin matches the external interrupt sense configuration and will generate an interrupt request if 29.8.6 INTENCLR.EXTINT[x] or 29.8.7 INTENSET.EXTINT[x] is '1'. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the External Interrupt x flag. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 560 29.8.9 External Interrupt Asynchronous Mode Name:  ASYNCH Offset:  0x18 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the external interrupt x (EXTINTx) is set as Non-Secure in the NONSEC register (NONSEC.EXTINTx bit). Some restrictions apply for the Non-Secure accesses to an EnabledProtected register as it will not be possible for the Non-Secure to configure it once this register is enabled by the Secure application. This will require some veneers to be implemented on Secure side. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 ASYNCH[7:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bits 7:0 – ASYNCH[7:0] Asynchronous Edge Detection Mode The bit x of ASYNCH set the Asynchronous Edge Detection Mode for the interrupt associated with the EXTINTx pin. Value Description 0 The EXTINT x edge detection is synchronously operated. 1 The EXTINT x edge detection is asynchronously operated. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 561 29.8.10 External Interrupt Sense Configuration Name:  CONFIG Offset:  0x1C Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the external interrupt x (EXTINTx) is set as Non-Secure in the NONSEC register (NONSEC.EXTINTx bit). Some restrictions apply for the Non-Secure accesses to an EnabledProtected register as it will not be possible for the Non-Secure to configure it once this register is enabled by the Secure application. This will require some veneers to be implemented on Secure side. Bit 31 30 29 28 27 26 25 24 FILTENx SENSEx[2:0] FILTENx SENSEx[2:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 FILTENx SENSEx[2:0] FILTENx SENSEx[2:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 FILTENx SENSEx[2:0] FILTENx SENSEx[2:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 FILTENx SENSEx[2:0] FILTENx SENSEx[2:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bits 3,7,11,15,19,23,27,31 – FILTENx Filter Enable x [x=7..0] Value Description 0 Filter is disabled for EXTINT[x] input. 1 Filter is enabled for EXTINT[x] input. Bits 0:2,4:6,8:10,12:14,16:18,20:22,24:26,28:30 – SENSEx Input Sense Configuration x [x=7..0] These bits define on which edge or level the interrupt or event for EXTINT[x] will be generated. Value Name Description 0x0 NONE No detection 0x1 RISE Rising-edge detection 0x2 FALL Falling-edge detection SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 562 Value Name Description 0x3 BOTH Both-edge detection 0x4 HIGH High-level detection 0x5 LOW Low-level detection 0x6 - 0x7 - Reserved SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 563 29.8.11 Debouncer Enable Name:  DEBOUNCEN Offset:  0x30 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the external interrupt x (EXTINTx) is set as Non-Secure in the NONSEC register (NONSEC.EXTINTx bit). Some restrictions apply for the Non-Secure accesses to an EnabledProtected register as it will not be possible for the Non-Secure to configure it once this register is enabled by the Secure application. This will require some veneers to be implemented on Secure side. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 DEBOUNCEN[7:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bits 7:0 – DEBOUNCEN[7:0] Debouncer Enable The bit x of DEBOUNCEN set the Debounce mode for the interrupt associated with the EXTINTx pin. Value Description 0 The EXTINT x edge input is not debounced. 1 The EXTINT x edge input is debounced. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 564 29.8.12 Debouncer Prescaler Name:  DPRESCALER Offset:  0x34 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected, Secure Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 TICKON Access RW/-/RW Reset 0 Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 STATES PRESCALER[2:0] Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 Bit 16 – TICKON Pin Sampler frequency selection This bit selects the clock used for the sampling of bounce during transition detection. Value Description 0 The bounce sampler is using GCLK_EIC. 1 The bounce sampler is using the low frequency clock. Bit 3 – STATES Debouncer Number of States This bit selects the number of samples by the debouncer low frequency clock needed to validate a transition from current pin state to next pin state in synchronous debouncing mode for pins EXTINT[7:0]. Value Description 0 The number of low frequency samples is 3. 1 The number of low frequency samples is 7. Bits 2:0 – PRESCALER[2:0] Debouncer Prescaler These bits select the debouncer low frequency clock for pins EXTINT[7:0]. Value Name Description 0x0 F/2 EIC clock divided by 2 0x1 F/4 EIC clock divided by 4 0x2 F/8 EIC clock divided by 8 SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 565 Value Name Description 0x3 F/16 EIC clock divided by 16 0x4 F/32 EIC clock divided by 32 0x5 F/64 EIC clock divided by 64 0x6 F/128 EIC clock divided by 128 0x7 F/256 EIC clock divided by 256 SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 566 29.8.13 Pin State Name:  PINSTATE Offset:  0x38 Reset:  0x00000000 Property:  PAC Mix-Secure Important:  For SAM L11 Non-Secure accesses, read accesses (R*) are allowed only if the external interrupt x (EXTINTx) is set as Non-Secure in the NONSEC register (NONSEC.EXTINTx bit). Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 PINSTATE[7:0] Access R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R Reset 0 0 0 0 0 0 0 0 Bits 7:0 – PINSTATE[7:0] Pin State These bits return the valid pin state of the debounced external interrupt pin EXTINTx. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 567 29.8.14 Security Attribution Check Name:  NSCHK Offset:  0x3C Reset:  0x00000000 Property:  PAC Write-Protection This register allows the user to select one or more external pins to check their security attribution as nonsecured. Important:  This register is only available for SAM L11 and has no effect for SAM L10. Bit 31 30 29 28 27 26 25 24 NMI Access RW/RW/RW Reset 0 Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 EXTINT[7:0] Access RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW Reset 0 0 0 0 0 0 0 0 Bit 31 – NMI Non-Maskable Interrupt Security Attribution Check This bit selects the Non-Maskable Interrupt pin for security attribution check. If the NMI bit in NONSECNMI is set to the opposite value, then the NSCHK interrupt flag will be set. Value Description 0 0-to-1 transition will be detected on corresponding NONSEC bit. 1 1-to-0 transition will be detected on corresponding NONSEC bit. Bits 7:0 – EXTINT[7:0] External Interrupts Security Attribution Check These bits select the individual pins for security attribution check. If any pin selected in NSCHK has the corresponding bit in NONSEC set to the opposite value, then the NSCHK interrupt flag will be set. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 568 Value Description 0 0-to-1 transition will be detected on corresponding NONSEC bit. 1 1-to-0 transition will be detected on corresponding NONSEC bit. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 569 29.8.15 Non-secure Interrupt Name:  NONSEC Offset:  0x40 Reset:  0x00000000 Property:  PAC Write-Protection, Write-Secure This register allows to set the NMI or external interrupt control and status registers in non-secure mode, individually per interrupt pin. Important:  This register is only available for SAM L11 and has no effect for SAM L10. Bit 31 30 29 28 27 26 25 24 NMI Access RW/R/RW Reset 0 Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 EXTINT[7:0] Access RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW Reset 0 0 0 0 0 0 0 0 Bit 31 – NMI Non-Secure Non-Maskable Interrupt This bit enables the non-secure mode of NMI. The registers whose content is set in non-secure mode by NONSEC.NMI are NMICTRL and NMIFLAG registers. Value Description 0 NMI is secure. 1 NMI is non-secure. Bits 7:0 – EXTINT[7:0] Non-Secure External Interrupt The bit x of EXTINT enables the non-secure mode of EXTINTx. The registers whose EXTINT bit or bitfield x is set in non-secure mode by NONSEC.EXTINTx are EVCTRL, ASYNCH, IDEBOUNCEN, NTENCLR, INTENSET, INTFLAG and CONFIG registers. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 570 Value Description 0 EXTINTx is secure. 1 EXTINTx is non-secure. SAM L10/L11 Family EIC – External Interrupt Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 571 30. NVMCTRL – Nonvolatile Memory Controller 30.1 Overview Non-Volatile Memory (NVM) is a reprogrammable Flash memory that retains program and data storage even with power off. It embeds three separate arrays namely FLASH, Data FLASH and AUX FLASH. The Data FLASH array can be programmed while reading the FLASH array. It is intended to store data while executing from the FLASH without stalling. AUX FLASH stores data needed during the device startup such as calibration and system configuration. The NVM Controller (NVMCTRL) connects to the AHB and APB bus interfaces for system access to the NVM block. The AHB interface is used for reads and writes to the NVM block, while the APB interface is used for commands and configuration. 30.2 Features • 32-bit AHB interface for reads and writes • Write-While-Read (WWR) Data Flash • All NVM Sections are Memory Mapped to the AHB, Including Calibration and System Configuration • 32-bit APB Interface for Commands and Control • Programmable Wait States for Read Optimization • 6 Regions can be Individually Protected or Unprotected • Additional Protection for Bootloader • Interface to Power Manager for Power-Down of Flash Blocks in Sleep Modes • Can Optionally Wake-up on Exit from Sleep or on First Access • Direct-mapped Cache • TrustZone Support (SAM L11) Note:  A register with property "Enable-Protected" may contain bits that are not enable-protected. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 572 30.3 Block Diagram Figure 30-1. Block Diagram Command and Control NVM Interface Cache NVMCTRL NVM Block AHB APB Flash array Data Flash array 30.4 Signal Description Not applicable. 30.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described in the following sections. 30.5.1 Power Management The NVMCTRL will continue to operate in any sleep mode where the selected source clock is running. The NVMCTRL interrupts can be used to wake up the device from sleep modes. The Power Manager will automatically put the NVM block into a low-power state when entering sleep mode. This is based on the Control B register (CTRLB) SLEEPPRM bit setting. Refer to the 30.8.2 CTRLB.SLEEPPRM register description for more details. The NVM block goes into low-power mode automatically when the device enters STANDBY mode regardless of SLEEPPRM. The NVM Page Buffer is lost when the NVM goes into low power mode therefore a write command must be issued prior entering the NVM low power mode. NVMCTRL SLEEPPRM can be disabled to avoid such loss when the CPU goes into sleep except if the device goes into STANDBY mode for which there is no way to retain the Page Buffer. Related Links 22. PM – Power Manager 30.5.2 Clocks Two synchronous clocks are used by the NVMCTRL. One is provided by the AHB bus (CLK_NVMCTRL_AHB) and the other is provided by the APB bus (CLK_NVMCTRL_APB). For higher SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 573 system frequencies, a programmable number of wait states can be used to optimize performance. When changing the AHB bus frequency, the user must ensure that the NVM Controller is configured with the proper number of wait states. Refer to the Electrical Characteristics for the exact number of wait states to be used for a particular frequency range. 30.5.3 Interrupts The NVM Controller interrupt request line is connected to the interrupt controller. Using the NVMCTRL interrupt requires the interrupt controller to be programmed first. 30.5.4 Events The NVMCTRL can take the following actions on an input event: • Write zeroes in one Data FLASH row: Refer to 30.6.7 Tamper Erase for details. • Write a page in the FLASH or in the Data FLASH: Refer to 30.6.6 Event Automatic Write for details. The NVMCTRL uses only asynchronous events, so the asynchronous Event System channel path must be configured. By default, the NVMCTRL will detect a rising edge on the incoming event. If the NVMCTRL action must be performed on the falling edge of the incoming event, the event line must be inverted first. This is done by setting the corresponding Event Invert Enable bit in Event Control register (NVMCTRL.AUTOWINV=1). 30.5.5 Debug Operation When an external debugger forces the CPU into debug mode, the peripheral continues normal operation except that FLASH reads are not cached so that the cache state is not altered by debug tools. 30.5.6 Register Access Protection All registers with write-access are optionally write-protected by the Peripheral Access Controller (PAC), except the following registers: • Interrupt Flag Status and Clear register (INTFLAG) • Status register (STATUS) Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. When TrustZone is supported (SAM L11 only), all register reads are allowed. Non-secure writes to APB registers are limited as follows. Illegal writes will be ignored. • Some commands written to CTRLA such as Write/Erase and Lock/Unlock are only permitted to non-secure application and data space. • Writes to all other registers except CTRLC and INTFLAG are not allowed. Related Links 15. PAC - Peripheral Access Controller 30.5.7 SAM L11 TrustZone Specific Register Access Protection The NVMCTRL is a split-secure APB module, all registers are available in the secure alias and only a subset of registers is available in the non-secure alias with limited access. When NONSEC.WRITE is read zero, all APB write accesses to the non-secure APB alias and all nonsecure AHB write accesses to the Page Buffer are discarded. The latter returns a hardfault. Any attempt to change the configuration via the non-secure alias is silently ignored. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 574 Debug Access to the bus system can be restricted to allow only accesses to non-secure regions or reject all accesses. See the section on the NVMCTRL Debugger Access Level for details. Note:  Refer to the Mix-Secure Peripherals section in the SAM L11 Security Features chapter for more information. 30.5.8 Analog Connections Not applicable. 30.6 Functional Description 30.6.1 Principle of Operation The NVM Controller is a slave on the AHB and APB buses. It responds to commands, read requests and write requests, based on user configuration. 30.6.1.1 Initialization After power up, the NVM Controller goes through a power-up sequence. During this time, access to the NVM Controller from the AHB bus is halted. Upon power-up completion, the NVM Controller is operational without any need for user configuration. 30.6.2 Memory Organization Refer to the Physical Memory Map for memory sizes and addresses for each device. The NVM is organized into rows, where each row contains four pages, as shown in the NVM Row Organization figure. The NVM has a row-erase granularity, while the write granularity is by page. In other words, a single row erase will erase all four pages in the row, while four write operations are used to write the complete row. Figure 30-2. NVM Row Organization Row n Page (n*4) + 3 Page (n*4) + 2 Page (n*4) + 1 Page (n*4) + 0 The NVM block contains the AUX FLASH which contain calibration and system configuration, the FLASH area intended to store code and a separate array dedicated to data storage called Data FLASH that can be modified while the FLASH is read (no bus stall). All these areas are memory mapped. Refer to the NVM Organization figure below for details. The calibration and auxiliary space contains factory calibration and system configuration information. These spaces can be read from the AHB bus in the same way as the FLASH. Note that Data FLASH requires more cycles to be read. The Data FLASH are can be executable, however this is not recommended as it can weaken an application security and also affect performances. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 575 Figure 30-3. NVM Memory Organization Data Flash Flash Application Flash Boot BOOTPROT 0x00000000 0x00400000 The lower rows in the FLASH can be allocated as a boot loader section by using the BOOTPROT fuses. The boot loader section size is defined by the BOOTPROT fuses expressed in number of rows. Important:  Refer to the Boot ROM section to get Chip Erase commands effects for this specific BOOT area. 30.6.3 Region Unlock Bits The NVMCTRL has the ability to lock regions defined in the NVM Memory Organization figures. When a region is locked all modify (i.e. write or erase) commands directed to these regions are discarded. When such an operation occurs a LOCKE error is reported in the INTFLAG register and can generate an interruption. To lock or unlock a region, write a one to the bitfield corresponding to the selected regions in the SULCK and NSULCK registers with the correct key. Writes to these registers are silently discarded when the key is not correct. Writing these registers with the correct key will temporarily lock/unlock the corresponding regions. The new setting will stay in effect until the next Reset, or until the setting is changed again while writing SULCK and NSULCK. The current status of the lock can be determined by reading the SULCK and NSULCK registers. To change the default lock/unlock setting for a region, the user row of the AUX FLASH must be written using the Write Page command. Writing to the AUX FLASH user row will take effect after the next Reset. Therefore, a boot of the device is needed for changes in the lock/unlock setting to take effect. Refer to the Physical Memory Map for calibration and auxiliary space address mapping. 30.6.4 Command and Data Interface The NVM Controller is addressable from the APB bus, while the NVM main address space is addressable from the AHB bus. Read and automatic page write operations are performed by addressing the FLASH, Data FLASH and AUX FLASH spaces directly, while other operations such as manual page writes and row erases must be performed by issuing commands through the NVM Controller. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 576 To issue a command, the CTRLA.CMD bits must be written along with the CTRLA.CMDEX value. When a command is issued, STATUS.READY is cleared and rises again when the command has completed. INTFLAG.DONE is also set when a command completes. Any commands written while INTFLAG.READY is low will be ignored. The CTRLB and CTRLC registers must be used to control the power reduction mode, read wait states, and the write mode. 30.6.4.1 NVM Read Reading from the FLASH is performed via the AHB bus. Read data is available after the configured number of read wait states (CTRLB.RWS) set in the NVM Controller. The number of cycles data are delayed to the AHB bus is determined by the read wait states. Reading the NVM main address space while a programming or erase operation is ongoing on the NVM main array results in an AHB bus stall until the end of the operation. Reading the NVM main array does not stall the bus when the Data FLASH is being programmed or erased. 30.6.4.2 DATA FLASH Read Reading from the Data FLASH is performed via the AHB bus by addressing the Data FLASH address space directly. Read timings are increased by one cycle compared to regular FLASH read timings when access size is Byte or half-Word. The AHB data phase is twice as long in case of full-Word-size access. It is not possible to read the Data FLASH while the NVM main array is being written or erased (the read is stalled), whereas the Data FLASH can be written or erased while the main array is being read. The Data FLASH address space is not cached, therefore it is recommended to limit access to this area for performance and power consumption considerations. 30.6.4.3 NVM Write Data to be written to the NVM block are first written to and stored in an internal buffer called the page buffer. The page buffer contains the same number of bytes as an NVM page. Writes to the page buffer must be 16 or 32 bits. 8-bit writes to the page buffer are not allowed and will cause a bus error. Both FLASH and DATA FLASH share the same page buffer. Writing to the NVM block via the AHB bus is performed by a load operation to the page buffer. For each AHB bus write, the address is stored in the ADDR register. After the page buffer has been loaded with the required number of bytes, the page can be written to the array pointed by ADDR by setting CTRLA.CMD to 'Write Page' and setting the key value to CMDEX. The LOAD bit in the STATUS register indicates whether the page buffer has been loaded or not. If the NVMCTRL is busy processing a write command (STATUS.READY=0), then the AHB bus is stalled upon AHB write until the ongoing command completes. The NVM Controller requires that an erase must be done before programming. Rows can be individually erased by the Erase Row command to erase a row. Automatic page writes are enabled by writing the manual write bit to zero (CTRLB.MANW=0). This will trigger a write operation to the page addressed by ADDR when the last location of the page is written. Because the address is automatically stored in ADDR during the APB bus write operation, the last given address will be present in the ADDR register. There is no need to load the ADDR register manually, unless a different page in memory is to be written. The page buffer is automatically cleared upon a 'Write Page' command completion. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 577 30.6.4.3.1 Procedure for Manual Page Writes (CTRLB.MANW=1) The row to be written to must be erased before the write command is given. • Write to the page buffer by addressing the NVM main address space directly • Write the page buffer to memory: CTRL.CMD='Write Page' and CMDEX • The READY bit in the INTFLAG register will be low while programming is in progress, and access through the AHB will be stalled 30.6.4.3.2 Procedure for Automatic Page Writes (CTRLB.MANW=0) The row to be written to must be erased before the last write to the page buffer is performed. Note that partially written pages must be written with a manual write. • Write to the page buffer by addressing the NVM main address space directly. When the last location in the page buffer is written, the page is automatically written to NVM main address space. • INTFLAG.READY will be zero while programming is in progress and access through the AHB will be stalled. 30.6.4.4 Page Buffer Clear The page buffer is automatically set to all '1' after a page write is performed. If a partial page has been written and it is desired to clear the contents of the page buffer, the Page Buffer Clear command can be used. The status of the Page Buffer is reflected by the STATUS.LOAD bitfield, when the PBC command is issued successfuly, STATUS.LOAD reads 0. 30.6.4.5 Erase Row Before a page can be written, the row containing that page must be erased. The Erase Row command can be used to erase the desired row in the NVM (same command for FLASH, DATA FLASH and AUX FLASH). Erasing the row sets all bits to '1'. If the row resides in a region that is locked, the erase will not be performed and the Lock Error bit in the INTFLAG register (INTFLAG.LOCKE) will be set. 30.6.4.5.1 Procedure for Erase Row • Write the address of the row to erase to ADDR. Any address within the row can be used. • Issue an Erase Row command. Note:  The NVM Address bit field in the Address register (ADDR.ADDR) uses 16-bit addressing. 30.6.4.6 Set and Clear Power Reduction Mode The NVM Controller and block can be taken in and out of power reduction mode through the Set and Clear Power Reduction Mode commands. When the NVM Controller and block are in power reduction mode, the Power Reduction Mode bit in the Status register (STATUS.PRM) is set. 30.6.5 NVM User Configuration The NVM user configuration resides in the AUX FLASH user row. Refer to the Physical Memory Map of the device for calibration and auxiliary space address mapping. The NSULCK and SULCK bitfields in the user row define respectively the NSULCK and SULCK register default value after a reset. 30.6.6 Event Automatic Write The Event Automatic Write feature is enabled by setting EVCTRL.AUTOWEI=1. When enabled, an event input from EVSYS will trigger a page programming command. The polarity of the input event can be inverted by setting EVCTRL.AUTOWINV. The page written is addressed by the address register (ADDR) SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 578 and can reside in program or data memory. To use this feature, the row must be previously erased and the page buffer must contain the desired data to be written. As the Page Buffer is lost when the NVM enters low power mode (refer to 30.5.1 Power Management ) cannot be used if the device enters STANDBY mode or if the NVM uses power reduction modes. The cache coherency is not ensured after an Event Automatic Write in a FLASH page. The FLASH region is cacheable, it is the user responsability to clear the cache after such an action. Note that the Data FLASH is not subject to cache coherency issues since it is not cacheble. 30.6.7 Tamper Erase Tamper Erase ensures rapid overwrite on tamper of a Data FLASH row selected by SECCTRL.TEROW. When a RTC tamper event occur while tamper erase is enabled (SECCTRL.TAMPEEN=1): • the Tamper Erase row in data space addressed by SECCTRL.TEROW is written to zero. This is performed using a special overwrite mechanism in the NVM block that overwrites the complete row with zero. The RTC must be configured to generate the tamper erase event. Note:  Data Flash endurance is affected by the tamper erase feature. Refer to the "NVM Reliability Characteristics" from Electrical Characteristics chapter. 30.6.8 Silent Access When enabled (SECCTRL.SILACC=1), Silent accesses are performed when accessing one Data Flash row selected by SECCTRL.TEROW. The physical and logical size of the TEROW is divided by two to store each word of Data and its complement to reduce Data Flash reading noise. When Silent Access is enabled, data in the selected Tamper Erase ROW must be accessed using following address mapping: TEROW_base_address W31 W30 W29 … W3 W2 W1 W0 Page Data Data Data Data Data Data Data Data page0 Data Data Data Data Data Data Data Data page1 reserved reserved reserved reserved reserved reserved reserved reserved page2 reserved reserved reserved reserved reserved reserved reserved reserved page3 TEROW_base_address + ROW size All accesses to Reserved area are discarded and generate a bus error. Note that the physical TEROW mapping in Data Flash is the following: TEROW_physical_base_address W31 W30 W29 … W3 W2 W1 W0 Page CompData Data CompData Data CompData Data CompData Data page0 CompData Data CompData Data CompData Data CompData Data page1 SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 579 W31 W30 W29 … W3 W2 W1 W0 Page CompData Data CompData Data CompData Data CompData Data page2 CompData Data CompData Data CompData Data CompData Data page3 TEROW_physical_base_address + ROW size 30.6.9 Chip Erase The various chip erase operations are managed by the boot ROM code. For more details, refer to the Boot ROM section. 30.6.10 Cache The NVM Controller cache reduces the device power consumption and improves system performance when wait states are required. Only the Data FLASH area is cached. It is a direct-mapped cache that implements 64 lines of 64 bits (i.e., 512 Bytes). NVM Controller cache can be enabled by writing a '0' to the Cache Disable bit in the Control B register (CTRLB.CACHEDIS). The cache can be configured to three different modes using the Read Mode bit group in the Control B register (CTRLB.READMODE). The INVALL command can be issued using the Command bits in the Control A register to invalidate all cache lines (CTRLA.CMD=INVALL). Commands affecting NVM content automatically invalidate cache lines. 30.6.11 Debugger Access Level The Debugger Access Level (DSU STATUSB.DAL) defines the access rights of a debugger connected to the device. • 0x0 = Access to very limited features (basically only the DSU external address space) • 0x1 = Access to all non-secure memory; can debug non-secure CPU code (SAM L11 only) • 0x2 = Access to all memory; can debug secure and non-secure CPU code DAL can be set to a lower setting using a SDAL command (CTRLA register). Important:  Issuing a SDAL command to set a higher setting for DAL will set INTFLAG.PROGE. Only a Chip Erase can change DAL to a higher setting. 30.6.12 SAM L11 TrustZone Protection Considerations On TrustZone protected devices, the FLASH and Data FLASH areas are partitioned into secure, nonsecure and non-secure callable sections in order to accommodate with TrustZone core capability. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 580 Figure 30-4. NVM Memory Organization AS BOOTPROT DS Non-Secure Application Flash Data Flash, Non-Secure Secure Boot Flash Data Flash, Secure Secure Application Flash Non-Secure Boot Flash 0x00400000 0x00000000 NSC Boot Flash NSC App Flash BS ANSC BNSC The various ranges and attributes are shown below. Table 30-1. Memory Regions and Attributes Memory Region Base Address Size Attribute FLASH boot secure 0x00000000 BS*ROWSIZE Secure FLASH boot non-secure callable BS*ROWSIZEBNSC*0x20 BNSC*0x20 Secure (included in Boot secure) FLASH boot non-secure BS*ROWSIZE (remaining boot NVM) Non-secure FLASH application secure BOOTPROT*ROWSIZE AS*ROWSIZE Secure FLASH application nonsecure callable BOOTPROT*ROWSIZEANSC*0x20 ANSC*0x20 Secure (included in Application secure) FLASH application nonsecure (BOOTPROT +AS)*ROWSIZE (remaining application NVM) Non-secure Data FLASH secure 0x00400000 DS*ROWSIZE Secure Data FLASH non-secure 0x00400000 + DS*ROWSIZE (remaining Data NVM area) Non-secure Access to the various sections is restricted as shown in the following table. All sections can be read and written without restriction when the access is secure. When the access is non-secure the secure sections SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 581 are not accessible. When defined non-secure callable sections have the same attributes as the secure sections, therefore the NVMCTRL considers them as secure regions. The system may also have a secure callable boot and application regions. These regions have the same attributes as the secure sections, so there is no special treatment needed in NVMCTRL. Any illegal access will result in a bus error. The BOOT and Application non-secure callable regions are shown for reference but have no effect on the NVMCTRL. These regions are included in secure regions therefore the NVMCTRL considers them as secure regions. Table 30-2. Memory Regions AHB Access Limitations Memory Region Secure Access Non-Secure Access Limitations FLASH Boot secure R+W - FLASH Boot non-secure R+W R+W FLASH Application secure R+W - FLASH Application nonsecure R+W R+W Data FLASH secure R+W - Data FLASH non-secure R+W R+W AUX FLASH Calibration Row R+W R AUX FLASH User Row (UROW) R+W R AUX FLASH Boot Configuration (BOCOR) R+W - No read if BCREN is cleared. The Boot Configuration row (BOCOR) contains information that is read by the boot ROM and written to IDAU and NVMCTRL registers. The BOCOR is read/writable if SCFGB.BCREN/BCWEN are set, respectively. Important:  SCFGB.BCREN/BCWEN are copied from BOCOR by the boot ROM. Table 30-3. Memory Regions Modify operations Limitations (WP, EP commands) Memory Region Secure Access NonSecure Access Limitations FLASH Boot secure Y N No if SULCK.BS=0 FLASH Boot non-secure Y Y No if NSULCK.BNS=0 FLASH Application secure Y N No if SULCK.AS=0 SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 582 Memory Region Secure Access NonSecure Access Limitations FLASH Application nonsecure Y Y No if NSULCK.ANS=0 Data FLASH secure Y N No if SULCK.DS=0 Data FLASH non-secure Y Y No if NSULCK.DNS=0 AUX FLASH User Row (UROW) Y N No if BOCOR.URWEN=0 AUX FLASH Boot Configuration (BOCOR) Y N No if BOCOR.BCWEN=0 The NSULCK SULCK bitfields in the user row define respectively the NSULCK and SULCK register default value after a reset. Special care must be taken when sharing the NVMCTRL between the secure and non-secure domains. When the secure code modifies the NVM it is highly recommended that it disables all write accesses to the APB non-secure alias and writes to AHB non-secure regions by writing a 0 to NONSEC.WRITE. This avoids any interference with non-secure modify operations. Note that in this case even a secure application cannot write the page buffer at a non-secure location since the IDAU changes security attributions of Non-Secure transactions to Non-Secure regions to Non-Secure. The NONSEC.WRITE reset value is '1', meaning that it is always possible to program a Non-Secure FLASH or Data FLASH region after a debugger probe cold-plugging. But if the debugger connects with the hot-plugging procedure then NONSEC.WRITE must be '1' to let the debugger program Non-Secure regions otherwise the transaction will cause a hardfault (seen as a DAP fault at DAP level). For applications that don't require Non-Secure regions programming other than from a secure code, it is recommended to always disable Non-Secure writes by disabling NONSEC.WRITE. When disabled secure code needs to enable it to be able to modify Non-Secure regions following this procedure: • disable interrupts • write a one to NONSEC.WRITE to allow writes to the non-secure region • write the page buffer • write a zero to NONSEC.WRITE • enable again the interrupts If the NSCHK interrupt is enabled, a NONSEC.WRITE modification will generate an interrupt so that the non-secure world is aware of this change. Depending on NSCHK.WRITE INTFLAG.NSCHK will rise upon a rising or falling NONSEC.WRITE transition. The interrupt can be configured as secure or non-secure in the NVIC. If secure then a software mechanism can be implemented to call a non-secure NVMCTRL IRQ handler from the secure world. The NVMCTRL monitors the Page Buffer write accesses and accepts only writes to non-secure regions when the transaction is non-secure. Moreover it checks that any write to the page buffer is in the same page as the previous write when the Page Buffer is not empty. When this check fails, an error is returned to the bus master that initiated the transaction. This ensures that it is not possible to mix different page writes into the Page Buffer. Therefore, any Page Buffer write access must at some point be followed by a manual or automatic Write Page (WP) that automatically clears the page buffer or a Clear Page Buffer (PBC) command. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 583 For security reasons, the ADDR register is not accessible from the non-secure alias. The only way to change it is to write a data to the Page Buffer. If the intention is to issue a command that doesn't write the NVM (for instance an Erase Row command (ER)) then the PBC command must be issued to avoid locking further write accesses (even secure writes). The status of the Page Buffer is reflected by the STATUS.LOAD bitfield. 30.6.12.1 Page Buffer Clear When Page Buffer Clear command is issued from the non-secure APB alias, ADDR must point on a nonsecure region otherwise the command is silently discarded. For security reasons, the ADDR register is not accessible from the non-secure alias. The only way to change it is to write a data to the Page Buffer. If the intention is to issue a command that doesn't write the NVM (for instance an Erase Row command (ER)) then the PBC command must be issued to avoid locking further write accesses (even secure writes). ADDR must point to a non-secure NVM region when PBC is issued from the non-secure alias. 30.6.12.2 Page Write The NVMCTRL monitors the Page Buffer write accesses and accepts only writes to non-secure regions when the transaction is non-secure. Moreover it checks that any write to the page buffer is in the same page as the previous write when the Page Buffer is not empty. When this check fails, an error is returned to the bus master that initiated the transaction. This ensures that it is not possible to mix different page writes into the Page Buffer. Therefore, any Page Buffer write access must at some point be followed by a manual or automatic Write Page (WP) that automatically clears the page buffer or a Clear Page Buffer (PBC) command. For security reasons, the ADDR register is not accessible from the non-secure alias. The only way to change it is to write a data to the Page Buffer. If the intention is to issue a command that doesn't write the NVM (for instance an Erase Row command (ER)) then the PBC command must be issued to avoid locking further write accesses (even secure writes). The status of the Page Buffer is reflected by the STATUS.LOAD bitfield. 30.6.12.3 Erase Row ADDR must point to a non-secure region when an ER command is issued from the non-secure APB alias. 30.6.12.4 Lock regions The NVMCTRL has the ability to lock regions with respect to the IDAU memory mapping: • FLASH Boot Secure and Non-Secure Callable regions • FLASH Boot Non-Secure region • FLASH Application secure region • FLASH Application non-Secure and Non-Secure Callable regions • Data FLASH Secure region • Data FLASH Non-Secure region When a region is locked, all modify commands (i.e. write or erase) directed to this region are discarded. A LOCKE error is reported in the INTFLAG register and can generate an interrupt. To lock or unlock a region, write a one to the corresponding bitfield in SULCK and NSULCK registers Writes to these registers are silently discarded if the key is not correct. Writing these registers with the correct key will temporarily lock or unlock the corresponding regions. The new lock setting will stay in effect until the next reset, or until the setting is changed again while writing SULCK and NSULCK. Note:  Writes to these registers are silently discarded if the key is not correct. The current status of the lock can be determined by reading the SULCK and NSULCK registers. To change the default lock/unlock setting for a region, the user row of the AUX FLASH must be written using SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 584 the Write Page command. Writing to the NVM User Row (UROW) will take effect after the next Reset. Therefore, a boot of the device is needed for changes in the lock/unlock setting to take effect. Refer to the Physical Memory Map for calibration and auxiliary space address mapping. SULCK is a Write-Secure register: • This register can only be written by secure masters from the secure alias • This register is always readable by secure or non-secure masters from their respective alias NSULCK is a Write-Mix-Secure register: • This register can always be written by a secure master from the secure alias • Or, by a non-secure master from the non-secure alias only if NONSEC.WRITE is set • This register is always readable by secure or non-secure masters in their respective alias 30.6.12.5 Cache When a line is cached, the type of transaction is stored in the cache. If the line has been updated upon a secure transaction, only secure transaction can hit, otherwise there is a cache miss and the transaction propagates to the NVMCTRL which enforces the security. If the line has been updated upon a non-secure transaction, it can be hit by both the secure or non-secure transactions. In case of a non-secure transaction cache miss, a line is replaced even if it contained a secure data. 30.6.12.6 Data Scrambling When data scrambling is enabled (DSCC.DSCEN), data in the secure portion of the Data FLASH (rows below SCFGAD.DS) is scrambled when written and de-scrambled when read. Scrambling and differential operation can be performed on the same data if the tamper row resides in the secure Data FLASH area and both are enabled. In this case, the process is serial starting with scrambling, followed by Silent Access on writes and the reverse on reads. 30.6.12.7 Tamper Erase The scrambling key stored in DSCC is written to zero when a RTC tamper event occurs in addition to the erase of the row. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 585 30.7 Register Summary Important:  For SAM L11, the NVMCTRL register map is automatically duplicated in a Secure and NonSecure alias: • The Non-Secure alias is at the peripheral base address • The Secure alias is located at the peripheral base address + 0x1000 Refer to Mix-Secure Peripherals for more information on register access rights Offset Name Bit Pos. 0x00 CTRLA 7:0 CMD[6:0] 15:8 CMDEX[7:0] 0x02 ... 0x03 Reserved 0x04 CTRLB 7:0 RWS[3:0] 15:8 FWUP SLEEPPRM[1:0] 23:16 CACHEDIS READMODE[1:0] 31:24 0x08 CTRLC 7:0 MANW 0x09 Reserved 0x0A EVCTRL 7:0 AUTOWINV AUTOWEI 0x0B Reserved 0x0C INTENCLR 7:0 NSCHK KEYE NVME LOCKE PROGE DONE 0x0D ... 0x0F Reserved 0x10 INTENSET 7:0 NSCHK KEYE NVME LOCKE PROGE DONE 0x11 ... 0x13 Reserved 0x14 INTFLAG 7:0 NSCHK KEYE NVME LOCKE PROGE DONE 0x15 ... 0x17 Reserved 0x18 STATUS 7:0 DALFUSE[1:0] READY LOAD PRM 15:8 0x1A ... 0x1B Reserved 0x1C ADDR 7:0 AOFFSET[7:0] 15:8 AOFFSET[15:8] 23:16 ARRAY[1:0] 31:24 0x20 SULCK 7:0 DS AS BS SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 586 Offset Name Bit Pos. 15:8 SLKEY[7:0] 0x22 NSULCK 7:0 DNS ANS BNS 15:8 NSLKEY[7:0] 0x24 PARAM 7:0 FLASHP[7:0] 15:8 FLASHP[15:8] 23:16 DFLASHP[3:0] PSZ[2:0] 31:24 DFLASHP[11:4] 0x28 ... 0x2F Reserved 0x30 DSCC 7:0 DSCKEY[7:0] 15:8 DSCKEY[15:8] 23:16 DSCKEY[23:16] 31:24 DSCKEY[29:24] 0x34 SECCTRL 7:0 DXN DSCEN SILACC TAMPEEN 15:8 TEROW[2:0] 23:16 31:24 KEY[7:0] 0x38 SCFGB 7:0 BCWEN BCREN 15:8 23:16 31:24 0x3C SCFGAD 7:0 URWEN 15:8 23:16 31:24 0x40 NONSEC 7:0 WRITE 15:8 23:16 31:24 0x44 NSCHK 7:0 WRITE 15:8 23:16 31:24 30.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16-, and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers require synchronization when read and/or written. Synchronization is denoted by the "Read-Synchronized" and/or "Write-Synchronized" property in each individual register description. Some registers are enable-protected, meaning they can only be written when the module is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 587 On SAM L11 devices, the Mix-Secure peripheral has different types of registers (Non-Secure, Secure, Write-Secure, Mix-Secure, and Write-Mix-Secure) with different access permissions for each bitfield. Refer to Mix-Secure Peripherals for more details. In the following register descriptions, the access permissions are specified as shown in the following figure. Bit 7 6 5 4 3 2 1 0 CMD[7:0] Access R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW TrustZone Non-Protected Devices Access TrustZone Protected Devices Non-Secure Access TrustZone Protected Devices Secure Access SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 588 30.8.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x0000 Property:  PAC Write-Protection, Write-Mix-Secure Important:  For SAM L11 Non-Secure accesses, write accesses (W*) are allowed only if NonSecure Write is set in the NONSEC register. Bit 15 14 13 12 11 10 9 8 CMDEX[7:0] Access W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 CMD[6:0] Access W/W/W W/W/W W/W/W W/W/W W/W/W W/W/W W/W/W Reset 0 0 0 0 0 0 0 Bits 15:8 – CMDEX[7:0] Command Execution When this bit group is written to the key value 0xA5, the command written to CMD will be executed. If a value different from the key value is tried, the write will not be performed and the key error interrupt (INTFLAG.KEYE) will be set. PROGE is set if a previously written command is not completed yet or in case of bad conditions. The key value must be written at the same time as CMD. If a command is issued through the APB bus on the same cycle as an AHB bus access, the AHB bus access will be given priority. The command will then be executed when the NVM block and the AHB bus are idle. STATUS.READY must be '1' when the command has issued. Note:  The NVM Address bit field in the Address register (ADDR.ADDR) is driving the hardware (8-bit) address to the NVM when a command is executed using CMDEX. Bits 6:0 – CMD[6:0] Command These bits define the command to be executed when the CMDEX key is written. Important:  For SAM L11, only ER, WP, PBC, SDAL0 commands are available from the nonsecure alias. Non-secure ER, WP, PBC are processed only if ADDR points to a non secure address, otherwise a PROGE error is issued. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 589 CMD[6:0] Group Configuration Description 0x00-0x01 - Reserved 0x02 ER Erase Row - Erases the row addressed by the ADDR register in the NVM main array. 0x03 - Reserved 0x04 WP Write Page - Writes the contents of the page buffer to the page addressed by the ADDR register. 0x05-0x41 - Reserved 0x42 SPRM Sets the Power Reduction Mode. 0x43 CPRM Clears the Power Reduction Mode. 0x44 PBC Page Buffer Clear - Clears the page buffer. 0x45 - Reserved 0x46 INVALL Invalidates all cache lines. 0x47-0x4A - Reserved 0x4B SDAL0 Set DAL=0 0x4C (SAM L10 ) Reserved Reserved 0x4C (SAM L11 ) SDAL1 Set DAL=1 0x4D-0x7F - Reserved SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 590 30.8.2 Control B Name:  CTRLB Offset:  0x04 Reset:  0x00000080 Property:  PAC Write-Protection, Write-Secure Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 CACHEDIS READMODE[1:0] Access RW/R/RW RW/R/RW RW/R/RW Reset 0 0 0 Bit 15 14 13 12 11 10 9 8 FWUP SLEEPPRM[1:0] Access RW/R/RW RW/R/RW RW/R/RW Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 RWS[3:0] Access RW/R/RW RW/R/RW RW/R/RW RW/R/RW Reset 0 0 0 0 Bit 18 – CACHEDIS Cache Disable This bit is used to disable the cache. Value Description 0 The cache is enabled 1 The cache is disabled Bits 17:16 – READMODE[1:0] NVMCTRL Read Mode Value Name Description 0x0 NO_MISS_PENALTY The NVM Controller (cache system) does not insert wait states on a cache miss. Gives the best system performance. 0x1 LOW_POWER Reduces power consumption of the cache system, but inserts a wait state each time there is a cache miss. This mode may not be relevant if CPU performance is required, as the application will be stalled and may lead to increased run time. 0x2 DETERMINISTIC The cache system ensures that a cache hit or miss takes the same amount of time, determined by the number of programmed Flash wait states. This mode can be used for real-time applications that require deterministic execution timings. 0x3 Reserved SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 591 Bit 11 – FWUP Cache Disable This bit is used to disable the cache. Value Description 0 Fast wake-up is turned off 1 Fast wake-up is turned on Bits 9:8 – SLEEPPRM[1:0] Power Reduction Mode during Sleep Indicates the Power Reduction Mode during sleep. Value Name Description 0x0 WAKEUPACCESS NVM block enters low-power mode when entering sleep. NVM block exits low-power mode upon first access. 0x1 WAKEUPINSTANT NVM block enters low-power mode when entering sleep. NVM block exits low-power mode when exiting sleep. 0x2 Reserved 0x3 DISABLED Auto power reduction disabled. Bits 4:1 – RWS[3:0] NVM Read Wait States These bits control the number of wait states for a read operation. '0' indicates zero wait states, '1' indicates one wait state, etc., up to 15 wait states. This register is initialized to 0 wait states. Software can change this value based on the NVM access time and system frequency. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 592 30.8.3 Control C Name:  CTRLC Offset:  0x08 Reset:  0x01 Property:  PAC Write-Protection, Write-Mix-Secure Important:  For SAM L11 Non-Secure accesses, write accesses (W*) are allowed only if NonSecure Write is set in the NONSEC register. Bit 7 6 5 4 3 2 1 0 MANW Access RW/RW*/RW Reset 1 Bit 0 – MANW Manual Write Value Description 0 Writing to the last word in the page buffer will initiate a write operation to the page addressed by the last write operation. This includes writes to FLASH, Data FLASH and AUX FLASH. 1 Write commands must be issued through the CTRLA.CMD register. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 593 30.8.4 Event Control Name:  EVCTRL Offset:  0x0A Reset:  0x00 Property:  PAC Write-Protection, Secure Bit 7 6 5 4 3 2 1 0 AUTOWINV AUTOWEI Access RW/-/RW RW/-/RW Reset 0 0 Bit 1 – AUTOWINV Event Action Value Description 0 Input event polarity is not inverted. 1 Input event polarity is inverted. Bit 0 – AUTOWEI Event Action Value Description 0 Input event has no effect. 1 Input event triggers an Automatic Page Write SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 594 30.8.5 Interrupt Enable Clear Name:  INTENCLR Offset:  0x0C Reset:  0x00 Property:  PAC Write-Protection, Write-Mix-Secure Important:  For SAM L11 Non-Secure accesses, write accesses (W*) are allowed only if NonSecure Write is set in the NONSEC register. This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 7 6 5 4 3 2 1 0 NSCHK KEYE NVME LOCKE PROGE DONE Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 Bit 5 – NSCHK Non-secure Check Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the NSCHK interrupt enable. This bit will read as the current value of the NSCHK interrupt enable. Bit 4 – KEYE Key Error Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the KEYE interrupt enable. This bit will read as the current value of the KEYE interrupt enable. Bit 3 – NVME NVM internal Error Interrupt Clear Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the NVME interrupt enable. This bit will read as the current value of the NVME interrupt enable. Bit 2 – LOCKE Lock Error Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit sets the LOCKE interrupt enable. This bit will read as the current value of the LOCKE interrupt enable. Bit 1 – PROGE Programming Error Interrupt Clear Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the PROGE interrupt enable. This bit will read as the current value of the PROGE interrupt enable. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 595 Bit 0 – DONE NVM Done Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the DONE interrupt enable. This bit will read as the current value of the DONE interrupt enable. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 596 30.8.6 Interrupt Enable Set Name:  INTENSET Offset:  0x10 Reset:  0x00 Property:  PAC Write-Protection, Write-Mix-Secure Important:  For SAM L11 Non-Secure accesses, write accesses (W*) are allowed only if NonSecure Write is set in the NONSEC register. This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear register (INTENCLR). Bit 7 6 5 4 3 2 1 0 NSCHK KEYE NVME LOCKE PROGE DONE Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 Bit 5 – NSCHK Non-secure Check Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit sets the NSCHK interrupt enable. This bit will read as the current value of the NSCHK interrupt enable. Bit 4 – KEYE Key Error Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit sets the KEYE interrupt enable. This bit will read as the current value of the KEYE interrupt enable. Bit 3 – NVME NVM internal Error Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit sets the NVME interrupt enable. This bit will read as the current value of the NVME interrupt enable. Bit 2 – LOCKE Lock Error Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit sets the LOCKE interrupt enable. This bit will read as the current value of the LOCKE interrupt enable. Bit 1 – PROGE Programming Error Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit sets the PROGE interrupt enable. This bit will read as the current value of the PROGE interrupt enable. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 597 Bit 0 – DONE NVM Done Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit sets the DONE interrupt enable. This bit will read as the current value of the DONE interrupt enable. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 598 30.8.7 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x14 Reset:  0x00 Property:  Write-Mix-Secure Important:  For SAM L11 Non-Secure accesses, write accesses (W*) are allowed only if NonSecure Write is set in the NONSEC register. Bit 7 6 5 4 3 2 1 0 NSCHK KEYE NVME LOCKE PROGE DONE Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 Bit 5 – NSCHK Non-Secure Check This flag is set when the NONSEC register is changed and the new value differs from the NSCHK value. This bit can be cleared by writing a '1' to its bit location. Value Description 0 The NONSEC configuration has not changed since last clear. 1 At least one change has been made to the NONSEC configuration since the last clear. Bit 4 – KEYE Key Error This flag is set when a key write-protected register has been accessed in write with a bad key. A one indicates that at least one write access has been discarded. This bit can be cleared by writing a '1' to its bit location. Value Description 0 No key error occured since the last clear. 1 At least one key error occured since the last clear. Bit 3 – NVME NVM internal Error This flag is set on the occurrence of a NVM internal error. This bit can be cleared by writing a '1' to its bit location. Value Description 0 No NVM internal error has happened since this bit was last cleared. 1 At least one NVM internal error has happened since this bit was last cleared. Bit 2 – LOCKE Lock Error This flag is set on the occurrence of a LOCKE error. This bit can be cleared by writing a '1' to its bit location. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 599 Value Description 0 No programming of any locked lock region has happened since this bit was last cleared. 1 Programming of at least one locked lock region has happened since this bit was last cleared. Bit 1 – PROGE Programming Error This flag is set on the occurrence of a PROGE error. This bit can be cleared by writing a '1' to its bit location. Value Description 0 No invalid commands or bad keywords were written in the NVM Command register since this bit was last cleared. 1 An invalid command and/or a bad keyword was/were written in the NVM Command register since this bit was last cleared. Bit 0 – DONE NVM Command Done This bit can be cleared by writing a one to its bit location Value Description 0 The NVM controller has not completed any commands since the last clear. 1 At least one command has completed since the last clear. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 600 30.8.8 Status Name:  STATUS Offset:  0x18 Reset:  0x0X00 Property:  Write-Secure Important:  For SAM L11 Non-Secure accesses, write accesses (W*) are allowed only if NonSecure Write is set in NONSEC register. Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 DALFUSE[1:0] READY LOAD PRM Access R/R/R R/R/R R/R/R R/R/R R/R/R Reset x x 0 0 0 Bits 4:3 – DALFUSE[1:0] DAL Fuse Value This field is the current debugger access level fuse value. Value Description 0 DAL = 0 : Access to very limited features. 1 DAL = 1 (SAM L11 only): Access to all non-secure memory. Can debug non-secure CPU code. 2 DAL = 2 : Access to all memory. Can debug Secure and non-secure CPU code. 3 Reserved Bit 2 – READY NVM Ready Value Description 0 The NVM controller is busy programming or erasing. 1 The NVM controller is ready to accept a new command. Bit 1 – LOAD NVM Page Buffer Active Loading This bit indicates that the NVM page buffer has been loaded with one or more words. Immediately after an NVM load has been performed, this flag is set. It remains set until a page write or a page buffer clear (PBC) command is given. Bit 0 – PRM Power Reduction Mode This bit indicates the current NVM power reduction state. The NVM block can be set in power reduction mode in two ways: through the command interface or automatically when entering sleep with SLEEPPRM set accordingly. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 601 PRM can be cleared in three ways: through AHB access to the NVM block, through the command interface (SPRM and CPRM) or when exiting sleep with SLEEPPRM set accordingly. Value Description 0 NVM is not in power reduction mode. 1 NVM is in power reduction mode. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 602 30.8.9 Address Name:  ADDR Offset:  0x1C Reset:  0x00000000 Property:  PAC Write-Protection, Secure ADDR drives the hardware address to the NVM when a command is executed using CMDEX. This is a Byte aligned address. This register is automatically updated upon AHB writes to the page buffer. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 ARRAY[1:0] Access RW/-/RW RW/-/RW Reset 0 0 Bit 15 14 13 12 11 10 9 8 AOFFSET[15:8] Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 AOFFSET[7:0] Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 0 0 0 Bits 23:22 – ARRAY[1:0] Array Select Value Description 00 Flash 01 Data Flash 10 NVM Rows Bits 15:0 – AOFFSET[15:0] Array Offset Address offset SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 603 30.8.10 Secure Region Unlock Bits Name:  SULCK Offset:  0x20 Reset:  x initially determined from NVM User Row after reset Property:  PAC Write-Protection, Write-Secure Important:  This register is only available for SAM L11 and has no effect for SAM L10. Bit 15 14 13 12 11 10 9 8 SLKEY[7:0] Access W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DS AS BS Access RW/R/RW RW/R/RW RW/R/RW Reset x x x Bits 15:8 – SLKEY[7:0] Secure Unlock Key When this bit group is written to the key value 0xA5, the write will be performed. If a value different from the key value is tried, the write will be discarded and INTFLAG.KEYE set. Bit 2 – DS DATA Secure Unlock Bit Default state after erase will be unlocked (0x1). Value Description 0 The DS region is locked. 1 The DS region is not locked. Bit 1 – AS Application Secure Unlock Bit Default state after erase will be unlocked (0x1). Value Description 0 The AS region is locked. 1 The AS region is not locked. Bit 0 – BS BOOT Secure Unlock Bit Default state after erase will be unlocked (0x1). Value Description 0 The BS region is locked. 1 The BS region is not locked. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 604 30.8.11 Non-Secure Region Unlock Bits Name:  NSULCK Offset:  0x22 Reset:  x initially determined from NVM User Row after reset Property:  PAC Write-Protection, Write-Mix-Secure Important:  For SAM L11 Non-Secure accesses, write accesses (W*) are allowed only if NonSecure Write is set in the NONSEC register. Bit 15 14 13 12 11 10 9 8 NSLKEY[7:0] Access W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DNS ANS BNS Access RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset x x x Bits 15:8 – NSLKEY[7:0] Non-Secure Unlock Key When this bit group is written to the key value 0xA5, the write will be performed. If a value different from the key value is tried, the write will be discarded and INTFLAG.KEYE set. Bit 2 – DNS Data Non-Secure Unlock Bit Note:  For SAM L10 devices, the Non-Secure Data Flash region corresponds to the entire Data Flash region. Value Description 0 The Non-Secure Data Flash region is locked. 1 The Non-Secure Data Flash region is not locked. Bit 1 – ANS Application Non-Secure Unlock Bit Note:  For SAM L10 devices, the Non-Secure APPLICATION region corresponds to the entire APPLICATION Flash region. Value Description 0 The Non-Secure APPLICATION region is locked. 1 The Non-Secure APPLICATION region is not locked. Bit 0 – BNS BOOT Non-Secure Unlock Bit Note:  For SAM L10 devices, the Non-Secure BOOT region corresponds to the entire BOOT Flash region. Value Description 0 The Non-Secure BOOT region is locked. 1 The Non-Secure BOOT region is not locked. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 605 30.8.12 NVM Parameter Name:  PARAM Offset:  0x24 Reset:  0x000XXXXX Property:  Write-Secure Bit 31 30 29 28 27 26 25 24 DFLASHP[11:4] Access R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DFLASHP[3:0] PSZ[2:0] Access R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R Reset 0 0 0 0 x x x Bit 15 14 13 12 11 10 9 8 FLASHP[15:8] Access R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R Reset x x x x x x x x Bit 7 6 5 4 3 2 1 0 FLASHP[7:0] Access R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R R/R/R Reset x x x x x x x x Bits 31:20 – DFLASHP[11:0] Data FLASH area Pages Indicates the number of pages in the Data FLASH array. Bits 18:16 – PSZ[2:0] Page Size Indicates the page size. Not all devices of the device families will provide all the page sizes indicated in the table. Value Name Description 0x0 8 8 bytes 0x1 16 16 bytes 0x2 32 32 bytes 0x3 64 64 bytes 0x4 128 128 bytes 0x5 256 256 bytes 0x6 512 512 bytes 0x7 1024 1024 bytes Bits 15:0 – FLASHP[15:0] FLASH Pages Indicates the number of pages in the FLASH array. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 606 30.8.13 Data Scramble Control Name:  DSCC Offset:  0x30 Reset:  0x00000000 Property:  PAC Write-Protection, Secure, Enable-Protected Important:  This register is only available for SAM L11 and has no effect for SAM L10. Bit 31 30 29 28 27 26 25 24 DSCKEY[29:24] Access W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W Reset 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DSCKEY[23:16] Access W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DSCKEY[15:8] Access W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DSCKEY[7:0] Access W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W Reset 0 0 0 0 0 0 0 0 Bits 29:0 – DSCKEY[29:0] Data Scramble Key This key value is used for data scrambling of the Secure Data Flash. After reset the key is 0. When written, the new value in the register is an XOR of the value written and the previous value of DSCC.DSCKEY. This register is write only and will always read back as zero. This register is Enable-Protected with SECCTRL.DSCEN meaning that it can't be modified when DSCEN=1 otherwise a PAC error is generated. Updated DSCC.DSCKEY contents <- DSCC.DSCKEY XOR value written. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 607 30.8.14 Security Control Name:  SECCTRL Offset:  0x34 Reset:  'x' initially determined from NVM User Row after Reset Property:  PAC Write-Protection, Secure Bit 31 30 29 28 27 26 25 24 KEY[7:0] Access W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W W/-/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 TEROW[2:0] Access RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 DXN DSCEN SILACC TAMPEEN Access R/-/R RW/-/RW RW/-/RW RW/-/RW Reset x 0 0 0 Bits 31:24 – KEY[7:0] Write Key When this bit group is written to the key value 0xA5, the write will be performed. If a value different from the key value is tried, the write will be discarded and INTFLAG.KEYE set. Bits 10:8 – TEROW[2:0] Tamper Erase Row Row address of the row in data space to be erased on RTC tamper event. Bit 6 – DXN Data eXecute Never This bit field is only available for SAM L11 and has no effect for SAM L10. Value Description 0 Execution out of Data Flash is authorized. 1 Execution out of Data Flash is not authorized. Bit 3 – DSCEN Data Scramble Enable Important:  This bitfield is only available for SAM L11 and has no effect for SAM L10. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 608 Value Description 0 Secure Data FLASH is not scrambled. 1 Secure Data FLASH is scrambled. Bit 2 – SILACC Silent Access Value Description 0 Data in Tamper Erase Row is not mapped as differential data. 1 Data in Tamper Erase Row is mapped as differential data. Bit 0 – TAMPEEN Tamper Erase Enable Value Description 0 RTC tamper event has no effect. 1 RTC tamper event triggers a Tamper Erase. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 609 30.8.15 Secure Boot Configuration Name:  SCFGB Offset:  0x38 Reset:  0x00000003 Property:  PAC Write-Protection, Write-Secure This register is loaded from BOCOR at boot. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 BCWEN BCREN Access RW/R/RW RW/R/RW Reset 1 1 Bit 1 – BCWEN Boot Configuration Row Write Enable Value Description 0 BOCOR is not writable. 1 BOCOR is writable. Bit 0 – BCREN Boot Configuration Row Read Enable Value Description 0 BOCOR is not readable. 1 BOCOR is readable. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 610 30.8.16 Secure Application and Data Configuration Name:  SCFGAD Offset:  0x3C Reset:  x initially determined from NVM User Row after reset Property:  PAC Write-Protection, Write-Secure Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 URWEN Access RW/R/RW Reset x Bit 0 – URWEN User Row Write Enable Value Description 0 UROW is not writable. 1 UROW is writable. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 611 30.8.17 Non-secure Write Enable Name:  NONSEC Offset:  0x40 Reset:  0x00000001 Property:  PAC Write-Protection, Write-Secure This register allows the non-secure writes to the non-secure APB alias and also non-secure AHB writes to the Page Buffer. Important:  This register is only available for SAM L11 and has no effect for SAM L10. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 WRITE Access RW/R/RW Reset 1 Bit 0 – WRITE Non-secure Write Enable Non-secure APB alias write enable, non-secure AHB writes to non-secure regions enable Value Description 0 The non-secure APB alias is not writable, AHB secure or non-secure writes to non-secure regions (Page Buffer) return a hardfault. 1 No restriction. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 612 30.8.18 Non-secure Write Enable Check Name:  NSCHK Offset:  0x44 Reset:  0x00000001 Property:  PAC Write-Protection Important:  This register is only available for SAM L11 and has no effect for SAM L10. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 WRITE Access RW/RW/RW Reset 1 Bit 0 – WRITE Non-secure Write Transition Select This bitfield selects whether to generate a NSCHK interrupt on a NONSEC.WRITE rising of falling transition. Value Description 0 INTFLAG.NSCHK rises if NONSEC.WRITE transitions from 0 to 1. 1 INTFLAG.NSCHK rises if NONSEC.WRITE transitions from 1 to 0. SAM L10/L11 Family NVMCTRL – Nonvolatile Memory Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 613 31. TRAM - TrustRAM 31.1 Overview The TrustRAM (TRAM) is the controller interface for a 256-byte security RAM. This RAM is intended for volatile secret data. The TRAM is capable of performing address map scrambling as well as data scrambling for both write and read access to the secure RAM. The TRAM can perform silent access of the data stream to prevent side-channel attacks. The TRAM can execute two automated tasks that are triggered by external events: remanence prevention and erase. When a remanence periodic event occurs, the physical data stored in the RAM is inverted in order to prevent physical “burn-in” signatures. When a tamper event occurs, the TRAM executes a full erase of the control signals as well as the data in the security RAM. Both automated tasks do not require CPU interaction and can be performed in all sleep modes. 31.2 Features • Address scrambling to the RAM • Data scrambling to/from the RAM • Silent access of data for improved side-channel protection • Data remanence prevention • Active shielding to prevent tamper on physical RAM • Full erasure of scramble key and RAM data on tamper detection 31.3 Block Diagram Figure 31-1. Block Diagram INVERT TRAM DRP ERASE TAMPERS DSCKEY RAMINV SCRAMBLE SILENT APB ACCESS RTC ACTIVE LAYER 31.4 Signal Description Not applicable. SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 614 31.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 31.5.1 I/O Lines Not applicable. 31.5.2 Power Management The TRAM will continue to operate in any sleep mode, as long as its source clock is running. The TRAM interrupts can be used to wake up the device from sleep modes. Events connected to the event system can trigger other operations in the system without exiting sleep modes. Refer PM – Power Manager for details on the different sleep modes. 31.5.3 Clocks The TRAM bus clock (CLK_TRAM_AHB) can be enabled and disabled by the Main Clock module, and the default state of CLK_TRAM_AHB can be found in the Peripheral Clock Masking section. 31.5.4 DMA Not applicable 31.5.5 Interrupts The interrupt request lines are connected to the interrupt controller. Using the TRAM interrupts requires the interrupt controller to be configured first. Refer to NVIC - Nested Interrupt Nested Vector Interrupt Controller for details. 31.5.6 Events Data Remanence Prevention and Tamper events are connected directly from the RTC to the TRAM, without going through the Event System. 31.5.7 Debug Operation Not applicable. 31.5.8 Register Access Protection All registers with write-access are optionally write-protected by the Peripheral Access Controller (PAC), except for the following registers: • Interrupt Flag (INTFLAG) register • Data Scramble Control (DSCC) register • Permutation Write (PERMW) register • All RAM (RAM[0:63]) addresses Write-protection is denoted by the Write-Protected property in the register description. Write-protection does not apply to accesses through an external debugger. Refer to the Peripheral Access Controller chapter for details. 31.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 615 – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 31.6 Functional Description 31.6.1 Principle of Operation System bus transactions from the CPU to the security RAM undergoes a scrambling routine. Both address and data buses information are modified through an algorithm determined by a scrambling key. This is performed on both write and read transactions. 31.6.2 Basic Operation 31.6.2.1 Initialization The following bits are enable-protected, meaning that they can only be written when the TRAM is disabled (CTRLA.ENABLE is zero): • Tamper Erase bit in the Control A register (CTRLA.TAMPERS) • Data Remanence Protection bit in the Control A register (CTRLA.DRP) • Silent Access bit in the Control A register (CTRLA.SILACC) The following register is enable-protected: • Data Scramble Control register (DSCC) Enable-protected bits in the CTRLA register can be written at the same time as CTRLA.ENABLE is written to one, but not at the same time as CTRLA.ENABLE is written to zero. Enable-protection is denoted by the Enable-Protected property in the register description. 31.6.2.2 Enabling, Disabling and Resetting The TRAM is enabled by writing a one to the Enable bit in the Control A register (CTRLA.ENABLE). The TRAM is disabled by writing a zero to CTRLA.ENABLE. The TRAM is reset by writing a one to the Software Reset bit in the Control A register (CTRLA.SWRST). All registers in the TRAM will be reset to their initial state, and the TRAM will be disabled. All data in the secure RAM will be cleared to ‘0’. 31.6.2.3 Scrambling The Data Scramble Control (DSCC) must be configured before the CTRLA.ENABLE is set. These settings cannot be changed while the module is enabled. The scrambling logic is enabled by writing one to the enable bit in the Data Scramble Control register (DSCC.DSCEN). Scrambling is disabled by writing a zero to DSCC.DSCEN. Writing a zero to CTRLA.ENABLE will also disable the scrambling, but will not clear the DSCC.DSCEN bit. 31.6.2.4 Silent Access Silent access bit (CTRLA.SILACC) must be configured before CTRLA.ENABLE is set. This setting cannot be changed while the module is enabled. When this mode is enabled, only 128 bytes of the security RAM are accessible since the other 128 bytes are reserved to store the 1's complement (bitwise invert) values. The physical access to the RAM is now twice as wide compared to the bus access. Therefore, only 8-bit SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 616 byte access and 16-bit half-word access are supported in this mode. 32-bit word write accesses are ignored and 32-bit word read accesses return 0. The TRAM executes the following protocols: • When the CPU writes to the security RAM, the data and its bitwise invert are stored into the RAM. • When the CPU reads from the security RAM, both the data and its bitwise invert are retrieved from the RAM. If the TRAM cannot verify that both values complement each other, a bus error is returned. 31.6.2.5 Data Remanence Prevention Data remanence prevention bit (CTRLA.DRP) must be configured before CTRLA.ENABLE is set. This setting cannot be changed while the module is enabled. When this feature is enabled, the RTC Periodic Interval Daily Event (RTC_PERD) will trigger the automated data remanence routine. An internal counter will count from 0 to 63 and serves as the address access bus to the security RAM. For every address iteration, the TRAM reads the word data from the security RAM, inverts the value and writes back to the same address. To prevent linear access to the security RAM, the remanence address value is scrambled using the same protocols as a CPU address scramble. After remanence has updated all address locations, the routine will end by toggling the RAM inversion status bit (STATUS.RAMINV). See figure. Data remanence is a low-priority routine. If the CPU attempts to access the security RAM while remanence is active, the routine is temporarily paused until the CPU access is completed. If a tamper full erase event is detected, the remanence routine is aborted and the internal address counter will reset to 0. Figure 31-2. Remanence Routine ADDRESS COUNT 0-63 EVENT DSCKEY UPDATE RAMINV ADDRESS SCRAMBLE DATA INVERSION SCRAMBLE SILENT ACCESS INVERT Remanence Routine CPU Security Routine APB TRAM Active CPU Transaction Pause Count Increment Disable Remanence Transaction 31.6.2.6 Tamper Full Erase Tamper full erase bit (CTRLA.TAMPERS) must be configured before CTRLA.ENABLE is set. This setting cannot be changed while the module is enabled. When this feature is enabled, the RTC Tamper Event (RTC_TAMPER) will trigger the full erase equivalent to a TRAM software reset and the reset of the Data Scramble Key (DSCC.DSCKEY) register. All TRAM registers are reverted to the default reset value. Data inside the security RAM is written to ‘0’ for all address locations. SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 617 The tamper full erase routine operates at the highest priority. If a remanence routine executing when a tamper full erase occurs, the remanence routine is immediately terminated. If the CPU attempts to write a new scramble key at the same time the tamper key erase routine is active, the CPU data is ignored, but no bus error will occur. If a CPU security routine access is requested during a tamper full erase, the CPU transaction will be ignored and treated as a bus error similar to accessing the module during a software reset. Important:  In STANDBY low power mode, it is mandatory to enable the dynamic power gating feature (STDBYCFG.DPGPDSW) to ensure TrustRAM erasing when the power domain PDSW is in a retention state. 31.6.3 Interrupts The TRAM has the following interrupt sources: • Data Remanence Prevention (DRP): Indicates that the data remanence prevention routine has ended. • Data Read Error (ERR): Indicates when there is a RAM readout error. Each interrupt source has an interrupt flag associated with it. The interrupt flag in the Interrupt Flag Status and Clear (INTFLAG) register is set when the interrupt condition occurs. Each interrupt can be individually enabled by writing a one to the corresponding bit in the Interrupt Enable Set (INTENSET) register, and disabled by writing a one to the corresponding bit in the Interrupt Enable Clear (INTENCLR) register. An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until the interrupt flag is cleared, the interrupt is disabled, or the TRAM is reset. See 22.8.6 INTFLAG for details on how to clear interrupt flags. All interrupt requests from the peripheral are ORed together on system level to generate one combined interrupt request to the NVIC. Refer to Nested Vector Interrupt Controller for details. The user must read the INTFLAG register to determine which interrupt condition is present. Note that interrupts must be globally enabled for interrupt requests to be generated. Refer to Nested Vector Interrupt Controller for details. 31.6.4 Sleep Mode Operation The TRAM continues to operate during sleep. When it receives events from the Event System, it will request its own clock in order to perform the requested operation. An interrupt request will be generated after the wake-up if the Interrupt Controller is configured accordingly. Otherwise the CPU will wake up directly, without triggering an interrupt. In this case, the CPU will continue executing from the instruction following the entry into sleep. The periodic events can also wake up the CPU through the interrupt function of the Event System. In this case, the event must be enabled and connected to an event channel with its interrupt enabled. See EVSYS – Event System for more information. 31.6.5 Synchronization Due to the asynchronicity between event sources and CLK_TRAM_APB some registers must be synchronized when accessed. A register can require: • Synchronization when written SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 618 • No synchronization When executing an operation that requires synchronization, the corresponding status bit in the Synchronization Busy register (SYNCBUSY.xxx) will be set immediately, and cleared when synchronization is complete. If an operation that requires synchronization is executed while SYNCBUSY.xxx is one, the operation is discarded and an error is generated. The following bits need synchronization when written: • Software Reset bit in Control A register (CTRLA.SWRST) • Enable bit in Control A register (CTRLA.ENABLE) SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 619 31.7 Register Summary Offset Name Bit Pos. 0x00 CTRLA 7:0 SILACC DRP TAMPERS ENABLE SWRST 0x01 ... 0x03 Reserved 0x04 INTENCLR 7:0 DRP ERR 0x05 INTENSET 7:0 DRP ERR 0x06 INTFLAG 7:0 DRP ERR 0x07 STATUS 7:0 DRP RAMINV 0x08 SYNCBUSY 7:0 ENABLE SWRST 15:8 23:16 31:24 0x0C DSCC 7:0 DSCKEY[7:0] 15:8 DSCKEY[15:8] 23:16 DSCKEY[23:16] 31:24 DSCEN DSCKEY[29:24] 0x10 PERMW 7:0 DATA[2:0] 0x11 PERMR 7:0 DATA[2:0] 0x12 ... 0xFF Reserved 0x0100 RAM0 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0104 RAM1 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0108 RAM2 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x010C RAM3 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0110 RAM4 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0114 RAM5 7:0 DATA[7:0] 15:8 DATA[15:8] SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 620 Offset Name Bit Pos. 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0118 RAM6 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x011C RAM7 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0120 RAM8 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0124 RAM9 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0128 RAM10 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x012C RAM11 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0130 RAM12 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0134 RAM13 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0138 RAM14 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x013C RAM15 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0140 RAM16 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 621 Offset Name Bit Pos. 0x0144 RAM17 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0148 RAM18 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x014C RAM19 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0150 RAM20 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0154 RAM21 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0158 RAM22 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x015C RAM23 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0160 RAM24 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0164 RAM25 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0168 RAM26 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x016C RAM27 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0170 RAM28 7:0 DATA[7:0] 15:8 DATA[15:8] SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 622 Offset Name Bit Pos. 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0174 RAM29 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0178 RAM30 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x017C RAM31 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0180 RAM32 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0184 RAM33 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0188 RAM34 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x018C RAM35 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0190 RAM36 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0194 RAM37 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x0198 RAM38 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x019C RAM39 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 623 Offset Name Bit Pos. 0x01A0 RAM40 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01A4 RAM41 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01A8 RAM42 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01AC RAM43 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01B0 RAM44 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01B4 RAM45 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01B8 RAM46 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01BC RAM47 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01C0 RAM48 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01C4 RAM49 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01C8 RAM50 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01CC RAM51 7:0 DATA[7:0] 15:8 DATA[15:8] SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 624 Offset Name Bit Pos. 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01D0 RAM52 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01D4 RAM53 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01D8 RAM54 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01DC RAM55 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01E0 RAM56 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01E4 RAM57 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01E8 RAM58 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01EC RAM59 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01F0 RAM60 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01F4 RAM61 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 0x01F8 RAM62 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 625 Offset Name Bit Pos. 0x01FC RAM63 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 31.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16-, and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers require synchronization when read and/or written. Synchronization is denoted by the "Read-Synchronized" and/or "Write-Synchronized" property in each individual register description. Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. Some registers are enable-protected, meaning they can only be written when the module is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. Refer to PAC - Peripheral Access Controller and 39.6.6 Synchronization for details. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 626 31.8.1 Control A Name:  CTRLA Offset:  0x000 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 SILACC DRP TAMPERS ENABLE SWRST Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 7 – SILACC Silent Access Enables differential storage of data. Value Description 0 Silent access is disabled. 1 Silent access is enabled. Bit 6 – DRP Data Remanence Prevention Enables periodic DRP in TrustRAM. Value Description 0 Data remanence prevention is disabled. 1 Data remanence prevention is enabled. Bit 4 – TAMPERS Tamper Erase Auto-erases TrustRAM and DSCC.DSCKEY on tamper event. Value Description 0 Tamper erase is disabled. 1 Tamper erase is enabled. Bit 1 – ENABLE Enable Value Description 0 The TRAM is disabled. 1 The TRAM is enabled. Bit 0 – SWRST Software Reset Writing a zero to this bit has no effect. Writing a one to this bit resets all registers in the TRAM to their initial state, and the TRAM will be disabled. This bit can also be set via hardware when a tamper occurs while CTRLA.TAMPERS is set. Writing a one to CTRLA.SWRST will always take precedence, meaning that all other writes in the same writeoperation will be discarded. Due to synchronization there is a delay from writing CTRLA.SWRST until the reset is complete. CTRLA.SWRST and SYNCBUSY.SWRST will both be cleared when the reset is complete. SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 627 Value Description 0 There is no reset operation ongoing. 1 The reset operation is ongoing. SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 628 31.8.2 Interrupt Enable Clear Name:  INTENCLR Offset:  0x004 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DRP ERR Access R/W R/W Reset 0 0 Bit 1 – DRP Data Remanence Prevention Complete Interrupt Enable Writing a zero to this bit has no effect. Writing a one to this bit will clear the Data Remanence Prevention Complete Interrupt Enable bit, which disables the data remanence prevention complete interrupt. Value Description 0 Data remanence prevention complete interrupt is disabled. 1 Data remanence prevention complete interrupt is enabled. Bit 0 – ERR TrustRAM Read Error Interrupt Enable Writing a zero to this bit has no effect. Writing a one to this bit will clear the TrustRAM Read Error Interrupt Enable bit, which disables the TrustRAM read error interrupt. Value Description 0 TrustRAM read error interrupt is disabled. 1 TrustRAM read error interrupt is enabled. SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 629 31.8.3 Interrupt Enable Set Name:  INTENSET Offset:  0x005 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DRP ERR Access R/W R/W Reset 0 0 Bit 1 – DRP Data Remanence Prevention Complete Interrupt Enable Writing a zero to this bit has no effect. Writing a one to this bit will set the Data Remanence Prevention Complete Interrupt Enable bit, which enables the data remanence prevention complete interrupt. Value Description 0 Data remanence prevention complete interrupt is disabled. 1 Data remanence prevention complete interrupt is enabled. Bit 0 – ERR TrustRAM Read Error Interrupt Enable Writing a zero to this bit has no effect. Writing a one to this bit will set the TrustRAM Read Error Interrupt Enable bit, which enables the TrustRAM read error interrupt. Value Description 0 TrustRAM read error interrupt is disabled. 1 TrustRAM read error interrupt is enabled. SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 630 31.8.4 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x006 Reset:  0x00 Property:  - Bit 7 6 5 4 3 2 1 0 DRP ERR Access R/W R/W Reset 0 0 Bit 1 – DRP Data Remanence Prevention Complete Interrupt This flag is set when the data remanence prevention routine has completed, and an interrupt request will be generated if INTENCLR.DRP/INTENSET.DRP is one. Writing a zero to this bit has no effect. Writing a one to this bit clears the data remanence prevention complete interrupt flag. Value Description 0 Data remanence prevention complete interrupt is disabled. 1 Data remanence prevention complete interrupt is enabled. Bit 0 – ERR TrustRAM Read Error Interrupt This flag is set when an error is detected in the TrustRAM readout, and an interrupt request will be generated if INTENCLR.ERR/INTENSET.ERR is one. Writing a zero to this bit has no effect. Writing a one to this bit clears the TrustRAM read error interrupt flag. Value Description 0 TrustRAM read error interrupt is disabled. 1 TrustRAM read error interrupt is enabled. SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 631 31.8.5 Status Name:  STATUS Offset:  0x007 Reset:  0x00 Property:  Read-Only Bit 7 6 5 4 3 2 1 0 DRP RAMINV Access R R Reset 0 0 Bit 1 – DRP Data Remanence Prevention Routine This bit identifies if the data remanence prevention routine is running. Value Description 0 The data remanence prevention routine is not running. 1 The data remanence prevention routine is running. Bit 0 – RAMINV RAM Inversion Bit This bit identifies if the TrustRAM bit values are inverted. Value Description 0 The TrustRAM physical bit information is normal. 1 The TrustRAM physical bit information is inverted. SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 632 31.8.6 Synchronization Busy Name:  SYNCBUSY Offset:  0x008 Reset:  0x00000000 Property:  Read-Only Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 ENABLE SWRST Access R R Reset 0 0 Bit 1 – ENABLE Enable Value Description 0 Write synchronization for CTRLA.ENABLE bit is complete. 1 Write synchronization for CTRLA.ENABLE bit is ongoing. Bit 0 – SWRST Software Reset Synchronization Busy Status This bit will set in two ways: • Writing ‘1’ to CTRLA.SWRST • A tamper event occurs when CTRLA.TAMPERS = ‘1’ Value Description 0 Write synchronization for CTRLA.SWRST bit is complete. 1 Write synchronization for CTRLA.SWRST bit is ongoing. SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 633 31.8.7 Data Scramble Control Name:  DSCC Offset:  0x00C Reset:  0x00000000 Property:  PAC Write-Protected, Enable-Protected Bit 31 30 29 28 27 26 25 24 DSCEN DSCKEY[29:24] Access R/W W W W W W W Reset 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DSCKEY[23:16] Access W W W W W W W W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DSCKEY[15:8] Access W W W W W W W W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DSCKEY[7:0] Access W W W W W W W W Reset 0 0 0 0 0 0 0 0 Bit 31 – DSCEN Data Scramble Enable Value Description 0 TrustRAM is not scrambled. 1 TrustRAM is scrambled. Bits 29:0 – DSCKEY[29:0] Data Scramble Key The key value used for data scrambling. Any value written to this field is XOR’ed with the previous data. Writing ‘1’ to CTRLA.SWRST will reset this field to 0. These bits will always return zero when read. SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 634 31.8.8 Permutation Write Name:  PERMW Offset:  0x010 Reset:  0x00 Property:  PAC Write-Protected Bit 7 6 5 4 3 2 1 0 DATA[2:0] Access W W W Reset 0 0 0 Bits 2:0 – DATA[2:0] Permutation Write Data Data is the input value for the scrambler permutation function: PERMR.DATA = Permutate(PERMW.DATA, DSCC.DSCKEY) These bits will always return zero when read. SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 635 31.8.9 Permutation Read Name:  PERMR Offset:  0x011 Reset:  0x00 Property:  Read-Only Bit 7 6 5 4 3 2 1 0 DATA[2:0] Access R R R Reset 0 0 0 Bits 2:0 – DATA[2:0] Permutation Write Data Data is the input value for the scrambler permutation function: PERMR.DATA = Permutate(PERMW.DATA, DSCC.DSCKEY) SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 636 31.8.10 Security RAM n Name:  RAM Offset:  0x0100 + n*0x04 [n=0..63] Reset:  0x00000000 Property:  PAC Write-Protected, Enable-Protected Access to the Security RAM is only permitted when CTRLA.ENABLE=1. Bit 31 30 29 28 27 26 25 24 DATA[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DATA[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DATA[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DATA[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – DATA[31:0] RAM Data SAM L10/L11 Family TRAM - TrustRAM © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 637 32. PORT - I/O Pin Controller 32.1 Overview The IO Pin Controller (PORT) controls the I/O pins of the device. The I/O pins are organized in a series of groups, collectively referred to as a PORT group. Each PORT group can have up to 32 pins that can be configured and controlled individually or as a group. The number of PORT groups on a device may depend on the package/number of pins. Each pin may either be used for general-purpose I/O under direct application control or be assigned to an embedded device peripheral. When used for generalpurpose I/O, each pin can be configured as input or output, with highly configurable driver and pull settings. Each pin can be defined as secured or non-secured, where secured pins can only be handled by secure accesses. All I/O pins have true read-modify-write functionality when used for general-purpose I/O; the direction or the output value of one or more pins may be changed (set, reset or toggled) explicitly without unintentionally changing the state of any other pins in the same port group by a single, atomic 8-, 16- or 32-bit write. The PORT is connected to the high-speed bus matrix through an AHB/APB bridge. The Pin Direction, Data Output Value and Data Input Value registers may also be accessed using the low-latency CPU local bus (IOBUS; ARM® single-cycle I/O port). 32.2 Features • Selectable input and output configuration for each individual pin • Software-controlled multiplexing of peripheral functions on I/O pins • Flexible pin configuration through a dedicated Pin Configuration register • Configurable output driver and pull settings: – Totem-pole (push-pull) – Pull configuration – Driver strength • Configurable input buffer and pull settings: – Internal pull-up or pull-down – Input sampling criteria – Input buffer can be disabled if not needed for lower power consumption • Input event: – Up to four input event pins for each PORT group – SET/CLEAR/TOGGLE event actions for each event input on output value of a pin – Can be output to pin • Selectable secured or non-secured attribution for each individual pin (SAM L11) SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 638 32.3 Block Diagram Figure 32-1. PORT Block Diagram ANALOG BLOCKS PERIPHERALS Digital Controls of Analog Blocks Analog Pad Connections I/O PADS Port Line Bundles IP Line Bundles Peripheral Mux Select PORT Control and Status Pad Line Bundles PORTMUX 32.4 Signal Description Table 32-1. Signal description for PORT Signal name Type Description Pxy Digital I/O General-purpose I/O pin y in group x Refer to the I/O Multiplexing and Considerations for details on the pin mapping for this peripheral. One signal can be mapped on several pins. 32.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly as following. 32.5.1 I/O Lines The I/O lines of the PORT are mapped to pins of the physical device. The following naming scheme is used: Each line bundle with up to 32 lines is assigned an identifier 'xy', with letter x=A, B, C… and two-digit number y=00, 01, …31. Examples: A24, C03. PORT pins are labeled 'Pxy' accordingly, for example PA24, PC03. This identifies each pin in the device uniquely. Each pin may be controlled by one or more peripheral multiplexer settings, which allow the pad to be routed internally to a dedicated peripheral function. When the setting is enabled, the selected peripheral has control over the output state of the pad, as well as the ability to read the current physical pad state. Refer to I/O Multiplexing and Considerations for details. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 639 Each pin may be secured or non-secured, with secured pins only accessible by secure accesses. Device-specific configurations may cause some lines (and the corresponding Pxy pin) not to be implemented. 32.5.2 Power Management During Reset, all PORT lines are configured as inputs with input buffers, output buffers and pull disabled. The PORT peripheral will continue operating in any sleep mode where its source clock is running. 32.5.3 Clocks The PORT bus clock (CLK_PORT_APB) can be enabled and disabled in the Main Clock module, and the default state of CLK_PORT_APB can be found in the Peripheral Clock Masking section in MCLK – Main Clock. The PORT requires an APB clock, which may be divided from the CPU main clock and allows the CPU to access the registers of PORT through the high-speed matrix and the AHB/APB bridge. The priority of IOBUS accesses is higher than APB accesses. One clock cycle latency can be observed on the APB access in case of concurrent PORT accesses. Related Links 19. MCLK – Main Clock 32.5.4 DMA Not applicable. 32.5.5 Interrupts Not applicable. 32.5.6 Events The events of this peripheral are connected to the Event System. Related Links 33. EVSYS – Event System 32.5.7 Debug Operation When the CPU is halted in debug mode, this peripheral will continue normal operation. 32.5.8 Register Access Protection All registers with write-access can be optionally write-protected by the Peripheral Access Controller (PAC). Note:  Optional write-protection is indicated by the "PAC Write-Protection" property in the register description. Write-protection does not apply for accesses through an external debugger. Related Links 15. PAC - Peripheral Access Controller 32.5.9 Analog Connections Analog functions are connected directly between the analog blocks and the I/O pads using analog buses. However, selecting an analog peripheral function for a given pin will disable the corresponding digital features of the pad. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 640 32.5.10 CPU Local Bus The CPU local bus (IOBUS) is an interface that connects the CPU directly to the PORT. It is a singlecycle bus interface, which does not support wait states. It supports 8-bit, 16-bit and 32-bit sizes. This bus is generally used for low latency operation. The Data Direction (DIR) and Data Output Value (OUT) registers can be read, written, set, cleared or be toggled using this bus, and the Data Input Value (IN) registers can be read. Since the IOBUS cannot wait for IN register resynchronization, the Control register (CTRL) must be configured to continuous sampling of all pins that need to be read via the IOBUS in order to prevent stale data from being read. Note:  Refer to the Product Mapping chapter for the IOBUS address. 32.6 Functional Description Figure 32-2. Overview of the PORT PULLENx OUTx DIRx INENx PORT PAD VDD INEN OE OUT PULLEN PAD Pull Resistor PG NG Input to Other Modules Analog Input/Output INx IN APB Bus Synchronizer Q D R R DQ DRIVEx DRIVE 32.6.1 Principle of Operation Each PORT group of up to 32 pins is controlled by the registers in PORT, as described in the figure. These registers in PORT are duplicated for each PORT group, with increasing base addresses. The number of PORT groups may depend on the package/number of pins. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 641 Figure 32-3. Overview of the peripheral functions multiplexing Port y PINCFG Port y Periph Signal 0 PORT bit y PMUXEN Data+Config Periph Signal 1 Periph Signal 15 Port y PMUX[3:0] Port y PMUX Select Port y Line Bundle PAD y Pad y Peripheral Signals to be muxed to Pad y Port y Peripheral Mux Enable 15 1 0 0 1 Line Bundle PORTMUX The I/O pins of the device are controlled by PORT peripheral registers. Each port pin has a corresponding bit in the Data Direction (DIR) and Data Output Value (OUT) registers to enable that pin as an output and to define the output state. The direction of each pin in a PORT group is configured by the DIR register. If a bit in DIR is set to '1', the corresponding pin is configured as an output pin. If a bit in DIR is set to '0', the corresponding pin is configured as an input pin. When the direction is set as output, the corresponding bit in the OUT register will set the level of the pin. If bit y in OUT is written to '1', pin y is driven HIGH. If bit y in OUT is written to '0', pin y is driven LOW. Pin configuration can be set by Pin Configuration (PINCFGy) registers, with y=00, 01, ..31 representing the bit position. The Data Input Value (IN) is set as the input value of a port pin with resynchronization to the PORT clock. To reduce power consumption, these input synchronizers are clocked only when system requires reading the input value. The value of the pin can always be read, whether the pin is configured as input or output. If the Input Enable bit in the Pin Configuration registers (PINCFGy.INEN) is '0', the input value will not be sampled. In PORT, the Peripheral Multiplexer Enable bit in the PINCFGy register (PINCFGy.PMUXEN) can be written to '1' to enable the connection between peripheral functions and individual I/O pins. The Peripheral Multiplexing n (PMUXn) registers select the peripheral function for the corresponding pin. This will override the connection between the PORT and that I/O pin, and connect the selected peripheral signal to the particular I/O pin instead of the PORT line bundle. The security attribution of each pin in a PORT group is configured by the NONSEC register. If a bit in the NONSEC register is set to '0', the corresponding pin is configured as a secured pin and can only be handled by secure accesses. If a bit in the NONSEC register is set to '1', the corresponding pin is configured as a non-secured pin. Only secure accesses are allowed to write to the NONSEC register. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 642 32.6.2 Basic Operation 32.6.2.1 Initialization After reset, all standard function device I/O pads are connected to the PORT with outputs tri-stated and input buffers disabled, even if there is no clock running. However, specific pins, such as those used for connection to a debugger, may be configured differently, as required by their special function. 32.6.2.2 Operation Each I/O pin y can be controlled by the registers in PORT. Each PORT group has its own set of PORT registers, the base address of the register set for pin y is at byte address PORT + ([y] * 0x4). The index within that register set is [y]. Refer to I/O Multiplexing and Considerations for details on available pin configuration and PORT groups. Configuring Pins as Output To use pin number y as an output, write bit y of the DIR register to '1'. This can also be done by writing bit y in the DIRSET register to '1' - this will avoid disturbing the configuration of other pins in that group. The y bit in the OUT register must be written to the desired output value. Similarly, writing an OUTSET bit to '1' will set the corresponding bit in the OUT register to '1'. Writing a bit in OUTCLR to '1' will set that bit in OUT to zero. Writing a bit in OUTTGL to '1' will toggle that bit in OUT. Configuring Pins as Input To use pin y as an input, bit y in the DIR register must be written to '0'. This can also be done by writing bit y in the DIRCLR register to '1' - this will avoid disturbing the configuration of other pins in that group. The input value can be read from bit y in register IN as soon as the INEN bit in the Pin Configuration register (PINCFGy.INEN) is written to '1'. By default, the input synchronizer is clocked only when an input read is requested. This will delay the read operation by two CLK_PORT cycles. To remove the delay, the input synchronizers for each PORT group of eight pins can be configured to be always active, but this will increase power consumption. This is enabled by writing '1' to the corresponding SAMPLINGn bit field of the CTRL register, see CTRL.SAMPLING for details. Using Alternative Peripheral Functions To use pin y as one of the available peripheral functions, the corresponding PMUXEN bit of the PINCFGy register must be '1'. The PINCFGy register for pin y is at byte offset (PINCFG0 + [y]). The peripheral function can be selected by setting the PMUXO or PMUXE in the PMUXn register. The PMUXO/PMUXE is at byte offset PMUX0 + (y/2). The chosen peripheral must also be configured and enabled. 32.6.3 I/O Pin Configuration The Pin Configuration register (PINCFGy) is used for additional I/O pin configuration. A pin can be set in a totem-pole or pull configuration. As pull configuration is done through the Pin Configuration register, all intermediate PORT states during switching of pin direction and pin values are avoided. The I/O pin configurations are described further in this chapter, and summarized in Table 32-2. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 643 32.6.3.1 Pin Configurations Summary Table 32-2. Pin Configurations Summary DIR INEN PULLEN OUT Configuration 0 0 0 X Reset or analog I/O: all digital disabled 0 0 1 0 Pull-down; input disabled 0 0 1 1 Pull-up; input disabled 0 1 0 X Input 0 1 1 0 Input with pull-down 0 1 1 1 Input with pull-up 1 0 X X Output; input disabled 1 1 X X Output; input enabled 32.6.3.2 Input Configuration Figure 32-4. I/O configuration - Standard Input PULLEN DIR OUT IN INEN PULLEN INEN DIR 0 1 0 Figure 32-5. I/O Configuration - Input with Pull PULLEN DIR OUT IN INEN PULLEN INEN DIR 1 1 0 Note:  When pull is enabled, the pull value is defined by the OUT value. 32.6.3.3 Totem-Pole Output When configured for totem-pole (push-pull) output, 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 is connected. Note:  Enabling the output driver will automatically disable pull. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 644 Figure 32-6. I/O Configuration - Totem-Pole Output with Disabled Input PULLEN DIR OUT IN INEN PULLEN INEN DIR 0 0 1 Figure 32-7. I/O Configuration - Totem-Pole Output with Enabled Input PULLEN DIR OUT IN INEN PULLEN INEN DIR 0 1 1 Figure 32-8. I/O Configuration - Output with Pull PULLEN DIR OUT IN INEN PULLEN INEN DIR 1 0 0 32.6.3.4 Digital Functionality Disabled Neither Input nor Output functionality are enabled. Figure 32-9. I/O Configuration - Reset or Analog I/O: Digital Output, Input and Pull Disabled PULLEN DIR OUT IN INEN PULLEN INEN DIR 0 0 0 32.6.4 SAM L11 Secure Access Rights Non-secure write to CTRL, EVCTRL, or NONSEC registers is prohibited. Non-secure read to CTRL or EVCTRL registers will return zero with no error resulting. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 645 Non-secure write to a bit of DIR, DIRCLR, DIRSET, DIRTGL, OUT, OUTCLR, OUTSET, or OUTTGL registers is prohibited if the corresponding bit in NONSEC is zero. Non-secure write to a PINCFGn register or to a PMUXn register field, either directly or through a write to the WRCONFIG register, is prohibited if the corresponding bit in NONSEC is zero. DIR, DIRCLR, DIRSET, DIRTGL, IN, OUT, OUTCLR, OUTSET, or OUTTGL bits, PINCFGn registers, or PMUXn register fields relating to secure I/O pins (i.e. the corresponding bits in NONSEC are zero), read as zero in non-secure mode, with no error resulting. INTFLAG.NSCHK is set to 1 when NSCHK and NONSEC register values are different. Writing a 1 to INTFLAG.NSCHK will clear it and clear the PORT interrupt if enabled. Secure code should initially write a 1 for all non-secure pins into both NONSEC and NSCHK registers. Then, whenever secure code writes a different value into NONSEC, INTFLAG.NSCHK will be set to 1 and a PORT interrupt will occur, if enabled. The non-secure code can then compare the values of the NONSEC and NSCHK registers to determine which PORT pins have just changed to secure or to nonsecure. It should then copy the current NONSEC register value into NSCHK. 32.6.5 Events The PORT allows input events to control individual I/O pins. These input events are generated by the EVSYS module and can originate from a different clock domain than the PORT module. The PORT can perform the following actions: • Output (OUT): I/O pin will be set when the incoming event has a high level ('1') and cleared when the incoming event has a low-level ('0'). • Set (SET): I/O pin will be set when an incoming event is detected. • Clear (CLR): I/O pin will be cleared when an incoming event is detected. • Toggle (TGL): I/O pin will toggle when an incoming event is detected. The event is output to pin without any internal latency. For SET, CLEAR and TOGGLE event actions, the action will be executed up to three clock cycles after a rising edge. The event actions can be configured with the Event Action m bit group in the Event Input Control register( EVCTRL.EVACTm). Writing a '1' to a PORT Event Enable Input m of the Event Control register (EVCTRL.PORTEIm) enables the corresponding action on input event. Writing '0' to this bit disables the corresponding action on input event. Note that several actions can be enabled for incoming events. If several events are connected to the peripheral, any enabled action will be taken for any of the incoming events. Refer to EVSYS – Event System. for details on configuring the Event System. Each event input can address one and only one I/O pin at a time. The selection of the pin is indicated by the PORT Event Pin Identifier of the Event Input Control register (EVCTR.PIDn). On the other hand, one I/O pin can be addressed by up to four different input events. To avoid action conflict on the output value of the register (OUT) of this particular I/O pin, only one action is performed according to the table below. Note that this truth table can be applied to any SET/CLR/TGL configuration from two to four active input events. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 646 Table 32-3. Priority on Simultaneous SET/CLR/TGL Event Actions EVACT0 EVACT1 EVACT2 EVACT3 Executed Event Action SET SET SET SET SET CLR CLR CLR CLR CLR All Other Combinations TGL Be careful when the event is output to pin. Due to the fact the events are received asynchronously, the I/O pin may have unpredictable levels, depending on the timing of when the events are received. When several events are output to the same pin, the lowest event line will get the access. All other events will be ignored. Related Links 33. EVSYS – Event System 32.6.6 PORT Access Priority The PORT is accessed by different systems: • The ARM® CPU through the ARM® single-cycle I/O port (IOBUS) • The ARM® CPU through the high-speed matrix and the AHB/APB bridge (APB) • EVSYS through four asynchronous input events The following priority is adopted: 1. ARM® CPU IOBUS (No wait tolerated) 2. APB 3. EVSYS input events For input events that require different actions on the same I/O pin, refer to 32.6.5 Events. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 647 32.7 Register Summary Important:  For SAM L11, the PORT register map is automatically duplicated in a Secure and Non-Secure alias: • The Non-Secure alias is at the peripheral base address • The Secure alias is located at the peripheral base address + 0x200 Refer to Mix-Secure Peripherals for more information on register access rights Offset Name Bit Pos. 0x00 DIR 7:0 DIR[7:0] 15:8 DIR[15:8] 23:16 DIR[23:16] 31:24 DIR[31:24] 0x04 DIRCLR 7:0 DIRCLR[7:0] 15:8 DIRCLR[15:8] 23:16 DIRCLR[23:16] 31:24 DIRCLR[31:24] 0x08 DIRSET 7:0 DIRSET[7:0] 15:8 DIRSET[15:8] 23:16 DIRSET[23:16] 31:24 DIRSET[31:24] 0x0C DIRTGL 7:0 DIRTGL[7:0] 15:8 DIRTGL[15:8] 23:16 DIRTGL[23:16] 31:24 DIRTGL[31:24] 0x10 OUT 7:0 OUT[7:0] 15:8 OUT[15:8] 23:16 OUT[23:16] 31:24 OUT[31:24] 0x14 OUTCLR 7:0 OUTCLR[7:0] 15:8 OUTCLR[15:8] 23:16 OUTCLR[23:16] 31:24 OUTCLR[31:24] 0x18 OUTSET 7:0 OUTSET[7:0] 15:8 OUTSET[15:8] 23:16 OUTSET[23:16] 31:24 OUTSET[31:24] 0x1C OUTTGL 7:0 OUTTGL[7:0] 15:8 OUTTGL[15:8] 23:16 OUTTGL[23:16] 31:24 OUTTGL[31:24] 0x20 IN 7:0 IN[7:0] 15:8 IN[15:8] 23:16 IN[23:16] SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 648 Offset Name Bit Pos. 31:24 IN[31:24] 0x24 CTRL 7:0 SAMPLING[7:0] 15:8 SAMPLING[15:8] 23:16 SAMPLING[23:16] 31:24 SAMPLING[31:24] 0x28 WRCONFIG 7:0 PINMASK[7:0] 15:8 PINMASK[15:8] 23:16 DRVSTR PULLEN INEN PMUXEN 31:24 HWSEL WRPINCFG WRPMUX PMUX[3:0] 0x2C EVCTRL 7:0 PORTEIx EVACTx[1:0] PIDx[4:0] 15:8 PORTEIx EVACTx[1:0] PIDx[4:0] 23:16 PORTEIx EVACTx[1:0] PIDx[4:0] 31:24 PORTEIx EVACTx[1:0] PIDx[4:0] 0x30 PMUX0 7:0 PMUXO[3:0] PMUXE[3:0] 0x31 PMUX1 7:0 PMUXO[3:0] PMUXE[3:0] 0x32 PMUX2 7:0 PMUXO[3:0] PMUXE[3:0] 0x33 PMUX3 7:0 PMUXO[3:0] PMUXE[3:0] 0x34 PMUX4 7:0 PMUXO[3:0] PMUXE[3:0] 0x35 PMUX5 7:0 PMUXO[3:0] PMUXE[3:0] 0x36 PMUX6 7:0 PMUXO[3:0] PMUXE[3:0] 0x37 PMUX7 7:0 PMUXO[3:0] PMUXE[3:0] 0x38 PMUX8 7:0 PMUXO[3:0] PMUXE[3:0] 0x39 PMUX9 7:0 PMUXO[3:0] PMUXE[3:0] 0x3A PMUX10 7:0 PMUXO[3:0] PMUXE[3:0] 0x3B PMUX11 7:0 PMUXO[3:0] PMUXE[3:0] 0x3C PMUX12 7:0 PMUXO[3:0] PMUXE[3:0] 0x3D PMUX13 7:0 PMUXO[3:0] PMUXE[3:0] 0x3E PMUX14 7:0 PMUXO[3:0] PMUXE[3:0] 0x3F PMUX15 7:0 PMUXO[3:0] PMUXE[3:0] 0x40 PINCFG0 7:0 DRVSTR PULLEN INEN PMUXEN 0x41 PINCFG1 7:0 DRVSTR PULLEN INEN PMUXEN 0x42 PINCFG2 7:0 DRVSTR PULLEN INEN PMUXEN 0x43 PINCFG3 7:0 DRVSTR PULLEN INEN PMUXEN 0x44 PINCFG4 7:0 DRVSTR PULLEN INEN PMUXEN 0x45 PINCFG5 7:0 DRVSTR PULLEN INEN PMUXEN 0x46 PINCFG6 7:0 DRVSTR PULLEN INEN PMUXEN 0x47 PINCFG7 7:0 DRVSTR PULLEN INEN PMUXEN 0x48 PINCFG8 7:0 DRVSTR PULLEN INEN PMUXEN 0x49 PINCFG9 7:0 DRVSTR PULLEN INEN PMUXEN 0x4A PINCFG10 7:0 DRVSTR PULLEN INEN PMUXEN 0x4B PINCFG11 7:0 DRVSTR PULLEN INEN PMUXEN 0x4C PINCFG12 7:0 DRVSTR PULLEN INEN PMUXEN 0x4D PINCFG13 7:0 DRVSTR PULLEN INEN PMUXEN 0x4E PINCFG14 7:0 DRVSTR PULLEN INEN PMUXEN 0x4F PINCFG15 7:0 DRVSTR PULLEN INEN PMUXEN 0x50 PINCFG16 7:0 DRVSTR PULLEN INEN PMUXEN SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 649 Offset Name Bit Pos. 0x51 PINCFG17 7:0 DRVSTR PULLEN INEN PMUXEN 0x52 PINCFG18 7:0 DRVSTR PULLEN INEN PMUXEN 0x53 PINCFG19 7:0 DRVSTR PULLEN INEN PMUXEN 0x54 PINCFG20 7:0 DRVSTR PULLEN INEN PMUXEN 0x55 PINCFG21 7:0 DRVSTR PULLEN INEN PMUXEN 0x56 PINCFG22 7:0 DRVSTR PULLEN INEN PMUXEN 0x57 PINCFG23 7:0 DRVSTR PULLEN INEN PMUXEN 0x58 PINCFG24 7:0 DRVSTR PULLEN INEN PMUXEN 0x59 PINCFG25 7:0 DRVSTR PULLEN INEN PMUXEN 0x5A PINCFG26 7:0 DRVSTR PULLEN INEN PMUXEN 0x5B PINCFG27 7:0 DRVSTR PULLEN INEN PMUXEN 0x5C PINCFG28 7:0 DRVSTR PULLEN INEN PMUXEN 0x5D PINCFG29 7:0 DRVSTR PULLEN INEN PMUXEN 0x5E PINCFG30 7:0 DRVSTR PULLEN INEN PMUXEN 0x5F PINCFG31 7:0 DRVSTR PULLEN INEN PMUXEN 0x60 INTENCLR 7:0 NSCHK 15:8 23:16 31:24 0x64 INTENSET 7:0 NSCHK 15:8 23:16 31:24 0x68 INTFLAG 7:0 NSCHK 15:8 23:16 31:24 0x6C NONSEC 7:0 NONSEC[7:0] 15:8 NONSEC[15:8] 23:16 NONSEC[23:16] 31:24 NONSEC[31:24] 0x70 NSCHK 7:0 NSCHK[7:0] 15:8 NSCHK[15:8] 23:16 NSCHK[23:16] 31:24 NSCHK[31:24] 32.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to 32.5.8 Register Access Protection. On SAM L11 devices, the Mix-Secure peripheral has different types of registers (Non-Secure, Secure, Write-Secure, Mix-Secure, and Write-Mix-Secure) with different access permissions for each bitfield. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 650 Refer to Mix-Secure Peripherals for more details. In the following register descriptions, the access permissions are specified as shown in the following figure. Bit 7 6 5 4 3 2 1 0 CMD[7:0] Access R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW TrustZone Non-Protected Devices Access TrustZone Protected Devices Non-Secure Access TrustZone Protected Devices Secure Access SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 651 32.8.1 Data Direction Name:  DIR Offset:  0x00 Reset:  0x00000000 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write write accesses (RW*) are allowed only if the security attribution for the corresponding I/O pin is set as Non-Secured in the NONSEC register. This register allows the user to configure one or more I/O pins as an input or output. This register can be manipulated without doing a read-modify-write operation by using the Data Direction Toggle (DIRTGL), Data Direction Clear (DIRCLR) and Data Direction Set (DIRSET) registers. Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. Bit 31 30 29 28 27 26 25 24 DIR[31:24] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DIR[23:16] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DIR[15:8] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DIR[7:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bits 31:0 – DIR[31:0] Port Data Direction These bits set the data direction for the individual I/O pins in the PORT group. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 652 Value Description 0 The corresponding I/O pin in the PORT group is configured as an input. 1 The corresponding I/O pin in the PORT group is configured as an output. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 653 32.8.2 Data Direction Clear Name:  DIRCLR Offset:  0x04 Reset:  0x00000000 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the security attribution for the corresponding I/O pin is set as Non-Secured in the NONSEC register. This register allows the user to set one or more I/O pins as an input, without doing a read-modify-write operation. Changes in this register will also be reflected in the Data Direction (DIR), Data Direction Toggle (DIRTGL) and Data Direction Set (DIRSET) registers. Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. Bit 31 30 29 28 27 26 25 24 DIRCLR[31:24] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DIRCLR[23:16] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DIRCLR[15:8] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DIRCLR[7:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bits 31:0 – DIRCLR[31:0] Port Data Direction Clear Writing a '0' to a bit has no effect. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 654 Writing a '1' to a bit will clear the corresponding bit in the DIR register, which configures the I/O pin as an input. Value Description 0 The corresponding I/O pin in the PORT group will keep its configuration. 1 The corresponding I/O pin in the PORT group is configured as input. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 655 32.8.3 Data Direction Set Name:  DIRSET Offset:  0x08 Reset:  0x00000000 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the security attribution for the corresponding I/O pin is set as Non-Secured in the NONSEC register. This register allows the user to set one or more I/O pins as an output, without doing a read-modify-write operation. Changes in this register will also be reflected in the Data Direction (DIR), Data Direction Toggle (DIRTGL) and Data Direction Clear (DIRCLR) registers. Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. Bit 31 30 29 28 27 26 25 24 DIRSET[31:24] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DIRSET[23:16] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DIRSET[15:8] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DIRSET[7:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bits 31:0 – DIRSET[31:0] Port Data Direction Set Writing '0' to a bit has no effect. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 656 Writing '1' to a bit will set the corresponding bit in the DIR register, which configures the I/O pin as an output. Value Description 0 The corresponding I/O pin in the PORT group will keep its configuration. 1 The corresponding I/O pin in the PORT group is configured as an output. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 657 32.8.4 Data Direction Toggle Name:  DIRTGL Offset:  0x0C Reset:  0x00000000 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the security attribution for the corresponding I/O pin is set as Non-Secured in the NONSEC register. This register allows the user to toggle the direction of one or more I/O pins, without doing a read-modifywrite operation. Changes in this register will also be reflected in the Data Direction (DIR), Data Direction Set (DIRSET) and Data Direction Clear (DIRCLR) registers. Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. Bit 31 30 29 28 27 26 25 24 DIRTGL[31:24] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DIRTGL[23:16] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DIRTGL[15:8] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DIRTGL[7:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bits 31:0 – DIRTGL[31:0] Port Data Direction Toggle Writing '0' to a bit has no effect. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 658 Writing '1' to a bit will toggle the corresponding bit in the DIR register, which reverses the direction of the I/O pin. Value Description 0 The corresponding I/O pin in the PORT group will keep its configuration. 1 The direction of the corresponding I/O pin is toggled. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 659 32.8.5 Data Output Value Name:  OUT Offset:  0x10 Reset:  0x00000000 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the security attribution for the corresponding I/O pin is set as Non-Secured in the NONSEC register. This register sets the data output drive value for the individual I/O pins in the PORT. This register can be manipulated without doing a read-modify-write operation by using the Data Output Value Clear (OUTCLR), Data Output Value Set (OUTSET), and Data Output Value Toggle (OUTTGL) registers. Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 660 Bit 31 30 29 28 27 26 25 24 OUT[31:24] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 OUT[23:16] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 OUT[15:8] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 OUT[7:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bits 31:0 – OUT[31:0] PORT Data Output Value For pins configured as outputs via the Data Direction register (DIR), these bits set the logical output drive level. For pins configured as inputs via the Data Direction register (DIR) and with pull enabled via the Pull Enable bit in the Pin Configuration register (PINCFG.PULLEN), these bits will set the input pull direction. Value Description 0 The I/O pin output is driven low, or the input is connected to an internal pull-down. 1 The I/O pin output is driven high, or the input is connected to an internal pull-up. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 661 32.8.6 Data Output Value Clear Name:  OUTCLR Offset:  0x14 Reset:  0x00000000 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the security attribution for the corresponding I/O pin is set as Non-Secured in the NONSEC register. This register allows the user to set one or more output I/O pin drive levels low, without doing a readmodify-write operation. Changes in this register will also be reflected in the Data Output Value (OUT), Data Output Value Toggle (OUTTGL) and Data Output Value Set (OUTSET) registers. Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. Bit 31 30 29 28 27 26 25 24 OUTCLR[31:24] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 OUTCLR[23:16] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 OUTCLR[15:8] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 OUTCLR[7:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bits 31:0 – OUTCLR[31:0] PORT Data Output Value Clear Writing '0' to a bit has no effect. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 662 Writing '1' to a bit will clear the corresponding bit in the OUT register. Pins configured as outputs via the Data Direction register (DIR) will be set to low output drive level. Pins configured as inputs via DIR and with pull enabled via the Pull Enable bit in the Pin Configuration register (PINCFG.PULLEN) will set the input pull direction to an internal pull-down. Value Description 0 The corresponding I/O pin in the PORT group will keep its configuration. 1 The corresponding I/O pin output is driven low, or the input is connected to an internal pulldown. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 663 32.8.7 Data Output Value Set Name:  OUTSET Offset:  0x18 Reset:  0x00000000 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the security attribution for the corresponding I/O pin is set as Non-Secured in the NONSEC register. This register allows the user to set one or more output I/O pin drive levels high, without doing a readmodify-write operation. Changes in this register will also be reflected in the Data Output Value (OUT), Data Output Value Toggle (OUTTGL) and Data Output Value Clear (OUTCLR) registers. Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. Bit 31 30 29 28 27 26 25 24 OUTSET[31:24] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 OUTSET[23:16] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 OUTSET[15:8] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 OUTSET[7:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bits 31:0 – OUTSET[31:0] PORT Data Output Value Set Writing '0' to a bit has no effect. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 664 Writing '1' to a bit will set the corresponding bit in the OUT register, which sets the output drive level high for I/O pins configured as outputs via the Data Direction register (DIR). For pins configured as inputs via Data Direction register (DIR) with pull enabled via the Pull Enable register (PULLEN), these bits will set the input pull direction to an internal pull-up. Value Description 0 The corresponding I/O pin in the group will keep its configuration. 1 The corresponding I/O pin output is driven high, or the input is connected to an internal pullup. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 665 32.8.8 Data Output Value Toggle Name:  OUTTGL Offset:  0x1C Reset:  0x00000000 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the security attribution for the corresponding I/O pin is set as Non-Secured in the NONSEC register. This register allows the user to toggle the drive level of one or more output I/O pins, without doing a readmodify-write operation. Changes in this register will also be reflected in the Data Output Value (OUT), Data Output Value Set (OUTSET) and Data Output Value Clear (OUTCLR) registers. Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. Bit 31 30 29 28 27 26 25 24 OUTTGL[31:24] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 OUTTGL[23:16] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 OUTTGL[15:8] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 OUTTGL[7:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bits 31:0 – OUTTGL[31:0] PORT Data Output Value Toggle Writing '0' to a bit has no effect. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 666 Writing '1' to a bit will toggle the corresponding bit in the OUT register, which inverts the output drive level for I/O pins configured as outputs via the Data Direction register (DIR). For pins configured as inputs via Data Direction register (DIR) with pull enabled via the Pull Enable register (PULLEN), these bits will toggle the input pull direction. Value Description 0 The corresponding I/O pin in the PORT group will keep its configuration. 1 The corresponding OUT bit value is toggled. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 667 32.8.9 Data Input Value Name:  IN Offset:  0x20 Reset:  0x40000000 Property:  Mix-Secure Important:  For SAM L11 Non-Secure accesses, read accesses (R*) are allowed only if the security attribution for the corresponding I/O pin is set as Non-Secured in the NONSEC register. Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. Bit 31 30 29 28 27 26 25 24 IN[31:24] Access R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 IN[23:16] Access R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 IN[15:8] Access R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 IN[7:0] Access R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R R/R*/R Reset 0 0 0 0 0 0 0 0 Bits 31:0 – IN[31:0] PORT Data Input Value These bits are cleared when the corresponding I/O pin input sampler detects a logical low level on the input pin. These bits are set when the corresponding I/O pin input sampler detects a logical high level on the input pin. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 668 32.8.10 Control Name:  CTRL Offset:  0x24 Reset:  0x00000000 Property:  PAC Write-Protection, Secure Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. Bit 31 30 29 28 27 26 25 24 SAMPLING[31:24] Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 SAMPLING[23:16] Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 SAMPLING[15:8] Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 SAMPLING[7:0] Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 0 0 0 Bits 31:0 – SAMPLING[31:0] Input Sampling Mode Configures the input sampling functionality of the I/O pin input samplers, for pins configured as inputs via the Data Direction register (DIR). The input samplers are enabled and disabled in sub-groups of eight. Thus if any pins within a byte request continuous sampling, all pins in that eight pin sub-group will be continuously sampled. Value Description 0 The I/O pin input synchronizer is disabled. 1 The I/O pin input synchronizer is enabled. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 669 32.8.11 Write Configuration Name:  WRCONFIG Offset:  0x28 Reset:  0x00000000 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, write accesses (W*) are allowed only if the security attribution for the corresponding I/O pin is set as Non-Secured in the NONSEC register. Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. This write-only register is used to configure several pins simultaneously with the same configuration and/or peripheral multiplexing. In order to avoid side effect of non-atomic access, 8-bit or 16-bit writes to this register will have no effect. Reading this register always returns zero. Bit 31 30 29 28 27 26 25 24 HWSEL WRPINCFG WRPMUX PMUX[3:0] Access W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W Reset 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DRVSTR PULLEN INEN PMUXEN Access W/W*/W W/W*/W W/W*/W W/W*/W Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 PINMASK[15:8] Access W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 PINMASK[7:0] Access W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W Reset 0 0 0 0 0 0 0 0 Bit 31 – HWSEL Half-Word Select This bit selects the half-word field of a 32-PORT group to be reconfigured in the atomic write operation. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 670 This bit will always read as zero. Value Description 0 The lower 16 pins of the PORT group will be configured. 1 The upper 16 pins of the PORT group will be configured. Bit 30 – WRPINCFG Write PINCFG This bit determines whether the atomic write operation will update the Pin Configuration register (PINCFGy) or not for all pins selected by the WRCONFIG.PINMASK and WRCONFIG.HWSEL bits. Writing '0' to this bit has no effect. Writing '1' to this bit updates the configuration of the selected pins with the written WRCONFIG.DRVSTR, WRCONFIG.PULLEN, WRCONFIG.INEN, WRCONFIG.PMUXEN, and WRCONFIG.PINMASK values. This bit will always read as zero. Value Description 0 The PINCFGy registers of the selected pins will not be updated. 1 The PINCFGy registers of the selected pins will be updated. Bit 28 – WRPMUX Write PMUX This bit determines whether the atomic write operation will update the Peripheral Multiplexing register (PMUXn) or not for all pins selected by the WRCONFIG.PINMASK and WRCONFIG.HWSEL bits. Writing '0' to this bit has no effect. Writing '1' to this bit updates the pin multiplexer configuration of the selected pins with the written WRCONFIG. PMUX value. This bit will always read as zero. Value Description 0 The PMUXn registers of the selected pins will not be updated. 1 The PMUXn registers of the selected pins will be updated. Bits 27:24 – PMUX[3:0] Peripheral Multiplexing These bits determine the new value written to the Peripheral Multiplexing register (PMUXn) for all pins selected by the WRCONFIG.PINMASK and WRCONFIG.HWSEL bits, when the WRCONFIG.WRPMUX bit is set. These bits will always read as zero. Bit 22 – DRVSTR Output Driver Strength Selection This bit determines the new value written to PINCFGy.DRVSTR for all pins selected by the WRCONFIG.PINMASK and WRCONFIG.HWSEL bits, when the WRCONFIG.WRPINCFG bit is set. This bit will always read as zero. Bit 18 – PULLEN Pull Enable This bit determines the new value written to PINCFGy.PULLEN for all pins selected by the WRCONFIG.PINMASK and WRCONFIG.HWSEL bits, when the WRCONFIG.WRPINCFG bit is set. This bit will always read as zero. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 671 Bit 17 – INEN Input Enable This bit determines the new value written to PINCFGy.INEN for all pins selected by the WRCONFIG.PINMASK and WRCONFIG.HWSEL bits, when the WRCONFIG.WRPINCFG bit is set. This bit will always read as zero. Bit 16 – PMUXEN Peripheral Multiplexer Enable This bit determines the new value written to PINCFGy.PMUXEN for all pins selected by the WRCONFIG.PINMASK and WRCONFIG.HWSEL bits, when the WRCONFIG.WRPINCFG bit is set. This bit will always read as zero. Bits 15:0 – PINMASK[15:0] Pin Mask for Multiple Pin Configuration These bits select the pins to be configured within the half-word group selected by the WRCONFIG.HWSEL bit. These bits will always read as zero. Value Description 0 The configuration of the corresponding I/O pin in the half-word group will be left unchanged. 1 The configuration of the corresponding I/O pin in the half-word PORT group will be updated. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 672 32.8.12 Event Input Control Name:  EVCTRL Offset:  0x2C Reset:  0x00000000 Property:  PAC Write-Protection, Secure Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. There are up to four input event pins for each PORT group. Each byte of this register addresses one Event input pin. Bit 31 30 29 28 27 26 25 24 PORTEIx EVACTx[1:0] PIDx[4:0] Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 PORTEIx EVACTx[1:0] PIDx[4:0] Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 PORTEIx EVACTx[1:0] PIDx[4:0] Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 PORTEIx EVACTx[1:0] PIDx[4:0] Access RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW RW/-/RW Reset 0 0 0 0 0 0 0 0 Bits 31,23,15,7 – PORTEIx PORT Event Input Enable x [x = 3..0] Value Description 0 The event action x (EVACTx) will not be triggered on any incoming event. 1 The event action x (EVACTx) will be triggered on any incoming event. Bits 30:29, 22:21,14:13,6:5 – EVACTx PORT Event Action x [x = 3..0] These bits define the event action the PORT will perform on event input x. See also Table 32-4. Bits 28:24,20:16,12:8,4:0 – PIDx PORT Event Pin Identifier x [x = 3..0] These bits define the I/O pin on which the event action will be performed, according to Table 32-5. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 673 Table 32-4. PORT Event x Action ( x = [3..0] ) Value Name Description 0x0 OUT Output register of pin will be set to level of event. 0x1 SET Set output register of pin on event. 0x2 CLR Clear output register of pin on event. 0x3 TGL Toggle output register of pin on event. Table 32-5. PORT Event x Pin Identifier ( x = [3..0] ) Value Name Description 0x0 PIN0 Event action to be executed on PIN 0. 0x1 PIN1 Event action to be executed on PIN 1. ... ... ... 0x31 PIN31 Event action to be executed on PIN 31. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 674 32.8.13 Peripheral Multiplexing n Name:  PMUX Offset:  0x30 + n*0x01 [n=0..15] Reset:  0x00 except PMUX15 = 0x06 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the security attribution for the corresponding I/O pin is set as Non-Secured in the NONSEC register. Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. There are up to 16 Peripheral Multiplexing registers in each group, one for every set of two subsequent I/O lines. The n denotes the number of the set of I/O lines. Bit 7 6 5 4 3 2 1 0 PMUXO[3:0] PMUXE[3:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 0 0 Bits 7:4 – PMUXO[3:0] Peripheral Multiplexing for Odd-Numbered Pin These bits select the peripheral function for odd-numbered pins (2*n + 1) of a PORT group, if the corresponding PINCFGy.PMUXEN bit is '1'. Not all possible values for this selection may be valid. For more details, refer to the I/O Multiplexing and Considerations. PMUXO[3:0] Name Description 0x0 A Peripheral function A selected 0x1 B Peripheral function B selected 0x2 C Peripheral function C selected 0x3 D Peripheral function D selected 0x4 E Peripheral function E selected 0x5 - Reserved 0x6 G Peripheral function G selected 0x7 H Peripheral function H selected SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 675 PMUXO[3:0] Name Description 0x8 I Peripheral function I selected 0x9-0xF - Reserved Bits 3:0 – PMUXE[3:0] Peripheral Multiplexing for Even-Numbered Pin These bits select the peripheral function for even-numbered pins (2*n) of a PORT group, if the corresponding PINCFGy.PMUXEN bit is '1'. Not all possible values for this selection may be valid. For more details, refer to the I/O Multiplexing and Considerations. PMUXE[3:0] Name Description 0x0 A Peripheral function A selected 0x1 B Peripheral function B selected 0x2 C Peripheral function C selected 0x3 D Peripheral function D selected 0x4 E Peripheral function E selected 0x5 - Reserved 0x6 G Peripheral function G selected 0x7 H Peripheral function H selected 0x8 I Peripheral function I selected 0x9-0xF - Reserved SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 676 32.8.14 Pin Configuration Name:  PINCFG Offset:  0x40 + n*0x01 [n=0..31] Reset:  0x00 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the security attribution for the corresponding I/O pin is set as Non-Secured in the NONSEC register. Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. There are up to 32 Pin Configuration registers in each PORT group, one for each I/O line. Bit 7 6 5 4 3 2 1 0 DRVSTR PULLEN INEN PMUXEN Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 Bit 6 – DRVSTR Output Driver Strength Selection This bit controls the output driver strength of an I/O pin configured as an output. Value Description 0 Pin drive strength is set to normal drive strength. 1 Pin drive strength is set to stronger drive strength. Bit 2 – PULLEN Pull Enable This bit enables the internal pull-up or pull-down resistor of an I/O pin configured as an input. Value Description 0 Internal pull resistor is disabled, and the input is in a high-impedance configuration. 1 Internal pull resistor is enabled, and the input is driven to a defined logic level in the absence of external input. Bit 1 – INEN Input Enable This bit controls the input buffer of an I/O pin configured as either an input or output. Writing a zero to this bit disables the input buffer completely, preventing read-back of the physical pin state when the pin is configured as either an input or output. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 677 Value Description 0 Input buffer for the I/O pin is disabled, and the input value will not be sampled. 1 Input buffer for the I/O pin is enabled, and the input value will be sampled when required. Bit 0 – PMUXEN Peripheral Multiplexer Enable This bit enables or disables the peripheral multiplexer selection set in the Peripheral Multiplexing register (PMUXn) to enable or disable alternative peripheral control over an I/O pin direction and output drive value. Writing a zero to this bit allows the PORT to control the pad direction via the Data Direction register (DIR) and output drive value via the Data Output Value register (OUT). The peripheral multiplexer value in PMUXn is ignored. Writing '1' to this bit enables the peripheral selection in PMUXn to control the pad. In this configuration, the physical pin state may still be read from the Data Input Value register (IN) if PINCFGn.INEN is set. Value Description 0 The peripheral multiplexer selection is disabled, and the PORT registers control the direction and output drive value. 1 The peripheral multiplexer selection is enabled, and the selected peripheral function controls the direction and output drive value. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 678 32.8.15 Interrupt Enable Clear Name:  INTENCLR Offset:  0x60 Reset:  0x00000000 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 NSCHK Access RW/RW/RW Reset 0 Bit 0 – NSCHK Non-Secure Check Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Non-Secure Check Interrupt Enable bit, which disables the Non-Secure Check interrupt. Value Description 0 The Non-Secure Check interrupt is disabled. 1 The Non-Secure Check interrupt is enabled. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 679 32.8.16 Interrupt Enable Set Name:  INTENSET Offset:  0x64 Reset:  0x00000000 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear register (INTENCLR). Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 NSCHK Access RW/RW/RW Reset 0 Bit 0 – NSCHK Non-Secure Check Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Non-Secure Check Interrupt Enable bit, which enables the Non-Secure Check interrupt. Value Description 0 The Non-Secure Check interrupt is disabled. 1 The Non-Secure Check interrupt is enabled. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 680 32.8.17 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x68 Reset:  0x00000000 Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 NSCHK Access RW/RW/RW Reset 0 Bit 0 – NSCHK Non-Secure Check This flag is set on NONSEC write when a bit in NSCHK is 1 and the corresponding bit in NONSEC is cleared, or when a bit in NSCHK is 0 and the corresponding bit in NONSEC is set. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Non-Secure Check interrupt flag. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 681 32.8.18 Security Attribution Name:  NONSEC Offset:  0x6C Reset:  0x00000000 Property:  PAC Write-Protection, Write-Secure Important:  This register is only available for SAM L11 and has no effect for SAM L10. This register allows the user to configure one or more I/O pins as secured or non-secured. Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. Bit 31 30 29 28 27 26 25 24 NONSEC[31:24] Access RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 NONSEC[23:16] Access RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 NONSEC[15:8] Access RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 NONSEC[7:0] Access RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW Reset 0 0 0 0 0 0 0 0 Bits 31:0 – NONSEC[31:0] Port Security Attribution These bits set the security attribution for the individual I/O pins in the PORT group. Value Description 0 The corresponding I/O pin in the PORT group is configured as secured. When module is PAC secured, the configuration for this pin is only available through the secure alias. Attempt SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 682 Value Description to change the pin configuration through the non-secure alias will be silently ignored and reads will return 0. 1 The corresponding I/O pin in the PORT group is configured as non-secured. The I/O line configuration for this pin is available through the non-secure alias. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 683 32.8.19 Security Attribution Check Name:  NSCHK Offset:  0x70 Reset:  0x00000000 Property:  PAC Write-Protection Important:  This register is only available for SAM L11 and has no effect for SAM L10. This register allows the user to select one or more pins to check their security attribution as non-secured. Tip:  The I/O pins are assembled in pin groups (”PORT groups”) with up to 32 pins. Group 0 consists of the PA pins, group 1 is for the PB pins, etc. Each pin group has its own PORT registers, with a 0x80 address spacing. For example, the register address offset for the Data Direction (DIR) register for group 0 (PA00 to PA31) is 0x00, and the register address offset for the DIR register for group 1 (PB00 to PB31) is 0x80. Bit 31 30 29 28 27 26 25 24 NSCHK[31:24] Access RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 NSCHK[23:16] Access RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 NSCHK[15:8] Access RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 NSCHK[7:0] Access RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW Reset 0 0 0 0 0 0 0 0 Bits 31:0 – NSCHK[31:0] Port Security Attribution Check These bits select the individual pins for security attribution check. If any pin selected in NSCHK has the corresponding bit in NONSEC set to the opposite value, then the NSCHK interrupt flag will be set. Value Description 0 0-to-1 transition will be detected on corresponding NONSEC bit. 1 1-to-0 transition will be detected on corresponding NONSEC bit. SAM L10/L11 Family PORT - I/O Pin Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 684 33. EVSYS – Event System 33.1 Overview The Event System (EVSYS) allows autonomous, low-latency and configurable communication between peripherals. Several peripherals can be configured to generate and/or respond to signals known as events. The exact condition to generate an event, or the action taken upon receiving an event, is specific to each peripheral. Peripherals that respond to events are called event users. Peripherals that generate events are called event generators. A peripheral can have one or more event generators and can have one or more event users. Channels and event users can be defined as secured or non-secured, where secured channels or event users can only be handled by secure code. Communication is made without CPU intervention and without consuming system resources such as bus or RAM bandwidth. This reduces the load on the CPU and other system resources, compared to a traditional interrupt-based system. 33.2 Features • 8 configurable event channels: – All channels can be connected to any event generator – All channels provide a pure asynchronous path – 4 channels (CHANNEL0 to CHANNEL3) provide a resynchronized or synchronous path using their dedicated generic clock (GCLK_EVSYS_CHANNEL_n) • 49 event generators. • 23 event users. • Configurable edge detector. • Peripherals can be event generators, event users, or both. • SleepWalking and interrupt for operation in sleep modes. • Software event generation. • Each event user can choose which channel to respond to. • Optional Static or Round-Robin interrupt priority arbitration. • Each channel and each event user can be configured as secured or non-secured (SAM L11). SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 685 33.3 Block Diagram Figure 33-1. Event System Block Diagram USER m+1 Event Channel n Event Channel 1 Event Channel 0 USER m D Q R Synchronized Path Asynchronous Path Edge Detector CHANNEL0.EDGSEL CHANNEL0.PATH EVT Q D R Q D R Q D R Resynchronized Path D Q R D Q R D Q R SWEVT.CHANNEL0 PERIPHERAL x PERIPHERAL0 CHANNEL0.EVGEN USERm.CHANNEL Channel_EVT_0 EVT ACK Channel_EVT_n Clock Request [n:0] To Peripheral x Peripheral x GCLK_EVSYS_0 SleepWalking Detector Event Acknowledge 33.4 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 33.4.1 I/O Lines Not applicable. 33.4.2 Power Management The EVSYS can be used to wake up the CPU from all sleep modes (except OFF Mode), even if the clock used by the EVSYS channel and the EVSYS bus clock are disabled. Refer to the PM – Power Manager for details on the different sleep modes. Although the clock for the EVSYS is stopped, the device still can wake up the EVSYS clock. Some event generators can generate an event when their clocks are stopped. The generic clock for the channel (GCLK_EVSYS_CHANNEL_n) will be restarted if that channel uses a synchronized path or a resynchronized path. It does not need to wake the system from sleep. Important:  This generic clock only applies to channels which can be configured as synchronous or resynchronized. Related Links 22. PM – Power Manager 33.4.3 Clocks The EVSYS bus clock (CLK_EVSYS_APB) can be enabled and disabled in the Main Clock module, and the default state of CLK_EVSYS_APB can be found in Peripheral Clock Masking. Each EVSYS channel which can be configured as synchronous or resynchronized has a dedicated generic clock (GCLK_EVSYS_CHANNEL_n). These are used for event detection and propagation for each channel. These clocks must be configured and enabled in the generic clock controller before using the EVSYS. Refer to GCLK - Generic Clock Controller for details. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 686 Important:  Only EVSYS channel 0 to 3 can be configured as synchronous or resynchronized. Related Links 19.6.2.6 Peripheral Clock Masking 18. GCLK - Generic Clock Controller 33.4.4 DMA Not applicable. 33.4.5 Interrupts The interrupt request line is connected to the Interrupt Controller. Using the EVSYS interrupts requires the interrupt controller to be configured first. Refer to Nested Vector Interrupt Controller for details. 33.4.6 Events Not applicable. 33.4.7 Debug Operation When the CPU is halted in debug mode, this peripheral will continue normal operation. If the peripheral is configured to require periodical service by the CPU through interrupts or similar, improper operation or data loss may result during debugging. This peripheral can be forced to halt operation during debugging. 33.4.8 Register Access Protection Registers with write-access can be optionally write-protected by the Peripheral Access Controller (PAC), except for the following: • Channel Pending Interrupt (INTPEND) • Channel n Interrupt Flag Status and Clear (CHINTFLAGn) Note:  Optional write-protection is indicated by the "PAC Write-Protection" property in the register description. Write-protection does not apply for accesses through an external debugger. 33.4.9 SAM L11 TrustZone Specific Register Access Protection When the EVSYS is not PAC secured, non-secure and secure code can both access all functionalities. When the EVSYS is PAC secured, all registers are by default available in the secure alias only. A PAC secured EVSYS can open up individual event channels and event users for non-secure access. This is done using the NONSECCHAN and NONSECUSER registers. When a channel or event user has been configured as non-secure, it can be handled from non-secure code using the EVSYS module nonsecure alias. Since only Secured code has the rights to modify the NONSECCHAN and NONSECUSER registers, an interrupt-based mechanism has been added to let Non Secured code know when these registers have been changed by Secured code. A single flag called NSCHK in the INTFLAG register will rise should changes, conditioned by the NSCHKCHAN and NSCHKUSER registers, occur in the NONSECCHAN and NONSECUSER registers. Note:  Refer to the Mix-Secure Peripherals section in the SAM L11 Security Features chapter. 33.4.10 Analog Connections Not applicable. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 687 33.5 Functional Description 33.5.1 Principle of Operation The Event System consists of several channels which route the internal events from peripherals (generators) to other internal peripherals or I/O pins (users). Each event generator can be selected as source for multiple channels, but a channel cannot be set to use multiple event generators at the same time. A channel path can be configured in asynchronous, synchronous or resynchronized mode of operation. The mode of operation must be selected based on the requirements of the application. When using synchronous or resynchronized path, the Event System includes options to transfer events to users when rising, falling or both edges are detected on event generators. For further details, refer to the Channel Path section of this chapter. Related Links 33.5.2.6 Channel Path 33.5.2 Basic Operation 33.5.2.1 Initialization Before enabling event routing within the system, the Event Users Multiplexer and Event Channels must be selected in the Event System (EVSYS), and the two peripherals that generate and use the event have to be configured. The recommended sequence is: 1. In the event generator peripheral, enable output of event by writing a '1' to the respective Event Output Enable bit ("EO") in the peripheral's Event Control register (e.g., TCC.EVCTRL.MCEO1, AC.EVCTRL.WINEO0, RTC.EVCTRL.OVFEO). 2. Configure the EVSYS: 2.1. Configure the Event User multiplexer by writing the respective EVSYS.USERm register, see also 33.5.2.3 User Multiplexer Setup. 2.2. Configure the Event Channel by writing the respective EVSYS.CHANNELn register, see also 33.5.2.4 Event System Channel. 3. Configure the action to be executed by the event user peripheral by writing to the Event Action bits (EVACT) in the respective Event control register (e.g., TC.EVCTRL.EVACT, PDEC.EVCTRL.EVACT). Note: not all peripherals require this step. 4. In the event user peripheral, enable event input by writing a '1' to the respective Event Input Enable bit ("EI") in the peripheral's Event Control register (e.g., AC.EVCTRL.IVEI0, ADC.EVCTRL.STARTEI). 33.5.2.2 Enabling, Disabling, and Resetting The EVSYS is always enabled. The EVSYS is reset by writing a ‘1’ to the Software Reset bit in the Control A register (CTRLA.SWRST). All registers in the EVSYS will be reset to their initial state and all ongoing events will be canceled. Refer to CTRLA.SWRST register for details. 33.5.2.3 User Multiplexer Setup The user multiplexer defines the channel to be connected to which event user. Each user multiplexer is dedicated to one event user. A user multiplexer receives all event channels output and must be configured to select one of these channels, as shown in Block Diagram section. The channel is selected with the Channel bit group in the User register (USERm.CHANNEL). SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 688 The user multiplexer must always be configured before the channel. A list of all user multiplexers is found in the User (USERm) register description. Related Links 33.3 Block Diagram 33.5.2.4 Event System Channel An event channel can select one event from a list of event generators. Depending on configuration, the selected event could be synchronized, resynchronized or asynchronously sent to the users. When synchronization or resynchronization is required, the channel includes an internal edge detector, allowing the Event System to generate internal events when rising, falling or both edges are detected on the selected event generator. An event channel is able to generate internal events for the specific software commands. A channel block diagram is shown in Block Diagram section. Related Links 33.3 Block Diagram 33.5.2.5 Event Generators Each event channel can receive the events form all event generators. All event generators are listed in the Event Generator bit field in the Channel n register (CHANNELn.EVGEN). For details on event generation, refer to the corresponding module chapter. The channel event generator is selected by the Event Generator bit group in the Channel register (CHANNELn.EVGEN). By default, the channels are not connected to any event generators (ie, CHANNELn.EVGEN = 0) 33.5.2.6 Channel Path There are different ways to propagate the event from an event generator: • Asynchronous path • Synchronous path • Resynchronized path The path is decided by writing to the Path Selection bit group of the Channel register (CHANNELn.PATH). Asynchronous Path When using the asynchronous path, the events are propagated from the event generator to the event user without intervention from the Event System. The GCLK for this channel (GCLK_EVSYS_CHANNEL_n) is not mandatory, meaning that an event will be propagated to the user without any clock latency. When the asynchronous path is selected, the channel cannot generate any interrupts, and the Channel x Status register (CHSTATUSx) is always zero. The edge detection is not required and must be disabled by software. Each peripheral event user has to select which event edge must trigger internal actions. For further details, refer to each peripheral chapter description. Synchronous Path The synchronous path should be used when the event generator and the event channel share the same generator for the generic clock. If they do not share the same clock, a logic change from the event generator to the event channel might not be detected in the channel, which means that the event will not be propagated to the event user. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 689 When using the synchronous path, the channel is able to generate interrupts. The channel status bits in the Channel Status register (CHSTATUS) are also updated and available for use. Resynchronized Path The resynchronized path are used when the event generator and the event channel do not share the same generator for the generic clock. When the resynchronized path is used, resynchronization of the event from the event generator is done in the channel. When the resynchronized path is used, the channel is able to generate interrupts. The channel status bits in the Channel Status register (CHSTATUS) are also updated and available for use. 33.5.2.7 Edge Detection When synchronous or resynchronized paths are used, edge detection must be enabled. The event system can execute edge detection in three different ways: • Generate an event only on the rising edge • Generate an event only on the falling edge • Generate an event on rising and falling edges. Edge detection is selected by writing to the Edge Selection bit group of the Channel register (CHANNELn.EDGSEL). 33.5.2.8 Event Latency An event from an event generator is propagated to an event user with different latency, depending on event channel configuration. • Asynchronous Path: The maximum routing latency of an external event is related to the internal signal routing and it is device dependent. • Synchronous Path: The maximum routing latency of an external event is one GCLK_EVSYS_CHANNEL_n clock cycle. • Resynchronized Path: The maximum routing latency of an external event is three GCLK_EVSYS_CHANNEL_n clock cycles. The maximum propagation latency of a user event to the peripheral clock core domain is three peripheral clock cycles. The event generators, event channel and event user clocks ratio must be selected in relation with the internal event latency constraints. Events propagation or event actions in peripherals may be lost if the clock setup violates the internal latencies. 33.5.2.9 The Overrun Channel n Interrupt The Overrun Channel n interrupt flag in the Interrupt Flag Status and Clear register (CHINTFLAGn.OVR) will be set, and the optional interrupt will be generated in the following cases: • One or more event users on channel n is not ready when there is a new event. • An event occurs when the previous event on channel m has not been handled by all event users connected to that channel. The flag will only be set when using synchronous or resynchronized paths. In the case of asynchronous path, the CHINTFLAGn.OVR is always read as zero. 33.5.2.10 The Event Detected Channel n Interrupt The Event Detected Channel n interrupt flag in the Interrupt Flag Status and Clear register (CHINTFLAGn.EVD) is set when an event coming from the event generator configured on channel n is detected. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 690 The flag will only be set when using a synchronous or resynchronized path. In the case of asynchronous path, the CHINTFLAGn.EVD is always zero. 33.5.2.11 Channel Status The Channel Status register (CHSTATUS) shows the status of the channels when using a synchronous or resynchronized path. There are two different status bits in CHSTATUS for each of the available channels: • The CHSTATUSn.BUSYCH bit will be set when an event on the corresponding channel n has not been handled by all event users connected to that channel. • The CHSTATUSn.RDYUSR bit will be set when all event users connected to the corresponding channel are ready to handle incoming events on that channel. 33.5.2.12 Software Event A software event can be initiated on a channel by writing a '1' to the Software Event bit in the Channel register (CHANNELm.SWEVT). Then the software event can be serviced as any event generator; i.e., when the bit is set to ‘1’, an event will be generated on the respective channel. 33.5.2.13 Interrupt Status and Interrupts Arbitration The Interrupt Status register stores all channels with pending interrupts, as shown below. Figure 33-2. Interrupt Status Register CHINTFLAG31.OVR CHINTENSET31.OVR CHINTFLAG31.EVD CHINTENSET31.EVD CHINTFLAG0.OVR CHINTENSET0.OVR CHINTFLAG0.EVD CHINTENSET0.EVD 31 0 INTSTATUS 30 1 The Event System can arbitrate between all channels with pending interrupts. The arbiter can be configured to prioritize statically or dynamically the incoming events. The priority is evaluated each time a new channel has an interrupt pending, or an interrupt has been cleared. The Channel Pending Interrupt register (INTPEND) will provide the channel number with the highest interrupt priority, and the corresponding channel interrupt flags and status bits. By default, static arbitration is enabled (PRICTRL.RRENx is '0'), the arbiter will prioritize a low channel number over a high channel number as shown below. When using the status scheme, there is a risk of high channel numbers never being granted access by the arbiter. This can be avoided using a dynamic arbitration scheme. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 691 Figure 33-3. Static Priority Highest Channel Lowest Channel Highest Priority Channel N Lowest Priority Channel 0 Channel x+1 Channel x . . . . . . The dynamic arbitration scheme available in the Event System is round-robin. Round-robin arbitration is enabled by writing PRICTRL.RREN to one. With the round-robin scheme, the channel number of the last channel being granted access will have the lowest priority the next time the arbiter has to grant access to a channel, as shown below. The channel number of the last channel being granted access, will be stored in the Channel Priority Number bit group in the Priority Control register (PRICTRL.PRI). Figure 33-4. Round-Robin Scheduling Channel N Channel N Channel 0 Channel x Channel x+1 Channel x last acknowledge request Channel (x+1) last acknowledge request Channel 0 Channel x Channel x+1 Channel x+2 Lowest Priority Highest Priority Highest Priority Lowest Priority . . . . . . The Channel Pending Interrupt register (INTPEND) also offers the possibility to indirectly clear the interrupt flags of a specific channel. Writing a flag to one in this register, will clear the corresponding interrupt flag of the channel specified by the INTPEND.ID bits. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 692 33.5.3 Interrupts The EVSYS has the following interrupt sources for each channel: • Overrun Channel n interrupt (OVR) • Event Detected Channel n interrupt (EVD) These interrupts events are asynchronous wake-up sources. Each interrupt source has an interrupt flag associated with it. The interrupt flag in the corresponding Channel n Interrupt Flag Status and Clear (CHINTFLAG) register is set when the interrupt condition occurs. Note:  Interrupts must be globally enabled to allow the generation of interrupt requests. Each interrupt can be individually enabled by writing a '1' to the corresponding bit in the Channel n Interrupt Enable Set (CHINTENSET) register, and disabled by writing a '1' to the corresponding bit in the Channel n Interrupt Enable Clear (CHINTENCLR) register. An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until the interrupt flag is cleared, the interrupt is disabled or the Event System is reset. All interrupt requests are ORed together on system level to generate one combined interrupt request to the NVIC. The user must read the Channel Interrupt Status (INTSTATUS) register to identify the channels with pending interrupts, and must read the Channel n Interrupt Flag Status and Clear (CHINTFLAG) register to determine which interrupt condition is present for the corresponding channel. It is also possible to read the Interrupt Pending register (INTPEND), which provides the highest priority channel with pending interrupt and the respective interrupt flags. 33.5.4 Sleep Mode Operation The Event System can generate interrupts to wake up the device from IDLE or STANDBY sleep mode. To be able to run in standby, the Run in Standby bit in the Channel register (CHANNELn.RUNSTDBY) must be set to '1'. When the Generic Clock On Demand bit in Channel register (CHANNELn.ONDEMAND) is set to '1' and the event generator is detected, the event channel will request its clock (GCLK_EVSYS_CHANNEL_n). The event latency for a resynchronized channel path will increase by two GCLK_EVSYS_CHANNEL_n clock (i.e., up to five GCLK_EVSYS_CHANNEL_n clock cycles). A channel will behave differently in different sleep modes regarding to CHANNELn.RUNSTDBY and CHANNELn.ONDEMAND: Table 33-1. Event Channel Sleep Behavior CHANNELn.PAT H CHANNELn. ONDEMAND CHANNELn. RUNSTDBY Sleep Behavior ASYNC 0 0 Only run in IDLE sleep modes if an event must be propagated. Disabled in STANDBY sleep mode. SYNC/RESYNC 0 1 Run in both IDLE and STANDBY sleep modes. SYNC/RESYNC 1 0 Only run in IDLE sleep modes if an event must be propagated. Disabled in STANDBY sleep mode. Two GCLK_EVSYS_n latency SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 693 CHANNELn.PAT H CHANNELn. ONDEMAND CHANNELn. RUNSTDBY Sleep Behavior added in RESYNC path before the event is propagated internally. SYNC/RESYNC 1 1 Run in both IDLE and STANDBY sleep modes. Two GCLK_EVSYS_n latency added in RESYNC path before the event is propagated internally. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 694 33.6 Register Summary Important:  For SAM L11, the EVSYS register map is automatically duplicated in a Secure and Non-Secure alias: • The Non-Secure alias is at the peripheral base address • The Secure alias is located at the peripheral base address + 0x200 Refer to Mix-Secure Peripherals for more information on register access rights Offset Name Bit Pos. 0x00 CTRLA 7:0 SWRST 0x01 ... 0x03 Reserved 0x04 SWEVT 7:0 CHANNEL[7:0] 15:8 23:16 31:24 0x08 PRICTRL 7:0 RREN PRI[1:0] 0x09 ... 0x0F Reserved 0x10 INTPEND 7:0 ID[1:0] 15:8 BUSY READY EVD OVR 0x12 ... 0x13 Reserved 0x14 INTSTATUS 7:0 CHINT3 CHINT2 CHINT1 CHINT0 15:8 23:16 31:24 0x18 BUSYCH 7:0 BUSYCHx3 BUSYCHx2 BUSYCHx1 BUSYCHx0 15:8 23:16 31:24 0x1C READYUSR 7:0 READYUSR3 READYUSR2 READYUSR1 READYUSR0 15:8 23:16 31:24 0x20 CHANNEL0 7:0 EVGEN[5:0] 15:8 ONDEMAND RUNSTDBY EDGSEL[1:0] PATH[1:0] 23:16 31:24 0x24 CHINTENCLR0 7:0 EVD OVR 0x25 CHINTENSET0 7:0 EVD OVR SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 695 Offset Name Bit Pos. 0x26 CHINTFLAG0 7:0 EVD OVR 0x27 CHSTATUS0 7:0 BUSYCH RDYUSR 0x28 CHANNEL1 7:0 EVGEN[5:0] 15:8 ONDEMAND RUNSTDBY EDGSEL[1:0] PATH[1:0] 23:16 31:24 0x2C CHINTENCLR1 7:0 EVD OVR 0x2D CHINTENSET1 7:0 EVD OVR 0x2E CHINTFLAG1 7:0 EVD OVR 0x2F CHSTATUS1 7:0 BUSYCH RDYUSR 0x30 CHANNEL2 7:0 EVGEN[5:0] 15:8 ONDEMAND RUNSTDBY EDGSEL[1:0] PATH[1:0] 23:16 31:24 0x34 CHINTENCLR2 7:0 EVD OVR 0x35 CHINTENSET2 7:0 EVD OVR 0x36 CHINTFLAG2 7:0 EVD OVR 0x37 CHSTATUS2 7:0 BUSYCH RDYUSR 0x38 CHANNEL3 7:0 EVGEN[5:0] 15:8 ONDEMAND RUNSTDBY EDGSEL[1:0] PATH[1:0] 23:16 31:24 0x3C CHINTENCLR3 7:0 EVD OVR 0x3D CHINTENSET3 7:0 EVD OVR 0x3E CHINTFLAG3 7:0 EVD OVR 0x3F CHSTATUS3 7:0 BUSYCH RDYUSR 0x40 CHANNEL4 7:0 EVGEN[5:0] 15:8 ONDEMAND RUNSTDBY EDGSEL[1:0] PATH[1:0] 23:16 31:24 0x44 CHINTENCLR4 7:0 EVD OVR 0x45 CHINTENSET4 7:0 EVD OVR 0x46 CHINTFLAG4 7:0 EVD OVR 0x47 CHSTATUS4 7:0 BUSYCH RDYUSR 0x48 CHANNEL5 7:0 EVGEN[5:0] 15:8 ONDEMAND RUNSTDBY EDGSEL[1:0] PATH[1:0] 23:16 31:24 0x4C CHINTENCLR5 7:0 EVD OVR 0x4D CHINTENSET5 7:0 EVD OVR 0x4E CHINTFLAG5 7:0 EVD OVR 0x4F CHSTATUS5 7:0 BUSYCH RDYUSR 0x50 CHANNEL6 7:0 EVGEN[5:0] 15:8 ONDEMAND RUNSTDBY EDGSEL[1:0] PATH[1:0] 23:16 31:24 SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 696 Offset Name Bit Pos. 0x54 CHINTENCLR6 7:0 EVD OVR 0x55 CHINTENSET6 7:0 EVD OVR 0x56 CHINTFLAG6 7:0 EVD OVR 0x57 CHSTATUS6 7:0 BUSYCH RDYUSR 0x58 CHANNEL7 7:0 EVGEN[5:0] 15:8 ONDEMAND RUNSTDBY EDGSEL[1:0] PATH[1:0] 23:16 31:24 0x5C CHINTENCLR7 7:0 EVD OVR 0x5D CHINTENSET7 7:0 EVD OVR 0x5E CHINTFLAG7 7:0 EVD OVR 0x5F CHSTATUS7 7:0 BUSYCH RDYUSR 0x60 ... 0x011F Reserved 0x0120 USER0 7:0 CHANNEL[3:0] 0x0121 USER1 7:0 CHANNEL[3:0] 0x0122 USER2 7:0 CHANNEL[3:0] 0x0123 USER3 7:0 CHANNEL[3:0] 0x0124 USER4 7:0 CHANNEL[3:0] 0x0125 USER5 7:0 CHANNEL[3:0] 0x0126 USER6 7:0 CHANNEL[3:0] 0x0127 USER7 7:0 CHANNEL[3:0] 0x0128 USER8 7:0 CHANNEL[3:0] 0x0129 USER9 7:0 CHANNEL[3:0] 0x012A USER10 7:0 CHANNEL[3:0] 0x012B USER11 7:0 CHANNEL[3:0] 0x012C USER12 7:0 CHANNEL[3:0] 0x012D USER13 7:0 CHANNEL[3:0] 0x012E USER14 7:0 CHANNEL[3:0] 0x012F USER15 7:0 CHANNEL[3:0] 0x0130 USER16 7:0 CHANNEL[3:0] 0x0131 USER17 7:0 CHANNEL[3:0] 0x0132 USER18 7:0 CHANNEL[3:0] 0x0133 USER19 7:0 CHANNEL[3:0] 0x0134 USER20 7:0 CHANNEL[3:0] 0x0135 USER21 7:0 CHANNEL[3:0] 0x0136 USER22 7:0 CHANNEL[3:0] 0x0137 ... 0x01D3 Reserved 0x01D4 INTENCLR 7:0 NSCHK 0x01D5 INTENSET 7:0 NSCHK 0x01D6 INTFLAG 7:0 NSCHK 0x01D7 Reserved 0x01D8 NONSECCHAN 7:0 CHANNELn[7:0] SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 697 Offset Name Bit Pos. 15:8 23:16 31:24 0x01DC NSCHKCHAN 7:0 CHANNELn[7:0] 15:8 23:16 31:24 0x01E0 NONSECUSER0 7:0 USERn[7:0] 15:8 USERn[15:8] 23:16 USERn[22:16] 31:24 0x01E4 NONSECUSER1 7:0 USERn[7:0] 15:8 USERn[15:8] 23:16 USERn[22:16] 31:24 0x01E8 ... 0x01EF Reserved 0x01F0 NSCHKUSER0 7:0 USERn[7:0] 15:8 USERn[15:8] 23:16 USERn[22:16] 31:24 0x01F4 NSCHKUSER1 7:0 USERn[7:0] 15:8 USERn[15:8] 23:16 USERn[22:16] 31:24 33.7 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16-, and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. Refer to Register Access Protection and PAC - Peripheral Access Controller. On SAM L11 devices, the Mix-Secure peripheral has different types of registers (Non-Secure, Secure, Write-Secure, Mix-Secure, and Write-Mix-Secure) with different access permissions for each bitfield. Refer to Mix-Secure Peripherals for more details. In the following register descriptions, the access permissions are specified as shown in the following figure. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 698 Bit 7 6 5 4 3 2 1 0 CMD[7:0] Access R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW R/-/RW TrustZone Non-Protected Devices Access TrustZone Protected Devices Non-Secure Access TrustZone Protected Devices Secure Access Related Links 15. PAC - Peripheral Access Controller 33.4.8 Register Access Protection SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 699 33.7.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00 Property:  PAC Write-Protection , Secure Bit 7 6 5 4 3 2 1 0 SWRST Access W/-/W Reset 0 Bit 0 – SWRST Software Reset Writing '0' to this bit has no effect. Writing '1' to this bit resets all registers in the EVSYS to their initial state. Note:  Before applying a Software Reset it is recommended to disable the event generators. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 700 33.7.2 Software Event Name:  SWEVT Offset:  0x04 Reset:  0x00000000 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, write accesses (W*) are allowed only if the security attribution for the corresponding channel (CHANNELx) is set as Non-Secured in the NONSECCHAN register. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 CHANNEL[7:0] Access W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W W/W*/W Reset 0 0 0 0 0 0 0 0 Bits 7:0 – CHANNEL[7:0] Channel x Software Selection Writing a '0' to this bit has no effect. Writing a '1' to this bit will trigger a software event for channel x. These bits always return '0' when read. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 701 33.7.3 Priority Control Name:  PRICTRL Offset:  0x08 Reset:  0x00 Property:  PAC Write-Protection, Secure Bit 7 6 5 4 3 2 1 0 RREN PRI[1:0] Access RW/RW/RW RW/-/RW RW/-/RW Reset 0 0 0 Bit 7 – RREN Round-Robin Scheduling Enable For details on scheduling schemes, refer to Interrupt Status and Interrupts Arbitration Value Description 0 Static scheduling scheme for channels with level priority 1 Round-robin scheduling scheme for channels with level priority Bits 1:0 – PRI[1:0] Channel Priority Number When round-robin arbitration is enabled (PRICTRL.RREN=1) for priority level, this register holds the channel number of the last EVSYS channel being granted access as the active channel with priority level. The value of this bit group is updated each time the INTPEND or any of CHINTFLAG registers are written. When static arbitration is enabled (PRICTRL.RREN=0) for priority level, and the value of this bit group is nonzero, it will not affect the static priority scheme. This bit group is not reset when round-robin scheduling gets disabled (PRICTRL.RREN written to zero). SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 702 33.7.4 Channel Pending Interrupt Name:  INTPEND Offset:  0x10 Reset:  0x4000 Property:  Secure An interrupt that handles several channels should consult the INTPEND register to find out which channel number has priority (ignoring/filtering each channel that has its own interrupt line). An interrupt dedicated to only one channel must not use the INTPEND register. Bit 15 14 13 12 11 10 9 8 BUSY READY EVD OVR Access R/-/R R/-/R RW/-/RW RW/-/RW Reset 0 1 0 0 Bit 7 6 5 4 3 2 1 0 ID[1:0] Access RW/-/RW RW/-/RW Reset 0 0 Bit 15 – BUSY Busy This bit is read '1' when the event on a channel selected by Channel ID field (ID) has not been handled by all the event users connected to this channel. Bit 14 – READY Ready This bit is read '1' when all event users connected to the channel selected by Channel ID field (ID) are ready to handle incoming events on this channel. Bit 9 – EVD Channel Event Detected This flag is set on the next CLK_EVSYS_APB cycle when an event is being propagated through the channel, and an interrupt request will be generated if CHINTENCLR/SET.EVD is '1'. When the event channel path is asynchronous, the EVD bit will not be set. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear it. It will also clear the corresponding flag in the Channel n Interrupt Flag Status and Clear register (CHINTFLAGn) of this peripheral, where n is determined by the Channel ID bit field (ID) in this register. Bit 8 – OVR Channel Overrun This flag is set on the next CLK_EVSYS cycle after an overrun channel condition occurs, and an interrupt request will be generated if CHINTENCLR/SET.OVRx is '1'. There are two possible overrun channel conditions: • One or more of the event users on channel selected by Channel ID field (ID) are not ready when a new event occurs • An event happens when the previous event on channel selected by Channel ID field (ID) has not yet been handled by all event users SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 703 When the event channel path is asynchronous, the OVR interrupt flag will not be set. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear it. It will also clear the corresponding flag in the Channel n Interrupt Flag Status and Clear register (CHINTFLAGn) of this peripheral, where n is determined by the Channel ID bit field (ID) in this register. Bits 1:0 – ID[1:0] Channel ID These bits store the channel number of the highest priority. When the bits are written, indirect access to the corresponding Channel Interrupt Flag register is enabled. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 704 33.7.5 Interrupt Status Name:  INTSTATUS Offset:  0x14 Reset:  0x00000000 Property:  Mix-Secure Important:  For SAM L11 Non-Secure accesses, read accesses (R*) are allowed only if the security attribution for the corresponding channel (CHANNELx) is set as Non-Secured in the NONSECCHAN register. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 CHINT3 CHINT2 CHINT1 CHINT0 Access R/R*/R R/R*/R R/R*/R R/R*/R Reset 0 0 0 0 Bits 0, 1, 2, 3 – CHINT Channel x Pending Interrupt This bit is set when Channel x has a pending interrupt. This bit is cleared when the corresponding Channel x interrupts are disabled, or the source interrupt sources are cleared. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 705 33.7.6 Busy Channels Name:  BUSYCH Offset:  0x18 Reset:  0x00000000 Property:  Mix-Secure Important:  For SAM L11 Non-Secure accesses, read accesses (R*) are allowed only if the security attribution for the corresponding channel (CHANNELx) is set as Non-Secured in the NONSECCHAN register. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 BUSYCHx3 BUSYCHx2 BUSYCHx1 BUSYCHx0 Access R/R*/R R/R*/R R/R*/R R/R*/R Reset 0 0 0 0 Bits 0, 1, 2, 3 – BUSYCHx Busy Channel x This bit is set if an event occurs on channel x has not been handled by all event users connected to channel x. This bit is cleared when channel x is idle. When the event channel x path is asynchronous, this bit is always read '0'. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 706 33.7.7 Ready Users Name:  READYUSR Offset:  0x1C Reset:  0x0000000F Property:  Mix-Secure Important:  For SAM L11 Non-Secure accesses, read accesses (R*) are allowed only if the security attribution for the corresponding channel (CHANNELx) is set as Non-Secured in the NONSECCHAN register. Bit 31 30 29 28 27 26 25 24 Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 READYUSR3 READYUSR2 READYUSR1 READYUSR0 Access R R R R R/R*/R R/R*/R R/R*/R R/R*/R Reset 0 0 0 0 1 1 1 1 Bits 0, 1, 2, 3 – READYUSR Ready User for Channel n This bit is set when all event users connected to channel n are ready to handle incoming events on channel n. This bit is cleared when at least one of the event users connected to the channel is not ready. When the event channel n path is asynchronous, this bit is always read zero. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 707 33.7.8 Channel n Control Name:  CHANNEL Offset:  0x20 + n*0x08 [n=0..7] Reset:  0x00008000 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the security attribution for the corresponding channel (CHANNELx) is set as NonSecured in the NONSECCHAN register. This register allows the user to configure channel n. To write to this register, do a single, 32-bit write of all the configuration data. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 ONDEMAND RUNSTDBY EDGSEL[1:0] PATH[1:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 1 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 EVGEN[5:0] Access RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW RW/RW*/RW Reset 0 0 0 0 0 0 Bit 15 – ONDEMAND Generic Clock On Demand Value Description 0 Generic clock for a channel is always on, if the channel is configured and generic clock source is enabled. 1 Generic clock is requested on demand while an event is handled Bit 14 – RUNSTDBY Run in Standby This bit is used to define the behavior during standby sleep mode. Value Description 0 The channel is disabled in standby sleep mode. 1 The channel is not stopped in standby sleep mode and depends on the CHANNEL.ONDEMAND bit. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 708 Bits 11:10 – EDGSEL[1:0] Edge Detection Selection These bits set the type of edge detection to be used on the channel. These bits must be written to zero when using the asynchronous path. Value Name Description 0x0 NO_EVT_OUTPUT No event output when using the resynchronized or synchronous path 0x1 RISING_EDGE Event detection only on the rising edge of the signal from the event generator 0x2 FALLING_EDGE Event detection only on the falling edge of the signal from the event generator 0x3 BOTH_EDGES Event detection on rising and falling edges of the signal from the event generator Bits 9:8 – PATH[1:0] Path Selection These bits are used to choose which path will be used by the selected channel. Note:  The path choice can be limited by the channel source, see the table in 33.7.13 USERm. Important:  Only EVSYS channel 0 to 3 can be configured as synchronous or resynchronized. Value Name Description 0x0 SYNCHRONOUS Synchronous path 0x1 RESYNCHRONIZED Resynchronized path 0x2 ASYNCHRONOUS Asynchronous path Other - Reserved Bits 5:0 – EVGEN[5:0] Event Generator Selection These bits are used to choose the event generator to connect to the selected channel. Table 33-2. Event Generators Value Event Generator Description 0x00 NONE No event generator selected 0x01 OSCCTRL_XOSC_FAIL XOSC fail detection 0x02 OSC32KCTRL_XOSC32K_FAIL XOSC32K fail detection 0x03 SUPC_BOD33DET SUPC BOD33 detection 0x04-0x0B RTC_PER RTC period 0x0C-0x0D RTC_CMP RTC comparison 0x0E RTC_TAMPER RTC tamper detection 0x0F RTC_OVF RTC overflow 0x10 RTC_PERD RTC periodic interval daily 0x11-0x18 EIC_EXTINT EIC external interrupt SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 709 Value Event Generator Description 0x19-0x1C DMAC_CH DMAC channel 0x1D TC0_OVF TC0 overflow 0x1E-0x1F TC0_MCX TC0 match/compare 0x20 TC1_OVF TC1 overflow 0x21-0x22 TC1_MCX TC1 match/compare 0x23 TC2_OVF TC2 overflow 0x24-0x25 TC2_MCX TC2 match/compare 0x26 ADC_RESRDY ADC resolution ready 0x27 ADC_WINMON ADC window monitor 0x28-0x29 AC_COMP AC comparator 0x2A AC_WIN AC window 0x2B DAC_EMPTY DAC empty 0x2C PTC_EOC PTC end of conversion 0x2D PTC_WCOMP PTC window comparator 0x2E TRNG_READY Data ready 0x2F-0x30 CCL_LUTOUT CCL output 0x31 PAC_ERR PAC access error SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 710 33.7.9 Channel n Interrupt Enable Clear Name:  CHINTENCLR Offset:  0x24 + n*0x08 [n=0..7] Reset:  0x00 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the security attribution for the corresponding channel (CHANNELx) is set as NonSecured in the NONSECCHAN register. Bit 7 6 5 4 3 2 1 0 EVD OVR Access RW/RW*/RW RW/RW*/RW Reset 0 0 Bit 1 – EVD Channel Event Detected Interrupt Disable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Event Detected Channel Interrupt Enable bit, which disables the Event Detected Channel interrupt. Value Description 0 The Event Detected Channel interrupt is disabled. 1 The Event Detected Channel interrupt is enabled. Bit 0 – OVR Channel Overrun Interrupt Disable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Overrun Channel Interrupt Enable bit, which disables the Overrun Channel interrupt. Value Description 0 The Overrun Channel interrupt is disabled. 1 The Overrun Channel interrupt is enabled. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 711 33.7.10 Channel n Interrupt Enable Set Name:  CHINTENSET Offset:  0x25 + n*0x08 [n=0..7] Reset:  0x00 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the security attribution for the corresponding channel (CHANNELx) is set as NonSecured in the NONSECCHAN register. Bit 7 6 5 4 3 2 1 0 EVD OVR Access RW/RW*/RW RW/RW*/RW Reset 0 0 Bit 1 – EVD Channel Event Detected Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Event Detected Channel Interrupt Enable bit, which enables the Event Detected Channel interrupt. Value Description 0 The Event Detected Channel interrupt is disabled. 1 The Event Detected Channel interrupt is enabled. Bit 0 – OVR Channel Overrun Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Overrun Channel Interrupt Enable bit, which enables the Overrun Channel interrupt. Value Description 0 The Overrun Channel interrupt is disabled. 1 The Overrun Channel interrupt is enabled. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 712 33.7.11 Channel n Interrupt Flag Status and Clear Name:  CHINTFLAG Offset:  0x26 + n*0x08 [n=0..7] Reset:  0x00 Property:  Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the security attribution for the corresponding channel (CHANNELx) is set as NonSecured in the NONSECCHAN register. Bit 7 6 5 4 3 2 1 0 EVD OVR Access RW/RW*/RW RW/RW*/RW Reset 0 0 Bit 1 – EVD Channel Event Detected This flag is set on the next CLK_EVSYS_APB cycle when an event is being propagated through the channel, and an interrupt request will be generated if CHINTENCLR/SET.EVD is '1'. When the event channel path is asynchronous, the EVD interrupt flag will not be set. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Event Detected Channel interrupt flag. Bit 0 – OVR Channel Overrun This flag is set on the next CLK_EVSYS cycle after an overrun channel condition occurs, and an interrupt request will be generated if CHINTENCLR/SET.OVRx is '1'. There are two possible overrun channel conditions: • One or more of the event users on the channel are not ready when a new event occurs. • An event happens when the previous event on channel has not yet been handled by all event users. When the event channel path is asynchronous, the OVR interrupt flag will not be set. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Overrun Channel interrupt flag. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 713 33.7.12 Channel n Status Name:  CHSTATUSn Offset:  0x27 + n*0x08 [n=0..7] Reset:  0x01 Property:  Mix-Secure Important:  For SAM L11 Non-Secure accesses, read accesses (R*) are allowed only if the security attribution for the corresponding channel (CHANNELx) is set as Non-Secured in the NONSECCHAN register. Bit 7 6 5 4 3 2 1 0 BUSYCH RDYUSR Access R/R*/R R/R*/R Reset 0 0 Bit 1 – BUSYCH Busy Channel This bit is cleared when channel is idle. This bit is set if an event on channel has not been handled by all event users connected to channel. When the event channel path is asynchronous, this bit is always read '0'. Bit 0 – RDYUSR Ready User This bit is cleared when at least one of the event users connected to the channel is not ready. This bit is set when all event users connected to channel are ready to handle incoming events on the channel. When the event channel path is asynchronous, this bit is always read zero. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 714 33.7.13 Event User m Name:  USERm Offset:  0x0120 + m*0x01 [m=0..22] Reset:  0x0 Property:  PAC Write-Protection, Mix-Secure Important:  For SAM L11 Non-Secure accesses, read and write accesses (RW*) are allowed only if the security attribution for the corresponding event user (USERx) is set as Non-Secured in the NONSECUSER register. Bit 7 6 5 4 3 2 1 0 CHANNEL[3:0] Access R/W/RW*/RW R/W/RW*/RW R/W/RW*/RW R/W/RW*/RW Reset 0 0 0 0 Bits 3:0 – CHANNEL[3:0] Channel Event Selection These bits select channel n to connect to the event user m. Note:  A value x of this bit field selects channel n = x-1. Table 33-3. User Multiplexer Number m USERm User Multiplexer Description Path Type m=0 OSCCTRL_TUNE DFLLULP Tune A m=1 RTC_TAMPER RTC Tamper A m=2 NWMCTRL_PAGEW NVMCTRL Auto-Write A,S,R m=3..6 PORT_EV[0..3] Port Event 0..3 A m=7..10 DMAC_CH[0..3] Channel 0...3 S,R m=11 TC0_EVU TC0 EVU A,S,R m=12 TC1_EVU TC1 EVU A,S,R m=13 TC2_EVU TC2 EVU A,S,R m=14 ADC_START ADC Start Conversion A,S,R m=15 ADC_SYNC Flush ADC A,S,R m=16..17 AC_COMP[0..1] Start Comparator 0..1 A m=18 DAC_START DAC Start Conversion A m=19 PTC_STCONV PTC Start Conversion A,S,R m=20 PTC_DSEQR PTC Sequencing A,S,R m=21..22 CCL_LUTIN[0..1] CCL Input 0..1 A 1) A = Asynchronous path, S = Synchronous path, R = Resynchronized path SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 715 Value Description 0x00 No channel selected 0x01 Channel 0 selected 0x02 Channel 1 selected 0x03 Channel 2 selected 0x04 Channel 3 selected 0x05 Channel 4 selected 0x06 Channel 5 selected 0x07 Channel 6 selected 0x08 Channel 7 selected SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 716 33.7.14 Interrupt Enable Clear Name:  INTENCLR Offset:  0x1D4 Reset:  0x0 Property:  PAC Write-Protection Important:  This register is only available for SAM L11 and has no effect for SAM L10. Bit 7 6 5 4 3 2 1 0 NSCHK Access RW/RW/RW Reset 0 Bit 0 – NSCHK Non-Secure Check Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Non-Secure Check Interrupt Enable bit, which disables the Non-Secure Check interrupt. Value Description 0 The Non-Secure Check interrupt is disabled. 1 The Non-Secure Check interrupt is enabled. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 717 33.7.15 Interrupt Enable Set Name:  INTENSET Offset:  0x1D5 Reset:  0x0 Property:  PAC Write-Protection Important:  This register is only available for SAM L11 and has no effect for SAM L10. Bit 7 6 5 4 3 2 1 0 NSCHK Access RW/RW/RW Reset 0 Bit 0 – NSCHK Non-Secure Check Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Non-Secure Check Interrupt Enable bit, which disables the Non-Secure Check interrupt. Value Description 0 The Non-Secure Check interrupt is disabled. 1 The Non-Secure Check interrupt is enabled. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 718 33.7.16 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x1D6 Reset:  0x0 Property:  - Important:  This register is only available for SAM L11 and has no effect for SAM L10. Bit 7 6 5 4 3 2 1 0 NSCHK Access RW/RW/RW Reset 0 Bit 0 – NSCHK Non-Secure Check This flag is set when a bit in NSCHKCHAN is 1 and the corresponding bit in NONSECCHAN is cleared, or when a bit in NSCHKCHAN is 0 and the corresponding bit in NONSECCHAN is set, or when a bit in NSCHKUSER is 1 and the corresponding bit in NONSECUSER is cleared, or when a bit in NSCHKUSER is 0 and the corresponding bit in NONSECUSER is set. Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Non-Secure Check interrupt flag. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 719 33.7.17 Channel Security Attribution Name:  NONSECCHAN Offset:  0x1D8 Reset:  0x00000000 Property:  PAC Write-Protection, Write-Secure This register allows the user to configure one or more channels as secured or non-secured. Important:  This register is only available for SAM L11 and has no effect for SAM L10. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 CHANNELn[7:0] Access RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW Reset 0 0 0 0 0 0 0 0 Bits 7:0 – CHANNELn[7:0] Channel n Security Attribution [n=7..0]The bit n of CHANNEL enables the non-secure mode of CHANNELn. The registers whose CHANNEL bit or bitfield n is set in non-secure mode by NONSECCHAN.CHANNELn are CHANNELn, CHINTENCLRn, CHINTENSETn, CHINTFLAGn and CHSTATUSx registers. These bits set the security attribution for the individual channels. Value Description 0 The corresponding channel is secured. When the module is PAC secured, the configuration and status bits for this channel are only available through the secure alias. Attempts to change the channel configuration through the non-secure alias will be silently ignored and reads will return 0. 1 The corresponding channel is non-secured. The configuration and status bits for this channel are available through the non-secure alias. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 720 33.7.18 Channel Security Attribution Check Name:  NSCHKCHAN Offset:  0x1DC Reset:  0x00000000 Property:  PAC Write-Protection This register allows the user to select one or more channels to check their security attribution as nonsecured. Important:  This register is only available for SAM L11 and has no effect for SAM L10. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 CHANNELn[7:0] Access RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW Reset 0 0 0 0 0 0 0 0 Bits 7:0 – CHANNELn[7:0] Channel n Selection [n=7..0] These bits selects the individual channels for security attribution check. If any channel selected in NSCHKCHAN has the corresponding bit in NONSECCHAN set to the opposite value, then the NSCHK interrupt flag will be set. Value Description 0 0-to-1 transition will be detected on corresponding NONSECCHAN bit. 1 1-to-0 transition will be detected on corresponding NONSECCHAN bit. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 721 33.7.19 Event User Security Attribution Name:  NONSECUSERm Offset:  0x01E0 + m*0x04 [m=0..1] Reset:  0x00000000 Property:  PAC Write-Protection, Write-Secure This register allows the user to configure one or more event users as secured or non-secured. Important:  This register is only available for SAM L11 and has no effect for SAM L10. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 USERn[22:16] Access RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW Reset 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 USERn[15:8] Access RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 USERn[7:0] Access RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW RW/R/RW Reset 0 0 0 0 0 0 0 0 Bits 22:0 – USERn[22:0] Event User n Security Attribution [n=22..0]The bit n of USER enables the nonsecure mode of USERn. The registers whose USER bit or bitfield n is set in non-secure mode by NONSECUSER.USERn are USERn registers. These bits set the security attribution for the individual event users. Value Description 0 The corresponding event user is secured. When the module is PAC secured, the configuration and status bits for this event user are only available through the secure alias. Attempts to change the event user configuration through the non-secure alias will be silently ignored and reads will return 0. 1 The corresponding event user is non-secured. The configuration and status bits for this event user are available through the non-secure alias. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 722 33.7.20 Event User Security Attribution Check Name:  NSCHKUSERm Offset:  0x01F0 + m*0x04 [m=0..1] Reset:  0x00000000 Property:  PAC Write-Protection This register allows the user to select one or more event users to check their security attribution as nonsecured. Important:  This register is only available for SAM L11 and has no effect for SAM L10. Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 USERn[22:16] Access RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW Reset 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 USERn[15:8] Access RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 USERn[7:0] Access RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW RW/RW/RW Reset 0 0 0 0 0 0 0 0 Bits 22:0 – USERn[22:0] Event User n Selection [n=22..0] These bits selects the individual event users for security attribution check. If any event user selected in NSCHKUSER has the corresponding bit in NONSECUSER set to the opposite value, then the NSCHK interrupt flag will be set. Value Description 0 0-to-1 transition will be detected on corresponding NONSECUSER bit. 1 1-to-0 transition will be detected on corresponding NONSECUSER bit. SAM L10/L11 Family EVSYS – Event System © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 723 34. SERCOM – Serial Communication Interface 34.1 Overview There are up to three instances of the serial communication interface (SERCOM) peripheral. A SERCOM can be configured to support a number of modes: I2C, SPI, and USART. When an instance of SERCOM is configured and enabled, all of the resources of that SERCOM instance will be dedicated to the selected mode. The SERCOM serial engine consists of a transmitter and receiver, baud-rate generator and address matching functionality. It can use the internal generic clock or an external clock. Using an external clock allows the SERCOM to be operated in all Sleep modes. Related Links 35. SERCOM USART - SERCOM Synchronous and Asynchronous Receiver and Transmitter 36. SERCOM SPI – SERCOM Serial Peripheral Interface 37. SERCOM I2C – SERCOM Inter-Integrated Circuit 34.2 Features • Interface for configuring into one of the following: – Inter-Integrated Circuit (I2C) Two-wire Serial Interface – System Management Bus (SMBus™) compatible – Serial Peripheral Interface (SPI) – Universal Synchronous/Asynchronous Receiver/Transmitter (USART) • Single transmit buffer and double receive buffer • Baud-rate generator • Address match/mask logic • Operational in all Sleep modes with an external clock source • Can be used with DMA See the Related Links for full feature lists of the interface configurations. Related Links 35. SERCOM USART - SERCOM Synchronous and Asynchronous Receiver and Transmitter 36. SERCOM SPI – SERCOM Serial Peripheral Interface 37. SERCOM I2C – SERCOM Inter-Integrated Circuit SAM L10/L11 Family SERCOM – Serial Communication Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 724 34.3 Block Diagram Figure 34-1. SERCOM Block Diagram CONTROL/STATUS TX/RX DATA Mode n SERCOM BAUD/ADDR Transmitter Register Interface Serial Engine Receiver Mode 0 Mode 1 Baud Rate Generator Address Match Mode Specific PAD[3:0] 34.4 Signal Description See the respective SERCOM mode chapters for details. Related Links 35. SERCOM USART - SERCOM Synchronous and Asynchronous Receiver and Transmitter 36. SERCOM SPI – SERCOM Serial Peripheral Interface 37. SERCOM I2C – SERCOM Inter-Integrated Circuit 34.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 34.5.1 I/O Lines Using the SERCOM I/O lines requires the I/O pins to be configured using port configuration (PORT). The SERCOM has four internal pads, PAD[3:0], and the signals from I2C, SPI and USART are routed through these SERCOM pads via a multiplexer. The configuration of the multiplexer is available from the different SERCOM modes. Refer to the mode specific chapters for details. Related Links 35. SERCOM USART - SERCOM Synchronous and Asynchronous Receiver and Transmitter 36. SERCOM SPI – SERCOM Serial Peripheral Interface 37. SERCOM I2C – SERCOM Inter-Integrated Circuit 32. PORT - I/O Pin Controller 35.3 Block Diagram 34.5.2 Power Management The SERCOM can operate in any Sleep mode provided the selected clock source is running. SERCOM interrupts can be configured to wake the device from Sleep modes. SAM L10/L11 Family SERCOM – Serial Communication Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 725 Related Links 22. PM – Power Manager 34.5.3 Clocks The SERCOM bus clock (CLK_SERCOMx_APB) can be enabled and disabled in the Main Clock Controller. Refer to Peripheral Clock Masking for details and default status of this clock. The SERCOM uses two generic clocks: GCLK_SERCOMx_CORE and GCLK_SERCOMx_SLOW. The core clock (GCLK_SERCOMx_CORE) is required to clock the SERCOM while working as a master. The slow clock (GCLK_SERCOMx_SLOW) is only required for certain functions. See specific mode chapters for details. These clocks must be configured and enabled in the Generic Clock Controller (GCLK) before using the SERCOM. The generic clocks are asynchronous to the user interface clock (CLK_SERCOMx_APB). Due to this asynchronicity, writing to certain registers will require synchronization between the clock domains. Refer to 34.6.8 Synchronization for details. Related Links 18. GCLK - Generic Clock Controller 19. MCLK – Main Clock 34.5.4 DMA The DMA request lines are connected to the DMA Controller (DMAC). The DMAC must be configured before the SERCOM DMA requests are used. Related Links 28. DMAC – Direct Memory Access Controller 34.5.5 Interrupts The interrupt request line is connected to the Interrupt Controller (NVIC). The NVIC must be configured before the SERCOM interrupts are used. 34.5.6 Events Not applicable. 34.5.7 Debug Operation When the CPU is halted in debug mode, this peripheral will continue normal operation. If the peripheral is configured to require periodical service by the CPU through interrupts or similar, improper operation or data loss may result during debugging. This peripheral can be forced to halt operation during debugging - refer to the Debug Control (DBGCTRL) register for details. 34.5.8 Register Access Protection All registers with write-access can be write-protected optionally by the Peripheral Access Controller (PAC), except for the following registers: • Interrupt Flag Clear and Status register (INTFLAG) • Status register (STATUS) • Data register (DATA) • Address register (ADDR) SAM L10/L11 Family SERCOM – Serial Communication Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 726 Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. PAC write-protection does not apply to accesses through an external debugger. Related Links 15. PAC - Peripheral Access Controller 34.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 34.5.10 Analog Connections Not applicable. 34.6 Functional Description 34.6.1 Principle of Operation The basic structure of the SERCOM serial engine is shown in Figure 34-2. Labels in capital letters are synchronous to the system clock and accessible by the CPU; labels in lowercase letters can be configured to run on the GCLK_SERCOMx_CORE clock or an external clock. Figure 34-2. SERCOM Serial Engine Transmitter Baud Rate Generator Equal Selectable Internal Clk (GCLK) Ext Clk Receiver Address Match Baud Rate Generator TX Shift Register RX Shift Register Status RX Buffer BAUD TX DATA ADDR/ADDRMASK STATUS RX DATA 1/- /2- /16 The transmitter consists of a single write buffer and a shift register. SAM L10/L11 Family SERCOM – Serial Communication Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 727 The receiver consists of a one-level (I2C), two-level or four-level (USART, SPI) receive buffer and a shift register. The baud-rate generator is capable of running on the GCLK_SERCOMx_CORE clock or an external clock. Address matching logic is included for SPI and I2C operation. 34.6.2 Basic Operation 34.6.2.1 Initialization The SERCOM must be configured to the desired mode by writing the Operating Mode bits in the Control A register (CTRLA.MODE). Refer to table SERCOM Modes for details. Table 34-1. SERCOM Modes CTRLA.MODE Description 0x0 USART with external clock 0x1 USART with internal clock 0x2 SPI in slave operation 0x3 SPI in master operation 0x4 I 2C slave operation 0x5 I 2C master operation 0x6-0x7 Reserved For further initialization information, see the respective SERCOM mode chapters: Related Links 35. SERCOM USART - SERCOM Synchronous and Asynchronous Receiver and Transmitter 36. SERCOM SPI – SERCOM Serial Peripheral Interface 37. SERCOM I2C – SERCOM Inter-Integrated Circuit 34.6.2.2 Enabling, Disabling, and Resetting This peripheral is enabled by writing '1' to the Enable bit in the Control A register (CTRLA.ENABLE), and disabled by writing '0' to it. Writing ‘1’ to the Software Reset bit in the Control A register (CTRLA.SWRST) will reset all registers of this peripheral to their initial states, except the DBGCTRL register, and the peripheral is disabled. Refer to the CTRLA register description for details. 34.6.2.3 Clock Generation – Baud-Rate Generator The baud-rate generator, as shown in Figure 34-3, generates internal clocks for asynchronous and synchronous communication. The output frequency (fBAUD) is determined by the Baud register (BAUD) setting and the baud reference frequency (fref). The baud reference clock is the serial engine clock, and it can be internal or external. For asynchronous communication, the /16 (divide-by-16) output is used when transmitting, whereas the /1 (divide-by-1) output is used while receiving. For synchronous communication, the /2 (divide-by-2) output is used. SAM L10/L11 Family SERCOM – Serial Communication Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 728 This functionality is automatically configured, depending on the selected operating mode. Figure 34-3. Baud Rate Generator Base Period Selectable Internal Clk (GCLK) Ext Clk CTRLA.MODE[0] 0 1 0 1 0 1 0 1 fref Clock Recovery Tx Clk Rx Clk CTRLA.MODE /2 /8 /1 /2 /16 Baud Rate Generator Table 34-2 contains equations for the baud rate (in bits per second) and the BAUD register value for each operating mode. For asynchronous operation, there is one mode: arithmetic mode, the BAUD register value is 16 bits (0 to 65,535). For synchronous operation, the BAUD register value is 8 bits (0 to 255). Table 34-2. Baud Rate Equations Operating Mode Condition Baud Rate (Bits Per Second) BAUD Register Value Calculation Asynchronous ≥ ܦܷܣܤ݂ Arithmetic ݂݁ݎ݂ = ܦܷܣܤ݂ 16 ݂݁ݎ݂ 16 1 െ ܦܷܣܤ 65536 ܣܤܷܦ = 65536 ڄ 1 െ 16 ڄ ܦܷܣܤ݂ ݂݁ݎ݂ Asynchronous ≥ ܦܷܣܤ݂ Fractional ݂݁ݎ݂ S = ܦܷܣܤ݂ ݂݁ݎ݂ + ܦܷܣܤ ڄ S ܲܨ 8 = ܦܷܣܤ ݂݁ݎ݂ ܦܷܣܤ݂ ڄ ܵ െ ܲܨ 8 ≥ ܦܷܣܤ݂ Synchronous ݂݁ݎ݂ 2 = ܦܷܣܤ݂ ݂݁ݎ݂ = ܦܷܣܤ 1 + ܦܷܣܤ ڄ 2 ݂݁ݎ݂ ܦܷܣܤ݂ ڄ 2 െ 1 S - Number of samples per bit, which can be 16, 8, or 3. The Asynchronous Fractional option is used for auto-baud detection. The baud rate error is represented by the following formula: Error = 1 െ ExpectedBaudRate ActualBaudRate 34.6.2.3.1 Asynchronous Arithmetic Mode BAUD Value Selection The formula given for fBAUD calculates the average frequency over 65536 fref cycles. Although the BAUD register can be set to any value between 0 and 65536, the actual average frequency of fBAUD over a single frame is more granular. The BAUD register values that will affect the average frequency over a single frame lead to an integer increase in the cycles per frame (CPF) = ܨܲܥ ݂݁ݎ݂ ܦܷܣܤ݂ ܵ + ܦ SAM L10/L11 Family SERCOM – Serial Communication Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 729 where • D represent the data bits per frame • S represent the sum of start and first stop bits, if present. Table 34-3 shows the BAUD register value versus baud frequency fBAUD at a serial engine frequency of 48MHz. This assumes a D value of 8 bits and an S value of 2 bits (10 bits, including start and stop bits). Table 34-3. BAUD Register Value vs. Baud Frequency BAUD Register Value Serial Engine CPF fBAUD at 48MHz Serial Engine Frequency (fREF) 0 – 406 160 3MHz 407 – 808 161 2.981MHz 809 – 1205 162 2.963MHz ... ... ... 65206 31775 15.11kHz 65207 31871 15.06kHz 65208 31969 15.01kHz 34.6.3 Additional Features 34.6.3.1 Address Match and Mask The SERCOM address match and mask feature is capable of matching either one address, two unique addresses, or a range of addresses with a mask, based on the mode selected. The match uses seven or eight bits, depending on the mode. 34.6.3.1.1 Address With Mask An address written to the Address bits in the Address register (ADDR.ADDR), and a mask written to the Address Mask bits in the Address register (ADDR.ADDRMASK) will yield an address match. All bits that are masked are not included in the match. Note that writing the ADDR.ADDRMASK to 'all zeros' will match a single unique address, while writing ADDR.ADDRMASK to 'all ones' will result in all addresses being accepted. Figure 34-4. Address With Mask rx shift register ADDRMASK ADDR == Match 34.6.3.1.2 Two Unique Addresses The two addresses written to ADDR and ADDRMASK will cause a match. SAM L10/L11 Family SERCOM – Serial Communication Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 730 Figure 34-5. Two Unique Addresses ADDRMASK rx shift register ADDR == Match == 34.6.3.1.3 Address Range The range of addresses between and including ADDR.ADDR and ADDR.ADDRMASK will cause a match. ADDR.ADDR and ADDR.ADDRMASK can be set to any two addresses, with ADDR.ADDR acting as the upper limit and ADDR.ADDRMASK acting as the lower limit. Figure 34-6. Address Range ADDRMASK rx shift register ADDR == Match 34.6.4 DMA Operation The available DMA interrupts and their depend on the operation mode of the SERCOM peripheral. Refer to the Functional Description sections of the respective SERCOM mode. Related Links 35. SERCOM USART - SERCOM Synchronous and Asynchronous Receiver and Transmitter 36. SERCOM SPI – SERCOM Serial Peripheral Interface 37. SERCOM I2C – SERCOM Inter-Integrated Circuit 34.6.5 Interrupts Interrupt sources are mode-specific. See the respective SERCOM mode chapters for details. Each interrupt source has its own interrupt flag. The interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG) will be set when the interrupt condition is met. Each interrupt can be individually enabled by writing '1' to the corresponding bit in the Interrupt Enable Set register (INTENSET), and disabled by writing '1' to the corresponding bit in the Interrupt Enable Clear register (INTENCLR). An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until either the interrupt flag is cleared, the interrupt is disabled, or the SERCOM is reset. For details on clearing interrupt flags, refer to the INTFLAG register description. The value of INTFLAG indicates which interrupt condition occurred. The user must read the INTFLAG register to determine which interrupt condition is present. Note:  Interrupts must be globally enabled for interrupt requests. 34.6.6 Events Not applicable. SAM L10/L11 Family SERCOM – Serial Communication Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 731 34.6.7 Sleep Mode Operation The peripheral can operate in any sleep mode where the selected serial clock is running. This clock can be external or generated by the internal baud-rate generator. The SERCOM interrupts can be used to wake up the device from sleep modes. Refer to the different SERCOM mode chapters for details. 34.6.8 Synchronization Due to asynchronicity between the main clock domain and the peripheral clock domains, some registers need to be synchronized when written or read. Required write-synchronization is denoted by the "Write-Synchronized" property in the register description. Required read-synchronization is denoted by the "Read-Synchronized" property in the register description. SAM L10/L11 Family SERCOM – Serial Communication Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 732 35. SERCOM USART - SERCOM Synchronous and Asynchronous Receiver and Transmitter 35.1 Overview The Universal Synchronous and Asynchronous Receiver and Transmitter (USART) is one of the available modes in the Serial Communication Interface (SERCOM). The USART uses the SERCOM transmitter and receiver, see 35.3 Block Diagram. Labels in uppercase letters are synchronous to CLK_SERCOMx_APB and accessible for CPU. Labels in lowercase letters can be programmed to run on the internal generic clock or an external clock. The transmitter consists of a single write buffer, a shift register, and control logic for different frame formats. The write buffer support data transmission without any delay between frames. The receiver consists of a two-level or four-level receive buffer and a shift register. Status information of the received data is available for error checking. Data and clock recovery units ensure robust synchronization and noise filtering during asynchronous data reception. Related Links 34. SERCOM – Serial Communication Interface 35.2 USART Features • Full-duplex operation • Asynchronous (with clock reconstruction) or synchronous operation • Internal or external clock source for asynchronous and synchronous operation • Baud-rate generator • Supports serial frames with 5, 6, 7, 8 or 9 data bits and 1 or 2 stop bits • Odd or even parity generation and parity check • Selectable LSB- or MSB-first data transfer • Buffer overflow and frame error detection • Noise filtering, including false start-bit detection and digital low-pass filter • Collision detection • Can operate in all sleep modes • Operation at speeds up to half the system clock for internally generated clocks • Operation at speeds up to the system clock for externally generated clocks • RTS and CTS flow control • IrDA modulation and demodulation up to 115.2kbps • LIN slave support – Auto-baud and break character detection • ISO 7816 T=0 or T=1 protocols for Smart Card interfacing • RS485 Support • Start-of-frame detection • Two- or Four-Level Receive Buffer • Can work with DMA SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 733 Related Links 34.2 Features 35.3 Block Diagram Figure 35-1. USART Block Diagram GCLK (internal) XCK BAUD Baud Rate Generator TX DATA TX Shift Register RX Shift Register STATUS Status RX DATA RX Buffer TxD RxD CTRLA.MODE /1 - /2 - /16 CTRLA.MODE 35.4 Signal Description Table 35-1. SERCOM USART Signals Signal Name Type Description PAD[3:0] Digital I/O General SERCOM pins One signal can be mapped to one of several pins. 35.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 35.5.1 I/O Lines Using the USART’s I/O lines requires the I/O pins to be configured using the I/O Pin Controller (PORT). When the SERCOM is used in USART mode, the SERCOM controls the direction and value of the I/O pins according to the table below. Both PORT control bits PINCFGn.PULLEN and PINCFGn.DRVSTR are still effective. If the receiver or transmitter is disabled, these pins can be used for other purposes. Table 35-2. USART Pin Configuration Pin Pin Configuration TxD Output RxD Input XCK Output or input SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 734 The combined configuration of PORT and the Transmit Data Pinout and Receive Data Pinout bit fields in the Control A register (CTRLA.TXPO and CTRLA.RXPO, respectively) will define the physical position of the USART signals in Table 35-2. Related Links 32. PORT - I/O Pin Controller 35.5.2 Power Management This peripheral can continue to operate in any sleep mode where its source clock is running. The interrupts can wake up the device from sleep modes. Related Links 22. PM – Power Manager 35.5.3 Clocks The SERCOM bus clock (CLK_SERCOMx_APB) can be enabled and disabled in the Main Clock Controller. Refer to Peripheral Clock Masking for details and default status of this clock. A generic clock (GCLK_SERCOMx_CORE) is required to clock the SERCOMx_CORE. This clock must be configured and enabled in the Generic Clock Controller before using the SERCOMx_CORE. Refer to GCLK - Generic Clock Controller for details. This generic clock is asynchronous to the bus clock (CLK_SERCOMx_APB). Therefore, writing to certain registers will require synchronization to the clock domains. Refer to Synchronization for further details. Related Links 19.6.2.6 Peripheral Clock Masking 35.6.6 Synchronization 18. GCLK - Generic Clock Controller 35.5.4 DMA The DMA request lines are connected to the DMA Controller (DMAC). In order to use DMA requests with this peripheral the DMAC must be configured first. Refer to DMAC – Direct Memory Access Controller for details. Related Links 28. DMAC – Direct Memory Access Controller 35.5.5 Interrupts The interrupt request line is connected to the Interrupt Controller. In order to use interrupt requests of this peripheral, the Interrupt Controller (NVIC) must be configured first. Refer to Nested Vector Interrupt Controller for details. 35.5.6 Events Not applicable. 35.5.7 Debug Operation When the CPU is halted in debug mode, this peripheral will continue normal operation. If the peripheral is configured to require periodical service by the CPU through interrupts or similar, improper operation or data loss may result during debugging. This peripheral can be forced to halt operation during debugging - refer to the Debug Control (DBGCTRL) register for details. Related Links SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 735 35.8.13 DBGCTRL 35.5.8 Register Access Protection Registers with write-access can be write-protected optionally by the peripheral access controller (PAC). PAC Write-Protection is not available for the following registers: • Interrupt Flag Clear and Status register (INTFLAG) • Status register (STATUS) • Data register (DATA) Optional PAC Write-Protection is denoted by the "PAC Write-Protection" property in each individual register description. Write-protection does not apply to accesses through an external debugger. Related Links 15. PAC - Peripheral Access Controller 35.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 35.5.10 Analog Connections Not applicable. 35.6 Functional Description 35.6.1 Principle of Operation The USART uses the following lines for data transfer: • RxD for receiving • TxD for transmitting • XCK for the transmission clock in synchronous operation USART data transfer is frame based. A serial frame consists of: • 1 start bit • From 5 to 9 data bits (MSB or LSB first) • No, even or odd parity bit • 1 or 2 stop bits A frame starts with the start bit followed by one character of data bits. If enabled, the parity bit is inserted after the data bits and before the first stop bit. After the stop bit(s) of a frame, either the next frame can SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 736 follow immediately, or the communication line can return to the idle (high) state. The figure below illustrates the possible frame formats. Brackets denote optional bits. Figure 35-2. Frame Formats Frame (IDLE) St 0 1 2 3 4 [5] [6] [7] [8] [P] Sp1 [Sp2] [St/IDL] St Start bit. Signal is always low. n, [n] Data bits. 0 to [5..9] [P] Parity bit. Either odd or even. Sp, [Sp] Stop bit. Signal is always high. IDLE No frame is transferred on the communication line. Signal is always high in this state. 35.6.2 Basic Operation 35.6.2.1 Initialization The following registers are enable-protected, meaning they can only be written when the USART is disabled (CTRL.ENABLE=0): • Control A register (CTRLA), except the Enable (ENABLE) and Software Reset (SWRST) bits. • Control B register (CTRLB), except the Receiver Enable (RXEN) and Transmitter Enable (TXEN) bits. • Baud register (BAUD) When the USART is enabled or is being enabled (CTRLA.ENABLE=1), any writing attempt to these registers will be discarded. If the peripheral is being disabled, writing to these registers will be executed after disabling is completed. Enable-protection is denoted by the "Enable-Protection" property in the register description. Before the USART is enabled, it must be configured by these steps: 1. Select either external (0x0) or internal clock (0x1) by writing the Operating Mode value in the CTRLA register (CTRLA.MODE). 2. Select either asynchronous (0) or or synchronous (1) communication mode by writing the Communication Mode bit in the CTRLA register (CTRLA.CMODE). 3. Select pin for receive data by writing the Receive Data Pinout value in the CTRLA register (CTRLA.RXPO). 4. Select pads for the transmitter and external clock by writing the Transmit Data Pinout bit in the CTRLA register (CTRLA.TXPO). 5. Configure the Character Size field in the CTRLB register (CTRLB.CHSIZE) for character size. 6. Set the Data Order bit in the CTRLA register (CTRLA.DORD) to determine MSB- or LSB-first data transmission. 7. To use parity mode: 7.1. Enable parity mode by writing 0x1 to the Frame Format field in the CTRLA register (CTRLA.FORM). SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 737 7.2. Configure the Parity Mode bit in the CTRLB register (CTRLB.PMODE) for even or odd parity. 8. Configure the number of stop bits in the Stop Bit Mode bit in the CTRLB register (CTRLB.SBMODE). 9. When using an internal clock, write the Baud register (BAUD) to generate the desired baud rate. 10. Enable the transmitter and receiver by writing '1' to the Receiver Enable and Transmitter Enable bits in the CTRLB register (CTRLB.RXEN and CTRLB.TXEN). 35.6.2.2 Enabling, Disabling, and Resetting This peripheral is enabled by writing '1' to the Enable bit in the Control A register (CTRLA.ENABLE), and disabled by writing '0' to it. Writing ‘1’ to the Software Reset bit in the Control A register (CTRLA.SWRST) will reset all registers of this peripheral to their initial states, except the DBGCTRL register, and the peripheral is disabled. Refer to the CTRLA register description for details. 35.6.2.3 Clock Generation and Selection For both synchronous and asynchronous modes, the clock used for shifting and sampling data can be generated internally by the SERCOM baud-rate generator or supplied externally through the XCK line. The synchronous mode is selected by writing a '1' to the Communication Mode bit in the Control A register (CTRLA.CMODE), the asynchronous mode is selected by writing a zero to CTRLA.CMODE. The internal clock source is selected by writing 0x1 to the Operation Mode bit field in the Control A register (CTRLA.MODE), the external clock source is selected by writing 0x0 to CTRLA.MODE. The SERCOM baud-rate generator is configured as in the figure below. In asynchronous mode (CTRLA.CMODE=0), the 16-bit Baud register value is used. In synchronous mode (CTRLA.CMODE=1), the eight LSBs of the Baud register are used. Refer to Clock Generation – Baud-Rate Generator for details on configuring the baud rate. Figure 35-3. Clock Generation XCK CTRLA.MODE[0] 1 0 XCKInternal Clk (GCLK) Baud Rate Generator Base Period /2 /8 /1 /2 /8 1 0 1 0 0 1 Tx Clk Rx Clk CTRLA.CMODE Related Links 34.6.2.3 Clock Generation – Baud-Rate Generator 34.6.2.3.1 Asynchronous Arithmetic Mode BAUD Value Selection 35.6.2.3.1 Synchronous Clock Operation In synchronous mode, the CTRLA.MODE bit field determines whether the transmission clock line (XCK) serves either as input or output. The dependency between clock edges, data sampling, and data change SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 738 is the same for internal and external clocks. Data input on the RxD pin is sampled at the opposite XCK clock edge when data is driven on the TxD pin. The Clock Polarity bit in the Control A register (CTRLA.CPOL) selects which XCK clock edge is used for RxD sampling, and which is used for TxD change: When CTRLA.CPOL is '0', the data will be changed on the rising edge of XCK, and sampled on the falling edge of XCK. When CTRLA.CPOL is '1', the data will be changed on the falling edge of XCK, and sampled on the rising edge of XCK. Figure 35-4. Synchronous Mode XCK Timing XCK RxD / TxD CTRLA.CPOL=1 Change Sample XCK RxD / TxD CTRLA.CPOL=0 Change Sample When the clock is provided through XCK (CTRLA.MODE=0x0), the shift registers operate directly on the XCK clock. This means that XCK is not synchronized with the system clock and, therefore, can operate at frequencies up to the system frequency. 35.6.2.4 Data Register The USART Transmit Data register (TxDATA) and USART Receive Data register (RxDATA) share the same I/O address, referred to as the Data register (DATA). Writing the DATA register will update the TxDATA register. Reading the DATA register will return the contents of the RxDATA register. 35.6.2.5 Data Transmission Data transmission is initiated by writing the data to be sent into the DATA register. Then, the data in TxDATA will be moved to the shift register when the shift register is empty and ready to send a new frame. After the shift register is loaded with data, the data frame will be transmitted. When the entire data frame including stop bit(s) has been transmitted and no new data was written to DATA, the Transmit Complete interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG.TXC) will be set, and the optional interrupt will be generated. The Data Register Empty flag in the Interrupt Flag Status and Clear register (INTFLAG.DRE) indicates that the register is empty and ready for new data. The DATA register should only be written to when INTFLAG.DRE is set. 35.6.2.5.1 Disabling the Transmitter The transmitter is disabled by writing '0' to the Transmitter Enable bit in the CTRLB register (CTRLB.TXEN). Disabling the transmitter will complete only after any ongoing and pending transmissions are completed, i.e., there is no data in the transmit shift register and TxDATA to transmit. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 739 35.6.2.6 Data Reception The receiver accepts data when a valid start bit is detected. Each bit following the start bit will be sampled according to the baud rate or XCK clock, and shifted into the receive shift register until the first stop bit of a frame is received. The 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 two-level or four-level receive buffer. Then, the Receive Complete interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG.RXC) will be set, and the optional interrupt will be generated. The received data can be read from the DATA register when the Receive Complete interrupt flag is set. 35.6.2.6.1 Disabling the Receiver Writing '0' to the Receiver Enable bit in the CTRLB register (CTRLB.RXEN) will disable the receiver, flush the two-level or four-level receive buffer, and data from ongoing receptions will be lost. 35.6.2.6.2 Error Bits The USART receiver has three error bits in the Status (STATUS) register: Frame Error (FERR), Buffer Overflow (BUFOVF), and Parity Error (PERR). Once an error happens, the corresponding error bit will be set until it is cleared by writing ‘1’ to it. These bits are also cleared automatically when the receiver is disabled. There are two methods for buffer overflow notification, selected by the Immediate Buffer Overflow Notification bit in the Control A register (CTRLA.IBON): When CTRLA.IBON=1, STATUS.BUFOVF is raised immediately upon buffer overflow. Software can then empty the receive FIFO by reading RxDATA, until the receiver complete interrupt flag (INTFLAG.RXC) is cleared. When CTRLA.IBON=0, the buffer overflow condition is attending data through the receive FIFO. After the received data is read, STATUS.BUFOVF will be set along with INTFLAG.RXC. 35.6.2.6.3 Asynchronous Data Reception The USART includes a clock recovery and data recovery unit for handling asynchronous data reception. The clock recovery logic can synchronize the incoming asynchronous serial frames at the RxD pin to the internally generated baud-rate clock. The data recovery logic samples and applies a low-pass filter to each incoming bit, thereby improving the noise immunity of the receiver. 35.6.2.6.4 Asynchronous Operational Range The operational range of the asynchronous reception depends on the accuracy of the internal baud-rate clock, the rate of the incoming frames, and the frame size (in number of bits). In addition, the operational range of the receiver is depending on the difference between the received bit rate and the internally generated baud rate. If the baud rate of an external transmitter is too high or too low compared to the internally generated baud rate, the receiver will not be able to synchronize the frames to the start bit. There are two possible sources for a mismatch in baud rate: First, the reference clock will always have some minor instability. Second, the baud-rate generator cannot always do an exact division of the reference clock frequency to get the baud rate desired. In this case, the BAUD register value should be set to give the lowest possible error. Refer to Clock Generation – Baud-Rate Generator for details. Recommended maximum receiver baud-rate errors for various character sizes are shown in the table below. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 740 Table 35-3. Asynchronous Receiver Error for 16-fold Oversampling D (Data bits+Parity) RSLOW [%] RFAST [%] Max. total error [%] Recommended max. Rx error [%] 5 94.12 107.69 +5.88/-7.69 ±2.5 6 94.92 106.67 +5.08/-6.67 ±2.0 7 95.52 105.88 +4.48/-5.88 ±2.0 8 96.00 105.26 +4.00/-5.26 ±2.0 9 96.39 104.76 +3.61/-4.76 ±1.5 10 96.70 104.35 +3.30/-4.35 ±1.5 The following equations calculate the ratio of the incoming data rate and internal receiver baud rate: ܴSLOW = ܵ 1 + ܦ ܨܵ + ܵ ڄ ܦ + 1 െܵ , ܴFAST = ܵ 2 + ܦ ܯܵ + ܵ 1 + ܦ • RSLOW is the ratio of the slowest incoming data rate that can be accepted in relation to the receiver baud rate • RFAST is the ratio of the fastest incoming data rate that can be accepted in relation to the receiver baud rate • D is the sum of character size and parity size (D = 5 to 10 bits) • S is the number of samples per bit (S = 16, 8 or 3) • SF is the first sample number used for majority voting (SF = 7, 3, or 2) when CTRLA.SAMPA=0. • SM is the middle sample number used for majority voting (SM = 8, 4, or 2) when CTRLA.SAMPA=0. The recommended maximum Rx Error assumes that the receiver and transmitter equally divide the maximum total error. Its connection to the SERCOM Receiver error acceptance is depicted in this figure: Figure 35-5. USART Rx Error Calculation + + Error Max (%) Error Min (%) Baud Rate SERCOM Receiver error acceptance from RSLOW and RFAST formulas Baud Generator offset error depends on BAUD register value + Clock source error Recommended max. Rx Error (%) The recommendation values in the table above accommodate errors of the clock source and the baud generator. The following figure gives an example for a baud rate of 3Mbps: SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 741 Figure 35-6. USART Rx Error Calculation Example + + Error Max 3.3% Error Min -4.35% Baud Rate 2Mbps SERCOM Receiver error acceptance sampling = x16 data bits = 10 parity = 0 start bit = stop bit = 1 No baud generator offset error Fbaud(2Mbps) = 32MHz *1(BAUD=0) /16 + DFLLULP source at 2MHz +/-0.3% Recommended max. Rx Error +/-1.5% (example) Error Max 3.3% Error Min -4.35% + Error Max 3.0% Error Min -4.05% Transmitter Error* Accepted Receiver Error security margin *Transmitter Error depends on the external transmitter used in the application. It is advised that it is within the Recommended max. Rx Error (+/-1.5% in this example). Larger Transmitter Errors are acceptable but must lie within the Accepted Receiver Error. Related Links 34.6.2.3 Clock Generation – Baud-Rate Generator 34.6.2.3.1 Asynchronous Arithmetic Mode BAUD Value Selection 35.6.3 Additional Features 35.6.3.1 Parity Even or odd parity can be selected for error checking by writing 0x1 to the Frame Format bit field in the Control A register (CTRLA.FORM). If even parity is selected (CTRLB.PMODE=0), the parity bit of an outgoing frame is '1' if the data contains an odd number of bits that are '1', making the total number of '1' even. If odd parity is selected (CTRLB.PMODE=1), the parity bit of an outgoing frame is '1' if the data contains an even number of bits that are '0', making the total number of '1' odd. When parity checking is 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 bit in the Status register (STATUS.PERR) is set. 35.6.3.2 Hardware Handshaking The USART features an out-of-band hardware handshaking flow control mechanism, implemented by connecting the RTS and CTS pins with the remote device, as shown in the figure below. Figure 35-7. Connection with a Remote Device for Hardware Handshaking RXD CTS RTS USART TXD RTS CTS Remote Device TXD RXD Hardware handshaking is only available in the following configuration: • USART with internal clock (CTRLA.MODE=1), • Asynchronous mode (CTRLA.CMODE=0), • and Flow control pinout (CTRLA.TXPO=2). SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 742 When the receiver is disabled or the receive FIFO is full, the receiver will drive the RTS pin high. This notifies the remote device to stop transfer after the ongoing transmission. Enabling and disabling the receiver by writing to CTRLB.RXEN will set/clear the RTS pin after a synchronization delay. When the receive FIFO goes full, RTS will be set immediately and the frame being received will be stored in the shift register until the receive FIFO is no longer full. Figure 35-8. Receiver Behavior when Operating with Hardware Handshaking RTS Rx FIFO Full RXD RXEN The current CTS Status is in the STATUS register (STATUS.CTS). Character transmission will start only if STATUS.CTS=0. When CTS is set, the transmitter will complete the ongoing transmission and stop transmitting. Figure 35-9. Transmitter Behavior when Operating with Hardware Handshaking CTS TXD 35.6.3.3 IrDA Modulation and Demodulation Transmission and reception can be encoded IrDA compliant up to 115.2 kb/s. IrDA modulation and demodulation work in the following configuration: • IrDA encoding enabled (CTRLB.ENC=1), • Asynchronous mode (CTRLA.CMODE=0), • and 16x sample rate (CTRLA.SAMPR[0]=0). During transmission, each low bit is transmitted as a high pulse. The pulse width is 3/16 of the baud rate period, as illustrated in the figure below. Figure 35-10. IrDA Transmit Encoding IrDA encoded TXD TXD 1 baud clock 3/16 baud clock The reception decoder has two main functions. The first is to synchronize the incoming data to the IrDA baud rate counter. Synchronization is performed at the start of each zero pulse. The second main function is to decode incoming Rx data. If a pulse width meets the minimum length set by configuration (RXPL.RXPL), it is accepted. When the baud rate counter reaches its middle value (1/2 bit length), it is transferred to the receiver. Note:  Note that the polarity of the transmitter and receiver are opposite: During transmission, a '0' bit is transmitted as a '1' pulse. During reception, an accepted '0' pulse is received as a '0' bit. Example: The figure below illustrates reception where RXPL.RXPL is set to 19. This indicates that the pulse width should be at least 20 SE clock cycles. When using BAUD=0xE666 or 160 SE cycles per bit, this corresponds to 2/16 baud clock as SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 743 minimum pulse width required. In this case the first bit is accepted as a '0', the second bit is a '1', and the third bit is also a '1'. A low pulse is rejected since it does not meet the minimum requirement of 2/16 baud clock. Figure 35-11. IrDA Receive Decoding IrDA encoded RXD RXD Baud clock 20 SE clock cycles 0 0.5 1 1.5 2 2.5 35.6.3.4 Break Character Detection and Auto-Baud/LIN Slave Break character detection and auto-baud are available in this configuration: • Auto-baud frame format (CTRLA.FORM = 0x04 or 0x05), • Asynchronous mode (CTRLA.CMODE = 0), • and 16x sample rate using fractional baud rate generation (CTRLA.SAMPR = 1). The USART uses a break detection threshold of greater than 11 nominal bit times at the configured baud rate. At any time, if more than 11 consecutive dominant bits are detected on the bus, the USART detects a Break Field. When a Break Field has been detected, the Receive Break interrupt flag (INTFLAG.RXBRK) is set and the USART expects the Sync Field character to be 0x55. This field is used to update the actual baud rate in order to stay synchronized. If the received Sync character is not 0x55, then the Inconsistent Sync Field error flag (STATUS.ISF) is set along with the Error interrupt flag (INTFLAG.ERROR), and the baud rate is unchanged. The auto-baud follows the LIN format. All LIN Frames start with a Break Field followed by a Sync Field. Figure 35-12. LIN Break and Sync Fields Break Field Sync Field 8 bit times After a break field is detected and the start bit of the Sync Field is detected, a counter is started. The counter is then incremented for the next 8 bit times of the Sync Field. At the end of these 8 bit times, the counter is stopped. At this moment, the 13 most significant bits of the counter (value divided by 8) give the new clock divider (BAUD.BAUD), and the 3 least significant bits of this value (the remainder) give the new Fractional Part (BAUD.FP). When the Sync Field has been received, the clock divider (BAUD.BAUD) and the Fractional Part (BAUD.FP) are updated after a synchronization delay. After the Break and Sync Fields are received, multiple characters of data can be received. 35.6.3.5 RS485 RS485 is available with the following configuration: • USART frame format (CTRLA.FORM = 0x00 or 0x01) • RS485 pinout (CTRLA.TXPO=0x3). The RS485 feature enables control of an external line driver as shown in the figure below. While operating in RS485 mode, the transmit enable pin (TE) is driven high when the transmitter is active. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 744 Figure 35-13. RS485 Bus Connection TXD TE USART RXD Differential Bus The TE pin will remain high for the complete frame including stop bit(s). If a Guard Time is programmed in the Control C register (CTRLC.GTIME), the line will remain driven after the last character completion. The following figure shows a transfer with one stop bit and CTRLC.GTIME=3. Figure 35-14. Example of TE Drive with Guard Time TXD Start StopData GTIME=3 TE The Transmit Complete interrupt flag (INTFLAG.TXC) will be raised after the guard time is complete and TE goes low. 35.6.3.6 ISO 7816 for Smart Card Interfacing The SERCOM USART features an ISO/IEC 7816-compatible operating mode. This mode permits interfacing with smart cards and Security Access Modules (SAM) communicating through an ISO 7816 link. Both T=0 and T=1 protocols defined by the ISO 7816 specification are supported. ISO 7816 is available with the following configuration: • ISO 7816 format (CTRLA.FORM = 0x07) • Inverse transmission and reception (CTRLA.RXINV=1 and CTRLA.TXINV=1) • Single bidirectional data line (CTRLA.TXPO and CTRLA.RXPO configured to use the same data pin) • Even parity (CTRLB.PMODE=0) • 8-bit character size (CTRLB.CHSIZE=0) • T=0 (CTRLA.CMODE=1) or T=1 (CTRLA.CMODE=0) ISO 7816 is a half duplex communication on a single bidirectional line. The USART connects to a smart card as shown below. The output is only driven when the USART is transmitting. The USART is considered as the master of the communication as it generates the clock. Figure 35-15. Connection of a Smart Card to the SERCOM USART TXD/RXD SERCOM USART SCK I/O Smart Card CLK ISO 7816 characters are specified as 8 bits with even parity. The USART must be configured accordingly. The USART cannot operate concurrently in both receiver and transmitter modes as the communication is unidirectional. It has to be configured according to the required mode by enabling or disabling either the receiver or the transmitter as desired. Enabling both the receiver and the transmitter at the same time in ISO 7816 mode may lead to unpredictable results. The ISO 7816 specification defines an inverse transmission format. Data bits of the character must be transmitted on the I/O line at their negative value (CTRLA.RXINV=1 and CTRLA.TXINV=1). SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 745 Protocol T=0 In T=0 protocol, a character is made up of: • one start bit, • eight data bits, • one parity bit • and one guard time, which lasts two bit times. The transfer is synchronous (CTRLA.CMODE=1). The transmitter shifts out the bits and does not drive the I/O line during the guard time. Additional guard time can be added by programming the Guard Time (CTRLC.GTIME). If no parity error is detected, the I/O line remains during the guard time and the transmitter can continue with the transmission of the next character, as shown in the figure below. Figure 35-16. T=0 Protocol without Parity Error SCK I/O Start Bit D0 D1 D2 D3 D4 D5 D6 D7 P Guard Time1 Guard Time2 Next Start Bit If a parity error is detected by the receiver, it drives the I/O line to 0 during the guard time, as shown in the next figure. This error bit is also named NACK, for Non Acknowledge. In this case, the character lasts 1 bit time more, as the guard time length is the same and is added to the error bit time, which lasts 1 bit time. Figure 35-17. T=0 Protocol with Parity Error SCK I/O Start Bit D0 D1 D2 D3 D4 D5 D6 D7 P Guard Time1 Guard Time2 Start Bit D0 D1 Repetition Error When the USART is the receiver and it detects a parity error, the parity error bit in the Status Register (STATUS.PERR) is set and the character is not written to the receive FIFO. Receive Error Counter The receiver also records the total number of errors (receiver parity errors and NACKs from the remote transmitter) up to a maximum of 255. This can be read in the Receive Error Count (RXERRCNT) register. RXERRCNT is automatically cleared on read. Receive NACK Inhibit The receiver can also be configured to inhibit error generation. This can be achieved by setting the Inhibit Not Acknowledge (CTRLC.INACK) bit. If CTRLC.INACK is 1, no error signal is driven on the I/O line even if a parity error is detected. Moreover, if CTRLC.INACK is set, the erroneous received character is stored in the receive FIFO, and the STATUS.PERR bit is set. Inhibit not acknowledge (CTRLC.INACK) takes priority over disable successive receive NACK (CTRLC.DSNACK). Transmit Character Repetition When the USART is transmitting a character and gets a NACK, it can automatically repeat the character before moving on to the next character. Repetition is enabled by writing the Maximum Iterations register (CTRLC.MAXITER) to a non-zero value. The USART repeats the character the number of times specified in CTRLC.MAXITER. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 746 When the USART repetition number reaches the programmed value in CTRLC.MAXITER, the STATUS.ITER bit is set and the internal iteration counter is reset. If the repetition of the character is acknowledged by the receiver before the maximum iteration is reached, the repetitions are stopped and the iteration counter is cleared. Disable Successive Receive NACK The receiver can limit the number of successive NACKs sent back to the remote transmitter. This is programmed by setting the Disable Successive NACK bit (CTRLC.DSNACK). The maximum number of NACKs transmitted is programmed in the CTRLC.MAXITER field. As soon as the maximum is reached, the character is considered as correct, an acknowledge is sent on the line, the STATUS.ITER bit is set and the internal iteration counter is reset. Protocol T=1 When operating in ISO7816 protocol T=1, the transmission is asynchronous (CTRL1.CMODE=0) with one or two stop bits. After the stop bits are sent, the transmitter does not drive the I/O line. Parity is generated when transmitting and checked when receiving. Parity error detection sets the STATUS.PERR bit, and the erroneous character is written to the receive FIFO. When using T=1 protocol, the receiver does not signal errors on the I/O line and the transmitter does not retransmit. 35.6.3.7 Collision Detection When the receiver and transmitter are connected either through pin configuration or externally, transmit collision can be detected after selecting the Collision Detection Enable bit in the CTRLB register (CTRLB.COLDEN=1). To detect collision, the receiver and transmitter must be enabled (CTRLB.RXEN=1 and CTRLB.TXEN=1). Collision detection is performed for each bit transmitted by comparing the received value with the transmit value, as shown in the figure below. While the transmitter is idle (no transmission in progress), characters can be received on RxD without triggering a collision. Figure 35-18. Collision Checking 8-bit character, single stop bit Collision checked TXD RXD The next figure shows the conditions for a collision detection. In this case, the start bit and the first data bit are received with the same value as transmitted. The second received data bit is found to be different than the transmitted bit at the detection point, which indicates a collision. Figure 35-19. Collision Detected Collision checked and ok TXD RXD Collision detected Tri-state TXEN When a collision is detected, the USART follows this sequence: SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 747 1. Abort the current transfer. 2. Flush the transmit buffer. 3. Disable transmitter (CTRLB.TXEN=0) – This is done after a synchronization delay. The CTRLB Synchronization Busy bit (SYNCBUSY.CTRLB) will be set until this is complete. – After disabling, the TxD pin will be tri-stated. 4. Set the Collision Detected bit (STATUS.COLL) along with the Error interrupt flag (INTFLAG.ERROR). 5. Set the Transmit Complete interrupt flag (INTFLAG.TXC), since the transmit buffer no longer contains data. After a collision, software must manually enable the transmitter again before continuing, after assuring that the CTRLB Synchronization Busy bit (SYNCBUSY.CTRLB) is not set. 35.6.3.8 Loop-Back Mode For loop-back mode, configure the Receive Data Pinout (CTRLA.RXPO) and Transmit Data Pinout (CTRLA.TXPO) to use the same data pins for transmit and receive. The loop-back is through the pad, so the signal is also available externally. 35.6.3.9 Start-of-Frame Detection The USART start-of-frame detector can wake-up the CPU when it detects a Start bit. In Standby Sleep mode, the internal fast start-up oscillator must be selected as the GCLK_SERCOMx_CORE source. When a 1-to-0 transition is detected on RxD, the 8 MHz Internal Oscillator is powered up and the USART clock is enabled. After start-up, the rest of the data frame can be received, provided that the baud rate is slow enough in relation to the fast start-up internal oscillator start-up time. Refer to the Electrical Characteristics chapters for details. The start-up time of this oscillator varies with supply voltage and temperature. The USART start-of-frame detection works both in Asynchronous and Synchronous modes. It is enabled by writing ‘1’ to the Start of Frame Detection Enable bit in the Control B register (CTRLB.SFDE). If the Receive Start Interrupt Enable bit in the Interrupt Enable Set register (INTENSET.RXS) is set, the Receive Start interrupt is generated immediately when a start is detected. When using start-of-frame detection without the Receive Start interrupt, start detection will force the 8 MHz internal oscillator and USART clock active while the frame is being received. In this case, the CPU will not wake up until the receive complete interrupt is generated. 35.6.3.10 Sample Adjustment In asynchronous mode (CTRLA.CMODE=0), three samples in the middle are used to determine the value based on majority voting. The three samples used for voting can be selected using the Sample Adjustment bit field in Control A register (CTRLA.SAMPA). When CTRLA.SAMPA=0, samples 7-8-9 are used for 16x oversampling, and samples 3-4-5 are used for 8x oversampling. 35.6.4 DMA, Interrupts and Events Table 35-4. Module Request for SERCOM USART Condition Request DMA Interrupt Event Data Register Empty (DRE) Yes Yes NA SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 748 Condition Request DMA Interrupt Event (request cleared when data is written) Receive Complete (RXC) Yes (request cleared when data is read) Yes Transmit Complete (TXC) NA Yes Receive Start (RXS) NA Yes Clear to Send Input Change (CTSIC) NA Yes Receive Break (RXBRK) NA Yes Error (ERROR) NA Yes 35.6.4.1 DMA Operation The USART generates the following DMA requests: • Data received (RX): The request is set when data is available in the receive FIFO. The request is cleared when DATA is read. • Data transmit (TX): The request is set when the transmit buffer (TX DATA) is empty. The request is cleared when DATA is written. 35.6.4.2 Interrupts The USART has the following interrupt sources. These are asynchronous interrupts, and can wake up the device from any sleep mode: • Data Register Empty (DRE) • Receive Complete (RXC) • Transmit Complete (TXC) • Receive Start (RXS) • Clear to Send Input Change (CTSIC) • Received Break (RXBRK) • Error (ERROR) Each interrupt source has its own interrupt flag. The interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG) will be set when the interrupt condition is met. Each interrupt can be individually enabled by writing '1' to the corresponding bit in the Interrupt Enable Set register (INTENSET), and disabled by writing '1' to the corresponding bit in the Interrupt Enable Clear register (INTENCLR). An interrupt request is generated when the interrupt flag is set and if the corresponding interrupt is enabled. The interrupt request remains active until either the interrupt flag is cleared, the interrupt is disabled, or the USART is reset. For details on clearing interrupt flags, refer to the INTFLAG register description. The value of INTFLAG indicates which interrupt is executed. Note that interrupts must be globally enabled for interrupt requests. Refer to Nested Vector Interrupt Controller for details. 35.6.4.3 Events Not applicable. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 749 35.6.5 Sleep Mode Operation The behavior in sleep mode is depending on the clock source and the Run In Standby bit in the Control A register (CTRLA.RUNSTDBY): • Internal clocking, CTRLA.RUNSTDBY=1: GCLK_SERCOMx_CORE can be enabled in all sleep modes. Any interrupt can wake up the device. • External clocking, CTRLA.RUNSTDBY=1: The Receive Complete interrupt(s) can wake up the device. • Internal clocking, CTRLA.RUNSTDBY=0: Internal clock will be disabled, after any ongoing transfer was completed. The Receive Complete interrupt(s) can wake up the device. • External clocking, CTRLA.RUNSTDBY=0: External clock will be disconnected, after any ongoing transfer was completed. All reception will be dropped. 35.6.6 Synchronization Due to asynchronicity between the main clock domain and the peripheral clock domains, some registers need to be synchronized when written or read. The following bits are synchronized when written: • Software Reset bit in the CTRLA register (CTRLA.SWRST) • Enable bit in the CTRLA register (CTRLA.ENABLE) • Receiver Enable bit in the CTRLB register (CTRLB.RXEN) • Transmitter Enable bit in the Control B register (CTRLB.TXEN) Note:  CTRLB.RXEN is write-synchronized somewhat differently. See also 35.8.2 CTRLB for details. Required write-synchronization is denoted by the "Write-Synchronized" property in the register description. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 750 35.7 Register Summary Offset Name Bit Pos. 0x00 CTRLA 7:0 RUNSTDBY MODE[2:0] ENABLE SWRST 15:8 SAMPR[2:0] RXINV TXINV IBON 23:16 SAMPA[1:0] RXPO[1:0] TXPO[1:0] 31:24 DORD CPOL CMODE FORM[3:0] 0x04 CTRLB 7:0 SBMODE CHSIZE[2:0] 15:8 PMODE ENC SFDE COLDEN 23:16 RXEN TXEN 31:24 0x08 CTRLC 7:0 GTIME[2:0] 15:8 23:16 MAXITER[2:0] DSNACK INACK 31:24 0x0C BAUD 7:0 BAUD[7:0] 15:8 BAUD[15:8] 0x0E RXPL 7:0 RXPL[7:0] 0x0F ... 0x13 Reserved 0x14 INTENCLR 7:0 ERROR RXBRK CTSIC RXS RXC TXC DRE 0x15 Reserved 0x16 INTENSET 7:0 ERROR RXBRK CTSIC RXS RXC TXC DRE 0x17 Reserved 0x18 INTFLAG 7:0 ERROR RXBRK CTSIC RXS RXC TXC DRE 0x19 Reserved 0x1A STATUS 7:0 ITER TXE COLL ISF CTS BUFOVF FERR PERR 15:8 0x1C SYNCBUSY 7:0 RXERRCNT CTRLB ENABLE SWRST 15:8 23:16 31:24 0x20 RXERRCNT 7:0 RXERRCNT[7:0] 0x21 ... 0x27 Reserved 0x28 DATA 7:0 DATA[7:0] 15:8 DATA[8:8] 0x2A ... 0x2F Reserved 0x30 DBGCTRL 7:0 DBGSTOP SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 751 35.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16-, and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers require synchronization when read and/or written. Synchronization is denoted by the "Read-Synchronized" and/or "Write-Synchronized" property in each individual register description. Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. Some registers are enable-protected, meaning they can only be written when the module is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 752 35.8.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 DORD CPOL CMODE FORM[3:0] Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 SAMPA[1:0] RXPO[1:0] TXPO[1:0] Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 SAMPR[2:0] RXINV TXINV IBON Access R/W R/W R/W R/W R/W R Reset 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 RUNSTDBY MODE[2:0] ENABLE SWRST Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 30 – DORD Data Order This bit selects the data order when a character is shifted out from the Data register. This bit is not synchronized. Value Description 0 MSB is transmitted first. 1 LSB is transmitted first. Bit 29 – CPOL Clock Polarity This bit selects the relationship between data output change and data input sampling in synchronous mode. This bit is not synchronized. CPOL TxD Change RxD Sample 0x0 Rising XCK edge Falling XCK edge 0x1 Falling XCK edge Rising XCK edge Bit 28 – CMODE Communication Mode This bit selects asynchronous or synchronous communication. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 753 This bit is not synchronized. Value Description 0 Asynchronous communication. 1 Synchronous communication. Bits 27:24 – FORM[3:0] Frame Format These bits define the frame format. These bits are not synchronized. FORM[3:0] Description 0x0 USART frame 0x1 USART frame with parity 0x2-0x3 Reserved 0x4 Auto-baud (LIN Slave) - break detection and auto-baud. 0x5 Auto-baud - break detection and auto-baud with parity 0x6 Reserved 0x7 ISO 7816 0x8-0xF Reserved Bits 23:22 – SAMPA[1:0] Sample Adjustment These bits define the sample adjustment. These bits are not synchronized. SAMPA[1:0] 16x Over-sampling (CTRLA.SAMPR=0 or 1) 8x Over-sampling (CTRLA.SAMPR=2 or 3) 0x0 7-8-9 3-4-5 0x1 9-10-11 4-5-6 0x2 11-12-13 5-6-7 0x3 13-14-15 6-7-8 Bits 21:20 – RXPO[1:0] Receive Data Pinout These bits define the receive data (RxD) pin configuration. These bits are not synchronized. RXPO[1:0] Name Description 0x0 PAD[0] SERCOM PAD[0] is used for data reception 0x1 PAD[1] SERCOM PAD[1] is used for data reception 0x2 PAD[2] SERCOM PAD[2] is used for data reception 0x3 PAD[3] SERCOM PAD[3] is used for data reception SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 754 Bits 17:16 – TXPO[1:0] Transmit Data Pinout These bits define the transmit data (TxD) and XCK pin configurations. This bit is not synchronized. TXPO TxD Pin Location XCK Pin Location (When Applicable) RTS/TE CTS 0x0 SERCOM PAD[0] SERCOM PAD[1] N/A N/A 0x1 SERCOM PAD[2] SERCOM PAD[3] N/A N/A 0x2 SERCOM PAD[0] N/A SERCOM PAD[2] SERCOM PAD[3] 0x3 SERCOM_PAD[0] SERCOM_PAD[1] SERCOM_PAD[2] N/A Bits 15:13 – SAMPR[2:0] Sample Rate These bits select the sample rate. These bits are not synchronized. SAMPR[2:0] Description 0x0 16x over-sampling using arithmetic baud rate generation. 0x1 16x over-sampling using fractional baud rate generation. 0x2 8x over-sampling using arithmetic baud rate generation. 0x3 8x over-sampling using fractional baud rate generation. 0x4 3x over-sampling using arithmetic baud rate generation. 0x5-0x7 Reserved Bit 10 – RXINV Receive Data Invert This bit controls whether the receive data (RxD) is inverted or not. Note:  Start, parity and stop bit(s) are unchanged. When enabled, parity is calculated on the inverted data. Value Description 0 RxD is not inverted. 1 RxD is inverted. Bit 9 – TXINV Transmit Data Invert This bit controls whether the transmit data (TxD) is inverted or not. Note:  Start, parity and stop bit(s) are unchanged. When enabled, parity is calculated on the inverted data. Value Description 0 TxD is not inverted. 1 TxD is inverted. Bit 8 – IBON Immediate Buffer Overflow Notification This bit controls when the buffer overflow status bit (STATUS.BUFOVF) is asserted when a buffer overflow occurs. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 755 Value Description 0 STATUS.BUFOVF is asserted when it occurs in the data stream. 1 STATUS.BUFOVF is asserted immediately upon buffer overflow. Bit 7 – RUNSTDBY Run In Standby This bit defines the functionality in standby sleep mode. This bit is not synchronized. RUNSTDBY External Clock Internal Clock 0x0 External clock is disconnected when ongoing transfer is finished. All reception is dropped. Generic clock is disabled when ongoing transfer is finished. The device can wake up on Transfer Complete interrupt. 0x1 Wake on Receive Complete interrupt. Generic clock is enabled in all sleep modes. Any interrupt can wake up the device. Bits 4:2 – MODE[2:0] Operating Mode These bits select the USART serial communication interface of the SERCOM. These bits are not synchronized. Value Description 0x0 USART with external clock 0x1 USART with internal clock Bit 1 – ENABLE Enable Due to synchronization, there is delay from writing CTRLA.ENABLE until the peripheral is enabled/ disabled. The value written to CTRLA.ENABLE will read back immediately and the Enable Synchronization Busy bit in the Synchronization Busy register (SYNCBUSY.ENABLE) will be set. SYNCBUSY.ENABLE is cleared when the operation is complete. This bit is not enable-protected. Value Description 0 The peripheral is disabled or being disabled. 1 The peripheral is enabled or being enabled. Bit 0 – SWRST Software Reset Writing '0' to this bit has no effect. Writing '1' to this bit resets all registers in the SERCOM, except DBGCTRL, to their initial state, and the SERCOM will be disabled. Writing '1' to CTRLA.SWRST will always take precedence, meaning that all other writes in the same write-operation will be discarded. Any register write access during the ongoing reset will result in an APB error. Reading any register will return the reset value of the register. Due to synchronization, there is a delay from writing CTRLA.SWRST until the reset is complete. CTRLA.SWRST and SYNCBUSY.SWRST will both be cleared when the reset is complete. This bit is not enable-protected. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 756 Value Description 0 There is no reset operation ongoing. 1 The reset operation is ongoing. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 757 35.8.2 Control B Name:  CTRLB Offset:  0x04 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected, Write-Synchronized Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 RXEN TXEN Access R/W R/W Reset 0 0 Bit 15 14 13 12 11 10 9 8 PMODE ENC SFDE COLDEN Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 6 5 4 3 2 1 0 SBMODE CHSIZE[2:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 17 – RXEN Receiver Enable Writing '0' to this bit will disable the USART receiver. Disabling the receiver will flush the receive buffer and clear the FERR, PERR and BUFOVF bits in the STATUS register. Writing '1' to CTRLB.RXEN when the USART is disabled will set CTRLB.RXEN immediately. When the USART is enabled, CTRLB.RXEN will be cleared, and SYNCBUSY.CTRLB will be set and remain set until the receiver is enabled. When the receiver is enabled, CTRLB.RXEN will read back as '1'. Writing '1' to CTRLB.RXEN when the USART is enabled will set SYNCBUSY.CTRLB, which will remain set until the receiver is enabled, and CTRLB.RXEN will read back as '1'. This bit is not enable-protected. Value Description 0 The receiver is disabled or being enabled. 1 The receiver is enabled or will be enabled when the USART is enabled. Bit 16 – TXEN Transmitter Enable Writing '0' to this bit will disable the USART transmitter. Disabling the transmitter will not become effective until ongoing and pending transmissions are completed. Writing '1' to CTRLB.TXEN when the USART is disabled will set CTRLB.TXEN immediately. When the USART is enabled, CTRLB.TXEN will be cleared, and SYNCBUSY.CTRLB will be set and remain set until the transmitter is enabled. When the transmitter is enabled, CTRLB.TXEN will read back as '1'. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 758 Writing '1' to CTRLB.TXEN when the USART is enabled will set SYNCBUSY.CTRLB, which will remain set until the transmitter is enabled, and CTRLB.TXEN will read back as '1'. This bit is not enable-protected. Value Description 0 The transmitter is disabled or being enabled. 1 The transmitter is enabled or will be enabled when the USART is enabled. Bit 13 – PMODE Parity Mode This bit selects the type of parity used when parity is enabled (CTRLA.FORM is '1'). 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 parity bit, compare it to the parity mode and, if a mismatch is detected, STATUS.PERR will be set. This bit is not synchronized. Value Description 0 Even parity. 1 Odd parity. Bit 10 – ENC Encoding Format This bit selects the data encoding format. This bit is not synchronized. Value Description 0 Data is not encoded. 1 Data is IrDA encoded. Bit 9 – SFDE Start of Frame Detection Enable This bit controls whether the start-of-frame detector will wake up the device when a start bit is detected on the RxD line. This bit is not synchronized. SFDE INTENSET.RXS INTENSET.RXC Description 0 X X Start-of-frame detection disabled. 1 0 0 Reserved 1 0 1 Start-of-frame detection enabled. RXC wakes up the device from all sleep modes. 1 1 0 Start-of-frame detection enabled. RXS wakes up the device from all sleep modes. 1 1 1 Start-of-frame detection enabled. Both RXC and RXS wake up the device from all sleep modes. Bit 8 – COLDEN Collision Detection Enable This bit enables collision detection. This bit is not synchronized. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 759 Value Description 0 Collision detection is not enabled. 1 Collision detection is enabled. Bit 6 – SBMODE Stop Bit Mode This bit selects the number of stop bits transmitted. This bit is not synchronized. Value Description 0 One stop bit. 1 Two stop bits. Bits 2:0 – CHSIZE[2:0] Character Size These bits select the number of bits in a character. These bits are not synchronized. CHSIZE[2:0] Description 0x0 8 bits 0x1 9 bits 0x2-0x4 Reserved 0x5 5 bits 0x6 6 bits 0x7 7 bits SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 760 35.8.3 Control C Name:  CTRLC Offset:  0x08 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 MAXITER[2:0] DSNACK INACK Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 GTIME[2:0] Access R/W R/W R/W Reset 0 0 0 Bits 22:20 – MAXITER[2:0] Maximum Iterations These bits define the maximum number of retransmit iterations. These bits also define the successive NACKs sent to the remote transmitter when CTRLC.DSNACK is set. This field is only valid when using ISO7816 T=0 mode (CTRLA.MODE=0x7 and CTRLA.CMODE=0). Bit 17 – DSNACK Disable Successive Not Acknowledge This bit controls how many times NACK will be sent on parity error reception. This bit is only valid in ISO7816 T=0 mode and when CTRLC.INACK=0. Value Description 0 NACK is sent on the ISO line for every parity error received. 1 Successive parity errors are counted up to the value specified in CTRLC.MAXITER. These parity errors generate a NACK on the ISO line. As soon as this value is reached, no additional NACK is sent on the ISO line. Bit 16 – INACK Inhibit Not Acknowledge This bit controls whether a NACK is transmitted when a parity error is received. This bit is only valid in ISO7816 T=0 mode. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 761 Value Description 0 NACK is transmitted when a parity error is received. 1 NACK is not transmitted when a parity error is received. Bits 2:0 – GTIME[2:0] Guard Time These bits define the guard time when using RS485 mode (CTRLA.FORM=0x0 or CTRLA.FORM=0x1, and CTRLA.TXPO=0x3) or ISO7816 mode (CTRLA.FORM=0x7). For RS485 mode, the guard time is programmable from 0-7 bit times and defines the time that the transmit enable pin (TE) remains high after the last stop bit is transmitted and there is no remaining data to be transmitted. For ISO7816 T=0 mode, the guard time is programmable from 2-9 bit times and defines the guard time between each transmitted byte. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 762 35.8.4 Baud Name:  BAUD Offset:  0x0C Reset:  0x0000 Property:  Enable-Protected, PAC Write-Protection Bit 15 14 13 12 11 10 9 8 BAUD[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 BAUD[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 15:0 – BAUD[15:0] Baud Value Arithmetic Baud Rate Generation (CTRLA.SAMPR[0]=0): These bits control the clock generation, as described in the SERCOM Baud Rate section. If Fractional Baud Rate Generation (CTRLA.SAMPR[0]=1) bit positions 15 to 13 are replaced by FP[2:0] Fractional Part: • Bits 15:13 - FP[2:0]: Fractional Part These bits control the clock generation, as described in the SERCOM Clock Generation – BaudRate Generator section. • Bits 12:0 - BAUD[12:0]: Baud Value These bits control the clock generation, as described in the SERCOM Clock Generation – BaudRate Generator section. Related Links 34.6.2.3 Clock Generation – Baud-Rate Generator 34.6.2.3.1 Asynchronous Arithmetic Mode BAUD Value Selection SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 763 35.8.5 Receive Pulse Length Register Name:  RXPL Offset:  0x0E Reset:  0x00 Property:  Enable-Protected, PAC Write-Protection Bit 7 6 5 4 3 2 1 0 RXPL[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 7:0 – RXPL[7:0] Receive Pulse Length When the encoding format is set to IrDA (CTRLB.ENC=1), these bits control the minimum pulse length that is required for a pulse to be accepted by the IrDA receiver with regards to the serial engine clock .ݎ݁݌ܧܵ period ݎ݁݌ܧܵ ڄ 2 + RXPL ≥ ܧܵܮܷܲ SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 764 35.8.6 Interrupt Enable Clear Name:  INTENCLR Offset:  0x14 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 7 6 5 4 3 2 1 0 ERROR RXBRK CTSIC RXS RXC TXC DRE Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bit 7 – ERROR Error Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Error Interrupt Enable bit, which disables the Error interrupt. Value Description 0 Error interrupt is disabled. 1 Error interrupt is enabled. Bit 5 – RXBRK Receive Break Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Receive Break Interrupt Enable bit, which disables the Receive Break interrupt. Value Description 0 Receive Break interrupt is disabled. 1 Receive Break interrupt is enabled. Bit 4 – CTSIC Clear to Send Input Change Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Clear To Send Input Change Interrupt Enable bit, which disables the Clear To Send Input Change interrupt. Value Description 0 Clear To Send Input Change interrupt is disabled. 1 Clear To Send Input Change interrupt is enabled. Bit 3 – RXS Receive Start Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Receive Start Interrupt Enable bit, which disables the Receive Start interrupt. Value Description 0 Receive Start interrupt is disabled. 1 Receive Start interrupt is enabled. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 765 Bit 2 – RXC Receive Complete Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Receive Complete Interrupt Enable bit, which disables the Receive Complete interrupt. Value Description 0 Receive Complete interrupt is disabled. 1 Receive Complete interrupt is enabled. Bit 1 – TXC Transmit Complete Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Transmit Complete Interrupt Enable bit, which disables the Receive Complete interrupt. Value Description 0 Transmit Complete interrupt is disabled. 1 Transmit Complete interrupt is enabled. Bit 0 – DRE Data Register Empty Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Data Register Empty Interrupt Enable bit, which disables the Data Register Empty interrupt. Value Description 0 Data Register Empty interrupt is disabled. 1 Data Register Empty interrupt is enabled. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 766 35.8.7 Interrupt Enable Set Name:  INTENSET Offset:  0x16 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear register (INTENCLR). Bit 7 6 5 4 3 2 1 0 ERROR RXBRK CTSIC RXS RXC TXC DRE Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bit 7 – ERROR Error Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Error Interrupt Enable bit, which enables the Error interrupt. Value Description 0 Error interrupt is disabled. 1 Error interrupt is enabled. Bit 5 – RXBRK Receive Break Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Receive Break Interrupt Enable bit, which enables the Receive Break interrupt. Value Description 0 Receive Break interrupt is disabled. 1 Receive Break interrupt is enabled. Bit 4 – CTSIC Clear to Send Input Change Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Clear To Send Input Change Interrupt Enable bit, which enables the Clear To Send Input Change interrupt. Value Description 0 Clear To Send Input Change interrupt is disabled. 1 Clear To Send Input Change interrupt is enabled. Bit 3 – RXS Receive Start Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Receive Start Interrupt Enable bit, which enables the Receive Start interrupt. Value Description 0 Receive Start interrupt is disabled. 1 Receive Start interrupt is enabled. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 767 Bit 2 – RXC Receive Complete Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Receive Complete Interrupt Enable bit, which enables the Receive Complete interrupt. Value Description 0 Receive Complete interrupt is disabled. 1 Receive Complete interrupt is enabled. Bit 1 – TXC Transmit Complete Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Transmit Complete Interrupt Enable bit, which enables the Transmit Complete interrupt. Value Description 0 Transmit Complete interrupt is disabled. 1 Transmit Complete interrupt is enabled. Bit 0 – DRE Data Register Empty Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Data Register Empty Interrupt Enable bit, which enables the Data Register Empty interrupt. Value Description 0 Data Register Empty interrupt is disabled. 1 Data Register Empty interrupt is enabled. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 768 35.8.8 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x18 Reset:  0x00 Property:  - Bit 7 6 5 4 3 2 1 0 ERROR RXBRK CTSIC RXS RXC TXC DRE Access R/W R/W R/W R/W R R/W R Reset 0 0 0 0 0 0 0 Bit 7 – ERROR Error This flag is cleared by writing '1' to it. This bit is set when any error is detected. Errors that will set this flag have corresponding status flags in the STATUS register. Errors that will set this flag are COLL, ISF, BUFOVF, FERR, and PERR.Writing '0' to this bit has no effect. Writing '1' to this bit will clear the flag. Bit 5 – RXBRK Receive Break This flag is cleared by writing '1' to it. This flag is set when auto-baud is enabled (CTRLA.FORM) and a break character is received. Writing '0' to this bit has no effect. Writing '1' to this bit will clear the flag. Bit 4 – CTSIC Clear to Send Input Change This flag is cleared by writing a '1' to it. This flag is set when a change is detected on the CTS pin. Writing '0' to this bit has no effect. Writing '1' to this bit will clear the flag. Bit 3 – RXS Receive Start This flag is cleared by writing '1' to it. This flag is set when a start condition is detected on the RxD line and start-of-frame detection is enabled (CTRLB.SFDE is '1'). Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Receive Start interrupt flag. Bit 2 – RXC Receive Complete This flag is cleared by reading the Data register (DATA) or by disabling the receiver. This flag is set when there are unread data in DATA. Writing '0' to this bit has no effect. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 769 Writing '1' to this bit has no effect. Bit 1 – TXC Transmit Complete This flag is cleared by writing '1' to it or by writing new data to DATA. This flag is set when the entire frame in the transmit shift register has been shifted out and there are no new data in DATA. Writing '0' to this bit has no effect. Writing '1' to this bit will clear the flag. Bit 0 – DRE Data Register Empty This flag is cleared by writing new data to DATA. This flag is set when DATA is empty and ready to be written. Writing '0' to this bit has no effect. Writing '1' to this bit has no effect. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 770 35.8.9 Status Name:  STATUS Offset:  0x1A Reset:  0x0000 Property:  - Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 ITER TXE COLL ISF CTS BUFOVF FERR PERR Access R/W R/W R/W R/W R R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 – ITER Maximum Number of Repetitions Reached This bit is set when the maximum number of NACK repetitions or retransmissions is met in ISO7816 T=0 mode. Writing '0' to this bit has no effect. Writing '1' to this bit will clear it. Bit 6 – TXE Transmitter Empty This bit will always read back as zero. Writing '0' to this bit has no effect. Writing '1' to this bit will clear it. Bit 5 – COLL Collision Detected This bit is cleared by writing '1' to the bit or by disabling the receiver. This bit is set when collision detection is enabled (CTRLB.COLDEN) and a collision is detected. Writing '0' to this bit has no effect. Writing '1' to this bit will clear it. Bit 4 – ISF Inconsistent Sync Field This bit is cleared by writing '1' to the bit or by disabling the receiver. This bit is set when the frame format is set to auto-baud (CTRLA.FORM) and a sync field not equal to 0x55 is received. Writing '0' to this bit has no effect. Writing '1' to this bit will clear it. Bit 3 – CTS Clear to Send This bit indicates the current level of the CTS pin when flow control is enabled (CTRLA.TXPO). SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 771 Writing '0' to this bit has no effect. Writing '1' to this bit has no effect. Bit 2 – BUFOVF Buffer Overflow Reading this bit before reading the Data register will indicate the error status of the next character to be read. This bit is cleared by writing '1' to the bit or by disabling the receiver. This bit is set when a buffer overflow condition is detected. A buffer overflow occurs when the receive buffer is full, there is a new character waiting in the receive shift register and a new start bit is detected. Writing '0' to this bit has no effect. Writing '1' to this bit will clear it. Bit 1 – FERR Frame Error Reading this bit before reading the Data register will indicate the error status of the next character to be read. This bit is cleared by writing '1' to the bit or by disabling the receiver. This bit is set if the received character had a frame error, i.e., when the first stop bit is zero. Writing '0' to this bit has no effect. Writing '1' to this bit will clear it. Bit 0 – PERR Parity Error Reading this bit before reading the Data register will indicate the error status of the next character to be read. This bit is cleared by writing '1' to the bit or by disabling the receiver. This bit is set if parity checking is enabled (CTRLA.FORM is 0x1, 0x5, or 0x7) and a parity error is detected. Writing '0' to this bit has no effect. Writing '1' to this bit will clear it. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 772 35.8.10 Synchronization Busy Name:  SYNCBUSY Offset:  0x1C Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 RXERRCNT CTRLB ENABLE SWRST Access R R R R Reset 0 0 0 0 Bit 3 – RXERRCNT Receive Error Count Synchronization Busy The RXERRCNT register is automatically synchronized to the APB domain upon error. When returning from sleep, this bit will be raised until the new value is available to be read. Value Description 0 RXERRCNT synchronization is not busy. 1 RXERRCNT synchronization is busy. Bit 2 – CTRLB CTRLB Synchronization Busy Writing to the CTRLB register when the SERCOM is enabled requires synchronization. When writing to CTRLB the SYNCBUSY.CTRLB bit will be set until synchronization is complete. If CTRLB is written while SYNCBUSY.CTRLB is asserted, an APB error will be generated. Value Description 0 CTRLB synchronization is not busy. 1 CTRLB synchronization is busy. Bit 1 – ENABLE SERCOM Enable Synchronization Busy Enabling and disabling the SERCOM (CTRLA.ENABLE) requires synchronization. When written, the SYNCBUSY.ENABLE bit will be set until synchronization is complete. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 773 Value Description 0 Enable synchronization is not busy. 1 Enable synchronization is busy. Bit 0 – SWRST Software Reset Synchronization Busy Resetting the SERCOM (CTRLA.SWRST) requires synchronization. When written, the SYNCBUSY.SWRST bit will be set until synchronization is complete. Value Description 0 SWRST synchronization is not busy. 1 SWRST synchronization is busy. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 774 35.8.11 Receive Error Count Name:  RXERRCNT Offset:  0x20 Reset:  0x00 Property:  Read-Synchronized Bit 7 6 5 4 3 2 1 0 RXERRCNT[7:0] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bits 7:0 – RXERRCNT[7:0] Receive Error Count This register records the total number of parity errors and NACK errors combined in ISO7816 mode (CTRLA.FORM=0x7). This register is automatically cleared on read. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 775 35.8.12 Data Name:  DATA Offset:  0x28 Reset:  0x0000 Property:  - Bit 15 14 13 12 11 10 9 8 DATA[8:8] Access R/W Reset 0 Bit 7 6 5 4 3 2 1 0 DATA[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 8:0 – DATA[8:0] Data Reading these bits will return the contents of the Receive Data register. The register should be read only when the Receive Complete Interrupt Flag bit in the Interrupt Flag Status and Clear register (INTFLAG.RXC) is set. The status bits in STATUS should be read before reading the DATA value in order to get any corresponding error. Writing these bits will write the Transmit Data register. This register should be written only when the Data Register Empty Interrupt Flag bit in the Interrupt Flag Status and Clear register (INTFLAG.DRE) is set. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 776 35.8.13 Debug Control Name:  DBGCTRL Offset:  0x30 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DBGSTOP Access R/W Reset 0 Bit 0 – DBGSTOP Debug Stop Mode This bit controls the baud-rate generator functionality when the CPU is halted by an external debugger. Value Description 0 The baud-rate generator continues normal operation when the CPU is halted by an external debugger. 1 The baud-rate generator is halted when the CPU is halted by an external debugger. SAM L10/L11 Family SERCOM USART - SERCOM Synchronous and Asyn... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 777 36. SERCOM SPI – SERCOM Serial Peripheral Interface 36.1 Overview The serial peripheral interface (SPI) is one of the available modes in the Serial Communication Interface (SERCOM). The SPI uses the SERCOM transmitter and receiver configured as shown in 36.3 Block Diagram. Each side, master and slave, depicts a separate SPI containing a shift register, a transmit buffer and a two-level or four-level receive buffer. In addition, the SPI master uses the SERCOM baud-rate generator, while the SPI slave can use the SERCOM address match logic. Labels in capital letters are synchronous to CLK_SERCOMx_APB and accessible by the CPU, while labels in lowercase letters are synchronous to the SCK clock. Related Links 34. SERCOM – Serial Communication Interface 36.2 Features SERCOM SPI includes the following features: • Full-duplex, four-wire interface (MISO, MOSI, SCK, SS) • One-level transmit buffer, two-level or four-level receive buffer • Supports all four SPI modes of operation • Single data direction operation allows alternate function on MISO or MOSI pin • Selectable LSB- or MSB-first data transfer • Can be used with DMA • Master operation: – Serial clock speed, fSCK=1/tSCK(1) – 8-bit clock generator – Hardware controlled SS 1. For tSCK and tSSCK values, refer to SPI Timing Characteristics. Related Links 34. SERCOM – Serial Communication Interface 34.2 Features SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 778 36.3 Block Diagram Figure 36-1. Full-Duplex SPI Master Slave Interconnection BAUD baud rate generator Tx DATA shift register rx buffer Rx DATA Master Slave Tx DATA shift register rx buffer Rx DATA SCK _SS MISO MOSI ADDR/ADDRMASK == Address Match 36.4 Signal Description Table 36-1. SERCOM SPI Signals Signal Name Type Description PAD[3:0] Digital I/O General SERCOM pins One signal can be mapped to one of several pins. 36.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 36.5.1 I/O Lines In order to use the SERCOM’s I/O lines, the I/O pins must be configured using the IO Pin Controller (PORT). When the SERCOM is configured for SPI operation, the SERCOM controls the direction and value of the I/O pins according to the table below. Both PORT control bits PINCFGn.PULLEN and PINCFGn.DRVSTR are still effective. If the receiver is disabled, the data input pin can be used for other purposes. In master mode, the slave select line (SS) is hardware controlled when the Master Slave Select Enable bit in the Control B register (CTRLB.MSSEN) is '1'. Table 36-2. SPI Pin Configuration Pin Master SPI Slave SPI MOSI Output Input MISO Input Output SCK Output Input SS Output (CTRLB.MSSEN=1) Input The combined configuration of PORT, the Data In Pinout and the Data Out Pinout bit groups in the Control A register (CTRLA.DIPO and CTRLA.DOPO) define the physical position of the SPI signals in the table above. Related Links SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 779 32. PORT - I/O Pin Controller 36.5.2 Power Management This peripheral can continue to operate in any sleep mode where its source clock is running. The interrupts can wake up the device from sleep modes. Related Links 22. PM – Power Manager 36.5.3 Clocks The SERCOM bus clock (CLK_SERCOMx_APB) can be enabled and disabled in the Main Clock Controller. Refer to Peripheral Clock Masking for details and default status of this clock. A generic clock (GCLK_SERCOMx_CORE) is required to clock the SPI. This clock must be configured and enabled in the Generic Clock Controller before using the SPI. This generic clock is asynchronous to the bus clock (CLK_SERCOMx_APB). Therefore, writes to certain registers will require synchronization to the clock domains. Related Links 18. GCLK - Generic Clock Controller 19.6.2.6 Peripheral Clock Masking 36.6.6 Synchronization 36.5.4 DMA The DMA request lines are connected to the DMA Controller (DMAC). In order to use DMA requests with this peripheral the DMAC must be configured first. Refer to DMAC – Direct Memory Access Controller for details. Related Links 28. DMAC – Direct Memory Access Controller 36.5.5 Interrupts The interrupt request line is connected to the Interrupt Controller. In order to use interrupt requests of this peripheral, the Interrupt Controller (NVIC) must be configured first. Refer to Nested Vector Interrupt Controller for details. 36.5.6 Events Not applicable. 36.5.7 Debug Operation When the CPU is halted in debug mode, this peripheral will continue normal operation. If the peripheral is configured to require periodical service by the CPU through interrupts or similar, improper operation or data loss may result during debugging. This peripheral can be forced to halt operation during debugging - refer to the Debug Control (DBGCTRL) register for details. 36.5.8 Register Access Protection Registers with write-access can be write-protected optionally by the peripheral access controller (PAC). PAC Write-Protection is not available for the following registers: • Interrupt Flag Clear and Status register (INTFLAG) SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 780 • Status register (STATUS) • Data register (DATA) Optional PAC Write-Protection is denoted by the "PAC Write-Protection" property in each individual register description. Write-protection does not apply to accesses through an external debugger. Related Links 15. PAC - Peripheral Access Controller 36.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 36.5.10 Analog Connections Not applicable. 36.6 Functional Description 36.6.1 Principle of Operation The SPI is a high-speed synchronous data transfer interface It allows high-speed communication between the device and peripheral devices. The SPI can operate as master or slave. As master, the SPI initiates and controls all data transactions. The SPI is single buffered for transmitting and double buffered for receiving. When transmitting data, the Data register can be loaded with the next character to be transmitted during the current transmission. When receiving, the data is transferred to the two-level or four-level receive buffer, and the receiver is ready for a new character. The SPI transaction format is shown in SPI Transaction Format. Each transaction can contain one or more characters. The character size is configurable, and can be either 8 or 9 bits. Figure 36-2. SPI Transaction Format Character Transaction MOSI/MISO _SS Character 0 Character 1 Character 2 SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 781 The SPI master must pull the slave select line (SS) of the desired slave low to initiate a transaction. The master and slave prepare data to send via their respective shift registers, and the master generates the serial clock on the SCK line. Data are always shifted from master to slave on the Master Output Slave Input line (MOSI); data is shifted from slave to master on the Master Input Slave Output line (MISO). Each time character is shifted out from the master, a character will be shifted out from the slave simultaneously. To signal the end of a transaction, the master will pull the SS line high 36.6.2 Basic Operation 36.6.2.1 Initialization The following registers are enable-protected, meaning that they can only be written when the SPI is disabled (CTRL.ENABLE=0): • Control A register (CTRLA), except Enable (CTRLA.ENABLE) and Software Reset (CTRLA.SWRST) • Control B register (CTRLB), except Receiver Enable (CTRLB.RXEN) • Baud register (BAUD) • Address register (ADDR) When the SPI is enabled or is being enabled (CTRLA.ENABLE=1), any writing to these registers will be discarded. when the SPI is being disabled, writing to these registers will be completed after the disabling. Enable-protection is denoted by the Enable-Protection property in the register description. Initialize the SPI by following these steps: 1. Select SPI mode in master / slave operation in the Operating Mode bit group in the CTRLA register (CTRLA.MODE= 0x2 or 0x3 ). 2. Select transfer mode for the Clock Polarity bit and the Clock Phase bit in the CTRLA register (CTRLA.CPOL and CTRLA.CPHA) if desired. 3. Select the Frame Format value in the CTRLA register (CTRLA.FORM). 4. Configure the Data In Pinout field in the Control A register (CTRLA.DIPO) for SERCOM pads of the receiver. 5. Configure the Data Out Pinout bit group in the Control A register (CTRLA.DOPO) for SERCOM pads of the transmitter. 6. Select the Character Size value in the CTRLB register (CTRLB.CHSIZE). 7. Write the Data Order bit in the CTRLA register (CTRLA.DORD) for data direction. 8. If the SPI is used in master mode: 8.1. Select the desired baud rate by writing to the Baud register (BAUD). 8.2. If Hardware SS control is required, write '1' to the Master Slave Select Enable bit in CTRLB register (CTRLB.MSSEN). 9. Enable the receiver by writing the Receiver Enable bit in the CTRLB register (CTRLB.RXEN=1). 36.6.2.2 Enabling, Disabling, and Resetting This peripheral is enabled by writing '1' to the Enable bit in the Control A register (CTRLA.ENABLE), and disabled by writing '0' to it. Writing ‘1’ to the Software Reset bit in the Control A register (CTRLA.SWRST) will reset all registers of this peripheral to their initial states, except the DBGCTRL register, and the peripheral is disabled. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 782 Refer to the CTRLA register description for details. 36.6.2.3 Clock Generation In SPI master operation (CTRLA.MODE=0x3), the serial clock (SCK) is generated internally by the SERCOM baud-rate generator. In SPI mode, the baud-rate generator is set to synchronous mode. The 8-bit Baud register (BAUD) value is used for generating SCK and clocking the shift register. Refer to Clock Generation – Baud-Rate Generator for more details. In SPI slave operation (CTRLA.MODE is 0x2), the clock is provided by an external master on the SCK pin. This clock is used to directly clock the SPI shift register. Related Links 34.6.2.3 Clock Generation – Baud-Rate Generator 34.6.2.3.1 Asynchronous Arithmetic Mode BAUD Value Selection 36.6.2.4 Data Register The SPI Transmit Data register (TxDATA) and SPI Receive Data register (RxDATA) share the same I/O address, referred to as the SPI Data register (DATA). Writing DATA register will update the Transmit Data register. Reading the DATA register will return the contents of the Receive Data register. 36.6.2.5 SPI Transfer Modes There are four combinations of SCK phase and polarity to transfer serial data. The SPI data transfer modes are shown in SPI Transfer Modes (Table) and SPI Transfer Modes (Figure). SCK phase is configured by the Clock Phase bit in the CTRLA register (CTRLA.CPHA). SCK polarity is programmed by the Clock Polarity bit in the CTRLA register (CTRLA.CPOL). Data bits are shifted out and latched in on opposite edges of the SCK signal. This ensures sufficient time for the data signals to stabilize. Table 36-3. SPI Transfer Modes Mode CPOL CPHA 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 Note:  Leading edge is the first clock edge in a clock cycle. Trailing edge is the second clock edge in a clock cycle. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 783 Figure 36-3. SPI Transfer Modes 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) 36.6.2.6 Transferring Data 36.6.2.6.1 Master In master mode (CTRLA.MODE=0x3), when Master Slave Enable Select (CTRLB.MSSEN) is ‘1’, hardware will control the SS line. When Master Slave Select Enable (CTRLB.MSSEN) is '0', the SS line must be configured as an output. SS can be assigned to any general purpose I/O pin. When the SPI is ready for a data transaction, software must pull the SS line low. When writing a character to the Data register (DATA), the character will be transferred to the shift register. Once the content of TxDATA has been transferred to the shift register, the Data Register Empty flag in the Interrupt Flag Status and Clear register (INTFLAG.DRE) will be set. And a new character can be written to DATA. Each time one character is shifted out from the master, another character will be shifted in from the slave simultaneously. If the receiver is enabled (CTRLA.RXEN=1), the contents of the shift register will be SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 784 transferred to the two-level or four-level receive buffer. The transfer takes place in the same clock cycle as the last data bit is shifted in. And the Receive Complete Interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG.RXC) will be set. The received data can be retrieved by reading DATA. When the last character has been transmitted and there is no valid data in DATA, the Transmit Complete Interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG.TXC) will be set. When the transaction is finished, the master must pull the SS line high to notify the slave. If Master Slave Select Enable (CTRLB.MSSEN) is set to '0', the software must pull the SS line high. 36.6.2.6.2 Slave In slave mode (CTRLA.MODE=0x2), the SPI interface will remain inactive with the MISO line tri-stated as long as the SS pin is pulled high. Software may update the contents of DATA at any time as long as the Data Register Empty flag in the Interrupt Status and Clear register (INTFLAG.DRE) is set. When SS is pulled low and SCK is running, the slave will sample and shift out data according to the transaction mode set. When the content of TxDATA has been loaded into the shift register, INTFLAG.DRE will be set, and new data can be written to DATA. Similar to the master, the slave will receive one character for each character transmitted. A character will be transferred into the two-level or four-level receive buffer within the same clock cycle its last data bit is received. The received character can be retrieved from DATA when the Receive Complete interrupt flag (INTFLAG.RXC) is set. When the master pulls the SS line high, the transaction is done and the Transmit Complete Interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG.TXC) will be set. After DATA is written it takes up to three SCK clock cycles until the content of DATA is ready to be loaded into the shift register on the next character boundary. As a consequence, the first character transferred in a SPI transaction will not be the content of DATA. This can be avoided by using the preloading feature. Refer to 36.6.3.2 Preloading of the Slave Shift Register. When transmitting several characters in one SPI transaction, the data has to be written into DATA register with at least three SCK clock cycles left in the current character transmission. If this criteria is not met, the previously received character will be transmitted. Once the DATA register is empty, it takes three CLK_SERCOM_APB cycles for INTFLAG.DRE to be set. 36.6.2.7 Receiver Error Bit The SPI receiver has one error bit: the Buffer Overflow bit (BUFOVF), which can be read from the Status register (STATUS). Once an error happens, the bit will stay set until it is cleared by writing '1' to it. The bit is also automatically cleared when the receiver is disabled. There are two methods for buffer overflow notification, selected by the immediate buffer overflow notification bit in the Control A register (CTRLA.IBON): If CTRLA.IBON=1, STATUS.BUFOVF is raised immediately upon buffer overflow. Software can then empty the receive FIFO by reading RxDATA until the receiver complete interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG.RXC) goes low. If CTRLA.IBON=0, the buffer overflow condition travels with data through the receive FIFO. After the received data is read, STATUS.BUFOVF and INTFLAG.ERROR will be set along with INTFLAG.RXC, and RxDATA will be zero. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 785 36.6.3 Additional Features 36.6.3.1 Address Recognition When the SPI is configured for slave operation (CTRLA.MODE=0x2) with address recognition (CTRLA.FORM is 0x2), the SERCOM address recognition logic is enabled: the first character in a transaction is checked for an address match. If there is a match, the Receive Complete Interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG.RXC) is set, the MISO output is enabled, and the transaction is processed. If the device is in sleep mode, an address match can wake up the device in order to process the transaction. If there is no match, the complete transaction is ignored. If a 9-bit frame format is selected, only the lower 8 bits of the shift register are checked against the Address register (ADDR). Preload must be disabled (CTRLB.PLOADEN=0) in order to use this mode. Related Links 34.6.3.1 Address Match and Mask 36.6.3.2 Preloading of the Slave Shift Register When starting a transaction, the slave will first transmit the contents of the shift register before loading new data from DATA. The first character sent can be either the reset value of the shift register (if this is the first transmission since the last reset) or the last character in the previous transmission. Preloading can be used to preload data into the shift register while SS is high: this eliminates sending a dummy character when starting a transaction. If the shift register is not preloaded, the current contents of the shift register will be shifted out. Only one data character will be preloaded into the shift register while the synchronized SS signal is high. If the next character is written to DATA before SS is pulled low, the second character will be stored in DATA until transfer begins. For proper preloading, sufficient time must elapse between SS going low and the first SCK sampling edge, as in Timing Using Preloading. See also the Electrical Characteristics chapters for timing details. Preloading is enabled by writing '1' to the Slave Data Preload Enable bit in the CTRLB register (CTRLB.PLOADEN). Figure 36-4. Timing Using Preloading _SS _SS synchronized to system domain SCK Synchronization to system domain MISO to SCK setup time Required _SS-to-SCK time using PRELOADEN 36.6.3.3 Master with Several Slaves Master with multiple slaves in parallel is only available when Master Slave Select Enable (CTRLB.MSSEN) is set to zero and hardware SS control is disabled. If the bus consists of several SPI SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 786 slaves, an SPI master can use general purpose I/O pins to control the SS line to each of the slaves on the bus, as shown in Multiple Slaves in Parallel. In this configuration, the single selected SPI slave will drive the tri-state MISO line. Figure 36-5. Multiple Slaves in Parallel MOSI MISO SCK _SS MOSI MISO SCK _SS[0] MOSI MISO SCK _SS _SS[n-1] shift register shift register shift register SPI Master SPI Slave 0 SPI Slave n-1 Another configuration is multiple slaves in series, as in Multiple Slaves in Series. In this configuration, all n attached slaves are connected in series. A common SS line is provided to all slaves, enabling them simultaneously. The master must shift n characters for a complete transaction. Depending on the Master Slave Select Enable bit (CTRLB.MSSEN), the SS line can be controlled either by hardware or user software and normal GPIO. Figure 36-6. Multiple Slaves in Series MOSI MISO SCK _SS MOSI MISO SCK _SS MOSI MISO SCK _SS shift register shift register shift register SPI Master SPI Slave 0 SPI Slave n-1 36.6.3.4 Loop-Back Mode For loop-back mode, configure the Data In Pinout (CTRLA.DIPO) and Data Out Pinout (CTRLA.DOPO) to use the same data pins for transmit and receive. The loop-back is through the pad, so the signal is also available externally. 36.6.3.5 Hardware Controlled SS In master mode, a single SS chip select can be controlled by hardware by writing the Master Slave Select Enable (CTRLB.MSSEN) bit to '1'. In this mode, the SS pin is driven low for a minimum of one baud cycle before transmission begins, and stays low for a minimum of one baud cycle after transmission completes. If back-to-back frames are transmitted, the SS pin will always be driven high for a minimum of one baud cycle between frames. In Hardware Controlled SS, the time T is between one and two baud cycles depending on the SPI transfer mode. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 787 Figure 36-7. Hardware Controlled SS _SS SCK T T = 1 to 2 baud cycles T T T T When CTRLB.MSSEN=0, the SS pin(s) is/are controlled by user software and normal GPIO. 36.6.3.6 Slave Select Low Detection In slave mode, the SPI can wake the CPU when the slave select (SS) goes low. When the Slave Select Low Detect is enabled (CTRLB.SSDE=1), a high-to-low transition will set the Slave Select Low interrupt flag (INTFLAG.SSL) and the device will wake up if applicable. 36.6.4 DMA, Interrupts, and Events Table 36-4. Module Request for SERCOM SPI Condition Request DMA Interrupt Event Data Register Empty (DRE) Yes (request cleared when data is written) Yes NA Receive Complete (RXC) Yes (request cleared when data is read) Yes Transmit Complete (TXC) NA Yes Slave Select low (SSL) NA Yes Error (ERROR) NA Yes 36.6.4.1 DMA Operation The SPI generates the following DMA requests: • Data received (RX): The request is set when data is available in the receive FIFO. The request is cleared when DATA is read. • Data transmit (TX): The request is set when the transmit buffer (TX DATA) is empty. The request is cleared when DATA is written. 36.6.4.2 Interrupts The SPI has the following interrupt sources. These are asynchronous interrupts, and can wake up the device from any sleep mode: • Data Register Empty (DRE) • Receive Complete (RXC) • Transmit Complete (TXC) • Slave Select Low (SSL) • Error (ERROR) SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 788 Each interrupt source has its own interrupt flag. The interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG) will be set when the interrupt condition is met. Each interrupt can be individually enabled by writing '1' to the corresponding bit in the Interrupt Enable Set register (INTENSET), and disabled by writing '1' to the corresponding bit in the Interrupt Enable Clear register (INTENCLR). An interrupt request is generated when the interrupt flag is set and if the corresponding interrupt is enabled. The interrupt request remains active until either the interrupt flag is cleared, the interrupt is disabled, or the SPI is reset. For details on clearing interrupt flags, refer to the INTFLAG register description. The value of INTFLAG indicates which interrupt is executed. Note that interrupts must be globally enabled for interrupt requests. Refer to Nested Vector Interrupt Controller for details. 36.6.4.3 Events Not applicable. 36.6.5 Sleep Mode Operation The behavior in Sleep mode is depending on the master/slave configuration and the Run In Standby bit in the Control A register (CTRLA.RUNSTDBY): • Master operation, CTRLA.RUNSTDBY=1: The peripheral clock GCLK_SERCOM_CORE will continue to run in idle sleep mode and in Standby Sleep mode. Any interrupt can wake up the device. • Master operation, CTRLA.RUNSTDBY=0: GLK_SERCOMx_CORE will be disabled after the ongoing transaction is finished. Any interrupt can wake up the device. • Slave operation, CTRLA.RUNSTDBY=1: The Receive Complete interrupt can wake up the device. • Slave operation, CTRLA.RUNSTDBY=0: All reception will be dropped, including the ongoing transaction. 36.6.6 Synchronization Due to asynchronicity between the main clock domain and the peripheral clock domains, some registers need to be synchronized when written or read. The following bits are synchronized when written: • Software Reset bit in the CTRLA register (CTRLA.SWRST) • Enable bit in the CTRLA register (CTRLA.ENABLE) • Receiver Enable bit in the CTRLB register (CTRLB.RXEN) Note:  CTRLB.RXEN is write-synchronized somewhat differently. See also CTRLB register for details. Required write-synchronization is denoted by the "Write-Synchronized" property in the register description. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 789 36.7 Register Summary Offset Name Bit Pos. 0x00 CTRLA 7:0 RUNSTDBY MODE[2:0] ENABLE SWRST 15:8 IBON 23:16 DIPO[1:0] DOPO[1:0] 31:24 DORD CPOL CPHA FORM[3:0] 0x04 CTRLB 7:0 PLOADEN CHSIZE[2:0] 15:8 AMODE[1:0] MSSEN SSDE 23:16 RXEN 31:24 0x08 ... 0x0B Reserved 0x0C BAUD 7:0 BAUD[7:0] 0x0D ... 0x13 Reserved 0x14 INTENCLR 7:0 ERROR SSL RXC TXC DRE 0x15 Reserved 0x16 INTENSET 7:0 ERROR SSL RXC TXC DRE 0x17 Reserved 0x18 INTFLAG 7:0 ERROR SSL RXC TXC DRE 0x19 Reserved 0x1A STATUS 7:0 BUFOVF 15:8 0x1C SYNCBUSY 7:0 CTRLB ENABLE SWRST 15:8 23:16 31:24 0x20 ... 0x23 Reserved 0x24 ADDR 7:0 ADDR[7:0] 15:8 23:16 ADDRMASK[7:0] 31:24 0x28 DATA 7:0 DATA[7:0] 15:8 DATA[8:8] 0x2A ... 0x2F Reserved 0x30 DBGCTRL 7:0 DBGSTOP SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 790 36.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16-, and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers require synchronization when read and/or written. Synchronization is denoted by the "Read-Synchronized" and/or "Write-Synchronized" property in each individual register description. Refer to 36.6.6 Synchronization Some registers are enable-protected, meaning they can only be written when the module is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. Refer to 36.5.8 Register Access Protection. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 791 36.8.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 DORD CPOL CPHA FORM[3:0] Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DIPO[1:0] DOPO[1:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 IBON Access R/W Reset 0 Bit 7 6 5 4 3 2 1 0 RUNSTDBY MODE[2:0] ENABLE SWRST Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 30 – DORD Data Order This bit selects the data order when a character is shifted out from the shift register. This bit is not synchronized. Value Description 0 MSB is transferred first. 1 LSB is transferred first. Bit 29 – CPOL Clock Polarity In combination with the Clock Phase bit (CPHA), this bit determines the SPI transfer mode. This bit is not synchronized. Value Description 0 SCK is low when idle. The leading edge of a clock cycle is a rising edge, while the trailing edge is a falling edge. 1 SCK is high when idle. The leading edge of a clock cycle is a falling edge, while the trailing edge is a rising edge. Bit 28 – CPHA Clock Phase In combination with the Clock Polarity bit (CPOL), this bit determines the SPI transfer mode. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 792 This bit is not synchronized. Mode CPOL CPHA Leading Edge Trailing Edge 0x0 0 0 Rising, sample Falling, change 0x1 0 1 Rising, change Falling, sample 0x2 1 0 Falling, sample Rising, change 0x3 1 1 Falling, change Rising, sample Value Description 0 The data is sampled on a leading SCK edge and changed on a trailing SCK edge. 1 The data is sampled on a trailing SCK edge and changed on a leading SCK edge. Bits 27:24 – FORM[3:0] Frame Format This bit field selects the various frame formats supported by the SPI in slave mode. When the 'SPI frame with address' format is selected, the first byte received is checked against the ADDR register. FORM[3:0] Name Description 0x0 SPI SPI frame 0x1 - Reserved 0x2 SPI_ADDR SPI frame with address 0x3-0xF - Reserved Bits 21:20 – DIPO[1:0] Data In Pinout These bits define the data in (DI) pad configurations. In master operation, DI is MISO. In slave operation, DI is MOSI. These bits are not synchronized. DIPO[1:0] Name Description 0x0 PAD[0] SERCOM PAD[0] is used as data input 0x1 PAD[1] SERCOM PAD[1] is used as data input 0x2 PAD[2] SERCOM PAD[2] is used as data input 0x3 PAD[3] SERCOM PAD[3] is used as data input Bits 17:16 – DOPO[1:0] Data Out Pinout This bit defines the available pad configurations for data out (DO) and the serial clock (SCK). In slave operation, the slave select line (SS) is controlled by DOPO, while in master operation the SS line is controlled by the port configuration. In master operation, DO is MOSI. In slave operation, DO is MISO. These bits are not synchronized. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 793 DOPO DO SCK Slave SS Master SS 0x0 PAD[0] PAD[1] PAD[2] System configuration 0x1 PAD[2] PAD[3] PAD[1] System configuration 0x2 PAD[3] PAD[1] PAD[2] System configuration 0x3 PAD[0] PAD[3] PAD[1] System configuration Bit 8 – IBON Immediate Buffer Overflow Notification This bit controls when the buffer overflow status bit (STATUS.BUFOVF) is set when a buffer overflow occurs. This bit is not synchronized. Value Description 0 STATUS.BUFOVF is set when it occurs in the data stream. 1 STATUS.BUFOVF is set immediately upon buffer overflow. Bit 7 – RUNSTDBY Run In Standby This bit defines the functionality in standby sleep mode. These bits are not synchronized. RUNSTDBY Slave Master 0x0 Disabled. All reception is dropped, including the ongoing transaction. Generic clock is disabled when ongoing transaction is finished. All interrupts can wake up the device. 0x1 Ongoing transaction continues, wake on Receive Complete interrupt. Generic clock is enabled while in sleep modes. All interrupts can wake up the device. Bits 4:2 – MODE[2:0] Operating Mode These bits must be written to 0x2 or 0x3 to select the SPI serial communication interface of the SERCOM. 0x2: SPI slave operation 0x3: SPI master operation These bits are not synchronized. Bit 1 – ENABLE Enable Due to synchronization, there is delay from writing CTRLA.ENABLE until the peripheral is enabled/ disabled. The value written to CTRL.ENABLE will read back immediately and the Synchronization Enable Busy bit in the Synchronization Busy register (SYNCBUSY.ENABLE) will be set. SYNCBUSY.ENABLE is cleared when the operation is complete. This bit is not enable-protected. Value Description 0 The peripheral is disabled or being disabled. 1 The peripheral is enabled or being enabled. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 794 Bit 0 – SWRST Software Reset Writing '0' to this bit has no effect. Writing '1' to this bit resets all registers in the SERCOM, except DBGCTRL, to their initial state, and the SERCOM will be disabled. Writing ''1' to CTRL.SWRST will always take precedence, meaning that all other writes in the same writeoperation will be discarded. Any register write access during the ongoing reset will result in an APB error. Reading any register will return the reset value of the register. Due to synchronization, there is a delay from writing CTRLA.SWRST until the reset is complete. CTRLA.SWRST and SYNCBUSY. SWRST will both be cleared when the reset is complete. This bit is not enable-protected. Value Description 0 There is no reset operation ongoing. 1 The reset operation is ongoing. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 795 36.8.2 Control B Name:  CTRLB Offset:  0x04 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 RXEN Access R/W Reset 0 Bit 15 14 13 12 11 10 9 8 AMODE[1:0] MSSEN SSDE Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 6 5 4 3 2 1 0 PLOADEN CHSIZE[2:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 17 – RXEN Receiver Enable Writing '0' to this bit will disable the SPI receiver immediately. The receive buffer will be flushed, data from ongoing receptions will be lost and STATUS.BUFOVF will be cleared. Writing '1' to CTRLB.RXEN when the SPI is disabled will set CTRLB.RXEN immediately. When the SPI is enabled, CTRLB.RXEN will be cleared, SYNCBUSY.CTRLB will be set and remain set until the receiver is enabled. When the receiver is enabled CTRLB.RXEN will read back as '1'. Writing '1' to CTRLB.RXEN when the SPI is enabled will set SYNCBUSY.CTRLB, which will remain set until the receiver is enabled, and CTRLB.RXEN will read back as '1'. This bit is not enable-protected. Value Description 0 The receiver is disabled or being enabled. 1 The receiver is enabled or it will be enabled when SPI is enabled. Bits 15:14 – AMODE[1:0] Address Mode These bits set the slave addressing mode when the frame format (CTRLA.FORM) with address is used. They are unused in master mode. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 796 AMODE[1:0] Name Description 0x0 MASK ADDRMASK is used as a mask to the ADDR register 0x1 2_ADDRS The slave responds to the two unique addresses in ADDR and ADDRMASK 0x2 RANGE The slave responds to the range of addresses between and including ADDR and ADDRMASK. ADDR is the upper limit 0x3 - Reserved Bit 13 – MSSEN Master Slave Select Enable This bit enables hardware slave select (SS) control. Value Description 0 Hardware SS control is disabled. 1 Hardware SS control is enabled. Bit 9 – SSDE Slave Select Low Detect Enable This bit enables wake up when the slave select (SS) pin transitions from high to low. Value Description 0 SS low detector is disabled. 1 SS low detector is enabled. Bit 6 – PLOADEN Slave Data Preload Enable Setting this bit will enable preloading of the slave shift register when there is no transfer in progress. If the SS line is high when DATA is written, it will be transferred immediately to the shift register. Bits 2:0 – CHSIZE[2:0] Character Size CHSIZE[2:0] Name Description 0x0 8BIT 8 bits 0x1 9BIT 9 bits 0x2-0x7 - Reserved SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 797 36.8.3 Baud Rate Name:  BAUD Offset:  0x0C Reset:  0x00 Property:  PAC Write-Protection, Enable-Protected Bit 7 6 5 4 3 2 1 0 BAUD[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 7:0 – BAUD[7:0] Baud Register These bits control the clock generation, as described in the SERCOM Clock Generation – Baud-Rate Generator. Related Links 34.6.2.3 Clock Generation – Baud-Rate Generator 34.6.2.3.1 Asynchronous Arithmetic Mode BAUD Value Selection SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 798 36.8.4 Interrupt Enable Clear Name:  INTENCLR Offset:  0x14 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 7 6 5 4 3 2 1 0 ERROR SSL RXC TXC DRE Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 7 – ERROR Error Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Error Interrupt Enable bit, which disables the Error interrupt. Value Description 0 Error interrupt is disabled. 1 Error interrupt is enabled. Bit 3 – SSL Slave Select Low Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Slave Select Low Interrupt Enable bit, which disables the Slave Select Low interrupt. Value Description 0 Slave Select Low interrupt is disabled. 1 Slave Select Low interrupt is enabled. Bit 2 – RXC Receive Complete Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Receive Complete Interrupt Enable bit, which disables the Receive Complete interrupt. Value Description 0 Receive Complete interrupt is disabled. 1 Receive Complete interrupt is enabled. Bit 1 – TXC Transmit Complete Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Transmit Complete Interrupt Enable bit, which disable the Transmit Complete interrupt. Value Description 0 Transmit Complete interrupt is disabled. 1 Transmit Complete interrupt is enabled. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 799 Bit 0 – DRE Data Register Empty Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Data Register Empty Interrupt Enable bit, which disables the Data Register Empty interrupt. Value Description 0 Data Register Empty interrupt is disabled. 1 Data Register Empty interrupt is enabled. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 800 36.8.5 Interrupt Enable Set Name:  INTENSET Offset:  0x16 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear register (INTENCLR). Bit 7 6 5 4 3 2 1 0 ERROR SSL RXC TXC DRE Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 7 – ERROR Error Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Error Interrupt Enable bit, which enables the Error interrupt. Value Description 0 Error interrupt is disabled. 1 Error interrupt is enabled. Bit 3 – SSL Slave Select Low Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Slave Select Low Interrupt Enable bit, which enables the Slave Select Low interrupt. Value Description 0 Slave Select Low interrupt is disabled. 1 Slave Select Low interrupt is enabled. Bit 2 – RXC Receive Complete Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Receive Complete Interrupt Enable bit, which enables the Receive Complete interrupt. Value Description 0 Receive Complete interrupt is disabled. 1 Receive Complete interrupt is enabled. Bit 1 – TXC Transmit Complete Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Transmit Complete Interrupt Enable bit, which enables the Transmit Complete interrupt. Value Description 0 Transmit Complete interrupt is disabled. 1 Transmit Complete interrupt is enabled. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 801 Bit 0 – DRE Data Register Empty Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Data Register Empty Interrupt Enable bit, which enables the Data Register Empty interrupt. Value Description 0 Data Register Empty interrupt is disabled. 1 Data Register Empty interrupt is enabled. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 802 36.8.6 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x18 Reset:  0x00 Property:  - Bit 7 6 5 4 3 2 1 0 ERROR SSL RXC TXC DRE Access R/W R/W R R/W R Reset 0 0 0 0 0 Bit 7 – ERROR Error This flag is cleared by writing '1' to it. This bit is set when any error is detected. Errors that will set this flag have corresponding status flags in the STATUS register. The BUFOVF error will set this interrupt flag. Writing '0' to this bit has no effect. Writing '1' to this bit will clear the flag. Bit 3 – SSL Slave Select Low This flag is cleared by writing '1' to it. This bit is set when a high to low transition is detected on the _SS pin in slave mode and Slave Select Low Detect (CTRLB.SSDE) is enabled. Writing '0' to this bit has no effect. Writing '1' to this bit will clear the flag. Bit 2 – RXC Receive Complete This flag is cleared by reading the Data (DATA) register or by disabling the receiver. This flag is set when there are unread data in the receive buffer. If address matching is enabled, the first data received in a transaction will be an address. Writing '0' to this bit has no effect. Writing '1' to this bit has no effect. Bit 1 – TXC Transmit Complete This flag is cleared by writing '1' to it or by writing new data to DATA. In master mode, this flag is set when the data have been shifted out and there are no new data in DATA. In slave mode, this flag is set when the _SS pin is pulled high. If address matching is enabled, this flag is only set if the transaction was initiated with an address match. Writing '0' to this bit has no effect. Writing '1' to this bit will clear the flag. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 803 Bit 0 – DRE Data Register Empty This flag is cleared by writing new data to DATA. This flag is set when DATA is empty and ready for new data to transmit. Writing '0' to this bit has no effect. Writing '1' to this bit has no effect. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 804 36.8.7 Status Name:  STATUS Offset:  0x1A Reset:  0x0000 Property:  – Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 BUFOVF Access R/W Reset 0 Bit 2 – BUFOVF Buffer Overflow Reading this bit before reading DATA will indicate the error status of the next character to be read. This bit is cleared by writing '1' to the bit or by disabling the receiver. This bit is set when a buffer overflow condition is detected. See also CTRLA.IBON for overflow handling. When set, the corresponding RxDATA will be zero. Writing '0' to this bit has no effect. Writing '1' to this bit will clear it. Value Description 0 No Buffer Overflow has occurred. 1 A Buffer Overflow has occurred. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 805 36.8.8 Synchronization Busy Name:  SYNCBUSY Offset:  0x1C Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 CTRLB ENABLE SWRST Access R R R Reset 0 0 0 Bit 2 – CTRLB CTRLB Synchronization Busy Writing to the CTRLB when the SERCOM is enabled requires synchronization. Ongoing synchronization is indicated by SYNCBUSY.CTRLB=1 until synchronization is complete. If CTRLB is written while SYNCBUSY.CTRLB=1, an APB error will be generated. Value Description 0 CTRLB synchronization is not busy. 1 CTRLB synchronization is busy. Bit 1 – ENABLE SERCOM Enable Synchronization Busy Enabling and disabling the SERCOM (CTRLA.ENABLE) requires synchronization. Ongoing synchronization is indicated by SYNCBUSY.ENABLE=1 until synchronization is complete. Value Description 0 Enable synchronization is not busy. 1 Enable synchronization is busy. Bit 0 – SWRST Software Reset Synchronization Busy Resetting the SERCOM (CTRLA.SWRST) requires synchronization. Ongoing synchronization is indicated by SYNCBUSY.SWRST=1 until synchronization is complete. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 806 Value Description 0 SWRST synchronization is not busy. 1 SWRST synchronization is busy. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 807 36.8.9 Address Name:  ADDR Offset:  0x24 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 ADDRMASK[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 ADDR[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 23:16 – ADDRMASK[7:0] Address Mask These bits hold the address mask when the transaction format with address is used (CTRLA.FORM, CTRLB.AMODE). Bits 7:0 – ADDR[7:0] Address These bits hold the address when the transaction format with address is used (CTRLA.FORM, CTRLB.AMODE). SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 808 36.8.10 Data Name:  DATA Offset:  0x28 Reset:  0x0000 Property:  – Bit 15 14 13 12 11 10 9 8 DATA[8:8] Access R/W Reset 0 Bit 7 6 5 4 3 2 1 0 DATA[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 8:0 – DATA[8:0] Data Reading these bits will return the contents of the receive data buffer. The register should be read only when the Receive Complete Interrupt Flag bit in the Interrupt Flag Status and Clear register (INTFLAG.RXC) is set. Writing these bits will write the transmit data buffer. This register should be written only when the Data Register Empty Interrupt Flag bit in the Interrupt Flag Status and Clear register (INTFLAG.DRE) is set. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 809 36.8.11 Debug Control Name:  DBGCTRL Offset:  0x30 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DBGSTOP Access R/W Reset 0 Bit 0 – DBGSTOP Debug Stop Mode This bit controls the functionality when the CPU is halted by an external debugger. Value Description 0 The baud-rate generator continues normal operation when the CPU is halted by an external debugger. 1 The baud-rate generator is halted when the CPU is halted by an external debugger. SAM L10/L11 Family SERCOM SPI – SERCOM Serial Peripheral Interface © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 810 37. SERCOM I2C – SERCOM Inter-Integrated Circuit 37.1 Overview The inter-integrated circuit ( I2C) interface is one of the available modes in the serial communication interface (SERCOM). The I2C interface uses the SERCOM transmitter and receiver configured as shown in Figure 37-1. Labels in capital letters are registers accessible by the CPU, while lowercase labels are internal to the SERCOM. A SERCOM instance can be configured to be either an I2C master or an I2C slave. Both master and slave have an interface containing a shift register, a transmit buffer and a receive buffer. In addition, the I2C master uses the SERCOM baud-rate generator, while the I2C slave uses the SERCOM address match logic. Related Links 34. SERCOM – Serial Communication Interface 37.2 Features SERCOM I2C includes the following features: • Master or slave operation • Can be used with DMA • Philips I2C compatible • SMBus™ compatible • PMBus compatible • Support of 100kHz and 400kHz, 1MHz and 3.4MHz I2C mode • 4-Wire operation supported • Physical interface includes: – Slew-rate limited outputs – Filtered inputs • Slave operation: – Operation in all sleep modes – Wake-up on address match – 7-bit and 10-bit Address match in hardware for: – • Unique address and/or 7-bit general call address • Address range • Two unique addresses can be used with DMA Related Links 34.2 Features SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 811 37.3 Block Diagram Figure 37-1. I2C Single-Master Single-Slave Interconnection BAUD TxDATA RxDATA baud rate generator SCL hold low shift register TxDATA RxDATA shift register 0 0 0 0 SCL hold low ADDR/ADDRMASK == SDA SCL Master Slave 37.4 Signal Description Signal Name Type Description PAD[0] Digital I/O SDA PAD[1] Digital I/O SCL PAD[2] Digital I/O SDA_OUT (4-wire operation) PAD[3] Digital I/O SCL_OUT (4-wire operation) One signal can be mapped on several pins. Not all the pins are I2C pins. Related Links 37.6.3.3 4-Wire Mode 37.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 37.5.1 I/O Lines In order to use the I/O lines of this peripheral, the I/O pins must be configured using the I/O Pin Controller (PORT). When the SERCOM is used in I2C mode, the SERCOM controls the direction and value of the I/O pins. Both PORT control bits PINCFGn.PULLEN and PINCFGn.DRVSTR are still effective. If the receiver or transmitter is disabled, these pins can be used for other purposes. Related Links 32. PORT - I/O Pin Controller SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 812 37.5.2 Power Management This peripheral can continue to operate in any sleep mode where its source clock is running. The interrupts can wake up the device from sleep modes. Related Links 22. PM – Power Manager 37.5.3 Clocks The SERCOM bus clock (CLK_SERCOMx_APB) can be enabled and disabled in the Main Clock Controller. Refer to Peripheral Clock Masking for details and default status of this clock. Two generic clocks are used by SERCOM, GCLK_SERCOMx_CORE and GCLK_SERCOM_SLOW. The core clock (GCLK_SERCOMx_CORE) can clock the I2C when working as a master. The slow clock (GCLK_SERCOM_SLOW) is required only for certain functions, e.g. SMBus timing. These two clocks must be configured and enabled in the Generic Clock Controller (GCLK) before using the I2C. These generic clocks are asynchronous to the bus clock (CLK_SERCOMx_APB). Due to this asynchronicity, writes to certain registers will require synchronization between the clock domains. Refer to 37.6.6 Synchronization for further details. Related Links 18. GCLK - Generic Clock Controller 19.6.2.6 Peripheral Clock Masking 22. PM – Power Manager 37.5.4 DMA The DMA request lines are connected to the DMA Controller (DMAC). In order to use DMA requests with this peripheral the DMAC must be configured first. Refer to DMAC – Direct Memory Access Controller for details. Related Links 28. DMAC – Direct Memory Access Controller 37.5.5 Interrupts The interrupt request line is connected to the Interrupt Controller. In order to use interrupt requests of this peripheral, the Interrupt Controller (NVIC) must be configured first. Refer to Nested Vector Interrupt Controller for details. 37.5.6 Events Not applicable. 37.5.7 Debug Operation When the CPU is halted in debug mode, this peripheral will continue normal operation. If the peripheral is configured to require periodical service by the CPU through interrupts or similar, improper operation or data loss may result during debugging. This peripheral can be forced to halt operation during debugging - refer to the Debug Control (DBGCTRL) register for details. 37.5.8 Register Access Protection Registers with write-access can be write-protected optionally by the peripheral access controller (PAC). PAC Write-Protection is not available for the following registers: SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 813 • Interrupt Flag Clear and Status register (INTFLAG) • Status register (STATUS) • Data register (DATA) • Address register (ADDR) Optional PAC Write-Protection is denoted by the "PAC Write-Protection" property in each individual register description. Write-protection does not apply to accesses through an external debugger. Related Links 15. PAC - Peripheral Access Controller 37.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 37.5.10 Analog Connections Not applicable. 37.6 Functional Description 37.6.1 Principle of Operation The I2C interface uses two physical lines for communication: • Serial Data Line (SDA) for data transfer • Serial Clock Line (SCL) for the bus clock A transaction starts with the I2C master sending the start condition, followed by a 7-bit address and a direction bit (read or write to/from the slave). The addressed I2C slave will then acknowledge (ACK) the address, and data packet transactions can begin. Every 9-bit data packet consists of 8 data bits followed by a one-bit reply indicating whether the data was acknowledged or not. If a data packet is not acknowledged (NACK), whether by the I2C slave or master, the I2C master takes action by either terminating the transaction by sending the stop condition, or by sending a repeated start to transfer more data. The figure below illustrates the possible transaction formats and Transaction Diagram Symbols explains the transaction symbols. These symbols will be used in the following descriptions. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 814 Figure 37-2. Transaction Diagram Symbols S Sr A A R W P START condition repeated START condition STOP condition Master driving bus Slave driving bus Either Master or Slave driving bus Acknowledge (ACK) Not Acknowledge (NACK) Master Read Master Write Bus Driver Special Bus Conditions Data Package Direction Acknowledge '1' '0' '0' '1' Figure 37-3. Basic I2C Transaction Diagram SDA SCL S ADDRESS R/W ACK DATA ACK DATA ACK/NACK 6..0 7..0 7..0 P S ADDRESS R/W A DATA A DATA A/A P Direction Address Packet Data Packet #0 Data Packet #1 Transaction 37.6.2 Basic Operation 37.6.2.1 Initialization The following registers are enable-protected, meaning they can be written only when the I2C interface is disabled (CTRLA.ENABLE is ‘0’): • Control A register (CTRLA), except Enable (CTRLA.ENABLE) and Software Reset (CTRLA.SWRST) bits • Control B register (CTRLB), except Acknowledge Action (CTRLB.ACKACT) and Command (CTRLB.CMD) bits • Baud register (BAUD) • Address register (ADDR) in slave operation. When the I2C is enabled or is being enabled (CTRLA.ENABLE=1), writing to these registers will be discarded. If the I2C is being disabled, writing to these registers will be completed after the disabling. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 815 Enable-protection is denoted by the "Enable-Protection" property in the register description. Before the I2C is enabled it must be configured as outlined by the following steps: 1. Select I2C Master or Slave mode by writing 0x4 (Slave mode) or 0x5 (Master mode) to the Operating Mode bits in the CTRLA register (CTRLA.MODE). 2. If desired, select the SDA Hold Time value in the CTRLA register (CTRLA.SDAHOLD). 3. If desired, enable smart operation by setting the Smart Mode Enable bit in the CTRLB register (CTRLB.SMEN). 4. If desired, enable SCL low time-out by setting the SCL Low Time-Out bit in the Control A register (CTRLA.LOWTOUT). 5. In Master mode: 5.1. Select the inactive bus time-out in the Inactive Time-Out bit group in the CTRLA register (CTRLA.INACTOUT). 5.2. Write the Baud Rate register (BAUD) to generate the desired baud rate. In Slave mode: 5.1. Configure the address match configuration by writing the Address Mode value in the CTRLB register (CTRLB.AMODE). 5.2. Set the Address and Address Mask value in the Address register (ADDR.ADDR and ADDR.ADDRMASK) according to the address configuration. 37.6.2.2 Enabling, Disabling, and Resetting This peripheral is enabled by writing '1' to the Enable bit in the Control A register (CTRLA.ENABLE), and disabled by writing '0' to it. Writing ‘1’ to the Software Reset bit in the Control A register (CTRLA.SWRST) will reset all registers of this peripheral to their initial states, except the DBGCTRL register, and the peripheral is disabled. 37.6.2.3 I 2C Bus State Logic The bus state logic includes several logic blocks that continuously monitor the activity on the I2C bus lines in all sleep modes with running GCLK_SERCOM_x clocks. The start and stop detectors and the bit counter are all essential in the process of determining the current bus state. The bus state is determined according to Bus State Diagram. Software can get the current bus state by reading the Master Bus State bits in the Status register (STATUS.BUSSTATE). The value of STATUS.BUSSTATE in the figure is shown in binary. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 816 Figure 37-4. Bus State Diagram RESET Write ADDR to generate Start Condition IDLE (0b01) Start Condition BUSY (0b11) Timeout or Stop Condition UNKNOWN (0b00) OWNER (0b10) Lost Arbitration Start Condition Repeated Write ADDR to generate Repeated Start Condition Stop Condition Timeout or Stop Condition The bus state machine is active when the I2C master is enabled. After the I2C master has been enabled, the bus state is UNKNOWN (0b00). From the UNKNOWN state, the bus will transition to IDLE (0b01) by either: • Forcing by writing 0b01 to STATUS.BUSSTATE • A stop condition is detected on the bus • If the inactive bus time-out is configured for SMBus compatibility (CTRLA.INACTOUT) and a timeout occurs. Note:  Once a known bus state is established, the bus state logic will not re-enter the UNKNOWN state. When the bus is IDLE it is ready for a new transaction. If a start condition is issued on the bus by another I 2C master in a multi-master setup, the bus becomes BUSY (0b11). The bus will re-enter IDLE either when a stop condition is detected, or when a time-out occurs (inactive bus time-out needs to be configured). If a start condition is generated internally by writing the Address bit group in the Address register (ADDR.ADDR) while IDLE, the OWNER state (0b10) is entered. If the complete transaction was performed without interference, i.e., arbitration was not lost, the I2C master can issue a stop condition, which will change the bus state back to IDLE. However, if a packet collision is detected while in OWNER state, the arbitration is assumed lost and the bus state becomes BUSY until a stop condition is detected. A repeated start condition will change the bus state only if arbitration is lost while issuing a repeated start. Note:  Violating the protocol may cause the I2C to hang. If this happens it is possible to recover from this state by a software reset (CTRLA.SWRST='1'). Related Links 37.10.1 CTRLA SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 817 37.6.2.4 I 2C Master Operation The I2C master is byte-oriented and interrupt based. The number of interrupts generated is kept at a minimum by automatic handling of most incidents. The software driver complexity and code size are reduced by auto-triggering of operations, and a special smart mode, which can be enabled by the Smart Mode Enable bit in the Control A register (CTRLA.SMEN). The I2C master has two interrupt strategies. When SCL Stretch Mode (CTRLA.SCLSM) is '0', SCL is stretched before or after the acknowledge bit . In this mode the I2C master operates according to Master Behavioral Diagram (SCLSM=0). The circles labelled "Mn" (M1, M2..) indicate the nodes the bus logic can jump to, based on software or hardware interaction. This diagram is used as reference for the description of the I2C master operation throughout the document. Figure 37-5. I2C Master Behavioral Diagram (SCLSM=0) BUSY P IDLE S BUSY Sr P M3 M3 M2 M2 M1 M1 R DATA Wait for IDLE ADDRESS W DATA A/A APPLICATION SW SW Sr P M3 M2 SW A BUSY M4 A/A A/A A/A M4 A IDLE IDLE Slave Bus INTERRUPT + SCL HOLD Master Bus INTERRUPT + SCL HOLD SW SW SW R/W BUSY SW Software interaction A A R/W BUSY M4 The master provides data on the bus Addressed slave provides data on the bus In the second strategy (CTRLA.SCLSM=1), interrupts only occur after the ACK bit, as in Master Behavioral Diagram (SCLSM=1). This strategy can be used when it is not necessary to check DATA before acknowledging. Note:  I2C High-speed (Hs) mode requires CTRLA.SCLSM=1. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 818 Figure 37-6.  I2C Master Behavioral Diagram (SCLSM=1) BUSY P IDLE S BUSY Sr P M3 M3 M2 M2 M1 M1 R DATA W DATA A/A APPLICATION SW SW Sr P M3 M2 SW BUSY M4 A/A M4 A IDLE IDLE Master Bus INTERRUPT + SCL HOLD SW SW SW R/W BUSY A A R/W BUSY M4 SW Software interaction The master provides data on the bus Addressed slave provides data on the bus Slave Bus INTERRUPT + SCL HOLD Wait for IDLE ADDRESS 37.6.2.4.1 Master Clock Generation The SERCOM peripheral supports several I2C bidirectional modes: • Standard mode (Sm) up to 100 kHz • Fast mode (Fm) up to 400 kHz • Fast mode Plus (Fm+) up to 1 MHz • High-speed mode (Hs) up to 3.4 MHz The Master clock configuration for Sm, Fm, and Fm+ are described in Clock Generation (Standard-Mode, Fast-Mode, and Fast-Mode Plus). For Hs, refer to Master Clock Generation (High-Speed Mode). Clock Generation (Standard-Mode, Fast-Mode, and Fast-Mode Plus) In I2C Sm, Fm, and Fm+ mode, the Master clock (SCL) frequency is determined as described in this section: The low (TLOW) and high (THIGH) times are determined by the Baud Rate register (BAUD), while the rise (TRISE) and fall (TFALL) times are determined by the bus topology. Because of the wired-AND logic of the bus, TFALL will be considered as part of TLOW. Likewise, TRISE will be in a state between TLOW and THIGH until a high state has been detected. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 819 Figure 37-7. SCL Timing TSU;STO THD;STA TBUF TFALL TLOW TRISE THIGH SCL SDA P S TSU;STA Sr The following parameters are timed using the SCL low time period TLOW. This comes from the Master Baud Rate Low bit group in the Baud Rate register (BAUD.BAUDLOW). When BAUD.BAUDLOW=0, or the Master Baud Rate bit group in the Baud Rate register (BAUD.BAUD) determines it. • TLOW – Low period of SCL clock • TSU;STO – Set-up time for stop condition • TBUF – Bus free time between stop and start conditions • THD;STA – Hold time (repeated) start condition • TSU;STA – Set-up time for repeated start condition • THIGH is timed using the SCL high time count from BAUD.BAUD • TRISE is determined by the bus impedance; for internal pull-ups. • TFALL is determined by the open-drain current limit and bus impedance; can typically be regarded as zero. The SCL frequency is given by: ݂SCL = 1 ܶLOW + ܶHIGH + ܶRISE When BAUD.BAUDLOW is zero, the BAUD.BAUD value is used to time both SCL high and SCL low. In this case the following formula will give the SCL frequency: ݂SCL = ݂GCLK 10 + 2ܣܤܷܦ݂ + GCLK ڄܶ RISE When BAUD.BAUDLOW is non-zero, the following formula determines the SCL frequency: ݂SCL = ݂GCLK RISE ܶڄ GCLKܱܹ + ݂ܮܦܷܣܤ + ܦܷܣܤ + 10 The following formulas can determine the SCL TLOW and THIGH times: ܶLOW = 5ܱܹ + ܮܦܷܣܤ ݂GCLK ܶHIGH = 5 + ܦܷܣܤ ݂GCLK SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 820 Note:  The I2C standard Fm+ (Fast-mode plus) requires a nominal high to low SCL ratio of 1:2, and BAUD should be set accordingly. At a minimum, BAUD.BAUD and/or BAUD.BAUDLOW must be nonzero. Startup Timing The minimum time between SDA transition and SCL rising edge is 6 APB cycles when the DATA register is written in smart mode. If a greater startup time is required due to long rise times, the time between DATA write and IF clear must be controlled by software. Note:  When timing is controlled by user, the Smart Mode cannot be enabled. Master Clock Generation (High-Speed Mode) For I2C Hs transfers, there is no SCL synchronization. Instead, the SCL frequency is determined by the GCLK_SERCOMx_CORE frequency (fGCLK) and the High-Speed Baud setting in the Baud register (BAUD.HSBAUD). When BAUD.HSBAUDLOW=0, the HSBAUD value will determine both SCL high and SCL low. In this case the following formula determines the SCL frequency. ݂SCL = ݂GCLK ܦܷܣܤ ܵܪ ڄ 2 + 2 When HSBAUDLOW is non-zero, the following formula determines the SCL frequency. ݂SCL = ݂GCLK ܹܱܮܦܷܣܤܵܪ + ܦܷܣܤ ܵܪ + 2 Note:  The I2C standard Hs (High-speed) requires a nominal high to low SCL ratio of 1:2, and HSBAUD should be set accordingly. At a minimum, BAUD.HSBAUD and/or BAUD.HSBAUDLOW must be nonzero. 37.6.2.4.2 Transmitting Address Packets The I2C master starts a bus transaction by writing the I2C slave address to ADDR.ADDR and the direction bit, as described in 37.6.1 Principle of Operation. If the bus is busy, the I2C master will wait until the bus becomes idle before continuing the operation. When the bus is idle, the I2C master will issue a start condition on the bus. The I2C master will then transmit an address packet using the address written to ADDR.ADDR. After the address packet has been transmitted by the I2C master, one of four cases will arise according to arbitration and transfer direction. Case 1: Arbitration lost or bus error during address packet transmission If arbitration was lost during transmission of the address packet, the Master on Bus bit in the Interrupt Flag Status and Clear register (INTFLAG.MB) and the Arbitration Lost bit in the Status register (STATUS.ARBLOST) are both set. Serial data output to SDA is disabled, and the SCL is released, which disables clock stretching. In effect the I2C master is no longer allowed to execute any operation on the bus until the bus is idle again. A bus error will behave similarly to the arbitration lost condition. In this case, the MB interrupt flag and Master Bus Error bit in the Status register (STATUS.BUSERR) are both set in addition to STATUS.ARBLOST. The Master Received Not Acknowledge bit in the Status register (STATUS.RXNACK) will always contain the last successfully received acknowledge or not acknowledge indication. In this case, software will typically inform the application code of the condition and then clear the interrupt flag before exiting the interrupt routine. No other flags have to be cleared at this moment, because all flags will be cleared automatically the next time the ADDR.ADDR register is written. Case 2: Address packet transmit complete – No ACK received If there is no I2C slave device responding to the address packet, then the INTFLAG.MB interrupt flag and STATUS.RXNACK will be set. The clock hold is active at this point, preventing further activity on the bus. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 821 The missing ACK response can indicate that the I2C slave is busy with other tasks or sleeping. Therefore, it is not able to respond. In this event, the next step can be either issuing a stop condition (recommended) or resending the address packet by a repeated start condition. When using SMBus logic, the slave must ACK the address. If there is no response, it means that the slave is not available on the bus. Case 3: Address packet transmit complete – Write packet, Master on Bus set If the I2C master receives an acknowledge response from the I2C slave, INTFLAG.MB will be set and STATUS.RXNACK will be cleared. The clock hold is active at this point, preventing further activity on the bus. In this case, the software implementation becomes highly protocol dependent. Three possible actions can enable the I2C operation to continue: • Initiate a data transmit operation by writing the data byte to be transmitted into DATA.DATA. • Transmit a new address packet by writing ADDR.ADDR. A repeated start condition will automatically be inserted before the address packet. • Issue a stop condition, consequently terminating the transaction. Case 4: Address packet transmit complete – Read packet, Slave on Bus set If the I2C master receives an ACK from the I2C slave, the I2C master proceeds to receive the next byte of data from the I2C slave. When the first data byte is received, the Slave on Bus bit in the Interrupt Flag register (INTFLAG.SB) will be set and STATUS.RXNACK will be cleared. The clock hold is active at this point, preventing further activity on the bus. In this case, the software implementation becomes highly protocol dependent. Three possible actions can enable the I2C operation to continue: • Let the I2C master continue to read data by acknowledging the data received. ACK can be sent by software, or automatically in smart mode. • Transmit a new address packet. • Terminate the transaction by issuing a stop condition. Note:  An ACK or NACK will be automatically transmitted if smart mode is enabled. The Acknowledge Action bit in the Control B register (CTRLB.ACKACT) determines whether ACK or NACK should be sent. 37.6.2.4.3 Transmitting Data Packets When an address packet with direction Master Write (see Figure 37-3) was transmitted successfully , INTFLAG.MB will be set. The I2C master will start transmitting data via the I2C bus by writing to DATA.DATA, and monitor continuously for packet collisions. I If a collision is detected, the I2C master will lose arbitration and STATUS.ARBLOST will be set. If the transmit was successful, the I2C master will receive an ACK bit from the I2C slave, and STATUS.RXNACK will be cleared. INTFLAG.MB will be set in both cases, regardless of arbitration outcome. It is recommended to read STATUS.ARBLOST and handle the arbitration lost condition in the beginning of the I2C Master on Bus interrupt. This can be done as there is no difference between handling address and data packet arbitration. STATUS.RXNACK must be checked for each data packet transmitted before the next data packet transmission can commence. The I2C master is not allowed to continue transmitting data packets if a NACK is received from the I2C slave. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 822 37.6.2.4.4 Receiving Data Packets (SCLSM=0) When INTFLAG.SB is set, the I2C master will already have received one data packet. The I2C master must respond by sending either an ACK or NACK. Sending a NACK may be unsuccessful when arbitration is lost during the transmission. In this case, a lost arbitration will prevent setting INTFLAG.SB. Instead, INTFLAG.MB will indicate a change in arbitration. Handling of lost arbitration is the same as for data bit transmission. 37.6.2.4.5 Receiving Data Packets (SCLSM=1) When INTFLAG.SB is set, the I2C master will already have received one data packet and transmitted an ACK or NACK, depending on CTRLB.ACKACT. At this point, CTRLB.ACKACT must be set to the correct value for the next ACK bit, and the transaction can continue by reading DATA and issuing a command if not in the smart mode. 37.6.2.4.6 High-Speed Mode High-speed transfers are a multi-step process, see High Speed Transfer. First, a master code (0b00001nnn, where 'nnn' is a unique master code) is transmitted in Full-speed mode, followed by a NACK since no slaveshould acknowledge. Arbitration is performed only during the Full-speed Master Code phase. The master code is transmitted by writing the master code to the address register (ADDR.ADDR) and writing the high-speed bit (ADDR.HS) to '0'. After the master code and NACK have been transmitted, the master write interrupt will be asserted. In the meanwhile, the slave address can be written to the ADDR.ADDR register together with ADDR.HS=1. Now in High-speed mode, the master will generate a repeated start, followed by the slave address with RW-direction. The bus will remain in High-speed mode until a stop is generated. If a repeated start is desired, the ADDR.HS bit must again be written to '1', along with the new address ADDR.ADDR to be transmitted. Figure 37-8. High Speed Transfer S A Sr A DATA A/A P N Data Packets Master Code ADDRESS R/W Sr ADDRESS Hs-mode continues F/S-mode Hs-mode F/S-mode Transmitting in High-speed mode requires the I2C master to be configured in High-speed mode (CTRLA.SPEED=0x2) and the SCL clock stretch mode (CTRLA.SCLSM) bit set to '1'. 37.6.2.4.7 10-Bit Addressing When 10-bit addressing is enabled by the Ten Bit Addressing Enable bit in the Address register (ADDR.TENBITEN=1) and the Address bit field ADDR.ADDR is written, the two address bytes will be transmitted, see 10-bit Address Transmission for a Read Transaction. The addressed slave acknowledges the two address bytes, and the transaction continues. Regardless of whether the transaction is a read or write, the master must start by sending the 10-bit address with the direction bit (ADDR.ADDR[0]) being zero. If the master receives a NACK after the first byte, the write interrupt flag will be raised and the STATUS.RXNACK bit will be set. If the first byte is acknowledged by one or more slaves, then the master will proceed to transmit the second address byte and the master will first see the write interrupt flag after the second byte is transmitted. If the transaction direction is read-from-slave, the 10-bit address transmission must be followed by a repeated start and the first 7 bits of the address with the read/write bit equal to '1'. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 823 Figure 37-9. 10-bit Address Transmission for a Read Transaction S 11110 addr[9:8] W A addr[7:0] A Sr R A 1 S W 11110 addr[9:8] MB INTERRUPT This implies the following procedure for a 10-bit read operation: 1. Write the 10-bit address to ADDR.ADDR[10:1]. ADDR.TENBITEN must be '1', the direction bit (ADDR.ADDR[0]) must be '0' (can be written simultaneously with ADDR). 2. Once the Master on Bus interrupt is asserted, Write ADDR[7:0] register to '11110 address[9:8] 1'. ADDR.TENBITEN must be cleared (can be written simultaneously with ADDR). 3. Proceed to transmit data. 37.6.2.5 I 2C Slave Operation The I2C slave is byte-oriented and interrupt-based. The number of interrupts generated is kept at a minimum by automatic handling of most events. The software driver complexity and code size are reduced by auto-triggering of operations, and a special smart mode, which can be enabled by the Smart Mode Enable bit in the Control A register (CTRLA.SMEN). The I2C slave has two interrupt strategies. When SCL Stretch Mode bit (CTRLA.SCLSM) is '0', SCL is stretched before or after the acknowledge bit. In this mode, the I2C slave operates according to I 2C Slave Behavioral Diagram (SCLSM=0). The circles labelled "Sn" (S1, S2..) indicate the nodes the bus logic can jump to, based on software or hardware interaction. This diagram is used as reference for the description of the I2C slave operation throughout the document. Figure 37-10. I2C Slave Behavioral Diagram (SCLSM=0) S S3 S2 ADDRESS A S1 R W DATA A/A DATA P S2 Sr S3 P S2 Sr S3 A S W S W S W S W A A/A A S1 S W Interrupt on STOP Condition Enabled S1 S W Software interaction The master provides data on the bus Addressed slave provides data on the bus AMATCH INTERRUPT DRDY INTERRUPT PREC INTERRUPT SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 824 In the second strategy (CTRLA.SCLSM=1), interrupts only occur after the ACK bit is sent as shown in Slave Behavioral Diagram (SCLSM=1). This strategy can be used when it is not necessary to check DATA before acknowledging. For master reads, an address and data interrupt will be issued simultaneously after the address acknowledge. However, for master writes, the first data interrupt will be seen after the first data byte has been received by the slave and the acknowledge bit has been sent to the master. Note:  For I2C High-speed mode (Hs), SCLSM=1 is required. Figure 37-11. I2C Slave Behavioral Diagram (SCLSM=1) S S3 S2 ADDRESS R W DATA A/A DATA P S2 Sr S3 P S2 Sr S3 S W S W S W A/A S W Interrupt on STOP Condition Enabled S1 S W Software interaction The master provides data on the bus Addressed slave provides data on the bus A/A A/A PREC INTERRUPT AMATCH INTERRUPT (+ DRDY INTERRUPT in Master Read mode) DRDY INTERRUPT 37.6.2.5.1 Receiving Address Packets (SCLSM=0) When CTRLA.SCLSM=0, the I2C slave stretches the SCL line according to Figure 37-10. When the I2C slave is properly configured, it will wait for a start condition. When a start condition is detected, the successive address packet will be received and checked by the address match logic. If the received address is not a match, the packet will be rejected, and the I2C slave will wait for a new start condition. If the received address is a match, the Address Match bit in the Interrupt Flag register (INTFLAG.AMATCH) will be set. SCL will be stretched until the I2C slave clears INTFLAG.AMATCH. As the I2C slave holds the clock by forcing SCL low, the software has unlimited time to respond. The direction of a transaction is determined by reading the Read / Write Direction bit in the Status register (STATUS.DIR). This bit will be updated only when a valid address packet is received. If the Transmit Collision bit in the Status register (STATUS.COLL) is set, this indicates that the last packet addressed to the I2C slave had a packet collision. A collision causes the SDA and SCL lines to be released without any notification to software. Therefore, the next AMATCH interrupt is the first indication of the previous packet’s collision. Collisions are intended to follow the SMBus Address Resolution Protocol (ARP). After the address packet has been received from the I2C master, one of two cases will arise based on transfer direction. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 825 Case 1: Address packet accepted – Read flag set The STATUS.DIR bit is ‘1’, indicating an I2C master read operation. The SCL line is forced low, stretching the bus clock. If an ACK is sent, I2C slave hardware will set the Data Ready bit in the Interrupt Flag register (INTFLAG.DRDY), indicating data are needed for transmit. If a NACK is sent, the I2C slave will wait for a new start condition and address match. Typically, software will immediately acknowledge the address packet by sending an ACK/NACK bit. The I 2C slave Command bit field in the Control B register (CTRLB.CMD) can be written to '0x3' for both read and write operations as the command execution is dependent on the STATUS.DIR bit. Writing ‘1’ to INTFLAG.AMATCH will also cause an ACK/NACK to be sent corresponding to the CTRLB.ACKACT bit. Case 2: Address packet accepted – Write flag set The STATUS.DIR bit is cleared, indicating an I2C master write operation. The SCL line is forced low, stretching the bus clock. If an ACK is sent, the I2C slave will wait for data to be received. Data, repeated start or stop can be received. If a NACK is sent, the I2C slave will wait for a new start condition and address match. Typically, software will immediately acknowledge the address packet by sending an ACK/NACK. The I2C slave command CTRLB.CMD = 3 can be used for both read and write operation as the command execution is dependent on STATUS.DIR. Writing ‘1’ to INTFLAG.AMATCH will also cause an ACK/NACK to be sent corresponding to the CTRLB.ACKACT bit. 37.6.2.5.2 Receiving Address Packets (SCLSM=1) When SCLSM=1, the I2C slave will stretch the SCL line only after an ACK, see Slave Behavioral Diagram (SCLSM=1). When the I2C slave is properly configured, it will wait for a start condition to be detected. When a start condition is detected, the successive address packet will be received and checked by the address match logic. If the received address is not a match, the packet will be rejected and the I2C slave will wait for a new start condition. If the address matches, the acknowledge action as configured by the Acknowledge Action bit Control B register (CTRLB.ACKACT) will be sent and the Address Match bit in the Interrupt Flag register (INTFLAG.AMATCH) is set. SCL will be stretched until the I2C slave clears INTFLAG.AMATCH. As the I 2C slave holds the clock by forcing SCL low, the software is given unlimited time to respond to the address. The direction of a transaction is determined by reading the Read/Write Direction bit in the Status register (STATUS.DIR). This bit will be updated only when a valid address packet is received. If the Transmit Collision bit in the Status register (STATUS.COLL) is set, the last packet addressed to the I 2C slave had a packet collision. A collision causes the SDA and SCL lines to be released without any notification to software. The next AMATCH interrupt is, therefore, the first indication of the previous packet’s collision. Collisions are intended to follow the SMBus Address Resolution Protocol (ARP). After the address packet has been received from the I2C master, INTFLAG.AMATCH be set to ‘1’ to clear it. 37.6.2.5.3 Receiving and Transmitting Data Packets After the I2C slave has received an address packet, it will respond according to the direction either by waiting for the data packet to be received or by starting to send a data packet by writing to DATA.DATA. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 826 When a data packet is received or sent, INTFLAG.DRDY will be set. After receiving data, the I2C slave will send an acknowledge according to CTRLB.ACKACT. Case 1: Data received INTFLAG.DRDY is set, and SCL is held low, pending for SW interaction. Case 2: Data sent When a byte transmission is successfully completed, the INTFLAG.DRDY interrupt flag is set. If NACK is received, indicated by STATUS.RXNACK=1, the I2C slave must expect a stop or a repeated start to be received. The I2C slave must release the data line to allow the I2C master to generate a stop or repeated start. Upon detecting a stop condition, the Stop Received bit in the Interrupt Flag register (INTFLAG.PREC) will be set and the I2C slave will return to IDLE state. 37.6.2.5.4 High-Speed Mode When the I2C slave is configured in High-speed mode (Hs, CTRLA.SPEED=0x2) and CTRLA.SCLSM=1, switching between Full-speed and High-speed modes is automatic. When the slave recognizes a START followed by a master code transmission and a NACK, it automatically switches to High-speed mode and sets the High-speed status bit (STATUS.HS). The slave will then remain in High-speed mode until a STOP is received. 37.6.2.5.5 10-Bit Addressing When 10-bit addressing is enabled (ADDR.TENBITEN=1), the two address bytes following a START will be checked against the 10-bit slave address recognition. The first byte of the address will always be acknowledged, and the second byte will raise the address interrupt flag, see 10-bit Addressing. If the transaction is a write, then the 10-bit address will be followed by N data bytes. If the operation is a read, the 10-bit address will be followed by a repeated START and reception of '11110 ADDR[9:8] 1', and the second address interrupt will be received with the DIR bit set. The slave matches on the second address as it it was addressed by the previous 10-bit address. Figure 37-12. 10-bit Addressing S 11110 addr[9:8] W A addr[7:0] A Sr R S W S W 11110 addr[9:8] AMATCH INTERRUPT AMATCH INTERRUPT 37.6.2.5.6 PMBus Group Command When the PMBus Group Command bit in the CTRLB register is set (CTRLB.GCMD=1) and 7-bit addressing is used, INTFLAG.PREC will be set if the slave has been addressed since the last STOP condition. When CTRLB.GCMD=0, a STOP condition without address match will not be set INTFLAG.PREC. The group command protocol is used to send commands to more than one device. The commands are sent in one continuous transmission with a single STOP condition at the end. When the STOP condition is detected by the slaves addressed during the group command, they all begin executing the command they received. PMBus Group Command Example shows an example where this slave, bearing ADDRESS 1, is addressed after a repeated START condition. There can be multiple slaves addressed before and after this slave. Eventually, at the end of the group command, a single STOP is generated by the master. At this point a STOP interrupt is asserted. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 827 Figure 37-13. PMBus Group Command Example S ADDRESS 0 W A n Bytes A Command/Data Sr W A n Bytes A ADDRESS 1 (this slave) Command/Data S W S W Sr ADDRESS 2 W A n Bytes A Command/Data P S W AMATCH INTERRUPT DRDY INTERRUPT PREC INTERRUPT 37.6.3 Additional Features 37.6.3.1 SMBus The I2C includes three hardware SCL low time-outs which allow a time-out to occur for SMBus SCL low time-out, master extend time-out, and slave extend time-out. This allows for SMBus functionality These time-outs are driven by the GCLK_SERCOM_SLOW clock. The GCLK_SERCOM_SLOW clock is used to accurately time the time-out and must be configured to use a 32KHz oscillator. The I2C interface also allows for a SMBus compatible SDA hold time. • TTIMEOUT: SCL low time of 25..35ms – Measured for a single SCL low period. It is enabled by CTRLA.LOWTOUTEN. • TLOW:SEXT: Cumulative clock low extend time of 25 ms – Measured as the cumulative SCL low extend time by a slave device in a single message from the initial START to the STOP. It is enabled by CTRLA.SEXTTOEN. • TLOW:MEXT: Cumulative clock low extend time of 10 ms – Measured as the cumulative SCL low extend time by the master device within a single byte from START-to-ACK, ACK-to-ACK, or ACKto-STOP. It is enabled by CTRLA.MEXTTOEN. 37.6.3.2 Smart Mode The I2C interface has a smart mode that simplifies application code and minimizes the user interaction needed to adhere to the I2C protocol. The smart mode accomplishes this by automatically issuing an ACK or NACK (based on the content of CTRLB.ACKACT) as soon as DATA.DATA is read. 37.6.3.3 4-Wire Mode Writing a '1' to the Pin Usage bit in the Control A register (CTRLA.PINOUT) will enable 4-wire mode operation. In this mode, the internal I2C tri-state drivers are bypassed, and an external I2C compliant tristate driver is needed when connecting to an I2C bus. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 828 Figure 37-14. I2C Pad Interface SCL/SDA pad I2C Driver SCL_OUT/ SDA_OUT PINOUT pad PINOUT SCL_IN/ SDA_IN SCL_OUT/ SDA_OUT 37.6.3.4 Quick Command Setting the Quick Command Enable bit in the Control B register (CTRLB.QCEN) enables quick command. When quick command is enabled, the corresponding interrupt flag (INTFLAG.SB or INTFLAG.MB) is set immediately after the slave acknowledges the address. At this point, the software can either issue a stop command or a repeated start by writing CTRLB.CMD or ADDR.ADDR. 37.6.4 DMA, Interrupts and Events Each interrupt source has its own interrupt flag. The interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG) will be set when the interrupt condition is meet. Each interrupt can be individually enabled by writing ‘1’ to the corresponding bit in the Interrupt Enable Set register (INTENSET), and disabled by writing ‘1’ to the corresponding bit in the Interrupt Enable Clear register (INTENCLR). An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request is active until the interrupt flag is cleared, the interrupt is disabled or the I2C is reset. See the 37.8.5 INTFLAG (Slave) or 37.10.6 INTFLAG (Master) register for details on how to clear interrupt flags. Table 37-1. Module Request for SERCOM I2C Slave Condition Request DMA Interrupt Event Data needed for transmit (TX) (Slave transmit mode) Yes (request cleared when data is written) NA Data received (RX) (Slave receive mode) Yes (request cleared when data is read) Data Ready (DRDY) Yes Address Match (AMATCH) Yes Stop received (PREC) Yes Error (ERROR) Yes SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 829 Table 37-2. Module Request for SERCOM I2C Master Condition Request DMA Interrupt Event Data needed for transmit (TX) (Master transmit mode) Yes (request cleared when data is written) NA Data needed for transmit (RX) (Master transmit mode) Yes (request cleared when data is read) Master on Bus (MB) Yes Stop received (SB) Yes Error (ERROR) Yes 37.6.4.1 DMA Operation Smart mode must be enabled for DMA operation in the Control B register by writing CTRLB.SMEN=1. 37.6.4.1.1 Slave DMA When using the I2C slave with DMA, an address match will cause the address interrupt flag (INTFLAG.ADDRMATCH) to be raised. After the interrupt has been serviced, data transfer will be performed through DMA. The I2C slave generates the following requests: • Write data received (RX): The request is set when master write data is received. The request is cleared when DATA is read. • Read data needed for transmit (TX): The request is set when data is needed for a master read operation. The request is cleared when DATA is written. 37.6.4.1.2 Master DMA When using the I2C master with DMA, the ADDR register must be written with the desired address (ADDR.ADDR), transaction length (ADDR.LEN), and transaction length enable (ADDR.LENEN). When ADDR.LENEN is written to 1 along with ADDR.ADDR, ADDR.LEN determines the number of data bytes in the transaction from 0 to 255. DMA is then used to transfer ADDR.LEN bytes followed by an automatically generated NACK (for master reads) and a STOP. If a NACK is received by the slave for a master write transaction before ADDR.LEN bytes, a STOP will be automatically generated and the length error (STATUS.LENERR) will be raised along with the INTFLAG.ERROR interrupt. The I2C master generates the following requests: • Read data received (RX): The request is set when master read data is received. The request is cleared when DATA is read. • Write data needed for transmit (TX): The request is set when data is needed for a master write operation. The request is cleared when DATA is written. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 830 37.6.4.2 Interrupts The I2C slave has the following interrupt sources. These are asynchronous interrupts. They can wake-up the device from any sleep mode: • Error (ERROR) • Data Ready (DRDY) • Address Match (AMATCH) • Stop Received (PREC) The I2C master has the following interrupt sources. These are asynchronous interrupts. They can wakeup the device from any sleep mode: • Error (ERROR) • Slave on Bus (SB) • Master on Bus (MB) Each interrupt source has its own interrupt flag. The interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG) will be set when the interrupt condition is meet. Each interrupt can be individually enabled by writing ‘1’ to the corresponding bit in the Interrupt Enable Set register (INTENSET), and disabled by writing ‘1’ to the corresponding bit in the Interrupt Enable Clear register (INTENCLR). An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request active until the interrupt flag is cleared, the interrupt is disabled or the I2C is reset. See the INTFLAG register for details on how to clear interrupt flags. The value of INTFLAG indicates which interrupt is executed. Note that interrupts must be globally enabled for interrupt requests. Refer to Nested Vector Interrupt Controller for details. 37.6.4.3 Events Not applicable. 37.6.5 Sleep Mode Operation I 2C Master Operation The generic clock (GCLK_SERCOMx_CORE) will continue to run in Idle Sleep mode. If the Run In Standby bit in the Control A register (CTRLA.RUNSTDBY) is '1', the GLK_SERCOMx_CORE will also run in standby Sleep mode. Any interrupt can wake up the device. If CTRLA.RUNSTDBY=0, the GLK_SERCOMx_CORE will be disabled after any ongoing transaction is finished. Any interrupt can wake up the device. I 2C Slave Operation Writing CTRLA.RUNSTDBY=1 will allow the Address Match interrupt to wake up the device. When CTRLA.RUNSTDBY=0, all receptions will be dropped. 37.6.6 Synchronization Due to asynchronicity between the main clock domain and the peripheral clock domains, some registers need to be synchronized when written or read. The following bits are synchronized when written: • Software Reset bit in the CTRLA register (CTRLA.SWRST) • Enable bit in the CTRLA register (CTRLA.ENABLE) • Command bits in CTRLB register (CTRLB.CMD) SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 831 • Write to Bus State bits in the Status register (STATUS.BUSSTATE) • Address bits in the Address register (ADDR.ADDR) when in master operation. The following registers are synchronized when written: • Data (DATA) when in master operation Required write-synchronization is denoted by the "Write-Synchronized" property in the register description. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 832 37.7 Register Summary - I2C Slave Offset Name Bit Pos. 0x00 CTRLA 7:0 RUNSTDBY MODE[2:0] ENABLE SWRST 15:8 23:16 SEXTTOEN SDAHOLD[1:0] PINOUT 31:24 LOWTOUT SCLSM SPEED[1:0] 0x04 CTRLB 7:0 15:8 AMODE[1:0] AACKEN GCMD SMEN 23:16 ACKACT CMD[1:0] 31:24 0x08 ... 0x13 Reserved 0x14 INTENCLR 7:0 ERROR DRDY AMATCH PREC 0x15 Reserved 0x16 INTENSET 7:0 ERROR DRDY AMATCH PREC 0x17 Reserved 0x18 INTFLAG 7:0 ERROR DRDY AMATCH PREC 0x19 Reserved 0x1A STATUS 7:0 CLKHOLD LOWTOUT SR DIR RXNACK COLL BUSERR 15:8 LENERR HS SEXTTOUT 0x1C SYNCBUSY 7:0 ENABLE SWRST 15:8 23:16 31:24 0x20 ... 0x23 Reserved 0x24 ADDR 7:0 ADDR[6:0] GENCEN 15:8 TENBITEN ADDR[9:7] 23:16 ADDRMASK[6:0] 31:24 ADDRMASK[9:7] 0x28 DATA 7:0 DATA[7:0] 15:8 37.8 Register Description - I2C Slave Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to 37.5.8 Register Access Protection. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 833 Some registers are synchronized when read and/or written. Synchronization is denoted by the "WriteSynchronized" or the "Read-Synchronized" property in each individual register description. For details, refer to 37.6.6 Synchronization. Some registers are enable-protected, meaning they can only be written when the peripheral is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 834 37.8.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 LOWTOUT SCLSM SPEED[1:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 23 22 21 20 19 18 17 16 SEXTTOEN SDAHOLD[1:0] PINOUT Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 RUNSTDBY MODE[2:0] ENABLE SWRST Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 30 – LOWTOUT SCL Low Time-Out This bit enables the SCL low time-out. If SCL is held low for 25ms-35ms, the slave will release its clock hold, if enabled, and reset the internal state machine. Any interrupt flags set at the time of time-out will remain set. Value Description 0 Time-out disabled. 1 Time-out enabled. Bit 27 – SCLSM SCL Clock Stretch Mode This bit controls when SCL will be stretched for software interaction. This bit is not synchronized. Value Description 0 SCL stretch according to Figure 37-10 1 SCL stretch only after ACK bit according to Figure 37-11 Bits 25:24 – SPEED[1:0] Transfer Speed These bits define bus speed. These bits are not synchronized. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 835 Value Description 0x0 Standard-mode (Sm) up to 100 kHz and Fast-mode (Fm) up to 400 kHz 0x1 Fast-mode Plus (Fm+) up to 1 MHz 0x2 High-speed mode (Hs-mode) up to 3.4 MHz 0x3 Reserved Bit 23 – SEXTTOEN Slave SCL Low Extend Time-Out This bit enables the slave SCL low extend time-out. If SCL is cumulatively held low for greater than 25ms from the initial START to a STOP, the slave will release its clock hold if enabled and reset the internal state machine. Any interrupt flags set at the time of time-out will remain set. If the address was recognized, PREC will be set when a STOP is received. This bit is not synchronized. Value Description 0 Time-out disabled 1 Time-out enabled Bits 21:20 – SDAHOLD[1:0] SDA Hold Time These bits define the SDA hold time with respect to the negative edge of SCL. These bits are not synchronized. Value Name Description 0x0 DIS Disabled 0x1 75 50-100ns hold time 0x2 450 300-600ns hold time 0x3 600 400-800ns hold time Bit 16 – PINOUT Pin Usage This bit sets the pin usage to either two- or four-wire operation: This bit is not synchronized. Value Description 0 4-wire operation disabled 1 4-wire operation enabled Bit 7 – RUNSTDBY Run in Standby This bit defines the functionality in standby sleep mode. This bit is not synchronized. Value Description 0 Disabled – All reception is dropped. 1 Wake on address match, if enabled. Bits 4:2 – MODE[2:0] Operating Mode These bits must be written to 0x04 to select the I2C slave serial communication interface of the SERCOM. These bits are not synchronized. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 836 Bit 1 – ENABLE Enable Due to synchronization, there is delay from writing CTRLA.ENABLE until the peripheral is enabled/ disabled. The value written to CTRL.ENABLE will read back immediately and the Enable Synchronization Busy bit in the Synchronization Busy register (SYNCBUSY.ENABLE) will be set. SYNCBUSY.ENABLE will be cleared when the operation is complete. This bit is not enable-protected. Value Description 0 The peripheral is disabled or being disabled. 1 The peripheral is enabled. Bit 0 – SWRST Software Reset Writing '0' to this bit has no effect. Writing '1' to this bit resets all registers in the SERCOM, except DBGCTRL, to their initial state, and the SERCOM will be disabled. Writing '1' to CTRLA.SWRST will always take precedence, meaning that all other writes in the same write-operation will be discarded. Any register write access during the ongoing reset will result in an APB error. Reading any register will return the reset value of the register. Due to synchronization, there is a delay from writing CTRLA.SWRST until the reset is complete. CTRLA.SWRST and SYNCBUSY.SWRST will both be cleared when the reset is complete. This bit is not enable-protected. Value Description 0 There is no reset operation ongoing. 1 The reset operation is ongoing. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 837 37.8.2 Control B Name:  CTRLB Offset:  0x04 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected, Write-Synchronized Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 ACKACT CMD[1:0] Access R/W W W Reset 0 0 0 Bit 15 14 13 12 11 10 9 8 AMODE[1:0] AACKEN GCMD SMEN Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 Access Reset Bit 18 – 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 smart mode is enabled (CTRLB.SMEN=1), the acknowledge action is performed when the DATA register is read. ACKACT shall not be updated more than once between each peripheral interrupts request. This bit is not enable-protected. Value Description 0 Send ACK 1 Send NACK Bits 17:16 – CMD[1:0] Command This bit field triggers the slave operation as the below. The CMD bits are strobe bits, and always read as zero. The operation is dependent on the slave interrupt flags, INTFLAG.DRDY and INTFLAG.AMATCH, in addition to STATUS.DIR. All interrupt flags (INTFLAG.DRDY, INTFLAG.AMATCH and INTFLAG.PREC) are automatically cleared when a command is given. This bit is not enable-protected. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 838 Table 37-3. Command Description CMD[1:0] DIR Action 0x0 X (No action) 0x1 X (Reserved) 0x2 Used to complete a transaction in response to a data interrupt (DRDY) 0 (Master write) Execute acknowledge action succeeded by waiting for any start (S/Sr) condition 1 (Master read) Wait for any start (S/Sr) condition 0x3 Used in response to an address interrupt (AMATCH) 0 (Master write) Execute acknowledge action succeeded by reception of next byte 1 (Master read) Execute acknowledge action succeeded by slave data interrupt Used in response to a data interrupt (DRDY) 0 (Master write) Execute acknowledge action succeeded by reception of next byte 1 (Master read) Execute a byte read operation followed by ACK/NACK reception Bits 15:14 – AMODE[1:0] Address Mode These bits set the addressing mode. These bits are not write-synchronized. Value Name Description 0x0 MASK The slave responds to the address written in ADDR.ADDR masked by the value in ADDR.ADDRMASK. See SERCOM – Serial Communication Interface for additional information. 0x1 2_ADDRS The slave responds to the two unique addresses in ADDR.ADDR and ADDR.ADDRMASK. 0x2 RANGE The slave responds to the range of addresses between and including ADDR.ADDR and ADDR.ADDRMASK. ADDR.ADDR is the upper limit. 0x3 - Reserved. Bit 10 – AACKEN Automatic Acknowledge Enable This bit enables the address to be automatically acknowledged if there is an address match. This bit is not write-synchronized. Value Description 0 Automatic acknowledge is disabled. 1 Automatic acknowledge is enabled. Bit 9 – GCMD PMBus Group Command This bit enables PMBus group command support. When enabled, the Stop Recived interrupt flag (INTFLAG.PREC) will be set when a STOP condition is detected if the slave has been addressed since the last STOP condition on the bus. This bit is not write-synchronized. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 839 Value Description 0 Group command is disabled. 1 Group command is enabled. Bit 8 – SMEN Smart Mode Enable When smart mode is enabled, data is acknowledged automatically when DATA.DATA is read. This bit is not write-synchronized. Value Description 0 Smart mode is disabled. 1 Smart mode is enabled. Related Links 34. SERCOM – Serial Communication Interface SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 840 37.8.3 Interrupt Enable Clear Name:  INTENCLR Offset:  0x14 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 7 6 5 4 3 2 1 0 ERROR DRDY AMATCH PREC Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 – ERROR Error Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Error Interrupt Enable bit, which disables the Error interrupt. Value Description 0 Error interrupt is disabled. 1 Error interrupt is enabled. Bit 2 – DRDY Data Ready Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Data Ready bit, which disables the Data Ready interrupt. Value Description 0 The Data Ready interrupt is disabled. 1 The Data Ready interrupt is enabled. Bit 1 – AMATCH Address Match Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Address Match Interrupt Enable bit, which disables the Address Match interrupt. Value Description 0 The Address Match interrupt is disabled. 1 The Address Match interrupt is enabled. Bit 0 – PREC Stop Received Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Stop Received Interrupt Enable bit, which disables the Stop Received interrupt. Value Description 0 The Stop Received interrupt is disabled. 1 The Stop Received interrupt is enabled. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 841 37.8.4 Interrupt Enable Set Name:  INTENSET Offset:  0x16 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear register (INTENCLR). Bit 7 6 5 4 3 2 1 0 ERROR DRDY AMATCH PREC Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 – ERROR Error Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Error Interrupt Enable bit, which enables the Error interrupt. Value Description 0 Error interrupt is disabled. 1 Error interrupt is enabled. Bit 2 – DRDY Data Ready Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Data Ready bit, which enables the Data Ready interrupt. Value Description 0 The Data Ready interrupt is disabled. 1 The Data Ready interrupt is enabled. Bit 1 – AMATCH Address Match Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Address Match Interrupt Enable bit, which enables the Address Match interrupt. Value Description 0 The Address Match interrupt is disabled. 1 The Address Match interrupt is enabled. Bit 0 – PREC Stop Received Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Stop Received Interrupt Enable bit, which enables the Stop Received interrupt. Value Description 0 The Stop Received interrupt is disabled. 1 The Stop Received interrupt is enabled. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 842 37.8.5 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x18 Reset:  0x00 Property:  - Bit 7 6 5 4 3 2 1 0 ERROR DRDY AMATCH PREC Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 – ERROR Error This bit is set when any error is detected. Errors that will set this flag have corresponding status flags in the STATUS register. The corresponding bits in STATUS are SEXTTOUT, LOWTOUT, COLL, and BUSERR. Writing '0' to this bit has no effect. Writing '1' to this bit will clear the flag. Bit 2 – DRDY Data Ready This flag is set when a I2C slave byte transmission is successfully completed. The flag is cleared by hardware when either: • Writing to the DATA register. • Reading the DATA register with smart mode enabled. • Writing a valid command to the CMD register. Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Data Ready interrupt flag. Bit 1 – AMATCH Address Match This flag is set when the I2C slave address match logic detects that a valid address has been received. The flag is cleared by hardware when CTRL.CMD is written. Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Address Match interrupt flag. When cleared, an ACK/NACK will be sent according to CTRLB.ACKACT. Bit 0 – PREC Stop Received This flag is set when a stop condition is detected for a transaction being processed. A stop condition detected between a bus master and another slave will not set this flag, unless the PMBus Group Command is enabled in the Control B register (CTRLB.GCMD=1). This flag is cleared by hardware after a command is issued on the next address match. Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Stop Received interrupt flag. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 843 37.8.6 Status Name:  STATUS Offset:  0x1A Reset:  0x0000 Property:  - Bit 15 14 13 12 11 10 9 8 LENERR HS SEXTTOUT Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 CLKHOLD LOWTOUT SR DIR RXNACK COLL BUSERR Access R R/W R R R R/W R/W Reset 0 0 0 0 0 0 0 Bit 11 – LENERR Transaction Length Error This bit is set when the length counter is enabled (LENGTH.LENEN) and a STOP or repeated START is received before or after the length in LENGTH.LEN is reached. This bit is cleared automatically when responding to a new start condition with ACK or NACK (CTRLB.CMD=0x3) or when INTFLAG.AMATCH is cleared. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the status. Bit 10 – HS High-speed This bit is set if the slave detects a START followed by a Master Code transmission. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the status. However, this flag is automatically cleared when a STOP is received. Bit 9 – SEXTTOUT Slave SCL Low Extend Time-Out This bit is set if a slave SCL low extend time-out occurs. This bit is cleared automatically if responding to a new start condition with ACK or NACK (write 3 to CTRLB.CMD) or when INTFLAG.AMATCH is cleared. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the status. Value Description 0 No SCL low extend time-out has occurred. 1 SCL low extend time-out has occurred. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 844 Bit 7 – CLKHOLD Clock Hold The slave Clock Hold bit (STATUS.CLKHOLD) is set when the slave is holding the SCL line low, stretching the I2C clock. Software should consider this bit a read-only status flag that is set when INTFLAG.DRDY or INTFLAG.AMATCH is set. This bit is automatically cleared when the corresponding interrupt is also cleared. Bit 6 – LOWTOUT SCL Low Time-out This bit is set if an SCL low time-out occurs. This bit is cleared automatically if responding to a new start condition with ACK or NACK (write 3 to CTRLB.CMD) or when INTFLAG.AMATCH is cleared. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the status. Value Description 0 No SCL low time-out has occurred. 1 SCL low time-out has occurred. Bit 4 – SR Repeated Start When INTFLAG.AMATCH is raised due to an address match, SR indicates a repeated start or start condition. This flag is only valid while the INTFLAG.AMATCH flag is one. Value Description 0 Start condition on last address match 1 Repeated start condition on last address match Bit 3 – DIR Read / Write Direction The Read/Write Direction (STATUS.DIR) bit stores the direction of the last address packet received from a master. Value Description 0 Master write operation is in progress. 1 Master read operation is in progress. Bit 2 – RXNACK Received Not Acknowledge This bit indicates whether the last data packet sent was acknowledged or not. Value Description 0 Master responded with ACK. 1 Master responded with NACK. Bit 1 – COLL Transmit Collision If set, the I2C slave was not able to transmit a high data or NACK bit, the I2C slave will immediately release the SDA and SCL lines and wait for the next packet addressed to it. This flag is intended for the SMBus address resolution protocol (ARP). A detected collision in non-ARP situations indicates that there has been a protocol violation, and should be treated as a bus error. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 845 Note that this status will not trigger any interrupt, and should be checked by software to verify that the data were sent correctly. This bit is cleared automatically if responding to an address match with an ACK or a NACK (writing 0x3 to CTRLB.CMD), or INTFLAG.AMATCH is cleared. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the status. Value Description 0 No collision detected on last data byte sent. 1 Collision detected on last data byte sent. Bit 0 – BUSERR Bus Error The Bus Error bit (STATUS.BUSERR) indicates that an illegal bus condition has occurred on the bus, regardless of bus ownership. An illegal bus condition is detected if a protocol violating start, repeated start or stop is detected on the I2C bus lines. A start condition directly followed by a stop condition is one example of a protocol violation. If a time-out occurs during a frame, this is also considered a protocol violation, and will set STATUS.BUSERR. This bit is cleared automatically if responding to an address match with an ACK or a NACK (writing 0x3 to CTRLB.CMD) or INTFLAG.AMATCH is cleared. Writing a '1' to this bit will clear the status. Writing a '0' to this bit has no effect. Value Description 0 No bus error detected. 1 Bus error detected. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 846 37.8.7 Synchronization Busy Name:  SYNCBUSY Offset:  0x1C Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 ENABLE SWRST Access R R Reset 0 0 Bit 1 – ENABLE SERCOM Enable Synchronization Busy Enabling and disabling the SERCOM (CTRLA.ENABLE) requires synchronization. When written, the SYNCBUSY.ENABLE bit will be set until synchronization is complete. Value Description 0 Enable synchronization is not busy. 1 Enable synchronization is busy. Bit 0 – SWRST Software Reset Synchronization Busy Resetting the SERCOM (CTRLA.SWRST) requires synchronization. When written, the SYNCBUSY.SWRST bit will be set until synchronization is complete. Value Description 0 SWRST synchronization is not busy. 1 SWRST synchronization is busy. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 847 37.8.8 Address Name:  ADDR Offset:  0x24 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 ADDRMASK[9:7] Access R/W R/W R/W Reset 0 0 0 Bit 23 22 21 20 19 18 17 16 ADDRMASK[6:0] Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 TENBITEN ADDR[9:7] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 6 5 4 3 2 1 0 ADDR[6:0] GENCEN Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 26:17 – ADDRMASK[9:0] Address Mask These bits act as a second address match register, an address mask register or the lower limit of an address range, depending on the CTRLB.AMODE setting. Bit 15 – TENBITEN Ten Bit Addressing Enable Value Description 0 10-bit address recognition disabled. 1 10-bit address recognition enabled. Bits 10:1 – ADDR[9:0] Address These bits contain the I2C slave address used by the slave address match logic to determine if a master has addressed the slave. When using 7-bit addressing, the slave address is represented by ADDR[6:0]. When using 10-bit addressing (ADDR.TENBITEN=1), the slave address is represented by ADDR[9:0] When the address match logic detects a match, INTFLAG.AMATCH is set and STATUS.DIR is updated to indicate whether it is a read or a write transaction. Bit 0 – GENCEN General Call Address Enable A general call address is an address consisting of all-zeroes, including the direction bit (master write). SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 848 Value Description 0 General call address recognition disabled. 1 General call address recognition enabled. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 849 37.8.9 Data Name:  DATA Offset:  0x28 Reset:  0x0000 Property:  Read/Write Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 DATA[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 7:0 – DATA[7:0] Data The slave data register I/O location (DATA.DATA) provides access to the master transmit and receive data buffers. Reading valid data or writing data to be transmitted can be successfully done only when SCL is held low by the slave (STATUS.CLKHOLD is set). An exception occurs when reading the last data byte after the stop condition has been received. Accessing DATA.DATA auto-triggers I2C bus operations. The operation performed depends on the state of CTRLB.ACKACT, CTRLB.SMEN and the type of access (read/write). SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 850 37.9 Register Summary - I2C Master Offset Name Bit Pos. 0x00 CTRLA 7:0 RUNSTDBY MODE[2:0] ENABLE SWRST 15:8 23:16 SEXTTOEN MEXTTOEN SDAHOLD[1:0] PINOUT 31:24 LOWTOUT INACTOUT[1:0] SCLSM SPEED[1:0] 0x04 CTRLB 7:0 15:8 QCEN SMEN 23:16 ACKACT CMD[1:0] 31:24 0x08 ... 0x0B Reserved 0x0C BAUD 7:0 BAUD[7:0] 15:8 BAUDLOW[7:0] 23:16 HSBAUD[7:0] 31:24 HSBAUDLOW[7:0] 0x10 ... 0x13 Reserved 0x14 INTENCLR 7:0 ERROR SB MB 0x15 Reserved 0x16 INTENSET 7:0 ERROR SB MB 0x17 Reserved 0x18 INTFLAG 7:0 ERROR SB MB 0x19 Reserved 0x1A STATUS 7:0 CLKHOLD LOWTOUT BUSSTATE[1:0] RXNACK ARBLOST BUSERR 15:8 LENERR SEXTTOUT MEXTTOUT 0x1C SYNCBUSY 7:0 SYSOP ENABLE SWRST 15:8 23:16 31:24 0x20 ... 0x23 Reserved 0x24 ADDR 7:0 ADDR[7:0] 15:8 TENBITEN HS LENEN ADDR[10:8] 23:16 LEN[7:0] 31:24 0x28 DATA 7:0 DATA[7:0] 15:8 0x2A ... 0x2F Reserved 0x30 DBGCTRL 7:0 DBGSTOP SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 851 37.10 Register Description - I2C Master Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to 37.5.8 Register Access Protection. Some registers are synchronized when read and/or written. Synchronization is denoted by the "WriteSynchronized" or the "Read-Synchronized" property in each individual register description. For details, refer to 37.6.6 Synchronization. Some registers are enable-protected, meaning they can only be written when the peripheral is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 852 37.10.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 LOWTOUT INACTOUT[1:0] SCLSM SPEED[1:0] Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 SEXTTOEN MEXTTOEN SDAHOLD[1:0] PINOUT Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 RUNSTDBY MODE[2:0] ENABLE SWRST Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 30 – LOWTOUT SCL Low Time-Out This bit enables the SCL low time-out. If SCL is held low for 25ms-35ms, the master will release its clock hold, if enabled, and complete the current transaction. A stop condition will automatically be transmitted. INTFLAG.SB or INTFLAG.MB will be set as normal, but the clock hold will be released. The STATUS.LOWTOUT and STATUS.BUSERR status bits will be set. This bit is not synchronized. Value Description 0 Time-out disabled. 1 Time-out enabled. Bits 29:28 – INACTOUT[1:0] Inactive Time-Out If the inactive bus time-out is enabled and the bus is inactive for longer than the time-out setting, the bus state logic will be set to idle. An inactive bus arise when either an I2C master or slave is holding the SCL low. Enabling this option is necessary for SMBus compatibility, but can also be used in a non-SMBus set-up. Calculated time-out periods are based on a 100kHz baud rate. These bits are not synchronized. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 853 Value Name Description 0x0 DIS Disabled 0x1 55US 5-6 SCL cycle time-out (50-60µs) 0x2 105US 10-11 SCL cycle time-out (100-110µs) 0x3 205US 20-21 SCL cycle time-out (200-210µs) Bit 27 – SCLSM SCL Clock Stretch Mode This bit controls when SCL will be stretched for software interaction. This bit is not synchronized. Value Description 0 SCL stretch according to Figure 37-5. 1 SCL stretch only after ACK bit, Figure 37-6. Bits 25:24 – SPEED[1:0] Transfer Speed These bits define bus speed. These bits are not synchronized. Value Description 0x0 Standard-mode (Sm) up to 100 kHz and Fast-mode (Fm) up to 400 kHz 0x1 Fast-mode Plus (Fm+) up to 1 MHz 0x2 High-speed mode (Hs-mode) up to 3.4 MHz 0x3 Reserved Bit 23 – SEXTTOEN Slave SCL Low Extend Time-Out This bit enables the slave SCL low extend time-out. If SCL is cumulatively held low for greater than 25ms from the initial START to a STOP, the master will release its clock hold if enabled, and complete the current transaction. A STOP will automatically be transmitted. SB or MB will be set as normal, but CLKHOLD will be release. The MEXTTOUT and BUSERR status bits will be set. This bit is not synchronized. Value Description 0 Time-out disabled 1 Time-out enabled Bit 22 – MEXTTOEN Master SCL Low Extend Time-Out This bit enables the master SCL low extend time-out. If SCL is cumulatively held low for greater than 10ms from START-to-ACK, ACK-to-ACK, or ACK-to-STOP the master will release its clock hold if enabled, and complete the current transaction. A STOP will automatically be transmitted. SB or MB will be set as normal, but CLKHOLD will be released. The MEXTTOUT and BUSERR status bits will be set. This bit is not synchronized. Value Description 0 Time-out disabled 1 Time-out enabled SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 854 Bits 21:20 – SDAHOLD[1:0] SDA Hold Time These bits define the SDA hold time with respect to the negative edge of SCL. These bits are not synchronized. Value Name Description 0x0 DIS Disabled 0x1 75NS 50-100ns hold time 0x2 450NS 300-600ns hold time 0x3 600NS 400-800ns hold time Bit 16 – PINOUT Pin Usage This bit set the pin usage to either two- or four-wire operation: This bit is not synchronized. Value Description 0 4-wire operation disabled. 1 4-wire operation enabled. Bit 7 – RUNSTDBY Run in Standby This bit defines the functionality in standby sleep mode. This bit is not synchronized. Value Description 0 GCLK_SERCOMx_CORE is disabled and the I2C master will not operate in standby sleep mode. 1 GCLK_SERCOMx_CORE is enabled in all sleep modes. Bits 4:2 – MODE[2:0] Operating Mode These bits must be written to 0x5 to select the I2C master serial communication interface of the SERCOM. These bits are not synchronized. Bit 1 – ENABLE Enable Due to synchronization, there is delay from writing CTRLA.ENABLE until the peripheral is enabled/ disabled. The value written to CTRL.ENABLE will read back immediately and the Synchronization Enable Busy bit in the Synchronization Busy register (SYNCBUSY.ENABLE) will be set. SYNCBUSY.ENABLE will be cleared when the operation is complete. This bit is not enable-protected. Value Description 0 The peripheral is disabled or being disabled. 1 The peripheral is enabled. Bit 0 – SWRST Software Reset Writing '0' to this bit has no effect. Writing '1' to this bit resets all registers in the SERCOM, except DBGCTRL, to their initial state, and the SERCOM will be disabled. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 855 Writing '1' to CTRLA.SWRST will always take precedence, meaning that all other writes in the same write-operation will be discarded. Any register write access during the ongoing reset will result in an APB error. Reading any register will return the reset value of the register. Due to synchronization there is a delay from writing CTRLA.SWRST until the reset is complete. CTRLA.SWRST and SYNCBUSY.SWRST will both be cleared when the reset is complete. This bit is not enable-protected. Value Description 0 There is no reset operation ongoing. 1 The reset operation is ongoing. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 856 37.10.2 Control B Name:  CTRLB Offset:  0x04 Reset:  0x00000000 Property:  PAC Write-Protection, Enable-Protected, Write-Synchronized Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 ACKACT CMD[1:0] Access R/W R/W R/W Reset 0 0 0 Bit 15 14 13 12 11 10 9 8 QCEN SMEN Access R R/W Reset 0 0 Bit 7 6 5 4 3 2 1 0 Access Reset Bit 18 – ACKACT Acknowledge Action This bit defines the I2C master's acknowledge behavior after a data byte is received from the I2C slave. The acknowledge action is executed when a command is written to CTRLB.CMD, or if smart mode is enabled (CTRLB.SMEN is written to one), when DATA.DATA is read. This bit is not enable-protected. This bit is not write-synchronized. Value Description 0 Send ACK. 1 Send NACK. Bits 17:16 – CMD[1:0] Command Writing these bits triggers a master operation as described below. The CMD bits are strobe bits, and always read as zero. The acknowledge action is only valid in master read mode. In master write mode, a command will only result in a repeated start or stop condition. The CTRLB.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. Commands can only be issued when either the Slave on Bus interrupt flag (INTFLAG.SB) or Master on Bus interrupt flag (INTFLAG.MB) is '1'. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 857 If CMD 0x1 is issued, a repeated start will be issued followed by the transmission of the current address in ADDR.ADDR. If another address is desired, ADDR.ADDR must be written instead of the CMD bits. This will trigger a repeated start followed by transmission of the new address. Issuing a command will set the System Operation bit in the Synchronization Busy register (SYNCBUSY.SYSOP). Table 37-4. Command Description CMD[1:0] Direction Action 0x0 X (No action) 0x1 X Execute acknowledge action succeeded by repeated Start 0x2 0 (Write) No operation 1 (Read) Execute acknowledge action succeeded by a byte read operation 0x3 X Execute acknowledge action succeeded by issuing a stop condition These bits are not enable-protected. Bit 9 – QCEN Quick Command Enable This bit is not write-synchronized. Value Description 0 Quick Command is disabled. 1 Quick Command is enabled. Bit 8 – SMEN Smart Mode Enable When smart mode is enabled, acknowledge action is sent when DATA.DATA is read. This bit is not write-synchronized. Value Description 0 Smart mode is disabled. 1 Smart mode is enabled. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 858 37.10.3 Baud Rate Name:  BAUD Offset:  0x0C Reset:  0x0000 Property:  PAC Write-Protection, Enable-Protected Bit 31 30 29 28 27 26 25 24 HSBAUDLOW[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 HSBAUD[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 BAUDLOW[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 BAUD[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:24 – HSBAUDLOW[7:0] High Speed Master Baud Rate Low HSBAUDLOW non-zero: HSBAUDLOW indicates the SCL low time in High-speed mode according to HSBAUDLOW = ݂GCLK ڄܶ LOW െ 1 HSBAUDLOW equal to zero: The HSBAUD register is used to time TLOW, THIGH, TSU;STO, THD;STA and TSU;STA.. TBUF is timed by the BAUD register. Bits 23:16 – HSBAUD[7:0] High Speed Master Baud Rate This bit field indicates the SCL high time in High-speed mode according to the following formula. When HSBAUDLOW is zero, TLOW, THIGH, TSU;STO, THD;STA and TSU;STA are derived using this formula. TBUF is timed by the BAUD register. HSBAUD = ݂GCLK ڄܶ HIGH െ 1 Bits 15:8 – BAUDLOW[7:0] Master Baud Rate Low If this bit field is non-zero, the SCL low time will be described by the value written. For more information on how to calculate the frequency, see SERCOM 34.6.2.3 Clock Generation – Baud-Rate Generator. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 859 Bits 7:0 – BAUD[7:0] Master Baud Rate This bit field is used to derive the SCL high time if BAUD.BAUDLOW is non-zero. If BAUD.BAUDLOW is zero, BAUD will be used to generate both high and low periods of the SCL. For more information on how to calculate the frequency, see SERCOM 34.6.2.3 Clock Generation – Baud-Rate Generator. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 860 37.10.4 Interrupt Enable Clear Name:  INTENCLR Offset:  0x14 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 7 6 5 4 3 2 1 0 ERROR SB MB Access R/W R/W R/W Reset 0 0 0 Bit 7 – ERROR Error Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Error Interrupt Enable bit, which disables the Error interrupt. Value Description 0 Error interrupt is disabled. 1 Error interrupt is enabled. Bit 1 – SB Slave on Bus Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Slave on Bus Interrupt Enable bit, which disables the Slave on Bus interrupt. Value Description 0 The Slave on Bus interrupt is disabled. 1 The Slave on Bus interrupt is enabled. Bit 0 – MB Master on Bus Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will clear the Master on Bus Interrupt Enable bit, which disables the Master on Bus interrupt. Value Description 0 The Master on Bus interrupt is disabled. 1 The Master on Bus interrupt is enabled. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 861 37.10.5 Interrupt Enable Set Name:  INTENSET Offset:  0x16 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear register (INTENCLR). Bit 7 6 5 4 3 2 1 0 ERROR SB MB Access R/W R/W R/W Reset 0 0 0 Bit 7 – ERROR Error Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Error Interrupt Enable bit, which enables the Error interrupt. Value Description 0 Error interrupt is disabled. 1 Error interrupt is enabled. Bit 1 – SB Slave on Bus Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Slave on Bus Interrupt Enable bit, which enables the Slave on Bus interrupt. Value Description 0 The Slave on Bus interrupt is disabled. 1 The Slave on Bus interrupt is enabled. Bit 0 – MB Master on Bus Interrupt Enable Writing '0' to this bit has no effect. Writing '1' to this bit will set the Master on Bus Interrupt Enable bit, which enables the Master on Bus interrupt. Value Description 0 The Master on Bus interrupt is disabled. 1 The Master on Bus interrupt is enabled. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 862 37.10.6 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x18 Reset:  0x00 Property:  - Bit 7 6 5 4 3 2 1 0 ERROR SB MB Access R/W R/W R/W Reset 0 0 0 Bit 7 – ERROR Error This flag is cleared by writing '1' to it. This bit is set when any error is detected. Errors that will set this flag have corresponding status bits in the STATUS register. These status bits are LENERR, SEXTTOUT, MEXTTOUT, LOWTOUT, ARBLOST, and BUSERR. Writing '0' to this bit has no effect. Writing '1' to this bit will clear the flag. Bit 1 – SB Slave on Bus The Slave on Bus flag (SB) is set when a byte is successfully received in master read mode, i.e., no arbitration lost or bus error occurred during the operation. When this flag is set, the master forces the SCL line low, stretching the I2C clock period. The SCL line will be released and SB will be cleared on one of the following actions: • Writing to ADDR.ADDR • Writing to DATA.DATA • Reading DATA.DATA when smart mode is enabled (CTRLB.SMEN) • Writing a valid command to CTRLB.CMD Writing '1' to this bit location will clear the SB flag. The transaction will not continue or be terminated until one of the above actions is performed. Writing '0' to this bit has no effect. Bit 0 – MB Master on Bus 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. MB is also set when arbitration is lost during sending of NACK in master read mode, or when issuing a start condition if the bus state is unknown. When this flag is set and arbitration is not lost, the master forces the SCL line low, stretching the I2C clock period. The SCL line will be released and MB will be cleared on one of the following actions: • Writing to ADDR.ADDR • Writing to DATA.DATA • Reading DATA.DATA when smart mode is enabled (CTRLB.SMEN) • Writing a valid command to CTRLB.CMD SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 863 Writing '1' to this bit location will clear the MB flag. The transaction will not continue or be terminated until one of the above actions is performed. Writing '0' to this bit has no effect. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 864 37.10.7 Status Name:  STATUS Offset:  0x1A Reset:  0x0000 Property:  Write-Synchronized Bit 15 14 13 12 11 10 9 8 LENERR SEXTTOUT MEXTTOUT Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 CLKHOLD LOWTOUT BUSSTATE[1:0] RXNACK ARBLOST BUSERR Access R R/W R/W R/W R R/W R/W Reset 0 0 0 0 0 0 0 Bit 10 – LENERR Transaction Length Error This bit is set when automatic length is used for a DMA transaction and the slave sends a NACK before ADDR.LEN bytes have been written by the master. Writing '1' to this bit location will clear STATUS.LENERR. This flag is automatically cleared when writing to the ADDR register. Writing '0' to this bit has no effect. This bit is not write-synchronized. Bit 9 – SEXTTOUT Slave SCL Low Extend Time-Out This bit is set if a slave SCL low extend time-out occurs. This bit is automatically cleared when writing to the ADDR register. Writing '1' to this bit location will clear SEXTTOUT. Normal use of the I2C interface does not require the SEXTTOUT flag to be cleared by this method. Writing '0' to this bit has no effect. This bit is not write-synchronized. Bit 8 – MEXTTOUT Master SCL Low Extend Time-Out This bit is set if a master SCL low time-out occurs. Writing '1' to this bit location will clear STATUS.MEXTTOUT. This flag is automatically cleared when writing to the ADDR register. Writing '0' to this bit has no effect. This bit is not write-synchronized. Bit 7 – CLKHOLD Clock Hold This bit is set when the master is holding the SCL line low, stretching the I2C clock. Software should consider this bit when INTFLAG.SB or INTFLAG.MB is set. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 865 This bit is cleared when the corresponding interrupt flag is cleared and the next operation is given. Writing '0' to this bit has no effect. Writing '1' to this bit has no effect. This bit is not write-synchronized. Bit 6 – LOWTOUT SCL Low Time-Out This bit is set if an SCL low time-out occurs. Writing '1' to this bit location will clear this bit. This flag is automatically cleared when writing to the ADDR register. Writing '0' to this bit has no effect. This bit is not write-synchronized. Bits 5:4 – BUSSTATE[1:0] Bus State These bits indicate the current I2C bus state. When in UNKNOWN state, writing 0x1 to BUSSTATE forces the bus state into the IDLE state. The bus state cannot be forced into any other state. Writing BUSSTATE to idle will set SYNCBUSY.SYSOP. Value Name Description 0x0 UNKNOWN The bus state is unknown to the I2C master and will wait for a stop condition to be detected or wait to be forced into an idle state by software 0x1 IDLE The bus state is waiting for a transaction to be initialized 0x2 OWNER The I2C master is the current owner of the bus 0x3 BUSY Some other I2C master owns the bus Bit 2 – RXNACK Received Not Acknowledge This bit indicates whether the last address or data packet sent was acknowledged or not. Writing '0' to this bit has no effect. Writing '1' to this bit has no effect. This bit is not write-synchronized. Value Description 0 Slave responded with ACK. 1 Slave responded with NACK. Bit 1 – ARBLOST Arbitration Lost This bit 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. The Master on Bus interrupt flag (INTFLAG.MB) will be set when STATUS.ARBLOST is set. Writing the ADDR.ADDR register will automatically clear STATUS.ARBLOST. Writing '0' to this bit has no effect. Writing '1' to this bit will clear it. This bit is not write-synchronized. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 866 Bit 0 – BUSERR Bus Error This bit indicates that an illegal bus condition has occurred on the bus, regardless of bus ownership. An illegal bus condition is detected if a protocol violating start, repeated start or stop is detected on the I2C bus lines. A start condition directly followed by a stop condition is one example of a protocol violation. If a time-out occurs during a frame, this is also considered a protocol violation, and will set BUSERR. If the I2C master is the bus owner at the time a bus error occurs, STATUS.ARBLOST and INTFLAG.MB will be set in addition to BUSERR. Writing the ADDR.ADDR register will automatically clear the BUSERR flag. Writing '0' to this bit has no effect. Writing '1' to this bit will clear it. This bit is not write-synchronized. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 867 37.10.8 Synchronization Busy Name:  SYNCBUSY Offset:  0x1C Reset:  0x00000000 Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 SYSOP ENABLE SWRST Access R R R Reset 0 0 0 Bit 2 – SYSOP System Operation Synchronization Busy Writing CTRLB.CMD, STATUS.BUSSTATE, ADDR, or DATA when the SERCOM is enabled requires synchronization. When written, the SYNCBUSY.SYSOP bit will be set until synchronization is complete. Value Description 0 System operation synchronization is not busy. 1 System operation synchronization is busy. Bit 1 – ENABLE SERCOM Enable Synchronization Busy Enabling and disabling the SERCOM (CTRLA.ENABLE) requires synchronization. When written, the SYNCBUSY.ENABLE bit will be set until synchronization is complete. Value Description 0 Enable synchronization is not busy. 1 Enable synchronization is busy. Bit 0 – SWRST Software Reset Synchronization Busy Resetting the SERCOM (CTRLA.SWRST) requires synchronization. When written, the SYNCBUSY.SWRST bit will be set until synchronization is complete. Value Description 0 SWRST synchronization is not busy. 1 SWRST synchronization is busy. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 868 37.10.9 Address Name:  ADDR Offset:  0x24 Reset:  0x0000 Property:  Write-Synchronized Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 LEN[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 TENBITEN HS LENEN ADDR[10:8] Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 ADDR[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 23:16 – LEN[7:0] Transaction Length These bits define the transaction length of a DMA transaction from 0 to 255 bytes. The Transfer Length Enable (LENEN) bit must be written to '1' in order to use DMA. Bit 15 – TENBITEN Ten Bit Addressing Enable This bit enables 10-bit addressing. This bit can be written simultaneously with ADDR to indicate a 10-bit or 7-bit address transmission. Value Description 0 10-bit addressing disabled. 1 10-bit addressing enabled. Bit 14 – HS High Speed This bit enables High-speed mode for the current transfer from repeated START to STOP. This bit can be written simultaneously with ADDR for a high speed transfer. Value Description 0 High-speed transfer disabled. 1 High-speed transfer enabled. Bit 13 – LENEN Transfer Length Enable SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 869 Value Description 0 Automatic transfer length disabled. 1 Automatic transfer length enabled. Bits 10:0 – ADDR[10:0] Address When ADDR is written, the consecutive operation will depend on the bus state: UNKNOWN: INTFLAG.MB and STATUS.BUSERR are set, and the operation is terminated. BUSY: The I2C master will await further operation until the bus becomes IDLE. IDLE: The I2C master will issue a start condition followed by the address written in ADDR. If the address is acknowledged, SCL is forced and held low, and STATUS.CLKHOLD and INTFLAG.MB are set. OWNER: A repeated start sequence will be performed. If the previous transaction was a read, the acknowledge action is sent before the repeated start bus condition is issued on the bus. Writing ADDR to issue a repeated start is performed while INTFLAG.MB or INTFLAG.SB is set. STATUS.BUSERR, STATUS.ARBLOST, INTFLAG.MB and INTFLAG.SB will be cleared when ADDR is written. The ADDR register can be read at any time without interfering with ongoing bus activity, as a read access does not trigger the master logic to perform any bus protocol related operations. The I2C master control logic uses bit 0 of ADDR as the bus protocol’s read/write flag (R/W); 0 for write and 1 for read. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 870 37.10.10 Data Name:  DATA Offset:  0x28 Reset:  0x0000 Property:  - Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 DATA[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 7:0 – DATA[7:0] Data The master data register I/O location (DATA) provides access to the master transmit and receive data buffers. Reading valid data or writing data to be transmitted can be successfully done only when SCL is held low by the master (STATUS.CLKHOLD is set). An exception is reading the last data byte after the stop condition has been sent. Accessing DATA.DATA auto-triggers I2C bus operations. The operation performed depends on the state of CTRLB.ACKACT, CTRLB.SMEN and the type of access (read/write). Writing or reading DATA.DATA when not in Smart mode does not require synchronization. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 871 37.10.11 Debug Control Name:  DBGCTRL Offset:  0x30 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DBGSTOP Access R/W Reset 0 Bit 0 – DBGSTOP Debug Stop Mode This bit controls functionality when the CPU is halted by an external debugger. Value Description 0 The baud-rate generator continues normal operation when the CPU is halted by an external debugger. 1 The baud-rate generator is halted when the CPU is halted by an external debugger. SAM L10/L11 Family SERCOM I2C – SERCOM Inter-Integrated Circ... © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 872 38. TC – Timer/Counter 38.1 Overview There are up to three TC peripheral instances. Each TC consists of a counter, a prescaler, compare/capture channels and control logic. The counter can be set to count events, or clock pulses. The counter, together with the compare/capture channels, can be configured to timestamp input events or IO pin edges, allowing for capturing of frequency and/or pulse width. A TC can also perform waveform generation, such as frequency generation and pulse-width modulation. 38.2 Features • Selectable configuration – 8-, 16- or 32-bit TC operation, with compare/capture channels • 2 compare/capture channels (CC) with: – Double buffered timer period setting (in 8-bit mode only) – Double buffered compare channel • Waveform generation – Frequency generation – Single-slope pulse-width modulation • Input capture – Event / IO pin edge capture – Frequency capture – Pulse-width capture – Time-stamp capture • One input event • Interrupts/output events on: – Counter overflow/underflow – Compare match or capture • Internal prescaler • DMA support SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 873 38.3 Block Diagram Figure 38-1. Timer/Counter Block Diagram Base Counter "count" "clear" "load" "direction" TOP BOTTOM "event" UPDATE = OVF (INT/Event/DMA Req.) ERR (INT Req.) TC Input Event PERBUF PER Prescaler Compare/Capture (Unit x = {0,1} BUFV "capture" "match" Control Logic WO[1] WO[0] MCx (INT/Event/DMA Req.) Counter BUFV = 0 Event System = Waveform Generation Control Logic COUNT CCx CCBUFx 38.4 Signal Description Table 38-1. Signal Description for TC. Signal Name Type Description WO[1:0] Digital output Waveform output Digital input Capture input Refer to I/O Multiplexing and Considerations for details on the pin mapping for this peripheral. One signal can be mapped on several pins. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 874 38.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 38.5.1 I/O Lines In order to use the I/O lines of this peripheral, the I/O pins must be configured using the I/O Pin Controller (PORT). Related Links 32. PORT - I/O Pin Controller 38.5.2 Power Management This peripheral can continue to operate in any sleep mode where its source clock is running. The interrupts can wake up the device from sleep modes. Events connected to the event system can trigger other operations in the system without exiting sleep modes. Related Links 22. PM – Power Manager 38.5.3 Clocks The TC bus clocks (CLK_TCx_APB) can be enabled and disabled in the Main Clock Module. The default state of CLK_TCx_APB can be found in the Peripheral Clock Masking. The generic clocks (GCLK_TCx) are asynchronous to the user interface clock (CLK_TCx_APB). Due to this asynchronicity, accessing certain registers will require synchronization between the clock domains. Refer to Synchronization for further details. Note:  Two instances of the TC may share a peripheral clock channel. In this case, they cannot be set to different clock frequencies. Refer to the peripheral clock channel mapping of the Generic Clock Controller (GCLK.PCHTRLm) to identify shared peripheral clocks. Related Links 18.8.4 PCHCTRLm 19.6.2.6 Peripheral Clock Masking 38.5.4 DMA The DMA request lines are connected to the DMA Controller (DMAC). In order to use DMA requests with this peripheral the DMAC must be configured first. Refer to DMAC – Direct Memory Access Controller for details. Related Links 28. DMAC – Direct Memory Access Controller 38.5.5 Interrupts The interrupt request line is connected to the Interrupt Controller. In order to use interrupt requests of this peripheral, the Interrupt Controller (NVIC) must be configured first. Refer to Nested Vector Interrupt Controller for details. 38.5.6 Events The events of this peripheral are connected to the Event System. Related Links SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 875 33. EVSYS – Event System 38.5.7 Debug Operation When the CPU is halted in debug mode, this peripheral will halt normal operation. This peripheral can be forced to continue operation during debugging - refer to the Debug Control (DBGCTRL) register for details. Related Links 38.7.1.11 DBGCTRL 38.5.8 Register Access Protection Registers with write-access can be optionally write-protected by the Peripheral Access Controller (PAC), except for the following: • Interrupt Flag Status and Clear register (INTFLAG) • Status register (STATUS) • Count register (COUNT) • Period and Period Buffer registers (PER, PERBUF) • Compare/Capture Value registers and Compare/Capture Value Buffer registers (CCx, CCBUFx) Note:  Optional write-protection is indicated by the "PAC Write-Protection" property in the register description. Write-protection does not apply for accesses through an external debugger. 38.5.9 Analog Connections Not applicable. 38.5.10 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 38.6 Functional Description 38.6.1 Principle of Operation The following definitions are used throughout the documentation: Table 38-2. Timer/Counter Definitions Name Description TOP The counter reaches TOP when it becomes equal to the highest value in the count sequence. The TOP value can be the same as Period (PER) SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 876 Name Description or the Compare Channel 0 (CC0) register value depending on the waveform generator mode in 38.6.2.6.1 Waveform Output Operations. ZERO The counter is ZERO when it contains all zeroes MAX The counter reaches MAX when it contains all ones UPDATE The timer/counter signals an update when it reaches ZERO or TOP, depending on the direction settings. Timer The timer/counter clock control is handled by an internal source Counter The clock control is handled externally (e.g. counting external events) CC For compare operations, the CC are referred to as “compare channels” For capture operations, the CC are referred to as “capture channels.” Each TC instance has up to two compare/capture channels (CC0 and CC1). The counter in the TC can either count events from the Event System, or clock ticks of the GCLK_TCx clock, which may be divided by the prescaler. The counter value is passed to the CCx where it can be either compared to user-defined values or captured. The CCx registers are using buffer registers (CCBUFx) for optimized timing. Each buffer register has a buffer valid (BUFV) flag that indicates when the buffer contains a new value. The Counter register (COUNT) and the Compare and Capture registers with buffers (CCx and CCBUFx) can be configured as 8-, 16- or 32-bit registers, with according MAX values. Mode settings (CTRLA.MODE) determine the maximum range of the Counter register. In 8-bit mode, a Period Value (PER) register and its Period Buffer Value (PERBUF) register are also available. The counter range and the operating frequency determine the maximum time resolution achievable with the TC peripheral. The TC can be set to count up or down. Under normal operation, the counter value is continuously compared to the TOP or ZERO value to determine whether the counter has reached that value. On a comparison match the TC can request DMA transactions, or generate interrupts or events for the Event System. In compare operation, the counter value is continuously compared to the values in the CCx registers. In case of a match the TC can request DMA transactions, or generate interrupts or events for the Event System. In waveform generator mode, these comparisons are used to set the waveform period or pulse width. Capture operation can be enabled to perform input signal period and pulse width measurements, or to capture selectable edges from an IO pin or internal event from Event System. 38.6.2 Basic Operation 38.6.2.1 Initialization The following registers are enable-protected, meaning that they can only be written when the TC is disabled (CTRLA.ENABLE =0): SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 877 • Control A register (CTRLA), except the Enable (ENABLE) and Software Reset (SWRST) bits • Drive Control register (DRVCTRL) • Wave register (WAVE) • Event Control register (EVCTRL) Writing to Enable-Protected bits and setting the CTRLA.ENABLE bit can be performed in a single 32-bit access of the CTRLA register. Writing to Enable-Protected bits and clearing the CTRLA.ENABLE bit cannot be performed in a single 32-bit access. Before enabling the TC, the peripheral must be configured by the following steps: 1. Enable the TC bus clock (CLK_TCx_APB). 2. Select 8-, 16- or 32-bit counter mode via the TC Mode bit group in the Control A register (CTRLA.MODE). The default mode is 16-bit. 3. Select one wave generation operation in the Waveform Generation Operation bit group in the WAVE register (WAVE.WAVEGEN). 4. If desired, the GCLK_TCx clock can be prescaled via the Prescaler bit group in the Control A register (CTRLA.PRESCALER). – If the prescaler is used, select a prescaler synchronization operation via the Prescaler and Counter Synchronization bit group in the Control A register (CTRLA.PRESYNC). 5. If desired, select one-shot operation by writing a '1' to the One-Shot bit in the Control B Set register (CTRLBSET.ONESHOT). 6. If desired, configure the counting direction 'down' (starting from the TOP value) by writing a '1' to the Counter Direction bit in the Control B register (CTRLBSET.DIR). 7. For capture operation, enable the individual channels to capture in the Capture Channel x Enable bit group in the Control A register (CTRLA.CAPTEN). 8. If desired, enable inversion of the waveform output or IO pin input signal for individual channels via the Invert Enable bit group in the Drive Control register (DRVCTRL.INVEN). 38.6.2.2 Enabling, Disabling, and Resetting The TC is enabled by writing a '1' to the Enable bit in the Control A register (CTRLA.ENABLE). The TC is disbled by writing a zero to CTRLA.ENABLE. The TC is reset by writing a '1' to the Software Reset bit in the Control A register (CTRLA.SWRST). All registers in the TC, except DBGCTRL, will be reset to their initial state. Refer to the CTRLA register for details. The TC should be disabled before the TC is reset in order to avoid undefined behavior. 38.6.2.3 Prescaler Selection The GCLK_TCx is fed into the internal prescaler. The prescaler consists of a counter that counts up to the selected prescaler value, whereupon the output of the prescaler toggles. If the prescaler value is higher than one, the counter update condition can be optionally executed on the next GCLK_TCx clock pulse or the next prescaled clock pulse. For further details, refer to Prescaler (CTRLA.PRESCALER) and Counter Synchronization (CTRLA.PRESYNC) description. Prescaler outputs from 1 to 1/1024 are available. For a complete list of available prescaler outputs, see the register description for the Prescaler bit group in the Control A register (CTRLA.PRESCALER). Note:  When counting events, the prescaler is bypassed. The joint stream of prescaler ticks and event action ticks is called CLK_TC_CNT. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 878 Figure 38-2. Prescaler PRESCALER GCLK_TC / {1,2,4,8,64,256,1024} GCLK_TC Prescaler CLK_TC_CNT COUNT EVACT EVENT 38.6.2.4 Counter Mode The counter mode is selected by the Mode bit group in the Control A register (CTRLA.MODE). By default, the counter is enabled in the 16-bit counter resolution. Three counter resolutions are available: • COUNT8: The 8-bit TC has its own Period Value and Period Buffer Value registers (PER and PERBUF). • COUNT16: 16-bit is the default counter mode. There is no dedicated period register in this mode. • COUNT32: This mode is achieved by pairing two 16-bit TC peripherals. TCn is paired with TCn+1. TC2 does not support 32-bit resolution. When paired, the TC peripherals are configured using the registers of the even-numbered TC. The odd-numbered partner will act as a slave, and the Slave bit in the Status register (STATUS.SLAVE) will be set. The register values of a slave will not reflect the registers of the 32-bit counter. Writing to any of the slave registers will not affect the 32-bit counter. Normal access to the slave COUNT and CCx registers is not allowed. 38.6.2.5 Counter Operations Depending on the mode of operation, the counter is cleared, reloaded, incremented, or decremented at each TC clock input (CLK_TC_CNT). A counter clear or reload marks the end of the current counter cycle and the start of a new one. The counting direction is set by the Direction bit in the Control B register (CTRLB.DIR). If this bit is zero the counter is counting up, and counting down if CTRLB.DIR=1. The counter will count up or down for each tick (clock or event) until it reaches TOP or ZERO. When it is counting up and TOP is reached, the counter will be set to zero at the next tick (overflow) and the Overflow Interrupt Flag in the Interrupt Flag Status and Clear register (INTFLAG.OVF) will be set. When it is counting down, the counter is reloaded with the TOP value when ZERO is reached (underflow), and INTFLAG.OVF is set. INTFLAG.OVF can be used to trigger an interrupt, a DMA request, or an event. An overflow/underflow occurrence (i.e., a compare match with TOP/ZERO) will stop counting if the One-Shot bit in the Control B register is set (CTRLBSET.ONESHOT). It is possible to change the counter value (by writing directly in the COUNT register) even when the counter is running. When starting the TC, the COUNT value will be either ZERO or TOP (depending on the counting direction set by CTRLBSET.DIR or CTRLBCLR.DIR), unless a different value has been written to it, or the TC has been stopped at a value other than ZERO. The write access has higher priority than count, clear, or reload. The direction of the counter can also be changed when the counter is running. See also the following figure. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 879 Figure 38-3. Counter Operation DIR COUNT MAX "reload" update TOP Period (T) Direction Change COUNT written ZERO "clear" update Due to asynchronous clock domains, the internal counter settings are written when the synchronization is complete. Normal operation must be used when using the counter as timer base for the capture channels. 38.6.2.5.1 Stop Command and Event Action A Stop command can be issued from software by using Command bits in the Control B Set register (CTRLBSET.CMD = 0x2, STOP). When a Stop is detected while the counter is running, the counter will be loaded with the starting value (ZERO or TOP, depending on direction set by CTRLBSET.DIR or CTRLBCLR.DIR). All waveforms are cleared and the Stop bit in the Status register is set (STATUS.STOP). 38.6.2.5.2 Re-Trigger Command and Event Action A re-trigger command can be issued from software by writing the Command bits in the Control B Set register (CTRLBSET.CMD = 0x1, RETRIGGER), or from event when a re-trigger event action is configured in the Event Control register (EVCTRL.EVACT = 0x1, RETRIGGER). When the command is detected during counting operation, the counter will be reloaded or cleared, depending on the counting direction (CTRLBSET.DIR or CTRLBCLR.DIR). When the re-trigger command is detected while the counter is stopped, the counter will resume counting from the current value in the COUNT register. Note:  When a re-trigger event action is configured in the Event Action bits in the Event Control register (EVCTRL.EVACT=0x1, RETRIGGER), enabling the counter will not start the counter. The counter will start on the next incoming event and restart on corresponding following event. 38.6.2.5.3 Count Event Action The TC can count events. When an event is received, the counter increases or decreases the value, depending on direction settings (CTRLBSET.DIR or CTRLBCLR.DIR). The count event action can be selected by the Event Action bit group in the Event Control register (EVCTRL.EVACT=0x2, COUNT). Note:  If this operation mode is selected, PWM generation is not supported. 38.6.2.5.4 Start Event Action The TC can start counting operation on an event when previously stopped. In this configuration, the event has no effect if the counter is already counting. When the peripheral is enabled, the counter operation starts when the event is received or when a re-trigger software command is applied. The Start TC on Event action can be selected by the Event Action bit group in the Event Control register (EVCTRL.EVACT=0x3, START). SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 880 38.6.2.6 Compare Operations By default, the Compare/Capture channel is configured for compare operations. When using the TC and the Compare/Capture Value registers (CCx) for compare operations, the counter value is continuously compared to the values in the CCx registers. This can be used for timer or for waveform operation. The Channel x Compare Buffer (CCBUFx) registers provide double buffer capability. The double buffering synchronizes the update of the CCx register with the buffer value at the UPDATE condition or a forced update command (CTRLBSET.CMD=UPDATE). For further details, refer to 38.6.2.7 Double Buffering. The synchronization prevents the occurrence of odd-length, non-symmetrical pulses and ensures glitchfree output. 38.6.2.6.1 Waveform Output Operations The compare channels can be used for waveform generation on output port pins. To make the waveform available on the connected pin, the following requirements must be fulfilled: 1. Choose a waveform generation mode in the Waveform Generation Operation bit in Waveform register (WAVE.WAVEGEN). 2. Optionally invert the waveform output WO[x] by writing the corresponding Output Waveform x Invert Enable bit in the Driver Control register (DRVCTRL.INVENx). 3. Configure the pins with the I/O Pin Controller. Refer to PORT - I/O Pin Controller for details. The counter value is continuously compared with each CCx value. On a comparison match, the Match or Capture Channel x bit in the Interrupt Flag Status and Clear register (INTFLAG.MCx) will be set on the next zero-to-one transition of CLK_TC_CNT (see Normal Frequency Operation). An interrupt/and or event can be generated on comparison match if enabled. The same condition generates a DMA request. There are four waveform configurations for the Waveform Generation Operation bit group in the Waveform register (WAVE.WAVEGEN). This will influence how the waveform is generated and impose restrictions on the top value. The configurations are: • Normal frequency (NFRQ) • Match frequency (MFRQ) • Normal pulse-width modulation (NPWM) • Match pulse-width modulation (MPWM) When using NPWM or NFRQ configuration, the TOP will be determined by the counter resolution. In 8-bit counter mode, the Period register (PER) is used as TOP, and the TOP can be changed by writing to the PER register. In 16- and 32-bit counter mode, TOP is fixed to the maximum (MAX) value of the counter. Normal Frequency Generation (NFRQ) For Normal Frequency Generation, the period time (T) is controlled by the period register (PER) for 8-bit counter mode and MAX for 16- and 32-bit mode. The waveform generation output (WO[x]) is toggled on each compare match between COUNT and CCx, and the corresponding Match or Capture Channel x Interrupt Flag (INTFLAG.MCx) will be set. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 881 Figure 38-4. Normal Frequency Operation COUNT MAX TOP ZERO CCx WO[x] Period (T) Direction Change COUNT Written "reload" update "clear" update "match" Match Frequency Generation (MFRQ) For Match Frequency Generation, the period time (T) is controlled by the CC0 register instead of PER or MAX. WO[0] toggles on each update condition. Figure 38-5. Match Frequency Operation COUNT MAX CC0 Period (T) Direction Change COUNT Written ZERO WO[0] "reload" update "clear" update Normal Pulse-Width Modulation Operation (NPWM) NPWM uses single-slope PWM generation. For single-slope PWM generation, the period time (T) is controlled by the TOP value, and CCx controls the duty cycle of the generated waveform output. When up-counting, the WO[x] is set at start or compare match between the COUNT and TOP values, and cleared on compare match between COUNT and CCx register values. When down-counting, the WO[x] is cleared at start or compare match between the COUNT and ZERO values, and set on compare match between COUNT and CCx register values. The following equation calculates the exact resolution for a single-slope PWM (RPWM_SS) waveform: ܴPWM_SS = log(TOP+1) log(2) The PWM frequency (fPWM_SS) depends on TOP value and the peripheral clock frequency (fGCLK_TC), and can be calculated by the following equation: ݂PWM_SS = ݂GCLK_TC N(TOP+1) Where N represents the prescaler divider used (1, 2, 4, 8, 16, 64, 256, 1024). Match Pulse-Width Modulation Operation (MPWM) In MPWM, the output of WO[1] is depending on CC1 as shown in the figure below. On every overflow/ underflow, a one-TC-clock-cycle negative pulse is put out on WO[0] (not shown in the figure). SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 882 Figure 38-6. Match PWM Operation COUNT MAX CC0 Period (T) " match" ZERO CCx=Zero CC1 CCx=TOP " clear" update WO[1] The table below shows the update counter and overflow event/interrupt generation conditions in different operation modes. Table 38-3. Counter Update and Overflow Event/interrupt Conditions in TC Name Operation TOP Update Output Waveform OVFIF/Event On Match On Update Up Down NFRQ Normal Frequency PER TOP/ ZERO Toggle Stable TOP ZERO MFRQ Match Frequency CC0 TOP/ ZERO Toggle Stable TOP ZERO NPWM Single-slope PWM PER TOP/ ZERO See description above. TOP ZERO MPWM Single-slope PWM CC0 TOP/ ZERO Toggle Toggle TOP ZERO Related Links 32. PORT - I/O Pin Controller 38.6.2.7 Double Buffering The Compare Channels (CCx) registers, and the Period (PER) register in 8-bit mode are double buffered. Each buffer register has a buffer valid bit (CCBUFVx or PERBUFV) in the STATUS register, which indicates that the buffer register contains a new valid value that can be copied into the corresponding register. As long as the respective buffer valid status flag (PERBUFV or CCBUFVx) are set to '1', related syncbusy bits are set (SYNCBUSY.PER or SYNCBUSY.CCx), a write to the respective PER/PERBUF or CCx/CCBUFx registers will generate a PAC error, and access to the respective PER or CCx register is invalid. When the buffer valid flag bit in the STATUS register is '1' and the Lock Update bit in the CTRLB register is set to '0', (writing CTRLBCLR.LUPD to '1'), double buffering is enabled: the data from buffer registers will be copied into the corresponding register under hardware UPDATE conditions, then the buffer valid flags bit in the STATUS register are automatically cleared by hardware. Note:  The software update command (CTRLBSET.CMD=0x3) is acting independently of the LUPD value. A compare register is double buffered as in the following figure. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 883 Figure 38-7. Compare Channel Double Buffering CCBUFVx UPDATE "write enable" "data write" = COUNT "match" EN EN CCBUFx CCx Both the registers (PER/CCx) and corresponding buffer registers (PERBUF/CCBUFx) are available in the I/O register map, and the double buffering feature is not mandatory. The double buffering is disabled by writing a '1' to CTRLBSET.LUPD. Note:  In NFRQ, MFRQ or PWM down-counting counter mode (CTRLBSET.DIR=1), when double buffering is enabled (CTRLBCLR.LUPD=1), PERBUF register is continously copied into the PER independently of update conditions. Changing the Period The counter period can be changed by writing a new TOP value to the Period register (PER or CC0, depending on the waveform generation mode), which is available in 8-bit mode. Any period update on registers (PER or CCx) is effective after the synchronization delay. Figure 38-8. Unbuffered Single-Slope Up-Counting Operation COUNT MAX New TOP written to PER that is higher than current COUNT Counter Wraparound New TOP written to PER that is lower than current COUNT "clear" update "write" ZERO A counter wraparound can occur in any operation mode when up-counting without buffering, see Figure 38-8. COUNT and TOP are continuously compared, so when a new TOP value that is lower than current COUNT is written to TOP, COUNT will wrap before a compare match. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 884 Figure 38-9. Unbuffered Single-Slope Down-Counting Operation COUNT MAX New TOP written to PER that is higher than current COUNT New TOP written to PER that is lower than current COUNT "reload" update "write" ZERO When double buffering is used, the buffer can be written at any time and the counter will still maintain correct operation. The period register is always updated on the update condition, as shown in Figure 38-10. This prevents wraparound and the generation of odd waveforms. Figure 38-10. Changing the Period Using Buffering COUNT MAX New TOP written to PER that is higher than current COUNT "clear" update "write" ZERO New TOP written to PER that is lower than current COUNT 38.6.2.8 Capture Operations To enable and use capture operations, the corresponding Capture Channel x Enable bit in the Control A register (CTRLA.CAPTENx) must be written to '1'. A capture trigger can be provided by input event line TC_EV or by asynchronous IO pin WO[x] for each capture channel or by a TC event. To enable the capture from input event line, Event Input Enable bit in the Event Control register (EVCTRL.TCEI) must be written to '1'. To enable the capture from the IO pin, the Capture On Pin x Enable bit in CTRLA register (CTRLA.COPENx) must be written to '1'. Note:  1. The RETRIGGER, COUNT and START event actions are available only on an event from the Event System. 2. Event system channels must be configured to operate in asynchronous mode of operation when used for capture operations. By default, a capture operation is done when a rising edge is detected on the input signal. Capture on falling edge is available, its activation is depending on the input source: • When the channel is used with a IO pin, write a '1' to the corresponding Invert Enable bit in the Drive Control register (DRVCTRL.INVENx). SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 885 • When the channel is counting events from the Event System, write a '1' to the TC Event Input Invert Enable bit in Event Control register (EVCTRL.TCINV). Figure 38-11. Capture Double Buffering BV "capture" IF COUNT CCBx EN CCx EN "INT/DMA request" data read For input capture, the buffer register and the corresponding CCx act like a FIFO. When CCx is empty or read, any content in CCBUFx is transferred to CCx. The buffer valid flag is passed to set the CCx interrupt flag (IF) and generate the optional interrupt, event or DMA request. The CCBUFx register value can't be read, all captured data must be read from CCx register. 38.6.2.8.1 Event Capture Action The compare/capture channels can be used as input capture channels to capture events from the Event System and give them a timestamp. The following figure shows four capture events for one capture channel. Figure 38-12. Input Capture Timing events COUNT TOP ZERO Capture 0 Capture 1 Capture 2 Capture 3 The TC can detect capture overflow of the input capture channels: When a new capture event is detected while the Capture Interrupt flag (INTFLAG.MCx) is still set, the new timestamp will not be stored and INTFLAG.ERR will be set. 38.6.2.8.2 Period and Pulse-Width (PPW) Capture Action The TC can perform two input captures and restart the counter on one of the edges. This enables the TC to measure the pulse width and period and to characterize the frequency f and duty cycle of an input signal: SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 886 ݂ = 1 ܶ dutyCycle = ݌ݐ ܶ Figure 38-13. PWP Capture Period (T) external signal events COUNT MAX ZERO "capture" Pulsewitdh (tp) CC0 CC1 CC0 CC1 Selecting PWP in the Event Action bit group in the Event Control register (EVCTRL.EVACT) enables the TC to perform one capture action on the rising edge and the other one on the falling edge. The period T will be captured into CC1 and the pulse width tp in CC0. EVCTRL.EVACT=PPW (period and pulse-width) offers identical functionality, but will capture T into CC0 and tp into CC1. The TC Event Input Invert Enable bit in the Event Control register (EVCTRL.TCINV) is used to select whether the wraparound should occur on the rising edge or the falling edge. If EVCTRL.TCINV=1, the wraparound will happen on the falling edge. In case pin capture is enabled, this can also be achieved by modifying the value of the DRVCTRL.INVENx bit. The TC can detect capture overflow of the input capture channels: When a new capture event is detected while the Capture Interrupt flag (INTFLAG.MCx) is still set, the new timestamp will not be stored and INTFLAG.ERR will be set. Note:  The corresponding capture is working only if the channel is enabled in capture mode (CTRLA.CAPTENx=1). If not, the capture action is ignored and the channel is enabled in compare mode of operation. Consequently, both channels must be enabled in order to fully characterize the input. 38.6.2.8.3 Pulse-Width Capture Action The TC performs the input capture on the falling edge of the input signal. When the edge is detected, the counter value is cleared and the TC stops counting. When a rising edge is detected on the input signal, the counter restarts the counting operation. To enable the operation on opposite edges, the input signal to capture must be inverted (refer to DRVCTRL.INVEN or EVCTRL.TCEINV). SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 887 Figure 38-14. Pulse-Width Capture on Channel 0 external signal events COUNT MAX ZERO "capture" Pulsewitdh (tp) CC0 CC0 "restart" The TC can detect capture overflow of the input capture channels: When a new capture event is detected while the Capture Interrupt flag (INTFLAG.MCx) is still set, the new timestamp will not be stored and INTFLAG.ERR will be set. 38.6.3 Additional Features 38.6.3.1 One-Shot Operation When one-shot is enabled, the counter automatically stops on the next counter overflow or underflow condition. When the counter is stopped, the Stop bit in the Status register (STATUS.STOP) is automatically set and the waveform outputs are set to zero. One-shot operation is enabled by writing a '1' to the One-Shot bit in the Control B Set register (CTRLBSET.ONESHOT), and disabled by writing a '1' to CTRLBCLR.ONESHOT. When enabled, the TC will count until an overflow or underflow occurs and stops counting operation. The one-shot operation can be restarted by a re-trigger software command, a re-trigger event, or a start event. When the counter restarts its operation, STATUS.STOP is automatically cleared. 38.6.3.2 Time-Stamp Capture This feature is enabled when the Capture Time Stamp (STAMP) Event Action in Event Control register (EVCTRL.EVACT) is selected. The counter TOP value must be smaller than MAX. When a capture event is detected, the COUNT value is copied into the corresponding Channel x Compare/Capture Value (CCx) register. In case of an overflow, the MAX value is copied into the corresponding CCx register. When a valid captured value is present in the capture channel register, the corresponding Capture Channel x Interrupt Flag (INTFLAG.MCx) is set. The timer/counter can detect capture overflow of the input capture channels: When a new capture event is detected while the Capture Channel interrupt flag (INTFLAG.MCx) is still set, the new time-stamp will not be stored and INTFLAG.ERR will be set. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 888 Figure 38-15. Time-Stamp MAX ZERO COUNT TOP "capture" "overflow" Capture Events CCx Value COUNT COUNT COUNTTOP MAX 38.6.4 DMA Operation The TC can generate the following DMA requests: • Overflow (OVF): the request is set when an update condition (overflow, underflow or re-trigger) is detected, the request is cleared by hardware on DMA acknowledge. • Match or Capture Channel x (MCx): for a compare channel, the request is set on each compare match detection, the request is cleared by hardware on DMA acknowledge. For a capture channel, the request is set when valid data is present in the CCx register, and cleared when CCx register is read. 38.6.5 Interrupts The TC has the following interrupt sources: • Overflow/Underflow (OVF) • Match or Capture Channel x (MCx) • Capture Overflow Error (ERR) Each interrupt source has an interrupt flag associated with it. The interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG) is set when the interrupt condition occurs. Each interrupt can be individually enabled by writing a '1' to the corresponding bit in the Interrupt Enable Set register (INTENSET), and disabled by writing a '1' to the corresponding bit in the Interrupt Enable Clear register (INTENCLR). An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until either the interrupt flag is cleared, the interrupt is disabled, or the TC is reset. See INTFLAG for details on how to clear interrupt flags. The TC has one common interrupt request line for all the interrupt sources. The user must read the INTFLAG register to determine which interrupt condition is present. Note that interrupts must be globally enabled for interrupt requests to be generated. Refer to Nested Vector Interrupt Controller for details. 38.6.6 Events The TC can generate the following output events: • Overflow/Underflow (OVF) • Match or Capture Channel x (MCx) SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 889 Writing a '1' to an Event Output bit in the Event Control register (EVCTRL.MCEOx) enables the corresponding output event. The output event is disabled by writing EVCTRL.MCEOx=0. One of the following event actions can be selected by the Event Action bit group in the Event Control register (EVCTRL.EVACT): • Disable event action (OFF) • Start TC (START) • Re-trigger TC (RETRIGGER) • Count on event (COUNT) • Capture time stamp (STAMP) • Capture Period (PPW and PWP) • Capture Pulse Width (PW) Writing a '1' to the TC Event Input bit in the Event Control register (EVCTRL.TCEI) enables input events to the TC. Writing a '0' to this bit disables input events to the TC. The TC requires only asynchronous event inputs. For further details on how configuring the asynchronous events, refer to EVSYS - Event System. Related Links 33. EVSYS – Event System 38.6.7 Sleep Mode Operation The TC can be configured to operate in any sleep mode. To be able to run in standby, the RUNSTDBY bit in the Control A register (CTRLA.RUNSTDBY) must be '1'. This peripheral can wake up the device from any sleep mode using interrupts or perform actions through the Event System. If the On Demand bit in the Control A register (CTRLA.ONDEMAND) is written to '1', the module stops requesting its peripheral clock when the STOP bit in STATUS register (STATUS.STOP) is set to '1'. When a re-trigger or start condition is detected, the TC requests the clock before the operation starts. 38.6.8 Synchronization Due to asynchronicity between the main clock domain and the peripheral clock domains, some registers need to be synchronized when written or read. The following bits are synchronized when written: • Software Reset and Enable bits in Control A register (CTRLA.SWRST and CTRLA.ENABLE) • Capture Channel Buffer Valid bit in STATUS register (STATUS.CCBUFVx) The following registers are synchronized when written: • Control B Clear and Control B Set registers (CTRLBCLR and CTRLBSET) • Count Value register (COUNT) • Period Value and Period Buffer Value registers (PER and PERBUF) • Channel x Compare/Capture Value and Channel x Compare/Capture Buffer Value registers (CCx and CCBUFx) The following registers are synchronized when read: • Count Value register (COUNT): synchronization is done on demand through READSYNC command (CTRLBSET.CMD). Required write-synchronization is denoted by the "Write-Synchronized" property in the register description. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 890 Required read-synchronization is denoted by the "Read-Synchronized" property in the register description. 38.7 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to Register Access Protection. Some registers are synchronized when read and/or written. Synchronization is denoted by the "WriteSynchronized" or the "Read-Synchronized" property in each individual register description. For details, refer to Synchronization. Some registers are enable-protected, meaning they can only be written when the peripheral is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 891 38.7.1 Register Summary - 8-bit Mode Offset Name Bit Pos. 0x00 CTRLA 7:0 ONDEMAND RUNSTDBY PRESCSYNC[1:0] MODE[1:0] ENABLE SWRST 15:8 ALOCK PRESCALER[2:0] 23:16 COPEN1 COPEN0 CAPTEN1 CAPTEN0 31:24 0x04 CTRLBCLR 7:0 CMD[2:0] ONESHOT LUPD DIR 0x05 CTRLBSET 7:0 CMD[2:0] ONESHOT LUPD DIR 0x06 EVCTRL 7:0 TCEI TCINV EVACT[2:0] 15:8 MCEOx MCEOx OVFEO 0x08 INTENCLR 7:0 MCx ERR OVF 0x09 INTENSET 7:0 MCx ERR OVF 0x0A INTFLAG 7:0 MCx ERR OVF 0x0B STATUS 7:0 CCBUFVx PERBUFV SLAVE STOP 0x0C WAVE 7:0 WAVEGEN[1:0] 0x0D DRVCTRL 7:0 INVENx 0x0E Reserved 0x0F DBGCTRL 7:0 DBGRUN 0x10 SYNCBUSY 7:0 CCx PER COUNT STATUS CTRLB ENABLE SWRST 15:8 23:16 31:24 0x14 COUNT 7:0 COUNT[7:0] 0x15 ... 0x1A Reserved 0x1B PER 7:0 PER[7:0] 0x1C CC0 7:0 CC[7:0] 0x1D CC1 7:0 CC[7:0] 0x1E ... 0x2E Reserved 0x2F PERBUF 7:0 PERBUF[7:0] 0x30 CCBUF0 7:0 CCBUF[7:0] 0x31 CCBUF1 7:0 CCBUF[7:0] SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 892 38.7.1.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00000000 Property:  PAC Write-Protection, Write-Synchronized, Enable-Protected Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 COPEN1 COPEN0 CAPTEN1 CAPTEN0 Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 ALOCK PRESCALER[2:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 6 5 4 3 2 1 0 ONDEMAND RUNSTDBY PRESCSYNC[1:0] MODE[1:0] ENABLE SWRST Access R/W R/W R/W R/W R/W R/W R/W W Reset 0 0 0 0 0 0 0 0 Bits 20, 21 – COPENx Capture On Pin x Enable Bit x of COPEN[1:0] selects the trigger source for capture operation, either events or I/O pin input. Value Description 0 Event from Event System is selected as trigger source for capture operation on channel x. 1 I/O pin is selected as trigger source for capture operation on channel x. Bits 16, 17 – CAPTENx Capture Channel x Enable Bit x of CAPTEN[1:0] selects whether channel x is a capture or a compare channel. These bits are not synchronized. Value Description 0 CAPTEN disables capture on channel x. 1 CAPTEN enables capture on channel x. Bit 11 – ALOCK Auto Lock When this bit is set, Lock bit update (LUPD) is set to '1' on each overflow/underflow or re-trigger event. This bit is not synchronized. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 893 Value Description 0 The LUPD bit is not affected on overflow/underflow, and re-trigger event. 1 The LUPD bit is set on each overflow/underflow or re-trigger event. Bits 10:8 – PRESCALER[2:0] Prescaler These bits select the counter prescaler factor. These bits are not synchronized. Value Name Description 0x0 DIV1 Prescaler: GCLK_TC 0x1 DIV2 Prescaler: GCLK_TC/2 0x2 DIV4 Prescaler: GCLK_TC/4 0x3 DIV8 Prescaler: GCLK_TC/8 0x4 DIV16 Prescaler: GCLK_TC/16 0x5 DIV64 Prescaler: GCLK_TC/64 0x6 DIV256 Prescaler: GCLK_TC/256 0x7 DIV1024 Prescaler: GCLK_TC/1024 Bit 7 – ONDEMAND Clock On Demand This bit selects the clock requirements when the TC is stopped. In standby mode, if the Run in Standby bit (CTRLA.RUNSTDBY) is '0', ONDEMAND is forced to '0'. This bit is not synchronized. Value Description 0 The On Demand is disabled. If On Demand is disabled, the TC will continue to request the clock when its operation is stopped (STATUS.STOP=1). 1 The On Demand is enabled. When On Demand is enabled, the stopped TC will not request the clock. The clock is requested when a software re-trigger command is applied or when an event with start/re-trigger action is detected. Bit 6 – RUNSTDBY Run in Standby This bit is used to keep the TC running in standby mode. This bit is not synchronized. Value Description 0 The TC is halted in standby. 1 The TC continues to run in standby. Bits 5:4 – PRESCSYNC[1:0] Prescaler and Counter Synchronization These bits select whether the counter should wrap around on the next GCLK_TCx clock or the next prescaled GCLK_TCx clock. It also makes it possible to reset the prescaler. These bits are not synchronized. Value Name Description 0x0 GCLK Reload or reset the counter on next generic clock 0x1 PRESC Reload or reset the counter on next prescaler clock 0x2 RESYNC Reload or reset the counter on next generic clock. Reset the prescaler counter 0x3 - Reserved SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 894 Bits 3:2 – MODE[1:0] Timer Counter Mode These bits select the counter mode. These bits are not synchronized. Value Name Description 0x0 COUNT16 Counter in 16-bit mode 0x1 COUNT8 Counter in 8-bit mode 0x2 COUNT32 Counter in 32-bit mode 0x3 - Reserved Bit 1 – ENABLE Enable Due to synchronization, there is delay from writing CTRLA.ENABLE until the peripheral is enabled/ disabled. The value written to CTRLA.ENABLE will read back immediately, and the ENABLE Synchronization Busy bit in the SYNCBUSY register (SYNCBUSY.ENABLE) will be set. SYNCBUSY.ENABLE will be cleared when the operation is complete. This bit is not enable protected. Value Description 0 The peripheral is disabled. 1 The peripheral is enabled. Bit 0 – SWRST Software Reset Writing a '0' to this bit has no effect. Writing a '1' to this bit resets all registers in the TC, except DBGCTRL, to their initial state, and the TC will be disabled. Writing a '1' to CTRLA.SWRST will always take precedence; all other writes in the same write-operation will be discarded. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 895 38.7.1.2 Control B Clear Name:  CTRLBCLR Offset:  0x04 Reset:  0x00 Property:  PAC Write-Protection, Read-Synchronized, Write-Synchronized This register allows the user to clear bits in the CTRLB register without doing a read-modify-write operation. Changes in this register will also be reflected in the Control B Set register (CTRLBSET). Bit 7 6 5 4 3 2 1 0 CMD[2:0] ONESHOT LUPD DIR Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bits 7:5 – CMD[2:0] Command These bits are used for software control of the TC. The commands are executed on the next prescaled GCLK_TC clock cycle. When a command has been executed, the CMD bit group will be read back as zero. Writing 0x0 to these bits has no effect. Writing a '1' to any of these bits will clear the pending command. Bit 2 – ONESHOT One-Shot on Counter This bit controls one-shot operation of the TC. Writing a '0' to this bit has no effect Writing a '1' to this bit will disable one-shot operation. Value Description 0 The TC will wrap around and continue counting on an overflow/underflow condition. 1 The TC will wrap around and stop on the next underflow/overflow condition. Bit 1 – LUPD Lock Update This bit controls the update operation of the TC buffered registers. When CTRLB.LUPD is set, no any update of the registers with value of its buffered register is performed on hardware UPDATE condition. Locking the update ensures that all buffer registers are valid before an hardware update is performed. After all the buffer registers are loaded correctly, the buffered registers can be unlocked. This bit has no effect when input capture operation is enabled. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the LUPD bit. Value Description 0 The CCBUFx and PERBUF buffer registers value are copied into CCx and PER registers on hardware update condition. 1 The CCBUFx and PERBUF buffer registers value are not copied into CCx and PER registers on hardware update condition. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 896 Bit 0 – DIR Counter Direction This bit is used to change the direction of the counter. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the bit and make the counter count up. Value Description 0 The timer/counter is counting up (incrementing). 1 The timer/counter is counting down (decrementing). SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 897 38.7.1.3 Control B Set Name:  CTRLBSET Offset:  0x05 Reset:  0x00 Property:  PAC Write-Protection, Read-synchronized, Write-Synchronized This register allows the user to set bits in the CTRLB register without doing a read-modify-write operation. Changes in this register will also be reflected in the Control B Clear register (CTRLBCLR). Bit 7 6 5 4 3 2 1 0 CMD[2:0] ONESHOT LUPD DIR Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bits 7:5 – CMD[2:0] Command These bits are used for software control of the TC. The commands are executed on the next prescaled GCLK_TC clock cycle. When a command has been executed, the CMD bit group will be read back as zero. Writing 0x0 to these bits has no effect. Writing a value different from 0x0 to these bits will issue a command for execution. Value Name Description 0x0 NONE No action 0x1 RETRIGGER Force a start, restart or retrigger 0x2 STOP Force a stop 0x3 UPDATE Force update of double buffered registers 0x4 READSYNC Force a read synchronization of COUNT Bit 2 – ONESHOT One-Shot on Counter This bit controls one-shot operation of the TC. Writing a '0' to this bit has no effect. Writing a '1' to this bit will enable one-shot operation. Value Description 0 The TC will wrap around and continue counting on an overflow/underflow condition. 1 The TC will wrap around and stop on the next underflow/overflow condition. Bit 1 – LUPD Lock Update This bit controls the update operation of the TC buffered registers. When CTRLB.LUPD is set, no any update of the registers with value of its buffered register is performed on hardware UPDATE condition. Locking the update ensures that all buffer registers are valid before an hardware update is performed. After all the buffer registers are loaded correctly, the buffered registers can be unlocked. Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the LUPD bit. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 898 This bit has no effect when input capture operation is enabled. Value Description 0 The CCBUFx and PERBUF buffer registers value are copied into CCx and PER registers on hardware update condition. 1 The CCBUFx and PERBUF buffer registers value are not copied into CCx and PER registers on hardware update condition. Bit 0 – DIR Counter Direction This bit is used to change the direction of the counter. Writing a '0' to this bit has no effect Writing a '1' to this bit will clear the bit and make the counter count up. Value Description 0 The timer/counter is counting up (incrementing). 1 The timer/counter is counting down (decrementing). SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 899 38.7.1.4 Event Control Name:  EVCTRL Offset:  0x06 Reset:  0x0000 Property:  PAC Write-Protection, Enable-Protected Bit 15 14 13 12 11 10 9 8 MCEOx MCEOx OVFEO Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 TCEI TCINV EVACT[2:0] Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bits 13,12 – MCEOx Match or Capture Channel x Event Output Enable [x = 1..0] These bits enable the generation of an event for every match or capture on channel x. Value Description 0 Match/Capture event on channel x is disabled and will not be generated. 1 Match/Capture event on channel x is enabled and will be generated for every compare/ capture. Bit 8 – OVFEO Overflow/Underflow Event Output Enable This bit enables the Overflow/Underflow event. When enabled, an event will be generated when the counter overflows/underflows. Value Description 0 Overflow/Underflow event is disabled and will not be generated. 1 Overflow/Underflow event is enabled and will be generated for every counter overflow/ underflow. Bit 5 – TCEI TC Event Enable This bit is used to enable asynchronous input events to the TC. Value Description 0 Incoming events are disabled. 1 Incoming events are enabled. Bit 4 – TCINV TC Inverted Event Input Polarity This bit inverts the asynchronous input event source. Value Description 0 Input event source is not inverted. 1 Input event source is inverted. Bits 2:0 – EVACT[2:0] Event Action These bits define the event action the TC will perform on an event. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 900 Value Name Description 0x0 OFF Event action disabled 0x1 RETRIGGER Start, restart or retrigger TC on event 0x2 COUNT Count on event 0x3 START Start TC on event 0x4 STAMP Time stamp capture 0x5 PPW Period captured in CC0, pulse width in CC1 0x6 PWP Period captured in CC1, pulse width in CC0 0x7 PW Pulse width capture SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 901 38.7.1.5 Interrupt Enable Clear Name:  INTENCLR Offset:  0x08 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 7 6 5 4 3 2 1 0 MCx ERR OVF Access R/W R/W R/W Reset 0 0 0 Bit 4 – MCx Match or Capture Channel x Interrupt Enable Writing a '0' to these bits has no effect. Writing a '1' to MCx will clear the corresponding Match or Capture Channel x Interrupt Enable bit, which disables the Match or Capture Channel x interrupt. Value Description 0 The Match or Capture Channel x interrupt is disabled. 1 The Match or Capture Channel x interrupt is enabled. Bit 1 – ERR Error Interrupt Disable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Error Interrupt Enable bit, which disables the Error interrupt. Value Description 0 The Error interrupt is disabled. 1 The Error interrupt is enabled. Bit 0 – OVF Overflow Interrupt Disable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Overflow Interrupt Enable bit, which disables the Overflow interrupt request. Value Description 0 The Overflow interrupt is disabled. 1 The Overflow interrupt is enabled. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 902 38.7.1.6 Interrupt Enable Set Name:  INTENSET Offset:  0x09 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear register (INTENCLR). Bit 7 6 5 4 3 2 1 0 MCx ERR OVF Access R/W R/W R/W Reset 0 0 0 Bit 4 – MCx Match or Capture Channel x Interrupt Enable Writing a '0' to these bits has no effect. Writing a '1' to MCx will set the corresponding Match or Capture Channel x Interrupt Enable bit, which enables the Match or Capture Channel x interrupt. Value Description 0 The Match or Capture Channel x interrupt is disabled. 1 The Match or Capture Channel x interrupt is enabled. Bit 1 – ERR Error Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Error Interrupt Enable bit, which enables the Error interrupt. Value Description 0 The Error interrupt is disabled. 1 The Error interrupt is enabled. Bit 0 – OVF Overflow Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Overflow Interrupt Enable bit, which enables the Overflow interrupt request. Value Description 0 The Overflow interrupt is disabled. 1 The Overflow interrupt is enabled. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 903 38.7.1.7 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x0A Reset:  0x00 Property:  - Bit 7 6 5 4 3 2 1 0 MCx ERR OVF Access R/W R/W R/W Reset 0 0 0 Bit 4 – MCx Match or Capture Channel x This flag is set on a comparison match, or when the corresponding CCx register contains a valid capture value. This flag is set on the next CLK_TC_CNT cycle, and will generate an interrupt request if the corresponding Match or Capture Channel x Interrupt Enable bit in the Interrupt Enable Set register (INTENSET.MCx) is '1'. Writing a '0' to one of these bits has no effect. Writing a '1' to one of these bits will clear the corresponding Match or Capture Channel x interrupt flag In capture operation, this flag is automatically cleared when CCx register is read. Bit 1 – ERR Error Interrupt Flag This flag is set when a new capture occurs on a channel while the corresponding Match or Capture Channel x interrupt flag is set, in which case there is nowhere to store the new capture. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Error interrupt flag. Bit 0 – OVF Overflow Interrupt Flag This flag is set on the next CLK_TC_CNT cycle after an overflow condition occurs, and will generate an interrupt request if INTENCLR.OVF or INTENSET.OVF is '1'. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Overflow interrupt flag. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 904 38.7.1.8 Status Name:  STATUS Offset:  0x0B Reset:  0x01 Property:  Read-Synchronized Bit 7 6 5 4 3 2 1 0 CCBUFVx PERBUFV SLAVE STOP Access R/W R/W R R Reset 0 0 0 1 Bit 4 – CCBUFVx Channel x Compare or Capture Buffer Valid For a compare channel x, the bit x is set when a new value is written to the corresponding CCBUFx register. The bit x is cleared by writing a '1' to it when CTRLB.LUPD is set, or it is cleared automatically by hardware on UPDATE condition. For a capture channel x, the bit x is set when a valid capture value is stored in the CCBUFx register. The bit x is cleared automatically when the CCx register is read. Bit 3 – PERBUFV Period Buffer Valid This bit is set when a new value is written to the PERBUF register. The bit is cleared by writing '1' to the corresponding location when CTRLB.LUPD is set, or automatically cleared by hardware on UPDATE condition. This bit is available only in 8-bit mode and will always read zero in 16- and 32-bit modes. Bit 1 – SLAVE Slave Status Flag This bit is only available in 32-bit mode on the slave TC (i.e., TC1 and/or TC3). The bit is set when the associated master TC (TC0 and TC2, respectively) is set to run in 32-bit mode. Bit 0 – STOP Stop Status Flag This bit is set when the TC is disabled, on a Stop command, or on an overflow/underflow condition when the One-Shot bit in the Control B Set register (CTRLBSET.ONESHOT) is '1'. Value Description 0 Counter is running. 1 Counter is stopped. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 905 38.7.1.9 Waveform Generation Control Name:  WAVE Offset:  0x0C Reset:  0x00 Property:  PAC Write-Protection, Enable-Protected Bit 7 6 5 4 3 2 1 0 WAVEGEN[1:0] Access R/W R/W Reset 0 0 Bits 1:0 – WAVEGEN[1:0] Waveform Generation Mode These bits select the waveform generation operation. They affect the top value, as shown in 38.6.2.6.1 Waveform Output Operations. They also control whether frequency or PWM waveform generation should be used. The waveform generation operations are explained in 38.6.2.6.1 Waveform Output Operations. These bits are not synchronized. Value Name Operation Top Value Output Waveform on Match Output Waveform on Wraparound 0x0 NFRQ Normal frequency PER1 / Max Toggle No action 0x1 MFRQ Match frequency CC0 Toggle No action 0x2 NPWM Normal PWM PER1 / Max Set Clear 0x3 MPWM Match PWM CC0 Set Clear 1) This depends on the TC mode: In 8-bit mode, the top value is the Period Value register (PER). In 16- and 32-bit mode it is the respective MAX value. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 906 38.7.1.10 Driver Control Name:  DRVCTRL Offset:  0x0D Reset:  0x00 Property:  PAC Write-Protection, Enable-Protected Bit 7 6 5 4 3 2 1 0 INVENx Access R/W Reset 0 Bit 0 – INVENx Output Waveform x Invert Enable Bit x of INVEN[1:0] selects inversion of the output or capture trigger input of channel x. Value Description 0 Disable inversion of the WO[x] output and IO input pin. 1 Enable inversion of the WO[x] output and IO input pin. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 907 38.7.1.11 Debug Control Name:  DBGCTRL Offset:  0x0F Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DBGRUN Access R/W Reset 0 Bit 0 – DBGRUN Run in Debug Mode This bit is not affected by a software Reset, and should not be changed by software while the TC is enabled. Value Description 0 The TC is halted when the device is halted in debug mode. 1 The TC continues normal operation when the device is halted in debug mode. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 908 38.7.1.12 Synchronization Busy Name:  SYNCBUSY Offset:  0x10 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 CCx PER COUNT STATUS CTRLB ENABLE SWRST Access R R R R R R R Reset 0 0 0 0 0 0 0 Bit 6 – CCx Compare/Capture Channel x Synchronization Busy For details on CC channels number, refer to each TC feature list. This bit is set when the synchronization of CCx between clock domains is started. This bit is also set when the CCBUFx is written, and cleared on update condition. The bit is automatically cleared when the STATUS.CCBUFx bit is cleared. Bit 5 – PER PER Synchronization Busy This bit is cleared when the synchronization of PER between the clock domains is complete. This bit is set when the synchronization of PER between clock domains is started. This bit is also set when the PER is written, and cleared on update condition. The bit is automatically cleared when the STATUS.PERBUF bit is cleared. Bit 4 – COUNT COUNT Synchronization Busy This bit is cleared when the synchronization of COUNT between the clock domains is complete. This bit is set when the synchronization of COUNT between clock domains is started. Bit 3 – STATUS STATUS Synchronization Busy This bit is cleared when the synchronization of STATUS between the clock domains is complete. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 909 This bit is set when a '1' is written to the Capture Channel Buffer Valid status flags (STATUS.CCBUFVx) and the synchronization of STATUS between clock domains is started. Bit 2 – CTRLB CTRLB Synchronization Busy This bit is cleared when the synchronization of CTRLB between the clock domains is complete. This bit is set when the synchronization of CTRLB between clock domains is started. Bit 1 – ENABLE ENABLE Synchronization Busy This bit is cleared when the synchronization of ENABLE bit between the clock domains is complete. This bit is set when the synchronization of ENABLE bit between clock domains is started. Bit 0 – SWRST SWRST Synchronization Busy This bit is cleared when the synchronization of SWRST bit between the clock domains is complete. This bit is set when the synchronization of SWRST bit between clock domains is started. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 910 38.7.1.13 Counter Value, 8-bit Mode Name:  COUNT Offset:  0x14 Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized, Read-Synchronized Note:  Prior to any read access, this register must be synchronized by user by writing the according TC Command value to the Control B Set register (CTRLBSET.CMD=READSYNC). Bit 7 6 5 4 3 2 1 0 COUNT[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 7:0 – COUNT[7:0]  Counter Value These bits contain the current counter value. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 911 38.7.1.14 Period Value, 8-bit Mode Name:  PER Offset:  0x1B Reset:  0xFF Property:  Write-Synchronized Bit 7 6 5 4 3 2 1 0 PER[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 1 Bits 7:0 – PER[7:0] Period Value These bits hold the value of the Period Buffer register PERBUF. The value is copied to PER register on UPDATE condition. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 912 38.7.1.15 Channel x Compare/Capture Value, 8-bit Mode Name:  CCx Offset:  0x1C + x*0x01 [x=0..1] Reset:  0x00 Property:  Write-Synchronized, Read-Synchronized Bit 7 6 5 4 3 2 1 0 CC[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 7:0 – CC[7:0] Channel x Compare/Capture Value These bits contain the compare/capture value in 8-bit TC mode. In Match frequency (MFRQ) or Match PWM (MPWM) waveform operation (WAVE.WAVEGEN), the CC0 register is used as a period register. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 913 38.7.1.16 Period Buffer Value, 8-bit Mode Name:  PERBUF Offset:  0x2F Reset:  0xFF Property:  Write-Synchronized Bit 7 6 5 4 3 2 1 0 PERBUF[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 1 Bits 7:0 – PERBUF[7:0] Period Buffer Value These bits hold the value of the period buffer register. The value is copied to PER register on UPDATE condition. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 914 38.7.1.17 Channel x Compare Buffer Value, 8-bit Mode Name:  CCBUFx Offset:  0x30 + x*0x01 [x=0..1] Reset:  0x00 Property:  Write-Synchronized Bit 7 6 5 4 3 2 1 0 CCBUF[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 7:0 – CCBUF[7:0] Channel x Compare Buffer Value These bits hold the value of the Channel x Compare Buffer Value. When the buffer valid flag is '1' and double buffering is enabled (CTRLBCLR.LUPD=1), the data from buffer registers will be copied into the corresponding CCx register under UPDATE condition (CTRLBSET.CMD=0x3), including the software update command. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 915 38.7.2 Register Summary - 16-bit Mode Offset Name Bit Pos. 0x00 CTRLA 7:0 ONDEMAND RUNSTDBY PRESCSYNC[1:0] MODE[1:0] ENABLE SWRST 15:8 ALOCK PRESCALER[2:0] 23:16 COPEN1 COPEN0 CAPTEN1 CAPTEN0 31:24 0x04 CTRLBCLR 7:0 CMD[2:0] ONESHOT LUPD DIR 0x05 CTRLBSET 7:0 CMD[2:0] ONESHOT LUPD DIR 0x06 EVCTRL 7:0 TCEI TCINV EVACT[2:0] 15:8 MCEOx MCEOx OVFEO 0x08 INTENCLR 7:0 MCx ERR OVF 0x09 INTENSET 7:0 MCx ERR OVF 0x0A INTFLAG 7:0 MCx ERR OVF 0x0B STATUS 7:0 CCBUFVx PERBUFV SLAVE STOP 0x0C WAVE 7:0 WAVEGEN[1:0] 0x0D DRVCTRL 7:0 INVENx 0x0E Reserved 0x0F DBGCTRL 7:0 DBGRUN 0x10 SYNCBUSY 7:0 CCx PER COUNT STATUS CTRLB ENABLE SWRST 15:8 23:16 31:24 0x14 COUNT 7:0 COUNT[7:0] 15:8 COUNT[15:8] 0x16 ... 0x19 Reserved 0x1A PER 7:0 PER[7:0] 15:8 PER[15:8] 0x1C CC0 7:0 CC[7:0] 15:8 CC[15:8] 0x1E CC1 7:0 CC[7:0] 15:8 CC[15:8] 0x20 ... 0x2D Reserved 0x2E PERBUF 7:0 PERBUF[7:0] 15:8 PERBUF[15:8] 0x30 CCBUF0 7:0 CCBUF[7:0] 15:8 CCBUF[15:8] 0x32 CCBUF1 7:0 CCBUF[7:0] 15:8 CCBUF[15:8] SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 916 38.7.2.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00000000 Property:  PAC Write-Protection, Write-Synchronized, Enable-Protected Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 COPEN1 COPEN0 CAPTEN1 CAPTEN0 Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 ALOCK PRESCALER[2:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 6 5 4 3 2 1 0 ONDEMAND RUNSTDBY PRESCSYNC[1:0] MODE[1:0] ENABLE SWRST Access R/W R/W R/W R/W R/W R/W R/W W Reset 0 0 0 0 0 0 0 0 Bits 20, 21 – COPENx Capture On Pin x Enable Bit x of COPEN[1:0] selects the trigger source for capture operation, either events or I/O pin input. Value Description 0 Event from Event System is selected as trigger source for capture operation on channel x. 1 I/O pin is selected as trigger source for capture operation on channel x. Bits 16, 17 – CAPTENx Capture Channel x Enable Bit x of CAPTEN[1:0] selects whether channel x is a capture or a compare channel. These bits are not synchronized. Value Description 0 CAPTEN disables capture on channel x. 1 CAPTEN enables capture on channel x. Bit 11 – ALOCK Auto Lock When this bit is set, Lock bit update (LUPD) is set to '1' on each overflow/underflow or re-trigger event. This bit is not synchronized. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 917 Value Description 0 The LUPD bit is not affected on overflow/underflow, and re-trigger event. 1 The LUPD bit is set on each overflow/underflow or re-trigger event. Bits 10:8 – PRESCALER[2:0] Prescaler These bits select the counter prescaler factor. These bits are not synchronized. Value Name Description 0x0 DIV1 Prescaler: GCLK_TC 0x1 DIV2 Prescaler: GCLK_TC/2 0x2 DIV4 Prescaler: GCLK_TC/4 0x3 DIV8 Prescaler: GCLK_TC/8 0x4 DIV16 Prescaler: GCLK_TC/16 0x5 DIV64 Prescaler: GCLK_TC/64 0x6 DIV256 Prescaler: GCLK_TC/256 0x7 DIV1024 Prescaler: GCLK_TC/1024 Bit 7 – ONDEMAND Clock On Demand This bit selects the clock requirements when the TC is stopped. In standby mode, if the Run in Standby bit (CTRLA.RUNSTDBY) is '0', ONDEMAND is forced to '0'. This bit is not synchronized. Value Description 0 The On Demand is disabled. If On Demand is disabled, the TC will continue to request the clock when its operation is stopped (STATUS.STOP=1). 1 The On Demand is enabled. When On Demand is enabled, the stopped TC will not request the clock. The clock is requested when a software re-trigger command is applied or when an event with start/re-trigger action is detected. Bit 6 – RUNSTDBY Run in Standby This bit is used to keep the TC running in standby mode. This bit is not synchronized. Value Description 0 The TC is halted in standby. 1 The TC continues to run in standby. Bits 5:4 – PRESCSYNC[1:0] Prescaler and Counter Synchronization These bits select whether the counter should wrap around on the next GCLK_TCx clock or the next prescaled GCLK_TCx clock. It also makes it possible to reset the prescaler. These bits are not synchronized. Value Name Description 0x0 GCLK Reload or reset the counter on next generic clock 0x1 PRESC Reload or reset the counter on next prescaler clock 0x2 RESYNC Reload or reset the counter on next generic clock. Reset the prescaler counter 0x3 - Reserved SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 918 Bits 3:2 – MODE[1:0] Timer Counter Mode These bits select the counter mode. These bits are not synchronized. Value Name Description 0x0 COUNT16 Counter in 16-bit mode 0x1 COUNT8 Counter in 8-bit mode 0x2 COUNT32 Counter in 32-bit mode 0x3 - Reserved Bit 1 – ENABLE Enable Due to synchronization, there is delay from writing CTRLA.ENABLE until the peripheral is enabled/ disabled. The value written to CTRLA.ENABLE will read back immediately, and the ENABLE Synchronization Busy bit in the SYNCBUSY register (SYNCBUSY.ENABLE) will be set. SYNCBUSY.ENABLE will be cleared when the operation is complete. This bit is not enable protected. Value Description 0 The peripheral is disabled. 1 The peripheral is enabled. Bit 0 – SWRST Software Reset Writing a '0' to this bit has no effect. Writing a '1' to this bit resets all registers in the TC, except DBGCTRL, to their initial state, and the TC will be disabled. Writing a '1' to CTRLA.SWRST will always take precedence; all other writes in the same write-operation will be discarded. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 919 38.7.2.2 Control B Clear Name:  CTRLBCLR Offset:  0x04 Reset:  0x00 Property:  PAC Write-Protection, Read-Synchronized, Write-Synchronized This register allows the user to clear bits in the CTRLB register without doing a read-modify-write operation. Changes in this register will also be reflected in the Control B Set register (CTRLBSET). Bit 7 6 5 4 3 2 1 0 CMD[2:0] ONESHOT LUPD DIR Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bits 7:5 – CMD[2:0] Command These bits are used for software control of the TC. The commands are executed on the next prescaled GCLK_TC clock cycle. When a command has been executed, the CMD bit group will be read back as zero. Writing 0x0 to these bits has no effect. Writing a '1' to any of these bits will clear the pending command. Bit 2 – ONESHOT One-Shot on Counter This bit controls one-shot operation of the TC. Writing a '0' to this bit has no effect Writing a '1' to this bit will disable one-shot operation. Value Description 0 The TC will wrap around and continue counting on an overflow/underflow condition. 1 The TC will wrap around and stop on the next underflow/overflow condition. Bit 1 – LUPD Lock Update This bit controls the update operation of the TC buffered registers. When CTRLB.LUPD is set, no any update of the registers with value of its buffered register is performed on hardware UPDATE condition. Locking the update ensures that all buffer registers are valid before an hardware update is performed. After all the buffer registers are loaded correctly, the buffered registers can be unlocked. This bit has no effect when input capture operation is enabled. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the LUPD bit. Value Description 0 The CCBUFx and PERBUF buffer registers value are copied into CCx and PER registers on hardware update condition. 1 The CCBUFx and PERBUF buffer registers value are not copied into CCx and PER registers on hardware update condition. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 920 Bit 0 – DIR Counter Direction This bit is used to change the direction of the counter. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the bit and make the counter count up. Value Description 0 The timer/counter is counting up (incrementing). 1 The timer/counter is counting down (decrementing). SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 921 38.7.2.3 Control B Set Name:  CTRLBSET Offset:  0x05 Reset:  0x00 Property:  PAC Write-Protection, Read-synchronized, Write-Synchronized This register allows the user to set bits in the CTRLB register without doing a read-modify-write operation. Changes in this register will also be reflected in the Control B Clear register (CTRLBCLR). Bit 7 6 5 4 3 2 1 0 CMD[2:0] ONESHOT LUPD DIR Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bits 7:5 – CMD[2:0] Command These bits are used for software control of the TC. The commands are executed on the next prescaled GCLK_TC clock cycle. When a command has been executed, the CMD bit group will be read back as zero. Writing 0x0 to these bits has no effect. Writing a value different from 0x0 to these bits will issue a command for execution. Value Name Description 0x0 NONE No action 0x1 RETRIGGER Force a start, restart or retrigger 0x2 STOP Force a stop 0x3 UPDATE Force update of double buffered registers 0x4 READSYNC Force a read synchronization of COUNT Bit 2 – ONESHOT One-Shot on Counter This bit controls one-shot operation of the TC. Writing a '0' to this bit has no effect. Writing a '1' to this bit will enable one-shot operation. Value Description 0 The TC will wrap around and continue counting on an overflow/underflow condition. 1 The TC will wrap around and stop on the next underflow/overflow condition. Bit 1 – LUPD Lock Update This bit controls the update operation of the TC buffered registers. When CTRLB.LUPD is set, no any update of the registers with value of its buffered register is performed on hardware UPDATE condition. Locking the update ensures that all buffer registers are valid before an hardware update is performed. After all the buffer registers are loaded correctly, the buffered registers can be unlocked. Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the LUPD bit. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 922 This bit has no effect when input capture operation is enabled. Value Description 0 The CCBUFx and PERBUF buffer registers value are copied into CCx and PER registers on hardware update condition. 1 The CCBUFx and PERBUF buffer registers value are not copied into CCx and PER registers on hardware update condition. Bit 0 – DIR Counter Direction This bit is used to change the direction of the counter. Writing a '0' to this bit has no effect Writing a '1' to this bit will clear the bit and make the counter count up. Value Description 0 The timer/counter is counting up (incrementing). 1 The timer/counter is counting down (decrementing). SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 923 38.7.2.4 Event Control Name:  EVCTRL Offset:  0x06 Reset:  0x0000 Property:  PAC Write-Protection, Enable-Protected Bit 15 14 13 12 11 10 9 8 MCEOx MCEOx OVFEO Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 TCEI TCINV EVACT[2:0] Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bits 13,12 – MCEOx Match or Capture Channel x Event Output Enable [x = 1..0] These bits enable the generation of an event for every match or capture on channel x. Value Description 0 Match/Capture event on channel x is disabled and will not be generated. 1 Match/Capture event on channel x is enabled and will be generated for every compare/ capture. Bit 8 – OVFEO Overflow/Underflow Event Output Enable This bit enables the Overflow/Underflow event. When enabled, an event will be generated when the counter overflows/underflows. Value Description 0 Overflow/Underflow event is disabled and will not be generated. 1 Overflow/Underflow event is enabled and will be generated for every counter overflow/ underflow. Bit 5 – TCEI TC Event Enable This bit is used to enable asynchronous input events to the TC. Value Description 0 Incoming events are disabled. 1 Incoming events are enabled. Bit 4 – TCINV TC Inverted Event Input Polarity This bit inverts the asynchronous input event source. Value Description 0 Input event source is not inverted. 1 Input event source is inverted. Bits 2:0 – EVACT[2:0] Event Action These bits define the event action the TC will perform on an event. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 924 Value Name Description 0x0 OFF Event action disabled 0x1 RETRIGGER Start, restart or retrigger TC on event 0x2 COUNT Count on event 0x3 START Start TC on event 0x4 STAMP Time stamp capture 0x5 PPW Period captured in CC0, pulse width in CC1 0x6 PWP Period captured in CC1, pulse width in CC0 0x7 PW Pulse width capture SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 925 38.7.2.5 Interrupt Enable Clear Name:  INTENCLR Offset:  0x08 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 7 6 5 4 3 2 1 0 MCx ERR OVF Access R/W R/W R/W Reset 0 0 0 Bit 4 – MCx Match or Capture Channel x Interrupt Enable Writing a '0' to these bits has no effect. Writing a '1' to MCx will clear the corresponding Match or Capture Channel x Interrupt Enable bit, which disables the Match or Capture Channel x interrupt. Value Description 0 The Match or Capture Channel x interrupt is disabled. 1 The Match or Capture Channel x interrupt is enabled. Bit 1 – ERR Error Interrupt Disable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Error Interrupt Enable bit, which disables the Error interrupt. Value Description 0 The Error interrupt is disabled. 1 The Error interrupt is enabled. Bit 0 – OVF Overflow Interrupt Disable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Overflow Interrupt Enable bit, which disables the Overflow interrupt request. Value Description 0 The Overflow interrupt is disabled. 1 The Overflow interrupt is enabled. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 926 38.7.2.6 Interrupt Enable Set Name:  INTENSET Offset:  0x09 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear register (INTENCLR). Bit 7 6 5 4 3 2 1 0 MCx ERR OVF Access R/W R/W R/W Reset 0 0 0 Bit 4 – MCx Match or Capture Channel x Interrupt Enable Writing a '0' to these bits has no effect. Writing a '1' to MCx will set the corresponding Match or Capture Channel x Interrupt Enable bit, which enables the Match or Capture Channel x interrupt. Value Description 0 The Match or Capture Channel x interrupt is disabled. 1 The Match or Capture Channel x interrupt is enabled. Bit 1 – ERR Error Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Error Interrupt Enable bit, which enables the Error interrupt. Value Description 0 The Error interrupt is disabled. 1 The Error interrupt is enabled. Bit 0 – OVF Overflow Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Overflow Interrupt Enable bit, which enables the Overflow interrupt request. Value Description 0 The Overflow interrupt is disabled. 1 The Overflow interrupt is enabled. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 927 38.7.2.7 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x0A Reset:  0x00 Property:  - Bit 7 6 5 4 3 2 1 0 MCx ERR OVF Access R/W R/W R/W Reset 0 0 0 Bit 4 – MCx Match or Capture Channel x This flag is set on a comparison match, or when the corresponding CCx register contains a valid capture value. This flag is set on the next CLK_TC_CNT cycle, and will generate an interrupt request if the corresponding Match or Capture Channel x Interrupt Enable bit in the Interrupt Enable Set register (INTENSET.MCx) is '1'. Writing a '0' to one of these bits has no effect. Writing a '1' to one of these bits will clear the corresponding Match or Capture Channel x interrupt flag In capture operation, this flag is automatically cleared when CCx register is read. Bit 1 – ERR Error Interrupt Flag This flag is set when a new capture occurs on a channel while the corresponding Match or Capture Channel x interrupt flag is set, in which case there is nowhere to store the new capture. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Error interrupt flag. Bit 0 – OVF Overflow Interrupt Flag This flag is set on the next CLK_TC_CNT cycle after an overflow condition occurs, and will generate an interrupt request if INTENCLR.OVF or INTENSET.OVF is '1'. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Overflow interrupt flag. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 928 38.7.2.8 Status Name:  STATUS Offset:  0x0B Reset:  0x01 Property:  Read-Synchronized Bit 7 6 5 4 3 2 1 0 CCBUFVx PERBUFV SLAVE STOP Access R/W R/W R R Reset 0 0 0 1 Bit 4 – CCBUFVx Channel x Compare or Capture Buffer Valid For a compare channel x, the bit x is set when a new value is written to the corresponding CCBUFx register. The bit x is cleared by writing a '1' to it when CTRLB.LUPD is set, or it is cleared automatically by hardware on UPDATE condition. For a capture channel x, the bit x is set when a valid capture value is stored in the CCBUFx register. The bit x is cleared automatically when the CCx register is read. Bit 3 – PERBUFV Period Buffer Valid This bit is set when a new value is written to the PERBUF register. The bit is cleared by writing '1' to the corresponding location when CTRLB.LUPD is set, or automatically cleared by hardware on UPDATE condition. This bit is available only in 8-bit mode and will always read zero in 16- and 32-bit modes. Bit 1 – SLAVE Slave Status Flag This bit is only available in 32-bit mode on the slave TC (i.e., TC1 and/or TC3). The bit is set when the associated master TC (TC0 and TC2, respectively) is set to run in 32-bit mode. Bit 0 – STOP Stop Status Flag This bit is set when the TC is disabled, on a Stop command, or on an overflow/underflow condition when the One-Shot bit in the Control B Set register (CTRLBSET.ONESHOT) is '1'. Value Description 0 Counter is running. 1 Counter is stopped. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 929 38.7.2.9 Waveform Generation Control Name:  WAVE Offset:  0x0C Reset:  0x00 Property:  PAC Write-Protection, Enable-Protected Bit 7 6 5 4 3 2 1 0 WAVEGEN[1:0] Access R/W R/W Reset 0 0 Bits 1:0 – WAVEGEN[1:0] Waveform Generation Mode These bits select the waveform generation operation. They affect the top value, as shown in 38.6.2.6.1 Waveform Output Operations. They also control whether frequency or PWM waveform generation should be used. The waveform generation operations are explained in 38.6.2.6.1 Waveform Output Operations. These bits are not synchronized. Value Name Operation Top Value Output Waveform on Match Output Waveform on Wraparound 0x0 NFRQ Normal frequency PER1 / Max Toggle No action 0x1 MFRQ Match frequency CC0 Toggle No action 0x2 NPWM Normal PWM PER1 / Max Set Clear 0x3 MPWM Match PWM CC0 Set Clear 1) This depends on the TC mode: In 8-bit mode, the top value is the Period Value register (PER). In 16- and 32-bit mode it is the respective MAX value. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 930 38.7.2.10 Driver Control Name:  DRVCTRL Offset:  0x0D Reset:  0x00 Property:  PAC Write-Protection, Enable-Protected Bit 7 6 5 4 3 2 1 0 INVENx Access R/W Reset 0 Bit 0 – INVENx Output Waveform x Invert Enable Bit x of INVEN[1:0] selects inversion of the output or capture trigger input of channel x. Value Description 0 Disable inversion of the WO[x] output and IO input pin. 1 Enable inversion of the WO[x] output and IO input pin. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 931 38.7.2.11 Debug Control Name:  DBGCTRL Offset:  0x0F Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DBGRUN Access R/W Reset 0 Bit 0 – DBGRUN Run in Debug Mode This bit is not affected by a software Reset, and should not be changed by software while the TC is enabled. Value Description 0 The TC is halted when the device is halted in debug mode. 1 The TC continues normal operation when the device is halted in debug mode. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 932 38.7.2.12 Synchronization Busy Name:  SYNCBUSY Offset:  0x10 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 CCx PER COUNT STATUS CTRLB ENABLE SWRST Access R R R R R R R Reset 0 0 0 0 0 0 0 Bit 6 – CCx Compare/Capture Channel x Synchronization Busy For details on CC channels number, refer to each TC feature list. This bit is set when the synchronization of CCx between clock domains is started. This bit is also set when the CCBUFx is written, and cleared on update condition. The bit is automatically cleared when the STATUS.CCBUFx bit is cleared. Bit 5 – PER PER Synchronization Busy This bit is cleared when the synchronization of PER between the clock domains is complete. This bit is set when the synchronization of PER between clock domains is started. This bit is also set when the PER is written, and cleared on update condition. The bit is automatically cleared when the STATUS.PERBUF bit is cleared. Bit 4 – COUNT COUNT Synchronization Busy This bit is cleared when the synchronization of COUNT between the clock domains is complete. This bit is set when the synchronization of COUNT between clock domains is started. Bit 3 – STATUS STATUS Synchronization Busy This bit is cleared when the synchronization of STATUS between the clock domains is complete. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 933 This bit is set when a '1' is written to the Capture Channel Buffer Valid status flags (STATUS.CCBUFVx) and the synchronization of STATUS between clock domains is started. Bit 2 – CTRLB CTRLB Synchronization Busy This bit is cleared when the synchronization of CTRLB between the clock domains is complete. This bit is set when the synchronization of CTRLB between clock domains is started. Bit 1 – ENABLE ENABLE Synchronization Busy This bit is cleared when the synchronization of ENABLE bit between the clock domains is complete. This bit is set when the synchronization of ENABLE bit between clock domains is started. Bit 0 – SWRST SWRST Synchronization Busy This bit is cleared when the synchronization of SWRST bit between the clock domains is complete. This bit is set when the synchronization of SWRST bit between clock domains is started. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 934 38.7.2.13 Counter Value, 16-bit Mode Name:  COUNT Offset:  0x14 Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized, Read-Synchronized Note:  Prior to any read access, this register must be synchronized by user by writing the according TC Command value to the Control B Set register (CTRLBSET.CMD=READSYNC). Bit 15 14 13 12 11 10 9 8 COUNT[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 COUNT[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 15:0 – COUNT[15:0]  Counter Value These bits contain the current counter value. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 935 38.7.2.14 Period Value, 16-bit Mode Name:  PER Offset:  0x1A Reset:  0xFFFF Property:  Write-Synchronized Bit 15 14 13 12 11 10 9 8 PER[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 PER[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 1 Bits 15:0 – PER[15:0] Period Value These bits hold the value of the Period Buffer register PERBUF. The value is copied to PER register on UPDATE condition. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 936 38.7.2.15 Channel x Compare/Capture Value, 16-bit Mode Name:  CCx Offset:  0x1C + x*0x02 [x=0..1] Reset:  0x0000 Property:  Write-Synchronized Bit 15 14 13 12 11 10 9 8 CC[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 CC[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 15:0 – CC[15:0] Channel x Compare/Capture Value These bits contain the compare/capture value in 16-bit TC mode. In Match frequency (MFRQ) or Match PWM (MPWM) waveform operation (WAVE.WAVEGEN), the CC0 register is used as a period register. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 937 38.7.2.16 Period Buffer Value, 16-bit Mode Name:  PERBUF Offset:  0x2E Reset:  0xFFFF Property:  Write-Synchronized Bit 15 14 13 12 11 10 9 8 PERBUF[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 PERBUF[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 1 Bits 15:0 – PERBUF[15:0] Period Buffer Value These bits hold the value of the period buffer register. The value is copied to PER register on UPDATE condition. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 938 38.7.2.17 Channel x Compare Buffer Value, 16-bit Mode Name:  CCBUFx Offset:  0x30 + x*0x02 [x=0..1] Reset:  0x0000 Property:  Write-Synchronized Bit 15 14 13 12 11 10 9 8 CCBUF[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 CCBUF[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 15:0 – CCBUF[15:0] Channel x Compare Buffer Value These bits hold the value of the Channel x Compare Buffer Value. When the buffer valid flag is '1' and double buffering is enabled (CTRLBCLR.LUPD=1), the data from buffer registers will be copied into the corresponding CCx register under UPDATE condition (CTRLBSET.CMD=0x3), including the software update command. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 939 38.7.3 Register Summary - 32-bit Mode Offset Name Bit Pos. 0x00 CTRLA 7:0 ONDEMAND RUNSTDBY PRESCSYNC[1:0] MODE[1:0] ENABLE SWRST 15:8 ALOCK PRESCALER[2:0] 23:16 COPEN1 COPEN0 CAPTEN1 CAPTEN0 31:24 0x04 CTRLBCLR 7:0 CMD[2:0] ONESHOT LUPD DIR 0x05 CTRLBSET 7:0 CMD[2:0] ONESHOT LUPD DIR 0x06 EVCTRL 7:0 TCEI TCINV EVACT[2:0] 15:8 MCEOx MCEOx OVFEO 0x08 INTENCLR 7:0 MCx ERR OVF 0x09 INTENSET 7:0 MCx ERR OVF 0x0A INTFLAG 7:0 MCx ERR OVF 0x0B STATUS 7:0 CCBUFVx PERBUFV SLAVE STOP 0x0C WAVE 7:0 WAVEGEN[1:0] 0x0D DRVCTRL 7:0 INVENx 0x0E Reserved 0x0F DBGCTRL 7:0 DBGRUN 0x10 SYNCBUSY 7:0 CCx PER COUNT STATUS CTRLB ENABLE SWRST 15:8 23:16 31:24 0x14 COUNT 7:0 COUNT[7:0] 15:8 COUNT[15:8] 23:16 COUNT[23:16] 31:24 COUNT[31:24] 0x18 ... 0x19 Reserved 0x1A PER 7:0 PER[7:0] 15:8 PER[15:8] 23:16 PER[23:16] 31:24 PER[31:24] 0x1C CC0 7:0 CC[7:0] 15:8 CC[15:8] 23:16 CC[23:16] 31:24 CC[31:24] 0x20 CC1 7:0 CC[7:0] 15:8 CC[15:8] 23:16 CC[23:16] 31:24 CC[31:24] 0x24 ... 0x2B Reserved 0x2C PERBUF 7:0 PERBUF[7:0] 15:8 PERBUF[15:8] SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 940 Offset Name Bit Pos. 23:16 PERBUF[23:16] 31:24 PERBUF[31:24] 0x30 CCBUF0 7:0 CCBUF[7:0] 15:8 CCBUF[15:8] 23:16 CCBUF[23:16] 31:24 CCBUF[31:24] 0x34 CCBUF1 7:0 CCBUF[7:0] 15:8 CCBUF[15:8] 23:16 CCBUF[23:16] 31:24 CCBUF[31:24] SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 941 38.7.3.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00000000 Property:  PAC Write-Protection, Write-Synchronized, Enable-Protected Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 COPEN1 COPEN0 CAPTEN1 CAPTEN0 Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 15 14 13 12 11 10 9 8 ALOCK PRESCALER[2:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 6 5 4 3 2 1 0 ONDEMAND RUNSTDBY PRESCSYNC[1:0] MODE[1:0] ENABLE SWRST Access R/W R/W R/W R/W R/W R/W R/W W Reset 0 0 0 0 0 0 0 0 Bits 20, 21 – COPENx Capture On Pin x Enable Bit x of COPEN[1:0] selects the trigger source for capture operation, either events or I/O pin input. Value Description 0 Event from Event System is selected as trigger source for capture operation on channel x. 1 I/O pin is selected as trigger source for capture operation on channel x. Bits 16, 17 – CAPTENx Capture Channel x Enable Bit x of CAPTEN[1:0] selects whether channel x is a capture or a compare channel. These bits are not synchronized. Value Description 0 CAPTEN disables capture on channel x. 1 CAPTEN enables capture on channel x. Bit 11 – ALOCK Auto Lock When this bit is set, Lock bit update (LUPD) is set to '1' on each overflow/underflow or re-trigger event. This bit is not synchronized. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 942 Value Description 0 The LUPD bit is not affected on overflow/underflow, and re-trigger event. 1 The LUPD bit is set on each overflow/underflow or re-trigger event. Bits 10:8 – PRESCALER[2:0] Prescaler These bits select the counter prescaler factor. These bits are not synchronized. Value Name Description 0x0 DIV1 Prescaler: GCLK_TC 0x1 DIV2 Prescaler: GCLK_TC/2 0x2 DIV4 Prescaler: GCLK_TC/4 0x3 DIV8 Prescaler: GCLK_TC/8 0x4 DIV16 Prescaler: GCLK_TC/16 0x5 DIV64 Prescaler: GCLK_TC/64 0x6 DIV256 Prescaler: GCLK_TC/256 0x7 DIV1024 Prescaler: GCLK_TC/1024 Bit 7 – ONDEMAND Clock On Demand This bit selects the clock requirements when the TC is stopped. In standby mode, if the Run in Standby bit (CTRLA.RUNSTDBY) is '0', ONDEMAND is forced to '0'. This bit is not synchronized. Value Description 0 The On Demand is disabled. If On Demand is disabled, the TC will continue to request the clock when its operation is stopped (STATUS.STOP=1). 1 The On Demand is enabled. When On Demand is enabled, the stopped TC will not request the clock. The clock is requested when a software re-trigger command is applied or when an event with start/re-trigger action is detected. Bit 6 – RUNSTDBY Run in Standby This bit is used to keep the TC running in standby mode. This bit is not synchronized. Value Description 0 The TC is halted in standby. 1 The TC continues to run in standby. Bits 5:4 – PRESCSYNC[1:0] Prescaler and Counter Synchronization These bits select whether the counter should wrap around on the next GCLK_TCx clock or the next prescaled GCLK_TCx clock. It also makes it possible to reset the prescaler. These bits are not synchronized. Value Name Description 0x0 GCLK Reload or reset the counter on next generic clock 0x1 PRESC Reload or reset the counter on next prescaler clock 0x2 RESYNC Reload or reset the counter on next generic clock. Reset the prescaler counter 0x3 - Reserved SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 943 Bits 3:2 – MODE[1:0] Timer Counter Mode These bits select the counter mode. These bits are not synchronized. Value Name Description 0x0 COUNT16 Counter in 16-bit mode 0x1 COUNT8 Counter in 8-bit mode 0x2 COUNT32 Counter in 32-bit mode 0x3 - Reserved Bit 1 – ENABLE Enable Due to synchronization, there is delay from writing CTRLA.ENABLE until the peripheral is enabled/ disabled. The value written to CTRLA.ENABLE will read back immediately, and the ENABLE Synchronization Busy bit in the SYNCBUSY register (SYNCBUSY.ENABLE) will be set. SYNCBUSY.ENABLE will be cleared when the operation is complete. This bit is not enable protected. Value Description 0 The peripheral is disabled. 1 The peripheral is enabled. Bit 0 – SWRST Software Reset Writing a '0' to this bit has no effect. Writing a '1' to this bit resets all registers in the TC, except DBGCTRL, to their initial state, and the TC will be disabled. Writing a '1' to CTRLA.SWRST will always take precedence; all other writes in the same write-operation will be discarded. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 944 38.7.3.2 Control B Clear Name:  CTRLBCLR Offset:  0x04 Reset:  0x00 Property:  PAC Write-Protection, Read-Synchronized, Write-Synchronized This register allows the user to clear bits in the CTRLB register without doing a read-modify-write operation. Changes in this register will also be reflected in the Control B Set register (CTRLBSET). Bit 7 6 5 4 3 2 1 0 CMD[2:0] ONESHOT LUPD DIR Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bits 7:5 – CMD[2:0] Command These bits are used for software control of the TC. The commands are executed on the next prescaled GCLK_TC clock cycle. When a command has been executed, the CMD bit group will be read back as zero. Writing 0x0 to these bits has no effect. Writing a '1' to any of these bits will clear the pending command. Bit 2 – ONESHOT One-Shot on Counter This bit controls one-shot operation of the TC. Writing a '0' to this bit has no effect Writing a '1' to this bit will disable one-shot operation. Value Description 0 The TC will wrap around and continue counting on an overflow/underflow condition. 1 The TC will wrap around and stop on the next underflow/overflow condition. Bit 1 – LUPD Lock Update This bit controls the update operation of the TC buffered registers. When CTRLB.LUPD is set, no any update of the registers with value of its buffered register is performed on hardware UPDATE condition. Locking the update ensures that all buffer registers are valid before an hardware update is performed. After all the buffer registers are loaded correctly, the buffered registers can be unlocked. This bit has no effect when input capture operation is enabled. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the LUPD bit. Value Description 0 The CCBUFx and PERBUF buffer registers value are copied into CCx and PER registers on hardware update condition. 1 The CCBUFx and PERBUF buffer registers value are not copied into CCx and PER registers on hardware update condition. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 945 Bit 0 – DIR Counter Direction This bit is used to change the direction of the counter. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the bit and make the counter count up. Value Description 0 The timer/counter is counting up (incrementing). 1 The timer/counter is counting down (decrementing). SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 946 38.7.3.3 Control B Set Name:  CTRLBSET Offset:  0x05 Reset:  0x00 Property:  PAC Write-Protection, Read-synchronized, Write-Synchronized This register allows the user to set bits in the CTRLB register without doing a read-modify-write operation. Changes in this register will also be reflected in the Control B Clear register (CTRLBCLR). Bit 7 6 5 4 3 2 1 0 CMD[2:0] ONESHOT LUPD DIR Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bits 7:5 – CMD[2:0] Command These bits are used for software control of the TC. The commands are executed on the next prescaled GCLK_TC clock cycle. When a command has been executed, the CMD bit group will be read back as zero. Writing 0x0 to these bits has no effect. Writing a value different from 0x0 to these bits will issue a command for execution. Value Name Description 0x0 NONE No action 0x1 RETRIGGER Force a start, restart or retrigger 0x2 STOP Force a stop 0x3 UPDATE Force update of double buffered registers 0x4 READSYNC Force a read synchronization of COUNT Bit 2 – ONESHOT One-Shot on Counter This bit controls one-shot operation of the TC. Writing a '0' to this bit has no effect. Writing a '1' to this bit will enable one-shot operation. Value Description 0 The TC will wrap around and continue counting on an overflow/underflow condition. 1 The TC will wrap around and stop on the next underflow/overflow condition. Bit 1 – LUPD Lock Update This bit controls the update operation of the TC buffered registers. When CTRLB.LUPD is set, no any update of the registers with value of its buffered register is performed on hardware UPDATE condition. Locking the update ensures that all buffer registers are valid before an hardware update is performed. After all the buffer registers are loaded correctly, the buffered registers can be unlocked. Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the LUPD bit. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 947 This bit has no effect when input capture operation is enabled. Value Description 0 The CCBUFx and PERBUF buffer registers value are copied into CCx and PER registers on hardware update condition. 1 The CCBUFx and PERBUF buffer registers value are not copied into CCx and PER registers on hardware update condition. Bit 0 – DIR Counter Direction This bit is used to change the direction of the counter. Writing a '0' to this bit has no effect Writing a '1' to this bit will clear the bit and make the counter count up. Value Description 0 The timer/counter is counting up (incrementing). 1 The timer/counter is counting down (decrementing). SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 948 38.7.3.4 Event Control Name:  EVCTRL Offset:  0x06 Reset:  0x0000 Property:  PAC Write-Protection, Enable-Protected Bit 15 14 13 12 11 10 9 8 MCEOx MCEOx OVFEO Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 TCEI TCINV EVACT[2:0] Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bits 13,12 – MCEOx Match or Capture Channel x Event Output Enable [x = 1..0] These bits enable the generation of an event for every match or capture on channel x. Value Description 0 Match/Capture event on channel x is disabled and will not be generated. 1 Match/Capture event on channel x is enabled and will be generated for every compare/ capture. Bit 8 – OVFEO Overflow/Underflow Event Output Enable This bit enables the Overflow/Underflow event. When enabled, an event will be generated when the counter overflows/underflows. Value Description 0 Overflow/Underflow event is disabled and will not be generated. 1 Overflow/Underflow event is enabled and will be generated for every counter overflow/ underflow. Bit 5 – TCEI TC Event Enable This bit is used to enable asynchronous input events to the TC. Value Description 0 Incoming events are disabled. 1 Incoming events are enabled. Bit 4 – TCINV TC Inverted Event Input Polarity This bit inverts the asynchronous input event source. Value Description 0 Input event source is not inverted. 1 Input event source is inverted. Bits 2:0 – EVACT[2:0] Event Action These bits define the event action the TC will perform on an event. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 949 Value Name Description 0x0 OFF Event action disabled 0x1 RETRIGGER Start, restart or retrigger TC on event 0x2 COUNT Count on event 0x3 START Start TC on event 0x4 STAMP Time stamp capture 0x5 PPW Period captured in CC0, pulse width in CC1 0x6 PWP Period captured in CC1, pulse width in CC0 0x7 PW Pulse width capture SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 950 38.7.3.5 Interrupt Enable Clear Name:  INTENCLR Offset:  0x08 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 7 6 5 4 3 2 1 0 MCx ERR OVF Access R/W R/W R/W Reset 0 0 0 Bit 4 – MCx Match or Capture Channel x Interrupt Enable Writing a '0' to these bits has no effect. Writing a '1' to MCx will clear the corresponding Match or Capture Channel x Interrupt Enable bit, which disables the Match or Capture Channel x interrupt. Value Description 0 The Match or Capture Channel x interrupt is disabled. 1 The Match or Capture Channel x interrupt is enabled. Bit 1 – ERR Error Interrupt Disable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Error Interrupt Enable bit, which disables the Error interrupt. Value Description 0 The Error interrupt is disabled. 1 The Error interrupt is enabled. Bit 0 – OVF Overflow Interrupt Disable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Overflow Interrupt Enable bit, which disables the Overflow interrupt request. Value Description 0 The Overflow interrupt is disabled. 1 The Overflow interrupt is enabled. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 951 38.7.3.6 Interrupt Enable Set Name:  INTENSET Offset:  0x09 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear register (INTENCLR). Bit 7 6 5 4 3 2 1 0 MCx ERR OVF Access R/W R/W R/W Reset 0 0 0 Bit 4 – MCx Match or Capture Channel x Interrupt Enable Writing a '0' to these bits has no effect. Writing a '1' to MCx will set the corresponding Match or Capture Channel x Interrupt Enable bit, which enables the Match or Capture Channel x interrupt. Value Description 0 The Match or Capture Channel x interrupt is disabled. 1 The Match or Capture Channel x interrupt is enabled. Bit 1 – ERR Error Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Error Interrupt Enable bit, which enables the Error interrupt. Value Description 0 The Error interrupt is disabled. 1 The Error interrupt is enabled. Bit 0 – OVF Overflow Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Overflow Interrupt Enable bit, which enables the Overflow interrupt request. Value Description 0 The Overflow interrupt is disabled. 1 The Overflow interrupt is enabled. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 952 38.7.3.7 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x0A Reset:  0x00 Property:  - Bit 7 6 5 4 3 2 1 0 MCx ERR OVF Access R/W R/W R/W Reset 0 0 0 Bit 4 – MCx Match or Capture Channel x This flag is set on a comparison match, or when the corresponding CCx register contains a valid capture value. This flag is set on the next CLK_TC_CNT cycle, and will generate an interrupt request if the corresponding Match or Capture Channel x Interrupt Enable bit in the Interrupt Enable Set register (INTENSET.MCx) is '1'. Writing a '0' to one of these bits has no effect. Writing a '1' to one of these bits will clear the corresponding Match or Capture Channel x interrupt flag In capture operation, this flag is automatically cleared when CCx register is read. Bit 1 – ERR Error Interrupt Flag This flag is set when a new capture occurs on a channel while the corresponding Match or Capture Channel x interrupt flag is set, in which case there is nowhere to store the new capture. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Error interrupt flag. Bit 0 – OVF Overflow Interrupt Flag This flag is set on the next CLK_TC_CNT cycle after an overflow condition occurs, and will generate an interrupt request if INTENCLR.OVF or INTENSET.OVF is '1'. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Overflow interrupt flag. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 953 38.7.3.8 Status Name:  STATUS Offset:  0x0B Reset:  0x01 Property:  Read-Synchronized Bit 7 6 5 4 3 2 1 0 CCBUFVx PERBUFV SLAVE STOP Access R/W R/W R R Reset 0 0 0 1 Bit 4 – CCBUFVx Channel x Compare or Capture Buffer Valid For a compare channel x, the bit x is set when a new value is written to the corresponding CCBUFx register. The bit x is cleared by writing a '1' to it when CTRLB.LUPD is set, or it is cleared automatically by hardware on UPDATE condition. For a capture channel x, the bit x is set when a valid capture value is stored in the CCBUFx register. The bit x is cleared automatically when the CCx register is read. Bit 3 – PERBUFV Period Buffer Valid This bit is set when a new value is written to the PERBUF register. The bit is cleared by writing '1' to the corresponding location when CTRLB.LUPD is set, or automatically cleared by hardware on UPDATE condition. This bit is available only in 8-bit mode and will always read zero in 16- and 32-bit modes. Bit 1 – SLAVE Slave Status Flag This bit is only available in 32-bit mode on the slave TC (i.e., TC1 and/or TC3). The bit is set when the associated master TC (TC0 and TC2, respectively) is set to run in 32-bit mode. Bit 0 – STOP Stop Status Flag This bit is set when the TC is disabled, on a Stop command, or on an overflow/underflow condition when the One-Shot bit in the Control B Set register (CTRLBSET.ONESHOT) is '1'. Value Description 0 Counter is running. 1 Counter is stopped. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 954 38.7.3.9 Waveform Generation Control Name:  WAVE Offset:  0x0C Reset:  0x00 Property:  PAC Write-Protection, Enable-Protected Bit 7 6 5 4 3 2 1 0 WAVEGEN[1:0] Access R/W R/W Reset 0 0 Bits 1:0 – WAVEGEN[1:0] Waveform Generation Mode These bits select the waveform generation operation. They affect the top value, as shown in 38.6.2.6.1 Waveform Output Operations. They also control whether frequency or PWM waveform generation should be used. The waveform generation operations are explained in 38.6.2.6.1 Waveform Output Operations. These bits are not synchronized. Value Name Operation Top Value Output Waveform on Match Output Waveform on Wraparound 0x0 NFRQ Normal frequency PER1 / Max Toggle No action 0x1 MFRQ Match frequency CC0 Toggle No action 0x2 NPWM Normal PWM PER1 / Max Set Clear 0x3 MPWM Match PWM CC0 Set Clear 1) This depends on the TC mode: In 8-bit mode, the top value is the Period Value register (PER). In 16- and 32-bit mode it is the respective MAX value. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 955 38.7.3.10 Driver Control Name:  DRVCTRL Offset:  0x0D Reset:  0x00 Property:  PAC Write-Protection, Enable-Protected Bit 7 6 5 4 3 2 1 0 INVENx Access R/W Reset 0 Bit 0 – INVENx Output Waveform x Invert Enable Bit x of INVEN[1:0] selects inversion of the output or capture trigger input of channel x. Value Description 0 Disable inversion of the WO[x] output and IO input pin. 1 Enable inversion of the WO[x] output and IO input pin. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 956 38.7.3.11 Debug Control Name:  DBGCTRL Offset:  0x0F Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DBGRUN Access R/W Reset 0 Bit 0 – DBGRUN Run in Debug Mode This bit is not affected by a software Reset, and should not be changed by software while the TC is enabled. Value Description 0 The TC is halted when the device is halted in debug mode. 1 The TC continues normal operation when the device is halted in debug mode. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 957 38.7.3.12 Synchronization Busy Name:  SYNCBUSY Offset:  0x10 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 CCx PER COUNT STATUS CTRLB ENABLE SWRST Access R R R R R R R Reset 0 0 0 0 0 0 0 Bit 6 – CCx Compare/Capture Channel x Synchronization Busy For details on CC channels number, refer to each TC feature list. This bit is set when the synchronization of CCx between clock domains is started. This bit is also set when the CCBUFx is written, and cleared on update condition. The bit is automatically cleared when the STATUS.CCBUFx bit is cleared. Bit 5 – PER PER Synchronization Busy This bit is cleared when the synchronization of PER between the clock domains is complete. This bit is set when the synchronization of PER between clock domains is started. This bit is also set when the PER is written, and cleared on update condition. The bit is automatically cleared when the STATUS.PERBUF bit is cleared. Bit 4 – COUNT COUNT Synchronization Busy This bit is cleared when the synchronization of COUNT between the clock domains is complete. This bit is set when the synchronization of COUNT between clock domains is started. Bit 3 – STATUS STATUS Synchronization Busy This bit is cleared when the synchronization of STATUS between the clock domains is complete. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 958 This bit is set when a '1' is written to the Capture Channel Buffer Valid status flags (STATUS.CCBUFVx) and the synchronization of STATUS between clock domains is started. Bit 2 – CTRLB CTRLB Synchronization Busy This bit is cleared when the synchronization of CTRLB between the clock domains is complete. This bit is set when the synchronization of CTRLB between clock domains is started. Bit 1 – ENABLE ENABLE Synchronization Busy This bit is cleared when the synchronization of ENABLE bit between the clock domains is complete. This bit is set when the synchronization of ENABLE bit between clock domains is started. Bit 0 – SWRST SWRST Synchronization Busy This bit is cleared when the synchronization of SWRST bit between the clock domains is complete. This bit is set when the synchronization of SWRST bit between clock domains is started. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 959 38.7.3.13 Counter Value, 32-bit Mode Name:  COUNT Offset:  0x14 Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized, Read-Synchronized Note:  Prior to any read access, this register must be synchronized by user by writing the according TC Command value to the Control B Set register (CTRLBSET.CMD=READSYNC). Bit 31 30 29 28 27 26 25 24 COUNT[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 COUNT[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 COUNT[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 COUNT[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – COUNT[31:0]  Counter Value These bits contain the current counter value. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 960 38.7.3.14 Period Value, 32-bit Mode Name:  PER Offset:  0x1A Reset:  0xFFFFFFFF Property:  Write-Synchronized Bit 31 30 29 28 27 26 25 24 PER[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 PER[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 PER[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 PER[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 1 Bits 31:0 – PER[31:0] Period Value These bits hold the value of the Period Buffer register PERBUF. The value is copied to PER register on UPDATE condition. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 961 38.7.3.15 Channel x Compare/Capture Value, 32-bit Mode Name:  CCx Offset:  0x1C + x*0x04 [x=0..1] Reset:  0x00000000 Property:  Write-Synchronized Bit 31 30 29 28 27 26 25 24 CC[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 CC[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 CC[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 CC[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – CC[31:0] Channel x Compare/Capture Value These bits contain the compare/capture value in 32-bit TC mode. In Match frequency (MFRQ) or Match PWM (MPWM) waveform operation (WAVE.WAVEGEN), the CC0 register is used as a period register. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 962 38.7.3.16 Period Buffer Value, 32-bit Mode Name:  PERBUF Offset:  0x2C Reset:  0xFFFFFFFF Property:  Write-Synchronized Bit 31 30 29 28 27 26 25 24 PERBUF[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 PERBUF[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 PERBUF[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 PERBUF[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 1 Bits 31:0 – PERBUF[31:0] Period Buffer Value These bits hold the value of the period buffer register. The value is copied to PER register on UPDATE condition. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 963 38.7.3.17 Channel x Compare Buffer Value, 32-bit Mode Name:  CCBUFx Offset:  0x30 + x*0x04 [x=0..1] Reset:  0x00000000 Property:  Write-Synchronized Bit 31 30 29 28 27 26 25 24 CCBUF[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 CCBUF[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 CCBUF[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 CCBUF[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – CCBUF[31:0] Channel x Compare Buffer Value These bits hold the value of the Channel x Compare Buffer Value. When the buffer valid flag is '1' and double buffering is enabled (CTRLBCLR.LUPD=1), the data from buffer registers will be copied into the corresponding CCx register under UPDATE condition (CTRLBSET.CMD=0x3), including the software update command. SAM L10/L11 Family TC – Timer/Counter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 964 39. TRNG – True Random Number Generator 39.1 Overview The True Random Number Generator (TRNG) generates unpredictable random numbers that are not generated by an algorithm. It passes the American NIST Special Publication 800-22 and Diehard Random Tests Suites. The TRNG may be used as an entropy source for seeding an NIST approved DRNG (Deterministic RNG) as required by FIPS PUB 140-2 and 140-3. 39.2 Features • Passed NIST Special Publication 800-22 Tests Suite • Passed Diehard Random Tests Suite • May be used as Entropy Source for seeding an NIST approved DRNG (Deterministic RNG) as required by FIPS PUB 140-2 and 140-3 • Provides a 32-bit random number every 84 clock cycles 39.3 Block Diagram Figure 39-1. TRNG Block Diagram. MCLK User Interface Entropy Source Control Logic TRNG Interrupt Controller APB Event Controller 39.4 Signal Description Not applicable. 39.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 39.5.1 I/O Lines Not applicable. 39.5.2 Power Management The functioning of TRNG depends on the sleep mode of device. SAM L10/L11 Family TRNG – True Random Number Generator © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 965 The TRNG interrupts can be used to wake up the device from sleep modes. Events connected to the event system can trigger other operations in the system without exiting sleep modes. Related Links 22. PM – Power Manager 39.6.5 Sleep Mode Operation 39.5.3 Clocks The TRNG bus clock (CLK_TRNG_APB) can be enabled and disabled in the Main Clock module, and the default state of CLK_TRNG_APB can be found in Peripheral Clock Masking. Related Links 19.6.2.6 Peripheral Clock Masking 39.5.4 DMA Not applicable. 39.5.5 Interrupts The interrupt request line is connected to the interrupt controller. Using the TRNG interrupt(s) requires the interrupt controller to be configured first. Refer to NVIC - Nested Interrupt Nested Vector Interrupt Controller for details. 39.5.6 Events TRNG can generate Events that are used by the Event System (EVSYS) and EVSYS users. TRNG cannot use any Events from other peripherals, as it is not an Event User. Related Links 33. EVSYS – Event System 39.5.7 Debug Operation When the CPU is halted in debug mode the TRNG continues normal operation. If the TRNG 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. 39.5.8 Register Access Protection All registers with write-access are optionally write-protected by the Peripheral Access Controller (PAC), except the following register: Interrupt Flag Status and Clear (INTFLAG) register Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. 39.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted SAM L10/L11 Family TRNG – True Random Number Generator © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 966 – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 39.5.10 Analog Connections Not applicable. 39.6 Functional Description 39.6.1 Principle of Operation When the TRNG is enabled, the peripheral starts providing new 32-bit random numbers every 84 CLK_TRNG_APB clock cycles. The TRNG can be configured to generate an interrupt or event when a new random number is available. Figure 39-2. TRNG Data Generation Sequence 84 clock cycles 84 clock cycles 84 clock cycles Read TRNG_ISR Read DATA Read TRNG_ISR Read DATA Clock Interrupt ENABLE 39.6.2 Basic Operation 39.6.2.1 Initialization To operate the TRNG, do the following: • Configure the clock source for CLK_TRNG_APB in the Main Clock Controller (MCLK) and enable the clock by writing a ‘1’ to the TRNG bit in the APB Mask register of the MCLK. • Optional: Enable the output event by writing a ‘1’ to the EVCTRL.DATARDYEO bit. • Optional: Enable the TRNG to Run in Standby sleep mode by writing a ‘1’ to CTRLA.RUNSTDBY. • Enable the TRNG operation by writing a ‘1’ to CTRLA.ENABLE. The following register is enable-protected, meaning that it can only be written when the TRNG is disabled (CTRLA.ENABLE is zero): • Event Control register (EVCTRL) Enable-protection is denoted by the Enable-Protected property in the register description. 39.6.2.2 Enabling, Disabling and Resetting The TRNG is enabled by writing '1' to the Enable bit in the Control A register (CTRLA.ENABLE). The TRNG is disabled by writing a zero to CTRLA.ENABLE. 39.6.3 Interrupts The TRNG has the following interrupt source: • Data Ready (DATARDY): Indicates that a new random number is available in the DATA register and ready to be read. SAM L10/L11 Family TRNG – True Random Number Generator © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 967 This interrupt is a synchronous wake-up source. See Sleep Mode Controller for details. The interrupt source has an interrupt flag associated with it. The interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG.DATARDY) is set to ‘1’ when the interrupt condition occurs. The interrupt can be enabled by writing a '1' to the corresponding bit in the Interrupt Enable Set register (INTENSET.DATARDY), and disabled by writing a '1' to the corresponding bit in the Interrupt Enable Clear (INTENCLR) register. An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until the interrupt flag is cleared, or the interrupt is disabled. See 39.8.5 INTFLAG for details on how to clear interrupt flags. Note that interrupts must be globally enabled for interrupt requests to be generated. Related Links 22.6.3.3 Sleep Mode Controller 39.6.4 Events The TRNG can generate the following output event: • Data Ready (DATARDY): Generated when a new random number is available in the DATA register. Writing '1' to the Data Ready Event Output bit in the Event Control Register (EVCTRL.DATARDYEO) enables the DTARDY event. Writing a '0' to this bit disables the corresponding output event. Refer to EVSYS – Event System for details on configuring the Event System. Related Links 33. EVSYS – Event System 39.6.5 Sleep Mode Operation The Run in Standby bit in Control A register (CTRLA.RUNSTDBY) controls the behavior of the TRNG during standby sleep mode: When this bit is '0', the TRNG is disabled during sleep, but maintains its current configuration. When this bit is '1', the TRNG continues to operate during sleep and any enabled TRNG interrupt source can wake up the CPU. 39.6.6 Synchronization Not applicable. SAM L10/L11 Family TRNG – True Random Number Generator © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 968 39.7 Register Summary Offset Name Bit Pos. 0x00 CTRLA 7:0 RUNSTDBY ENABLE 0x01 ... 0x03 Reserved 0x04 EVCTRL 7:0 DATARDYEO 0x05 ... 0x07 Reserved 0x08 INTENCLR 7:0 DATARDY 0x09 INTENSET 7:0 DATARDY 0x0A INTFLAG 7:0 DATARDY 0x0B ... 0x1F Reserved 0x20 DATA 7:0 DATA[7:0] 15:8 DATA[15:8] 23:16 DATA[23:16] 31:24 DATA[31:24] 39.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16-, and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers require synchronization when read and/or written. Synchronization is denoted by the "Read-Synchronized" and/or "Write-Synchronized" property in each individual register description. Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. Some registers are enable-protected, meaning they can only be written when the module is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. Refer to PAC - Peripheral Access Controller and 39.6.6 Synchronizationfor details. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. Related Links SAM L10/L11 Family TRNG – True Random Number Generator © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 969 15. PAC - Peripheral Access Controller SAM L10/L11 Family TRNG – True Random Number Generator © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 970 39.8.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 RUNSTDBY ENABLE Access R/W R/W Reset 0 0 Bit 6 – RUNSTDBY Run in Standby This bit controls how the ADC behaves during standby sleep mode: Value Description 0 The TRNG is halted during standby sleep mode. 1 The TRNG is not stopped in standby sleep mode. Bit 1 – ENABLE Enable Value Description 0 The TRNG is disabled. 1 The TRNG is enabled. SAM L10/L11 Family TRNG – True Random Number Generator © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 971 39.8.2 Event Control Name:  EVCTRL Offset:  0x04 Reset:  0x00 Property:  PAC Write-Protection, Enable-Protected Bit 7 6 5 4 3 2 1 0 DATARDYEO Access R/W Reset 0 Bit 0 – DATARDYEO Data Ready Event Output This bit indicates whether the Data Ready event output is enabled and whether an output event will be generated when a new random value is ready. Value Description 0 Data Ready event output is disabled and an event will not be generated. 1 Data Ready event output is enabled and an event will be generated. SAM L10/L11 Family TRNG – True Random Number Generator © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 972 39.8.3 Interrupt Enable Clear Name:  INTENCLR Offset:  0x08 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set (INTENSET) register. Bit 7 6 5 4 3 2 1 0 DATARDY Access R/W Reset 0 Bit 0 – DATARDY Data Ready Interrupt Enable Writing a '1' to this bit will clear the Data Ready Interrupt Enable bit, which disables the corresponding interrupt request. Value Description 0 The DATARDY interrupt is disabled. 1 The DATARDY interrupt is enabled. SAM L10/L11 Family TRNG – True Random Number Generator © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 973 39.8.4 Interrupt Enable Set Name:  INTENSET Offset:  0x09 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear (INTENCLR) register. Bit 7 6 5 4 3 2 1 0 DATARDY Access R/W Reset 0 Bit 0 – DATARDY Data Ready Interrupt Enable Writing a '1' to this bit will set the Data Ready Interrupt Enable bit, which enables the corresponding interrupt request. Value Description 0 The DATARDY interrupt is disabled. 1 The DATARDY interrupt is enabled. SAM L10/L11 Family TRNG – True Random Number Generator © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 974 39.8.5 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x0A Reset:  0x00 Property:  - Bit 7 6 5 4 3 2 1 0 DATARDY Access R/W Reset 0 Bit 0 – DATARDY Data Ready This flag is set when a new random value is generated, and an interrupt will be generated if INTENCLR/ SET.DATARDY=1. This flag is cleared by writing a '1' to the flag or by reading the DATA register. Writing a '0' to this bit has no effect. SAM L10/L11 Family TRNG – True Random Number Generator © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 975 39.8.6 Output Data Name:  DATA Offset:  0x20 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 DATA[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 DATA[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 DATA[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DATA[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – DATA[31:0] Output Data These bits hold the 32-bit randomly generated output data. SAM L10/L11 Family TRNG – True Random Number Generator © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 976 40. CCL – Configurable Custom Logic 40.1 Overview The Configurable Custom Logic (CCL) is a programmable logic peripheral which can be connected to the device pins, to events, or to other internal peripherals. This allows the user to eliminate logic gates for simple glue logic functions on the PCB. Each LookUp Table (LUT) consists of three inputs, a truth table, an optional synchronizer/filter, and an optional edge detector. Each LUT can generate an output as a user programmable logic expression with three inputs. Inputs can be individually masked. The output can be combinatorially generated from the inputs, and can be filtered to remove spikes. Optional sequential logic can be used. The inputs of the sequential module are individually controlled by two independent, adjacent LUT (LUT0/LUT1, LUT2/LUT3 etc.) outputs, enabling complex waveform generation. 40.2 Features • Glue logic for general purpose PCB design • Up to 2 programmable LookUp Tables (LUTs) • Combinatorial logic functions: AND, NAND, OR, NOR, XOR, XNOR, NOT • Sequential logic functions: Gated D Flip-Flop, JK Flip-Flop, gated D Latch, RS Latch • Flexible LUT inputs selection: – I/Os – Events – Internal peripherals – Subsequent LUT output • Output can be connected to the I/O pins or the Event System • Optional synchronizer, filter, or edge detector available on each LUT output SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 977 40.3 Block Diagram Figure 40-1. Configurable Custom Logic Filter / Synch Edge Detector Truth Table 8 CLR CLR Sequential CLR Internal Events I/O Peripherals LUTCTRL0 (ENABLE) LUTCTRL0 (EDGESEL) LUTCTRL0 (FILTSEL) LUTCTRL0 (INSEL) SEQCTRL (SEQSEL0) CTRL (ENABLE) D Q CLK_CCL_APB GCLK_CCL LUT0 Filter / Synch Edge Detector Truth Table 8 CLR CLR Internal Events I/O Peripherals LUTCTRL1 (ENABLE) LUTCTRL1 (EDGESEL) LUTCTRL1 (FILTSEL) LUTCTRL1 (INSEL) D Q CLK_CCL_APB GCLK_CCL LUT1 CTRL (ENABLE) UNIT 0 ..... OUT1 Event System Peripherals I/O OUT0 Event System Peripherals I/O UNIT x OUT2x-1 Event System Peripherals I/O 40.4 Signal Description Pin Name Type Description OUT[n:0] Digital output Output from lookup table IN[3n+2:0] Digital input Input to lookup table 1. n is the number of CCL groups. Refer to I/O Multiplexing and Considerations for details on the pin mapping for this peripheral. One signal can be mapped on several pins. 40.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 40.5.1 I/O Lines The CCL can take inputs and generate output through I/O pins. For this to function properly, the I/O pins must be configured to be used by a Look-up Table (LUT). Related Links 32. PORT - I/O Pin Controller 40.5.2 Power Management This peripheral can continue to operate in any sleep mode where its source clock is running. Events connected to the event system can trigger other operations in the system without exiting sleep modes. Related Links 22. PM – Power Manager SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 978 40.5.3 Clocks The CCL bus clock (CLK_CCL_APB) can be enabled and disabled in the Main Clock module, MCLK (see MCLK - Main Clock), and the default state of CLK_CCL_APB can be found in Peripheral Clock Masking. A generic clock (GCLK_CCL) is optionally required to clock the CCL. This clock must be configured and enabled in the Generic Clock Controller (GCLK) before using input events, filter, edge detection or sequential logic. GCLK_CCL is required when input events, a filter, an edge detector, or a sequential submodule is enabled. Refer to GCLK - Generic Clock Controller for details. This generic clock is asynchronous to the user interface clock (CLK_CCL_APB). Related Links 19. MCLK – Main Clock 19.6.2.6 Peripheral Clock Masking 18. GCLK - Generic Clock Controller 40.5.4 DMA Not applicable. 40.5.5 Interrupts Not applicable. 40.5.6 Events The CCL can use events from other peripherals and generate events that can be used by other peripherals. For this feature to function, the Events have to be configured properly. Refer to the Related Links below for more information about the Event Users and Event Generators. Related Links 33. EVSYS – Event System 40.5.7 Debug Operation When the CPU is halted in Debug mode the CCL continues normal operation. However, the CCL cannot be halted when the CPU is halted in Debug mode. If the CCL is configured in a way that requires it to be periodically serviced by the CPU, improper operation or data loss may result during debugging. 40.5.8 Register Access Protection All registers with write-access can be write-protected optionally by the peripheral access controller (PAC). Refer to PAC - Peripheral Access Controller for details. Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. PAC write-protection does not apply to accesses through an external debugger. Related Links 15. PAC - Peripheral Access Controller 40.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 979 • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 40.5.10 Analog Connections Not applicable. 40.6 Functional Description 40.6.1 Principle of Operation Configurable Custom Logic (CCL) is a programmable logic block that can use the device port pins, internal peripherals, and the internal Event System as both input and output channels. The CCL can serve as glue logic between the device and external devices. The CCL can eliminate the need for external logic component and can also help the designer overcome challenging real-time constrains by combining core independent peripherals in clever ways to handle the most time critical parts of the application independent of the CPU. 40.6.2 Operation 40.6.2.1 Initialization The following bits are enable-protected, meaning that they can only be written when the corresponding even LUT is disabled (LUTCTRLx.ENABLE=0): • Sequential Selection bits in the Sequential Control x (SEQCTRLx.SEQSEL) register The following registers are enable-protected, meaning that they can only be written when the corresponding LUT is disabled (LUTCTRLx.ENABLE=0): • LUT Control x (LUTCTRLx) register, except the ENABLE bit Enable-protected bits in the LUTCTRLx registers can be written at the same time as LUTCTRLx.ENABLE is written to '1', but not at the same time as LUTCTRLx.ENABLE is written to '0'. Enable-protection is denoted by the Enable-Protected property in the register description. 40.6.2.2 Enabling, Disabling, and Resetting The CCL is enabled by writing a '1' to the Enable bit in the Control register (CTRL.ENABLE). The CCL is disabled by writing a '0' to CTRL.ENABLE. Each LUT is enabled by writing a '1' to the Enable bit in the LUT Control x register (LUTCTRLx.ENABLE). Each LUT is disabled by writing a '0' to LUTCTRLx.ENABLE. The CCL is reset by writing a '1' to the Software Reset bit in the Control register (CTRL.SWRST). All registers in the CCL will be reset to their initial state, and the CCL will be disabled. Refer to 40.8.1 CTRL for details. 40.6.2.3 Lookup Table Logic The lookup table in each LUT unit can generate any logic expression OUT as a function of three inputs (IN[2:0]), as shown in Figure 40-2. One or more inputs can be masked. The truth table for the expression is defined by TRUTH bits in LUT Control x register (LUTCTRLx.TRUTH). SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 980 Figure 40-2. Truth Table Output Value Selection TRUTH[0] TRUTH[1] TRUTH[2] TRUTH[3] TRUTH[4] TRUTH[5] TRUTH[6] TRUTH[7] OUT IN[2:0] LUTCTRL (ENABLE) LUT Table 40-1. Truth Table of LUT IN[2] IN[1] IN[0] OUT 0 0 0 TRUTH[0] 0 0 1 TRUTH[1] 0 1 0 TRUTH[2] 0 1 1 TRUTH[3] 1 0 0 TRUTH[4] 1 0 1 TRUTH[5] 1 1 0 TRUTH[6] 1 1 1 TRUTH[7] 40.6.2.4 Truth Table Inputs Selection Input Overview The inputs can be individually: • Masked • Driven by peripherals: – Analog comparator output (AC) – Timer/Counters waveform outputs (TC) – Serial Communication output transmit interface (SERCOM) • Driven by internal events from Event System • Driven by other CCL sub-modules The Input Selection for each input y of LUT x is configured by writing the Input y Source Selection bit in the LUT x Control register (LUTCTRLx.INSELy). Masked Inputs (MASK) When a LUT input is masked (LUTCTRLx.INSELy=MASK), the corresponding TRUTH input (IN) is internally tied to zero, as shown in this figure: SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 981 Figure 40-3. Masked Input Selection Internal Feedback Inputs (FEEDBACK) When selected (LUTCTRLx.INSELy=FEEDBACK), the Sequential (SEQ) output is used as input for the corresponding LUT. The output from an internal sequential sub-module can be used as input source for the LUT, see figure below for an example for LUT0 and LUT1. The sequential selection for each LUT follows the formula: IN 2N ݅ = SEQ ܰ IN 2N+1 ݅ = SEQ ܰ With N representing the sequencer number and i=0,1,2 representing the LUT input index. For details, refer to 40.6.2.7 Sequential Logic. Figure 40-4. Feedback Input Selection Linked LUT (LINK) When selected (LUTCTRLx.INSELy=LINK), the subsequent LUT output is used as the LUT input (e.g., LUT2 is the input for LUT1), as shown in this figure: SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 982 Figure 40-5. Linked LUT Input Selection CTRL (ENABLE) LUT0 SEQ 0 LUT1 CTRL (ENABLE) LUT2 SEQ 1 LUT3 CTRL (ENABLE) LUT(2n – 2) SEQ n LUT(2n-1) Internal Events Inputs Selection (EVENT) Asynchronous events from the Event System can be used as input selection, as shown in Figure 40-6. For each LUT, one event input line is available and can be selected on each LUT input. Before enabling the event selection by writing LUTCTRLx.INSELy=EVENT, the Event System must be configured first. By default CCL includes an edge detector. When the event is received, an internal strobe is generated when a rising edge is detected. The pulse duration is one GCLK_CCL clock cycle. Writing the LUTCTRLx.INSELy=ASYNCEVENT will disable the edge detector. In this case, it is possible to combine an asynchronous event input with any other input source. This is typically useful with event levels inputs (external IO pin events, as example). The following steps ensure proper operation: 1. Enable the GCLK_CCL clock. 2. Configure the Event System to route the event asynchronously. 3. Select the event input type (LUTCTRLx.INSEL). 4. If a strobe must be generated on the event input falling edge, write a '1' to the Inverted Event Input Enable bit in LUT Control register (LUTCTRLx.INVEI) . 5. Enable the event input by writing the Event Input Enable bit in LUT Control register (LUTCTRLx.LUTEI) to '1'. SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 983 Figure 40-6. Event Input Selection I/O Pin Inputs (IO) When the IO pin is selected as LUT input (LUTCTRLx.INSELy=IO), the corresponding LUT input will be connected to the pin, as shown in the figure below. Figure 40-7. I/O Pin Input Selection Analog Comparator Inputs (AC) The AC outputs can be used as input source for the LUT (LUTCTRLx.INSELy=AC). The analog comparator outputs are distributed following the formula: IN[N][i]=AC[N % ComparatorOutput_Number] With N representing the LUT number and i=[0,1,2] representing the LUT input index. Before selecting the comparator output, the AC must be configured first. The output of comparator 0 is available on even LUTs ("LUT(2x)": LUT0, LUT2) and the comparator 1 output is available on odd LUTs ("LUT(2x+1)": LUT1, LUT3), as shown in the figure below. Figure 40-8. AC Input Selection SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 984 Timer/Counter Inputs (TC) The TC waveform output WO[0] can be used as input source for the LUT (LUTCTRLx.INSELy=TC). Only consecutive instances of the TC, i.e. TCx and the subsequent TC(x+1), are available as default and alternative TC selections (e.g., TC0 and TC1 are sources for LUT0, TC1 and TC2 are sources for LUT1, etc). See the figure below for an example for LUT0. More general, the Timer/Counter selection for each LUT follows the formula: Number_Instance_TC ܰ % ܥܶݐ݈ݑ݂ܽ݁ܦ = ݅ ܰ IN Number_Instance_TC % 1 ܰ + ܥܶ݁ݒ݅ݐܽ݊ݎ݁ݐ݈ܣ = ݅ ܰ IN Where N represents the LUT number and i represents the LUT input index (i=0,1,2). Before selecting the waveform outputs, the TC must be configured first. Figure 40-9. TC Input Selection WO[0] WO[0] Timer/Counter for Control Application Inputs (TCC) The TCC waveform outputs can be used as input source for the LUT. Only WO[2:0] outputs can be selected and routed to the respective LUT input (i.e., IN0 is connected to WO0, IN1 to WO1, and IN2 to WO2), as shown in the figure below. Before selecting the waveform outputs, the TCC must be configured first. Figure 40-10. TCC Input Selection Serial Communication Output Transmit Inputs (SERCOM) The serial engine transmitter output from Serial Communication Interface (SERCOM TX, TXd for USART, MOSI for SPI) can be used as input source for the LUT. The figure below shows an example for LUT0 and LUT1. The SERCOM selection for each LUT follows the formula: IN ܰ ݅ = ܵܧܴܥܱܯ % ܰ]SERCOM_Instance_Number With N representing the LUT number and i=0,1,2 representing the LUT input index. Before selecting the SERCOM as input source, the SERCOM must be configured first: the SERCOM TX signal must be output on SERCOMn/pad[0], which serves as input pad to the CCL. SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 985 Figure 40-11. SERCOM Input Selection Related Links 32. PORT - I/O Pin Controller 18. GCLK - Generic Clock Controller 42. AC – Analog Comparators 38. TC – Timer/Counter 34. SERCOM – Serial Communication Interface 40.6.2.5 Filter By default, the LUT output is a combinatorial function of the LUT inputs. This may cause some short glitches when the inputs change value. These glitches can be removed by clocking through filters, if demanded by application needs. The Filter Selection bits in LUT Control register (LUTCTRLx.FILTSEL) define the synchronizer or digital filter options. When a filter is enabled, the OUT output will be delayed by two to five GCLK cycles. One APB clock after the corresponding LUT is disabled, all internal filter logic is cleared. Note:  Events used as LUT input will also be filtered, if the filter is enabled. Figure 40-12. Filter D Q R D Q R D Q R D Q R FILTSEL OUT Input GCLK_CCL CLR G 40.6.2.6 Edge Detector The edge detector can be used to generate a pulse when detecting a rising edge on its input. To detect a falling edge, the TRUTH table should be inverted. The edge detector is enabled by writing '1' to the Edge Selection bit in LUT Control register (LUTCTRLx.EDGESEL). In order to avoid unpredictable behavior, either the filter or synchronizer must be enabled. Edge detection is disabled by writing a '0' to LUTCTRLx.EDGESEL. After disabling a LUT, the corresponding internal Edge Detector logic is cleared one APB clock cycle later. SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 986 Figure 40-13. Edge Detector 40.6.2.7 Sequential Logic Each LUT pair can be connected to the internal sequential logic which can be configured to work as D flip flop, JK flip flop, gated D-latch or RS-latch by writing the Sequential Selection bits on the corresponding Sequential Control x register (SEQCTRLx.SEQSEL). Before using sequential logic, the GCLK_CCL clock and optionally each LUT filter or edge detector must be enabled. Note:  While configuring the sequential logic, the even LUT must be disabled. When configured the even LUT must be enabled. Gated D Flip-Flop (DFF) When the DFF is selected, the D-input is driven by the even LUT output (), and the G-input is driven by the odd LUT output (), as shown in Figure 40-14. Figure 40-14. D Flip Flop When the even LUT is disabled (), the flip-flop is asynchronously cleared. The reset command (R) is kept enabled for one APB clock cycle. In all other cases, the flip-flop output (OUT) is refreshed on rising edge of the GCLK_CCL, as shown in Table 40-2. Table 40-2. DFF Characteristics R G D OUT 1 X X Clear 0 1 1 Set 0 Clear 0 X Hold state (no change) JK Flip-Flop (JK) When this configuration is selected, the J-input is driven by the even LUT output (), and the K-input is driven by the odd LUT output (), as shown in Figure 40-15. SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 987 Figure 40-15. JK Flip Flop When the even LUT is disabled (), the flip-flop is asynchronously cleared. The reset command (R) is kept enabled for one APB clock cycle. In all other cases, the flip-flop output (OUT) is refreshed on rising edge of the GCLK_CCL, as shown in Table 40-3. Table 40-3. JK Characteristics R J K OUT 1 X X Clear 0 0 0 Hold state (no change) 0 0 1 Clear 0 1 0 Set 0 1 1 Toggle Gated D-Latch (DLATCH) When the DLATCH is selected, the D-input is driven by the even LUT output (), and the G-input is driven by the odd LUT output (), as shown in Figure 40-14. Figure 40-16. D-Latch D Q G even LUT OUT odd LUT When the even LUT is disabled (), the latch output will be cleared. The G-input is forced enabled for one more APB clock cycle, and the D-input to zero. In all other cases, the latch output (OUT) is refreshed as shown in Table 40-4. Table 40-4. D-Latch Characteristics G D OUT 0 X Hold state (no change) 1 0 Clear 1 1 Set RS Latch (RS) When this configuration is selected, the S-input is driven by the even LUT output (), and the R-input is driven by the odd LUT output (), as shown in Figure 40-17. SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 988 Figure 40-17. RS-Latch S Q R even LUT OUT odd LUT When the even LUT is disabled ), the latch output will be cleared. The R-input is forced enabled for one more APB clock cycle and S-input to zero. In all other cases, the latch output (OUT) is refreshed as shown in Table 40-5. Table 40-5. RS-Latch Characteristics S R OUT 0 0 Hold state (no change) 0 1 Clear 1 0 Set 1 1 Forbidden state 40.6.3 Events The CCL can generate the following output events: • OUTx: Lookup Table Output Value Writing a '1' to the LUT Control Event Output Enable bit (LUTCTRL.LUTEO) enables the corresponding output event. Writing a '0' to this bit disables the corresponding output event. The CCL can take the following actions on an input event: • INSELx: The event is used as input for the TRUTH table. For further details refer to 40.5.6 Events. Writing a '1' to the LUT Control Event Input Enable bit (LUTCTRL.LUTEI) enables the corresponding action on input event. Writing a '0' to this bit disables the corresponding action on input event. Related Links 33. EVSYS – Event System 40.6.4 Sleep Mode Operation When using the GCLK_CCL internal clocking, writing the Run In Standby bit in the Control register (CTRL.RUNSTDBY) to '1' will allow GCLK_CCL to be enabled in Standby Sleep mode. If CTRL.RUNSTDBY=0, the GCLK_CCL will be disabled in Standby Sleep mode. If the Filter, Edge Detector or Sequential logic are enabled, the LUT output will be forced to zero in STANDBY mode. In all other cases, the TRUTH table decoder will continue operation and the LUT output will be refreshed accordingly. Related Links 22. PM – Power Manager SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 989 40.7 Register Summary Offset Name Bit Pos. 0x00 CTRL 7:0 RUNSTDBY ENABLE SWRST 0x01 ... 0x03 Reserved 0x04 SEQCTRL0 7:0 SEQSEL[3:0] 0x05 ... 0x07 Reserved 0x08 LUTCTRL0 7:0 EDGESEL FILTSEL[1:0] ENABLE 15:8 INSELx[3:0] INSELx[3:0] 23:16 LUTEO LUTEI INVEI INSELx[3:0] 31:24 TRUTH[7:0] 0x0C LUTCTRL1 7:0 EDGESEL FILTSEL[1:0] ENABLE 15:8 INSELx[3:0] INSELx[3:0] 23:16 LUTEO LUTEI INVEI INSELx[3:0] 31:24 TRUTH[7:0] 40.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to 40.5.8 Register Access Protection. Some registers are enable-protected, meaning they can only be written when the peripheral is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 990 40.8.1 Control Name:  CTRL Offset:  0x00 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 RUNSTDBY ENABLE SWRST Access R/W R/W W Reset 0 0 0 Bit 6 – RUNSTDBY Run in Standby This bit indicates if the GCLK_CCL clock must be kept running in standby mode. The setting is ignored for configurations where the generic clock is not required. For details refer to 40.6.4 Sleep Mode Operation. Important:  This bit must be written before enabling the CCL. Value Description 0 Generic clock is not required in standby sleep mode. 1 Generic clock is required in standby sleep mode. Bit 1 – ENABLE Enable Value Description 0 The peripheral is disabled. 1 The peripheral is enabled. Bit 0 – SWRST Software Reset Writing a '0' to this bit has no effect. Writing a '1' to this bit resets all registers in the CCL to their initial state. Value Description 0 There is no reset operation ongoing. 1 The reset operation is ongoing. SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 991 40.8.2 Sequential Control x Name:  SEQCTRL Offset:  0x04 Reset:  0x00 Property:  PAC Write-Protection, Enable-Protected Bit 7 6 5 4 3 2 1 0 SEQSEL[3:0] Access R/W R/W R/W R/W Reset 0 0 0 0 Bits 3:0 – SEQSEL[3:0] Sequential Selection These bits select the sequential configuration: Sequential Selection Value Name Description 0x0 DISABLE Sequential logic is disabled 0x1 DFF D flip flop 0x2 JK JK flip flop 0x3 LATCH D latch 0x4 RS RS latch 0x5 - 0xF Reserved SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 992 40.8.3 LUT Control x Name:  LUTCTRL Offset:  0x08 + n*0x04 [n=0..1] Reset:  0x00000000 Property:  PAC Write-Protection, Enable-protected Bit 31 30 29 28 27 26 25 24 TRUTH[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 LUTEO LUTEI INVEI INSELx[3:0] Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 INSELx[3:0] INSELx[3:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 EDGESEL FILTSEL[1:0] ENABLE Access R/W R/W R/W R/W Reset 0 0 0 0 Bits 31:24 – TRUTH[7:0] Truth Table These bits define the value of truth logic as a function of inputs IN[2:0]. Bit 22 – LUTEO LUT Event Output Enable Value Description 0 LUT event output is disabled. 1 LUT event output is enabled. Bit 21 – LUTEI LUT Event Input Enable Value Description 0 LUT incoming event is disabled. 1 LUT incoming event is enabled. Bit 20 – INVEI Inverted Event Input Enable Value Description 0 Incoming event is not inverted. 1 Incoming event is inverted. Bit 7 – EDGESEL Edge Selection SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 993 Value Description 0 Edge detector is disabled. 1 Edge detector is enabled. Bits 5:4 – FILTSEL[1:0] Filter Selection These bits select the LUT output filter options: Filter Selection Value Name Description 0x0 DISABLE Filter disabled 0x1 SYNCH Synchronizer enabled 0x2 FILTER Filter enabled 0x3 - Reserved Bit 1 – ENABLE LUT Enable Value Description 0 The LUT is disabled. 1 The LUT is enabled. Bits 19:16,15:12,11:8 – INSELx LUT Input x Source Selection These bits select the LUT input x source: Value Name Description 0x0 MASK Masked input 0x1 FEEDBACK Feedback input source 0x2 LINK Linked LUT input source 0x3 EVENT Event input source 0x4 IO I/O pin input source 0x5 AC AC input source 0x6 TC TC input source 0x7 ALTTC Alternative TC input source 0x8 TCC TCC input source 0x9 SERCOM SERCOM input source 0xB ASYNCEVENT Asynchronous event input source SAM L10/L11 Family CCL – Configurable Custom Logic © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 994 41. ADC – Analog-to-Digital Converter 41.1 Overview The Analog-to-Digital Converter (ADC) converts analog signals to digital values. The ADC has up to 12- bit resolution, and is capable of a sampling rate of up to 1MSPS. The input selection is flexible, and both differential and single-ended measurements can be performed. In addition, several internal signal inputs are available. The ADC can provide both signed and unsigned results. ADC measurements can be started by either application software or an incoming event from another peripheral in the device. ADC measurements can be started with predictable timing, and without software intervention. Both internal and external reference voltages can be used. An integrated temperature sensor is available for use with the ADC. The INTREF voltage reference, as well as the scaled I/O and core voltages, 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. The ADC can be configured for 8-, 10- or 12-bit results. ADC conversion results are provided left- or rightadjusted, which eases calculation when the result is represented as a signed value. It is possible to use DMA to move ADC results directly to memory or peripherals when conversions are done. 41.2 Features • 8-, 10- or 12-bit resolution • Up to 1,000,000 samples per second (1MSPS) • Differential and single-ended inputs – Up to 10 analog inputs 10 positive and 8 negative, including internal and external • Internal inputs: – Internal temperature sensor – INTREF voltage reference – Scaled core supply – Scaled I/O supply – DAC • Single, continuous and sequencing options • Windowing monitor with selectable channel • Conversion range: Vref = [1.0V to VDDANA ] • Built-in internal reference and external reference options • Event-triggered conversion for accurate timing (one event input) • Optional DMA transfer of conversion settings or result • Hardware gain and offset compensation • Averaging and oversampling with decimation to support up to 16-bit result • Selectable sampling time SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 995 • Flexible Power / Throughput rate management 41.3 Block Diagram Figure 41-1. ADC Block Diagram ADC AIN0 AINn ... INT.SIG AIN0 AINn ... REFCTRL INTREF INTVCC1 VREFB OFFSETCORR GAINCORRSWTRIG EVCTRL AVGCTRL SEQCTRL SAMPCTRL WINUT POST PROCESSING PRESCALER CTRLB WINLT VREFA CTRLA RESULT INPUTCTRL SEQSTATUS INTVCC0 INTVCC2 41.4 Signal Description Signal Description Type VREFA/B Analog input External reference voltage AIN[9..0] Analog input Analog input channels Note:  One signal can be mapped on several pins. Related Links 1. Configuration Summary 41.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 996 41.5.1 I/O Lines Using the ADC's I/O lines requires the I/O pins to be configured using the port configuration (PORT). Related Links 32. PORT - I/O Pin Controller 41.5.2 Power Management The ADC will continue to operate in any Sleep mode where the selected source clock is running. The ADC’s interrupts, except the OVERRUN interrupt, can be used to wake up the device from sleep modes, except the OVERRUN interrupt. Events connected to the event system can trigger other operations in the system without exiting sleep modes. Related Links 22. PM – Power Manager 41.5.3 Clocks The ADC bus clock (CLK_APB_ADCx) can be enabled in the Main Clock, which also defines the default state. The ADC requires a generic clock (GCLK_ADC). This clock must be configured and enabled in the Generic Clock Controller (GCLK) before using the ADC. A generic clock is asynchronous to the bus clock. Due to this asynchronicity, writes to certain registers will require synchronization between the clock domains. Refer to Synchronization for further details. Related Links 41.6.8 Synchronization 19.6.2.6 Peripheral Clock Masking 18. GCLK - Generic Clock Controller 41.5.4 DMA The DMA request line is connected to the DMA Controller (DMAC). Using the ADC DMA requests requires the DMA Controller to be configured first. Related Links 28. DMAC – Direct Memory Access Controller 41.5.5 Interrupts The interrupt request line is connected to the interrupt controller. Using the ADC interrupt requires the interrupt controller to be configured first. 41.5.6 Events The events are connected to the Event System. Related Links 33. EVSYS – Event System 41.5.7 Debug Operation When the CPU is halted in debug mode the ADC will halt normal operation. The ADC can be forced to continue operation during debugging. Refer to DBGCTRL register for details. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 997 41.5.8 Register Access Protection All registers with write-access are optionally write-protected by the peripheral access controller (PAC), except the following register: • Interrupt Flag Status and Clear (INTFLAG) register Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. PAC write-protection does not apply to accesses through an external debugger. Related Links 15. PAC - Peripheral Access Controller 41.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 41.5.10 Analog Connections I/O-pins (AINx), as well as the VREFA/VREFB reference voltage pins are analog inputs to the ADC. Any internal reference source, such as a bandgap voltage reference, or DAC must be configured and enabled prior to its use with the ADC. The analog signals of AC, ADC, DAC and OPAMP can be interconnected. The AC and ADC peripheral can request the OPAMP using an analog ONDEMAND functionality. See Analog Connections of Peripherals for details. 41.5.11 Calibration The BIAS and LINEARITY calibration values from the production test must be loaded from the NVM Software Calibration Area into the ADC Calibration register (CALIB) by software to achieve specified accuracy. 41.6 Functional Description 41.6.1 Principle of Operation By default, the ADC provides results with 12-bit resolution. 8-bit or 10-bit results can be selected in order to reduce the conversion time, see 41.6.2.8 Conversion Timing and Sampling Rate. The ADC has an oversampling with decimation option that can extend the resolution to 16 bits. The input values can be either internal (e.g., an internal temperature sensor) or external (connected I/O pins). The user can also configure whether the conversion should be single-ended or differential. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 998 41.6.2 Basic Operation 41.6.2.1 Initialization The following registers are enable-protected, meaning that they can only be written when the ADC is disabled (CTRLA.ENABLE=0): • Control B register (CTRLB) • Reference Control register (REFCTRL) • Event Control register (EVCTRL) • Calibration register (CALIB) Enable-protection is denoted by the "Enable-Protected" property in the register description. 41.6.2.2 Enabling, Disabling and Resetting The ADC is enabled by writing a '1' to the Enable bit in the Control A register (CTRLA.ENABLE). The ADC is disabled by writing CTRLA.ENABLE=0. The ADC is reset by writing a '1' to the Software Reset bit in the Control A register (CTRLA.SWRST). All registers in the ADC, except DBGCTRL, will be reset to their initial state, and the ADC will be disabled. Refer to 41.8.1 CTRLA for details. 41.6.2.3 Operation In the most basic configuration, the ADC samples values from the configured internal or external sources (INPUTCTRL register). The rate of the conversion depends on the combination of the GCLK_ADC frequency and the clock prescaler. To convert analog values to digital values, the ADC needs to be initialized first, as described in the Initialization section. Data conversion can be started either manually by setting the Start bit in the Software Trigger register (SWTRIG.START=1), or automatically by configuring an automatic trigger to initiate the conversions. A free-running mode can be used to continuously convert an input channel. When using free-running mode the first conversion must be started, while subsequent conversions will start automatically at the end of previous conversions. The result of the conversion is stored in the Result register (RESULT) overwriting the result from the previous conversion. To avoid data loss if more than one channel is enabled, the conversion result must be read as soon as it is available (INTFLAG.RESRDY). Failing to do so will result in an overrun error condition, indicated by the OVERRUN bit in the Interrupt Flag Status and Clear register (INTFLAG.OVERRUN). To enable one of the available interrupts sources, the corresponding bit in the Interrupt Enable Set register (INTENSET) must be written to '1'. 41.6.2.4 Prescaler Selection The ADC is clocked by GCLK_ADC. There is also a prescaler in the ADC to enable conversion at lower clock rates. Refer to CTRLB for details on prescaler settings. Refer to 41.6.2.8 Conversion Timing and Sampling Rate for details on timing and sampling rate. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 999 Figure 41-2. ADC Prescaler GCLK_ADC 9-BIT PRESCALER CTRLB.PRESCALER[2:0] DIV2 DIV4 DIV8 DIV16 DIV32 DIV64 DIV128 DIV256 CLK_ADC Note:  The minimum prescaling factor is DIV2. 41.6.2.5 Reference Configuration The ADC has various sources for its reference voltage VREF. The Reference Voltage Selection bit field in the Reference Control register (REFCTRL.REFSEL) determines which reference is selected. By default, the internal voltage reference INTREF is selected. Based on customer application requirements, the external or internal reference can be selected. Refer to REFCTRL.REFSEL for further details on available selections. Related Links 41.8.3 REFCTRL 41.6.2.6 ADC Resolution The ADC supports 8-bit, 10-bit or 12-bit resolution. Resolution can be changed by writing the Resolution bit group in the Control C register (CTRLC.RESSEL). By default, the ADC resolution is set to 12 bits. The resolution affects the propagation delay, see also 41.6.2.8 Conversion Timing and Sampling Rate. 41.6.2.7 Differential and Single-Ended Conversions The ADC has two conversion options: differential and single-ended: If the positive input is always positive, the single-ended conversion should be used in order to have full 12-bit resolution in the conversion. If the positive input may go below the negative input, the differential mode should be used in order to get correct results. The differential mode is enabled by setting DIFFMODE bit in the Control C register (CTRLC.DIFFMODE). Both conversion types could be run in single mode or in free-running mode. When the free-running mode is selected, an ADC input will continuously sample the input and performs a new conversion. The INTFLAG.RESRDY bit will be set at the end of each conversion. 41.6.2.8 Conversion Timing and Sampling Rate The following figure shows the ADC timing for one single conversion. A conversion starts after the software or event start are synchronized with the GCLK_ADC clock. The input channel is sampled in the first half CLK_ADC period. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1000 Figure 41-3. ADC Timing for One Conversion in 12-bit Resolution CLK_ADC STATE START SAMPLING MSB LSB INT The sampling time can be increased by using the Sampling Time Length bit group in the Sampling Time Control register (SAMPCTRL.SAMPLEN). As example, the next figure is showing the timing conversion with sampling time increased to six CLK_ADC cycles. Figure 41-4. ADC Timing for One Conversion with Increased Sampling Time, 12-bit CLK_ADC STATE START MSB LSB INT SAMPLING The ADC provides also offset compensation, see the following figure. The offset compensation is enabled by the Offset Compensation bit in the Sampling Control register (SAMPCTRL.OFFCOMP). Note:  If offset compensation is used, the sampling time must be set to one cycle of CLK_ADC. In free running mode, the sampling rate RS is calculated by RS = fCLK_ADC / ( nSAMPLING + nOFFCOMP + nDATA) Here, nSAMPLING is the sampling duration in CLK_ADC cycles, nOFFCOMP is the offset compensation duration in clock cycles, and nDATA is the bit resolution. fCLK_ADC is the ADC clock frequency from the internal prescaler: fCLK_ADC = fGCLK_ADC / 2^(1 + CTRLB.PRESCALER) Figure 41-5. ADC Timing for One Conversion with Offset Compensation, 12-bit CLK_ADC STATE START SAMPLING MSB LSB INT Offset Compensation The impact of resolution on the sampling rate is seen in the next two figures, where free-running sampling in 12-bit and 8-bit resolution are compared. Figure 41-6. ADC Timing for Free Running in 12-bit Resolution CLK_ADC STATE CONVERT SAMPLING MSB LSB INT LSB SAMPLING MSB SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1001 Figure 41-7. ADC Timing for Free Running in 8-bit Resolution CLK_ADC STATE CONVERT SAMPLING LSB INT LSB MSB SAMPLING MSB 4 3 2 LSB SAMPLING MSB The propagation delay of an ADC measurement is given by: PropagationDelay = 1 + Resolution ݂ADC Example. In order to obtain 1MSPS in 12-bit resolution with a sampling time length of four CLK_ADC cycles, fCLK_ADC must be 1MSPS * (4 + 12) = 16MHz. As the minimal division factor of the prescaler is 2, GCLK_ADC must be 32MHz. 41.6.2.9 Accumulation The result from multiple consecutive conversions can be accumulated. The number of samples to be accumulated is specified by the Sample Number field in the Average Control register (AVGCTRL.SAMPLENUM). When accumulating more than 16 samples, the result will be too large to match the 16-bit RESULT register size. To avoid overflow, the result is right shifted automatically to fit within the available register size. The number of automatic right shifts is specified in the table below. Note:  To perform the accumulation of two or more samples, the Conversion Result Resolution field in the Control C register (CTRLC.RESSEL) must be set. Table 41-1. Accumulation Number of Accumulated Samples AVGCTRL. SAMPLENUM Number of Automatic Right Shifts Final Result Precision Automatic Division Factor 1 0x0 0 12 bits 0 2 0x1 0 13 bits 0 4 0x2 0 14 bits 0 8 0x3 0 15 bits 0 16 0x4 0 16 bits 0 32 0x5 1 16 bits 2 64 0x6 2 16 bits 4 128 0x7 3 16 bits 8 256 0x8 4 16 bits 16 512 0x9 5 16 bits 32 1024 0xA 6 16 bits 64 Reserved 0xB –0xF 12 bits 0 SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1002 41.6.2.10 Averaging Averaging is a feature that increases the sample accuracy, at the cost of a reduced sampling rate. This feature is suitable when operating in noisy conditions. Averaging is done by accumulating m samples, as described in 41.6.2.9 Accumulation, and dividing the result by m. The averaged result is available in the RESULT register. The number of samples to be accumulated is specified by writing to AVGCTRL.SAMPLENUM as shown in Table 41-2. The division is obtained by a combination of the automatic right shift described above, and an additional right shift that must be specified by writing to the Adjusting Result/Division Coefficient field in AVGCTRL (AVGCTRL.ADJRES), as described in Table 41-2. Note:  To perform the averaging of two or more samples, the Conversion Result Resolution field in the Control C register (CTRLC.RESSEL) must be set. Averaging AVGCTRL.SAMPLENUM samples will reduce the un-averaged sampling rate by a factor 1 AVGCTRL.SAMPLENUM. When the averaged result is available, the INTFLAG.RESRDY bit will be set. Table 41-2. Averaging Number of Accumulated Samples AVGCTRL. SAMPLENUM Intermediate Result Precision Number of Automatic Right Shifts Division Factor AVGCTRL.ADJRES Total Number of Right Shifts Final Result Precision Automatic Division Factor 1 0x0 12 bits 0 1 0x0 12 bits 0 2 0x1 13 0 2 0x1 1 12 bits 0 4 0x2 14 0 4 0x2 2 12 bits 0 8 0x3 15 0 8 0x3 3 12 bits 0 16 0x4 16 0 16 0x4 4 12 bits 0 32 0x5 17 1 16 0x4 5 12 bits 2 64 0x6 18 2 16 0x4 6 12 bits 4 128 0x7 19 3 16 0x4 7 12 bits 8 256 0x8 20 4 16 0x4 8 12 bits 16 512 0x9 21 5 16 0x4 9 12 bits 32 1024 0xA 22 6 16 0x4 10 12 bits 64 Reserved 0xB –0xF 0x0 12 bits 0 41.6.2.11 Oversampling and Decimation By using oversampling and decimation, the ADC resolution can be increased from 12 bits up to 16 bits, for the cost of reduced effective sampling rate. To increase the resolution by n bits, 4n samples must be accumulated. The result must then be rightshifted by n bits. This right-shift is a combination of the automatic right-shift and the value written to AVGCTRL.ADJRES. To obtain the correct resolution, the ADJRES must be configured as described in the table below. This method will result in n bit extra LSB resolution. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1003 Table 41-3. Configuration Required for Oversampling and Decimation Result Resolution Number of Samples to Average AVGCTRL.SAMPLENUM[3:0] Number of Automatic Right Shifts AVGCTRL.ADJRES[2:0] 13 bits 4 1 = 4 0x2 0 0x1 14 bits 4 2 = 16 0x4 0 0x2 15 bits 4 3 = 64 0x6 2 0x1 16 bits 4 4 = 256 0x8 4 0x0 41.6.2.12 Automatic Sequences The ADC has the ability to automatically sequence a series of conversions. This means that each time the ADC receives a start-of-conversion request, it can perform multiple conversions automatically. All of the 32 positive inputs can be included in a sequence by writing to corresponding bits in the Sequence Control register (SEQCTRL). The order of the conversion in a sequence is the lower positive MUX selection to upper positive MUX (AIN0, AIN1, AIN2 ...). In differential mode, the negative inputs selected by MUXNEG field, will be used for the entire sequence. When a sequence starts, the Sequence Busy status bit in Sequence Status register (SEQSTATUS.SEQBUSY) will be set. When the sequence is complete, the Sequence Busy status bit will be cleared. Each time a conversion is completed, the Sequence State bit in Sequence Status register (SEQSTATUS.SEQSTATE) will store the input number from which the conversion is done. The result will be stored in the RESULT register, and the Result Ready Interrupt Flag (INTFLAG.RESRDY) is set. If additional inputs must be scanned, the ADC will automatically start a new conversion on the next input present in the sequence list. Note that if SEQCTRL register has no bits set to '1', the conversion is done with the selected MUXPOS input. 41.6.2.13 Window Monitor The window monitor feature allows the conversion result in the RESULT register to be compared to predefined threshold values. The window mode is selected by setting the Window Monitor Mode bits in the Control C register (CTRLC.WINMODE). Threshold values must be written in the Window Monitor Lower Threshold register (WINLT) and Window Monitor Upper Threshold register (WINUT). If differential input is selected, the WINLT and WINUT are evaluated as signed values. Otherwise they are evaluated as unsigned values. The significant WINLT and WINUT bits are given by the precision selected in the Conversion Result Resolution bit group in the Control C register (CTRLC.RESSEL). This means that for example in 8-bit mode, only the eight lower bits will be considered. In addition, in differential mode, the eighth bit will be considered as the sign bit, even if the ninth bit is zero. The INTFLAG.WINMON interrupt flag will be set if the conversion result matches the window monitor condition. 41.6.2.14 Offset and Gain Correction Inherent gain and offset errors affect the absolute accuracy of the ADC. The offset error is defined as the deviation of the actual ADC transfer function from an ideal straight line at zero input voltage. The offset error cancellation is handled by the Offset Correction register SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1004 (OFFSETCORR). The offset correction value is subtracted from the converted data before writing the Result register (RESULT). The gain error is defined as the deviation of the last output step’s midpoint from the ideal straight line, after compensating for offset error. The gain error cancellation is handled by the Gain Correction register (GAINCORR). To correct these two errors, the Digital Correction Logic Enabled bit in the Control C register (CTRLC.CORREN) must be set. Offset and gain error compensation results are both calculated according to: Result = Conversion value+ െ OFFSETCORR ڄ GAINCORR The correction will introduce a latency of 13 CLK_ADC clock cycles. In free running mode this latency is introduced on the first conversion only, since its duration is always less than the propagation delay. In single conversion mode this latency is introduced for each conversion. Figure 41-8.  ADC Timing Correction Enabled START CONV0 CONV1 CONV2 CONV3 CORR0 CORR1 CORR2 CORR3 41.6.2.15 Reference Buffer Compensation Offset A hardware compensation using a reference buffer can be used. When the REFCTRL.REFCOMP bit is set, the offset of the reference buffer is sensed during the ADC sampling phase. This offset will be then cancelled during the conversion phase. This feature allows to decrease the overall gain error of the ADC. There is also a digital gain correction (refer to Offset and gain correction chapter) but contrary to that digital gain correction, the hardware compensation won’t introduce any latency. 41.6.3 Additional Features 41.6.3.1 Double Buffering The following registers are double buffered: • Input Control (INPUTCTRL) • Control C (CTRLC) • Average Control (AVGCTRL) • Sampling Time Control (SAMPCTRL) • Window Monitor Lower Threshold (WINLT) • Window Monitor Upper Threshold (WINUT) SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1005 • Gain Correction (GAINCORR) • Offset Correction (OFFSETCORR) When one of these registers is written, the data is stored in the corresponding buffer as long as the current conversion is not impacted, and the corresponding busy status will be set in the Synchronization Busy register (SYNCBUSY). When a new RESULT is available, data stored in the buffer registers will be transfered to the ADC and a new conversion can start. 41.6.3.2 Device Temperature Measurement Principle The device has an integrated temperature sensor which is part of the Supply Controller (SUPC). The analog signal of that sensor can be converted into a digital value by the ADC. The digital value can be converted into a temperature in °C by following the steps in this section. Configuration and Conditions In order to conduct temperature measurements, configure the device according to these steps. 1. Configure the clocks and device frequencies according to the Electrical Characteristics chapters. 2. Configure the Voltage References System of the Supply Controller (SUPC): 2.1. Enable the temperature sensor by writing a '1' to the Temperature Sensor Enable bit in the VREF Control register (SUPC.VREF.TSEN). 2.2. Select the required voltage for the internal voltage reference INTREF by writing to the Voltage Reference Selection bits (SUPC.VREF.SEL). The required value can be found in the Electrical Characteristics chapters. 2.3. Enable routing INTREF to the ADC by writing a '1' to the Voltage Reference Output Enable bit (SUPC.VREF.VREFOE). 3. Configure the ADC: 3.1. Select the internal voltage reference INTREF as ADC reference voltage by writing to the Reference Control register (ADC.REFCTRL.REFSEL). 3.2. Select the temperature sensor vs. internal GND as input by writing TEMP and GND to the positive and negative MUX Input Selection bit fields (ADC.INPUTCTRL.MUXNEG and .MUXPOS, respectively). 3.3. Configure the remaining ADC parameters according to the Electrical Characteristics chapters. 3.4. Enable the ADC and acquire a value, ADCm. Calculation Parameter Values The temperature sensor behavior is linear, but it is sensitive to several parameters such as the internal voltage reference - which itself depends on the temperature. To take this into account, each device contains a Temperature Log row with individual calibration data measured and written during the production tests. These calibration values are read by software to infer the most accurate temperature readings possible. The Temperature Log Row basically contains the following parameter set for two different temperatures ("ROOM" and "HOT"): • Calibration temperatures in °C. One at room temperature tempR, one at a higher temperature tempH: – ROOM_TEMP_VAL_INT and ROOM_TEMP_VAL_DEC contain the measured temperature at room insertion, tempR, in °C, separated in integer and decimal value. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1006 Example: For ROOM_TEMP_VAL_INT=0x19=25 and ROOM_TEMP_VAL_DEC=2, the measured temperature at room insertion is 25.2°C. – HOT_TEMP_VAL_INT and HOT_TEMP_VAL_DEC contain the measured temperature at hot insertion, tempH, in °C. The integer and decimal value are also separated. • For each temperature, the corresponding sensor value at the ADC in 12-bit, ADCR and ADCH: – ROOM_ADC_VAL contains the 12-bit ADC value, ADCR, corresponding to tempR. Its conversion to Volt is denoted VADCR. – HOT_ADC_VAL contains the 12-bit ADC value, ADCH, corresponding to tempH. Its conversion to Volt is denoted VADCH. • Actual reference voltages at each calibration temperature in Volt, INT1VR and INT1VH, respectively: – ROOM_INT1V_VAL is the 2’s complement of the internal 1V reference value at tempR: INT1VR. – HOT_INT1V_VAL is the 2’s complement of the internal 1V reference value at tempH: INT1VH. – Both ROOM_INT1V_VAL and HOT_INT1V_VAL values are centered around 1V with a 0.001V step. In other words, the range of values [0,127] corresponds to [1V, 0.873V] and the range of values [-1, -127] corresponds to [1.001V, 1.127V]. INT1V == 1 - (VAL/1000) is valid for both ranges. Calculating the Temperature by Linear Interpolation Using the data pairs (tempR, VADCR) and (tempH, VADCH) for a linear interpolation, we have the following equation: ( ܴܥܦܣܸ െ ܥܦܣܸ ܴ݌݉݁ݐ െ ݌݉݁ݐ ) = ( ܴܥܦܣܸ െ ܪܥܦܣܸ ܴ݌݉݁ݐ െ ܪ݌݉݁ݐ ) The voltages Vx are acquired as 12-bit ADC values ADCx , with respect to an internal reference voltage INT1Vx : [Equation 1] ݔܥܦܣ = ݔܥܦܣܸ ڄ ݔINT1V 2 12 െ 1 For the measured value of the temperature sensor, ADCm, the reference voltage is assumed to be perfect, i.e., INT1Vm=INT1Vc=1V. These substitutions yield a coarse value of the measured temperature tempC: [Equation 2] + ܴ݌݉݁ݐ = ܥ݌݉݁ݐ ڄ ݉ܥܦܣ INT1Vܿ 2 12 െ 1 ڄ ܴܥܦܣ െ INT1Vܴ 2 12 െ 1 ܴ݌݉݁ݐ െ ܪ݌݉݁ݐ ڄ ڄ ܪܥܦܣ ܪINT1V 2 12 െ 1 ڄ ܴܥܦܣ െ INT1Vܴ 2 12 െ 1 Or, after eliminating the 12-bit scaling factor (212-1): [Equation 3] + ܴ݌݉݁ݐ = ܥ݌݉݁ݐ ܴ݌݉݁ݐ െ ܪ݌݉݁ݐ ڄ ܴINT1V ڄ ܴܥܦܣ െܿ INT1V ڄ ݉ܥܦܣ ܴINT1V ڄ ܴܥܦܣ െ ܪINT1V ڄ ܪܥܦܣ SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1007 Equations 3 is a coarse value, because we assumed that INT1Vc=1V. To achieve a more accurate result, we replace INT1Vc with an interpolated value INT1Vm. We use the two data pairs (tempR, INT1VR) and (tempH, INT1VH) and yield: ( INT1V݉ െ INT1Vܴ ܴ݌݉݁ݐ െ݉ ݌݉݁ݐ ) = ( INT1Vܪ െ INT1Vܸܴ ܴ݌݉݁ݐ െ ܪ݌݉݁ݐ ) Using the coarse temperature value tempc , we can infer a more precise INT1Vm value during the ADC conversion as: [Equation 4] INT1V݉ = INT1Vܴ + ( (ܴ݌݉݁ݐ െ ܥ݌݉݁ݐ) ڄ (ܴINT1V െ ܪINT1V( (ܴ݌݉݁ݐ െ ܪ݌݉݁ݐ) ) Back to Equation 3, we replace the simple INT1Vc=1V by the more precise INT1Vm of Equation 4, and find a more accurate temperature value tempf : [Equation 5] + ܴ݌݉݁ݐ = ݂݌݉݁ݐ ܴ݌݉݁ݐ െ ܪ݌݉݁ݐ ڄ ܴINT1V ڄ ܴܥܦܣ െ݉ INT1V ڄ ݉ܥܦܣ ܴINT1V ڄ ܴܥܦܣ െ ܪINT1V ڄ ܪܥܦܣ 41.6.4 DMA Operation The ADC generates the following DMA request: • Result Conversion Ready (RESRDY): the request is set when a conversion result is available and cleared when the RESULT register is read. When the averaging operation is enabled, the DMA request is set when the averaging is completed and result is available. 41.6.5 Interrupts The ADC has the following interrupt sources: • Result Conversion Ready: RESRDY • Window Monitor: WINMON • Overrun: OVERRUN These interrupts, except the OVERRUN interrupt, are asynchronous wake-up sources. See Sleep Mode Controller for details. Each interrupt source has an interrupt flag associated with it. The interrupt flag in the Interrupt Flag Status and Clear (INTFLAG) register is set when the interrupt condition occurs. Each interrupt can be individually enabled by writing a one to the corresponding bit in the Interrupt Enable Set (INTENSET) register, and disabled by writing a one to the corresponding bit in the Interrupt Enable Clear (INTENCLR) register. An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until the interrupt flag is cleared, the interrupt is disabled, or the ADC is reset. See INTFLAG register for details on how to clear interrupt flags. All interrupt requests from the peripheral are ORed together on system level to generate one combined interrupt request to the NVIC. Refer to Nested Vector Interrupt Controller for details. The user must read the INTFLAG register to determine which interrupt condition is present. Note that interrupts must be globally enabled for interrupt requests to be generated. Refer to Nested Vector Interrupt Controller for details. Related Links 22.6.3.3 Sleep Mode Controller SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1008 41.8.5 INTENCLR 41.8.6 INTENSET 41.8.7 INTFLAG 41.6.6 Events The ADC can generate the following output events: • Result Ready (RESRDY): Generated when the conversion is complete and the result is available. Refer to 41.8.4 EVCTRL for details. • Window Monitor (WINMON): Generated when the window monitor condition match. Refer to 41.8.10 CTRLC for details. Setting an Event Output bit in the Event Control Register (EVCTRL.xxEO=1) enables the corresponding output event. Clearing this bit disables the corresponding output event. Refer to the Event System chapter for details on configuring the event system. The ADC can take the following actions on an input event: • Start conversion (START): Start a conversion. Refer to 41.8.17 SWTRIG for details. • Conversion flush (FLUSH): Flush the conversion. Refer to 41.8.17 SWTRIG for details. Setting an Event Input bit in the Event Control register (EVCTRL.xxEI=1) enables the corresponding action on input event. Clearing this bit disables the corresponding action on input event. The ADC uses only asynchronous events, so the asynchronous Event System channel path must be configured. By default, the ADC will detect a rising edge on the incoming event. If the ADC action must be performed on the falling edge of the incoming event, the event line must be inverted first. This is done by setting the corresponding Event Invert Enable bit in Event Control register (EVCTRL.xINV=1). Note:  If several events are connected to the ADC, the enabled action will be taken on any of the incoming events. If FLUSH and START events are available at the same time, the FLUSH event has priority. Related Links 33. EVSYS – Event System 41.6.7 Sleep Mode Operation The ONDEMAND and RUNSTDBY bits in the Control A register (CTRLA) control the behavior of the ADC during standby sleep mode, in cases where the ADC is enabled (CTRLA.ENABLE = 1). For further details on available options, refer to Table 41-4. Note:  When CTRLA.ONDEMAND=1, the analog block is powered-off when the conversion is complete. When a start request is detected, the system returns from sleep and starts a new conversion after the start-up time delay. Table 41-4. ADC Sleep Behavior CTRLA.RUNSTDBY CTRLA.ONDEMAND CTRLA.ENABLE Description x x 0 Disabled 0 0 1 Run in all sleep modes except STANDBY. 0 1 1 Run in all sleep modes on request, except STANDBY. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1009 CTRLA.RUNSTDBY CTRLA.ONDEMAND CTRLA.ENABLE Description 1 0 1 Run in all sleep modes. 1 1 1 Run in all sleep modes on request. 41.6.8 Synchronization Due to asynchronicity between the main clock domain and the peripheral clock domains, some registers need to be synchronized when written or read. The following bits are synchronized when written: • Software Reset bit in Control A register (CTRLA.SWRST) • Enable bit in Control A register (CTRLA.ENABLE) The following registers are synchronized when written: • Input Control register (INPUTCTRL) • Control C register (CTRLC) • Average control register (AVGCTRL) • Sampling time control register (SAMPCTRL) • Window Monitor Lower Threshold register (WINLT) • Window Monitor Upper Threshold register (WINUT) • Gain correction register (GAINCORR) • Offset Correction register (OFFSETCORR) • Software Trigger register (SWTRIG) Required write-synchronization is denoted by the "Write-Synchronized" property in the register description. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1010 41.7 Register Summary Offset Name Bit Pos. 0x00 CTRLA 7:0 ONDEMAND RUNSTDBY ENABLE SWRST 0x01 CTRLB 7:0 PRESCALER[2:0] 0x02 REFCTRL 7:0 REFCOMP REFSEL[3:0] 0x03 EVCTRL 7:0 WINMONEO RESRDYEO STARTINV FLUSHINV STARTEI FLUSHEI 0x04 INTENCLR 7:0 WINMON OVERRUN RESRDY 0x05 INTENSET 7:0 WINMON OVERRUN RESRDY 0x06 INTFLAG 7:0 WINMON OVERRUN RESRDY 0x07 SEQSTATUS 7:0 SEQBUSY SEQSTATE[4:0] 0x08 INPUTCTRL 7:0 MUXPOS[4:0] 15:8 MUXNEG[4:0] 0x0A CTRLC 7:0 RESSEL[1:0] CORREN FREERUN LEFTADJ DIFFMODE 15:8 WINMODE[2:0] 0x0C AVGCTRL 7:0 ADJRES[2:0] SAMPLENUM[3:0] 0x0D SAMPCTRL 7:0 OFFCOMP SAMPLEN[5:0] 0x0E WINLT 7:0 WINLT[7:0] 15:8 WINLT[15:8] 0x10 WINUT 7:0 WINUT[7:0] 15:8 WINUT[15:8] 0x12 GAINCORR 7:0 GAINCORR[7:0] 15:8 GAINCORR[11:8] 0x14 OFFSETCORR 7:0 OFFSETCORR[7:0] 15:8 OFFSETCORR[11:8] 0x16 ... 0x17 Reserved 0x18 SWTRIG 7:0 START FLUSH 0x19 ... 0x1B Reserved 0x1C DBGCTRL 7:0 DBGRUN 0x1D ... 0x1F Reserved 0x20 SYNCBUSY 7:0 WINUT WINLT SAMPCTRL AVGCTRL CTRLC INPUTCTRL ENABLE SWRST 15:8 SWTRIG OFFSETCOR R GAINCORR 0x22 ... 0x23 Reserved 0x24 RESULT 7:0 RESULT[7:0] 15:8 RESULT[15:8] 0x26 ... 0x27 Reserved SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1011 Offset Name Bit Pos. 0x28 SEQCTRL 7:0 SEQENn[7:0] 15:8 SEQENn[15:8] 23:16 SEQENn[23:16] 31:24 SEQENn[31:24] 0x2C CALIB 7:0 BIASCOMP[2:0] 15:8 BIASREFBUF[2:0] 41.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to the section on Synchronization. Some registers are synchronized when read and/or written. Synchronization is denoted by the "WriteSynchronized" or the "Read-Synchronized" property in each individual register description. For details, refer to Synchronization section. Some registers are enable-protected, meaning they can only be written when the peripheral is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1012 41.8.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized Bit 7 6 5 4 3 2 1 0 ONDEMAND RUNSTDBY ENABLE SWRST Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 – ONDEMAND On Demand Control The On Demand operation mode allows the ADC to be enabled or disabled, depending on other peripheral requests. In On Demand operation mode, i.e., if the ONDEMAND bit has been previously set, the ADC will only be running when requested by a peripheral. If there is no peripheral requesting the ADC will be in a disable state. If On Demand is disabled the ADC will always be running when enabled. In standby sleep mode, the On Demand operation is still active if the CTRLA.RUNSTDBY bit is '1'. If CTRLA.RUNSTDBY is '0', the ADC is disabled. This bit is not synchronized. Value Description 0 The ADC is always on , if enabled. 1 The ADC is enabled, when a peripheral is requesting the ADC conversion. The ADC is disabled if no peripheral is requesting it. Bit 6 – RUNSTDBY Run in Standby This bit controls how the ADC behaves during standby sleep mode. This bit is not synchronized. Value Description 0 The ADC is halted during standby sleep mode. 1 The ADC is not stopped in standby sleep mode. If CTRLA.ONDEMAND=1, the ADC will be running when a peripheral is requesting it. If CTRLA.ONDEMAND=0, the ADC will always be running in standby sleep mode. Bit 1 – ENABLE Enable Due to synchronization there is delay from writing CTRLA.ENABLE until the peripheral is enabled/ disabled. The value written to CTRL.ENABLE will read back immediately and the ENABLE bit in the SYNCBUSY register (SYNCBUSY.ENABLE) will be set. SYNCBUSY.ENABLE will be cleared when the operation is complete. Value Description 0 The ADC is disabled. 1 The ADC is enabled. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1013 Bit 0 – SWRST Software Reset Writing a '0' to this bit has no effect. Writing a '1' to this bit resets all registers in the ADC, except DBGCTRL, to their initial state, and the ADC will be disabled. Writing a '1' to CTRL.SWRST will always take precedence, meaning that all other writes in the same write-operation will be discarded. Due to synchronization there is a delay from writing CTRLA.SWRST until the reset is complete. CTRLA.SWRST and SYNCBUSY.SWRST will both be cleared when the reset is complete. Value Description 0 There is no reset operation ongoing. 1 The reset operation is ongoing. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1014 41.8.2 Control B Name:  CTRLB Offset:  0x01 Reset:  0x00 Property:  PAC Write-Protection, Enable-Protected Bit 7 6 5 4 3 2 1 0 PRESCALER[2:0] Access R/W R/W R/W Reset 0 0 0 Bits 2:0 – PRESCALER[2:0] Prescaler Configuration This field defines the ADC clock relative to the peripheral clock. Value Name Description 0x0 DIV2 Peripheral clock divided by 2 0x1 DIV4 Peripheral clock divided by 4 0x2 DIV8 Peripheral clock divided by 8 0x3 DIV16 Peripheral clock divided by 16 0x4 DIV32 Peripheral clock divided by 32 0x5 DIV64 Peripheral clock divided by 64 0x6 DIV128 Peripheral clock divided by 128 0x7 DIV256 Peripheral clock divided by 256 SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1015 41.8.3 Reference Control Name:  REFCTRL Offset:  0x02 Reset:  0x00 Property:  PAC Write-Protection, Enable-Protected Bit 7 6 5 4 3 2 1 0 REFCOMP REFSEL[3:0] Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 7 – REFCOMP Reference Buffer Offset Compensation Enable The gain error can be reduced by enabling the reference buffer offset compensation. This will increase the start-up time of the reference. Value Description 0 Reference buffer offset compensation is disabled. 1 Reference buffer offset compensation is enabled. Bits 3:0 – REFSEL[3:0] Reference Selection These bits select the reference for the ADC. Value Name Description 0x0 INTREF Internal variable reference voltage, refer to the SUPC.VREF register for voltage reference value x01 INTVCC0 1/1.6 VDDANA 0x2 INTVCC1 1/2 VDDANA (only for VDDANA > 2.0V) 0x3 VREFA External reference 0x4 VREFB External reference 0x5 INTVCC2 VDDANA 0x6 - 0xF Reserved SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1016 41.8.4 Event Control Name:  EVCTRL Offset:  0x03 Reset:  0x00 Property:  PAC Write-Protection, Enable-Protected Bit 7 6 5 4 3 2 1 0 WINMONEO RESRDYEO STARTINV FLUSHINV STARTEI FLUSHEI Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bit 5 – WINMONEO Window Monitor Event Out This bit indicates whether the Window Monitor event output is enabled or not and an output event will be generated when the window monitor detects something. Value Description 0 Window Monitor event output is disabled and an event will not be generated. 1 Window Monitor event output is enabled and an event will be generated. Bit 4 – RESRDYEO Result Ready Event Out This bit indicates whether the Result Ready event output is enabled or not and an output event will be generated when the conversion result is available. Value Description 0 Result Ready event output is disabled and an event will not be generated. 1 Result Ready event output is enabled and an event will be generated. Bit 3 – STARTINV Start Conversion Event Invert Enable Value Description 0 Start event input source is not inverted. 1 Start event input source is inverted. Bit 2 – FLUSHINV Flush Event Invert Enable Value Description 0 Flush event input source is not inverted. 1 Flush event input source is inverted. Bit 1 – STARTEI Start Conversion Event Input Enable Value Description 0 A new conversion will not be triggered on any incoming event. 1 A new conversion will be triggered on any incoming event. Bit 0 – FLUSHEI Flush Event Input Enable SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1017 Value Description 0 A flush and new conversion will not be triggered on any incoming event. 1 A flush and new conversion will be triggered on any incoming event. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1018 41.8.5 Interrupt Enable Clear Name:  INTENCLR Offset:  0x04 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set (INTENSET) register. Bit 7 6 5 4 3 2 1 0 WINMON OVERRUN RESRDY Access R/W R/W R/W Reset 0 0 0 Bit 2 – WINMON Window Monitor Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Window Monitor Interrupt Enable bit, which disables the corresponding interrupt request. Value Description 0 The window monitor interrupt is disabled. 1 The window monitor interrupt is enabled, and an interrupt request will be generated when the Window Monitor interrupt flag is set. Bit 1 – OVERRUN Overrun Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Overrun Interrupt Enable bit, which disables the corresponding interrupt request. Value Description 0 The Overrun interrupt is disabled. 1 The Overrun interrupt is enabled, and an interrupt request will be generated when the Overrun interrupt flag is set. Bit 0 – RESRDY Result Ready Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Result Ready Interrupt Enable bit, which disables the corresponding interrupt request. Value Description 0 The Result Ready interrupt is disabled. 1 The Result Ready interrupt is enabled, and an interrupt request will be generated when the Result Ready interrupt flag is set. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1019 41.8.6 Interrupt Enable Set Name:  INTENSET Offset:  0x05 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear (INTENCLR) register. Bit 7 6 5 4 3 2 1 0 WINMON OVERRUN RESRDY Access R/W R/W R/W Reset 0 0 0 Bit 2 – WINMON Window Monitor Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Window Monitor Interrupt bit, which enables the Window Monitor interrupt. Value Description 0 The Window Monitor interrupt is disabled. 1 The Window Monitor interrupt is enabled. Bit 1 – OVERRUN Overrun Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Overrun Interrupt bit, which enables the Overrun interrupt. Value Description 0 The Overrun interrupt is disabled. 1 The Overrun interrupt is enabled. Bit 0 – RESRDY Result Ready Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Result Ready Interrupt bit, which enables the Result Ready interrupt. Value Description 0 The Result Ready interrupt is disabled. 1 The Result Ready interrupt is enabled. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1020 41.8.7 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x06 Reset:  0x00 Property:  – Bit 7 6 5 4 3 2 1 0 WINMON OVERRUN RESRDY Access R/W R/W R/W Reset 0 0 0 Bit 2 – WINMON Window Monitor This flag is cleared by writing a '1' to the flag or by reading the RESULT register. This flag is set on the next GCLK_ADC cycle after a match with the window monitor condition, and an interrupt request will be generated if INTENCLR/SET.WINMON is '1'. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Window Monitor interrupt flag. Bit 1 – OVERRUN Overrun This flag is cleared by writing a '1' to the flag. This flag is set if RESULT is written before the previous value has been read by CPU, and an interrupt request will be generated if INTENCLR/SET.OVERRUN=1. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Overrun interrupt flag. Bit 0 – RESRDY Result Ready This flag is cleared by writing a '1' to the flag or by reading the RESULT register. This flag is set when the conversion result is available, and an interrupt will be generated if INTENCLR/ SET.RESRDY=1. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Result Ready interrupt flag. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1021 41.8.8 Sequence Status Name:  SEQSTATUS Offset:  0x07 Reset:  0x00 Property:  - Bit 7 6 5 4 3 2 1 0 SEQBUSY SEQSTATE[4:0] Access R R R R R R Reset 0 0 0 0 0 0 Bit 7 – SEQBUSY Sequence busy This bit is set when the sequence start. This bit is clear when the last conversion in a sequence is done. Bits 4:0 – SEQSTATE[4:0] Sequence State These bit fields are the pointer of sequence. This value identifies the last conversion done in the sequence. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1022 41.8.9 Input Control Name:  INPUTCTRL Offset:  0x08 Reset:  0x0000 Property:  PAC Write-Protection, Write-Synchronized Bit 15 14 13 12 11 10 9 8 MUXNEG[4:0] Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 MUXPOS[4:0] Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bits 12:8 – MUXNEG[4:0] Negative MUX Input Selection These bits define the MUX selection for the negative ADC input. Value Name Description 0x00 AIN0 ADC AIN0 pin 0x01 AIN1 ADC AIN1 pin 0x02 AIN2 ADC AIN2 pin 0x03 AIN3 ADC AIN3 pin 0x04 AIN4 ADC AIN4 pin 0x05 AIN5 ADC AIN5 pin 0x06 AIN6 ADC AIN6 pin 0x07 AIN7 ADC AIN7 pin 0x08 - 0x17 - Reserved 0x18 GND Internal ground 0x19 - 0x1F - Reserved Bits 4:0 – MUXPOS[4:0] Positive MUX Input Selection These bits define the MUX selection for the positive ADC input. If the internal bandgap voltage or temperature sensor input channel is selected, then the Sampling Time Length bit group in the Sampling Control register must be written with a corresponding value. Value Name Description 0x00 AIN0 ADC AIN0 pin 0x01 AIN1 ADC AIN1 pin 0x02 AIN2 ADC AIN2 pin 0x03 AIN3 ADC AIN3 pin 0x04 AIN4 ADC AIN4 pin 0x05 AIN5 ADC AIN5 pin 0x06 AIN6 ADC AIN6 pin SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1023 Value Name Description 0x07 AIN7 ADC AIN7 pin 0x08 AIN8 ADC AIN8 pin 0x09 AIN9 ADC AIN9 pin 0x0A - 0x17 - Reserved 0x18 TEMP Temperature Sensor 0x19 BANDGAP INTREF Voltage Reference 0x1A SCALEDVDDCORE 1/4 Scaled VDDCORE Supply 0x1B SCALEDVDDANA 1/4 Scaled VDDANA Supply 0x1C DAC DAC Output 0x1D SCALEDVDDIO 1/4 Scaled VDDIO Supply 0x1E OPAMP01 OPAMP0 or OPAMP1 output 0x1F OPAMP2 OPAMP2 output SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1024 41.8.10 Control C Name:  CTRLC Offset:  0x0A Reset:  0x0000 Property:  PAC Write-Protection, Write-Synchronized Bit 15 14 13 12 11 10 9 8 WINMODE[2:0] Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 RESSEL[1:0] CORREN FREERUN LEFTADJ DIFFMODE Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bits 10:8 – WINMODE[2:0] Window Monitor Mode These bits enable and define the window monitor mode. Value Name Description 0x0 DISABLE No window mode (default) 0x1 MODE1 RESULT > WINLT 0x2 MODE2 RESULT < WINUT 0x3 MODE3 WINLT < RESULT < WINUT 0x4 MODE4 WINUT < RESULT < WINLT 0x5 - 0x7 Reserved Bits 5:4 – RESSEL[1:0] Conversion Result Resolution These bits define whether the ADC completes the conversion 12-, 10- or 8-bit result resolution. Value Name Description 0x0 12BIT 12-bit result 0x1 16BIT For averaging mode output 0x2 10BIT 10-bit result 0x3 8BIT 8-bit result Bit 3 – CORREN Digital Correction Logic Enabled Value Description 0 Disable the digital result correction. 1 Enable the digital result correction. The ADC conversion result in the RESULT register is then corrected for gain and offset based on the values in the GAINCORR and OFFSETCORR registers. Conversion time will be increased by 13 cycles according to the value in the Offset Correction Value bit group in the Offset Correction register. Bit 2 – FREERUN Free Running Mode SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1025 Value Description 0 The ADC run in single conversion mode. 1 The ADC is in free running mode and a new conversion will be initiated when a previous conversion completes. Bit 1 – LEFTADJ Left-Adjusted Result Value Description 0 The ADC conversion result is right-adjusted in the RESULT register. 1 The ADC conversion result is left-adjusted in the RESULT register. The high byte of the 12- bit result will be present in the upper part of the result register. Writing this bit to zero (default) will right-adjust the value in the RESULT register. Bit 0 – DIFFMODE Differential Mode Value Description 0 The ADC is running in singled-ended mode. 1 The ADC is running in differential mode. In this mode, the voltage difference between the MUXPOS and MUXNEG inputs will be converted by the ADC. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1026 41.8.11 Average Control Name:  AVGCTRL Offset:  0x0C Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized Bit 7 6 5 4 3 2 1 0 ADJRES[2:0] SAMPLENUM[3:0] Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bits 6:4 – ADJRES[2:0] Adjusting Result / Division Coefficient These bits define the division coefficient in 2n steps. Bits 3:0 – SAMPLENUM[3:0] Number of Samples to be Collected These bits define how many samples are added together. The result will be available in the Result register (RESULT). Note: if the result width increases, CTRLC.RESSEL must be changed. Value Description 0x0 1 sample 0x1 2 samples 0x2 4 samples 0x3 8 samples 0x4 16 samples 0x5 32 samples 0x6 64 samples 0x7 128 samples 0x8 256 samples 0x9 512 samples 0xA 1024 samples 0xB - 0xF Reserved SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1027 41.8.12 Sampling Time Control Name:  SAMPCTRL Offset:  0x0D Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized Bit 7 6 5 4 3 2 1 0 OFFCOMP SAMPLEN[5:0] Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bit 7 – OFFCOMP Comparator Offset Compensation Enable Setting this bit enables the offset compensation for each sampling period to ensure low offset and immunity to temperature or voltage drift. This compensation increases the sampling time by three clock cycles. This bit must be set to zero to validate the SAMPLEN value. It’s not possible to use OFFCOMP=1 and SAMPLEN>0. Bits 5:0 – SAMPLEN[5:0] Sampling Time Length These bits control the ADC sampling time in number of CLK_ADC cycles, depending of the prescaler value, thus controlling the ADC input impedance. Sampling time is set according to the equation: Sampling time = SAMPLEN+1 ڄ CLKADC SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1028 41.8.13 Window Monitor Lower Threshold Name:  WINLT Offset:  0x0E Reset:  0x0000 Property:  PAC Write-Protection, Write-Synchronized Bit 15 14 13 12 11 10 9 8 WINLT[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 WINLT[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 15:0 – WINLT[15:0] Window Lower Threshold If the window monitor is enabled, these bits define the lower threshold value. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1029 41.8.14 Window Monitor Upper Threshold Name:  WINUT Offset:  0x10 Reset:  0x0000 Property:  PAV Write-Protection, Write-Synchronized Bit 15 14 13 12 11 10 9 8 WINUT[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 WINUT[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 15:0 – WINUT[15:0] Window Upper Threshold If the window monitor is enabled, these bits define the upper threshold value. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1030 41.8.15 Gain Correction Name:  GAINCORR Offset:  0x12 Reset:  0x0000 Property:  PAC Write-Protection, Write-Synchronized Bit 15 14 13 12 11 10 9 8 GAINCORR[11:8] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 6 5 4 3 2 1 0 GAINCORR[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 11:0 – GAINCORR[11:0] Gain Correction Value If CTRLC.CORREN=1, these bits define how the ADC conversion result is compensated for gain error before being written to the result register. The gain correction is a fractional value, a 1-bit integer plus an 11-bit fraction, and therefore ½ <= GAINCORR < 2. GAINCORR values range from 0.10000000000 to 1.11111111111. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1031 41.8.16 Offset Correction Name:  OFFSETCORR Offset:  0x14 Reset:  0x0000 Property:  PAC Write-Protection, Write-Synchronized Bit 15 14 13 12 11 10 9 8 OFFSETCORR[11:8] Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 6 5 4 3 2 1 0 OFFSETCORR[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 11:0 – OFFSETCORR[11:0] Offset Correction Value If CTRLC.CORREN=1, these bits define how the ADC conversion result is compensated for offset error before being written to the Result register. This OFFSETCORR value is in two’s complement format. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1032 41.8.17 Software Trigger Name:  SWTRIG Offset:  0x18 Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized Bit 7 6 5 4 3 2 1 0 START FLUSH Access W W Reset 0 0 Bit 1 – START ADC Start Conversion Writing a '1' to this bit will start a conversion or sequence. The bit is cleared by hardware when the conversion has started. Writing a '1' to this bit when it is already set has no effect. Writing a '0' to this bit will have no effect. Bit 0 – FLUSH ADC Conversion Flush Writing a '1' to this bit will flush the ADC pipeline. A flush will restart the ADC clock on the next peripheral clock edge, and all conversions in progress will be aborted and lost. This bit is cleared until the ADC has been flushed. After the flush, the ADC will resume where it left off; i.e., if a conversion was pending, the ADC will start a new conversion. Writing this bit to '0' will have no effect. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1033 41.8.18 Debug Control Name:  DBGCTRL Offset:  0x1C Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DBGRUN Access R/W Reset 0 Bit 0 – DBGRUN Debug Run This bit is not reset by a software reset. This bit controls the functionality when the CPU is halted by an external debugger. This bit should be written only while a conversion is not ongoing. Value Description 0 The ADC is halted when the CPU is halted by an external debugger. 1 The ADC continues normal operation when the CPU is halted by an external debugger. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1034 41.8.19 Synchronization Busy Name:  SYNCBUSY Offset:  0x20 Reset:  0x0000 Property:  - Bit 15 14 13 12 11 10 9 8 SWTRIG OFFSETCORR GAINCORR Access R R R Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 WINUT WINLT SAMPCTRL AVGCTRL CTRLC INPUTCTRL ENABLE SWRST Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 10 – SWTRIG Software Trigger Synchronization Busy This bit is cleared when the synchronization of SWTRIG register between the clock domains is complete. This bit is set when the synchronization of SWTRIG register between clock domains is started. Bit 9 – OFFSETCORR Offset Correction Synchronization Busy This bit is cleared when the synchronization of OFFSETCORR register between the clock domains is complete. This bit is set when the synchronization of OFFSETCORR register between clock domains is started. Bit 8 – GAINCORR Gain Correction Synchronization Busy This bit is cleared when the synchronization of GAINCORR register between the clock domains is complete. This bit is set when the synchronization of GAINCORR register between clock domains is started. Bit 7 – WINUT Window Monitor Lower Threshold Synchronization Busy This bit is cleared when the synchronization of WINUT register between the clock domains is complete. This bit is set when the synchronization of WINUT register between clock domains is started. Bit 6 – WINLT Window Monitor Upper Threshold Synchronization Busy This bit is cleared when the synchronization of WINLT register between the clock domains is complete. This bit is set when the synchronization of WINLT register between clock domains is started. Bit 5 – SAMPCTRL Sampling Time Control Synchronization Busy This bit is cleared when the synchronization of SAMPCTRL register between the clock domains is complete. This bit is set when the synchronization of SAMPCTRL register between clock domains is started. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1035 Bit 4 – AVGCTRL Average Control Synchronization Busy This bit is cleared when the synchronization of AVGCTRL register between the clock domains is complete. This bit is set when the synchronization of AVGCTRL register between clock domains is started. Bit 3 – CTRLC Control C Synchronization Busy This bit is cleared when the synchronization of CTRLC register between the clock domains is complete. This bit is set when the synchronization of CTRLC register between clock domains is started. Bit 2 – INPUTCTRL Input Control Synchronization Busy This bit is cleared when the synchronization of INPUTCTRL register between the clock domains is complete. This bit is set when the synchronization of INPUTCTRL register between clock domains is started. Bit 1 – ENABLE ENABLE Synchronization Busy This bit is cleared when the synchronization of ENABLE register between the clock domains is complete. This bit is set when the synchronization of ENABLE register between clock domains is started. Bit 0 – SWRST SWRST Synchronization Busy This bit is cleared when the synchronization of SWRST register between the clock domains is complete. This bit is set when the synchronization of SWRST register between clock domains is started SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1036 41.8.20 Result Name:  RESULT Offset:  0x24 Reset:  0x0000 Property:  - Bit 15 14 13 12 11 10 9 8 RESULT[15:8] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 RESULT[7:0] Access R R R R R R R R Reset 0 0 0 0 0 0 0 0 Bits 15:0 – RESULT[15:0] Result Conversion Value These bits will hold up to a 16-bit ADC conversion result, depending on the configuration. In single conversion mode without averaging, the ADC conversion will produce a 12-bit result, which can be left- or right-shifted, depending on the setting of CTRLC.LEFTADJ. If the result is left-adjusted (CTRLC.LEFTADJ), the high byte of the result will be in bit position [15:8], while the remaining 4 bits of the result will be placed in bit locations [7:4]. This can be used only if an 8-bit result is needed; i.e., one can read only the high byte of the entire 16-bit register. If the result is not left-adjusted (CTRLC.LEFTADJ) and no oversampling is used, the result will be available in bit locations [11:0], and the result is then 12 bits long. If oversampling is used, the result will be located in bit locations [15:0], depending on the settings of the Average Control register. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1037 41.8.21 Sequence Control Name:  SEQCTRL Offset:  0x28 Reset:  0x00000000 Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 SEQENn[31:24] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 SEQENn[23:16] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 SEQENn[15:8] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 SEQENn[7:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 31:0 – SEQENn[31:0] Enable Positive Input in the Sequence For details on available positive mux selection, refer to INPUTCTRL.MUXENG. The sequence start from the lowest input, and go to the next enabled input automatically when the conversion is done. If no bits are set the sequence is disabled. Value Description 0 Disable the positive input mux n selection from the sequence. 1 Enable the positive input mux n selection to the sequence. SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1038 41.8.22 Calibration Name:  CALIB Offset:  0x2C Reset:  0x0000 Property:  PAC Write-Protection, Enable-Protected Bit 15 14 13 12 11 10 9 8 BIASREFBUF[2:0] Access R/W R/W R/W Reset 0 0 0 Bit 7 6 5 4 3 2 1 0 BIASCOMP[2:0] Access R/W R/W R/W Reset 0 0 0 Bits 10:8 – BIASREFBUF[2:0] Bias Reference Buffer Scaling This value from production test must be loaded from the NVM software calibration row into the CALIB register by software to achieve the specified accuracy. The value must be copied only, and must not be changed. Bits 2:0 – BIASCOMP[2:0] Bias Comparator Scaling This value from production test must be loaded from the NVM software calibration row into the CALIB register by software to achieve the specified accuracy. The value must be copied only, and must not be changed SAM L10/L11 Family ADC – Analog-to-Digital Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1039 42. AC – Analog Comparators 42.1 Overview The Analog Comparator (AC) supports two individual comparators. Each comparator (COMP) compares the voltage levels on two inputs, and provides a digital output based on this comparison. Each comparator may be configured to generate interrupt requests and/or peripheral events upon several different combinations of input change. Hysteresis and propagation delay can be adjusted to achieve the optimal operation for each application. The input selection includes four shared analog port pins and several internal signals. Each comparator output state can also be output on a pin for use by external devices. The comparators are grouped in pairs on each port. The AC peripheral implements one pair of comparators . These are called Comparator 0 (COMP0) and Comparator 1 (COMP1) They have identical behaviors, but separate control registers. The pair can be set in window mode to compare a signal to a voltage range instead of a single voltage level. 42.2 Features • Two individual comparators • Selectable propagation delay versus current consumption • Selectable hysteresis: 4-level On, or Off • Analog comparator outputs available on pins – Asynchronous or synchronous • Flexible input selection: – Four pins selectable for positive or negative inputs – Ground (for zero crossing) – Bandgap reference voltage – 64-level programmable VDD scaler per comparator – DAC – OPAMP2 • Interrupt generation on: – Rising or falling edge – Toggle – End of comparison • Window function interrupt generation on: – Signal above window – Signal inside window – Signal below window – Signal outside window • Event generation on: – Comparator output – Window function inside/outside window SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1040 • Optional digital filter on comparator output 42.3 Block Diagram Figure 42-1. Analog Comparator Block Diagram INTERRUPT MODE ENABLE ENABLE HYSTERESIS HYSTERESIS DAC VDD SCALER BANDGAP + - + - CMP0 CMP1 INTERRUPTS EVENTS GCLK_AC AIN3 AIN2 AIN1 AIN0 COMP0 COMP1 COMPCTRLn WINCTRL INTERRUPT SENSITIVITY CONTROL & WINDOW FUNCTION OPAMP2 42.4 Signal Description Signal Description Type AIN[3..0] Analog input Comparator inputs CMP[1..0] Digital output Comparator outputs Refer to I/O Multiplexing and Considerations for details on the pin mapping for this peripheral. One signal can be mapped on several pins. 42.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 42.5.1 I/O Lines Using the AC’s I/O lines requires the I/O pins to be configured. Refer to PORT - I/O Pin Controller for details. Related Links 32. PORT - I/O Pin Controller SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1041 42.5.2 Power Management The AC will continue to operate in any sleep mode where the selected source clock is running. The AC’s interrupts can be used to wake up the device from sleep modes. Events connected to the event system can trigger other operations in the system without exiting sleep modes. Related Links 22. PM – Power Manager 42.5.3 Clocks The AC bus clock (CLK_AC_APB) can be enabled and disabled in the Main Clock module, MCLK (see MCLK - Main Clock, and the default state of CLK_AC_APB can be found in Peripheral Clock Masking. A generic clock (GCLK_AC) is required to clock the AC. This clock must be configured and enabled in the generic clock controller before using the AC. Refer to the Generic Clock Controller chapter for details. This generic clock is asynchronous to the bus clock (CLK_AC_APB). Due to this asynchronicity, writes to certain registers will require synchronization between the clock domains. Refer to Synchronization for further details. Related Links 22. PM – Power Manager 42.5.4 DMA Not applicable. 42.5.5 Interrupts The interrupt request lines are connected to the interrupt controller. Using the AC interrupts requires the interrupt controller to be configured first. Refer to Nested Vector Interrupt Controller for details. 42.5.6 Events The events are connected to the Event System. Refer to EVSYS – Event System for details on how to configure the Event System. Related Links 33. EVSYS – Event System 42.5.7 Debug Operation When the CPU is halted in debug mode, the AC will halt normal operation after any on-going comparison is completed. The AC can be forced to continue normal operation during debugging. Refer to DBGCTRL for details. If the AC 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. 42.5.8 Register Access Protection All registers with write-access can be write-protected optionally by the Peripheral Access Controller (PAC), except for the following registers: • Control B register (CTRLB) • Interrupt Flag register (INTFLAG) Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. PAC write-protection does not apply to accesses through an external debugger. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1042 Related Links 15. PAC - Peripheral Access Controller 42.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 42.5.10 Analog Connections Each comparator has up to four I/O pins that can be used as analog inputs. Each pair of comparators shares the same four pins. These pins must be configured for analog operation before using them as comparator inputs. Any internal reference source, such as a bandgap voltage reference, OPAMP2,or DAC must be configured and enabled prior to its use as a comparator input. The analog signals of AC, ADC, DAC and OPAMP can be interconnected. The AC and ADC peripheral can request the OPAMP using an analog ONDEMAND functionality. See Analog Connections of Peripherals for details. 42.6 Functional Description 42.6.1 Principle of Operation Each comparator has one positive input and one negative input. Each positive input may be chosen from a selection of analog input pins. Each negative input may be chosen from a selection of both analog input pins and internal inputs, such as a bandgap voltage reference. The digital output from the comparator is '1' when the difference between the positive and the negative input voltage is positive, and '0' otherwise. The individual comparators can be used independently (normal mode) or paired to form a window comparison (window mode). 42.6.2 Basic Operation 42.6.2.1 Initialization Some registers are enable-protected, meaning they can only be written when the module is disabled. The following register is enable-protected: • Event Control register (EVCTRL) Enable-protection is denoted by the "Enable-Protected" property in each individual register description. 42.6.2.2 Enabling, Disabling and Resetting The AC is enabled by writing a '1' to the Enable bit in the Control A register (CTRLA.ENABLE). The AC is disabled writing a '0' to CTRLA.ENABLE. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1043 The AC is reset by writing a '1' to the Software Reset bit in the Control A register (CTRLA.SWRST). All registers in the AC will be reset to their initial state, and the AC will be disabled. Refer to CTRLA for details. 42.6.2.3 Comparator Configuration Each individual comparator must be configured by its respective Comparator Control register (COMPCTRLx) before that comparator is enabled. These settings cannot be changed while the comparator is enabled. • Select the desired measurement mode with COMPCTRLx.SINGLE. See Starting a Comparison for more details. • Select the desired hysteresis with COMPCTRLx.HYSTEN and COMPCTRLx.HYST. See Input Hysteresis for more details. • Select the comparator speed versus power with COMPCTRLx.SPEED. See Propagation Delay vs. Power Consumption for more details. • Select the interrupt source with COMPCTRLx.INTSEL. • Select the positive and negative input sources with the COMPCTRLx.MUXPOS and COMPCTRLx.MUXNEG bits. See Selecting Comparator Inputs for more details. • Select the filtering option with COMPCTRLx.FLEN. • Select standby operation with Run in Standby bit (COMPCTRLx.RUNSTDBY). The individual comparators are enabled by writing a '1' to the Enable bit in the Comparator x Control registers (COMPCTRLx.ENABLE). The individual comparators are disabled by writing a '0' to COMPCTRLx.ENABLE. Writing a '0' to CTRLA.ENABLE will also disable all the comparators, but will not clear their COMPCTRLx.ENABLE bits. 42.6.2.4 Starting a Comparison Each comparator channel can be in one of two different measurement modes, determined by the Single bit in the Comparator x Control register (COMPCTRLx.SINGLE): • Continuous measurement • Single-shot After being enabled, a start-up delay is required before the result of the comparison is ready. This start-up time is measured automatically to account for environmental changes, such as temperature or voltage supply level, and is specified in the Electrical Characteristics chapters. During the start-up time, the COMP output is not available. The comparator can be configured to generate interrupts when the output toggles, when the output changes from '0' to '1' (rising edge), when the output changes from '1' to '0' (falling edge) or at the end of the comparison. An end-of-comparison interrupt can be used with the Single-Shot mode to chain further events in the system, regardless of the state of the comparator outputs. The Interrupt mode is set by the Interrupt Selection bit group in the Comparator Control register (COMPCTRLx.INTSEL). Events are generated using the comparator output state, regardless of whether the interrupt is enabled or not. 42.6.2.4.1 Continuous Measurement Continuous measurement is selected by writing COMPCTRLx.SINGLE to zero. In continuous mode, the comparator is continuously enabled and performing comparisons. This ensures that the result of the latest comparison is always available in the Current State bit in the Status A register (STATUSA.STATEx). After the start-up time has passed, a comparison is done and STATUSA is updated. The Comparator x Ready bit in the Status B register (STATUSB.READYx) is set, and the appropriate peripheral events and SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1044 interrupts are also generated. New comparisons are performed continuously until the COMPCTRLx.ENABLE bit is written to zero. The start-up time applies only to the first comparison. In continuous operation, edge detection of the comparator output for interrupts is done by comparing the current and previous sample. The sampling rate is the GCLK_AC frequency. An example of continuous measurement is shown in the Figure 42-2. Figure 42-2. Continuous Measurement Example GCLK_AC STATUSB.READYx Sampled Comparator Output COMPCTRLx.ENABLE tSTARTUP Write ‘1’ 2-3 cycles For low-power operation, comparisons can be performed during sleep modes without a clock. The comparator is enabled continuously, and changes of the comparator state are detected asynchronously. When a toggle occurs, the Power Manager will start GCLK_AC to register the appropriate peripheral events and interrupts. The GCLK_AC clock is then disabled again automatically, unless configured to wake up the system from sleep. 42.6.2.4.2 Single-Shot Single-shot operation is selected by writing COMPCTRLx.SINGLE to '1'. During single-shot operation, the comparator is normally idle. The user starts a single comparison by writing '1' to the respective Start Comparison bit in the write-only Control B register (CTRLB.STARTx). The comparator is enabled, and after the start-up time has passed, a single comparison is done and STATUSA is updated. Appropriate peripheral events and interrupts are also generated. No new comparisons will be performed. Writing '1' to CTRLB.STARTx also clears the Comparator x Ready bit in the Status B register (STATUSB.READYx). STATUSB.READYx is set automatically by hardware when the single comparison has completed. A single-shot measurement can also be triggered by the Event System. Setting the Comparator x Event Input bit in the Event Control Register (EVCTRL.COMPEIx) enables triggering on incoming peripheral events. Each comparator can be triggered independently by separate events. Event-triggered operation is similar to user-triggered operation; the difference is that a peripheral event from another hardware module causes the hardware to automatically start the comparison and clear STATUSB.READYx. To detect an edge of the comparator output in single-shot operation for the purpose of interrupts, the result of the current measurement is compared with the result of the previous measurement (one sampling period earlier). An example of single-shot operation is shown in Figure 42-3. Figure 42-3. Single-Shot Example GCLK_AC STATUSB.READYx Sampled Comparator Output CTRLB.STARTx tSTARTUP Write ‘1’ tSTARTUP Write ‘1’ 2-3 cycles 2-3 cycles For low-power operation, event-triggered measurements can be performed during sleep modes. When the event occurs, the Power Manager will start GCLK_AC. The comparator is enabled, and after the startup time has passed, a comparison is done and appropriate peripheral events and interrupts are also generated. The comparator and GCLK_AC are then disabled again automatically, unless configured to wake up the system from sleep. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1045 42.6.3 Selecting Comparator Inputs Each comparator has one positive and one negative input. The positive input is one of the external input pins (AINx). The negative input can be fed either from an external input pin (AINx) or from one of the several internal reference voltage sources common to all comparators. The user selects the input source as follows: • The positive input is selected by the Positive Input MUX Select bit group in the Comparator Control register (COMPCTRLx.MUXPOS) • The negative input is selected by the Negative Input MUX Select bit group in the Comparator Control register (COMPCTRLx.MUXNEG) In the case of using an external I/O pin, the selected pin must be configured for analog use in the PORT Controller by disabling the digital input and output. The switching of the analog input multiplexers is controlled to minimize crosstalk between the channels. The input selection must be changed only while the individual comparator is disabled. Note:  For internal use of the comparison results by the CCL, this bit must be 0x1 or 0x2. 42.6.4 Window Operation Each comparator pair can be configured to work together in window mode. In this mode, a voltage range is defined, and the comparators give information about whether an input signal is within this range or not. Window mode is enabled by the Window Enable x bit in the Window Control register (WINCTRL.WENx). Both comparators in a pair must have the same measurement mode setting in their respective Comparator Control Registers (COMPCTRLx.SINGLE). To physically configure the pair of comparators for window mode, the same I/O pin must be chosen as positive input for each comparator, providing a shared input signal. The negative inputs define the range for the window. In Figure 42-4, COMP0 defines the upper limit and COMP1 defines the lower limit of the window, as shown but the window will also work in the opposite configuration with COMP0 lower and COMP1 higher. The current state of the window function is available in the Window x State bit group of the Status register (STATUS.WSTATEx). Window mode can be configured to generate interrupts when the input voltage changes to below the window, when the input voltage changes to above the window, when the input voltage changes into the window or when the input voltage changes outside the window. The interrupt selections are set by the Window Interrupt Selection bit field in the Window Control register (WINCTRL.WINTSEL). Events are generated using the inside/outside state of the window, regardless of whether the interrupt is enabled or not. Note that the individual comparator outputs, interrupts and events continue to function normally during window mode. When the comparators are configured for window mode and single-shot mode, measurements are performed simultaneously on both comparators. Writing '1' to either Start Comparison bit in the Control B register (CTRLB.STARTx) will start a measurement. Likewise either peripheral event can start a measurement. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1046 Figure 42-4. Comparators in Window Mode + - + - STATE0 STATE1 WSTATE[1:0] INTERRUPTS EVENTS INPUT SIGNAL UPPER LIMIT OF WINDOW COMP0 COMP1 INTERRUPT SENSITIVITY CONTROL & WINDOW FUNCTION LOWER LIMIT OF WINDOW 42.6.5 VDD Scaler The VDD scaler generates a reference voltage that is a fraction of the device’s supply voltage, with 64 levels. One independent voltage channel is dedicated for each comparator. The scaler of a comparator is enabled when the Negative Input Mux bit field in the respective Comparator Control register (COMPCTRLx.MUXNEG) is set to 0x5 and the comparator is enabled. The voltage of each channel is selected by the Value bit field in the Scaler x registers (SCALERx.VALUE). SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1047 Figure 42-5. VDD Scaler COMPCTRLx.MUXNEG == 5 SCALERx. VALUE to COMPx 6 42.6.6 Input Hysteresis Application software can selectively enable/disable hysteresis for the comparison. Applying hysteresis will help prevent constant toggling of the output, which can be caused by noise when the input signals are close to each other. Hysteresis is enabled for each comparator individually by the Hysteresis Enable bit in the Comparator x Control register (COMPCTRLx.HYSTEN). Furthermore, when enabled, the level of hysteresis is programmable through the Hysteresis Level bits also in the Comparator x Control register (COMPCTRLx.HYST). Hysteresis is available only in continuous mode (COMPCTRLx.SINGLE=0). 42.6.7 Propagation Delay vs. Power Consumption It is possible to trade off comparison speed for power efficiency to get the shortest possible propagation delay or the lowest power consumption. The speed setting is configured for each comparator individually by the Speed bit group in the Comparator x Control register (COMPCTRLx.SPEED). The Speed bits select the amount of bias current provided to the comparator, and as such will also affect the start-up time. 42.6.8 Filtering The output of the comparators can be filtered digitally to reduce noise. The filtering is determined by the Filter Length bits in the Comparator Control x register (COMPCTRLx.FLEN), and is independent for each comparator. Filtering is selectable from none, 3-bit majority (N=3) or 5-bit majority (N=5) functions. Any change in the comparator output is considered valid only if N/2+1 out of the last N samples agree. The filter sampling rate is the GCLK_AC frequency. Note that filtering creates an additional delay of N-1 sampling cycles from when a comparison is started until the comparator output is validated. For continuous mode, the first valid output will occur when the required number of filter samples is taken. Subsequent outputs will be generated every cycle based on the current sample plus the previous N-1 samples, as shown in Figure 42-6. For single-shot mode, the comparison completes after the Nth filter sample, as shown in Figure 42-7. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1048 Figure 42-6. Continuous Mode Filtering Sampling Clock Sampled Comparator Output 3-bit Majority Filter Output 5-bit Majority Filter Output Figure 42-7. Single-Shot Filtering Sampling Clock 3-bit Sampled Comparator Output 3-bit Majority Filter Output Start 5-bit Sampled Comparator Output 5-bit Majority Filter Output tSTARTUP During sleep modes, filtering is supported only for single-shot measurements. Filtering must be disabled if continuous measurements will be done during sleep modes, or the resulting interrupt/event may be generated incorrectly. 42.6.9 Comparator Output The output of each comparator can be routed to an I/O pin by setting the Output bit group in the Comparator Control x register (COMPCTRLx.OUT). This allows the comparator to be used by external circuitry. Either the raw, non-synchronized output of the comparator or the CLK_AC-synchronized version, including filtering, can be used as the I/O signal source. The output appears on the corresponding CMP[x] pin. 42.6.10 Offset Compensation The Swap bit in the Comparator Control registers (COMPCTRLx.SWAP) controls switching of the input signals to a comparator's positive and negative terminals. When the comparator terminals are swapped, the output signal from the comparator is also inverted, as shown in Figure 42-8. This allows the user to measure or compensate for the comparator input offset voltage. As part of the input selection, COMPCTRLx.SWAP can be changed only while the comparator is disabled. Figure 42-8. Input Swapping for Offset Compensation MUXPOS MUXNEG + - COMPx SWAP ENABLE HYSTERESIS SWAP CMPx COMPCTRLx 42.6.11 DMA Operation Not applicable. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1049 42.6.12 Interrupts The AC has the following interrupt sources: • Comparator (COMP0, COMP1): Indicates a change in comparator status. • Window (WIN0): Indicates a change in the window status. Comparator interrupts are generated based on the conditions selected by the Interrupt Selection bit group in the Comparator Control registers (COMPCTRLx.INTSEL). Window interrupts are generated based on the conditions selected by the Window Interrupt Selection bit group in the Window Control register (WINCTRL.WINTSEL[1:0]). Each interrupt source has an interrupt flag associated with it. The interrupt flag in the Interrupt Flag Status and Clear (INTFLAG) register is set when the interrupt condition occurs. Each interrupt can be individually enabled by writing a one to the corresponding bit in the Interrupt Enable Set (INTENSET) register, and disabled by writing a one to the corresponding bit in the Interrupt Enable Clear (INTENCLR) register. An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until the interrupt flag is cleared, the interrupt is disabled, or the AC is reset. See INFLAG register for details on how to clear interrupt flags. All interrupt requests from the peripheral are ORed together on system level to generate one combined interrupt request to the NVIC. The user must read the INTFLAG register to determine which interrupt condition is present. Note that interrupts must be globally enabled for interrupt requests to be generated. 42.6.13 Events The AC can generate the following output events: • Comparator (COMP0, COMP1): Generated as a copy of the comparator status • Window (WIN0): Generated as a copy of the window inside/outside status Writing a one to an Event Output bit in the Event Control Register (EVCTRL.xxEO) enables the corresponding output event. Writing a zero to this bit disables the corresponding output event. Refer to the Event System chapter for details on configuring the event system. The AC can take the following action on an input event: • Start comparison (START0, START1): Start a comparison. Writing a one to an Event Input bit into the Event Control register (EVCTRL.COMPEIx) enables the corresponding action on input event. Writing a zero to this bit disables the corresponding action on input event. Note that if several events are connected to the AC, the enabled action will be taken on any of the incoming events. Refer to the Event System chapter for details on configuring the event system. When EVCTRL.COMPEIx is one, the event will start a comparison on COMPx after the start-up time delay. In normal mode, each comparator responds to its corresponding input event independently. For a pair of comparators in window mode, either comparator event will trigger a comparison on both comparators simultaneously. 42.6.14 Sleep Mode Operation The Run in Standby bits in the Comparator x Control registers (COMPCTRLx.RUNSTDBY) control the behavior of the AC during standby sleep mode. Each RUNSTDBY bit controls one comparator. When the bit is zero, the comparator is disabled during sleep, but maintains its current configuration. When the bit is one, the comparator continues to operate during sleep. Note that when RUNSTDBY is zero, the analog blocks are powered off for the lowest power consumption. This necessitates a start-up time delay when the system returns from sleep. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1050 For Window Mode operation, both comparators in a pair must have the same RUNSTDBY configuration. When RUNSTDBY is one, any enabled AC interrupt source can wake up the CPU. The AC can also be used during sleep modes where the clock used by the AC is disabled, provided that the AC is still powered (not in shutdown). In this case, the behavior is slightly different and depends on the measurement mode, as listed in Table 42-1. Table 42-1. Sleep Mode Operation COMPCTRLx.MODE RUNSTDBY=0 RUNSTDBY=1 0 (Continuous) COMPx disabled GCLK_AC stopped, COMPx enabled 1 (Single-shot) COMPx disabled GCLK_AC stopped, COMPx enabled only when triggered by an input event 42.6.14.1 Continuous Measurement during Sleep When a comparator is enabled in continuous measurement mode and GCLK_AC is disabled during sleep, the comparator will remain continuously enabled and will function asynchronously. The current state of the comparator is asynchronously monitored for changes. If an edge matching the interrupt condition is found, GCLK_AC is started to register the interrupt condition and generate events. If the interrupt is enabled in the Interrupt Enable registers (INTENCLR/SET), the AC can wake up the device; otherwise GCLK_AC is disabled until the next edge detection. Filtering is not possible with this configuration. Figure 42-9. Continuous Mode SleepWalking GCLK_AC STATUSB.READYx Sampled Comparator Output COMPCTRLx.ENABLE tSTARTUP Write ‘1’ 2-3 cycles 42.6.14.2 Single-Shot Measurement during Sleep For low-power operation, event-triggered measurements can be performed during sleep modes. When the event occurs, the Power Manager will start GCLK_AC. The comparator is enabled, and after the startup time has passed, a comparison is done, with filtering if desired, and the appropriate peripheral events and interrupts are also generated, as shown in Figure 42-10. The comparator and GCLK_AC are then disabled again automatically, unless configured to wake the system from sleep. Filtering is allowed with this configuration. Figure 42-10. Single-Shot SleepWalking GCLK_AC Comparator Output or Event Input Event tSTARTUP tSTARTUP 42.6.15 Synchronization Due to asynchronicity between the main clock domain and the peripheral clock domains, some registers need to be synchronized when written or read. The following bits are synchronized when written: SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1051 • Software Reset bit in control register (CTRLA.SWRST) • Enable bit in control register (CTRLA.ENABLE) • Enable bit in Comparator Control register (COMPCTRLn.ENABLE) The following registers are synchronized when written: • Window Control register (WINCTRL) Required write-synchronization is denoted by the "Write-Synchronized" property in the register description. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1052 42.7 Register Summary Offset Name Bit Pos. 0x00 CTRLA 7:0 ENABLE SWRST 0x01 CTRLB 7:0 STARTx STARTx 0x02 EVCTRL 7:0 WINEO0 COMPEOx COMPEOx 15:8 INVEIx INVEIx COMPEIx COMPEIx 0x04 INTENCLR 7:0 WIN0 COMPx COMPx 0x05 INTENSET 7:0 WIN0 COMPx COMPx 0x06 INTFLAG 7:0 WIN0 COMPx COMPx 0x07 STATUSA 7:0 WSTATE0[1:0] STATEx STATEx 0x08 STATUSB 7:0 READYx READYx 0x09 DBGCTRL 7:0 DBGRUN 0x0A WINCTRL 7:0 WINTSEL0[1:0] WEN0 0x0B Reserved 0x0C SCALER0 7:0 VALUE[5:0] 0x0D SCALER1 7:0 VALUE[5:0] 0x0E ... 0x0F Reserved 0x10 COMPCTRL0 7:0 RUNSTDBY INTSEL[1:0] SINGLE ENABLE 15:8 SWAP MUXPOS[2:0] MUXNEG[2:0] 23:16 HYST[1:0] HYSTEN SPEED[1:0] 31:24 OUT[1:0] FLEN[2:0] 0x14 COMPCTRL1 7:0 RUNSTDBY INTSEL[1:0] SINGLE ENABLE 15:8 SWAP MUXPOS[2:0] MUXNEG[2:0] 23:16 HYST[1:0] HYSTEN SPEED[1:0] 31:24 OUT[1:0] FLEN[2:0] 0x18 ... 0x1F Reserved 0x20 SYNCBUSY 7:0 COMPCTRLx COMPCTRLx WINCTRL ENABLE SWRST 15:8 23:16 31:24 42.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to Register Access Protection. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1053 Some registers are synchronized when read and/or written. Synchronization is denoted by the "WriteSynchronized" or the "Read-Synchronized" property in each individual register description. For details, refer to Synchronization. Some registers are enable-protected, meaning they can only be written when the peripheral is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1054 42.8.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized Bit 7 6 5 4 3 2 1 0 ENABLE SWRST Access R/W W Reset 0 0 Bit 1 – ENABLE Enable Due to synchronization, there is delay from updating the register until the peripheral is enabled/disabled. The value written to CTRL.ENABLE will read back immediately and the corresponding bit in the Synchronization Busy register (SYNCBUSY.ENABLE) will be set. SYNCBUSY.ENABLE is cleared when the peripheral is enabled/disabled. Value Description 0 The AC is disabled. 1 The AC is enabled. Each comparator must also be enabled individually by the Enable bit in the Comparator Control register (COMPCTRLn.ENABLE). Bit 0 – SWRST Software Reset Writing a '0' to this bit has no effect. Writing a '1' to this bit resets all registers in the AC to their initial state, and the AC will be disabled. Writing a '1' to CTRLA.SWRST will always take precedence, meaning that all other writes in the same write-operation will be discarded. Due to synchronization, there is a delay from writing CTRLA.SWRST until the reset is complete. CTRLA.SWRST and SYNCBUSY.SWRST will both be cleared when the reset is complete. Value Description 0 There is no reset operation ongoing. 1 The reset operation is ongoing. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1055 42.8.2 Control B Name:  CTRLB Offset:  0x01 Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized Bit 7 6 5 4 3 2 1 0 STARTx STARTx Access R/W R/W Reset 0 0 Bits 1,0 – STARTx Comparator x Start Comparison Writing a '0' to this field has no effect. Writing a '1' to STARTx starts a single-shot comparison on COMPx if both the Single-Shot and Enable bits in the Comparator x Control Register are '1' (COMPCTRLx.SINGLE and COMPCTRLx.ENABLE). If comparator x is not implemented, or if it is not enabled in single-shot mode, Writing a '1' has no effect. This bit always reads as zero. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1056 42.8.3 Event Control Name:  EVCTRL Offset:  0x02 Reset:  0x0000 Property:  PAC Write-Protection, Enable-Protected Bit 15 14 13 12 11 10 9 8 INVEIx INVEIx COMPEIx COMPEIx Access R/W R/W R/W R/W Reset 0 0 0 0 Bit 7 6 5 4 3 2 1 0 WINEO0 COMPEOx COMPEOx Access R/W R/W R/W Reset 0 0 0 Bits 13,12 – INVEIx Inverted Event Input Enable x Value Description 0 Incoming event is not inverted for comparator x. 1 Incoming event is inverted for comparator x. Bits 9,8 – COMPEIx Comparator x Event Input Note that several actions can be enabled for incoming events. If several events are connected to the peripheral, the enabled action will be taken for any of the incoming events. There is no way to tell which of the incoming events caused the action. These bits indicate whether a comparison will start or not on any incoming event. Value Description 0 Comparison will not start on any incoming event. 1 Comparison will start on any incoming event. Bit 4 – WINEO0 Window 0 Event Output Enable These bits indicate whether the window 0 function can generate a peripheral event or not. Value Description 0 Window 0 Event is disabled. 1 Window 0 Event is enabled. Bits 1,0 – COMPEOx Comparator x Event Output Enable These bits indicate whether the comparator x output can generate a peripheral event or not. Value Description 0 COMPx event generation is disabled. 1 COMPx event generation is enabled. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1057 42.8.4 Interrupt Enable Clear Name:  INTENCLR Offset:  0x04 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 7 6 5 4 3 2 1 0 WIN0 COMPx COMPx Access R/W R/W R/W Reset 0 0 0 Bit 4 – WIN0 Window 0 Interrupt Enable Reading this bit returns the state of the Window 0 interrupt enable. Writing a '0' to this bit has no effect. Writing a '1' to this bit disables the Window 0 interrupt. Value Description 0 The Window 0 interrupt is disabled. 1 The Window 0 interrupt is enabled. Bits 1,0 – COMPx Comparator x Interrupt Enable Reading this bit returns the state of the Comparator x interrupt enable. Writing a '0' to this bit has no effect. Writing a '1' to this bit disables the Comparator x interrupt. Value Description 0 The Comparator x interrupt is disabled. 1 The Comparator x interrupt is enabled. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1058 42.8.5 Interrupt Enable Set Name:  INTENSET Offset:  0x05 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to enable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear register (INTENCLR). Bit 7 6 5 4 3 2 1 0 WIN0 COMPx COMPx Access R/W R/W R/W Reset 0 0 0 Bit 4 – WIN0 Window 0 Interrupt Enable Reading this bit returns the state of the Window 0 interrupt enable. Writing a '0' to this bit has no effect. Writing a '1' to this bit enables the Window 0 interrupt. Value Description 0 The Window 0 interrupt is disabled. 1 The Window 0 interrupt is enabled. Bits 1,0 – COMPx Comparator x Interrupt Enable Reading this bit returns the state of the Comparator x interrupt enable. Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Ready interrupt bit and enable the Ready interrupt. Value Description 0 The Comparator x interrupt is disabled. 1 The Comparator x interrupt is enabled. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1059 42.8.6 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x06 Reset:  0x00 Property:  – Bit 7 6 5 4 3 2 1 0 WIN0 COMPx COMPx Access R/W R/W R/W Reset 0 0 0 Bit 4 – WIN0 Window 0 This flag is set according to the Window 0 Interrupt Selection bit group in the WINCTRL register (WINCTRL.WINTSELx) and will generate an interrupt if INTENCLR/SET.WINx is also one. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Window 0 interrupt flag. Bits 1,0 – COMPx Comparator x Reading this bit returns the status of the Comparator x interrupt flag. If comparator x is not implemented, COMPx always reads as zero. This flag is set according to the Interrupt Selection bit group in the Comparator x Control register (COMPCTRLx.INTSEL) and will generate an interrupt if INTENCLR/SET.COMPx is also one. Writing a '0' to this bit has no effect. Writing a '1' to this bit clears the Comparator x interrupt flag. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1060 42.8.7 Status A Name:  STATUSA Offset:  0x07 Reset:  0x00 Property:  Read-Only Bit 7 6 5 4 3 2 1 0 WSTATE0[1:0] STATEx STATEx Access R R R R Reset 0 0 0 0 Bits 5:4 – WSTATE0[1:0] Window 0 Current State These bits show the current state of the signal if the window 0 mode is enabled. Value Name Description 0x0 ABOVE Signal is above window 0x1 INSIDE Signal is inside window 0x2 BELOW Signal is below window 0x3 Reserved Bits 1,0 – STATEx Comparator x Current State This bit shows the current state of the output signal from COMPx. STATEx is valid only when STATUSB.READYx is one. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1061 42.8.8 Status B Name:  STATUSB Offset:  0x08 Reset:  0x00 Property:  Read-Only Bit 7 6 5 4 3 2 1 0 READYx READYx Access R R Reset 0 0 Bits 1,0 – READYx Comparator x Ready This bit is cleared when the comparator x output is not ready. This bit is set when the comparator x output is ready. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1062 42.8.9 Debug Control Name:  DBGCTRL Offset:  0x09 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DBGRUN Access R/W Reset 0 Bit 0 – DBGRUN Debug Run This bit is not reset by a software reset. This bits controls the functionality when the CPU is halted by an external debugger. Value Description 0 The AC is halted when the CPU is halted by an external debugger. Any on-going comparison will complete. 1 The AC continues normal operation when the CPU is halted by an external debugger. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1063 42.8.10 Window Control Name:  WINCTRL Offset:  0x0A Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized Bit 7 6 5 4 3 2 1 0 WINTSEL0[1:0] WEN0 Access R/W R/W R/W Reset 0 0 0 Bits 2:1 – WINTSEL0[1:0] Window 0 Interrupt Selection These bits configure the interrupt mode for the comparator window 0 mode. Value Name Description 0x0 ABOVE Interrupt on signal above window 0x1 INSIDE Interrupt on signal inside window 0x2 BELOW Interrupt on signal below window 0x3 OUTSIDE Interrupt on signal outside window Bit 0 – WEN0 Window 0 Mode Enable Value Description 0 Window mode is disabled for comparators 0 and 1. 1 Window mode is enabled for comparators 0 and 1. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1064 42.8.11 Scaler n Name:  SCALER Offset:  0x0C + n*0x01 [n=0..1] Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 VALUE[5:0] Access R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 Bits 5:0 – VALUE[5:0] Scaler Value These bits define the scaling factor for channel n of the VDD voltage scaler. The output voltage, VSCALE, is: ܸSCALE = ܸDD ڄ VALUE+1 64 SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1065 42.8.12 Comparator Control n Name:  COMPCTRL Offset:  0x10 + n*0x04 [n=0..1] Reset:  0x00000000 Property:  PAC Write-Protection, Write-Synchronized Bit 31 30 29 28 27 26 25 24 OUT[1:0] FLEN[2:0] Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 23 22 21 20 19 18 17 16 HYST[1:0] HYSTEN SPEED[1:0] Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 SWAP MUXPOS[2:0] MUXNEG[2:0] Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 RUNSTDBY INTSEL[1:0] SINGLE ENABLE Access R/W R/W R/W R/W R/W Reset 0 0 0 0 0 Bits 29:28 – OUT[1:0] Output These bits configure the output selection for comparator n. COMPCTRLn.OUT can be written only while COMPCTRLn.ENABLE is zero. Note:  For internal use of the comparison results by the CCL, this bit must be 0x1 or 0x2. These bits are not synchronized. Value Name Description 0x0 OFF The output of COMPn is not routed to the COMPn I/O port 0x1 ASYNC The asynchronous output of COMPn is routed to the COMPn I/O port 0x2 SYNC The synchronous output (including filtering) of COMPn is routed to the COMPn I/O port 0x3 N/A Reserved Bits 26:24 – FLEN[2:0] Filter Length These bits configure the filtering for comparator n. COMPCTRLn.FLEN can only be written while COMPCTRLn.ENABLE is zero. These bits are not synchronized. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1066 Value Name Description 0x0 OFF No filtering 0x1 MAJ3 3-bit majority function (2 of 3) 0x2 MAJ5 5-bit majority function (3 of 5) 0x3-0x7 N/A Reserved Bits 21:20 – HYST[1:0] Hysteresis Level These bits indicate the hysteresis level of comparator n when hysteresis is enabled (COMPCTRLn.HYSTEN=1). Hysteresis is available only for continuous mode (COMPCTRLn.SINGLE=0). COMPCTRLn.HYST can be written only while COMPCTRLn.ENABLE is zero. These bits are not synchronized. Value Name Description 0x0 HYST50 50mV 0x1 HYST70 70mV 0x2 HYST90 90mV 0x3 HYST110 110mV Bit 19 – HYSTEN Hysteresis Enable This bit indicates the hysteresis mode of comparator n. Hysteresis is available only for continuous mode (COMPCTRLn.SINGLE=0). COMPCTRLn.HYST can be written only while COMPCTRLn.ENABLE is zero. This bit is not synchronized. Value Description 0 Hysteresis is disabled. 1 Hysteresis is enabled. Bits 17:16 – SPEED[1:0] Speed Selection This bit indicates the speed/propagation delay mode of comparator n. COMPCTRLn.SPEED can be written only while COMPCTRLn.ENABLE is zero. These bits are not synchronized. Value Name Description 0x0 LOW Low speed 0x1 MEDLOW Medium low speed 0x2 MEDHIGH Medium high speed 0x3 HIGH High speed Bit 15 – SWAP Swap Inputs and Invert This bit swaps the positive and negative inputs to COMPn and inverts the output. This function can be used for offset cancellation. COMPCTRLn.SWAP can be written only while COMPCTRLn.ENABLE is zero. These bits are not synchronized. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1067 Value Description 0 The output of MUXPOS connects to the positive input, and the output of MUXNEG connects to the negative input. 1 The output of MUXNEG connects to the positive input, and the output of MUXPOS connects to the negative input. Bits 14:12 – MUXPOS[2:0] Positive Input Mux Selection These bits select which input will be connected to the positive input of comparator n. COMPCTRLn.MUXPOS can be written only while COMPCTRLn.ENABLE is zero. These bits are not synchronized. Value Name Description 0x0 PIN0 I/O pin 0 0x1 PIN1 I/O pin 1 0x2 PIN2 I/O pin 2 0x3 PIN3 I/O pin 3 0x4 VSCALE VDD scaler 0x5–0x7 - Reserved Bits 10:8 – MUXNEG[2:0] Negative Input Mux Selection These bits select which input will be connected to the negative input of comparator n. COMPCTRLn.MUXNEG can only be written while COMPCTRLn.ENABLE is zero. These bits are not synchronized. Value Name Description 0x0 PIN0 I/O pin 0 0x1 PIN1 I/O pin 1 0x2 PIN2 I/O pin 2 0x3 PIN3 I/O pin 3 0x4 GND Ground 0x5 VSCALE VDD scaler 0x6 BANDGAP Internal bandgap voltage 0x7 DAC / OPAMP DAC0 output (COMP0) OPAMP2 output (COMP1) Bit 6 – RUNSTDBY Run in Standby This bit controls the behavior of the comparator during standby sleep mode. This bit is not synchronized Value Description 0 The comparator is disabled during sleep. 1 The comparator continues to operate during sleep. Bits 4:3 – INTSEL[1:0] Interrupt Selection These bits select the condition for comparator n to generate an interrupt or event. COMPCTRLn.INTSEL can be written only while COMPCTRLn.ENABLE is zero. These bits are not synchronized. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1068 Value Name Description 0x0 TOGGLE Interrupt on comparator output toggle 0x1 RISING Interrupt on comparator output rising 0x2 FALLING Interrupt on comparator output falling 0x3 EOC Interrupt on end of comparison (single-shot mode only) Bit 2 – SINGLE Single-Shot Mode This bit determines the operation of comparator n. COMPCTRLn.SINGLE can be written only while COMPCTRLn.ENABLE is zero. These bits are not synchronized. Value Description 0 Comparator n operates in continuous measurement mode. 1 Comparator n operates in single-shot mode. Bit 1 – ENABLE Enable Writing a zero to this bit disables comparator n. Writing a one to this bit enables comparator n. Due to synchronization, there is delay from updating the register until the comparator is enabled/disabled. The value written to COMPCTRLn.ENABLE will read back immediately after being written. SYNCBUSY.COMPCTRLn is set. SYNCBUSY.COMPCTRLn is cleared when the peripheral is enabled/ disabled. Writing a one to COMPCTRLn.ENABLE will prevent further changes to the other bits in COMPCTRLn. These bits remain protected until COMPCTRLn.ENABLE is written to zero and the write is synchronized. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1069 42.8.13 Synchronization Busy Name:  SYNCBUSY Offset:  0x20 Reset:  0x00000000 Property:  Read-Only Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 COMPCTRLx COMPCTRLx WINCTRL ENABLE SWRST Access R R R R R Reset 0 0 0 0 0 Bits 4,3 – COMPCTRLx COMPCTRLx Synchronization Busy This bit is cleared when the synchronization of the COMPCTRLx register between the clock domains is complete. This bit is set when the synchronization of the COMPCTRLx register between clock domains is started. Bit 2 – WINCTRL WINCTRL Synchronization Busy This bit is cleared when the synchronization of the WINCTRL register between the clock domains is complete. This bit is set when the synchronization of the WINCTRL register between clock domains is started. Bit 1 – ENABLE Enable Synchronization Busy This bit is cleared when the synchronization of the CTRLA.ENABLE bit between the clock domains is complete. This bit is set when the synchronization of the CTRLA.ENABLE bit between clock domains is started. Bit 0 – SWRST Software Reset Synchronization Busy This bit is cleared when the synchronization of the CTRLA.SWRST bit between the clock domains is complete. This bit is set when the synchronization of the CTRLA.SWRST bit between clock domains is started. SAM L10/L11 Family AC – Analog Comparators © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1070 43. DAC – Digital-to-Analog Converter 43.1 Overview The Digital-to-Analog Converter (DAC) converts a digital value to a voltage. The DAC has one channel with 10-bit resolution, and it is capable of converting up to 350,000 samples per second (350ksps). 43.2 Features • DAC with 10-bit resolution • Up to 350ksps conversion rate • Hardware support for 14-bit using dithering • Multiple trigger sources • High-drive capabilities • Output can be used as input to the Analog Comparator (AC), ADC • DMA support 43.3 Block Diagram Figure 43-1. DAC Block Diagram DATABUF DATA DAC Controller DAC10 VOUT VREFA Internal input VDDANA Ref.voltage (VREF) Output Buffer 43.4 Signal Description Signal Name Type Description VOUT Analog output DAC output VREFA Analog input External reference 43.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 43.5.1 I/O Lines Using the DAC Controller’s I/O lines requires the I/O pins to be configured using the port configuration (PORT). Related Links SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1071 32. PORT - I/O Pin Controller 43.5.2 Power Management The DAC will continue to operate in any Sleep mode where the selected source clock is running. The DAC interrupts can be used to wake up the device from sleep modes. Events connected to the event system can trigger other operations in the system without exiting sleep modes. Related Links 22. PM – Power Manager 43.5.3 Clocks The DAC bus clock (CLK_DAC_APB) can be enabled and disabled by the Main Clock module, and the default state of CLK_DAC_APB can be found in the Peripheral Clock Masking section. A generic clock (GCLK_DAC) is required to clock the DAC Controller. This clock must be configured and enabled in the Generic Clock Controller before using the DAC Controller. Refer to GCLK – Generic Clock Controller for details. This generic clock is asynchronous to the bus clock (CLK_DAC_APB). Due to this asynchronicity, writes to certain registers will require synchronization between the clock domains. Refer to 43.6.7 Synchronization for further details. Related Links 18. GCLK - Generic Clock Controller 43.5.4 DMA The DMA request line is connected to the DMA Controller (DMAC). Using the DAC Controller DMA requests requires to configure the DMAC first. Related Links 28. DMAC – Direct Memory Access Controller 43.5.5 Interrupts The interrupt request line is connected to the interrupt controller. Using the DAC Controller interrupt(s) requires the interrupt controller to be configured first. 43.5.6 Events The events are connected to the Event System. Related Links 33. EVSYS – Event System 43.5.7 Debug Operation When the CPU is halted in debug mode the DAC will halt normal operation. Any on-going conversions will be completed. The DAC can be forced to continue normal operation during debugging. If the DAC 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. 43.5.8 Register Access Protection All registers with write-access can be write-protected optionally by the Peripheral Access Controller (PAC), except the following registers: SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1072 • Interrupt Flag Status and Clear (INTFLAG) register • Data Buffer (DATABUF) register Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. PAC write-protection does not apply to accesses through an external debugger Related Links 15. PAC - Peripheral Access Controller 43.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 43.5.10 Analog Connections The DAC has one output pin (VOUT) and one analog input pin (VREFA) that must be configured first. When internal input is used, it must be enabled before DAC Controller is enabled. 43.6 Functional Description 43.6.1 Principle of Operation The DAC converts the digital value located in the Data register (DATA) into an analog voltage on the DAC output (VOUT). A conversion is started when new data is written to the Data register. The resulting voltage is available on the DAC output after the conversion time. A conversion can also be started by input events from the Event System. 43.6.2 Basic Operation 43.6.2.1 Initialization The following registers are enable-protected, meaning they can only be written when the DAC is disabled (CTRLA.ENABLE is zero): • Control B register (CTRLB) • Event Control register (EVCTRL) Enable-protection is denoted by the Enable-Protected property in the register description. Before enabling the DAC, it must be configured by selecting the voltage reference using the Reference Selection bits in the Control B register (CTRLB.REFSEL). 43.6.2.2 Enabling, Disabling and Resetting The DAC Controller is enabled by writing a '1' to the Enable bit in the Control A register (CTRLA.ENABLE). The DAC Controller is disabled by writing a '0' to CTRLA.ENABLE. SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1073 The DAC Controller is reset by writing a '1' to the Software Reset bit in the Control A register (CTRLA.SWRST). All registers in the DAC will be reset to their initial state, and the DAC Controller will be disabled. Refer to the CTRLA register for details. 43.6.2.3 Enabling the Output Buffer To enable the DAC output on the VOUT pin, the output driver must be enabled by writing a one to the External Output Enable bit in the Control B register (CTRLB.EOEN). The DAC output buffer provides a high-drive-strength output, and is capable of driving both resistive and capacitive loads. To minimize power consumption, the output buffer should be enabled only when external output is needed. 43.6.2.4 Digital to Analog Conversion The DAC converts a digital value (stored in the DATA register) into an analog voltage. The conversion range is between GND and the selected DAC voltage reference. The default voltage reference is the internal reference voltage. Other voltage reference options are the analog supply voltage (VDDANA) and the external voltage reference (VREFA). The voltage reference is selected by writing to the Reference Selection bits in the Control B register (CTRLB.REFSEL). The output voltage from the DAC can be calculated using the following formula: ܸOUT = DATA 0ݔ3FF ڄ VREF A new conversion starts as soon as a new value is loaded into DATA. DATA can either be loaded via the APB bus during a CPU write operation, using DMA, or from the DATABUF register when a START event occurs. Refer to 43.6.5 Events for details. As there is no automatic indication that a conversion is done, the sampling period must be greater than or equal to the specified conversion time. 43.6.3 DMA Operation The DAC generates the following DMA request: • Data Buffer Empty (EMPTY): The request is set when data is transferred from DATABUF to the internal data buffer of DAC. The request is cleared when DATABUF register is written, or by writing a one to the EMPTY bit in the Interrupt Flag register (INTFLAG.EMPTY). For each Start Conversion event, DATABUF is transferred into DATA and the conversion starts. When DATABUF is empty, the DAC generates the DMA request for new data. As DATABUF is initially empty, a DMA request is generated whenever the DAC is enabled. If the CPU accesses the registers that are the source of a DMA request set/clear condition, the DMA request can be lost or the DMA transfer can be corrupted, if enabled. 43.6.4 Interrupts The DAC Controller has the following interrupt sources: • Data Buffer Empty (EMPTY): Indicates that the internal data buffer of the DAC is empty. • Underrun (UNDERRUN): Indicates that the internal data buffer of the DAC is empty and a DAC start of conversion event occurred. Refer to 43.6.5 Events for details. Each interrupt source has an interrupt flag associated with it. The interrupt flag in the Interrupt Flag Status and Clear register (INTFLAG) is set when the interrupt condition occurs. Each interrupt can be individually enabled by writing a one to the corresponding bit in the Interrupt Enable Set register (INTENSET), and disabled by writing a one to the corresponding bit in the Interrupt Enable Clear register (INTENCLR). SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1074 An interrupt request is generated when the interrupt flag is set and the corresponding interrupt is enabled. The interrupt request remains active until the interrupt flag is cleared, the interrupt is disabled or the DAC is reset. See INTFLAG register for details on how to clear interrupt flags. All interrupt requests from the peripheral are ORed together on system level to generate one combined interrupt request to the NVIC. The user must read the INTFLAG register to determine which interrupt condition is present. Note that interrupts must be globally enabled for interrupt requests to be generated.. 43.6.5 Events The DAC Controller can generate the following output events: • Data Buffer Empty (EMPTY): Generated when the internal data buffer of the DAC is empty. Refer to DMA Operation for details. Writing a '1' to an Event Output bit in the Event Control register (EVCTRL.EMPTYEO) enables the corresponding output event. Writing a '0' to this bit disables the corresponding output event. The DAC can take the following action on an input event: • Start Conversion (START): DATABUF value is transferred into DATA as soon as the DAC is ready for the next conversion, and then conversion is started. START is considered as asynchronous to GCLK_DAC thus it is resynchronized in DAC Controller. Refer to 43.6.2.4 Digital to Analog Conversion for details. Writing a '1' to an Event Input bit in the Event Control register (EVCTRL.STARTEI) enables the corresponding action on an input event. Writing a '0' to this bit disables the corresponding action on input event. Note: When several events are connected to the DAC Controller, the enabled action will be taken on any of the incoming events. By default, DAC Controller detects rising edge events. Falling edge detection can be enabled by writing a '1' to EVCTRL.INVEIx. Related Links 33. EVSYS – Event System 43.6.6 Sleep Mode Operation The generic clock for the DAC is running in idle sleep mode. If the Run In Standby bit in the Control A register (CTRLA.RUNSTDBY) is one, the DAC output buffer will keep its value in standby sleep mode. If CTRLA.RUNSTDBY is zero, the DAC output buffer will be disabled in standby sleep mode. 43.6.7 Synchronization Due to the asynchronicity between main clock domain and the peripheral clock domains, some registers need to be synchronized when written or read. A register can require: • Synchronization when written • Synchronization when read • Synchronization when written and read • No synchronization When executing an operation that requires synchronization, the corresponding status bit in the Synchronization Busy register (SYNCBUSY) will be set immediately, and cleared when synchronization is complete. SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1075 If an operation that requires synchronization is executed while its busy bit is one, the operation is discarded and an error is generated. The following bits need synchronization when written: • Software Reset bit in the Control A register (CTRLA.SWRST) • Enable bit in the Control A register (CTRLA.ENABLE) • All bits in the Data register (DATA) • All bits in the Data Buffer register (DATABUF) Write-synchronization is denoted by the Write-Synchronized property in the register description. No bits need synchronization when read. 43.6.8 Additional Features 43.6.8.1 DAC as an Internal Reference The DAC output can be internally enabled as input to the analog comparator. This is enabled by writing a one to the Internal Output Enable bit in the Control B register (CTRLB.IOEN). It is possible to have the internal and external output enabled simultaneously. The DAC output can also be enabled as input to the Analog-to-Digital Converter. In this case, the output buffer must be enabled. 43.6.8.2 Data Buffer The Data Buffer register (DATABUF) and the Data register (DATA) are linked together to form a two-stage FIFO. The DAC uses the Start Conversion event to load data from DATABUF into DATA and start a new conversion. The Start Conversion event is enabled by writing a one to the Start Event Input bit in the Event Control register (EVCTRL.STARTEI). If a Start Conversion event occurs when DATABUF is empty, an Underrun interrupt request is generated if the Underrun interrupt is enabled. The DAC can generate a Data Buffer Empty event when DATABUF becomes empty and new data can be loaded to the buffer. The Data Buffer Empty event is enabled by writing a one to the Empty Event Output bit in the Event Control register (EVCTRL.EMPTYEO). A Data Buffer Empty interrupt request is generated if the Data Buffer Empty interrupt is enabled. 43.6.8.3 Voltage Pump When the DAC is used at operating voltages lower than 2.5V, the voltage pump must be enabled. This enabling is done automatically, depending on operating voltage. The voltage pump can be disabled by writing a one to the Voltage Pump Disable bit in the Control B register (CTRLB.VPD). This can be used to reduce power consumption when the operating voltage is above 2.5V. The voltage pump uses the asynchronous GCLK_DAC clock, and requires that the clock frequency be at least four times higher than the sampling period. 43.6.8.4 Dithering mode In dithering mode, DATA is a 14-bit signed value where DATA[13:4] is the 10-bit data converted by DAC and DATA[3:0] the dither bits, used to minimize the quantization error. The principle is to make 16 sub-conversions of DATA[13:4] value or (DATA[13:4] + 1) value so that by averaging those 2 values, the 14-bit value (DATA[13:0]) conversion is accurate. To operate, START event must be configured to generate 16 events for each DATA[15:0] conversion and DATABUF must be loaded every 16 DAC conversions. EMPTY event and DMA request are therefore generated every 16 DATABUF to DATA transfer. SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1076 Writing a one to the Left Adjust bit in Control B register (CTRLB.LEFTADJ) change the data to DATA[15:6] and the dithering bits to DATA[5:2]. Refer to 43.8.8 DATA description for further details. Following timing diagram shows examples with DATA[15:0] = 0x1210 then DATA[15:0] = 0x12E0 and CTRLB.LEFTADJ=1. Figure 43-2. DAC Conversions in Dithering Mode (CTRLB.LEFTADJ=1) DATA [15:0] 0x1300 0x12C0 0x1240 0x1200 0x1210 0x12E0 VOUT0 sub-conversion 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1077 43.7 Register Summary Offset Name Bit Pos. 0x00 CTRLA 7:0 RUNSTDBY ENABLE SWRST 0x01 CTRLB 7:0 REFSEL[1:0] DITHER VPD LEFTADJ IOEN EOEN 0x02 EVCTRL 7:0 INVEI EMPTYEO STARTEI 0x03 Reserved 0x04 INTENCLR 7:0 EMPTY UNDERRUN 0x05 INTENSET 7:0 EMPTY UNDERRUN 0x06 INTFLAG 7:0 EMPTY UNDERRUN 0x07 STATUS 7:0 READY 0x08 DATA 7:0 DATA[7:0] 15:8 DATA[15:8] 0x0A ... 0x0B Reserved 0x0C DATABUF 7:0 DATABUF[7:0] 15:8 DATABUF[15:8] 0x0E ... 0x0F Reserved 0x10 SYNCBUSY 7:0 DATABUF DATA ENABLE SWRST 15:8 23:16 31:24 0x14 ... 0x17 Reserved 0x18 DBGCTRL 7:0 DBGRUN 43.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to 43.5.8 Register Access Protection. Some registers are synchronized when read and/or written. Synchronization is denoted by the "WriteSynchronized" or the "Read-Synchronized" property in each individual register description. For details, refer to 43.6.7 Synchronization. Some registers are enable-protected, meaning they can only be written when the peripheral is disabled. Enable-protection is denoted by the "Enable-Protected" property in each individual register description. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1078 • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1079 43.8.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00 Property:  PAC Write-Protection, Write-Synchronized Bit 7 6 5 4 3 2 1 0 RUNSTDBY ENABLE SWRST Access R/W R/W R/W Reset 0 0 0 Bit 6 – RUNSTDBY Run in Standby This bit is not synchronized Value Description 0 The DAC output buffer is disabled in standby sleep mode. 1 The DAC output buffer can be enabled in standby sleep mode. Bit 1 – ENABLE Enable DAC Controller Due to synchronization there is delay from writing CTRLA.ENABLE until the peripheral is enabled/ disabled. The value written to CTRLA.ENABLE will read back immediately and the corresponding bit in the Synchronization Busy register (SYNCBUSY.ENABLE) will be set. SYNCBUSY.ENABLE will be cleared when the operation is complete. Value Description 0 The peripheral is disabled or being disabled. 1 The peripheral is enabled or being enabled. Bit 0 – SWRST Software Reset Writing '0' to this bit has no effect. Writing '1' to this bit resets all registers in the DAC to their initial state, and the DAC will be disabled. Writing a '1' to CTRLA.SWRST will always take precedence, meaning that all other writes in the same write-operation will be discarded. Due to synchronization there is a delay from writing CTRLA.SWRST until the reset is complete. CTRLA.SWRST and SYNCBUSY.SWRST will both be cleared when the reset is complete. Value Description 0 There is no reset operation ongoing. 1 The reset operation is ongoing. SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1080 43.8.2 Control B Name:  CTRLB Offset:  0x01 Reset:  0x00 Property:  PAC Write-Protection, Enable-Protected Bit 7 6 5 4 3 2 1 0 REFSEL[1:0] DITHER VPD LEFTADJ IOEN EOEN Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bits 7:6 – REFSEL[1:0] Reference Selection This bit field selects the Reference Voltage for the DAC. Important:  For the SAM L10/L11 devices, the 1.1V voltage reference typical value must be selected in case of an internal voltage reference (INTREF). Refer to the Supply Controller VREF register. Value Name Description 0x0 INTREF Internal voltage reference 0x1 VDDANA Analog voltage supply 0x2 VREFA External reference 0x3 Reserved Bit 5 – DITHER Dithering Mode This bit controls dithering operation according to 43.6.8.4 Dithering mode. Value Description 0 Dithering mode is disabled. 1 Dithering mode is enabled. Bit 3 – VPD Voltage Pump Disabled This bit controls the behavior of the voltage pump. Value Description 0 Voltage pump is turned on/off automatically 1 Voltage pump is disabled. Bit 2 – LEFTADJ Left-Adjusted Data This bit controls how the 10-bit conversion data is adjusted in the Data and Data Buffer registers. Value Description 0 DATA and DATABUF registers are right-adjusted. 1 DATA and DATABUF registers are left-adjusted. Bit 1 – IOEN Internal Output Enable SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1081 Value Description 0 Internal DAC output not enabled. 1 Internal DAC output enabled to be used by the AC or ADC. Bit 0 – EOEN External Output Enable Value Description 0 The DAC output is turned off. 1 The high-drive output buffer drives the DAC output to the VOUT pin. SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1082 43.8.3 Event Control Name:  EVCTRL Offset:  0x02 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 INVEI EMPTYEO STARTEI Access R/W R/W R/W Reset 0 0 0 Bit 2 – INVEI Enable Inversion Data Buffer Empty Event Output This bit defines the edge detection of the input event for STARTEI. Value Description 0 Rising edge. 1 Falling edge. Bit 1 – EMPTYEO Data Buffer Empty Event Output This bit indicates whether or not the Data Buffer Empty event is enabled and will be generated when the Data Buffer register is empty. Value Description 0 Data Buffer Empty event is disabled and will not be generated. 1 Data Buffer Empty event is enabled and will be generated. Bit 0 – STARTEI Start Conversion Event Input This bit indicates whether or not the Start Conversion event is enabled and data are loaded from the Data Buffer register to the Data register upon event reception. Value Description 0 A new conversion will not be triggered on any incoming event. 1 A new conversion will be triggered on any incoming event. SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1083 43.8.4 Interrupt Enable Clear Name:  INTENCLR Offset:  0x04 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Set register (INTENSET). Bit 7 6 5 4 3 2 1 0 EMPTY UNDERRUN Access R/W R/W Reset 0 0 Bit 1 – EMPTY Data Buffer Empty Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Data Buffer Empty Interrupt Enable bit, which disables the Data Buffer Empty interrupt. Value Description 0 The Data Buffer Empty interrupt is disabled. 1 The Data Buffer Empty interrupt is enabled. Bit 0 – UNDERRUN Underrun Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Data Buffer Underrun Interrupt Enable bit, which disables the Data Buffer Underrun interrupt. Value Description 0 The Data Buffer Underrun interrupt is disabled. 1 The Data Buffer Underrun interrupt is enabled. SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1084 43.8.5 Interrupt Enable Set Name:  INTENSET Offset:  0x05 Reset:  0x00 Property:  PAC Write-Protection This register allows the user to disable an interrupt without doing a read-modify-write operation. Changes in this register will also be reflected in the Interrupt Enable Clear register (INTENCLR). Bit 7 6 5 4 3 2 1 0 EMPTY UNDERRUN Access R/W R/W Reset 0 0 Bit 1 – EMPTY Data Buffer Empty Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Data Buffer Empty Interrupt Enable bit, which enables the Data Buffer Empty interrupt. Value Description 0 The Data Buffer Empty interrupt is disabled. 1 The Data Buffer Empty interrupt is enabled. Bit 0 – UNDERRUN Underrun Interrupt Enable Writing a '0' to this bit has no effect. Writing a '1' to this bit will set the Data Buffer Underrun Interrupt Enable bit, which enables the Data Buffer Underrun interrupt. Value Description 0 The Data Buffer Underrun interrupt is disabled. 1 The Data Buffer Underrun interrupt is enabled. SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1085 43.8.6 Interrupt Flag Status and Clear Name:  INTFLAG Offset:  0x06 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 EMPTY UNDERRUN Access R/W R/W Reset 0 0 Bit 1 – EMPTY Data Buffer Empty This flag is cleared by writing a '1' to it or by writing new data to DATABUF. This flag is set when data is transferred from DATABUF to DATA, and the DAC is ready to receive new data in DATABUF, and will generate an interrupt request if INTENCLR/SET.EMPTY is one. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Data Buffer Empty interrupt flag. Bit 0 – UNDERRUN Underrun This flag is cleared by writing a '1' to it. This flag is set when a start conversion event occurs when DATABUF is empty, and will generate an interrupt request if INTENCLR/SET.UNDERRUN is one. Writing a '0' to this bit has no effect. Writing a '1' to this bit will clear the Underrun interrupt flag. SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1086 43.8.7 Status Name:  STATUS Offset:  0x07 Reset:  0x00 Property:  - Bit 7 6 5 4 3 2 1 0 READY Access R Reset 0 Bit 0 – READY DAC Ready Value Description 0 DAC is not ready for conversion. 1 Startup time has elapsed, DAC is ready for conversion. SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1087 43.8.8 Data DAC Name:  DATA Offset:  0x08 Reset:  0x0000 Property:  PAC Write-Protection, Write-Synchronized Bit 15 14 13 12 11 10 9 8 DATA[15:8] Access W W W W W W W W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DATA[7:0] Access W W W W W W W W Reset 0 0 0 0 0 0 0 0 Bits 15:0 – DATA[15:0] Data value to be converted DATA register contains the 10-bit value that is converted to a voltage by the DAC. The adjustment of these 10 bits within the 16-bit register is controlled by CTRLB.LEFTADJ. Four additional bits are also used for the dithering feature according to 43.6.8.4 Dithering mode. Table 43-1. Valid Data Bits CTRLB.DITHER CTRLB.LEFTADJ DATA Description 0 0 DATA[9:0] Right adjusted, 10-bits 0 1 DATA[15:6] Left adjusted, 10-bits 1 0 DATA[13:4], DATA[3:0] Right adjusted, 14-bits 1 1 DATA[15:6], DATA[5:2] Left adjusted, 14-bits SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1088 43.8.9 Data Buffer Name:  DATABUF Offset:  0x0C Reset:  0x0000 Property:  Write-Synchronized Bit 15 14 13 12 11 10 9 8 DATABUF[15:8] Access W W W W W W W W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 DATABUF[7:0] Access W W W W W W W W Reset 0 0 0 0 0 0 0 0 Bits 15:0 – DATABUF[15:0] Data Buffer DATABUF contains the value to be transferred into DATA register. SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1089 43.8.10 Synchronization Busy Name:  SYNCBUSY Offset:  0x10 Reset:  0x00000000 Property:  - Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 Access Reset Bit 15 14 13 12 11 10 9 8 Access Reset Bit 7 6 5 4 3 2 1 0 DATABUF DATA ENABLE SWRST Access R R R R Reset 0 0 0 0 Bit 3 – DATABUF Data Buffer DAC0 This bit is set when DATABUF register is written. This bit is cleared when DATABUF synchronization is completed. Value Description 0 No ongoing synchronized access. 1 Synchronized access is ongoing. Bit 2 – DATA Data This bit is set when DATA register is written. This bit is cleared when DATA synchronization is completed. Value Description 0 No ongoing synchronized access. 1 Synchronized access is ongoing. Bit 1 – ENABLE DAC Enable Status This bit is set when CTRLA.ENABLE bit is written. This bit is cleared when CTRLA.ENABLE synchronization is completed. SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1090 Value Description 0 No ongoing synchronization. 1 Synchronization is ongoing. Bit 0 – SWRST Software Reset This bit is set when CTRLA.SWRST bit is written. This bit is cleared when CTRLA.SWRST synchronization is completed. Value Description 0 No ongoing synchronization. 1 Synchronization is ongoing. SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1091 43.8.11 Debug Control Name:  DBGCTRL Offset:  0x18 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 DBGRUN Access Reset 0 Bit 0 – DBGRUN Debug Run This bit is not reset by a software reset. This bits controls the functionality when the CPU is halted by an external debugger. Value Description 0 The DAC is halted when the CPU is halted by an external debugger. Any ongoing conversion will complete. 1 The DAC continues normal operation when the CPU is halted by an external debugger. SAM L10/L11 Family DAC – Digital-to-Analog Converter © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1092 44. OPAMP – Operational Amplifier Controller 44.1 Overview The Operational Amplifier (OPAMP) Controller configures and controls three low power, general purpose operational amplifiers offering a high degree of flexibility and rail-to-rail inputs. Most common inverting or non-inverting programmable gain and hysteresis configurations can be selected by software - no external components are required for these configurations. The OPAMPs can be cascaded for both standalone mode and built-in configurations. Each OPAMP can be used as a standalone amplifier. External pins are available for filter configurations or other applications. A reference can be generated from the DAC to be used as selectable reference for inverting PGA (programmable gain amplifier) or instrumentation amplifier. Each OPAMP can be used as buffer or PGA for the ADC or an AC. The OPAMP offset voltage can be compensated when it is used in combination with the ADC. Four modes are available to select the trade-off between speed and power consumption to best fit the application requirements and optimize the power consumption. 44.2 Features • Three individually configurable low power OPAMPs • Rail-to-rail inputs • Configurable resistor ladders for internal feedback • Selectable configurations – Standalone OPAMP with flexible inputs – Unity gain amplifier – Non-inverting / inverting Programmable Gain Amplifier (PGA) – Cascaded PGAs – Instrumentation amplifier – Comparator with programmable hysteresis • OPAMP output: – On I/O pins – As input for AC or ADC • Flexible input selection: – I/O pins – DAC – Ground • Low power options: – Selectable voltage doubler and propagation delay versus current consumption – On demand start-up for ADC and AC operations • Offset/Gain measurement for calibration when used with the ADC SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1093 44.3 Block Diagram Figure 44-1. OPAMP Block Diagram OPAMP0 OA0POS OA0TAP DAC/ REFBUF GND OA0OUT ADC OA0NEG OA0TAP OA0POS OA0NEG DAC/REFBUF GND VDDANA CTRLA STATUS UG OPAMP1 GND OA0OUT OA1TAP OA1POS OA1OUT OA1NEG OA1TAP OA1POS OA1NEG OA0OUT GND CTRLA STATUS UG OPAMP2 GND OA1OUT OA1POS OA0TAP OA2OUT OA2NEG OA2TAP OA2POS OA2NEG OA1OUT GND CTRLA STATUS UG OA2POS OA2TAP OA0NEG OA1NEG R2 R1 R2 R1 R2 R1 + - + - + - Voltage Doubler CTRLA.LPMUX CLK_ULP32K VDDANA VDOUBLER* GND VDDANA GND VDDANA GND VDDANA *: VDOUBLER supplies all muxes OPAMPCTRL0.MUXNEG OPAMPCTRL0.MUXPOS OPAMPCTRL0.RES1MUX OPAMPCTRL0.POTMUX OPAMPCTRL0.RES2OUT OPAMPCTRL0.ANAOUT OPAMPCTRL0.RES2VCC ADC/AC OPAMPCTRL2.ANAOUT VDDANA OPAMPCTRL2.RES2VCC OPAMPCTRL2.RES1MUX OPAMPCTRL2.POTMUX OPAMPCTRL2.RES2OUT OPAMPCTRL2.MUXPOS OPAMPCTRL2.MUXNEG OPAMPCTRL1.MUXPOS OPAMPCTRL1.MUXNEG OPAMPCTRL1.POTMUX OPAMPCTRL1.RES2OUT OPAMPCTRL1.RES1MUX ADC OPAMPCTRL1.ANAOUT VDDANA OPAMPCTRL1.RES2VCC OPAMPCTRL0.RES1EN OPAMPCTRL1.RES1EN OPAMPCTRL2.RES1EN R2 R1 RESCTRL.RES1MUX RESCTRL.POTMUX RESCTRL.RES2OUT RESCTRL.RES1EN REFBUF DAC DAC/ REFBUF Rg_CONN DAC/ REFBUF DAC/ REFBUF Rg_CONN OA0OUT DAC/REFBUF OA0POS RES3TAP DAC/REFBUF RES3TAP OPAMPCTRLx.ENABLE DAC/REFBUF 44.4 Signal Description Signal Description Type OA0POS OPAMP0 positive input Analog input OA0NEG OPAMP0 negative input Analog input OA1POS OPAMP1 positive input Analog input SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1094 Signal Description Type OA1NEG OPAMP1 negative input Analog input OA2POS OPAMP2 positive input Analog input OA2NEG OPAMP2 negative input Analog input OA0OUT OPAMP0 output Analog output OA1OUT OPAMP1 output Analog output OA2OUT OPAMP2 output Analog output One signal can be mapped on several pins. Important:  When an analog peripheral is enabled, the analog output of the peripheral will interfere with the alternative functions of the output pads. This is also true even when the peripheral is used for internal purposes. Analog inputs do not interfere with alternative pad functions. 44.5 Product Dependencies In order to use this peripheral, other parts of the system must be configured correctly, as described below. 44.5.1 I/O Lines Using the OPAMP I/O lines requires the I/O pins to be configured. Refer to the PORT - I/O Pin Controller chapter for details. 44.5.2 Power Management The OPAMP can operate in idle and standby sleep mode, according to the settings of the Run in Standby and On Demand bits in the OPAMP Control x registers (OPAMPCTRLx.RUNSTDBY and OPAMPCTRLx.ONDEMAND), as well as the Enable bit in the Control A register (CTRLA.ENABLE). Refer to PM – Power Manager for details on the different sleep modes. Related Links 22. PM – Power Manager 44.5.3 Clocks The OPAMP bus clock (CLK_OPAMP_APB) can be enabled and disabled in the Power Manager, and the default state of CLK_OPAMP_APB can be found in the Peripheral Clock Masking. A clock (CLK_ULP32K) is required by the voltage doubler for low voltage operation (VCC < 2.5V). The CLK_ULP32K is a 32KHz clock which is provided by the OSCULP32K oscillator in the OSC32KCTRL module. Related Links 19.6.2.6 Peripheral Clock Masking 44.5.4 DMA Not applicable. SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1095 44.5.5 Interrupts Not applicable. 44.5.6 Events Not applicable. 44.5.7 Debug Operation When the CPU is halted in debug mode the OPAMP continues normal operation. If the OPAMP 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. 44.5.8 Register Access Protection All registers with write-access can be write-protected optionally by the peripheral access controller (PAC). Refer to PAC - Peripheral Access Controller for details. Optional write-protection by the Peripheral Access Controller (PAC) is denoted by the "PAC WriteProtection" property in each individual register description. PAC write-protection does not apply to accesses through an external debugger. Related Links 15. PAC - Peripheral Access Controller 44.5.9 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. 44.5.10 Analog Connections Each OPAMP has two I/O pins that can be used as analog inputs. These pins must be configured for analog operation before using them as OPAMP inputs. If the DAC is to be used as OPAMP input, the DAC must be configured and enabled first. Each OPAMP has one I/O pin that can be used as analog output. This pin must be configured for analog operation before using it as OPAMP output. The analog signals of AC, ADC, DAC and OPAMP can be interconnected. The AC and ADC peripheral can request the OPAMP using an analog ONDEMAND functionality. See Analog Connections of Peripherals for details. 44.5.11 Other dependencies Not applicable. SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1096 44.6 Functional Description 44.6.1 Principle of Operation Each OPAMP has one positive and one negative input. Each input may be chosen from either a selection of analog input pins, or internal inputs such as the DAC, the resistor ladder, and the ground and output of another OPAMP. Each OPAMP can be configured with built-in feedback to support various functions with programmable or unity gain. I/O pins are externally accessible so that the operational amplifier can be configured with external feedback. All OPAMPs can be cascaded to support circuits such as differential amplifiers. 44.6.2 Basic Operation Each operational amplifier can be configured in different modes, selected by the OPAMP Control x register (OPAMPCTRLx): • Standalone operational amplifier • Operational amplifier with built-in feedback After being enabled, a start-up delay is added before the output of the operational amplifier is available. This start-up time is measured internally to account for environmental changes such as temperature or voltage supply level. When the OPAMP is ready, the respective Ready x bit in the Status register is set (STATUS.READYx=1). If the supply voltage is below 2.5V, the start-up time is also dependent on the voltage doubler. If the supply voltage is always above 2.5V, the voltage doubler can be disabled by setting the Low-Power Mux bit in the Control A Register (CTRLA.LPMUX). 44.6.2.1 Initialization The OPAMP must be configured with the desired properties and inputs before it is enabled. The asynchronous clocks CLK_ULP32K must be configured in the OSC32KCTRL module before enabling individual OPAMPs. See OSC32KCTRL – 32KHz Oscillators Controller for further details. Related Links 24. OSC32KCTRL – 32KHz Oscillators Controller 44.6.2.2 Enabling, Disabling, and Resetting The OPAMP is enabled by writing a '1' to the Enable bit in the Control A register (CTRLA.ENABLE). The OPAMP is disabled by writing a '0' to CTRLA.ENABLE. Each OPAMP sub-module is enabled by writing a '1' to the Enable bit in the OPAMP Control x register (OPAMPCTRLx.ENABLE). Each OPAMP sub-module is disabled by writing a '0' to OPAMPCTRLx.ENABLE. The OPAMP module is reset by writing a '1' to the Software Reset bit in the Control A register (CTRLA.SWRST). All registers in the OPAMP will be reset to their initial state, and the OPAMP will be disabled. Refer to 44.8.1 CTRLA for details. 44.6.3 DMA Operation Not applicable. SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1097 44.6.4 Interrupts Not applicable. 44.6.5 Events Not applicable. 44.6.6 Sleep Mode Operation The OPAMPs can also be used during sleep modes. The 32KHz clock source used by the voltage doubler must remain active. See Voltage Doubler for more details. Each OPAMP x can be configured to behave differently in different sleep modes. The behavior is determined by the individual Run in Standby and On Demand bits in the OPAMP Control x registers (OPAMPCTRLx.RUNSTDBY, and OPAMPCTRLx.ONDEMAND), as well as the common Enable bit in the Control A register (CTRLA.ENABLE). Table 44-1. Individual OPAMP Sleep Mode Operation OPAMPCTRLx.RUNSTDBY OPAMPCTRLx.ONDEMAND CTRLA.ENABLE Sleep Behavior - - 0 Disabled 0 0 1 Always run in all sleep modes except STANDBY sleep mode 0 1 1 Only run in all sleep modes except STANDBY sleep mode if requested by a peripheral. 1 0 1 Always run in all sleep mode 1 1 1 Only run in all sleep modes if requested by a peripheral. Note:  When OPAMPCTRLx.ONDEMAND=1, the analog block is powered off for the lowest power consumption if it is not requested. When requested, a start-up time delay is necessary when the system returns from sleep. The start-up time is depending on the Bias Selection bits in the OPAMP Control x register (OPAMPCTRLx.BIAS) and the corresponding speed/current consumption requirements. 44.6.7 Synchronization Not applicable. 44.6.8 Configuring the Operational Amplifiers Each individual operational amplifier is configured by its respective Operational Amplifier Control x register (OPAMPCTRLx). These settings must be configured before the amplifier is started. • Select the positive input in OPAMPCTRLx.MUXPOS • Select the negative input in OPAMPCTRLx.MUXNEG • Select RES1EN if resistor ladder is used • Select the input for the resistor ladder in OPAMPCTRLx.RES1MUX • Select the potentiometer selection of the resistor ladder in OPAMPCTRLx.POTMUX • Select the VCC input for the resistor ladder in OPAMPCTRLx.RES2VCC • Connect the operational amplifier output to the resistor ladder using OPAMPCTRLx.RES2OUT • Select the trade-off between speed and energy consumption in OPAMPCTRLx.BIAS SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1098 • Select RES3TAP as positive input for the OPAMP2 and connect the resistor ladder to OA0OUT by setting the RESCTRL.RES2OUT bit only if OPAMPs are configured as a High Gain Instrumentation Amplifier 44.6.9 Standalone Mode Each operational amplifier can be used as standalone amplifier. In this mode, positive input, negative input and the output are routed from/to external I/Os, requiring external feedback. OPAMPs can also be cascaded to support multiple OPAMP configurations. Refer to Operational Amplifier Control x register (OPAMPCTRLx) for further details on how to configure OPAMP I/Os. 44.6.10 Built-in Modes 44.6.10.1 Voltage Follower In this mode the unity gain path is selected for the negative input. The OPAMPCTRLx register can be configured as follows: Table 44-2. Configuration - Three Independent Unitary Gain Followers MUXPOS MUXNEG RES1MUX POTMUX RES2VCC RES2OUT RES1EN ANAOUT OPAMP0 0000 011 011 000 0 0 0 0 OPAMP1 0000 011 011 000 0 0 0 0 OPAMP2 0000 011 011 000 0 0 0 0 Figure 44-2. Voltage follower OPAMP0 Vin Vout + - 44.6.10.2 Inverting PGA For inverting programmable gain amplifier operation, the OPAMPCTRLx registers can be configured as follows: Table 44-3. Configuration - Three Independent Inverting PGAs MUXPOS MUXNEG RES1MUX POTMUX RES2VCC RES2OUT RES1EN ANAOUT OPAMP0 0010 001 001 100 0 1 1 0 OPAMP1 0010 001 001 100 0 1 1 0 OPAMP2 0010 001 001 100 0 1 1 0 Inverting PGA (Example: Vout=-3.Vin, R1=4R, R2=12R) SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1099 Figure 44-3. Inverting PGA OPAMP0 Vin Vout DAC/REFBUF Vout = -(Vin-Ref)R2/R1 + Ref + - R2 R1 44.6.10.3 Non-Inverting PGA For non-inverting programmable gain amplifier operation, the OPAMPCTRLx registers can be configured as follows: Table 44-4. Configuration - Three Independent Non-Inverting PGAs (Example: Vout=4.Vin, R1=4R, R2=12R) MUXPOS MUXNEG RES1MUX POTMUX RES2VCC RES2OUT RES1EN ANAOUT OPAMP0 000 001 11 100 0 1 1 0 OPAMP1 000 001 11 100 0 1 1 0 OPAMP2 000 001 11 100 0 1 1 0 Figure 44-4. Non-Inverting PGA OPAMP0 Vout R1 R2 Vin Vout = Vin(1+R2/R1) 44.6.10.4 Cascaded Inverting PGA The OPAMPs can be configured as three cascaded, inverting PGAs using these settings in OPAMPCTRLx: Table 44-5. Cascade of three inverting PGAs (Example: R1=4R, R2=12R) MUXPOS MUXNEG RES1MUX POTMUX RES2VCC RES2OUT RES1EN ANAOUT OPAMP0 0010 001 001 100 0 1 1 0 OPAMP1 0010 001 010 100 0 1 1 0 OPAMP2 0010 001 010 100 0 1 1 0 SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1100 Figure 44-5. Cascaded Inverting PGA OPAMP0 Vref Vout R1 R2 OPAMP1 R1 R2 OPAMP2 R1 R2 Vin OA0OUT = -(Vin-Vref)R2/R1 + Vref OA1OUT = -(OA0OUT-Vref)R2/R1 + Vref OA2OUT = -(OA1OUT-Vref)R2/R1 + Vref + - + - + Vref - Vref Vref = DAC/REFBUF 44.6.10.5 Cascaded Non-Inverting PGA The OPAMPs can be configured as three cascaded, non-inverting PGAs using these settings in OPAMPCTRLx: Table 44-6. Cascaded Non-Inverting PGA (Exemple: R1=4R, R2=12R) MUXPOS MUXNEG RES1MUX POTMUX RES2VCC RES2OUT RES1EN ANAOUT OPAMP0 0000 001 011 100 0 1 1 0 OPAMP1 0100 001 011 100 0 1 1 0 OPAMP2 0100 001 011 100 0 1 1 0 Figure 44-6. Cascaded Non-Inverting PGA OPAMP0 Vout R1 R2 OPAMP1 R1 R2 OPAMP2 R1 R2 Vin OA0OUT = Vin(1+R2/R1) OA1OUT = OA0OUT(1+R2/R1) OA2OUT = OA1OUT(1+R2/R1) 44.6.10.6 Two OPAMPs Differential Amplifier In this mode, OPAMP0 can be coupled with OPAMP1 or OPAMP1 with OPAMP2 in order to amplify a differential signal. To configure OPAMP0 and OPAMP1 as differential amplifier, the OPAMPCTRLx register can be configured as follows: SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1101 Table 44-7. OPAMP0 OPAMP1 Differential Amplifier (Example: R1=4R, R2=12R) MUXPOS MUXNEG RES1MUX POTMUX RES2VCC RES2OUT RES1EN ANAOUT OPAMP0 0000 011 011 000 0 0 0 0 OPAMP1 0000 001 010 100 0 1 1 0 OPAMP2 0000 000 000 000 0 0 0 0 To configure OPAMP1 and OPAMP2 as differential amplifier, the OPAMPCTRLx register can be configured as follows: Table 44-8. OPAMP1 OPAMP2 Differential Amplifier (Example: R1=4R, R2=12R) MUXPOS MUXNEG RES1MUX POTMUX RES2VCC RES2OUT RES1EN ANAOUT OPAMP0 0000 000 000 000 0 0 0 0 OPAMP1 0000 011 011 000 0 0 0 0 OPAMP2 0000 001 010 100 0 1 1 0 Figure 44-7. OPAMP0 OPAMP1 Differential Amplifier OPAMP0 OPAMP1 Vout = (1+ R2/R1)V2 - V1(R2/R1) R1 R2 V1 V2 + - + - 44.6.10.7 Instrumentation Amplifier In this mode, OPAMP0 and OPAMP1 are configured as voltage followers. The OPAMPCTRLx register can be configured as follows: Table 44-9. Instrumentation Amplifier Configuration MUXPOS MUXNEG RES1MUX POTMUX RES2VCC RES2OUT RES1EN ANAOUT OPAMP0 0000 011 010 010 0 1 1 0 OPAMP1 0000 011 011 000 0 0 0 0 OPAMP2 0111 001 010 010 0 1 1 0 The resistor ladders associated with OPAMP0 and OPAMP2 must be configured as follows in order to select the appropriate gain: SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1102 Table 44-10. Instrumentation Amplifier Gain Selection OPAMPCTRL0.POTMUX OPAMPCTRL2.POTMUX GAIN 0x7 Reserved Reserved 0x6 0x0 1/7 0x5 Reserved Reserved 0x4 0x1 1/3 0x3 Reserved Reserved 0x2 0x2 1 0x1 0x4 3 0x0 0x6 7 Note:  Either the DAC or GND must be the reference, selected by the OPAMPCTRL0.RES1MUX bits. Refer to the OPAMP Control 'x' register (44.8.3 OPAMPCTRL) for details. Figure 44-8. Instrumentation amplifier OPAMP1 Vout = (V2-V1).Gain + Vref OPAMP2 V1 V2 OPAMP0 Vref = DAC/REFBUF R1 R1 R2 R2 44.6.10.8 High Gain Instrumentation Amplifier In this mode, OPAMP0 and OPAMP1 are configured as non inverting amplifiers [Stage 1]. OPAMP2 is configured as difference amplifier[Stage 2]. Total gain of the instrumentation amplifier is product of gains of stage 1 and stage 2. The OPAMPCTRLx and RESCTRL registers can be configured as follows: SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1103 Table 44-11. Instrumentation Amplifier Configuration MUXPOS MUXNEG RES1MUX POTMUX RES2VCC RES2OUT RES1EN ANAOUT OPAMP0 0000 001 100 111 0 1 1 0 OPAMP1 0000 001 100 111 0 1 1 0 OPAMP2 1000 001 010 111 0 1 1 0 Table 44-12. Resister Control Configuration RES1MUX POTMUX RES2OUT RES1EN 0 (DAC) 111 1 1 1 (REFBUF) 111 1 1 The resistor ladders associated with OPAMP0, OPAMP1, OPAMP2 and RESCTRL must be configured as follows in order to select the appropriate gain: Table 44-13. Instrumentation Amplifier Gain Selection OPAMPCTRL0.POTMUX OPAMPCTRL1.POTMUX STAGE 1 GAIN OPAMPCTRL2.POTMUX RESCTRL1.POTMUX STAGE 2 GAIN 0x7 0x7 16 0x7 0x7 15 0x6 0x6 8 0x6 0x6 7 0x5 0x5 5 + 1/3 0x5 0x5 4 + 1/3 0x4 0x4 4 0x4 0x4 3 0x3 0x3 2 + 2/3 0x3 0x3 1 + 2/3 0x2 0x2 2 0x2 0x2 1 0x1 0x1 1 + 1/3 0x1 0x1 1/3 0x0 0x0 1 + 1/7 0x0 0x0 1/7 The RES3TAP potentiometer can be selected as a positive input for the OPAMP2 and the resistor ladder can be connected to OA0OUT by setting the RESCTRL.RES2OUT bit in order to configure OPAMPs as a High Gain Instrumentation Amplifier. SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1104 Figure 44-9. High Gain Instrumentation amplifier OPAMP0 Vout = (Vinp-Vinn)(1+R5/Rg)(R2/R1)+Vref OPAMP2 Vinn OPAMP1 Vref = DAC/REFBUF + - Rg_conn Rg/2 R5 R1 Rg/2 R6 R3 R4 R2 Vinp Vref Vout 44.6.10.9 Transimpedance amplifier Each OPAMP can be configured as a transimpedance amplifier (current to voltage converter). In this mode the positive input is connected to ground. The negative input is connected to the output through the resistor ladder. The OPAMPCTRLx register can be configured as follows: Table 44-14. Transimpedance Amplifier MUXPOS MUXNEG RES1MUX POTMUX RES2VCC RES2OUT RES1EN ANAOUT OPAMP0 0010 000 001 000 0 1 1 0 OPAMP1 0010 000 001 000 0 1 1 0 OPAMP2 0010 000 001 000 0 1 1 0 SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1105 Figure 44-10. Transimpedance Amplifier OPAMPn Vref = DAC/REFBUF R1 R2 Iin + - Vout = -Iin(R1+R2) 44.6.10.10 Programmable Hysteresis OPAMP can be configured as an inverting or non-inverting comparator with programmable hysteresis. Applying hysteresis will prevent constant toggling of the output, caused by noise when the input signals are close to each other. In both inverting and non-inverting comparator configurations the positive input is connected to the resistor ladder. When OPAMP is configured as an inverting comparator with programmable hysteresis, the input voltage must be applied to the negative input and RES1MUX must be connected to the ground. When an OPAMP is configured as a non-inverting comparator with programmable hysteresis, the input voltage must be applied to RES1MUX and the negative input must be connected to the ground. To configure an OPAMP as an inverting comparator with programmable hysteresis, the OPAMPCTRLx register can be configured as follows: Table 44-15. Configuration of Input Multiplexes for OPAMP0 (Example: Vth = 3/4*Vcc, Ref = GND) MUXPOS MUXNEG RES1MUX POTMUX RES2VCC RES2OUT RES1EN ANAOUT OPAMP0 0001 000 010 001 0 1 1 0 Table 44-16. POTMUX [2:0]: Potentiometer Selection Value R1 R2 Threshold = Vcc * R1 / (R1 + R2) 0x0 14R 2R 7/8 * Vcc 0x1 12R 4R 3/4 * Vcc 0x2 8R 8R 1/2 * Vcc 0x3 6R 10R 3/8 * Vcc 0x4 4R 12R 1/4 * Vcc 0x5 3R 13R 3/16 * Vcc 0x6 2R 14R 1/8 * Vcc 0x7 R 15R 1/16 * Vcc SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1106 Figure 44-11. Inverting comparator with programmable hysteresis OPAMPn Vin Vout Ref R1 R2 Threshold = Vcc*R1/(R1+R2)+Ref + - To configure an OPAMP as a non-inverting comparator with programmable hysteresis, the OPAMPCTRLx register can be configured as follows: Table 44-17. Configuration of Input Multiplexes for OPAMP0 and OPAMP1 (Example: Vth = 1/3*Vcc, Ref = Gnd) MUXPOS MUXNEG RES1MUX POTMUX RES2VCC RES2OUT RES1EN ANAOUT OPAMP0 0001 010 000 100 0 1 1 0 OPAMP1 0001 010 000 100 0 1 1 0 OPAMP2 0001 010 000 100 0 1 1 0 Table 44-18. POTMUX [2:0]: Potentiometer Selection Value R1 R2 Threshold = Vcc * R1 / R2 0x0 14R 2R Vcc * 7 (unused) 0x1 12R 4R Vcc * 3 (unused) 0x2 8R 8R Vcc (unused) 0x3 6R 10R 0.6* Vcc 0x4 4R 12R 1/3 * Vcc 0x5 3R 13R 3/13 *Vcc 0x6 2R 14R 1/7 * Vcc 0x7 R 15R 1/15 * Vcc Figure 44-12. Non-Inverting comparator with programmable hysteresis OPAMPn Vin Vout Ref R1 R2 Threshold = Vcc*R1/R2+Ref + - SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1107 44.6.11 ADC Driver 44.6.11.1 Buffer/PGA for ADC Each OPAMP can be configured as a buffer or a PGA for the other modules (such as ADC or AC). OPAMPs can also be cascaded to increase the programmable gain. The output to the OPAMP must be enabled by writing a '1' to the Analog Output bit in the Operational Amplifier x Control register (OPAMPCTRLx.ANAOUT). The ADC input mux must be configured to select OPAMP as input. Refer to ADC – Analog-to-Digital Converter for details on configuring the ADC. Related Links 41. ADC – Analog-to-Digital Converter 44.6.11.2 Offset and Gain Compensation When the OPAMP is used in combination with the ADC, the OPAMP offset and gain errors can be compensated. To calculate offset and gain error compensation values 1. Configure OPAMP as Voltage Follower 2. Route the OPAMP output to the ADC: – Write a '1' to the Analog Output bit in the Operational Amplifier x Control register (OPAMPCTRLx.ANAOUT) – Select the OPAMP as input for the ADC, see ADC – Analog-to-Digital Converter. 3. Measure and set the Offset Correction value for the ADC OFFSETCORR register as in 44.6.11.3 Offset Compensation. 4. Measure and set the Gain Correction value for the ADC GAINCORR register as in 44.6.11.4 Gain Compensation. The offset error compensation must be determined before gain error compensation. The relation for offset and gain error compensation is shown in this equation: Result = (converted value + OFFSETCORR)*GAINCORR Related Links 41. ADC – Analog-to-Digital Converter 44.6.11.3 Offset Compensation To determine the offset compensation value, the positive input must be tied to ground. The result of the ADC conversion gives directly the offset compensation value that must be written in the ADC OFFSETCORR register. SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1108 Figure 44-13. Offset Compensation OPAMPn ADC RESULT Vref= OFFSETCORR DAC/REFBUF 44.6.11.4 Gain Compensation To perform gain compensation positive input must be close to VDD, but less (e.g. 0.8*Vref for instance) to avoid ADC saturation. The value for gain error compensation is obtained by dividing the theoretical ADC conversion result by the result from measurement. The obtained value for gain error compensation must be written in the ADC GAINCORR register. Figure 44-14. Gain Compensation OPAn ADC RESULT OFFSETCORR 0.8*Vcc RESULTth/RESULT 44.6.12 AC Driver One or several OPAMPs can be configured as input for the AC. The AC input mux must be appropriately configured to select OPAMP as input. Related Links 42. AC – Analog Comparators 44.6.13 Input Connection to DAC The DAC can be used as a reference. This is configured by the corresponding OPAMPCTRLx.MUXPOS and OPAMPCTRLx.RES1MUX bits. 44.6.14 Voltage Doubler The OPAMP peripheral contains a voltage doubler for the analog multiplexer switches to ensure proper operation for a supply voltage below 2.5V. Aside from the multiplexers, no other supply voltages are affected by the voltage doubler. The voltage doubler is normally switched on/off automatically, based on the supply level. If the supply voltage is guaranteed to be above 2.5V, the voltage doubler can be completely disabled by writing the Low-Power Mux bit in the Control Register (CTRLA.LPMUX). SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1109 When enabling OPAMPs, additional start-up time is required for the voltage doubler to settle. Disabling the voltage doubler saves power and reduces the startup time. 44.6.15 Performance vs. Power Consumption It is possible to tradeoff speed versus power efficiency to get the shortest possible propagation delay or the lowest power consumption. The speed setting is configured for each amplifier individually by the Bias Control field in the Operational Amplifier x Control register (OPAMPCTRLx.BIAS). The BIAS bits select the amount of bias current provided to the operational amplifiers. This will also affect the start-up time. SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1110 44.7 Register Summary Offset Name Bit Pos. 0x00 CTRLA 7:0 LPMUX ENABLE SWRST 0x01 Reserved 0x02 STATUS 7:0 READYx READYx READYx 0x03 Reserved 0x04 OPAMPCTRL0 7:0 ONDEMAND RUNSTDBY RES2VCC BIAS[1:0] ANAOUT ENABLE 15:8 POTMUX[2:0] RES1MUX[2:0] RES1EN RES2OUT 23:16 MUXNEG[3:0] MUXPOS[3:0] 31:24 0x08 OPAMPCTRL1 7:0 ONDEMAND RUNSTDBY RES2VCC BIAS[1:0] ANAOUT ENABLE 15:8 POTMUX[2:0] RES1MUX[2:0] RES1EN RES2OUT 23:16 MUXNEG[3:0] MUXPOS[3:0] 31:24 0x0C OPAMPCTRL2 7:0 ONDEMAND RUNSTDBY RES2VCC BIAS[1:0] ANAOUT ENABLE 15:8 POTMUX[2:0] RES1MUX[2:0] RES1EN RES2OUT 23:16 MUXNEG[3:0] MUXPOS[3:0] 31:24 0x10 RESCTRL 7:0 REFBUFLEVEL[1:0] POTMUX[2:0] RES1MUX RES1EN RES2OUT 44.8 Register Description Registers can be 8, 16, or 32 bits wide. Atomic 8-, 16- and 32-bit accesses are supported. In addition, the 8-bit quarters and 16-bit halves of a 32-bit register, and the 8-bit halves of a 16-bit register can be accessed directly. Some registers are optionally write-protected by the Peripheral Access Controller (PAC). Optional PAC write-protection is denoted by the "PAC Write-Protection" property in each individual register description. For details, refer to Register Access Protection. On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered Refer to Peripherals Security Attribution for more information. SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1111 44.8.1 Control A Name:  CTRLA Offset:  0x00 Reset:  0x00 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 LPMUX ENABLE SWRST Access R/W R/W R/W Reset 0 0 0 Bit 7 – LPMUX Low-Power Mux Value Description 0 The analog input muxes have low resistance, but consume more power at lower voltages (e.g., are driven by the voltage doubler). 1 The analog input muxes have high resistance, but consume less power at lower voltages (e.g., the voltage doubler is disabled). Bit 1 – ENABLE Enable Value Description 0 The peripheral is disabled. 1 The peripheral is enabled. Each OPAMP must also be enabled individually by the Enable bit in the corresponding OPAMP Control register (OPAMPCTRLx.ENABLE). Bit 0 – SWRST Software Reset Writing a '0' to this bit has no effect. Writing a '1' to this bit resets all registers in the MODULE to their initial state, and the OPAMP will be disabled. Writing a '1' to CTRLA.SWRST will always take precedence, meaning that all other writes in the same write-operation will be discarded. Value Description 0 There is no reset operation ongoing. 1 The reset operation is ongoing. SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1112 44.8.2 Status Name:  STATUS Offset:  0x02 Reset:  0x00 Property:  – Bit 7 6 5 4 3 2 1 0 READYx READYx READYx Access R R R Reset 0 0 0 Bits 2,1,0 – READYx OPAMP x Ready This bit is set when the OPAMPx output is ready. This bit is cleared when the output of OPAMPx is not ready. SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1113 44.8.3 OPAMP Control x Name:  OPAMPCTRL Offset:  0x04 + n*0x04 [n=0..2] Reset:  0x00000080 Property:  PAC Write-Protection Bit 31 30 29 28 27 26 25 24 Access Reset Bit 23 22 21 20 19 18 17 16 MUXNEG[3:0] MUXPOS[3:0] Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 15 14 13 12 11 10 9 8 POTMUX[2:0] RES1MUX[2:0] RES1EN RES2OUT Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bit 7 6 5 4 3 2 1 0 ONDEMAND RUNSTDBY RES2VCC BIAS[1:0] ANAOUT ENABLE Access R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 Bits 23:20 – MUXNEG[3:0] Negative Input Mux Selection Selection on negative input for operational amplifier x. Value OPAMPx Name Description 0x0 x=0,1,2 OAxNEG OPAMPx Negative Input 0x1 x=0,1,2 OAxTAP OPAMPx Resistor Ladder Taps 0x2 x=0,1,2 REFERENCE REFERENCE[DAC/REFBUF] 0x3 x=0,1,2 OAxOUT 0x4 x=0,1 Reserved x=2 OA0NEG OPAMP0 Negative Input 0x5 x=0,1 Reserved x=2 OA1NEG OPAMP1 Negative Input Bits 19:16 – MUXPOS[3:0] Positive Input Mux Selection Selection on positive input for operational amplifier x. SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1114 Value OPAMPx Name Description 0x0 x=0,1,2 OAxPOS OPAMPx Positive Input 0x1 x=0,1,2 OAxTAP OPAMPx Resistor Ladder Taps 0x2 x=0,1,2 REFERENCE REFERENCE[DAC/REFBUF] 0x3 x=0,1,2 GND Ground 0x4 x=0 Reserved x=1 OA0OUT OPAMP0 output x=2 OA1OUT OPAMP1 output 0x5 x=0,1 Reserved x=2 OA0POS OPAMP0 Positive Input 0x6 x=0,1 Reserved x=2 OA1POS OPAMP1 Positive Input 0x7 x=0,1 Reserved x=2 OA0TAP OPAMP0 Resistor Ladder Taps 0x8 x=0,1 Reserved x=2 RES3TAP Bits 15:13 – POTMUX[2:0] Potentiometer selection Resistor selection bits control a numeric potentiometer with eight fixed values. Value R1 R2 0x0 14R 2R 0x1 12R 4R 0x2 8R 8R 0x3 6R 10R 0x4 4R 12R 0x5 3R 13R 0x6 2R 14R 0x7 R 15R Bits 12:10 – RES1MUX[2:0] Resistor 1 Mux These bits select the connection of R1 resistor of the potentiometer. Value OPAMPx Name Description 0x0 x=0,1,2 OAxPOS OPAMPx Positive Input 0x1 x=0,1,2 OAxNEG OPAMPx Negative Input SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1115 Value OPAMPx Name Description 0x2 x=0 REFERENCE REFERENCE[DAC/REFBUF] x=1 OA0OUT OPAMP0 output x=2 OA1OUT OPAMP1 output 0x3 x=0,1,2 GND 0x4 x=0,1 RG_CONN x=2 Reserved Bit 9 – RES1EN Resistor 1 Enable Value Description 0 R1 disconnected from RES1MUX. 1 R1 connected to RES1MUX. Bit 8 – RES2OUT Resistor ladder To Output Value Description 0 Swith open. 1 Switch closed. Bit 7 – ONDEMAND On Demand Control The On Demand operation mode allows the OPAMPx to be enabled or disabled, depending on other peripheral requests. Value Description 0 The OPAMPx is always on, if enabled. 1 The OPAMPx is enabled when a peripheral is requesting the OPAMPx to be used as an input. The OPAMPx is disabled if no peripheral is requesting it as an input. Bit 6 – RUNSTDBY Run in Standby This bit controls how the OPAMPx behaves during standby sleep mode: Value Description 0 The OPAMPx is disabled in standby sleep mode. 1 The OPAMPx is not stopped in standby sleep mode. If OPAMPCTRLx.ONDEMAND=1, the OPAMPx will be running when a peripheral is requesting it as an input. If OPAMPCTRLx.ONDEMAND=0, OPAMPx will always be running in standby sleep mode. Bit 5 – RES2VCC Resistor ladder To VCC Value Description 0 Swith open. 1 Switch closed. Bits 4:3 – BIAS[1:0] Bias Selection These bits are used to select the bias mode. SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1116 Value Name Description 0x0 Mode 0 Minimum current consumption, but the slowest mode 0x1 Mode 1 Low current consumption, slow speed 0x2 Mode 2 High current consumption, fast speed 0x3 Mode 3 Maximum current consumption but the fastest mode Bit 2 – ANAOUT Analog Output This bit controls a switch connected to the OPAMP output. Value Description 0 Switch open. No ADC or AC connection. 1 Switch closed. OPAMP output is connected to the ADC or AC input. Bit 1 – ENABLE Operational Amplifier Enable Value Description 0 The OPAMPx is disabled 1 The OPAMPx is enabled SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1117 44.8.4 Resistor Control Name:  RESCTRL Offset:  0x10 Reset:  0x0 Property:  PAC Write-Protection Bit 7 6 5 4 3 2 1 0 REFBUFLEVEL[1:0] POTMUX[2:0] RES1MUX RES1EN RES2OUT Access R/W R/W R/W R/W R/W R/W R/W R/W Reset 0 0 0 0 0 0 0 0 Bits 7:6 – REFBUFLEVEL[1:0] Reference output voltage level select Reference output voltage level select. Value Reference Level 0x0 1.1v 0x1 1.25v 0x2 1.6v 0x3 Reserved Bits 5:3 – POTMUX[2:0] Potentiometer selection Resistor selection bits control a numeric potentiometer with eight fixed values. Value R1 R2 0x0 14R 2R 0x1 12R 4R 0x2 8R 8R 0x3 6R 10R 0x4 4R 12R 0x5 3R 13R 0x6 2R 14R 0x7 R 15R Bit 2 – RES1MUX Resistor 1 Mux These bits select the connection of R1 resistor of the potentiometer. Value Name Description 0x0 DAC DACOUT 0x1 REFBUF REFBUF SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1118 Bit 1 – RES1EN Resistor 1 Enable RES1EN = 1 is required in order to provide DAC/REFBUF to POSMUX, NEGMUX and RES1MUX. Value Description 0 R1 disconnected from RES1MUX. 1 R1 connected to RES1MUX. Bit 0 – RES2OUT Resistor ladder To Output RES2OUT switch can only be closed if all OPAMPs are enabled. Value Description 0 Swith open. 1 Switch closed. SAM L10/L11 Family OPAMP – Operational Amplifier Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1119 45. PTC - Peripheral Touch Controller 45.1 Overview The Peripheral Touch Controller (PTC) acquires signals in order to detect touch on capacitive sensors. The external capacitive touch sensor is typically formed on a PCB, and the sensor electrodes are connected to the analog front end of the PTC through the I/O pins in the device. The PTC supports both self- and mutual-capacitance sensors. In mutual-capacitance mode, sensing is done using capacitive touch matrices in various X-Y configurations, including indium tin oxide (ITO) sensor grids. The PTC requires one pin per X-line and one pin per Y-line. In self-capacitance mode, the PTC requires only one pin (Y-line) for each touch sensor. The number of available pins and the assignment of X- and Y-lines is depending on both package type and device configuration. Refer to the Configuration Summary and I/O Multiplexing table for details. Related Links 1. Configuration Summary 45.2 Features • Low-power, high-sensitivity, environmentally robust capacitive touch buttons, sliders, and wheels • Supports wake-up on touch from standby Sleep mode • Supports mutual capacitance and self-capacitance sensing – Mix-and-match mutual-and self-capacitance sensors • One pin per electrode – no external components • Load compensating charge sensing – Parasitic capacitance compensation and adjustable gain for superior sensitivity • Zero drift over the temperature and VDD range – Auto calibration and recalibration of sensors • Single-shot and free-running charge measurement • Hardware noise filtering and noise signal desynchronization for high conducted immunity • Polarity control, allowing Parallel Acquisition (through the QTouch Library) individually controls the polarity of each line • Driven Shield Plus for better noise immunity and moisture tolerance – Any PTC X/Y line can be used for the driven shield – All enabled sensors will be driven at the same potential as the sensor scanned • Selectable channel change delay allows choosing the settling time on a new channel, as required • Acquisition-start triggered by command or through auto-triggering feature • Low CPU utilization through interrupt on acquisition-complete Related Links 1. Configuration Summary SAM L10/L11 Family PTC - Peripheral Touch Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1120 45.3 Block Diagram Figure 45-1. PTC Block Diagram Mutual Capacitance Compensation Circuit Acquisition Module - Gain control - ADC - Filtering RS IRQ Result Y0 Y1 Ym X0 X1 Xn X Line Driver Input Control 10 CX0Y0 CXnYm Note:  For SAM L10/L11 the RS = 100 KΩ. Figure 45-2. PTC Block Diagram Self Capacitance Compensation Circuit Acquisition Module - Gain control - ADC - Filtering RS IRQ Result Y0 Y1 Ym X Line Driver Input Control 10 CY0 CYm Shield Driver Note:  For SAM L10/L11 the RS = 100 KΩ. SAM L10/L11 Family PTC - Peripheral Touch Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1121 45.4 Signal Description Table 45-1. Signal Description for PTC Name Type Description Y[m:0] Analog Y-line (Input/Output) X[n:0] Digital X-line (Output) Note:  The number of X- and Y-lines are device dependent. Refer to Configuration Summary for details. Refer to I/O Multiplexing and Considerations for details on the pin mapping for this peripheral. One signal can be mapped on several pins. Related Links 1. Configuration Summary 45.5 System Dependencies In order to use this peripheral, configure the other components of the system as described in the following sections. 45.5.1 I/O Lines The I/O lines used for analog X-lines and Y-lines must be connected to external capacitive touch sensor electrodes. External components are not required for normal operation. However, to improve the EMC performance, a series resistor of 1kΩ or more can be used on X-lines and Y-lines. 45.5.1.1 Mutual-Capacitance Sensor Arrangement A mutual-capacitance sensor is formed between two I/O lines - an X electrode for transmitting and Y electrode for sensing. The mutual capacitance between the X and Y electrode is measured by the Peripheral Touch Controller. Figure 45-3. Mutual Capacitance Sensor Arrangement PTC Module MCU X0 Xn Y0 Ym X1 Y1 Sensor Capacitance Cx,y Cx0,y0 Cx0,y1 Cx0,ym Cx1,y0 Cx1,y1 Cx1,ym Cxn,y0 Cxn,y1 Cxn,ym PTC Module SAM L10/L11 Family PTC - Peripheral Touch Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1122 45.5.1.2 Self-Capacitance Sensor Arrangement A self-capacitance sensor is connected to a single pin on the Peripheral Touch Controller through the Y electrode for sensing the signal. The sense electrode capacitance is measured by the Peripheral Touch Controller. Figure 45-4. Self-capacitance Sensor Arrangement MCU PTC Module Y0 Y1 Ym Cy0 Cy1 Cym Sensor Capacitance Cy For more information about designing the touch sensor, refer to Buttons, Sliders and Wheels Touch Sensor Design Guide. 45.5.2 Clocks The PTC is clocked by the GCLK_PTC clock. The PTC operates from an asynchronous clock source and the operation is independent of the main system clock and its derivative clocks, such as the peripheral bus clock (CLK_APB). A number of clock sources can be selected as the source for the asynchronous GCLK_PTC. The clock source is selected by configuring the Generic Clock Selection ID in the Generic Clock Control register. For more information about selecting the clock sources, refer to GCLK - Generic Clock Controller. The selected clock must be enabled in the Power Manager, before it can be used by the PTC. By default these clocks are disabled. The frequency range of GCLK_PTC is 400kHz to 4MHz. Related Links 18. GCLK - Generic Clock Controller 22. PM – Power Manager 45.5.3 SAM L11 TrustZone Specific Register Access Protection On SAM L11 devices, this peripheral has different access permissions depending on PAC Security Attribution (Secure or Non-Secure): • If the peripheral is configured as Non-Secure in the PAC: – Secure access and Non-Secure access are granted • If the peripheral is configured as Secure in the PAC: – Secure access is granted – Non-Secure access is discarded (Write is ignored, read 0x0) and a PAC error is triggered SAM L10/L11 Family PTC - Peripheral Touch Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1123 Refer to Peripherals Security Attribution for more information. 45.6 Functional Description In order to access the PTC, the user must use the Atmel Start QTouch Configurator to configure and link the QTouch Library firmware with the application software. QTouch Library can be used to implement buttons, sliders, wheels in a variety of combinations on a single interface. For more information about QTouch Library, refer to the QTouch Library Peripheral Touch Controller User Guide. SAM L10/L11 Family PTC - Peripheral Touch Controller © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1124 46. Electrical Characteristics This section provides an overview of the SAM L10 and SAM L11 electrical characteristics. Specifications for Extended Temperature Devices (-40ºC to +125ºC) that are different from the specifications in this section are provided in 47. 125°C Electrical Characteristics. 46.1 Disclaimer All typical values are measured at T = 25°C unless otherwise specified. All minimum and maximum values are valid across operating temperature and voltage unless otherwise specified. 46.2 Thermal Considerations 46.2.1 Thermal Resistance Data The following table summarizes the thermal resistance data depending on the package. Table 46-1. Thermal Resistance Data Package Type θJA θJC 32-pin TQFP 65.1°C/W 16.3°C/W 32-pin QFN 40.4°C/W 15.8°C/W 24-pin QFN 59.1°C/W 21.1°C/W 24-pin SSOP 76.3°C/W 16.0°C/W 32-pin WLCSP 76.89°C/W 12.15°C/W 46.2.2 Junction Temperature The average chip-junction temperature, TJ , in °C can be obtained from the following: 1. TJ = TA + (PD x θJA) 2. TJ = TA + (PD x (θHEATSINK + θJC)) where: • θJA = Package thermal resistance, Junction-to-ambient (°C/W), see Thermal Resistance Data • θJC = Package thermal resistance, Junction-to-case thermal resistance (°C/W), see Thermal Resistance Data • θHEATSINK = Thermal resistance (°C/W) specification of the external cooling device • PD = Device power consumption (W) • 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. SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1125 46.3 Absolute Maximum Ratings Stresses beyond those listed in the following table 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. Table 46-2. Absolute Maximum Ratings Symbol Description Min. Max. Units VDD Power supply voltage 0 3.8 V IVDD Current into a VDD pin - 46(1) mA IGND Current out of a GND pin - 65(1) mA VPIN Pin voltage with respect to GND and VDD GND-0.6V VDD+0.6V V Tstorage Storage temperature -60 150 °C Note:  1. Maximum source current is 46 mA and maximum sink current is 65 mA per cluster. A cluster is a group of GPIOs. Also note that each VDD\GND pair is connected to two clusters, hence current consumption through the pair will be a sum of the clusters' source/sink currents. CAUTION This device is sensitive to electrostatic discharges (ESD). Improper handling may lead to permanent performance degradation or malfunctioning. Handle the device following best practice ESD protection rules: Be aware that the human body can accumulate charges large enough to impair functionality or destroy the device. 46.4 General Operating Ratings The device must operate within the ratings listed in the following table for all other electrical characteristics and typical characteristics of the device to be valid. Table 46-3. General Operating Conditions Symbol Description Min. Typ. Max. Units VDDIO IO Supply Voltage 1.62 3.3 3.63 V VDDANA Analog supply voltage 1.62 3.3 3.63 V TA Temperature range -40 25 85 °C TJ Junction temperature - - 105 °C SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1126 46.5 Supply Characteristics Table 46-4. Supply Characteristics Symbol Voltage Min. Max. Units VDDIO 1.62 3.63 V VDDANA 1.62 3.63 V Table 46-5. Supply Slew Rates(1) Symbol Fall Rate Rise Rate Units Max. Max. VDDIO 0.05 0.1 V/µs VDDANA 0.05 0.1 V/µs Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. 46.6 Maximum Clock Frequencies Table 46-6. Maximum GCLK Generator Output Frequencies(1) Symbol Description Conditions Fmax Units PL0 PL2 Fgclkgen[0:2] GCLK Generator output Frequency - 24 96 MHz Fgclkgen[3:4] - 12 48 MHz Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. Table 46-7. Maximum Peripheral Clock Frequencies(1) Symbol Description Conditions Fmax. Units PL0 PL2 fCPU CPU clock frequency - 8 32 MHz fAHB AHB clock frequency - 8 32 MHz fAPBA APBA clock frequency - 8 32 MHz fAPBB APBB clock frequency - fAPBC APBC clock frequency - fGCLK_DFLLULP DFLLULP Reference clock frequency - 1 4 MHz SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1127 Symbol Description Conditions Fmax. Units PL0 PL2 fGCLK_DPLL FDPLL96M Reference clock frequency - 2 2 MHz fGCLK_DPLL_32K FDPLL96M 32K clock frequency - 32.7 68 32.7 68 kHz fGCLK_EIC EIC input clock frequency - 12 48 MHz fGCLK_EVSYS_CHANNEL_0 EVSYS channel 0 input clock frequency - 12 48 MHz fGCLK_EVSYS_CHANNEL_1 EVSYS channel 1 input clock frequency - fGCLK_EVSYS_CHANNEL_2 EVSYS channel 2 input clock frequency - fGCLK_EVSYS_CHANNEL_3 EVSYS channel 3 input clock frequency - fGCLK_SERCOM0_SLOW Common SERCOM0 slow input clock frequency - 1 5 MHz fGCLK_SERCOM1_SLOW Common SERCOM1 slow input clock frequency - fGCLK_SERCOM2_SLOW Common SERCOM2 slow input clock frequency - fGCLK_SERCOM0_CORE SERCOM0 input clock frequency - 12 48 MHz fGCLK_SERCOM1_CORE SERCOM1 input clock frequency - fGCLK_SERCOM2_CORE SERCOM2 input clock frequency - fGCLK_TC0 TC0 input clock frequency - 12 48 MHz fGCLK_TC1 TC1 input clock frequency - f GCLK_TC2 TC2 input clock frequency - fGCLK_ADC ADC input clock frequency - 12 48 MHz fGCLK_AC AC digital input clock frequency - fGCLK_DAC DAC input clock frequency - fGCLK_FREQM_MSR FREQM measured clock frequency - fGCLK_FREQM_REF FREQM reference clock frequency - fGCLK_PTC PTC input clock frequency - fGCLK_CCL CCL input clock frequency - fGCLKin External GCLK input clock frequency - Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1128 46.7 Power Consumption The values in this section are measured values of power consumption under the following conditions, except where noted: • Operating Conditions – VDDIO = 3.3V or 1.8V – CPU is running on Flash with required Wait states, as recommended in the NVM Characteristics section – Low-power cache is enabled – BOD33 is disabled – I/Os are configured with digital input trigger disabled (default Reset configuration) • Oscillators – XOSC (crystal oscillator) stopped – XOSC32K (32.768 kHz crystal oscillator) running with external 32.768 kHz crystal – When in Active mode with Performance Level 2 (PL2), DPLL is running at 32 MHz and using XOSC32K as reference – When in Active mode on DFLLULP, the DFLLULP is configured in Closed Loop mode using XOSC32K as reference clock and MCLK.CTRLA.CKSEL = 1 Table 46-8. Active Current Consumption Mode Conditions Regulator PL CPU Clock Vcc Ta Typ. Max Units ACTIVE COREMARK/ FIBONACCI LDO PL0 DFLLULP at 8MHz 1.8V Max at 85°C Typ at 25° 64.1 82 μA/Mhz 3.3V 64.4 84 OSC 8MHz 1.8V 66.6 81 3.3V 70.3 83 OSC 4MHz 1.8V 74.1 102 3.3V 77.8 106 PL2 FDPLL96M at 32MHz 1.8V 82.0 89 3.3V 82.5 89 DFLLULP at 32MHz 1.8V 75.8 99 3.3V 75.8 96 BUCK PL0 DFLLULP at 8MHz 1.8V 40.0 53 3.3V 25.3 34 OSC 8MHz 1.8V 43.8 53 3.3V 32.1 39 OSC 4MHz 1.8V 50.3 68 3.3V 38.9 52 PL2 FDPLL96M at 32MHz 1.8V 59.9 66 SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1129 Mode Conditions Regulator PL CPU Clock Vcc Ta Typ. Max Units 3.3V 35.3 39 DFLLULP at 32MHz 1.8V 55.3 68 3.3V 32.6 41 WHILE1 LDO PL0 DFLLULP at 8MHz 1.8V 44.3 61 3.3V 44.4 62 OSC 8MHz 1.8V 47.6 60 3.3V 50.1 63 OSC 4MHz 1.8V 54.6 83 3.3V 57.7 86 PL2 FDPLL96M at 32MHz 1.8V 56.9 61 3.3V 57.2 62 DFLLULP at 32MHz 1.8V 50.8 66 3.3V 51.0 64 BUCK PL0 DFLLULP at 8MHz 1.8V 28.1 40 3.3V 18.5 27 OSC 8MHz 1.8V 32.2 41 3.3V 25.3 32 OSC 4MHz 1.8V 38.4 57 3.3V 31.9 45 PL2 FDPLL96M at 32MHz 1.8V 41.5 46 3.3V 24.6 28 DFLLULP at 32MHz 1.8V 37.1 47 3.3V 22.0 28 IDLE LDO PL0 DFLLULP at 8MHz 1.8V 16.0 32 3.3V 16.2 33 OSC 8MHz 1.8V 19.8 33 3.3V 22.0 36 OSC 4MHz 1.8V 26.2 55 3.3V 29.2 59 PL2 FDPLL96M at 32MHz 1.8V 20.3 25 3.3V 20.4 26 SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1130 Mode Conditions Regulator PL CPU Clock Vcc Ta Typ. Max Units DFLLULP at 32MHz 1.8V 14.3 19 3.3V 14.4 19 BUCK PL0 DFLLULP at 8MHz 1.8V 11.1 21 3.3V 8.3 16 OSC 8MHz 1.8V 15.5 24 3.3V 15.2 21 OSC 4MHz 1.8V 21.3 39 3.3V 21.6 35 PL2 FDPLL96M at 32MHz 1.8V 14.9 19 3.3V 9.1 12 DFLLULP at 32MHz 1.8V 10.6 14 3.3V 6.7 9 Table 46-9. Standby and Off Mode Current Consumption Mode Conditions Regulator Mode Vcc Ta Typ. Max. Units STANDBY All 16 kB RAM retained, PDSW domain in active state LPVREG with LPEFF Disable 1.8V 25°C 1.3 3.5 µA 85°C 18.4 66.0 LPVREG with LPEFF Enable 3.3V 25°C 1.1 3.0 85°C 14.2 41.8 BUCK in standby with MAINVREG in PL0 mode (VREG.RUNSTDBY=1 and VREG.STDBYPL0=1) 1.8V 25°C 1.2 2.9 85°C 14.6 42.9 3.3V 25°C 1.1 2.2 85°C 9.6 28.6 All 16 kB RAM retained, PDSW domain in retention LPVREG with LPEFF Disable 1.8V 25°C 0.6 1.1 85°C 5.1 14.9 LPVREG with LPEFF Enable 3.3V 25°C 0.5 1.0 85°C 4.3 12.1 BUCK in standby with MAINVREG in PL0 mode (VREG.RUNSTDBY=1 and VREG.STDBYPL0=1) 1.8V 25°C 0.8 1.1 85°C 4.3 11.9 3.3V 25°C 0.8 1.5 85°C 3.4 8.5 SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1131 Mode Conditions Regulator Mode Vcc Ta Typ. Max. Units 12 kB RAM retained,PDSW domain in retention LPVREG with LPEFF Disable 1.8V 25°C 0.6 1.1 85°C 4.7 13.6 LPVREG with LPEFF Enable 3.3V 25°C 0.5 1.0 85°C 4.0 11.1 BUCK in standby with MAINVREG in PL0 mode (VREG.RUNSTDBY=1 and VREG.STDBYPL0=1) 1.8V 25°C 0.7 1.1 85°C 4.1 11.0 3.3V 25°C 0.8 1.5 85°C 3.2 8.0 8kB RAM retained,PDSW domain in retention LPVREG with LPEFF Disable 1.8V 25°C 0.5 1.0 85°C 4.4 12.6 LPVREG with LPEFF Enable 3.3V 25°C 0.5 0.9 85°C 3.8 10.3 BUCK in standby with MAINVREG in PL0 mode (VREG.RUNSTDBY=1 and VREG.STDBYPL0=1) 1.8V 25°C 0.7 1.0 85°C 3.8 10.1 3.3V 25°C 0.7 1.4 85°C 3.0 7.9 4kB RAM retained,PDSW domain in retention LPVREG with LPEFF Disable 1.8V 25°C 0.5 0.9 85°C 4.0 11.2 LPVREG with LPEFF Enable 3.3V 25°C 0.5 0.9 85°C 3.5 9.3 BUCK in standby with MAINVREG in PL0 mode (VREG.RUNSTDBY=1 and VREG.STDBYPL0=1) 1.8V 25°C 0.7 1.0 85°C 3.5 9.1 3.3V 25°C 0.8 1.5 85°C 2.9 6.8 4kB RAM retained,PDSW domain in retention and RTC running on XOSC32K LPVREG with LPEFF Disable 1.8V 25°C 0.9 1.3 85°C 4.5 11.7 LPVREG with LPEFF Enable 3.3V 25°C 0.8 1.2 85°C 4.0 9.8 BUCK in standby with MAINVREG in PL0 mode (VREG.RUNSTDBY=1 and VREG.STDBYPL0=1) 1.8V 25°C 1.0 1.3 85°C 4.0 9.6 3.3V 25°C 1.1 1.7 85°C 3.3 7.3 SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1132 Mode Conditions Regulator Mode Vcc Ta Typ. Max. Units OFF 1.8V 25°C 34.6 54.4 nA 85°C 595.7 1197.3 3.3V 25°C 61.2 89.1 85°C 796.1 1622.8 46.8 Wake-Up Time Conditions: • VDDIO/VDDANA = 3.3V • LDO Regulation mode • CPU clock = OSC16M @ 4 MHz • One Wait-state • Cache enabled • Flash Fast Wake-up enabled (NVMCTRL.CTRLB.FWUP = 1) • Flash in WAKEUPINSTANT mode (NVMCTRL.CTRLB.SLEEPPRM = 1) Measurement Method: For Idle and Standby, the CPU sets an I/O by writing PORT->IOBUS without jumping in an interrupt handler (Cortex M23 register PRIMASK = 1). The wake-up time is measured between the edge of the wake-up input signal and the edge of the GPIO pin. For Off mode, the exit of the mode is done through the reset pin, the time is measured between the falling edge of the RESETN signal (with the minimum reset pulse length), and the set of the I/O which is done by the first executed instructions after Reset. Table 46-10. Wake-Up Timing (1) Sleep Mode Condition Typ Unit Idle PL2 or PL0 1.5 μs Standby PL0 PDSW domain in retention 5.3 PDSW domain in active 2.6 PL2 Voltage scaling at default values: SUPC >VREG.VSVSTEP=0 SUPC > VREG.VSPER=0 PDSW domain in retention 76 PDSW domain in active 75 PL2 Voltage scaling at fastest setting: SUPC > VREG.VSVSTEP=15 SUPC > VREG.VSPER=0 PDSW domain in retention 16 PDSW domain in active 15 OFF L10 with BOOTOPT=0 3.2 ms SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1133 Sleep Mode Condition Typ Unit L11 with BOOTOPT=0 4.1 L10 or L11 with BOOTOPT=1, BS = 0x40 210 L10 or L11 with BOOTOPT=1, BS = 0x80 410 L10 or L11 with BOOTOPT=2, BS = 0x40 210 L10 or L11 with BOOTOPT=2, BS = 0x80 410 Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. 46.9 I/O Pin Characteristics There are two different pin types with three different speeds: Normal and High Sink(2) . The Drive Strength bit is located in the Pin Configuration register of the PORT (PORT.PINCFG.DRVSTR). Table 46-11. I/O Pins Common Characteristics Symbol Parameter Conditions Min. Typ. Max. Units VIL Input low-level voltage VDD=1.62V-2.7V - - 0.25*VDD V VDD=2.7V-3.63V - - 0.3*VDD VIH Input high-level voltage VDD=1.62V-2.7V 0.7*VDD - - VDD=2.7V-3.63V 0.55*VDD - - VOL Output low-level voltage VDD>1.62V, IOL max - 0.1*VDD 0.2*VDD VOH Output high-level voltage VDD>1.62V, IOH max 0.75*VDD 0.85*VDD - RPULL Pull-up - Pull-down resistance 20 40 63 kΩ ILEAK Input leakage current Pull-up resistors disabled -1 ±0.015 1 µA Table 46-12. I/O Pins Maximum Output Current Symbol Parameter Conditions Normal Pins High Sink Pins(2) Normal Pins High Sink Pins(2) Units DRVSTR=0 DRVSTR=1 IOL Maximum Output lowlevel current VDD=1.62V-3V 1 2 2 4 mA VDD=3V-3.63V 2.5 6 6 12 IOH Maximum Output highlevel current VDD=1.62V-3V 0.7 1.5 1.5 3 VDD=3V-3.63V 2 5 5 10 SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1134 Table 46-13. I/O Pins Dynamic Characteristics(1) Symbol Parameter Conditions Normal Pins High Sink Pins(2) Normal Pins High Sink Pins(2) Units DRVSTR=0 DRVSTR=1 tRISE Maximum Rise time VDD=3.3V, load=20 pF, 10%/90% 13 6 6 4.5 ns tFALL Maximum Fall time VDD=3.3V, load=20 pF, 10%/90% 12 7 7 4.5 The pins with I2C alternative mode available are compliant(2) with I2C norms. All I2C pins support Standard mode (Sm), Fast mode (Fm), Fast plus mode (Fm+), and High speed mode (Hs, up to 3.4 MHz). The available I2C pins are listed in the I/O Multiplexing section. Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. 2. The following pins are High Sink pins and have different properties than normal pins: PA16, PA17, PA22,PA23, and PA31. 46.10 Injection Current Stresses beyond those listed in the table below 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. Table 46-14. Injection Current(1) Symbol Description min max Unit Iinj1 (2) I/O pin injection current -1 +1 mA Iinj2 (3) I/O pin injection current -15 +15 mA Iinjtotal Sum of I/O pins injection current -45 +45 mA Note:  1. Injecting current may have an effect on the accuracy of Analog blocks 2. Conditions for Vpin: Vpin < GND-0.6V or 3.6V 1.0V 0.7 - Vref-0.7 V For Vref=1.0V 0.3 - Vref-0.3 V CSAMPLE(1) Input sampling capacitance - 2.8 3.2 pF RSAMPLE(1) Input sampling on-resistance - - 1715 Ω Rref(1) Reference input source resistance REFCOMP = 1 - - 5 kΩ Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. Table 46-24. Differential Mode (1) Symb ol Parameters Conditions Measurements Unit Min Typ Max ENOB Effective Number of bits Fadc = 1Msps Vref=2.0V Vddana=3.0V 9.1 10.2 10.8 bits Vref=1.0V Vddana=1.6V to 3.6V 9.0 10.1 10.6 Vref=Vddana=1.6V to 3.6V 8.9 9.9 11.0 Bandgap Reference, Vddana=1.6V to 3.6V 9.0 9.8 10.6 TUE Total Unadjusted Error without offset and gain compensation Vref=Vddana=1.6V to 3.6V - 7 32 LSB INL Integral Non Linearity without offset and gain compensation Vref=Vddana=1.6V to 3.6V - +/-1.9 +/-4 DNL Differential Non Linearity without offset and gain compensation Vref=Vddana=1.6V to 3.6V - +0.94/- 1 +1.85/ -1 Gain Gain Error without gain compensation Vref=1V Vddana=1.6V to 3.6V - +/-0.38 +/-1.9 % Vref=3V Vddana=1.6V to 3.6V - +/-0.14 +/-0.9 Bandgap Reference - +/-0.64 +/-5.4 Vref=Vddana=1.6V to 3.6V - +/-0.15 +/-0.9 Offset Offset Error without offset compensation Vref=1V Vddana=1.6V to 3.6V - +/-0.13 +/-15. 8 mV SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1141 Symb ol Parameters Conditions Measurements Unit Min Typ Max Vref=3V Vddana=1.6V to 3.6V - +/-1.82 +/-14. 9 Bandgap Reference - +/-2.07 +/-15. 8 Vref=Vddana=1.6V to 3.6V - +/-1.82 +/-15. 3 SFDR Spurious Free Dynamic Range Fs = 1MHz / Fin = 13 kHz / Full range Input signal Vref=2.0V Vddana=3.0V 58.1 70.5 77.5 dB SINAD Signal to Noise and Distortion ratio 56.7 63.4 66.5 SNR Signal to Noise ratio 56.5 64.4 67.1 THD Total Harmonic Distortion -74.7 -68.7 -57.7 - Noise RMS External Reference voltage - 0.42 - mV Note:  1. These are given without any ADC oversampling and decimation features enabled. Table 46-25. Single-Ended Mode (1) Symbol Paramete rs Conditions Measurements Unit Min Typ Max ENOB Effective Number of bits Fadc = 1Msps Vref=2.0V Vddana=3.0V 8.0 9.3 9.7 bits Vref=1.0V Vddana=1.6V to 3.6V 7.9 8.2 9.4 Vref=Vddana=1.6V to 3.6V 8.6 9.2 9.9 Bandgap Reference, Vddana=1.6V to 3.6V 7.8 8.4 8.9 TUE Total Unadjuste d Error without offset and gain compensa tion Vref=2.0V Vddana=3.0V - 12 63 LSB INL Integral Non Linearity without offset and gain Vref=2.0V Vddana=3.0V - +/-3.4 +/-8.9 SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1142 Symbol Paramete rs Conditions Measurements Unit Min Typ Max compensa tion DNL Differential Non Linearity without offset and gain compensa tion Vref=2.0V Vddana=3.0V - +0.9/-1 +1.8/- 1 Gain Gain Error without gain compensa tion Vref=1V Vddana=1.6V to 3.6V - +/-0.3 +/-5.1 % Vref=3V Vddana=1.6V to 3.6V - +/-0.3 +/-5.1 Bandgap Reference - +/-0.4 +/-5.1 Vref=Vddana=1.6V to 3.6V - +/-0.2 +/-0.8 Offset Offset Error without offset compensa tion Vref=1V Vddana=1.6V to 3.6V - +/-2.6 +/-45 mV Vref=3V Vddana=1.6V to 3.6V - +/-2.6 +/-45 Bandgap Reference - +/-1.3 +/-34 Vref=Vddana=1.6V to 3.6V - +/-1.8 +/-37 SFDR Spurious Free Dynamic Range Fs = 1MHz / Fin = 13 kHz / Full range Input signal Vref=2.0V Vddana=3.0V 56.1 63.8 72.6 dB SINAD Signal to Noise and Distortion ratio 50.0 57.7 60.1 SNR Signal to Noise ratio 51.9 58.3 59.8 THD Total Harmonic Distortion -72.5 -62.4 -52.3 Noise RMS External Reference voltage - 0.80 - mV Note:  1. These are given without any ADC oversampling and decimation features enabled. SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1143 Figure 46-2. ADC Analog Input AINx The minimum sampling time tsamplehold for a given Rsource can be found using this formula: ݐsamplehold ≥ ܴsample + ܴsource × ܥsample × ݊ + 2 × ln 2 For 12-bit accuracy: ݐsamplehold ≥ ܴsample + ܴsource × ܥsample × 9.7 where ݐsamplehold ≥ 1 2 × ݂ADC . 46.11.5 Digital-to-Analog Converter (DAC) Characteristics Table 46-26. Operating Conditions(1) Symbol Parameters Conditions Min Typ Max Unit AVREF External reference voltage 1 - VDDANA-0.6 V Internal reference voltage 1 - 1 - V Internal reference voltage 2 - VDDANA - V Linear output voltage range 0.05 - VDDANA-0.05 V Minimum resistive load 5 - - kOhm Maximum capacitance load - - 100 pF IDD DC supply current(2) Voltage pump disabled - 175 247 µA Note:  1. The values in this table are based on specifications otherwise noted. 2. These values are based on characterization. These values are not covered in test limits in production. Table 46-27. Clock and Timing Parameter Conditions Min. Typ. Max. Units Conversion rate Cload=100pF Rload > 5kOhm Normal mode 350 ksps For DDATA=+/-1 1000 Startup time VDDANA > 2.6V VDDANA > 2.6V - - 2.85 µs VDDANA < 2.6V VDDANA < 2.6V - - 10 µs Note:  These values are based on simulation. These values are not covered by test limits in production or characterization. SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1144 Table 46-28. Accuracy Characteristics Symbol Parameter Conditions Min. Typ. Max. Units RES Input resolution - - 10 Bits INL Integral non-linearity VREF= Ext 1.0V VDD = 1.62V ±0.2 ±0.5 ±1.4 LSB VDD = 3.63V ±0.2 ±0.4 ± 1.2 VREF = VDDANA VDD = 1.62V ±0.2 ±0.6 ± 2.1 VDD = 3.63V ± 0.2 ±0.5 ± 1.9 VREF= INT1V VDD = 1.62V ± 0.4 ±0.7 ± 3.5 VDD = 3.63V ± 0.4 ±0.8 ± 6 DNL Differential non-linearity VREF= Ext 1.0V VDD = 1.62V ± 0.1 ±0.3 ± 1.5 LSB VDD = 3.63V ± 0.1 ±0.3 ± 1.2 VREF= VDDANA VDD = 1.62V ± 0.1 ±0.2 ± 1.7 VDD = 3.63V ± 0.1 ±0.2 ± 1.5 VREF= INT1V VDD = 1.62V ± 0.3 ±0.6 ± 3 VDD = 3.63V ± 0.3 ±0.8 ± 7 Gain Gain error VREF= Ext 1.0V - ±4 ± 16 mV VREF= VDDANA - ±12 ± 60 mV VREF= INT1V - ±1 ± 22 mV Offset Offset error VREF= Ext 1.0V - ±1 ± 13 mV VREF= VDDANA - ±2.5 ± 21 mV VREF= INT1V - ±1.5 ± 20 mV 46.11.6 Analog Comparator (AC) Characteristics Table 46-29. Electrical and Timing Symbol Parameters Conditions Min. Typ Max. Unit PNIVR Positive and Negative input range voltage 0 - VDDANA V ICMR Input common mode range 0 - VDDANA-0.1 V Off Offset COMPCTRLn.SPEED=0x0 -70 -4.5/+1.5 70 mV COMPCTRLn.SPEED=0x1 -55 -4.5/+1.5 55 COMPCTRLn.SPEED=0x2 -48 -4.5/+1.5 48 COMPCTRLn.SPEED=0x3 -42 -4.5/+1.5 42 VHys Hysteresis COMPCTRLn.HYST=0x0 10 45 74 mV COMPCTRLn.HYST=0x1 22 70 106 SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1145 Symbol Parameters Conditions Min. Typ Max. Unit COMPCTRLn.HYST=0x2 37 90 129 COMPCTRLn.HYST=0x3 49 105 150 Tpd Propagation Delay Vcm=VDDANA/2, Vin= +-100 mV overdrive from Vcm (see note 2) COMPCTRLn.SPEED=0x0 - 4 12.3 µs COMPCTRLn.SPEED=0x1 - 0.97 2.6 COMPCTRLn.SPEED=0x2 - 0.56 1.4 COMPCTRLn.SPEED=0x3 - 0.33 0.77 Tstart Start-up time COMPCTRLn.SPEED=0x0 - 17 71 µs COMPCTRLn.SPEED=0x1 - 0.85 4.5(1) COMPCTRLn.SPEED=0x2 - 0.55 3.2(1) COMPCTRLn.SPEED=0x3 - 0.45 2.7(1) Vscale INL - 0.4 - LSB DNL - 0.1 - Offset Error - 0.1 - Gain Error - 1.3 - Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. 2. Vcm: Common Mode Voltage. Table 46-30. Power Consumption Symbol Parameters Conditions Ta Min. Typ Max. Unit IDDANA Current consumption voltage scaler disabled. COMPCTRLn.SPEED=0x0, VDDANA=3.3V Max.85°C Typ.25°C - 51 118 nA COMPCTRLn.SPEED=0x1, VDDANA=3.3V - 233 481 COMPCTRLn.SPEED=0x2, VDDANA=3.3V - 456 885 COMPCTRLn.SPEED=0x3, VDDANA=3.3V - 879 1604 Current consumption voltage scaler only VDDANA=3.3V - 13 18 µA SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1146 46.11.7 DETREF Characteristics Table 46-31. Reference Voltage Characteristics Symbol Parameter Conditions Min. Typ. Max. Units ADC/DAC Ref ADC/DAC internal reference nom. 1.0V, VCC=3.0V, T= 25°C 0.976 1.0 1.022 V nom. 1.1V, VCC=3.0V, T= 25°C 1.077 1.1 1.127 nom. 1.2V, VCC=3.0V, T= 25°C 1.174 1.2 1.234 nom. 1.25V, VCC=3.0V, T= 25°C 1.221 1.25 1.287 nom. 2.0V, VCC=3.0V, T= 25°C 1.945 2.0 2.030 nom. 2.2V, VCC=3.0V, T= 25°C 2.143 2.2 2.242 nom. 2.4V, VCC=3.0V, T= 25°C 2.335 2.4 2.457 nom. 2.5V, VCC=3.0V, T= 25°C 2.428 2.5 2.563 Ref Temperature coefficient drift over [-40, +25]°C - -0.01/+0.015 - %/°C drift over [+25, +85]°C - -0.01/+0.005 - Ref Supply coefficient drift over [1.6, 3.63]V - +/-0.35 - %/V AC Ref AC Ref Accuracy VCC=3.0V, T=25°C 1.086 1.1 1.128 V Ref Temperature coefficient drift over [-40, +25]°C - +/-0.01 - %/°C drift over [+25, +85]°C - -0.005/+0.001 - %/°C Ref Supply coefficient drift over [1.6, 3.63]V - -0.35/+0.35 - %/V 46.11.8 OPAMP Characteristics Table 46-32. Operating Conditions Symbol Parameters Conditions Min. Typ. Max. Unit VCC Power Supply All power modes 1.6 3 3.63 V Vin Input voltage range 0 - Vcc V Vout Output voltage range 0.15 - Vcc-0.15 V Cload Maximum capacitance load - - 50 pF Rload (1) Minimum resistive load Output Range[0.15V;Vcc-0.15V] 3.5 - - kΩ Output Range[0.3V;Vcc-0.3V] 0.5 - - Iload(1) DC output current load Output Range[0.15V;Vcc-0.15V] - - 1 mA Output Range[0.3V;Vcc-0.3V] - - 6.9 Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1147 Table 46-33. Power Consumption(1) Symbol Parameters Conditions Ta Min. Typ. Max. Unit IDD DC supply current (Voltage Doubler OFF) Mode 3,VCC =3.3V Max 85°C Typ 25°C - 235 400 μA Mode 2,VCC =3.3V - 94 166 Mode 1,VCC =3.3V - 26 47 Mode 0 ,VCC =3.3V - 7 13 Voltage Doubler consumption VCC =3.3V - 0.70 1.4 Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. Table 46-34. Static Characteristics in 1X Gain(1) Symbol Parameters Conditions Min. Typ. Max. Unit G0 Open loop gain Mode 3 - 114.5 - dB Mode 2 - 117.6 - Mode 1 - 116.8 - Mode 0 - 108.5 - GBW Gain Bandwidth Mode 3 - 7.1 - MHz Mode 2 - 2.8 - Mode 1 - 0.85 - Mode 0 - 0.2 - фm Phase margin Mode 3 - 71.5 - deg Mode 2 - 64 - Mode 1 - 56 - Mode 0 - 52 - Tr1 Response Time at 240µV (X1 gain) Mode 3 - 1.3 - µs Mode 2 - 3.3 - Mode 1 - 13 - Mode 0 - 52 - ∆Tr1 Response Time Variation for 10mV Mode 3 - 100 - ns Tstart Start-up time (Enable to Ready), (Voltage Doubler OFF) Mode 3 - 2.7 - µs Mode 2 - 6.35 - Mode 1 - 21.5 - Mode 0 - 88.5 - Oe Input Offset Voltage - - +-3.5 mV SR Slew rate Mode 3 - - 2.8/2.6 - V/µs Mode 2 - -1.2/1.1 - SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1148 Symbol Parameters Conditions Min. Typ. Max. Unit Mode 1 - -0.3/0.3 - Mode 0 - -0.09/0.07 - CMRR 1X gain Mode 3 - 83 - dB Mode 2 - 84 - Mode 1 - 84 - Mode 0 - 83 - PSRR 1X gain Mode 3 - 76 - dB Mode 2 - 76 - Mode 1 - 76 - Mode 0 - 75 - - Integrated Noise, BW=[0.1Hz-10kHz], x1 gain - VOUT=1V Mode 3 - 7.9 - µVRMS Mode 2 - 8.3 - Mode 1 - 9.9 - Mode 0 - 12.7 - - Integrated Noise, BW=[0.1Hz-1MHz], x1 gain - VOUT=1V Mode 3 - 18.2 - µVRMS Mode 2 - 22.8 - Mode 1 - 36.7 - Mode 0 - 44.4 - Note:  1.These values are based on simulation. They are not covered by production test limits or characterization. Table 46-35. PGA Electrical Characteristics(1) Symbol Parameters Conditions Min. Typ. Max. Unit - Gain accuracy 16X Gain - - +/-2.4 % 4X Gain - - +/-1.1 1X Gain - - +/-2.6 THD Total Harmonic Distortion @ 10kHz - mode 3 16X Gain - -77 - dB 4X Gain - -72.8 - 1X Gain - -82.6 - - Integrated Noise, BW=[0.1Hz-10 kHz], 16X gain - VOUT=1V Mode 3 - 147 - µVrms Mode 2 - 147 - Mode 1 - 162 - Mode 0 - 191 - - Integrated Noise, BW=[0.1Hz-1MHz], 16X gain - VOUT=1V Mode 3 - 262 - µVrms Mode 2 - 247 - Mode 1 - 235 - Mode 0 - 235 - SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1149 Note:  1.These values are based on simulation. They are not covered by production test limits or characterization. 46.11.9 Peripheral Touch Controller (PTC) Characteristics Table 46-36. Sensor Load Capacitance Symbol Mode PTC channel Min PCB External (1) Max Sensor Load (2) Units Cload Self-capacitance Y0 5 54 pF Y1 - Y2 - 50 Y3 5 54 Y4 5 Y5 - Y6 5 Y7 5 Y8 5 Y9 5 Y10 - 45 Y11 5 54 Y12 5 Y13 - Y14 - Y15 5 50 Y16 5 54 Y17 5 Y18 5 Y19 5 Mutual-capacitance All - 31 Note:  1. Minimum external capacitance must be added on PCB design per PTC channel. Ensure that the PCB and sensor design add enough parasitic capacitance on each PTC channel, otherwise, an external capacitor must be added. 2. Capacitance load, the PTC circuitry, can compensate for each channel. SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1150 Table 46-37. Analog Gain Settings (1) Symbol Setting Average Gain GAIN_1 1.0 GAIN_2 2.0 GAIN_4 3.9 GAIN_8 8.1 Note:  1. Analog Gain is a parameter of the QTouch Library. Refer to the QTouch Library Peripheral Touch Controller User Guide. Power Consumption The values in the Power Consumption table below are measured values of power consumption under the following conditions: Operating Conditions • VDD = 3.3V Clocks • OSC16M divided to 4MHz used as main clock source • CPU is running on flash with 0 wait states, at 4MHz • PTC running at 4MHz • Voltage Regulator mode: LPEFF enabled PTC Configuration • Mutual-capacitance mode • One touch channel System Configuration • Standby sleep mode enabled • RTC running on OSCULP32K: used to define the PTC scan rate, through the event system • Drift Calibration disabled: no interrupts, PTC scans are performed in standby mode • Drift Calibration enabled: RTC interrupts (wakeup) the CPU to perform PTC scans. PTC drift calibration is performed every 1.5 sec. Table 46-38. Power Consumption (1) Symbol Parameters Drift Calibration PTC scan rate (msec) Oversamples Ta Typ. Max. Units IDD Current Consumption Disabled 10 4 Max. 85°C Typ. 25°C 6.2 49.2 µA 16 12.7 58.1 50 4 2.3 43.7 16 3.7 45.5 SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1151 Symbol Parameters Drift Calibration PTC scan rate (msec) Oversamples Ta Typ. Max. Units 100 4 1.7 43.2 16 2.4 43.9 200 4 1.4 42.8 16 1.8 43.2 Enabled 10 4 8.3 51.7 16 14.2 60.5 50 4 3.0 44.8 16 4.8 47.0 100 4 2.3 44.5 16 2.8 45.4 200 4 1.9 43.9 16 2.4 44.2 Note:  1. These are based on characterization. 46.12 NVM Characteristics Table 46-39. NVM Max Speed Characteristics (1) Conditions CPU Fmax (MHz) 0WS 1WS 2WS PL0 (-40/85°C) (-40/125°C) VDDIO>1.62 V 6 8 8 VDDIO>2.7 V 7.5 8 8 PL2 (-40/85°C) (-40/125°C) VDDIO>1.62 V 14 28 32 VDDIO>2.7 V 14 32 32 Table 46-40. NVM Timing Characteristics (1) Symbol Timings Max Units tFPP Page Write 2.5 ms tFRE Row erase 6 Note:  SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1152 1. For this Flash technology, a maximum number of 8 consecutive writes is allowed per row. Once this number is reached, a row erase is mandatory. Table 46-41. Flash Erase and Programming Current Symbol Parameter Typ. Units IDDNVM Maximum current (peak) during whole programming or erase operation 10 mA Table 46-42. NVM Reliability Characteristics Symbol Parameter Conditions Min. Typ. Units RetNVM25k Retention after up to 25k Average ambient 55°C 10 50 Years RetNVM2.5k Retention after up to 2.5k Average ambient 55°C 20 100 Years RetNVM100 Retention after up to 100 Average ambient 55°C 25 >100 Years CycNVM Cycling Endurance(1) -40°C < Ta < 85°C -40°C < Ta < 125°C 25K 100K Cycles Cycling Endurance using Tamper Erase(1) 50 100 Cycles Note:  1. An endurance cycle is a write and an erase operation. 46.13 Oscillators Characteristics 46.13.1 Crystal Oscillator (XOSC) Characteristics Digital Clock Characteristics The following table describes the characteristics for the oscillator when a digital clock is applied on XIN. Table 46-43. Digital Clock Characteristics Symbol Parameter Min. Typ. Max. Units FXIN XIN clock frequency - - 24 MHz DCXIN(1) XIN clock duty cycle 40 50 60 % Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. Crystal Oscillator Characteristics The following Table describes the characteristics for the oscillator when a crystal is connected between XIN and XOUT. SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1153 Figure 46-3. Oscillator Connection XIN CLEXT CLEXT CM RM LM CSHUNT XOUT DEVICE Crystal 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 be found in the crystal data sheet. The capacitance of the external capacitors (CLEXT) can then be computed as follows: CLEXT = 2(CL - CPARA - CPCB - CSHUNT) Where: • CPARA is the internal load capacitor parasitic between XIN and XOUT (CPARA = (CXIN * CXOUT)/(CXIN + CXOUT)) • CPCB is the capacitance of the PCB • CSHUNT is the shunt capacity of the crystal. Table 46-44. Multi Crystal Oscillator Electrical Characteristics Symbol Parameter Conditions Min. Typ. Max Units Fout Crystal oscillator frequency 0.4 - 32 MHz ESR(2) Crystal Equivalent Series Resistance - SF = 3 F = 0,4MHz - CL=100 pF XOSC,GAIN=0 - - 5.6K Ω F = 2MHz - CL=20 pF XOSC,GAIN=0, Cshunt=3.3pF - - 330 F = 4MHz - CL=20 pF XOSC,GAIN=1, Cshunt=2.5pF - - 240 F = 8MHz - CL=20 pF XOSC,GAIN=2, Cshunt=5.5pF - - 105 F = 16MHz - CL=20 pF XOSC,GAIN=3, Cshunt=4pF - - 60 F = 32MHz - CL=20 pF XOSC,GAIN=4, Cshunt=3.9pF - - 55 Cxin(2) Parasitic load capacitor - 6.7 - pF Cxout(2) - 4.2 - pF Tstart(2) Startup time F = 2MHz - CL=20 pF XOSC,GAIN=0, Cshunt=3.3pF - 15.6K 81.6K Cycles F = 4MHz - CL=20 pF XOSC,GAIN=1, Cshunt=2.5pF - 6.3K 25.2K SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1154 Symbol Parameter Conditions Min. Typ. Max Units F = 8MHz - CL=20 pF XOSC,GAIN=2, Cshunt=5.5pF - 6.2K 27.2K F = 16MHz - CL=20 pF XOSC,GAIN=3, Cshunt=4pF - 7.7K 27.3K F = 32MHz - CL=20 pF XOSC,GAIN=4, Cshunt=3.9pF - 6.0K 21K CL(1) Crystal load capacitance 10 - 20 pF Pon(1) Drive Level AMPGC=ON - - 100 uW Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. 2. These are based on characterization. Table 46-45. Power Consumption Symbol Parameter Conditions Ta Min. Typ. Max. Units IDD Current consumption F=2MHz - CL=20pF XOSC,GAIN=0, VCC=3.3V AMPGC=OFF Max 85°C Typ 25°C - 66 85 µA AMPGC=ON - 62 99 F=4MHz - CL=20pF XOSC,GAIN=1, VCC=3.3V AMPGC=OFF - 107 140 AMPGC=ON - 70 101 F=8MHz - CL=20pF XOSC,GAIN=2, VCC=3.3V AMPGC=OFF - 200 261 AMPGC=ON - 118 153 F=16MHz - CL=20pF XOSC,GAIN=3, VCC=3.3V AMPGC=OFF - 436 581 AMPGC=ON - 247 329 F=32MHz - CL=20pF XOSC,GAIN=4, VCC=3.3V AMPGC=OFF - 1303 1902 AMPGC=ON - 627 940 46.13.2 External 32KHz Crystal Oscillator (XOSC32K) Characteristics Digital Clock Characteristics The following table describes the characteristics for the oscillator when a digital clock is applied on XIN32 pin. SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1155 Table 46-46. Digital Clock Characteristics(1) Symbol Parameter Min. Typ. Max. Units fCPXIN32 XIN32 clock frequency 32.768 1000 kHz DCXIN XIN32 clock duty cycle 40 50 60 % Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. Crystal Oscillator Characteristics The following section describes the characteristics for the oscillator when a crystal is connected between XIN32 and XOUT32 pins. Figure 46-4. Oscillator Crystal Connection XIN32 CLEXT CLEXT CM RM LM CSHUNT XOUT32 DEVICE Crystal 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 be found in the crystal data sheet. The capacitance of the external capacitors (CLEXT) can then be computed as follows: CLEXT = 2(CL - CPARA - CPCB - CSHUNT) Where: • CPARA is the internal load capacitor parasitic between XIN and XOUT ( CPARA = (CXIN32K CXOUT32K)/(CXIN32K + CXOUT32K) ) • CPCB is the capacitance of the PCB • CSHUNT is the shunt capacity of the crystal. Table 46-47. 32 KHz Crystal Oscillator Electrical Characteristics Symbol Parameter Conditions Min. Typ. Max. Units FOUT Crystal oscillator frequency - - 32.768 - kHz CL(1) Crystal load capacitance - 7 - 9 pF CSHUNT(1) Crystal shunt capacitance - 0.6 - 2 pF CM (1) Motional capacitance - 0.6 - 3 fF ESR(2) Crystal Equivalent Series Resistance - SF=3 f=32.768kHz, CL= 9pF - - 70 kΩ CXIN32k(2) Parasitic load capacitor - - 3.2 - pF CXOUT32k(2) - - 3.4 - SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1156 Symbol Parameter Conditions Min. Typ. Max. Units tSTARTUP(2) Startup time f=32.768kHz, CL= 9pF - 10 43 KCycles Pon(1) Drive Level - - - 0.1 µW Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. 2. These are based on characterization. Table 46-48. Power Consumption Symbol Parameter Conditions Ta Min. Typ. Max. Units IDD Current consumption VCC=3.3V Max 85°C Typ 25°C - 309 606 nA 46.13.3 Ultra Low-Power Internal 32 kHz RC Oscillator (OSCULP32K) Characteristics Table 46-49. Ultra Low-Power Internal 32 kHz RC Oscillator Electrical Characteristics Symbol Parameter Conditions Min. Typ. Max. Units FOUT Output frequency at 25°C, at VDDIO=3.3V 30.84 32.768 34.51 kHz at 25°C, over [1.62, 3.63]V 30.84 32.768 34.74 kHz over[-40,+85]°C, over [1.62, 3.63]V 25.17 32.768 39.10 kHz Duty Duty Cycle - 50 - % 46.13.4 16 MHz RC Oscillator (OSC16M) Characteristics Table 46-50. Multi-RC Oscillator Electrical Characteristics Symbol Parameter Conditions Min. Typ. Max. Units FOUT Output frequency VDD=3.3V, T=25°C Calibrated against a 4/8/12/16 MHz reference 3.96 4.00 4.04 MHz 7.92 8.00 8.08 11.88 12.00 12.12 15.84 16.00 16.16 TempDrift Freq vs. temperature drift VDD=3.3V over temperature [-40°C-85°C], versus calibration reference at 25°C -5 - 5 % SupplyDrift Freq vs. supply drift Temperature =25°C over voltage [1.62V-3.63V], versus calibration reference at 3.3V -1.5 - 1.5 TWUP(2) Wake up time - 1st clock edge after enable FOUT = 4MHz - 0.13 0.28 µs FOUT = 8MHz - 0.13 0.28 SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1157 Symbol Parameter Conditions Min. Typ. Max. Units FOUT = 12MHz - 0.13 0.28 FOUT = 16MHz - 0.13 0.27 TSTARTUP(2) Startup time FOUT = 4MHz - 1.16 2.96 µs FOUT = 8MHz - 1.29 2.74 FOUT = 12MHz - 1.34 2.95 FOUT = 16MHz - 1.39 3.11 Duty(1) Duty Cycle - 45 50 55 % Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. 2. These are based on characterization. Table 46-51. Power Consumption Symbol Parameter Conditions Ta Min. Typ. Max. Units IDD Current consumption Fout=4MHz, VCC=3.3V Max.85°C Typ.25°C - 73 139 µA Fout=8MHz, VCC=3.3V - 106 169 Fout=12MHz, VCC=3.3V - 135 195 Fout=16MHz, VCC=3.3V - 166 225 46.13.5 Digital Frequency Locked Loop (DFLLULP) Characteristics Table 46-52. Digital Frequency Locked Loop Characteristics(2) Symbol Parameter Min Typ Max Unit FIN Input Clock Frequency 32 - 33 kHz FOUT Output Clock Frequency PL2 - 32 - MHz PL0 - 8 - Jp Period jitter PL0, Fin= 32 kHz 50 ppm, Fout = 8MHz -4 - 4 % PL2, Fin= 32 kHz 50 ppm, Fout = 32 MHz -4.3 - 4.3 tLOCK Lock Time After startup, time to get lock signal Fin = 32768 Hz, Fout = 8MHz, PL0 Binary Search mode enabled - 362 - µs After startup, time to get lock signal Fin = 32768 Hz, Fout = 32 MHz, PL2 - 362 - µs SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1158 Symbol Parameter Min Typ Max Unit Binary Search mode enabled Duty Duty cycle(1) 40 50 60 % Note:  1. These values are based on simulation. These values are not covered by test or characterization. 2. These characteristics are only applicable in LDO regulator mode. Table 46-53. Power Consumption(1) Symbol Parameters Conditions Ta Min Typ. Max Units IDD Current Consumption Fout=8MHz (PL0) - VCC=3.3V Max 85°C Typ 25°C - 33 93 µA Fout=32MHz (PL2) - VCC=3.3V - 144 223 Note:  1. These characteristics are only applicable in LDO regulator mode. 46.13.6 Digital Phase Lock Loop (DPLL) Characteristics Table 46-54. Fractional Digital Phase Lock Loop Characteristics(2) Symbol Parameter Min. Typ. Max. Unit FIN Input Clock Frequency 32 - 2000 kHz FOUT Output Clock Frequency PL2 32 - 96 MHz PL0 32 - 48 MHz Jp Period jitter PL0, Fin = 32 kHz, Fout = 32 MHz - 3 6 % PL2, Fin = 32 kHz, Fout = 32 MHz 2 5 PL0, Fin = 32 kHz, Fout = 48 MHz - 3 4 PL2, Fin = 32 kHz, Fout = 48 MHz 2 6 PL2, Fin = 32 kHz, Fout = 96 MHz - 3 4 PL0, Fin = 32 kHz, Fout = 32 MHz - 3 5 PL2, Fin = 32 kHz, Fout = 32 MHz 3 6 PL0, Fin = 2 MHz, Fout = 48 MHz - 5 7 PL2, Fin = 2 MHz, Fout = 48 MHz 3 6 PL2, Fin = 2 MHz, Fout = 96 MHz - 4 10 tLOCK Lock Time After startup, time to get lock signal Fin = 32 kHz, Fout = 96 MHz - 1.1 1.5 ms After startup, time to get lock signal Fin = 2 MHz, Fout = 96 MHz - 24 35 µs Duty Duty cycle(1) 40 50 60 % SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1159 Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. 2. These characteristics are applicable only in LDO regulator mode and with a XOSC or XOSC32K reference. Table 46-55. Power Consumption(1) Symbol Parameter Conditions TA Min. Typ. Max. Units IDD Current Consumption Fout = 48 MHz (PL0) - VDD=3.3V Max. 85°C Typ. 25°C - 339 432 µA Fout = 96 MHz (PL2) - VDD=3.3V - 678 777 Note:  1. These characteristics are only applicable in LDO regulator mode. 46.14 Timing Characteristics 46.14.1 External Reset Pin Table 46-56. External Reset Characteristics(1) Symbol Parameter Conditions Min. Typ. Max. Units tEXT Minimum reset pulse width 1 - - µs Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. 46.14.2 SERCOM in SPI Mode in PL0 Table 46-57. SPI Timing Characteristics and Requirements (1) Symbol Parameter Conditions Min. Typ. Max. Units tSCK SCK period when tSOV=0 on the slave side Master Reception 2*(tMIS +tSLAVE_OUT) (3) - - ns Master Transmission 2*(tMOV +tSLAVE_IN) (4) - - tSCKW SCK high/low width Master - 0,5*tSCK - tSCKR SCK rise time(2) Master - 0,25*tSCK - tSCKF SCK fall time(2) Master - 0,25*tSCK - tMIS MISO setup to SCK Master, VDD>2,70V 90 - - Master, VDD>1,62V 98.1 - - tMIH MISO hold after SCK Master, VDD>2,70V 0 - - SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1160 Symbol Parameter Conditions Min. Typ. Max. Units Master, VDD>1,62V 0 - - tMOV MOSI output valid after SCK Master, VDD>2,70V - - 34.5 ns Master, VDD>1,62V - - 38.6 tMOH MOSI hold after SCK Master, VDD>2,70V 9.7 - - Master, VDD>1,62V 9.7 - - tSSCK Slave SCK Period when tMIS=0 on the master side Slave Reception 2*(tSIS +tMASTER_OUT) (5) - - Slave Transmission 2*(tSOV +tMASTER_IN) (6) - - tSSCKW SCK high/low width Slave - 0,5*tSCK - tSSCKR SCK rise time(2) Slave - 0,25*tSCK - tSSCKF SCK fall time(2) Slave - 0,25*tSCK - tSIS MOSI setup to SCK Slave, VDD>2,70V 25.6 - - ns Slave, VDD>1,62V 26.2 - - tSIH MOSI hold after SCK Slave, VDD>2,70V 13.2 - - Slave, VDD>1,62V 13.9 - - tSSS SS setup to SCK Slave PRELOADEN=1 tSOSS+tEXT_MIS +2*tAPBC (8) (9) - - PRELOADEN=0 tSOSS+tEXT_MIS (8) - - tSSH SS hold after SCK Slave 0.5*tSSCK - - tSOV MISO output valid after SCK Slave, VDD>2,70V - - 69 Slave, VDD>1,62V - - 78.4 tSOH MISO hold after SCK Slave, VDD>2,70V 20.2 - - Slave, VDD>1,62V 20.2 - - tSOSS MISO setup after SS low Slave, VDD>2,70V - - 1* tSCK Slave, VDD>1,62V - - 1* tSCK SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1161 Symbol Parameter Conditions Min. Typ. Max. Units tSOSH MISO hold after SS high Slave, VDD>2,70V 15 - - Slave, VDD>1,62V 15 - - Note:  1. These values are based on simulation. These values are not covered by test limits in production. 2. See I/O Pin Characteristics. 3. Where tSLAVE_OUT is the slave external device output response time, generally tEXT_SOV +tLINE_DELAY. (7) 4. Where tSLAVE_IN is the slave external device input constraint, generally tEXT_SIS+tLINE_DELAY. (7) 5. Where tMASTER_OUT is the master external device output response time, generally tEXT_MOV +tLINE_DELAY. (7) 6. Where tMASTER_IN is the master external device input constraint, generally tEXT_MIS +tLINE_DELAY. (7) 7. tLINE_DELAY is the transmission line time delay. 8. tEXT_MIS is the input constraint for the master external device. 9. tAPBC is the APB period for SERCOM. Figure 46-5. SPI Timing Requirements in Master Mode Figure 46-6. SPI Timing Requirements in Slave Mode Maximum SPI Frequency SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1162 • Master Mode fSCKmax = 1/2*(tMIS + tvalid), where tvalid is the slave time response to output data after detecting an SCK edge. For a non-volatile memory with tvalid = 12 ns Max, fSPCKMax = 3.7 MHz @ VDDIO > 2.7V • Slave Mode fSCKmax = 1/2*(tSOV + tsu), where tsu is the setup time from the master before sampling data. With a perfect master (tsu=0), fSPCKMax = 6 MHz @ VDDIO > 2.7V 46.14.3 SERCOM in SPI Mode in PL2 Table 46-58. SPI Timing Characteristics and Requirements (1) Symbol Parameter Conditions Min. Typ. Max. Units tSCK SCK period when tSOV=0 on the slave side Master Reception 2*(tMIS +tSLAVE_OUT) (3) - - ns Master Transmission 2*(tMOV +tSLAVE_IN) (4) - - tSCKW SCK high/low width Master - 0,5*tSCK - tSCKR SCK rise time(2) Master - 0,25*tSCK - tSCKF SCK fall time(2) Master - 0,25*tSCK - tMIS MISO setup to SCK Master, VDD>2,70V 42.5 - - Master, VDD>1,62V 52.5 - - tMIH MISO hold after SCK Master, VDD>2,70V 0 - - Master, VDD>1,62V 0 - - tMOV MOSI output valid after SCK Master, VDD>2,70V - - 17.1 Master, VDD>1,62V - - 21.2 tMOH MOSI hold after SCK Master, VDD>2,70V 6.3 - - Master, VDD>1,62V 6.3 - - tSSCK Slave SCK Period when tMIS =0 on the master side Slave Reception 2*(tSIS +tMASTER_OUT) (5) - - Slave Transmission 2*(tSOV +tMASTER_IN) (6) - - tSSCKW SCK high/low width Slave - 0,5*tSCK - ns tSSCKR SCK rise time(2) Slave - 0,25*tSCK - tSSCKF SCK fall time(2) Slave - 0,25*tSCK - SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1163 Symbol Parameter Conditions Min. Typ. Max. Units tSIS MOSI setup to SCK Slave, VDD>2,70V 10.3 - - Slave, VDD>1,62V 11.1 - - tSIH MOSI hold after SCK Slave, VDD>2,70V 6.1 - - Slave, VDD>1,62V 6.9 - - tSSS SS setup to SCK Slave PRELOADEN=1 tSOSS+tEXT_MIS +2*tAPBC (8) (9) - - PRELOADEN=0 tSOSS+tEXT_MIS (8) - - ns tSSH SS hold after SCK Slave 0.5*tSSCK - - tSOV MISO output valid after SCK Slave, VDD>2,70V - - 35 Slave, VDD>1,62V - - 44.8 tSOH MISO hold after SCK Slave, VDD>2,70V 13.4 - - Slave, VDD>1,62V 13.4 - - tSOSS MISO setup after SS low Slave, VDD>2,70V - - 1* tSCK Slave, VDD>1,62V - - 1* tSCK tSOSH MISO hold after SS high Slave, VDD>2,70V 8.6 - - Slave, VDD>1,62V 8.6 - - Note:  1. These values are based on simulation. These values are not covered by test limits in production. 2. See I/O Pin Characteristics. 3. Where tSLAVE_OUT is the slave external device output response time, generally tEXT_SOV +tLINE_DELAY. (7) 4. Where tSLAVE_IN is the slave external device input constraint, generally tEXT_SIS+tLINE_DELAY. (7) 5. Where tMASTER_OUT is the master external device output response time, generally tEXT_MOV +tLINE_DELAY. (7) 6. Where tMASTER_IN is the master external device input constraint, generally tEXT_MIS +tLINE_DELAY. (7) 7. tLINE_DELAY is the transmission line time delay. 8. tEXT_MIS is the input constraint for the master external device. 9. tAPBC is the APB period for SERCOM. SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1164 Figure 46-7. SPI Timing Requirements in Master Mode Figure 46-8. SPI Timing Requirements in Slave Mode Maximum SPI Frequency • Master Mode fSCKmax = 1/2*(tMIS + tvalid), where tvalid is the slave time response to output data after detecting an SCK edge. For a non-volatile memory with tvalid = 12ns Max, fSPCKMax = 9.8 MHz @ VDDIO > 2.7V • Slave Mode fSCKmax = 1/2*(tSOV + tsu), where tsu is the setup time from the master before sampling data. With a perfect master (tsu=0), fSPCKMax = 16.3MHz @ VDDIO > 2.7V SAM L10/L11 Family Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1165 47. 125°C Electrical Characteristics This section provides an overview of the SAM L10 and SAM L11 electrical characteristics, which are specific for devices running up to 125ºC. 47.1 Disclaimer All typical values are measured at T = 25°C unless otherwise specified. All minimum and maximum values are valid across operating temperature and voltage unless otherwise specified. 47.2 General Operating Ratings The device must operate within the ratings listed in the following table for all other electrical characteristics and typical characteristics of the device to be valid. Table 47-1. General Operating Conditions Symbol Description Min. Typ. Max. Units VDDIO IO Supply Voltage 1.62 3.3 3.63 V VDDANA Analog supply voltage 1.62 3.3 3.63 V TA Temperature range -40 25 125 °C TJ Junction temperature - - 145 °C 47.3 Power Consumption The values in this section are measured values of power consumption under the following conditions, except where noted: • Operating Conditions – VDDIO = 3.3V or 1.8V – CPU is running on Flash with required Wait states, as recommended in the NVM Characteristics section. – Low power cache is enabled – BOD33 is disabled – I/Os are configured with digital input trigger disabled (default Reset configuration) • Oscillators – XOSC (crystal oscillator) stopped – XOSC32K (32.768 kHz crystal oscillator) running with external 32.768 kHz crystal – When in active PL2 mode on FDPLL96M at 32 MHZ, DPLL is using XOSC32K as reference clock and running at 32 MHz – When in Active mode on DFLLULP, the DFLLULP is configured in Closed Loop mode using XOSC32K as reference clock and MCLK.CTRLA.CKSEL = 1 SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1166 Table 47-2. Active Current Consumption Mode Conditions Regulator PL CPU Clock Vcc Ta Typ. Max. Units ACTIVE COREMARK / FIBONACCI LDO PL0 DFLLUP at 8 MHz 1.8V Max at 125°C Typ at 25°C 64.1 129 uA/MHz 3.3V 64.4 131 OSC 8 MHz 1.8V 66.6 130 3.3V 70.3 132 OSC 4 MHz 1.8V 74.1 203 3.3V 77.8 206 PL2 FDPLL96 at 32 MHz 1.8V 82.0 98 3.3V 82.5 99 DFLLULP at 32 MHz 1.8V 75.8 109 3.3V 75.8 107 BUCK PL0 DFLLUP at 8 MHz 1.8V 40.0 84 3.3V 25.3 54 OSC 8 MHz 1.8V 43.8 84 3.3V 32.1 58 OSC 4 MHz 1.8V 50.3 131 3.3V 38.9 92 PL2 FDPLL96 at 32 MHz 1.8V 59.9 70 3.3V 35.3 43 DFLLULP at 32 MHz 1.8V 55.3 78 3.3V 32.6 46 WHILE1 LDO PL0 DFLLUP at 8 MHz 1.8V 44.3 110 3.3V 44.4 111 OSC 8 MHz 1.8V 47.6 111 3.3V 50.1 113 OSC 4 MHz 1.8V 54.6 184 3.3V 57.7 187 PL2 FDPLL96 at 32 MHz 1.8V 56.9 79 3.3V 57.2 80 DFLLULP at 32 MHz 1.8V 50.8 72 3.3V 51.0 72 SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1167 Mode Conditions Regulator PL CPU Clock Vcc Ta Typ. Max. Units BUCK PL0 DFLLUP at 8 MHz 1.8V 28.1 72 3.3V 18.5 47 OSC 8 MHz 1.8V 32.2 73 3.3V 25.3 51 OSC 4 MHz 1.8V 38.4 121 3.3V 31.9 86 PL2 FDPLL96 at 32 MHz 1.8V 41.5 55 3.3V 24.6 34 DFLLULP at 32 MHz 1.8V 37.1 53 3.3V 22.0 32 IDLE LDO PL0 DFLLUP at 8 MHz 1.8V 16.0 81 3.3V 16.2 82 OSC 8 MHz 1.8V 19.8 82 3.3V 22.0 85 OSC 4 MHz 1.8V 26.2 152 3.3V 29.2 157 PL2 FDPLL96 at 32 MHz 1.8V 20.3 54 3.3V 20.4 54 DFLLULP at 32 MHz 1.8V 14.3 32 3.3V 14.4 33 BUCK PL0 DFLLUP at 8 MHz 1.8V 11.1 52 3.3V 8.3 35 OSC 8 MHz 1.8V 15.5 55 3.3V 15.2 40 OSC 4 MHz 1.8V 21.3 100 3.3V 21.6 73 PL2 FDPLL96 at 32 MHz 1.8V 14.9 30 3.3V 9.1 19 DFLLULP at 32 MHz 1.8V 10.6 24 3.3V 6.7 15 SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1168 Table 47-3. Standby and Off Mode Current Consumption Mode Conditions Regulator Mode Vcc Ta Typ. Max. Units STANDBY All 16kB RAM retained, PDSW domain in active state LPEFF Disable 1,8V 25°C 1.3 3.5 µA 125°C 121.7 304.8 LPEFF Enable 3,3V 25°C 1.1 3.0 125°C 74.5 282.6 BUCK in standby PL0 (VREG.RUNSTDBY=1 and VREG.STDBYPL0=1) 1,8V 25°C 1.2 2.9 125°C 78.0 188.7 3,3V 25°C 1.1 2.2 125°C 50.9 122.9 μA All 16kB RAM retained, PDSW domain in retention LPEFF Disable 1,8V 25°C 0.6 1.1 125°C 27.1 81.0 LPEFF Enable 3,3V 25°C 0.5 1.0 125°C 23.1 52.8 BUCK in standby PL0 (VREG.RUNSTDBY=1 and VREG.STDBYPL0=1) 1,8V 25°C 0.8 1.1 125°C 23.0 53.7 3,3V 25°C 0.8 1.5 125°C 17.3 37.6 12 kB RAM retained,PDSW domain in retention LPEFF Disable 1,8V 25°C 0.6 1.1 125°C 25.5 73.7 LPEFF Enable 3,3V 25°C 0.5 1.0 125°C 21.6 48.8 Buck in standby PL0 (VREG.RUNSTDBY=1 and VREG.STDBYPL0=1) 1,8V 25°C 0.7 1.1 125°C 21.5 50.5 3,3V 25°C 0.8 1.5 125°C 16.4 35.4 8kB RAM retained,PDSW domain in retention LPEFF Disable 1,8V 25°C 0.5 1.0 μA 125°C 23.8 67.1 LPEFF Enable 3,3V 25°C 0.5 0.9 125°C 20.2 45.4 BUCK in standby PL0 (VREG.RUNSTDBY=1 and VREG.STDBYPL0=1) 1,8V 25°C 0.7 1.0 125°C 19.9 46.5 3,3V 25°C 0.7 1.4 SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1169 Mode Conditions Regulator Mode Vcc Ta Typ. Max. Units 125°C 15.5 33.2 4kB RAM retained,PDSW domain in retention LPEFF Disable 1,8V 25°C 0.5 0.9 125°C 22.0 58.9 LPEFF Enable 3,3V 25°C 0.5 0.9 125°C 18.7 41.5 BUCK in standby PL0 (VREG.RUNSTDBY=1 and VREG.STDBYPL0=1) 1,8V 25°C 0.7 1.0 125°C 18.4 42.7 μA 3,3V 25°C 0.8 1.5 125°C 14.6 31.0 4kB RAM retained,PDSW domain in retention and RTC running on XOSC32k LPEFF Disable 1,8V 25°C 0.9 1.3 125°C 22.6 59.8 LPEFF Enable 3,3V 25°C 0.8 1.2 125°C 19.3 42.1 BUCK in standby PL0 (VREG.RUNSTDBY=1 and VREG.STDBYPL0=1) 1,8V 25°C 1.0 1.3 125°C 19.0 43.3 3,3V 25°C 1.1 1.7 125°C 15.2 31.6 OFF 1,8V 25°C 34.6 54.4 nA 125°C 4385.0 8291.5 3,3V 25°C 61.2 89.1 125°C 5489.5 10564.7 47.4 Analog Characteristics 47.4.1 Brown-Out Detectors (BOD) Characteristics Table 47-4. BOD33 Characteristics with BOD33.VREFSEL = 0 Symbol Parameters Conditions Min. Typ. Max. Unit VBOD+ (2) BOD33 high threshold level BOD33.LEVEL = 6 1.66 1.68 1.70 V BOD33.LEVEL = 7 1.70 1.72 1.74 BOD33.LEVEL = 39 2.79 2.84 2.89 SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1170 Symbol Parameters Conditions Min. Typ. Max. Unit BOD33.LEVEL = 48 3.11 3.18 3.20 VBOD- / VBOD(2) BOD33 low threshold level BOD33.LEVEL = 6 1.61 1.64 1.65 BOD33.LEVEL = 7 1.65 1.67 1.68 BOD33.LEVEL = 39 2.74 2.78 2.80 BOD33.LEVEL = 48 3.04 3.09 3.11 - Step size 34 mV VHys Hysteresis (VBOD+ - VBOD-) BOD33.LEVEL = 0x0 to 0x3F 30 - 180 mV Tstart Startup time(1) time from enable to RDY - 3.2 - us Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. 2. With BOD33.VREF_SEL = 0 and no hysteresis configured, BOD levels can be given as: VBOD+ = VBOD- = 1.43 + BOD Setting * Step_size Table 47-5. BOD33 Characteristics with BOD33.VREFSEL = 1 Symbol Parameters Conditions Min. Typ. Max. Unit VBOD + (2) - BOD33.LEVEL = 17 1.62 1.70 1.79 V BOD33.LEVEL = 18 1.65 1.73 1.81 BOD33.LEVEL = 59 2.86 2.96 3.09 BOD33.LEVEL = 63 2.97 3.08 3.20 VBOD- / VBOD(2) - BOD33.LEVEL = 17 1.59 1.65 1.72 V BOD33.LEVEL = 18 1.62 1.68 1.75 BOD33.LEVEL = 59 2.73 2.83 2.94 SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1171 Symbol Parameters Conditions Min. Typ. Max. Unit BOD33.LEVEL = 63 2.83 2.94 3.06 - Step size 28 mV VHys Hysteresis (VBOD + - VBOD-) BOD33.LEVEL = 0x0 to 0x3F 30 - 150 mV Tstart Startup time(1) Time from enable to RDY - 3.2 - us Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. 2. With BOD33.VREF_SEL = 0 and no hysteresis configured, BOD levels can be given as: Vbod+ = Vbod- = 1.17 + Bod setting * Step_size Table 47-6. Power Consumption Symb ol Parameters Conditions Ta Min. Typ. Max. Units IDD IDLE, Mode CONT VCC = 1.8V Max 125°C Typ 25°C - 17.4 21.8 µA VCC = 3.3V - 28.5 37.5 IDLE, Mode SAMPL VCC = 1.8V - 0.02 0.17 VCC = 3.3V - 0.04 0.13 STANDBY, Mode SAMPL VCC = 1.8V - 0.11 0.17 VCC = 3.3V - 0.23 0.29 47.4.2 Analog to Digital (ADC) Characteristics Table 47-7. Operating Conditions Symbol Parameters Conditions Min Typ Max Unit Res Resolution - - 12 bits Rs Sampling rate 10 - 1000 kSPS Differential mode Number of ADC clock cycles SAMPCTRL.OFFCOMP=1 resolution 12 bit (RESEL=0) - 16 - cycles resolution 10 bit (RESEL=2) 14 resolution 8 bit (RESEL=3) 12 Differential mode resolution 12 bit (RESEL=0) - SAMPLEN +13 - cycles SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1172 Symbol Parameters Conditions Min Typ Max Unit Number of ADC clock cycles SAMPCTRL.OFFCOMP=0 SAMPLEN corresponds to the decimal value of SAMPLEN[5:0] register resolution 10 bit (RESEL=2) SAMPLEN +11 resolution 8 bit (RESEL=3) SAMPLEN +9 Single-ended mode Number of ADC clock cycles SAMPCTRL.OFFCOMP=1 resolution 12 bit (RESEL=0) - 16 - cycles resolution 10 bit (RESEL=2) 15 resolution 8 bit (RESEL=3) 13 Single-ended mode Number of ADC clock cycles SAMPCTRL.OFFCOMP=0 SAMPLEN corresponds to the decimal value of SAMPLEN[5:0] register resolution 12 bit (RESEL=0) - SAMPLEN +13 - cycles resolution 10 bit (RESEL=2) SAMPLEN +12 resolution 8 bit (RESEL=3) SAMPLEN +10 fadc ADC Clock frequency 160 - 16000 kHz Ts Sampling time SAMPCTRL.OFFCOMP=1 250 - 25000 ns SAMPCTRL.OFFCOMP=0 76 - 7692 Sampling time with DAC as input (MUXPOS = 0x1C) SAMPCTRL.OFFCOMP=1 3000 - 25000 SAMPCTRL.OFFCOMP=0 3000 - 7692 Conversion range Diff mode - VREF - +VREF V Conversion range Single-ended mode 0 - VREF Vref Reference input 1 - VDDANA-0.6 V Vin Input channel range - 0 - VDDANA V Vcmin Input common mode voltage For Vref > 1.0V 0.7 - VREF-0.7 V For Vref=1.0V 0.3 - VREF-0.3 V CSAMPLE (1) Input sampling capacitance - 2.8 3.2 pF RSAMPLE (1) Input sampling onresistance - - 1715 Ω Rref (1) Reference input source resistance REFCOMP = 1 - - 5 kΩ SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1173 Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. Table 47-8. Differential Mode (1) Symbol Parameter s Conditions Measurements Unit Min Typ Max ENOB Effective Number of bits Fadc = 1Msps Vref=2.0V Vddana=3. 0V 9.1 10.2 10.8 bits Vref=1.0V Vddana=1. 6V to 3.6V 9.0 10.1 10.6 Vref=Vdda na=1.6V to 3.6V 8.9 9.9 11.0 Bandgap Reference, Vddana=1. 6V to 3.6V 9.0 9.8 10.6 TUE Total Unadjusted Error without offset and gain compensati on Vref=Vdda na=1.6V to 3.6V - 7 32 LSB INL Integral Non Linearity without offset and gain compensati on Vref=Vdda na=1.6V to 3.6V - +/-1.9 +/-4.8 DNL Differential Non Linearity without offset and gain compensati on Vref=Vdda na=1.6V to 3.6V - +0.94/-1 +1.85/-1 Gain Gain Error without gain compensati on Vref=1V Vddana=1. 6V to 3.6V - +/-0.38 +/-1.9 % Vref=3V Vddana=1. 6V to 3.6V - +/-0.14 +/-0.9 Bandgap Reference - +/-0.64 +/-5.4 SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1174 Symbol Parameter s Conditions Measurements Unit Min Typ Max Vref=Vdda na=1.6V to 3.6V - +/-0.15 +/-0.9 Offset Offset Error without offset compensati on Vref=1V Vddana=1. 6V to 3.6V - +/-0.13 +/-15.8 mV Vref=3V Vddana=1. 6V to 3.6V - +/-1.82 +/-14.9 Bandgap Reference - +/-2.07 +/-15.8 Vref=Vdda na=1.6V to 3.6V - +/-1.82 +/-15.3 SFDR Spurious Free Dynamic Range Fs = 1MHz / Fin = 13 kHz / Full range Input signal Vref=2.0V Vddana=3. 0V 58.1 70.5 77.5 dB SINAD Signal to Noise and Distortion ratio 56.7 63.4 66.5 SNR Signal to Noise ratio 56.5 64.4 67.1 THD Total Harmonic Distortion -74.7 -68.7 -57.7 Noise RMS External Reference voltage External Reference voltage - 0.42 - mV Note:  1. These are given without any ADC oversampling and decimation features enabled. SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1175 Table 47-9. Single Ended Mode (1) Symbol Parameter s Conditions Measurements Unit Min Typ Max ENOB Effective Number of bits Fadc = 1Msps Vref=2.0V Vddana=3. 0V 8.0 9.3 9.7 bits Vref=1.0V Vddana=1. 6V to 3.6V 7.9 8.2 9.4 Vref=Vdda na=1.6V to 3.6V 8.6 9.2 9.9 Bandgap Reference, Vddana=1. 6V to 3.6V 7.8 8.4 8.9 TUE Total Unadjusted Error without offset and gain compensati on Vref=2.0V Vddana=3. 0V - 12 66 LSB INL Integral Non Linearity without offset and gain compensati on Vref=2.0V Vddana=3. 0V - +/-3.4 +/-9.1 DNL Differential Non Linearity without offset and gain compensati on Vref=2.0V Vddana=3. 0V - +0.9/-1 +1.8/-1 Gain Gain Error without gain compensati on Vref=1V Vddana=1. 6V to 3.6V - +/-0.3 +/-5.1 % Vref=3V Vddana=1. 6V to 3.6V - +/-0.3 +/-5.1 Bandgap Reference - +/-0.4 +/-5.1 Vref=Vdda na=1.6V to 3.6V - +/-0.2 +/-0.8 SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1176 Symbol Parameter s Conditions Measurements Unit Min Typ Max Offset Offset Error without offset compensati on Vref=1V Vddana=1. 6V to 3.6V - +/-2.6 +/-48 mV Vref=3V Vddana=1. 6V to 3.6V - +/-2.6 +/-48 Bandgap Reference - +/-1.3 +/-35 Vref=Vdda na=1.6V to 3.6V - +/-1.8 +/-38 SFDR Spurious Free Dynamic Range Fs = 1MHz / Fin = 13 kHz / Full range Input signal Vref=2.0V Vddana=3. 0V 56.1 63.8 72.6 dB SINAD Signal to Noise and Distortion ratio 50.0 57.7 60.1 SNR Signal to Noise ratio 51.9 58.3 59.8 THD Total Harmonic Distortion -72.5 -62.4 -52.3 Noise RMS External Reference voltage External Reference voltage - 0.80 - mV Note:  1. These are given without any ADC oversampling and decimation features enabled. Figure 47-1. ADC Analog Input AINx The minimum sampling time tsamplehold for a given Rsource can be found using this formula: ݐsamplehold ≥ ܴsample + ܴsource × ܥsample × ݊ + 2 × ln 2 SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1177 For 12-bit accuracy: ݐsamplehold ≥ ܴsample + ܴsource × ܥsample × 9.7 where ݐsamplehold = 1 2 × ݂ADC . 47.4.3 Digital-to-Analog Converter (DAC) Characteristics Table 47-10. Operating Conditions (1) Symbol Parameters Conditions Min Typ Max Unit AVREF External reference voltage 1 - VDDANA-0.6 V Internal reference voltage 1 - 1 - V Internal reference voltage 2 - VDDANA - V Linear output voltage range 0.05 - VDDANA-0.05 V Minimum resistive load 5 - - kOhm Maximum capacitance load - - 100 pF IDD DC supply current(2) Voltage pump disabled - 175 270 µA Note:  1. The values in this table are based on specifications otherwise noted. 2. These values are based on characterization. These values are not covered in test limits in production. Table 47-11. Clock and Timing (1) Symbol Parameter Conditions Min. Typ. Max. Units Conversion rate Cload=100pF Rload > 5 kOhm Normal mode - - 350 ksps For DDATA=+/-1 - - 1000 Startup time VDDANA > 2.6V VDDANA > 2.6V - - 2.85 µs VDDANA < 2.6V VDDANA < 2.6V - - 10 µs Note:  1. These values are based on simulation. These values are not covered by test limits in production or characterization. Table 47-12. Accuracy Characteristics (1) Symbol Parameter Conditions Min. Typ. Max. Units RES Input resolution - - 10 Bits INL Integral non-linearity VREF= Ext 1.0V VDD = 1.62V +/-0,2 +/-0,5 +/-1.4 LSB VDD = 3.63V +/-0,2 +/-0,4 +/-1,2 VREF = VDDANA VDD = 1.62V +/-0,2 +/-0,6 +/-2.1 VDD = 3.63V +/-0,2 +/-0,5 +/-1,9 SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1178 Symbol Parameter Conditions Min. Typ. Max. Units VREF= INT1V VDD = 1.62V +/-0,4 +/-0,7 +/-4.2 VDD = 3.63V +/-0,4 +/-0,8 +/-6 DNL Differential non-linearity VREF= Ext 1.0V VDD = 1.62V +/-0,1 +/-0,3 +/-2 LSB VDD = 3.63V +/-0,1 +/-0,3 +/-1.5 VREF= VDDANA VDD = 1.62V +/-0,1 +-0,2 +/-3.0 VDD = 3.63V +/-0,1 +/-0,2 +/-1.6 VREF= INT1V VDD = 1.62V +/-0,3 +/-0,6 +/-4.3 VDD = 3.63V +/-0,3 +/-0,8 +/-7 Gain error VREF= Ext 1.0V - +/-4 +/-16 mV VREF= VDDANA - +/-12 +/-60 mV VREF= INT1V - +/-1 +/-23 mV Offset error VREF= Ext 1.0V - +/-1 +/-13 mV VREF= VDDANA - +/-2.5 +/-32 mV VREF= INT1V - +/-1.5 +/-30 mV Note:  1. All values measured using a conversion rate of 350ksps. 47.4.4 Analog Comparator Characteristics Table 47-13. Electrical and Timing (1) Symbol Parameters Conditions Min. Typ Max. Unit PNIVR Positive and Negative input range voltage 0 - VDDANA V ICMR Input common mode range 0 - VDDANA-0.1 V Off Offset COMPCTRLn.SPEED=0x0 -70 -4.5/+1.5 70 mV COMPCTRLn.SPEED=0x1 -55 -4.5/+1.5 55 COMPCTRLn.SPEED=0x2 -48 -4.5/+1.5 48 COMPCTRLn.SPEED=0x3 -42 -4.5/+1.5 42 VHys Hysteresis COMPCTRLn.HYST=0x0 10 45 79 mV COMPCTRLn.HYST=0x1 22 70 115 COMPCTRLn.HYST=0x2 37 90 138 COMPCTRLn.HYST=0x3 49 105 159 SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1179 Symbol Parameters Conditions Min. Typ Max. Unit Tpd Propagation Delay Vcm=Vddana/2, Vin= +-100mV overdrive from VCM COMPCTRLn.SPEED=0x0 - 4 12.3 µs COMPCTRLn.SPEED=0x1 - 0.97 2.6 COMPCTRLn.SPEED=0x2 - 0.56 1.4 COMPCTRLn.SPEED=0x3 - 0.33 0.77 Tstart Start-up time COMPCTRLn.SPEED=0x0 - 17 71 µs COMPCTRLn.SPEED=0x1 - 0.85 4.5(1) COMPCTRLn.SPEED=0x2 - 0.55 3.2(1) COMPCTRLn.SPEED=0x3 - 0.45 2.7(1) Vscale INL - 0.4 - LSB DNL - 0.1 - Offset Error - 0.1 - Gain Error - 1.3 - Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. Table 47-14. Power Consumption Symbol Parameters Conditions Ta Min. Typ Max. Unit IDDANA Current consumption VCM=VDDANA/2, +/-100mV overdrive from VCM, Voltage scaler disabled COMPCTRLn.SPEED=0x0, VDDANA=3.3V Max.125°C Typ.25°C - 51 232 nA COMPCTRLn.SPEED=0x1, VDDANA=3.3V - 233 604 COMPCTRLn.SPEED=0x2, VDDANA=3.3V - 456 1009 COMPCTRLn.SPEED=0x3, VDDANA=3.3V - 879 1756 Current consumption Voltage Scaler only VDDANA=3.3V - 13 19 µA 47.4.5 DETREF Characteristics Table 47-15. Reference Voltage Characteristics Symbol Parameter Conditions Min. Typ. Max. Units ADC/DAC Ref ADC/DAC internal reference nom. 1.0V, VCC=3.0V, T= 25°C 0.976 1.0 1.022 V nom. 1.1V, VCC=3.0V, T= 25°C 1.077 1.1 1.127 nom. 1.2V, VCC=3.0V, T= 25°C 1.174 1.2 1.234 SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1180 Symbol Parameter Conditions Min. Typ. Max. Units nom. 1.25V, VCC=3.0V, T= 25°C 1.221 1.25 1.287 nom. 2.0V, VCC=3.0V, T= 25°C 1.945 2.0 2.030 nom. 2.2V, VCC=3.0V, T= 25°C 2.143 2.2 2.242 nom. 2.4V, VCC=3.0V, T= 25°C 2.335 2.4 2.457 nom. 2.5V, VCC=3.0V, T= 25°C 2.428 2.5 2.563 Ref Temperature coefficient drift over [-40, +25]°C - -0.01/+0.015 - %/°C drift over [+25, +125]°C - -0.006/+0.003 - Ref Supply coefficient drift over [1.6, 3.63]V - +/-0.35 - %/V AC Ref AC Ref Accuracy VCC=3.0V, T=25°C 1.086 1.1 1.128 V Ref Temperature coefficient drift over [-40, +25]°C - +/-0.01 - %/°C drift over [+25, +125]°C - -0.005/+0.001 - %/°C Ref Supply coefficient drift over [1.6, 3.63]V - -0.35/+0.35 - %/V 47.4.6 OPAMP Characteristics Table 47-16. Power Consumption(1) Symbol Parameters Conditions Ta Min. Typ. Max. Unit IDD DC supply current (Voltage Doubler OFF) Mode 3,VCC =3.3V Max 125°C Typ 25°C - 235 415 μA Mode 2,VCC =3.3V - 94 173 Mode 1,VCC =3.3V - 26 50 Mode 0 ,VCC =3.3V - 7 14 Voltage Doubler consumption VCC =3.3V - 0.70 1.5 Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. 47.4.7 Peripheral Touch Controller (PTC) Characteristics Power Consumption The values in the Power Consumption table below are measured values of power consumption under the following conditions: Operating Conditions • VDD = 3.3V Clocks • OSC16M divided to 4MHz used as main clock source SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1181 • CPU is running on Flash with 0 wait states, at 4MHz • PTC running at 4MHz • Voltage Regulator mode: LPEFF enabled PTC Configuration • Mutual-Capacitance mode • One touch channel System Configuration • Standby Sleep mode enabled • RTC running on OSCULP32K: used to define the PTC scan rate, through the event system • Drift Calibration disabled: no interrupts, PTC scans are performed in Standby mode • Drift Calibration enabled: RTC interrupts (wake-up) the CPU to perform PTC scans. PTC drift calibration is performed every 1.5 sec. Table 47-17. Power Consumption (1) Symbol Parameters Drift Calibration PTC scan rate (msec) Oversamples Ta Typ. Max. Units IDD Current Consumption Disabled 10 4 Max 125°C Typ 25°C 6.2 292.0 µA 16 12.7 300.5 50 4 2.3 286.1 16 3.7 290.3 100 4 1.7 286.1 16 2.4 286.2 200 4 1.4 285.5 16 1.8 286.2 Enabled 10 4 8.3 293.9 16 14.2 304.9 50 4 3.0 289.2 16 4.8 290.5 100 4 2.3 289.2 16 2.8 289.5 200 4 1.9 287.9 16 2.4 289.0 Note:  1. These are based on characterization. SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1182 47.5 Oscillators Characteristics 47.5.1 Crystal Oscillator (XOSC) Characteristics Table 47-18. Power Consumption Symbol Parameter Conditions Ta Min. Typ. Max. Units IDD Current consumption F=2MHz - CL=20pF XOSC,GAIN=0, VCC=3.3V AMPGC=OFF Max 125°C Typ 25°C - 66 106 µA AMPGC=ON - 62 107 F=4MHz - CL=20pF XOSC,GAIN=1, VCC=3.3V AMPGC=OFF - 107 164 AMPGC=ON - 70 132 F=8MHz - CL=20pF XOSC,GAIN=2, VCC=3.3V AMPGC=OFF - 200 307 AMPGC=ON - 118 180 F=16MHz - CL=20pF XOSC,GAIN=3, VCC=3.3V AMPGC=OFF - 436 630 AMPGC=ON - 247 382 F=32MHz - CL=20pF XOSC,GAIN=4, VCC=3.3V AMPGC=OFF - 1303 2251 AMPGC=ON - 627 1116 47.5.2 External 32KHz Crystal Oscillator (XOSC32K) Characteristics Table 47-19. Power Consumption Symbol Parameter Conditions Ta Min. Typ. Max. Units IDD Current consumption VCC=3.3V Max 125°C Typ 25°C - 309 767 nA 47.5.3 Ultra Low-Power Internal 32 kHz RC Oscillator (OSCULP32K) Characteristics Table 47-20. Ultra Low-Power Internal 32 kHz RC Oscillator Electrical Characteristics Symbol Parameter Conditions Min. Typ. Max. Units FOUT Output frequency at 25°C, at VDDIO=3.3V 30.84 32.768 34.51 kHz at 25°C, over [1.62, 3.63]V 30.84 32.768 34.74 kHz over[-40,+125]°C, over [1.62, 3.63]V 25.17 32.768 41.76 kHz Duty Duty Cycle - 50 - % 47.5.4 16 MHz RC Oscillator (OSC16M) Characteristics Table 47-21. Multi-RC Oscillator Electrical Characteristics Symbol Parameter Conditions Min. Typ. Max. Units FOUT Output frequency VDD=3.3V, T=25°C 3.96 4.00 4.04 MHz SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1183 Symbol Parameter Conditions Min. Typ. Max. Units Calibrated against a 4/8/12/16 MHz reference 7.92 8.00 8.08 11.88 12.00 12.12 15.84 16.00 16.16 TempDrift Freq vs. temperature drift VDD=3.3V over temperature [-40°C-125°C], versus calibration reference at 25°C -5 5 % SupplyDrift Freq vs. supply drift Temperature =25°C over voltage [1.62V-3.63V], versus calibration reference at 3.3V -1.5 1.5 TWUP(2) Wake up time - 1st clock edge after enable FOUT = 4MHz - 0.13 0.32 µs FOUT = 8MHz - 0.13 0.31 FOUT = 12MHz - 0.13 0.31 FOUT = 16MHz - 0.13 0.31 TSTARTUP(2) Startup time FOUT = 4MHz - 1.16 2.96 µs FOUT = 8MHz - 1.29 2.74 FOUT = 12MHz - 1.34 2.95 FOUT = 16MHz - 1.39 3.11 Duty(1) Duty Cycle - 45 50 55 % Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. 2. These values are based on characterization. These values are not covered in test limits in production. Table 47-22. Power Consumption Symbol Parameter Conditions Ta Min. Typ. Max. Units IDD Current consumption Fout=4MHz, VCC=3.3V Max.125°C Typ.25°C - 73 370 µA Fout=8MHz, VCC=3.3V - 106 400 Fout=12MHz, VCC=3.3V - 135 425 Fout=16MHz, VCC=3.3V - 166 455 SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1184 47.5.5 Digital Frequency Locked Loop (DFLLULP) Characteristics Table 47-23. Power Consumption(1) Symbol Parameters Conditions Ta Min. Typ. Max Units IDD Current Consumption Fout = 8 MHz (PL0) - VCC = 3.3V Max 125°C Typ 25°C - 33 284 µA Fout = 32 MHz (PL2) - VCC=3.3V - 144 458 Note:  These characteristics are only applicable in LDO Regulator mode 47.5.6 Digital Phase Lock Loop (DPLL) Characteristics Table 47-24. Fractional Digital Phase Lock Loop(2) Symbol Parameter Min. Typ. Max. Unit FIN Input Clock Frequency 32 - 2000 kHz FOUT Output Clock Frequency PL2 32 - 96 MHz PL0 32 - 48 MHz Jp Period jitter PL0, Fin = 32 kHz, Fout = 32 MHz - 3 6 % PL2, = 32 kHz, Fout = 32 MHz - 2 6 PL0, Fin = 32 kHz, Fout = 48 MHz - 3 4 PL2, Fin = 32 kHz, Fout = 48 MHz - 2 6 PL2, Fin = 32 kHz, Fout = 96 MHz - 3 4 PL0, Fin = 32 kHz, Fout = 32 MHz - 3 5 PL2, Fin = 32 kHz, Fout = 32 MHz - 3 6 PL0, Fin = 2 MHz, Fout = 48 MHz - 5 7 PL2, Fin = 2 MHz, Fout = 48 MHz - 3 6 PL2, Fin= 2 MHz, Fout= 96 MHz - 4 10 tLOCK Lock Time After startup, time to get lock signal Fin = 32 kHz, Fout = 96 MHz - 1.1 1.5 ms After startup, time to get lock signal Fin = 2 MHz, Fout = 96 MHz - 24 35 µs Duty Duty cycle (1) 40 50 60 % Note:  1. These values are based on simulation. They are not covered by production test limits or characterization. 2. These characteristics are applicable only in LDO Regulator mode and with a XOSC or XOSC32K reference. SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1185 Table 47-25. Power Consumption(1) Symbol Parameter Conditions TA Min. Typ. Max. Units IDD Current Consumption Fout = 48 MHz (PL0) - VDD = 3.3V Max. 125°C Typ. 25°C - 339 618 µA Fout = 96 MHz (PL2) - VDD = 3.3V - 678 1005 Note:  These characteristics are only applicable in LDO regulator mode. 47.6 Timing Characteristics 47.6.1 SERCOM in SPI Mode in PL0 Table 47-26. SPI Timing Characteristics and Requirements (1) Symbol Parameter Conditions Min. Typ. Max. Units tSCK SCK period when tSOV=0 on the slave side Master Reception 2*(tMIS +tSLAVE_OUT) (3) - - ns Master Transmission 2*(tMOV +tSLAVE_IN) (4) - - tSCKW SCK high/low width Master - 0,5*tSCK - tSCKR SCK rise time(2) Master - 0,25*tSCK - tSCKF SCK fall time(2) Master - 0,25*tSCK - tMIS MISO setup to SCK Master, VDD>2,70V 86 - - Master, VDD>1,62V 95 - - tMIH MISO hold after SCK Master, VDD>2,70V 0 - - Master, VDD>1,62V 0 - - tMOV MOSI output valid after SCK Master, VDD>2,70V - - 33.3 ns Master, VDD>1,62V - - 49.6 tMOH MOSI hold after SCK Master, VDD>2,70V 9.7 - - tMOH MOSI hold after SCK Master, VDD>1,62V 9.7 - - tSSCK Slave SCK Period when tMIS=0 on the master side Slave Reception 2*(tSIS +tMASTER_OUT) (5) - - Slave Transmission 2*(tSOV +tMASTER_IN) (6) - - tSSCKW SCK high/low width Slave - 0,5*tSCK - SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1186 Symbol Parameter Conditions Min. Typ. Max. Units tSSCKR SCK rise time(2) Slave - 0,25*tSCK - tSSCKF SCK fall time(2) Slave - 0,25*tSCK - tSIS MOSI setup to SCK Slave, VDD>2,70V 24.2 - - Slave, VDD>1,62V 24.9 - - tSIH MOSI hold after SCK Slave, VDD>2,70V 12.9 - - Slave, VDD>1,62V 13.5 - - tSSS SS setup to SCK Slave PRELOADEN=1 tSOSS+tEXT_MIS +2*tAPBC (8) (9) - - ns PRELOADEN=0 tSOSS+tEXT_MIS (8) - - tSSH SS hold after SCK Slave 0.5*tSSCK - - tSOV MISO output valid after SCK Slave, VDD>2,70V - - 66.9 Slave, VDD>1,62V - - 76.6 tSOH MISO hold after SCK Slave, VDD>2,70V 22.7 - - Slave, VDD>1,62V 20.3 - - tSOSS MISO setup after SS low Slave, VDD>2,70V - - 1* tSCK Slave, VDD>1,62V - - 1* tSCK tSOSH MISO hold after SS high Slave, VDD>2,70V 15 - - Slave, VDD>1,62V 15 - - Note:  1. These values are based on simulation. These values are not covered by test limits in production. 2. See I/O Pin Characteristics. 3. Where tSLAVE_OUT is the slave external device output response time, generally tEXT_SOV +tLINE_DELAY (See Note 7). 4. Where tSLAVE_IN is the slave external device input constraint, generally tEXT_SIS+tLINE_DELAY (See Note 7). 5. Where tMASTER_OUT is the master external device output response time, generally tEXT_MOV +tLINE_DELAY (See Note 7). 6. Where tMASTER_IN is the master external device input constraint, generally tEXT_MIS +tLINE_DELAY (See Note 7). 7. tLINE_DELAY is the transmission line time delay. 8. tEXT_MIS is the input constraint for the master external device. 9. tAPBC is the APB period for SERCOM. SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1187 Figure 47-2. SPI Timing Requirements in Master Mode Figure 47-3. SPI Timing Requirements in Slave Mode Maximum SPI Frequency • Master mode: fSCKmax = 1/2*(tMIS + tvalid), where tvalid is the slave time response to output data after detecting an SCK edge. For a non-volatile memory with tvalid = 12 ns Max, fSPCKMax = 3.7 MHz @ VDDIO > 2.7V • Slave mode: fSCKmax = 1/2*(tSOV + tsu), where tsu is the setup time from the master before sampling data. With a perfect master (tsu=0), fSPCKMax = 6 MHz @ VDDIO > 2.7V 47.6.2 SERCOM in SPI Mode in PL2 Table 47-27. SPI Timing Characteristics and Requirements (1) Symbol Parameter Conditions Min. Typ. Max. Units tSCK SCK period when tSOV=0 on the slave side Master Reception 2*(tMIS +tSLAVE_OUT) (3) - - ns Master Transmission 2*(tMOV +tSLAVE_IN) (4) - - tSCKW SCK high/low width Master - 0,5*tSCK - tSCKR SCK rise time(2) Master - 0,25*tSCK - SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1188 Symbol Parameter Conditions Min. Typ. Max. Units tSCKF SCK fall time(2) Master - 0,25*tSCK - tMIS MISO setup to SCK Master, VDD>2,70V 43.8 - - Master, VDD>1,62V 54.1 - - tMIH MISO hold after SCK Master, VDD>2,70V 0 - - ns Master, VDD>1,62V 0 - - tMOV MOSI output valid after SCK Master, VDD>2,70V - - 17.5 Master, VDD>1,62V - - 21.2 tMOH MOSI hold after SCK Master, VDD>2,70V 6.32 - - Master, VDD>1,62V 6.32 - - tSSCK Slave SCK Period when tMIS=0 on the master side Slave Reception 2*(tSIS +tMASTER_OUT) (5) - - Slave Transmission 2*(tSOV +tMASTER_IN) (6) - - tSSCKW SCK high/low width Slave - 0,5*tSCK - tSSCKR SCK rise time(2) Slave - 0,25*tSCK - tSSCKF SCK fall time(2) Slave - 0,25*tSCK - tSIS MOSI setup to SCK Slave, VDD>2,70V 10.7 - - ns Slave, VDD>1,62V 11.4 - - tSIH MOSI hold after SCK Slave, VDD>2,70V 6.4 - - Slave, VDD>1,62V 7.1 - - tSSS SS setup to SCK Slave PRELOADEN=1 tSOSS+tEXT_MIS +2*tAPBC (8) (9) - - PRELOADEN=0 tSOSS+tEXT_MIS (8) - - tSSH SS hold after SCK Slave 0.5*tSSCK - - tSOV MISO output valid after SCK Slave, VDD>2,70V - - 36.1 Slave, VDD>1,62V - - 46.4 tSOH MISO hold after SCK Slave, VDD>2,70V 13.4 - - SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1189 Symbol Parameter Conditions Min. Typ. Max. Units Slave, VDD>1,62V 13.4 - - tSOSS MISO setup after SS low Slave, VDD>2,70V - 1* tSCK Slave, VDD>1,62V - 1* tSCK tSOSH MISO hold after SS high Slave, VDD>2,70V 8.7 - - Slave, VDD>1,62V 8.7 - - Note:  1. These values are based on simulation. These values are not covered by test limits in production. 2. See I/O Pin Characteristics. 3. Where tSLAVE_OUT is the slave external device output response time, generally tEXT_SOV +tLINE_DELAY (See Note 7). 4. Where tSLAVE_IN is the slave external device input constraint, generally tEXT_SIS+tLINE_DELAY (See Note 7). 5. Where tMASTER_OUT is the master external device output response time, generally tEXT_MOV +tLINE_DELAY (See Note 7). 6. Where tMASTER_IN is the master external device input constraint, generally tEXT_MIS +tLINE_DELAY (See Note 7). 7. tLINE_DELAY is the transmission line time delay. 8. tEXT_MIS is the input constraint for the master external device. 9. tAPBC is the APB period for SERCOM. Figure 47-4. SPI Timing Requirements in Master Mode SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1190 Figure 47-5. SPI Timing Requirements in Slave Mode Maximum SPI Frequency • Master mode: fSCKmax = 1/2*(tMIS + tvalid), where tvalid is the slave time response to output data after detecting an SCK edge. For a non-volatile memory with tvalid = 12 ns Max, fSPCKMax = 9.8 MHz @ VDDIO > 2.7V • Slave mode: fSCKmax = 1/2*(tSOV + tsu), where tsu is the setup time from the master before sampling data. With a perfect master (tsu=0), fSPCKMax = 16.3 MHz @ VDDIO > 2.7V SAM L10/L11 Family 125°C Electrical Characteristics © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1191 48. AC and DC Characteristics Graphs 48.1 Typical Power Consumption over Temperature in Sleep Modes - 85°C Power Consumption in Standby Sleep Mode with PDSW in Active state Operating conditions: • VDDIO = 3.3V or 1.8V • No RTC running • BOD33 is disabled • LPVREG with LPEFF Enable • All 16 kB SRAM retained • PDSW Domain in Active state Figure 48-1. Power Consumption over Temperature in Standby Sleep Mode with PDSW in Active state Power Consumption in Standby Sleep Mode with PDSW in Retention state Operating conditions: • VDDIO = 3.3V or 1.8V • No RTC running • BOD33 is disabled • LPVREG with LPEFF Enable • All 16 kB SRAM retained • PDSW Domain in Retention state SAM L10/L11 Family AC and DC Characteristics Graphs © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1192 Figure 48-2. Power Consumption over Temperature in Standby Sleep Mode with PDSW in Retention state Power Consumption in Off Sleep Mode Operating conditions: • VDDIO = 3.3V or 1.8V Figure 48-3. Power Consumption over Temperature in Off Sleep Mode SAM L10/L11 Family AC and DC Characteristics Graphs © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1193 48.2 Typical Power Consumption over Temperature in Sleep Modes - 125°C Power Consumption in Standby Sleep mode with PDSW in Active state Operating conditions: • VDDIO = 3.3V or 1.8V • No RTC running • BOD33 is disabled • LPVREG with LPEFF Enable • All 16 kB SRAM retained • PDSW Domain in Active state Figure 48-4. Power Consumption over Temperature in Standby Sleep Mode with PDSW in Active state Power Consumption in Standby Sleep Mode with PDSW in Retention state Operating conditions: • VDDIO = 3.3V or 1.8V • No RTC running • BOD33 is disabled • LPVREG with LPEFF Enable • All 16 kB SRAM retained • PDSW Domain in Retention state SAM L10/L11 Family AC and DC Characteristics Graphs © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1194 Figure 48-5. Power Consumption over Temperature in Standby Sleep Mode with PDSW in Retention state Power Consumption in Off Sleep Mode Operating conditions: • VDDIO = 3.3V or 1.8V Figure 48-6. Power Consumption over Temperature in Off Sleep Mode SAM L10/L11 Family AC and DC Characteristics Graphs © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1195 49. Packaging Information 49.1 Package Marking Information All devices are marked with the Atmel logo, a shortened ordering code and additional marking (the two last lines) YYWW R ARM XXXXXX CC Where: • "Y" or "YY": Manufacturing Year (last OR two last digit(s)) • "WW": Manufacturing Week • "R": Revision • "XXXXXX": Lot number • "CC": Internal Code SAM L10/L11 Family Packaging Information © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1196 49.2 Package Drawings 49.2.1 32-pin TQFP Table 49-1. Device and Package Maximum Weight 100 mg Table 49-2. Package Characteristics Moisture Sensitivity Level MSL3 SAM L10/L11 Family Packaging Information © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1197 Table 49-3. Package Reference JEDEC Drawing Reference MS-026 JESD97 Classification E3 49.2.2 24-pin VQFN Table 49-4. Device and Package Maximum Weight 36 mg SAM L10/L11 Family Packaging Information © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1198 Table 49-5. Package Characteristics Moisture Sensitivity Level MSL1 Table 49-6. Package Reference JEDEC Drawing Reference MO-220 JESD97 Classification E3 49.2.3 32-pin VQFN SAM L10/L11 Family Packaging Information © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1199 Table 49-7. Device and Package Maximum Weight 90 mg Table 49-8. Package Characteristics Moisture Sensitivity Level MSL3 Table 49-9. Package Reference JEDEC Drawing Reference MO-220 JESD97 Classification E3 SAM L10/L11 Family Packaging Information © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1200 49.2.4 24-pin SSOP SAM L10/L11 Family Packaging Information © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1201 Table 49-10. Device and Package Maximum Weight 187.322 mg Table 49-11. Package Characteristics Moisture Sensitivity Level MSL3 Table 49-12. Package Reference JEDEC Drawing Reference MO-150 JESD97 Classification E3 SAM L10/L11 Family Packaging Information © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1202 49.2.5 32-pin WLCSP Table 49-13. Device and Package Maximum Weight 6.04 mg SAM L10/L11 Family Packaging Information © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1203 Table 49-14. Package Characteristics Moisture Sensitivity Level MSL1 Table 49-15. Package Reference JEDEC Drawing Reference N/A JESD97 Classification E1 49.3 Soldering Profile The following table gives the recommended soldering profile from J-STD-20. Table 49-16. Recommended 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-150s Time within 5°C of Actual Peak Temperature 30s Peak Temperature Range 260°C Ramp-down Rate 6°C/s max. Time 25°C to Peak Temperature 8 minutes max. A maximum of three reflow passes is allowed per component. SAM L10/L11 Family Packaging Information © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1204 50. Schematic Checklist 50.1 Introduction This chapter describes a common checklist which should be used when starting and reviewing the schematics for a SAM L10/L11 design. This chapter illustrates the recommended power supply connections, how to connect external analog references, programmer, debugger, oscillator and crystal. 50.2 Power Supply The SAM L10/L11 supports a single or dual power supply from 1.62V to 3.63V. The same voltage must be applied to both VDDIO and VDDANA. The internal voltage regulator has four different modes: • Linear mode: this mode does not require any external inductor. This is the default mode when CPU and peripherals are running • Switching mode (Buck): the most efficient mode when the CPU and peripherals are running • Low Power (LP) mode: This is the default mode used when the device is in Standby mode Selecting between switching mode and linear mode can be done by software on the fly, but the power supply must be designed according to which mode is to be used. 50.2.1 Power Supply Connections The following figures shows the recommended power supply connections for Switched/Linear mode and Linear mode only. SAM L10/L11 Family Schematic Checklist © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1205 Figure 50-1. Power Supply Connection for Switching/Linear Mode VDDANA VDDIO SAM L11 SAML10 VDDOUT (1.62V — 3.63V) Main Supply 100nF 100nF 10µF 10µF Close to device (for every pin) 10µH VDDCORE GND GNDANA 1µF 100nF Figure 50-2. Power Supply Connection for Linear Mode Only VDDANA VDDIO SAM L11 SAML10 VDDOUT (1.62V — 3.63V) Main Supply 100nF 100nF 10µF 10µF Close to device (for every pin) VDDCORE GND GNDANA 1µF 100nF SAM L10/L11 Family Schematic Checklist © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1206 Table 50-1. Power Supply Connections Signal Name Recommended Pin Connection Description VDDIO 1.62V to 3.63V Decoupling/filtering capacitors 100 nF(1,2) and 10 µF(1) Decoupling/filtering inductor 10 μH(1,3) Digital supply voltage VDDANA 1.62V to 3.63V Decoupling/filtering capacitors 100 nF(1,2) and 10 µF(1) Ferrite bead(4) prevents the VDD noise interfering with VDDANA Analog supply voltage VDDCORE 0.9V to 1.2V typical Decoupling/filtering capacitors 100 nF(1,2) and 1µF(1) Linear regulator mode: Core supply voltage output/external decoupling pin Switched regulator mode: Core supply voltage input, must be connected to VDDOUT via inductor VDDOUT Switching regulator mode: 10 µH inductor with saturation current above 150mA and DCR<1Ω Linear regulator mode: Not connected On-chip Switching mode regulator output GND Ground GNDANA Ground for the analog power domain 1. These values are only given as a typical example. 2. Decoupling capacitors should be placed close to the device for each supply pin pair in the signal group, low ESR capacitors should be used for better decoupling. 3. An inductor should be added between the external power and the VDD for power filtering. 4. A ferrite bead has better filtering performance compared to standard inductor at high frequencies. A ferrite bead can be added between the main power supply and VDDANA to prevent digital noise from entering the analog power domain. The bead should provide enough impedance (for example, 50Ω at 20MHz and 220Ω at 100MHz) to separate the digital and analog power domains. Make sure to select a ferrite bead designed for filtering applications with a low DC resistance to avoid a large voltage drop across the ferrite bead. 50.2.2 Special Considerations for QFN Packages The QFN package has an exposed paddle that must be connected to GND. 50.3 External Analog Reference Connections The following schematic checklist is only necessary if the application is using one or more of the external analog references. If the internal references are used instead, the circuits in the following two figures are not necessary. SAM L10/L11 Family Schematic Checklist © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1207 Figure 50-3. External Analog Reference Schematic With Two References GND VREFA EXTERNAL REFERENCE 1 4.7μF 100nF GND VREFB EXTERNAL REFERENCE 2 4.7μF 100nF Close to device (for every pin) Figure 50-4. External Analog Reference Schematic With One Reference GND VREFA EXTERNAL REFERENCE 4.7μF 100nF GND VREFB 100nF Close to device (for every pin) Table 50-2. External Analog Reference Connections Signal Name Recommended Pin Connection Description VREFx 1.0V to (VDDANA - 0.6V) for ADC 1.0V to (VDDANA - 0.15V) for DAC Decoupling/filtering capacitors 100nF(1)(2) and 4.7µF(1) External reference VREFx for the analog port GND Ground 1. These values are only given as a typical example. SAM L10/L11 Family Schematic Checklist © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1208 2. Decoupling capacitor should be placed close to the device for each supply pin pair in the signal group. 50.4 External Reset Circuit The external Reset circuit is connected to the RESET pin when the external Reset function is used. The circuit is not necessary when the RESET pin is not driven LOW externally by the application circuitry. The reset switch can also be removed, if a manual reset is not desired. The RESET pin itself has an internal pull-up resistor, hence it is optional to add any external pull-up resistor. Figure 50-5. External Reset Circuit Schematic GND RESET 2.2kΩ 100pF VDD 330Ω A pull-up resistor makes sure that the reset does not go low and unintentionally causing a device reset. An additional resistor has been added in series with the switch to safely discharge the filtering capacitor, i.e. preventing a current surge when shorting the filtering capacitor which again can cause a noise spike that can have a negative effect on the system. Table 50-3. Reset Circuit Connections Signal Name Recommended Pin Connection Description RESET Reset low level threshold voltage VDDIO = 1.62V - 2.0V: Below 0.33 * VDDIO VDDIO = 2.7V - 3.63V: Below 0.36 * VDDIO Decoupling/filter capacitor 100pF(1) Pull-up resistor 2.2kΩ(1,2) Resistor in series with the switch 330Ω(1) Reset pin 1. These values are only given as a typical example. 2. The SAM L10/L11 features an internal pull-up resistor on the RESET pin, hence an external pull-up is optional. SAM L10/L11 Family Schematic Checklist © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1209 50.5 Unused or Unconnected Pins For unused pins the default state of the pins will give the lowest current leakage. Thus there is no need to do any configuration of the unused pins in order to lower the power consumption. 50.6 Clocks and Crystal Oscillators The SAM L10/L11 can be run from internal or external clock sources, or a mix of internal and external sources. An example of usage can be to use the internal 16MHz oscillator as source for the system clock and an external 32.768kHz watch crystal as clock source for the Real-Time counter (RTC). 50.6.1 External Clock Source Figure 50-6. External Clock Source Schematic XOUT/GPIO XIN NC/GPIO External Clock Table 50-4. External Clock Source Connections Signal Name Recommended Pin Connection Description XIN XIN is used as input for an external clock signal Input for inverting oscillator pin XOUT/GPIO Can be left unconnected or used as normal GPIO NC/GPIO 50.6.2 Crystal Oscillator Figure 50-7. Crystal Oscillator Schematic XOUT XIN 15pF 15pF The crystal should be located as close to the device as possible. Long signal lines may cause too high load to operate the crystal, and cause crosstalk to other parts of the system. Table 50-5. Crystal Oscillator Checklist Signal Name Recommended Pin Connection Description XIN Load capacitor 15pF(1)(2) External crystal between 0.4 to 32MHz XOUT Load capacitor 15pF(1)(2) SAM L10/L11 Family Schematic Checklist © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1210 1. These values are only given as a typical example. 2. The capacitors should be placed close to the device for each supply pin pair in the signal group. 50.6.3 External Real Time Oscillator The low frequency crystal oscillator is optimized for use with a 32.768 kHz watch crystal. When selecting crystals, load capacitance and the crystal’s Equivalent Series Resistance (ESR) must be taken into consideration. Both values are specified by the crystal vendor. SAM L10/L11 oscillator is optimized for very low power consumption, hence close attention should be made when selecting crystals. The typical parasitic load capacitance values are available in the Electrical Characteristics chapters. This capacitance and PCB capacitance can allow using a crystal inferior to 12.5 pF load capacitance without external capacitors as shown in the following figure. Figure 50-8. External Real Time Oscillator without Load Capacitor XOUT32 XIN32 32.768kHz To improve accuracy and Safety Factor, the crystal data sheet can recommend adding external capacitors, as shown in the following figure. To find suitable load capacitance for a 32.768 kHz crystal, consult the crystal data sheet. Figure 50-9. External Real Time Oscillator with Load Capacitor XOUT32 XIN32 32.768kHz 12pF 12pF Table 50-6. External Real Time Oscillator Checklist Signal Name Recommended Pin Connection Description XIN32 Load capacitor 12 pF(1,2) Timer oscillator input XOUT32 Load capacitor 12 pF(1,2) Timer oscillator output 1. These values are only given as typical examples. 2. The capacitors should be placed close to the device for each supply pin pair in the signal group. Note:  To minimize the cycle-to-cycle jitter of the external oscillator, keep the neighboring pins as steady as possible. For neighboring pin details, refer to 4.2 Oscillators Pinout. SAM L10/L11 Family Schematic Checklist © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1211 50.6.4 Calculating the Correct Crystal Decoupling Capacitor The model shown in the following figure can be used to calculate correct load capacitor for a given crystal. This model includes internal capacitors CLn, external parasitic capacitance CELn and external load capacitance CPn. Figure 50-10. Crystal Circuit With Internal, External and Parasitic Capacitance XOUT Internal CEL1 CL1 CL2 CP1 CP2 CEL2 External XIN Using this model the total capacitive load for the crystal can be calculated as shown in the equation below: = totܥ EL2ܥ + 2ܲܥ + 2ܮܥ EL1ܥ + 1ܲܥ + 1ܮܥ EL2ܥ + 2ܲܥ + 2ܮܥ + EL1ܥ + 1ܲܥ + 1ܮܥ where Ctot is the total load capacitance seen by the crystal. This value should be equal to the load capacitance value found in the crystal manufacturer datasheet. The parasitic capacitance CELn can in most applications be disregarded as these are usually very small. If accounted for, these values are dependent on the PCB material and PCB layout. For some crystal the internal capacitive load provided by the device itself can be enough. To calculate the total load capacitance in this case. CELn and CPn are both zero, CL1 = CL2 = CL, and the equation reduces to the following: = totܥ ܮܥ 2 See the related links for equivalent internal pin capacitance values. 50.7 Programming and Debug Ports For programming and/or debugging the SAM L10/L11, the device should be connected using the Serial Wire Debug, SWD, interface. Currently the SWD interface is supported by several Microchip and third party programmers and debuggers, like the Atmel-ICE, SAM-ICE or SAM L10/L11 Xplained Pro (SAM L10/L11 evaluation kit) Embedded Debugger. Refer to the Atmel-ICE, SAM-ICE or SAM L10/L11 Xplained Pro user guides for details on debugging and programming connections and options. For connecting to any other programming or debugging tool, refer to that specific programmer or debugger’s user guide. SAM L10/L11 Family Schematic Checklist © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1212 The SAM L10/L11 Xplained Pro evaluation board supports programming and debugging through the onboard embedded debugger so no external programmer or debugger is needed. The SWDIO pin should be pulled up on the target. It is recommended that the SWCLK pin is pulled to a defined state of the target board. 50.7.1 Cortex Debug Connector (10-pin) For debuggers and/or programmers that support the Cortex Debug Connector (10-pin) interface the signals should be connected as shown in the following figure, with details described in the following table. Figure 50-11. Cortex Debug Connector (10-pin) 1 Cortex Debug Connector (10-pin) VDD VTref GND GND NC NC NC NC SWDCLK SWDIO RESET RESET SWDIO SWCLK GND Table 50-7. Cortex Debug Connector (10-pin) Header Signal Name Description SWDCLK Serial wire clock pin SWDIO Serial wire bidirectional data pin RESET Target device reset pin, active low VTref Target voltage sense, should be connected to the device VDD GND Ground 50.7.2 10-pin JTAGICE3 Compatible Serial Wire Debug Interface The JTAGICE3 debugger and programmer does not support the Cortex Debug Connector (10-pin) directly, hence a special pinout is needed to directly connect the SAM L10/L11 to the JTAGICE3, alternatively one can use the JTAGICE3 squid cable and manually match the signals between the SAM L10/L11 Family Schematic Checklist © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1213 JTAGICE3 and SAM L10/L11. The following figure describes how to connect a 10-pin header that support connecting the JTAGICE3 directly to the SAM L10/L11 without the need for a squid cable. This can also be used for the Atmel-ICE AVR connector port. The JTAGICE3 squid cable or the JTACICE3 50mil cable can be used to connect the JTAGICE3 programmer and debugger to the SAM L10/L11. The figure illustrates the correct pinout for the JTAGICE3 50 mil, and details are given in the following table. Figure 50-12. 10-pin JTAGICE3 Compatible Serial Wire Debug Interface 1 10-pin JTAGICE3 Compatible Serial Wire Debug Header VDD SWDCLK NC SWDIO NC NC GND VTG RESET NC NC SWCLK RESET SWDIO GND Table 50-8. 10-pin JTAGICE3 Compatible Serial Wire Debug Interface Header Signal Name Description SWDCLK Serial wire clock pin SWDIO Serial wire bidirectional data pin RESET Target device reset pin, active low VTG Target voltage sense, should be connected to the device VDD GND Ground 50.7.3 20-pin IDC JTAG Connector For debuggers and/or programmers that support the 20-pin IDC JTAG Connector, e.g., the SAM-ICE, the signals should be connected, as shown in the following figure, with details described in the following table. SAM L10/L11 Family Schematic Checklist © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1214 Figure 50-13. 20-pin IDC JTAG Connector 1 20-pin IDC JTAG Connector VDD VCC NC NC SWDIO SWDCLK NC NC RESET NC NC NC GND GND GND GND GND GND* GND* GND* GND* RESET SWCLK SWDIO GND Table 50-9. 20-pin IDC JTAG Connector Header Signal Name Description SWDCLK Serial wire clock pin SWDIO Serial wire bidirectional data pin RESET Target device reset pin, active low VCC Target voltage sense, should be connected to the device VDD GND Ground GND* These pins are reserved for firmware extension purposes. They can be left unconnected or connected to GND in normal debug environment. They are not essential for SWD in general. 50.8 Peripherals Considerations ADC Accuracy The ADC accuracy may depend on different parameters, such as its input sources, as well as its conversion speed. Please refer to the Analog-to-Digital Converter (ADC) Characteristics section in the Electrical Characteristics chapters for more details. SAM L10/L11 Family Schematic Checklist © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1215 51. Conventions 51.1 Numerical Notation Table 51-1. Numerical Notation Symbol Description 165 Decimal number 0b0101 Binary number (example 0b0101 = 5 decimal) '0101' Binary numbers are given without prefix if unambiguous. 0x3B24 Hexadecimal number X Represents an unknown or don't care value Z Represents a high-impedance (floating) state for either a signal or a bus 51.2 Memory Size and Type Table 51-2. Memory Size and Bit Rate Symbol Description KB (kbyte) kilobyte (210 = 1024) MB (Mbyte) megabyte (220 = 1024*1024) GB (Gbyte) gigabyte (230 = 1024*1024*1024) b bit (binary '0' or '1') B byte (8 bits) 1kbit/s 1,000 bit/s rate (not 1,024 bit/s) 1Mbit/s 1,000,000 bit/s rate 1Gbit/s 1,000,000,000 bit/s rate word 32 bit half-word 16 bit 51.3 Frequency and Time Table 51-3. Frequency and Time Symbol Description kHz 1kHz = 103Hz = 1,000Hz KHz 1KHz = 1,024Hz, 32KHz = 32,768Hz SAM L10/L11 Family Conventions © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1216 Symbol Description MHz 106 = 1,000,000Hz GHz 109 = 1,000,000,000Hz s second ms millisecond µs microsecond ns nanosecond 51.4 Registers and Bits Table 51-4. Register and Bit Mnemonics Symbol Description R/W Read/Write accessible register bit. The user can read from and write to this bit. R Read-only accessible register bit. The user can only read this bit. Writes will be ignored. W Write-only accessible register bit. The user can only write this bit. Reading this bit will return an undefined value. BIT Bit names are shown in uppercase. (Example ENABLE) FIELD[n:m] A set of bits from bit n down to m. (Example: PINA[3:0] = {PINA3, PINA2, PINA1, PINA0} Reserved Reserved bits are unused and reserved for future use. For compatibility with future devices, always write reserved bits to zero when the register is written. Reserved bits will always return zero when read. Reserved bit field values must not be written to a bit field. A reserved value won't be read from a read-only bit field. PERIPHERALi If several instances of a peripheral exist, the peripheral name is followed by a number to indicate the number of the instance in the range 0-n. PERIPHERAL0 denotes one specific instance. Reset Value of a register after a power Reset. This is also the value of registers in a peripheral after performing a software Reset of the peripheral, except for the Debug Control registers. SET/CLR Registers with SET/CLR suffix allows the user to clear and set bits in a register without doing a read-modify-write operation. These registers always come in pairs. Writing a one to a bit in the CLR register will clear the corresponding bit in both registers, while writing a one to a bit in the SET register will set the corresponding bit in both registers. Both registers will return the same value when read. If both registers are written simultaneously, the write to the CLR register will take precedence. SAM L10/L11 Family Conventions © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1217 52. Acronyms and Abbreviations The below table contains acronyms and abbreviations used in this document. Table 52-1. Acronyms and Abbreviations Abbreviation Description AC Analog Comparator ADC Analog-to-Digital Converter ADDR Address AES Advanced Encryption Standard AHB Advanced High-performance Bus AMBA Advanced Microcontroller Bus Architecture APB AMBA Advanced Peripheral Bus AREF Analog Reference Voltage BOD Brown-out Detector CAL Calibration CC Compare/Capture CCL Configurable Custom Logic CLK Clock CRC Cyclic Redundancy Check CTRL Control DAC Digital-to-Analog Converter DAP Debug Access Port DFLL Digital Frequency Locked Loop DPLL Digital Phase Locked Loop DMAC DMA (Direct Memory Access) Controller DSU Device Service Unit EEPROM Electrically Erasable Programmable Read-Only Memory EIC External Interrupt Controller EVSYS Event System FDPLL Fractional Digital Phase Locked Loop, also DPLL FREQM Frequency Meter GCLK Generic Clock Controller GND Ground SAM L10/L11 Family Acronyms and Abbreviations © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1218 Abbreviation Description GPIO General Purpose Input/Output I 2C Inter-Integrated Circuit IF Interrupt Flag INT Interrupt MBIST Memory Built-In Self-Test MEM-AP Memory Access Port MTB Micro Trace Buffer NMI Non-maskable Interrupt NVIC Nested Vector Interrupt Controller NVM Nonvolatile Memory NVMCTRL Nonvolatile Memory Controller OPAMP Operation Amplifier OSC Oscillator PAC Peripheral Access Controller PC Program Counter PER Period PM Power Manager POR Power-on Reset PORT I/O Pin Controller PTC Peripheral Touch Controller PWM Pulse-Width Modulation RAM Random-Access Memory REF Reference RTC Real-Time Counter RX Receiver/Receive SEEP SmartEEPROM Page SERCOM Serial Communication Interface SMBus System Management Bus SP Stack Pointer SPI Serial Peripheral Interface SRAM Static Random Access Memory SUPC Supply Controller SAM L10/L11 Family Acronyms and Abbreviations © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1219 Abbreviation Description SWD Serial Wire Debug TC Timer/Counter TRNG True Random Number Generator TX Transmitter/Transmit ULP Ultra Low-Power USART Universal Synchronous and Asynchronous Serial Receiver and Transmitter VDD Common voltage to be applied to VDDIO and VDDANA VDDIO Digital Supply Voltage VDDANA Analog Supply Voltage VREF Voltage Reference WDT Watchdog Timer XOSC Crystal Oscillator SAM L10/L11 Family Acronyms and Abbreviations © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1220 53. Datasheet Revision History Note:  The datasheet revision is independent of the die revision (Revision bit in the Device Identification register of the Device Service Unit, DSU.DID.REVISION) and the device variant (last letter of the ordering number). 53.1 Rev A - 09/2017 This is the initial released version of the document. 53.2 Rev B - 6/2018 Added new documentation for Electrical Characteristics -125°C. SAM L10/L11 Family Datasheet Revision History © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1221 The Microchip Web Site Microchip provides online support via our web site at http://www.microchip.com/. This web site is used as a means to make files and information easily available to customers. Accessible by using your favorite Internet browser, the web site contains the following information: • Product Support – Data sheets and errata, application notes and sample programs, design resources, user’s guides and hardware support documents, latest software releases and archived software • General Technical Support – Frequently Asked Questions (FAQ), technical support requests, online discussion groups, Microchip consultant program member listing • Business of Microchip – Product selector and ordering guides, latest Microchip press releases, listing of seminars and events, listings of Microchip sales offices, distributors and factory representatives Customer Change Notification Service Microchip’s customer notification service helps keep customers current on Microchip products. Subscribers will receive e-mail notification whenever there are changes, updates, revisions or errata related to a specified product family or development tool of interest. To register, access the Microchip web site at http://www.microchip.com/. Under “Support”, click on “Customer Change Notification” and follow the registration instructions. Customer Support Users of Microchip products can receive assistance through several channels: • Distributor or Representative • Local Sales Office • Field Application Engineer (FAE) • Technical Support Customers should contact their distributor, representative or Field Application Engineer (FAE) for support. Local sales offices are also available to help customers. A listing of sales offices and locations is included in the back of this document. Technical support is available through the web site at: http://www.microchip.com/support SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1222 Product Identification System To order or obtain information, e.g., on pricing or delivery, refer to the factory or the listed sales office. ATSAML 11 D 14 A M U T No character = Tray or Tube 16 = 64 KB 15 = 32 KB 14 = 16 KB D = 24 Pins E = 32 Pins 10 = Cortex-M23 CPU 11 = Cortex-M23 CPU with TrustZone Enabled A = TQFP M = VQFN Y = SSOP U = -40 - +85°C Matte Sn Plating F = -40 - +125°C Matte Sn Plating (Flash) SAML = Ultra Low Power Microcontroller U = WLCSP Microchip Devices Code Protection Feature Note the following details of the code protection feature on Microchip devices: • Microchip products meet the specification contained in their particular Microchip Data Sheet. • Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the intended manner and under normal conditions. • There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data Sheets. Most likely, the person doing so is engaged in theft of intellectual property. • Microchip is willing to work with the customer who is concerned about the integrity of their code. • Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not mean that we are guaranteeing the product as “unbreakable.” Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of our products. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such acts allow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act. Legal Notice Information contained in this publication regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1223 WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer’s risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights unless otherwise stated. Trademarks The Microchip name and logo, the Microchip logo, AnyRate, AVR, AVR logo, AVR Freaks, BeaconThings, BitCloud, CryptoMemory, CryptoRF, dsPIC, FlashFlex, flexPWR, Heldo, JukeBlox, KeeLoq, KeeLoq logo, Kleer, LANCheck, LINK MD, maXStylus, maXTouch, MediaLB, megaAVR, MOST, MOST logo, MPLAB, OptoLyzer, PIC, picoPower, PICSTART, PIC32 logo, Prochip Designer, QTouch, RightTouch, SAM-BA, SpyNIC, SST, SST Logo, SuperFlash, tinyAVR, UNI/O, and XMEGA are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. ClockWorks, The Embedded Control Solutions Company, EtherSynch, Hyper Speed Control, HyperLight Load, IntelliMOS, mTouch, Precision Edge, and Quiet-Wire are registered trademarks of Microchip Technology Incorporated in the U.S.A. Adjacent Key Suppression, AKS, Analog-for-the-Digital Age, Any Capacitor, AnyIn, AnyOut, BodyCom, chipKIT, chipKIT logo, CodeGuard, CryptoAuthentication, CryptoCompanion, CryptoController, dsPICDEM, dsPICDEM.net, Dynamic Average Matching, DAM, ECAN, EtherGREEN, In-Circuit Serial Programming, ICSP, Inter-Chip Connectivity, JitterBlocker, KleerNet, KleerNet logo, Mindi, MiWi, motorBench, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, MultiTRAK, NetDetach, Omniscient Code Generation, PICDEM, PICDEM.net, PICkit, PICtail, PureSilicon, QMatrix, RightTouch logo, REAL ICE, Ripple Blocker, SAM-ICE, Serial Quad I/O, SMART-I.S., SQI, SuperSwitcher, SuperSwitcher II, Total Endurance, TSHARC, USBCheck, VariSense, ViewSpan, WiperLock, Wireless DNA, and ZENA are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. SQTP is a service mark of Microchip Technology Incorporated in the U.S.A. Silicon Storage Technology is a registered trademark of Microchip Technology Inc. in other countries. GestIC is a registered trademark of Microchip Technology Germany II GmbH & Co. KG, a subsidiary of Microchip Technology Inc., in other countries. All other trademarks mentioned herein are property of their respective companies. © 2017, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved. ISBN: 978-1-5224-3156-5 Quality Management System Certified by DNV ISO/TS 16949 Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California and India. The Company’s quality system processes and procedures are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1224 analog products. In addition, Microchip’s quality system for the design and manufacture of development systems is ISO 9001:2000 certified. SAM L10/L11 Family © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1225 AMERICAS ASIA/PACIFIC ASIA/PACIFIC EUROPE Corporate Office 2355 West Chandler Blvd. Chandler, AZ 85224-6199 Tel: 480-792-7200 Fax: 480-792-7277 Technical Support: http://www.microchip.com/ support Web Address: www.microchip.com Atlanta Duluth, GA Tel: 678-957-9614 Fax: 678-957-1455 Austin, TX Tel: 512-257-3370 Boston Westborough, MA Tel: 774-760-0087 Fax: 774-760-0088 Chicago Itasca, IL Tel: 630-285-0071 Fax: 630-285-0075 Dallas Addison, TX Tel: 972-818-7423 Fax: 972-818-2924 Detroit Novi, MI Tel: 248-848-4000 Houston, TX Tel: 281-894-5983 Indianapolis Noblesville, IN Tel: 317-773-8323 Fax: 317-773-5453 Tel: 317-536-2380 Los Angeles Mission Viejo, CA Tel: 949-462-9523 Fax: 949-462-9608 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 Fax: 905-695-2078 Asia Pacific Office Suites 3707-14, 37th Floor Tower 6, The Gateway Harbour City, Kowloon Hong Kong Tel: 852-2943-5100 Fax: 852-2401-3431 Australia - Sydney Tel: 61-2-9868-6733 Fax: 61-2-9868-6755 China - Beijing Tel: 86-10-8569-7000 Fax: 86-10-8528-2104 China - Chengdu Tel: 86-28-8665-5511 Fax: 86-28-8665-7889 China - Chongqing Tel: 86-23-8980-9588 Fax: 86-23-8980-9500 China - Dongguan Tel: 86-769-8702-9880 China - Guangzhou Tel: 86-20-8755-8029 China - Hangzhou Tel: 86-571-8792-8115 Fax: 86-571-8792-8116 China - Hong Kong SAR Tel: 852-2943-5100 Fax: 852-2401-3431 China - Nanjing Tel: 86-25-8473-2460 Fax: 86-25-8473-2470 China - Qingdao Tel: 86-532-8502-7355 Fax: 86-532-8502-7205 China - Shanghai Tel: 86-21-3326-8000 Fax: 86-21-3326-8021 China - Shenyang Tel: 86-24-2334-2829 Fax: 86-24-2334-2393 China - Shenzhen Tel: 86-755-8864-2200 Fax: 86-755-8203-1760 China - Wuhan Tel: 86-27-5980-5300 Fax: 86-27-5980-5118 China - Xian Tel: 86-29-8833-7252 Fax: 86-29-8833-7256 China - Xiamen Tel: 86-592-2388138 Fax: 86-592-2388130 China - Zhuhai Tel: 86-756-3210040 Fax: 86-756-3210049 India - Bangalore Tel: 91-80-3090-4444 Fax: 91-80-3090-4123 India - New Delhi Tel: 91-11-4160-8631 Fax: 91-11-4160-8632 India - Pune Tel: 91-20-3019-1500 Japan - Osaka Tel: 81-6-6152-7160 Fax: 81-6-6152-9310 Japan - Tokyo Tel: 81-3-6880- 3770 Fax: 81-3-6880-3771 Korea - Daegu Tel: 82-53-744-4301 Fax: 82-53-744-4302 Korea - Seoul Tel: 82-2-554-7200 Fax: 82-2-558-5932 or 82-2-558-5934 Malaysia - Kuala Lumpur Tel: 60-3-6201-9857 Fax: 60-3-6201-9859 Malaysia - Penang Tel: 60-4-227-8870 Fax: 60-4-227-4068 Philippines - Manila Tel: 63-2-634-9065 Fax: 63-2-634-9069 Singapore Tel: 65-6334-8870 Fax: 65-6334-8850 Taiwan - Hsin Chu Tel: 886-3-5778-366 Fax: 886-3-5770-955 Taiwan - Kaohsiung Tel: 886-7-213-7830 Taiwan - Taipei Tel: 886-2-2508-8600 Fax: 886-2-2508-0102 Thailand - Bangkok Tel: 66-2-694-1351 Fax: 66-2-694-1350 Austria - Wels Tel: 43-7242-2244-39 Fax: 43-7242-2244-393 Denmark - Copenhagen Tel: 45-4450-2828 Fax: 45-4485-2829 Finland - Espoo Tel: 358-9-4520-820 France - Paris Tel: 33-1-69-53-63-20 Fax: 33-1-69-30-90-79 France - Saint Cloud Tel: 33-1-30-60-70-00 Germany - Garching Tel: 49-8931-9700 Germany - Haan Tel: 49-2129-3766400 Germany - Heilbronn Tel: 49-7131-67-3636 Germany - Karlsruhe Tel: 49-721-625370 Germany - Munich Tel: 49-89-627-144-0 Fax: 49-89-627-144-44 Germany - Rosenheim Tel: 49-8031-354-560 Israel - Ra’anana Tel: 972-9-744-7705 Italy - Milan Tel: 39-0331-742611 Fax: 39-0331-466781 Italy - Padova Tel: 39-049-7625286 Netherlands - Drunen Tel: 31-416-690399 Fax: 31-416-690340 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 Fax: 34-91-708-08-91 Sweden - Gothenberg Tel: 46-31-704-60-40 Sweden - Stockholm Tel: 46-8-5090-4654 UK - Wokingham Tel: 44-118-921-5800 Fax: 44-118-921-5820 Worldwide Sales and Service © 2018 Microchip Technology Inc. Datasheet DS60001513B-page 1226

 2011-2013 Microchip Technology Inc. DS70000657H-page 1 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X Operating Conditions • 3.0V to 3.6V, -40°C to +85°C, DC to 70 MIPS • 3.0V to 3.6V, -40°C to +125°C, DC to 60 MIPS Core: 16-Bit dsPIC33E/PIC24E CPU • Code Efficient (C and Assembly) Architecture • Two 40-Bit-Wide Accumulators • Single Cycle (MAC/MPY) with Dual Data Fetch • Single-Cycle, Mixed-Sign MUL plus Hardware Divide • 32-Bit Multiply Support Clock Management • 1.0% Internal Oscillator • Programmable PLLs and Oscillator Clock Sources • Fail-Safe Clock Monitor (FSCM) • Independent Watchdog Timer (WDT) • Fast Wake-up and Start-up Power Management • Low-Power Management modes (Sleep, Idle, Doze) • Integrated Power-on Reset and Brown-out Reset • 0.6 mA/MHz Dynamic Current (typical) • 30 µA IPD Current (typical) High-Speed PWM • Up to Three PWM Pairs with Independent Timing • Dead Time for Rising and Falling Edges • 7.14 ns PWM Resolution • PWM Support for: - DC/DC, AC/DC, Inverters, PFC, Lighting - BLDC, PMSM, ACIM, SRM • Programmable Fault Inputs • Flexible Trigger Configurations for ADC Conversions Advanced Analog Features • ADC module: - Configurable as 10-bit, 1.1 Msps with four S&H or 12-bit, 500 ksps with one S&H - Six analog inputs on 28-pin devices and up to 16 analog inputs on 64-pin devices • Flexible and Independent ADC Trigger Sources • Up to Three Op Amp/Comparators with Direct Connection to the ADC module: - Additional dedicated comparator - Programmable references with 32 voltage points • Charge Time Measurement Unit (CTMU): - Supports mTouch™ capacitive touch sensing - Provides high-resolution time measurement (1 ns) - On-chip temperature measurement Timers/Output Compare/Input Capture • 12 General Purpose Timers: - Five 16-bit and up to two 32-bit timers/counters - Four Output Compare (OC) modules, configurable as timers/counters - PTG module with two configurable timers/counters - 32-bit Quadrature Encoder Interface (QEI) module, configurable as a timer/counter • Four Input Capture (IC) modules • Peripheral Pin Select (PPS) to allow Function Remap • Peripheral Trigger Generator (PTG) for Scheduling Complex Sequences Communication Interfaces • Two UART modules (17.5 Mbps): - With support for LIN/J2602 protocols and IrDA® • Two 4-Wire SPI modules (15 Mbps) • ECAN™ module (1 Mbaud) CAN 2.0B Support • Two I2C™ modules (up to 1 Mbaud) with SMBus Support • PPS to allow Function Remap • Programmable Cyclic Redundancy Check (CRC) Direct Memory Access (DMA) • 4-Channel DMA with User-Selectable Priority Arbitration • UART, SPI, ADC, ECAN, IC, OC and Timers Input/Output • Sink/Source 12 mA or 6 mA, Pin-Specific for Standard VOH/VOL, up to 22 or 14 mA, respectively for Non-Standard VOH1 • 5V Tolerant Pins • Peripheral Pin Select (PPS) to allow Digital Function Remapping • Selectable Open-Drain, Pull-ups and Pull-Downs • Up to 5 mA Overvoltage Clamp Current • Change Notification Interrupts on All I/O Pins Qualification and Class B Support • AEC-Q100 REVG (Grade 1, -40°C to +125°C) Planned • AEC-Q100 REVG (Grade 0, -40°C to +150°C) Planned • Class B Safety Library, IEC 60730 Debugger Development Support • In-Circuit and In-Application Programming • Two Program and Two Complex Data Breakpoints • IEEE 1149.2 Compatible (JTAG) Boundary Scan • Trace and Run-Time Watch 16-Bit Microcontrollers and Digital Signal Controllers with High-Speed PWM, Op Amps and Advanced Analog dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 2  2011-2013 Microchip Technology Inc. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X PRODUCT FAMILIES The device names, pin counts, memory sizes and peripheral availability of each device are listed in Table 1 (General Purpose Families) and Table 2 (Motor Control Families). Their pinout diagrams appear on the following pages. TABLE 1: dsPIC33EPXXXGP50X and PIC24EPXXXGP20X GENERAL PURPOSE FAMILIES Device Page Erase Size (Instructions) Program Flash Memory (Kbytes) RAM (Kbyte) Remappable Peripherals I 2C™ CRC Generator 10-Bit/12-Bit ADC (Channels) Op Amps/Comparators CTMU PTG I/O Pins Pins Packages 16-Bit/32-Bit Timers Input Capture Output Compare UART SPI(2) ECAN™ Technology External Interrupts(3) PIC24EP32GP202 512 32 4 5 4 4 2 2 — 3 2 1 6 2/3(1) Yes Yes 21 28 SPDIP, SOIC, SSOP(4) , QFN-S PIC24EP64GP202 1024 64 8 PIC24EP128GP202 1024 128 16 PIC24EP256GP202 1024 256 32 PIC24EP512GP202 1024 512 48 PIC24EP32GP203 512 32 4 5 4 4 2 2 — 3 2 1 8 3/4 Yes Yes 25 36 VTLA PIC24EP64GP203 1024 64 8 PIC24EP32GP204 512 32 4 5 4 4 2 2 — 3 2 1 9 3/4 Yes Yes 35 44/ 48 VTLA(4) , TQFP, QFN, UQFN PIC24EP64GP204 1024 64 8 PIC24EP128GP204 1024 128 16 PIC24EP256GP204 1024 256 32 PIC24EP512GP204 1024 512 48 PIC24EP64GP206 1024 64 8 5 4 4 2 2 — 3 2 1 16 3/4 Yes Yes 53 64 TQFP, QFN PIC24EP128GP206 1024 128 16 PIC24EP256GP206 1024 256 32 PIC24EP512GP206 1024 512 48 dsPIC33EP32GP502 512 32 4 5 4 4 2 2 1 3 2 1 6 2/3(1) Yes Yes 21 28 SPDIP, SOIC, SSOP(4) , QFN-S dsPIC33EP64GP502 1024 64 8 dsPIC33EP128GP502 1024 128 16 dsPIC33EP256GP502 1024 256 32 dsPIC33EP512GP502 1024 512 48 dsPIC33EP32GP503 512 32 4 5 4 4 2 2 1 3 2 1 8 3/4 Yes Yes 25 36 VTLA dsPIC33EP64GP503 1024 64 8 dsPIC33EP32GP504 512 32 4 5 4 4 2 2 1 3 2 1 9 3/4 Yes Yes 35 44/ 48 VTLA(4) , TQFP, QFN, UQFN dsPIC33EP64GP504 1024 64 8 dsPIC33EP128GP504 1024 128 16 dsPIC33EP256GP504 1024 256 32 dsPIC33EP512GP504 1024 512 48 dsPIC33EP64GP506 1024 64 8 5 4 4 2 2 1 3 2 1 16 3/4 Yes Yes 53 64 TQFP, QFN dsPIC33EP128GP506 1024 128 16 dsPIC33EP256GP506 1024 256 32 dsPIC33EP512GP506 1024 512 48 Note 1: On 28-pin devices, Comparator 4 does not have external connections. Refer to Section 25.0 “Op Amp/Comparator Module” for details. 2: Only SPI2 is remappable. 3: INT0 is not remappable. 4: The SSOP and VTLA packages are not available for devices with 512 Kbytes of memory.  2011-2013 Microchip Technology Inc. DS70000657H-page 3 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 2: dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X MOTOR CONTROL FAMILIES Device Page Erase Size (Instructions) Program Flash Memory (Kbytes) RAM (Kbytes) Remappable Peripherals I 2C™ CRC Generator 10-Bit/12-Bit ADC (Channels) Op Amps/Comparators CTMU PTG I/O Pins Pins Packages 16-Bit/32-Bit Timers Input Capture Output Compare Motor Control PWM(4) (Channels) Quadrature Encoder Interface UART SPI(2) ECAN™ Technology External Interrupts(3) PIC24EP32MC202 512 32 4 5 4 4 6 1 2 2 — 3 2 1 6 2/3(1) Yes Yes 21 28 SPDIP, SOIC, SSOP(5) , QFN-S PIC24EP64MC202 1024 64 8 PIC24EP128MC202 1024 128 16 PIC24EP256MC202 1024 256 32 PIC24EP512MC202 1024 512 48 PIC24EP32MC203 512 32 4 5 4 4 6 1 2 2 — 3 2 1 8 3/4 Yes Yes 25 36 VTLA PIC24EP64MC203 1024 64 8 PIC24EP32MC204 512 32 4 5 4 4 6 1 2 2 — 3 2 1 9 3/4 Yes Yes 35 44/ 48 VTLA(5) , TQFP, QFN, UQFN PIC24EP64MC204 1024 64 8 PIC24EP128MC204 1024 128 16 PIC24EP256MC204 1024 256 32 PIC24EP512MC204 1024 512 48 PIC24EP64MC206 1024 64 8 5 4 4 6 1 2 2 — 3 2 1 16 3/4 Yes Yes 53 64 TQFP, QFN PIC24EP128MC206 1024 128 16 PIC24EP256MC206 1024 256 32 PIC24EP512MC206 1024 512 48 dsPIC33EP32MC202 512 32 4 5 4 4 6 1 2 2 — 3 2 1 6 2/3(1) Yes Yes 21 28 SPDIP, SOIC, SSOP(5) , QFN-S dsPIC33EP64MC202 1024 64 8 dsPIC33EP128MC202 1024 128 16 dsPIC33EP256MC202 1024 256 32 dsPIC33EP512MC202 1024 512 48 dsPIC33EP32MC203 512 32 4 5 4 4 6 1 2 2 — 3 2 1 8 3/4 Yes Yes 25 36 VTLA dsPIC33EP64MC203 1024 64 8 dsPIC33EP32MC204 512 32 4 5 4 4 6 1 2 2 — 3 2 1 9 3/4 Yes Yes 35 44/ 48 VTLA(5) , TQFP, QFN, UQFN dsPIC33EP64MC204 1024 64 8 dsPIC33EP128MC204 1024 128 16 dsPIC33EP256MC204 1024 256 32 dsPIC33EP512MC204 1024 512 48 dsPIC33EP64MC206 1024 64 8 5 4 4 6 1 2 2 — 3 2 1 16 3/4 Yes Yes 53 64 TQFP, QFN dsPIC33EP128MC206 1024 128 16 dsPIC33EP256MC206 1024 256 32 dsPIC33EP512MC206 1024 512 48 dsPIC33EP32MC502 512 32 4 5 4 4 6 1 2 2 1 3 2 1 6 2/3(1) Yes Yes 21 28 SPDIP, SOIC, SSOP(5) , QFN-S dsPIC33EP64MC502 1024 64 8 dsPIC33EP128MC502 1024 128 16 dsPIC33EP256MC502 1024 256 32 dsPIC33EP512MC502 1024 512 48 dsPIC33EP32MC503 512 32 4 5 4 4 6 1 2 2 1 3 2 1 8 3/4 Yes Yes 25 36 VTLA dsPIC33EP64MC503 1024 64 8 Note 1: On 28-pin devices, Comparator 4 does not have external connections. Refer to Section 25.0 “Op Amp/Comparator Module” for details. 2: Only SPI2 is remappable. 3: INT0 is not remappable. 4: Only the PWM Faults are remappable. 5: The SSOP and VTLA packages are not available for devices with 512 Kbytes of memory. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 4  2011-2013 Microchip Technology Inc. dsPIC33EP32MC504 512 32 4 5 4 4 6 1 2 2 1 3 2 1 9 3/4 Yes Yes 35 44/ 48 VTLA(5) , TQFP, QFN, UQFN dsPIC33EP64MC504 1024 64 8 dsPIC33EP128MC504 1024 128 16 dsPIC33EP256MC504 1024 256 32 dsPIC33EP512MC504 1024 512 48 dsPIC33EP64MC506 1024 64 8 5 4 4 6 1 2 2 1 3 2 1 16 3/4 Yes Yes 53 64 TQFP, QFN dsPIC33EP128MC506 1024 128 16 dsPIC33EP256MC506 1024 256 32 dsPIC33EP512MC506 1024 512 48 TABLE 2: dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X MOTOR CONTROL FAMILIES (CONTINUED) Device Page Erase Size (Instructions) Program Flash Memory (Kbytes) RAM (Kbytes) Remappable Peripherals I 2C™ CRC Generator 10-Bit/12-Bit ADC (Channels) Op Amps/Comparators CTMU PTG I/O Pins Pins Packages 16-Bit/32-Bit Timers Input Capture Output Compare Motor Control PWM(4) (Channels) Quadrature Encoder Interface UART SPI(2) ECAN™ Technology External Interrupts(3) Note 1: On 28-pin devices, Comparator 4 does not have external connections. Refer to Section 25.0 “Op Amp/Comparator Module” for details. 2: Only SPI2 is remappable. 3: INT0 is not remappable. 4: Only the PWM Faults are remappable. 5: The SSOP and VTLA packages are not available for devices with 512 Kbytes of memory.  2011-2013 Microchip Technology Inc. DS70000657H-page 5 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Pin Diagrams 28-Pin SPDIP/SOIC/SSOP(1,2) Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. = Pins are up to 5V tolerant MCLR AVDD AN0/OA2OUT/RA0 AVSS AN1/C2IN1+/RA1 RPI47/T5CK/RB15 PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 RPI46/T3CK/RB14 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 RPI45/CTPLS/RB13 PGEC1/AN4/C1IN1+/RPI34/RB2 RPI44/RB12 PGED1/AN5/C1IN1-/RP35/RB3 TDI/RP43/RB11 TDO/RP42/RB10 OSC1/CLKI/RA2 VCAP OSC2/CLKO/RA3 VSS RP36/RB4 TMS/ASDA1/SDI1/RP41/RB9(3) CVREF2O/RP20/T1CK/RA4 TCK/CVREF1O/ASCL1/SDO1/RP40/T4CK/RB8 VDD SCK1/RP39/INT0/RB7 PGED2/ASDA2/RP37/RB5 PGEC2/ASCL2/RP38/RB6 VSS MCLR AVDD AN0/OA2OUT/RA0 AVSS AN1/C2IN1+/RA1 RPI47/PWM1L/T5CK/RB15 PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 RPI46/PWM1H/T3CK/RB14 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 RPI45/PWM2L/CTPLS/RB13 PGEC1/AN4/C1IN1+/RPI34/RB2 RPI44/PWM2H/RB12 PGED1/AN5/C1IN1-/RP35/RB3 TDI/RP43/PWM3L/RB11 TDO/RP42/PWM3H/RB10 OSC1/CLKI/RA2 VCAP OSC2/CLKO/RA3 VSS FLT32/RP36/RB4 TMS/ASDA1/SDI1/RP41/RB9(3) CVREF2O/RP20/T1CK/RA4 TCK/CVREF1O/ASCL1/SDO1/RP40/T4CK/RB8 VDD SCK1/RP39/INT0/RB7 PGED2/ASDA2/RP37/RB5 PGEC2/ASCL2/RP38/RB6 VSS 1 28 2 27 3 26 4 25 5 24 6 23 7 22 8 21 9 20 10 19 11 18 12 17 13 16 14 15 PIC24EPXXXGP202 dsPIC33EPXXXGP502 1 28 2 27 3 26 4 25 5 24 6 23 7 22 8 21 9 20 10 19 11 18 12 17 13 16 14 15 PIC24EPXXXMC202 dsPIC33EPXXXMC202/502 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 6  2011-2013 Microchip Technology Inc. Pin Diagrams (Continued) 28-Pin QFN-S(1,2,3) = Pins are up to 5V tolerant 28 27 26 25 24 23 22 8 9 10 11 12 13 14 3 18 17 16 15 4 5 7 1 2 20 19 6 21 PIC24EPXXXGP202 dsPIC33EPXXXGP502TCK/CVREF1O/ASCL1/SDO1/RP40/T4CK/RB8 SCK1/RP39/INT0/RB7 PGED2/ASDA2/RP37/RB5 PGEC2/ASCL2/RP38/RB6 VDD CVREF2O/RP20/T1CK/RA4 RP36/RB4 RPI45/CTPLS/RB13 RPI44/RB12 TDI/RP43/RB11 TDO/RP42/RB10 VCAP VSS TMS/ASDA1/SDI1/RP41/RB9(4) AV RPI47/T5CK/RB15 RPI46/T3CK/RB14 SS AVDD AN1/C2IN1+/RA1 AN0/OA2OUT/RA0 MCLR PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 VSS OSC1/CLKI/RA2 OSC2/CLKO/RA3 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: The metal pad at the bottom of the device is not connected to any pins and is recommended to be connected to VSS externally. 4: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2.  2011-2013 Microchip Technology Inc. DS70000657H-page 7 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Pin Diagrams (Continued) 28-Pin QFN-S(1,2,3) = Pins are up to 5V tolerant 28 27 26 25 24 23 22 8 9 10 11 12 13 14 3 18 17 16 15 4 5 7 1 2 20 19 6 21 PIC24EPXXXMC202 dsPIC33EPXXXMC202/502TCK/CVREF1O/ASCL1/SDO1/RP40/T4CK/RB8 SCK1/RP39/INT0/RB7 PGED2/ASDA2/RP37/RB5 PGEC2/ASCL2/RP38/RB6 VDD CVREF2O FLT32/RP36/RB4 /RP20/T1CK/RA4 RPI45/PWM2L/CTPLS/RB13 RPI44/PWM2H/RB12 TDI/RP43/PWM3L/RB11 TDO/RP42/PWM3H/RB10 VCAP VSS TMS/ASDA1/SDI1/RP41/RB9(4) AV RPI47/PWM1L/T5CK/RB15 RPI46/PWM1H/T3CK/RB14 SS AVDD AN1/C2IN1+/RA1 AN0/OA2OUT/RA0 MCLR PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 VSS OSC1/CLKI/RA2 OSC2/CLKO/RA3 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: The metal pad at the bottom of the device is not connected to any pins and is recommended to be connected to VSS externally. 4: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 8  2011-2013 Microchip Technology Inc. Pin Diagrams (Continued) 17 36-Pin VTLA(1,2,3) 1 10 33 32 31 30 29 28 2 3 4 5 6 24 23 22 21 20 19 11 12 13 14 15 7 8 9 36 35 34 16 18 27 26 25 = Pins are up to 5V tolerant PIC24EP32GP203 TCK/CVREF1O/ASCL1/SDO1/RP40/T4CK/RB8 RPI45/CTPLS/RB13 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 AN6/OA3OUT/C4IN1+/OCFB/RC0 AN7/C3IN1-/C4IN1-/RC1 VDD VSS OSC1/CLKI/RA2 OSC2/CLKO/RA3 SDA2/RPI24/RA8 AV RPI47/T5CK/RB15 RPI46/T3CK/RB14 SS AVDD PGED3/V AN1/C2IN1+/RA1 AN0/OA2OUT/RA0 MCLR REF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 RPI44/RB12 TDI/RP43/RB11 TDO/RP42/RB10 VCAP VSS RP56/RC8 TMS/ASDA1/SDI1/RP41/RB9(4) SCK1/RP39/INT0/RB7 PGED2/ASDA2/RP37/RB5 PGEC2/ASCL2/RP38/RB6 VDD VSS CVREF2O/RP20/T1CK/RA4 VDD SCL2/RP36/RB4 VDD Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: The metal pad at the bottom of the device is not connected to any pins and is recommended to be connected to VSS externally. 4: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. dsPIC33EP32GP503 PIC24EP64GP203 dsPIC33EP64GP503 17  2011-2013 Microchip Technology Inc. DS70000657H-page 9 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Pin Diagrams (Continued) 36-Pin VTLA(1,2,3) = Pins are up to 5V tolerant 1 10 33 32 31 30 29 28 2 3 4 5 6 24 23 22 21 20 19 11 12 13 14 15 7 8 9 36 35 34 16 17 18 27 26 25 PIC24EP32MC203 TCK/CVREF1O/ASCL1/SDO1/RP40/T4CK/RB8 RPI45/PWM2L/CTPLS/RB13 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 AN6/OA3OUT/C4IN1+/OCFB/RC0 AN7/C3IN1-/C4IN1-/RC1 VDD VSS OSC1/CLKI/RA2 OSC2/CLKO/RA3 SDA2/RPI24/RA8 AV RPI47/PWM1L/T5CK/RB15 RPI46/PWM1H/T3CK/RB14 SS AVDD PGED3/V AN1/C2IN1+/RA1 AN0/OA2OUT/RA0 MCLR REF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 RPI44/PWM2H/RB12 TDI/RP43/PWM3L/RB11 TDO/RP42/PWM3H/RB10 VCAP VSS RP56/RC8 TMS/ASDA1/SDI1/RP41/RB9(4) SCK1/RP39/INT0/RB7 PGED2/ASDA2/RP37/RB5 PGEC2/ASCL2/RP38/RB6 VDD VSS CVREF2O/RP20/T1CK/RA4 VDD FLT32/SCL2/RP36/RB4 VDD Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: The metal pad at the bottom of the device is not connected to any pins and is recommended to be connected to VSS externally. 4: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. dsPIC33EP32MC203/503 PIC24EP64MC203 dsPIC33EP64MC203/503 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 10  2011-2013 Microchip Technology Inc. Pin Diagrams (Continued) 44-Pin TQFP(1,2) = Pins are up to 5V tolerant 4443424140393837363534 1 33 2 32 3 31 4 30 5 29 6 28 7 27 8 26 9 25 10 24 11 23 1213141516171819202122 PIC24EPXXXGP204 TCK/CVREF1O/ASCL1/RP40/T4CK/RB8 TDO/RA10 RPI45/CTPLS/RB13 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 AN6/OA3OUT/C4IN1+/OCFB/RC0 AN7/C3IN1-/C4IN1-/RC1 AN8/C3IN1+/U1RTS/BCLK1/RC2 VDD VSS OSC1/CLKI/RA2 OSC2/CLKO/RA3 SDA2/RPI24/RA8 SCL2/RP36/RB4 TDI/RA7 RPI46/T3CK/RB14 RPI47/T5CK/RB15 AVSS AVDD MCLR AN0/OA2OUT/RA0 AN1/C2IN1+/RA1 PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 RPI44/RB12 RP43/RB11 RP42/RB10 VCAP VSS RP57/RC9 RP56/RC8 RP55/RC7 RP54/RC6 TMS/ASDA1/RP41/RB9(3) RP39/INT0/RB7 PGEC2/ASCL2/RP38/RB6 PGED2/ASDA2/RP37/RB5 VDD VSS SCL1/RPI53/RC5 SDA1/RPI52/RC4 SCK1/RPI51/RC3 SDI1/RPI25/RA9 CVREF2O/SDO1/RP20/T1CK/RA4 Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. dsPIC33EPXXXGP504  2011-2013 Microchip Technology Inc. DS70000657H-page 11 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Pin Diagrams (Continued) 44-Pin TQFP(1,2) = Pins are up to 5V tolerant 4443424140393837363534 1 33 2 32 3 31 4 30 5 29 6 28 7 27 8 26 9 25 10 24 11 23 1213141516171819202122 PIC24EPXXXMC204 TCK/CVREF1O/ASCL1/RP40/T4CK/RB8 TDO/RA10 RPI45/PWM2L/CTPLS/RB13 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 AN6/OA3OUT/C4IN1+/OCFB/RC0 AN7/C3IN1-/C4IN1-/RC1 AN8/C3IN1+/U1RTS/BCLK1/FLT3/RC2 VDD VSS OSC1/CLKI/RA2 OSC2/CLKO/RA3 SDA2/RPI24/RA8 FLT32/SCL2/RP36/RB4 TDI/RA7 RPI46/PWM1H/T3CK/RB14 RPI47/PWM1L/T5CK/RB15 AVSS AVDD MCLR AN0/OA2OUT/RA0 AN1/C2IN1+/RA1 PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 RPI44/PWM2H/RB12 RP43/PWM3L/RB11 RP42/PWM3H/RB10 VCAP VSS RP57/RC9 RP56/RC8 RP55/RC7 RP54/RC6 TMS/ASDA1/RP41/RB9(3) RP39/INT0/RB7 PGEC2/ASCL2/RP38/RB6 PGED2/ASDA2/RP37/RB5 VDD VSS SCL1/RPI53/RC5 SDA1/RPI52/RC4 SCK1/RPI51/RC3 SDI1/RPI25/RA9 CVREF2O/SDO1/RP20/T1CK/RA4 Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. dsPIC33EPXXXMC204/504 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 12  2011-2013 Microchip Technology Inc. Pin Diagrams (Continued) 44-Pin VTLA(1,2,3) = Pins are up to 5V tolerant PIC24EPXXXGP204 1 12 41 40 39 38 37 36 35 34 2 3 4 5 6 7 8 30 29 28 27 26 25 24 23 13 14 15 16 17 18 19 9 10 11 20 21 22 33 32 31 44 43 42 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 AN6/OA3OUT/C4IN1+/OCFB/RC0 AN7/C3IN1-/C4IN1-/RC1 AN8/C3IN1+/U1RTS/BCLK1/RC2 VDD VSS OSC1/CLKI/RA2 OSC2/CLKO/RA3 SDA2/RPI24/RA8 SCL2/RP36/RB4 TCK/CVREF1O/ASCL1/RP40/T4CK/RB8 RP39/INT0/RB7 PGEC2/ASCL2/RP38/RB6 PGED2/ASDA2/RP37/RB5 VDD VSS SCL1/RPI53/RC5 SDA1/RPI52/RC4 SCK1/RPI51/RC3 SDI1/RPI25/RA9 CVREF2O/SDO1/RP20/T1CK/RA4 RPI45/CTPLS/RB13 RPI44/RB12 RP43/RB11 RP42/RB10 VCAP VSS RP57/RC9 RP56/RC8 RP55/RC7 RP54/RC6 TMS/ASDA1/RP41/RB9(4) TDO/RA10 TDI/RA7 RPI46/T3CK/RB14 RPI47/T5CK/RB15 AVSS AVDD MCLR AN0/OA2OUT/RA0 AN1/C2IN1+/RA1 PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: The metal pad at the bottom of the device is not connected to any pins and is recommended to be connected to VSS externally. 4: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. dsPIC33EPXXXGP504  2011-2013 Microchip Technology Inc. DS70000657H-page 13 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Pin Diagrams (Continued) 43 44-Pin VTLA(1,2,3) = Pins are up to 5V tolerant PIC24EPXXXMC204 1 12 41 40 39 38 37 36 35 34 2 3 4 5 6 7 8 30 29 28 27 26 25 24 23 13 14 15 16 17 18 19 9 10 11 20 21 22 33 32 31 44 42 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 AN6/OA3OUT/C4IN1+/OCFB/RC0 AN7/C3IN1-/C4IN1-/RC1 AN8/C3IN1+/U1RTS/BCLK1/FLT3/RC2 VDD VSS OSC1/CLKI/RA2 OSC2/CLKO/RA3 SDA2/RPI24/RA8 FLT32/SCL2/RP36/RB4 TCK/CVREF1O/ASCL1/RP40/T4CK/RB8 RP39/INT0/RB7 PGEC2/ASCL2/RP38/RB6 PGED2/ASDA2/RP37/RB5 VDD VSS SCL1/RPI53/RC5 SDA1/RPI52/RC4 SCK1/RPI51/RC3 SDI1/RPI25/RA9 CVREF2O/SDO1/RP20/T1CK/RA4 RPI45/PWM2L/CTPLS/RB13 RPI44/PWM2H/RB12 RP43/PWM3L/RB11 RP42/PWM3H/RB10 VCAP VSS RP57/RC9 RP56/RC8 RP55/RC7 RP54/RC6 TMS/ASDA1/RP41/RB9(4) TDO/RA10 TDI/RA7 RPI46/PWM1H/T3CK/RB14 RPI47/PWM1L/T5CK/RB15 AVSS AVDD MCLR AN0/OA2OUT/RA0 AN1/C2IN1+/RA1 PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: The metal pad at the bottom of the device is not connected to any pins and is recommended to be connected to VSS externally. 4: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. dsPIC33EPXXXMC204/504 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 14  2011-2013 Microchip Technology Inc. Pin Diagrams (Continued) 44-Pin QFN(1,2,3) = Pins are up to 5V tolerant 44 43 42 41 40 39 38 37 36 35 12 13 14 15 16 17 18 19 20 21 3 30 29 28 27 26 25 24 23 4 5 7 8 9 10 11 1 2 32 31 6 22 33 34 PIC24EPXXXGP204 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 AN6/OA3OUT/C4IN1+/OCFB/RC0 AN7/C3IN1-/C4IN1-/RC1 AN8/C3IN1+/U1RTS/BCLK1/RC2 VDD VSS OSC1/CLKI/RA2 OSC2/CLKO/RA3 SDA2/RPI24/RA8 SCL2/RP36/RB4 TCK/CVREF1O/ASCL1/RP40/T4CK/RB8 RP39/INT0/RB7 PGEC2/ASCL2/RP38/RB6 PGED2/ASDA2/RP37/RB5 VDD VSS SCL1/RPI53/RC5 SDA1/RPI52/RC4 SCK1/RPI51/RC3 SDI1/RPI25/RA9 CVREF2O/SDO1/RP20/T1CK/RA4 RPI45/CTPLS/RB13 RPI44/RB12 RP43/RB11 RP42/RB10 VCAP VSS RP57/RC9 RP56/RC8 RP55/RC7 RP54/RC6 TMS/ASDA1/RP41/RB9(4) TDO/RA10 TDI/RA7 RPI46/T3CK/RB14 RPI47/T5CK/RB15 AVSS AVDD MCLR AN0/OA2OUT/RA0 AN1/C2IN1+/RA1 PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 dsPIC33EPXXXGP504 Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: The metal pad at the bottom of the device is not connected to any pins and is recommended to be connected to VSS externally. 4: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2.  2011-2013 Microchip Technology Inc. DS70000657H-page 15 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Pin Diagrams (Continued) 44-Pin QFN(1,2,3) = Pins are up to 5V tolerant 44 43 42 41 40 39 38 37 36 35 12 13 14 15 16 17 18 19 20 21 3 30 29 28 27 26 25 24 23 4 5 7 8 9 10 11 1 2 32 31 6 22 33 34 PIC24EPXXXMC204 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 AN6/OA3OUT/C4IN1+/OCFB/RC0 AN7/C3IN1-/C4IN1-/RC1 AN8/C3IN1+/U1RTS/BCLK1/FLT3/RC2 VDD VSS OSC1/CLKI/RA2 OSC2/CLKO/RA3 SDA2/RPI24/RA8 FLT32/SCL2/RP36/RB4 TCK/CVREF1O/ASCL1/RP40/T4CK/RB8 RP39/INT0/RB7 PGEC2/ASCL2/RP38/RB6 PGED2/ASDA2/RP37/RB5 VDD VSS SCL1/RPI53/RC5 SDA1/RPI52/RC4 SCK1/RPI51/RC3 SDI1/RPI25/RA9 CVREF2O/SDO1/RP20/T1CK/RA4 RPI45/PWM2L/CTPLS/RB13 RPI44/PWM2H/RB12 RP43/PWM3L/RB11 RP42/PWM3H/RB10 VCAP VSS RP57/RC9 RP56/RC8 RP55/RC7 RP54/RC6 TMS/ASDA1/RP41/RB9(4) TDO/RA10 TDI/RA7 RPI46/PWM1H/T3CK/RB14 RPI47/PWM1L/T5CK/RB15 AVSS AVDD MCLR AN0/OA2OUT/RA0 AN1/C2IN1+/RA1 PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 dsPIC33EPXXXMC204/504 Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: The metal pad at the bottom of the device is not connected to any pins and is recommended to be connected to VSS externally. 4: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 16  2011-2013 Microchip Technology Inc. Pin Diagrams (Continued) 48-Pin UQFN(1,2,3) = Pins are up to 5V tolerant Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: The metal pad at the bottom of the device is not connected to any pins and is recommended to be connected to VSS externally. 4: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. 48 47 46 45 43 42 41 40 39 38 13 14 15 16 17 18 19 21 22 23 3 33 31 30 29 28 27 26 25 4 5 7 9 10 11 12 1 2 35 34 6 24 36 37 PIC24EPXXXGP204 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 AN6/OA3OUT/C4IN1+/OCFB/RC0 AN7/C3IN1-/C4IN1-/RC1 AN8/C3IN1+/U1RTS/BCLK1/RC2 VDD VSS OSC1/CLKI/RA2 OSC2/CLKO/RA3 SDA2/RPI24/RA8 SCL2/RP36/RB4 TCK/CVREF1O/ASCL1/RP40/T4CK/RB8 RP39/INT0/RB7 PGEC2/ASCL2/RP38/RB6 PGED2/ASDA2/RP37/RB5 VDD VSS SCL1/RPI53/RC5 SDA1/RPI52/RC4 SCK1/RPI51/RC3 SDI1/RPI25/RA9 CVREF2O/SDO1/RP20/T1CK/RA4 RPI45/CTPLS/RB13 RPI44/RB12 RP43/RB11 RP42/RB10 VCAP VSS RP57/RC9 RP56/RC8 RP55/RC7 RP54/RC6 TMS/ASDA1/RP41/RB9(4) TDO/RA10 TDI/RA7 RPI46/T3CK/RB14 RPI47/T5CK/RB15 AVSS AVDD MCLR AN0/OA2OUT/RA0 AN1/C2IN1+/RA1 PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 dsPIC33EPXXXGP504 N/C 8 20N/C 32 N/C 44N/C  2011-2013 Microchip Technology Inc. DS70000657H-page 17 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Pin Diagrams (Continued) 48-Pin UQFN(1,2,3) = Pins are up to 5V tolerant Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: The metal pad at the bottom of the device is not connected to any pins and is recommended to be connected to VSS externally. 4: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. 48 47 46 45 43 42 41 40 39 38 13 14 15 16 17 18 19 21 22 23 3 33 31 30 29 28 27 26 25 4 5 7 9 10 11 12 1 2 35 34 6 24 36 37 PIC24EPXXXMC204 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 AN6/OA3OUT/C4IN1+/OCFB/RC0 AN7/C3IN1-/C4IN1-/RC1 AN8/C3IN1+/U1RTS/BCLK1/FLT3/RC2 VDD VSS OSC1/CLKI/RA2 OSC2/CLKO/RA3 SDA2/RPI24/RA8 FLT32/SCL2/RP36/RB4 TCK/CVREF1O/ASCL1/RP40/T4CK/RB8 RP39/INT0/RB7 PGEC2/ASCL2/RP38/RB6 PGED2/ASDA2/RP37/RB5 VDD VSS SCL1/RPI53/RC5 SDA1/RPI52/RC4 SCK1/RPI51/RC3 SDI1/RPI25/RA9 CVREF2O/SDO1/RP20/T1CK/RA4 RPI45/PWM2L/CTPLS/RB13 RPI44/PWM2H/RB12 RP43/PWM3L/RB11 RP42/PWM3H/RB10 VCAP VSS RP57/RC9 RP56/RC8 RP55/RC7 RP54/RC6 TMS/ASDA1/RP41/RB9(4) TDO/RA10 TDI/RA7 RPI46/PWM1H/T3CK/RB14 RPI47/PWM1L/T5CK/RB15 AVSS AVDD MCLR AN0/OA2OUT/RA0 AN1/C2IN1+/RA1 PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 dsPIC33EPXXXMC204/504 N/C 8 20N/C 32 N/C 44N/C dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 18  2011-2013 Microchip Technology Inc. Pin Diagrams (Continued) 64 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 1 48 2 47 3 46 4 45 5 44 6 43 7 42 8 41 9 40 10 39 11 38 12 37 13 36 14 35 15 34 16 33 17181920212223242526272829303132 TDI/RA7 RPI46/T3CK/RB14 RPI47/T5CK/RB15 RP118/RG6 RPI119/RG7 RP120/RG8 MCLR RPI121/RG9 VSS VDD AN10/RPI28/RA12 AN9/RPI27/RA11 AN0/OA2OUT/RA0 AN1/C2IN1+/RA1 PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 TDO/RA10 RPI45/CTPLS/RB13 RPI44/RB12 RP43/RB11 RP42/RB10 RP97/RF1 RPI96/RF0 VDD VCAP RP57/RC9 RD6 RD5 RP56/RC8 RP55/RC7 RP54/RC6 TMS/ASDA1/RP41/RB9(4) TCK/CVREF1O/ASCL1/RP40/T4CK/RB8 RC13 RP39/INT0/RB7 RPI58/RC10 PGEC2/ASCL2/RP38/RB6 PGED2/ASDA2/RP37/RB5 RD8 VSS OSC2/CLKO/RC15 OSC1/CLKI/RC12 VDD SCL1/RPI53/RC5 SDA1/RPI52/RC4 SCK1/RPI51/RC3 SDI1/RPI25/RA9 CVREF2O/SDO1/RP20/T1CK/RA4 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 AVDD AVSS AN6/OA3OUT/C4IN1+/OCFB/RC0 AN7/C3IN1-/C4IN1-/RC1 AN8/C3IN1+/U1RTS/BCLK1/RC2 AN11/C1IN2-(3)/U1CTS/RC11 VSS VDD AN12/C2IN2-(3)/U2RTS/BCLK2/RE12 AN13/C3IN2-(3)/U2CTS/RE13 AN14/RPI94/RE14 AN15/RPI95/RE15 SDA2/RPI24/RA8 SCL2/RP36/RB4 dsPIC33EP64GP506 PIC24EP64GP206 PIC24EP128GP206 PIC24EP256GP206 dsPIC33EP128GP506 dsPIC33EP256GP506 dsPIC33EP512GP506 PIC24EP512GP206 Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: The metal pad at the bottom of the device is not connected to any pins and is recommended to be connected to VSS externally. 4: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. 64-Pin TQFP(1,2,3) = Pins are up to 5V tolerant  2011-2013 Microchip Technology Inc. DS70000657H-page 19 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Pin Diagrams (Continued) 64-Pin TQFP(1,2,3) = Pins are up to 5V tolerant 64636261605958575655545352515049 1 48 2 47 3 46 4 45 5 44 6 43 7 42 8 41 9 40 10 39 11 38 12 37 13 36 14 35 15 34 16 33 17181920212223242526272829303132 TDI/RA7 RPI46/PWM1H/T3CK/RB14 RPI47/PWM1L/T5CK/RB15 RP118/RG6 RPI119/RG7 RP120/RG8 MCLR RPI121/RG9 VSS VDD AN10/RPI28/RA12 AN9/RPI27/RA11 AN0/OA2OUT/RA0 AN1/C2IN1+/RA1 PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 TDO/RA10 RPI45/PWM2L/CTPLS/RB13 RPI44/PWM2H/RB12 RP43/PWM3L/RB11 RP42/PWM3H/RB10 RP97/RF1 RPI96/RF0 VDD VCAP RP57/RC9 RD6 RD5 RP56/RC8 RP55/RC7 RP54/RC6 TMS/ASDA1/RP41/RB9(4) TCK/CVREF1O/ASCL1/RP40/T4CK/RB8 RC13 RP39/INT0/RB7 RPI58/RC10 PGEC2/ASCL2/RP38/RB6 PGED2/ASDA2/RP37/RB5 RD8 VSS OSC2/CLKO/RC15 OSC1/CLKI/RC12 VDD SCL1/RPI53/RC5 SDA1/RPI52/RC4 SCK1/RPI51/RC3 SDI1/RPI25/RA9 CVREF2O/SDO1/RP20/T1CK/RA4 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 AVDD AVSS AN6/OA3OUT/C4IN1+/OCFB/RC0 AN7/C3IN1-/C4IN1-/RC1 AN8/C3IN1+/U1RTS/BCLK1/FLT3/RC2 AN11/C1IN2-(3)/U1CTS/FLT4/RC11 VSS VDD AN12/C2IN2-(3)/U2RTS/BCLK2/RE12 AN13/C3IN2-(3)/U2CTS/RE13 AN14/RPI94/RE14 AN15/RPI95/RE15 SDA2/RPI24/RA8 FLT32/SCL2/RP36/RB4 PIC24EP64MC206 dsPIC33EP64MC206/506 PIC24EP128MC206 PIC24EP256MC206 dsPIC33EP128MC206/506 dsPIC33EP256MC206/506 dsPIC33EP512MC206/506 PIC24EP512MC206 Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: The metal pad at the bottom of the device is not connected to any pins and is recommended to be connected to VSS externally. 4: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 20  2011-2013 Microchip Technology Inc. Pin Diagrams (Continued) 64-Pin QFN(1,2,3,4) = Pins are up to 5V tolerant TDO/RA10 RPI45/CTPLS/RB13 RPI44/RB12 RP43/RB11 RP42/RB10 RP97/RF1 RPI96/RF0 VDD VCAP RP57/RC9 RD6 RD5 RP56/RC8 RP55/RC7 RP54/RC6 TMS/ASDA1/RP41/RB9(5) TCK/CVREF1O/ASCL1/RP40/T4CK/RB8 RC13 RP39/INT0/RB7 RPI58/RC10 PGEC2/ASCL2/RP38/RB6 PGED2/ASDA2/RP37/RB5 RD8 VSS OSC2/CLKO/RC15 OSC1/CLKI/RC12 VDD SCL1/RPI53/RC5 SDA1/RPI52/RC4 SCK1/RPI51/RC3 SDI1/RPI25/RA9 CVREF2O/SDO1/RP20/T1CK/RA4 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 AVDD AVSS AN6/OA3OUT/C4IN1+/OCFB/RC0 AN7/C3IN1-/C4IN1-/RC1 AN8/C3IN1+/U1RTS/BCLK1/RC2 AN11/C1IN2-(3)/U1CTS/RC11 VSS VDD AN12/C2IN2-(3)/U2RTS/BCLK2/RE12 AN13/C3IN2-(3)/U2CTS/RE13 AN14/RPI94/RE14 AN15/RPI95/RE15 SDA2/RPI24/RA8 SCL2/RP36/RB4 TDI/RA7 RPI46/T3CK/RB14 RPI47/T5CK/RB15 RP118/RG6 RPI119/RG7 RP120/RG8 MCLR RPI121/RG9 VSS VDD AN10/RPI28/RA12 AN9/RPI27/RA11 AN0/OA2OUT/RA0 AN1/C2IN1+/RA1 PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 PIC24EP64GP206 64 63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 1 48 2 47 3 46 4 45 5 44 6 43 7 42 8 41 9 40 10 39 11 38 12 37 13 36 14 35 15 34 16 33 17181920212223242526272829303132 Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: This pin is not available as an input when OPMODE (CMxCON<10>) = 1. 4: The metal pad at the bottom of the device is not connected to any pins and is recommended to be connected to VSS externally. 5: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. dsPIC33EP64GP506 PIC24EP128GP206 PIC24EP256GP206 dsPIC33EP128GP506 dsPIC33EP256GP506 dsPIC33EP512GP506 PIC24EP512GP206  2011-2013 Microchip Technology Inc. DS70000657H-page 21 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Pin Diagrams (Continued) 64-Pin QFN(1,2,3,4) = Pins are up to 5V tolerant 64636261605958575655545352515049 1 48 2 47 3 46 4 45 5 44 6 43 7 42 8 41 9 40 10 39 11 38 12 37 13 36 14 35 15 34 16 33 17181920212223242526272829303132 TDO/RA10 RPI45/PWM2L/CTPLS/RB13 RPI44/PWM2H/RB12 RP43/PWM3L/RB11 RP42/PWM3H/RB10 RP97/RF1 RPI96/RF0 VDD VCAP RP57/RC9 RD6 RD5 RP56/RC8 RP55/RC7 RP54/RC6 TMS/ASDA1/RP41/RB9(5) TCK/CVREF1O/ASCL1/RP40/T4CK/RB8 RC13 RP39/INT0/RB7 RPI58/RC10 PGEC2/ASCL2/RP38/RB6 PGED2/ASDA2/RP37/RB5 RD8 VSS OSC2/CLKO/RC15 OSC1/CLKI/RC12 VDD SCL1/RPI53/RC5 SDA1/RPI52/RC4 SCK1/RPI51/RC3 SDI1/RPI25/RA9 CVREF2O/SDO1/RP20/T1CK/RA4 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 AVDD AVSS AN6/OA3OUT/C4IN1+/OCFB/RC0 AN7/C3IN1-/C4IN1-/RC1 AN8/C3IN1+/U1RTS/BCLK1/FLT3/RC2 AN11/C1IN2-(3)/U1CTS/FLT4/RC11 VSS VDD AN12/C2IN2-(3)/U2RTS/BCLK2/RE12 AN13/C3IN2-(3)/U2CTS/RE13 AN14/RPI94/RE14 AN15/RPI95/RE15 SDA2/RPI24/RA8 FLT32/SCL2/RP36/RB4 TDI/RA7 RPI46/PWM1H/T3CK/RB14 RPI47/PWM1L/T5CK/RB15 RP118/RG6 RPI119/RG7 RP120/RG8 MCLR RPI121/RG9 VSS VDD AN10/RPI28/RA12 AN9/RPI27/RA11 AN0/OA2OUT/RA0 AN1/C2IN1+/RA1 PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 PIC24EP64MC206 dsPIC33EP64MC206/506 PIC24EP128MC206 PIC24EP256MC206 dsPIC33EP128MC206/506 dsPIC33EP256MC206/506 dsPIC33EP512MC206/506 PIC24EP512MC206 Note 1: The RPn/RPIn pins can be used by any remappable peripheral with some limitation. See Section 11.4 “Peripheral Pin Select (PPS)” for available peripherals and for information on limitations. 2: Every I/O port pin (RAx-RGx) can be used as a Change Notification pin (CNAx-CNGx). See Section 11.0 “I/O Ports” for more information. 3: This pin is not available as an input when OPMODE (CMxCON<10>) = 1. 4: The metal pad at the bottom of the device is not connected to any pins and is recommended to be connected to VSS externally. 5: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 22  2011-2013 Microchip Technology Inc. Table of Contents 1.0 Device Overview ........................................................................................................................................................................ 25 2.0 Guidelines for Getting Started with 16-bit Digital Signal Controllers and Microcontrollers......................................................... 29 3.0 CPU............................................................................................................................................................................................ 35 4.0 Memory Organization ................................................................................................................................................................. 45 5.0 Flash Program Memory............................................................................................................................................................ 119 6.0 Resets ..................................................................................................................................................................................... 123 7.0 Interrupt Controller ................................................................................................................................................................... 127 8.0 Direct Memory Access (DMA) .................................................................................................................................................. 139 9.0 Oscillator Configuration ............................................................................................................................................................ 153 10.0 Power-Saving Features............................................................................................................................................................ 163 11.0 I/O Ports ................................................................................................................................................................................... 173 12.0 Timer1 ...................................................................................................................................................................................... 203 13.0 Timer2/3 and Timer4/5 ............................................................................................................................................................ 207 14.0 Input Capture............................................................................................................................................................................ 213 15.0 Output Compare....................................................................................................................................................................... 219 16.0 High-Speed PWM Module (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X Devices Only) ....................................... 225 17.0 Quadrature Encoder Interface (QEI) Module (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X Devices Only)........... 249 18.0 Serial Peripheral Interface (SPI)............................................................................................................................................... 265 19.0 Inter-Integrated Circuit™ (I2C™).............................................................................................................................................. 273 20.0 Universal Asynchronous Receiver Transmitter (UART) ........................................................................................................... 281 21.0 Enhanced CAN (ECAN™) Module (dsPIC33EPXXXGP/MC50X Devices Only) ..................................................................... 287 22.0 Charge Time Measurement Unit (CTMU) ............................................................................................................................... 315 23.0 10-Bit/12-Bit Analog-to-Digital Converter (ADC) ...................................................................................................................... 321 24.0 Peripheral Trigger Generator (PTG) Module............................................................................................................................ 337 25.0 Op Amp/Comparator Module ................................................................................................................................................... 355 26.0 Programmable Cyclic Redundancy Check (CRC) Generator .................................................................................................. 373 27.0 Special Features ...................................................................................................................................................................... 379 28.0 Instruction Set Summary .......................................................................................................................................................... 387 29.0 Development Support............................................................................................................................................................... 397 30.0 Electrical Characteristics .......................................................................................................................................................... 401 31.0 High-Temperature Electrical Characteristics............................................................................................................................ 467 32.0 DC and AC Device Characteristics Graphs.............................................................................................................................. 475 33.0 Packaging Information.............................................................................................................................................................. 479 Appendix A: Revision History............................................................................................................................................................. 507 Index ................................................................................................................................................................................................. 517 The Microchip Web Site ..................................................................................................................................................................... 525 Customer Change Notification Service .............................................................................................................................................. 525 Customer Support.............................................................................................................................................................................. 525 Product Identification System............................................................................................................................................................. 527  2011-2013 Microchip Technology Inc. DS70000657H-page 23 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TO OUR VALUED CUSTOMERS It is our intention to provide our valued customers with the best documentation possible to ensure successful use of your Microchip products. To this end, we will continue to improve our publications to better suit your needs. Our publications will be refined and enhanced as new volumes and updates are introduced. If you have any questions or comments regarding this publication, please contact the Marketing Communications Department via E-mail at docerrors@microchip.com. We welcome your feedback. Most Current Data Sheet To obtain the most up-to-date version of this data sheet, please register at our Worldwide Web site at: http://www.microchip.com You can determine the version of a data sheet by examining its literature number found on the bottom outside corner of any page. The last character of the literature number is the version number, (e.g., DS30000000A is version A of document DS30000000). Errata An errata sheet, describing minor operational differences from the data sheet and recommended workarounds, may exist for current devices. As device/documentation issues become known to us, we will publish an errata sheet. The errata will specify the revision of silicon and revision of document to which it applies. To determine if an errata sheet exists for a particular device, please check with one of the following: • Microchip’s Worldwide Web site; http://www.microchip.com • Your local Microchip sales office (see last page) When contacting a sales office, please specify which device, revision of silicon and data sheet (include literature number) you are using. Customer Notification System Register on our web site at www.microchip.com to receive the most current information on all of our products. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 24  2011-2013 Microchip Technology Inc. Referenced Sources This device data sheet is based on the following individual chapters of the “dsPIC33/PIC24 Family Reference Manual”. These documents should be considered as the general reference for the operation of a particular module or device feature. • “Introduction” (DS70573) • “CPU” (DS70359) • “Data Memory” (DS70595) • “Program Memory” (DS70613) • “Flash Programming” (DS70609) • “Interrupts” (DS70600) • “Oscillator” (DS70580) • “Reset” (DS70602) • “Watchdog Timer and Power-Saving Modes” (DS70615) • “I/O Ports” (DS70598) • “Timers” (DS70362) • “Input Capture” (DS70352) • “Output Compare” (DS70358) • “High-Speed PWM” (DS70645) • “Quadrature Encoder Interface (QEI)” (DS70601) • “Analog-to-Digital Converter (ADC)” (DS70621) • “UART” (DS70582) • “Serial Peripheral Interface (SPI)” (DS70569) • “Inter-Integrated Circuit (I2C™)” (DS70330) • “Enhanced Controller Area Network (ECAN™)” (DS70353) • “Direct Memory Access (DMA)” (DS70348) • “CodeGuard™ Security” (DS70634) • “Programming and Diagnostics” (DS70608) • “Op Amp/Comparator” (DS70357) • “Programmable Cyclic Redundancy Check (CRC)” (DS70346) • “Device Configuration” (DS70618) • “Peripheral Trigger Generator (PTG)” (DS70669) • “Charge Time Measurement Unit (CTMU)” (DS70661) Note 1: To access the documents listed below, browse to the documentation section of the dsPIC33EP64MC506 product page of the Microchip web site (www.microchip.com) or select a family reference manual section from the following list. In addition to parameters, features and other documentation, the resulting page provides links to the related family reference manual sections.  2011-2013 Microchip Technology Inc. DS70000657H-page 25 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 1.0 DEVICE OVERVIEW This document contains device-specific information for the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X Digital Signal Controller (DSC) and Microcontroller (MCU) devices. dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X devices contain extensive Digital Signal Processor (DSP) functionality with a high-performance, 16-bit MCU architecture. Figure 1-1 shows a general block diagram of the core and peripheral modules. Table 1-1 lists the functions of the various pins shown in the pinout diagrams. FIGURE 1-1: dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X BLOCK DIAGRAM Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive resource. To complement the information in this data sheet, refer to the related section of the “dsPIC33/ PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com) 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. PORTA Power-up Timer Oscillator Start-up OSC1/CLKI MCLR VDD, VSS UART1, Timing Generation ECAN1(2) I2C1, ADC Timers Input Capture Output Compare AVDD, AVSS SPI2 UART2 SPI1, Watchdog Timer POR/BOR CRC I2C2 QEI1(1) PWM(1) Remappable Pins Note 1: This feature or peripheral is only available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices. 2: This feature or peripheral is only available on dsPIC33EPXXXGP/MC50X devices. Op Amp/ Comparator CTMU PTG CPU Refer to Figure 3-1 for CPU diagram details. 16 16 PORTB PORTC PORTD PORTE PORTF PORTG PORTS Peripheral Modules Timer dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 26  2011-2013 Microchip Technology Inc. TABLE 1-1: PINOUT I/O DESCRIPTIONS Pin Name(4) Pin Type Buffer Type PPS Description AN0-AN15 I Analog No Analog input channels. CLKI I ST/ CMOS No External clock source input. Always associated with OSC1 pin function. CLKO O — No Oscillator crystal output. Connects to crystal or resonator in Crystal Oscillator mode. Optionally functions as CLKO in RC and EC modes. Always associated with OSC2 pin function. OSC1 OSC2 I I/O ST/ CMOS — No No Oscillator crystal input. ST buffer when configured in RC mode; CMOS otherwise. Oscillator crystal output. Connects to crystal or resonator in Crystal Oscillator mode. Optionally functions as CLKO in RC and EC modes. REFCLKO O — Yes Reference clock output. IC1-IC4 I ST Yes Capture Inputs 1 through 4. OCFA OCFB OC1-OC4 I I O ST ST — Yes No Yes Compare Fault A input (for Compare channels). Compare Fault B input (for Compare channels). Compare Outputs 1 through 4. INT0 INT1 INT2 I I I ST ST ST No Yes Yes External Interrupt 0. External Interrupt 1. External Interrupt 2. RA0-RA4, RA7-RA12 I/O ST No PORTA is a bidirectional I/O port. RB0-RB15 I/O ST No PORTB is a bidirectional I/O port. RC0-RC13, RC15 I/O ST No PORTC is a bidirectional I/O port. RD5, RD6, RD8 I/O ST No PORTD is a bidirectional I/O port. RE12-RE15 I/O ST No PORTE is a bidirectional I/O port. RF0, RF1 I/O ST No PORTF is a bidirectional I/O port. RG6-RG9 I/O ST No PORTG is a bidirectional I/O port. T1CK T2CK T3CK T4CK T5CK I I I I I ST ST ST ST ST No Yes No No No Timer1 external clock input. Timer2 external clock input. Timer3 external clock input. Timer4 external clock input. Timer5 external clock input. CTPLS CTED1 CTED2 O I I ST ST ST No No No CTMU pulse output. CTMU External Edge Input 1. CTMU External Edge Input 2. U1CTS U1RTS U1RX U1TX BCLK1 I O I O O ST — ST — ST No No Yes Yes No UART1 Clear-To-Send. UART1 Ready-To-Send. UART1 receive. UART1 transmit. UART1 IrDA® baud clock output. Legend: CMOS = CMOS compatible input or output Analog = Analog input P = Power ST = Schmitt Trigger input with CMOS levels O = Output I = Input PPS = Peripheral Pin Select TTL = TTL input buffer Note 1: This pin is available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. 2: This pin is available on dsPIC33EPXXXGP/MC50X devices only. 3: This is the default Fault on Reset for dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices. See Section 16.0 “High-Speed PWM Module (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X Devices Only)” for more information. 4: Not all pins are available in all packages variants. See the “Pin Diagrams” section for pin availability. 5: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2.  2011-2013 Microchip Technology Inc. DS70000657H-page 27 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X U2CTS U2RTS U2RX U2TX BCLK2 I O I O O ST — ST — ST No No Yes Yes No UART2 Clear-To-Send. UART2 Ready-To-Send. UART2 receive. UART2 transmit. UART2 IrDA® baud clock output. SCK1 SDI1 SDO1 SS1 I/O I O I/O ST ST — ST No No No No Synchronous serial clock input/output for SPI1. SPI1 data in. SPI1 data out. SPI1 slave synchronization or frame pulse I/O. SCK2 SDI2 SDO2 SS2 I/O I O I/O ST ST — ST Yes Yes Yes Yes Synchronous serial clock input/output for SPI2. SPI2 data in. SPI2 data out. SPI2 slave synchronization or frame pulse I/O. SCL1 SDA1 ASCL1 ASDA1 I/O I/O I/O I/O ST ST ST ST No No No No Synchronous serial clock input/output for I2C1. Synchronous serial data input/output for I2C1. Alternate synchronous serial clock input/output for I2C1. Alternate synchronous serial data input/output for I2C1. SCL2 SDA2 ASCL2 ASDA2 I/O I/O I/O I/O ST ST ST ST No No No No Synchronous serial clock input/output for I2C2. Synchronous serial data input/output for I2C2. Alternate synchronous serial clock input/output for I2C2. Alternate synchronous serial data input/output for I2C2. TMS(5) TCK TDI TDO I I I O ST ST ST — No No No No JTAG Test mode select pin. JTAG test clock input pin. JTAG test data input pin. JTAG test data output pin. C1RX(2) C1TX(2) I O ST — Yes Yes ECAN1 bus receive pin. ECAN1 bus transmit pin. FLT1(1) , FLT2(1) FLT3(1) , FLT4(1) FLT32(1,3) DTCMP1-DTCMP3(1) PWM1L-PWM3L(1) PWM1H-PWM3H(1) SYNCI1(1) SYNCO1(1) I I I I O O I O ST ST ST ST — — ST — Yes No No Yes No No Yes Yes PWM Fault Inputs 1 and 2. PWM Fault Inputs 3 and 4. PWM Fault Input 32 (Class B Fault). PWM Dead-Time Compensation Inputs 1 through 3. PWM Low Outputs 1 through 3. PWM High Outputs 1 through 3. PWM Synchronization Input 1. PWM Synchronization Output 1. INDX1(1) HOME1(1) QEA1(1) QEB1(1) CNTCMP1(1) I I I I O ST ST ST ST — Yes Yes Yes Yes Yes Quadrature Encoder Index1 pulse input. Quadrature Encoder Home1 pulse input. Quadrature Encoder Phase A input in QEI1 mode. Auxiliary timer external clock/gate input in Timer mode. Quadrature Encoder Phase B input in QEI1 mode. Auxiliary timer external clock/gate input in Timer mode. Quadrature Encoder Compare Output 1. TABLE 1-1: PINOUT I/O DESCRIPTIONS (CONTINUED) Pin Name(4) Pin Type Buffer Type PPS Description Legend: CMOS = CMOS compatible input or output Analog = Analog input P = Power ST = Schmitt Trigger input with CMOS levels O = Output I = Input PPS = Peripheral Pin Select TTL = TTL input buffer Note 1: This pin is available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. 2: This pin is available on dsPIC33EPXXXGP/MC50X devices only. 3: This is the default Fault on Reset for dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices. See Section 16.0 “High-Speed PWM Module (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X Devices Only)” for more information. 4: Not all pins are available in all packages variants. See the “Pin Diagrams” section for pin availability. 5: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 28  2011-2013 Microchip Technology Inc. C1IN1- C1IN2- C1IN1+ OA1OUT C1OUT I I I O O Analog Analog Analog Analog — No No No No Yes Op Amp/Comparator 1 Negative Input 1. Comparator 1 Negative Input 2. Op Amp/Comparator 1 Positive Input 1. Op Amp 1 output. Comparator 1 output. C2IN1- C2IN2- C2IN1+ OA2OUT C2OUT I I I O O Analog Analog Analog Analog — No No No No Yes Op Amp/Comparator 2 Negative Input 1. Comparator 2 Negative Input 2. Op Amp/Comparator 2 Positive Input 1. Op Amp 2 output. Comparator 2 output. C3IN1- C3IN2- C3IN1+ OA3OUT C3OUT I I I O O Analog Analog Analog Analog — No No No No Yes Op Amp/Comparator 3 Negative Input 1. Comparator 3 Negative Input 2. Op Amp/Comparator 3 Positive Input 1. Op Amp 3 output. Comparator 3 output. C4IN1- C4IN1+ C4OUT I I O Analog Analog — No No Yes Comparator 4 Negative Input 1. Comparator 4 Positive Input 1. Comparator 4 output. CVREF1O CVREF2O O O Analog Analog No No Op amp/comparator voltage reference output. Op amp/comparator voltage reference divided by 2 output. PGED1 PGEC1 PGED2 PGEC2 PGED3 PGEC3 I/O I I/O I I/O I ST ST ST ST ST ST No No No No No No Data I/O pin for Programming/Debugging Communication Channel 1. Clock input pin for Programming/Debugging Communication Channel 1. Data I/O pin for Programming/Debugging Communication Channel 2. Clock input pin for Programming/Debugging Communication Channel 2. Data I/O pin for Programming/Debugging Communication Channel 3. Clock input pin for Programming/Debugging Communication Channel 3. MCLR I/P ST No Master Clear (Reset) input. This pin is an active-low Reset to the device. AVDD P P No Positive supply for analog modules. This pin must be connected at all times. AVSS P P No Ground reference for analog modules. This pin must be connected at all times. VDD P — No Positive supply for peripheral logic and I/O pins. VCAP P — No CPU logic filter capacitor connection. VSS P — No Ground reference for logic and I/O pins. VREF+ I Analog No Analog voltage reference (high) input. VREF- I Analog No Analog voltage reference (low) input. TABLE 1-1: PINOUT I/O DESCRIPTIONS (CONTINUED) Pin Name(4) Pin Type Buffer Type PPS Description Legend: CMOS = CMOS compatible input or output Analog = Analog input P = Power ST = Schmitt Trigger input with CMOS levels O = Output I = Input PPS = Peripheral Pin Select TTL = TTL input buffer Note 1: This pin is available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. 2: This pin is available on dsPIC33EPXXXGP/MC50X devices only. 3: This is the default Fault on Reset for dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices. See Section 16.0 “High-Speed PWM Module (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X Devices Only)” for more information. 4: Not all pins are available in all packages variants. See the “Pin Diagrams” section for pin availability. 5: There is an internal pull-up resistor connected to the TMS pin when the JTAG interface is active. See the JTAGEN bit field in Table 27-2.  2011-2013 Microchip Technology Inc. DS70000657H-page 29 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 2.0 GUIDELINES FOR GETTING STARTED WITH 16-BIT DIGITAL SIGNAL CONTROLLERS AND MICROCONTROLLERS 2.1 Basic Connection Requirements Getting started with the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families requires attention to a minimal set of device pin connections before proceeding with development. The following is a list of pin names, which must always be connected: • All VDD and VSS pins (see Section 2.2 “Decoupling Capacitors”) • All AVDD and AVSS pins (regardless if ADC module is not used) (see Section 2.2 “Decoupling Capacitors”) • VCAP (see Section 2.3 “CPU Logic Filter Capacitor Connection (VCAP)”) • MCLR pin (see Section 2.4 “Master Clear (MCLR) Pin”) • PGECx/PGEDx pins used for In-Circuit Serial Programming™ (ICSP™) and debugging purposes (see Section 2.5 “ICSP Pins”) • OSC1 and OSC2 pins when external oscillator source is used (see Section 2.6 “External Oscillator Pins”) Additionally, the following pins may be required: • VREF+/VREF- pins are used when external voltage reference for the ADC module is implemented 2.2 Decoupling Capacitors The use of decoupling capacitors on every pair of power supply pins, such as VDD, VSS, AVDD and AVSS is required. Consider the following criteria when using decoupling capacitors: • Value and type of capacitor: Recommendation of 0.1 µF (100 nF), 10-20V. This capacitor should be a low-ESR and have resonance frequency in the range of 20 MHz and higher. It is recommended to use ceramic capacitors. • Placement on the printed circuit board: The decoupling capacitors should be placed as close to the pins as possible. It is recommended to place the capacitors on the same side of the board as the device. If space is constricted, the capacitor can be placed on another layer on the PCB using a via; however, ensure that the trace length from the pin to the capacitor is within one-quarter inch (6 mm) in length. • Handling high-frequency noise: If the board is experiencing high-frequency noise, above tens of MHz, add a second ceramic-type capacitor in parallel to the above described decoupling capacitor. The value of the second capacitor can be in the range of 0.01 µF to 0.001 µF. Place this second capacitor next to the primary decoupling capacitor. In high-speed circuit designs, consider implementing a decade pair of capacitances as close to the power and ground pins as possible. For example, 0.1 µF in parallel with 0.001 µF. • Maximizing performance: On the board layout from the power supply circuit, run the power and return traces to the decoupling capacitors first, and then to the device pins. This ensures that the decoupling capacitors are first in the power chain. Equally important is to keep the trace length between the capacitor and the power pins to a minimum, thereby reducing PCB track inductance. Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to the related section of the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com) 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. Note: The AVDD and AVSS pins must be connected, independent of the ADC voltage reference source. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 30  2011-2013 Microchip Technology Inc. FIGURE 2-1: RECOMMENDED MINIMUM CONNECTION 2.2.1 TANK CAPACITORS On boards with power traces running longer than six inches in length, it is suggested to use a tank capacitor for integrated circuits including DSCs to supply a local power source. The value of the tank capacitor should be determined based on the trace resistance that connects the power supply source to the device and the maximum current drawn by the device in the application. In other words, select the tank capacitor so that it meets the acceptable voltage sag at the device. Typical values range from 4.7 µF to 47 µF. 2.3 CPU Logic Filter Capacitor Connection (VCAP) A low-ESR (< 1 Ohm) capacitor is required on the VCAP pin, which is used to stabilize the voltage regulator output voltage. The VCAP pin must not be connected to VDD and must have a capacitor greater than 4.7 µF (10 µF is recommended), 16V connected to ground. The type can be ceramic or tantalum. See Section 30.0 “Electrical Characteristics” for additional information. The placement of this capacitor should be close to the VCAP pin. It is recommended that the trace length not exceeds one-quarter inch (6 mm). See Section 27.3 “On-Chip Voltage Regulator” for details. 2.4 Master Clear (MCLR) Pin The MCLR pin provides two specific device functions: • Device Reset • Device Programming and Debugging. During device programming and debugging, the resistance and capacitance that can be added to the pin must be considered. Device programmers and debuggers drive the MCLR pin. Consequently, specific voltage levels (VIH and VIL) and fast signal transitions must not be adversely affected. Therefore, specific values of R and C will need to be adjusted based on the application and PCB requirements. For example, as shown in Figure 2-2, it is recommended that the capacitor, C, be isolated from the MCLR pin during programming and debugging operations. Place the components as shown in Figure 2-2 within one-quarter inch (6 mm) from the MCLR pin. FIGURE 2-2: EXAMPLE OF MCLR PIN CONNECTIONS dsPIC33E/PIC24E VDD VSS VDD VSS VSS VDD AVDD AVSS VDD VSS 0.1 µF Ceramic 0.1 µF Ceramic 0.1 µF Ceramic 0.1 µF Ceramic C R VDD MCLR 0.1 µF Ceramic VCAP L1(1) R1 10 µF Tantalum Note 1: As an option, instead of a hard-wired connection, an inductor (L1) can be substituted between VDD and AVDD to improve ADC noise rejection. The inductor impedance should be less than 1 and the inductor capacity greater than 10 mA. Where: f FCNV 2 = ------------- f 1   2 LC = ----------------------- L 1   2f C ---------------------     2 = (i.e., ADC conversion rate/2) Note 1: R  10 k is recommended. A suggested starting value is 10 k. Ensure that the MCLR pin VIH and VIL specifications are met. 2: R1  470 will limit any current flowing into MCLR from the external capacitor, C, in the event of MCLR pin breakdown, due to Electrostatic Discharge (ESD) or Electrical Overstress (EOS). Ensure that the MCLR pin VIH and VIL specifications are met. C R1(2) R(1) VDD MCLR JP dsPIC33E/PIC24E  2011-2013 Microchip Technology Inc. DS70000657H-page 31 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 2.5 ICSP Pins The PGECx and PGEDx pins are used for ICSP and debugging purposes. It is recommended to keep the trace length between the ICSP connector and the ICSP pins on the device as short as possible. If the ICSP connector is expected to experience an ESD event, a series resistor is recommended, with the value in the range of a few tens of Ohms, not to exceed 100 Ohms. Pull-up resistors, series diodes, and capacitors on the PGECx and PGEDx pins are not recommended as they will interfere with the programmer/debugger communications to the device. If such discrete components are an application requirement, they should be removed from the circuit during programming and debugging. Alternatively, refer to the AC/DC characteristics and timing requirements information in the respective device Flash programming specification for information on capacitive loading limits and pin Voltage Input High (VIH) and Voltage Input Low (VIL) requirements. Ensure that the “Communication Channel Select” (i.e., PGECx/PGEDx pins) programmed into the device matches the physical connections for the ICSP to MPLAB® PICkit™ 3, MPLAB ICD 3, or MPLAB REAL ICE™. For more information on MPLAB ICD 2, ICD 3 and REAL ICE connection requirements, refer to the following documents that are available on the Microchip web site. • “Using MPLAB® ICD 3” (poster) DS51765 • “MPLAB® ICD 3 Design Advisory” DS51764 • “MPLAB® REAL ICE™ In-Circuit Emulator User’s Guide” DS51616 • “Using MPLAB® REAL ICE™ In-Circuit Emulator” (poster) DS51749 2.6 External Oscillator Pins Many DSCs have options for at least two oscillators: a high-frequency Primary Oscillator and a low-frequency Secondary Oscillator. For details, see Section 9.0 “Oscillator Configuration” for details. The oscillator circuit should be placed on the same side of the board as the device. Also, place the oscillator circuit close to the respective oscillator pins, not exceeding one-half inch (12 mm) distance between them. The load capacitors should be placed next to the oscillator itself, on the same side of the board. Use a grounded copper pour around the oscillator circuit to isolate them from surrounding circuits. The grounded copper pour should be routed directly to the MCU ground. Do not run any signal traces or power traces inside the ground pour. Also, if using a two-sided board, avoid any traces on the other side of the board where the crystal is placed. A suggested layout is shown in Figure 2-3. FIGURE 2-3: SUGGESTED PLACEMENT OF THE OSCILLATOR CIRCUIT Main Oscillator Guard Ring Guard Trace Oscillator Pins dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 32  2011-2013 Microchip Technology Inc. 2.7 Oscillator Value Conditions on Device Start-up If the PLL of the target device is enabled and configured for the device start-up oscillator, the maximum oscillator source frequency must be limited to 3 MHz < FIN < 5.5 MHz to comply with device PLL start-up conditions. This means that if the external oscillator frequency is outside this range, the application must start-up in the FRC mode first. The default PLL settings after a POR with an oscillator frequency outside this range will violate the device operating speed. Once the device powers up, the application firmware can initialize the PLL SFRs, CLKDIV and PLLFBD, to a suitable value, and then perform a clock switch to the Oscillator + PLL clock source. Note that clock switching must be enabled in the device Configuration Word. 2.8 Unused I/Os Unused I/O pins should be configured as outputs and driven to a logic low state. Alternatively, connect a 1k to 10k resistor between VSS and unused pins, and drive the output to logic low. 2.9 Application Examples • Induction heating • Uninterruptable Power Supplies (UPS) • DC/AC inverters • Compressor motor control • Washing machine 3-phase motor control • BLDC motor control • Automotive HVAC, cooling fans, fuel pumps • Stepper motor control • Audio and fluid sensor monitoring • Camera lens focus and stability control • Speech (playback, hands-free kits, answering machines, VoIP) • Consumer audio • Industrial and building control (security systems and access control) • Barcode reading • Networking: LAN switches, gateways • Data storage device management • Smart cards and smart card readers Examples of typical application connections are shown in Figure 2-4 through Figure 2-8. FIGURE 2-4: BOOST CONVERTER IMPLEMENTATION IPFC VOUTPUT ADC Channel Op Amp/ ADC Channel PWM k1 k2 k3 FET dsPIC33EP VINPUT Comparator Output Driver  2011-2013 Microchip Technology Inc. DS70000657H-page 33 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 2-5: SINGLE-PHASE SYNCHRONOUS BUCK CONVERTER FIGURE 2-6: MULTIPHASE SYNCHRONOUS BUCK CONVERTER k1 Op Amp/ Comparator k2 k7 PWM PWM ADC Channel ADC Channel 5V Output I5V 12V Input FET Driver dsPIC33EP k5 k4 k3 k6 k7 Op Amp/Comparator Op Amp/Comparator ADC Channel Op Amp/Comparator ADC Channel PWM PWM PWM PWM PWM PWM 3.3V Output 12V Input FET Driver FET Driver FET Driver dsPIC33EP dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 34  2011-2013 Microchip Technology Inc. FIGURE 2-7: INTERLEAVED PFC FIGURE 2-8: BEMF VOLTAGE MEASURED USING THE ADC MODULE VAC VOUT+ Op Amp/Comparator PWM PWM ADC |VAC| k4 k3 FET dsPIC33EP Driver VOUTADC Channel FET Driver Op Amp/ k1 k2 Comparator Channel Op Amp/ Comparator 3-Phase Inverter PWM3H PWM3L PWM2H PWM2L PWM1H PWM1L FLTx Fault BLDC dsPIC33EP/PIC24EP AN3 AN4 AN5 AN2 Demand Phase Terminal Voltage Feedback R49 R41 R34 R36 R44 R52  2011-2013 Microchip Technology Inc. DS70000657H-page 35 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 3.0 CPU The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X CPU has a 16-bit (data) modified Harvard architecture with an enhanced instruction set, including significant support for digital signal processing. The CPU has a 24-bit instruction word with a variable length opcode field. The Program Counter (PC) is 23 bits wide and addresses up to 4M x 24 bits of user program memory space. An instruction prefetch mechanism helps maintain throughput and provides predictable execution. Most instructions execute in a single-cycle effective execution rate, with the exception of instructions that change the program flow, the double-word move (MOV.D) instruction, PSV accesses and the table instructions. Overhead-free program loop constructs are supported using the DO and REPEAT instructions, both of which are interruptible at any point. 3.1 Registers The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X devices have sixteen, 16-bit working registers in the programmer’s model. Each of the working registers can act as a data, address or address offset register. The 16th working register (W15) operates as a Software Stack Pointer for interrupts and calls. 3.2 Instruction Set The instruction set for dsPIC33EPXXXGP50X and dsPIC33EPXXXMC20X/50X devices has two classes of instructions: the MCU class of instructions and the DSP class of instructions. The instruction set for PIC24EPXXXGP/MC20X devices has the MCU class of instructions only and does not support DSP instructions. These two instruction classes are seamlessly integrated into the architecture and execute from a single execution unit. The instruction set includes many addressing modes and was designed for optimum C compiler efficiency. 3.3 Data Space Addressing The base Data Space can be addressed as 64 Kbytes (32K words). The Data Space includes two ranges of memory, referred to as X and Y data memory. Each memory range is accessible through its own independent Address Generation Unit (AGU). The MCU class of instructions operates solely through the X memory AGU, which accesses the entire memory map as one linear Data Space. On dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X devices, certain DSP instructions operate through the X and Y AGUs to support dual operand reads, which splits the data address space into two parts. The X and Y Data Spaces have memory locations that are device-specific, and are described further in the data memory maps in Section 4.2 “Data Address Space”. The upper 32 Kbytes of the Data Space memory map can optionally be mapped into Program Space (PS) at any 32-Kbyte aligned program word boundary. The Program-to-Data Space mapping feature, known as Program Space Visibility (PSV), lets any instruction access Program Space as if it were Data Space. Moreover, the Base Data Space address is used in conjunction with a Read or Write Page register (DSRPAG or DSWPAG) to form an Extended Data Space (EDS) address. The EDS can be addressed as 8M words or 16 Mbytes. Refer to the “Data Memory” (DS70595) and “Program Memory” (DS70613) sections in the “dsPIC33/PIC24 Family Reference Manual” for more details on EDS, PSV and table accesses. On the dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X devices, overhead-free circular buffers (Modulo Addressing) are supported in both X and Y address spaces. The Modulo Addressing removes the software boundary checking overhead for DSP algorithms. The X AGU Circular Addressing can be used with any of the MCU class of instructions. The X AGU also supports Bit-Reversed Addressing to greatly simplify input or output data re-ordering for radix-2 FFT algorithms. PIC24EPXXXGP/MC20X devices do not support Modulo and Bit-Reversed Addressing. 3.4 Addressing Modes The CPU supports these addressing modes: • Inherent (no operand) • Relative • Literal • Memory Direct • Register Direct • Register Indirect Each instruction is associated with a predefined addressing mode group, depending upon its functional requirements. As many as six addressing modes are supported for each instruction. Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “CPU” (DS70359) in the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 36  2011-2013 Microchip Technology Inc. FIGURE 3-1: dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X CPU BLOCK DIAGRAM Instruction Decode and Control 16 PCL 16 Program Counter 16-Bit ALU 24 24 24 24 X Data Bus PCU 16 16 16 Divide Support Engine(1) DSP ROM Latch 16 Y Data Bus(1) EA MUX X RAGU X WAGU Y AGU(1) 16 24 16 16 16 16 16 16 16 8 Interrupt Controller PSV and Table Data Access Control Block Stack Control Logic Loop Control Logic Data Latch Data Latch Y Data RAM(1) X Data RAM Address Latch Address Latch 16 Data Latch 16 16 16 X Address Bus Y Address Bus 24 Literal Data Program Memory Address Latch Power, Reset and Oscillator Control Signals to Various Blocks Ports Peripheral Modules Note 1: This feature is not available on PIC24EPXXXGP/MC20X devices. Modules PCH IR 16 x 16 W Register Array  2011-2013 Microchip Technology Inc. DS70000657H-page 37 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 3.5 Programmer’s Model The programmer’s model for the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X is shown in Figure 3-2. All registers in the programmer’s model are memory mapped and can be manipulated directly by instructions. Table 3-1 lists a description of each register. In addition to the registers contained in the programmer’s model, the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/ MC20X devices contain control registers for Modulo Addressing (dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X devices only), Bit-Reversed Addressing (dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X devices only) and interrupts. These registers are described in subsequent sections of this document. All registers associated with the programmer’s model are memory mapped, as shown in Table 4-1. TABLE 3-1: PROGRAMMER’S MODEL REGISTER DESCRIPTIONS Register(s) Name Description W0 through W15 Working Register Array ACCA, ACCB 40-Bit DSP Accumulators PC 23-Bit Program Counter SR ALU and DSP Engine STATUS Register SPLIM Stack Pointer Limit Value Register TBLPAG Table Memory Page Address Register DSRPAG Extended Data Space (EDS) Read Page Register DSWPAG Extended Data Space (EDS) Write Page Register RCOUNT REPEAT Loop Count Register DCOUNT(1) DO Loop Count Register DOSTARTH(1,2) , DOSTARTL(1,2) DO Loop Start Address Register (High and Low) DOENDH(1) , DOENDL(1) DO Loop End Address Register (High and Low) CORCON Contains DSP Engine, DO Loop Control and Trap Status bits Note 1: This register is available on dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X devices only. 2: The DOSTARTH and DOSTARTL registers are read-only. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 38  2011-2013 Microchip Technology Inc. FIGURE 3-2: PROGRAMMER’S MODEL N OV Z C TBLPAG PC23 PC0 7 0 D15 D0 Program Counter Data Table Page Address STATUS Register Working/Address Registers DSP Operand Registers W0 (WREG) W1 W2 W3 W4 W5 W6 W7 W8 W9 W10 W11 W12 W13 Frame Pointer/W14 Stack Pointer/W15 DSP Address Registers AD39 AD0 AD31 DSP Accumulators(1) ACCA ACCB DSRPAG 9 0 RA 0 OA(1) OB(1) SA(1) SB(1) RCOUNT 15 0 Repeat Loop Counter DCOUNT 15 0 DO Loop Counter and Stack(1) DOSTART 23 0 DO Loop Start Address and Stack(1) 0 DOEND DO Loop End Address and Stack(1) IPL2 IPL1 SPLIM Stack Pointer Limit AD15 23 0 SRL IPL0 PUSH.s and POP.s Shadows Nested DO Stack 0 0 OAB(1) SAB(1) X Data Space Read Page Address DA(1) DC 0 0 0 0 DSWPAG X Data Space Write Page Address 8 0 Note 1: This feature or bit is available on dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X devices only. CORCON 15 0 CPU Core Control Register  2011-2013 Microchip Technology Inc. DS70000657H-page 39 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 3.6 CPU Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 3.6.1 KEY RESOURCES • “CPU” (DS70359) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 40  2011-2013 Microchip Technology Inc. 3.7 CPU Control Registers REGISTER 3-1: SR: CPU STATUS REGISTER R/W-0 R/W-0 R/W-0 R/W-0 R/C-0 R/C-0 R-0 R/W-0 OA(1) OB(1) SA(1,4) SB(1,4) OAB(1) SAB(1) DA(1) DC bit 15 bit 8 R/W-0(2,3) R/W-0(2,3) R/W-0(2,3) R-0 R/W-0 R/W-0 R/W-0 R/W-0 IPL2 IPL1 IPL0 RA N OV Z C bit 7 bit 0 Legend: C = Clearable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’= Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 OA: Accumulator A Overflow Status bit(1) 1 = Accumulator A has overflowed 0 = Accumulator A has not overflowed bit 14 OB: Accumulator B Overflow Status bit(1) 1 = Accumulator B has overflowed 0 = Accumulator B has not overflowed bit 13 SA: Accumulator A Saturation ‘Sticky’ Status bit(1,4) 1 = Accumulator A is saturated or has been saturated at some time 0 = Accumulator A is not saturated bit 12 SB: Accumulator B Saturation ‘Sticky’ Status bit(1,4) 1 = Accumulator B is saturated or has been saturated at some time 0 = Accumulator B is not saturated bit 11 OAB: OA || OB Combined Accumulator Overflow Status bit(1) 1 = Accumulators A or B have overflowed 0 = Neither Accumulators A or B have overflowed bit 10 SAB: SA || SB Combined Accumulator ‘Sticky’ Status bit(1) 1 = Accumulators A or B are saturated or have been saturated at some time 0 = Neither Accumulators A or B are saturated bit 9 DA: DO Loop Active bit(1) 1 = DO loop is in progress 0 = DO loop is not in progress bit 8 DC: MCU ALU Half Carry/Borrow bit 1 = A carry-out from the 4th low-order bit (for byte-sized data) or 8th low-order bit (for word-sized data) of the result occurred 0 = No carry-out from the 4th low-order bit (for byte-sized data) or 8th low-order bit (for word-sized data) of the result occurred Note 1: This bit is available on dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X devices only. 2: The IPL<2:0> bits are concatenated with the IPL<3> bit (CORCON<3>) to form the CPU Interrupt Priority Level. The value in parentheses indicates the IPL, if IPL<3> = 1. User interrupts are disabled when IPL<3> = 1. 3: The IPL<2:0> Status bits are read-only when the NSTDIS bit (INTCON1<15>) = 1. 4: A data write to the SR register can modify the SA and SB bits by either a data write to SA and SB or by clearing the SAB bit. To avoid a possible SA or SB bit write race condition, the SA and SB bits should not be modified using bit operations.  2011-2013 Microchip Technology Inc. DS70000657H-page 41 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 7-5 IPL<2:0>: CPU Interrupt Priority Level Status bits(2,3) 111 = CPU Interrupt Priority Level is 7 (15); user interrupts are disabled 110 = CPU Interrupt Priority Level is 6 (14) 101 = CPU Interrupt Priority Level is 5 (13) 100 = CPU Interrupt Priority Level is 4 (12) 011 = CPU Interrupt Priority Level is 3 (11) 010 = CPU Interrupt Priority Level is 2 (10) 001 = CPU Interrupt Priority Level is 1 (9) 000 = CPU Interrupt Priority Level is 0 (8) bit 4 RA: REPEAT Loop Active bit 1 = REPEAT loop in progress 0 = REPEAT loop not in progress bit 3 N: MCU ALU Negative bit 1 = Result was negative 0 = Result was non-negative (zero or positive) bit 2 OV: MCU ALU Overflow bit This bit is used for signed arithmetic (2’s complement). It indicates an overflow of the magnitude that causes the sign bit to change state. 1 = Overflow occurred for signed arithmetic (in this arithmetic operation) 0 = No overflow occurred bit 1 Z: MCU ALU Zero bit 1 = An operation that affects the Z bit has set it at some time in the past 0 = The most recent operation that affects the Z bit has cleared it (i.e., a non-zero result) bit 0 C: MCU ALU Carry/Borrow bit 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 REGISTER 3-1: SR: CPU STATUS REGISTER (CONTINUED) Note 1: This bit is available on dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X devices only. 2: The IPL<2:0> bits are concatenated with the IPL<3> bit (CORCON<3>) to form the CPU Interrupt Priority Level. The value in parentheses indicates the IPL, if IPL<3> = 1. User interrupts are disabled when IPL<3> = 1. 3: The IPL<2:0> Status bits are read-only when the NSTDIS bit (INTCON1<15>) = 1. 4: A data write to the SR register can modify the SA and SB bits by either a data write to SA and SB or by clearing the SAB bit. To avoid a possible SA or SB bit write race condition, the SA and SB bits should not be modified using bit operations. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 42  2011-2013 Microchip Technology Inc. REGISTER 3-2: CORCON: CORE CONTROL REGISTER R/W-0 U-0 R/W-0 R/W-0 R/W-0 R-0 R-0 R-0 VAR — US1(1) US0(1) EDT(1,2) DL2(1) DL1(1) DL0(1) bit 15 bit 8 R/W-0 R/W-0 R/W-1 R/W-0 R/C-0 R-0 R/W-0 R/W-0 SATA(1) SATB(1) SATDW(1) ACCSAT(1) IPL3(3) SFA RND(1) IF(1) bit 7 bit 0 Legend: C = Clearable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 VAR: Variable Exception Processing Latency Control bit 1 = Variable exception processing latency is enabled 0 = Fixed exception processing latency is enabled bit 14 Unimplemented: Read as ‘0’ bit 13-12 US<1:0>: DSP Multiply Unsigned/Signed Control bits(1) 11 = Reserved 10 = DSP engine multiplies are mixed-sign 01 = DSP engine multiplies are unsigned 00 = DSP engine multiplies are signed bit 11 EDT: Early DO Loop Termination Control bit(1,2) 1 = Terminates executing DO loop at end of current loop iteration 0 = No effect bit 10-8 DL<2:0>: DO Loop Nesting Level Status bits(1) 111 = 7 DO loops are active • • • 001 = 1 DO loop is active 000 = 0 DO loops are active bit 7 SATA: ACCA Saturation Enable bit(1) 1 = Accumulator A saturation is enabled 0 = Accumulator A saturation is disabled bit 6 SATB: ACCB Saturation Enable bit(1) 1 = Accumulator B saturation is enabled 0 = Accumulator B saturation is disabled bit 5 SATDW: Data Space Write from DSP Engine Saturation Enable bit(1) 1 = Data Space write saturation is enabled 0 = Data Space write saturation is disabled bit 4 ACCSAT: Accumulator Saturation Mode Select bit(1) 1 = 9.31 saturation (super saturation) 0 = 1.31 saturation (normal saturation) bit 3 IPL3: CPU Interrupt Priority Level Status bit 3(3) 1 = CPU Interrupt Priority Level is greater than 7 0 = CPU Interrupt Priority Level is 7 or less Note 1: This bit is available on dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X devices only. 2: This bit is always read as ‘0’. 3: The IPL3 bit is concatenated with the IPL<2:0> bits (SR<7:5>) to form the CPU Interrupt Priority Level.  2011-2013 Microchip Technology Inc. DS70000657H-page 43 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 2 SFA: Stack Frame Active Status bit 1 = Stack frame is active; W14 and W15 address 0x0000 to 0xFFFF, regardless of DSRPAG and DSWPAG values 0 = Stack frame is not active; W14 and W15 address of EDS or Base Data Space bit 1 RND: Rounding Mode Select bit(1) 1 = Biased (conventional) rounding is enabled 0 = Unbiased (convergent) rounding is enabled bit 0 IF: Integer or Fractional Multiplier Mode Select bit(1) 1 = Integer mode is enabled for DSP multiply 0 = Fractional mode is enabled for DSP multiply REGISTER 3-2: CORCON: CORE CONTROL REGISTER (CONTINUED) Note 1: This bit is available on dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X devices only. 2: This bit is always read as ‘0’. 3: The IPL3 bit is concatenated with the IPL<2:0> bits (SR<7:5>) to form the CPU Interrupt Priority Level. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 44  2011-2013 Microchip Technology Inc. 3.8 Arithmetic Logic Unit (ALU) The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X ALU is 16 bits wide, and is capable of addition, subtraction, bit shifts and logic operations. Unless otherwise mentioned, arithmetic operations are two’s complement in nature. Depending on the operation, the ALU can affect the values of the Carry (C), Zero (Z), Negative (N), Overflow (OV) and Digit Carry (DC) Status bits in the SR register. The C and DC Status bits operate as Borrow and Digit Borrow bits, respectively, for subtraction operations. The ALU can perform 8-bit or 16-bit operations, depending on the mode of the instruction that is used. Data for the ALU operation can come from the W register array or data memory, depending on the addressing mode of the instruction. Likewise, output data from the ALU can be written to the W register array or a data memory location. Refer to the “16-bit MCU and DSC Programmer’s Reference Manual” (DS70157) for information on the SR bits affected by each instruction. The core CPU incorporates hardware support for both multiplication and division. This includes a dedicated hardware multiplier and support hardware for 16-bit divisor division. 3.8.1 MULTIPLIER Using the high-speed 17-bit x 17-bit multiplier, the ALU supports unsigned, signed, or mixed-sign operation in several MCU multiplication modes: • 16-bit x 16-bit signed • 16-bit x 16-bit unsigned • 16-bit signed x 5-bit (literal) unsigned • 16-bit signed x 16-bit unsigned • 16-bit unsigned x 5-bit (literal) unsigned • 16-bit unsigned x 16-bit signed • 8-bit unsigned x 8-bit unsigned 3.8.2 DIVIDER The divide block supports 32-bit/16-bit and 16-bit/16-bit signed and unsigned integer divide operations with the following data sizes: • 32-bit signed/16-bit signed divide • 32-bit unsigned/16-bit unsigned divide • 16-bit signed/16-bit signed divide • 16-bit unsigned/16-bit unsigned divide The quotient for all divide instructions ends up in W0 and the remainder in W1. The 16-bit signed and unsigned DIV instructions can specify any W register for both the 16-bit divisor (Wn) and any W register (aligned) pair (W(m + 1):Wm) for the 32-bit dividend. The divide algorithm takes one cycle per bit of divisor, so both 32-bit/16-bit and 16-bit/16-bit instructions take the same number of cycles to execute. 3.9 DSP Engine (dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X Devices Only) The DSP engine consists of a high-speed 17-bit x 17-bit multiplier, a 40-bit barrel shifter and a 40-bit adder/subtracter (with two target accumulators, round and saturation logic). The DSP engine can also perform inherent accumulatorto-accumulator operations that require no additional data. These instructions are ADD, SUB and NEG. The DSP engine has options selected through bits in the CPU Core Control register (CORCON), as listed below: • Fractional or integer DSP multiply (IF) • Signed, unsigned or mixed-sign DSP multiply (US) • Conventional or convergent rounding (RND) • Automatic saturation on/off for ACCA (SATA) • Automatic saturation on/off for ACCB (SATB) • Automatic saturation on/off for writes to data memory (SATDW) • Accumulator Saturation mode selection (ACCSAT) TABLE 3-2: DSP INSTRUCTIONS SUMMARY Instruction Algebraic Operation ACC Write Back CLR A = 0 Yes ED A = (x – y)2 No EDAC A = A + (x – y)2 No MAC A = A + (x • y) Yes MAC A = A + x2 No MOVSAC No change in A Yes MPY A = x • y No MPY A = x2 No MPY.N A = – x • y No MSC A = A – x • y Yes  2011-2013 Microchip Technology Inc. DS70000657H-page 45 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 4.0 MEMORY ORGANIZATION The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X architecture features separate program and data memory spaces, and buses. This architecture also allows the direct access of program memory from the Data Space (DS) during code execution. 4.1 Program Address Space The program address memory space of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X devices is 4M instructions. The space is addressable by a 24-bit value derived either from the 23-bit PC during program execution, or from table operation or Data Space remapping, as described in Section 4.8 “Interfacing Program and Data Memory Spaces”. User application access to the program memory space is restricted to the lower half of the address range (0x000000 to 0x7FFFFF). The exception is the use of TBLRD operations, which use TBLPAG<7> to read Device ID sections of the configuration memory space. The program memory maps, which are presented by device family and memory size, are shown in Figure 4-1 through Figure 4-5. FIGURE 4-1: PROGRAM MEMORY MAP FOR dsPIC33EP32GP50X, dsPIC33EP32MC20X/50X AND PIC24EP32GP/MC20X DEVICES Note: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Program Memory” (DS70613) in the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). Reset Address 0x000000 0x000002 Write Latches User Program Flash Memory 0x0057EC 0x0057EA (11K instructions) 0x800000 0xFA0000 0xFA0002 0xFA0004 DEVID 0xFEFFFE 0xFF0000 0xFFFFFE 0xF9FFFE Unimplemented (Read ‘0’s) GOTO Instruction 0x000004 Reserved 0x7FFFFE Reserved 0x000200 0x0001FE Interrupt Vector Table Configuration Memory Space User Memory Space Flash Configuration Bytes 0x005800 0x0057FE Reserved 0xFF0002 Note: Memory areas are not shown to scale. 0xFF0004 Reserved 0x800FF8 0x800FF6 0x801000 0x800FFE USERID dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 46  2011-2013 Microchip Technology Inc. FIGURE 4-2: PROGRAM MEMORY MAP FOR dsPIC33EP64GP50X, dsPIC33EP64MC20X/50X AND PIC24EP64GP/MC20X DEVICES Reset Address 0x000000 0x000002 Write Latches User Program Flash Memory 0x00AFEC 0x00AFEA (22K instructions) 0x800000 0xFA0000 0xFA0002 0xFA0004 DEVID 0xFEFFFE 0xFF0000 0xFFFFFE 0xF9FFFE Unimplemented (Read ‘0’s) GOTO Instruction 0x000004 Reserved 0x7FFFFE Reserved 0x000200 Interrupt Vector Table 0x0001FE Configuration Memory Space User Memory Space Flash Configuration Bytes 0x00B000 0x00AFFE Reserved 0xFF0002 Note: Memory areas are not shown to scale. 0xFF0004 Reserved 0x800FF8 0x800FF6 0x801000 0x800FFE USERID  2011-2013 Microchip Technology Inc. DS70000657H-page 47 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 4-3: PROGRAM MEMORY MAP FOR dsPIC33EP128GP50X, dsPIC33EP128MC20X/50X AND PIC24EP128GP/MC20X DEVICES Reset Address 0x000000 0x000002 Write Latches User Program Flash Memory 0x0157EC 0x0157EA (44K instructions) 0x800000 0xFA0000 0xFA0002 0xFA0004 DEVID 0xFEFFFE 0xFF0000 0xFFFFFE 0xF9FFFE Unimplemented (Read ‘0’s) GOTO Instruction 0x000004 Reserved 0x7FFFFE Reserved 0x000200 0x0001FE Interrupt Vector Table Configuration Memory Space User Memory Space Flash Configuration Bytes 0x015800 0x0157FE Reserved 0xFF0002 Note: Memory areas are not shown to scale. 0xFF0004 Reserved 0x800FF8 0x800FF6 0x801000 0x800FFE USERID dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 48  2011-2013 Microchip Technology Inc. FIGURE 4-4: PROGRAM MEMORY MAP FOR dsPIC33EP256GP50X, dsPIC33EP256MC20X/50X AND PIC24EP256GP/MC20X DEVICES Reset Address 0x000000 0x000002 Write Latches User Program Flash Memory 0x02AFEC 0x02AFEA (88K instructions) 0x800000 0xFA0000 0xFA0002 0xFA0004 DEVID 0xFEFFFE 0xFF0000 0xFFFFFE 0xF9FFFE Unimplemented (Read ‘0’s) GOTO Instruction 0x000004 Reserved 0x7FFFFE Reserved 0x000200 0x0001FE Interrupt Vector Table Configuration Memory Space User Memory Space Flash Configuration Bytes 0x02B000 0x02AFFE Reserved 0xFF0002 Note: Memory areas are not shown to scale. 0xFF0004 Reserved 0x800FF8 0x800FF6 0x801000 0x800FFE USERID  2011-2013 Microchip Technology Inc. DS70000657H-page 49 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 4-5: PROGRAM MEMORY MAP FOR dsPIC33EP512GP50X, dsPIC33EP512MC20X/50X AND PIC24EP512GP/MC20X DEVICES Reset Address 0x000000 0x000002 Write Latches User Program Flash Memory 0x0557EC 0x0557EA (175K instructions) 0x800000 0xFA0000 0xFA0002 0xFA0004 DEVID 0xFEFFFE 0xFF0000 0xFFFFFE 0xF9FFFE Unimplemented (Read ‘0’s) GOTO Instruction 0x000004 Reserved 0x7FFFFE Reserved 0x000200 Interrupt Vector Table 0x0001FE Configuration Memory Space User Memory Space Flash Configuration Bytes 0x055800 0x0557FE Reserved 0xFF0002 Note: Memory areas are not shown to scale. 0xFF0004 Reserved 0x800FF8 0x800FF6 0x801000 0x800FFE USERID dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 50  2011-2013 Microchip Technology Inc. 4.1.1 PROGRAM MEMORY ORGANIZATION The program memory space is organized in wordaddressable blocks. Although it is treated as 24 bits wide, it is more appropriate to think of each address of the program memory as a lower and upper word, with the upper byte of the upper word being unimplemented. The lower word always has an even address, while the upper word has an odd address (Figure 4-6). Program memory addresses are always word-aligned on the lower word and addresses are incremented, or decremented by two, during code execution. This arrangement provides compatibility with data memory space addressing and makes data in the program memory space accessible. 4.1.2 INTERRUPT AND TRAP VECTORS All dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X devices reserve the addresses between 0x000000 and 0x000200 for hardcoded program execution vectors. A hardware Reset vector is provided to redirect code execution from the default value of the PC on device Reset to the actual start of code. A GOTO instruction is programmed by the user application at address, 0x000000, of Flash memory, with the actual address for the start of code at address, 0x000002, of Flash memory. A more detailed discussion of the Interrupt Vector Tables (IVTs) is provided in Section 7.1 “Interrupt Vector Table”. FIGURE 4-6: PROGRAM MEMORY ORGANIZATION 16 8 0 PC Address 0x000000 0x000002 0x000004 0x000006 23 00000000 00000000 00000000 00000000 Program Memory ‘Phantom’ Byte (read as ‘0’) most significant word least significant word Instruction Width 0x000001 0x000003 0x000005 0x000007 msw Address (lsw Address)  2011-2013 Microchip Technology Inc. DS70000657H-page 51 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 4.2 Data Address Space The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X CPU has a separate 16-bit-wide data memory space. The Data Space is accessed using separate Address Generation Units (AGUs) for read and write operations. The data memory maps, which are presented by device family and memory size, are shown in Figure 4-7 through Figure 4-16. All Effective Addresses (EAs) in the data memory space are 16 bits wide and point to bytes within the Data Space. This arrangement gives a base Data Space address range of 64 Kbytes (32K words). The base Data Space address is used in conjunction with a Read or Write Page register (DSRPAG or DSWPAG) to form an Extended Data Space, which has a total address range of 16 Mbytes. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X devices implement up to 52 Kbytes of data memory (4 Kbytes of data memory for Special Function Registers and up to 48 Kbytes of data memory for RAM). If an EA points to a location outside of this area, an all-zero word or byte is returned. 4.2.1 DATA SPACE WIDTH The data memory space is organized in byteaddressable, 16-bit-wide blocks. Data is aligned in data memory and registers as 16-bit words, but all Data Space EAs resolve to bytes. The Least Significant Bytes (LSBs) of each word have even addresses, while the Most Significant Bytes (MSBs) have odd addresses. 4.2.2 DATA MEMORY ORGANIZATION AND ALIGNMENT To maintain backward compatibility with PIC® MCU devices and improve Data Space memory usage efficiency, the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/ MC20X instruction set supports both word and byte operations. As a consequence of byte accessibility, all Effective Address calculations are internally scaled to step through word-aligned memory. For example, the core recognizes that Post-Modified Register Indirect Addressing mode [Ws++] results in a value of Ws + 1 for byte operations and Ws + 2 for word operations. A data byte read, reads the complete word that contains the byte, using the LSb of any EA to determine which byte to select. The selected byte is placed onto the LSB of the data path. That is, data memory and registers are organized as two parallel, byte-wide entities with shared (word) address decode but separate write lines. Data byte writes only write to the corresponding side of the array or register that matches the byte address. All word accesses must be aligned to an even address. Misaligned word data fetches are not supported, so care must be taken when mixing byte and word operations, or translating from 8-bit MCU code. If a misaligned read or write is attempted, an address error trap is generated. If the error occurred on a read, the instruction underway is completed. If the error occurred on a write, the instruction is executed but the write does not occur. In either case, a trap is then executed, allowing the system and/or user application to examine the machine state prior to execution of the address Fault. All byte loads into any W register are loaded into the LSB. The MSB is not modified. A Sign-Extend (SE) instruction is provided to allow user applications to translate 8-bit signed data to 16-bit signed values. Alternatively, for 16-bit unsigned data, user applications can clear the MSB of any W register by executing a Zero-Extend (ZE) instruction on the appropriate address. 4.2.3 SFR SPACE The first 4 Kbytes of the Near Data Space, from 0x0000 to 0x0FFF, is primarily occupied by Special Function Registers (SFRs). These are used by the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X core and peripheral modules for controlling the operation of the device. SFRs are distributed among the modules that they control and are generally grouped together by module. Much of the SFR space contains unused addresses; these are read as ‘0’. 4.2.4 NEAR DATA SPACE The 8-Kbyte area, between 0x0000 and 0x1FFF, is referred to as the Near Data Space. Locations in this space are directly addressable through a 13-bit absolute address field within all memory direct instructions. Additionally, the whole Data Space is addressable using MOV instructions, which support Memory Direct Addressing mode with a 16-bit address field, or by using Indirect Addressing mode using a working register as an Address Pointer. Note: The actual set of peripheral features and interrupts varies by the device. Refer to the corresponding device tables and pinout diagrams for device-specific information. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 52  2011-2013 Microchip Technology Inc. FIGURE 4-7: DATA MEMORY MAP FOR dsPIC33EP32MC20X/50X AND dsPIC33EP32GP50X DEVICES 0x0000 0x0FFE 0x17FE 0xFFFE LSB 16 Bits Address MSB LSB MSB Address 0x0001 0x0FFF 0x17FF 0xFFFF Optionally Mapped into Program Memory Space 0x1FFF 0x1FFE 0x1001 0x1000 0x1801 0x1800 4-Kbyte SFR Space 4-Kbyte SRAM Space 0x2001 0x2000 Data Space Near 8-Kbyte SFR Space X Data RAM (X) X Data Unimplemented (X) 0x8001 0x8000 Note: Memory areas are not shown to scale. (PSV) Y Data RAM (Y)  2011-2013 Microchip Technology Inc. DS70000657H-page 53 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 4-8: DATA MEMORY MAP FOR dsPIC33EP64MC20X/50X AND dsPIC33EP64GP50X DEVICES 0x0000 0x0FFE 0x1FFE 0xFFFE LSB 16 Bits Address MSB LSB MSB Address 0x0001 0x0FFF 0x1FFF 0xFFFF Optionally Mapped into Program Memory Space 0x2FFF 0x2FFE 0x1001 0x1000 0x2001 0x2000 4-Kbyte SFR Space 8-Kbyte SRAM Space 0x3001 0x3000 Data Space Near 8-Kbyte SFR Space X Data RAM (X) X Data Unimplemented (X) 0x8001 0x8000 Note: Memory areas are not shown to scale. (PSV) Y Data RAM (Y) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 54  2011-2013 Microchip Technology Inc. FIGURE 4-9: DATA MEMORY MAP FOR dsPIC33EP128MC20X/50X AND dsPIC33EP128GP50X DEVICES 0x0000 0x0FFE 0x2FFE 0xFFFE LSB 16 Bits Address MSB LSB MSB Address 0x0001 0x0FFF 0x2FFF 0xFFFF Optionally Mapped into Program Memory Space 0x4FFF 0x4FFE 0x1001 0x1000 0x3001 0x3000 4-Kbyte SFR Space 16-Kbyte SRAM Space 0x5001 0x5000 Data Space Near 8-Kbyte SFR Space X Data RAM (X) X Data Unimplemented (X) 0x8001 0x8000 Note: Memory areas are not shown to scale. (PSV) 0x1FFF 0x1FFE 0x2001 0x2000 Y Data RAM (Y)  2011-2013 Microchip Technology Inc. DS70000657H-page 55 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 4-10: DATA MEMORY MAP FOR dsPIC33EP256MC20X/50X AND dsPIC33EP256GP50X DEVICES 0x0000 0x0FFE 0x4FFE 0xFFFE LSB 16 Bits Address MSB LSB MSB Address 0x0001 0x0FFF 0x4FFF 0xFFFF Optionally Mapped into Program Memory Space 0x8FFF 0x8FFE 0x1001 0x1000 0x5001 0x5000 4-Kbyte SFR Space 32-Kbyte SRAM Space 0x9001 0x9000 Data Space Near 8-Kbyte SFR Space X Data RAM (X) X Data Unimplemented (X) Y Data RAM (Y) Note: Memory areas are not shown to scale. (PSV) 0x1FFF 0x1FFE 0x2001 0x2000 0x7FFF 0x7FFE 0x8001 0x8000 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 56  2011-2013 Microchip Technology Inc. FIGURE 4-11: DATA MEMORY MAP FOR dsPIC33EP512MC20X/50X AND dsPIC33EP512GP50X DEVICES 0x0000 0x0FFE 0x7FFE 0xFFFE LSB 16 Bits Address MSB LSB MSB Address 0x0001 0x0FFF 0x7FFF 0xFFFF Optionally Mapped into Program Memory Space 0xEFFF 0xEFFE 0x1001 0x1000 0x8001 0x8000 4-Kbyte SFR Space 48-Kbyte SRAM Space 0xD001 0xD000 Data Space Near 8-Kbyte SFR Space X Data RAM (X) X Data Unimplemented (X) Note: Memory areas are not shown to scale. (PSV) 0x1FFF 0x1FFE 0x2001 0x2000 0x8FFF 0x8FFE 0x9001 0x9000 Y Data RAM (Y)  2011-2013 Microchip Technology Inc. DS70000657H-page 57 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 4-12: DATA MEMORY MAP FOR PIC24EP32GP/MC20X/50X DEVICES 0x0000 0x0FFE 0xFFFE LSB 16 Bits Address MSB LSB MSB Address 0x0001 0x0FFF 0xFFFF Optionally Mapped into Program Memory Space 0x1FFF 0x1FFE 0x1001 0x1000 4-Kbyte SFR Space 4-Kbyte SRAM Space 0x2001 0x2000 Data Space Near 8-Kbyte SFR Space X Data RAM (X) X Data Unimplemented (X) 0x8001 0x8000 Note: Memory areas are not shown to scale. (PSV) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 58  2011-2013 Microchip Technology Inc. FIGURE 4-13: DATA MEMORY MAP FOR PIC24EP64GP/MC20X/50X DEVICES 0x0000 0x0FFE 0x1FFE 0xFFFE LSB 16 Bits Address MSB LSB MSB Address 0x0001 0x0FFF 0x1FFF 0xFFFF Optionally Mapped into Program Memory Space 0x2FFF 0x2FFE 0x1001 0x1000 0x2001 0x2000 4-Kbyte SFR Space 8-Kbyte SRAM Space 0x3001 0x3000 Data Space Near 8-Kbyte SFR Space X Data RAM (X) X Data Unimplemented (X) 0x8001 0x8000 Note: Memory areas are not shown to scale. (PSV)  2011-2013 Microchip Technology Inc. DS70000657H-page 59 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 4-14: DATA MEMORY MAP FOR PIC24EP128GP/MC20X/50X DEVICES 0x0000 0x0FFE 0xFFFE LSB 16 Bits Address MSB LSB MSB Address 0x0001 0x0FFF 0xFFFF Optionally Mapped into Program Memory Space 0x4FFF 0x4FFE 0x1001 0x1000 4-Kbyte SFR Space 16-Kbyte SRAM Space 0x5001 0x5000 Data Space Near 8-Kbyte SFR Space X Data RAM (X) X Data Unimplemented (X) 0x8001 0x8000 Note: Memory areas are not shown to scale. (PSV) 0x1FFF 0x1FFE 0x2001 0x2000 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 60  2011-2013 Microchip Technology Inc. FIGURE 4-15: DATA MEMORY MAP FOR PIC24EP256GP/MC20X/50X DEVICES 0x0000 0x0FFE 0xFFFE LSB 16 Bits Address MSB LSB MSB Address 0x0001 0x0FFF 0xFFFF Optionally Mapped into Program Memory Space 0x8FFF 0x8FFE 0x1001 0x1000 4-Kbyte SFR Space 32-Kbyte SRAM Space 0x9001 0x9000 Data Space Near 8-Kbyte SFR Space X Data RAM (X) X Data Unimplemented (X) Note: Memory areas are not shown to scale. (PSV) 0x1FFF 0x1FFE 0x2001 0x2000 0x7FFF 0x7FFE 0x8001 0x8000  2011-2013 Microchip Technology Inc. DS70000657H-page 61 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 4-16: DATA MEMORY MAP FOR PIC24EP512GP/MC20X/50X DEVICES 0x0000 0x0FFE 0xFFFE LSB 16 Bits Address MSB LSB MSB Address 0x0001 0x0FFF 0xFFFF Optionally Mapped into Program Memory Space 0xEFFF 0xEFFE 0x1001 0x1000 4-Kbyte SFR Space 48-Kbyte SRAM Space 0xD001 0xD000 Data Space Near 8-Kbyte SFR Space X Data RAM (X) X Data Unimplemented (X) Note: Memory areas are not shown to scale. (PSV) 0x1FFF 0x1FFE 0x2001 0x2000 0x7FFF 0x7FFE 0x8001 0x8000 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 62  2011-2013 Microchip Technology Inc. 4.2.5 X AND Y DATA SPACES The dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X core has two Data Spaces, X and Y. These Data Spaces can be considered either separate (for some DSP instructions) or as one unified linear address range (for MCU instructions). The Data Spaces are accessed using two Address Generation Units (AGUs) and separate data paths. This feature allows certain instructions to concurrently fetch two words from RAM, thereby enabling efficient execution of DSP algorithms, such as Finite Impulse Response (FIR) filtering and Fast Fourier Transform (FFT). The X Data Space is used by all instructions and supports all addressing modes. X Data Space has separate read and write data buses. The X read data bus is the read data path for all instructions that view Data Space as combined X and Y address space. It is also the X data prefetch path for the dual operand DSP instructions (MAC class). The Y Data Space is used in concert with the X Data Space by the MAC class of instructions (CLR, ED, EDAC, MAC, MOVSAC, MPY, MPY.N and MSC) to provide two concurrent data read paths. Both the X and Y Data Spaces support Modulo Addressing mode for all instructions, subject to addressing mode restrictions. Bit-Reversed Addressing mode is only supported for writes to X Data Space. Modulo Addressing and Bit-Reversed Addressing are not present in PIC24EPXXXGP/MC20X devices. All data memory writes, including in DSP instructions, view Data Space as combined X and Y address space. The boundary between the X and Y Data Spaces is device-dependent and is not user-programmable. 4.3 Memory Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 4.3.1 KEY RESOURCES • “Program Memory” (DS70613) in the “dsPIC33/ PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464  2011-2013 Microchip Technology Inc. DS70000657H-page 63 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 4.4 Special Function Register Maps TABLE 4-1: CPU CORE REGISTER MAP FOR dsPIC33EPXXXMC20X/50X AND dsPIC33EPXXXGP50X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets W0 0000 W0 (WREG) xxxx W1 0002 W1 xxxx W2 0004 W2 xxxx W3 0006 W3 xxxx W4 0008 W4 xxxx W5 000A W5 xxxx W6 000C W6 xxxx W7 000E W7 xxxx W8 0010 W8 xxxx W9 0012 W9 xxxx W10 0014 W10 xxxx W11 0016 W11 xxxx W12 0018 W12 xxxx W13 001A W13 xxxx W14 001C W14 xxxx W15 001E W15 xxxx SPLIM 0020 SPLIM 0000 ACCAL 0022 ACCAL 0000 ACCAH 0024 ACCAH 0000 ACCAU 0026 Sign Extension of ACCA<39> ACCAU 0000 ACCBL 0028 ACCBL 0000 ACCBH 002A ACCBH 0000 ACCBU 002C Sign Extension of ACCB<39> ACCBU 0000 PCL 002E PCL<15:0> — 0000 PCH 0030 — — — — — — — — — PCH<6:0> 0000 DSRPAG 0032 — — — — — — DSRPAG<9:0> 0001 DSWPAG 0034 — — — — — — — DSWPAG<8:0> 0001 RCOUNT 0036 RCOUNT<15:0> 0000 DCOUNT 0038 DCOUNT<15:0> 0000 DOSTARTL 003A DOSTARTL<15:1> — 0000 DOSTARTH 003C — — — — — — — — — — DOSTARTH<5:0> 0000 DOENDL 003E DOENDL<15:1> — 0000 DOENDH 0040 — — — — — — — — — — DOENDH<5:0> 0000 Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 64 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. SR 0042 OA OB SA SB OAB SAB DA DC IPL2 IPL1 IPL0 RA N OV Z C 0000 CORCON 0044 VAR — US<1:0> EDT DL<2:0> SATA SATB SATDW ACCSAT IPL3 SFA RND IF 0020 MODCON 0046 XMODEN YMODEN — — BWM<3:0> YWM<3:0> XWM<3:0> 0000 XMODSRT 0048 XMODSRT<15:0> — 0000 XMODEND 004A XMODEND<15:0> — 0001 YMODSRT 004C YMODSRT<15:0> — 0000 YMODEND 004E YMODEND<15:0> — 0001 XBREV 0050 BREN XBREV<14:0> 0000 DISICNT 0052 — — DISICNT<13:0> 0000 TBLPAG 0054 — — — — — — — — TBLPAG<7:0> 0000 MSTRPR 0058 MSTRPR<15:0> 0000 TABLE 4-1: CPU CORE REGISTER MAP FOR dsPIC33EPXXXMC20X/50X AND dsPIC33EPXXXGP50X DEVICES ONLY (CONTINUED) File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 65 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-2: CPU CORE REGISTER MAP FOR PIC24EPXXXGP/MC20X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets W0 0000 W0 (WREG) xxxx W1 0002 W1 xxxx W2 0004 W2 xxxx W3 0006 W3 xxxx W4 0008 W4 xxxx W5 000A W5 xxxx W6 000C W6 xxxx W7 000E W7 xxxx W8 0010 W8 xxxx W9 0012 W9 xxxx W10 0014 W10 xxxx W11 0016 W11 xxxx W12 0018 W12 xxxx W13 001A W13 xxxx W14 001C W14 xxxx W15 001E W15 xxxx SPLIM 0020 SPLIM<15:0> 0000 PCL 002E PCL<15:1> — 0000 PCH 0030 — — — — — — — — — PCH<6:0> 0000 DSRPAG 0032 — — — — — — DSRPAG<9:0> 0001 DSWPAG 0034 — — — — — — — DSWPAG<8:0> 0001 RCOUNT 0036 RCOUNT<15:0> 0000 SR 0042 — — — — — — — DC IPL2 IPL1 IPL0 RA N OV Z C 0000 CORCON 0044 VAR — — — — — — — — — — — IPL3 SFA — — 0020 DISICNT 0052 — — DISICNT<13:0> 0000 TBLPAG 0054 — — — — — — — — TBLPAG<7:0> 0000 MSTRPR 0058 MSTRPR<15:0> 0000 Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 66 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-3: INTERRUPT CONTROLLER REGISTER MAP FOR PIC24EPXXXGP20X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets IFS0 0800 — DMA1IF AD1IF U1TXIF U1RXIF SPI1IF SPI1EIF T3IF T2IF OC2IF IC2IF DMA0IF T1IF OC1IF IC1IF INT0IF 0000 IFS1 0802 U2TXIF U2RXIF INT2IF T5IF T4IF OC4IF OC3IF DMA2IF — — — INT1IF CNIF CMIF MI2C1IF SI2C1IF 0000 IFS2 0804 — — — — — — — — — IC4IF IC3IF DMA3IF — — SPI2IF SPI2EIF 0000 IFS3 0806 — — — — — — — — — — — — — MI2C2IF SI2C2IF — 0000 IFS4 0808 — — CTMUIF — — — — — — — — — CRCIF U2EIF U1EIF — 0000 IFS8 0810 JTAGIF ICDIF — — — — — — — — — — — — — — 0000 IFS9 0812 — — — — — — — — — PTG3IF PTG2IF PTG1IF PTG0IF PTGWDTIF PTGSTEPIF — 0000 IEC0 0820 — DMA1IE AD1IE U1TXIE U1RXIE SPI1IE SPI1EIE T3IE T2IE OC2IE IC2IE DMA0IE T1IE OC1IE IC1IE INT0IE 0000 IEC1 0822 U2TXIE U2RXIE INT2IE T5IE T4IE OC4IE OC3IE DMA2IE — — — INT1IE CNIE CMIE MI2C1IE SI2C1IE 0000 IEC2 0824 — — — — — — — — — IC4IE IC3IE DMA3IE — — SPI2IE SPI2EIE 0000 IEC3 0826 — — — — — — — — — — — — — MI2C2IE SI2C2IE — 0000 IEC4 0828 — — CTMUIE — — — — — — — — — CRCIE U2EIE U1EIE — 0000 IEC8 0830 JTAGIE ICDIE — — — — — — — — — — — — — — 0000 IEC9 0832 — — — — — — — — — PTG3IE PTG2IE PTG1IE PTG0IE PTGWDTIE PTGSTEPIE — 0000 IPC0 0840 — T1IP<2:0> — OC1IP<2:0> — IC1IP<2:0> — INT0IP<2:0> 4444 IPC1 0842 — T2IP<2:0> — OC2IP<2:0> — IC2IP<2:0> — DMA0IP<2:0> 4444 IPC2 0844 — U1RXIP<2:0> — SPI1IP<2:0> — SPI1EIP<2:0> — T3IP<2:0> 4444 IPC3 0846 — — — — — DMA1IP<2:0> — AD1IP<2:0> — U1TXIP<2:0> 0444 IPC4 0848 — CNIP<2:0> — CMIP<2:0> — MI2C1IP<2:0> — SI2C1IP<2:0> 4444 IPC5 084A — — — — — — — — — — — — — INT1IP<2:0> 0004 IPC6 084C — T4IP<2:0> — OC4IP<2:0> — OC3IP<2:0> — DMA2IP<2:0> 4444 IPC7 084E — U2TXIP<2:0> — U2RXIP<2:0> — INT2IP<2:0> — T5IP<2:0> 4444 IPC8 0850 — — — — — — — — — SPI2IP<2:0> — SPI2EIP<2:0> 0044 IPC9 0852 — — — — — IC4IP<2:0> — IC3IP<2:0> — DMA3IP<2:0> 0444 IPC12 0858 — — — — — MI2C2IP<2:0> — SI2C2IP<2:0> — — — — 0440 IPC16 0860 — CRCIP<2:0> — U2EIP<2:0> — U1EIP<2:0> — — — — 4440 IPC19 0866 — — — — — — — — — CTMUIP<2:0> — — — — 0040 IPC35 0886 — JTAGIP<2:0> — ICDIP<2:0> — — — — — — — — 4400 IPC36 0888 — PTG0IP<2:0> — PTGWDTIP<2:0> — PTGSTEPIP<2:0> — — — — 4440 IPC37 088A — — — — — PTG3IP<2:0> — PTG2IP<2:0> — PTG1IP<2:0> 0444 INTCON1 08C0 NSTDIS OVAERR OVBERR — — — — — — DIV0ERR DMACERR MATHERR ADDRERR STKERR OSCFAIL — 0000 INTCON2 08C2 GIE DISI SWTRAP — — — — — — — — — — INT2EP INT1EP INT0EP 8000 INTCON3 08C4 — — — — — — — — — — DAE DOOVR — — — — 0000 INTCON4 08C6 — — — — — — — — — — — — — — — SGHT 0000 INTTREG 08C8 — — — — ILR<3:0> VECNUM<7:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 67 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-4: INTERRUPT CONTROLLER REGISTER MAP FOR PIC24EPXXXMC20X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets IFS0 0800 — DMA1IF AD1IF U1TXIF U1RXIF SPI1IF SPI1EIF T3IF T2IF OC2IF IC2IF DMA0IF T1IF OC1IF IC1IF INT0IF 0000 IFS1 0802 U2TXIF U2RXIF INT2IF T5IF T4IF OC4IF OC3IF DMA2IF — — — INT1IF CNIF CMIF MI2C1IF SI2C1IF 0000 IFS2 0804 — — — — — — — — — IC4IF IC3IF DMA3IF — — SPI2IF SPI2EIF 0000 IFS3 0806 — — — — — QEI1IF PSEMIF — — — — — — MI2C2IF SI2C2IF — 0000 IFS4 0808 — — CTMUIF — — — — — — — — — CRCIF U2EIF U1EIF — 0000 IFS5 080A PWM2IF PWM1IF — — — — — — — — — — — — — — 0000 IFS6 080C — — — — — — — — — — — — — — — PWM3IF 0000 IFS8 0810 JTAGIF ICDIF — — — — — — — — — — — — — — 0000 IFS9 0812 — — — — — — — — — PTG3IF PTG2IF PTG1IF PTG0IF PTGWDTIF PTGSTEPIF — 0000 IEC0 0820 — DMA1IE AD1IE U1TXIE U1RXIE SPI1IE SPI1EIE T3IE T2IE OC2IE IC2IE DMA0IE T1IE OC1IE IC1IE INT0IE 0000 IEC1 0822 U2TXIE U2RXIE INT2IE T5IE T4IE OC4IE OC3IE DMA2IE — — — INT1IE CNIE CMIE MI2C1IE SI2C1IE 0000 IEC2 0824 — — — — — — — — — IC4IE IC3IE DMA3IE — — SPI2IE SPI2EIE 0000 IEC3 0826 — — — — — QEI1IE PSEMIE — — — — — — MI2C2IE SI2C2IE — 0000 IEC4 0828 — — CTMUIE — — — — — — — — — CRCIE U2EIE U1EIE — 0000 IEC5 082A PWM2IE PWM1IE — — — — — — — — — — — — — — 0000 IEC6 082C — — — — — — — — — — — — — — — PWM3IE 0000 IEC8 0830 JTAGIE ICDIE — — — — — — — — — — — — — — 0000 IEC9 0832 — — — — — — — — — PTG3IE PTG2IE PTG1IE PTG0IE PTGWDTIE PTGSTEPIE — 0000 IPC0 0840 — T1IP<2:0> — OC1IP<2:0> — IC1IP<2:0> — INT0IP<2:0> 4444 IPC1 0842 — T2IP<2:0> — OC2IP<2:0> — IC2IP<2:0> — DMA0IP<2:0> 4444 IPC2 0844 — U1RXIP<2:0> — SPI1IP<2:0> — SPI1EIP<2:0> — T3IP<2:0> 4444 IPC3 0846 — — — — — DMA1IP<2:0> — AD1IP<2:0> — U1TXIP<2:0> 0444 IPC4 0848 — CNIP<2:0> — CMIP<2:0> — MI2C1IP<2:0> — SI2C1IP<2:0> 4444 IPC5 084A — — — — — — — — — — — — — INT1IP<2:0> 0004 IPC6 084C — T4IP<2:0> — OC4IP<2:0> — OC3IP<2:0> — DMA2IP<2:0> 4444 IPC7 084E — U2TXIP<2:0> — U2RXIP<2:0> — INT2IP<2:0> — T5IP<2:0> 4444 IPC8 0850 — — — — — — — — — SPI2IP<2:0> — SPI2EIP<2:0> 0044 IPC9 0852 — — — — — IC4IP<2:0> — IC3IP<2:0> — DMA3IP<2:0> 0444 IPC12 0858 — — — — — MI2C2IP<2:0> — SI2C2IP<2:0> — — — — 0440 IPC14 085C — — — — — QEI1IP<2:0> — PSEMIP<2:0> — — — — 0440 IPC16 0860 — CRCIP<2:0> — U2EIP<2:0> — U1EIP<2:0> — — — — 4440 IPC19 0866 — — — — — — — — — CTMUIP<2:0> — — — — 0040 IPC23 086E — PWM2IP<2:0> — PWM1IP<2:0> — — — — — — — — 4400 IPC24 0870 — — — — — — — — — — — — — PWM3IP<2:0> 4004 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 68 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. IPC35 0886 — JTAGIP<2:0> — ICDIP<2:0> — — — — — — — — 4400 IPC36 0888 — PTG0IP<2:0> — PTGWDTIP<2:0> — PTGSTEPIP<2:0> — — — — 4440 IPC37 088A — — — — — PTG3IP<2:0> — PTG2IP<2:0> — PTG1IP<2:0> 0444 INTCON1 08C0 NSTDIS OVAERR OVBERR — — — — — — DIV0ERR DMACERR MATHERR ADDRERR STKERR OSCFAIL — 0000 INTCON2 08C2 GIE DISI SWTRAP — — — — — — — — — — INT2EP INT1EP INT0EP 8000 INTCON3 08C4 — — — — — — — — — — DAE DOOVR — — — — 0000 INTCON4 08C6 — — — — — — — — — — — — — — — SGHT 0000 INTTREG 08C8 — — — — ILR<3:0> VECNUM<7:0> 0000 TABLE 4-4: INTERRUPT CONTROLLER REGISTER MAP FOR PIC24EPXXXMC20X DEVICES ONLY (CONTINUED) File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 69 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-5: INTERRUPT CONTROLLER REGISTER MAP FOR dsPIC33EPXXXGP50X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets IFS0 0800 — DMA1IF AD1IF U1TXIF U1RXIF SPI1IF SPI1EIF T3IF T2IF OC2IF IC2IF DMA0IF T1IF OC1IF IC1IF INT0IF 0000 IFS1 0802 U2TXIF U2RXIF INT2IF T5IF T4IF OC4IF OC3IF DMA2IF — — — INT1IF CNIF CMIF MI2C1IF SI2C1IF 0000 IFS2 0804 — — — — — — — — — IC4IF IC3IF DMA3IF C1IF C1RXIF SPI2IF SPI2EIF 0000 IFS3 0806 — — — — — — — — — — — — — MI2C2IF SI2C2IF — 0000 IFS4 0808 — — CTMUIF — — — — — — C1TXIF — — CRCIF U2EIF U1EIF — 0000 IFS6 080C — — — — — — — — — — — — — — — PWM3IF 0000 IFS8 0810 JTAGIF ICDIF — — — — — — — — — — — — — — 0000 IFS9 0812 — — — — — — — — — PTG3IF PTG2IF PTG1IF PTG0IF PTGWDTIF PTGSTEPIF — 0000 IEC0 0820 — DMA1IE AD1IE U1TXIE U1RXIE SPI1IE SPI1EIE T3IE T2IE OC2IE IC2IE DMA0IE T1IE OC1IE IC1IE INT0IE 0000 IEC1 0822 U2TXIE U2RXIE INT2IE T5IE T4IE OC4IE OC3IE DMA2IE — — — INT1IE CNIE CMIE MI2C1IE SI2C1IE 0000 IEC2 0824 — — — — — — — — — IC4IE IC3IE DMA3IE C1IE C1RXIE SPI2IE SPI2EIE 0000 IEC3 0826 — — — — — — — — — — — — — MI2C2IE SI2C2IE — 0000 IEC4 0828 — — CTMUIE — — — — — — C1TXIE — — CRCIE U2EIE U1EIE — 0000 IEC8 0830 JTAGIE ICDIE — — — — — — — — — — — — — — 0000 IEC9 0832 — — — — — — — — — PTG3IE PTG2IE PTG1IE PTG0IE PTGWDTIE PTGSTEPIE — 0000 IPC0 0840 — T1IP<2:0> — OC1IP<2:0> — IC1IP<2:0> — INT0IP<2:0> 4444 IPC1 0842 — T2IP<2:0> — OC2IP<2:0> — IC2IP<2:0> — DMA0IP<2:0> 4444 IPC2 0844 — U1RXIP<2:0> — SPI1IP<2:0> — SPI1EIP<2:0> — T3IP<2:0> 4444 IPC3 0846 — — — — — DMA1IP<2:0> — AD1IP<2:0> — U1TXIP<2:0> 0444 IPC4 0848 — CNIP<2:0> — CMIP<2:0> — MI2C1IP<2:0> — SI2C1IP<2:0> 4444 IPC5 084A — — — — — — — — — — — — — INT1IP<2:0> 0004 IPC6 084C — T4IP<2:0> — OC4IP<2:0> — OC3IP<2:0> — DMA2IP<2:0> 4444 IPC7 084E — U2TXIP<2:0> — U2RXIP<2:0> — INT2IP<2:0> — T5IP<2:0> 4444 IPC8 0850 — C1IP<2:0> — C1RXIP<2:0> — SPI2IP<2:0> — SPI2EIP<2:0> 4444 IPC9 0852 — — — — — IC4IP<2:0> — IC3IP<2:0> — DMA3IP<2:0> 0444 IPC11 0856 — — — — — — — — — — — — — — — — 0000 IPC12 0858 — — — — — MI2C2IP<2:0> — SI2C2IP<2:0> — — — — 0440 IPC16 0860 — CRCIP<2:0> — U2EIP<2:0> — U1EIP<2:0> — — — — 4440 IPC17 0862 — — — — — C1TXIP<2:0> — — — — — — — — 0400 IPC19 0866 — — — — — — — — — CTMUIP<2:0> — — — — 0040 IPC35 0886 — JTAGIP<2:0> — ICDIP<2:0> — — — — — — — — 4400 IPC36 0888 — PTG0IP<2:0> — PTGWDTIP<2:0> — PTGSTEPIP<2:0> — — — — 4440 IPC37 088A — — — — — PTG3IP<2:0> — PTG2IP<2:0> — PTG1IP<2:0> 0444 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 70 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. INTCON1 08C0 NSTDIS OVAERR OVBERR COVAERR COVBERR OVATE OVBTE COVTE SFTACERR DIV0ERR DMACERR MATHERR ADDRERR STKERR OSCFAIL — 0000 INTCON2 08C2 GIE DISI SWTRAP — — — — — — — — — — INT2EP INT1EP INT0EP 8000 INTCON3 08C4 — — — — — — — — — — DAE DOOVR — — — — 0000 INTCON4 08C6 — — — — — — — — — — — — — — — SGHT 0000 INTTREG 08C8 — — — — ILR<3:0> VECNUM<7:0> 0000 TABLE 4-5: INTERRUPT CONTROLLER REGISTER MAP FOR dsPIC33EPXXXGP50X DEVICES ONLY (CONTINUED) File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 71 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-6: INTERRUPT CONTROLLER REGISTER MAP FOR dsPIC33EPXXXMC20X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets IFS0 0800 — DMA1IF AD1IF U1TXIF U1RXIF SPI1IF SPI1EIF T3IF T2IF OC2IF IC2IF DMA0IF T1IF OC1IF IC1IF INT0IF 0000 IFS1 0802 U2TXIF U2RXIF INT2IF T5IF T4IF OC4IF OC3IF DMA2IF — — — INT1IF CNIF CMIF MI2C1IF SI2C1IF 0000 IFS2 0804 — — — — — — — — — IC4IF IC3IF DMA3IF — — SPI2IF SPI2EIF 0000 IFS3 0806 — — — — — QEI1IF PSEMIF — — — — — — MI2C2IF SI2C2IF — 0000 IFS4 0808 — — CTMUIF — — — — — — — — — CRCIF U2EIF U1EIF — 0000 IFS5 080A PWM2IF PWM1IF — — — — — — — — — — — — — — 0000 IFS6 080C — — — — — — — — — — — — — — — PWM3IF 0000 IFS8 0810 JTAGIF ICDIF — — — — — — — — — — — — — — 0000 IFS9 0812 — — — — — — — — — PTG3IF PTG2IF PTG1IF PTG0IF PTGWDTIF PTGSTEPIF — 0000 IEC0 0820 — DMA1IE AD1IE U1TXIE U1RXIE SPI1IE SPI1EIE T3IE T2IE OC2IE IC2IE DMA0IE T1IE OC1IE IC1IE INT0IE 0000 IEC1 0822 U2TXIE U2RXIE INT2IE T5IE T4IE OC4IE OC3IE DMA2IE — — — INT1IE CNIE CMIE MI2C1IE SI2C1IE 0000 IEC2 0824 — — — — — — — — — IC4IE IC3IE DMA3IE — — SPI2IE SPI2EIE 0000 IEC3 0826 — — — — — QEI1IE PSEMIE — — — — — — MI2C2IE SI2C2IE — 0000 IEC4 0828 — — CTMUIE — — — — — — — — — CRCIE U2EIE U1EIE — 0000 IEC5 082A PWM2IE PWM1IE — — — — — — — — — — — — — — 0000 IEC6 082C — — — — — — — — — — — — — — — PWM3IE 0000 IEC8 0830 JTAGIE ICDIE — — — — — — — — — — — — — — 0000 IEC9 0832 — — — — — — — — — PTG3IE PTG2IE PTG1IE PTG0IE PTGWDTIE PTGSTEPIE — 0000 IPC0 0840 — T1IP<2:0> — OC1IP<2:0> — IC1IP<2:0> — INT0IP<2:0> 4444 IPC1 0842 — T2IP<2:0> — OC2IP<2:0> — IC2IP<2:0> — DMA0IP<2:0> 4444 IPC2 0844 — U1RXIP<2:0> — SPI1IP<2:0> — SPI1EIP<2:0> — T3IP<2:0> 4444 IPC3 0846 — — — — — DMA1IP<2:0> — AD1IP<2:0> — U1TXIP<2:0> 0444 IPC4 0848 — CNIP<2:0> — CMIP<2:0> — MI2C1IP<2:0> — SI2C1IP<2:0> 4444 IPC5 084A — — — — — — — — — — — — — INT1IP<2:0> 0004 IPC6 084C — T4IP<2:0> — OC4IP<2:0> — OC3IP<2:0> — DMA2IP<2:0> 4444 IPC7 084E — U2TXIP<2:0> — U2RXIP<2:0> — INT2IP<2:0> — T5IP<2:0> 4444 IPC8 0850 — — — — — C1RXIP<2:0> — SPI2IP<2:0> — SPI2EIP<2:0> 0444 IPC9 0852 — — — — — IC4IP<2:0> — IC3IP<2:0> — DMA3IP<2:0> 0444 IPC12 0858 — — — — — MI2C2IP<2:0> — SI2C2IP<2:0> — — — — 0440 IPC14 085C — — — — — QEI1IP<2:0> — PSEMIP<2:0> — — — — 0440 IPC16 0860 — CRCIP<2:0> — U2EIP<2:0> — U1EIP<2:0> — — — — 4440 IPC19 0866 — — — — — — — — — CTMUIP<2:0> — — — — 0040 IPC23 086E — PWM2IP<2:0> — PWM1IP<2:0> — — — — — — — — 4400 IPC24 0870 — — — — — — — — — — — — — PWM3IP<2:0> 0004 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 72 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. IPC35 0886 — JTAGIP<2:0> — ICDIP<2:0> — — — — — — — — 4400 IPC36 0888 — PTG0IP<2:0> — PTGWDTIP<2:0> — PTGSTEPIP<2:0> — — — — 4440 IPC37 088A — — — — — PTG3IP<2:0> — PTG2IP<2:0> — PTG1IP<2:0> 0444 INTCON1 08C0 NSTDIS OVAERR OVBERR COVAERR COVBERR OVATE OVBTE COVTE SFTACERR DIV0ERR DMACERR MATHERR ADDRERR STKERR OSCFAIL — 0000 INTCON2 08C2 GIE DISI SWTRAP — — — — — — — — — — INT2EP INT1EP INT0EP 8000 INTCON3 08C4 — — — — — — — — — — DAE DOOVR — — — — 0000 INTCON4 08C6 — — — — — — — — — — — — — — — SGHT 0000 INTTREG 08C8 — — — — ILR<3:0> VECNUM<7:0> 0000 TABLE 4-6: INTERRUPT CONTROLLER REGISTER MAP FOR dsPIC33EPXXXMC20X DEVICES ONLY (CONTINUED) File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 73 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-7: INTERRUPT CONTROLLER REGISTER MAP FOR dsPIC33EPXXXMC50X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets IFS0 0800 — DMA1IF AD1IF U1TXIF U1RXIF SPI1IF SPI1EIF T3IF T2IF OC2IF IC2IF DMA0IF T1IF OC1IF IC1IF INT0IF 0000 IFS1 0802 U2TXIF U2RXIF INT2IF T5IF T4IF OC4IF OC3IF DMA2IF — — — INT1IF CNIF CMIF MI2C1IF SI2C1IF 0000 IFS2 0804 — — — — — — — — — IC4IF IC3IF DMA3IF C1IF C1RXIF SPI2IF SPI2EIF 0000 IFS3 0806 — — — — — QEI1IF PSEMIF — — — — — — MI2C2IF SI2C2IF — 0000 IFS4 0808 — — CTMUIF — — — — — — C1TXIF — — CRCIF U2EIF U1EIF — 0000 IFS5 080A PWM2IF PWM1IF — — — — — — — — — — — — — — 0000 IFS6 080C — — — — — — — — — — — — — — — PWM3IF 0000 IFS8 0810 JTAGIF ICDIF — — — — — — — — — — — — — — 0000 IFS9 0812 — — — — — — — — — PTG3IF PTG2IF PTG1IF PTG0IF PTGWDTIF PTGSTEPIF — 0000 IEC0 0820 — DMA1IE AD1IE U1TXIE U1RXIE SPI1IE SPI1EIE T3IE T2IE OC2IE IC2IE DMA0IE T1IE OC1IE IC1IE INT0IE 0000 IEC1 0822 U2TXIE U2RXIE INT2IE T5IE T4IE OC4IE OC3IE DMA2IE — — — INT1IE CNIE CMIE MI2C1IE SI2C1IE 0000 IEC2 0824 — — — — — — — — — IC4IE IC3IE DMA3IE C1IE C1RXIE SPI2IE SPI2EIE 0000 IEC3 0826 — — — — — QEI1IE PSEMIE — — — — — — MI2C2IE SI2C2IE — 0000 IEC4 0828 — — CTMUIE — — — — — — C1TXIE — — CRCIE U2EIE U1EIE — 0000 IEC5 082A PWM2IE PWM1IE — — — — — — — — — — — — — — 0000 IEC6 082C — — — — — — — — — — — — — — — PWM3IE 0000 IEC7 082E — — — — — — — — — — — — — — — — 0000 IEC8 0830 JTAGIE ICDIE — — — — — — — — — — — — — — 0000 IEC9 0832 — — — — — — — — — PTG3IE PTG2IE PTG1IE PTG0IE PTGWDTIE PTGSTEPIE — 0000 IPC0 0840 — T1IP<2:0> — OC1IP<2:0> — IC1IP<2:0> — INT0IP<2:0> 4444 IPC1 0842 — T2IP<2:0> — OC2IP<2:0> — IC2IP<2:0> — DMA0IP<2:0> 4444 IPC2 0844 — U1RXIP<2:0> — SPI1IP<2:0> — SPI1EIP<2:0> — T3IP<2:0> 4444 IPC3 0846 — — — — — DMA1IP<2:0> — AD1IP<2:0> — U1TXIP<2:0> 0444 IPC4 0848 — CNIP<2:0> — CMIP<2:0> — MI2C1IP<2:0> — SI2C1IP<2:0> 4444 IPC5 084A — — — — — — — — — — — — — INT1IP<2:0> 0004 IPC6 084C — T4IP<2:0> — OC4IP<2:0> — OC3IP<2:0> — DMA2IP<2:0> 4444 IPC7 084E — U2TXIP<2:0> — U2RXIP<2:0> — INT2IP<2:0> — T5IP<2:0> 4444 IPC8 0850 — C1IP<2:0> — C1RXIP<2:0> — SPI2IP<2:0> — SPI2EIP<2:0> 4444 IPC9 0852 — — — — — IC4IP<2:0> — IC3IP<2:0> — DMA3IP<2:0> 0444 IPC12 0858 — — — — — MI2C2IP<2:0> — SI2C2IP<2:0> — — — — 0440 IPC14 085C — — — — — QEI1IP<2:0> — PSEMIP<2:0> — — — — 0440 IPC16 0860 — CRCIP<2:0> — U2EIP<2:0> — U1EIP<2:0> — — — — 4440 IPC17 0862 — — — — — C1TXIP<2:0> — — — — — — — — 0400 IPC19 0866 — — — — — — — — — CTMUIP<2:0> — — — — 0040 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 74 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. IPC23 086E — PWM2IP<2:0> — PWM1IP<2:0> — — — — — — — — 4400 IPC24 0870 — — — — — — — — — — — — — PWM3IP<2:0> 0004 IPC35 0886 — JTAGIP<2:0> — ICDIP<2:0> — — — — — — — — 4400 IPC36 0888 — PTG0IP<2:0> — PTGWDTIP<2:0> — PTGSTEPIP<2:0> — — — — 4440 IPC37 088A — — — — — PTG3IP<2:0> — PTG2IP<2:0> — PTG1IP<2:0> 0444 INTCON1 08C0 NSTDIS OVAERR OVBERR COVAERR COVBERR OVATE OVBTE COVTE SFTACERR DIV0ERR DMACERR MATHERR ADDRERR STKERR OSCFAIL — 0000 INTCON2 08C2 GIE DISI SWTRAP — — — — — — — — — — INT2EP INT1EP INT0EP 8000 INTCON3 08C4 — — — — — — — — — — DAE DOOVR — — — — 0000 INTCON4 08C6 — — — — — — — — — — — — — — — SGHT 0000 INTTREG 08C8 — — — — ILR<3:0> VECNUM<7:0> 0000 TABLE 4-7: INTERRUPT CONTROLLER REGISTER MAP FOR dsPIC33EPXXXMC50X DEVICES ONLY (CONTINUED) File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 75 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-8: TIMER1 THROUGH TIMER5 REGISTER MAP SFR Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TMR1 0100 Timer1 Register xxxx PR1 0102 Period Register 1 FFFF T1CON 0104 TON — TSIDL — — — — — — TGATE TCKPS<1:0> — TSYNC TCS — 0000 TMR2 0106 Timer2 Register xxxx TMR3HLD 0108 Timer3 Holding Register (for 32-bit timer operations only) xxxx TMR3 010A Timer3 Register xxxx PR2 010C Period Register 2 FFFF PR3 010E Period Register 3 FFFF T2CON 0110 TON — TSIDL — — — — — — TGATE TCKPS<1:0> T32 — TCS — 0000 T3CON 0112 TON — TSIDL — — — — — — TGATE TCKPS<1:0> — — TCS — 0000 TMR4 0114 Timer4 Register xxxx TMR5HLD 0116 Timer5 Holding Register (for 32-bit operations only) xxxx TMR5 0118 Timer5 Register xxxx PR4 011A Period Register 4 FFFF PR5 011C Period Register 5 FFFF T4CON 011E TON — TSIDL — — — — — — TGATE TCKPS<1:0> T32 — TCS — 0000 T5CON 0120 TON — TSIDL — — — — — — TGATE TCKPS<1:0> — — TCS — 0000 Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 76 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-9: INPUT CAPTURE 1 THROUGH INPUT CAPTURE 4 REGISTER MAP File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets IC1CON1 0140 — — ICSIDL ICTSEL<2:0> — — — ICI<1:0> ICOV ICBNE ICM<2:0> 0000 IC1CON2 0142 — — — — — — — IC32 ICTRIG TRIGSTAT — SYNCSEL<4:0> 000D IC1BUF 0144 Input Capture 1 Buffer Register xxxx IC1TMR 0146 Input Capture 1 Timer 0000 IC2CON1 0148 — — ICSIDL ICTSEL<2:0> — — — ICI<1:0> ICOV ICBNE ICM<2:0> 0000 IC2CON2 014A — — — — — — — IC32 ICTRIG TRIGSTAT — SYNCSEL<4:0> 000D IC2BUF 014C Input Capture 2 Buffer Register xxxx IC2TMR 014E Input Capture 2 Timer 0000 IC3CON1 0150 — — ICSIDL ICTSEL<2:0> — — — ICI<1:0> ICOV ICBNE ICM<2:0> 0000 IC3CON2 0152 — — — — — — — IC32 ICTRIG TRIGSTAT — SYNCSEL<4:0> 000D IC3BUF 0154 Input Capture 3 Buffer Register xxxx IC3TMR 0156 Input Capture 3 Timer 0000 IC4CON1 0158 — — ICSIDL ICTSEL<2:0> — — — ICI<1:0> ICOV ICBNE ICM<2:0> 0000 IC4CON2 015A — — — — — — — IC32 ICTRIG TRIGSTAT — SYNCSEL<4:0> 000D IC4BUF 015C Input Capture 4 Buffer Register xxxx IC4TMR 015E Input Capture 4 Timer 0000 Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 77 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-10: OUTPUT COMPARE 1 THROUGH OUTPUT COMPARE 4 REGISTER MAP File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets OC1CON1 0900 — — OCSIDL OCTSEL<2:0> — ENFLTB ENFLTA — OCFLTB OCFLTA TRIGMODE OCM<2:0> 0000 OC1CON2 0902 FLTMD FLTOUT FLTTRIEN OCINV — — — OC32 OCTRIG TRIGSTAT OCTRIS SYNCSEL<4:0> 000C OC1RS 0904 Output Compare 1 Secondary Register xxxx OC1R 0906 Output Compare 1 Register xxxx OC1TMR 0908 Timer Value 1 Register xxxx OC2CON1 090A — — OCSIDL OCTSEL<2:0> — ENFLTB ENFLTA — OCFLTB OCFLTA TRIGMODE OCM<2:0> 0000 OC2CON2 090C FLTMD FLTOUT FLTTRIEN OCINV — — — OC32 OCTRIG TRIGSTAT OCTRIS SYNCSEL<4:0> 000C OC2RS 090E Output Compare 2 Secondary Register xxxx OC2R 0910 Output Compare 2 Register xxxx OC2TMR 0912 Timer Value 2 Register xxxx OC3CON1 0914 — — OCSIDL OCTSEL<2:0> — ENFLTB ENFLTA — OCFLTB OCFLTA TRIGMODE OCM<2:0> 0000 OC3CON2 0916 FLTMD FLTOUT FLTTRIEN OCINV — — — OC32 OCTRIG TRIGSTAT OCTRIS SYNCSEL<4:0> 000C OC3RS 0918 Output Compare 3 Secondary Register xxxx OC3R 091A Output Compare 3 Register xxxx OC3TMR 091C Timer Value 3 Register xxxx OC4CON1 091E — — OCSIDL OCTSEL<2:0> — ENFLTB ENFLTA — OCFLTB OCFLTA TRIGMODE OCM<2:0> 0000 OC4CON2 0920 FLTMD FLTOUT FLTTRIEN OCINV — — — OC32 OCTRIG TRIGSTAT OCTRIS SYNCSEL<4:0> 000C OC4RS 0922 Output Compare 4 Secondary Register xxxx OC4R 0924 Output Compare 4 Register xxxx OC4TMR 0926 Timer Value 4 Register xxxx Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 78 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-11: PTG REGISTER MAP File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets PTGCST 0AC0 PTGEN — PTGSIDL PTGTOGL — PTGSWT PTGSSEN PTGIVIS PTGSTRT PTGWTO — — — — PTGITM<1:0> 0000 PTGCON 0AC2 PTGCLK<2:0> PTGDIV<4:0> PTGPWD<3:0> — PTGWDT<2:0> 0000 PTGBTE 0AC4 ADCTS<4:1> IC4TSS IC3TSS IC2TSS IC1TSS OC4CS OC3CS OC2CS OC1CS OC4TSS OC3TSS OC2TSS OC1TSS 0000 PTGHOLD 0AC6 PTGHOLD<15:0> 0000 PTGT0LIM 0AC8 PTGT0LIM<15:0> 0000 PTGT1LIM 0ACA PTGT1LIM<15:0> 0000 PTGSDLIM 0ACC PTGSDLIM<15:0> 0000 PTGC0LIM 0ACE PTGC0LIM<15:0> 0000 PTGC1LIM 0AD0 PTGC1LIM<15:0> 0000 PTGADJ 0AD2 PTGADJ<15:0> 0000 PTGL0 0AD4 PTGL0<15:0> 0000 PTGQPTR 0AD6 — — — — — — — — — — — PTGQPTR<4:0> 0000 PTGQUE0 0AD8 STEP1<7:0> STEP0<7:0> 0000 PTGQUE1 0ADA STEP3<7:0> STEP2<7:0> 0000 PTGQUE2 0ADC STEP5<7:0> STEP4<7:0> 0000 PTGQUE3 0ADE STEP7<7:0> STEP6<7:0> 0000 PTGQUE4 0AE0 STEP9<7:0> STEP8<7:0> 0000 PTGQUE5 0AE2 STEP11<7:0> STEP10<7:0> 0000 PTGQUE6 0AE4 STEP13<7:0> STEP12<7:0> 0000 PTGQUE7 0AE6 STEP15<7:0> STEP14<7:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 79 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-12: PWM REGISTER MAP FOR dsPIC33EPXXXMC20X/50X AND PIC24EPXXXMC20X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets PTCON 0C00 PTEN — PTSIDL SESTAT SEIEN EIPU SYNCPOL SYNCOEN SYNCEN SYNCSRC<2:0> SEVTPS<3:0> 0000 PTCON2 0C02 — — — — — — — — — — — — — PCLKDIV<2:0> 0000 PTPER 0C04 PTPER<15:0> 00F8 SEVTCMP 0C06 SEVTCMP<15:0> 0000 MDC 0C0A MDC<15:0> 0000 CHOP 0C1A CHPCLKEN — — — — — CHOPCLK<9:0> 0000 PWMKEY 0C1E PWMKEY<15:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. TABLE 4-13: PWM GENERATOR 1 REGISTER MAP FOR dsPIC33EPXXXMC20X/50X AND PIC24EPXXXMC20X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets PWMCON1 0C20 FLTSTAT CLSTAT TRGSTAT FLTIEN CLIEN TRGIEN ITB MDCS DTC<1:0> DTCP — MTBS CAM XPRES IUE 0000 IOCON1 0C22 PENH PENL POLH POLL PMOD<1:0> OVRENH OVRENL OVRDAT<1:0> FLTDAT<1:0> CLDAT<1:0> SWAP OSYNC C000 FCLCON1 0C24 — CLSRC<4:0> CLPOL CLMOD FLTSRC<4:0> FLTPOL FLTMOD<1:0> 0000 PDC1 0C26 PDC1<15:0> FFF8 PHASE1 0C28 PHASE1<15:0> 0000 DTR1 0C2A — — DTR1<13:0> 0000 ALTDTR1 0C2C — — ALTDTR1<13:0> 0000 TRIG1 0C32 TRGCMP<15:0> 0000 TRGCON1 0C34 TRGDIV<3:0> — — — — — — TRGSTRT<5:0> 0000 LEBCON1 0C3A PHR PHF PLR PLF FLTLEBEN CLLEBEN — — — — BCH BCL BPHH BPHL BPLH BPLL 0000 LEBDLY1 0C3C — — — — LEB<11:0> 0000 AUXCON1 0C3E — — — — BLANKSEL<3:0> — — CHOPSEL<3:0> CHOPHEN CHOPLEN 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 80 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-14: PWM GENERATOR 2 REGISTER MAP FOR dsPIC33EPXXXMC20X/50X AND PIC24EPXXXMC20X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets PWMCON2 0C40 FLTSTAT CLSTAT TRGSTAT FLTIEN CLIEN TRGIEN ITB MDCS DTC<1:0> DTCP — MTBS CAM XPRES IUE 0000 IOCON2 0C42 PENH PENL POLH POLL PMOD<1:0> OVRENH OVRENL OVRDAT<1:0> FLTDAT<1:0> CLDAT<1:0> SWAP OSYNC C000 FCLCON2 0C44 — CLSRC<4:0> CLPOL CLMOD FLTSRC<4:0> FLTPOL FLTMOD<1:0> 00F8 PDC2 0C46 PDC2<15:0> 0000 PHASE2 0C48 PHASE2<15:0> 0000 DTR2 0C4A — — DTR2<13:0> 0000 ALTDTR2 0C4C — — ALTDTR2<13:0> 0000 TRIG2 0C52 TRGCMP<15:0> 0000 TRGCON2 0C54 TRGDIV<3:0> — — — — — — TRGSTRT<5:0> 0000 LEBCON2 0C5A PHR PHF PLR PLF FLTLEBEN CLLEBEN — — — — BCH BCL BPHH BPHL BPLH BPLL 0000 LEBDLY2 0C5C — — — — LEB<11:0> 0000 AUXCON2 0C5E — — — — BLANKSEL<3:0> — — CHOPSEL<3:0> CHOPHEN CHOPLEN 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. TABLE 4-15: PWM GENERATOR 3 REGISTER MAP FOR dsPIC33EPXXXMC20X/50X AND PIC24EPXXXMC20X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets PWMCON3 0C60 FLTSTAT CLSTAT TRGSTAT FLTIEN CLIEN TRGIEN ITB MDCS DTC<1:0> DTCP — MTBS CAM XPRES IUE 0000 IOCON3 0C62 PENH PENL POLH POLL PMOD<1:0> OVRENH OVRENL OVRDAT<1:0> FLTDAT<1:0> CLDAT<1:0> SWAP OSYNC C000 FCLCON3 0C64 — CLSRC<4:0> CLPOL CLMOD FLTSRC<4:0> FLTPOL FLTMOD<1:0> 00F8 PDC3 0C66 PDC3<15:0> 0000 PHASE3 0C68 PHASE3<15:0> 0000 DTR3 0C6A — — DTR3<13:0> 0000 ALTDTR3 0C6C — — ALTDTR3<13:0> 0000 TRIG3 0C72 TRGCMP<15:0> 0000 TRGCON3 0C74 TRGDIV<3:0> — — — — — — TRGSTRT<5:0> 0000 LEBCON3 0C7A PHR PHF PLR PLF FLTLEBEN CLLEBEN — — — — BCH BCL BPHH BPHL BPLH BPLL 0000 LEBDLY3 0C7C — — — — LEB<11:0> 0000 AUXCON3 0C7E — — — — BLANKSEL<3:0> — — CHOPSEL<3:0> CHOPHEN CHOPLEN 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 81 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-16: QEI1 REGISTER MAP FOR dsPIC33EPXXXMC20X/50X AND PIC24EPXXXMC20X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets QEI1CON 01C0 QEIEN — QEISIDL PIMOD<2:0> IMV<1:0> — INTDIV<2:0> CNTPOL GATEN CCM<1:0> 0000 QEI1IOC 01C2 QCAPEN FLTREN QFDIV<2:0> OUTFNC<1:0> SWPAB HOMPOL IDXPOL QEBPOL QEAPOL HOME INDEX QEB QEA 000x QEI1STAT 01C4 — — PCHEQIRQ PCHEQIEN PCLEQIRQ PCLEQIEN POSOVIRQ POSOVIEN PCIIRQ PCIIEN VELOVIRQ VELOVIEN HOMIRQ HOMIEN IDXIRQ IDXIEN 0000 POS1CNTL 01C6 POSCNT<15:0> 0000 POS1CNTH 01C8 POSCNT<31:16> 0000 POS1HLD 01CA POSHLD<15:0> 0000 VEL1CNT 01CC VELCNT<15:0> 0000 INT1TMRL 01CE INTTMR<15:0> 0000 INT1TMRH 01D0 INTTMR<31:16> 0000 INT1HLDL 01D2 INTHLD<15:0> 0000 INT1HLDH 01D4 INTHLD<31:16> 0000 INDX1CNTL 01D6 INDXCNT<15:0> 0000 INDX1CNTH 01D8 INDXCNT<31:16> 0000 INDX1HLD 01DA INDXHLD<15:0> 0000 QEI1GECL 01DC QEIGEC<15:0> 0000 QEI1ICL 01DC QEIIC<15:0> 0000 QEI1GECH 01DE QEIGEC<31:16> 0000 QEI1ICH 01DE QEIIC<31:16> 0000 QEI1LECL 01E0 QEILEC<15:0> 0000 QEI1LECH 01E2 QEILEC<31:16> 0000 Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 82 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-17: I2C1 AND I2C2 REGISTER MAP File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets I2C1RCV 0200 — — — — — — — — I2C1 Receive Register 0000 I2C1TRN 0202 — — — — — — — — I2C1 Transmit Register 00FF I2C1BRG 0204 — — — — — — — Baud Rate Generator 0000 I2C1CON 0206 I2CEN — I2CSIDL SCLREL IPMIEN A10M DISSLW SMEN GCEN STREN ACKDT ACKEN RCEN PEN RSEN SEN 1000 I2C1STAT 0208 ACKSTAT TRSTAT — — — BCL GCSTAT ADD10 IWCOL I2COV D_A P S R_W RBF TBF 0000 I2C1ADD 020A — — — — — — I2C1 Address Register 0000 I2C1MSK 020C — — — — — — I2C1 Address Mask 0000 I2C2RCV 0210 — — — — — — — — I2C2 Receive Register 0000 I2C2TRN 0212 — — — — — — — — I2C2 Transmit Register 00FF I2C2BRG 0214 — — — — — — — Baud Rate Generator 0000 I2C2CON 0216 I2CEN — I2CSIDL SCLREL IPMIEN A10M DISSLW SMEN GCEN STREN ACKDT ACKEN RCEN PEN RSEN SEN 1000 I2C2STAT 0218 ACKSTAT TRSTAT — — — BCL GCSTAT ADD10 IWCOL I2COV D_A P S R_W RBF TBF 0000 I2C2ADD 021A — — — — — — I2C2 Address Register 0000 I2C2MSK 021C — — — — — — I2C2 Address Mask 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. TABLE 4-18: UART1 AND UART2 REGISTER MAP SFR Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets U1MODE 0220 UARTEN — USIDL IREN RTSMD — UEN<1:0> WAKE LPBACK ABAUD URXINV BRGH PDSEL<1:0> STSEL 0000 U1STA 0222 UTXISEL1 UTXINV UTXISEL0 — UTXBRK UTXEN UTXBF TRMT URXISEL<1:0> ADDEN RIDLE PERR FERR OERR URXDA 0110 U1TXREG 0224 — — — — — — — UART1 Transmit Register xxxx U1RXREG 0226 — — — — — — — UART1 Receive Register 0000 U1BRG 0228 Baud Rate Generator Prescaler 0000 U2MODE 0230 UARTEN — USIDL IREN RTSMD — UEN<1:0> WAKE LPBACK ABAUD URXINV BRGH PDSEL<1:0> STSEL 0000 U2STA 0232 UTXISEL1 UTXINV UTXISEL0 — UTXBRK UTXEN UTXBF TRMT URXISEL<1:0> ADDEN RIDLE PERR FERR OERR URXDA 0110 U2TXREG 0234 — — — — — — — UART2 Transmit Register xxxx U2RXREG 0236 — — — — — — — UART2 Receive Register 0000 U2BRG 0238 Baud Rate Generator Prescaler 0000 Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 83 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-19: SPI1 AND SPI2 REGISTER MAP SFR Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets SPI1STAT 0240 SPIEN — SPISIDL — — SPIBEC<2:0> SRMPT SPIROV SRXMPT SISEL<2:0> SPITBF SPIRBF 0000 SPI1CON1 0242 — — — DISSCK DISSDO MODE16 SMP CKE SSEN CKP MSTEN SPRE<2:0> PPRE<1:0> 0000 SPI1CON2 0244 FRMEN SPIFSD FRMPOL — — — — — — — — — — — FRMDLY SPIBEN 0000 SPI1BUF 0248 SPI1 Transmit and Receive Buffer Register 0000 SPI2STAT 0260 SPIEN — SPISIDL — — SPIBEC<2:0> SRMPT SPIROV SRXMPT SISEL<2:0> SPITBF SPIRBF 0000 SPI2CON1 0262 — — — DISSCK DISSDO MODE16 SMP CKE SSEN CKP MSTEN SPRE<2:0> PPRE<1:0> 0000 SPI2CON2 0264 FRMEN SPIFSD FRMPOL — — — — — — — — — — — FRMDLY SPIBEN 0000 SPI2BUF 0268 SPI2 Transmit and Receive Buffer Register 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 84 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-20: ADC1 REGISTER MAP File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets ADC1BUF0 0300 ADC1 Data Buffer 0 xxxx ADC1BUF1 0302 ADC1 Data Buffer 1 xxxx ADC1BUF2 0304 ADC1 Data Buffer 2 xxxx ADC1BUF3 0306 ADC1 Data Buffer 3 xxxx ADC1BUF4 0308 ADC1 Data Buffer 4 xxxx ADC1BUF5 030A ADC1 Data Buffer 5 xxxx ADC1BUF6 030C ADC1 Data Buffer 6 xxxx ADC1BUF7 030E ADC1 Data Buffer 7 xxxx ADC1BUF8 0310 ADC1 Data Buffer 8 xxxx ADC1BUF9 0312 ADC1 Data Buffer 9 xxxx ADC1BUFA 0314 ADC1 Data Buffer 10 xxxx ADC1BUFB 0316 ADC1 Data Buffer 11 xxxx ADC1BUFC 0318 ADC1 Data Buffer 12 xxxx ADC1BUFD 031A ADC1 Data Buffer 13 xxxx ADC1BUFE 031C ADC1 Data Buffer 14 xxxx ADC1BUFF 031E ADC1 Data Buffer 15 xxxx AD1CON1 0320 ADON — ADSIDL ADDMABM — AD12B FORM<1:0> SSRC<2:0> SSRCG SIMSAM ASAM SAMP DONE 0000 AD1CON2 0322 VCFG<2:0> — — CSCNA CHPS<1:0> BUFS SMPI<4:0> BUFM ALTS 0000 AD1CON3 0324 ADRC — — SAMC<4:0> ADCS<7:0> 0000 AD1CHS123 0326 — — — — — CH123NB<1:0> CH123SB — — — — — CH123NA<1:0> CH123SA 0000 AD1CHS0 0328 CH0NB — — CH0SB<4:0> CH0NA — — CH0SA<4:0> 0000 AD1CSSH 032E CSS31 CSS30 — — — CSS26 CSS25 CSS24 — — — — — — — — 0000 AD1CSSL 0330 CSS15 CSS14 CSS13 CSS12 CSS11 CSS10 CSS9 CSS8 CSS7 CSS6 CSS5 CSS4 CSS3 CSS2 CSS1 CSS0 0000 AD1CON4 0332 — — — — — — — ADDMAEN — — — — — DMABL<2:0> 0000 Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 85 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-21: ECAN1 REGISTER MAP WHEN WIN (C1CTRL1<0>) = 0 OR 1 FOR dsPIC33EPXXXMC/GP50X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets C1CTRL1 0400 — — CSIDL ABAT CANCKS REQOP<2:0> OPMODE<2:0> — CANCAP — — WIN 0480 C1CTRL2 0402 — — — — — — — — — — — DNCNT<4:0> 0000 C1VEC 0404 — — — FILHIT<4:0> — ICODE<6:0> 0040 C1FCTRL 0406 DMABS<2:0> — — — — — — — — FSA<4:0> 0000 C1FIFO 0408 — — FBP<5:0> — — FNRB<5:0> 0000 C1INTF 040A — — TXBO TXBP RXBP TXWAR RXWAR EWARN IVRIF WAKIF ERRIF — FIFOIF RBOVIF RBIF TBIF 0000 C1INTE 040C — — — — — — — — IVRIE WAKIE ERRIE — FIFOIE RBOVIE RBIE TBIE 0000 C1EC 040E TERRCNT<7:0> RERRCNT<7:0> 0000 C1CFG1 0410 — — — — — — — — SJW<1:0> BRP<5:0> 0000 C1CFG2 0412 — WAKFIL — — — SEG2PH<2:0> SEG2PHTS SAM SEG1PH<2:0> PRSEG<2:0> 0000 C1FEN1 0414 FLTEN15 FLTEN14 FLTEN13 FLTEN12 FLTEN11 FLTEN10 FLTEN9 FLTEN8 FLTEN7 FLTEN6 FLTEN5 FLTEN4 FLTEN3 FLTEN2 FLTEN1 FLTEN0 FFFF C1FMSKSEL1 0418 F7MSK<1:0> F6MSK<1:0> F5MSK<1:0> F4MSK<1:0> F3MSK<1:0> F2MSK<1:0> F1MSK<1:0> F0MSK<1:0> 0000 C1FMSKSEL2 041A F15MSK<1:0> F14MSK<1:0> F13MSK<1:0> F12MSK<1:0> F11MSK<1:0> F10MSK<1:0> F9MSK<1:0> F8MSK<1:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. TABLE 4-22: ECAN1 REGISTER MAP WHEN WIN (C1CTRL1<0>) = 0 FOR dsPIC33EPXXXMC/GP50X DEVICES ONLY File Name Addr Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets 0400- 041E See definition when WIN = x C1RXFUL1 0420 RXFUL15 RXFUL14 RXFUL13 RXFUL12 RXFUL11 RXFUL10 RXFUL9 RXFUL8 RXFUL7 RXFUL6 RXFUL5 RXFUL4 RXFUL3 RXFUL2 RXFUL1 RXFUL0 0000 C1RXFUL2 0422 RXFUL31 RXFUL30 RXFUL29 RXFUL28 RXFUL27 RXFUL26 RXFUL25 RXFUL24 RXFUL23 RXFUL22 RXFUL21 RXFUL20 RXFUL19 RXFUL18 RXFUL17 RXFUL16 0000 C1RXOVF1 0428 RXOVF15 RXOVF14 RXOVF13 RXOVF12 RXOVF11 RXOVF10 RXOVF9 RXOVF8 RXOVF7 RXOVF6 RXOVF5 RXOVF4 RXOVF3 RXOVF2 RXOVF1 RXOVF0 0000 C1RXOVF2 042A RXOVF31 RXOVF30 RXOVF29 RXOVF28 RXOVF27 RXOVF26 RXOVF25 RXOVF24 RXOVF23 RXOVF22 RXOVF21 RXOVF20 RXOVF19 RXOVF18 RXOVF17 RXOVF16 0000 C1TR01CON 0430 TXEN1 TXABT1 TXLARB1 TXERR1 TXREQ1 RTREN1 TX1PRI<1:0> TXEN0 TXABAT0 TXLARB0 TXERR0 TXREQ0 RTREN0 TX0PRI<1:0> 0000 C1TR23CON 0432 TXEN3 TXABT3 TXLARB3 TXERR3 TXREQ3 RTREN3 TX3PRI<1:0> TXEN2 TXABAT2 TXLARB2 TXERR2 TXREQ2 RTREN2 TX2PRI<1:0> 0000 C1TR45CON 0434 TXEN5 TXABT5 TXLARB5 TXERR5 TXREQ5 RTREN5 TX5PRI<1:0> TXEN4 TXABAT4 TXLARB4 TXERR4 TXREQ4 RTREN4 TX4PRI<1:0> 0000 C1TR67CON 0436 TXEN7 TXABT7 TXLARB7 TXERR7 TXREQ7 RTREN7 TX7PRI<1:0> TXEN6 TXABAT6 TXLARB6 TXERR6 TXREQ6 RTREN6 TX6PRI<1:0> xxxx C1RXD 0440 ECAN1 Receive Data Word xxxx C1TXD 0442 ECAN1 Transmit Data Word xxxx Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 86 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-23: ECAN1 REGISTER MAP WHEN WIN (C1CTRL1<0>) = 1 FOR dsPIC33EPXXXMC/GP50X DEVICES ONLY File Name Addr Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets 0400- 041E See definition when WIN = x C1BUFPNT1 0420 F3BP<3:0> F2BP<3:0> F1BP<3:0> F0BP<3:0> 0000 C1BUFPNT2 0422 F7BP<3:0> F6BP<3:0> F5BP<3:0> F4BP<3:0> 0000 C1BUFPNT3 0424 F11BP<3:0> F10BP<3:0> F9BP<3:0> F8BP<3:0> 0000 C1BUFPNT4 0426 F15BP<3:0> F14BP<3:0> F13BP<3:0> F12BP<3:0> 0000 C1RXM0SID 0430 SID<10:3> SID<2:0> — MIDE — EID<17:16> xxxx C1RXM0EID 0432 EID<15:8> EID<7:0> xxxx C1RXM1SID 0434 SID<10:3> SID<2:0> — MIDE — EID<17:16> xxxx C1RXM1EID 0436 EID<15:8> EID<7:0> xxxx C1RXM2SID 0438 SID<10:3> SID<2:0> — MIDE — EID<17:16> xxxx C1RXM2EID 043A EID<15:8> EID<7:0> xxxx C1RXF0SID 0440 SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx C1RXF0EID 0442 EID<15:8> EID<7:0> xxxx C1RXF1SID 0444 SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx C1RXF1EID 0446 EID<15:8> EID<7:0> xxxx C1RXF2SID 0448 SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx C1RXF2EID 044A EID<15:8> EID<7:0> xxxx C1RXF3SID 044C SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx C1RXF3EID 044E EID<15:8> EID<7:0> xxxx C1RXF4SID 0450 SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx C1RXF4EID 0452 EID<15:8> EID<7:0> xxxx C1RXF5SID 0454 SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx C1RXF5EID 0456 EID<15:8> EID<7:0> xxxx C1RXF6SID 0458 SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx C1RXF6EID 045A EID<15:8> EID<7:0> xxxx C1RXF7SID 045C SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx C1RXF7EID 045E EID<15:8> EID<7:0> xxxx C1RXF8SID 0460 SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx C1RXF8EID 0462 EID<15:8> EID<7:0> xxxx C1RXF9SID 0464 SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx C1RXF9EID 0466 EID<15:8> EID<7:0> xxxx C1RXF10SID 0468 SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx C1RXF10EID 046A EID<15:8> EID<7:0> xxxx C1RXF11SID 046C SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 87 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X C1RXF11EID 046E EID<15:8> EID<7:0> xxxx C1RXF12SID 0470 SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx C1RXF12EID 0472 EID<15:8> EID<7:0> xxxx C1RXF13SID 0474 SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx C1RXF13EID 0476 EID<15:8> EID<7:0> xxxx C1RXF14SID 0478 SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx C1RXF14EID 047A EID<15:8> EID<7:0> xxxx C1RXF15SID 047C SID<10:3> SID<2:0> — EXIDE — EID<17:16> xxxx C1RXF15EID 047E EID<15:8> EID<7:0> xxxx TABLE 4-23: ECAN1 REGISTER MAP WHEN WIN (C1CTRL1<0>) = 1 FOR dsPIC33EPXXXMC/GP50X DEVICES ONLY (CONTINUED) File Name Addr Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 88 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-24: CRC REGISTER MAP TABLE 4-25: PERIPHERAL PIN SELECT OUTPUT REGISTER MAP FOR dsPIC33EPXXXGP/MC202/502 AND PIC24EPXXXGP/MC202 DEVICES ONLY TABLE 4-26: PERIPHERAL PIN SELECT OUTPUT REGISTER MAP FOR dsPIC33EPXXXGP/MC203/503 AND PIC24EPXXXGP/MC203 DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets CRCCON1 0640 CRCEN — CSIDL VWORD<4:0> CRCFUL CRCMPT CRCISEL CRCGO LENDIAN — — — 0000 CRCCON2 0642 — — — DWIDTH<4:0> — — — PLEN<4:0> 0000 CRCXORL 0644 X<15:1> — 0000 CRCXORH 0646 X<31:16> 0000 CRCDATL 0648 CRC Data Input Low Word 0000 CRCDATH 064A CRC Data Input High Word 0000 CRCWDATL 064C CRC Result Low Word 0000 CRCWDATH 064E CRC Result High Word 0000 Legend: — = unimplemented, read as ‘0’. Shaded bits are not used in the operation of the programmable CRC module. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets RPOR0 0680 — — RP35R<5:0> — — RP20R<5:0> 0000 RPOR1 0682 — — RP37R<5:0> — — RP36R<5:0> 0000 RPOR2 0684 — — RP39R<5:0> — — RP38R<5:0> 0000 RPOR3 0686 — — RP41R<5:0> — — RP40R<5:0> 0000 RPOR4 0688 — — RP43R<5:0> — — RP42R<5:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets RPOR0 0680 — — RP35R<5:0> — — RP20R<5:0> 0000 RPOR1 0682 — — RP37R<5:0> — — RP36R<5:0> 0000 RPOR2 0684 — — RP39R<5:0> — — RP38R<5:0> 0000 RPOR3 0686 — — RP41R<5:0> — — RP40R<5:0> 0000 RPOR4 0688 — — RP43R<5:0> — — RP42R<5:0> 0000 RPOR5 068A — — — — — — — — — — — — — — — — 0000 RPOR6 068C — — — — — — — — — — RP56R<5:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 89 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-27: PERIPHERAL PIN SELECT OUTPUT REGISTER MAP FOR dsPIC33EPXXXGP/MC204/504 AND PIC24EPXXXGP/MC204 DEVICES ONLY TABLE 4-28: PERIPHERAL PIN SELECT OUTPUT REGISTER MAP FOR dsPIC33EPXXXGP/MC206/506 AND PIC24EPXXXGP/MC206 DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets RPOR0 0680 — — RP35R<5:0> — — RP20R<5:0> 0000 RPOR1 0682 — — RP37R<5:0> — — RP36R<5:0> 0000 RPOR2 0684 — — RP39R<5:0> — — RP38R<5:0> 0000 RPOR3 0686 — — RP41R<5:0> — — RP40R<5:0> 0000 RPOR4 0688 — — RP43R<5:0> — — RP42R<5:0> 0000 RPOR5 068A — — RP55R<5:0> — — RP54R<5:0> 0000 RPOR6 068C — — RP57R<5:0> — — RP56R<5:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets RPOR0 0680 — — RP35R<5:0> — — RP20R<5:0> 0000 RPOR1 0682 — — RP37R<5:0> — — RP36R<5:0> 0000 RPOR2 0684 — — RP39R<5:0> — — RP38R<5:0> 0000 RPOR3 0686 — — RP41R<5:0> — — RP40R<5:0> 0000 RPOR4 0688 — — RP43R<5:0> — — RP42R<5:0> 0000 RPOR5 068A — — RP55R<5:0> — — RP54R<5:0> 0000 RPOR6 068C — — RP57R<5:0> — — RP56R<5:0> 0000 RPOR7 068E — — RP97R<5:0> — — — — — — — — 0000 RPOR8 0690 — — RP118R<5:0> — — — — — — — — 0000 RPOR9 0692 — — — — — — — — — — RP120R<5:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 90 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-29: PERIPHERAL PIN SELECT INPUT REGISTER MAP FOR PIC24EPXXXMC20X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets RPINR0 06A0 — INT1R<6:0> — — — — — — — — 0000 RPINR1 06A2 — — — — — — — — — INT2R<6:0> 0000 RPINR3 06A6 — — — — — — — — — T2CKR<6:0> 0000 RPINR7 06AE — IC2R<6:0> — IC1R<6:0> 0000 RPINR8 06B0 — IC4R<6:0> — IC3R<6:0> 0000 RPINR11 06B6 — — — — — — — — — OCFAR<6:0> 0000 RPINR12 06B8 — FLT2R<6:0> — FLT1R<6:0> 0000 RPINR14 06BC — QEB1R<6:0> — QEA1R<6:0> 0000 RPINR15 06BE — HOME1R<6:0> — INDX1R<6:0> 0000 RPINR18 06C4 — — — — — — — — — U1RXR<6:0> 0000 RPINR19 06C6 — — — — — — — — — U2RXR<6:0> 0000 RPINR22 06CC — SCK2INR<6:0> — SDI2R<6:0> 0000 RPINR23 06CE — — — — — — — — — SS2R<6:0> 0000 RPINR26 06D4 — — — — — — — — — — — — — — — — 0000 RPINR37 06EA — SYNCI1R<6:0> — — — — — — — — 0000 RPINR38 06EC — DTCMP1R<6:0> — — — — — — — — 0000 RPINR39 06EE — DTCMP3R<6:0> — DTCMP2R<6:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. TABLE 4-30: PERIPHERAL PIN SELECT INPUT REGISTER MAP FOR PIC24EPXXXGP20X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets RPINR0 06A0 — INT1R<6:0> — — — — — — — — 0000 RPINR1 06A2 — — — — — — — — — INT2R<6:0> 0000 RPINR3 06A6 — — — — — — — — — T2CKR<6:0> 0000 RPINR7 06AE — IC2R<6:0> — IC1R<6:0> 0000 RPINR8 06B0 — IC4R<6:0> — IC3R<6:0> 0000 RPINR11 06B6 — — — — — — — — — OCFAR<6:0> 0000 RPINR18 06C4 — — — — — — — — — U1RXR<6:0> 0000 RPINR19 06C6 — — — — — — — — — U2RXR<6:0> 0000 RPINR22 06CC — SCK2INR<6:0> — SDI2R<6:0> 0000 RPINR23 06CE — — — — — — — — — SS2R<6:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 91 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-31: PERIPHERAL PIN SELECT INPUT REGISTER MAP FOR dsPIC33EPXXXGP50X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets RPINR0 06A0 — INT1R<6:0> — — — — — — — — 0000 RPINR1 06A2 — — — — — — — — — INT2R<6:0> 0000 RPINR3 06A6 — — — — — — — — — T2CKR<6:0> 0000 RPINR7 06AE — IC2R<6:0> — IC1R<6:0> 0000 RPINR8 06B0 — IC4R<6:0> — IC3R<6:0> 0000 RPINR11 06B6 — — — — — — — — — OCFAR<6:0> 0000 RPINR18 06C4 — — — — — — — — — U1RXR<6:0> 0000 RPINR19 06C6 — — — — — — — — — U2RXR<6:0> 0000 RPINR22 06CC — SCK2INR<6:0> — SDI2R<6:0> 0000 RPINR23 06CE — — — — — — — — — SS2R<6:0> 0000 RPINR26 06D4 — — — — — — — — — C1RXR<6:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. TABLE 4-32: PERIPHERAL PIN SELECT INPUT REGISTER MAP FOR dsPIC33EPXXXMC50X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets RPINR0 06A0 — INT1R<6:0> — — — — — — — — 0000 RPINR1 06A2 — — — — — — — — — INT2R<6:0> 0000 RPINR3 06A6 — — — — — — — — — T2CKR<6:0> 0000 RPINR7 06AE — IC2R<6:0> — IC1R<6:0> 0000 RPINR8 06B0 — IC4R<6:0> — IC3R<6:0> 0000 RPINR11 06B6 — — — — — — — — — OCFAR<6:0> 0000 RPINR12 06B8 — FLT2R<6:0> — FLT1R<6:0> 0000 RPINR14 06BC — QEB1R<6:0> — QEA1R<6:0> 0000 RPINR15 06BE — HOME1R<6:0> — INDX1R<6:0> 0000 RPINR18 06C4 — — — — — — — — — U1RXR<6:0> 0000 RPINR19 06C6 — — — — — — — — — U2RXR<6:0> 0000 RPINR22 06CC — SCK2INR<6:0> — SDI2R<6:0> 0000 RPINR23 06CE — — — — — — — — — SS2R<6:0> 0000 RPINR26 06D4 — — — — — — — — — C1RXR<6:0> 0000 RPINR37 06EA — SYNCI1R<6:0> — — — — — — — — 0000 RPINR38 06EC — DTCMP1R<6:0> — — — — — — — — 0000 RPINR39 06EE — DTCMP3R<6:0> — DTCMP2R<6:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 92 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-33: PERIPHERAL PIN SELECT INPUT REGISTER MAP FOR dsPIC33EPXXXMC20X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets RPINR0 06A0 — INT1R<6:0> — — — — — — — — 0000 RPINR1 06A2 — — — — — — — — — INT2R<6:0> 0000 RPINR3 06A6 — — — — — — — — — T2CKR<6:0> 0000 RPINR7 06AE — IC2R<6:0> — IC1R<6:0> 0000 RPINR8 06B0 — IC4R<6:0> — IC3R<6:0> 0000 RPINR11 06B6 — — — — — — — — — OCFAR<6:0> 0000 RPINR12 06B8 — FLT2R<6:0> — FLT1R<6:0> 0000 RPINR14 06BC — QEB1R<6:0> — QEA1R<6:0> 0000 RPINR15 06BE — HOME1R<6:0> — INDX1R<6:0> 0000 RPINR18 06C4 — — — — — — — — — U1RXR<6:0> 0000 RPINR19 06C6 — — — — — — — — — U2RXR<6:0> 0000 RPINR22 06CC — SCK2INR<6:0> — SDI2R<6:0> 0000 RPINR23 06CE — — — — — — — — — SS2R<6:0> 0000 RPINR37 06EA — SYNCI1R<6:0> — — — — — — — — 0000 RPINR38 06EC — DTCMP1R<6:0> — — — — — — — — 0000 RPINR39 06EE — DTCMP3R<6:0> — DTCMP2R<6:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 93 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-34: NVM REGISTER MAP TABLE 4-35: SYSTEM CONTROL REGISTER MAP TABLE 4-36: REFERENCE CLOCK REGISTER MAP File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets NVMCON 0728 WR WREN WRERR NVMSIDL — — — — — — — — NVMOP<3:0> 0000 NVMADRL 072A NVMADR<15:0> 0000 NVMADRH 072C — — — — — — — — NVMADR<23:16> 0000 NVMKEY 072E — — — — — — — — NVMKEY<7:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets RCON 0740 TRAPR IOPUWR — — VREGSF — CM VREGS EXTR SWR SWDTEN WDTO SLEEP IDLE BOR POR Note 1 OSCCON 0742 — COSC<2:0> — NOSC<2:0> CLKLOCK IOLOCK LOCK — CF — — OSWEN Note 2 CLKDIV 0744 ROI DOZE<2:0> DOZEN FRCDIV<2:0> PLLPOST<1:0> — PLLPRE<4:0> 0030 PLLFBD 0746 — — — — — — — PLLDIV<8:0> 0030 OSCTUN 0748 — — — — — — — — — — TUN<5:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. Note 1: RCON register Reset values are dependent on the type of Reset. 2: OSCCON register Reset values are dependent on the Configuration Fuses. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets REFOCON 074E ROON — ROSSLP ROSEL RODIV<3:0> — — — — — — — — 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 94 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-37: PMD REGISTER MAP FOR PIC24EPXXXGP20X DEVICES ONLY TABLE 4-38: PMD REGISTER MAP FOR PIC24EPXXXMC20X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets PMD1 0760 T5MD T4MD T3MD T2MD T1MD — — — I2C1MD U2MD U1MD SPI2MD SPI1MD — — AD1MD 0000 PMD2 0762 — — — — IC4MD IC3MD IC2MD IC1MD — — — — OC4MD OC3MD OC2MD OC1MD 0000 PMD3 0764 — — — — — CMPMD — — CRCMD — — — — — I2C2MD — 0000 PMD4 0766 — — — — — — — — — — — — REFOMD CTMUMD — — 0000 PMD6 076A — — — — — — — — — — — — — — — — 0000 PMD7 076C — — — — — — — — — — — DMA0MD PTGMD — — — 0000 DMA1MD DMA2MD DMA3MD Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets PMD1 0760 T5MD T4MD T3MD T2MD T1MD QEI1MD PWMMD — I2C1MD U2MD U1MD SPI2MD SPI1MD — — AD1MD 0000 PMD2 0762 — — — — IC4MD IC3MD IC2MD IC1MD — — — — OC4MD OC3MD OC2MD OC1MD 0000 PMD3 0764 — — — — — CMPMD — — CRCMD — — — — — I2C2MD — 0000 PMD4 0766 — — — — — — — — — — — — REFOMD CTMUMD — — 0000 PMD6 076A — — — — — PWM3MD PWM2MD PWM1MD — — — — — — — — 0000 PMD7 076C — — — — — — — — — — — DMA0MD PTGMD — — — 0000 DMA1MD DMA2MD DMA3MD Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 95 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-39: PMD REGISTER MAP FOR dsPIC33EPXXXGP50X DEVICES ONLY TABLE 4-40: PMD REGISTER MAP FOR dsPIC33EPXXXMC50X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets PMD1 0760 T5MD T4MD T3MD T2MD T1MD — — — I2C1MD U2MD U1MD SPI2MD SPI1MD — C1MD AD1MD 0000 PMD2 0762 — — — — IC4MD IC3MD IC2MD IC1MD — — — — OC4MD OC3MD OC2MD OC1MD 0000 PMD3 0764 — — — — — CMPMD — — CRCMD — — — — — I2C2MD — 0000 PMD4 0766 — — — — — — — — — — — — REFOMD CTMUMD — — 0000 PMD6 076A — — — — — — — — — — — — — — — — 0000 PMD7 076C — — — — — — — — — — — DMA0MD PTGMD — — — 0000 DMA1MD DMA2MD DMA3MD Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets PMD1 0760 T5MD T4MD T3MD T2MD T1MD QEI1MD PWMMD — I2C1MD U2MD U1MD SPI2MD SPI1MD — C1MD AD1MD 0000 PMD2 0762 — — — — IC4MD IC3MD IC2MD IC1MD — — — — OC4MD OC3MD OC2MD OC1MD 0000 PMD3 0764 — — — — — CMPMD — — CRCMD — — — — — I2C2MD — 0000 PMD4 0766 — — — — — — — — — — — — REFOMD CTMUMD — — 0000 PMD6 076A — — — — — PWM3MD PWM2MD PWM1MD — — — — — — — — 0000 PMD7 076C — — — — — — — — — — — DMA0MD PTGMD — — — 0000 DMA1MD DMA2MD DMA3MD Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 96 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-41: PMD REGISTER MAP FOR dsPIC33EPXXXMC20X DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets PMD1 0760 T5MD T4MD T3MD T2MD T1MD QEI1MD PWMMD — I2C1MD U2MD U1MD SPI2MD SPI1MD — — AD1MD 0000 PMD2 0762 — — — — IC4MD IC3MD IC2MD IC1MD — — — — OC4MD OC3MD OC2MD OC1MD 0000 PMD3 0764 — — — — — CMPMD — — CRCMD — — — — — I2C2MD — 0000 PMD4 0766 — — — — — — — — — — — — REFOMD CTMUMD — — 0000 PMD6 076A — — — — — PWM3MD PWM2MD PWM1MD — — — — — — — — 0000 PMD7 076C — — — — — — — — — — — DMA0MD PTGMD — — — 0000 DMA1MD DMA2MD DMA3MD Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 97 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-42: OP AMP/COMPARATOR REGISTER MAP TABLE 4-44: JTAG INTERFACE REGISTER MAP File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets CMSTAT 0A80 PSIDL — — — C4EVT C3EVT C2EVT C1EVT — — — — C4OUT C3OUT C2OUT C1OUT 0000 CVRCON 0A82 — CVR2OE — — — VREFSEL — — CVREN CVR1OE CVRR CVRSS CVR<3:0> 0000 CM1CON 0A84 CON COE CPOL — — OPMODE CEVT COUT EVPOL<1:0> — CREF — — CCH<1:0> 0000 CM1MSKSRC 0A86 — — — — SELSRCC<3:0> SELSRCB<3:0> SELSRCA<3:0> 0000 CM1MSKCON 0A88 HLMS — OCEN OCNEN OBEN OBNEN OAEN OANEN NAGS PAGS ACEN ACNEN ABEN ABNEN AAEN AANEN 0000 CM1FLTR 0A8A — — — — — — — — — CFSEL<2:0> CFLTREN CFDIV<2:0> 0000 CM2CON 0A8C CON COE CPOL — — OPMODE CEVT COUT EVPOL<1:0> — CREF — — CCH<1:0> 0000 CM2MSKSRC 0A8E — — — — SELSRCC<3:0> SELSRCB<3:0> SELSRCA<3:0> 0000 CM2MSKCON 0A90 HLMS — OCEN OCNEN OBEN OBNEN OAEN OANEN NAGS PAGS ACEN ACNEN ABEN ABNEN AAEN AANEN 0000 CM2FLTR 0A92 — — — — — — — — — CFSEL<2:0> CFLTREN CFDIV<2:0> 0000 CM3CON(1) 0A94 CON COE CPOL — — OPMODE CEVT COUT EVPOL<1:0> — CREF — — CCH<1:0> 0000 CM3MSKSRC(1) 0A96 — — — — SELSRCC<3:0> SELSRCB<3:0> SELSRCA<3:0> 0000 CM3MSKCON(1) 0A98 HLMS — OCEN OCNEN OBEN OBNEN OAEN OANEN NAGS PAGS ACEN ACNEN ABEN ABNEN AAEN AANEN 0000 CM3FLTR(1) 0A9A — — — — — — — — — CFSEL<2:0> CFLTREN CFDIV<2:0> 0000 CM4CON 0A9C CON COE CPOL — — — CEVT COUT EVPOL<1:0> — CREF — — CCH<1:0> 0000 CM4MSKSRC 0A9E — — — — SELSRCC<3:0> SELSRCB<3:0> SELSRCA<3:0> 0000 CM4MSKCON 0AA0 HLMS — OCEN OCNEN OBEN OBNEN OAEN OANEN NAGS PAGS ACEN ACNEN ABEN ABNEN AAEN AANEN 0000 CM4FLTR 0AA2 — — — — — — — — — CFSEL<2:0> CFLTREN CFDIV<2:0> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. Note 1: These registers are unavailable on dsPIC33EPXXXGP502/MC502/MC202 and PIC24EP256GP/MC202 (28-pin) devices. TABLE 4-43: CTMU REGISTER MAP File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets CTMUCON1 033A CTMUEN — CTMUSIDL TGEN EDGEN EDGSEQEN IDISSEN CTTRIG — — — — — — — — 0000 CTMUCON2 033C EDG1MOD EDG1POL EDG1SEL<3:0> EDG2STAT EDG1STAT EDG2MOD EDG2POL EDG2SEL<3:0> — — 0000 CTMUICON 033E ITRIM<5:0> IRNG<1:0> — — — — — — — — 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. File Name Addr Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets JDATAH 0FF0 — — — — JDATAH<27:16> xxxx JDATAL 0FF2 JDATAL<15:0> 0000 Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 98 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-45: DMAC REGISTER MAP File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets DMA0CON 0B00 CHEN SIZE DIR HALF NULLW — — — — — AMODE<1:0> — — MODE<1:0> 0000 DMA0REQ 0B02 FORCE — — — — — — — IRQSEL<7:0> 00FF DMA0STAL 0B04 STA<15:0> 0000 DMA0STAH 0B06 — — — — — — — — STA<23:16> 0000 DMA0STBL 0B08 STB<15:0> 0000 DMA0STBH 0B0A — — — — — — — — STB<23:16> 0000 DMA0PAD 0B0C PAD<15:0> 0000 DMA0CNT 0B0E — — CNT<13:0> 0000 DMA1CON 0B10 CHEN SIZE DIR HALF NULLW — — — — — AMODE<1:0> — — MODE<1:0> 0000 DMA1REQ 0B12 FORCE — — — — — — — IRQSEL<7:0> 00FF DMA1STAL 0B14 STA<15:0> 0000 DMA1STAH 0B16 — — — — — — — — STA<23:16> 0000 DMA1STBL 0B18 STB<15:0> 0000 DMA1STBH 0B1A — — — — — — — — STB<23:16> 0000 DMA1PAD 0B1C PAD<15:0> 0000 DMA1CNT 0B1E — — CNT<13:0> 0000 DMA2CON 0B20 CHEN SIZE DIR HALF NULLW — — — — — AMODE<1:0> — — MODE<1:0> 0000 DMA2REQ 0B22 FORCE — — — — — — — IRQSEL<7:0> 00FF DMA2STAL 0B24 STA<15:0> 0000 DMA2STAH 0B26 — — — — — — — — STA<23:16> 0000 DMA2STBL 0B28 STB<15:0> 0000 DMA2STBH 0B2A — — — — — — — — STB<23:16> 0000 DMA2PAD 0B2C PAD<15:0> 0000 DMA2CNT 0B2E — — CNT<13:0> 0000 DMA3CON 0B30 CHEN SIZE DIR HALF NULLW — — — — — AMODE<1:0> — — MODE<1:0> 0000 DMA3REQ 0B32 FORCE — — — — — — — IRQSEL<7:0> 00FF DMA3STAL 0B34 STA<15:0> 0000 DMA3STAH 0B36 — — — — — — — — STA<23:16> 0000 DMA3STBL 0B38 STB<15:0> 0000 DMA3STBH 0B3A — — — — — — — — STB<23:16> 0000 DMA3PAD 0B3C PAD<15:0> 0000 DMA3CNT 0B3E — — CNT<13:0> 0000 DMAPWC 0BF0 — — — — — — — — — — — — PWCOL3 PWCOL2 PWCOL1 PWCOL0 0000 DMARQC 0BF2 — — — — — — — — — — — — RQCOL3 RQCOL2 RQCOL1 RQCOL0 0000 DMAPPS 0BF4 — — — — — — — — — — — — PPST3 PPST2 PPST1 PPST0 0000 DMALCA 0BF6 — — — — — — — — — — — — LSTCH<3:0> 000F DSADRL 0BF8 DSADR<15:0> 0000 DSADRH 0BFA — — — — — — — — DSADR<23:16> 0000 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 99 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-46: PORTA REGISTER MAP FOR PIC24EPXXXGP/MC206 AND dsPIC33EPXXXGP/MC206/506 DEVICES ONLY TABLE 4-47: PORTB REGISTER MAP FOR PIC24EPXXXGP/MC206 AND dsPIC33EPXXXGP/MC206/506 DEVICES ONLY TABLE 4-48: PORTC REGISTER MAP FOR PIC24EPXXXGP/MC206 AND dsPIC33EPXXXGP/MC206/506 DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TRISA 0E00 — — — TRISA12 TRISA11 TRISA10 TRISA9 TRISA8 TRISA7 — — TRISA4 — — TRISA1 TRISA0 1F93 PORTA 0E02 — — — RA12 RA11 RA10 RA9 RA8 RA7 — — RA4 — — RA1 RA0 0000 LATA 0E04 — — — LATA12 LATA11 LATA10 LATA9 LATA8 LATA7 — — LATA4 — — LA1TA1 LA0TA0 0000 ODCA 0E06 — — — ODCA12 ODCA11 ODCA10 ODCA9 ODCA8 ODCA7 — — ODCA4 — — ODCA1 ODCA0 0000 CNENA 0E08 — — — CNIEA12 CNIEA11 CNIEA10 CNIEA9 CNIEA8 CNIEA7 — — CNIEA4 — — CNIEA1 CNIEA0 0000 CNPUA 0E0A — — — CNPUA12 CNPUA11 CNPUA10 CNPUA9 CNPUA8 CNPUA7 — — CNPUA4 — — CNPUA1 CNPUA0 0000 CNPDA 0E0C — — — CNPDA12 CNPDA11 CNPDA10 CNPDA9 CNPDA8 CNPDA7 — — CNPDA4 — — CNPDA1 CNPDA0 0000 ANSELA 0E0E — — — ANSA12 ANSA11 — — — — — — ANSA4 — — ANSA1 ANSA0 1813 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TRISB 0E10 TRISB15 TRISB14 TRISB13 TRISB12 TRISB11 TRISB10 TRISB9 TRISB8 TRISB7 TRISB6 TRISB5 TRISB4 TRISB3 TRISB2 TRISB1 TRISB0 FFFF PORTB 0E12 RB15 RB14 RB13 RB12 RB11 RB10 RB9 RB8 RB7 RB6 RB5 RB4 RB3 RB2 RB1 RB0 xxxx LATB 0E14 LATB15 LATB14 LATB13 LATB12 LATB11 LATB10 LATB9 LATB8 LATB7 LATB6 LATB5 LATB4 LATB3 LATB2 LATB1 LATB0 xxxx ODCB 0E16 ODCB15 ODCB14 ODCB13 ODCB12 ODCB11 ODCB10 ODCB9 ODCB8 ODCB7 ODCB6 ODCB5 ODCB4 ODCB3 ODCB2 ODCB1 ODCB0 0000 CNENB 0E18 CNIEB15 CNIEB14 CNIEB13 CNIEB12 CNIEB11 CNIEB10 CNIEB9 CNIEB8 CNIEB7 CNIEB6 CNIEB5 CNIEB4 CNIEB3 CNIEB2 CNIEB1 CNIEB0 0000 CNPUB 0E1A CNPUB15 CNPUB14 CNPUB13 CNPUB12 CNPUB11 CNPUB10 CNPUB9 CNPUB8 CNPUB7 CNPUB6 CNPUB5 CNPUB4 CNPUB3 CNPUB2 CNPUB1 CNPUB0 0000 CNPDB 0E1C CNPDB15 CNPDB14 CNPDB13 CNPDB12 CNPDB11 CNPDB10 CNPDB9 CNPDB8 CNPDB7 CNPDB6 CNPDB5 CNPDB4 CNPDB3 CNPDB2 CNPDB1 CNPDB0 0000 ANSELB 0E1E — — — — — — — ANSB8 — — — — ANSB3 ANSB2 ANSB1 ANSB0 010F Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TRISC 0E20 TRISC15 — TRISC13 TRISC12 TRISC11 TRISC10 TRISC9 TRISC8 TRISC7 TRISC6 TRISC5 TRISC4 TRISC3 TRISC2 TRISC1 TRISC0 BFFF PORTC 0E22 RC15 — RC13 RC12 RC11 RC10 RC9 RC8 RC7 RC6 RC5 RC4 RC3 RC2 RC1 RC0 xxxx LATC 0E24 LATC15 — LATC13 LATC12 LATC11 LATC10 LATC9 LATC8 LATC7 LATC6 LATC5 LATC4 LATC3 LATC2 LATC1 LATC0 xxxx ODCC 0E26 ODCC15 — ODCC13 ODCC12 ODCC11 ODCC10 ODCC9 ODCC8 ODCC7 ODCC6 ODCC5 ODCC4 ODCC3 ODCC2 ODCC1 ODCC0 0000 CNENC 0E28 CNIEC15 — CNIEC13 CNIEC12 CNIEC11 CNIEC10 CNIEC9 CNIEC8 CNIEC7 CNIEC6 CNIEC5 CNIEC4 CNIEC3 CNIEC2 CNIEC1 CNIEC0 0000 CNPUC 0E2A CNPUC15 — CNPUC13 CNPUC12 CNPUC11 CNPUC10 CNPUC9 CNPUC8 CNPUC7 CNPUC6 CNPUC5 CNPUC4 CNPUC3 CNPUC2 CNPUC1 CNPUC0 0000 CNPDC 0E2C CNPDC15 — CNPDC13 CNPDC12 CNPDC11 CNPDC10 CNPDC9 CNPDC8 CNPDC7 CNPDC6 CNPDC5 CNPDC4 CNPDC3 CNPDC2 CNPDC1 CNPDC0 0000 ANSELC 0E2E — — — — ANSC11 — — — — — — — — ANSC2 ANSC1 ANSC0 0807 Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 100 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-49: PORTD REGISTER MAP FOR PIC24EPXXXGP/MC206 AND dsPIC33EPXXXGP/MC206/506 DEVICES ONLY TABLE 4-50: PORTE REGISTER MAP FOR PIC24EPXXXGP/MC206 AND dsPIC33EPXXXGP/MC206/506 DEVICES ONLY TABLE 4-51: PORTF REGISTER MAP FOR PIC24EPXXXGP/MC206 AND dsPIC33EPXXXGP/MC206/506 DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TRISD 0E30 — — — — — — — TRISD8 — TRISD6 TRISD5 — — — — — 0160 PORTD 0E32 — — — — — — — RD8 — RD6 RD5 — — — — — xxxx LATD 0E34 — — — — — — — LATD8 — LATD6 LATD5 — — — — — xxxx ODCD 0E36 — — — — — — — ODCD8 — ODCD6 ODCD5 — — — — — 0000 CNEND 0E38 — — — — — — — CNIED8 — CNIED6 CNIED5 — — — — — 0000 CNPUD 0E3A — — — — — — — CNPUD8 — CNPUD6 CNPUD5 — — — — — 0000 CNPDD 0E3C — — — — — — — CNPDD8 — CNPDD6 CNPDD5 — — — — — 0000 Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TRISE 0E40 TRISE15 TRISE14 TRISE13 TRISE12 — — — — — — — — — — — — F000 PORTE 0E42 RE15 RE14 RE13 RE12 — — — — — — — — — — — — xxxx LATE 0E44 LATE15 LATE14 LATE13 LATE12 — — — — — — — — — — — — xxxx ODCE 0E46 ODCE15 ODCE14 ODCE13 ODCE12 — — — — — — — — — — — — 0000 CNENE 0E48 CNIEE15 CNIEE14 CNIEE13 CNIEE12 — — — — — — — — — — — — 0000 CNPUE 0E4A CNPUE15 CNPUE14 CNPUE13 CNPUE12 — — — — — — — — — — — — 0000 CNPDE 0E4C CNPDE15 CNPDE14 CNPDE13 CNPDE12 — — — — — — — — — — — — 0000 ANSELE 0E4E ANSE15 ANSE14 ANSE13 ANSE12 — — — — — — — — — — — — F000 Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TRISF 0E50 — — — — — — — — — — — — — — TRISF1 TRISF0 0003 PORTF 0E52 — — — — — — — — — — — — — — RF1 RF0 xxxx LATF 0E54 — — — — — — — — — — — — — — LATF1 LATF0 xxxx ODCF 0E56 — — — — — — — — — — — — — — ODCF1 ODCF0 0000 CNENF 0E58 — — — — — — — — — — — — — — CNIEF1 CNIEF0 0000 CNPUF 0E5A — — — — — — — — — — — — — — CNPUF1 CNPUF0 0000 CNPDF 0E5C — — — — — — — — — — — — — — CNPDF1 CNPDF0 0000 Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 101 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-52: PORTG REGISTER MAP FOR PIC24EPXXXGP/MC206 AND dsPIC33EPXXXGP/MC206/506 DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TRISG 0E60 — — — — — — TRISG9 TRISG8 TRISG7 TRISG6 — — — — — — 03C0 PORTG 0E62 — — — — — — RG9 RG8 RG7 RG6 — — — — — — xxxx LATG 0E64 — — — — — — LATG9 LATG8 LATG7 LATG6 — — — — — — xxxx ODCG 0E66 — — — — — — ODCG9 ODCG8 ODCG7 ODCG6 — — — — — — 0000 CNENG 0E68 — — — — — — CNIEG9 CNIEG8 CNIEG7 CNIEG6 — — — — — — 0000 CNPUG 0E6A — — — — — — CNPUG9 CNPUG8 CNPUG7 CNPUG6 — — — — — — 0000 CNPDG 0E6C — — — — — — CNPDG9 CNPDG8 CNPDG7 CNPDG6 — — — — — — 0000 Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 102 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-53: PORTA REGISTER MAP FOR PIC24EPXXXGP/MC204 AND dsPIC33EPXXXGP/MC204/504 DEVICES ONLY TABLE 4-54: PORTB REGISTER MAP FOR PIC24EPXXXGP/MC204 AND dsPIC33EPXXXGP/MC204/504 DEVICES ONLY TABLE 4-55: PORTC REGISTER MAP FOR PIC24EPXXXGP/MC204 AND dsPIC33EPXXXGP/MC204/504 DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TRISA 0E00 — — — — — TRISA10 TRISA9 TRISA8 TRISA7 — — TRISA4 TRISA3 TRISA2 TRISA1 TRISA0 079F PORTA 0E02 — — — — — RA10 RA9 RA8 RA7 — — RA4 RA3 RA2 RA1 RA0 0000 LATA 0E04 — — — — — LATA10 LATA9 LATA8 LATA7 — — LATA4 LATA3 LATA2 LA1TA1 LA0TA0 0000 ODCA 0E06 — — — — — ODCA10 ODCA9 ODCA8 ODCA7 — — ODCA4 ODCA3 ODCA2 ODCA1 ODCA0 0000 CNENA 0E08 — — — — — CNIEA10 CNIEA9 CNIEA8 CNIEA7 — — CNIEA4 CNIEA3 CNIEA2 CNIEA1 CNIEA0 0000 CNPUA 0E0A — — — — — CNPUA10 CNPUA9 CNPUA8 CNPUA7 — — CNPUA4 CNPUA3 CNPUA2 CNPUA1 CNPUA0 0000 CNPDA 0E0C — — — — — CNPDA10 CNPDA9 CNPDA8 CNPDA7 — — CNPDA4 CNPDA3 CNPDA2 CNPDA1 CNPDA0 0000 ANSELA 0E0E — — — — — — — — — — — ANSA4 — — ANSA1 ANSA0 0013 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TRISB 0E10 TRISB15 TRISB14 TRISB13 TRISB12 TRISB11 TRISB10 TRISB9 TRISB8 TRISB7 TRISB6 TRISB5 TRISB4 TRISB3 TRISB2 TRISB1 TRISB0 FFFF PORTB 0E12 RB15 RB14 RB13 RB12 RB11 RB10 RB9 RB8 RB7 RB6 RB5 RB4 RB3 RB2 RB1 RB0 xxxx LATB 0E14 LATB15 LATB14 LATB13 LATB12 LATB11 LATB10 LATB9 LATB8 LATB7 LATB6 LATB5 LATB4 LATB3 LATB2 LATB1 LATB0 xxxx ODCB 0E16 ODCB15 ODCB14 ODCB13 ODCB12 ODCB11 ODCB10 ODCB9 ODCB8 ODCB7 ODCB6 ODCB5 ODCB4 ODCB3 ODCB2 ODCB1 ODCB0 0000 CNENB 0E18 CNIEB15 CNIEB14 CNIEB13 CNIEB12 CNIEB11 CNIEB10 CNIEB9 CNIEB8 CNIEB7 CNIEB6 CNIEB5 CNIEB4 CNIEB3 CNIEB2 CNIEB1 CNIEB0 0000 CNPUB 0E1A CNPUB15 CNPUB14 CNPUB13 CNPUB12 CNPUB11 CNPUB10 CNPUB9 CNPUB8 CNPUB7 CNPUB6 CNPUB5 CNPUB4 CNPUB3 CNPUB2 CNPUB1 CNPUB0 0000 CNPDB 0E1C CNPDB15 CNPDB14 CNPDB13 CNPDB12 CNPDB11 CNPDB10 CNPDB9 CNPDB8 CNPDB7 CNPDB6 CNPDB5 CNPDB4 CNPDB3 CNPDB2 CNPDB1 CNPDB0 0000 ANSELB 0E1E — — — — — — — ANSB8 — — — — ANSB3 ANSB2 ANSB1 ANSB0 010F Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TRISC 0E20 — — — — — — TRISC9 TRISC8 TRISC7 TRISC6 TRISC5 TRISC4 TRISC3 TRISC2 TRISC1 TRISC0 03FF PORTC 0E22 — — — — — — RC9 RC8 RC7 RC6 RC5 RC4 RC3 RC2 RC1 RC0 xxxx LATC 0E24 — — — — — — LATC9 LATC8 LATC7 LATC6 LATC5 LATC4 LATC3 LATC2 LATC1 LATC0 xxxx ODCC 0E26 — — — — — — ODCC9 ODCC8 ODCC7 ODCC6 ODCC5 ODCC4 ODCC3 ODCC2 ODCC1 ODCC0 0000 CNENC 0E28 — — — — — — CNIEC9 CNIEC8 CNIEC7 CNIEC6 CNIEC5 CNIEC4 CNIEC3 CNIEC2 CNIEC1 CNIEC0 0000 CNPUC 0E2A — — — — — — CNPUC9 CNPUC8 CNPUC7 CNPUC6 CNPUC5 CNPUC4 CNPUC3 CNPUC2 CNPUC1 CNPUC0 0000 CNPDC 0E2C — — — — — — CNPDC9 CNPDC8 CNPDC7 CNPDC6 CNPDC5 CNPDC4 CNPDC3 CNPDC2 CNPDC1 CNPDC0 0000 ANSELC 0E2E — — — — — — — — — — — — — ANSC2 ANSC1 ANSC0 0007 Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 103 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 4-56: PORTA REGISTER MAP FOR PIC24EPXXXGP/MC203 AND dsPIC33EPXXXGP/MC203/503 DEVICES ONLY TABLE 4-57: PORTB REGISTER MAP FOR PIC24EPXXXGP/MC203 AND dsPIC33EPXXXGP/MC203/503 DEVICES ONLY TABLE 4-58: PORTC REGISTER MAP FOR PIC24EPXXXGP/MC203 AND dsPIC33EPXXXGP/MC203/503 DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TRISA 0E00 — — — — — — — TRISA8 — — — TRISA4 TRISA3 TRISA2 TRISA1 TRISA0 011F PORTA 0E02 — — — — — — — RA8 — — — RA4 RA3 RA2 RA1 RA0 0000 LATA 0E04 — — — — — — — LATA8 — — — LATA4 LATA3 LATA2 LA1TA1 LA0TA0 0000 ODCA 0E06 — — — — — — — ODCA8 — — — ODCA4 ODCA3 ODCA2 ODCA1 ODCA0 0000 CNENA 0E08 — — — — — — — CNIEA8 — — — CNIEA4 CNIEA3 CNIEA2 CNIEA1 CNIEA0 0000 CNPUA 0E0A — — — — — — — CNPUA8 — — — CNPUA4 CNPUA3 CNPUA2 CNPUA1 CNPUA0 0000 CNPDA 0E0C — — — — — — — CNPDA8 — — — CNPDA4 CNPDA3 CNPDA2 CNPDA1 CNPDA0 0000 ANSELA 0E0E — — — — — — — — — — — ANSA4 — — ANSA1 ANSA0 0013 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TRISB 0E10 TRISB15 TRISB14 TRISB13 TRISB12 TRISB11 TRISB10 TRISB9 TRISB8 TRISB7 TRISB6 TRISB5 TRISB4 TRISB3 TRISB2 TRISB1 TRISB0 FFFF PORTB 0E12 RB15 RB14 RB13 RB12 RB11 RB10 RB9 RB8 RB7 RB6 RB5 RB4 RB3 RB2 RB1 RB0 xxxx LATB 0E14 LATB15 LATB14 LATB13 LATB12 LATB11 LATB10 LATB9 LATB8 LATB7 LATB6 LATB5 LATB4 LATB3 LATB2 LATB1 LATB0 xxxx ODCB 0E16 ODCB15 ODCB14 ODCB13 ODCB12 ODCB11 ODCB10 ODCB9 ODCB8 ODCB7 ODCB6 ODCB5 ODCB4 ODCB3 ODCB2 ODCB1 ODCB0 0000 CNENB 0E18 CNIEB15 CNIEB14 CNIEB13 CNIEB12 CNIEB11 CNIEB10 CNIEB9 CNIEB8 CNIEB7 CNIEB6 CNIEB5 CNIEB4 CNIEB3 CNIEB2 CNIEB1 CNIEB0 0000 CNPUB 0E1A CNPUB15 CNPUB14 CNPUB13 CNPUB12 CNPUB11 CNPUB10 CNPUB9 CNPUB8 CNPUB7 CNPUB6 CNPUB5 CNPUB4 CNPUB3 CNPUB2 CNPUB1 CNPUB0 0000 CNPDB 0E1C CNPDB15 CNPDB14 CNPDB13 CNPDB12 CNPDB11 CNPDB10 CNPDB9 CNPDB8 CNPDB7 CNPDB6 CNPDB5 CNPDB4 CNPDB3 CNPDB2 CNPDB1 CNPDB0 0000 ANSELB 0E1E — — — — — — — ANSB8 — — — — ANSB3 ANSB2 ANSB1 ANSB0 010F Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TRISC 0E20 — — — — — — — TRISC8 — — — — — — TRISC1 TRISC0 0103 PORTC 0E22 — — — — — — — RC8 — — — — — — RC1 RC0 xxxx LATC 0E24 — — — — — — — LATC8 — — — — — — LATC1 LATC0 xxxx ODCC 0E26 — — — — — — — ODCC8 — — — — — — ODCC1 ODCC0 0000 CNENC 0E28 — — — — — — — CNIEC8 — — — — — — CNIEC1 CNIEC0 0000 CNPUC 0E2A — — — — — — — CNPUC8 — — — — — — CNPUC1 CNPUC0 0000 CNPDC 0E2C — — — — — — — CNPDC8 — — — — — — CNPDC1 CNPDC0 0000 ANSELC 0E2E — — — — — — — — — — — — — — ANSC1 ANSC0 0003 Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. DS70000657H-page 104 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. TABLE 4-59: PORTA REGISTER MAP FOR PIC24EPXXXGP/MC202 AND dsPIC33EPXXXGP/MC202/502 DEVICES ONLY TABLE 4-60: PORTB REGISTER MAP FOR PIC24EPXXXGP/MC202 AND dsPIC33EPXXXGP/MC202/502 DEVICES ONLY File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TRISA 0E00 — — — — — — — — — — — TRISA4 TRISA3 TRISA2 TRISA1 TRISA0 001F PORTA 0E02 — — — — — — — — — — — RA4 RA3 RA2 RA1 RA0 0000 LATA 0E04 — — — — — — — — — — — LATA4 LATA3 LATA2 LA1TA1 LA0TA0 0000 ODCA 0E06 — — — — — — — — — — — ODCA4 ODCA3 ODCA2 ODCA1 ODCA0 0000 CNENA 0E08 — — — — — — — — — — — CNIEA4 CNIEA3 CNIEA2 CNIEA1 CNIEA0 0000 CNPUA 0E0A — — — — — — — — — — — CNPUA4 CNPUA3 CNPUA2 CNPUA1 CNPUA0 0000 CNPDA 0E0C — — — — — — — — — — — CNPDA4 CNPDA3 CNPDA2 CNPDA1 CNPDA0 0000 ANSELA 0E0E — — — — — — — — — — — ANSA4 — — ANSA1 ANSA0 0013 Legend: — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal. File Name Addr. Bit 15 Bit 14 Bit 13 Bit 12 Bit 11 Bit 10 Bit 9 Bit 8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 All Resets TRISB 0E10 TRISB15 TRISB14 TRISB13 TRISB12 TRISB11 TRISB10 TRISB9 TRISB8 TRISB7 TRISB6 TRISB5 TRISB4 TRISB3 TRISB2 TRISB1 TRISB0 FFFF PORTB 0E12 RB15 RB14 RB13 RB12 RB11 RB10 RB9 RB8 RB7 RB6 RB5 RB4 RB3 RB2 RB1 RB0 xxxx LATB 0E14 LATB15 LATB14 LATB13 LATB12 LATB11 LATB10 LATB9 LATB8 LATB7 LATB6 LATB5 LATB4 LATB3 LATB2 LATB1 LATB0 xxxx ODCB 0E16 ODCB15 ODCB14 ODCB13 ODCB12 ODCB11 ODCB10 ODCB9 ODCB8 ODCB7 ODCB6 ODCB5 ODCB4 ODCB3 ODCB2 ODCB1 ODCB0 0000 CNENB 0E18 CNIEB15 CNIEB14 CNIEB13 CNIEB12 CNIEB11 CNIEB10 CNIEB9 CNIEB8 CNIEB7 CNIEB6 CNIEB5 CNIEB4 CNIEB3 CNIEB2 CNIEB1 CNIEB0 0000 CNPUB 0E1A CNPUB15 CNPUB14 CNPUB13 CNPUB12 CNPUB11 CNPUB10 CNPUB9 CNPUB8 CNPUB7 CNPUB6 CNPUB5 CNPUB4 CNPUB3 CNPUB2 CNPUB1 CNPUB0 0000 CNPDB 0E1C CNPDB15 CNPDB14 CNPDB13 CNPDB12 CNPDB11 CNPDB10 CNPDB9 CNPDB8 CNPDB7 CNPDB6 CNPDB5 CNPDB4 CNPDB3 CNPDB2 CNPDB1 CNPDB0 0000 ANSELB 0E1E — — — — — — — ANSB8 — — — — ANSB3 ANSB2 ANSB1 ANSB0 010F Legend: x = unknown value on Reset, — = unimplemented, read as ‘0’. Reset values are shown in hexadecimal.  2011-2013 Microchip Technology Inc. DS70000657H-page 105 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 4.4.1 PAGED MEMORY SCHEME The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X architecture extends the available Data Space through a paging scheme, which allows the available Data Space to be accessed using MOV instructions in a linear fashion for pre-modified and post-modified Effective Addresses (EA). The upper half of the base Data Space address is used in conjunction with the Data Space Page registers, the 10-bit Read Page register (DSRPAG) or the 9-bit Write Page register (DSWPAG), to form an Extended Data Space (EDS) address or Program Space Visibility (PSV) address. The Data Space Page registers are located in the SFR space. Construction of the EDS address is shown in Example 4-1. When DSRPAG<9> = 0 and the base address bit, EA<15> = 1, the DSRPAG<8:0> bits are concatenated onto EA<14:0> to form the 24-bit EDS read address. Similarly, when base address bit, EA<15> = 1, DSWPAG<8:0> are concatenated onto EA<14:0> to form the 24-bit EDS write address. EXAMPLE 4-1: EXTENDED DATA SPACE (EDS) READ ADDRESS GENERATION 1 DSRPAG<8:0> 9 Bits EA 15 Bits Select 24-Bit EDS EA Byte Select EA (DSRPAG = Don’t care) No EDS Access 16-Bit DS EA Select Byte EA<15> = 0 DSRPAG 0 EA<15> Note: DS read access when DSRPAG = 0x000 will force an address error trap. = 1? DSRPAG<9> Y N Generate PSV Address 0 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 106  2011-2013 Microchip Technology Inc. EXAMPLE 4-2: EXTENDED DATA SPACE (EDS) WRITE ADDRESS GENERATION The paged memory scheme provides access to multiple 32-Kbyte windows in the EDS and PSV memory. The Data Space Page registers, DSxPAG, in combination with the upper half of the Data Space address, can provide up to 16 Mbytes of additional address space in the EDS and 8 Mbytes (DSRPAG only) of PSV address space. The paged data memory space is shown in Example 4-3. The Program Space (PS) can be accessed with a DSRPAG of 0x200 or greater. Only reads from PS are supported using the DSRPAG. Writes to PS are not supported, so DSWPAG is dedicated to DS, including EDS only. The Data Space and EDS can be read from, and written to, using DSRPAG and DSWPAG, respectively. 1 DSWPAG<8:0> 9 Bits EA 15 Bits 24-Bit EDS EA Byte Select EA (DSWPAG = don’t care) No EDS Access 16-Bit DS EA Select Byte EA<15> = 0 EA<15> Note: DS read access when DSRPAG = 0x000 will force an address error trap. Generate PSV Address 0  2011-2013 Microchip Technology Inc. DS70000657H-page 107 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X EXAMPLE 4-3: PAGED DATA MEMORY SPACE 0x0000 Program Memory 0x0000 0x7FFF 0x7FFF EDS Page 0x001 0x0000 SFR Registers 0x0FFF 0x1000 Up to 8-Kbyte 0x2FFF Local Data Space EDS (DSRPAG<9:0>/DSWPAG<8:0>) Reserved (Will produce an address error trap) 32-Kbyte EDS Window 0xFFFF 0x3000 Page 0 Program Space 0x00_0000 0x7F_FFFF (lsw – <15:0>) 0x0000 (DSRPAG = 0x001) (DSWPAG = 0x001) EDS Page 0x1FF (DSRPAG = 0x1FF) (DSWPAG = 0x1FF) EDS Page 0x200 (DSRPAG = 0x200) PSV Program Memory EDS Page 0x2FF (DSRPAG = 0x2FF) EDS Page 0x300 (DSRPAG = 0x300) EDS Page 0x3FF (DSRPAG = 0x3FF) 0x7FFF 0x0000 0x7FFF 0x0000 0x7FFF 0x0000 0x7FFF 0x0000 0x7FFF DS_Addr<14:0> DS_Addr<15:0> (lsw) PSV Program Memory (MSB) Table Address Space (TBLPAG<7:0>) Program Memory 0x00_0000 0x7F_FFFF (MSB – <23:16>) 0x0000 (TBLPAG = 0x00) 0xFFFF DS_Addr<15:0> lsw Using TBLRDL/TBLWTL MSB Using TBLRDH/TBLWTH 0x0000 (TBLPAG = 0x7F) 0xFFFF lsw Using TBLRDL/TBLWTL MSB Using TBLRDH/TBLWTH (Instruction & Data) No writes allowed No writes allowed No writes allowed No writes allowed RAM(1) 0x7FFF 0x8000 Note 1: For 64K Flash devices. RAM size and end location is dependent on device; see Section 4.2 “Data Address Space” for more information. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 108  2011-2013 Microchip Technology Inc. Allocating different Page registers for read and write access allows the architecture to support data movement between different pages in data memory. This is accomplished by setting the DSRPAG register value to the page from which you want to read, and configuring the DSWPAG register to the page to which it needs to be written. Data can also be moved from different PSV to EDS pages, by configuring the DSRPAG and DSWPAG registers to address PSV and EDS space, respectively. The data can be moved between pages by a single instruction. When an EDS or PSV page overflow or underflow occurs, EA<15> is cleared as a result of the register indirect EA calculation. An overflow or underflow of the EA in the EDS or PSV pages can occur at the page boundaries when: • The initial address prior to modification addresses an EDS or PSV page • The EA calculation uses Pre-Modified or Post-Modified Register Indirect Addressing; however, this does not include Register Offset Addressing In general, when an overflow is detected, the DSxPAG register is incremented and the EA<15> bit is set to keep the base address within the EDS or PSV window. When an underflow is detected, the DSxPAG register is decremented and the EA<15> bit is set to keep the base address within the EDS or PSV window. This creates a linear EDS and PSV address space, but only when using Register Indirect Addressing modes. Exceptions to the operation described above arise when entering and exiting the boundaries of Page 0, EDS and PSV spaces. Table 4-61 lists the effects of overflow and underflow scenarios at different boundaries. In the following cases, when overflow or underflow occurs, the EA<15> bit is set and the DSxPAG is not modified; therefore, the EA will wrap to the beginning of the current page: • Register Indirect with Register Offset Addressing • Modulo Addressing • Bit-Reversed Addressing TABLE 4-61: OVERFLOW AND UNDERFLOW SCENARIOS AT PAGE 0, EDS and PSV SPACE BOUNDARIES(2,3,4) O/U, R/W Operation Before After DSxPAG DS EA<15> Page Description DSxPAG DS EA<15> Page Description O, Read [++Wn] or [Wn++] DSRPAG = 0x1FF 1 EDS: Last page DSRPAG = 0x1FF 0 See Note 1 O, Read DSRPAG = 0x2FF 1 PSV: Last lsw page DSRPAG = 0x300 1 PSV: First MSB page O, Read DSRPAG = 0x3FF 1 PSV: Last MSB page DSRPAG = 0x3FF 0 See Note 1 O, Write DSWPAG = 0x1FF 1 EDS: Last page DSWPAG = 0x1FF 0 See Note 1 U, Read [--Wn] or [Wn--] DSRPAG = 0x001 1 PSV page DSRPAG = 0x001 0 See Note 1 U, Read DSRPAG = 0x200 1 PSV: First lsw page DSRPAG = 0x200 0 See Note 1 U, Read DSRPAG = 0x300 1 PSV: First MSB page DSRPAG = 0x2FF 1 PSV: Last lsw page Legend: O = Overflow, U = Underflow, R = Read, W = Write Note 1: The Register Indirect Addressing now addresses a location in the base Data Space (0x0000-0x8000). 2: An EDS access with DSxPAG = 0x000 will generate an address error trap. 3: Only reads from PS are supported using DSRPAG. An attempt to write to PS using DSWPAG will generate an address error trap. 4: Pseudo-Linear Addressing is not supported for large offsets.  2011-2013 Microchip Technology Inc. DS70000657H-page 109 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 4.4.2 EXTENDED X DATA SPACE The lower portion of the base address space range, between 0x0000 and 0x7FFF, is always accessible regardless of the contents of the Data Space Page registers. It is indirectly addressable through the register indirect instructions. It can be regarded as being located in the default EDS Page 0 (i.e., EDS address range of 0x000000 to 0x007FFF with the base address bit, EA<15> = 0, for this address range). However, Page 0 cannot be accessed through the upper 32 Kbytes, 0x8000 to 0xFFFF, of base Data Space, in combination with DSRPAG = 0x000 or DSWPAG = 0x000. Consequently, DSRPAG and DSWPAG are initialized to 0x001 at Reset. The remaining pages, including both EDS and PSV pages, are only accessible using the DSRPAG or DSWPAG registers in combination with the upper 32 Kbytes, 0x8000 to 0xFFFF, of the base address, where base address bit, EA<15> = 1. For example, when DSRPAG = 0x001 or DSWPAG = 0x001, accesses to the upper 32 Kbytes, 0x8000 to 0xFFFF, of the Data Space will map to the EDS address range of 0x008000 to 0x00FFFF. When DSRPAG = 0x002 or DSWPAG = 0x002, accesses to the upper 32 Kbytes of the Data Space will map to the EDS address range of 0x010000 to 0x017FFF and so on, as shown in the EDS memory map in Figure 4-17. For more information on the PSV page access using Data Space Page registers, refer to the “Program Space Visibility from Data Space” section in “Program Memory” (DS70613) of the “dsPIC33/ PIC24 Family Reference Manual”. FIGURE 4-17: EDS MEMORY MAP Note 1: DSxPAG should not be used to access Page 0. An EDS access with DSxPAG set to 0x000 will generate an address error trap. 2: Clearing the DSxPAG in software has no effect. 0x008000 0x010000 0x018000 PAGE 3 PAGE 2 PAGE 1FD 0xFE8000 0xFF0000 0xFF8000 PAGE 1FF PAGE 1FE SFR/DS 0x0000 0xFFFF EDS EA Address (24 bits) DS Conventional EA<15:0> 0x8000 (PAGE 0) (DSRPAG<8:0>, EA<14:0>) (DSWPAG<8:0>, EA<14:0>) PAGE 1 DSRPAG<9> = 0 DS Address dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 110  2011-2013 Microchip Technology Inc. 4.4.3 DATA MEMORY ARBITRATION AND BUS MASTER PRIORITY EDS accesses from bus masters in the system are arbitrated. The arbiter for data memory (including EDS) arbitrates between the CPU, the DMA and the ICD module. In the event of coincidental access to a bus by the bus masters, the arbiter determines which bus master access has the highest priority. The other bus masters are suspended and processed after the access of the bus by the bus master with the highest priority. By default, the CPU is Bus Master 0 (M0) with the highest priority and the ICD is Bus Master 4 (M4) with the lowest priority. The remaining bus master (DMA Controller) is allocated to M3 (M1 and M2 are reserved and cannot be used). The user application may raise or lower the priority of the DMA Controller to be above that of the CPU by setting the appropriate bits in the EDS Bus Master Priority Control (MSTRPR) register. All bus masters with raised priorities will maintain the same priority relationship relative to each other (i.e., M1 being highest and M3 being lowest, with M2 in between). Also, all the bus masters with priorities below that of the CPU maintain the same priority relationship relative to each other. The priority schemes for bus masters with different MSTRPR values are tabulated in Table 4-62. This bus master priority control allows the user application to manipulate the real-time response of the system, either statically during initialization or dynamically in response to real-time events. TABLE 4-62: DATA MEMORY BUS ARBITER PRIORITY FIGURE 4-18: ARBITER ARCHITECTURE Priority MSTRPR<15:0> Bit Setting(1) 0x0000 0x0020 M0 (highest) CPU DMA M1 Reserved CPU M2 Reserved Reserved M3 DMA Reserved M4 (lowest) ICD ICD Note 1: All other values of MSTRPR<15:0> are reserved. Reserved ICD Data Memory Arbiter M0 M1 M2 M3 M4 MSTRPR<15:0> DMA CPU SRAM  2011-2013 Microchip Technology Inc. DS70000657H-page 111 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 4.4.4 SOFTWARE STACK The W15 register serves as a dedicated Software Stack Pointer (SSP) and is automatically modified by exception processing, subroutine calls and returns; however, W15 can be referenced by any instruction in the same manner as all other W registers. This simplifies reading, writing and manipulating of the Stack Pointer (for example, creating stack frames). W15 is initialized to 0x1000 during all Resets. This address ensures that the SSP points to valid RAM in all dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X devices, and permits stack availability for non-maskable trap exceptions. These can occur before the SSP is initialized by the user software. You can reprogram the SSP during initialization to any location within Data Space. The Software Stack Pointer always points to the first available free word and fills the software stack working from lower toward higher addresses. Figure 4-19 illustrates how it pre-decrements for a stack pop (read) and post-increments for a stack push (writes). When the PC is pushed onto the stack, PC<15:0> are pushed onto the first available stack word, then PC<22:16> are pushed into the second available stack location. For a PC push during any CALL instruction, the MSB of the PC is zero-extended before the push, as shown in Figure 4-19. During exception processing, the MSB of the PC is concatenated with the lower 8 bits of the CPU STATUS Register, SR. This allows the contents of SRL to be preserved automatically during interrupt processing. FIGURE 4-19: CALL STACK FRAME Note: To protect against misaligned stack accesses, W15<0> is fixed to ‘0’ by the hardware. Note 1: To maintain system Stack Pointer (W15) coherency, W15 is never subject to (EDS) paging, and is therefore restricted to an address range of 0x0000 to 0xFFFF. The same applies to the W14 when used as a Stack Frame Pointer (SFA = 1). 2: As the stack can be placed in, and can access X and Y spaces, care must be taken regarding its use, particularly with regard to local automatic variables in a C development environment PC<15:0> b‘000000000’ 15 0 W15 (before CALL) W15 (after CALL) Stack Grows Toward Higher Address 0x0000 PC<22:16> CALL SUBR dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 112  2011-2013 Microchip Technology Inc. 4.5 Instruction Addressing Modes The addressing modes shown in Table 4-63 form the basis of the addressing modes optimized to support the specific features of individual instructions. The addressing modes provided in the MAC class of instructions differ from those in the other instruction types. 4.5.1 FILE REGISTER INSTRUCTIONS Most file register instructions use a 13-bit address field (f) to directly address data present in the first 8192 bytes of data memory (Near Data Space). Most file register instructions employ a working register, W0, which is denoted as WREG in these instructions. The destination is typically either the same file register or WREG (with the exception of the MUL instruction), which writes the result to a register or register pair. The MOV instruction allows additional flexibility and can access the entire Data Space. 4.5.2 MCU INSTRUCTIONS The three-operand MCU instructions are of the form: Operand 3 = Operand 1 Operand 2 where Operand 1 is always a working register (that is, the addressing mode can only be Register Direct), which is referred to as Wb. Operand 2 can be a W register fetched from data memory or a 5-bit literal. The result location can either be a W register or a data memory location. The following addressing modes are supported by MCU instructions: • Register Direct • Register Indirect • Register Indirect Post-Modified • Register Indirect Pre-Modified • 5-Bit or 10-Bit Literal TABLE 4-63: FUNDAMENTAL ADDRESSING MODES SUPPORTED Note: Not all instructions support all the addressing modes given above. Individual instructions can support different subsets of these addressing modes. Addressing Mode Description File Register Direct The address of the file register is specified explicitly. Register Direct The contents of a register are accessed directly. Register Indirect The contents of Wn form the Effective Address (EA). Register Indirect Post-Modified The contents of Wn form the EA. Wn is post-modified (incremented or decremented) by a constant value. Register Indirect Pre-Modified Wn is pre-modified (incremented or decremented) by a signed constant value to form the EA. Register Indirect with Register Offset (Register Indexed) The sum of Wn and Wb forms the EA. Register Indirect with Literal Offset The sum of Wn and a literal forms the EA.  2011-2013 Microchip Technology Inc. DS70000657H-page 113 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 4.5.3 MOVE AND ACCUMULATOR INSTRUCTIONS Move instructions, which apply to dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X devices, and the DSP accumulator class of instructions, which apply to the dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X devices, provide a greater degree of addressing flexibility than other instructions. In addition to the addressing modes supported by most MCU instructions, move and accumulator instructions also support Register Indirect with Register Offset Addressing mode, also referred to as Register Indexed mode. In summary, the following addressing modes are supported by move and accumulator instructions: • Register Direct • Register Indirect • Register Indirect Post-modified • Register Indirect Pre-modified • Register Indirect with Register Offset (Indexed) • Register Indirect with Literal Offset • 8-Bit Literal • 16-Bit Literal 4.5.4 MAC INSTRUCTIONS (dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X DEVICES ONLY) The dual source operand DSP instructions (CLR, ED, EDAC, MAC, MPY, MPY.N, MOVSAC and MSC), also referred to as MAC instructions, use a simplified set of addressing modes to allow the user application to effectively manipulate the Data Pointers through register indirect tables. The Two-Source Operand Prefetch registers must be members of the set: {W8, W9, W10, W11}. For data reads, W8 and W9 are always directed to the X RAGU, and W10 and W11 are always directed to the Y AGU. The Effective Addresses generated (before and after modification) must therefore, be valid addresses within X Data Space for W8 and W9, and Y Data Space for W10 and W11. In summary, the following addressing modes are supported by the MAC class of instructions: • Register Indirect • Register Indirect Post-Modified by 2 • Register Indirect Post-Modified by 4 • Register Indirect Post-Modified by 6 • Register Indirect with Register Offset (Indexed) 4.5.5 OTHER INSTRUCTIONS Besides the addressing modes outlined previously, some instructions use literal constants of various sizes. For example, BRA (branch) instructions use 16-bit signed literals to specify the branch destination directly, whereas the DISI instruction uses a 14-bit unsigned literal field. In some instructions, such as ULNK, the source of an operand or result is implied by the opcode itself. Certain operations, such as a NOP, do not have any operands. Note: For the MOV instructions, the addressing mode specified in the instruction can differ for the source and destination EA. However, the 4-bit Wb (Register Offset) field is shared by both source and destination (but typically only used by one). Note: Not all instructions support all the addressing modes given above. Individual instructions may support different subsets of these addressing modes. Note: Register Indirect with Register Offset Addressing mode is available only for W9 (in X space) and W11 (in Y space). dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 114  2011-2013 Microchip Technology Inc. 4.6 Modulo Addressing (dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X Devices Only) Modulo Addressing mode is a method of providing an automated means to support circular data buffers using hardware. The objective is to remove the need for software to perform data address boundary checks when executing tightly looped code, as is typical in many DSP algorithms. Modulo Addressing can operate in either Data or Program Space (since the Data Pointer mechanism is essentially the same for both). One circular buffer can be supported in each of the X (which also provides the pointers into Program Space) and Y Data Spaces. Modulo Addressing can operate on any W Register Pointer. However, it is not advisable to use W14 or W15 for Modulo Addressing since these two registers are used as the Stack Frame Pointer and Stack Pointer, respectively. In general, any particular circular buffer can be configured to operate in only one direction, as there are certain restrictions on the buffer start address (for incrementing buffers) or end address (for decrementing buffers), based upon the direction of the buffer. The only exception to the usage restrictions is for buffers that have a power-of-two length. As these buffers satisfy the start and end address criteria, they can operate in a bidirectional mode (that is, address boundary checks are performed on both the lower and upper address boundaries). 4.6.1 START AND END ADDRESS The Modulo Addressing scheme requires that a starting and ending address be specified, and loaded into the 16-bit Modulo Buffer Address registers: XMODSRT, XMODEND, YMODSRT and YMODEND (see Table 4-1). The length of a circular buffer is not directly specified. It is determined by the difference between the corresponding start and end addresses. The maximum possible length of the circular buffer is 32K words (64 Kbytes). 4.6.2 W ADDRESS REGISTER SELECTION The Modulo and Bit-Reversed Addressing Control register, MODCON<15:0>, contains enable flags as well as a W register field to specify the W Address registers. The XWM and YWM fields select the registers that operate with Modulo Addressing: • If XWM = 1111, X RAGU and X WAGU Modulo Addressing is disabled • If YWM = 1111, Y AGU Modulo Addressing is disabled The X Address Space Pointer W register (XWM), to which Modulo Addressing is to be applied, is stored in MODCON<3:0> (see Table 4-1). Modulo Addressing is enabled for X Data Space when XWM is set to any value other than ‘1111’ and the XMODEN bit is set (MODCON<15>). The Y Address Space Pointer W register (YWM), to which Modulo Addressing is to be applied, is stored in MODCON<7:4>. Modulo Addressing is enabled for Y Data Space when YWM is set to any value other than ‘1111’ and the YMODEN bit is set at MODCON<14>. FIGURE 4-20: MODULO ADDRESSING OPERATION EXAMPLE Note: Y space Modulo Addressing EA calculations assume word-sized data (LSb of every EA is always clear). 0x1100 0x1163 Start Addr = 0x1100 End Addr = 0x1163 Length = 50 words Byte Address MOV #0x1100, W0 MOV W0, XMODSRT ;set modulo start address MOV #0x1163, W0 MOV W0, MODEND ;set modulo end address MOV #0x8001, W0 MOV W0, MODCON ;enable W1, X AGU for modulo MOV #0x0000, W0 ;W0 holds buffer fill value MOV #0x1110, W1 ;point W1 to buffer DO AGAIN, #0x31 ;fill the 50 buffer locations MOV W0, [W1++] ;fill the next location AGAIN: INC W0, W0 ;increment the fill value  2011-2013 Microchip Technology Inc. DS70000657H-page 115 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 4.6.3 MODULO ADDRESSING APPLICABILITY Modulo Addressing can be applied to the Effective Address (EA) calculation associated with any W register. Address boundaries check for addresses equal to: • The upper boundary addresses for incrementing buffers • The lower boundary addresses for decrementing buffers It is important to realize that the address boundaries check for addresses less than, or greater than, the upper (for incrementing buffers) and lower (for decrementing buffers) boundary addresses (not just equal to). Address changes can, therefore, jump beyond boundaries and still be adjusted correctly. 4.7 Bit-Reversed Addressing (dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X Devices Only) Bit-Reversed Addressing mode is intended to simplify data reordering for radix-2 FFT algorithms. It is supported by the X AGU for data writes only. The modifier, which can be a constant value or register contents, is regarded as having its bit order reversed. The address source and destination are kept in normal order. Thus, the only operand requiring reversal is the modifier. 4.7.1 BIT-REVERSED ADDRESSING IMPLEMENTATION Bit-Reversed Addressing mode is enabled when all these conditions are met: • BWMx bits (W register selection) in the MODCON register are any value other than ‘1111’ (the stack cannot be accessed using Bit-Reversed Addressing) • The BREN bit is set in the XBREV register • The addressing mode used is Register Indirect with Pre-Increment or Post-Increment If the length of a bit-reversed buffer is M = 2N bytes, the last ‘N’ bits of the data buffer start address must be zeros. XBREV<14:0> is the Bit-Reversed Addressing modifier, or ‘pivot point’, which is typically a constant. In the case of an FFT computation, its value is equal to half of the FFT data buffer size. When enabled, Bit-Reversed Addressing is executed only for Register Indirect with Pre-Increment or PostIncrement Addressing and word-sized data writes. It does not function for any other addressing mode or for byte-sized data and normal addresses are generated instead. When Bit-Reversed Addressing is active, the W Address Pointer is always added to the address modifier (XBREVx) and the offset associated with the Register Indirect Addressing mode is ignored. In addition, as word-sized data is a requirement, the LSb of the EA is ignored (and always clear). If Bit-Reversed Addressing has already been enabled by setting the BREN (XBREV<15>) bit, a write to the XBREV register should not be immediately followed by an indirect read operation using the W register that has been designated as the Bit-Reversed Pointer. Note: The modulo corrected Effective Address is written back to the register only when Pre-Modify or Post-Modify Addressing mode is used to compute the Effective Address. When an address offset (such as [W7 + W2]) is used, Modulo Addressing correction is performed but the contents of the register remain unchanged. Note: All bit-reversed EA calculations assume word-sized data (LSb of every EA is always clear). The XBREVx value is scaled accordingly to generate compatible (byte) addresses. Note: Modulo Addressing and Bit-Reversed Addressing can be enabled simultaneously using the same W register, but BitReversed Addressing operation will always take precedence for data writes when enabled. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 116  2011-2013 Microchip Technology Inc. FIGURE 4-21: BIT-REVERSED ADDRESSING EXAMPLE TABLE 4-64: BIT-REVERSED ADDRESSING SEQUENCE (16-ENTRY) Normal Address Bit-Reversed Address A3 A2 A1 A0 Decimal A3 A2 A1 A0 Decimal 0000 0 0000 0 0001 1 1000 8 0010 2 0100 4 0011 3 1100 12 0100 4 0010 2 0101 5 1010 10 0110 6 0110 6 0111 7 1110 14 1000 8 0001 1 1001 9 1001 9 1010 10 0101 5 1011 11 1101 13 1100 12 0011 3 1101 13 1011 11 1110 14 0111 7 1111 15 1111 15 b3 b2 b1 0 b2 b3 b4 0 Bit Locations Swapped Left-to-Right Around Center of Binary Value Bit-Reversed Address XBREV<14:0> = 0x0008 for a 16-Word Bit-Reversed Buffer b7 b6 b5 b1 b11 b10 b9 b8 b7 b6 b5 b4 b11 b10 b9 b8 b15 b14 b13 b12 b15 b14 b13 b12 Sequential Address Pivot Point  2011-2013 Microchip Technology Inc. DS70000657H-page 117 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 4.8 Interfacing Program and Data Memory Spaces The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X architecture uses a 24-bit-wide Program Space (PS) and a 16-bit-wide Data Space (DS). The architecture is also a modified Harvard scheme, meaning that data can also be present in the Program Space. To use this data successfully, it must be accessed in a way that preserves the alignment of information in both spaces. Aside from normal execution, the architecture of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X devices provides two methods by which Program Space can be accessed during operation: • Using table instructions to access individual bytes or words anywhere in the Program Space • Remapping a portion of the Program Space into the Data Space (Program Space Visibility) Table instructions allow an application to read or write to small areas of the program memory. This capability makes the method ideal for accessing data tables that need to be updated periodically. It also allows access to all bytes of the program word. The remapping method allows an application to access a large block of data on a read-only basis, which is ideal for look-ups from a large table of static data. The application can only access the least significant word of the program word. TABLE 4-65: PROGRAM SPACE ADDRESS CONSTRUCTION FIGURE 4-22: DATA ACCESS FROM PROGRAM SPACE ADDRESS GENERATION Access Type Access Space Program Space Address <23> <22:16> <15> <14:1> <0> Instruction Access (Code Execution) User 0 PC<22:1> 0 0xx xxxx xxxx xxxx xxxx xxx0 TBLRD/TBLWT (Byte/Word Read/Write) User TBLPAG<7:0> Data EA<15:0> 0xxx xxxx xxxx xxxx xxxx xxxx Configuration TBLPAG<7:0> Data EA<15:0> 1xxx xxxx xxxx xxxx xxxx xxxx Program Counter 0 23 Bits Program Counter(1) TBLPAG 8 Bits EA 16 Bits Byte Select 0 1/0 User/Configuration Table Operations(2) Space Select 24 Bits 1/0 Note 1: The Least Significant bit (LSb) of Program Space addresses is always fixed as ‘0’ to maintain word alignment of data in the Program and Data Spaces. 2: Table operations are not required to be word-aligned. Table Read operations are permitted in the configuration memory space. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 118  2011-2013 Microchip Technology Inc. 4.8.1 DATA ACCESS FROM PROGRAM MEMORY USING TABLE INSTRUCTIONS The TBLRDL and TBLWTL instructions offer a direct method of reading or writing the lower word of any address within the Program Space without going through Data Space. The TBLRDH and TBLWTH instructions are the only method to read or write the upper 8 bits of a Program Space word as data. The PC is incremented by two for each successive 24-bit program word. This allows program memory addresses to directly map to Data Space addresses. Program memory can thus be regarded as two 16-bit-wide word address spaces, residing side by side, each with the same address range. TBLRDL and TBLWTL access the space that contains the least significant data word. TBLRDH and TBLWTH access the space that contains the upper data byte. Two table instructions are provided to move byte or word-sized (16-bit) data to and from Program Space. Both function as either byte or word operations. • TBLRDL (Table Read Low): - In Word mode, this instruction maps the lower word of the Program Space location (P<15:0>) to a data address (D<15:0>) - In Byte mode, either the upper or lower byte of the lower program word is mapped to the lower byte of a data address. The upper byte is selected when Byte Select is ‘1’; the lower byte is selected when it is ‘0’. • TBLRDH (Table Read High): - In Word mode, this instruction maps the entire upper word of a program address (P<23:16>) to a data address. The ‘phantom’ byte (D<15:8>) is always ‘0’. - In Byte mode, this instruction maps the upper or lower byte of the program word to D<7:0> of the data address in the TBLRDL instruction. The data is always ‘0’ when the upper ‘phantom’ byte is selected (Byte Select = 1). In a similar fashion, two table instructions, TBLWTH and TBLWTL, are used to write individual bytes or words to a Program Space address. The details of their operation are explained in Section 5.0 “Flash Program Memory”. For all table operations, the area of program memory space to be accessed is determined by the Table Page register (TBLPAG). TBLPAG covers the entire program memory space of the device, including user application and configuration spaces. When TBLPAG<7> = 0, the table page is located in the user memory space. When TBLPAG<7> = 1, the page is located in configuration space. FIGURE 4-23: ACCESSING PROGRAM MEMORY WITH TABLE INSTRUCTIONS 23 16 8 0 00000000 00000000 00000000 00000000 ‘Phantom’ Byte TBLRDH.B (Wn<0> = 0) TBLRDL.W TBLRDL.B (Wn<0> = 1) TBLRDL.B (Wn<0> = 0) 23 15 0 TBLPAG 02 0x000000 0x800000 0x020000 0x030000 Program Space The address for the table operation is determined by the data EA within the page defined by the TBLPAG register. Only read operations are shown; write operations are also valid in the user memory area.  2011-2013 Microchip Technology Inc. DS70000657H-page 119 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 5.0 FLASH PROGRAM MEMORY The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X devices contain internal Flash program memory for storing and executing application code. The memory is readable, writable and erasable during normal operation over the entire VDD range. Flash memory can be programmed in two ways: • In-Circuit Serial Programming™ (ICSP™) programming capability • Run-Time Self-Programming (RTSP) ICSP allows for a dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/ MC20X device to be serially programmed while in the end application circuit. This is done with two lines for programming clock and programming data (one of the alternate programming pin pairs: PGECx/PGEDx), and three other lines for power (VDD), ground (VSS) and Master Clear (MCLR). This allows customers to manufacture boards with unprogrammed devices and then program the device just before shipping the product. This also allows the most recent firmware or a custom firmware to be programmed. RTSP is accomplished using TBLRD (Table Read) and TBLWT (Table Write) instructions. With RTSP, the user application can write program memory data a single program memory word, and erase program memory in blocks or ‘pages’ of 1024 instructions (3072 bytes) at a time. 5.1 Table Instructions and Flash Programming Regardless of the method used, all programming of Flash memory is done with the Table Read and Table Write instructions. These allow direct read and write access to the program memory space from the data memory while the device is in normal operating mode. The 24-bit target address in the program memory is formed using bits<7:0> of the TBLPAG register and the Effective Address (EA) from a W register, specified in the table instruction, as shown in Figure 5-1. The TBLRDL and the TBLWTL instructions are used to read or write to bits<15:0> of program memory. TBLRDL and TBLWTL can access program memory in both Word and Byte modes. The TBLRDH and TBLWTH instructions are used to read or write to bits<23:16> of program memory. TBLRDH and TBLWTH can also access program memory in Word or Byte mode. FIGURE 5-1: ADDRESSING FOR TABLE REGISTERS Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Flash Programming” (DS70609) in the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. Program Counter 0 24 Bits Program Counter TBLPAG Reg 8 Bits Working Reg EA 16 Bits Byte 24-Bit EA 0 1/0 Select Using Table Instruction Using User/Configuration Space Select dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 120  2011-2013 Microchip Technology Inc. 5.2 RTSP Operation RTSP allows the user application to erase a single page of memory and to program two instruction words at a time. See the General Purpose and Motor Control Family tables (Table 1 and Table 2, respectively) for the page sizes of each device. For more information on erasing and programming Flash memory, refer to “Flash Programming” (DS70609) in the “dsPIC33/PIC24 Family Reference Manual”. 5.3 Programming Operations A complete programming sequence is necessary for programming or erasing the internal Flash in RTSP mode. The processor stalls (waits) until the programming operation is finished. For erase and program times, refer to Parameters D137a and D137b (Page Erase Time), and D138a and D138b (Word Write Cycle Time) in Table 30-14 in Section 30.0 “Electrical Characteristics”. Setting the WR bit (NVMCON<15>) starts the operation and the WR bit is automatically cleared when the operation is finished. 5.3.1 PROGRAMMING ALGORITHM FOR FLASH PROGRAM MEMORY Programmers can program two adjacent words (24 bits x 2) of program Flash memory at a time on every other word address boundary (0x000002, 0x000006, 0x00000A, etc.). To do this, it is necessary to erase the page that contains the desired address of the location the user wants to change. For protection against accidental operations, the write initiate sequence for NVMKEY must be used to allow any erase or program operation to proceed. After the programming command has been executed, the user application must wait for the programming time until programming is complete. The two instructions following the start of the programming sequence should be NOPs. Refer to Flash Programming” (DS70609) in the “dsPIC33/PIC24 Family Reference Manual” for details and codes examples on programming using RTSP. 5.4 Flash Memory Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 5.4.1 KEY RESOURCES • “Flash Programming” (DS70609) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools 5.5 Control Registers Four SFRs are used to erase and write the program Flash memory: NVMCON, NVMKEY, NVMADRH and NVMADRL. The NVMCON register (Register 5-1) enables and initiates Flash memory erase and write operations. NVMKEY (Register 5-4) is a write-only register that is used for write protection. To start a programming or erase sequence, the user application must consecutively write 0x55 and 0xAA to the NVMKEY register. There are two NVM Address registers: NVMADRH and NVMADRL. These two registers, when concatenated, form the 24-bit Effective Address (EA) of the selected word for programming operations or the selected page for erase operations. The NVMADRH register is used to hold the upper 8 bits of the EA, while the NVMADRL register is used to hold the lower 16 bits of the EA. Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464  2011-2013 Microchip Technology Inc. DS70000657H-page 121 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 5-1: NVMCON: NONVOLATILE MEMORY (NVM) CONTROL REGISTER R/SO-0(1) R/W-0(1) R/W-0(1) R/W-0 U-0 U-0 U-0 U-0 WR WREN WRERR NVMSIDL(2) — — — — bit 15 bit 8 U-0 U-0 U-0 U-0 R/W-0(1) R/W-0(1) R/W-0(1) R/W-0(1) — — — — NVMOP3(3,4) NVMOP2(3,4) NVMOP1(3,4) NVMOP0(3,4) bit 7 bit 0 Legend: SO = Settable Only bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 WR: Write Control bit(1) 1 = Initiates a Flash memory program or erase operation; the operation is self-timed and the bit is cleared by hardware once the operation is complete 0 = Program or erase operation is complete and inactive bit 14 WREN: Write Enable bit(1) 1 = Enables Flash program/erase operations 0 = Inhibits Flash program/erase operations bit 13 WRERR: Write Sequence Error Flag bit(1) 1 = An improper program or erase sequence attempt or termination has occurred (bit is set automatically on any set attempt of the WR bit) 0 = The program or erase operation completed normally bit 12 NVMSIDL: NVM Stop in Idle Control bit(2) 1 = Flash voltage regulator goes into Standby mode during Idle mode 0 = Flash voltage regulator is active during Idle mode bit 11-4 Unimplemented: Read as ‘0’ bit 3-0 NVMOP<3:0>: NVM Operation Select bits(1,3,4) 1111 = Reserved 1110 = Reserved 1101 = Reserved 1100 = Reserved 1011 = Reserved 1010 = Reserved 0011 = Memory page erase operation 0010 = Reserved 0001 = Memory double-word program operation(5) 0000 = Reserved Note 1: These bits can only be reset on a POR. 2: If this bit is set, there will be minimal power savings (IIDLE) and upon exiting Idle mode, there is a delay (TVREG) before Flash memory becomes operational. 3: All other combinations of NVMOP<3:0> are unimplemented. 4: Execution of the PWRSAV instruction is ignored while any of the NVM operations are in progress. 5: Two adjacent words on a 4-word boundary are programmed during execution of this operation. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 122  2011-2013 Microchip Technology Inc. REGISTER 5-4: NVMKEY: NONVOLATILE MEMORY KEY REGISTER 5-2: NVMADRH: NONVOLATILE MEMORY ADDRESS REGISTER HIGH U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x NVMADR<23:16> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-8 Unimplemented: Read as ‘0’ bit 7-0 NVMADR<23:16>: Nonvolatile Memory Write Address High bits Selects the upper 8 bits of the location to program or erase in program Flash memory. This register may be read or written by the user application. REGISTER 5-3: NVMADRL: NONVOLATILE MEMORY ADDRESS REGISTER LOW R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x NVMADR<15:8> bit 15 bit 8 R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x NVMADR<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 NVMADR<15:0>: Nonvolatile Memory Write Address Low bits Selects the lower 16 bits of the location to program or erase in program Flash memory. This register may be read or written by the user application. U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 W-0 W-0 W-0 W-0 W-0 W-0 W-0 W-0 NVMKEY<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-8 Unimplemented: Read as ‘0’ bit 7-0 NVMKEY<7:0>: Key Register (write-only) bits  2011-2013 Microchip Technology Inc. DS70000657H-page 123 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 6.0 RESETS The Reset module combines all Reset sources and controls the device Master Reset Signal, SYSRST. The following is a list of device Reset sources: • POR: Power-on Reset • BOR: Brown-out Reset • MCLR: Master Clear Pin Reset • SWR: RESET Instruction • WDTO: Watchdog Timer Time-out Reset • CM: Configuration Mismatch Reset • TRAPR: Trap Conflict Reset • IOPUWR: Illegal Condition Device Reset - Illegal Opcode Reset - Uninitialized W Register Reset - Security Reset A simplified block diagram of the Reset module is shown in Figure 6-1. Any active source of Reset will make the SYSRST signal active. On system Reset, some of the registers associated with the CPU and peripherals are forced to a known Reset state and some are unaffected. All types of device Reset set a corresponding status bit in the RCON register to indicate the type of Reset (see Register 6-1). A POR clears all the bits, except for the POR and BOR bits (RCON<1:0>), that are set. The user application can set or clear any bit at any time during code execution. The RCON bits only serve as status bits. Setting a particular Reset status bit in software does not cause a device Reset to occur. The RCON register also has other bits associated with the Watchdog Timer and device power-saving states. The function of these bits is discussed in other sections of this manual. For all Resets, the default clock source is determined by the FNOSC<2:0> bits in the FOSCSEL Configuration register. The value of the FNOSC<2:0> bits is loaded into NOSC<2:0> (OSCCON<10:8>) on Reset, which in turn, initializes the system clock. FIGURE 6-1: RESET SYSTEM BLOCK DIAGRAM Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Reset” (DS70602) in the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. Note: Refer to the specific peripheral section or Section 4.0 “Memory Organization” of this manual for register Reset states. Note: The status bits in the RCON register should be cleared after they are read so that the next RCON register value after a device Reset is meaningful. MCLR VDD BOR Sleep or Idle RESET Instruction WDT Module Glitch Filter Trap Conflict Illegal Opcode Uninitialized W Register SYSRST VDD Rise Detect POR Configuration Mismatch Security Reset Internal Regulator dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 124  2011-2013 Microchip Technology Inc. 6.1 Reset Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 6.1.1 KEY RESOURCES • “Reset” (DS70602) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464  2011-2013 Microchip Technology Inc. DS70000657H-page 125 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 6-1: RCON: RESET CONTROL REGISTER(1) R/W-0 R/W-0 U-0 U-0 R/W-0 U-0 R/W-0 R/W-0 TRAPR IOPUWR — — VREGSF — CM VREGS bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-1 R/W-1 EXTR SWR SWDTEN(2) WDTO SLEEP IDLE BOR POR bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 TRAPR: Trap Reset Flag bit 1 = A Trap Conflict Reset has occurred 0 = A Trap Conflict Reset has not occurred bit 14 IOPUWR: Illegal Opcode or Uninitialized W Access Reset Flag bit 1 = An illegal opcode detection, an illegal address mode or Uninitialized W register used as an Address Pointer caused a Reset 0 = An illegal opcode or Uninitialized W register Reset has not occurred bit 13-12 Unimplemented: Read as ‘0’ bit 11 VREGSF: Flash Voltage Regulator Standby During Sleep bit 1 = Flash voltage regulator is active during Sleep 0 = Flash voltage regulator goes into Standby mode during Sleep bit 10 Unimplemented: Read as ‘0’ bit 9 CM: Configuration Mismatch Flag bit 1 = A Configuration Mismatch Reset has occurred. 0 = A Configuration Mismatch Reset has not occurred bit 8 VREGS: Voltage Regulator Standby During Sleep bit 1 = Voltage regulator is active during Sleep 0 = Voltage regulator goes into Standby mode during Sleep bit 7 EXTR: External Reset (MCLR) Pin bit 1 = A Master Clear (pin) Reset has occurred 0 = A Master Clear (pin) Reset has not occurred bit 6 SWR: Software RESET (Instruction) Flag bit 1 = A RESET instruction has been executed 0 = A RESET instruction has not been executed bit 5 SWDTEN: Software Enable/Disable of WDT bit(2) 1 = WDT is enabled 0 = WDT is disabled bit 4 WDTO: Watchdog Timer Time-out Flag bit 1 = WDT time-out has occurred 0 = WDT time-out has not occurred Note 1: All of the Reset status bits can be set or cleared in software. Setting one of these bits in software does not cause a device Reset. 2: If the FWDTEN Configuration bit is ‘1’ (unprogrammed), the WDT is always enabled, regardless of the SWDTEN bit setting. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 126  2011-2013 Microchip Technology Inc. bit 3 SLEEP: Wake-up from Sleep Flag bit 1 = Device has been in Sleep mode 0 = Device has not been in Sleep mode bit 2 IDLE: Wake-up from Idle Flag bit 1 = Device was in Idle mode 0 = Device was not in Idle mode bit 1 BOR: Brown-out Reset Flag bit 1 = A Brown-out Reset has occurred 0 = A Brown-out Reset has not occurred bit 0 POR: Power-on Reset Flag bit 1 = A Power-on Reset has occurred 0 = A Power-on Reset has not occurred REGISTER 6-1: RCON: RESET CONTROL REGISTER(1) (CONTINUED) Note 1: All of the Reset status bits can be set or cleared in software. Setting one of these bits in software does not cause a device Reset. 2: If the FWDTEN Configuration bit is ‘1’ (unprogrammed), the WDT is always enabled, regardless of the SWDTEN bit setting.  2011-2013 Microchip Technology Inc. DS70000657H-page 127 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 7.0 INTERRUPT CONTROLLER The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X interrupt controller reduces the numerous peripheral interrupt request signals to a single interrupt request signal to the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X CPU. The interrupt controller has the following features: • Up to eight processor exceptions and software traps • Eight user-selectable priority levels • Interrupt Vector Table (IVT) with a unique vector for each interrupt or exception source • Fixed priority within a specified user priority level • Fixed interrupt entry and return latencies 7.1 Interrupt Vector Table The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X Interrupt Vector Table (IVT), shown in Figure 7-1, resides in program memory starting at location, 000004h. The IVT contains seven non-maskable trap vectors and up to 246 sources of interrupt. In general, each interrupt source has its own vector. Each interrupt vector contains a 24-bit-wide address. The value programmed into each interrupt vector location is the starting address of the associated Interrupt Service Routine (ISR). Interrupt vectors are prioritized in terms of their natural priority. This priority is linked to their position in the vector table. Lower addresses generally have a higher natural priority. For example, the interrupt associated with Vector 0 takes priority over interrupts at any other vector address. 7.2 Reset Sequence A device Reset is not a true exception because the interrupt controller is not involved in the Reset process. The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X devices clear their registers in response to a Reset, which forces the PC to zero. The device then begins program execution at location, 0x000000. A GOTO instruction at the Reset address can redirect program execution to the appropriate start-up routine. Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Interrupts” (DS70600) in the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. Note: Any unimplemented or unused vector locations in the IVT should be programmed with the address of a default interrupt handler routine that contains a RESET instruction. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 128  2011-2013 Microchip Technology Inc. FIGURE 7-1: dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X INTERRUPT VECTOR TABLE IVT Decreasing Natural Order Priority Reset – GOTO Instruction 0x000000 Reset – GOTO Address 0x000002 Oscillator Fail Trap Vector 0x000004 Address Error Trap Vector 0x000006 Generic Hard Trap Vector 0x000008 Stack Error Trap Vector 0x00000A Math Error Trap Vector 0x00000C DMAC Error Trap Vector 0x00000E Generic Soft Trap Vector 0x000010 Reserved 0x000012 Interrupt Vector 0 0x000014 Interrupt Vector 1 0x000016 : : : : : : Interrupt Vector 52 0x00007C Interrupt Vector 53 0x00007E Interrupt Vector 54 0x000080 : : : : : : Interrupt Vector 116 0x0000FC Interrupt Vector 117 0x0000FE Interrupt Vector 118 0x000100 Interrupt Vector 119 0x000102 Interrupt Vector 120 0x000104 : : : : : : Interrupt Vector 244 0x0001FC Interrupt Vector 245 0x0001FE START OF CODE 0x000200 See Table 7-1 for Interrupt Vector Details  2011-2013 Microchip Technology Inc. DS70000657H-page 129 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 7-1: INTERRUPT VECTOR DETAILS Interrupt Source Vector # IRQ # IVT Address Interrupt Bit Location Flag Enable Priority Highest Natural Order Priority INT0 – External Interrupt 0 8 0 0x000014 IFS0<0> IEC0<0> IPC0<2:0> IC1 – Input Capture 1 9 1 0x000016 IFS0<1> IEC0<1> IPC0<6:4> OC1 – Output Compare 1 10 2 0x000018 IFS0<2> IEC0<2> IPC0<10:8> T1 – Timer1 11 3 0x00001A IFS0<3> IEC0<3> IPC0<14:12> DMA0 – DMA Channel 0 12 4 0x00001C IFS0<4> IEC0<4> IPC1<2:0> IC2 – Input Capture 2 13 5 0x00001E IFS0<5> IEC0<5> IPC1<6:4> OC2 – Output Compare 2 14 6 0x000020 IFS0<6> IEC0<6> IPC1<10:8> T2 – Timer2 15 7 0x000022 IFS0<7> IEC0<7> IPC1<14:12> T3 – Timer3 16 8 0x000024 IFS0<8> IEC0<8> IPC2<2:0> SPI1E – SPI1 Error 17 9 0x000026 IFS0<9> IEC0<9> IPC2<6:4> SPI1 – SPI1 Transfer Done 18 10 0x000028 IFS0<10> IEC0<10> IPC2<10:8> U1RX – UART1 Receiver 19 11 0x00002A IFS0<11> IEC0<11> IPC2<14:12> U1TX – UART1 Transmitter 20 12 0x00002C IFS0<12> IEC0<12> IPC3<2:0> AD1 – ADC1 Convert Done 21 13 0x00002E IFS0<13> IEC0<13> IPC3<6:4> DMA1 – DMA Channel 1 22 14 0x000030 IFS0<14> IEC0<14> IPC3<10:8> Reserved 23 15 0x000032 — — — SI2C1 – I2C1 Slave Event 24 16 0x000034 IFS1<0> IEC1<0> IPC4<2:0> MI2C1 – I2C1 Master Event 25 17 0x000036 IFS1<1> IEC1<1> IPC4<6:4> CM – Comparator Combined Event 26 18 0x000038 IFS1<2> IEC1<2> IPC4<10:8> CN – Input Change Interrupt 27 19 0x00003A IFS1<3> IEC1<3> IPC4<14:12> INT1 – External Interrupt 1 28 20 0x00003C IFS1<4> IEC1<4> IPC5<2:0> Reserved 29-31 21-23 0x00003E-0x000042 — — — DMA2 – DMA Channel 2 32 24 0x000044 IFS1<8> IEC1<8> IPC6<2:0> OC3 – Output Compare 3 33 25 0x000046 IFS1<9> IEC1<9> IPC6<6:4> OC4 – Output Compare 4 34 26 0x000048 IFS1<10> IEC1<10> IPC6<10:8> T4 – Timer4 35 27 0x00004A IFS1<11> IEC1<11> IPC6<14:12> T5 – Timer5 36 28 0x00004C IFS1<12> IEC1<12> IPC7<2:0> INT2 – External Interrupt 2 37 29 0x00004E IFS1<13> IEC1<13> IPC7<6:4> U2RX – UART2 Receiver 38 30 0x000050 IFS1<14> IEC1<14> IPC7<10:8> U2TX – UART2 Transmitter 39 31 0x000052 IFS1<15> IEC1<15> IPC7<14:12> SPI2E – SPI2 Error 40 32 0x000054 IFS2<0> IEC2<0> IPC8<2:0> SPI2 – SPI2 Transfer Done 41 33 0x000056 IFS2<1> IEC2<1> IPC8<6:4> C1RX – CAN1 RX Data Ready(1) 42 34 0x000058 IFS2<2> IEC2<2> IPC8<10:8> C1 – CAN1 Event(1) 43 35 0x00005A IFS2<3> IEC2<3> IPC8<14:12> DMA3 – DMA Channel 3 44 36 0x00005C IFS2<4> IEC2<4> IPC9<2:0> IC3 – Input Capture 3 45 37 0x00005E IFS2<5> IEC2<5> IPC9<6:4> IC4 – Input Capture 4 46 38 0x000060 IFS2<6> IEC2<6> IPC9<10:8> Reserved 47-56 39-48 0x000062-0x000074 — — — SI2C2 – I2C2 Slave Event 57 49 0x000076 IFS3<1> IEC3<1> IPC12<6:4> MI2C2 – I2C2 Master Event 58 50 0x000078 IFS3<2> IEC3<2> IPC12<10:8> Reserved 59-64 51-56 0x00007A-0x000084 — — — PSEM – PWM Special Event Match(2) 65 57 0x000086 IFS3<9> IEC3<9> IPC14<6:4> Note 1: This interrupt source is available on dsPIC33EPXXXGP50X and dsPIC33EPXXXMC50X devices only. 2: This interrupt source is available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 130  2011-2013 Microchip Technology Inc. QEI1 – QEI1 Position Counter Compare(2) 66 58 0x000088 IFS3<10> IEC3<10> IPC14<10:8> Reserved 67-72 59-64 0x00008A-0x000094 — — — U1E – UART1 Error Interrupt 73 65 0x000096 IFS4<1> IEC4<1> IPC16<6:4> U2E – UART2 Error Interrupt 74 66 0x000098 IFS4<2> IEC4<2> IPC16<10:8> CRC – CRC Generator Interrupt 75 67 0x00009A IFS4<3> IEC4<3> IPC16<14:12> Reserved 76-77 68-69 0x00009C-0x00009E — — — C1TX – CAN1 TX Data Request(1) 78 70 0x000A0 IFS4<6> IEC4<6> IPC17<10:8> Reserved 79-84 71-76 0x0000A2-0x0000AC — — — CTMU – CTMU Interrupt 85 77 0x0000AE IFS4<13> IEC4<13> IPC19<6:4> Reserved 86-101 78-93 0x0000B0-0x0000CE — — — PWM1 – PWM Generator 1(2) 102 94 0x0000D0 IFS5<14> IEC5<14> IPC23<10:8> PWM2 – PWM Generator 2(2) 103 95 0x0000D2 IFS5<15> IEC5<15> IPC23<14:12> PWM3 – PWM Generator 3(2) 104 96 0x0000D4 IFS6<0> IEC6<0> IPC24<2:0> Reserved 105-149 97-141 0x0001D6-0x00012E — — — ICD – ICD Application 150 142 0x000142 IFS8<14> IEC8<14> IPC35<10:8> JTAG – JTAG Programming 151 143 0x000130 IFS8<15> IEC8<15> IPC35<14:12> Reserved 152 144 0x000134 — — — PTGSTEP – PTG Step 153 145 0x000136 IFS9<1> IEC9<1> IPC36<6:4> PTGWDT – PTG Watchdog Time-out 154 146 0x000138 IFS9<2> IEC9<2> IPC36<10:8> PTG0 – PTG Interrupt 0 155 147 0x00013A IFS9<3> IEC9<3> IPC36<14:12> PTG1 – PTG Interrupt 1 156 148 0x00013C IFS9<4> IEC9<4> IPC37<2:0> PTG2 – PTG Interrupt 2 157 149 0x00013E IFS9<5> IEC9<5> IPC37<6:4> PTG3 – PTG Interrupt 3 158 150 0x000140 IFS9<6> IEC9<6> IPC37<10:8> Reserved 159-245 151-245 0x000142-0x0001FE — — — Lowest Natural Order Priority TABLE 7-1: INTERRUPT VECTOR DETAILS (CONTINUED) Interrupt Source Vector # IRQ # IVT Address Interrupt Bit Location Flag Enable Priority Note 1: This interrupt source is available on dsPIC33EPXXXGP50X and dsPIC33EPXXXMC50X devices only. 2: This interrupt source is available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only.  2011-2013 Microchip Technology Inc. DS70000657H-page 131 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 7.3 Interrupt Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 7.3.1 KEY RESOURCES • “Interrupts” (DS70600) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools 7.4 Interrupt Control and Status Registers dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X devices implement the following registers for the interrupt controller: • INTCON1 • INTCON2 • INTCON3 • INTCON4 • INTTREG 7.4.1 INTCON1 THROUGH INTCON4 Global interrupt control functions are controlled from INTCON1, INTCON2, INTCON3 and INTCON4. INTCON1 contains the Interrupt Nesting Disable bit (NSTDIS), as well as the control and status flags for the processor trap sources. The INTCON2 register controls external interrupt request signal behavior and also contains the Global Interrupt Enable bit (GIE). INTCON3 contains the status flags for the DMA and DO stack overflow status trap sources. The INTCON4 register contains the software generated hard trap status bit (SGHT). 7.4.2 IFSx The IFSx registers maintain all of the interrupt request flags. Each source of interrupt has a status bit, which is set by the respective peripherals or external signal and is cleared via software. 7.4.3 IECx The IECx registers maintain all of the interrupt enable bits. These control bits are used to individually enable interrupts from the peripherals or external signals. 7.4.4 IPCx The IPCx registers are used to set the Interrupt Priority Level (IPL) for each source of interrupt. Each user interrupt source can be assigned to one of eight priority levels. 7.4.5 INTTREG The INTTREG register contains the associated interrupt vector number and the new CPU Interrupt Priority Level, which are latched into the Vector Number bits (VECNUM<7:0>) and Interrupt Priority Level bits (ILR<3:0>) fields in the INTTREG register. The new Interrupt Priority Level is the priority of the pending interrupt. The interrupt sources are assigned to the IFSx, IECx and IPCx registers in the same sequence as they are listed in Table 7-1. For example, the INT0 (External Interrupt 0) is shown as having Vector Number 8 and a natural order priority of 0. Thus, the INT0IF bit is found in IFS0<0>, the INT0IE bit in IEC0<0> and the INT0IP bits in the first position of IPC0 (IPC0<2:0>). 7.4.6 STATUS/CONTROL REGISTERS Although these registers are not specifically part of the interrupt control hardware, two of the CPU Control registers contain bits that control interrupt functionality. For more information on these registers refer to “CPU” (DS70359) in the “dsPIC33/PIC24 Family Reference Manual”. • The CPU STATUS Register, SR, contains the IPL<2:0> bits (SR<7:5>). These bits indicate the current CPU Interrupt Priority Level. The user software can change the current CPU Interrupt Priority Level by writing to the IPLx bits. • The CORCON register contains the IPL3 bit which, together with IPL<2:0>, also indicates the current CPU priority level. IPL3 is a read-only bit so that trap events cannot be masked by the user software. All Interrupt registers are described in Register 7-3 through Register 7-7 in the following pages. Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 132  2011-2013 Microchip Technology Inc. REGISTER 7-1: SR: CPU STATUS REGISTER(1) R/W-0 R/W-0 R/W-0 R/W-0 R/C-0 R/C-0 R-0 R/W-0 OA OB SA SB OAB SAB DA DC bit 15 bit 8 R/W-0(3) R/W-0(3) R/W-0(3) R-0 R/W-0 R/W-0 R/W-0 R/W-0 IPL<2:0>(2) RA N OV Z C bit 7 bit 0 Legend: C = Clearable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’= Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 7-5 IPL<2:0>: CPU Interrupt Priority Level Status bits(2,3) 111 = CPU Interrupt Priority Level is 7 (15); user interrupts are disabled 110 = CPU Interrupt Priority Level is 6 (14) 101 = CPU Interrupt Priority Level is 5 (13) 100 = CPU Interrupt Priority Level is 4 (12) 011 = CPU Interrupt Priority Level is 3 (11) 010 = CPU Interrupt Priority Level is 2 (10) 001 = CPU Interrupt Priority Level is 1 (9) 000 = CPU Interrupt Priority Level is 0 (8) Note 1: For complete register details, see Register 3-1. 2: The IPL<2:0> bits are concatenated with the IPL<3> bit (CORCON<3>) to form the CPU Interrupt Priority Level. The value in parentheses indicates the IPL, if IPL<3> = 1. User interrupts are disabled when IPL<3> = 1. 3: The IPL<2:0> Status bits are read-only when the NSTDIS bit (INTCON1<15>) = 1.  2011-2013 Microchip Technology Inc. DS70000657H-page 133 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 7-2: CORCON: CORE CONTROL REGISTER(1) R/W-0 U-0 R/W-0 R/W-0 R/W-0 R-0 R-0 R-0 VAR — US1 US0 EDT DL2 DL1 DL0 bit 15 bit 8 R/W-0 R/W-0 R/W-1 R/W-0 R/C-0 R-0 R/W-0 R/W-0 SATA SATB SATDW ACCSAT IPL3(2) SFA RND IF bit 7 bit 0 Legend: C = Clearable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’= Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 VAR: Variable Exception Processing Latency Control bit 1 = Variable exception processing is enabled 0 = Fixed exception processing is enabled bit 3 IPL3: CPU Interrupt Priority Level Status bit 3(2) 1 = CPU Interrupt Priority Level is greater than 7 0 = CPU Interrupt Priority Level is 7 or less Note 1: For complete register details, see Register 3-2. 2: The IPL3 bit is concatenated with the IPL<2:0> bits (SR<7:5>) to form the CPU Interrupt Priority Level. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 134  2011-2013 Microchip Technology Inc. REGISTER 7-3: INTCON1: INTERRUPT 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 NSTDIS OVAERR(1) OVBERR(1) COVAERR(1) COVBERR(1) OVATE(1) OVBTE(1) COVTE(1) bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 U-0 SFTACERR(1) DIV0ERR DMACERR MATHERR ADDRERR STKERR OSCFAIL — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 NSTDIS: Interrupt Nesting Disable bit 1 = Interrupt nesting is disabled 0 = Interrupt nesting is enabled bit 14 OVAERR: Accumulator A Overflow Trap Flag bit(1) 1 = Trap was caused by overflow of Accumulator A 0 = Trap was not caused by overflow of Accumulator A bit 13 OVBERR: Accumulator B Overflow Trap Flag bit(1) 1 = Trap was caused by overflow of Accumulator B 0 = Trap was not caused by overflow of Accumulator B bit 12 COVAERR: Accumulator A Catastrophic Overflow Trap Flag bit(1) 1 = Trap was caused by catastrophic overflow of Accumulator A 0 = Trap was not caused by catastrophic overflow of Accumulator A bit 11 COVBERR: Accumulator B Catastrophic Overflow Trap Flag bit(1) 1 = Trap was caused by catastrophic overflow of Accumulator B 0 = Trap was not caused by catastrophic overflow of Accumulator B bit 10 OVATE: Accumulator A Overflow Trap Enable bit(1) 1 = Trap overflow of Accumulator A 0 = Trap is disabled bit 9 OVBTE: Accumulator B Overflow Trap Enable bit(1) 1 = Trap overflow of Accumulator B 0 = Trap is disabled bit 8 COVTE: Catastrophic Overflow Trap Enable bit(1) 1 = Trap on catastrophic overflow of Accumulator A or B is enabled 0 = Trap is disabled bit 7 SFTACERR: Shift Accumulator Error Status bit(1) 1 = Math error trap was caused by an invalid accumulator shift 0 = Math error trap was not caused by an invalid accumulator shift bit 6 DIV0ERR: Divide-by-Zero Error Status bit 1 = Math error trap was caused by a divide-by-zero 0 = Math error trap was not caused by a divide-by-zero bit 5 DMACERR: DMAC Trap Flag bit 1 = DMAC trap has occurred 0 = DMAC trap has not occurred Note 1: These bits are available on dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X devices only.  2011-2013 Microchip Technology Inc. DS70000657H-page 135 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 4 MATHERR: Math Error Status bit 1 = Math error trap has occurred 0 = Math error trap has not occurred bit 3 ADDRERR: Address Error Trap Status bit 1 = Address error trap has occurred 0 = Address error trap has not occurred bit 2 STKERR: Stack Error Trap Status bit 1 = Stack error trap has occurred 0 = Stack error trap has not occurred bit 1 OSCFAIL: Oscillator Failure Trap Status bit 1 = Oscillator failure trap has occurred 0 = Oscillator failure trap has not occurred bit 0 Unimplemented: Read as ‘0’ REGISTER 7-3: INTCON1: INTERRUPT CONTROL REGISTER 1 (CONTINUED) Note 1: These bits are available on dsPIC33EPXXXMC20X/50X and dsPIC33EPXXXGP50X devices only. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 136  2011-2013 Microchip Technology Inc. REGISTER 7-4: INTCON2: INTERRUPT CONTROL REGISTER 2 R/W-1 R/W-0 R/W-0 U-0 U-0 U-0 U-0 U-0 GIE DISI SWTRAP — — — — — bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 — — — — — INT2EP INT1EP INT0EP bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 GIE: Global Interrupt Enable bit 1 = Interrupts and associated IE bits are enabled 0 = Interrupts are disabled, but traps are still enabled bit 14 DISI: DISI Instruction Status bit 1 = DISI instruction is active 0 = DISI instruction is not active bit 13 SWTRAP: Software Trap Status bit 1 = Software trap is enabled 0 = Software trap is disabled bit 12-3 Unimplemented: Read as ‘0’ bit 2 INT2EP: External Interrupt 2 Edge Detect Polarity Select bit 1 = Interrupt on negative edge 0 = Interrupt on positive edge bit 1 INT1EP: External Interrupt 1 Edge Detect Polarity Select bit 1 = Interrupt on negative edge 0 = Interrupt on positive edge bit 0 INT0EP: External Interrupt 0 Edge Detect Polarity Select bit 1 = Interrupt on negative edge 0 = Interrupt on positive edge  2011-2013 Microchip Technology Inc. DS70000657H-page 137 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 7-5: INTCON3: INTERRUPT CONTROL REGISTER 3 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 U-0 R/W-0 R/W-0 U-0 U-0 U-0 U-0 — — DAE DOOVR — — — — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-6 Unimplemented: Read as ‘0’ bit 5 DAE: DMA Address Error Soft Trap Status bit 1 = DMA address error soft trap has occurred 0 = DMA address error soft trap has not occurred bit 4 DOOVR: DO Stack Overflow Soft Trap Status bit 1 = DO stack overflow soft trap has occurred 0 = DO stack overflow soft trap has not occurred bit 3-0 Unimplemented: Read as ‘0’ REGISTER 7-6: INTCON4: INTERRUPT CONTROL REGISTER 4 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 U-0 U-0 R/W-0 — — — — — — — SGHT bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-1 Unimplemented: Read as ‘0’ bit 0 SGHT: Software Generated Hard Trap Status bit 1 = Software generated hard trap has occurred 0 = Software generated hard trap has not occurred dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 138  2011-2013 Microchip Technology Inc. REGISTER 7-7: INTTREG: INTERRUPT CONTROL AND STATUS REGISTER U-0 U-0 U-0 U-0 R-0 R-0 R-0 R-0 — — — — ILR3 ILR2 ILR1 ILR0 bit 15 bit 8 R-0 R-0 R-0 R-0 R-0 R-0 R-0 R-0 VECNUM7 VECNUM6 VECNUM5 VECNUM4 VECNUM3 VECNUM2 VECNUM1 VECNUM0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-12 Unimplemented: Read as ‘0’ bit 11-8 ILR<3:0>: New CPU Interrupt Priority Level bits 1111 = CPU Interrupt Priority Level is 15 • • • 0001 = CPU Interrupt Priority Level is 1 0000 = CPU Interrupt Priority Level is 0 bit 7-0 VECNUM<7:0>: Vector Number of Pending Interrupt bits 11111111 = 255, Reserved; do not use • • • 00001001 = 9, IC1 – Input Capture 1 00001000 = 8, INT0 – External Interrupt 0 00000111 = 7, Reserved; do not use 00000110 = 6, Generic soft error trap 00000101 = 5, DMAC error trap 00000100 = 4, Math error trap 00000011 = 3, Stack error trap 00000010 = 2, Generic hard trap 00000001 = 1, Address error trap 00000000 = 0, Oscillator fail trap  2011-2013 Microchip Technology Inc. DS70000657H-page 139 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 8.0 DIRECT MEMORY ACCESS (DMA) The DMA Controller transfers data between Peripheral Data registers and Data Space SRAM In addition, DMA can access the entire data memory space. The Data Memory Bus Arbiter is utilized when either the CPU or DMA attempts to access SRAM, resulting in potential DMA or CPU stalls. The DMA Controller supports 4 independent channels. Each channel can be configured for transfers to or from selected peripherals. Some of the peripherals supported by the DMA Controller include: • ECAN™ • Analog-to-Digital Converter (ADC) • Serial Peripheral Interface (SPI) • UART • Input Capture • Output Compare Refer to Table 8-1 for a complete list of supported peripherals. FIGURE 8-1: DMA CONTROLLER MODULE Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Direct Memory Access (DMA)” (DS70348) in the “dsPIC33/ PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. PERIPHERAL DMA Data Memory SRAM (see Figure 4-18) Arbiter dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 140  2011-2013 Microchip Technology Inc. In addition, DMA transfers can be triggered by timers as well as external interrupts. Each DMA channel is unidirectional. Two DMA channels must be allocated to read and write to a peripheral. If more than one channel receives a request to transfer data, a simple fixed priority scheme based on channel number, dictates which channel completes the transfer and which channel, or channels, are left pending. Each DMA channel moves a block of data, after which, it generates an interrupt to the CPU to indicate that the block is available for processing. The DMA Controller provides these functional capabilities: • Four DMA channels • Register Indirect with Post-Increment Addressing mode • Register Indirect without Post-Increment Addressing mode • Peripheral Indirect Addressing mode (peripheral generates destination address) • CPU interrupt after half or full block transfer complete • Byte or word transfers • Fixed priority channel arbitration • Manual (software) or automatic (peripheral DMA requests) transfer initiation • One-Shot or Auto-Repeat Block Transfer modes • Ping-Pong mode (automatic switch between two SRAM start addresses after each block transfer is complete) • DMA request for each channel can be selected from any supported interrupt source • Debug support features The peripherals that can utilize DMA are listed in Table 8-1. TABLE 8-1: DMA CHANNEL TO PERIPHERAL ASSOCIATIONS Peripheral to DMA Association DMAxREQ Register IRQSEL<7:0> Bits DMAxPAD Register (Values to Read from Peripheral) DMAxPAD Register (Values to Write to Peripheral) INT0 – External Interrupt 0 00000000 — — IC1 – Input Capture 1 00000001 0x0144 (IC1BUF) — IC2 – Input Capture 2 00000101 0x014C (IC2BUF) — IC3 – Input Capture 3 00100101 0x0154 (IC3BUF) — IC4 – Input Capture 4 00100110 0x015C (IC4BUF) — OC1 – Output Compare 1 00000010 — 0x0906 (OC1R) 0x0904 (OC1RS) OC2 – Output Compare 2 00000110 — 0x0910 (OC2R) 0x090E (OC2RS) OC3 – Output Compare 3 00011001 — 0x091A (OC3R) 0x0918 (OC3RS) OC4 – Output Compare 4 00011010 — 0x0924 (OC4R) 0x0922 (OC4RS) TMR2 – Timer2 00000111 — — TMR3 – Timer3 00001000 — — TMR4 – Timer4 00011011 — — TMR5 – Timer5 00011100 — — SPI1 Transfer Done 00001010 0x0248 (SPI1BUF) 0x0248 (SPI1BUF) SPI2 Transfer Done 00100001 0x0268 (SPI2BUF) 0x0268 (SPI2BUF) UART1RX – UART1 Receiver 00001011 0x0226 (U1RXREG) — UART1TX – UART1 Transmitter 00001100 — 0x0224 (U1TXREG) UART2RX – UART2 Receiver 00011110 0x0236 (U2RXREG) — UART2TX – UART2 Transmitter 00011111 — 0x0234 (U2TXREG) ECAN1 – RX Data Ready 00100010 0x0440 (C1RXD) — ECAN1 – TX Data Request 01000110 — 0x0442 (C1TXD) ADC1 – ADC1 Convert Done 00001101 0x0300 (ADC1BUF0) —  2011-2013 Microchip Technology Inc. DS70000657H-page 141 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 8-2: DMA CONTROLLER BLOCK DIAGRAM 8.1 DMA Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 8.1.1 KEY RESOURCES • Section 22. “Direct Memory Access (DMA)” (DS70348) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools 8.2 DMAC Registers Each DMAC Channel x (where x = 0 through 3) contains the following registers: • 16-Bit DMA Channel Control register (DMAxCON) • 16-Bit DMA Channel IRQ Select register (DMAxREQ) • 32-Bit DMA RAM Primary Start Address register (DMAxSTA) • 32-Bit DMA RAM Secondary Start Address register (DMAxSTB) • 16-Bit DMA Peripheral Address register (DMAxPAD) • 14-Bit DMA Transfer Count register (DMAxCNT) Additional status registers (DMAPWC, DMARQC, DMAPPS, DMALCA and DSADR) are common to all DMAC channels. These status registers provide information on write and request collisions, as well as on last address and channel access information. The interrupt flags (DMAxIF) are located in an IFSx register in the interrupt controller. The corresponding interrupt enable control bits (DMAxIE) are located in an IECx register in the interrupt controller, and the corresponding interrupt priority control bits (DMAxIP) are located in an IPCx register in the interrupt controller. CPU Arbiter Peripheral Non-DMA DMA X-Bus Peripheral Indirect Address DMA Control DMA Controller DMA CPU Peripheral X-Bus IRQ to DMA and Interrupt Controller Modules IRQ to DMA and Interrupt Controller Modules IRQ to DMA and Interrupt Controller Modules 0123 SRAM Channels Peripheral 1 DMA Ready CPU DMA Peripheral 3 DMA Ready CPU DMA Peripheral 2 DMA Ready CPU DMA Note: CPU and DMA address buses are not shown for clarity. Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 142  2011-2013 Microchip Technology Inc. REGISTER 8-1: DMAXCON: DMA CHANNEL X CONTROL REGISTER R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 U-0 U-0 U-0 CHEN SIZE DIR HALF NULLW — — — bit 15 bit 8 U-0 U-0 R/W-0 R/W-0 U-0 U-0 R/W-0 R/W-0 — — AMODE1 AMODE0 — — MODE1 MODE0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 CHEN: DMA Channel Enable bit 1 = Channel is enabled 0 = Channel is disabled bit 14 SIZE: DMA Data Transfer Size bit 1 = Byte 0 = Word bit 13 DIR: DMA Transfer Direction bit (source/destination bus select) 1 = Reads from RAM address, writes to peripheral address 0 = Reads from peripheral address, writes to RAM address bit 12 HALF: DMA Block Transfer Interrupt Select bit 1 = Initiates interrupt when half of the data has been moved 0 = Initiates interrupt when all of the data has been moved bit 11 NULLW: Null Data Peripheral Write Mode Select bit 1 = Null data write to peripheral in addition to RAM write (DIR bit must also be clear) 0 = Normal operation bit 10-6 Unimplemented: Read as ‘0’ bit 5-4 AMODE<1:0>: DMA Channel Addressing Mode Select bits 11 = Reserved 10 = Peripheral Indirect Addressing mode 01 = Register Indirect without Post-Increment mode 00 = Register Indirect with Post-Increment mode bit 3-2 Unimplemented: Read as ‘0’ bit 1-0 MODE<1:0>: DMA Channel Operating Mode Select bits 11 = One-Shot, Ping-Pong modes are enabled (one block transfer from/to each DMA buffer) 10 = Continuous, Ping-Pong modes are enabled 01 = One-Shot, Ping-Pong modes are disabled 00 = Continuous, Ping-Pong modes are disabled  2011-2013 Microchip Technology Inc. DS70000657H-page 143 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 8-2: DMAXREQ: DMA CHANNEL X IRQ SELECT REGISTER R/S-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 FORCE(1) — — — — — — — bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 IRQSEL7 IRQSEL6 IRQSEL5 IRQSEL4 IRQSEL3 IRQSEL2 IRQSEL1 IRQSEL0 bit 7 bit 0 Legend: S = Settable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 FORCE: Force DMA Transfer bit(1) 1 = Forces a single DMA transfer (Manual mode) 0 = Automatic DMA transfer initiation by DMA request bit 14-8 Unimplemented: Read as ‘0’ bit 7-0 IRQSEL<7:0>: DMA Peripheral IRQ Number Select bits 01000110 = ECAN1 – TX Data Request(2) 00100110 = IC4 – Input Capture 4 00100101 = IC3 – Input Capture 3 00100010 = ECAN1 – RX Data Ready(2) 00100001 = SPI2 Transfer Done 00011111 = UART2TX – UART2 Transmitter 00011110 = UART2RX – UART2 Receiver 00011100 = TMR5 – Timer5 00011011 = TMR4 – Timer4 00011010 = OC4 – Output Compare 4 00011001 = OC3 – Output Compare 3 00001101 = ADC1 – ADC1 Convert done 00001100 = UART1TX – UART1 Transmitter 00001011 = UART1RX – UART1 Receiver 00001010 = SPI1 – Transfer Done 00001000 = TMR3 – Timer3 00000111 = TMR2 – Timer2 00000110 = OC2 – Output Compare 2 00000101 = IC2 – Input Capture 2 00000010 = OC1 – Output Compare 1 00000001 = IC1 – Input Capture 1 00000000 = INT0 – External Interrupt 0 Note 1: The FORCE bit cannot be cleared by user software. The FORCE bit is cleared by hardware when the forced DMA transfer is complete or the channel is disabled (CHEN = 0). 2: This selection is available in dsPIC33EPXXXGP/MC50X devices only. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 144  2011-2013 Microchip Technology Inc. REGISTER 8-3: DMAXSTAH: DMA CHANNEL X START ADDRESS REGISTER A (HIGH) U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 STA<23:16> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-8 Unimplemented: Read as ‘0’ bit 7-0 STA<23:16>: Primary Start Address bits (source or destination) REGISTER 8-4: DMAXSTAL: DMA CHANNEL X START ADDRESS REGISTER A (LOW) R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 STA<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 STA<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 STA<15:0>: Primary Start Address bits (source or destination)  2011-2013 Microchip Technology Inc. DS70000657H-page 145 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 8-5: DMAXSTBH: DMA CHANNEL X START ADDRESS REGISTER B (HIGH) U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 STB<23:16> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-8 Unimplemented: Read as ‘0’ bit 7-0 STB<23:16>: Secondary Start Address bits (source or destination) REGISTER 8-6: DMAXSTBL: DMA CHANNEL X START ADDRESS REGISTER B (LOW) R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 STB<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 STB<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 STB<15:0>: Secondary Start Address bits (source or destination) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 146  2011-2013 Microchip Technology Inc. REGISTER 8-7: DMAXPAD: DMA CHANNEL X PERIPHERAL ADDRESS 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 PAD<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 PAD<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 PAD<15:0>: Peripheral Address Register bits Note 1: If the channel is enabled (i.e., active), writes to this register may result in unpredictable behavior of the DMA channel and should be avoided. REGISTER 8-8: DMAXCNT: DMA CHANNEL X TRANSFER COUNT REGISTER(1) U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — CNT<13:8>(2) bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 CNT<7:0>(2) bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13-0 CNT<13:0>: DMA Transfer Count Register bits(2) Note 1: If the channel is enabled (i.e., active), writes to this register may result in unpredictable behavior of the DMA channel and should be avoided. 2: The number of DMA transfers = CNT<13:0> + 1.  2011-2013 Microchip Technology Inc. DS70000657H-page 147 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 8-9: DSADRH: DMA MOST RECENT RAM HIGH ADDRESS REGISTER U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 R-0 R-0 R-0 R-0 R-0 R-0 R-0 R-0 DSADR<23:16> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-8 Unimplemented: Read as ‘0’ bit 7-0 DSADR<23:16>: Most Recent DMA Address Accessed by DMA bits REGISTER 8-10: DSADRL: DMA MOST RECENT RAM LOW ADDRESS REGISTER R-0 R-0 R-0 R-0 R-0 R-0 R-0 R-0 DSADR<15:8> bit 15 bit 8 R-0 R-0 R-0 R-0 R-0 R-0 R-0 R-0 DSADR<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 DSADR<15:0>: Most Recent DMA Address Accessed by DMA bits dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 148  2011-2013 Microchip Technology Inc. REGISTER 8-11: DMAPWC: DMA PERIPHERAL WRITE COLLISION STATUS REGISTER U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 U-0 U-0 U-0 R-0 R-0 R-0 R-0 — — — — PWCOL3 PWCOL2 PWCOL1 PWCOL0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-4 Unimplemented: Read as ‘0’ bit 3 PWCOL3: DMA Channel 3 Peripheral Write Collision Flag bit 1 = Write collision is detected 0 = No write collision is detected bit 2 PWCOL2: DMA Channel 2 Peripheral Write Collision Flag bit 1 = Write collision is detected 0 = No write collision is detected bit 1 PWCOL1: DMA Channel 1 Peripheral Write Collision Flag bit 1 = Write collision is detected 0 = No write collision is detected bit 0 PWCOL0: DMA Channel 0 Peripheral Write Collision Flag bit 1 = Write collision is detected 0 = No write collision is detected  2011-2013 Microchip Technology Inc. DS70000657H-page 149 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 8-12: DMARQC: DMA REQUEST COLLISION STATUS REGISTER U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 U-0 U-0 U-0 R-0 R-0 R-0 R-0 — — — — RQCOL3 RQCOL2 RQCOL1 RQCOL0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-4 Unimplemented: Read as ‘0’ bit 3 RQCOL3: DMA Channel 3 Transfer Request Collision Flag bit 1 = User force and interrupt-based request collision is detected 0 = No request collision is detected bit 2 RQCOL2: DMA Channel 2 Transfer Request Collision Flag bit 1 = User force and interrupt-based request collision is detected 0 = No request collision is detected bit 1 RQCOL1: DMA Channel 1 Transfer Request Collision Flag bit 1 = User force and interrupt-based request collision is detected 0 = No request collision is detected bit 0 RQCOL0: DMA Channel 0 Transfer Request Collision Flag bit 1 = User force and interrupt-based request collision is detected 0 = No request collision is detected dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 150  2011-2013 Microchip Technology Inc. REGISTER 8-13: DMALCA: DMA LAST CHANNEL ACTIVE STATUS REGISTER U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 U-0 U-0 U-0 R-1 R-1 R-1 R-1 — — — — LSTCH<3:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-4 Unimplemented: Read as ‘0’ bit 3-0 LSTCH<3:0>: Last DMAC Channel Active Status bits 1111 = No DMA transfer has occurred since system Reset 1110 = Reserved • • • 0100 = Reserved 0011 = Last data transfer was handled by Channel 3 0010 = Last data transfer was handled by Channel 2 0001 = Last data transfer was handled by Channel 1 0000 = Last data transfer was handled by Channel 0  2011-2013 Microchip Technology Inc. DS70000657H-page 151 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 8-14: DMAPPS: DMA PING-PONG STATUS REGISTER U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 U-0 U-0 U-0 R-0 R-0 R-0 R-0 — — — — PPST3 PPST2 PPST1 PPST0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-4 Unimplemented: Read as ‘0’ bit 3 PPST3: DMA Channel 3 Ping-Pong Mode Status Flag bit 1 = DMASTB3 register is selected 0 = DMASTA3 register is selected bit 2 PPST2: DMA Channel 2 Ping-Pong Mode Status Flag bit 1 = DMASTB2 register is selected 0 = DMASTA2 register is selected bit 1 PPST1: DMA Channel 1 Ping-Pong Mode Status Flag bit 1 = DMASTB1 register is selected 0 = DMASTA1 register is selected bit 0 PPST0: DMA Channel 0 Ping-Pong Mode Status Flag bit 1 = DMASTB0 register is selected 0 = DMASTA0 register is selected dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 152  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 153 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 9.0 OSCILLATOR CONFIGURATION The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X oscillator system provides: • On-chip Phase-Locked Loop (PLL) to boost internal operating frequency on select internal and external oscillator sources • On-the-fly clock switching between various clock sources • Doze mode for system power savings • Fail-Safe Clock Monitor (FSCM) that detects clock failure and permits safe application recovery or shutdown • Configuration bits for clock source selection A simplified diagram of the oscillator system is shown in Figure 9-1. FIGURE 9-1: OSCILLATOR SYSTEM DIAGRAM Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Oscillator” (DS70580) in the “dsPIC33/ PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. Note 1: See Figure 9-2 for PLL details. 2: The term, FP, refers to the clock source for all peripherals, while FCY refers to the clock source for the CPU. Throughout this document, FCY and FP are used interchangeably, except in the case of Doze mode. FP and FCY will be different when Doze mode is used with a doze ratio of 1:2 or lower. XTPLL, HSPLL, ECPLL, XT, HS, EC FRCDIV<2:0> WDT, PWRT, FRCDIVN FRCDIV16 NOSC<2:0> FNOSC<2:0> Reset FRC Oscillator LPRC Oscillator DOZE<2:0> S3 S1 S2 S1/S3 S7 S6 FRC LPRC S0 S5 ÷ 16 Clock Switch 0b000 Clock Fail ÷ 2 TUN<5:0> PLL(1) FCY(2) FOSC FRCDIV DOZE FSCM POSCCLK FRCCLK OSC2 OSC1 Primary Oscillator POSCMD<1:0> FP(2) ÷ N ROSEL RODIV<3:0> REFCLKO POSCCLK RPn FOSC Reference Clock Generation FRCPLL, FPLLO COSC<2:0> dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 154  2011-2013 Microchip Technology Inc. 9.1 CPU Clocking System The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X family of devices provides six system clock options: • Fast RC (FRC) Oscillator • FRC Oscillator with Phase Locked Loop (PLL) • FRC Oscillator with Postscaler • Primary (XT, HS or EC) Oscillator • Primary Oscillator with PLL • Low-Power RC (LPRC) Oscillator Instruction execution speed or device operating frequency, FCY, is given by Equation 9-1. EQUATION 9-1: DEVICE OPERATING FREQUENCY Figure 9-2 is a block diagram of the PLL module. Equation 9-2 provides the relationship between input frequency (FIN) and output frequency (FPLLO). In clock modes S1 and S3, when the PLL output is selected, FOSC = FPLLO. Equation 9-3 provides the relationship between input frequency (FIN) and VCO frequency (FVCO). FIGURE 9-2: PLL BLOCK DIAGRAM EQUATION 9-2: FPLLO CALCULATION EQUATION 9-3: FVCO CALCULATION FCY = Fosc/2 ÷ N1 ÷ M PFD VCO ÷ N2 PLLPRE<4:0> PLLDIV<8:0> PLLPOST<1:0> 0.8 MHz < FPLLI(1) < 8.0 MHz 120 MHZ < FVCO(1) < 340 MHZ FPLLO(1)  120 MHz @ +125ºC FIN FPLLI FVCO FPLLO Note 1: This frequency range must be met at all times. FPLLO(1)  140 MHz @ +85ºC To FOSC clock multiplexer FPLLO FIN M N1  N2 --------------------      FIN   PLLDIV + 2   PLLPRE + 2  2  PLLPOST + 1 ---------------------------------------------------------------------------------------     = =  Where: N1 = PLLPRE + 2 N2 = 2 x (PLLPOST + 1) M = PLLDIV + 2 Fvco FIN M N1 ------      FIN   PLLDIV + 2   PLLPRE + 2 ------------------------------------     = =   2011-2013 Microchip Technology Inc. DS70000657H-page 155 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 9-1: CONFIGURATION BIT VALUES FOR CLOCK SELECTION 9.2 Oscillator Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 9.2.1 KEY RESOURCES • “Oscillator” (DS70580) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Oscillator Mode Oscillator Source POSCMD<1:0> FNOSC<2:0> See Notes Fast RC Oscillator with Divide-by-N (FRCDIVN) Internal xx 111 1, 2 Fast RC Oscillator with Divide-by-16 (FRCDIV16) Internal xx 110 1 Low-Power RC Oscillator (LPRC) Internal xx 101 1 Primary Oscillator (HS) with PLL (HSPLL) Primary 10 011 Primary Oscillator (XT) with PLL (XTPLL) Primary 01 011 Primary Oscillator (EC) with PLL (ECPLL) Primary 00 011 1 Primary Oscillator (HS) Primary 10 010 Primary Oscillator (XT) Primary 01 010 Primary Oscillator (EC) Primary 00 010 1 Fast RC Oscillator (FRC) with Divide-by-N and PLL (FRCPLL) Internal xx 001 1 Fast RC Oscillator (FRC) Internal xx 000 1 Note 1: OSC2 pin function is determined by the OSCIOFNC Configuration bit. 2: This is the default oscillator mode for an unprogrammed (erased) device. Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 156  2011-2013 Microchip Technology Inc. 9.3 Oscillator Control Registers REGISTER 9-1: OSCCON: OSCILLATOR CONTROL REGISTER(1) U-0 R-0 R-0 R-0 U-0 R/W-y R/W-y R/W-y — COSC2 COSC1 COSC0 — NOSC2(2) NOSC1(2) NOSC0(2) bit 15 bit 8 R/W-0 R/W-0 R-0 U-0 R/W-0 U-0 U-0 R/W-0 CLKLOCK IOLOCK LOCK — CF(3) — — OSWEN bit 7 bit 0 Legend: y = Value set from Configuration bits on POR R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 Unimplemented: Read as ‘0’ bit 14-12 COSC<2:0>: Current Oscillator Selection bits (read-only) 111 = Fast RC Oscillator (FRC) with Divide-by-n 110 = Fast RC Oscillator (FRC) with Divide-by-16 101 = Low-Power RC Oscillator (LPRC) 100 = Reserved 011 = Primary Oscillator (XT, HS, EC) with PLL 010 = Primary Oscillator (XT, HS, EC) 001 = Fast RC Oscillator (FRC) with Divide-by-N and PLL (FRCPLL) 000 = Fast RC Oscillator (FRC) bit 11 Unimplemented: Read as ‘0’ bit 10-8 NOSC<2:0>: New Oscillator Selection bits(2) 111 = Fast RC Oscillator (FRC) with Divide-by-n 110 = Fast RC Oscillator (FRC) with Divide-by-16 101 = Low-Power RC Oscillator (LPRC) 100 = Reserved 011 = Primary Oscillator (XT, HS, EC) with PLL 010 = Primary Oscillator (XT, HS, EC) 001 = Fast RC Oscillator (FRC) with Divide-by-N and PLL (FRCPLL) 000 = Fast RC Oscillator (FRC) bit 7 CLKLOCK: Clock Lock Enable bit 1 = If (FCKSM0 = 1), then clock and PLL configurations are locked; if (FCKSM0 = 0), then clock and PLL configurations may be modified 0 = Clock and PLL selections are not locked, configurations may be modified bit 6 IOLOCK: I/O Lock Enable bit 1 = I/O lock is active 0 = I/O lock is not active bit 5 LOCK: PLL Lock Status bit (read-only) 1 = Indicates that PLL is in lock or PLL start-up timer is satisfied 0 = Indicates that PLL is out of lock, start-up timer is in progress or PLL is disabled Note 1: Writes to this register require an unlock sequence. Refer to “Oscillator” (DS70580) in the “dsPIC33/ PIC24 Family Reference Manual” (available from the Microchip web site) for details. 2: Direct clock switches between any primary oscillator mode with PLL and FRCPLL mode are not permitted. This applies to clock switches in either direction. In these instances, the application must switch to FRC mode as a transitional clock source between the two PLL modes. 3: This bit should only be cleared in software. Setting the bit in software (= 1) will have the same effect as an actual oscillator failure and trigger an oscillator failure trap.  2011-2013 Microchip Technology Inc. DS70000657H-page 157 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 4 Unimplemented: Read as ‘0’ bit 3 CF: Clock Fail Detect bit(3) 1 = FSCM has detected clock failure 0 = FSCM has not detected clock failure bit 2-1 Unimplemented: Read as ‘0’ bit 0 OSWEN: Oscillator Switch Enable bit 1 = Requests oscillator switch to selection specified by the NOSC<2:0> bits 0 = Oscillator switch is complete REGISTER 9-1: OSCCON: OSCILLATOR CONTROL REGISTER(1) (CONTINUED) Note 1: Writes to this register require an unlock sequence. Refer to “Oscillator” (DS70580) in the “dsPIC33/ PIC24 Family Reference Manual” (available from the Microchip web site) for details. 2: Direct clock switches between any primary oscillator mode with PLL and FRCPLL mode are not permitted. This applies to clock switches in either direction. In these instances, the application must switch to FRC mode as a transitional clock source between the two PLL modes. 3: This bit should only be cleared in software. Setting the bit in software (= 1) will have the same effect as an actual oscillator failure and trigger an oscillator failure trap. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 158  2011-2013 Microchip Technology Inc. REGISTER 9-2: CLKDIV: CLOCK DIVISOR REGISTER R/W-0 R/W-0 R/W-1 R/W-1 R/W-0 R/W-0 R/W-0 R/W-0 ROI DOZE2(1) DOZE1(1) DOZE0(1) DOZEN(2,3) FRCDIV2 FRCDIV1 FRCDIV0 bit 15 bit 8 R/W-0 R/W-1 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 PLLPOST1 PLLPOST0 — PLLPRE4 PLLPRE3 PLLPRE2 PLLPRE1 PLLPRE0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 ROI: Recover on Interrupt bit 1 = Interrupts will clear the DOZEN bit 0 = Interrupts have no effect on the DOZEN bit bit 14-12 DOZE<2:0>: Processor Clock Reduction Select bits(1) 111 = FCY divided by 128 110 = FCY divided by 64 101 = FCY divided by 32 100 = FCY divided by 16 011 = FCY divided by 8 (default) 010 = FCY divided by 4 001 = FCY divided by 2 000 = FCY divided by 1 bit 11 DOZEN: Doze Mode Enable bit(2,3) 1 = DOZE<2:0> field specifies the ratio between the peripheral clocks and the processor clocks 0 = Processor clock and peripheral clock ratio is forced to 1:1 bit 10-8 FRCDIV<2:0>: Internal Fast RC Oscillator Postscaler bits 111 = FRC divided by 256 110 = FRC divided by 64 101 = FRC divided by 32 100 = FRC divided by 16 011 = FRC divided by 8 010 = FRC divided by 4 001 = FRC divided by 2 000 = FRC divided by 1 (default) bit 7-6 PLLPOST<1:0>: PLL VCO Output Divider Select bits (also denoted as ‘N2’, PLL postscaler) 11 = Output divided by 8 10 = Reserved 01 = Output divided by 4 (default) 00 = Output divided by 2 bit 5 Unimplemented: Read as ‘0’ Note 1: The DOZE<2:0> bits can only be written to when the DOZEN bit is clear. If DOZEN = 1, any writes to DOZE<2:0> are ignored. 2: This bit is cleared when the ROI bit is set and an interrupt occurs. 3: The DOZEN bit cannot be set if DOZE<2:0> = 000. If DOZE<2:0> = 000, any attempt by user software to set the DOZEN bit is ignored.  2011-2013 Microchip Technology Inc. DS70000657H-page 159 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 4-0 PLLPRE<4:0>: PLL Phase Detector Input Divider Select bits (also denoted as ‘N1’, PLL prescaler) 11111 = Input divided by 33 • • • 00001 = Input divided by 3 00000 = Input divided by 2 (default) REGISTER 9-2: CLKDIV: CLOCK DIVISOR REGISTER (CONTINUED) Note 1: The DOZE<2:0> bits can only be written to when the DOZEN bit is clear. If DOZEN = 1, any writes to DOZE<2:0> are ignored. 2: This bit is cleared when the ROI bit is set and an interrupt occurs. 3: The DOZEN bit cannot be set if DOZE<2:0> = 000. If DOZE<2:0> = 000, any attempt by user software to set the DOZEN bit is ignored. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 160  2011-2013 Microchip Technology Inc. REGISTER 9-3: PLLFBD: PLL FEEDBACK DIVISOR REGISTER U-0 U-0 U-0 U-0 U-0 U-0 U-0 R/W-0 — — — — — — — PLLDIV8 bit 15 bit 8 R/W-0 R/W-0 R/W-1 R/W-1 R/W-0 R/W-0 R/W-0 R/W-0 PLLDIV7 PLLDIV6 PLLDIV5 PLLDIV4 PLLDIV3 PLLDIV2 PLLDIV1 PLLDIV0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-9 Unimplemented: Read as ‘0’ bit 8-0 PLLDIV<8:0>: PLL Feedback Divisor bits (also denoted as ‘M’, PLL multiplier) 111111111 = 513 • • • 000110000 = 50 (default) • • • 000000010 = 4 000000001 = 3 000000000 = 2  2011-2013 Microchip Technology Inc. DS70000657H-page 161 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 9-4: OSCTUN: FRC OSCILLATOR TUNING REGISTER U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — TUN5 TUN4 TUN3 TUN2 TUN1 TUN0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-6 Unimplemented: Read as ‘0’ bit 5-0 TUN<5:0>: FRC Oscillator Tuning bits 011111 = Maximum frequency deviation of 1.453% (7.477 MHz) 011110 = Center frequency + 1.406% (7.474 MHz)    000001 = Center frequency + 0.047% (7.373 MHz) 000000 = Center frequency (7.37 MHz nominal) 111111 = Center frequency – 0.047% (7.367 MHz)    100001 = Center frequency – 1.453% (7.263 MHz) 100000 = Minimum frequency deviation of -1.5% (7.259 MHz) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 162  2011-2013 Microchip Technology Inc. REGISTER 9-5: REFOCON: REFERENCE OSCILLATOR 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 ROON — ROSSLP ROSEL RODIV3(1) RODIV2(1) RODIV1(1) RODIV0(1) bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 ROON: Reference Oscillator Output Enable bit 1 = Reference oscillator output is enabled on the REFCLK pin(2) 0 = Reference oscillator output is disabled bit 14 Unimplemented: Read as ‘0’ bit 13 ROSSLP: Reference Oscillator Run in Sleep bit 1 = Reference oscillator output continues to run in Sleep 0 = Reference oscillator output is disabled in Sleep bit 12 ROSEL: Reference Oscillator Source Select bit 1 = Oscillator crystal is used as the reference clock 0 = System clock is used as the reference clock bit 11-8 RODIV<3:0>: Reference Oscillator Divider bits(1) 1111 = Reference clock divided by 32,768 1110 = Reference clock divided by 16,384 1101 = Reference clock divided by 8,192 1100 = Reference clock divided by 4,096 1011 = Reference clock divided by 2,048 1010 = Reference clock divided by 1,024 1001 = Reference clock divided by 512 1000 = Reference clock divided by 256 0111 = Reference clock divided by 128 0110 = Reference clock divided by 64 0101 = Reference clock divided by 32 0100 = Reference clock divided by 16 0011 = Reference clock divided by 8 0010 = Reference clock divided by 4 0001 = Reference clock divided by 2 0000 = Reference clock bit 7-0 Unimplemented: Read as ‘0’ Note 1: The reference oscillator output must be disabled (ROON = 0) before writing to these bits. 2: This pin is remappable. See Section 11.4 “Peripheral Pin Select (PPS)” for more information.  2011-2013 Microchip Technology Inc. DS70000657H-page 163 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 10.0 POWER-SAVING FEATURES The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X devices provide the ability to manage power consumption by selectively managing clocking to the CPU and the peripherals. In general, a lower clock frequency and a reduction in the number of peripherals being clocked constitutes lower consumed power. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X devices can manage power consumption in four ways: • Clock Frequency • Instruction-Based Sleep and Idle modes • Software-Controlled Doze mode • Selective Peripheral Control in Software Combinations of these methods can be used to selectively tailor an application’s power consumption while still maintaining critical application features, such as timing-sensitive communications. 10.1 Clock Frequency and Clock Switching The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X devices allow a wide range of clock frequencies to be selected under application control. If the system clock configuration is not locked, users can choose low-power or highprecision oscillators by simply changing the NOSCx bits (OSCCON<10:8>). The process of changing a system clock during operation, as well as limitations to the process, are discussed in more detail in Section 9.0 “Oscillator Configuration”. 10.2 Instruction-Based Power-Saving Modes The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X devices have two special power-saving modes that are entered through the execution of a special PWRSAV instruction. Sleep mode stops clock operation and halts all code execution. Idle mode halts the CPU and code execution, but allows peripheral modules to continue operation. The assembler syntax of the PWRSAV instruction is shown in Example 10-1. Sleep and Idle modes can be exited as a result of an enabled interrupt, WDT time-out or a device Reset. When the device exits these modes, it is said to “wake-up”. EXAMPLE 10-1: PWRSAV INSTRUCTION SYNTAX Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Watchdog Timer and Power-Saving Modes” (DS70615) in the “dsPIC33/ PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. Note: SLEEP_MODE and IDLE_MODE are constants defined in the assembler include file for the selected device. PWRSAV #SLEEP_MODE ; Put the device into Sleep mode PWRSAV #IDLE_MODE ; Put the device into Idle mode dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 164  2011-2013 Microchip Technology Inc. 10.2.1 SLEEP MODE The following occurs in Sleep mode: • The system clock source is shut down. If an on-chip oscillator is used, it is turned off. • The device current consumption is reduced to a minimum, provided that no I/O pin is sourcing current. • The Fail-Safe Clock Monitor does not operate, since the system clock source is disabled. • The LPRC clock continues to run in Sleep mode if the WDT is enabled. • The WDT, if enabled, is automatically cleared prior to entering Sleep mode. • Some device features or peripherals can continue to operate. This includes items such as the Input Change Notification (ICN) on the I/O ports or peripherals that use an external clock input. • Any peripheral that requires the system clock source for its operation is disabled. The device wakes up from Sleep mode on any of these events: • Any interrupt source that is individually enabled • Any form of device Reset • A WDT time-out On wake-up from Sleep mode, the processor restarts with the same clock source that was active when Sleep mode was entered. For optimal power savings, the internal regulator and the Flash regulator can be configured to go into Standby when Sleep mode is entered by clearing the VREGS (RCON<8>) and VREGSF (RCON<11>) bits (default configuration). If the application requires a faster wake-up time, and can accept higher current requirements, the VREGS (RCON<8>) and VREGSF (RCON<11>) bits can be set to keep the internal regulator and the Flash regulator active during Sleep mode. 10.2.2 IDLE MODE The following occurs in Idle mode: • The CPU stops executing instructions. • The WDT is automatically cleared. • The system clock source remains active. By default, all peripheral modules continue to operate normally from the system clock source, but can also be selectively disabled (see Section 10.4 “Peripheral Module Disable”). • If the WDT or FSCM is enabled, the LPRC also remains active. The device wakes from Idle mode on any of these events: • Any interrupt that is individually enabled • Any device Reset • A WDT time-out On wake-up from Idle mode, the clock is reapplied to the CPU and instruction execution will begin (2-4 clock cycles later), starting with the instruction following the PWRSAV instruction or the first instruction in the Interrupt Service Routine (ISR). All peripherals also have the option to discontinue operation when Idle mode is entered to allow for increased power savings. This option is selectable in the control register of each peripheral; for example, the TSIDL bit in the Timer1 Control register (T1CON<13>). 10.2.3 INTERRUPTS COINCIDENT WITH POWER SAVE INSTRUCTIONS Any interrupt that coincides with the execution of a PWRSAV instruction is held off until entry into Sleep or Idle mode has completed. The device then wakes up from Sleep or Idle mode.  2011-2013 Microchip Technology Inc. DS70000657H-page 165 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 10.3 Doze Mode The preferred strategies for reducing power consumption are changing clock speed and invoking one of the powersaving modes. In some circumstances, this cannot be practical. For example, it may be necessary for an application to maintain uninterrupted synchronous communication, even while it is doing nothing else. Reducing system clock speed can introduce communication errors, while using a power-saving mode can stop communications completely. Doze mode is a simple and effective alternative method to reduce power consumption while the device is still executing code. In this mode, the system clock continues to operate from the same source and at the same speed. Peripheral modules continue to be clocked at the same speed, while the CPU clock speed is reduced. Synchronization between the two clock domains is maintained, allowing the peripherals to access the SFRs while the CPU executes code at a slower rate. Doze mode is enabled by setting the DOZEN bit (CLKDIV<11>). The ratio between peripheral and core clock speed is determined by the DOZE<2:0> bits (CLKDIV<14:12>). There are eight possible configurations, from 1:1 to 1:128, with 1:1 being the default setting. Programs can use Doze mode to selectively reduce power consumption in event-driven applications. This allows clock-sensitive functions, such as synchronous communications, to continue without interruption while the CPU Idles, waiting for something to invoke an interrupt routine. An automatic return to full-speed CPU operation on interrupts can be enabled by setting the ROI bit (CLKDIV<15>). By default, interrupt events have no effect on Doze mode operation. For example, suppose the device is operating at 20 MIPS and the ECAN™ module has been configured for 500 kbps, based on this device operating speed. If the device is placed in Doze mode with a clock frequency ratio of 1:4, the ECAN module continues to communicate at the required bit rate of 500 kbps, but the CPU now starts executing instructions at a frequency of 5 MIPS. 10.4 Peripheral Module Disable The Peripheral Module Disable (PMD) registers provide a method to disable a peripheral module by stopping all clock sources supplied to that module. When a peripheral is disabled using the appropriate PMD control bit, the peripheral is in a minimum power consumption state. The control and status registers associated with the peripheral are also disabled, so writes to those registers do not have effect and read values are invalid. A peripheral module is enabled only if both the associated bit in the PMD register is cleared and the peripheral is supported by the specific dsPIC® DSC variant. If the peripheral is present in the device, it is enabled in the PMD register by default. 10.5 Power-Saving Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 10.5.1 KEY RESOURCES • “Watchdog Timer and Power-Saving Modes” (DS70615) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: If a PMD bit is set, the corresponding module is disabled after a delay of one instruction cycle. Similarly, if a PMD bit is cleared, the corresponding module is enabled after a delay of one instruction cycle (assuming the module control registers are already configured to enable module operation). Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 166  2011-2013 Microchip Technology Inc. REGISTER 10-1: PMD1: PERIPHERAL MODULE DISABLE CONTROL REGISTER 1 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 U-0 T5MD T4MD T3MD T2MD T1MD QEI1MD(1) PWMMD(1) — bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 U-0 R/W-0 R/W-0 I2C1MD U2MD U1MD SPI2MD SPI1MD — C1MD(2) AD1MD bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 T5MD: Timer5 Module Disable bit 1 = Timer5 module is disabled 0 = Timer5 module is enabled bit 14 T4MD: Timer4 Module Disable bit 1 = Timer4 module is disabled 0 = Timer4 module is enabled bit 13 T3MD: Timer3 Module Disable bit 1 = Timer3 module is disabled 0 = Timer3 module is enabled bit 12 T2MD: Timer2 Module Disable bit 1 = Timer2 module is disabled 0 = Timer2 module is enabled bit 11 T1MD: Timer1 Module Disable bit 1 = Timer1 module is disabled 0 = Timer1 module is enabled bit 10 QEI1MD: QEI1 Module Disable bit(1) 1 = QEI1 module is disabled 0 = QEI1 module is enabled bit 9 PWMMD: PWM Module Disable bit(1) 1 = PWM module is disabled 0 = PWM module is enabled bit 8 Unimplemented: Read as ‘0’ bit 7 I2C1MD: I2C1 Module Disable bit 1 = I2C1 module is disabled 0 = I2C1 module is enabled bit 6 U2MD: UART2 Module Disable bit 1 = UART2 module is disabled 0 = UART2 module is enabled bit 5 U1MD: UART1 Module Disable bit 1 = UART1 module is disabled 0 = UART1 module is enabled bit 4 SPI2MD: SPI2 Module Disable bit 1 = SPI2 module is disabled 0 = SPI2 module is enabled Note 1: This bit is available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. 2: This bit is available on dsPIC33EPXXXGP50X and dsPIC33EPXXXMC50X devices only.  2011-2013 Microchip Technology Inc. DS70000657H-page 167 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 3 SPI1MD: SPI1 Module Disable bit 1 = SPI1 module is disabled 0 = SPI1 module is enabled bit 2 Unimplemented: Read as ‘0’ bit 1 C1MD: ECAN1 Module Disable bit(2) 1 = ECAN1 module is disabled 0 = ECAN1 module is enabled bit 0 AD1MD: ADC1 Module Disable bit 1 = ADC1 module is disabled 0 = ADC1 module is enabled REGISTER 10-1: PMD1: PERIPHERAL MODULE DISABLE CONTROL REGISTER 1 (CONTINUED) Note 1: This bit is available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. 2: This bit is available on dsPIC33EPXXXGP50X and dsPIC33EPXXXMC50X devices only. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 168  2011-2013 Microchip Technology Inc. REGISTER 10-2: PMD2: PERIPHERAL MODULE DISABLE CONTROL REGISTER 2 U-0 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 — — — — IC4MD IC3MD IC2MD IC1MD bit 15 bit 8 U-0 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 — — — — OC4MD OC3MD OC2MD OC1MD bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-12 Unimplemented: Read as ‘0’ bit 11 IC4MD: Input Capture 4 Module Disable bit 1 = Input Capture 4 module is disabled 0 = Input Capture 4 module is enabled bit 10 IC3MD: Input Capture 3 Module Disable bit 1 = Input Capture 3 module is disabled 0 = Input Capture 3 module is enabled bit 9 IC2MD: Input Capture 2 Module Disable bit 1 = Input Capture 2 module is disabled 0 = Input Capture 2 module is enabled bit 8 IC1MD: Input Capture 1 Module Disable bit 1 = Input Capture 1 module is disabled 0 = Input Capture 1 module is enabled bit 7-4 Unimplemented: Read as ‘0’ bit 3 OC4MD: Output Compare 4 Module Disable bit 1 = Output Compare 4 module is disabled 0 = Output Compare 4 module is enabled bit 2 OC3MD: Output Compare 3 Module Disable bit 1 = Output Compare 3 module is disabled 0 = Output Compare 3 module is enabled bit 1 OC2MD: Output Compare 2 Module Disable bit 1 = Output Compare 2 module is disabled 0 = Output Compare 2 module is enabled bit 0 OC1MD: Output Compare 1 Module Disable bit 1 = Output Compare 1 module is disabled 0 = Output Compare 1 module is enabled  2011-2013 Microchip Technology Inc. DS70000657H-page 169 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 10-3: PMD3: PERIPHERAL MODULE DISABLE CONTROL REGISTER 3 REGISTER 10-4: PMD4: PERIPHERAL MODULE DISABLE CONTROL REGISTER 4 U-0 U-0 U-0 U-0 U-0 R/W-0 U-0 U-0 — — — — — CMPMD — — bit 15 bit 8 R/W-0 U-0 U-0 U-0 U-0 U-0 R/W-0 U-0 CRCMD — — — — — I2C2MD — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-11 Unimplemented: Read as ‘0’ bit 10 CMPMD: Comparator Module Disable bit 1 = Comparator module is disabled 0 = Comparator module is enabled bit 9-8 Unimplemented: Read as ‘0’ bit 7 CRCMD: CRC Module Disable bit 1 = CRC module is disabled 0 = CRC module is enabled bit 6-2 Unimplemented: Read as ‘0’ bit 1 I2C2MD: I2C2 Module Disable bit 1 = I2C2 module is disabled 0 = I2C2 module is enabled bit 0 Unimplemented: Read as ‘0’ U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 U-0 U-0 U-0 R/W-0 R/W-0 U-0 U-0 — — — — REFOMD CTMUMD — — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-4 Unimplemented: Read as ‘0’ bit 3 REFOMD: Reference Clock Module Disable bit 1 = Reference clock module is disabled 0 = Reference clock module is enabled bit 2 CTMUMD: CTMU Module Disable bit 1 = CTMU module is disabled 0 = CTMU module is enabled bit 1-0 Unimplemented: Read as ‘0’ dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 170  2011-2013 Microchip Technology Inc. REGISTER 10-5: PMD6: PERIPHERAL MODULE DISABLE CONTROL REGISTER 6 U-0 U-0 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 — — — — — PWM3MD(1) PWM2MD(1) PWM1MD(1) bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-11 Unimplemented: Read as ‘0’ bit 10 PWM3MD: PWM3 Module Disable bit(1) 1 = PWM3 module is disabled 0 = PWM3 module is enabled bit 9 PWM2MD: PWM2 Module Disable bit(1) 1 = PWM2 module is disabled 0 = PWM2 module is enabled bit 8 PWM1MD: PWM1 Module Disable bit(1) 1 = PWM1 module is disabled 0 = PWM1 module is enabled bit 7-0 Unimplemented: Read as ‘0’ Note 1: This bit is available on dsPIC33EPXXXMC50X/20X and PIC24EPXXXMC20X devices only.  2011-2013 Microchip Technology Inc. DS70000657H-page 171 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 10-6: PMD7: PERIPHERAL MODULE DISABLE CONTROL REGISTER 7 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 U-0 U-0 R/W-0 R/W-0 U-0 U-0 U-0 — — — DMA0MD(1) PTGMD — — — DMA1MD(1) DMA2MD(1) DMA3MD(1) bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-5 Unimplemented: Read as ‘0’ bit 4 DMA0MD: DMA0 Module Disable bit(1) 1 = DMA0 module is disabled 0 = DMA0 module is enabled DMA1MD: DMA1 Module Disable bit(1) 1 = DMA1 module is disabled 0 = DMA1 module is enabled DMA2MD: DMA2 Module Disable bit(1) 1 = DMA2 module is disabled 0 = DMA2 module is enabled DMA3MD: DMA3 Module Disable bit(1) 1 = DMA3 module is disabled 0 = DMA3 module is enabled bit 3 PTGMD: PTG Module Disable bit 1 = PTG module is disabled 0 = PTG module is enabled bit 2-0 Unimplemented: Read as ‘0’ Note 1: This single bit enables and disables all four DMA channels. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 172  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 173 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 11.0 I/O PORTS Many of the device pins are shared among the peripherals and the parallel I/O ports. All I/O input ports feature Schmitt Trigger inputs for improved noise immunity. 11.1 Parallel I/O (PIO) Ports Generally, a parallel I/O port that shares a pin with a peripheral is subservient to the peripheral. The peripheral’s output buffer data and control signals are provided to a pair of multiplexers. The multiplexers select whether the peripheral or the associated port has ownership of the output data and control signals of the I/O pin. The logic also prevents “loop through,” in which a port’s digital output can drive the input of a peripheral that shares the same pin. Figure 11-1 illustrates how ports are shared with other peripherals and the associated I/O pin to which they are connected. When a peripheral is enabled and the peripheral is actively driving an associated pin, the use of the pin as a general purpose output pin is disabled. The I/O pin can be read, but the output driver for the parallel port bit is disabled. If a peripheral is enabled, but the peripheral is not actively driving a pin, that pin can be driven by a port. All port pins have eight registers directly associated with their operation as digital I/O. The Data Direction register (TRISx) determines whether the pin is an input or an output. If the data direction bit is a ‘1’, then the pin is an input. All port pins are defined as inputs after a Reset. Reads from the Latch register (LATx) read the latch. Writes to the Latch write the latch. Reads from the port (PORTx) read the port pins, while writes to the port pins write the latch. Any bit and its associated data and control registers that are not valid for a particular device is disabled. This means the corresponding LATx and TRISx registers and the port pin are read as zeros. When a pin is shared with another peripheral or function that is defined as an input only, it is nevertheless regarded as a dedicated port because there is no other competing source of outputs. FIGURE 11-1: BLOCK DIAGRAM OF A TYPICAL SHARED PORT STRUCTURE Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “I/O Ports” (DS70598) in the “dsPIC33/ PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. D Q CK WR LAT + TRIS Latch I/O Pin WR Port Data Bus D Q CK Data Latch Read Port Read TRIS 1 0 1 0 WR TRIS Peripheral Output Data Output Enable Peripheral Input Data I/O Peripheral Module Peripheral Output Enable PIO Module Output Multiplexers Output Data Input Data Peripheral Module Enable Read LAT dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 174  2011-2013 Microchip Technology Inc. 11.1.1 OPEN-DRAIN CONFIGURATION In addition to the PORTx, LATx and TRISx registers for data control, port pins can also be individually configured for either digital or open-drain output. This is controlled by the Open-Drain Control register, ODCx, associated with each port. Setting any of the bits configures the corresponding pin to act as an open-drain output. The open-drain feature allows the generation of outputs other than VDD by using external pull-up resistors. The maximum open-drain voltage allowed on any pin is the same as the maximum VIH specification for that particular pin. See the “Pin Diagrams” section for the available 5V tolerant pins and Table 30-11 for the maximum VIH specification for each pin. 11.2 Configuring Analog and Digital Port Pins The ANSELx register controls the operation of the analog port pins. The port pins that are to function as analog inputs or outputs must have their corresponding ANSELx and TRISx bits set. In order to use port pins for I/O functionality with digital modules, such as Timers, UARTs, etc., the corresponding ANSELx bit must be cleared. The ANSELx register has a default value of 0xFFFF; therefore, all pins that share analog functions are analog (not digital) by default. Pins with analog functions affected by the ANSELx registers are listed with a buffer type of analog in the Pinout I/O Descriptions (see Table 1-1). If the TRISx bit is cleared (output) while the ANSELx bit is set, the digital output level (VOH or VOL) is converted by an analog peripheral, such as the ADC module or comparator module. When the PORTx register is read, all pins configured as analog input channels are read as cleared (a low level). Pins configured as digital inputs do not convert an analog input. Analog levels on any pin defined as a digital input (including the ANx pins) can cause the input buffer to consume current that exceeds the device specifications. 11.2.1 I/O PORT WRITE/READ TIMING 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, as shown in Example 11-1. 11.3 Input Change Notification (ICN) The Input Change Notification function of the I/O ports allows devices to generate interrupt requests to the processor in response to a Change-of-State (COS) on selected input pins. This feature can detect input Change-of-States even in Sleep mode, when the clocks are disabled. Every I/O port pin can be selected (enabled) for generating an interrupt request on a Change-of-State. Three control registers are associated with the Change Notification (CN) functionality of each I/O port. The CNENx registers contain the CN interrupt enable control bits for each of the input pins. Setting any of these bits enables a CN interrupt for the corresponding pins. Each I/O pin also has a weak pull-up and a weak pull-down connected to it. The pull-ups and pulldowns act as a current source or sink source connected to the pin and eliminate the need for external resistors when push button, or keypad devices are connected. The pull-ups and pull-downs are enabled separately, using the CNPUx and the CNPDx registers, which contain the control bits for each of the pins. Setting any of the control bits enables the weak pull-ups and/or pull-downs for the corresponding pins. EXAMPLE 11-1: PORT WRITE/READ EXAMPLE Note: Pull-ups and pull-downs on Change Notification pins should always be disabled when the port pin is configured as a digital output. MOV 0xFF00, W0 ; Configure PORTB<15:8> ; as inputs MOV W0, TRISB ; and PORTB<7:0> ; as outputs NOP ; Delay 1 cycle BTSS PORTB, #13 ; Next Instruction  2011-2013 Microchip Technology Inc. DS70000657H-page 175 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 11.4 Peripheral Pin Select (PPS) 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 challenge is even greater on low pin count devices. In an application where more than one peripheral needs to be assigned to a single pin, inconvenient workarounds in application code, or a complete redesign, may be the only option. Peripheral Pin Select configuration provides an alternative to these choices by enabling peripheral set selection and their placement on a wide range of I/O pins. By increasing the pinout options available on a particular device, users can better tailor the device to their entire application, rather than trimming the application to fit the device. The Peripheral Pin Select configuration feature operates over a fixed subset of digital I/O pins. Users may independently map the input and/or output of most digital peripherals to any one of these I/O pins. Hardware safeguards are included that prevent accidental or spurious changes to the peripheral mapping once it has been established. 11.4.1 AVAILABLE PINS The number of available pins is dependent on the particular device and its pin count. Pins that support the Peripheral Pin Select feature include the label, “RPn” or “RPIn”, in their full pin designation, where “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 support remappable input functions only. 11.4.2 AVAILABLE PERIPHERALS The peripherals managed by the Peripheral Pin Select 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) and interrupt-on-change inputs. 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™ and the PWM. A similar requirement excludes all modules with analog inputs, such as the ADC Converter. A key difference between remappable and nonremappable peripherals is that remappable peripherals are not associated with a default I/O pin. The peripheral must always be assigned to a specific I/O pin before it can be used. In contrast, non-remappable peripherals are always available on a default pin, assuming that the peripheral is active and not conflicting with another peripheral. 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. 11.4.3 CONTROLLING PERIPHERAL PIN SELECT Peripheral Pin Select features are controlled through two sets of SFRs: one to map peripheral inputs and one to map outputs. Because they are separately controlled, a particular peripheral’s input and output (if the peripheral has both) can be placed on any selectable function pin without constraint. The association of a peripheral to a peripheralselectable pin is handled in two different ways, depending on whether an input or output is being mapped. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 176  2011-2013 Microchip Technology Inc. 11.4.4 INPUT MAPPING The inputs of the Peripheral Pin Select options are mapped on the basis of the peripheral. That is, a control register associated with a peripheral dictates the pin it will be mapped to. The RPINRx registers are used to configure peripheral input mapping (see Register 11-1 through Register 11-17). Each register contains sets of 7-bit fields, with each set associated with one of the remappable peripherals. Programming a given peripheral’s bit field with an appropriate 7-bit value maps the RPn pin with the corresponding value to that peripheral. For any given device, the valid range of values for any bit field corresponds to the maximum number of Peripheral Pin Selections supported by the device. For example, Figure 11-2 illustrates remappable pin selection for the U1RX input. FIGURE 11-2: REMAPPABLE INPUT FOR U1RX 11.4.4.1 Virtual Connections dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X devices support virtual (internal) connections to the output of the op amp/ comparator module (see Figure 25-1 in Section 25.0 “Op Amp/Comparator Module”), and the PTG module (see Section 24.0 “Peripheral Trigger Generator (PTG) Module”). In addition, dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices support virtual connections to the filtered QEI module inputs: FINDX1, FHOME1, FINDX2 and FHOME2 (see Figure 17-1 in Section 17.0 “Quadrature Encoder Interface (QEI) Module (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X Devices Only)”. Virtual connections provide a simple way of interperipheral connection without utilizing a physical pin. For example, by setting the FLT1R<6:0> bits of the RPINR12 register to the value of ‘b0000001, the output of the analog comparator, C1OUT, will be connected to the PWM Fault 1 input, which allows the analog comparator to trigger PWM Faults without the use of an actual physical pin on the device. Virtual connection to the QEI module allows peripherals to be connected to the QEI digital filter input. To utilize this filter, the QEI module must be enabled and its inputs must be connected to a physical RPn pin. Example 11-2 illustrates how the input capture module can be connected to the QEI digital filter. EXAMPLE 11-2: CONNECTING IC1 TO THE HOME1 QEI1 DIGITAL FILTER INPUT ON PIN 43 OF THE dsPIC33EPXXXMC206 DEVICE RP0 RP1 RP3 0 1 2 U1RX Input U1RXR<6:0> to Peripheral RPn n Note: For input only, Peripheral Pin Select functionality does not have priority over TRISx settings. Therefore, when configuring an RPn pin for input, the corresponding bit in the TRISx register must also be configured for input (set to ‘1’). RPINR15 = 0x2500; /* Connect the QEI1 HOME1 input to RP37 (pin 43) */ RPINR7 = 0x009; /* Connect the IC1 input to the digital filter on the FHOME1 input */ QEI1IOC = 0x4000; /* Enable the QEI digital filter */ QEI1CON = 0x8000; /* Enable the QEI module */  2011-2013 Microchip Technology Inc. DS70000657H-page 177 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 11-1: SELECTABLE INPUT SOURCES (MAPS INPUT TO FUNCTION) Input Name(1) Function Name Register Configuration Bits External Interrupt 1 INT1 RPINR0 INT1R<6:0> External Interrupt 2 INT2 RPINR1 INT2R<6:0> Timer2 External Clock T2CK RPINR3 T2CKR<6:0> Input Capture 1 IC1 RPINR7 IC1R<6:0> Input Capture 2 IC2 RPINR7 IC2R<6:0> Input Capture 3 IC3 RPINR8 IC3R<6:0> Input Capture 4 IC4 RPINR8 IC4R<6:0> Output Compare Fault A OCFA RPINR11 OCFAR<6:0> PWM Fault 1(3) FLT1 RPINR12 FLT1R<6:0> PWM Fault 2(3) FLT2 RPINR12 FLT2R<6:0> QEI1 Phase A(3) QEA1 RPINR14 QEA1R<6:0> QEI1 Phase B(3) QEB1 RPINR14 QEB1R<6:0> QEI1 Index(3) INDX1 RPINR15 INDX1R<6:0> QEI1 Home(3) HOME1 RPINR15 HOM1R<6:0> UART1 Receive U1RX RPINR18 U1RXR<6:0> UART2 Receive U2RX RPINR19 U2RXR<6:0> SPI2 Data Input SDI2 RPINR22 SDI2R<6:0> SPI2 Clock Input SCK2 RPINR22 SCK2R<6:0> SPI2 Slave Select SS2 RPINR23 SS2R<6:0> CAN1 Receive(2) C1RX RPINR26 C1RXR<6:0> PWM Sync Input 1(3) SYNCI1 RPINR37 SYNCI1R<6:0> PWM Dead-Time Compensation 1(3) DTCMP1 RPINR38 DTCMP1R<6:0> PWM Dead-Time Compensation 2(3) DTCMP2 RPINR39 DTCMP2R<6:0> PWM Dead-Time Compensation 3(3) DTCMP3 RPINR39 DTCMP3R<6:0> Note 1: Unless otherwise noted, all inputs use the Schmitt Trigger input buffers. 2: This input source is available on dsPIC33EPXXXGP/MC50X devices only. 3: This input source is available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 178  2011-2013 Microchip Technology Inc. TABLE 11-2: INPUT PIN SELECTION FOR SELECTABLE INPUT SOURCES Peripheral Pin Select Input Register Value Input/ Output Pin Assignment Peripheral Pin Select Input Register Value Input/ Output Pin Assignment 000 0000 I VSS 010 1101 I RPI45 000 0001 I C1OUT(1) 010 1110 I RPI46 000 0010 I C2OUT(1) 010 1111 I RPI47 000 0011 I C3OUT(1) 011 0000 — — 000 0100 I C4OUT(1) 011 0001 — — 000 0101 — — 011 0010 — — 000 0110 I PTGO30(1) 011 0011 I RPI51 000 0111 I PTGO31(1) 011 0100 I RPI52 000 1000 I FINDX1(1,2) 011 0101 I RPI53 000 1001 I FHOME1(1,2) 011 0110 I/O RP54 000 1010 — — 011 0111 I/O RP55 000 1011 — — 011 1000 I/O RP56 000 1100 — — 011 1001 I/O RP57 000 1101 — — 011 1010 I RPI58 000 1110 — — 011 1011 — — 000 1111 — — 011 1100 — — 001 0000 — — 011 1101 — — 001 0001 — — 011 1110 — — 001 0010 — — 011 1111 — — 001 0011 — — 100 0000 — — 001 0100 I/O RP20 100 0001 — — 001 0101 — — 100 0010 — — 001 0110 — — 100 0011 — — 001 0111 — — 100 0100 — — 001 1000 I RPI24 100 0101 — — 001 1001 I RPI25 100 0110 — — 001 1010 — — 100 0111 — — 001 1011 I RPI27 100 1000 — — 001 1100 I RPI28 100 1001 — — 001 1101 — — 100 1010 — — 001 1110 — — 100 1011 — — 001 1111 — — 100 1100 — — 010 0000 I RPI32 100 1101 — — 010 0001 I RPI33 100 1110 — — 010 0010 I RPI34 100 1111 — — 010 0011 I/O RP35 101 0000 — — 010 0100 I/O RP36 101 0001 — — 010 0101 I/O RP37 101 0010 — — 010 0110 I/O RP38 101 0011 — — 010 0111 I/O RP39 101 0100 — — Legend: Shaded rows indicate PPS Input register values that are unimplemented. Note 1: See Section 11.4.4.1 “Virtual Connections” for more information on selecting this pin assignment. 2: These inputs are available on dsPIC33EPXXXGP/MC50X devices only.  2011-2013 Microchip Technology Inc. DS70000657H-page 179 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 010 1000 I/O RP40 101 0101 — — 010 1001 I/O RP41 101 0110 — — 010 1010 I/O RP42 101 0111 — — 010 1011 I/O RP43 101 1000 — — 010 1100 I RPI44 101 1001 — — 101 1010 — — 110 1101 — — 101 1011 — — 110 1110 — — 101 1100 — — 110 1111 — — 101 1101 — — 111 0000 — — 101 1110 I RPI94 111 0001 — — 101 1111 I RPI95 111 0010 — — 110 0000 I RPI96 111 0011 — — 110 0001 I/O RP97 111 0100 — — 110 0010 — — 111 0101 — — 110 0011 — — 111 0110 I/O RP118 110 0100 — — 111 0111 I RPI119 110 0101 — — 111 1000 I/O RP120 110 0110 — — 111 1001 I RPI121 110 0111 — — 111 1010 — — 110 1000 — — 111 1011 — — 110 1001 — — 111 1100 — — 110 1010 — — 111 1101 — — 110 1011 — — 111 1110 — — 110 1100 — — 111 1111 — — TABLE 11-2: INPUT PIN SELECTION FOR SELECTABLE INPUT SOURCES (CONTINUED) Peripheral Pin Select Input Register Value Input/ Output Pin Assignment Peripheral Pin Select Input Register Value Input/ Output Pin Assignment Legend: Shaded rows indicate PPS Input register values that are unimplemented. Note 1: See Section 11.4.4.1 “Virtual Connections” for more information on selecting this pin assignment. 2: These inputs are available on dsPIC33EPXXXGP/MC50X devices only. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 180  2011-2013 Microchip Technology Inc. 11.4.4.2 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 register associated with a particular pin dictates the peripheral output to be mapped. The RPORx registers are used to control output mapping. Like the RPINRx registers, each register contains sets of 6-bit fields, with each set associated with one RPn pin (see Register 11-18 through Register 11-27). The value of the bit field corresponds to one of the peripherals and that peripheral’s output is mapped to the pin (see Table 11-3 and Figure 11-3). A null output is associated with the output register Reset value of ‘0’. This is done to ensure that remappable outputs remain disconnected from all output pins by default. FIGURE 11-3: MULTIPLEXING REMAPPABLE OUTPUT FOR RPn 11.4.4.3 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 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-toone 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. RPxR<5:0> 0 49 1 Default U1TX Output SDO2 Output 2 REFCLKO Output 48 QEI1CCMP Output Output Data RPn TABLE 11-3: OUTPUT SELECTION FOR REMAPPABLE PINS (RPn) Function RPxR<5:0> Output Name Default PORT 000000 RPn tied to Default Pin U1TX 000001 RPn tied to UART1 Transmit U2TX 000011 RPn tied to UART2 Transmit SDO2 001000 RPn tied to SPI2 Data Output SCK2 001001 RPn tied to SPI2 Clock Output SS2 001010 RPn tied to SPI2 Slave Select C1TX(2) 001110 RPn tied to CAN1 Transmit OC1 010000 RPn tied to Output Compare 1 Output OC2 010001 RPn tied to Output Compare 2 Output OC3 010010 RPn tied to Output Compare 3 Output OC4 010011 RPn tied to Output Compare 4 Output C1OUT 011000 RPn tied to Comparator Output 1 C2OUT 011001 RPn tied to Comparator Output 2 C3OUT 011010 RPn tied to Comparator Output 3 SYNCO1(1) 101101 RPn tied to PWM Primary Time Base Sync Output QEI1CCMP(1) 101111 RPn tied to QEI 1 Counter Comparator Output REFCLKO 110001 RPn tied to Reference Clock Output C4OUT 110010 RPn tied to Comparator Output 4 Note 1: This function is available in dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. 2: This function is available in dsPIC33EPXXXGP/MC50X devices only.  2011-2013 Microchip Technology Inc. DS70000657H-page 181 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 11.5 I/O Helpful Tips 1. In some cases, certain pins, as defined in Table 30-11, under “Injection Current”, have internal protection diodes to VDD and VSS. The term, “Injection Current”, is also referred to as “Clamp Current”. On designated pins, with sufficient external current-limiting precautions by the user, I/O pin input voltages are allowed to be greater or less than the data sheet absolute maximum ratings, with respect to the VSS and VDD supplies. Note that when the user application forward biases either of the high or low side internal input clamp diodes, that the resulting current being injected into the device, that is clamped internally by the VDD and VSS power rails, may affect the ADC accuracy by four to six counts. 2. I/O pins that are shared with any analog input pin (i.e., ANx) are always analog pins by default after any Reset. Consequently, configuring a pin as an analog input pin automatically disables the digital input pin buffer and any attempt to read the digital input level by reading PORTx or LATx will always return a ‘0’, regardless of the digital logic level on the pin. To use a pin as a digital I/O pin on a shared ANx pin, the user application needs to configure the Analog Pin Configuration registers in the I/O ports module (i.e., ANSELx) by setting the appropriate bit that corresponds to that I/O port pin to a ‘0’. 3. Most I/O pins have multiple functions. Referring to the device pin diagrams in this data sheet, the priorities of the functions allocated to any pins are indicated by reading the pin name from left-to-right. The left most function name takes precedence over any function to its right in the naming convention. For example: AN16/T2CK/T7CK/RC1. This indicates that AN16 is the highest priority in this example and will supersede all other functions to its right in the list. Those other functions to its right, even if enabled, would not work as long as any other function to its left was enabled. This rule applies to all of the functions listed for a given pin. 4. Each pin has an internal weak pull-up resistor and pull-down resistor that can be configured using the CNPUx and CNPDx registers, respectively. These resistors eliminate the need for external resistors in certain applications. The internal pull-up is up to ~(VDD – 0.8), not VDD. This value is still above the minimum VIH of CMOS and TTL devices. 5. When driving LEDs directly, the I/O pin can source or sink more current than what is specified in the VOH/IOH and VOL/IOL DC characteristic specification. The respective IOH and IOL current rating only applies to maintaining the corresponding output at or above the VOH, and at or below the VOL levels. However, for LEDs, unlike digital inputs of an externally connected device, they are not governed by the same minimum VIH/VIL levels. An I/O pin output can safely sink or source any current less than that listed in the absolute maximum rating section of this data sheet. For example: VOH = 2.4V @ IOH = -8 mA and VDD = 3.3V The maximum output current sourced by any 8 mA I/O pin = 12 mA. LED source current < 12 mA is technically permitted. Refer to the VOH/IOH graphs in Section 30.0 “Electrical Characteristics” for additional information. 6. The Peripheral Pin Select (PPS) pin mapping rules are as follows: a) Only one “output” function can be active on a given pin at any time, regardless if it is a dedicated or remappable function (one pin, one output). b) It is possible to assign a “remappable output” function to multiple pins and externally short or tie them together for increased current drive. c) If any “dedicated output” function is enabled on a pin, it will take precedence over any remappable “output” function. d) If any “dedicated digital” (input or output) function is enabled on a pin, any number of “input” remappable functions can be mapped to the same pin. e) If any “dedicated analog” function(s) are enabled on a given pin, “digital input(s)” of any kind will all be disabled, although a single “digital output”, at the user’s cautionary discretion, can be enabled and active as long as there is no signal contention with an external analog input signal. For example, it is possible for the ADC to convert the digital output logic level, or to toggle a digital output on a comparator or ADC input provided there is no external analog input, such as for a built-in self-test. f) Any number of “input” remappable functions can be mapped to the same pin(s) at the same time, including to any pin with a single output from either a dedicated or remappable “output”. Note: Although it is not possible to use a digital input pin when its analog function is enabled, it is possible to use the digital I/O output function, TRISx = 0x0, while the analog function is also enabled. However, this is not recommended, particularly if the analog input is connected to an external analog voltage source, which would create signal contention between the analog signal and the output pin driver. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 182  2011-2013 Microchip Technology Inc. g) The TRISx registers control only the digital I/O output buffer. Any other dedicated or remappable active “output” will automatically override the TRIS setting. The TRISx register does not control the digital logic “input” buffer. Remappable digital “inputs” do not automatically override TRIS settings, which means that the TRISx bit must be set to input for pins with only remappable input function(s) assigned h) All analog pins are enabled by default after any Reset and the corresponding digital input buffer on the pin has been disabled. Only the Analog Pin Select registers control the digital input buffer, not the TRISx register. The user must disable the analog function on a pin using the Analog Pin Select registers in order to use any “digital input(s)” on a corresponding pin, no exceptions. 11.6 I/O Ports Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 11.6.1 KEY RESOURCES • “I/O Ports” (DS70598) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464  2011-2013 Microchip Technology Inc. DS70000657H-page 183 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 11.7 Peripheral Pin Select Registers REGISTER 11-1: RPINR0: PERIPHERAL PIN SELECT INPUT REGISTER 0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — INT1R<6:0> bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 Unimplemented: Read as ‘0’ bit 14-8 INT1R<6:0>: Assign External Interrupt 1 (INT1) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS bit 7-0 Unimplemented: Read as ‘0’ dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 184  2011-2013 Microchip Technology Inc. REGISTER 11-2: RPINR1: PERIPHERAL PIN SELECT INPUT REGISTER 1 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — INT2R<6:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-7 Unimplemented: Read as ‘0’ bit 6-0 INT2R<6:0>: Assign External Interrupt 2 (INT2) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS REGISTER 11-3: RPINR3: PERIPHERAL PIN SELECT INPUT REGISTER 3 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — T2CKR<6:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-7 Unimplemented: Read as ‘0’ bit 6-0 T2CKR<6:0>: Assign Timer2 External Clock (T2CK) to the Corresponding RPn pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS  2011-2013 Microchip Technology Inc. DS70000657H-page 185 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 11-4: RPINR7: PERIPHERAL PIN SELECT INPUT REGISTER 7 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — IC2R<6:0> bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — IC1R<6:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 Unimplemented: Read as ‘0’ bit 14-8 IC2R<6:0>: Assign Input Capture 2 (IC2) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS bit 7 Unimplemented: Read as ‘0’ bit 6-0 IC1R<6:0>: Assign Input Capture 1 (IC1) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 186  2011-2013 Microchip Technology Inc. REGISTER 11-5: RPINR8: PERIPHERAL PIN SELECT INPUT REGISTER 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — IC4R<6:0> bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — IC3R<6:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 Unimplemented: Read as ‘0’ bit 14-8 IC4R<6:0>: Assign Input Capture 4 (IC4) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS bit 7 Unimplemented: Read as ‘0’ bit 6-0 IC3R<6:0>: Assign Input Capture 3 (IC3) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS  2011-2013 Microchip Technology Inc. DS70000657H-page 187 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 11-6: RPINR11: PERIPHERAL PIN SELECT INPUT REGISTER 11 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — OCFAR<6:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-7 Unimplemented: Read as ‘0’ bit 6-0 OCFAR<6:0>: Assign Output Compare Fault A (OCFA) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 188  2011-2013 Microchip Technology Inc. REGISTER 11-7: RPINR12: PERIPHERAL PIN SELECT INPUT REGISTER 12 (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X DEVICES ONLY) U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — FLT2R<6:0> bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — FLT1R<6:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 Unimplemented: Read as ‘0’ bit 14-8 FLT2R<6:0>: Assign PWM Fault 2 (FLT2) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS bit 7 Unimplemented: Read as ‘0’ bit 6-0 FLT1R<6:0>: Assign PWM Fault 1 (FLT1) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS  2011-2013 Microchip Technology Inc. DS70000657H-page 189 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 11-8: RPINR14: PERIPHERAL PIN SELECT INPUT REGISTER 14 (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X DEVICES ONLY) U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — QEB1R<6:0> bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — QEA1R<6:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 Unimplemented: Read as ‘0’ bit 14-8 QEB1R<6:0>: Assign B (QEB) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS bit 7 Unimplemented: Read as ‘0’ bit 6-0 QEA1R<6:0>: Assign A (QEA) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 190  2011-2013 Microchip Technology Inc. REGISTER 11-9: RPINR15: PERIPHERAL PIN SELECT INPUT REGISTER 15 (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X DEVICES ONLY) U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — HOME1R<6:0> bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — INDX1R<6:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 Unimplemented: Read as ‘0’ bit 14-8 HOME1R<6:0>: Assign QEI1 HOME1 (HOME1) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS bit 7 Unimplemented: Read as ‘0’ bit 6-0 IND1XR<6:0>: Assign QEI1 INDEX1 (INDX1) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS  2011-2013 Microchip Technology Inc. DS70000657H-page 191 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 11-10: RPINR18: PERIPHERAL PIN SELECT INPUT REGISTER 18 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — U1RXR<6:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-7 Unimplemented: Read as ‘0’ bit 6-0 U1RXR<6:0>: Assign UART1 Receive (U1RX) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS REGISTER 11-11: RPINR19: PERIPHERAL PIN SELECT INPUT REGISTER 19 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — U2RXR<6:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-7 Unimplemented: Read as ‘0’ bit 6-0 U2RXR<6:0>: Assign UART2 Receive (U2RX) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 192  2011-2013 Microchip Technology Inc. REGISTER 11-12: RPINR22: PERIPHERAL PIN SELECT INPUT REGISTER 22 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — SCK2INR<6:0> bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — SDI2R<6:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 Unimplemented: Read as ‘0’ bit 14-8 SCK2INR<6:0>: Assign SPI2 Clock Input (SCK2) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS bit 7 Unimplemented: Read as ‘0’ bit 6-0 SDI2R<6:0>: Assign SPI2 Data Input (SDI2) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS  2011-2013 Microchip Technology Inc. DS70000657H-page 193 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 11-13: RPINR23: PERIPHERAL PIN SELECT INPUT REGISTER 23 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — SS2R<6:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-7 Unimplemented: Read as ‘0’ bit 6-0 SS2R<6:0>: Assign SPI2 Slave Select (SS2) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS REGISTER 11-14: RPINR26: PERIPHERAL PIN SELECT INPUT REGISTER 26 (dsPIC33EPXXXGP/MC50X DEVICES ONLY) U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — C1RXR<6:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-7 Unimplemented: Read as ‘0’ bit 6-0 C1RXR<6:0>: Assign CAN1 RX Input (CRX1) to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 194  2011-2013 Microchip Technology Inc. REGISTER 11-15: RPINR37: PERIPHERAL PIN SELECT INPUT REGISTER 37 (dsPIC33EPXXXMC20X/50X AND PIC24EPXXXMC20X DEVICES ONLY) U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — SYNCI1R<6:0> bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 Unimplemented: Read as ‘0’ bit 14-8 SYNCI1R<6:0>: Assign PWM Synchronization Input 1 to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS bit 7-0 Unimplemented: Read as ‘0’  2011-2013 Microchip Technology Inc. DS70000657H-page 195 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 11-16: RPINR38: PERIPHERAL PIN SELECT INPUT REGISTER 38 (dsPIC33EPXXXMC20X AND PIC24EPXXXMC20X DEVICES ONLY) U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — DTCMP1R<6:0> bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 Unimplemented: Read as ‘0’ bit 14-8 DTCMP1R<6:0>: Assign PWM Dead-Time Compensation Input 1 to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS bit 7-0 Unimplemented: Read as ‘0’ dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 196  2011-2013 Microchip Technology Inc. REGISTER 11-17: RPINR39: PERIPHERAL PIN SELECT INPUT REGISTER 39 (dsPIC33EPXXXMC20X/50X AND PIC24EPXXXMC20X DEVICES ONLY) U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — DTCMP3R<6:0> bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — DTCMP2R<6:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 Unimplemented: Read as ‘0’ bit 14-8 DTCMP3R<6:0>: Assign PWM Dead-Time Compensation Input 3 to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS bit 7 Unimplemented: Read as ‘0’ bit 6-0 DTCMP2R<6:0>: Assign PWM Dead-Time Compensation Input 2 to the Corresponding RPn Pin bits (see Table 11-2 for input pin selection numbers) 1111001 = Input tied to RPI121 . . . 0000001 = Input tied to CMP1 0000000 = Input tied to VSS  2011-2013 Microchip Technology Inc. DS70000657H-page 197 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 11-18: RPOR0: PERIPHERAL PIN SELECT OUTPUT REGISTER 0 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP35R<5:0> bit 15 bit 8 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP20R<5:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13-8 RP35R<5:0>: Peripheral Output Function is Assigned to RP35 Output Pin bits (see Table 11-3 for peripheral function numbers) bit 7-6 Unimplemented: Read as ‘0’ bit 5-0 RP20R<5:0>: Peripheral Output Function is Assigned to RP20 Output Pin bits (see Table 11-3 for peripheral function numbers) REGISTER 11-19: RPOR1: PERIPHERAL PIN SELECT OUTPUT REGISTER 1 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP37R<5:0> bit 15 bit 8 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP36R<5:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13-8 RP37R<5:0>: Peripheral Output Function is Assigned to RP37 Output Pin bits (see Table 11-3 for peripheral function numbers) bit 7-6 Unimplemented: Read as ‘0’ bit 5-0 RP36R<5:0>: Peripheral Output Function is Assigned to RP36 Output Pin bits (see Table 11-3 for peripheral function numbers) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 198  2011-2013 Microchip Technology Inc. REGISTER 11-20: RPOR2: PERIPHERAL PIN SELECT OUTPUT REGISTER 2 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP39R<5:0> bit 15 bit 8 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP38R<5:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13-8 RP39R<5:0>: Peripheral Output Function is Assigned to RP39 Output Pin bits (see Table 11-3 for peripheral function numbers) bit 7-6 Unimplemented: Read as ‘0’ bit 5-0 RP38R<5:0>: Peripheral Output Function is Assigned to RP38 Output Pin bits (see Table 11-3 for peripheral function numbers) REGISTER 11-21: RPOR3: PERIPHERAL PIN SELECT OUTPUT REGISTER 3 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP41R<5:0> bit 15 bit 8 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP40R<5:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13-8 RP41R<5:0>: Peripheral Output Function is Assigned to RP41 Output Pin bits (see Table 11-3 for peripheral function numbers) bit 7-6 Unimplemented: Read as ‘0’ bit 5-0 RP40R<5:0>: Peripheral Output Function is Assigned to RP40 Output Pin bits (see Table 11-3 for peripheral function numbers)  2011-2013 Microchip Technology Inc. DS70000657H-page 199 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 11-22: RPOR4: PERIPHERAL PIN SELECT OUTPUT REGISTER 4 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP43R<5:0> bit 15 bit 8 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP42R<5:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13-8 RP43R<5:0>: Peripheral Output Function is Assigned to RP43 Output Pin bits (see Table 11-3 for peripheral function numbers) bit 7-6 Unimplemented: Read as ‘0’ bit 5-0 RP42R<5:0>: Peripheral Output Function is Assigned to RP42 Output Pin bits (see Table 11-3 for peripheral function numbers) REGISTER 11-23: RPOR5: PERIPHERAL PIN SELECT OUTPUT REGISTER 5 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP55R<5:0> bit 15 bit 8 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP54R<5:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13-8 RP55R<5:0>: Peripheral Output Function is Assigned to RP55 Output Pin bits (see Table 11-3 for peripheral function numbers) bit 7-6 Unimplemented: Read as ‘0’ bit 5-0 RP54R<5:0>: Peripheral Output Function is Assigned to RP54 Output Pin bits (see Table 11-3 for peripheral function numbers) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 200  2011-2013 Microchip Technology Inc. REGISTER 11-24: RPOR6: PERIPHERAL PIN SELECT OUTPUT REGISTER 6 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP57R<5:0> bit 15 bit 8 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP56R<5:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13-8 RP57R<5:0>: Peripheral Output Function is Assigned to RP57 Output Pin bits (see Table 11-3 for peripheral function numbers) bit 7-6 Unimplemented: Read as ‘0’ bit 5-0 RP56R<5:0>: Peripheral Output Function is Assigned to RP56 Output Pin bits (see Table 11-3 for peripheral function numbers) REGISTER 11-25: RPOR7: PERIPHERAL PIN SELECT OUTPUT REGISTER 7 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP97R<5:0> bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13-8 RP97R<5:0>: Peripheral Output Function is Assigned to RP97 Output Pin bits (see Table 11-3 for peripheral function numbers) bit 7-0 Unimplemented: Read as ‘0’  2011-2013 Microchip Technology Inc. DS70000657H-page 201 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 11-26: RPOR8: PERIPHERAL PIN SELECT OUTPUT REGISTER 8 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP118R<5:0> bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13-8 RP118R<5:0>: Peripheral Output Function is Assigned to RP118 Output Pin bits (see Table 11-3 for peripheral function numbers) bit 7-0 Unimplemented: Read as ‘0’ REGISTER 11-27: RPOR9: PERIPHERAL PIN SELECT OUTPUT REGISTER 9 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — RP120R<5:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-6 Unimplemented: Read as ‘0’ bit 5-0 RP120R<5:0>: Peripheral Output Function is Assigned to RP120 Output Pin bits (see Table 11-3 for peripheral function numbers) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 202  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 203 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 12.0 TIMER1 The Timer1 module is a 16-bit timer that can operate as a free-running interval timer/counter. The Timer1 module has the following unique features over other timers: • Can be operated in Asynchronous Counter mode from an external clock source • The external clock input (T1CK) can optionally be synchronized to the internal device clock and the clock synchronization is performed after the prescaler A block diagram of Timer1 is shown in Figure 12-1. The Timer1 module can operate in one of the following modes: • Timer mode • Gated Timer mode • Synchronous Counter mode • Asynchronous Counter mode In Timer and Gated Timer modes, the input clock is derived from the internal instruction cycle clock (FCY). In Synchronous and Asynchronous Counter modes, the input clock is derived from the external clock input at the T1CK pin. The Timer modes are determined by the following bits: • Timer Clock Source Control bit (TCS): T1CON<1> • Timer Synchronization Control bit (TSYNC): T1CON<2> • Timer Gate Control bit (TGATE): T1CON<6> Timer control bit setting for different operating modes are given in the Table 12-1. TABLE 12-1: TIMER MODE SETTINGS FIGURE 12-1: 16-BIT TIMER1 MODULE BLOCK DIAGRAM Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Timers” (DS70362) in the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. Mode TCS TGATE TSYNC Timer 00x Gated Timer 01x Synchronous Counter 1x1 Asynchronous Counter 1x0 TGATE TCS 00 10 x1 PR1 TGATE Set T1IF Flag 0 1 TSYNC 1 0 Sync Equal Reset T1CK Prescaler (/n) TCKPS<1:0> Gate Sync FP(1) Falling Edge Detect TCKPS<1:0> Note 1: FP is the peripheral clock. Latch Data CLK T1CLK CTMU Edge Control Logic TMR1 Comparator Prescaler (/n) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 204  2011-2013 Microchip Technology Inc. 12.1 Timer1 Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 12.1.1 KEY RESOURCES • “Timers” (DS70362) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464  2011-2013 Microchip Technology Inc. DS70000657H-page 205 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 12.2 Timer1 Control Register REGISTER 12-1: T1CON: TIMER1 CONTROL REGISTER R/W-0 U-0 R/W-0 U-0 U-0 U-0 U-0 U-0 TON(1) — TSIDL — — — — — bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 U-0 R/W-0 R/W-0 U-0 — TGATE TCKPS1 TCKPS0 — TSYNC(1) TCS(1) — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 TON: Timer1 On bit(1) 1 = Starts 16-bit Timer1 0 = Stops 16-bit Timer1 bit 14 Unimplemented: Read as ‘0’ bit 13 TSIDL: Timer1 Stop in Idle Mode bit 1 = Discontinues module operation when device enters Idle mode 0 = Continues module operation in Idle mode bit 12-7 Unimplemented: Read as ‘0’ bit 6 TGATE: Timer1 Gated Time Accumulation Enable bit When TCS = 1: This bit is ignored. When TCS = 0: 1 = Gated time accumulation is enabled 0 = Gated time accumulation is disabled bit 5-4 TCKPS<1:0>: Timer1 Input Clock Prescale Select bits 11 = 1:256 10 = 1:64 01 = 1:8 00 = 1:1 bit 3 Unimplemented: Read as ‘0’ bit 2 TSYNC: Timer1 External Clock Input Synchronization Select bit(1) When TCS = 1: 1 = Synchronizes external clock input 0 = Does not synchronize external clock input When TCS = 0: This bit is ignored. bit 1 TCS: Timer1 Clock Source Select bit(1) 1 = External clock is from pin, T1CK (on the rising edge) 0 = Internal clock (FP) bit 0 Unimplemented: Read as ‘0’ Note 1: When Timer1 is enabled in External Synchronous Counter mode (TCS = 1, TSYNC = 1, TON = 1), any attempts by user software to write to the TMR1 register are ignored. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 206  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 207 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 13.0 TIMER2/3 AND TIMER4/5 The Timer2/3 and Timer4/5 modules are 32-bit timers, which can also be configured as four independent 16-bit timers with selectable operating modes. As 32-bit timers, Timer2/3 and Timer4/5 operate in three modes: • Two Independent 16-Bit Timers (e.g., Timer2 and Timer3) with all 16-Bit Operating modes (except Asynchronous Counter mode) • Single 32-Bit Timer • Single 32-Bit Synchronous Counter They also support these features: • Timer Gate Operation • Selectable Prescaler Settings • Timer Operation during Idle and Sleep modes • Interrupt on a 32-Bit Period Register Match • Time Base for Input Capture and Output Compare Modules (Timer2 and Timer3 only) • ADC1 Event Trigger (32-bit timer pairs, and Timer3 and Timer5 only) Individually, all four of the 16-bit timers can function as synchronous timers or counters. They also offer the features listed previously, except for the event trigger; this is implemented only with Timer2/3. The operating modes and enabled features are determined by setting the appropriate bit(s) in the T2CON, T3CON, and T4CON, T5CON registers. T2CON and T4CON are shown in generic form in Register 13-1. T3CON and T5CON are shown in Register 13-2. For 32-bit timer/counter operation, Timer2 and Timer4 are the least significant word (lsw); Timer3 and Timer5 are the most significant word (msw) of the 32-bit timers. A block diagram for an example 32-bit timer pair (Timer2/3 and Timer4/5) is shown in Figure 13-3. Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X family of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Timers” (DS70362) of the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. Note: For 32-bit operation, T3CON and T5CON control bits are ignored. Only T2CON and T4CON control bits are used for setup and control. Timer2 and Timer4 clock and gate inputs are utilized for the 32-bit timer modules, but an interrupt is generated with the Timer3 and Timer5 interrupt flags. Note: Only Timer2, 3, 4 and 5 can trigger a DMA data transfer. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 208  2011-2013 Microchip Technology Inc. FIGURE 13-1: TYPE B TIMER BLOCK DIAGRAM (x = 2 AND 4) FIGURE 13-2: TYPE C TIMER BLOCK DIAGRAM (x = 3 AND 5) Note 1: FP is the peripheral clock. TGATE TCS 00 10 x1 PRx TGATE Set TxIF Flag 0 1 Equal Reset TxCK TCKPS<1:0> Gate Sync FP(1) Falling Edge Detect TCKPS<1:0> Latch Data CLK TxCLK TMRx Comparator Prescaler (/n) Prescaler (/n) Sync Note 1: FP is the peripheral clock. 2: The ADC trigger is available on TMR3 and TMR5 only. TGATE TCS 00 10 x1 PRx TGATE Set TxIF Flag 0 1 Equal Reset TxCK TCKPS<1:0> Gate Sync FP(1) Falling Edge Detect TCKPS<1:0> Latch Data CLK TxCLK TMRx Comparator Prescaler (/n) Prescaler (/n) Sync ADC Start of Conversion Trigger(2)  2011-2013 Microchip Technology Inc. DS70000657H-page 209 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 13-3: TYPE B/TYPE C TIMER PAIR BLOCK DIAGRAM (32-BIT TIMER) 13.1 Timerx/y Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 13.1.1 KEY RESOURCES • “Timers” (DS70362) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools TGATE TCS 00 10 x1 Comparator TGATE Set TyIF Flag 0 1 Equal Reset TxCK TCKPS<1:0> FP(1) TCKPS<1:0> Note 1: The ADC trigger is available on the TMR3:TMR2 andTMR5:TMR4 32-bit timer pairs. 2: Timerx is a Type B timer (x = 2 and 4). 3: Timery is a Type C timer (y = 3 and 5). Latch Data CLK ADC PRx TMRyHLD Data Bus<15:0> lsw msw Prescaler (/n) Prescaler (/n) Sync Gate Sync Falling Edge Detect PRy TMRx TMRy Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/ wwwproducts/Devices.aspx?d DocName=en555464 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 210  2011-2013 Microchip Technology Inc. 13.2 Timer Control Registers REGISTER 13-1: TxCON: (TIMER2 AND TIMER4) CONTROL REGISTER R/W-0 U-0 R/W-0 U-0 U-0 U-0 U-0 U-0 TON — TSIDL — — — — — bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 U-0 R/W-0 U-0 — TGATE TCKPS1 TCKPS0 T32 — TCS — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 TON: Timerx On bit When T32 = 1: 1 = Starts 32-bit Timerx/y 0 = Stops 32-bit Timerx/y When T32 = 0: 1 = Starts 16-bit Timerx 0 = Stops 16-bit Timerx bit 14 Unimplemented: Read as ‘0’ bit 13 TSIDL: Timerx Stop in Idle Mode bit 1 = Discontinues module operation when device enters Idle mode 0 = Continues module operation in Idle mode bit 12-7 Unimplemented: Read as ‘0’ bit 6 TGATE: Timerx Gated Time Accumulation Enable bit When TCS = 1: This bit is ignored. When TCS = 0: 1 = Gated time accumulation is enabled 0 = Gated time accumulation is disabled bit 5-4 TCKPS<1:0>: Timerx Input Clock Prescale Select bits 11 = 1:256 10 = 1:64 01 = 1:8 00 = 1:1 bit 3 T32: 32-Bit Timer Mode Select bit 1 = Timerx and Timery form a single 32-bit timer 0 = Timerx and Timery act as two 16-bit timers bit 2 Unimplemented: Read as ‘0’ bit 1 TCS: Timerx Clock Source Select bit 1 = External clock is from pin, TxCK (on the rising edge) 0 = Internal clock (FP) bit 0 Unimplemented: Read as ‘0’  2011-2013 Microchip Technology Inc. DS70000657H-page 211 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 13-2: TyCON: (TIMER3 AND TIMER5) CONTROL REGISTER R/W-0 U-0 R/W-0 U-0 U-0 U-0 U-0 U-0 TON(1) — TSIDL(2) — — — — — bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 U-0 U-0 R/W-0 U-0 — TGATE(1) TCKPS1(1) TCKPS0(1) — — TCS(1,3) — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 TON: Timery On bit(1) 1 = Starts 16-bit Timery 0 = Stops 16-bit Timery bit 14 Unimplemented: Read as ‘0’ bit 13 TSIDL: Timery Stop in Idle Mode bit(2) 1 = Discontinues module operation when device enters Idle mode 0 = Continues module operation in Idle mode bit 12-7 Unimplemented: Read as ‘0’ bit 6 TGATE: Timery Gated Time Accumulation Enable bit(1) When TCS = 1: This bit is ignored. When TCS = 0: 1 = Gated time accumulation is enabled 0 = Gated time accumulation is disabled bit 5-4 TCKPS<1:0>: Timery Input Clock Prescale Select bits(1) 11 = 1:256 10 = 1:64 01 = 1:8 00 = 1:1 bit 3-2 Unimplemented: Read as ‘0’ bit 1 TCS: Timery Clock Source Select bit(1,3) 1 = External clock is from pin, TyCK (on the rising edge) 0 = Internal clock (FP) bit 0 Unimplemented: Read as ‘0’ Note 1: When 32-bit operation is enabled (T2CON<3> = 1), these bits have no effect on Timery operation; all timer functions are set through TxCON. 2: When 32-bit timer operation is enabled (T32 = 1) in the Timerx Control register (TxCON<3>), the TSIDL bit must be cleared to operate the 32-bit timer in Idle mode. 3: The TyCK pin is not available on all timers. See the “Pin Diagrams” section for the available pins. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 212  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 213 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 14.0 INPUT CAPTURE The input capture module is useful in applications requiring frequency (period) and pulse measurement. The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X devices support four input capture channels. Key features of the input capture module include: • Hardware-configurable for 32-bit operation in all modes by cascading two adjacent modules • Synchronous and Trigger modes of output compare operation, with up to 19 user-selectable Trigger/Sync sources available • A 4-level FIFO buffer for capturing and holding timer values for several events • Configurable interrupt generation • Up to six clock sources available for each module, driving a separate internal 16-bit counter FIGURE 14-1: INPUT CAPTURE x MODULE BLOCK DIAGRAM Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Input Capture” (DS70352) in the “dsPIC33/dsPIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. ICxBUF 4-Level FIFO Buffer ICx Pin ICM<2:0> Set ICxIF Edge Detect Logic ICI<1:0> ICOV, ICBNE Interrupt Logic System Bus Prescaler Counter 1:1/4/16 and Clock Synchronizer Event and Trigger and Sync Logic Clock Select IC Clock Sources Trigger and Sync Sources ICTSEL<2:0> SYNCSEL<4:0> Trigger(1) 16 16 16 ICxTMR Increment Reset Note 1: The Trigger/Sync source is enabled by default and is set to Timer3 as a source. This timer must be enabled for proper ICx module operation or the Trigger/Sync source must be changed to another source option. PTG Trigger Input CTMU Edge Control Logic dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 214  2011-2013 Microchip Technology Inc. 14.1 Input Capture Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 14.1.1 KEY RESOURCES • “Input Capture” (DS70352) in the “dsPIC33/ PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464  2011-2013 Microchip Technology Inc. DS70000657H-page 215 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 14.2 Input Capture Registers REGISTER 14-1: ICxCON1: INPUT CAPTURE x CONTROL REGISTER 1 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 U-0 U-0 — — ICSIDL ICTSEL2 ICTSEL1 ICTSEL0 — — bit 15 bit 8 U-0 R/W-0 R/W-0 R/HC/HS-0 R/HC/HS-0 R/W-0 R/W-0 R/W-0 — ICI1 ICI0 ICOV ICBNE ICM2 ICM1 ICM0 bit 7 bit 0 Legend: HC = Hardware Clearable bit HS = Hardware Settable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13 ICSIDL: Input Capture Stop in Idle Control bit 1 = Input capture will Halt in CPU Idle mode 0 = Input capture will continue to operate in CPU Idle mode bit 12-10 ICTSEL<2:0>: Input Capture Timer Select bits 111 = Peripheral clock (FP) is the clock source of the ICx 110 = Reserved 101 = Reserved 100 = T1CLK is the clock source of the ICx (only the synchronous clock is supported) 011 = T5CLK is the clock source of the ICx 010 = T4CLK is the clock source of the ICx 001 = T2CLK is the clock source of the ICx 000 = T3CLK is the clock source of the ICx bit 9-7 Unimplemented: Read as ‘0’ bit 6-5 ICI<1:0>: Number of Captures per Interrupt Select bits (this field is not used if ICM<2:0> = 001 or 111) 11 = Interrupt on every fourth capture event 10 = Interrupt on every third capture event 01 = Interrupt on every second capture event 00 = Interrupt on every capture event bit 4 ICOV: Input Capture Overflow Status Flag bit (read-only) 1 = Input capture buffer overflow occurred 0 = No input capture buffer overflow occurred bit 3 ICBNE: Input Capture Buffer Not Empty Status bit (read-only) 1 = Input capture buffer is not empty, at least one more capture value can be read 0 = Input capture buffer is empty bit 2-0 ICM<2:0>: Input Capture Mode Select bits 111 = Input capture functions as interrupt pin only in CPU Sleep and Idle modes (rising edge detect only, all other control bits are not applicable) 110 = Unused (module is disabled) 101 = Capture mode, every 16th rising edge (Prescaler Capture mode) 100 = Capture mode, every 4th rising edge (Prescaler Capture mode) 011 = Capture mode, every rising edge (Simple Capture mode) 010 = Capture mode, every falling edge (Simple Capture mode) 001 = Capture mode, every edge rising and falling (Edge Detect mode (ICI<1:0>) is not used in this mode) 000 = Input capture module is turned off dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 216  2011-2013 Microchip Technology Inc. REGISTER 14-2: ICxCON2: INPUT CAPTURE x CONTROL REGISTER 2 U-0 U-0 U-0 U-0 U-0 U-0 U-0 R/W-0 — — — — — — — IC32 bit 15 bit 8 R/W-0 R/W/HS-0 U-0 R/W-0 R/W-1 R/W-1 R/W-0 R/W-1 ICTRIG(2) TRIGSTAT(3) — SYNCSEL4(4) SYNCSEL3(4) SYNCSEL2(4) SYNCSEL1(4) SYNCSEL0(4) bit 7 bit 0 Legend: HS = Hardware Settable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-9 Unimplemented: Read as ‘0’ bit 8 IC32: Input Capture 32-Bit Timer Mode Select bit (Cascade mode) 1 = Odd IC and Even IC form a single 32-bit input capture module(1) 0 = Cascade module operation is disabled bit 7 ICTRIG: Input Capture Trigger Operation Select bit(2) 1 = Input source used to trigger the input capture timer (Trigger mode) 0 = Input source used to synchronize the input capture timer to a timer of another module (Synchronization mode) bit 6 TRIGSTAT: Timer Trigger Status bit(3) 1 = ICxTMR has been triggered and is running 0 = ICxTMR has not been triggered and is being held clear bit 5 Unimplemented: Read as ‘0’ Note 1: The IC32 bit in both the Odd and Even IC must be set to enable Cascade mode. 2: The input source is selected by the SYNCSEL<4:0> bits of the ICxCON2 register. 3: This bit is set by the selected input source (selected by SYNCSEL<4:0> bits). It can be read, set and cleared in software. 4: Do not use the ICx module as its own Sync or Trigger source. 5: This option should only be selected as a trigger source and not as a synchronization source. 6: Each Input Capture x (ICx) module has one PTG input source. See Section 24.0 “Peripheral Trigger Generator (PTG) Module” for more information. PTGO8 = IC1 PTGO9 = IC2 PTGO10 = IC3 PTGO11 = IC4  2011-2013 Microchip Technology Inc. DS70000657H-page 217 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 4-0 SYNCSEL<4:0>: Input Source Select for Synchronization and Trigger Operation bits(4) 11111 = No Sync or Trigger source for ICx 11110 = Reserved 11101 = Reserved 11100 = CTMU module synchronizes or triggers ICx 11011 = ADC1 module synchronizes or triggers ICx(5) 11010 = CMP3 module synchronizes or triggers ICx(5) 11001 = CMP2 module synchronizes or triggers ICx(5) 11000 = CMP1 module synchronizes or triggers ICx(5) 10111 = Reserved 10110 = Reserved 10101 = Reserved 10100 = Reserved 10011 = IC4 module synchronizes or triggers ICx 10010 = IC3 module synchronizes or triggers ICx 10001 = IC2 module synchronizes or triggers ICx 10000 = IC1 module synchronizes or triggers ICx 01111 = Timer5 synchronizes or triggers ICx 01110 = Timer4 synchronizes or triggers ICx 01101 = Timer3 synchronizes or triggers ICx (default) 01100 = Timer2 synchronizes or triggers ICx 01011 = Timer1 synchronizes or triggers ICx 01010 = PTGOx module synchronizes or triggers ICx(6) 01001 = Reserved 01000 = Reserved 00111 = Reserved 00110 = Reserved 00101 = Reserved 00100 = OC4 module synchronizes or triggers ICx 00011 = OC3 module synchronizes or triggers ICx 00010 = OC2 module synchronizes or triggers ICx 00001 = OC1 module synchronizes or triggers ICx 00000 = No Sync or Trigger source for ICx REGISTER 14-2: ICxCON2: INPUT CAPTURE x CONTROL REGISTER 2 (CONTINUED) Note 1: The IC32 bit in both the Odd and Even IC must be set to enable Cascade mode. 2: The input source is selected by the SYNCSEL<4:0> bits of the ICxCON2 register. 3: This bit is set by the selected input source (selected by SYNCSEL<4:0> bits). It can be read, set and cleared in software. 4: Do not use the ICx module as its own Sync or Trigger source. 5: This option should only be selected as a trigger source and not as a synchronization source. 6: Each Input Capture x (ICx) module has one PTG input source. See Section 24.0 “Peripheral Trigger Generator (PTG) Module” for more information. PTGO8 = IC1 PTGO9 = IC2 PTGO10 = IC3 PTGO11 = IC4 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 218  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 219 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 15.0 OUTPUT COMPARE The output compare module can select one of seven available clock sources for its time base. The module compares the value of the timer with the value of one or two compare registers depending on the operating mode selected. The state of the output pin changes when the timer value matches the compare register value. The output compare module generates either a single output pulse or a sequence of output pulses, by changing the state of the output pin on the compare match events. The output compare module can also generate interrupts on compare match events and trigger DMA data transfers. FIGURE 15-1: OUTPUT COMPARE x MODULE BLOCK DIAGRAM Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Output Compare” (DS70358) in the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. Note: See “Output Compare” (DS70358) in the “dsPIC33/PIC24 Family Reference Manual” for OCxR and OCxRS register restrictions. OCxR Buffer Comparator OCxTMR OCxCON1 OCxCON2 OCx Interrupt OCx Pin OCxRS Buffer Comparator Match Match Trigger and Sync Logic Clock Select Increment Reset OC Clock Sources Trigger and Sync Sources Reset Match Event OCFA OCxR OCxRS Event Event Rollover Rollover/Reset Rollover/Reset OCx Synchronization/Trigger Event OCFB SYNCSEL<4:0> Trigger(1) Note 1: The Trigger/Sync source is enabled by default and is set to Timer2 as a source. This timer must be enabled for proper OCx module operation or the Trigger/Sync source must be changed to another source option. PTG Trigger Input CTMU Edge Control Logic OC Output and Fault Logic dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 220  2011-2013 Microchip Technology Inc. 15.1 Output Compare Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 15.1.1 KEY RESOURCES • “Output Compare” (DS70358) in the “dsPIC33/ PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464  2011-2013 Microchip Technology Inc. DS70000657H-page 221 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 15.2 Output Compare Control Registers REGISTER 15-1: OCxCON1: OUTPUT COMPARE x CONTROL REGISTER 1 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 U-0 R/W-0 — — OCSIDL OCTSEL2 OCTSEL1 OCTSEL0 — ENFLTB bit 15 bit 8 R/W-0 U-0 R/W-0, HSC R/W-0, HSC R/W-0 R/W-0 R/W-0 R/W-0 ENFLTA — OCFLTB OCFLTA TRIGMODE OCM2 OCM1 OCM0 bit 7 bit 0 Legend: HSC = Hardware Settable/Clearable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13 OCSIDL: Output Compare x Stop in Idle Mode Control bit 1 = Output Compare x Halts in CPU Idle mode 0 = Output Compare x continues to operate in CPU Idle mode bit 12-10 OCTSEL<2:0>: Output Compare x Clock Select bits 111 = Peripheral clock (FP) 110 = Reserved 101 = PTGOx clock(2) 100 = T1CLK is the clock source of the OCx (only the synchronous clock is supported) 011 = T5CLK is the clock source of the OCx 010 = T4CLK is the clock source of the OCx 001 = T3CLK is the clock source of the OCx 000 = T2CLK is the clock source of the OCx bit 9 Unimplemented: Read as ‘0’ bit 8 ENFLTB: Fault B Input Enable bit 1 = Output Compare Fault B input (OCFB) is enabled 0 = Output Compare Fault B input (OCFB) is disabled bit 7 ENFLTA: Fault A Input Enable bit 1 = Output Compare Fault A input (OCFA) is enabled 0 = Output Compare Fault A input (OCFA) is disabled bit 6 Unimplemented: Read as ‘0’ bit 5 OCFLTB: PWM Fault B Condition Status bit 1 = PWM Fault B condition on OCFB pin has occurred 0 = No PWM Fault B condition on OCFB pin has occurred bit 4 OCFLTA: PWM Fault A Condition Status bit 1 = PWM Fault A condition on OCFA pin has occurred 0 = No PWM Fault A condition on OCFA pin has occurred Note 1: OCxR and OCxRS are double-buffered in PWM mode only. 2: Each Output Compare x module (OCx) has one PTG clock source. See Section 24.0 “Peripheral Trigger Generator (PTG) Module” for more information. PTGO4 = OC1 PTGO5 = OC2 PTGO6 = OC3 PTGO7 = OC4 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 222  2011-2013 Microchip Technology Inc. bit 3 TRIGMODE: Trigger Status Mode Select bit 1 = TRIGSTAT (OCxCON2<6>) is cleared when OCxRS = OCxTMR or in software 0 = TRIGSTAT is cleared only by software bit 2-0 OCM<2:0>: Output Compare x Mode Select bits 111 = Center-Aligned PWM mode: Output set high when OCxTMR = OCxR and set low when OCxTMR = OCxRS(1) 110 = Edge-Aligned PWM mode: Output set high when OCxTMR = 0 and set low when OCxTMR = OCxR(1) 101 = Double Compare Continuous Pulse mode: Initializes OCx pin low, toggles OCx state continuously on alternate matches of OCxR and OCxRS 100 = Double Compare Single-Shot mode: Initializes OCx pin low, toggles OCx state on matches of OCxR and OCxRS for one cycle 011 = Single Compare mode: Compare event with OCxR, continuously toggles OCx pin 010 = Single Compare Single-Shot mode: Initializes OCx pin high, compare event with OCxR, forces OCx pin low 001 = Single Compare Single-Shot mode: Initializes OCx pin low, compare event with OCxR, forces OCx pin high 000 = Output compare channel is disabled REGISTER 15-1: OCxCON1: OUTPUT COMPARE x CONTROL REGISTER 1 (CONTINUED) Note 1: OCxR and OCxRS are double-buffered in PWM mode only. 2: Each Output Compare x module (OCx) has one PTG clock source. See Section 24.0 “Peripheral Trigger Generator (PTG) Module” for more information. PTGO4 = OC1 PTGO5 = OC2 PTGO6 = OC3 PTGO7 = OC4  2011-2013 Microchip Technology Inc. DS70000657H-page 223 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 15-2: OCxCON2: OUTPUT COMPARE x CONTROL REGISTER 2 R/W-0 R/W-0 R/W-0 R/W-0 U-0 U-0 U-0 R/W-0 FLTMD FLTOUT FLTTRIEN OCINV — — — OC32 bit 15 bit 8 R/W-0 R/W-0, HS R/W-0 R/W-0 R/W-1 R/W-1 R/W-0 R/W-0 OCTRIG TRIGSTAT OCTRIS SYNCSEL4 SYNCSEL3 SYNCSEL2 SYNCSEL1 SYNCSEL0 bit 7 bit 0 Legend: HS = Hardware Settable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 FLTMD: Fault Mode Select bit 1 = Fault mode is maintained until the Fault source is removed; the corresponding OCFLTx bit is cleared in software and a new PWM period starts 0 = Fault mode is maintained until the Fault source is removed and a new PWM period starts bit 14 FLTOUT: Fault Out bit 1 = PWM output is driven high on a Fault 0 = PWM output is driven low on a Fault bit 13 FLTTRIEN: Fault Output State Select bit 1 = OCx pin is tri-stated on a Fault condition 0 = OCx pin I/O state is defined by the FLTOUT bit on a Fault condition bit 12 OCINV: Output Compare x Invert bit 1 = OCx output is inverted 0 = OCx output is not inverted bit 11-9 Unimplemented: Read as ‘0’ bit 8 OC32: Cascade Two OCx Modules Enable bit (32-bit operation) 1 = Cascade module operation is enabled 0 = Cascade module operation is disabled bit 7 OCTRIG: Output Compare x Trigger/Sync Select bit 1 = Triggers OCx from the source designated by the SYNCSELx bits 0 = Synchronizes OCx with the source designated by the SYNCSELx bits bit 6 TRIGSTAT: Timer Trigger Status bit 1 = Timer source has been triggered and is running 0 = Timer source has not been triggered and is being held clear bit 5 OCTRIS: Output Compare x Output Pin Direction Select bit 1 = OCx is tri-stated 0 = Output Compare x module drives the OCx pin Note 1: Do not use the OCx module as its own Synchronization or Trigger source. 2: When the OCy module is turned OFF, it sends a trigger out signal. If the OCx module uses the OCy module as a Trigger source, the OCy module must be unselected as a Trigger source prior to disabling it. 3: Each Output Compare x module (OCx) has one PTG Trigger/Synchronization source. See Section 24.0 “Peripheral Trigger Generator (PTG) Module” for more information. PTGO0 = OC1 PTGO1 = OC2 PTGO2 = OC3 PTGO3 = OC4 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 224  2011-2013 Microchip Technology Inc. bit 4-0 SYNCSEL<4:0>: Trigger/Synchronization Source Selection bits 11111 = OCxRS compare event is used for synchronization 11110 = INT2 pin synchronizes or triggers OCx 11101 = INT1 pin synchronizes or triggers OCx 11100 = CTMU module synchronizes or triggers OCx 11011 = ADC1 module synchronizes or triggers OCx 11010 = CMP3 module synchronizes or triggers OCx 11001 = CMP2 module synchronizes or triggers OCx 11000 = CMP1 module synchronizes or triggers OCx 10111 = Reserved 10110 = Reserved 10101 = Reserved 10100 = Reserved 10011 = IC4 input capture event synchronizes or triggers OCx 10010 = IC3 input capture event synchronizes or triggers OCx 10001 = IC2 input capture event synchronizes or triggers OCx 10000 = IC1 input capture event synchronizes or triggers OCx 01111 = Timer5 synchronizes or triggers OCx 01110 = Timer4 synchronizes or triggers OCx 01101 = Timer3 synchronizes or triggers OCx 01100 = Timer2 synchronizes or triggers OCx (default) 01011 = Timer1 synchronizes or triggers OCx 01010 = PTGOx synchronizes or triggers OCx(3) 01001 = Reserved 01000 = Reserved 00111 = Reserved 00110 = Reserved 00101 = Reserved 00100 = OC4 module synchronizes or triggers OCx(1,2) 00011 = OC3 module synchronizes or triggers OCx(1,2) 00010 = OC2 module synchronizes or triggers OCx(1,2) 00001 = OC1 module synchronizes or triggers OCx(1,2) 00000 = No Sync or Trigger source for OCx REGISTER 15-2: OCxCON2: OUTPUT COMPARE x CONTROL REGISTER 2 (CONTINUED) Note 1: Do not use the OCx module as its own Synchronization or Trigger source. 2: When the OCy module is turned OFF, it sends a trigger out signal. If the OCx module uses the OCy module as a Trigger source, the OCy module must be unselected as a Trigger source prior to disabling it. 3: Each Output Compare x module (OCx) has one PTG Trigger/Synchronization source. See Section 24.0 “Peripheral Trigger Generator (PTG) Module” for more information. PTGO0 = OC1 PTGO1 = OC2 PTGO2 = OC3 PTGO3 = OC4  2011-2013 Microchip Technology Inc. DS70000657H-page 225 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 16.0 HIGH-SPEED PWM MODULE (dsPIC33EPXXXMC20X/50X AND PIC24EPXXXMC20X DEVICES ONLY) The dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices support a dedicated Pulse-Width Modulation (PWM) module with up to 6 outputs. The high-speed PWMx module consists of the following major features: • Three PWM generators • Two PWM outputs per PWM generator • Individual period and duty cycle for each PWM pair • Duty cycle, dead time, phase shift and frequency resolution of TCY/2 (7.14 ns at FCY = 70MHz) • Independent Fault and current-limit inputs for six PWM outputs • Redundant output • Center-Aligned PWM mode • Output override control • Chop mode (also known as Gated mode) • Special Event Trigger • Prescaler for input clock • PWMxL and PWMxH output pin swapping • Independent PWM frequency, duty cycle and phase-shift changes for each PWM generator • Dead-time compensation • Enhanced Leading-Edge Blanking (LEB) functionality • Frequency resolution enhancement • PWM capture functionality The high-speed PWMx module contains up to three PWM generators. Each PWM generator provides two PWM outputs: PWMxH and PWMxL. The master time base generator provides a synchronous signal as a common time base to synchronize the various PWM outputs. The individual PWM outputs are available on the output pins of the device. The input Fault signals and current-limit signals, when enabled, can monitor and protect the system by placing the PWM outputs into a known “safe” state. Each PWMx can generate a trigger to the ADC module to sample the analog signal at a specific instance during the PWM period. In addition, the high-speed PWMx module also generates a Special Event Trigger to the ADC module based on either of the two master time bases. The high-speed PWMx module can synchronize itself with an external signal or can act as a synchronizing source to any external device. The SYNCI1 input pin that utilizes PPS, can synchronize the high-speed PWMx module with an external signal. The SYNCO1 pin is an output pin that provides a synchronous signal to an external device. Figure 16-1 illustrates an architectural overview of the high-speed PWMx module and its interconnection with the CPU and other peripherals. 16.1 PWM Faults The PWMx module incorporates multiple external Fault inputs to include FLT1 and FLT2 which are remappable using the PPS feature, FLT3 and FLT4 which are available only on the larger 44-pin and 64-pin packages, and FLT32 which has been implemented with Class B safety features, and is available on a fixed pin on all dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices. These Faults provide a safe and reliable way to safely shut down the PWM outputs when the Fault input is asserted. 16.1.1 PWM FAULTS AT RESET During any Reset event, the PWMx module maintains ownership of the Class B Fault, FLT32. At Reset, this Fault is enabled in Latched mode to ensure the fail-safe power-up of the application. The application software must clear the PWM Fault before enabling the highspeed motor control PWMx module. To clear the Fault condition, the FLT32 pin must first be pulled low externally or the internal pull-down resistor in the CNPDx register can be enabled. Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “High-Speed PWM” (DS70645) in the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. Note: In Edge-Aligned PWM mode, the duty cycle, dead time, phase shift and frequency resolution are 8.32 ns. Note: The Fault mode may be changed using the FLTMOD<1:0> bits (FCLCON<1:0>), regardless of the state of FLT32. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 226  2011-2013 Microchip Technology Inc. 16.1.2 WRITE-PROTECTED REGISTERS On dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices, write protection is implemented for the IOCONx and FCLCONx registers. The write protection feature prevents any inadvertent writes to these registers. This protection feature can be controlled by the PWMLOCK Configuration bit (FOSCSEL<6>). The default state of the write protection feature is enabled (PWMLOCK = 1). The write protection feature can be disabled by configuring, PWMLOCK = 0. To gain write access to these locked registers, the user application must write two consecutive values of (0xABCD and 0x4321) to the PWMKEY register to perform the unlock operation. The write access to the IOCONx or FCLCONx registers must be the next SFR access following the unlock process. There can be no other SFR accesses during the unlock process and subsequent write access. To write to both the IOCONx and FCLCONx registers requires two unlock operations. The correct unlocking sequence is described in Example 16-1. EXAMPLE 16-1: PWMx WRITE-PROTECTED REGISTER UNLOCK SEQUENCE ; FLT32 pin must be pulled low externally in order to clear and disable the fault ; Writing to FCLCON1 register requires unlock sequence mov #0xabcd,w10 ; Load first unlock key to w10 register mov #0x4321,w11 ; Load second unlock key to w11 register mov #0x0000,w0 ; Load desired value of FCLCON1 register in w0 mov w10, PWMKEY ; Write first unlock key to PWMKEY register mov w11, PWMKEY ; Write second unlock key to PWMKEY register mov w0,FCLCON1 ; Write desired value to FCLCON1 register ; Set PWM ownership and polarity using the IOCON1 register ; Writing to IOCON1 register requires unlock sequence mov #0xabcd,w10 ; Load first unlock key to w10 register mov #0x4321,w11 ; Load second unlock key to w11 register mov #0xF000,w0 ; Load desired value of IOCON1 register in w0 mov w10, PWMKEY ; Write first unlock key to PWMKEY register mov w11, PWMKEY ; Write second unlock key to PWMKEY register mov w0,IOCON1 ; Write desired value to IOCON1 register  2011-2013 Microchip Technology Inc. DS70000657H-page 227 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 16-1: HIGH-SPEED PWMx MODULE ARCHITECTURAL OVERVIEW CPU PWM Generator 1 PWM Generator 3 SYNCI1 SYNCO1 PWM1H PWM1L PWM1 Interrupt(1) PWM2H PWM2L PWM2 Interrupt(1) PWM3H PWM3L PWM3 Interrupt(1) Synchronization Signal Data Bus ADC Module FLT1-FLT4, FLT32 Synchronization Signal Synchronization Signal Primary Trigger Primary Special DTCMP1-DTCMP3 Fault, Current-Limit and Dead-Time Compensation Event Trigger Master Time Base Fault, Current-Limit and Dead-Time Compensation Fault, Current-Limit and Dead-Time Compensation FOSC Note 1: The PWM interrupts are generated by logically ORing the FLTSTAT, CLSTAT and TRGSTAT status bits for the given PWM generator. Refer to the “dsPIC33/PIC24 Family Reference Manual”, “High-Speed PWM” (DS70645) for more information. PWM Generator 2 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 228  2011-2013 Microchip Technology Inc. FIGURE 16-2: HIGH-SPEED PWMx MODULE REGISTER INTERCONNECTION DIAGRAM MUX PTMRx PDCx PWMCONx, PTCON, PTCON2 IOCONx DTRx PWMxL PWMxH FLTx PWM1L PWM1H FCLCONx MDC PHASEx LEBCONx, ALTDTRx User Override Logic Current-Limit PWM Output Mode Control Logic Logic Pin Control Logic Fault and Current-Limit Logic PWM Generator 1 FLTx PWM Generator 2 and PWM Generator 3 Interrupt Logic(1) Module Control and Timing Master Duty Cycle Register Synchronization Synchronization Master Period Master Period Master Duty Cycle Master Duty Cycle SYNCI1 SYNCO1 SEVTCMP Comparator Special Event Trigger Special Event Postscaler PTPER PMTMR Primary Master Time Base Master Time Base Counter Special Event Compare Trigger Comparator Clock Prescaler Comparator Dead-Time Fault Override Logic Override Logic DTCMPx DTCMP1 FOSC PWMKEY IOCONx and FCLCONx Unlock Register AUXCONx LEBDLYx PTG Trigger Input PTG Trigger Input PTG Trigger Input TRGCONx PWMCAPx ADC Trigger Comparator TRIGx 16-Bit Data Bus Note 1: The PWM interrupts are generated by logically ORing the FLTSTAT, CLSTAT and TRGSTAT status bits for the given PWM generator. Refer to the “dsPIC33/PIC24 Family Reference Manual”, “High-Speed PWM” (DS70645) for more information.  2011-2013 Microchip Technology Inc. DS70000657H-page 229 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 16.2 PWM Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 16.2.1 KEY RESOURCES • “High-Speed PWM” (DS70645) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 230  2011-2013 Microchip Technology Inc. 16.3 PWMx Control Registers REGISTER 16-1: PTCON: PWMx TIME BASE CONTROL REGISTER R/W-0 U-0 R/W-0 HS/HC-0 R/W-0 R/W-0 R/W-0 R/W-0 PTEN — PTSIDL SESTAT SEIEN EIPU(1) SYNCPOL(1) SYNCOEN(1) bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 SYNCEN(1) SYNCSRC2(1) SYNCSRC1(1) SYNCSRC0(1) SEVTPS3(1) SEVTPS2(1) SEVTPS1(1) SEVTPS0(1) bit 7 bit 0 Legend: HC = Hardware Clearable bit HS = Hardware Settable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 PTEN: PWMx Module Enable bit 1 = PWMx module is enabled 0 = PWMx module is disabled bit 14 Unimplemented: Read as ‘0’ bit 13 PTSIDL: PWMx Time Base Stop in Idle Mode bit 1 = PWMx time base halts in CPU Idle mode 0 = PWMx time base runs in CPU Idle mode bit 12 SESTAT: Special Event Interrupt Status bit 1 = Special event interrupt is pending 0 = Special event interrupt is not pending bit 11 SEIEN: Special Event Interrupt Enable bit 1 = Special event interrupt is enabled 0 = Special event interrupt is disabled bit 10 EIPU: Enable Immediate Period Updates bit(1) 1 = Active Period register is updated immediately 0 = Active Period register updates occur on PWMx cycle boundaries bit 9 SYNCPOL: Synchronize Input and Output Polarity bit(1) 1 = SYNCI1/SYNCO1 polarity is inverted (active-low) 0 = SYNCI1/SYNCO1 is active-high bit 8 SYNCOEN: Primary Time Base Sync Enable bit(1) 1 = SYNCO1 output is enabled 0 = SYNCO1 output is disabled bit 7 SYNCEN: External Time Base Synchronization Enable bit(1) 1 = External synchronization of primary time base is enabled 0 = External synchronization of primary time base is disabled Note 1: These bits should be changed only when PTEN = 0. In addition, when using the SYNCI1 feature, the user application must program the period register with a value that is slightly larger than the expected period of the external synchronization input signal. 2: See Section 24.0 “Peripheral Trigger Generator (PTG) Module” for information on this selection.  2011-2013 Microchip Technology Inc. DS70000657H-page 231 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 6-4 SYNCSRC<2:0>: Synchronous Source Selection bits(1) 111 = Reserved • • • 100 = Reserved 011 = PTGO17(2) 010 = PTGO16(2) 001 = Reserved 000 = SYNCI1 input from PPS bit 3-0 SEVTPS<3:0>: PWMx Special Event Trigger Output Postscaler Select bits(1) 1111 = 1:16 Postscaler generates Special Event Trigger on every sixteenth compare match event • • • 0001 = 1:2 Postscaler generates Special Event Trigger on every second compare match event 0000 = 1:1 Postscaler generates Special Event Trigger on every compare match event REGISTER 16-1: PTCON: PWMx TIME BASE CONTROL REGISTER (CONTINUED) Note 1: These bits should be changed only when PTEN = 0. In addition, when using the SYNCI1 feature, the user application must program the period register with a value that is slightly larger than the expected period of the external synchronization input signal. 2: See Section 24.0 “Peripheral Trigger Generator (PTG) Module” for information on this selection. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 232  2011-2013 Microchip Technology Inc. REGISTER 16-2: PTCON2: PWMx PRIMARY MASTER CLOCK DIVIDER SELECT REGISTER 2 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 — — — — — PCLKDIV2(1) PCLKDIV1(1) PCLKDIV0(1) bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-3 Unimplemented: Read as ‘0’ bit 2-0 PCLKDIV<2:0>: PWMx Input Clock Prescaler (Divider) Select bits(1) 111 = Reserved 110 = Divide-by-64 101 = Divide-by-32 100 = Divide-by-16 011 = Divide-by-8 010 = Divide-by-4 001 = Divide-by-2 000 = Divide-by-1, maximum PWMx timing resolution (power-on default) Note 1: These bits should be changed only when PTEN = 0. Changing the clock selection during operation will yield unpredictable results.  2011-2013 Microchip Technology Inc. DS70000657H-page 233 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 16-3: PTPER: PWMx PRIMARY MASTER TIME BASE PERIOD 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 PTPER<15:8> bit 15 bit 8 R/W-1 R/W-1 R/W-1 R/W-1 R/W-1 R/W-0 R/W-0 R/W-0 PTPER<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 PTPER<15:0>: Primary Master Time Base (PMTMR) Period Value bits REGISTER 16-4: SEVTCMP: PWMx PRIMARY SPECIAL EVENT COMPARE 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 SEVTCMP<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 SEVTCMP<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 SEVTCMP<15:0>: Special Event Compare Count Value bits dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 234  2011-2013 Microchip Technology Inc. REGISTER 16-5: CHOP: PWMx CHOP CLOCK GENERATOR REGISTER R/W-0 U-0 U-0 U-0 U-0 U-0 R/W-0 R/W-0 CHPCLKEN — — — — — CHOPCLK<9:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 CHOPCLK<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 CHPCLKEN: Enable Chop Clock Generator bit 1 = Chop clock generator is enabled 0 = Chop clock generator is disabled bit 14-10 Unimplemented: Read as ‘0’ bit 9-0 CHOPCLK<9:0>: Chop Clock Divider bits The frequency of the chop clock signal is given by the following expression: Chop Frequency = (FP/PCLKDIV<2:0)/(CHOPCLK<9:0> + 1) REGISTER 16-6: MDC: PWMx MASTER DUTY CYCLE 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 MDC<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 MDC<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 MDC<15:0>: PWMx Master Duty Cycle Value bits  2011-2013 Microchip Technology Inc. DS70000657H-page 235 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 16-7: PWMCONx: PWMx CONTROL REGISTER HS/HC-0 HS/HC-0 HS/HC-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 FLTSTAT(1) CLSTAT(1) TRGSTAT FLTIEN CLIEN TRGIEN ITB(2) MDCS(2) bit 15 bit 8 R/W-0 R/W-0 R/W-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 DTC1 DTC0 DTCP(3) — MTBS CAM(2,4) XPRES(5) IUE(2) bit 7 bit 0 Legend: HC = Hardware Clearable bit HS = Hardware Settable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 FLTSTAT: Fault Interrupt Status bit(1) 1 = Fault interrupt is pending 0 = No Fault interrupt is pending This bit is cleared by setting FLTIEN = 0. bit 14 CLSTAT: Current-Limit Interrupt Status bit(1) 1 = Current-limit interrupt is pending 0 = No current-limit interrupt is pending This bit is cleared by setting CLIEN = 0. bit 13 TRGSTAT: Trigger Interrupt Status bit 1 = Trigger interrupt is pending 0 = No trigger interrupt is pending This bit is cleared by setting TRGIEN = 0. bit 12 FLTIEN: Fault Interrupt Enable bit 1 = Fault interrupt is enabled 0 = Fault interrupt is disabled and the FLTSTAT bit is cleared bit 11 CLIEN: Current-Limit Interrupt Enable bit 1 = Current-limit interrupt is enabled 0 = Current-limit interrupt is disabled and the CLSTAT bit is cleared bit 10 TRGIEN: Trigger Interrupt Enable bit 1 = A trigger event generates an interrupt request 0 = Trigger event interrupts are disabled and the TRGSTAT bit is cleared bit 9 ITB: Independent Time Base Mode bit(2) 1 = PHASEx register provides time base period for this PWM generator 0 = PTPER register provides timing for this PWM generator bit 8 MDCS: Master Duty Cycle Register Select bit(2) 1 = MDC register provides duty cycle information for this PWM generator 0 = PDCx register provides duty cycle information for this PWM generator Note 1: Software must clear the interrupt status here and in the corresponding IFSx bit in the interrupt controller. 2: These bits should not be changed after the PWMx is enabled (PTEN = 1). 3: DTC<1:0> = 11 for DTCP to be effective; otherwise, DTCP is ignored. 4: The Independent Time Base (ITB = 1) mode must be enabled to use Center-Aligned mode. If ITB = 0, the CAM bit is ignored. 5: To operate in External Period Reset mode, the ITB bit must be ‘1’ and the CLMOD bit in the FCLCONx register must be ‘0’. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 236  2011-2013 Microchip Technology Inc. bit 7-6 DTC<1:0>: Dead-Time Control bits 11 = Dead-Time Compensation mode 10 = Dead-time function is disabled 01 = Negative dead time is actively applied for Complementary Output mode 00 = Positive dead time is actively applied for all output modes bit 5 DTCP: Dead-Time Compensation Polarity bit(3) When Set to ‘1’: If DTCMPx = 0, PWMxL is shortened and PWMxH is lengthened. If DTCMPx = 1, PWMxH is shortened and PWMxL is lengthened. When Set to ‘0’: If DTCMPx = 0, PWMxH is shortened and PWMxL is lengthened. If DTCMPx = 1, PWMxL is shortened and PWMxH is lengthened. bit 4 Unimplemented: Read as ‘0’ bit 3 MTBS: Master Time Base Select bit 1 = PWM generator uses the secondary master time base for synchronization and as the clock source for the PWM generation logic (if secondary time base is available) 0 = PWM generator uses the primary master time base for synchronization and as the clock source for the PWM generation logic bit 2 CAM: Center-Aligned Mode Enable bit(2,4) 1 = Center-Aligned mode is enabled 0 = Edge-Aligned mode is enabled bit 1 XPRES: External PWMx Reset Control bit(5) 1 = Current-limit source resets the time base for this PWM generator if it is in Independent Time Base mode 0 = External pins do not affect PWMx time base bit 0 IUE: Immediate Update Enable bit(2) 1 = Updates to the active MDC/PDCx/DTRx/ALTDTRx/PHASEx registers are immediate 0 = Updates to the active MDC/PDCx/DTRx/ALTDTRx/PHASEx registers are synchronized to the PWMx period boundary REGISTER 16-7: PWMCONx: PWMx CONTROL REGISTER (CONTINUED) Note 1: Software must clear the interrupt status here and in the corresponding IFSx bit in the interrupt controller. 2: These bits should not be changed after the PWMx is enabled (PTEN = 1). 3: DTC<1:0> = 11 for DTCP to be effective; otherwise, DTCP is ignored. 4: The Independent Time Base (ITB = 1) mode must be enabled to use Center-Aligned mode. If ITB = 0, the CAM bit is ignored. 5: To operate in External Period Reset mode, the ITB bit must be ‘1’ and the CLMOD bit in the FCLCONx register must be ‘0’.  2011-2013 Microchip Technology Inc. DS70000657H-page 237 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 16-8: PDCx: PWMx GENERATOR DUTY CYCLE 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 PDCx<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 PDCx<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 PDCx<15:0>: PWMx Generator # Duty Cycle Value bits REGISTER 16-9: PHASEx: PWMx PRIMARY PHASE-SHIFT 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 PHASEx<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 PHASEx<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 PHASEx<15:0>: PWMx Phase-Shift Value or Independent Time Base Period for the PWM Generator bits Note 1: If ITB (PWMCONx<9>) = 0, the following applies based on the mode of operation: Complementary, Redundant and Push-Pull Output mode (PMOD<1:0> (IOCON<11:10>) = 00, 01 or 10), PHASEx<15:0> = Phase-shift value for PWMxH and PWMxL outputs 2: If ITB (PWMCONx<9>) = 1, the following applies based on the mode of operation: Complementary, Redundant and Push-Pull Output mode (PMOD<1:0> (IOCONx<11:10>) = 00, 01 or 10), PHASEx<15:0> = Independent time base period value for PWMxH and PWMxL dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 238  2011-2013 Microchip Technology Inc. REGISTER 16-10: DTRx: PWMx DEAD-TIME REGISTER U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — DTRx<13:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 DTRx<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13-0 DTRx<13:0>: Unsigned 14-Bit Dead-Time Value for PWMx Dead-Time Unit bits REGISTER 16-11: ALTDTRx: PWMx ALTERNATE DEAD-TIME REGISTER U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — ALTDTRx<13:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 ALTDTRx<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13-0 ALTDTRx<13:0>: Unsigned 14-Bit Dead-Time Value for PWMx Dead-Time Unit bits  2011-2013 Microchip Technology Inc. DS70000657H-page 239 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 16-12: TRGCONx: PWMx TRIGGER CONTROL REGISTER R/W-0 R/W-0 R/W-0 R/W-0 U-0 U-0 U-0 U-0 TRGDIV<3:0> — — — — bit 15 bit 8 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — TRGSTRT<5:0>(1) bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-12 TRGDIV<3:0>: Trigger # Output Divider bits 1111 = Trigger output for every 16th trigger event 1110 = Trigger output for every 15th trigger event 1101 = Trigger output for every 14th trigger event 1100 = Trigger output for every 13th trigger event 1011 = Trigger output for every 12th trigger event 1010 = Trigger output for every 11th trigger event 1001 = Trigger output for every 10th trigger event 1000 = Trigger output for every 9th trigger event 0111 = Trigger output for every 8th trigger event 0110 = Trigger output for every 7th trigger event 0101 = Trigger output for every 6th trigger event 0100 = Trigger output for every 5th trigger event 0011 = Trigger output for every 4th trigger event 0010 = Trigger output for every 3rd trigger event 0001 = Trigger output for every 2nd trigger event 0000 = Trigger output for every trigger event bit 11-6 Unimplemented: Read as ‘0’ bit 5-0 TRGSTRT<5:0>: Trigger Postscaler Start Enable Select bits(1) 111111 = Waits 63 PWM cycles before generating the first trigger event after the module is enabled • • • 000010 = Waits 2 PWM cycles before generating the first trigger event after the module is enabled 000001 = Waits 1 PWM cycle before generating the first trigger event after the module is enabled 000000 = Waits 0 PWM cycles before generating the first trigger event after the module is enabled Note 1: The secondary PWM generator cannot generate PWMx trigger interrupts. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 240  2011-2013 Microchip Technology Inc. REGISTER 16-13: IOCONx: PWMx I/O CONTROL REGISTER(2) R/W-1 R/W-1 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 PENH PENL POLH POLL PMOD1(1) PMOD0(1) OVRENH OVRENL bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 OVRDAT1 OVRDAT0 FLTDAT1 FLTDAT0 CLDAT1 CLDAT0 SWAP OSYNC bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 PENH: PWMxH Output Pin Ownership bit 1 = PWMx module controls PWMxH pin 0 = GPIO module controls PWMxH pin bit 14 PENL: PWMxL Output Pin Ownership bit 1 = PWMx module controls PWMxL pin 0 = GPIO module controls PWMxL pin bit 13 POLH: PWMxH Output Pin Polarity bit 1 = PWMxH pin is active-low 0 = PWMxH pin is active-high bit 12 POLL: PWMxL Output Pin Polarity bit 1 = PWMxL pin is active-low 0 = PWMxL pin is active-high bit 11-10 PMOD<1:0>: PWMx # I/O Pin Mode bits(1) 11 = Reserved; do not use 10 = PWMx I/O pin pair is in the Push-Pull Output mode 01 = PWMx I/O pin pair is in the Redundant Output mode 00 = PWMx I/O pin pair is in the Complementary Output mode bit 9 OVRENH: Override Enable for PWMxH Pin bit 1 = OVRDAT<1> controls output on PWMxH pin 0 = PWMx generator controls PWMxH pin bit 8 OVRENL: Override Enable for PWMxL Pin bit 1 = OVRDAT<0> controls output on PWMxL pin 0 = PWMx generator controls PWMxL pin bit 7-6 OVRDAT<1:0>: Data for PWMxH, PWMxL Pins if Override is Enabled bits If OVERENH = 1, PWMxH is driven to the state specified by OVRDAT<1>. If OVERENL = 1, PWMxL is driven to the state specified by OVRDAT<0>. bit 5-4 FLTDAT<1:0>: Data for PWMxH and PWMxL Pins if FLTMOD is Enabled bits If Fault is active, PWMxH is driven to the state specified by FLTDAT<1>. If Fault is active, PWMxL is driven to the state specified by FLTDAT<0>. bit 3-2 CLDAT<1:0>: Data for PWMxH and PWMxL Pins if CLMOD is Enabled bits If current-limit is active, PWMxH is driven to the state specified by CLDAT<1>. If current-limit is active, PWMxL is driven to the state specified by CLDAT<0>. Note 1: These bits should not be changed after the PWMx module is enabled (PTEN = 1). 2: If the PWMLOCK Configuration bit (FOSCSEL<6>) is a ‘1’, the IOCONx register can only be written after the unlock sequence has been executed.  2011-2013 Microchip Technology Inc. DS70000657H-page 241 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 1 SWAP: SWAP PWMxH and PWMxL Pins bit 1 = PWMxH output signal is connected to PWMxL pins; PWMxL output signal is connected to PWMxH pins 0 = PWMxH and PWMxL pins are mapped to their respective pins bit 0 OSYNC: Output Override Synchronization bit 1 = Output overrides via the OVRDAT<1:0> bits are synchronized to the PWMx period boundary 0 = Output overrides via the OVDDAT<1:0> bits occur on the next CPU clock boundary REGISTER 16-13: IOCONx: PWMx I/O CONTROL REGISTER(2) (CONTINUED) Note 1: These bits should not be changed after the PWMx module is enabled (PTEN = 1). 2: If the PWMLOCK Configuration bit (FOSCSEL<6>) is a ‘1’, the IOCONx register can only be written after the unlock sequence has been executed. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 242  2011-2013 Microchip Technology Inc. REGISTER 16-14: TRIGx: PWMx PRIMARY TRIGGER COMPARE VALUE 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 TRGCMP<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 TRGCMP<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 TRGCMP<15:0>: Trigger Control Value bits When the primary PWMx functions in local time base, this register contains the compare values that can trigger the ADC module.  2011-2013 Microchip Technology Inc. DS70000657H-page 243 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 16-15: FCLCONx: PWMx FAULT CURRENT-LIMIT CONTROL REGISTER(1) U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — CLSRC4 CLSRC3 CLSRC2 CLSRC1 CLSRC0 CLPOL(2) CLMOD bit 15 bit 8 R/W-1 R/W-1 R/W-1 R/W-1 R/W-1 R/W-0 R/W-0 R/W-0 FLTSRC4 FLTSRC3 FLTSRC2 FLTSRC1 FLTSRC0 FLTPOL(2) FLTMOD1 FLTMOD0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 Unimplemented: Read as ‘0’ bit 14-10 CLSRC<4:0>: Current-Limit Control Signal Source Select for PWM Generator # bits 11111 = Fault 32 11110 = Reserved • • • 01100 = Reserved 01011 = Comparator 4 01010 = Op Amp/Comparator 3 01001 = Op Amp/Comparator 2 01000 = Op Amp/Comparator 1 00111 = Reserved 00110 = Reserved 00101 = Reserved 00100 = Reserved 00011 = Fault 4 00010 = Fault 3 00001 = Fault 2 00000 = Fault 1 (default) bit 9 CLPOL: Current-Limit Polarity for PWM Generator # bit(2) 1 = The selected current-limit source is active-low 0 = The selected current-limit source is active-high bit 8 CLMOD: Current-Limit Mode Enable for PWM Generator # bit 1 = Current-Limit mode is enabled 0 = Current-Limit mode is disabled Note 1: If the PWMLOCK Configuration bit (FOSCSEL<6>) is a ‘1’, the IOCONx register can only be written after the unlock sequence has been executed. 2: These bits should be changed only when PTEN = 0. Changing the clock selection during operation will yield unpredictable results. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 244  2011-2013 Microchip Technology Inc. bit 7-3 FLTSRC<4:0>: Fault Control Signal Source Select for PWM Generator # bits 11111 = Fault 32 (default) 11110 = Reserved • • • 01100 = Reserved 01011 = Comparator 4 01010 = Op Amp/Comparator 3 01001 = Op Amp/Comparator 2 01000 = Op Amp/Comparator 1 00111 = Reserved 00110 = Reserved 00101 = Reserved 00100 = Reserved 00011 = Fault 4 00010 = Fault 3 00001 = Fault 2 00000 = Fault 1 bit 2 FLTPOL: Fault Polarity for PWM Generator # bit(2) 1 = The selected Fault source is active-low 0 = The selected Fault source is active-high bit 1-0 FLTMOD<1:0>: Fault Mode for PWM Generator # bits 11 = Fault input is disabled 10 = Reserved 01 = The selected Fault source forces PWMxH, PWMxL pins to FLTDAT values (cycle) 00 = The selected Fault source forces PWMxH, PWMxL pins to FLTDAT values (latched condition) REGISTER 16-15: FCLCONx: PWMx FAULT CURRENT-LIMIT CONTROL REGISTER(1) Note 1: If the PWMLOCK Configuration bit (FOSCSEL<6>) is a ‘1’, the IOCONx register can only be written after the unlock sequence has been executed. 2: These bits should be changed only when PTEN = 0. Changing the clock selection during operation will yield unpredictable results.  2011-2013 Microchip Technology Inc. DS70000657H-page 245 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 16-16: LEBCONx: PWMx LEADING-EDGE BLANKING CONTROL REGISTER R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 U-0 U-0 PHR PHF PLR PLF FLTLEBEN CLLEBEN — — bit 15 bit 8 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — BCH(1) BCL(1) BPHH BPHL BPLH BPLL bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 PHR: PWMxH Rising Edge Trigger Enable bit 1 = Rising edge of PWMxH will trigger Leading-Edge Blanking counter 0 = Leading-Edge Blanking ignores rising edge of PWMxH bit 14 PHF: PWMxH Falling Edge Trigger Enable bit 1 = Falling edge of PWMxH will trigger Leading-Edge Blanking counter 0 = Leading-Edge Blanking ignores falling edge of PWMxH bit 13 PLR: PWMxL Rising Edge Trigger Enable bit 1 = Rising edge of PWMxL will trigger Leading-Edge Blanking counter 0 = Leading-Edge Blanking ignores rising edge of PWMxL bit 12 PLF: PWMxL Falling Edge Trigger Enable bit 1 = Falling edge of PWMxL will trigger Leading-Edge Blanking counter 0 = Leading-Edge Blanking ignores falling edge of PWMxL bit 11 FLTLEBEN: Fault Input Leading-Edge Blanking Enable bit 1 = Leading-Edge Blanking is applied to selected Fault input 0 = Leading-Edge Blanking is not applied to selected Fault input bit 10 CLLEBEN: Current-Limit Leading-Edge Blanking Enable bit 1 = Leading-Edge Blanking is applied to selected current-limit input 0 = Leading-Edge Blanking is not applied to selected current-limit input bit 9-6 Unimplemented: Read as ‘0’ bit 5 BCH: Blanking in Selected Blanking Signal High Enable bit(1) 1 = State blanking (of current-limit and/or Fault input signals) when selected blanking signal is high 0 = No blanking when selected blanking signal is high bit 4 BCL: Blanking in Selected Blanking Signal Low Enable bit(1) 1 = State blanking (of current-limit and/or Fault input signals) when selected blanking signal is low 0 = No blanking when selected blanking signal is low bit 3 BPHH: Blanking in PWMxH High Enable bit 1 = State blanking (of current-limit and/or Fault input signals) when PWMxH output is high 0 = No blanking when PWMxH output is high bit 2 BPHL: Blanking in PWMxH Low Enable bit 1 = State blanking (of current-limit and/or Fault input signals) when PWMxH output is low 0 = No blanking when PWMxH output is low bit 1 BPLH: Blanking in PWMxL High Enable bit 1 = State blanking (of current-limit and/or Fault input signals) when PWMxL output is high 0 = No blanking when PWMxL output is high bit 0 BPLL: Blanking in PWMxL Low Enable bit 1 = State blanking (of current-limit and/or Fault input signals) when PWMxL output is low 0 = No blanking when PWMxL output is low Note 1: The blanking signal is selected via the BLANKSELx bits in the AUXCONx register. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 246  2011-2013 Microchip Technology Inc. REGISTER 16-17: LEBDLYx: PWMx LEADING-EDGE BLANKING DELAY REGISTER U-0 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 — — — — LEB<11:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 LEB<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-12 Unimplemented: Read as ‘0’ bit 11-0 LEB<11:0>: Leading-Edge Blanking Delay for Current-Limit and Fault Inputs bits  2011-2013 Microchip Technology Inc. DS70000657H-page 247 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 16-18: AUXCONx: PWMx AUXILIARY CONTROL REGISTER U-0 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 — — — — BLANKSEL3 BLANKSEL2 BLANKSEL1 BLANKSEL0 bit 15 bit 8 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — CHOPSEL3 CHOPSEL2 CHOPSEL1 CHOPSEL0 CHOPHEN CHOPLEN bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-12 Unimplemented: Read as ‘0’ bit 11-8 BLANKSEL<3:0>: PWMx State Blank Source Select bits The selected state blank signal will block the current-limit and/or Fault input signals (if enabled via the BCH and BCL bits in the LEBCONx register). 1001 = Reserved • • • 0100 = Reserved 0011 = PWM3H selected as state blank source 0010 = PWM2H selected as state blank source 0001 = PWM1H selected as state blank source 0000 = No state blanking bit 7-6 Unimplemented: Read as ‘0’ bit 5-2 CHOPSEL<3:0>: PWMx Chop Clock Source Select bits The selected signal will enable and disable (CHOP) the selected PWMx outputs. 1001 = Reserved • • • 0100 = Reserved 0011 = PWM3H selected as CHOP clock source 0010 = PWM2H selected as CHOP clock source 0001 = PWM1H selected as CHOP clock source 0000 = Chop clock generator selected as CHOP clock source bit 1 CHOPHEN: PWMxH Output Chopping Enable bit 1 = PWMxH chopping function is enabled 0 = PWMxH chopping function is disabled bit 0 CHOPLEN: PWMxL Output Chopping Enable bit 1 = PWMxL chopping function is enabled 0 = PWMxL chopping function is disabled dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 248  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 249 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 17.0 QUADRATURE ENCODER INTERFACE (QEI) MODULE (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X DEVICES ONLY) This chapter describes the Quadrature Encoder Interface (QEI) module and associated operational modes. The QEI module provides the interface to incremental encoders for obtaining mechanical position data. The operational features of the QEI module include: • 32-Bit Position Counter • 32-Bit Index Pulse Counter • 32-Bit Interval Timer • 16-Bit Velocity Counter • 32-Bit Position Initialization/Capture/Compare High register • 32-Bit Position Compare Low register • x4 Quadrature Count mode • External Up/Down Count mode • External Gated Count mode • External Gated Timer mode • Internal Timer mode Figure 17-1 illustrates the QEI block diagram. Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Quadrature Encoder Interface (QEI)” (DS70601) in the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. DS70000657H-page 250 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. FIGURE 17-1: QEI BLOCK DIAGRAM Quadrature Decoder Logic CNTCMPx QEBx QEAx INDXx COUNT DIR FP COUNT COUNT_EN 32-Bit Greater Than or Equal Compare Register 32-Bit Index Counter Register Digital Filter HOMEx FHOMEx Data Bus 32-Bit Greater Than Data Bus COUNT_EN CNT_DIR CNT_DIR FINDXx FINDXx PCHEQ 16-Bit Index Counter 32-Bit Interval Timer Hold Register 32-Bit Interval Timer Register Hold Register COUNT_EN FP PCHGE EXTCNT EXTCNT DIR_GATE 16-Bit Velocity CNT_DIR COUNT_EN Counter Register PCLLE PCHGE DIVCLK DIR CNT_DIR DIR_GATE 1’b0 PCLLE CNTPOL DIR_GATE GATEN 01 DIVCLK or Equal Comparator 32-Bit Less Than PCLLE or Equal Comparator PCLEQ PCHGE  QFDIV CCM  INTDIV (VEL1CNT) (INT1TMR) (INT1HLD) (INDX1CNT) (INDX1HLD) INDX1CNTH INDX1CNTL POS1CNTH POS1CNTL (QEI1GEC)(1) 32-Bit Less Than or Equal Compare Register (QEI1LEC) 16-Bit Position Counter Hold Register (POS1HLD) 32-Bit Initialization and Capture Register (QEI1IC)(1) QCAPEN Note 1: These registers map to the same memory location. OUTFNC FLTREN (POS1CNT) 32-Bit Position Counter Register  2011-2013 Microchip Technology Inc. DS70000657H-page 251 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 17.1 QEI Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 17.1.1 KEY RESOURCES • “Quadrature Encoder Interface” (DS70601) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 252  2011-2013 Microchip Technology Inc. 17.2 QEI Control Registers REGISTER 17-1: QEI1CON: QEI1 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 QEIEN — QEISIDL PIMOD2(1) PIMOD1(1) PIMOD0(1) IMV1(2) IMV0(2) bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — INTDIV2(3) INTDIV1(3) INTDIV0(3) CNTPOL GATEN CCM1 CCM0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 QEIEN: Quadrature Encoder Interface Module Counter Enable bit 1 = Module counters are enabled 0 = Module counters are disabled, but SFRs can be read or written to bit 14 Unimplemented: Read as ‘0’ bit 13 QEISIDL: QEI Stop in Idle Mode bit 1 = Discontinues module operation when device enters Idle mode 0 = Continues module operation in Idle mode bit 12-10 PIMOD<2:0>: Position Counter Initialization Mode Select bits(1) 111 = Reserved 110 = Modulo Count mode for position counter 101 = Resets the position counter when the position counter equals QEI1GEC register 100 = Second index event after home event initializes position counter with contents of QEI1IC register 011 = First index event after home event initializes position counter with contents of QEI1IC register 010 = Next index input event initializes the position counter with contents of QEI1IC register 001 = Every index input event resets the position counter 000 = Index input event does not affect position counter bit 9 IMV1: Index Match Value for Phase B bit(2) 1 = Phase B match occurs when QEB = 1 0 = Phase B match occurs when QEB = 0 bit 8 IMV0: Index Match Value for Phase A bit(2) 1 = Phase A match occurs when QEA = 1 0 = Phase A match occurs when QEA = 0 bit 7 Unimplemented: Read as ‘0’ Note 1: When CCM<1:0> = 10 or 11, all of the QEI counters operate as timers and the PIMOD<2:0> bits are ignored. 2: When CCM<1:0> = 00, and QEA and QEB values match the Index Match Value (IMV), the POSCNTH and POSCNTL registers are reset. QEA/QEB signals used for the index match have swap and polarity values applied, as determined by the SWPAB and QEAPOL/QEBPOL bits. 3: The selected clock rate should be at least twice the expected maximum quadrature count rate.  2011-2013 Microchip Technology Inc. DS70000657H-page 253 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 6-4 INTDIV<2:0>: Timer Input Clock Prescale Select bits (interval timer, main timer (position counter), velocity counter and index counter internal clock divider select)(3) 111 = 1:128 prescale value 110 = 1:64 prescale value 101 = 1:32 prescale value 100 = 1:16 prescale value 011 = 1:8 prescale value 010 = 1:4 prescale value 001 = 1:2 prescale value 000 = 1:1 prescale value bit 3 CNTPOL: Position and Index Counter/Timer Direction Select bit 1 = Counter direction is negative unless modified by external up/down signal 0 = Counter direction is positive unless modified by external up/down signal bit 2 GATEN: External Count Gate Enable bit 1 = External gate signal controls position counter operation 0 = External gate signal does not affect position counter/timer operation bit 1-0 CCM<1:0>: Counter Control Mode Selection bits 11 = Internal Timer mode with optional external count is selected 10 = External clock count with optional external count is selected 01 = External clock count with external up/down direction is selected 00 = Quadrature Encoder Interface (x4 mode) Count mode is selected REGISTER 17-1: QEI1CON: QEI1 CONTROL REGISTER (CONTINUED) Note 1: When CCM<1:0> = 10 or 11, all of the QEI counters operate as timers and the PIMOD<2:0> bits are ignored. 2: When CCM<1:0> = 00, and QEA and QEB values match the Index Match Value (IMV), the POSCNTH and POSCNTL registers are reset. QEA/QEB signals used for the index match have swap and polarity values applied, as determined by the SWPAB and QEAPOL/QEBPOL bits. 3: The selected clock rate should be at least twice the expected maximum quadrature count rate. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 254  2011-2013 Microchip Technology Inc. REGISTER 17-2: QEI1IOC: QEI1 I/O 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 QCAPEN FLTREN QFDIV2 QFDIV1 QFDIV0 OUTFNC1 OUTFNC0 SWPAB bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R-x R-x R-x R-x HOMPOL IDXPOL QEBPOL QEAPOL HOME INDEX QEB QEA bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 QCAPEN: QEI Position Counter Input Capture Enable bit 1 = Index match event triggers a position capture event 0 = Index match event does not trigger a position capture event bit 14 FLTREN: QEAx/QEBx/INDXx/HOMEx Digital Filter Enable bit 1 = Input pin digital filter is enabled 0 = Input pin digital filter is disabled (bypassed) bit 13-11 QFDIV<2:0>: QEAx/QEBx/INDXx/HOMEx Digital Input Filter Clock Divide Select bits 111 = 1:128 clock divide 110 = 1:64 clock divide 101 = 1:32 clock divide 100 = 1:16 clock divide 011 = 1:8 clock divide 010 = 1:4 clock divide 001 = 1:2 clock divide 000 = 1:1 clock divide bit 10-9 OUTFNC<1:0>: QEI Module Output Function Mode Select bits 11 = The CTNCMPx pin goes high when QEI1LEC  POS1CNT  QEI1GEC 10 = The CTNCMPx pin goes high when POS1CNT  QEI1LEC 01 = The CTNCMPx pin goes high when POS1CNT  QEI1GEC 00 = Output is disabled bit 8 SWPAB: Swap QEA and QEB Inputs bit 1 = QEAx and QEBx are swapped prior to quadrature decoder logic 0 = QEAx and QEBx are not swapped bit 7 HOMPOL: HOMEx Input Polarity Select bit 1 = Input is inverted 0 = Input is not inverted bit 6 IDXPOL: INDXx Input Polarity Select bit 1 = Input is inverted 0 = Input is not inverted bit 5 QEBPOL: QEBx Input Polarity Select bit 1 = Input is inverted 0 = Input is not inverted bit 4 QEAPOL: QEAx Input Polarity Select bit 1 = Input is inverted 0 = Input is not inverted bit 3 HOME: Status of HOMEx Input Pin After Polarity Control 1 = Pin is at logic ‘1’ 0 = Pin is at logic ‘0’  2011-2013 Microchip Technology Inc. DS70000657H-page 255 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 2 INDEX: Status of INDXx Input Pin After Polarity Control 1 = Pin is at logic ‘1’ 0 = Pin is at logic ‘0’ bit 1 QEB: Status of QEBx Input Pin After Polarity Control And SWPAB Pin Swapping 1 = Pin is at logic ‘1’ 0 = Pin is at logic ‘0’ bit 0 QEA: Status of QEAx Input Pin After Polarity Control And SWPAB Pin Swapping 1 = Pin is at logic ‘1’ 0 = Pin is at logic ‘0’ REGISTER 17-2: QEI1IOC: QEI1 I/O CONTROL REGISTER (CONTINUED) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 256  2011-2013 Microchip Technology Inc. REGISTER 17-3: QEI1STAT: QEI1 STATUS REGISTER U-0 U-0 HS, R/C-0 R/W-0 HS, R/C-0 R/W-0 HS, R/C-0 R/W-0 — — PCHEQIRQ PCHEQIEN PCLEQIRQ PCLEQIEN POSOVIRQ POSOVIEN bit 15 bit 8 HS, R/C-0 R/W-0 HS, R/C-0 R/W-0 HS, R/C-0 R/W-0 HS, R/C-0 R/W-0 PCIIRQ(1) PCIIEN VELOVIRQ VELOVIEN HOMIRQ HOMIEN IDXIRQ IDXIEN bit 7 bit 0 Legend: HS = Hardware Settable bit C = Clearable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13 PCHEQIRQ: Position Counter Greater Than or Equal Compare Status bit 1 = POS1CNT ≥ QEI1GEC 0 = POS1CNT < QEI1GEC bit 12 PCHEQIEN: Position Counter Greater Than or Equal Compare Interrupt Enable bit 1 = Interrupt is enabled 0 = Interrupt is disabled bit 11 PCLEQIRQ: Position Counter Less Than or Equal Compare Status bit 1 = POS1CNT ≤ QEI1LEC 0 = POS1CNT > QEI1LEC bit 10 PCLEQIEN: Position Counter Less Than or Equal Compare Interrupt Enable bit 1 = Interrupt is enabled 0 = Interrupt is disabled bit 9 POSOVIRQ: Position Counter Overflow Status bit 1 = Overflow has occurred 0 = No overflow has occurred bit 8 POSOVIEN: Position Counter Overflow Interrupt Enable bit 1 = Interrupt is enabled 0 = Interrupt is disabled bit 7 PCIIRQ: Position Counter (Homing) Initialization Process Complete Status bit(1) 1 = POS1CNT was reinitialized 0 = POS1CNT was not reinitialized bit 6 PCIIEN: Position Counter (Homing) Initialization Process Complete interrupt Enable bit 1 = Interrupt is enabled 0 = Interrupt is disabled bit 5 VELOVIRQ: Velocity Counter Overflow Status bit 1 = Overflow has occurred 0 = No overflow has not occurred bit 4 VELOVIEN: Velocity Counter Overflow Interrupt Enable bit 1 = Interrupt is enabled 0 = Interrupt is disabled bit 3 HOMIRQ: Status Flag for Home Event Status bit 1 = Home event has occurred 0 = No Home event has occurred Note 1: This status bit is only applicable to PIMOD<2:0> modes, ‘011’ and ‘100’.  2011-2013 Microchip Technology Inc. DS70000657H-page 257 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 2 HOMIEN: Home Input Event Interrupt Enable bit 1 = Interrupt is enabled 0 = Interrupt is disabled bit 1 IDXIRQ: Status Flag for Index Event Status bit 1 = Index event has occurred 0 = No Index event has occurred bit 0 IDXIEN: Index Input Event Interrupt Enable bit 1 = Interrupt is enabled 0 = Interrupt is disabled REGISTER 17-3: QEI1STAT: QEI1 STATUS REGISTER (CONTINUED) Note 1: This status bit is only applicable to PIMOD<2:0> modes, ‘011’ and ‘100’. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 258  2011-2013 Microchip Technology Inc. REGISTER 17-4: POS1CNTH: POSITION COUNTER 1 HIGH WORD 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 POSCNT<31:24> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 POSCNT<23:16> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 POSCNT<31:16>: High Word Used to Form 32-Bit Position Counter Register (POS1CNT) bits REGISTER 17-5: POS1CNTL: POSITION COUNTER 1 LOW WORD 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 POSCNT<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 POSCNT<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 POSCNT<15:0>: Low Word Used to Form 32-Bit Position Counter Register (POS1CNT) bits REGISTER 17-6: POS1HLD: POSITION COUNTER 1 HOLD 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 POSHLD<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 POSHLD<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 POSHLD<15:0>: Hold Register for Reading and Writing POS1CNTH bits  2011-2013 Microchip Technology Inc. DS70000657H-page 259 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 17-7: VEL1CNT: VELOCITY COUNTER 1 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 VELCNT<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 VELCNT<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 VELCNT<15:0>: Velocity Counter bits REGISTER 17-8: INDX1CNTH: INDEX COUNTER 1 HIGH WORD 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 INDXCNT<31:24> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 INDXCNT<23:16> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 INDXCNT<31:16>: High Word Used to Form 32-Bit Index Counter Register (INDX1CNT) bits REGISTER 17-9: INDX1CNTL: INDEX COUNTER 1 LOW WORD 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 INDXCNT<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 INDXCNT<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 INDXCNT<15:0>: Low Word Used to Form 32-Bit Index Counter Register (INDX1CNT) bits dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 260  2011-2013 Microchip Technology Inc. REGISTER 17-10: INDX1HLD: INDEX COUNTER 1 HOLD 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 INDXHLD<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 INDXHLD<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 INDXHLD<15:0>: Hold Register for Reading and Writing INDX1CNTH bits REGISTER 17-11: QEI1ICH: QEI1 INITIALIZATION/CAPTURE HIGH WORD 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 QEIIC<31:24> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 QEIIC<23:16> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 QEIIC<31:16>: High Word Used to Form 32-Bit Initialization/Capture Register (QEI1IC) bits REGISTER 17-12: QEI1ICL: QEI1 INITIALIZATION/CAPTURE LOW WORD 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 QEIIC<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 QEIIC<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 QEIIC<15:0>: Low Word Used to Form 32-Bit Initialization/Capture Register (QEI1IC) bits  2011-2013 Microchip Technology Inc. DS70000657H-page 261 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 17-13: QEI1LECH: QEI1 LESS THAN OR EQUAL COMPARE HIGH WORD 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 QEILEC<31:24> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 QEILEC<23:16> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 QEILEC<31:16>: High Word Used to Form 32-Bit Less Than or Equal Compare Register (QEI1LEC) bits REGISTER 17-14: QEI1LECL: QEI1 LESS THAN OR EQUAL COMPARE LOW WORD 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 QEILEC<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 QEILEC<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 QEILEC<15:0>: Low Word Used to Form 32-Bit Less Than or Equal Compare Register (QEI1LEC) bits dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 262  2011-2013 Microchip Technology Inc. REGISTER 17-15: QEI1GECH: QEI1 GREATER THAN OR EQUAL COMPARE HIGH WORD 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 QEIGEC<31:24> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 QEIGEC<23:16> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 QEIGEC<31:16>: High Word Used to Form 32-Bit Greater Than or Equal Compare Register (QEI1GEC) bits REGISTER 17-16: QEI1GECL: QEI1 GREATER THAN OR EQUAL COMPARE LOW WORD 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 QEIGEC<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 QEIGEC<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 QEIGEC<15:0>: Low Word Used to Form 32-Bit Greater Than or Equal Compare Register (QEI1GEC) bits  2011-2013 Microchip Technology Inc. DS70000657H-page 263 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 17-17: INT1TMRH: INTERVAL 1 TIMER HIGH WORD 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 INTTMR<31:24> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 INTTMR<23:16> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 INTTMR<31:16>: High Word Used to Form 32-Bit Interval Timer Register (INT1TMR) bits REGISTER 17-18: INT1TMRL: INTERVAL 1 TIMER LOW WORD 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 INTTMR<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 INTTMR<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 INTTMR<15:0>: Low Word Used to Form 32-Bit Interval Timer Register (INT1TMR) bits dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 264  2011-2013 Microchip Technology Inc. REGISTER 17-19: INT1HLDH: INTERVAL 1 TIMER HOLD HIGH WORD 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 INTHLD<31:24> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 INTHLD<23:16> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 INTHLD<31:16>: Hold Register for Reading and Writing INT1TMRH bits REGISTER 17-20: INT1HLDL: INTERVAL 1 TIMER HOLD LOW WORD 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 INTHLD<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 INTHLD<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 INTHLD<15:0>: Hold Register for Reading and Writing INT1TMRL bits  2011-2013 Microchip Technology Inc. DS70000657H-page 265 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 18.0 SERIAL PERIPHERAL INTERFACE (SPI) The SPI module is a synchronous serial interface, useful for communicating with other peripheral or microcontroller devices. These peripheral devices can be serial EEPROMs, shift registers, display drivers, ADC Converters, etc. The SPI module is compatible with Motorola® SPI and SIOP interfaces. The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X device family offers two SPI modules on a single device. These modules, which are designated as SPI1 and SPI2, are functionally identical. Each SPI module includes an eight-word FIFO buffer and allows DMA bus connections. When using the SPI module with DMA, FIFO operation can be disabled. The SPI1 module uses dedicated pins which allow for a higher speed when using SPI1. The SPI2 module takes advantage of the Peripheral Pin Select (PPS) feature to allow for greater flexibility in pin configuration of the SPI2 module, but results in a lower maximum speed for SPI2. See Section 30.0 “Electrical Characteristics” for more information. The SPIx serial interface consists of four pins, as follows: • SDIx: Serial Data Input • SDOx: Serial Data Output • SCKx: Shift Clock Input or Output • SSx/FSYNCx: Active-Low Slave Select or Frame Synchronization I/O Pulse The SPIx module can be configured to operate with two, three or four pins. In 3-pin mode, SSx is not used. In 2-pin mode, neither SDOx nor SSx is used. Figure 18-1 illustrates the block diagram of the SPIx module in Standard and Enhanced modes. Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Serial Peripheral Interface (SPI)” (DS70569) in the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. Note: In this section, the SPI modules are referred to together as SPIx, or separately as SPI1 and SPI2. Special Function Registers follow a similar notation. For example, SPIxCON refers to the control register for the SPI1 and SPI2 modules. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 266  2011-2013 Microchip Technology Inc. FIGURE 18-1: SPIx MODULE BLOCK DIAGRAM Internal Data Bus SDIx SDOx SSx/FSYNCx SCKx bit 0 Shift Control Edge Select Primary FP 1:1/4/16/64 Enable Prescaler Sync Control Transfer Transfer Read SPIxBUF Write SPIxBUF 16 SPIxCON1<1:0> SPIxCON1<4:2> Master Clock Note 1: In Standard mode, the FIFO is only one level deep. Clock Control Secondary Prescaler 1:1 to 1:8 SPIxSR 8-Level FIFO Receive Buffer(1) 8-Level FIFO Transmit Buffer(1) SPIxBUF  2011-2013 Microchip Technology Inc. DS70000657H-page 267 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 18.1 SPI Helpful Tips 1. In Frame mode, if there is a possibility that the master may not be initialized before the slave: a) If FRMPOL (SPIxCON2<13>) = 1, use a pull-down resistor on SSx. b) If FRMPOL = 0, use a pull-up resistor on SSx. 2. In Non-Framed 3-Wire mode, (i.e., not using SSx from a master): a) If CKP (SPIxCON1<6>) = 1, always place a pull-up resistor on SSx. b) If CKP = 0, always place a pull-down resistor on SSx. 3. FRMEN (SPIxCON2<15>) = 1 and SSEN (SPIxCON1<7>) = 1 are exclusive and invalid. In Frame mode, SCKx is continuous and the Frame Sync pulse is active on the SSx pin, which indicates the start of a data frame. 4. In Master mode only, set the SMP bit (SPIxCON1<9>) to a ‘1’ for the fastest SPIx data rate possible. The SMP bit can only be set at the same time or after the MSTEN bit (SPIxCON1<5>) is set. To avoid invalid slave read data to the master, the user’s master software must ensure enough time for slave software to fill its write buffer before the user application initiates a master write/read cycle. It is always advisable to preload the SPIxBUF Transmit register in advance of the next master transaction cycle. SPIxBUF is transferred to the SPIx Shift register and is empty once the data transmission begins. 18.2 SPI Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 18.2.1 KEY RESOURCES • “Serial Peripheral Interface (SPI)” (DS70569) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: This insures that the first frame transmission after initialization is not shifted or corrupted. Note: This will insure that during power-up and initialization the master/slave will not lose Sync due to an errant SCKx transition that would cause the slave to accumulate data shift errors for both transmit and receive appearing as corrupted data. Note: Not all third-party devices support Frame mode timing. Refer to the SPIx specifications in Section 30.0 “Electrical Characteristics” for details. Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 268  2011-2013 Microchip Technology Inc. 18.3 SPIx Control Registers REGISTER 18-1: SPIxSTAT: SPIx STATUS AND CONTROL REGISTER R/W-0 U-0 R/W-0 U-0 U-0 R/W-0 R/W-0 R/W-0 SPIEN — SPISIDL — — SPIBEC<2:0> bit 15 bit 8 R/W-0 R/C-0, HS R/W-0 R/W-0 R/W-0 R/W-0 R-0, HS, HC R-0, HS, HC SRMPT SPIROV SRXMPT SISEL2 SISEL1 SISEL0 SPITBF SPIRBF bit 7 bit 0 Legend: C = Clearable bit HS = Hardware Settable bit HC = Hardware Clearable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 SPIEN: SPIx Enable bit 1 = Enables the module and configures SCKx, SDOx, SDIx and SSx as serial port pins 0 = Disables the module bit 14 Unimplemented: Read as ‘0’ bit 13 SPISIDL: SPIx Stop in Idle Mode bit 1 = Discontinues the module operation when device enters Idle mode 0 = Continues the module operation in Idle mode bit 12-11 Unimplemented: Read as ‘0’ bit 10-8 SPIBEC<2:0>: SPIx Buffer Element Count bits (valid in Enhanced Buffer mode) Master mode: Number of SPIx transfers that are pending. Slave mode: Number of SPIx transfers that are unread. bit 7 SRMPT: SPIx Shift Register (SPIxSR) Empty bit (valid in Enhanced Buffer mode) 1 = SPIx Shift register is empty and Ready-To-Send or receive the data 0 = SPIx Shift register is not empty bit 6 SPIROV: SPIx Receive Overflow Flag bit 1 = A new byte/word is completely received and discarded; the user application has not read the previous data in the SPIxBUF register 0 = No overflow has occurred bit 5 SRXMPT: SPIx Receive FIFO Empty bit (valid in Enhanced Buffer mode) 1 = RX FIFO is empty 0 = RX FIFO is not empty bit 4-2 SISEL<2:0>: SPIx Buffer Interrupt Mode bits (valid in Enhanced Buffer mode) 111 = Interrupt when the SPIx transmit buffer is full (SPITBF bit is set) 110 = Interrupt when last bit is shifted into SPIxSR and as a result, the TX FIFO is empty 101 = Interrupt when the last bit is shifted out of SPIxSR and the transmit is complete 100 = Interrupt when one data is shifted into the SPIxSR and as a result, the TX FIFO has one open memory location 011 = Interrupt when the SPIx receive buffer is full (SPIRBF bit is set) 010 = Interrupt when the SPIx receive buffer is 3/4 or more full 001 = Interrupt when data is available in the receive buffer (SRMPT bit is set) 000 = Interrupt when the last data in the receive buffer is read and as a result, the buffer is empty (SRXMPT bit is set)  2011-2013 Microchip Technology Inc. DS70000657H-page 269 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 1 SPITBF: SPIx Transmit Buffer Full Status bit 1 = Transmit not yet started, SPIxTXB is full 0 = Transmit started, SPIxTXB is empty Standard Buffer mode: Automatically set in hardware when core writes to the SPIxBUF location, loading SPIxTXB. Automatically cleared in hardware when SPIx module transfers data from SPIxTXB to SPIxSR. Enhanced Buffer mode: Automatically set in hardware when the CPU writes to the SPIxBUF location, loading the last available buffer location. Automatically cleared in hardware when a buffer location is available for a CPU write operation. bit 0 SPIRBF: SPIx Receive Buffer Full Status bit 1 = Receive is complete, SPIxRXB is full 0 = Receive is incomplete, SPIxRXB is empty Standard Buffer mode: Automatically set in hardware when SPIx transfers data from SPIxSR to SPIxRXB. Automatically cleared in hardware when the core reads the SPIxBUF location, reading SPIxRXB. Enhanced Buffer mode: Automatically set in hardware when SPIx transfers data from SPIxSR to the buffer, filling the last unread buffer location. Automatically cleared in hardware when a buffer location is available for a transfer from SPIxSR. REGISTER 18-1: SPIxSTAT: SPIx STATUS AND CONTROL REGISTER (CONTINUED) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 270  2011-2013 Microchip Technology Inc. REGISTER 18-2: SPIXCON1: SPIX CONTROL REGISTER 1 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — — DISSCK DISSDO MODE16 SMP CKE(1) bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 SSEN(2) CKP MSTEN SPRE2(3) SPRE1(3) SPRE0(3) PPRE1(3) PPRE0(3) bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-13 Unimplemented: Read as ‘0’ bit 12 DISSCK: Disable SCKx Pin bit (SPIx Master modes only) 1 = Internal SPIx clock is disabled, pin functions as I/O 0 = Internal SPIx clock is enabled bit 11 DISSDO: Disable SDOx Pin bit 1 = SDOx pin is not used by the module; pin functions as I/O 0 = SDOx pin is controlled by the module bit 10 MODE16: Word/Byte Communication Select bit 1 = Communication is word-wide (16 bits) 0 = Communication is byte-wide (8 bits) bit 9 SMP: SPIx Data Input Sample Phase bit Master mode: 1 = Input data is sampled at end of data output time 0 = Input data is sampled at middle of data output time Slave mode: SMP must be cleared when SPIx is used in Slave mode. bit 8 CKE: SPIx Clock Edge Select bit(1) 1 = Serial output data changes on transition from active clock state to Idle clock state (refer to bit 6) 0 = Serial output data changes on transition from Idle clock state to active clock state (refer to bit 6) bit 7 SSEN: Slave Select Enable bit (Slave mode)(2) 1 = SSx pin is used for Slave mode 0 = SSx pin is not used by the module; pin is controlled by port function bit 6 CKP: Clock Polarity Select bit 1 = Idle state for clock is a high level; active state is a low level 0 = Idle state for clock is a low level; active state is a high level bit 5 MSTEN: Master Mode Enable bit 1 = Master mode 0 = Slave mode Note 1: The CKE bit is not used in Framed SPI modes. Program this bit to ‘0’ for Framed SPI modes (FRMEN = 1). 2: This bit must be cleared when FRMEN = 1. 3: Do not set both primary and secondary prescalers to the value of 1:1.  2011-2013 Microchip Technology Inc. DS70000657H-page 271 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 4-2 SPRE<2:0>: Secondary Prescale bits (Master mode)(3) 111 = Secondary prescale 1:1 110 = Secondary prescale 2:1 • • • 000 = Secondary prescale 8:1 bit 1-0 PPRE<1:0>: Primary Prescale bits (Master mode)(3) 11 = Primary prescale 1:1 10 = Primary prescale 4:1 01 = Primary prescale 16:1 00 = Primary prescale 64:1 REGISTER 18-2: SPIXCON1: SPIX CONTROL REGISTER 1 (CONTINUED) Note 1: The CKE bit is not used in Framed SPI modes. Program this bit to ‘0’ for Framed SPI modes (FRMEN = 1). 2: This bit must be cleared when FRMEN = 1. 3: Do not set both primary and secondary prescalers to the value of 1:1. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 272  2011-2013 Microchip Technology Inc. REGISTER 18-3: SPIXCON2: SPIX CONTROL REGISTER 2 R/W-0 R/W-0 R/W-0 U-0 U-0 U-0 U-0 U-0 FRMEN SPIFSD FRMPOL — — — — — bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 U-0 R/W-0 R/W-0 — — — — — — FRMDLY SPIBEN bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 FRMEN: Framed SPIx Support bit 1 = Framed SPIx support is enabled (SSx pin is used as Frame Sync pulse input/output) 0 = Framed SPIx support is disabled bit 14 SPIFSD: Frame Sync Pulse Direction Control bit 1 = Frame Sync pulse input (slave) 0 = Frame Sync pulse output (master) bit 13 FRMPOL: Frame Sync Pulse Polarity bit 1 = Frame Sync pulse is active-high 0 = Frame Sync pulse is active-low bit 12-2 Unimplemented: Read as ‘0’ bit 1 FRMDLY: Frame Sync Pulse Edge Select bit 1 = Frame Sync pulse coincides with first bit clock 0 = Frame Sync pulse precedes first bit clock bit 0 SPIBEN: Enhanced Buffer Enable bit 1 = Enhanced buffer is enabled 0 = Enhanced buffer is disabled (Standard mode)  2011-2013 Microchip Technology Inc. DS70000657H-page 273 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 19.0 INTER-INTEGRATED CIRCUIT™ (I2C™) The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X family of devices contains two Inter-Integrated Circuit (I2C) modules: I2C1 and I2C2. The I2C module provides complete hardware support for both Slave and Multi-Master modes of the I2C serial communication standard, with a 16-bit interface. The I2C module has a 2-pin interface: • The SCLx pin is clock • The SDAx pin is data The I2C module offers the following key features: • I2C interface supporting both Master and Slave modes of operation • I2C Slave mode supports 7 and 10-bit addressing • I2C Master mode supports 7 and 10-bit addressing • I2C port allows bidirectional transfers between master and slaves • Serial clock synchronization for I2C port can be used as a handshake mechanism to suspend and resume serial transfer (SCLREL control) • I2C supports multi-master operation, detects bus collision and arbitrates accordingly • Intelligent Platform Management Interface (IPMI) support • System Management Bus (SMBus) support Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Inter-Integrated Circuit™ (I2C™)” (DS70330) in the “dsPIC33/ PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. 3: There are minimum bit rates of approximately FCY/512. As a result, high processor speeds may not support 100 Kbit/second operation. See timing specifications, IM10 and IM11, and the “Baud Rate Generator” in the “dsPIC33/ PIC24 Family Reference Manual”. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 274  2011-2013 Microchip Technology Inc. FIGURE 19-1: I2Cx BLOCK DIAGRAM (X = 1 OR 2) Internal Data Bus SCLx/ASCLx SDAx/ASDAx Shift Match Detect Start and Stop Bit Detect Clock Address Match Clock Stretching I2CxTRN LSb Shift Clock BRG Down Counter Reload Control FP/2 Start and Stop Bit Generation Acknowledge Generation Collision Detect I2CxCON I2CxSTAT Control Logic Read LSb Write Read I2CxBRG I2CxRSR Write Read Write Read Write Read Write Read Write Read I2CxMSK I2CxRCV I2CxADD  2011-2013 Microchip Technology Inc. DS70000657H-page 275 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 19.1 I2C Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 19.1.1 KEY RESOURCES • “Inter-Integrated Circuit (I2C)” (DS70330) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 276  2011-2013 Microchip Technology Inc. 19.2 I2C Control Registers REGISTER 19-1: I2CxCON: I2Cx CONTROL REGISTER R/W-0 U-0 R/W-0 R/W-1, HC R/W-0 R/W-0 R/W-0 R/W-0 I2CEN — I2CSIDL SCLREL IPMIEN(1) A10M DISSLW SMEN bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0, HC R/W-0, HC R/W-0, HC R/W-0, HC R/W-0, HC GCEN STREN ACKDT ACKEN RCEN PEN RSEN SEN bit 7 bit 0 Legend: HC = Hardware Clearable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 I2CEN: I2Cx Enable bit 1 = Enables the I2Cx module and configures the SDAx and SCLx pins as serial port pins 0 = Disables the I2Cx module; all I2C™ pins are controlled by port functions bit 14 Unimplemented: Read as ‘0’ bit 13 I2CSIDL: I2Cx Stop in Idle Mode bit 1 = Discontinues module operation when device enters an Idle mode 0 = Continues module operation in Idle mode bit 12 SCLREL: SCLx Release Control bit (when operating as I2C slave) 1 = Releases SCLx clock 0 = Holds SCLx clock low (clock stretch) If STREN = 1: Bit is R/W (i.e., software can write ‘0’ to initiate stretch and write ‘1’ to release clock). Hardware is clear at the beginning of every slave data byte transmission. Hardware is clear at the end of every slave address byte reception. Hardware is clear at the end of every slave data byte reception. If STREN = 0: Bit is R/S (i.e., software can only write ‘1’ to release clock). Hardware is clear at the beginning of every slave data byte transmission. Hardware is clear at the end of every slave address byte reception. bit 11 IPMIEN: Intelligent Peripheral Management Interface (IPMI) Enable bit(1) 1 = IPMI mode is enabled; all addresses are Acknowledged 0 = IPMI mode disabled bit 10 A10M: 10-Bit Slave Address bit 1 = I2CxADD is a 10-bit slave address 0 = I2CxADD is a 7-bit slave address bit 9 DISSLW: Disable Slew Rate Control bit 1 = Slew rate control is disabled 0 = Slew rate control is enabled bit 8 SMEN: SMBus Input Levels bit 1 = Enables I/O pin thresholds compliant with SMBus specification 0 = Disables SMBus input thresholds bit 7 GCEN: General Call Enable bit (when operating as I2C slave) 1 = Enables interrupt when a general call address is received in I2CxRSR (module is enabled for reception) 0 = General call address disabled Note 1: When performing master operations, ensure that the IPMIEN bit is set to ‘0’.  2011-2013 Microchip Technology Inc. DS70000657H-page 277 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 6 STREN: SCLx Clock Stretch Enable bit (when operating as I2C slave) Used in conjunction with the SCLREL bit. 1 = Enables software or receives clock stretching 0 = Disables software or receives clock stretching bit 5 ACKDT: Acknowledge Data bit (when operating as I2C master, applicable during master receive) Value that is transmitted when the software initiates an Acknowledge sequence. 1 = Sends NACK during Acknowledge 0 = Sends ACK during Acknowledge bit 4 ACKEN: Acknowledge Sequence Enable bit (when operating as I2C master, applicable during master receive) 1 = Initiates Acknowledge sequence on SDAx and SCLx pins and transmits ACKDT data bit. Hardware is clear at the end of the master Acknowledge sequence. 0 = Acknowledge sequence is not in progress bit 3 RCEN: Receive Enable bit (when operating as I2C master) 1 = Enables Receive mode for I2C. Hardware is clear at the end of the eighth bit of the master receive data byte. 0 = Receive sequence is not in progress bit 2 PEN: Stop Condition Enable bit (when operating as I2C master) 1 = Initiates Stop condition on SDAx and SCLx pins. Hardware is clear at the end of the master Stop sequence. 0 = Stop condition is not in progress bit 1 RSEN: Repeated Start Condition Enable bit (when operating as I2C master) 1 = Initiates Repeated Start condition on SDAx and SCLx pins. Hardware is clear at the end of the master Repeated Start sequence. 0 = Repeated Start condition is not in progress bit 0 SEN: Start Condition Enable bit (when operating as I2C master) 1 = Initiates Start condition on SDAx and SCLx pins. Hardware is clear at the end of the master Start sequence. 0 = Start condition is not in progress REGISTER 19-1: I2CxCON: I2Cx CONTROL REGISTER (CONTINUED) Note 1: When performing master operations, ensure that the IPMIEN bit is set to ‘0’. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 278  2011-2013 Microchip Technology Inc. REGISTER 19-2: I2CxSTAT: I2Cx STATUS REGISTER R-0, HSC R-0, HSC U-0 U-0 U-0 R/C-0, HS R-0, HSC R-0, HSC ACKSTAT TRSTAT — — — BCL GCSTAT ADD10 bit 15 bit 8 R/C-0, HS R/C-0, HS R-0, HSC R/C-0, HSC R/C-0, HSC R-0, HSC R-0, HSC R-0, HSC IWCOL I2COV D_A P S R_W RBF TBF bit 7 bit 0 Legend: C = Clearable bit HS = Hardware Settable bit HSC = Hardware Settable/Clearable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 ACKSTAT: Acknowledge Status bit (when operating as I2C™ master, applicable to master transmit operation) 1 = NACK received from slave 0 = ACK received from slave Hardware is set or clear at the end of slave Acknowledge. bit 14 TRSTAT: Transmit Status bit (when operating as I2C master, applicable to master transmit operation) 1 = Master transmit is in progress (8 bits + ACK) 0 = Master transmit is not in progress Hardware is set at the beginning of master transmission. Hardware is clear at the end of slave Acknowledge. bit 13-11 Unimplemented: Read as ‘0’ bit 10 BCL: Master Bus Collision Detect bit 1 = A bus collision has been detected during a master operation 0 = No bus collision detected Hardware is set at detection of a bus collision. bit 9 GCSTAT: General Call Status bit 1 = General call address was received 0 = General call address was not received Hardware is set when address matches general call address. Hardware is clear at Stop detection. bit 8 ADD10: 10-Bit Address Status bit 1 = 10-bit address was matched 0 = 10-bit address was not matched Hardware is set at the match of the 2nd byte of the matched 10-bit address. Hardware is clear at Stop detection. bit 7 IWCOL: I2Cx Write Collision Detect bit 1 = An attempt to write to the I2CxTRN register failed because the I2C module is busy 0 = No collision Hardware is set at the occurrence of a write to I2CxTRN while busy (cleared by software). bit 6 I2COV: I2Cx Receive Overflow Flag bit 1 = A byte was received while the I2CxRCV register was still holding the previous byte 0 = No overflow Hardware is set at an attempt to transfer I2CxRSR to I2CxRCV (cleared by software). bit 5 D_A: Data/Address bit (when operating as I2C slave) 1 = Indicates that the last byte received was data 0 = Indicates that the last byte received was a device address Hardware is clear at a device address match. Hardware is set by reception of a slave byte. bit 4 P: Stop bit 1 = Indicates that a Stop bit has been detected last 0 = Stop bit was not detected last Hardware is set or clear when a Start, Repeated Start or Stop is detected.  2011-2013 Microchip Technology Inc. DS70000657H-page 279 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 3 S: Start bit 1 = Indicates that a Start (or Repeated Start) bit has been detected last 0 = Start bit was not detected last Hardware is set or clear when a Start, Repeated Start or Stop is detected. bit 2 R_W: Read/Write Information bit (when operating as I2C slave) 1 = Read – Indicates data transfer is output from the slave 0 = Write – Indicates data transfer is input to the slave Hardware is set or clear after reception of an I2C device address byte. bit 1 RBF: Receive Buffer Full Status bit 1 = Receive is complete, I2CxRCV is full 0 = Receive is not complete, I2CxRCV is empty Hardware is set when I2CxRCV is written with a received byte. Hardware is clear when software reads I2CxRCV. bit 0 TBF: Transmit Buffer Full Status bit 1 = Transmit in progress, I2CxTRN is full 0 = Transmit is complete, I2CxTRN is empty Hardware is set when software writes to I2CxTRN. Hardware is clear at completion of a data transmission. REGISTER 19-2: I2CxSTAT: I2Cx STATUS REGISTER (CONTINUED) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 280  2011-2013 Microchip Technology Inc. REGISTER 19-3: I2CxMSK: I2Cx SLAVE MODE ADDRESS MASK REGISTER U-0 U-0 U-0 U-0 U-0 U-0 R/W-0 R/W-0 — — — — — — AMSK9 AMSK8 bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 AMSK7 AMSK6 AMSK5 AMSK4 AMSK3 AMSK2 AMSK1 AMSK0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-10 Unimplemented: Read as ‘0’ bit 9-0 AMSK<9:0>: Address Mask Select bits For 10-Bit Address: 1 = Enables masking for bit Ax of incoming message address; bit match is not required in this position 0 = Disables masking for bit Ax; bit match is required in this position For 7-Bit Address (I2CxMSK<6:0> only): 1 = Enables masking for bit Ax + 1 of incoming message address; bit match is not required in this position 0 = Disables masking for bit Ax + 1; bit match is required in this position  2011-2013 Microchip Technology Inc. DS70000657H-page 281 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 20.0 UNIVERSAL ASYNCHRONOUS RECEIVER TRANSMITTER (UART) The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X family of devices contains two UART modules. The Universal Asynchronous Receiver Transmitter (UART) module is one of the serial I/O modules available in the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X device family. The UART is a full-duplex, asynchronous system that can communicate with peripheral devices, such as personal computers, LIN/J2602, RS-232 and RS-485 interfaces. The module also supports a hardware flow control option with the UxCTS and UxRTS pins, and also includes an IrDA® encoder and decoder. The primary features of the UARTx module are: • Full-Duplex, 8 or 9-Bit Data Transmission through the UxTX and UxRX Pins • Even, Odd or No Parity Options (for 8-bit data) • One or Two Stop bits • Hardware Flow Control Option with UxCTS and UxRTS Pins • Fully Integrated Baud Rate Generator with 16-Bit Prescaler • Baud Rates Ranging from 4.375 Mbps to 67 bps at 16x mode at 70 MIPS • Baud Rates Ranging from 17.5 Mbps to 267 bps at 4x mode at 70 MIPS • 4-Deep First-In First-Out (FIFO) Transmit Data Buffer • 4-Deep FIFO Receive Data Buffer • Parity, Framing and Buffer Overrun Error Detection • Support for 9-bit mode with Address Detect (9th bit = 1) • Transmit and Receive Interrupts • A Separate Interrupt for all UARTx Error Conditions • Loopback mode for Diagnostic Support • Support for Sync and Break Characters • Support for Automatic Baud Rate Detection • IrDA® Encoder and Decoder Logic • 16x Baud Clock Output for IrDA Support A simplified block diagram of the UARTx module is shown in Figure 20-1. The UARTx module consists of these key hardware elements: • Baud Rate Generator • Asynchronous Transmitter • Asynchronous Receiver FIGURE 20-1: UARTx SIMPLIFIED BLOCK DIAGRAM Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “UART” (DS70582) in the “dsPIC33/ PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. Note: Hardware flow control using UxRTS and UxCTS is not available on all pin count devices. See the “Pin Diagrams” section for availability. UxRX Hardware Flow Control UARTx Receiver UARTx Transmitter UxTX Baud Rate Generator UxRTS/BCLKx UxCTS IrDA® dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 282  2011-2013 Microchip Technology Inc. 20.1 UART Helpful Tips 1. In multi-node, direct-connect UART networks, UART receive inputs react to the complementary logic level defined by the URXINV bit (UxMODE<4>), which defines the Idle state, the default of which is logic high (i.e., URXINV = 0). Because remote devices do not initialize at the same time, it is likely that one of the devices, because the RX line is floating, will trigger a Start bit detection and will cause the first byte received, after the device has been initialized, to be invalid. To avoid this situation, the user should use a pull-up or pull-down resistor on the RX pin depending on the value of the URXINV bit. a) If URXINV = 0, use a pull-up resistor on the RX pin. b) If URXINV = 1, use a pull-down resistor on the RX pin. 2. The first character received on a wake-up from Sleep mode caused by activity on the UxRX pin of the UARTx module will be invalid. In Sleep mode, peripheral clocks are disabled. By the time the oscillator system has restarted and stabilized from Sleep mode, the baud rate bit sampling clock, relative to the incoming UxRX bit timing, is no longer synchronized, resulting in the first character being invalid; this is to be expected. 20.2 UART Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 20.2.1 KEY RESOURCES • “UART” (DS70582) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464  2011-2013 Microchip Technology Inc. DS70000657H-page 283 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 20.3 UARTx Control Registers REGISTER 20-1: UxMODE: UARTx MODE REGISTER R/W-0 U-0 R/W-0 R/W-0 R/W-0 U-0 R/W-0 R/W-0 UARTEN(1) — USIDL IREN(2) RTSMD — UEN1 UEN0 bit 15 bit 8 R/W-0, HC R/W-0 R/W-0, HC R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 WAKE LPBACK ABAUD URXINV BRGH PDSEL1 PDSEL0 STSEL bit 7 bit 0 Legend: HC = Hardware Clearable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 UARTEN: UARTx Enable bit(1) 1 = UARTx is enabled; all UARTx pins are controlled by UARTx as defined by UEN<1:0> 0 = UARTx is disabled; all UARTx pins are controlled by PORT latches; UARTx power consumption is minimal bit 14 Unimplemented: Read as ‘0’ bit 13 USIDL: UARTx Stop in Idle Mode bit 1 = Discontinues module operation when device enters Idle mode 0 = Continues module operation in Idle mode bit 12 IREN: IrDA® Encoder and Decoder Enable bit(2) 1 = IrDA encoder and decoder are enabled 0 = IrDA encoder and decoder are disabled bit 11 RTSMD: Mode Selection for UxRTS Pin bit 1 = UxRTS pin is in Simplex mode 0 = UxRTS pin is in Flow Control mode bit 10 Unimplemented: Read as ‘0’ bit 9-8 UEN<1:0>: UARTx Pin Enable bits 11 = UxTX, UxRX and BCLKx pins are enabled and used; UxCTS pin is controlled by PORT latches(3) 10 = UxTX, UxRX, UxCTS and UxRTS pins are enabled and used(4) 01 = UxTX, UxRX and UxRTS pins are enabled and used; UxCTS pin is controlled by PORT latches(4) 00 = UxTX and UxRX pins are enabled and used; UxCTS and UxRTS/BCLKx pins are controlled by PORT latches bit 7 WAKE: Wake-up on Start bit Detect During Sleep Mode Enable bit 1 = UARTx continues to sample the UxRX pin; interrupt is generated on the falling edge; bit is cleared in hardware on the following rising edge 0 = No wake-up is enabled bit 6 LPBACK: UARTx Loopback Mode Select bit 1 = Enables Loopback mode 0 = Loopback mode is disabled Note 1: Refer to the “UART” (DS70582) section in the “dsPIC33/PIC24 Family Reference Manual” for information on enabling the UARTx module for receive or transmit operation. 2: This feature is only available for the 16x BRG mode (BRGH = 0). 3: This feature is only available on 44-pin and 64-pin devices. 4: This feature is only available on 64-pin devices. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 284  2011-2013 Microchip Technology Inc. bit 5 ABAUD: Auto-Baud Enable bit 1 = Enables baud rate measurement on the next character – requires reception of a Sync field (55h) before other data; cleared in hardware upon completion 0 = Baud rate measurement is disabled or completed bit 4 URXINV: UARTx Receive Polarity Inversion bit 1 = UxRX Idle state is ‘0’ 0 = UxRX Idle state is ‘1’ bit 3 BRGH: High Baud Rate Enable bit 1 = BRG generates 4 clocks per bit period (4x baud clock, High-Speed mode) 0 = BRG generates 16 clocks per bit period (16x baud clock, Standard mode) bit 2-1 PDSEL<1:0>: Parity and Data Selection bits 11 = 9-bit data, no parity 10 = 8-bit data, odd parity 01 = 8-bit data, even parity 00 = 8-bit data, no parity bit 0 STSEL: Stop Bit Selection bit 1 = Two Stop bits 0 = One Stop bit REGISTER 20-1: UxMODE: UARTx MODE REGISTER (CONTINUED) Note 1: Refer to the “UART” (DS70582) section in the “dsPIC33/PIC24 Family Reference Manual” for information on enabling the UARTx module for receive or transmit operation. 2: This feature is only available for the 16x BRG mode (BRGH = 0). 3: This feature is only available on 44-pin and 64-pin devices. 4: This feature is only available on 64-pin devices.  2011-2013 Microchip Technology Inc. DS70000657H-page 285 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 20-2: UxSTA: UARTx STATUS AND CONTROL REGISTER R/W-0 R/W-0 R/W-0 U-0 R/W-0, HC R/W-0 R-0 R-1 UTXISEL1 UTXINV UTXISEL0 — UTXBRK UTXEN(1) UTXBF TRMT bit 15 bit 8 R/W-0 R/W-0 R/W-0 R-1 R-0 R-0 R/C-0 R-0 URXISEL1 URXISEL0 ADDEN RIDLE PERR FERR OERR URXDA bit 7 bit 0 Legend: HC = Hardware Clearable bit C = Clearable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15,13 UTXISEL<1:0>: UARTx Transmission Interrupt Mode Selection bits 11 = Reserved; do not use 10 = Interrupt when a character is transferred to the Transmit Shift Register (TSR) and as a result, the transmit buffer becomes empty 01 = Interrupt when the last character is shifted out of the Transmit Shift Register; all transmit operations are completed 00 = Interrupt when a character is transferred to the Transmit Shift Register (this implies there is at least one character open in the transmit buffer) bit 14 UTXINV: UARTx Transmit Polarity Inversion bit If IREN = 0: 1 = UxTX Idle state is ‘0’ 0 = UxTX Idle state is ‘1’ If IREN = 1: 1 = IrDA encoded, UxTX Idle state is ‘1’ 0 = IrDA encoded, UxTX Idle state is ‘0’ bit 12 Unimplemented: Read as ‘0’ bit 11 UTXBRK: UARTx Transmit Break bit 1 = Sends Sync Break on next transmission – Start bit, followed by twelve ‘0’ bits, followed by Stop bit; cleared by hardware upon completion 0 = Sync Break transmission is disabled or completed bit 10 UTXEN: UARTx Transmit Enable bit(1) 1 = Transmit is enabled, UxTX pin is controlled by UARTx 0 = Transmit is disabled, any pending transmission is aborted and buffer is reset; UxTX pin is controlled by the PORT bit 9 UTXBF: UARTx Transmit Buffer Full Status bit (read-only) 1 = Transmit buffer is full 0 = Transmit buffer is not full, at least one more character can be written bit 8 TRMT: Transmit Shift Register Empty bit (read-only) 1 = Transmit Shift Register is empty and transmit buffer is empty (the last transmission has completed) 0 = Transmit Shift Register is not empty, a transmission is in progress or queued bit 7-6 URXISEL<1:0>: UARTx Receive Interrupt Mode Selection bits 11 = Interrupt is set on UxRSR transfer, making the receive buffer full (i.e., has 4 data characters) 10 = Interrupt is set on UxRSR transfer, making the receive buffer 3/4 full (i.e., has 3 data characters) 0x = Interrupt is set when any character is received and transferred from the UxRSR to the receive buffer; receive buffer has one or more characters Note 1: Refer to the “UART” (DS70582) section in the “dsPIC33/PIC24 Family Reference Manual” for information on enabling the UARTx module for transmit operation. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 286  2011-2013 Microchip Technology Inc. bit 5 ADDEN: Address Character Detect bit (bit 8 of received data = 1) 1 = Address Detect mode is enabled; if 9-bit mode is not selected, this does not take effect 0 = Address Detect mode is disabled bit 4 RIDLE: Receiver Idle bit (read-only) 1 = Receiver is Idle 0 = Receiver is active bit 3 PERR: Parity Error Status bit (read-only) 1 = Parity error has been detected for the current character (character at the top of the receive FIFO) 0 = Parity error has not been detected bit 2 FERR: Framing Error Status bit (read-only) 1 = Framing error has been detected for the current character (character at the top of the receive FIFO) 0 = Framing error has not been detected bit 1 OERR: Receive Buffer Overrun Error Status bit (clear/read-only) 1 = Receive buffer has overflowed 0 = Receive buffer has not overflowed; clearing a previously set OERR bit (1  0 transition) resets the receiver buffer and the UxRSR to the empty state bit 0 URXDA: UARTx Receive Buffer Data Available bit (read-only) 1 = Receive buffer has data, at least one more character can be read 0 = Receive buffer is empty REGISTER 20-2: UxSTA: UARTx STATUS AND CONTROL REGISTER (CONTINUED) Note 1: Refer to the “UART” (DS70582) section in the “dsPIC33/PIC24 Family Reference Manual” for information on enabling the UARTx module for transmit operation.  2011-2013 Microchip Technology Inc. DS70000657H-page 287 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 21.0 ENHANCED CAN (ECAN™) MODULE (dsPIC33EPXXXGP/ MC50X DEVICES ONLY) 21.1 Overview The Enhanced Controller Area Network (ECAN) module is a serial interface, useful for communicating with other CAN modules or microcontroller devices. This interface/protocol was designed to allow communications within noisy environments. The dsPIC33EPXXXGP/MC50X devices contain one ECAN module. The ECAN module is a communication controller implementing the CAN 2.0 A/B protocol, as defined in the BOSCH CAN specification. The module supports 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 CAN specification is not covered within this data sheet. The reader can refer to the BOSCH CAN specification for further details. The ECAN 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 • 0-8 bytes data length • Programmable bit rate up to 1 Mbit/sec • Automatic response to remote transmission requests • Up to eight transmit buffers with application specified prioritization and abort capability (each buffer can contain up to 8 bytes of data) • Up to 32 receive buffers (each buffer can contain up to 8 bytes of data) • Up to 16 full (Standard/Extended Identifier) acceptance filters • Three full acceptance filter masks • DeviceNet™ addressing support • Programmable wake-up functionality with integrated low-pass filter • Programmable Loopback mode supports self-test operation • Signaling via interrupt capabilities for all CAN receiver and transmitter error states • Programmable clock source • Programmable link to Input Capture (IC2) module for time-stamping and network synchronization • Low-power Sleep and Idle mode The CAN bus module consists of a protocol engine and message buffering/control. 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 receive registers. Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Enhanced Controller Area Network (ECAN™)” (DS70353) in the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 288  2011-2013 Microchip Technology Inc. FIGURE 21-1: ECAN™ MODULE BLOCK DIAGRAM Message Assembly CAN Protocol Engine CxTx Buffer CxRx RxF14 Filter RxF13 Filter RxF12 Filter RxF11 Filter RxF10 Filter RxF9 Filter RxF8 Filter RxF7 Filter RxF6 Filter RxF5 Filter RxF4 Filter RxF3 Filter RxF2 Filter RxF1 Filter RxF0 Filter Transmit Byte Sequencer RxM1 Mask RxM0 Mask Control Configuration Logic CPU Bus Interrupts TRB0 TX/RX Buffer Control Register RxF15 Filter RxM2 Mask TRB7 TX/RX Buffer Control Register TRB6 TX/RX Buffer Control Register TRB5 TX/RX Buffer Control Register TRB4 TX/RX Buffer Control Register TRB3 TX/RX Buffer Control Register TRB2 TX/RX Buffer Control Register TRB1 TX/RX Buffer Control Register DMA Controller  2011-2013 Microchip Technology Inc. DS70000657H-page 289 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 21.2 Modes of Operation The ECAN 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 • Listen All Messages mode • Loopback mode Modes are requested by setting the REQOP<2:0> bits (CxCTRL1<10:8>). Entry into a mode is Acknowledged by monitoring the OPMODE<2:0> bits (CxCTRL1<7:5>). The module does not change the mode and the OPMODEx bits until a change in mode is acceptable, generally during bus Idle time, which is defined as at least 11 consecutive recessive bits. 21.3 ECAN Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 21.3.1 KEY RESOURCES • “Enhanced Controller Area Network (ECAN™)” (DS70353) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 290  2011-2013 Microchip Technology Inc. 21.4 ECAN Control Registers REGISTER 21-1: CxCTRL1: ECANx CONTROL REGISTER 1 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-1 R/W-0 R/W-0 — — CSIDL ABAT CANCKS REQOP2 REQOP1 REQOP0 bit 15 bit 8 R-1 R-0 R-0 U-0 R/W-0 U-0 U-0 R/W-0 OPMODE2 OPMODE1 OPMODE0 — CANCAP — — WIN bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13 CSIDL: ECANx Stop in Idle Mode bit 1 = Discontinues module operation when device enters Idle mode 0 = Continues module operation in Idle mode bit 12 ABAT: Abort All Pending Transmissions bit 1 = Signals all transmit buffers to abort transmission 0 = Module will clear this bit when all transmissions are aborted bit 11 CANCKS: ECANx Module Clock (FCAN) Source Select bit 1 = FCAN is equal to 2 * FP 0 = FCAN is equal to FP bit 10-8 REQOP<2:0>: Request Operation Mode bits 111 = Set Listen All Messages mode 110 = Reserved 101 = Reserved 100 = Set Configuration mode 011 = Set Listen Only mode 010 = Set Loopback mode 001 = Set Disable mode 000 = Set Normal Operation mode bit 7-5 OPMODE<2:0>: Operation Mode bits 111 = Module is in Listen All Messages mode 110 = Reserved 101 = Reserved 100 = Module is in Configuration mode 011 = Module is in Listen Only mode 010 = Module is in Loopback mode 001 = Module is in Disable mode 000 = Module is in Normal Operation mode bit 4 Unimplemented: Read as ‘0’ bit 3 CANCAP: CAN Message Receive Timer Capture Event Enable bit 1 = Enables input capture based on CAN message receive 0 = Disables CAN capture bit 2-1 Unimplemented: Read as ‘0’ bit 0 WIN: SFR Map Window Select bit 1 = Uses filter window 0 = Uses buffer window  2011-2013 Microchip Technology Inc. DS70000657H-page 291 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 21-2: CxCTRL2: ECANx CONTROL REGISTER 2 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 U-0 U-0 R-0 R-0 R-0 R-0 R-0 — — — DNCNT4 DNCNT3 DNCNT2 DNCNT1 DNCNT0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-5 Unimplemented: Read as ‘0’ bit 4-0 DNCNT<4:0>: DeviceNet™ Filter Bit Number bits 10010-11111 = Invalid selection 10001 = Compares up to Data Byte 3, bit 6 with EID<17> • • • 00001 = Compares up to Data Byte 1, bit 7 with EID<0> 00000 = Does not compare data bytes dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 292  2011-2013 Microchip Technology Inc. REGISTER 21-3: CxVEC: ECANx INTERRUPT CODE REGISTER U-0 U-0 U-0 R-0 R-0 R-0 R-0 R-0 — — — FILHIT4 FILHIT3 FILHIT2 FILHIT1 FILHIT0 bit 15 bit 8 U-0 R-1 R-0 R-0 R-0 R-0 R-0 R-0 — ICODE6 ICODE5 ICODE4 ICODE3 ICODE2 ICODE1 ICODE0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-13 Unimplemented: Read as ‘0’ bit 12-8 FILHIT<4:0>: Filter Hit Number bits 10000-11111 = Reserved 01111 = Filter 15 • • • 00001 = Filter 1 00000 = Filter 0 bit 7 Unimplemented: Read as ‘0’ bit 6-0 ICODE<6:0>: Interrupt Flag Code bits 1000101-1111111 = Reserved 1000100 = FIFO almost full interrupt 1000011 = Receiver overflow interrupt 1000010 = Wake-up interrupt 1000001 = Error interrupt 1000000 = No interrupt • • • 0010000-0111111 = Reserved 0001111 = RB15 buffer interrupt • • • 0001001 = RB9 buffer interrupt 0001000 = RB8 buffer interrupt 0000111 = TRB7 buffer interrupt 0000110 = TRB6 buffer interrupt 0000101 = TRB5 buffer interrupt 0000100 = TRB4 buffer interrupt 0000011 = TRB3 buffer interrupt 0000010 = TRB2 buffer interrupt 0000001 = TRB1 buffer interrupt 0000000 = TRB0 buffer interrupt  2011-2013 Microchip Technology Inc. DS70000657H-page 293 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 21-4: CxFCTRL: ECANx FIFO CONTROL REGISTER R/W-0 R/W-0 R/W-0 U-0 U-0 U-0 U-0 U-0 DMABS2 DMABS1 DMABS0 — — — — — bit 15 bit 8 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — — FSA4 FSA3 FSA2 FSA1 FSA0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-13 DMABS<2:0>: DMA Buffer Size bits 111 = Reserved 110 = 32 buffers in RAM 101 = 24 buffers in RAM 100 = 16 buffers in RAM 011 = 12 buffers in RAM 010 = 8 buffers in RAM 001 = 6 buffers in RAM 000 = 4 buffers in RAM bit 12-5 Unimplemented: Read as ‘0’ bit 4-0 FSA<4:0>: FIFO Area Starts with Buffer bits 11111 = Read Buffer RB31 11110 = Read Buffer RB30 • • • 00001 = TX/RX Buffer TRB1 00000 = TX/RX Buffer TRB0 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 294  2011-2013 Microchip Technology Inc. REGISTER 21-5: CxFIFO: ECANx FIFO STATUS REGISTER U-0 U-0 R-0 R-0 R-0 R-0 R-0 R-0 — — FBP5 FBP4 FBP3 FBP2 FBP1 FBP0 bit 15 bit 8 U-0 U-0 R-0 R-0 R-0 R-0 R-0 R-0 — — FNRB5 FNRB4 FNRB3 FNRB2 FNRB1 FNRB0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13-8 FBP<5:0>: FIFO Buffer Pointer bits 011111 = RB31 buffer 011110 = RB30 buffer • • • 000001 = TRB1 buffer 000000 = TRB0 buffer bit 7-6 Unimplemented: Read as ‘0’ bit 5-0 FNRB<5:0>: FIFO Next Read Buffer Pointer bits 011111 = RB31 buffer 011110 = RB30 buffer • • • 000001 = TRB1 buffer 000000 = TRB0 buffer  2011-2013 Microchip Technology Inc. DS70000657H-page 295 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 21-6: CxINTF: ECANx INTERRUPT FLAG REGISTER U-0 U-0 R-0 R-0 R-0 R-0 R-0 R-0 — — TXBO TXBP RXBP TXWAR RXWAR EWARN bit 15 bit 8 R/C-0 R/C-0 R/C-0 U-0 R/C-0 R/C-0 R/C-0 R/C-0 IVRIF WAKIF ERRIF — FIFOIF RBOVIF RBIF TBIF bit 7 bit 0 Legend: C = Writable bit, but only ‘0’ can be written to clear the bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 Unimplemented: Read as ‘0’ bit 13 TXBO: Transmitter in Error State Bus Off bit 1 = Transmitter is in Bus Off state 0 = Transmitter is not in Bus Off state bit 12 TXBP: Transmitter in Error State Bus Passive bit 1 = Transmitter is in Bus Passive state 0 = Transmitter is not in Bus Passive state bit 11 RXBP: Receiver in Error State Bus Passive bit 1 = Receiver is in Bus Passive state 0 = Receiver is not in Bus Passive state bit 10 TXWAR: Transmitter in Error State Warning bit 1 = Transmitter is in Error Warning state 0 = Transmitter is not in Error Warning state bit 9 RXWAR: Receiver in Error State Warning bit 1 = Receiver is in Error Warning state 0 = Receiver is not in Error Warning state bit 8 EWARN: Transmitter or Receiver in Error State Warning bit 1 = Transmitter or receiver is in Error Warning state 0 = Transmitter or receiver is not in Error Warning state bit 7 IVRIF: Invalid Message Interrupt Flag bit 1 = Interrupt request has occurred 0 = Interrupt request has not occurred bit 6 WAKIF: Bus Wake-up Activity Interrupt Flag bit 1 = Interrupt request has occurred 0 = Interrupt request has not occurred bit 5 ERRIF: Error Interrupt Flag bit (multiple sources in CxINTF<13:8>) 1 = Interrupt request has occurred 0 = Interrupt request has not occurred bit 4 Unimplemented: Read as ‘0’ bit 3 FIFOIF: FIFO Almost Full Interrupt Flag bit 1 = Interrupt request has occurred 0 = Interrupt request has not occurred bit 2 RBOVIF: RX Buffer Overflow Interrupt Flag bit 1 = Interrupt request has occurred 0 = Interrupt request has not occurred dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 296  2011-2013 Microchip Technology Inc. bit 1 RBIF: RX Buffer Interrupt Flag bit 1 = Interrupt request has occurred 0 = Interrupt request has not occurred bit 0 TBIF: TX Buffer Interrupt Flag bit 1 = Interrupt request has occurred 0 = Interrupt request has not occurred REGISTER 21-6: CxINTF: ECANx INTERRUPT FLAG REGISTER (CONTINUED)  2011-2013 Microchip Technology Inc. DS70000657H-page 297 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 21-7: CxINTE: ECANx INTERRUPT ENABLE REGISTER U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 R/W-0 R/W-0 R/W-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 IVRIE WAKIE ERRIE — FIFOIE RBOVIE RBIE TBIE bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-8 Unimplemented: Read as ‘0’ bit 7 IVRIE: Invalid Message Interrupt Enable bit 1 = Interrupt request is enabled 0 = Interrupt request is not enabled bit 6 WAKIE: Bus Wake-up Activity Interrupt Enable bit 1 = Interrupt request is enabled 0 = Interrupt request is not enabled bit 5 ERRIE: Error Interrupt Enable bit 1 = Interrupt request is enabled 0 = Interrupt request is not enabled bit 4 Unimplemented: Read as ‘0’ bit 3 FIFOIE: FIFO Almost Full Interrupt Enable bit 1 = Interrupt request is enabled 0 = Interrupt request is not enabled bit 2 RBOVIE: RX Buffer Overflow Interrupt Enable bit 1 = Interrupt request is enabled 0 = Interrupt request is not enabled bit 1 RBIE: RX Buffer Interrupt Enable bit 1 = Interrupt request is enabled 0 = Interrupt request is not enabled bit 0 TBIE: TX Buffer Interrupt Enable bit 1 = Interrupt request is enabled 0 = Interrupt request is not enabled dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 298  2011-2013 Microchip Technology Inc. REGISTER 21-8: CxEC: ECANx TRANSMIT/RECEIVE ERROR COUNT REGISTER R-0 R-0 R-0 R-0 R-0 R-0 R-0 R-0 TERRCNT<7:0> bit 15 bit 8 R-0 R-0 R-0 R-0 R-0 R-0 R-0 R-0 RERRCNT<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-8 TERRCNT<7:0>: Transmit Error Count bits bit 7-0 RERRCNT<7:0>: Receive Error Count bits REGISTER 21-9: CxCFG1: ECANx BAUD RATE CONFIGURATION REGISTER 1 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 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 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-8 Unimplemented: Read as ‘0’ bit 7-6 SJW<1:0>: Synchronization Jump Width bits 11 = Length is 4 x TQ 10 = Length is 3 x TQ 01 = Length is 2 x TQ 00 = Length is 1 x TQ bit 5-0 BRP<5:0>: Baud Rate Prescaler bits 11 1111 = TQ = 2 x 64 x 1/FCAN • • • 00 0010 = TQ = 2 x 3 x 1/FCAN 00 0001 = TQ = 2 x 2 x 1/FCAN 00 0000 = TQ = 2 x 1 x 1/FCAN  2011-2013 Microchip Technology Inc. DS70000657H-page 299 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 21-10: CxCFG2: ECANx BAUD RATE CONFIGURATION REGISTER 2 U-0 R/W-x U-0 U-0 U-0 R/W-x R/W-x R/W-x — WAKFIL — — — SEG2PH2 SEG2PH1 SEG2PH0 bit 15 bit 8 R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x SEG2PHTS SAM SEG1PH2 SEG1PH1 SEG1PH0 PRSEG2 PRSEG1 PRSEG0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 Unimplemented: Read as ‘0’ bit 14 WAKFIL: Select CAN Bus Line Filter for Wake-up bit 1 = Uses CAN bus line filter for wake-up 0 = CAN bus line filter is not used for wake-up bit 13-11 Unimplemented: Read as ‘0’ bit 10-8 SEG2PH<2:0>: Phase Segment 2 bits 111 = Length is 8 x TQ • • • 000 = Length is 1 x TQ bit 7 SEG2PHTS: Phase Segment 2 Time Select bit 1 = Freely programmable 0 = Maximum of SEG1PHx bits 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 SEG1PH<2:0>: Phase Segment 1 bits 111 = Length is 8 x TQ • • • 000 = Length is 1 x TQ bit 2-0 PRSEG<2:0>: Propagation Time Segment bits 111 = Length is 8 x TQ • • • 000 = Length is 1 x TQ dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 300  2011-2013 Microchip Technology Inc. REGISTER 21-11: CxFEN1: ECANx ACCEPTANCE FILTER ENABLE REGISTER 1 R/W-1 R/W-1 R/W-1 R/W-1 R/W-1 R/W-1 R/W-1 R/W-1 FLTEN15 FLTEN14 FLTEN13 FLTEN12 FLTEN11 FLTEN10 FLTEN9 FLTEN8 bit 15 bit 8 R/W-1 R/W-1 R/W-1 R/W-1 R/W-1 R/W-1 R/W-1 R/W-1 FLTEN7 FLTEN6 FLTEN5 FLTEN4 FLTEN3 FLTEN2 FLTEN1 FLTEN0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 FLTEN<15:0>: Enable Filter n to Accept Messages bits 1 = Enables Filter n 0 = Disables Filter n REGISTER 21-12: CxBUFPNT1: ECANx FILTER 0-3 BUFFER POINTER 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 F3BP<3:0> F2BP<3:0> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 F1BP<3:0> F0BP<3:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-12 F3BP<3:0>: RX Buffer Mask for Filter 3 bits 1111 = Filter hits received in RX FIFO buffer 1110 = Filter hits received in RX Buffer 14 • • • 0001 = Filter hits received in RX Buffer 1 0000 = Filter hits received in RX Buffer 0 bit 11-8 F2BP<3:0>: RX Buffer Mask for Filter 2 bits (same values as bits<15:12>) bit 7-4 F1BP<3:0>: RX Buffer Mask for Filter 1 bits (same values as bits<15:12>) bit 3-0 F0BP<3:0>: RX Buffer Mask for Filter 0 bits (same values as bits<15:12>)  2011-2013 Microchip Technology Inc. DS70000657H-page 301 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 21-13: CxBUFPNT2: ECANx FILTER 4-7 BUFFER POINTER 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 F7BP<3:0> F6BP<3:0> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 F5BP<3:0> F4BP<3:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-12 F7BP<3:0>: RX Buffer Mask for Filter 7 bits 1111 = Filter hits received in RX FIFO buffer 1110 = Filter hits received in RX Buffer 14 • • • 0001 = Filter hits received in RX Buffer 1 0000 = Filter hits received in RX Buffer 0 bit 11-8 F6BP<3:0>: RX Buffer Mask for Filter 6 bits (same values as bits<15:12>) bit 7-4 F5BP<3:0>: RX Buffer Mask for Filter 5 bits (same values as bits<15:12>) bit 3-0 F4BP<3:0>: RX Buffer Mask for Filter 4 bits (same values as bits<15:12>) REGISTER 21-14: CxBUFPNT3: ECANx FILTER 8-11 BUFFER POINTER REGISTER 3 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 F11BP<3:0> F10BP<3:0> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 F9BP<3:0> F8BP<3:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-12 F11BP<3:0>: RX Buffer Mask for Filter 11 bits 1111 = Filter hits received in RX FIFO buffer 1110 = Filter hits received in RX Buffer 14 • • • 0001 = Filter hits received in RX Buffer 1 0000 = Filter hits received in RX Buffer 0 bit 11-8 F10BP<3:0>: RX Buffer Mask for Filter 10 bits (same values as bits<15:12>) bit 7-4 F9BP<3:0>: RX Buffer Mask for Filter 9 bits (same values as bits<15:12>) bit 3-0 F8BP<3:0>: RX Buffer Mask for Filter 8 bits (same values as bits<15:12>) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 302  2011-2013 Microchip Technology Inc. REGISTER 21-15: CxBUFPNT4: ECANx FILTER 12-15 BUFFER POINTER REGISTER 4 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 F15BP<3:0> F14BP<3:0> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 F13BP<3:0> F12BP<3:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-12 F15BP<3:0>: RX Buffer Mask for Filter 15 bits 1111 = Filter hits received in RX FIFO buffer 1110 = Filter hits received in RX Buffer 14 • • • 0001 = Filter hits received in RX Buffer 1 0000 = Filter hits received in RX Buffer 0 bit 11-8 F14BP<3:0>: RX Buffer Mask for Filter 14 bits (same values as bits<15:12>) bit 7-4 F13BP<3:0>: RX Buffer Mask for Filter 13 bits (same values as bits<15:12>) bit 3-0 F12BP<3:0>: RX Buffer Mask for Filter 12 bits (same values as bits<15:12>)  2011-2013 Microchip Technology Inc. DS70000657H-page 303 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 21-16: CxRXFnSID: ECANx ACCEPTANCE FILTER n STANDARD IDENTIFIER REGISTER (n = 0-15) 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 15 bit 8 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 — EXIDE — EID17 EID16 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-5 SID<10:0>: Standard Identifier bits 1 = Message address bit, SIDx, must be ‘1’ to match filter 0 = Message address bit, SIDx, must be ‘0’ to match filter bit 4 Unimplemented: Read as ‘0’ bit 3 EXIDE: Extended Identifier Enable bit If MIDE = 1: 1 = Matches only messages with Extended Identifier addresses 0 = Matches only messages with Standard Identifier addresses If MIDE = 0: Ignores EXIDE bit. bit 2 Unimplemented: Read as ‘0’ bit 1-0 EID<17:16>: Extended Identifier bits 1 = Message address bit, EIDx, must be ‘1’ to match filter 0 = Message address bit, EIDx, must be ‘0’ to match filter dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 304  2011-2013 Microchip Technology Inc. REGISTER 21-17: CxRXFnEID: ECANx ACCEPTANCE FILTER n EXTENDED IDENTIFIER REGISTER (n = 0-15) 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 15 bit 8 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 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 EID<15:0>: Extended Identifier bits 1 = Message address bit, EIDx, must be ‘1’ to match filter 0 = Message address bit, EIDx, must be ‘0’ to match filter REGISTER 21-18: CxFMSKSEL1: ECANx FILTER 7-0 MASK SELECTION 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 F7MSK<1:0> F6MSK<1:0> F5MSK<1:0> F4MSK<1:0> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 F3MSK<1:0> F2MSK<1:0> F1MSK<1:0> F0MSK<1:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 F7MSK<1:0>: Mask Source for Filter 7 bits 11 = Reserved 10 = Acceptance Mask 2 registers contain mask 01 = Acceptance Mask 1 registers contain mask 00 = Acceptance Mask 0 registers contain mask bit 13-12 F6MSK<1:0>: Mask Source for Filter 6 bits (same values as bits<15:14>) bit 11-10 F5MSK<1:0>: Mask Source for Filter 5 bits (same values as bits<15:14>) bit 9-8 F4MSK<1:0>: Mask Source for Filter 4 bits (same values as bits<15:14>) bit 7-6 F3MSK<1:0>: Mask Source for Filter 3 bits (same values as bits<15:14>) bit 5-4 F2MSK<1:0>: Mask Source for Filter 2 bits (same values as bits<15:14>) bit 3-2 F1MSK<1:0>: Mask Source for Filter 1 bits (same values as bits<15:14>) bit 1-0 F0MSK<1:0>: Mask Source for Filter 0 bits (same values as bits<15:14>)  2011-2013 Microchip Technology Inc. DS70000657H-page 305 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 21-19: CxFMSKSEL2: ECANx FILTER 15-8 MASK SELECTION 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 F15MSK<1:0> F14MSK<1:0> F13MSK<1:0> F12MSK<1:0> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 F11MSK<1:0> F10MSK<1:0> F9MSK<1:0> F8MSK<1:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-14 F15MSK<1:0>: Mask Source for Filter 15 bits 11 = Reserved 10 = Acceptance Mask 2 registers contain mask 01 = Acceptance Mask 1 registers contain mask 00 = Acceptance Mask 0 registers contain mask bit 13-12 F14MSK<1:0>: Mask Source for Filter 14 bits (same values as bits<15:14>) bit 11-10 F13MSK<1:0>: Mask Source for Filter 13 bits (same values as bits<15:14>) bit 9-8 F12MSK<1:0>: Mask Source for Filter 12 bits (same values as bits<15:14>) bit 7-6 F11MSK<1:0>: Mask Source for Filter 11 bits (same values as bits<15:14>) bit 5-4 F10MSK<1:0>: Mask Source for Filter 10 bits (same values as bits<15:14>) bit 3-2 F9MSK<1:0>: Mask Source for Filter 9 bits (same values as bits<15:14>) bit 1-0 F8MSK<1:0>: Mask Source for Filter 8 bits (same values as bits<15:14>) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 306  2011-2013 Microchip Technology Inc. REGISTER 21-20: CxRXMnSID: ECANx ACCEPTANCE FILTER MASK n STANDARD IDENTIFIER REGISTER (n = 0-2) 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 15 bit 8 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 — MIDE — EID17 EID16 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-5 SID<10:0>: Standard Identifier bits 1 = Includes bit, SIDx, in filter comparison 0 = SIDx bit is a don’t care in filter comparison bit 4 Unimplemented: Read as ‘0’ bit 3 MIDE: Identifier Receive Mode bit 1 = Matches only message types (standard or extended address) that correspond to EXIDE bit in the filter 0 = Matches either standard or extended address message if filters match (i.e., if (Filter SID) = (Message SID) or if (Filter SID/EID) = (Message SID/EID)) bit 2 Unimplemented: Read as ‘0’ bit 1-0 EID<17:16>: Extended Identifier bits 1 = Includes bit, EIDx, in filter comparison 0 = EIDx bit is a don’t care in filter comparison REGISTER 21-21: CxRXMnEID: ECANx ACCEPTANCE FILTER MASK n EXTENDED IDENTIFIER REGISTER (n = 0-2) 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 15 bit 8 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 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 EID<15:0>: Extended Identifier bits 1 = Includes bit, EIDx, in filter comparison 0 = EIDx bit is a don’t care in filter comparison  2011-2013 Microchip Technology Inc. DS70000657H-page 307 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 21-22: CxRXFUL1: ECANx RECEIVE BUFFER FULL REGISTER 1 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 RXFUL15 RXFUL14 RXFUL13 RXFUL12 RXFUL11 RXFUL10 RXFUL9 RXFUL8 bit 15 bit 8 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 RXFUL7 RXFUL6 RXFUL5 RXFUL4 RXFUL3 RXFUL2 RXFUL1 RXFUL0 bit 7 bit 0 Legend: C = Writable bit, but only ‘0’ can be written to clear the bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 RXFUL<15:0>: Receive Buffer n Full bits 1 = Buffer is full (set by module) 0 = Buffer is empty (cleared by user software) REGISTER 21-23: CxRXFUL2: ECANx RECEIVE BUFFER FULL REGISTER 2 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 RXFUL31 RXFUL30 RXFUL29 RXFUL28 RXFUL27 RXFUL26 RXFUL25 RXFUL24 bit 15 bit 8 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 RXFUL23 RXFUL22 RXFUL21 RXFUL20 RXFUL19 RXFUL18 RXFUL17 RXFUL16 bit 7 bit 0 Legend: C = Writable bit, but only ‘0’ can be written to clear the bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 RXFUL<31:16>: Receive Buffer n Full bits 1 = Buffer is full (set by module) 0 = Buffer is empty (cleared by user software) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 308  2011-2013 Microchip Technology Inc. REGISTER 21-24: CxRXOVF1: ECANx RECEIVE BUFFER OVERFLOW REGISTER 1 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 RXOVF15 RXOVF14 RXOVF13 RXOVF12 RXOVF11 RXOVF10 RXOVF9 RXOVF8 bit 15 bit 8 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 RXOVF7 RXOVF6 RXOVF5 RXOVF4 RXOVF3 RXOVF2 RXOVF1 RXOVF0 bit 7 bit 0 Legend: C = Writable bit, but only ‘0’ can be written to clear the bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 RXOVF<15:0>: Receive Buffer n Overflow bits 1 = Module attempted to write to a full buffer (set by module) 0 = No overflow condition (cleared by user software) REGISTER 21-25: CxRXOVF2: ECANx RECEIVE BUFFER OVERFLOW REGISTER 2 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 RXOVF31 RXOVF30 RXOVF29 RXOVF28 RXOVF27 RXOVF26 RXOVF25 RXOVF24 bit 15 bit 8 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 R/C-0 RXOVF23 RXOVF22 RXOVF21 RXOVF20 RXOVF19 RXOVF18 RXOVF17 RXOVF16 bit 7 bit 0 Legend: C = Writable bit, but only ‘0’ can be written to clear the bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 RXOVF<31:16>: Receive Buffer n Overflow bits 1 = Module attempted to write to a full buffer (set by module) 0 = No overflow condition (cleared by user software)  2011-2013 Microchip Technology Inc. DS70000657H-page 309 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 21-26: CxTRmnCON: ECANx TX/RX BUFFER mn CONTROL REGISTER (m = 0,2,4,6; n = 1,3,5,7) R/W-0 R-0 R-0 R-0 R/W-0 R/W-0 R/W-0 R/W-0 TXENn TXABTn TXLARBn TXERRn TXREQn RTRENn TXnPRI1 TXnPRI0 bit 15 bit 8 R/W-0 R-0 R-0 R-0 R/W-0 R/W-0 R/W-0 R/W-0 TXENm TXABTm(1) TXLARBm(1) TXERRm(1) TXREQm RTRENm TXmPRI1 TXmPRI0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-8 See Definition for bits<7:0>, Controls Buffer n bit 7 TXENm: TX/RX Buffer Selection bit 1 = Buffer TRBn is a transmit buffer 0 = Buffer TRBn is a receive buffer bit 6 TXABTm: Message Aborted bit(1) 1 = Message was aborted 0 = Message completed transmission successfully bit 5 TXLARBm: Message Lost Arbitration bit(1) 1 = Message lost arbitration while being sent 0 = Message did not lose arbitration while being sent bit 4 TXERRm: Error Detected During Transmission bit(1) 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 TXREQm: Message Send Request bit 1 = Requests that a message be sent; the bit automatically clears when the message is successfully sent 0 = Clearing the bit to ‘0’ while set requests a message abort bit 2 RTRENm: Auto-Remote Transmit Enable bit 1 = When a remote transmit is received, TXREQ will be set 0 = When a remote transmit is received, TXREQ will be unaffected bit 1-0 TXmPRI<1:0>: Message Transmission Priority bits 11 = Highest message priority 10 = High intermediate message priority 01 = Low intermediate message priority 00 = Lowest message priority Note 1: This bit is cleared when TXREQ is set. Note: The buffers, SID, EID, DLC, Data Field, and Receive Status registers are located in DMA RAM. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 310  2011-2013 Microchip Technology Inc. 21.5 ECAN Message Buffers ECAN Message Buffers are part of RAM memory. They are not ECAN Special Function Registers. The user application must directly write into the RAM area that is configured for ECAN Message Buffers. The location and size of the buffer area is defined by the user application. BUFFER 21-1: ECAN™ MESSAGE BUFFER WORD 0 U-0 U-0 U-0 R/W-x R/W-x R/W-x R/W-x R/W-x — — — SID10 SID9 SID8 SID7 SID6 bit 15 bit 8 R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x SID5 SID4 SID3 SID2 SID1 SID0 SRR IDE bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-13 Unimplemented: Read as ‘0’ bit 12-2 SID<10:0>: Standard Identifier bits bit 1 SRR: Substitute Remote Request bit When IDE = 0: 1 = Message will request remote transmission 0 = Normal message When IDE = 1: The SRR bit must be set to ‘1’. bit 0 IDE: Extended Identifier bit 1 = Message will transmit Extended Identifier 0 = Message will transmit Standard Identifier BUFFER 21-2: ECAN™ MESSAGE BUFFER WORD 1 U-0 U-0 U-0 U-0 R/W-x R/W-x R/W-x R/W-x — — — — EID17 EID16 EID15 EID14 bit 15 bit 8 R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x EID13 EID12 EID11 EID10 EID9 EID8 EID7 EID6 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-12 Unimplemented: Read as ‘0’ bit 11-0 EID<17:6>: Extended Identifier bits  2011-2013 Microchip Technology Inc. DS70000657H-page 311 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X ( BUFFER 21-3: ECAN™ MESSAGE BUFFER WORD 2 R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x EID5 EID4 EID3 EID2 EID1 EID0 RTR RB1 bit 15 bit 8 U-x U-x U-x R/W-x R/W-x R/W-x R/W-x R/W-x — — — RB0 DLC3 DLC2 DLC1 DLC0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-10 EID<5:0>: Extended Identifier bits bit 9 RTR: Remote Transmission Request bit When IDE = 1: 1 = Message will request remote transmission 0 = Normal message When IDE = 0: The RTR bit is ignored. bit 8 RB1: Reserved Bit 1 User must set this bit to ‘0’ per CAN protocol. bit 7-5 Unimplemented: Read as ‘0’ bit 4 RB0: Reserved Bit 0 User must set this bit to ‘0’ per CAN protocol. bit 3-0 DLC<3:0>: Data Length Code bits BUFFER 21-4: ECAN™ MESSAGE BUFFER WORD 3 R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x Byte 1 bit 15 bit 8 R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x Byte 0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-8 Byte 1<15:8>: ECAN Message Byte 1 bits bit 7-0 Byte 0<7:0>: ECAN Message Byte 0 bits dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 312  2011-2013 Microchip Technology Inc. BUFFER 21-5: ECAN™ MESSAGE BUFFER WORD 4 R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x Byte 3 bit 15 bit 8 R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x Byte 2 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-8 Byte 3<15:8>: ECAN Message Byte 3 bits bit 7-0 Byte 2<7:0>: ECAN Message Byte 2 bits BUFFER 21-6: ECAN™ MESSAGE BUFFER WORD 5 R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x Byte 5 bit 15 bit 8 R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x Byte 4 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-8 Byte 5<15:8>: ECAN Message Byte 5 bits bit 7-0 Byte 4<7:0>: ECAN Message Byte 4 bits  2011-2013 Microchip Technology Inc. DS70000657H-page 313 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X BUFFER 21-7: ECAN™ MESSAGE BUFFER WORD 6 R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x Byte 7 bit 15 bit 8 R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x R/W-x Byte 6 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-8 Byte 7<15:8>: ECAN Message Byte 7 bits bit 7-0 Byte 6<7:0>: ECAN Message Byte 6 bits BUFFER 21-8: ECAN™ MESSAGE BUFFER WORD 7 U-0 U-0 U-0 R/W-x R/W-x R/W-x R/W-x R/W-x — — — FILHIT4(1) FILHIT3(1) FILHIT2(1) FILHIT1(1) FILHIT0(1) bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-13 Unimplemented: Read as ‘0’ bit 12-8 FILHIT<4:0>: Filter Hit Code bits(1) Encodes number of filter that resulted in writing this buffer. bit 7-0 Unimplemented: Read as ‘0’ Note 1: Only written by module for receive buffers, unused for transmit buffers. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 314  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 315 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 22.0 CHARGE TIME MEASUREMENT UNIT (CTMU) The Charge Time Measurement Unit is a flexible analog module that provides accurate differential time measurement between pulse sources, as well as asynchronous pulse generation. Its key features include: • Four Edge Input Trigger Sources • Polarity Control for Each Edge Source • Control of Edge Sequence • Control of Response to Edges • Precise Time Measurement Resolution of 1 ns • Accurate Current Source Suitable for Capacitive Measurement • On-Chip Temperature Measurement using a Built-in Diode Together with other on-chip analog modules, the CTMU can be used to precisely measure time, measure capacitance, measure relative changes in capacitance or generate output pulses that are independent of the system clock. The CTMU module is ideal for interfacing with capacitive-based sensors.The CTMU is controlled through three registers: CTMUCON1, CTMUCON2 and CTMUICON. CTMUCON1 and CTMUCON2 enable the module and control edge source selection, edge source polarity selection and edge sequencing. The CTMUICON register controls the selection and trim of the current source. Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X family of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Charge Time Measurement Unit (CTMU)” (DS70661) in the “dsPIC33/PIC24 Family Reference Manual”, which is available on the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 316  2011-2013 Microchip Technology Inc. FIGURE 22-1: CTMU BLOCK DIAGRAM 22.1 CTMU Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 22.1.1 KEY RESOURCES • “Charge Time Measurement Unit (CTMU)” (DS70661) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools CTED1 CTED2 Current Source Edge Control Logic Pulse Generator CMP1 Timer1 OC1 Current Control ITRIM<5:0> IRNG<1:0> CTMU Control Logic EDG1STAT EDG2STAT Analog-to-Digital CTPLS IC1 CMP1 C1IN1- CDelay CTMU TEMP(3) CTMU Temperature Sensor Current Control Selection TGEN EDG1STAT, EDG2STAT CTMU TEMP 0 EDG1STAT = EDG2STAT CTMUI to ADC(2) 0 EDG1STAT  EDG2STAT CTMUP 1 EDG1STAT  EDG2STAT Internal Current Flow(4) 1 EDG1STAT = EDG2STAT Trigger TGEN CTMUP External Capacitor for Pulse Generation CTMUI to ADC(2) Note 1: When the CTMU is not actively used, set TGEN = 1, and ensure that EDG1STAT = EDG2STAT. All other settings allow current to flow into the ADC or the C1IN1- pin. If using the ADC for other purposes besides the CTMU, set IDISSEN = 0. If IDISSEN is set to ‘1’, it will short the output of the ADC CH0 MUX to VSS. 2: CTMUI connects to the output of the ADC CH0 MUX. When CTMU current is steered into this node, the current will flow out through the selected ADC channel determined by the CH0 MUX (see the CH0Sx bits in the AD1CHS0 register). 3: CTMU TEMP connects to one of the ADC CH0 inputs; see CH0SA and CH0SB (AD1CHS0<12:8,4:0). 4: If TGEN = 1 and EDG1STAT = EDG2STAT, CTMU current source is still enabled and may be shunted to VSS internally. This should be considered in low-power applications. 5: The switch connected to ADC CH0 is closed when IDISSEN (CTMUCON1<9>) = 1, and opened when IDISSEN = 0. ADC CH0(5) CTMUCON1 or CTMUCON2(1) CTMUICON Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464  2011-2013 Microchip Technology Inc. DS70000657H-page 317 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 22.2 CTMU Control Registers REGISTER 22-1: CTMUCON1: CTMU CONTROL REGISTER 1 R/W-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 CTMUEN — CTMUSIDL TGEN EDGEN EDGSEQEN IDISSEN(1) CTTRIG bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 CTMUEN: CTMU Enable bit 1 = Module is enabled 0 = Module is disabled bit 14 Unimplemented: Read as ‘0’ bit 13 CTMUSIDL: CTMU Stop in Idle Mode bit 1 = Discontinues module operation when device enters Idle mode 0 = Continues module operation in Idle mode bit 12 TGEN: Time Generation Enable bit 1 = Enables edge delay generation 0 = Disables edge delay generation bit 11 EDGEN: Edge Enable bit 1 = Hardware modules are used to trigger edges (TMRx, CTEDx, etc.) 0 = Software is used to trigger edges (manual set of EDGxSTAT) bit 10 EDGSEQEN: Edge Sequence Enable bit 1 = Edge 1 event must occur before Edge 2 event can occur 0 = No edge sequence is needed bit 9 IDISSEN: Analog Current Source Control bit(1) 1 = Analog current source output is grounded 0 = Analog current source output is not grounded bit 8 CTTRIG: ADC Trigger Control bit 1 = CTMU triggers ADC start of conversion 0 = CTMU does not trigger ADC start of conversion bit 7-0 Unimplemented: Read as ‘0’ Note 1: The ADC module Sample-and-Hold capacitor is not automatically discharged between sample/conversion cycles. Software using the ADC as part of a capacitance measurement must discharge the ADC capacitor before conducting the measurement. The IDISSEN bit, when set to ‘1’, performs this function. The ADC must be sampling while the IDISSEN bit is active to connect the discharge sink to the capacitor array. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 318  2011-2013 Microchip Technology Inc. REGISTER 22-2: CTMUCON2: CTMU 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 EDG1MOD EDG1POL EDG1SEL3 EDG1SEL2 EDG1SEL1 EDG1SEL0 EDG2STAT EDG1STAT bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 U-0 U-0 EDG2MOD EDG2POL EDG2SEL3 EDG2SEL2 EDG2SEL1 EDG2SEL0 — — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 EDG1MOD: Edge 1 Edge Sampling Mode Selection bit 1 = Edge 1 is edge-sensitive 0 = Edge 1 is level-sensitive bit 14 EDG1POL: Edge 1 Polarity Select bit 1 = Edge 1 is programmed for a positive edge response 0 = Edge 1 is programmed for a negative edge response bit 13-10 EDG1SEL<3:0>: Edge 1 Source Select bits 1xxx = Reserved 01xx = Reserved 0011 = CTED1 pin 0010 = CTED2 pin 0001 = OC1 module 0000 = Timer1 module bit 9 EDG2STAT: Edge 2 Status bit Indicates the status of Edge 2 and can be written to control the edge source. 1 = Edge 2 has occurred 0 = Edge 2 has not occurred bit 8 EDG1STAT: Edge 1 Status bit Indicates the status of Edge 1 and can be written to control the edge source. 1 = Edge 1 has occurred 0 = Edge 1 has not occurred bit 7 EDG2MOD: Edge 2 Edge Sampling Mode Selection bit 1 = Edge 2 is edge-sensitive 0 = Edge 2 is level-sensitive bit 6 EDG2POL: Edge 2 Polarity Select bit 1 = Edge 2 is programmed for a positive edge response 0 = Edge 2 is programmed for a negative edge response bit 5-2 EDG2SEL<3:0>: Edge 2 Source Select bits 1111 = Reserved 01xx = Reserved 0100 = CMP1 module 0011 = CTED2 pin 0010 = CTED1 pin 0001 = OC1 module 0000 = IC1 module bit 1-0 Unimplemented: Read as ‘0’  2011-2013 Microchip Technology Inc. DS70000657H-page 319 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 22-3: CTMUICON: CTMU CURRENT 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 ITRIM5 ITRIM4 ITRIM3 ITRIM2 ITRIM1 ITRIM0 IRNG1 IRNG0 bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-10 ITRIM<5:0>: Current Source Trim bits 011111 = Maximum positive change from nominal current + 62% 011110 = Maximum positive change from nominal current + 60% • • • 000010 = Minimum positive change from nominal current + 4% 000001 = Minimum positive change from nominal current + 2% 000000 = Nominal current output specified by IRNG<1:0> 111111 = Minimum negative change from nominal current – 2% 111110 = Minimum negative change from nominal current – 4% • • • 100010 = Maximum negative change from nominal current – 60% 100001 = Maximum negative change from nominal current – 62% bit 9-8 IRNG<1:0>: Current Source Range Select bits 11 = 100  Base Current(2) 10 = 10  Base Current(2) 01 = Base Current Level(2) 00 = 1000  Base Current(1,2) bit 7-0 Unimplemented: Read as ‘0’ Note 1: This current range is not available to be used with the internal temperature measurement diode. 2: Refer to the CTMU Current Source Specifications (Table 30-56) in Section 30.0 “Electrical Characteristics” for the current range selection values. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 320  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 321 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 23.0 10-BIT/12-BIT ANALOG-TO-DIGITAL CONVERTER (ADC) The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X devices have one ADC module. The ADC module supports up to 16 analog input channels. On ADC1, the AD12B bit (AD1CON1<10>) allows the ADC module to be configured by the user as either a 10-bit, 4 Sample-and-Hold (S&H) ADC (default configuration) or a 12-bit, 1 S&H ADC. 23.1 Key Features 23.1.1 10-BIT ADC CONFIGURATION The 10-bit ADC configuration has the following key features: • Successive Approximation (SAR) conversion • Conversion speeds of up to 1.1 Msps • Up to 16 analog input pins • Connections to three internal op amps • Connections to the Charge Time Measurement Unit (CTMU) and temperature measurement diode • Channel selection and triggering can be controlled by the Peripheral Trigger Generator (PTG) • External voltage reference input pins • Simultaneous sampling of: - Up to four analog input pins - Three op amp outputs - Combinations of analog inputs and op amp outputs • Automatic Channel Scan mode • Selectable conversion Trigger source • Selectable Buffer Fill modes • Four result alignment options (signed/unsigned, fractional/integer) • Operation during CPU Sleep and Idle modes 23.1.2 12-BIT ADC CONFIGURATION The 12-bit ADC configuration supports all the features listed above, with the exception of the following: • In the 12-bit configuration, conversion speeds of up to 500 ksps are supported • There is only one S&H amplifier in the 12-bit configuration; therefore, simultaneous sampling of multiple channels is not supported. Depending on the particular device pinout, the ADC can have up to 16 analog input pins, designated AN0 through AN15. These analog inputs are shared with op amp inputs and outputs, comparator inputs, and external voltage references. When op amp/comparator functionality is enabled, or an external voltage reference is used, the analog input that shares that pin is no longer available. The actual number of analog input pins, op amps and external voltage reference input configuration depends on the specific device. A block diagram of the ADC module is shown in Figure 23-1. Figure 23-2 provides a diagram of the ADC conversion clock period. Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Analog-to-Digital Converter (ADC)” (DS70621) in the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. Note: The ADC module needs to be disabled before modifying the AD12B bit. DS70000657H-page 322 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. FIGURE 23-1: ADC MODULE BLOCK DIAGRAM WITH CONNECTION OPTIONS FOR ANx PINS AND OP AMPS 0 1 + – CMP1 /OA1 0x 10 11 VREFL VREFL VREFL + – CH0 0 1 VREFL AN0-ANx OA1-OA3 CH0Sx CH0Nx CH123Nx 00000 11111 OPMODE OPMODE OPMODE A B 1 CH0SA<4:0> 0 (3) CH0SB<4:0>(3) CH0Sx CH0Nx CH0NA(3) CH0NB(3) CSCNA CH123Sx CH123Nx CH123SA CH123SB CH123NA<2:0> CH123NB<2:0> S&H1 Alternate Input Selection Channel Scan This diagram depicts all of the available ADC connection options to the four S&H amplifiers, which are designated: CH0, CH1, CH2 and CH3. The ANx analog pins or op amp outputs are connected to the CH0-CH3 amplifiers through the multiplexers, controlled by the SFR control bits, CH0Sx, CHONx, CH123Sx and CH123Nx. A B A B A B + – CH1 + – CH2 + – CH3 0 1 CH123Sx + – OA2 0 1 CH123Sx 0x 10 11 CH123Nx 0x 10 11 CH123Nx + – OA3(5) CH123Sx AN0/OA2OUT/RA0 PGEC1/AN4/C1IN1+/RPI34/RB2 PGED1/AN5/C1IN1-/RP35/RB3 PGEC3/VREF+/AN3/OA1OUT/RPI33/CTED1/RB1 AN9/RPI27/RA11 AN1/C2IN1+/RA1 AN10/RPI28/RA12 PGED3/VREF-/AN2/C2IN1-/SS1/RPI32/CTED2/RB0 AN8/C3IN1+/U1RTS/BCLK1/RC2 AN6/OA3OUT/C4IN1+/OCFB/RC0 AN7/C3IN1-/C4IN1-/RC1 AN11/C1IN2-/U1CTS/RC11 + – OA1 VREF+(1) AVDD VREF- AVSS (1) VCFG<2:0> ADC1BUF0(4) ADC1BUF1(4) ADC1BUF2(4) ADC1BUFF(4) ADC1BUFE(4) From CTMU CTMU Temp Current Source (CTMUI) S&H2 S&H3 S&H0 Note 1: VREF+, VREF- inputs can be multiplexed with other analog inputs. 2: Channels 1, 2 and 3 are not applicable for the 12-bit mode of operation. 3: These bits can be updated with Step commands from the PTG module. See Section 24.0 “Peripheral Trigger Generator (PTG) Module” for more information. 4: When ADDMAEN (AD1CON4<8>) = 1, enabling DMA, only ADC1BUF0 is used. 5: OA3 is not available for 28-pin devices. Open ALTS (MUXA/MUXB) SAR ADC VREFH VREFL  2011-2013 Microchip Technology Inc. DS70000657H-page 323 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 23-2: ADC CONVERSION CLOCK PERIOD BLOCK DIAGRAM 1 0 ADC Conversion Clock Multiplier 1, 2, 3, 4, 5,..., 256 AD1CON3<15> TP(1) TAD 6 AD1CON3<7:0> Note 1: TP = 1/FP. 2: See the ADC electrical specifications in Section 30.0 “Electrical Characteristics” for the exact RC clock value. ADC Internal RC Clock(2) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 324  2011-2013 Microchip Technology Inc. 23.2 ADC Helpful Tips 1. The SMPIx control bits in the AD1CON2 register: a) Determine when the ADC interrupt flag is set and an interrupt is generated, if enabled. b) When the CSCNA bit in the AD1CON2 registers is set to ‘1’, this determines when the ADC analog scan channel list, defined in the AD1CSSL/AD1CSSH registers, starts over from the beginning. c) When the DMA peripheral is not used (ADDMAEN = 0), this determines when the ADC Result Buffer Pointer to ADC1BUF0- ADC1BUFF gets reset back to the beginning at ADC1BUF0. d) When the DMA peripheral is used (ADDMAEN = 1), this determines when the DMA Address Pointer is incremented after a sample/conversion operation. ADC1BUF0 is the only ADC buffer used in this mode. The ADC Result Buffer Pointer to ADC1BUF0- ADC1BUFF gets reset back to the beginning at ADC1BUF0. The DMA address is incremented after completion of every 32nd sample/conversion operation. Conversion results are stored in the ADC1BUF0 register for transfer to RAM using DMA. 2. When the DMA module is disabled (ADDMAEN = 0), the ADC has 16 result buffers. ADC conversion results are stored sequentially in ADC1BUF0-ADC1BUFF, regardless of which analog inputs are being used subject to the SMPIx bits and the condition described in 1c) above. There is no relationship between the ANx input being measured and which ADC buffer (ADC1BUF0-ADC1BUFF) that the conversion results will be placed in. 3. When the DMA module is enabled (ADDMAEN = 1), the ADC module has only 1 ADC result buffer (i.e., ADC1BUF0) per ADC peripheral and the ADC conversion result must be read, either by the CPU or DMA Controller, before the next ADC conversion is complete to avoid overwriting the previous value. 4. The DONE bit (AD1CON1<0>) is only cleared at the start of each conversion and is set at the completion of the conversion, but remains set indefinitely, even through the next sample phase until the next conversion begins. If application code is monitoring the DONE bit in any kind of software loop, the user must consider this behavior because the CPU code execution is faster than the ADC. As a result, in Manual Sample mode, particularly where the user’s code is setting the SAMP bit (AD1CON1<1>), the DONE bit should also be cleared by the user application just before setting the SAMP bit. 5. Enabling op amps, comparator inputs and external voltage references can limit the availability of analog inputs (ANx pins). For example, when Op Amp 2 is enabled, the pins for AN0, AN1 and AN2 are used by the op amp’s inputs and output. This negates the usefulness of Alternate Input mode since the MUXA selections use AN0-AN2. Carefully study the ADC block diagram to determine the configuration that will best suit your application. Configuration examples are available in the “Analog-to-Digital Converter (ADC)” (DS70621) section in the “dsPIC33/ PIC24 Family Reference Manual”. 23.3 ADC Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 23.3.1 KEY RESOURCES • “Analog-to-Digital Converter (ADC)” (DS70621) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464  2011-2013 Microchip Technology Inc. DS70000657H-page 325 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 23.4 ADC Control Registers REGISTER 23-1: AD1CON1: ADC1 CONTROL REGISTER 1 R/W-0 U-0 R/W-0 R/W-0 U-0 R/W-0 R/W-0 R/W-0 ADON — ADSIDL ADDMABM — AD12B FORM1 FORM0 bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0, HC, HS R/C-0, HC, HS SSRC2 SSRC1 SSRC0 SSRCG SIMSAM ASAM SAMP DONE(3) bit 7 bit 0 Legend: HC = Hardware Clearable bit HS = Hardware Settable bit C = Clearable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 ADON: ADC1 Operating Mode bit 1 = ADC module is operating 0 = ADC is off bit 14 Unimplemented: Read as ‘0’ bit 13 ADSIDL: ADC1 Stop in Idle Mode bit 1 = Discontinues module operation when device enters Idle mode 0 = Continues module operation in Idle mode bit 12 ADDMABM: DMA Buffer Build Mode bit 1 = DMA buffers are written in the order of conversion; the module provides an address to the DMA channel that is the same as the address used for the non-DMA stand-alone buffer 0 = DMA buffers are written in Scatter/Gather mode; the module provides a Scatter/Gather address to the DMA channel, based on the index of the analog input and the size of the DMA buffer. bit 11 Unimplemented: Read as ‘0’ bit 10 AD12B: ADC1 10-Bit or 12-Bit Operation Mode bit 1 = 12-bit, 1-channel ADC operation 0 = 10-bit, 4-channel ADC operation bit 9-8 FORM<1:0>: Data Output Format bits For 10-Bit Operation: 11 = Signed fractional (DOUT = sddd dddd dd00 0000, where s = .NOT.d<9>) 10 = Fractional (DOUT = dddd dddd dd00 0000) 01 = Signed integer (DOUT = ssss sssd dddd dddd, where s = .NOT.d<9>) 00 = Integer (DOUT = 0000 00dd dddd dddd) For 12-Bit Operation: 11 = Signed fractional (DOUT = sddd dddd dddd 0000, where s = .NOT.d<11>) 10 = Fractional (DOUT = dddd dddd dddd 0000) 01 = Signed integer (DOUT = ssss sddd dddd dddd, where s = .NOT.d<11>) 00 = Integer (DOUT = 0000 dddd dddd dddd) Note 1: See Section 24.0 “Peripheral Trigger Generator (PTG) Module” for information on this selection. 2: This setting is available in dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. 3: Do not clear the DONE bit in software if Auto-Sample is enabled (ASAM = 1). dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 326  2011-2013 Microchip Technology Inc. bit 7-5 SSRC<2:0>: Sample Trigger Source Select bits If SSRCG = 1: 111 = Reserved 110 = PTGO15 primary trigger compare ends sampling and starts conversion(1) 101 = PTGO14 primary trigger compare ends sampling and starts conversion(1) 100 = PTGO13 primary trigger compare ends sampling and starts conversion(1) 011 = PTGO12 primary trigger compare ends sampling and starts conversion(1) 010 = PWM Generator 3 primary trigger compare ends sampling and starts conversion(2) 001 = PWM Generator 2 primary trigger compare ends sampling and starts conversion(2) 000 = PWM Generator 1 primary trigger compare ends sampling and starts conversion(2) If SSRCG = 0: 111 = Internal counter ends sampling and starts conversion (auto-convert) 110 = CTMU ends sampling and starts conversion 101 = Reserved 100 = Timer5 compare ends sampling and starts conversion 011 = PWM primary Special Event Trigger ends sampling and starts conversion(2) 010 = Timer3 compare ends sampling and starts conversion 001 = Active transition on the INT0 pin ends sampling and starts conversion 000 = Clearing the Sample bit (SAMP) ends sampling and starts conversion (Manual mode) bit 4 SSRCG: Sample Trigger Source Group bit See SSRC<2:0> for details. bit 3 SIMSAM: Simultaneous Sample Select bit (only applicable when CHPS<1:0> = 01 or 1x) In 12-bit mode (AD21B = 1), SIMSAM is Unimplemented and is Read as ‘0’: 1 = Samples CH0, CH1, CH2, CH3 simultaneously (when CHPS<1:0> = 1x); or samples CH0 and CH1 simultaneously (when CHPS<1:0> = 01) 0 = Samples multiple channels individually in sequence bit 2 ASAM: ADC1 Sample Auto-Start bit 1 = Sampling begins immediately after the last conversion; SAMP bit is auto-set 0 = Sampling begins when the SAMP bit is set bit 1 SAMP: ADC1 Sample Enable bit 1 = ADC Sample-and-Hold amplifiers are sampling 0 = ADC Sample-and-Hold amplifiers are holding If ASAM = 0, software can write ‘1’ to begin sampling. Automatically set by hardware if ASAM = 1. If SSRC<2:0> = 000, software can write ‘0’ to end sampling and start conversion. If SSRC<2:0> 000, automatically cleared by hardware to end sampling and start conversion. bit 0 DONE: ADC1 Conversion Status bit(3) 1 = ADC conversion cycle has completed 0 = ADC conversion has not started or is in progress Automatically set by hardware when the ADC conversion is complete. Software can write ‘0’ to clear the DONE status bit (software is not allowed to write ‘1’). Clearing this bit does NOT affect any operation in progress. Automatically cleared by hardware at the start of a new conversion. REGISTER 23-1: AD1CON1: ADC1 CONTROL REGISTER 1 (CONTINUED) Note 1: See Section 24.0 “Peripheral Trigger Generator (PTG) Module” for information on this selection. 2: This setting is available in dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. 3: Do not clear the DONE bit in software if Auto-Sample is enabled (ASAM = 1).  2011-2013 Microchip Technology Inc. DS70000657H-page 327 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 23-2: AD1CON2: ADC1 CONTROL REGISTER 2 R/W-0 R/W-0 R/W-0 U-0 U-0 R/W-0 R/W-0 R/W-0 VCFG2 VCFG1 VCFG0 — — CSCNA CHPS1 CHPS0 bit 15 bit 8 R-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 BUFS SMPI4 SMPI3 SMPI2 SMPI1 SMPI0 BUFM ALTS bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-13 VCFG<2:0>: Converter Voltage Reference Configuration bits bit 12-11 Unimplemented: Read as ‘0’ bit 10 CSCNA: Input Scan Select bit 1 = Scans inputs for CH0+ during Sample MUXA 0 = Does not scan inputs bit 9-8 CHPS<1:0>: Channel Select bits In 12-bit mode (AD21B = 1), the CHPS<1:0> bits are Unimplemented and are Read as ‘0’: 1x = Converts CH0, CH1, CH2 and CH3 01 = Converts CH0 and CH1 00 = Converts CH0 bit 7 BUFS: Buffer Fill Status bit (only valid when BUFM = 1) 1 = ADC is currently filling the second half of the buffer; the user application should access data in the first half of the buffer 0 = ADC is currently filling the first half of the buffer; the user application should access data in the second half of the buffer bit 6-2 SMPI<4:0>: Increment Rate bits When ADDMAEN = 0: x1111 = Generates interrupt after completion of every 16th sample/conversion operation x1110 = Generates interrupt after completion of every 15th sample/conversion operation • • • x0001 = Generates interrupt after completion of every 2nd sample/conversion operation x0000 = Generates interrupt after completion of every sample/conversion operation When ADDMAEN = 1: 11111 = Increments the DMA address after completion of every 32nd sample/conversion operation 11110 = Increments the DMA address after completion of every 31st sample/conversion operation • • • 00001 = Increments the DMA address after completion of every 2nd sample/conversion operation 00000 = Increments the DMA address after completion of every sample/conversion operation Value VREFH VREFL 000 AVDD Avss 001 External VREF+ Avss 010 AVDD External VREF011 External VREF+ External VREF1xx AVDD AVSS dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 328  2011-2013 Microchip Technology Inc. bit 1 BUFM: Buffer Fill Mode Select bit 1 = Starts the buffer filling the first half of the buffer on the first interrupt and the second half of the buffer on next interrupt 0 = Always starts filling the buffer from the start address. bit 0 ALTS: Alternate Input Sample Mode Select bit 1 = Uses channel input selects for Sample MUXA on first sample and Sample MUXB on next sample 0 = Always uses channel input selects for Sample MUXA REGISTER 23-2: AD1CON2: ADC1 CONTROL REGISTER 2 (CONTINUED)  2011-2013 Microchip Technology Inc. DS70000657H-page 329 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 23-3: AD1CON3: ADC1 CONTROL REGISTER 3 R/W-0 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 ADRC — — SAMC4(1) SAMC3(1) SAMC2(1) SAMC1(1) SAMC0(1) bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 ADCS7(2) ADCS6(2) ADCS5(2) ADCS4(2) ADCS3(2) ADCS2(2) ADCS1(2) ADCS0(2) bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 ADRC: ADC1 Conversion Clock Source bit 1 = ADC internal RC clock 0 = Clock derived from system clock bit 14-13 Unimplemented: Read as ‘0’ bit 12-8 SAMC<4:0>: Auto-Sample Time bits(1) 11111 = 31 TAD • • • 00001 = 1 TAD 00000 = 0 TAD bit 7-0 ADCS<7:0>: ADC1 Conversion Clock Select bits(2) 11111111 = TP • (ADCS<7:0> + 1) = TP •256 = TAD • • • 00000010 = TP • (ADCS<7:0> + 1) = TP •3 = TAD 00000001 = TP • (ADCS<7:0> + 1) = TP •2 = TAD 00000000 = TP • (ADCS<7:0> + 1) = TP •1 = TAD Note 1: This bit is only used if SSRC<2:0> (AD1CON1<7:5>) = 111 and SSRCG (AD1CON1<4>) = 0. 2: This bit is not used if ADRC (AD1CON3<15>) = 1. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 330  2011-2013 Microchip Technology Inc. REGISTER 23-4: AD1CON4: ADC1 CONTROL REGISTER 4 U-0 U-0 U-0 U-0 U-0 U-0 U-0 R/W-0 — — — — — — — ADDMAEN bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 — — — — — DMABL2 DMABL1 DMABL0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-9 Unimplemented: Read as ‘0’ bit 8 ADDMAEN: ADC1 DMA Enable bit 1 = Conversion results are stored in the ADC1BUF0 register for transfer to RAM using DMA 0 = Conversion results are stored in ADC1BUF0 through ADC1BUFF registers; DMA will not be used bit 7-3 Unimplemented: Read as ‘0’ bit 2-0 DMABL<2:0>: Selects Number of DMA Buffer Locations per Analog Input bits 111 = Allocates 128 words of buffer to each analog input 110 = Allocates 64 words of buffer to each analog input 101 = Allocates 32 words of buffer to each analog input 100 = Allocates 16 words of buffer to each analog input 011 = Allocates 8 words of buffer to each analog input 010 = Allocates 4 words of buffer to each analog input 001 = Allocates 2 words of buffer to each analog input 000 = Allocates 1 word of buffer to each analog input  2011-2013 Microchip Technology Inc. DS70000657H-page 331 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 23-5: AD1CHS123: ADC1 INPUT CHANNEL 1, 2, 3 SELECT REGISTER U-0 U-0 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 — — — — — CH123NB1 CH123NB0 CH123SB bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 — — — — — CH123NA1 CH123NA0 CH123SA bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-11 Unimplemented: Read as ‘0’ bit 10-9 CH123NB<1:0>: Channel 1, 2, 3 Negative Input Select for Sample MUXB bits In 12-bit mode (AD21B = 1), CH123NB is Unimplemented and is Read as ‘0’: bit 8 CH123SB: Channel 1, 2, 3 Positive Input Select for Sample MUXB bit In 12-bit mode (AD21B = 1), CH123SB is Unimplemented and is Read as ‘0’: bit 7-3 Unimplemented: Read as ‘0’ bit 2-1 CH123NA<1:0>: Channel 1, 2, 3 Negative Input Select for Sample MUXA bits In 12-bit mode (AD21B = 1), CH123NA is Unimplemented and is Read as ‘0’: Note 1: AN0 through AN7 are repurposed when comparator and op amp functionality is enabled. See Figure 23-1 to determine how enabling a particular op amp or comparator affects selection choices for Channels 1, 2 and 3. 2: The OAx input is used if the corresponding op amp is selected (OPMODE (CMxCON<10>) = 1); otherwise, the ANx input is used. Value ADC Channel CH1 CH2 CH3 11 AN9 AN10 AN11 10(1,2) OA3/AN6 AN7 AN8 0x VREFL VREFL VREFL Value ADC Channel CH1 CH2 CH3 1(2) OA1/AN3 OA2/AN0 OA3/AN6 0(1,2) OA2/AN0 AN1 AN2 Value ADC Channel CH1 CH2 CH3 11 AN9 AN10 AN11 10(1,2) OA3/AN6 AN7 AN8 0x VREFL VREFL VREFL dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 332  2011-2013 Microchip Technology Inc. bit 0 CH123SA: Channel 1, 2, 3 Positive Input Select for Sample MUXA bit In 12-bit mode (AD21B = 1), CH123SA is Unimplemented and is Read as ‘0’: REGISTER 23-5: AD1CHS123: ADC1 INPUT CHANNEL 1, 2, 3 SELECT REGISTER (CONTINUED) Note 1: AN0 through AN7 are repurposed when comparator and op amp functionality is enabled. See Figure 23-1 to determine how enabling a particular op amp or comparator affects selection choices for Channels 1, 2 and 3. 2: The OAx input is used if the corresponding op amp is selected (OPMODE (CMxCON<10>) = 1); otherwise, the ANx input is used. Value ADC Channel CH1 CH2 CH3 1(2) OA1/AN3 OA2/AN0 OA3/AN6 0(1,2) OA2/AN0 AN1 AN2  2011-2013 Microchip Technology Inc. DS70000657H-page 333 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 23-6: AD1CHS0: ADC1 INPUT CHANNEL 0 SELECT REGISTER R/W-0 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 CH0NB — — CH0SB4(1) CH0SB3(1) CH0SB2(1) CH0SB1(1) CH0SB0(1) bit 15 bit 8 R/W-0 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 CH0NA — — CH0SA4(1) CH0SA3(1) CH0SA2(1) CH0SA1(1) CH0SA0(1) bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 CH0NB: Channel 0 Negative Input Select for Sample MUXB bit 1 = Channel 0 negative input is AN1(1) 0 = Channel 0 negative input is VREFL bit 14-13 Unimplemented: Read as ‘0’ bit 12-8 CH0SB<4:0>: Channel 0 Positive Input Select for Sample MUXB bits(1) 11111 = Open; use this selection with CTMU capacitive and time measurement 11110 = Channel 0 positive input is connected to the CTMU temperature measurement diode (CTMU TEMP) 11101 = Reserved 11100 = Reserved 11011 = Reserved 11010 = Channel 0 positive input is the output of OA3/AN6(2,3) 11001 = Channel 0 positive input is the output of OA2/AN0(2) 11000 = Channel 0 positive input is the output of OA1/AN3(2) 10111 = Reserved • • • 10000 = Reserved 01111 = Channel 0 positive input is AN15(3) 01110 = Channel 0 positive input is AN14(3) 01101 = Channel 0 positive input is AN13(3) • • • 00010 = Channel 0 positive input is AN2(3) 00001 = Channel 0 positive input is AN1(3) 00000 = Channel 0 positive input is AN0(3) bit 7 CH0NA: Channel 0 Negative Input Select for Sample MUXA bit 1 = Channel 0 negative input is AN1(1) 0 = Channel 0 negative input is VREFL bit 6-5 Unimplemented: Read as ‘0’ Note 1: AN0 through AN7 are repurposed when comparator and op amp functionality is enabled. See Figure 23-1 to determine how enabling a particular op amp or comparator affects selection choices for Channels 1, 2 and 3. 2: The OAx input is used if the corresponding op amp is selected (OPMODE (CMxCON<10>) = 1); otherwise, the ANx input is used. 3: See the “Pin Diagrams” section for the available analog channels for each device. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 334  2011-2013 Microchip Technology Inc. bit 4-0 CH0SA<4:0>: Channel 0 Positive Input Select for Sample MUXA bits(1) 11111 = Open; use this selection with CTMU capacitive and time measurement 11110 = Channel 0 positive input is connected to the CTMU temperature measurement diode (CTMU TEMP) 11101 = Reserved 11100 = Reserved 11011 = Reserved 11010 = Channel 0 positive input is the output of OA3/AN6(2,3) 11001 = Channel 0 positive input is the output of OA2/AN0(2) 11000 = Channel 0 positive input is the output of OA1/AN3(2) 10110 = Reserved • • • 10000 = Reserved 01111 = Channel 0 positive input is AN15(1,3) 01110 = Channel 0 positive input is AN14(1,3) 01101 = Channel 0 positive input is AN13(1,3) • • • 00010 = Channel 0 positive input is AN2(1,3) 00001 = Channel 0 positive input is AN1(1,3) 00000 = Channel 0 positive input is AN0(1,3) REGISTER 23-6: AD1CHS0: ADC1 INPUT CHANNEL 0 SELECT REGISTER (CONTINUED) Note 1: AN0 through AN7 are repurposed when comparator and op amp functionality is enabled. See Figure 23-1 to determine how enabling a particular op amp or comparator affects selection choices for Channels 1, 2 and 3. 2: The OAx input is used if the corresponding op amp is selected (OPMODE (CMxCON<10>) = 1); otherwise, the ANx input is used. 3: See the “Pin Diagrams” section for the available analog channels for each device.  2011-2013 Microchip Technology Inc. DS70000657H-page 335 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 23-7: AD1CSSH: ADC1 INPUT SCAN SELECT REGISTER HIGH(1) R/W-0 R/W-0 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 CSS31 CSS30 — — — CSS26(2) CSS25(2) CSS24(2) bit 15 bit 8 U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 CSS31: ADC1 Input Scan Selection bit 1 = Selects CTMU capacitive and time measurement for input scan (Open) 0 = Skips CTMU capacitive and time measurement for input scan (Open) bit 14 CSS30: ADC1 Input Scan Selection bit 1 = Selects CTMU on-chip temperature measurement for input scan (CTMU TEMP) 0 = Skips CTMU on-chip temperature measurement for input scan (CTMU TEMP) bit 13-11 Unimplemented: Read as ‘0’ bit 10 CSS26: ADC1 Input Scan Selection bit(2) 1 = Selects OA3/AN6 for input scan 0 = Skips OA3/AN6 for input scan bit 9 CSS25: ADC1 Input Scan Selection bit(2) 1 = Selects OA2/AN0 for input scan 0 = Skips OA2/AN0 for input scan bit 8 CSS24: ADC1 Input Scan Selection bit(2) 1 = Selects OA1/AN3 for input scan 0 = Skips OA1/AN3 for input scan bit 7-0 Unimplemented: Read as ‘0’ Note 1: All AD1CSSH bits can be selected by user software. However, inputs selected for scan, without a corresponding input on the device, convert VREFL. 2: The OAx input is used if the corresponding op amp is selected (OPMODE (CMxCON<10>) = 1); otherwise, the ANx input is used. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 336  2011-2013 Microchip Technology Inc. REGISTER 23-8: AD1CSSL: ADC1 INPUT SCAN SELECT REGISTER LOW(1,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 CSS15 CSS14 CSS13 CSS12 CSS11 CSS10 CSS9 CSS8 bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 CSS7 CSS6 CSS5 CSS4 CSS3 CSS2 CSS1 CSS0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 CSS<15:0>: ADC1 Input Scan Selection bits 1 = Selects ANx for input scan 0 = Skips ANx for input scan Note 1: On devices with less than 16 analog inputs, all AD1CSSL bits can be selected by the user. However, inputs selected for scan, without a corresponding input on the device, convert VREFL. 2: CSSx = ANx, where x = 0-15.  2011-2013 Microchip Technology Inc. DS70000657H-page 337 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 24.0 PERIPHERAL TRIGGER GENERATOR (PTG) MODULE 24.1 Module Introduction The Peripheral Trigger Generator (PTG) provides a means to schedule complex high-speed peripheral operations that would be difficult to achieve using software. The PTG module uses 8-bit commands, called “Steps”, that the user writes to the PTG Queue registers (PTGQUE0-PTGQUE7), which perform operations, such as wait for input signal, generate output trigger and wait for timer. The PTG module has the following major features: • Multiple clock sources • Two 16-bit general purpose timers • Two 16-bit general limit counters • Configurable for rising or falling edge triggering • Generates processor interrupts to include: - Four configurable processor interrupts - Interrupt on a Step event in Single-Step mode - Interrupt on a PTG Watchdog Timer time-out • Able to receive trigger signals from these peripherals: - ADC - PWM - Output Compare - Input Capture - Op Amp/Comparator - INT2 • Able to trigger or synchronize to these peripherals: - Watchdog Timer - Output Compare - Input Capture - ADC - PWM - Op Amp/Comparator Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Peripheral Trigger Generator (PTG)” (DS70669) in the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 338  2011-2013 Microchip Technology Inc. FIGURE 24-1: PTG BLOCK DIAGRAM 16-Bit Data Bus PTGQPTR<4:0> Command Decoder PTGHOLD PTGADJ PTG Watchdog Timer(1) PTG Control Logic PTGWDTIF PTG General Purpose Timerx PTG Loop Counter x Clock Inputs FP TAD T1CLK T2CLK T3CLK PTGCLK<2:0> PTGL0<15:0> PTGTxLIM<15:0> PTGCxLIM<15:0> PTGBTE<15:0> PTGO0 PTGSDLIM<15:0> PTG Step Delay Timer PWM OC1 OC2 IC1 CMPx ADC INT2 PTGCON<15:0> PTG Interrupts Trigger Outputs AD1CHS0<15:0> Step Command Step Command PTGSTEPIF Trigger Inputs PTGO31 • • • PTG0IF PTG3IF • • • Step Command Step Command FOSC  PTGDIV<4:0> PTGCST<15:0> Note 1: This is a dedicated Watchdog Timer for the PTG module and is independent of the device Watchdog Timer. PTGQUE0 PTGQUE1 PTGQUE2 PTGQUE3 PTGQUE5 PTGQUE4 PTGQUE6 PTGQUE7  2011-2013 Microchip Technology Inc. DS70000657H-page 339 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 24.2 PTG Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 24.2.1 KEY RESOURCES • “Peripheral Trigger Generator” (DS70669) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 340  2011-2013 Microchip Technology Inc. 24.3 PTG Control Registers REGISTER 24-1: PTGCST: PTG CONTROL/STATUS REGISTER R/W-0 U-0 R/W-0 R/W-0 U-0 R/W-0 R/W-0 R/W-0 PTGEN — PTGSIDL PTGTOGL — PTGSWT(2) PTGSSEN(3) PTGIVIS bit 15 bit 8 R/W-0 HS-0 U-0 U-0 U-0 U-0 R/W-0 PTGSTRT PTGWDTO — — — — PTGITM1(1) PTGITM0(1) bit 7 bit 0 Legend: HS = Hardware Settable bit R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 PTGEN: Module Enable bit 1 = PTG module is enabled 0 = PTG module is disabled bit 14 Unimplemented: Read as ‘0’ bit 13 PTGSIDL: PTG Stop in Idle Mode bit 1 = Discontinues module operation when device enters Idle mode 0 = Continues module operation in Idle mode bit 12 PTGTOGL: PTG TRIG Output Toggle Mode bit 1 = Toggle state of the PTGOx for each execution of the PTGTRIG command 0 = Each execution of the PTGTRIG command will generate a single PTGOx pulse determined by the value in the PTGPWDx bits bit 11 Unimplemented: Read as ‘0’ bit 10 PTGSWT: PTG Software Trigger bit(2) 1 = Triggers the PTG module 0 = No action (clearing this bit will have no effect) bit 9 PTGSSEN: PTG Enable Single-Step bit(3) 1 = Enables Single-Step mode 0 = Disables Single-Step mode bit 8 PTGIVIS: PTG Counter/Timer Visibility Control bit 1 = Reads of the PTGSDLIM, PTGCxLIM or PTGTxLIM registers return the current values of their corresponding counter/timer registers (PTGSD, PTGCx, PTGTx) 0 = Reads of the PTGSDLIM, PTGCxLIM or PTGTxLIM registers return the value previously written to those limit registers bit 7 PTGSTRT: PTG Start Sequencer bit 1 = Starts to sequentially execute commands (Continuous mode) 0 = Stops executing commands bit 6 PTGWDTO: PTG Watchdog Timer Time-out Status bit 1 = PTG Watchdog Timer has timed out 0 = PTG Watchdog Timer has not timed out. bit 5-2 Unimplemented: Read as ‘0’ Note 1: These bits apply to the PTGWHI and PTGWLO commands only. 2: This bit is only used with the PTGCTRL step command software trigger option. 3: Use of the PTG Single-Step mode is reserved for debugging tools only.  2011-2013 Microchip Technology Inc. DS70000657H-page 341 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 1-0 PTGITM<1:0>: PTG Input Trigger Command Operating Mode bits(1) 11 = Single level detect with Step delay not executed on exit of command (regardless of the PTGCTRL command) 10 = Single level detect with Step delay executed on exit of command 01 = Continuous edge detect with Step delay not executed on exit of command (regardless of the PTGCTRL command) 00 = Continuous edge detect with Step delay executed on exit of command REGISTER 24-1: PTGCST: PTG CONTROL/STATUS REGISTER (CONTINUED) Note 1: These bits apply to the PTGWHI and PTGWLO commands only. 2: This bit is only used with the PTGCTRL step command software trigger option. 3: Use of the PTG Single-Step mode is reserved for debugging tools only. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 342  2011-2013 Microchip Technology Inc. REGISTER 24-2: PTGCON: PTG 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 PTGCLK2 PTGCLK1 PTGCLK0 PTGDIV4 PTGDIV3 PTGDIV2 PTGDIV1 PTGDIV0 bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 U-0 R/W-0 R/W-0 R/W-0 PTGPWD3 PTGPWD2 PTGPWD1 PTGPWD0 — PTGWDT2 PTGWDT1 PTGWDT0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-13 PTGCLK<2:0>: Select PTG Module Clock Source bits 111 = Reserved 110 = Reserved 101 = PTG module clock source will be T3CLK 100 = PTG module clock source will be T2CLK 011 = PTG module clock source will be T1CLK 010 = PTG module clock source will be TAD 001 = PTG module clock source will be FOSC 000 = PTG module clock source will be FP bit 12-8 PTGDIV<4:0>: PTG Module Clock Prescaler (divider) bits 11111 = Divide-by-32 11110 = Divide-by-31 • • • 00001 = Divide-by-2 00000 = Divide-by-1 bit 7-4 PTGPWD<3:0>: PTG Trigger Output Pulse-Width bits 1111 = All trigger outputs are 16 PTG clock cycles wide 1110 = All trigger outputs are 15 PTG clock cycles wide • • • 0001 = All trigger outputs are 2 PTG clock cycles wide 0000 = All trigger outputs are 1 PTG clock cycle wide bit 3 Unimplemented: Read as ‘0’ bit 2-0 PTGWDT<2:0>: Select PTG Watchdog Timer Time-out Count Value bits 111 = Watchdog Timer will time-out after 512 PTG clocks 110 = Watchdog Timer will time-out after 256 PTG clocks 101 = Watchdog Timer will time-out after 128 PTG clocks 100 = Watchdog Timer will time-out after 64 PTG clocks 011 = Watchdog Timer will time-out after 32 PTG clocks 010 = Watchdog Timer will time-out after 16 PTG clocks 001 = Watchdog Timer will time-out after 8 PTG clocks 000 = Watchdog Timer is disabled  2011-2013 Microchip Technology Inc. DS70000657H-page 343 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 24-3: PTGBTE: PTG BROADCAST TRIGGER ENABLE REGISTER(1,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 ADCTS4 ADCTS3 ADCTS2 ADCTS1 IC4TSS IC3TSS IC2TSS IC1TSS bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 OC4CS OC3CS OC2CS OC1CS OC4TSS OC3TSS OC2TSS OC1TSS bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 ADCTS4: Sample Trigger PTGO15 for ADC bit 1 = Generates Trigger when the broadcast command is executed 0 = Does not generate Trigger when the broadcast command is executed bit 14 ADCTS3: Sample Trigger PTGO14 for ADC bit 1 = Generates Trigger when the broadcast command is executed 0 = Does not generate Trigger when the broadcast command is executed bit 13 ADCTS2: Sample Trigger PTGO13 for ADC bit 1 = Generates Trigger when the broadcast command is executed 0 = Does not generate Trigger when the broadcast command is executed bit 12 ADCTS1: Sample Trigger PTGO12 for ADC bit 1 = Generates Trigger when the broadcast command is executed 0 = Does not generate Trigger when the broadcast command is executed bit 11 IC4TSS: Trigger/Synchronization Source for IC4 bit 1 = Generates Trigger/Synchronization when the broadcast command is executed 0 = Does not generate Trigger/Synchronization when the broadcast command is executed bit 10 IC3TSS: Trigger/Synchronization Source for IC3 bit 1 = Generates Trigger/Synchronization when the broadcast command is executed 0 = Does not generate Trigger/Synchronization when the broadcast command is executed bit 9 IC2TSS: Trigger/Synchronization Source for IC2 bit 1 = Generates Trigger/Synchronization when the broadcast command is executed 0 = Does not generate Trigger/Synchronization when the broadcast command is executed bit 8 IC1TSS: Trigger/Synchronization Source for IC1 bit 1 = Generates Trigger/Synchronization when the broadcast command is executed 0 = Does not generate Trigger/Synchronization when the broadcast command is executed bit 7 OC4CS: Clock Source for OC4 bit 1 = Generates clock pulse when the broadcast command is executed 0 = Does not generate clock pulse when the broadcast command is executed bit 6 OC3CS: Clock Source for OC3 bit 1 = Generates clock pulse when the broadcast command is executed 0 = Does not generate clock pulse when the broadcast command is executed bit 5 OC2CS: Clock Source for OC2 bit 1 = Generates clock pulse when the broadcast command is executed 0 = Does not generate clock pulse when the broadcast command is executed Note 1: This register is read-only when the PTG module is executing Step commands (PTGEN = 1 and PTGSTRT = 1). 2: This register is only used with the PTGCTRL OPTION = 1111 Step command. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 344  2011-2013 Microchip Technology Inc. bit 4 OC1CS: Clock Source for OC1 bit 1 = Generates clock pulse when the broadcast command is executed 0 = Does not generate clock pulse when the broadcast command is executed bit 3 OC4TSS: Trigger/Synchronization Source for OC4 bit 1 = Generates Trigger/Synchronization when the broadcast command is executed 0 = Does not generate Trigger/Synchronization when the broadcast command is executed bit 2 OC3TSS: Trigger/Synchronization Source for OC3 bit 1 = Generates Trigger/Synchronization when the broadcast command is executed 0 = Does not generate Trigger/Synchronization when the broadcast command is executed bit 1 OC2TSS: Trigger/Synchronization Source for OC2 bit 1 = Generates Trigger/Synchronization when the broadcast command is executed 0 = Does not generate Trigger/Synchronization when the broadcast command is executed bit 0 OC1TSS: Trigger/Synchronization Source for OC1 bit 1 = Generates Trigger/Synchronization when the broadcast command is executed 0 = Does not generate Trigger/Synchronization when the broadcast command is executed REGISTER 24-3: PTGBTE: PTG BROADCAST TRIGGER ENABLE REGISTER(1,2) (CONTINUED) Note 1: This register is read-only when the PTG module is executing Step commands (PTGEN = 1 and PTGSTRT = 1). 2: This register is only used with the PTGCTRL OPTION = 1111 Step command.  2011-2013 Microchip Technology Inc. DS70000657H-page 345 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 24-4: PTGT0LIM: PTG TIMER0 LIMIT 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 PTGT0LIM<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 PTGT0LIM<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 PTGT0LIM<15:0>: PTG Timer0 Limit Register bits General Purpose Timer0 Limit register (effective only with a PTGT0 Step command). Note 1: This register is read-only when the PTG module is executing Step commands (PTGEN = 1 and PTGSTRT = 1). REGISTER 24-5: PTGT1LIM: PTG TIMER1 LIMIT 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 PTGT1LIM<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 PTGT1LIM<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 PTGT1LIM<15:0>: PTG Timer1 Limit Register bits General Purpose Timer1 Limit register (effective only with a PTGT1 Step command). Note 1: This register is read-only when the PTG module is executing Step commands (PTGEN = 1 and PTGSTRT = 1). dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 346  2011-2013 Microchip Technology Inc. REGISTER 24-6: PTGSDLIM: PTG STEP DELAY LIMIT REGISTER(1,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 PTGSDLIM<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 PTGSDLIM<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 PTGSDLIM<15:0>: PTG Step Delay Limit Register bits Holds a PTG Step delay value representing the number of additional PTG clocks between the start of a Step command and the completion of a Step command. Note 1: A base Step delay of one PTG clock is added to any value written to the PTGSDLIM register (Step Delay = (PTGSDLIM) + 1). 2: This register is read-only when the PTG module is executing Step commands (PTGEN = 1 and PTGSTRT = 1). REGISTER 24-7: PTGC0LIM: PTG COUNTER 0 LIMIT 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 PTGC0LIM<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 PTGC0LIM<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 PTGC0LIM<15:0>: PTG Counter 0 Limit Register bits May be used to specify the loop count for the PTGJMPC0 Step command or as a limit register for the General Purpose Counter 0. Note 1: This register is read-only when the PTG module is executing Step commands (PTGEN = 1 and PTGSTRT = 1).  2011-2013 Microchip Technology Inc. DS70000657H-page 347 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 24-8: PTGC1LIM: PTG COUNTER 1 LIMIT 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 PTGC1LIM<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 PTGC1LIM<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 PTGC1LIM<15:0>: PTG Counter 1 Limit Register bits May be used to specify the loop count for the PTGJMPC1 Step command or as a limit register for the General Purpose Counter 1. Note 1: This register is read-only when the PTG module is executing Step commands (PTGEN = 1 and PTGSTRT = 1). REGISTER 24-9: PTGHOLD: PTG HOLD 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 PTGHOLD<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 PTGHOLD<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 PTGHOLD<15:0>: PTG General Purpose Hold Register bits Holds user-supplied data to be copied to the PTGTxLIM, PTGCxLIM, PTGSDLIM or PTGL0 registers with the PTGCOPY command. Note 1: This register is read-only when the PTG module is executing Step commands (PTGEN = 1 and PTGSTRT = 1). dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 348  2011-2013 Microchip Technology Inc. REGISTER 24-10: PTGADJ: PTG ADJUST 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 PTGADJ<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 PTGADJ<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 PTGADJ<15:0>: PTG Adjust Register bits This register holds user-supplied data to be added to the PTGTxLIM, PTGCxLIM, PTGSDLIM or PTGL0 registers with the PTGADD command. Note 1: This register is read-only when the PTG module is executing Step commands (PTGEN = 1 and PTGSTRT = 1). REGISTER 24-11: PTGL0: PTG LITERAL 0 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 PTGL0<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 PTGL0<7:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 PTGL0<15:0>: PTG Literal 0 Register bits This register holds the 16-bit value to be written to the AD1CHS0 register with the PTGCTRL Step command. Note 1: This register is read-only when the PTG module is executing Step commands (PTGEN = 1 and PTGSTRT = 1).  2011-2013 Microchip Technology Inc. DS70000657H-page 349 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 24-12: PTGQPTR: PTG STEP QUEUE POINTER REGISTER(1) U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — — PTGQPTR<4:0> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-5 Unimplemented: Read as ‘0’ bit 4-0 PTGQPTR<4:0>: PTG Step Queue Pointer Register bits This register points to the currently active Step command in the Step queue. Note 1: This register is read-only when the PTG module is executing Step commands (PTGEN = 1 and PTGSTRT = 1). REGISTER 24-13: PTGQUEx: PTG STEP QUEUE REGISTER x (x = 0-7)(1,3) R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 STEP(2x + 1)<7:0>(2) bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 STEP(2x)<7:0>(2) bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-8 STEP(2x + 1)<7:0>: PTG Step Queue Pointer Register bits(2) A queue location for storage of the STEP(2x + 1) command byte. bit 7-0 STEP(2x)<7:0>: PTG Step Queue Pointer Register bits(2) A queue location for storage of the STEP(2x) command byte. Note 1: This register is read-only when the PTG module is executing Step commands (PTGEN = 1 and PTGSTRT = 1). 2: Refer to Table 24-1 for the Step command encoding. 3: The Step registers maintain their values on any type of Reset. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 350  2011-2013 Microchip Technology Inc. 24.4 Step Commands and Format TABLE 24-1: PTG STEP COMMAND FORMAT Step Command Byte: STEPx<7:0> CMD<3:0> OPTION<3:0> bit 7 bit 4 bit 3 bit 0 bit 7-4 CMD<3:0> Step Command Command Description 0000 PTGCTRL Execute control command as described by OPTION<3:0>. 0001 PTGADD Add contents of PTGADJ register to target register as described by OPTION<3:0>. PTGCOPY Copy contents of PTGHOLD register to target register as described by OPTION<3:0>. 001x PTGSTRB Copy the value contained in CMD<0>:OPTION<3:0> to the CH0SA<4:0> bits (AD1CHS0<4:0>). 0100 PTGWHI Wait for a low-to-high edge input from the selected PTG trigger input as described by OPTION<3:0>. 0101 PTGWLO Wait for a high-to-low edge input from the selected PTG trigger input as described by OPTION<3:0>. 0110 Reserved Reserved. 0111 PTGIRQ Generate individual interrupt request as described by OPTION3<:0>. 100x PTGTRIG Generate individual trigger output as described by <:OPTION<3:0>>. 101x PTGJMP Copy the value indicated in <:OPTION<3:0>> to the Queue Pointer (PTGQPTR) and jump to that Step queue. 110x PTGJMPC0 PTGC0 = PTGC0LIM: Increment the Queue Pointer (PTGQPTR). PTGC0  PTGC0LIM: Increment Counter 0 (PTGC0) and copy the value indicated in <:OPTION<3:0>> to the Queue Pointer (PTGQPTR), and jump to that Step queue 111x PTGJMPC1 PTGC1 = PTGC1LIM: Increment the Queue Pointer (PTGQPTR). PTGC1  PTGC1LIM: Increment Counter 1 (PTGC1) and copy the value indicated in <:OPTION<3:0>> to the Queue Pointer (PTGQPTR), and jump to that Step queue. Note 1: All reserved commands or options will execute but have no effect (i.e., execute as a NOP instruction). 2: Refer to Table 24-2 for the trigger output descriptions. 3: This feature is only available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices.  2011-2013 Microchip Technology Inc. DS70000657H-page 351 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 24-1: PTG STEP COMMAND FORMAT (CONTINUED) bit 3-0 Step Command OPTION<3:0> Option Description PTGCTRL(1) 0000 Reserved. 0001 Reserved. 0010 Disable Step Delay Timer (PTGSD). 0011 Reserved. 0100 Reserved. 0101 Reserved. 0110 Enable Step Delay Timer (PTGSD). 0111 Reserved. 1000 Start and wait for the PTG Timer0 to match the Timer0 Limit Register. 1001 Start and wait for the PTG Timer1 to match the Timer1 Limit Register. 1010 Reserved. 1011 Wait for the software trigger bit transition from low-to-high before continuing (PTGSWT = 0 to 1). 1100 Copy contents of the Counter 0 register to the AD1CHS0 register. 1101 Copy contents of the Counter 1 register to the AD1CHS0 register. 1110 Copy contents of the Literal 0 register to the AD1CHS0 register. 1111 Generate triggers indicated in the Broadcast Trigger Enable register (PTGBTE). PTGADD(1) 0000 Add contents of the PTGADJ register to the Counter 0 Limit register (PTGC0LIM). 0001 Add contents of the PTGADJ register to the Counter 1 Limit register (PTGC1LIM). 0010 Add contents of the PTGADJ register to the Timer0 Limit register (PTGT0LIM). 0011 Add contents of the PTGADJ register to the Timer1 Limit register (PTGT1LIM). 0100 Add contents of the PTGADJ register to the Step Delay Limit register (PTGSDLIM). 0101 Add contents of the PTGADJ register to the Literal 0 register (PTGL0). 0110 Reserved. 0111 Reserved. PTGCOPY(1) 1000 Copy contents of the PTGHOLD register to the Counter 0 Limit register (PTGC0LIM). 1001 Copy contents of the PTGHOLD register to the Counter 1 Limit register (PTGC1LIM). 1010 Copy contents of the PTGHOLD register to the Timer0 Limit register (PTGT0LIM). 1011 Copy contents of the PTGHOLD register to the Timer1 Limit register (PTGT1LIM). 1100 Copy contents of the PTGHOLD register to the Step Delay Limit register (PTGSDLIM). 1101 Copy contents of the PTGHOLD register to the Literal 0 register (PTGL0). 1110 Reserved. 1111 Reserved. Note 1: All reserved commands or options will execute but have no effect (i.e., execute as a NOP instruction). 2: Refer to Table 24-2 for the trigger output descriptions. 3: This feature is only available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 352  2011-2013 Microchip Technology Inc. TABLE 24-1: PTG STEP COMMAND FORMAT (CONTINUED) bit 3-0 Step Command OPTION<3:0> Option Description PTGWHI(1) or PTGWLO(1) 0000 PWM Special Event Trigger.(3) 0001 PWM master time base synchronization output.(3) 0010 PWM1 interrupt.(3) 0011 PWM2 interrupt.(3) 0100 PWM3 interrupt.(3) 0101 Reserved. 0110 Reserved. 0111 OC1 Trigger event. 1000 OC2 Trigger event. 1001 IC1 Trigger event. 1010 CMP1 Trigger event. 1011 CMP2 Trigger event. 1100 CMP3 Trigger event. 1101 CMP4 Trigger event. 1110 ADC conversion done interrupt. 1111 INT2 external interrupt. PTGIRQ(1) 0000 Generate PTG Interrupt 0. 0001 Generate PTG Interrupt 1. 0010 Generate PTG Interrupt 2. 0011 Generate PTG Interrupt 3. 0100 Reserved. • • • • • • 1111 Reserved. PTGTRIG(2) 00000 PTGO0. 00001 PTGO1. • • • • • • 11110 PTGO30. 11111 PTGO31. Note 1: All reserved commands or options will execute but have no effect (i.e., execute as a NOP instruction). 2: Refer to Table 24-2 for the trigger output descriptions. 3: This feature is only available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices.  2011-2013 Microchip Technology Inc. DS70000657H-page 353 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 24-2: PTG OUTPUT DESCRIPTIONS PTG Output Number PTG Output Description PTGO0 Trigger/Synchronization Source for OC1 PTGO1 Trigger/Synchronization Source for OC2 PTGO2 Trigger/Synchronization Source for OC3 PTGO3 Trigger/Synchronization Source for OC4 PTGO4 Clock Source for OC1 PTGO5 Clock Source for OC2 PTGO6 Clock Source for OC3 PTGO7 Clock Source for OC4 PTGO8 Trigger/Synchronization Source for IC1 PTGO9 Trigger/Synchronization Source for IC2 PTGO10 Trigger/Synchronization Source for IC3 PTGO11 Trigger/Synchronization Source for IC4 PTGO12 Sample Trigger for ADC PTGO13 Sample Trigger for ADC PTGO14 Sample Trigger for ADC PTGO15 Sample Trigger for ADC PTGO16 PWM Time Base Synchronous Source for PWM(1) PTGO17 PWM Time Base Synchronous Source for PWM(1) PTGO18 Mask Input Select for Op Amp/Comparator PTGO19 Mask Input Select for Op Amp/Comparator PTGO20 Reserved PTGO21 Reserved PTGO22 Reserved PTGO23 Reserved PTGO24 Reserved PTGO25 Reserved PTGO26 Reserved PTGO27 Reserved PTGO28 Reserved PTGO29 Reserved PTGO30 PTG Output to PPS Input Selection PTGO31 PTG Output to PPS Input Selection Note 1: This feature is only available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 354  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 355 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 25.0 OP AMP/COMPARATOR MODULE The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X devices contain up to four comparators, which can be configured in various ways. Comparators, CMP1, CMP2 and CMP3, also have the option to be configured as op amps, with the output being brought to an external pin for gain/filtering connections. As shown in Figure 25-1, individual comparator options are specified by the comparator module’s Special Function Register (SFR) control bits. These options allow users to: • Select the edge for trigger and interrupt generation • Configure the comparator voltage reference • Configure output blanking and masking • Configure as a comparator or op amp (CMP1, CMP2 and CMP3 only) FIGURE 25-1: OP AMP/COMPARATOR x MODULE BLOCK DIAGRAM (MODULES 1, 2 AND 3) Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Op Amp/Comparator” (DS70357) in the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. Note: Op Amp/Comparator 3 is not available on the dsPIC33EPXXXGP502/MC502/MC202 and PIC24EP256GP/MC202 (28-pin) devices. Note: Not all op amp/comparator input/output connections are available on all devices. See the “Pin Diagrams” section for available connections. Blanking Function Digital Filter CxOUT(1) (see Figure 25-4) (see Figure 25-5) PTG Trigger Input 0 1 00 01 CxIN1+ CVREFIN(1) CxIN1- CXIN2-(1) Note 1: This input/output is not available as a selection when configured as an op amp (OPMODE (CMxCON<10>) = 1). 2: This module can be configured either as an op amp or a comparator using the OPMODE bit. 3: When configured as an op amp (OPMODE = 1), the ADC samples the op amp output; otherwise, the ADC samples the ANx pin. CMPx – + VINVIN+ CCH<1:0> (CMxCON<1:0>) CREF (CMxCON<4>) Op Amp/Comparator(2) Op Ampx – + OAx/ANx(3) OAxOUT/ANx OPMODE (CMxCON<10>) (to ADC) RINT1 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 356  2011-2013 Microchip Technology Inc. FIGURE 25-2: COMPARATOR MODULE BLOCK DIAGRAM (MODULE 4) FIGURE 25-3: OP AMP/COMPARATOR VOLTAGE REFERENCE BLOCK DIAGRAM CMP4 Blanking Function Digital Filter (see Figure 25-4) (see Figure 25-5) – + VIN+ C4OUT Trigger C4IN1+ Output CVREFIN VIN1 0 11 00 CCH<1:0> (CM4CON<1:0>) OA3/AN6 C4IN1- CREF (CMxCON<4>) 01 10 OA1/AN3 OA2/AN0 8R R CVREN CVRSS = 0 AVDD VREF+ CVRSS = 1(1) 8R R R R R R R 16 Steps CVRR CVREF1O CVR3 CVR2 CVR1 CVR0 CVRCON<3:0> AVSS CVRSRC CVR1OE CVREFIN VREFSEL CVREF2O(2) CVR2OE Note 1: In order to operate with CVRSS = 1, at least one of the comparator modules must be enabled. 2: This reference is (AVDD + AVSS)/2. AVSS AVDD 1 0 16-to-1 MUX (CVRCON<6>) (CVRCON<14>) (CVRCON<10>)  2011-2013 Microchip Technology Inc. DS70000657H-page 357 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 25-4: USER-PROGRAMMABLE BLANKING FUNCTION BLOCK DIAGRAM FIGURE 25-5: DIGITAL FILTER INTERCONNECT BLOCK DIAGRAM SELSRCA<3:0> SELSRCB<3:0> SELSRCC<3:0> AND CMxMSKCON MUX A MAI MBI MCI Comparator Output To Digital Signals Filter OR Blanking Blanking Blanking Signals Signals ANDI MASK “AND-OR” Function HLMS MUX B MUX C Blanking Logic (CMxMSKCON<15) (CMxMSKSRC<11:8) (CMxMSKSRC<7:4) (CMxMSKSRC<3:0>) MBI MCI MAI MBI MCI MAI CXOUT CFLTREN Digital Filter TxCLK(1,2) SYNCO1(3) FP(4) FOSC(4) CFSEL<2:0>  CFDIV Note 1: See the Type C Timer Block Diagram (Figure 13-2). 2: See the Type B Timer Block Diagram (Figure 13-1). 3: See the High-Speed PWMx Module Register Interconnection Diagram (Figure 16-2). 4: See the Oscillator System Diagram (Figure 9-1). From Blanking Logic 1xx 010 000 001 1 0 (CMxFLTR<6:4>) (CMxFLTR<3>) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 358  2011-2013 Microchip Technology Inc. 25.1 Op Amp Application Considerations There are two configurations to take into consideration when designing with the op amp modules that are available in the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/ MC20X devices. Configuration A (see Figure 25-6) takes advantage of the internal connection to the ADC module to route the output of the op amp directly to the ADC for measurement. Configuration B (see Figure 25-7) requires that the designer externally route the output of the op amp (OAxOUT) to a separate analog input pin (ANy) on the device. Table 30-55 in Section 30.0 “Electrical Characteristics” describes the performance characteristics for the op amps, distinguishing between the two configuration types where applicable. 25.1.1 OP AMP CONFIGURATION A Figure 25-6 shows a typical inverting amplifier circuit taking advantage of the internal connections from the op amp output to the input of the ADC. The advantage of this configuration is that the user does not need to consume another analog input (ANy) on the device, and allows the user to simultaneously sample all three op amps with the ADC module, if needed. However, the presence of the internal resistance, RINT1, adds an error in the feedback path. Since RINT1 is an internal resistance, in relation to the op amp output (VOAxOUT) and ADC internal connection (VADC), RINT1 must be included in the numerator term of the transfer function. See Table 30-53 in Section 30.0 “Electrical Characteristics” for the typical value of RINT1. Table 30-60 and Table 30-61 in Section 30.0 “Electrical Characteristics” describe the minimum sample time (TSAMP) requirements for the ADC module in this configuration. Figure 25-6 also defines the equations that should be used when calculating the expected voltages at points, VADC and VOAXOUT. FIGURE 25-6: OP AMP CONFIGURATION A – + CxIN1- CxIN1+ R1 ADC(3) OAxOUT RINT1(1) RFEEDBACK(2) OAx (to ADC) Op Ampx Note 1: See Table 30-53 for the Typical value. 2: See Table 30-53 for the Minimum value for the feedback resistor. 3: See Table 30-60 and Table 30-61 for the minimum sample time (TSAMP). 4: CVREF1O or CVREF2O are two options that are available for supplying bias voltage to the op amps. VIN VADC (VOAXOUT) VOAxOUT RFEEDBACK R1 -----------------------------     Bias Voltage V– IN =   VADC RFEEDBACK RINT1 + R1 --------------------------------------------------     Bias Voltage V– IN =   Bias Voltage(4)  2011-2013 Microchip Technology Inc. DS70000657H-page 359 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 25.1.2 OP AMP CONFIGURATION B Figure 25-7 shows a typical inverting amplifier circuit with the output of the op amp (OAxOUT) externally routed to a separate analog input pin (ANy) on the device. This op amp configuration is slightly different in terms of the op amp output and the ADC input connection, therefore, RINT1 is not included in the transfer function. However, this configuration requires the designer to externally route the op amp output (OAxOUT) to another analog input pin (ANy). See Table 30-53 in Section 30.0 “Electrical Characteristics” for the typical value of RINT1. Table 30-60 and Table 30-61 in Section 30.0 “Electrical Characteristics” describe the minimum sample time (TSAMP) requirements for the ADC module in this configuration. Figure 25-7 also defines the equation to be used to calculate the expected voltage at point VOAXOUT. This is the typical inverting amplifier equation. 25.2 Op Amp/Comparator Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 25.2.1 KEY RESOURCES • “Op Amp/Comparator” (DS70357) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools FIGURE 25-7: OP AMP CONFIGURATION B Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464 ADC(3) OAxOUT RFEEDBACK(2) ANy Note 1: See Table 30-53 for the Typical value. 2: See Table 30-53 for the Minimum value for the feedback resistor. 3: See Table 30-60 and Table 30-61 for the minimum sample time (TSAMP). 4: CVREF1O or CVREF2O are two options that are available for supplying bias voltage to the op amps. – + Op Ampx (VOAXOUT) RINT1(1) VOAxOUT RFEEDBACK R1 -----------------------------     Bias Voltage V– IN =   CxIN1- CxIN1+ R1 VIN Bias Voltage(4) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 360  2011-2013 Microchip Technology Inc. 25.3 Op Amp/Comparator Registers REGISTER 25-1: CMSTAT: OP AMP/COMPARATOR STATUS REGISTER R/W-0 U-0 U-0 U-0 R-0 R-0 R-0 R-0 PSIDL — — — C4EVT(1) C3EVT(1) C2EVT(1) C1EVT(1) bit 15 bit 8 U-0 U-0 U-0 U-0 R-0 R-0 R-0 R-0 — — — — C4OUT(2) C3OUT(2) C2OUT(2) C1OUT(2) bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 PSIDL: Comparator Stop in Idle Mode bit 1 = Discontinues operation of all comparators when device enters Idle mode 0 = Continues operation of all comparators in Idle mode bit 14-12 Unimplemented: Read as ‘0’ bit 11 C4EVT: Op Amp/Comparator 4 Event Status bit(1) 1 = Op amp/comparator event occurred 0 = Op amp/comparator event did not occur bit 10 C3EVT: Comparator 3 Event Status bit(1) 1 = Comparator event occurred 0 = Comparator event did not occur bit 9 C2EVT: Comparator 2 Event Status bit(1) 1 = Comparator event occurred 0 = Comparator event did not occur bit 8 C1EVT: Comparator 1 Event Status bit(1) 1 = Comparator event occurred 0 = Comparator event did not occur bit 7-4 Unimplemented: Read as ‘0’ bit 3 C4OUT: Comparator 4 Output Status bit(2) When CPOL = 0: 1 = VIN+ > VIN0 = VIN+ < VINWhen CPOL = 1: 1 = VIN+ < VIN0 = VIN+ > VINbit 2 C3OUT: Comparator 3 Output Status bit(2) When CPOL = 0: 1 = VIN+ > VIN0 = VIN+ < VINWhen CPOL = 1: 1 = VIN+ < VIN0 = VIN+ > VINNote 1: Reflects the value of the of the CEVT bit in the respective Op Amp/Comparator Control register, CMxCON<9>. 2: Reflects the value of the COUT bit in the respective Op Amp/Comparator Control register, CMxCON<8>.  2011-2013 Microchip Technology Inc. DS70000657H-page 361 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 1 C2OUT: Comparator 2 Output Status bit(2) When CPOL = 0: 1 = VIN+ > VIN0 = VIN+ < VINWhen CPOL = 1: 1 = VIN+ < VIN0 = VIN+ > VINbit 0 C1OUT: Comparator 1 Output Status bit(2) When CPOL = 0: 1 = VIN+ > VIN0 = VIN+ < VINWhen CPOL = 1: 1 = VIN+ < VIN0 = VIN+ > VINREGISTER 25-1: CMSTAT: OP AMP/COMPARATOR STATUS REGISTER (CONTINUED) Note 1: Reflects the value of the of the CEVT bit in the respective Op Amp/Comparator Control register, CMxCON<9>. 2: Reflects the value of the COUT bit in the respective Op Amp/Comparator Control register, CMxCON<8>. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 362  2011-2013 Microchip Technology Inc. REGISTER 25-2: CMxCON: COMPARATOR x CONTROL REGISTER (x = 1, 2 OR 3) R/W-0 R/W-0 R/W-0 U-0 U-0 R/W-0 R/W-0 R/W-0 CON COE(2) CPOL — — OPMODE CEVT COUT bit 15 bit 8 R/W-0 R/W-0 U-0 R/W-0 U-0 U-0 R/W-0 R/W-0 EVPOL1 EVPOL0 — CREF(1) — — CCH1(1) CCH0(1) bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 CON: Op Amp/Comparator Enable bit 1 = Op amp/comparator is enabled 0 = Op amp/comparator is disabled bit 14 COE: Comparator Output Enable bit(2) 1 = Comparator output is present on the CxOUT pin 0 = Comparator output is internal only bit 13 CPOL: Comparator Output Polarity Select bit 1 = Comparator output is inverted 0 = Comparator output is not inverted bit 12-11 Unimplemented: Read as ‘0’ bit 10 OPMODE: Op Amp/Comparator Operation Mode Select bit 1 = Circuit operates as an op amp 0 = Circuit operates as a comparator bit 9 CEVT: Comparator Event bit 1 = Comparator event according to the EVPOL<1:0> settings occurred; disables future triggers and interrupts until the bit is cleared 0 = Comparator event did not occur bit 8 COUT: Comparator Output bit When CPOL = 0 (non-inverted polarity): 1 = VIN+ > VIN0 = VIN+ < VINWhen CPOL = 1 (inverted polarity): 1 = VIN+ < VIN0 = VIN+ > VINNote 1: Inputs that are selected and not available will be tied to VSS. See the “Pin Diagrams” section for available inputs for each package. 2: This output is not available when OPMODE (CMxCON<10>) = 1.  2011-2013 Microchip Technology Inc. DS70000657H-page 363 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 7-6 EVPOL<1:0>: Trigger/Event/Interrupt Polarity Select bits 11 = Trigger/event/interrupt generated on any change of the comparator output (while CEVT = 0) 10 = Trigger/event/interrupt generated only on high-to-low transition of the polarity selected comparator output (while CEVT = 0) If CPOL = 1 (inverted polarity): Low-to-high transition of the comparator output. If CPOL = 0 (non-inverted polarity): High-to-low transition of the comparator output. 01 = Trigger/event/interrupt generated only on low-to-high transition of the polarity-selected comparator output (while CEVT = 0) If CPOL = 1 (inverted polarity): High-to-low transition of the comparator output. If CPOL = 0 (non-inverted polarity): Low-to-high transition of the comparator output 00 = Trigger/event/interrupt generation is disabled bit 5 Unimplemented: Read as ‘0’ bit 4 CREF: Comparator Reference Select bit (VIN+ input)(1) 1 = VIN+ input connects to internal CVREFIN voltage(2) 0 = VIN+ input connects to CxIN1+ pin bit 3-2 Unimplemented: Read as ‘0’ bit 1-0 CCH<1:0>: Op Amp/Comparator Channel Select bits(1) 11 = Unimplemented 10 = Unimplemented 01 = Inverting input of the comparator connects to the CxIN2- pin(2) 00 = Inverting input of the op amp/comparator connects to the CxIN1- pin REGISTER 25-2: CMxCON: COMPARATOR x CONTROL REGISTER (x = 1, 2 OR 3) (CONTINUED) Note 1: Inputs that are selected and not available will be tied to VSS. See the “Pin Diagrams” section for available inputs for each package. 2: This output is not available when OPMODE (CMxCON<10>) = 1. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 364  2011-2013 Microchip Technology Inc. REGISTER 25-3: CM4CON: COMPARATOR 4 CONTROL REGISTER R/W-0 R/W-0 R/W-0 U-0 U-0 U-0 R/W-0 R/W-0 CON COE CPOL — — — CEVT COUT bit 15 bit 8 R/W-0 R/W-0 U-0 R/W-0 U-0 U-0 R/W-0 R/W-0 EVPOL1 EVPOL0 — CREF(1) — — CCH1(1) CCH0(1) bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 CON: Comparator Enable bit 1 = Comparator is enabled 0 = Comparator is disabled bit 14 COE: Comparator Output Enable bit 1 = Comparator output is present on the CxOUT pin 0 = Comparator output is internal only bit 13 CPOL: Comparator Output Polarity Select bit 1 = Comparator output is inverted 0 = Comparator output is not inverted bit 12-10 Unimplemented: Read as ‘0’ bit 9 CEVT: Comparator Event bit 1 = Comparator event according to EVPOL<1:0> settings occurred; disables future triggers and interrupts until the bit is cleared 0 = Comparator event did not occur bit 8 COUT: Comparator Output bit When CPOL = 0 (non-inverted polarity): 1 = VIN+ > VIN0 = VIN+ < VINWhen CPOL = 1 (inverted polarity): 1 = VIN+ < VIN0 = VIN+ > VINbit 7-6 EVPOL<1:0>: Trigger/Event/Interrupt Polarity Select bits 11 = Trigger/event/interrupt generated on any change of the comparator output (while CEVT = 0) 10 = Trigger/event/interrupt generated only on high-to-low transition of the polarity selected comparator output (while CEVT = 0) If CPOL = 1 (inverted polarity): Low-to-high transition of the comparator output. If CPOL = 0 (non-inverted polarity): High-to-low transition of the comparator output. 01 = Trigger/event/interrupt generated only on low-to-high transition of the polarity selected comparator output (while CEVT = 0) If CPOL = 1 (inverted polarity): High-to-low transition of the comparator output. If CPOL = 0 (non-inverted polarity): Low-to-high transition of the comparator output. 00 = Trigger/event/interrupt generation is disabled Note 1: Inputs that are selected and not available will be tied to VSS. See the “Pin Diagrams” section for available inputs for each package.  2011-2013 Microchip Technology Inc. DS70000657H-page 365 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 5 Unimplemented: Read as ‘0’ bit 4 CREF: Comparator Reference Select bit (VIN+ input)(1) 1 = VIN+ input connects to internal CVREFIN voltage 0 = VIN+ input connects to C4IN1+ pin bit 3-2 Unimplemented: Read as ‘0’ bit 1-0 CCH<1:0>: Comparator Channel Select bits(1) 11 = VIN- input of comparator connects to OA3/AN6 10 = VIN- input of comparator connects to OA2/AN0 01 = VIN- input of comparator connects to OA1/AN3 00 = VIN- input of comparator connects to C4IN1- REGISTER 25-3: CM4CON: COMPARATOR 4 CONTROL REGISTER (CONTINUED) Note 1: Inputs that are selected and not available will be tied to VSS. See the “Pin Diagrams” section for available inputs for each package. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 366  2011-2013 Microchip Technology Inc. REGISTER 25-4: CMxMSKSRC: COMPARATOR x MASK SOURCE SELECT CONTROL REGISTER U-0 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 RW-0 — — — — SELSRCC3 SELSRCC2 SELSRCC1 SELSRCC0 bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 SELSRCB3 SELSRCB2 SELSRCB1 SELSRCB0 SELSRCA3 SELSRCA2 SELSRCA1 SELSRCA0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-12 Unimplemented: Read as ‘0’ bit 11-8 SELSRCC<3:0>: Mask C Input Select bits 1111 = FLT4 1110 = FLT2 1101 = PTGO19 1100 = PTGO18 1011 = Reserved 1010 = Reserved 1001 = Reserved 1000 = Reserved 0111 = Reserved 0110 = Reserved 0101 = PWM3H 0100 = PWM3L 0011 = PWM2H 0010 = PWM2L 0001 = PWM1H 0000 = PWM1L bit 7-4 SELSRCB<3:0>: Mask B Input Select bits 1111 = FLT4 1110 = FLT2 1101 = PTGO19 1100 = PTGO18 1011 = Reserved 1010 = Reserved 1001 = Reserved 1000 = Reserved 0111 = Reserved 0110 = Reserved 0101 = PWM3H 0100 = PWM3L 0011 = PWM2H 0010 = PWM2L 0001 = PWM1H 0000 = PWM1L  2011-2013 Microchip Technology Inc. DS70000657H-page 367 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 3-0 SELSRCA<3:0>: Mask A Input Select bits 1111 = FLT4 1110 = FLT2 1101 = PTGO19 1100 = PTGO18 1011 = Reserved 1010 = Reserved 1001 = Reserved 1000 = Reserved 0111 = Reserved 0110 = Reserved 0101 = PWM3H 0100 = PWM3L 0011 = PWM2H 0010 = PWM2L 0001 = PWM1H 0000 = PWM1L REGISTER 25-4: CMxMSKSRC: COMPARATOR x MASK SOURCE SELECT CONTROL REGISTER (CONTINUED) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 368  2011-2013 Microchip Technology Inc. REGISTER 25-5: CMxMSKCON: COMPARATOR x MASK GATING 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 HLMS — OCEN OCNEN OBEN OBNEN OAEN OANEN bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 NAGS PAGS ACEN ACNEN ABEN ABNEN AAEN AANEN bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 HLMS: High or Low-Level Masking Select bits 1 = The masking (blanking) function will prevent any asserted (‘0’) comparator signal from propagating 0 = The masking (blanking) function will prevent any asserted (‘1’) comparator signal from propagating bit 14 Unimplemented: Read as ‘0’ bit 13 OCEN: OR Gate C Input Enable bit 1 = MCI is connected to OR gate 0 = MCI is not connected to OR gate bit 12 OCNEN: OR Gate C Input Inverted Enable bit 1 = Inverted MCI is connected to OR gate 0 = Inverted MCI is not connected to OR gate bit 11 OBEN: OR Gate B Input Enable bit 1 = MBI is connected to OR gate 0 = MBI is not connected to OR gate bit 10 OBNEN: OR Gate B Input Inverted Enable bit 1 = Inverted MBI is connected to OR gate 0 = Inverted MBI is not connected to OR gate bit 9 OAEN: OR Gate A Input Enable bit 1 = MAI is connected to OR gate 0 = MAI is not connected to OR gate bit 8 OANEN: OR Gate A Input Inverted Enable bit 1 = Inverted MAI is connected to OR gate 0 = Inverted MAI is not connected to OR gate bit 7 NAGS: AND Gate Output Inverted Enable bit 1 = Inverted ANDI is connected to OR gate 0 = Inverted ANDI is not connected to OR gate bit 6 PAGS: AND Gate Output Enable bit 1 = ANDI is connected to OR gate 0 = ANDI is not connected to OR gate bit 5 ACEN: AND Gate C Input Enable bit 1 = MCI is connected to AND gate 0 = MCI is not connected to AND gate bit 4 ACNEN: AND Gate C Input Inverted Enable bit 1 = Inverted MCI is connected to AND gate 0 = Inverted MCI is not connected to AND gate  2011-2013 Microchip Technology Inc. DS70000657H-page 369 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X bit 3 ABEN: AND Gate B Input Enable bit 1 = MBI is connected to AND gate 0 = MBI is not connected to AND gate bit 2 ABNEN: AND Gate B Input Inverted Enable bit 1 = Inverted MBI is connected to AND gate 0 = Inverted MBI is not connected to AND gate bit 1 AAEN: AND Gate A Input Enable bit 1 = MAI is connected to AND gate 0 = MAI is not connected to AND gate bit 0 AANEN: AND Gate A Input Inverted Enable bit 1 = Inverted MAI is connected to AND gate 0 = Inverted MAI is not connected to AND gate REGISTER 25-5: CMxMSKCON: COMPARATOR x MASK GATING CONTROL REGISTER (CONTINUED) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 370  2011-2013 Microchip Technology Inc. REGISTER 25-6: CMxFLTR: COMPARATOR x FILTER CONTROL REGISTER U-0 U-0 U-0 U-0 U-0 U-0 U-0 U-0 — — — — — — — — bit 15 bit 8 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — CFSEL2 CFSEL1 CFSEL0 CFLTREN CFDIV2 CFDIV1 CFDIV0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-7 Unimplemented: Read as ‘0’ bit 6-4 CFSEL<2:0>: Comparator Filter Input Clock Select bits 111 = T5CLK(1) 110 = T4CLK(2) 101 = T3CLK(1) 100 = T2CLK(2) 011 = Reserved 010 = SYNCO1(3) 001 = FOSC(4) 000 = FP(4) bit 3 CFLTREN: Comparator Filter Enable bit 1 = Digital filter is enabled 0 = Digital filter is disabled bit 2-0 CFDIV<2:0>: Comparator Filter Clock Divide Select bits 111 = Clock Divide 1:128 110 = Clock Divide 1:64 101 = Clock Divide 1:32 100 = Clock Divide 1:16 011 = Clock Divide 1:8 010 = Clock Divide 1:4 001 = Clock Divide 1:2 000 = Clock Divide 1:1 Note 1: See the Type C Timer Block Diagram (Figure 13-2). 2: See the Type B Timer Block Diagram (Figure 13-1). 3: See the High-Speed PWMx Module Register Interconnection Diagram (Figure 16-2). 4: See the Oscillator System Diagram (Figure 9-1).  2011-2013 Microchip Technology Inc. DS70000657H-page 371 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 25-7: CVRCON: COMPARATOR VOLTAGE REFERENCE CONTROL REGISTER U-0 R/W-0 U-0 U-0 U-0 R/W-0 U-0 U-0 — CVR2OE(1) — — — VREFSEL — — bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 CVREN CVR1OE(1) CVRR CVRSS(2) CVR3 CVR2 CVR1 CVR0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 Unimplemented: Read as ‘0’ bit 14 CVR2OE: Comparator Voltage Reference 2 Output Enable bit(1) 1 = (AVDD – AVSS)/2 is connected to the CVREF2O pin 0 = (AVDD – AVSS)/2 is disconnected from the CVREF2O pin bit 13-11 Unimplemented: Read as ‘0’ bit 10 VREFSEL: Comparator Voltage Reference Select bit 1 = CVREFIN = VREF+ 0 = CVREFIN is generated by the resistor network bit 9-8 Unimplemented: Read as ‘0’ bit 7 CVREN: Comparator Voltage Reference Enable bit 1 = Comparator voltage reference circuit is powered on 0 = Comparator voltage reference circuit is powered down bit 6 CVR1OE: Comparator Voltage Reference 1 Output Enable bit(1) 1 = Voltage level is output on the CVREF1O pin 0 = Voltage level is disconnected from then CVREF1O pin bit 5 CVRR: Comparator Voltage Reference Range Selection bit 1 = CVRSRC/24 step-size 0 = CVRSRC/32 step-size bit 4 CVRSS: Comparator Voltage Reference Source Selection bit(2) 1 = Comparator voltage reference source, CVRSRC = (VREF+) – (AVSS) 0 = Comparator voltage reference source, CVRSRC = AVDD – AVSS bit 3-0 CVR<3:0> Comparator Voltage Reference Value Selection 0  CVR<3:0>  15 bits When CVRR = 1: CVREFIN = (CVR<3:0>/24)  (CVRSRC) When CVRR = 0: CVREFIN = (CVRSRC/4) + (CVR<3:0>/32)  (CVRSRC) Note 1: CVRxOE overrides the TRISx and the ANSELx bit settings. 2: In order to operate with CVRSS = 1, at least one of the comparator modules must be enabled. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 372  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 373 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 26.0 PROGRAMMABLE CYCLIC REDUNDANCY CHECK (CRC) GENERATOR The programmable CRC generator offers the following features: • User-programmable (up to 32nd order) polynomial CRC equation • Interrupt output • Data FIFO The programmable CRC generator provides a hardware implemented method of quickly generating checksums for various networking and security applications. It offers the following features: • User-programmable CRC polynomial equation, up to 32 bits • Programmable shift direction (little or big-endian) • Independent data and polynomial lengths • Configurable interrupt output • Data FIFO A simplified block diagram of the CRC generator is shown in Figure 26-1. A simple version of the CRC shift engine is shown in Figure 26-2. FIGURE 26-1: CRC BLOCK DIAGRAM Note 1: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to “Programmable Cyclic Redundancy Check (CRC)” (DS70346) of the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). 2: Some registers and associated bits described in this section may not be available on all devices. Refer to Section 4.0 “Memory Organization” in this data sheet for device-specific register and bit information. Variable FIFO (4x32, 8x16 or 16x8) CRCDATH CRCDATL Shift Buffer CRC Shift Engine CRCWDATH CRCWDATL 0 1 LENDIAN CRCISEL 1 0 FIFO Empty Event Shift Complete Event Set CRCIF 2 * FP Shift Clock dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 374  2011-2013 Microchip Technology Inc. FIGURE 26-2: CRC SHIFT ENGINE DETAIL 26.1 Overview The CRC module can be programmed for CRC polynomials of up to the 32nd order, using up to 32 bits. Polynomial length, which reflects the highest exponent in the equation, is selected by the PLEN<4:0> bits (CRCCON2<4:0>). The CRCXORL and CRCXORH registers control which exponent terms are included in the equation. Setting a particular bit includes that exponent term in the equation; functionally, this includes an XOR operation on the corresponding bit in the CRC engine. Clearing the bit disables the XOR. For example, consider two CRC polynomials, one a 16-bit equation and the other a 32-bit equation: To program these polynomials into the CRC generator, set the register bits as shown in Table 26-1. Note that the appropriate positions are set to ‘1’ to indicate that they are used in the equation (for example, X26 and X23). The 0 bit required by the equation is always XORed; thus, X0 is a don’t care. For a polynomial of length N, it is assumed that the Nth bit will always be used, regardless of the bit setting. Therefore, for a polynomial length of 32, there is no 32nd bit in the CRCxOR register. TABLE 26-1: CRC SETUP EXAMPLES FOR 16 AND 32-BIT POLYNOMIAL 26.2 Programmable CRC Resources Many useful resources are provided on the main product page of the Microchip web site for the devices listed in this data sheet. This product page, which can be accessed using this link, contains the latest updates and additional information. 26.2.1 KEY RESOURCES • “Programmable Cyclic Redundancy Check (CRC)” (DS70346) in the “dsPIC33/PIC24 Family Reference Manual” • Code Samples • Application Notes • Software Libraries • Webinars • All Related “dsPIC33/PIC24 Family Reference Manual” Sections • Development Tools CRCWDATH CRCWDATL Bit 0 Bit 1 Bit n(2) X(1)(1) Read/Write Bus Shift Buffer Data Bit 2 X(2)(1) X(n)(1) Note 1: Each XOR stage of the shift engine is programmable. See text for details. 2: Polynomial length n is determined by ([PLEN<4:0>] + 1). x16 + x12 + x5 + 1 and x32 + x26 + x23 + x22 + x16 + x12 + x11 + x10 + x8 + x7 + x5 + x4 + x2 + x + 1 CRC Control Bits Bit Values 16-bit Polynomial 32-bit Polynomial PLEN<4:0> 01111 11111 X<31:16> 0000 0000 0000 000x 0000 0100 1100 0001 X<15:0> 0001 0000 0010 000x 0001 1101 1011 011x Note: In the event you are not able to access the product page using the link above, enter this URL in your browser: http://www.microchip.com/wwwproducts/ Devices.aspx?dDocName=en555464  2011-2013 Microchip Technology Inc. DS70000657H-page 375 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 26.3 Programmable CRC Registers REGISTER 26-1: CRCCON1: CRC CONTROL REGISTER 1 R/W-0 U-0 R/W-0 R-0 R-0 R-0 R-0 R-0 CRCEN — CSIDL VWORD4 VWORD3 VWORD2 VWORD1 VWORD0 bit 15 bit 8 R-0 R-1 R/W-0 R/W-0 R/W-0 U-0 U-0 U-0 CRCFUL CRCMPT CRCISEL CRCGO LENDIAN — — — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15 CRCEN: CRC Enable bit 1 = CRC module is enabled 0 = CRC module is disabled; all state machines, pointers and CRCWDAT/CRCDAT are reset, other SFRs are not reset bit 14 Unimplemented: Read as ‘0’ bit 13 CSIDL: CRC Stop in Idle Mode bit 1 = Discontinues module operation when device enters Idle mode 0 = Continues module operation in Idle mode bit 12-8 VWORD<4:0>: Pointer Value bits Indicates the number of valid words in the FIFO. Has a maximum value of 8 when PLEN<4:0> > 7 or 16 when PLEN<4:0> 7. bit 7 CRCFUL: CRC FIFO Full bit 1 = FIFO is full 0 = FIFO is not full bit 6 CRCMPT: CRC FIFO Empty Bit 1 = FIFO is empty 0 = FIFO is not empty bit 5 CRCISEL: CRC Interrupt Selection bit 1 = Interrupt on FIFO is empty; final word of data is still shifting through CRC 0 = Interrupt on shift is complete and CRCWDAT results are ready bit 4 CRCGO: Start CRC bit 1 = Starts CRC serial shifter 0 = CRC serial shifter is turned off bit 3 LENDIAN: Data Word Little-Endian Configuration bit 1 = Data word is shifted into the CRC starting with the LSb (little endian) 0 = Data word is shifted into the CRC starting with the MSb (big endian) bit 2-0 Unimplemented: Read as ‘0’ dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 376  2011-2013 Microchip Technology Inc. REGISTER 26-2: CRCCON2: CRC CONTROL REGISTER 2 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — — DWIDTH4 DWIDTH3 DWIDTH2 DWIDTH1 DWIDTH0 bit 15 bit 8 U-0 U-0 U-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 — — — PLEN4 PLEN3 PLEN2 PLEN1 PLEN0 bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-13 Unimplemented: Read as ‘0’ bit 12-8 DWIDTH<4:0>: Data Width Select bits These bits set the width of the data word (DWIDTH<4:0> + 1). bit 7-5 Unimplemented: Read as ‘0’ bit 4-0 PLEN<4:0>: Polynomial Length Select bits These bits set the length of the polynomial (Polynomial Length = PLEN<4:0> + 1).  2011-2013 Microchip Technology Inc. DS70000657H-page 377 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 26-3: CRCXORH: CRC XOR POLYNOMIAL HIGH 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 X<31:24> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 X<23:16> bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-0 X<31:16>: XOR of Polynomial Term Xn Enable bits REGISTER 26-4: CRCXORL: CRC XOR POLYNOMIAL LOW 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 X<15:8> bit 15 bit 8 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 R/W-0 U-0 X<7:1> — bit 7 bit 0 Legend: R = Readable bit W = Writable bit U = Unimplemented bit, read as ‘0’ -n = Value at POR ‘1’ = Bit is set ‘0’ = Bit is cleared x = Bit is unknown bit 15-1 X<15:1>: XOR of Polynomial Term Xn Enable bits bit 0 Unimplemented: Read as ‘0’ dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 378  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 379 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 27.0 SPECIAL FEATURES dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X devices include several features intended to maximize application flexibility and reliability, and minimize cost through elimination of external components. These are: • Flexible Configuration • Watchdog Timer (WDT) • Code Protection and CodeGuard™ Security • JTAG Boundary Scan Interface • In-Circuit Serial Programming™ (ICSP™) • In-Circuit Emulation 27.1 Configuration Bits In dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X devices, the Configuration bytes are implemented as volatile memory. This means that configuration data must be programmed each time the device is powered up. Configuration data is stored in at the top of the on-chip program memory space, known as the Flash Configuration bytes. Their specific locations are shown in Table 27-1. The configuration data is automatically loaded from the Flash Configuration bytes to the proper Configuration Shadow registers during device Resets. When creating applications for these devices, users should always specifically allocate the location of the Flash Configuration bytes for configuration data in their code for the compiler. This is to make certain that program code is not stored in this address when the code is compiled. The upper 2 bytes of all Flash Configuration Words in program memory should always be ‘1111 1111 1111 1111’. This makes them appear to be NOP instructions in the remote event that their locations are ever executed by accident. Since Configuration bits are not implemented in the corresponding locations, writing ‘1’s to these locations has no effect on device operation. The Configuration Flash bytes map is shown in Table 27-1. Note: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to the related section of the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). Note: Configuration data is reloaded on all types of device Resets. Note: Performing a page erase operation on the last page of program memory clears the Flash Configuration bytes, enabling code protection as a result. Therefore, users should avoid performing page erase operations on the last page of program memory. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 380  2011-2013 Microchip Technology Inc. TABLE 27-1: CONFIGURATION BYTE REGISTER MAP File Name Address Device Memory Size (Kbytes) Bits 23-8 Bit 7 Bit 6 Bit 5 Bit 4 Bit 3 Bit 2 Bit 1 Bit 0 Reserved 0057EC 32 — — — — — — — — — 00AFEC 64 0157EC 128 02AFEC 256 0557EC 512 Reserved 0057EE 32 — — — — — — — — — 00AFEE 64 0157EE 128 02AFEE 256 0557EE 512 FICD 0057F0 32 — Reserved(3) — JTAGEN Reserved(2) Reserved(3) — ICS<1:0> 00AFF0 64 0157F0 128 02AFF0 256 0557F0 512 FPOR 0057F2 32 — WDTWIN<1:0> ALTI2C2 ALTI2C1 Reserved(3) — — — 00AFF2 64 0157F2 128 02AFF2 256 0557F2 512 FWDT 0057F4 32 — FWDTEN WINDIS PLLKEN WDTPRE WDTPOST<3:0> 00AFF4 64 0157F4 128 02AFF4 256 0557F4 512 FOSC 0057F6 32 — FCKSM<1:0> IOL1WAY — — OSCIOFNC POSCMD<1:0> 00AFF6 64 0157F6 128 02AFF6 256 0557F6 512 FOSCSEL 0057F8 32 — IESO PWMLOCK(1) — — — FNOSC<2:0> 00AFF8 64 0157F8 128 02AFF8 256 0557F8 512 FGS 0057FA 32 — — — — — — — GCP GWRP 00AFFA 64 0157FA 128 02AFFA 256 0557FA 512 Reserved 0057FC 32 — — — — — — — — — 00AFFC 64 0157FC 128 02AFFC 256 0557FC 512 Reserved 057FFE 32 — — — — — — — — — 00AFFE 64 0157FE 128 02AFFE 256 0557FE 512 Legend: — = unimplemented, read as ‘1’. Note 1: This bit is only available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices. 2: This bit is reserved and must be programmed as ‘0’. 3: These bits are reserved and must be programmed as ‘1’.  2011-2013 Microchip Technology Inc. DS70000657H-page 381 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 27-2: CONFIGURATION BITS DESCRIPTION Bit Field Description GCP General Segment Code-Protect bit 1 = User program memory is not code-protected 0 = Code protection is enabled for the entire program memory space GWRP General Segment Write-Protect bit 1 = User program memory is not write-protected 0 = User program memory is write-protected IESO Two-Speed Oscillator Start-up Enable bit 1 = Start up device with FRC, then automatically switch to the user-selected oscillator source when ready 0 = Start up device with user-selected oscillator source PWMLOCK(1) PWM Lock Enable bit 1 = Certain PWM registers may only be written after a key sequence 0 = PWM registers may be written without a key sequence FNOSC<2:0> Oscillator Selection bits 111 = Fast RC Oscillator with Divide-by-N (FRCDIVN) 110 = Fast RC Oscillator with Divide-by-16 (FRCDIV16) 101 = Low-Power RC Oscillator (LPRC) 100 = Reserved; do not use 011 = Primary Oscillator with PLL module (XT + PLL, HS + PLL, EC + PLL) 010 = Primary Oscillator (XT, HS, EC) 001 = Fast RC Oscillator with Divide-by-N with PLL module (FRCPLL) 000 = Fast RC Oscillator (FRC) FCKSM<1:0> Clock Switching Mode bits 1x = Clock switching is disabled, Fail-Safe Clock Monitor is disabled 01 = Clock switching is enabled, Fail-Safe Clock Monitor is disabled 00 = Clock switching is enabled, Fail-Safe Clock Monitor is enabled IOL1WAY Peripheral Pin Select Configuration bit 1 = Allow only one reconfiguration 0 = Allow multiple reconfigurations OSCIOFNC OSC2 Pin Function bit (except in XT and HS modes) 1 = OSC2 is the clock output 0 = OSC2 is a general purpose digital I/O pin POSCMD<1:0> Primary Oscillator Mode Select bits 11 = Primary Oscillator is disabled 10 = HS Crystal Oscillator mode 01 = XT Crystal Oscillator mode 00 = EC (External Clock) mode FWDTEN Watchdog Timer Enable bit 1 = Watchdog Timer is always enabled (LPRC oscillator cannot be disabled. Clearing the SWDTEN bit in the RCON register will have no effect.) 0 = Watchdog Timer is enabled/disabled by user software (LPRC can be disabled by clearing the SWDTEN bit in the RCON register) WINDIS Watchdog Timer Window Enable bit 1 = Watchdog Timer in Non-Window mode 0 = Watchdog Timer in Window mode PLLKEN PLL Lock Enable bit 1 = PLL lock is enabled 0 = PLL lock is disabled Note 1: This bit is only available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices. 2: When JTAGEN = 1, an internal pull-up resistor is enabled on the TMS pin. Erased devices default to JTAGEN = 1. Applications requiring I/O pins in a high-impedance state (tri-state) in Reset should use pins other than TMS for this purpose. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 382  2011-2013 Microchip Technology Inc. WDTPRE Watchdog Timer Prescaler bit 1 = 1:128 0 = 1:32 WDTPOST<3:0> Watchdog Timer Postscaler bits 1111 = 1:32,768 1110 = 1:16,384 • • • 0001 = 1:2 0000 = 1:1 WDTWIN<1:0> Watchdog Window Select bits 11 = WDT window is 25% of WDT period 10 = WDT window is 37.5% of WDT period 01 = WDT window is 50% of WDT period 00 = WDT window is 75% of WDT period ALTI2C1 Alternate I2C1 pin 1 = I2C1 is mapped to the SDA1/SCL1 pins 0 = I2C1 is mapped to the ASDA1/ASCL1 pins ALTI2C2 Alternate I2C2 pin 1 = I2C2 is mapped to the SDA2/SCL2 pins 0 = I2C2 is mapped to the ASDA2/ASCL2 pins JTAGEN(2) JTAG Enable bit 1 = JTAG is enabled 0 = JTAG is disabled ICS<1:0> ICD Communication Channel Select bits 11 = Communicate on PGEC1 and PGED1 10 = Communicate on PGEC2 and PGED2 01 = Communicate on PGEC3 and PGED3 00 = Reserved, do not use TABLE 27-2: CONFIGURATION BITS DESCRIPTION (CONTINUED) Bit Field Description Note 1: This bit is only available on dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices. 2: When JTAGEN = 1, an internal pull-up resistor is enabled on the TMS pin. Erased devices default to JTAGEN = 1. Applications requiring I/O pins in a high-impedance state (tri-state) in Reset should use pins other than TMS for this purpose.  2011-2013 Microchip Technology Inc. DS70000657H-page 383 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X REGISTER 27-1: DEVID: DEVICE ID REGISTER RRRRRRRR DEVID<23:16>(1) bit 23 bit 16 RRRRRRRR DEVID<15:8>(1) bit 15 bit 8 RRRRRRRR DEVID<7:0>(1) bit 7 bit 0 Legend: R = Read-Only bit U = Unimplemented bit bit 23-0 DEVID<23:0>: Device Identifier bits(1) Note 1: Refer to the “dsPIC33E/PIC24E Flash Programming Specification for Devices with Volatile Configuration Bits” (DS70663) for the list of device ID values. REGISTER 27-2: DEVREV: DEVICE REVISION REGISTER R R R RR R R R DEVREV<23:16>(1) bit 23 bit 16 R R R RR R R R DEVREV<15:8>(1) bit 15 bit 8 R R R RR R R R DEVREV<7:0>(1) bit 7 bit 0 Legend: R = Read-only bit U = Unimplemented bit bit 23-0 DEVREV<23:0>: Device Revision bits(1) Note 1: Refer to the “dsPIC33E/PIC24E Flash Programming Specification for Devices with Volatile Configuration Bits” (DS70663) for the list of device revision values. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 384  2011-2013 Microchip Technology Inc. 27.2 User ID Words dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X devices contain four User ID Words, located at addresses, 0x800FF8 through 0x800FFE. The User ID Words can be used for storing product information such as serial numbers, system manufacturing dates, manufacturing lot numbers and other application-specific information. The User ID Words register map is shown in Table 27-3. TABLE 27-3: USER ID WORDS REGISTER MAP 27.3 On-Chip Voltage Regulator All of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/ MC20X devices power their core digital logic at a nominal 1.8V. This can create a conflict for designs that are required to operate at a higher typical voltage, such as 3.3V. To simplify system design, all devices in the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X family incorporate an onchip regulator that allows the device to run its core logic from VDD. The regulator provides power to the core from the other VDD pins. A low-ESR (less than 1 Ohm) capacitor (such as tantalum or ceramic) must be connected to the VCAP pin (Figure 27-1). This helps to maintain the stability of the regulator. The recommended value for the filter capacitor is provided in Table 30-5 located in Section 30.0 “Electrical Characteristics”. FIGURE 27-1: CONNECTIONS FOR THE ON-CHIP VOLTAGE REGULATOR(1,2,3) 27.4 Brown-out Reset (BOR) The Brown-out Reset (BOR) module is based on an internal voltage reference circuit that monitors the regulated supply voltage, VCAP. The main purpose of the BOR module is to generate a device Reset when a brown-out condition occurs. Brown-out conditions are generally caused by glitches on the AC mains (for example, missing portions of the AC cycle waveform due to bad power transmission lines or voltage sags due to excessive current draw when a large inductive load is turned on). A BOR generates a Reset pulse, which resets the device. The BOR selects the clock source, based on the device Configuration bit values (FNOSC<2:0> and POSCMD<1:0>). If an oscillator mode is selected, the BOR activates the Oscillator Start-up Timer (OST). The system clock is held until OST expires. If the PLL is used, the clock is held until the LOCK bit (OSCCON<5>) is ‘1’. Concurrently, the PWRT Time-out (TPWRT) is applied before the internal Reset is released. If TPWRT = 0 and a crystal oscillator is being used, then a nominal delay of TFSCM is applied. The total delay in this case is TFSCM. Refer to Parameter SY35 in Table 30-22 of Section 30.0 “Electrical Characteristics” for specific TFSCM values. The BOR status bit (RCON<1>) is set to indicate that a BOR has occurred. The BOR circuit continues to operate while in Sleep or Idle modes and resets the device should VDD fall below the BOR threshold voltage. File Name Address Bits 23-16 Bits 15-0 FUID0 0x800FF8 — UID0 FUID1 0x800FFA — UID1 FUID2 0x800FFC — UID2 FUID3 0x800FFE — UID3 Legend: — = unimplemented, read as ‘1’. Note: It is important for the low-ESR capacitor to be placed as close as possible to the VCAP pin. Note 1: These are typical operating voltages. Refer to Table 30-5 located in Section 30.1 “DC Characteristics” for the full operating ranges of VDD and VCAP. 2: It is important for the low-ESR capacitor to be placed as close as possible to the VCAP pin. 3: Typical VCAP pin voltage = 1.8V when VDD ≥ VDDMIN. VDD VCAP VSS dsPIC33E/PIC24E 3.3V CEFC  2011-2013 Microchip Technology Inc. DS70000657H-page 385 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 27.5 Watchdog Timer (WDT) For dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X devices, the WDT is driven by the LPRC oscillator. When the WDT is enabled, the clock source is also enabled. 27.5.1 PRESCALER/POSTSCALER The nominal WDT clock source from LPRC is 32 kHz. This feeds a prescaler that can be configured for either 5-bit (divide-by-32) or 7-bit (divide-by-128) operation. The prescaler is set by the WDTPRE Configuration bit. With a 32 kHz input, the prescaler yields a WDT Timeout period (TWDT), as shown in Parameter SY12 in Table 30-22. A variable postscaler divides down the WDT prescaler output and allows for a wide range of time-out periods. The postscaler is controlled by the WDTPOST<3:0> Configuration bits (FWDT<3:0>), which allow the selection of 16 settings, from 1:1 to 1:32,768. Using the prescaler and postscaler, time-out periods ranging from 1 ms to 131 seconds can be achieved. The WDT, prescaler and postscaler are reset: • On any device Reset • On the completion of a clock switch, whether invoked by software (i.e., setting the OSWEN bit after changing the NOSCx bits) or by hardware (i.e., Fail-Safe Clock Monitor) • When a PWRSAV instruction is executed (i.e., Sleep or Idle mode is entered) • When the device exits Sleep or Idle mode to resume normal operation • By a CLRWDT instruction during normal execution 27.5.2 SLEEP AND IDLE MODES If the WDT is enabled, it continues to run during Sleep or Idle modes. When the WDT time-out occurs, the device wakes the device and code execution continues from where the PWRSAV instruction was executed. The corresponding SLEEP or IDLE bit (RCON<3,2>) needs to be cleared in software after the device wakes up. 27.5.3 ENABLING WDT The WDT is enabled or disabled by the FWDTEN Configuration bit in the FWDT Configuration register. When the FWDTEN Configuration bit is set, the WDT is always enabled. The WDT can be optionally controlled in software when the FWDTEN Configuration bit has been programmed to ‘0’. The WDT is enabled in software by setting the SWDTEN control bit (RCON<5>). The SWDTEN control bit is cleared on any device Reset. The software WDT option allows the user application to enable the WDT for critical code segments and disable the WDT during non-critical segments for maximum power savings. The WDT flag bit, WDTO (RCON<4>), is not automatically cleared following a WDT time-out. To detect subsequent WDT events, the flag must be cleared in software. 27.5.4 WDT WINDOW The Watchdog Timer has an optional Windowed mode, enabled by programming the WINDIS bit in the WDT Configuration register (FWDT<6>). In the Windowed mode (WINDIS = 0), the WDT should be cleared based on the settings in the programmable Watchdog Timer Window select bits (WDTWIN<1:0>). FIGURE 27-2: WDT BLOCK DIAGRAM Note: The CLRWDT and PWRSAV instructions clear the prescaler and postscaler counts when executed. 0 1 WDTPRE WDTPOST<3:0> Watchdog Timer Prescaler (Divide-by-N1) Postscaler (Divide-by-N2) Sleep/Idle WDT WDT Window Select WINDIS WDT CLRWDT Instruction SWDTEN FWDTEN LPRC Clock RS RS Wake-up Reset WDTWIN<1:0> All Device Resets Transition to New Clock Source Exit Sleep or Idle Mode PWRSAV Instruction CLRWDT Instruction dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 386  2011-2013 Microchip Technology Inc. 27.6 JTAG Interface dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X devices implement a JTAG interface, which supports boundary scan device testing. Detailed information on this interface is provided in future revisions of the document. 27.7 In-Circuit Serial Programming The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X and PIC24EPXXXGP/MC20X devices can be serially programmed while in the end application circuit. This is done with two lines for clock and data, and three other lines for power, ground and the programming sequence. Serial programming allows customers to manufacture boards with unprogrammed devices and then program the device just before shipping the product. Serial programming also allows the most recent firmware or a custom firmware to be programmed. Refer to the “dsPIC33E/PIC24E Flash Programming Specification for Devices with Volatile Configuration Bits” (DS70663) for details about In-Circuit Serial Programming (ICSP). Any of the three pairs of programming clock/data pins can be used: • PGEC1 and PGED1 • PGEC2 and PGED2 • PGEC3 and PGED3 27.8 In-Circuit Debugger When MPLAB® ICD 3 or REAL ICE™ is selected as a debugger, the in-circuit debugging functionality is enabled. This function allows simple debugging functions when used with MPLAB IDE. Debugging functionality is controlled through the PGECx (Emulation/ Debug Clock) and PGEDx (Emulation/Debug Data) pin functions. Any of the three pairs of debugging clock/data pins can be used: • PGEC1 and PGED1 • PGEC2 and PGED2 • PGEC3 and PGED3 To use the in-circuit debugger function of the device, the design must implement ICSP connections to MCLR, VDD, VSS and the PGECx/PGEDx pin pair. In addition, when the feature is enabled, some of the resources are not available for general use. These resources include the first 80 bytes of data RAM and two I/O pins (PGECx and PGEDx). 27.9 Code Protection and CodeGuard™ Security The dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/ 50X, and PIC24EPXXXGP/MC20X devices offer basic implementation of CodeGuard Security that supports only General Segment (GS) security. This feature helps protect individual Intellectual Property. Note: Refer to “Programming and Diagnostics” (DS70608) in the “dsPIC33/PIC24 Family Reference Manual” for further information on usage, configuration and operation of the JTAG interface. Note: Refer to “CodeGuard™ Security” (DS70634) in the “dsPIC33/PIC24 Family Reference Manual” for further information on usage, configuration and operation of CodeGuard Security.  2011-2013 Microchip Technology Inc. DS70000657H-page 387 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 28.0 INSTRUCTION SET SUMMARY The dsPIC33EP instruction set is almost identical to that of the dsPIC30F and dsPIC33F. The PIC24EP instruction set is almost identical to that of the PIC24F and PIC24H. Most instructions are a single program memory word (24 bits). Only three instructions require two program memory locations. Each single-word instruction is a 24-bit word, divided into an 8-bit opcode, which 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 five basic categories: • Word or byte-oriented operations • Bit-oriented operations • Literal operations • DSP operations • Control operations Table 28-1 lists the general symbols used in describing the instructions. The dsPIC33E instruction set summary in Table 28-2 lists all the instructions, along with the status flags affected by each instruction. Most word or byte-oriented W register instructions (including barrel shift instructions) have three operands: • The first source operand, which is typically a register ‘Wb’ without any address modifier • The second source operand, which is typically a register ‘Ws’ with or without an address modifier • The destination of the result, which is typically a register ‘Wd’ with or without an address modifier However, word or byte-oriented file register instructions have two operands: • The file register specified by the value ‘f’ • The destination, which could be either the file register ‘f’ or the W0 register, which is denoted as ‘WREG’ Most bit-oriented instructions (including simple rotate/ shift instructions) have two operands: • The W register (with or without an address modifier) or file register (specified by the value of ‘Ws’ or ‘f’) • The bit in the W register or file register (specified by a literal value or indirectly by the contents of register ‘Wb’) The literal instructions that involve data movement can use some of the following operands: • A literal value to be loaded into a W register or file register (specified by ‘k’) • The W register or file register where the literal value is to be loaded (specified by ‘Wb’ or ‘f’) However, literal instructions that involve arithmetic or logical operations use some of the following operands: • The first source operand, which is a register ‘Wb’ without any address modifier • The second source operand, which is a literal value • The destination of the result (only if not the same as the first source operand), which is typically a register ‘Wd’ with or without an address modifier The MAC class of DSP instructions can use some of the following operands: • The accumulator (A or B) to be used (required operand) • The W registers to be used as the two operands • The X and Y address space prefetch operations • The X and Y address space prefetch destinations • The accumulator write back destination The other DSP instructions do not involve any multiplication and can include: • The accumulator to be used (required) • The source or destination operand (designated as Wso or Wdo, respectively) with or without an address modifier • The amount of shift specified by a W register ‘Wn’ or a literal value The control instructions can use some of the following operands: • A program memory address • The mode of the Table Read and Table Write instructions Note: This data sheet summarizes the features of the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X families of devices. It is not intended to be a comprehensive reference source. To complement the information in this data sheet, refer to the related section of the “dsPIC33/PIC24 Family Reference Manual”, which is available from the Microchip web site (www.microchip.com). dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 388  2011-2013 Microchip Technology Inc. Most instructions are a single word. Certain double-word instructions are designed to provide all the required information in these 48 bits. In the second word, the 8 MSbs are ‘0’s. If this second word is executed as an instruction (by itself), it executes as a NOP. The double-word instructions execute in two instruction cycles. Most 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, or a PSV or Table Read is performed, or an SFR register is read. In these cases, the execution takes multiple instruction cycles with the additional instruction cycle(s) executed as a NOP. Certain instructions that involve skipping over the subsequent instruction require either two or three cycles if the skip is performed, depending on whether the instruction being skipped is a single-word or two-word instruction. Moreover, double-word moves require two cycles. Note: For more details on the instruction set, refer to the “16-bit MCU and DSC Programmer’s Reference Manual” (DS70157). For more information on instructions that take more than one instruction cycle to execute, refer to “CPU” (DS70359) in the “dsPIC33/PIC24 Family Reference Manual”, particularly the “Instruction Flow Types” section. TABLE 28-1: SYMBOLS USED IN OPCODE DESCRIPTIONS Field Description #text Means literal defined by “text” (text) Means “content of text” [text] Means “the location addressed by text” { } Optional field or operation a  {b, c, d} a is selected from the set of values b, c, d Register bit field .b Byte mode selection .d Double-Word mode selection .S Shadow register select .w Word mode selection (default) Acc One of two accumulators {A, B} AWB Accumulator write back destination address register {W13, [W13]+ = 2} bit4 4-bit bit selection field (used in word addressed instructions) {0...15} C, DC, N, OV, Z MCU Status bits: Carry, Digit Carry, Negative, Overflow, Sticky Zero Expr Absolute address, label or expression (resolved by the linker) f File register address {0x0000...0x1FFF} lit1 1-bit unsigned literal {0,1} lit4 4-bit unsigned literal {0...15} lit5 5-bit unsigned literal {0...31} lit8 8-bit unsigned literal {0...255} lit10 10-bit unsigned literal {0...255} for Byte mode, {0:1023} for Word mode lit14 14-bit unsigned literal {0...16384} lit16 16-bit unsigned literal {0...65535} lit23 23-bit unsigned literal {0...8388608}; LSb must be ‘0’ None Field does not require an entry, can be blank OA, OB, SA, SB DSP Status bits: ACCA Overflow, ACCB Overflow, ACCA Saturate, ACCB Saturate PC Program Counter Slit10 10-bit signed literal {-512...511} Slit16 16-bit signed literal {-32768...32767} Slit6 6-bit signed literal {-16...16} Wb Base W register {W0...W15} Wd Destination W register { Wd, [Wd], [Wd++], [Wd--], [++Wd], [--Wd] } Wdo Destination W register  { Wnd, [Wnd], [Wnd++], [Wnd--], [++Wnd], [--Wnd], [Wnd+Wb] }  2011-2013 Microchip Technology Inc. DS70000657H-page 389 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Wm,Wn Dividend, Divisor working register pair (direct addressing) Wm*Wm Multiplicand and Multiplier working register pair for Square instructions  {W4 * W4,W5 * W5,W6 * W6,W7 * W7} Wm*Wn Multiplicand and Multiplier working register pair for DSP instructions  {W4 * W5,W4 * W6,W4 * W7,W5 * W6,W5 * W7,W6 * W7} Wn One of 16 working registers {W0...W15} Wnd One of 16 destination working registers {W0...W15} Wns One of 16 source working registers {W0...W15} WREG W0 (working register used in file register instructions) Ws Source W register { Ws, [Ws], [Ws++], [Ws--], [++Ws], [--Ws] } Wso Source W register  { Wns, [Wns], [Wns++], [Wns--], [++Wns], [--Wns], [Wns+Wb] } Wx X Data Space Prefetch Address register for DSP instructions  {[W8] + = 6, [W8] + = 4, [W8] + = 2, [W8], [W8] - = 6, [W8] - = 4, [W8] - = 2, [W9] + = 6, [W9] + = 4, [W9] + = 2, [W9], [W9] - = 6, [W9] - = 4, [W9] - = 2, [W9 + W12], none} Wxd X Data Space Prefetch Destination register for DSP instructions {W4...W7} Wy Y Data Space Prefetch Address register for DSP instructions  {[W10] + = 6, [W10] + = 4, [W10] + = 2, [W10], [W10] - = 6, [W10] - = 4, [W10] - = 2, [W11] + = 6, [W11] + = 4, [W11] + = 2, [W11], [W11] - = 6, [W11] - = 4, [W11] - = 2, [W11 + W12], none} Wyd Y Data Space Prefetch Destination register for DSP instructions {W4...W7} TABLE 28-1: SYMBOLS USED IN OPCODE DESCRIPTIONS (CONTINUED) Field Description dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 390  2011-2013 Microchip Technology Inc. TABLE 28-2: INSTRUCTION SET OVERVIEW Base Instr # Assembly Mnemonic Assembly Syntax Description # of Words # of Cycles(2) Status Flags Affected 1 ADD ADD Acc(1) Add Accumulators 1 1 OA,OB,SA,SB ADD f f = f + WREG 1 1 C,DC,N,OV,Z ADD f,WREG WREG = f + WREG 1 1 C,DC,N,OV,Z ADD #lit10,Wn Wd = lit10 + Wd 1 1 C,DC,N,OV,Z ADD Wb,Ws,Wd Wd = Wb + Ws 1 1 C,DC,N,OV,Z ADD Wb,#lit5,Wd Wd = Wb + lit5 1 1 C,DC,N,OV,Z ADD Wso,#Slit4,Acc 16-bit Signed Add to Accumulator 1 1 OA,OB,SA,SB 2 ADDC ADDC f f = f + WREG + (C) 1 1 C,DC,N,OV,Z ADDC f,WREG WREG = f + WREG + (C) 1 1 C,DC,N,OV,Z ADDC #lit10,Wn Wd = lit10 + Wd + (C) 1 1 C,DC,N,OV,Z ADDC Wb,Ws,Wd Wd = Wb + Ws + (C) 1 1 C,DC,N,OV,Z ADDC Wb,#lit5,Wd Wd = Wb + lit5 + (C) 1 1 C,DC,N,OV,Z 3 AND AND f f = f .AND. WREG 1 1 N,Z AND f,WREG WREG = f .AND. WREG 1 1 N,Z AND #lit10,Wn Wd = lit10 .AND. Wd 1 1 N,Z AND Wb,Ws,Wd Wd = Wb .AND. Ws 1 1 N,Z AND Wb,#lit5,Wd Wd = Wb .AND. lit5 1 1 N,Z 4 ASR ASR f f = Arithmetic Right Shift f 1 1 C,N,OV,Z ASR f,WREG WREG = Arithmetic Right Shift f 1 1 C,N,OV,Z ASR Ws,Wd Wd = Arithmetic Right Shift Ws 1 1 C,N,OV,Z ASR Wb,Wns,Wnd Wnd = Arithmetic Right Shift Wb by Wns 1 1 N,Z ASR Wb,#lit5,Wnd Wnd = Arithmetic Right Shift Wb by lit5 1 1 N,Z 5 BCLR BCLR f,#bit4 Bit Clear f 1 1 None BCLR Ws,#bit4 Bit Clear Ws 1 1 None 6 BRA BRA C,Expr Branch if Carry 1 1 (4) None BRA GE,Expr Branch if greater than or equal 1 1 (4) None BRA GEU,Expr Branch if unsigned greater than or equal 1 1 (4) None BRA GT,Expr Branch if greater than 1 1 (4) None BRA GTU,Expr Branch if unsigned greater than 1 1 (4) None BRA LE,Expr Branch if less than or equal 1 1 (4) None BRA LEU,Expr Branch if unsigned less than or equal 1 1 (4) None BRA LT,Expr Branch if less than 1 1 (4) None BRA LTU,Expr Branch if unsigned less than 1 1 (4) None BRA N,Expr Branch if Negative 1 1 (4) None BRA NC,Expr Branch if Not Carry 1 1 (4) None BRA NN,Expr Branch if Not Negative 1 1 (4) None BRA NOV,Expr Branch if Not Overflow 1 1 (4) None BRA NZ,Expr Branch if Not Zero 1 1 (4) None BRA OA,Expr(1) Branch if Accumulator A overflow 1 1 (4) None BRA OB,Expr(1) Branch if Accumulator B overflow 1 1 (4) None BRA OV,Expr(1) Branch if Overflow 1 1 (4) None BRA SA,Expr(1) Branch if Accumulator A saturated 1 1 (4) None BRA SB,Expr(1) Branch if Accumulator B saturated 1 1 (4) None BRA Expr Branch Unconditionally 1 4 None BRA Z,Expr Branch if Zero 1 1 (4) None BRA Wn Computed Branch 1 4 None 7 BSET BSET f,#bit4 Bit Set f 1 1 None BSET Ws,#bit4 Bit Set Ws 1 1 None 8 BSW BSW.C Ws,Wb Write C bit to Ws 1 1 None BSW.Z Ws,Wb Write Z bit to Ws 1 1 None Note 1: These instructions are available in dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. 2: Read and Read-Modify-Write (e.g., bit operations and logical operations) on non-CPU SFRs incur an additional instruction cycle.  2011-2013 Microchip Technology Inc. DS70000657H-page 391 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 9 BTG BTG f,#bit4 Bit Toggle f 1 1 None BTG Ws,#bit4 Bit Toggle Ws 1 1 None 10 BTSC BTSC f,#bit4 Bit Test f, Skip if Clear 1 1 (2 or 3) None BTSC Ws,#bit4 Bit Test Ws, Skip if Clear 1 1 (2 or 3) None 11 BTSS BTSS f,#bit4 Bit Test f, Skip if Set 1 1 (2 or 3) None BTSS Ws,#bit4 Bit Test Ws, Skip if Set 1 1 (2 or 3) None 12 BTST BTST f,#bit4 Bit Test f 1 1 Z BTST.C Ws,#bit4 Bit Test Ws to C 1 1 C BTST.Z Ws,#bit4 Bit Test Ws to Z 1 1 Z BTST.C Ws,Wb Bit Test Ws to C 1 1 C BTST.Z Ws,Wb Bit Test Ws to Z 1 1 Z 13 BTSTS BTSTS f,#bit4 Bit Test then Set f 1 1 Z BTSTS.C Ws,#bit4 Bit Test Ws to C, then Set 1 1 C BTSTS.Z Ws,#bit4 Bit Test Ws to Z, then Set 1 1 Z 14 CALL CALL lit23 Call subroutine 2 4 SFA CALL Wn Call indirect subroutine 1 4 SFA CALL.L Wn Call indirect subroutine (long address) 1 4 SFA 15 CLR CLR f f = 0x0000 1 1 None CLR WREG WREG = 0x0000 1 1 None CLR Ws Ws = 0x0000 1 1 None CLR Acc,Wx,Wxd,Wy,Wyd,AWB(1) Clear Accumulator 1 1 OA,OB,SA,SB 16 CLRWDT CLRWDT Clear Watchdog Timer 1 1 WDTO,Sleep 17 COM COM f f = f 1 1 N,Z COM f,WREG WREG = f 1 1 N,Z COM Ws,Wd Wd = Ws 1 1 N,Z 18 CP CP f Compare f with WREG 1 1 C,DC,N,OV,Z CP Wb,#lit8 Compare Wb with lit8 1 1 C,DC,N,OV,Z CP Wb,Ws Compare Wb with Ws (Wb – Ws) 1 1 C,DC,N,OV,Z 19 CP0 CP0 f Compare f with 0x0000 1 1 C,DC,N,OV,Z CP0 Ws Compare Ws with 0x0000 1 1 C,DC,N,OV,Z 20 CPB CPB f Compare f with WREG, with Borrow 1 1 C,DC,N,OV,Z CPB Wb,#lit8 Compare Wb with lit8, with Borrow 1 1 C,DC,N,OV,Z CPB Wb,Ws Compare Wb with Ws, with Borrow (Wb – Ws – C) 1 1 C,DC,N,OV,Z 21 CPSEQ CPSEQ Wb,Wn Compare Wb with Wn, skip if = 1 1 (2 or 3) None CPBEQ CPBEQ Wb,Wn,Expr Compare Wb with Wn, branch if = 1 1 (5) None 22 CPSGT CPSGT Wb,Wn Compare Wb with Wn, skip if > 1 1 (2 or 3) None CPBGT CPBGT Wb,Wn,Expr Compare Wb with Wn, branch if > 1 1 (5) None 23 CPSLT CPSLT Wb,Wn Compare Wb with Wn, skip if < 1 1 (2 or 3) None CPBLT CPBLT Wb,Wn,Expr Compare Wb with Wn, branch if < 1 1 (5) None 24 CPSNE CPSNE Wb,Wn Compare Wb with Wn, skip if  1 1 (2 or 3) None CPBNE CPBNE Wb,Wn,Expr Compare Wb with Wn, branch if  1 1 (5) None TABLE 28-2: INSTRUCTION SET OVERVIEW (CONTINUED) Base Instr # Assembly Mnemonic Assembly Syntax Description # of Words # of Cycles(2) Status Flags Affected Note 1: These instructions are available in dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. 2: Read and Read-Modify-Write (e.g., bit operations and logical operations) on non-CPU SFRs incur an additional instruction cycle. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 392  2011-2013 Microchip Technology Inc. 25 DAW DAW Wn Wn = decimal adjust Wn 1 1 C 26 DEC DEC f f = f – 1 1 1 C,DC,N,OV,Z DEC f,WREG WREG = f – 1 1 1 C,DC,N,OV,Z DEC Ws,Wd Wd = Ws – 1 1 1 C,DC,N,OV,Z 27 DEC2 DEC2 f f = f – 2 1 1 C,DC,N,OV,Z DEC2 f,WREG WREG = f – 2 1 1 C,DC,N,OV,Z DEC2 Ws,Wd Wd = Ws – 2 1 1 C,DC,N,OV,Z 28 DISI DISI #lit14 Disable Interrupts for k instruction cycles 1 1 None 29 DIV DIV.S Wm,Wn Signed 16/16-bit Integer Divide 1 18 N,Z,C,OV DIV.SD Wm,Wn Signed 32/16-bit Integer Divide 1 18 N,Z,C,OV DIV.U Wm,Wn Unsigned 16/16-bit Integer Divide 1 18 N,Z,C,OV DIV.UD Wm,Wn Unsigned 32/16-bit Integer Divide 1 18 N,Z,C,OV 30 DIVF DIVF Wm,Wn(1) Signed 16/16-bit Fractional Divide 1 18 N,Z,C,OV 31 DO DO #lit15,Expr(1) Do code to PC + Expr, lit15 + 1 times 2 2 None DO Wn,Expr(1) Do code to PC + Expr, (Wn) + 1 times 2 2 None 32 ED ED Wm*Wm,Acc,Wx,Wy,Wxd(1) Euclidean Distance (no accumulate) 1 1 OA,OB,OAB, SA,SB,SAB 33 EDAC EDAC Wm*Wm,Acc,Wx,Wy,Wxd(1) Euclidean Distance 1 1 OA,OB,OAB, SA,SB,SAB 34 EXCH EXCH Wns,Wnd Swap Wns with Wnd 1 1 None 35 FBCL FBCL Ws,Wnd Find Bit Change from Left (MSb) Side 1 1 C 36 FF1L FF1L Ws,Wnd Find First One from Left (MSb) Side 1 1 C 37 FF1R FF1R Ws,Wnd Find First One from Right (LSb) Side 1 1 C 38 GOTO GOTO Expr Go to address 2 4 None GOTO Wn Go to indirect 1 4 None GOTO.L Wn Go to indirect (long address) 1 4 None 39 INC INC f f = f + 1 1 1 C,DC,N,OV,Z INC f,WREG WREG = f + 1 1 1 C,DC,N,OV,Z INC Ws,Wd Wd = Ws + 1 1 1 C,DC,N,OV,Z 40 INC2 INC2 f f = f + 2 1 1 C,DC,N,OV,Z INC2 f,WREG WREG = f + 2 1 1 C,DC,N,OV,Z INC2 Ws,Wd Wd = Ws + 2 1 1 C,DC,N,OV,Z 41 IOR IOR f f = f .IOR. WREG 1 1 N,Z IOR f,WREG WREG = f .IOR. WREG 1 1 N,Z IOR #lit10,Wn Wd = lit10 .IOR. Wd 1 1 N,Z IOR Wb,Ws,Wd Wd = Wb .IOR. Ws 1 1 N,Z IOR Wb,#lit5,Wd Wd = Wb .IOR. lit5 1 1 N,Z 42 LAC LAC Wso,#Slit4,Acc Load Accumulator 1 1 OA,OB,OAB, SA,SB,SAB 43 LNK LNK #lit14 Link Frame Pointer 1 1 SFA 44 LSR LSR f f = Logical Right Shift f 1 1 C,N,OV,Z LSR f,WREG WREG = Logical Right Shift f 1 1 C,N,OV,Z LSR Ws,Wd Wd = Logical Right Shift Ws 1 1 C,N,OV,Z LSR Wb,Wns,Wnd Wnd = Logical Right Shift Wb by Wns 1 1 N,Z LSR Wb,#lit5,Wnd Wnd = Logical Right Shift Wb by lit5 1 1 N,Z 45 MAC MAC Wm*Wn,Acc,Wx,Wxd,Wy,Wyd,AWB(1) Multiply and Accumulate 1 1 OA,OB,OAB, SA,SB,SAB MAC Wm*Wm,Acc,Wx,Wxd,Wy,Wyd(1) Square and Accumulate 1 1 OA,OB,OAB, SA,SB,SAB TABLE 28-2: INSTRUCTION SET OVERVIEW (CONTINUED) Base Instr # Assembly Mnemonic Assembly Syntax Description # of Words # of Cycles(2) Status Flags Affected Note 1: These instructions are available in dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. 2: Read and Read-Modify-Write (e.g., bit operations and logical operations) on non-CPU SFRs incur an additional instruction cycle.  2011-2013 Microchip Technology Inc. DS70000657H-page 393 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 46 MOV MOV f,Wn Move f to Wn 1 1 None MOV f Move f to f 1 1 None MOV f,WREG Move f to WREG 1 1 None MOV #lit16,Wn Move 16-bit literal to Wn 1 1 None MOV.b #lit8,Wn Move 8-bit literal to Wn 1 1 None MOV Wn,f Move Wn to f 1 1 None MOV Wso,Wdo Move Ws to Wd 1 1 None MOV WREG,f Move WREG to f 1 1 None MOV.D Wns,Wd Move Double from W(ns):W(ns + 1) to Wd 1 2 None MOV.D Ws,Wnd Move Double from Ws to W(nd + 1):W(nd) 1 2 None 47 MOVPAG MOVPAG #lit10,DSRPAG Move 10-bit literal to DSRPAG 1 1 None MOVPAG #lit9,DSWPAG Move 9-bit literal to DSWPAG 1 1 None MOVPAG #lit8,TBLPAG Move 8-bit literal to TBLPAG 1 1 None MOVPAG Ws, DSRPAG Move Ws<9:0> to DSRPAG 1 1 None MOVPAG Ws, DSWPAG Move Ws<8:0> to DSWPAG 1 1 None MOVPAG Ws, TBLPAG Move Ws<7:0> to TBLPAG 1 1 None 48 MOVSAC MOVSAC Acc,Wx,Wxd,Wy,Wyd,AWB(1) Prefetch and store accumulator 1 1 None 49 MPY MPY Wm*Wn,Acc,Wx,Wxd,Wy,Wyd(1) Multiply Wm by Wn to Accumulator 1 1 OA,OB,OAB, SA,SB,SAB MPY Wm*Wm,Acc,Wx,Wxd,Wy,Wyd(1) Square Wm to Accumulator 1 1 OA,OB,OAB, SA,SB,SAB 50 MPY.N MPY.N Wm*Wn,Acc,Wx,Wxd,Wy,Wyd(1) -(Multiply Wm by Wn) to Accumulator 1 1 None 51 MSC MSC Wm*Wm,Acc,Wx,Wxd,Wy,Wyd,AWB(1) Multiply and Subtract from Accumulator 1 1 OA,OB,OAB, SA,SB,SAB TABLE 28-2: INSTRUCTION SET OVERVIEW (CONTINUED) Base Instr # Assembly Mnemonic Assembly Syntax Description # of Words # of Cycles(2) Status Flags Affected Note 1: These instructions are available in dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. 2: Read and Read-Modify-Write (e.g., bit operations and logical operations) on non-CPU SFRs incur an additional instruction cycle. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 394  2011-2013 Microchip Technology Inc. 52 MUL MUL.SS Wb,Ws,Wnd {Wnd + 1, Wnd} = signed(Wb) * signed(Ws) 1 1 None MUL.SS Wb,Ws,Acc(1) Accumulator = signed(Wb) * signed(Ws) 1 1 None MUL.SU Wb,Ws,Wnd {Wnd + 1, Wnd} = signed(Wb) * unsigned(Ws) 1 1 None MUL.SU Wb,Ws,Acc(1) Accumulator = signed(Wb) * unsigned(Ws) 1 1 None MUL.SU Wb,#lit5,Acc(1) Accumulator = signed(Wb) * unsigned(lit5) 1 1 None MUL.US Wb,Ws,Wnd {Wnd + 1, Wnd} = unsigned(Wb) * signed(Ws) 1 1 None MUL.US Wb,Ws,Acc(1) Accumulator = unsigned(Wb) * signed(Ws) 1 1 None MUL.UU Wb,Ws,Wnd {Wnd + 1, Wnd} = unsigned(Wb) * unsigned(Ws) 1 1 None MUL.UU Wb,#lit5,Acc(1) Accumulator = unsigned(Wb) * unsigned(lit5) 1 1 None MUL.UU Wb,Ws,Acc(1) Accumulator = unsigned(Wb) * unsigned(Ws) 1 1 None MULW.SS Wb,Ws,Wnd Wnd = signed(Wb) * signed(Ws) 1 1 None MULW.SU Wb,Ws,Wnd Wnd = signed(Wb) * unsigned(Ws) 1 1 None MULW.US Wb,Ws,Wnd Wnd = unsigned(Wb) * signed(Ws) 1 1 None MULW.UU Wb,Ws,Wnd Wnd = unsigned(Wb) * unsigned(Ws) 1 1 None MUL.SU Wb,#lit5,Wnd {Wnd + 1, Wnd} = signed(Wb) * unsigned(lit5) 1 1 None MUL.SU Wb,#lit5,Wnd Wnd = signed(Wb) * unsigned(lit5) 1 1 None MUL.UU Wb,#lit5,Wnd {Wnd + 1, Wnd} = unsigned(Wb) * unsigned(lit5) 1 1 None MUL.UU Wb,#lit5,Wnd Wnd = unsigned(Wb) * unsigned(lit5) 1 1 None MUL f W3:W2 = f * WREG 1 1 None TABLE 28-2: INSTRUCTION SET OVERVIEW (CONTINUED) Base Instr # Assembly Mnemonic Assembly Syntax Description # of Words # of Cycles(2) Status Flags Affected Note 1: These instructions are available in dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. 2: Read and Read-Modify-Write (e.g., bit operations and logical operations) on non-CPU SFRs incur an additional instruction cycle.  2011-2013 Microchip Technology Inc. DS70000657H-page 395 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 53 NEG NEG Acc(1) Negate Accumulator 1 1 OA,OB,OAB, SA,SB,SAB NEG f f = f + 1 1 1 C,DC,N,OV,Z NEG f,WREG WREG = f + 1 1 1 C,DC,N,OV,Z NEG Ws,Wd Wd = Ws + 1 1 1 C,DC,N,OV,Z 54 NOP NOP No Operation 1 1 None NOPR No Operation 1 1 None 55 POP POP f Pop f from Top-of-Stack (TOS) 1 1 None POP Wdo Pop from Top-of-Stack (TOS) to Wdo 1 1 None POP.D Wnd Pop from Top-of-Stack (TOS) to W(nd):W(nd + 1) 1 2 None POP.S Pop Shadow Registers 1 1 All 56 PUSH PUSH f Push f to Top-of-Stack (TOS) 1 1 None PUSH Wso Push Wso to Top-of-Stack (TOS) 1 1 None PUSH.D Wns Push W(ns):W(ns + 1) to Top-of-Stack (TOS) 1 2 None PUSH.S Push Shadow Registers 1 1 None 57 PWRSAV PWRSAV #lit1 Go into Sleep or Idle mode 1 1 WDTO,Sleep 58 RCALL RCALL Expr Relative Call 1 4 SFA RCALL Wn Computed Call 1 4 SFA 59 REPEAT REPEAT #lit15 Repeat Next Instruction lit15 + 1 times 1 1 None REPEAT Wn Repeat Next Instruction (Wn) + 1 times 1 1 None 60 RESET RESET Software device Reset 1 1 None 61 RETFIE RETFIE Return from interrupt 1 6 (5) SFA 62 RETLW RETLW #lit10,Wn Return with literal in Wn 1 6 (5) SFA 63 RETURN RETURN Return from Subroutine 1 6 (5) SFA 64 RLC RLC f f = Rotate Left through Carry f 1 1 C,N,Z RLC f,WREG WREG = Rotate Left through Carry f 1 1 C,N,Z RLC Ws,Wd Wd = Rotate Left through Carry Ws 1 1 C,N,Z 65 RLNC RLNC f f = Rotate Left (No Carry) f 1 1 N,Z RLNC f,WREG WREG = Rotate Left (No Carry) f 1 1 N,Z RLNC Ws,Wd Wd = Rotate Left (No Carry) Ws 1 1 N,Z 66 RRC RRC f f = Rotate Right through Carry f 1 1 C,N,Z RRC f,WREG WREG = Rotate Right through Carry f 1 1 C,N,Z RRC Ws,Wd Wd = Rotate Right through Carry Ws 1 1 C,N,Z 67 RRNC RRNC f f = Rotate Right (No Carry) f 1 1 N,Z RRNC f,WREG WREG = Rotate Right (No Carry) f 1 1 N,Z RRNC Ws,Wd Wd = Rotate Right (No Carry) Ws 1 1 N,Z 68 SAC SAC Acc,#Slit4,Wdo(1) Store Accumulator 1 1 None SAC.R Acc,#Slit4,Wdo(1) Store Rounded Accumulator 1 1 None 69 SE SE Ws,Wnd Wnd = sign-extended Ws 1 1 C,N,Z 70 SETM SETM f f = 0xFFFF 1 1 None SETM WREG WREG = 0xFFFF 1 1 None SETM Ws Ws = 0xFFFF 1 1 None 71 SFTAC SFTAC Acc,Wn(1) Arithmetic Shift Accumulator by (Wn) 1 1 OA,OB,OAB, SA,SB,SAB SFTAC Acc,#Slit6(1) Arithmetic Shift Accumulator by Slit6 1 1 OA,OB,OAB, SA,SB,SAB TABLE 28-2: INSTRUCTION SET OVERVIEW (CONTINUED) Base Instr # Assembly Mnemonic Assembly Syntax Description # of Words # of Cycles(2) Status Flags Affected Note 1: These instructions are available in dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. 2: Read and Read-Modify-Write (e.g., bit operations and logical operations) on non-CPU SFRs incur an additional instruction cycle. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 396  2011-2013 Microchip Technology Inc. 72 SL SL f f = Left Shift f 1 1 C,N,OV,Z SL f,WREG WREG = Left Shift f 1 1 C,N,OV,Z SL Ws,Wd Wd = Left Shift Ws 1 1 C,N,OV,Z SL Wb,Wns,Wnd Wnd = Left Shift Wb by Wns 1 1 N,Z SL Wb,#lit5,Wnd Wnd = Left Shift Wb by lit5 1 1 N,Z 73 SUB SUB Acc(1) Subtract Accumulators 1 1 OA,OB,OAB, SA,SB,SAB SUB f f = f – WREG 1 1 C,DC,N,OV,Z SUB f,WREG WREG = f – WREG 1 1 C,DC,N,OV,Z SUB #lit10,Wn Wn = Wn – lit10 1 1 C,DC,N,OV,Z SUB Wb,Ws,Wd Wd = Wb – Ws 1 1 C,DC,N,OV,Z SUB Wb,#lit5,Wd Wd = Wb – lit5 1 1 C,DC,N,OV,Z 74 SUBB SUBB f f = f – WREG – (C) 1 1 C,DC,N,OV,Z SUBB f,WREG WREG = f – WREG – (C) 1 1 C,DC,N,OV,Z SUBB #lit10,Wn Wn = Wn – lit10 – (C) 1 1 C,DC,N,OV,Z SUBB Wb,Ws,Wd Wd = Wb – Ws – (C) 1 1 C,DC,N,OV,Z SUBB Wb,#lit5,Wd Wd = Wb – lit5 – (C) 1 1 C,DC,N,OV,Z 75 SUBR SUBR f f = WREG – f 1 1 C,DC,N,OV,Z SUBR f,WREG WREG = WREG – f 1 1 C,DC,N,OV,Z SUBR Wb,Ws,Wd Wd = Ws – Wb 1 1 C,DC,N,OV,Z SUBR Wb,#lit5,Wd Wd = lit5 – Wb 1 1 C,DC,N,OV,Z 76 SUBBR SUBBR f f = WREG – f – (C) 1 1 C,DC,N,OV,Z SUBBR f,WREG WREG = WREG – f – (C) 1 1 C,DC,N,OV,Z SUBBR Wb,Ws,Wd Wd = Ws – Wb – (C) 1 1 C,DC,N,OV,Z SUBBR Wb,#lit5,Wd Wd = lit5 – Wb – (C) 1 1 C,DC,N,OV,Z 77 SWAP SWAP.b Wn Wn = nibble swap Wn 1 1 None SWAP Wn Wn = byte swap Wn 1 1 None 78 TBLRDH TBLRDH Ws,Wd Read Prog<23:16> to Wd<7:0> 1 5 None 79 TBLRDL TBLRDL Ws,Wd Read Prog<15:0> to Wd 1 5 None 80 TBLWTH TBLWTH Ws,Wd Write Ws<7:0> to Prog<23:16> 1 2 None 81 TBLWTL TBLWTL Ws,Wd Write Ws to Prog<15:0> 1 2 None 82 ULNK ULNK Unlink Frame Pointer 1 1 SFA 83 XOR XOR f f = f .XOR. WREG 1 1 N,Z XOR f,WREG WREG = f .XOR. WREG 1 1 N,Z XOR #lit10,Wn Wd = lit10 .XOR. Wd 1 1 N,Z XOR Wb,Ws,Wd Wd = Wb .XOR. Ws 1 1 N,Z XOR Wb,#lit5,Wd Wd = Wb .XOR. lit5 1 1 N,Z 84 ZE ZE Ws,Wnd Wnd = Zero-extend Ws 1 1 C,Z,N TABLE 28-2: INSTRUCTION SET OVERVIEW (CONTINUED) Base Instr # Assembly Mnemonic Assembly Syntax Description # of Words # of Cycles(2) Status Flags Affected Note 1: These instructions are available in dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X devices only. 2: Read and Read-Modify-Write (e.g., bit operations and logical operations) on non-CPU SFRs incur an additional instruction cycle.  2011-2013 Microchip Technology Inc. DS70000657H-page 397 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 29.0 DEVELOPMENT SUPPORT The PIC® microcontrollers (MCU) and dsPIC® digital signal controllers (DSC) are supported with a full range of software and hardware development tools: • Integrated Development Environment - MPLAB® X IDE Software • Compilers/Assemblers/Linkers - MPLAB XC Compiler - MPASMTM Assembler - MPLINKTM Object Linker/ MPLIBTM Object Librarian - MPLAB Assembler/Linker/Librarian for Various Device Families • Simulators - MPLAB X SIM Software Simulator • Emulators - MPLAB REAL ICE™ In-Circuit Emulator • In-Circuit Debuggers/Programmers - MPLAB ICD 3 - PICkit™ 3 • Device Programmers - MPLAB PM3 Device Programmer • Low-Cost Demonstration/Development Boards, Evaluation Kits and Starter Kits • Third-party development tools 29.1 MPLAB X Integrated Development Environment Software The MPLAB X IDE is a single, unified graphical user interface for Microchip and third-party software, and hardware development tool that runs on Windows®, Linux and Mac OS® X. Based on the NetBeans IDE, MPLAB X IDE is an entirely new IDE with a host of free software components and plug-ins for highperformance application development and debugging. Moving between tools and upgrading from software simulators to hardware debugging and programming tools is simple with the seamless user interface. With complete project management, visual call graphs, a configurable watch window and a feature-rich editor that includes code completion and context menus, MPLAB X IDE is flexible and friendly enough for new users. With the ability to support multiple tools on multiple projects with simultaneous debugging, MPLAB X IDE is also suitable for the needs of experienced users. Feature-Rich Editor: • Color syntax highlighting • Smart code completion makes suggestions and provides hints as you type • Automatic code formatting based on user-defined rules • Live parsing User-Friendly, Customizable Interface: • Fully customizable interface: toolbars, toolbar buttons, windows, window placement, etc. • Call graph window Project-Based Workspaces: • Multiple projects • Multiple tools • Multiple configurations • Simultaneous debugging sessions File History and Bug Tracking: • Local file history feature • Built-in support for Bugzilla issue tracker dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 398  2011-2013 Microchip Technology Inc. 29.2 MPLAB XC Compilers The MPLAB XC Compilers are complete ANSI C compilers for all of Microchip’s 8, 16 and 32-bit MCU and DSC devices. These compilers provide powerful integration capabilities, superior code optimization and ease of use. MPLAB XC Compilers run on Windows, Linux or MAC OS X. For easy source level debugging, the compilers provide debug information that is optimized to the MPLAB X IDE. The free MPLAB XC Compiler editions support all devices and commands, with no time or memory restrictions, and offer sufficient code optimization for most applications. MPLAB XC Compilers include an assembler, linker and utilities. The assembler generates relocatable object files that can then be archived or linked with other relocatable object files and archives to create an executable file. MPLAB XC Compiler uses the assembler to produce its object file. Notable features of the assembler include: • Support for the entire device instruction set • Support for fixed-point and floating-point data • Command-line interface • Rich directive set • Flexible macro language • MPLAB X IDE compatibility 29.3 MPASM Assembler The MPASM Assembler is a full-featured, universal macro assembler for PIC10/12/16/18 MCUs. The MPASM Assembler generates relocatable object files for the MPLINK Object Linker, Intel® standard HEX files, MAP files to detail memory usage and symbol reference, absolute LST files that contain source lines and generated machine code, and COFF files for debugging. The MPASM Assembler features include: • Integration into MPLAB X IDE projects • User-defined macros to streamline assembly code • Conditional assembly for multipurpose source files • Directives that allow complete control over the assembly process 29.4 MPLINK Object Linker/ MPLIB Object Librarian The MPLINK Object Linker combines relocatable objects created by the MPASM Assembler. It can link relocatable objects from precompiled libraries, using directives from a linker script. The MPLIB Object Librarian manages the creation and modification of library files of precompiled code. When a routine from a library is called from a 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. The object linker/library features include: • Efficient linking of single libraries instead of many smaller files • Enhanced code maintainability by grouping related modules together • Flexible creation of libraries with easy module listing, replacement, deletion and extraction 29.5 MPLAB Assembler, Linker and Librarian for Various Device Families MPLAB Assembler produces relocatable machine code from symbolic assembly language for PIC24, PIC32 and dsPIC DSC devices. MPLAB XC Compiler uses the assembler to produce its object file. The assembler generates relocatable object files that can then be archived or linked with other relocatable object files and archives to create an executable file. Notable features of the assembler include: • Support for the entire device instruction set • Support for fixed-point and floating-point data • Command-line interface • Rich directive set • Flexible macro language • MPLAB X IDE compatibility  2011-2013 Microchip Technology Inc. DS70000657H-page 399 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 29.6 MPLAB X SIM Software Simulator The MPLAB X SIM Software Simulator allows code development in a PC-hosted environment by simulating the PIC MCUs and dsPIC DSCs on an instruction level. On any given instruction, the data areas can be examined or modified and stimuli can be applied from a comprehensive stimulus controller. Registers can be logged to files for further run-time analysis. The trace buffer and logic analyzer display extend the power of the simulator to record and track program execution, actions on I/O, most peripherals and internal registers. The MPLAB X SIM Software Simulator fully supports symbolic debugging using the MPLAB XC Compilers, and the MPASM and MPLAB Assemblers. The software simulator offers the flexibility to develop and debug code outside of the hardware laboratory environment, making it an excellent, economical software development tool. 29.7 MPLAB REAL ICE In-Circuit Emulator System The MPLAB REAL ICE In-Circuit Emulator System is Microchip’s next generation high-speed emulator for Microchip Flash DSC and MCU devices. It debugs and programs all 8, 16 and 32-bit MCU, and DSC devices with the easy-to-use, powerful graphical user interface of the MPLAB X IDE. The emulator is connected to the design engineer’s PC using a high-speed USB 2.0 interface and is connected to the target with either a connector compatible with in-circuit debugger systems (RJ-11) or with the new high-speed, noise tolerant, LowVoltage Differential Signal (LVDS) interconnection (CAT5). The emulator is field upgradable through future firmware downloads in MPLAB X IDE. MPLAB REAL ICE offers significant advantages over competitive emulators including full-speed emulation, run-time variable watches, trace analysis, complex breakpoints, logic probes, a ruggedized probe interface and long (up to three meters) interconnection cables. 29.8 MPLAB ICD 3 In-Circuit Debugger System The MPLAB ICD 3 In-Circuit Debugger System is Microchip’s most cost-effective, high-speed hardware debugger/programmer for Microchip Flash DSC and MCU devices. It debugs and programs PIC Flash microcontrollers and dsPIC DSCs with the powerful, yet easy-to-use graphical user interface of the MPLAB IDE. The MPLAB ICD 3 In-Circuit Debugger probe is connected to the design engineer’s PC using a highspeed USB 2.0 interface and is connected to the target with a connector compatible with the MPLAB ICD 2 or MPLAB REAL ICE systems (RJ-11). MPLAB ICD 3 supports all MPLAB ICD 2 headers. 29.9 PICkit 3 In-Circuit Debugger/ Programmer The MPLAB PICkit 3 allows debugging and programming of PIC and dsPIC Flash microcontrollers at a most affordable price point using the powerful graphical user interface of the MPLAB IDE. The MPLAB PICkit 3 is connected to the design engineer’s PC using a fullspeed USB interface and can be connected to the target via a Microchip debug (RJ-11) connector (compatible with MPLAB ICD 3 and MPLAB REAL ICE). The connector uses two device I/O pins and the Reset line to implement in-circuit debugging and In-Circuit Serial Programming™ (ICSP™). 29.10 MPLAB PM3 Device Programmer The MPLAB PM3 Device Programmer is a universal, CE compliant device programmer with programmable voltage verification at VDDMIN and VDDMAX for maximum reliability. It features a large LCD display (128 x 64) for menus and error messages, and a modular, detachable socket assembly to support various package types. The ICSP cable assembly is included as a standard item. In Stand-Alone mode, the MPLAB PM3 Device Programmer can read, verify and program PIC devices without a PC connection. It can also set code protection in this mode. The MPLAB PM3 connects to the host PC via an RS-232 or USB cable. The MPLAB PM3 has high-speed communications and optimized algorithms for quick programming of large memory devices, and incorporates an MMC card for file storage and data applications. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 400  2011-2013 Microchip Technology Inc. 29.11 Demonstration/Development Boards, Evaluation Kits and Starter Kits A wide variety of demonstration, development and evaluation boards for various PIC MCUs and dsPIC DSCs allows quick application development on fully functional systems. Most boards include prototyping areas for adding custom circuitry and provide application firmware and source code for examination and modification. The boards support a variety of features, including LEDs, temperature sensors, switches, speakers, RS-232 interfaces, LCD displays, potentiometers and additional EEPROM memory. The demonstration and development boards can be used in teaching environments, for prototyping custom circuits and for learning about various microcontroller applications. In addition to the PICDEM™ and dsPICDEM™ demonstration/development board series of circuits, Microchip has a line of evaluation kits and demonstration software for analog filter design, KEELOQ® security ICs, CAN, IrDA®, PowerSmart battery management, SEEVAL® evaluation system, Sigma-Delta ADC, flow rate sensing, plus many more. Also available are starter kits that contain everything needed to experience the specified device. This usually includes a single application and debug capability, all on one board. Check the Microchip web page (www.microchip.com) for the complete list of demonstration, development and evaluation kits. 29.12 Third-Party Development Tools Microchip also offers a great collection of tools from third-party vendors. These tools are carefully selected to offer good value and unique functionality. • Device Programmers and Gang Programmers from companies, such as SoftLog and CCS • Software Tools from companies, such as Gimpel and Trace Systems • Protocol Analyzers from companies, such as Saleae and Total Phase • Demonstration Boards from companies, such as MikroElektronika, Digilent® and Olimex • Embedded Ethernet Solutions from companies, such as EZ Web Lynx, WIZnet and IPLogika®  2011-2013 Microchip Technology Inc. DS70000657H-page 401 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 30.0 ELECTRICAL CHARACTERISTICS This section provides an overview of dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/ MC20X electrical characteristics. Additional information will be provided in future revisions of this document as it becomes available. Absolute maximum ratings for the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X family are listed below. Exposure to these maximum rating conditions for extended periods may affect device reliability. Functional operation of the device at these or any other conditions above the parameters indicated in the operation listings of this specification is not implied. Absolute Maximum Ratings(1) Ambient temperature under bias.............................................................................................................-40°C to +125°C Storage temperature .............................................................................................................................. -65°C to +150°C Voltage on VDD with respect to VSS .......................................................................................................... -0.3V to +4.0V Voltage on any pin that is not 5V tolerant, with respect to VSS(3) .................................................... -0.3V to (VDD + 0.3V) Voltage on any 5V tolerant pin with respect to VSS when VDD  3.0V(3) ................................................... -0.3V to +5.5V Voltage on any 5V tolerant pin with respect to Vss when VDD < 3.0V(3) ................................................... -0.3V to +3.6V Maximum current out of VSS pin ...........................................................................................................................300 mA Maximum current into VDD pin(2) ...........................................................................................................................300 mA Maximum current sunk/sourced by any 4x I/O pin..................................................................................................15 mA Maximum current sunk/sourced by any 8x I/O pin..................................................................................................25 mA Maximum current sunk by all ports(2,4) .................................................................................................................200 mA Note 1: 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. 2: Maximum allowable current is a function of device maximum power dissipation (see Table 30-2). 3: See the “Pin Diagrams” section for the 5V tolerant pins. 4: Exceptions are: dsPIC33EPXXXGP502, dsPIC33EPXXXMC202/502 and PIC24EPXXXGP/MC202 devices, which have a maximum sink/source capability of 130 mA. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 402  2011-2013 Microchip Technology Inc. 30.1 DC Characteristics TABLE 30-1: OPERATING MIPS VS. VOLTAGE Characteristic VDD Range (in Volts) Temp Range (in °C) Maximum MIPS dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X — 3.0V to 3.6V(1) -40°C to +85°C 70 — 3.0V to 3.6V(1) -40°C to +125°C 60 Note 1: Device is functional at VBORMIN < VDD < VDDMIN. Analog modules (ADC, op amp/comparator and comparator voltage reference) may have degraded performance. Device functionality is tested but not characterized. Refer to Parameter BO10 in Table 30-13 for the minimum and maximum BOR values. TABLE 30-2: THERMAL OPERATING CONDITIONS Rating Symbol Min. Typ. Max. Unit Industrial Temperature Devices Operating Junction Temperature Range TJ -40 — +125 °C Operating Ambient Temperature Range TA -40 — +85 °C Extended Temperature Devices Operating Junction Temperature Range TJ -40 — +140 °C Operating Ambient Temperature Range TA -40 — +125 °C Power Dissipation: Internal chip power dissipation: PINT = VDD x (IDD –  IOH) PD PINT + PI/O W I/O Pin Power Dissipation: I/O =  ({VDD – VOH} x IOH) +  (VOL x IOL) Maximum Allowed Power Dissipation PDMAX (TJ – TA)/JA W TABLE 30-3: THERMAL PACKAGING CHARACTERISTICS Characteristic Symbol Typ. Max. Unit Notes Package Thermal Resistance, 64-Pin QFN JA 28.0 — °C/W 1 Package Thermal Resistance, 64-Pin TQFP 10x10 mm JA 48.3 — °C/W 1 Package Thermal Resistance, 48-Pin UQFN 6x6 mm JA 41 — °C/W 1 Package Thermal Resistance, 44-Pin QFN JA 29.0 — °C/W 1 Package Thermal Resistance, 44-Pin TQFP 10x10 mm JA 49.8 — °C/W 1 Package Thermal Resistance, 44-Pin VTLA 6x6 mm JA 25.2 — °C/W 1 Package Thermal Resistance, 36-Pin VTLA 5x5 mm JA 28.5 — °C/W 1 Package Thermal Resistance, 28-Pin QFN-S JA 30.0 — °C/W 1 Package Thermal Resistance, 28-Pin SSOP JA 71.0 — °C/W 1 Package Thermal Resistance, 28-Pin SOIC JA 69.7 — °C/W 1 Package Thermal Resistance, 28-Pin SPDIP JA 60.0 — °C/W 1 Note 1: Junction to ambient thermal resistance, Theta-JA (JA) numbers are achieved by package simulations.  2011-2013 Microchip Technology Inc. DS70000657H-page 403 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-5: FILTER CAPACITOR (CEFC) SPECIFICATIONS TABLE 30-4: DC TEMPERATURE AND VOLTAGE SPECIFICATIONS DC CHARACTERISTICS Standard Operating Conditions (see Note 1): 3.0V to 3.6V (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 Operating Voltage DC10 VDD Supply Voltage 3.0 — 3.6 V DC16 VPOR VDD Start Voltage to Ensure Internal Power-on Reset Signal — —VSS V DC17 SVDD VDD Rise Rate to Ensure Internal Power-on Reset Signal 0.03 — — V/ms 0V-1V in 100 ms Note 1: Device is functional at VBORMIN < VDD < VDDMIN. Analog modules (ADC, op amp/comparator and comparator voltage reference) may have degraded performance. Device functionality is tested but not characterized. Refer to Parameter BO10 in Table 30-13 for the minimum and maximum BOR values. 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 Characteristics Min. Typ. Max. Units Comments CEFC External Filter Capacitor Value(1) 4.7 10 — F Capacitor must have a low series resistance (< 1 Ohm) Note 1: Typical VCAP voltage = 1.8 volts when VDD  VDDMIN. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 404  2011-2013 Microchip Technology Inc. TABLE 30-6: DC CHARACTERISTICS: OPERATING CURRENT (IDD) DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Parameter No. Typ. Max. Units Conditions Operating Current (IDD) (1) DC20d 9 15 mA -40°C 3.3V 10 MIPS DC20a 9 15 mA +25°C DC20b 9 15 mA +85°C DC20c 9 15 mA +125°C DC22d 16 25 mA -40°C 3.3V 20 MIPS DC22a 16 25 mA +25°C DC22b 16 25 mA +85°C DC22c 16 25 mA +125°C DC24d 27 40 mA -40°C 3.3V 40 MIPS DC24a 27 40 mA +25°C DC24b 27 40 mA +85°C DC24c 27 40 mA +125°C DC25d 36 55 mA -40°C 3.3V 60 MIPS DC25a 36 55 mA +25°C DC25b 36 55 mA +85°C DC25c 36 55 mA +125°C DC26d 41 60 mA -40°C DC26a 41 60 mA +25°C 3.3V 70 MIPS DC26b 41 60 mA +85°C Note 1: IDD is primarily 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 are as follows: • Oscillator is configured in EC mode with PLL, OSC1 is driven with external square wave from rail-to-rail (EC clock overshoot/undershoot < 250 mV required) • CLKO is configured as an I/O input pin in the Configuration Word • All I/O pins are configured as inputs and pulled to VSS • MCLR = VDD, WDT and FSCM are disabled • CPU, SRAM, program memory and data memory are operational • No peripheral modules are operating; however, every peripheral is being clocked (all PMDx bits are zeroed) • CPU is executing while(1){NOP();} statement • JTAG is disabled  2011-2013 Microchip Technology Inc. DS70000657H-page 405 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-7: DC CHARACTERISTICS: IDLE CURRENT (IIDLE) DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Parameter No. Typ. Max. Units Conditions Idle Current (IIDLE) (1) DC40d 3 8 mA -40°C 3.3V 10 MIPS DC40a 3 8 mA +25°C DC40b 3 8 mA +85°C DC40c 3 8 mA +125°C DC42d 6 12 mA -40°C 3.3V 20 MIPS DC42a 6 12 mA +25°C DC42b 6 12 mA +85°C DC42c 6 12 mA +125°C DC44d 11 18 mA -40°C 3.3V 40 MIPS DC44a 11 18 mA +25°C DC44b 11 mA +85°C 18 DC44c 11 mA +125°C 18 DC45d 17 27 mA -40°C 3.3V 60 MIPS DC45a 17 27 mA +25°C DC45b 17 mA +85°C 27 DC45c 17 mA +125°C 27 DC46d 20 35 mA -40°C DC46a 20 35 mA +25°C 3.3V 70 MIPS DC46b 20 mA +85°C 35 Note 1: Base Idle current (IIDLE) is measured as follows: • CPU core is off, oscillator is configured in EC mode and external clock is active; OSC1 is driven with external square wave from rail-to-rail (EC clock overshoot/undershoot < 250 mV required) • CLKO is configured as an I/O input pin in the Configuration Word • All I/O pins are configured as inputs and pulled to VSS • MCLR = VDD, WDT and FSCM are disabled • No peripheral modules are operating; however, every peripheral is being clocked (all PMDx bits are zeroed) • The NVMSIDL bit (NVMCON<12>) = 1 (i.e., Flash regulator is set to standby while the device is in Idle mode) • The VREGSF bit (RCON<11>) = 0 (i.e., Flash regulator is set to standby while the device is in Sleep mode) • JTAG is disabled dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 406  2011-2013 Microchip Technology Inc. TABLE 30-8: DC CHARACTERISTICS: POWER-DOWN CURRENT (IPD) DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Parameter No. Typ. Max. Units Conditions Power-Down Current (IPD) (1) – dsPIC33EP32GP50X, dsPIC33EP32MC20X/50X and PIC24EP32GP/MC20X DC60d 30 100 A -40°C 3.3V DC60a 35 100 A +25°C DC60b 150 200 A +85°C DC60c 250 500 A +125°C Power-Down Current (IPD) (1) – dsPIC33EP64GP50X, dsPIC33EP64MC20X/50X and PIC24EP64GP/MC20X DC60d 25 100 A -40°C 3.3V DC60a 30 100 A +25°C DC60b 150 350 A +85°C DC60c 350 800 A +125°C Power-Down Current (IPD) (1) – dsPIC33EP128GP50X, dsPIC33EP128MC20X/50X and PIC24EP128GP/MC20X DC60d 30 100 A -40°C 3.3V DC60a 35 100 A +25°C DC60b 150 350 A +85°C DC60c 550 1000 A +125°C Power-Down Current (IPD) (1) – dsPIC33EP256GP50X, dsPIC33EP256MC20X/50X and PIC24EP256GP/MC20X DC60d 35 100 A -40°C 3.3V DC60a 40 100 A +25°C DC60b 250 450 A +85°C DC60c 1000 1200 A +125°C Power-Down Current (IPD) (1) – dsPIC33EP512GP50X, dsPIC33EP512MC20X/50X and PIC24EP512GP/MC20X DC60d 40 100 A -40°C 3.3V DC60a 45 100 A +25°C DC60b 350 800 A +85°C DC60c 1100 1500 A +125°C Note 1: IPD (Sleep) current is measured as follows: • CPU core is off, oscillator is configured in EC mode and external clock is active; OSC1 is driven with external square wave from rail-to-rail (EC clock overshoot/undershoot < 250 mV required) • CLKO is configured as an I/O input pin in the Configuration Word • All I/O pins are configured as inputs and pulled to VSS • MCLR = VDD, WDT and FSCM are disabled • All peripheral modules are disabled (PMDx bits are all set) • The VREGS bit (RCON<8>) = 0 (i.e., core regulator is set to standby while the device is in Sleep mode) • The VREGSF bit (RCON<11>) = 0 (i.e., Flash regulator is set to standby while the device is in Sleep mode) • JTAG is disabled  2011-2013 Microchip Technology Inc. DS70000657H-page 407 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-9: DC CHARACTERISTICS: WATCHDOG TIMER DELTA CURRENT (IWDT) (1) DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Parameter No. Typ. Max. Units Conditions DC61d 8 — A -40°C 3.3V DC61a 10 — A +25°C DC61b 12 — A +85°C DC61c 13 — A +125°C Note 1: The IWDT current is the additional current consumed when the module is enabled. This current should be added to the base IPD current. All parameters are characterized but not tested during manufacturing. TABLE 30-10: DC CHARACTERISTICS: DOZE CURRENT (IDOZE) DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Parameter No. Typ. Max. Doze Ratio Units Conditions Doze Current (IDOZE) (1) DC73a(2) 35 — 1:2 mA -40°C 3.3V FOSC = 140 MHz DC73g 20 30 1:128 mA DC70a(2) 35 — 1:2 mA +25°C 3.3V FOSC = 140 MHz DC70g 20 30 1:128 mA DC71a(2) 35 — 1:2 mA +85°C 3.3V FOSC = 140 MHz DC71g 20 30 1:128 mA DC72a(2) 28 — 1:2 mA +125°C 3.3V FOSC = 120 MHz DC72g 15 30 1:128 mA Note 1: IDOZE is primarily 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 IDOZE measurements are as follows: • Oscillator is configured in EC mode and external clock is active, OSC1 is driven with external square wave from rail-to-rail (EC clock overshoot/undershoot < 250 mV required) • CLKO is configured as an I/O input pin in the Configuration Word • All I/O pins are configured as inputs and pulled to VSS • MCLR = VDD, WDT and FSCM are disabled • CPU, SRAM, program memory and data memory are operational • No peripheral modules are operating; however, every peripheral is being clocked (all PMDx bits are zeroed) • CPU is executing while(1) statement • JTAG is disabled 2: Parameter is characterized but not tested in manufacturing. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 408  2011-2013 Microchip Technology Inc. TABLE 30-11: DC CHARACTERISTICS: I/O PIN INPUT SPECIFICATIONS DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (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 VIL Input Low Voltage DI10 Any I/O Pin and MCLR VSS — 0.2 VDD V DI18 I/O Pins with SDAx, SCLx VSS — 0.3 VDD V SMBus disabled DI19 I/O Pins with SDAx, SCLx VSS — 0.8 V SMBus enabled VIH Input High Voltage DI20 I/O Pins Not 5V Tolerant 0.8 VDD — VDD V (Note 3) I/O Pins 5V Tolerant and MCLR 0.8 VDD — 5.5 V (Note 3) I/O Pins with SDAx, SCLx 0.8 VDD — 5.5 V SMBus disabled I/O Pins with SDAx, SCLx 2.1 — 5.5 V SMBus enabled ICNPU Change Notification Pull-up Current DI30 150 250 550 A VDD = 3.3V, VPIN = VSS ICNPD Change Notification Pull-Down Current(4) DI31 20 50 100 A VDD = 3.3V, VPIN = VDD Note 1: 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 can be measured at different input voltages. 2: Negative current is defined as current sourced by the pin. 3: See the “Pin Diagrams” section for the 5V tolerant I/O pins. 4: VIL source < (VSS – 0.3). Characterized but not tested. 5: Non-5V tolerant pins VIH source > (VDD + 0.3), 5V tolerant pins VIH source > 5.5V. Characterized but not tested. 6: Digital 5V tolerant pins cannot tolerate any “positive” input injection current from input sources > 5.5V. 7: Non-zero injection currents can affect the ADC results by approximately 4-6 counts. 8: Any number and/or combination of I/O pins not excluded under IICL or IICH conditions are permitted provided the mathematical “absolute instantaneous” sum of the input injection currents from all pins do not exceed the specified limit. Characterized but not tested.  2011-2013 Microchip Technology Inc. DS70000657H-page 409 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X IIL Input Leakage Current(1,2) DI50 I/O Pins 5V Tolerant(3) -1 — +1 A VSS  VPIN  VDD, Pin at high-impedance DI51 I/O Pins Not 5V Tolerant(3) -1 — +1 A VSS  VPIN  VDD, Pin at high-impedance, -40°C  TA  +85°C DI51a I/O Pins Not 5V Tolerant(3) -1 — +1 A Analog pins shared with external reference pins, -40°C  TA  +85°C DI51b I/O Pins Not 5V Tolerant(3) -1 — +1 A VSS  VPIN  VDD, Pin at high-impedance, -40°C  TA  +125°C DI51c I/O Pins Not 5V Tolerant(3) -1 — +1 A Analog pins shared with external reference pins, -40°C  TA  +125°C DI55 MCLR -5 — +5 A VSS VPIN VDD DI56 OSC1 -5 — +5 A VSS VPIN VDD, XT and HS modes TABLE 30-11: DC CHARACTERISTICS: I/O PIN INPUT SPECIFICATIONS (CONTINUED) DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (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 Note 1: 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 can be measured at different input voltages. 2: Negative current is defined as current sourced by the pin. 3: See the “Pin Diagrams” section for the 5V tolerant I/O pins. 4: VIL source < (VSS – 0.3). Characterized but not tested. 5: Non-5V tolerant pins VIH source > (VDD + 0.3), 5V tolerant pins VIH source > 5.5V. Characterized but not tested. 6: Digital 5V tolerant pins cannot tolerate any “positive” input injection current from input sources > 5.5V. 7: Non-zero injection currents can affect the ADC results by approximately 4-6 counts. 8: Any number and/or combination of I/O pins not excluded under IICL or IICH conditions are permitted provided the mathematical “absolute instantaneous” sum of the input injection currents from all pins do not exceed the specified limit. Characterized but not tested. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 410  2011-2013 Microchip Technology Inc. IICL Input Low Injection Current DI60a 0 — -5(4,7) mA All pins except VDD, VSS, AVDD, AVSS, MCLR, VCAP and RB7 IICH Input High Injection Current DI60b 0 — +5(5,6,7) mA All pins except VDD, VSS, AVDD, AVSS, MCLR, VCAP, RB7 and all 5V tolerant pins(6) IICT Total Input Injection Current DI60c (sum of all I/O and control pins) -20(8) — +20(8) mA Absolute instantaneous sum of all ± input injection currents from all I/O pins ( | IICL + | IICH | )  IICT TABLE 30-11: DC CHARACTERISTICS: I/O PIN INPUT SPECIFICATIONS (CONTINUED) DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (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 Note 1: 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 can be measured at different input voltages. 2: Negative current is defined as current sourced by the pin. 3: See the “Pin Diagrams” section for the 5V tolerant I/O pins. 4: VIL source < (VSS – 0.3). Characterized but not tested. 5: Non-5V tolerant pins VIH source > (VDD + 0.3), 5V tolerant pins VIH source > 5.5V. Characterized but not tested. 6: Digital 5V tolerant pins cannot tolerate any “positive” input injection current from input sources > 5.5V. 7: Non-zero injection currents can affect the ADC results by approximately 4-6 counts. 8: Any number and/or combination of I/O pins not excluded under IICL or IICH conditions are permitted provided the mathematical “absolute instantaneous” sum of the input injection currents from all pins do not exceed the specified limit. Characterized but not tested.  2011-2013 Microchip Technology Inc. DS70000657H-page 411 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-12: DC CHARACTERISTICS: I/O PIN OUTPUT SPECIFICATIONS DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic Min. Typ. Max. Units Conditions DO10 VOL Output Low Voltage 4x Sink Driver Pins(2) — — 0.4 V VDD = 3.3V, IOL  6 mA, -40°C  TA  +85°C IOL  5 mA, +85°C  TA  +125°C Output Low Voltage 8x Sink Driver Pins(3) — — 0.4 V VDD = 3.3V, IOL  12 mA, -40°C  TA  +85°C IOL  8 mA, +85°C  TA  +125°C DO20 VOH Output High Voltage 4x Source Driver Pins(2) 2.4 — — V IOH  -10 mA, VDD = 3.3V Output High Voltage 8x Source Driver Pins(3) 2.4 — — V IOH  -15 mA, VDD = 3.3V DO20A VOH1 Output High Voltage 4x Source Driver Pins(2) 1.5(1) — — VIOH  -14 mA, VDD = 3.3V 2.0(1) —— IOH  -12 mA, VDD = 3.3V 3.0(1) —— IOH  -7 mA, VDD = 3.3V Output High Voltage 8x Source Driver Pins(3) 1.5(1) — — VIOH  -22 mA, VDD = 3.3V 2.0(1) —— IOH  -18 mA, VDD = 3.3V 3.0(1) —— IOH  -10 mA, VDD = 3.3V Note 1: Parameters are characterized but not tested. 2: Includes all I/O pins that are not 8x Sink Driver pins (see below). 3: Includes the following pins: For devices with less than 64 pins: RA3, RA4, RA9, RB<7:15> and RC3 For 64-pin devices: RA4, RA9, RB<7:15>, RC3 and RC15 TABLE 30-13: ELECTRICAL CHARACTERISTICS: BOR DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated)(1) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristic Min.(2) Typ. Max. Units Conditions BO10 VBOR BOR Event on VDD Transition High-to-Low 2.65 — 2.95 V VDD (Notes 2 and 3) Note 1: Device is functional at VBORMIN < VDD < VDDMIN, but will have degraded performance. Device functionality is tested, but not characterized. Analog modules (ADC, op amp/comparator and comparator voltage reference) may have degraded performance. 2: Parameters are for design guidance only and are not tested in manufacturing. 3: The VBOR specification is relative to VDD. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 412  2011-2013 Microchip Technology Inc. TABLE 30-14: DC CHARACTERISTICS: PROGRAM MEMORY DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (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.(1) Max. Units Conditions Program Flash Memory D130 EP Cell Endurance 10,000 — — E/W -40C to +125C D131 VPR VDD for Read 3.0 — 3.6 V D132b VPEW VDD for Self-Timed Write 3.0 — 3.6 V D134 TRETD Characteristic Retention 20 — — Year Provided no other specifications are violated, -40C to +125C D135 IDDP Supply Current during Programming(2) — 10 — mA D136 IPEAK Instantaneous Peak Current During Start-up — — 150 mA D137a TPE Page Erase Time 17.7 — 22.9 ms TPE = 146893 FRC cycles, TA = +85°C (See Note 3) D137b TPE Page Erase Time 17.5 — 23.1 ms TPE = 146893 FRC cycles, TA = +125°C (See Note 3) D138a TWW Word Write Cycle Time 41.7 — 53.8 µs TWW = 346 FRC cycles, TA = +85°C (See Note 3) D138b TWW Word Write Cycle Time 41.2 — 54.4 µs TWW = 346 FRC cycles, TA = +125°C (See Note 3) Note 1: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 2: Parameter characterized but not tested in manufacturing. 3: Other conditions: FRC = 7.37 MHz, TUN<5:0> = 011111 (for Minimum), TUN<5:0> = 100000 (for Maximum). This parameter depends on the FRC accuracy (see Table 30-19) and the value of the FRC Oscillator Tuning register (see Register 9-4). For complete details on calculating the Minimum and Maximum time, see Section 5.3 “Programming Operations”.  2011-2013 Microchip Technology Inc. DS70000657H-page 413 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 30.2 AC Characteristics and Timing Parameters This section defines dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/ MC20X AC characteristics and timing parameters. TABLE 30-15: TEMPERATURE AND VOLTAGE SPECIFICATIONS – AC FIGURE 30-1: LOAD CONDITIONS FOR DEVICE TIMING SPECIFICATIONS TABLE 30-16: CAPACITIVE LOADING REQUIREMENTS ON OUTPUT PINS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (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 Section 30.1 “DC Characteristics”. Param No. Symbol Characteristic Min. Typ. Max. Units Conditions DO50 COSCO OSC2 Pin — — 15 pF In XT and HS modes, when external clock is used to drive OSC1 DO56 CIO All I/O Pins and OSC2 — — 50 pF EC mode DO58 CB SCLx, SDAx — — 400 pF In I2C™ mode VDD/2 CL RL Pin Pin VSS VSS CL RL = 464 CL = 50 pF for all pins except OSC2 15 pF for OSC2 output Load Condition 1 – for all pins except OSC2 Load Condition 2 – for OSC2 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 414  2011-2013 Microchip Technology Inc. FIGURE 30-2: EXTERNAL CLOCK TIMING Q1 Q2 Q3 Q4 OSC1 CLKO Q1 Q2 Q3 OS20 OS30 OS30 OS41 OS40 OS31 OS31 Q4 OS25 TABLE 30-17: EXTERNAL CLOCK TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symb Characteristic Min. Typ.(1) Max. Units Conditions OS10 FIN External CLKI Frequency (External clocks allowed only in EC and ECPLL modes) DC — 60 MHz EC Oscillator Crystal Frequency 3.5 10 — — 10 25 MHz MHz XT HS OS20 TOSC TOSC = 1/FOSC 8.33 — DC ns +125ºC TOSC = 1/FOSC 7.14 — DC ns +85ºC OS25 TCY Instruction Cycle Time(2) 16.67 — DC ns +125ºC Instruction Cycle Time(2) 14.28 — DC ns +85ºC OS30 TosL, TosH External Clock in (OSC1) High or Low Time 0.45 x TOSC — 0.55 x TOSC ns EC OS31 TosR, TosF External Clock in (OSC1) Rise or Fall Time — — 20 ns EC OS40 TckR CLKO Rise Time(3,4) — 5.2 — ns OS41 TckF CLKO Fall Time(3,4) — 5.2 — ns OS42 GM External Oscillator Transconductance(4) — 12 — mA/V HS, VDD = 3.3V, TA = +25ºC — 6 — mA/V XT, VDD = 3.3V, TA = +25ºC Note 1: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 2: Instruction cycle period (TCY) equals two 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 “Minimum” values with an external clock applied to the OSC1 pin. When an external clock input is used, the “Maximum” cycle time limit is “DC” (no clock) for all devices. 3: Measurements are taken in EC mode. The CLKO signal is measured on the OSC2 pin. 4: This parameter is characterized, but not tested in manufacturing.  2011-2013 Microchip Technology Inc. DS70000657H-page 415 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-18: PLL CLOCK TIMING SPECIFICATIONS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (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.(1) Max. Units Conditions OS50 FPLLI PLL Voltage Controlled Oscillator (VCO) Input Frequency Range 0.8 — 8.0 MHz ECPLL, XTPLL modes OS51 FVCO On-Chip VCO System Frequency 120 — 340 MHz OS52 TLOCK PLL Start-up Time (Lock Time) 0.9 1.5 3.1 ms OS53 DCLK CLKO Stability (Jitter)(2) -3 0.5 3 % Note 1: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. Parameters are for design guidance only and are not tested. 2: This jitter specification is based on clock cycle-by-clock cycle measurements. To get the effective jitter for individual time bases, or communication clocks used by the application, use the following formula: For example, if FOSC = 120 MHz and the SPIx bit rate = 10 MHz, the effective jitter is as follows: Effective Jitter DCLK FOSC Time Base or Communication Clock --------------------------------------------------------------------------------------- = ------------------------------------------------------------------------------------------- Effective Jitter DCLK 120 10 -------- -------------- DCLK 12 -------------- DCLK 3.464 === -------------- TABLE 30-19: INTERNAL FRC ACCURACY AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Characteristic Min. Typ. Max. Units Conditions Internal FRC Accuracy @ FRC Frequency = 7.37 MHz(1) F20a FRC -1.5 0.5 +1.5 % -40°C  TA -10°C VDD = 3.0-3.6V -1 0.5 +1 % -10°C  TA +85°C VDD = 3.0-3.6V F20b FRC -2 1 +2 % +85°C  TA  +125°C VDD = 3.0-3.6V Note 1: Frequency is calibrated at +25°C and 3.3V. TUNx bits can be used to compensate for temperature drift. TABLE 30-20: INTERNAL LPRC ACCURACY AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Characteristic Min. Typ. Max. Units Conditions LPRC @ 32.768 kHz(1) F21a LPRC -30 — +30 % -40°C  TA  -10°C VDD = 3.0-3.6V -20 — +20 % -10°C  TA  +85°C VDD = 3.0-3.6V F21b LPRC -30 — +30 % +85°C  TA  +125°C VDD = 3.0-3.6V Note 1: The change of LPRC frequency as VDD changes. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 416  2011-2013 Microchip Technology Inc. FIGURE 30-3: I/O TIMING CHARACTERISTICS FIGURE 30-4: BOR AND MASTER CLEAR RESET TIMING CHARACTERISTICS Note: Refer to Figure 30-1 for load conditions. I/O Pin (Input) I/O Pin (Output) DI35 Old Value New Value DI40 DO31 DO32 TABLE 30-21: I/O TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (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.(1) Max. Units Conditions DO31 TIOR Port Output Rise Time — 5 10 ns DO32 TIOF Port Output Fall Time — 5 10 ns DI35 TINP INTx Pin High or Low Time (input) 20 — — ns DI40 TRBP CNx High or Low Time (input) 2 — — TCY Note 1: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. MCLR (SY20) BOR (SY30) TMCLR TBOR Reset Sequence CPU Starts Fetching Code Various Delays (depending on configuration)  2011-2013 Microchip Technology Inc. DS70000657H-page 417 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-22: RESET, WATCHDOG TIMER, OSCILLATOR START-UP TIMER, POWER-UP TIMER TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions SY00 TPU Power-up Period — 400 600 s SY10 TOST Oscillator Start-up Time — 1024 TOSC — —TOSC = OSC1 period SY12 TWDT Watchdog Timer Time-out Period 0.81 0.98 1.22 ms WDTPRE = 0, WDTPOST<3:0> = 0000, using LPRC tolerances indicated in F21 (see Table 30-20) at +85ºC 3.26 3.91 4.88 ms WDTPRE = 1, WDTPOST<3:0> = 0000, using LPRC tolerances indicated in F21 (see Table 30-20) at +85ºC SY13 TIOZ I/O High-Impedance from MCLR Low or Watchdog Timer Reset 0.68 0.72 1.2 s SY20 TMCLR MCLR Pulse Width (low) 2 — — s SY30 TBOR BOR Pulse Width (low) 1 — — s SY35 TFSCM Fail-Safe Clock Monitor Delay — 500 900 s -40°C to +85°C SY36 TVREG Voltage Regulator Standby-to-Active mode Transition Time — — 30 s SY37 TOSCDFRC FRC Oscillator Start-up Delay 46 48 54 s SY38 TOSCDLPRC LPRC Oscillator Start-up Delay — — 70 s Note 1: These parameters are characterized but not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 418  2011-2013 Microchip Technology Inc. FIGURE 30-5: TIMER1-TIMER5 EXTERNAL CLOCK TIMING CHARACTERISTICS Note: Refer to Figure 30-1 for load conditions. TMRx OS60 TxCK Tx10 Tx11 Tx15 Tx20 TABLE 30-23: TIMER1 EXTERNAL CLOCK TIMING REQUIREMENTS(1) AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristic(2) Min. Typ. Max. Units Conditions TA10 TTXH T1CK High Time Synchronous mode Greater of: 20 or (TCY + 20)/N — — ns Must also meet Parameter TA15, N = prescaler value (1, 8, 64, 256) Asynchronous 35 — — ns TA11 TTXL T1CK Low Time Synchronous mode Greater of: 20 or (TCY + 20)/N — — ns Must also meet Parameter TA15, N = prescaler value (1, 8, 64, 256) Asynchronous 10 — — ns TA15 TTXP T1CK Input Period Synchronous mode Greater of: 40 or (2 TCY + 40)/N — — ns N = prescale value (1, 8, 64, 256) OS60 Ft1 T1CK Oscillator Input Frequency Range (oscillator enabled by setting bit, TCS (T1CON<1>)) DC — 50 kHz TA20 TCKEXTMRL Delay from External T1CK Clock Edge to Timer Increment 0.75 TCY + 40 — 1.75 TCY + 40 ns Note 1: Timer1 is a Type A. 2: These parameters are characterized, but are not tested in manufacturing.  2011-2013 Microchip Technology Inc. DS70000657H-page 419 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-24: TIMER2 AND TIMER4 (TYPE B TIMER) EXTERNAL CLOCK TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristic(1) Min. Typ. Max. Units Conditions TB10 TtxH TxCK High Time Synchronous mode Greater of: 20 or (TCY + 20)/N — — ns Must also meet Parameter TB15, N = prescale value (1, 8, 64, 256) TB11 TtxL TxCK Low Time Synchronous mode Greater of: 20 or (TCY + 20)/N — — ns Must also meet Parameter TB15, N = prescale value (1, 8, 64, 256) TB15 TtxP TxCK Input Period Synchronous mode Greater of: 40 or (2 TCY + 40)/N — — ns N = prescale value (1, 8, 64, 256) TB20 TCKEXTMRL Delay from External TxCK Clock Edge to Timer Increment 0.75 TCY + 40 — 1.75 TCY + 40 ns Note 1: These parameters are characterized, but are not tested in manufacturing. TABLE 30-25: TIMER3 AND TIMER5 (TYPE C TIMER) EXTERNAL CLOCK TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristic(1) Min. Typ. Max. Units Conditions TC10 TtxH TxCK High Time Synchronous TCY + 20 — — ns Must also meet Parameter TC15 TC11 TtxL TxCK Low Time Synchronous TCY + 20 — — ns Must also meet Parameter TC15 TC15 TtxP TxCK Input Period Synchronous, with prescaler 2 TCY + 40 — — ns N = prescale value (1, 8, 64, 256) TC20 TCKEXTMRL Delay from External TxCK Clock Edge to Timer Increment 0.75 TCY + 40 — 1.75 TCY + 40 ns Note 1: These parameters are characterized, but are not tested in manufacturing. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 420  2011-2013 Microchip Technology Inc. FIGURE 30-6: INPUT CAPTURE x (ICx) TIMING CHARACTERISTICS ICx IC10 IC11 IC15 Note: Refer to Figure 30-1 for load conditions. TABLE 30-26: INPUT CAPTURE x MODULE TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. No. Symbol Characteristics(1) Min. Max. Units Conditions IC10 TCCL ICx Input Low Time Greater of 12.5 + 25 or (0.5 TCY/N) + 25 — ns Must also meet Parameter IC15 N = prescale value (1, 4, 16) IC11 TCCH ICx Input High Time Greater of 12.5 + 25 or (0.5 TCY/N) + 25 — ns Must also meet Parameter IC15 IC15 TCCP ICx Input Period Greater of 25 + 50 or (1 TCY/N) + 50 — ns Note 1: These parameters are characterized, but not tested in manufacturing.  2011-2013 Microchip Technology Inc. DS70000657H-page 421 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 30-7: OUTPUT COMPARE x MODULE (OCx) TIMING CHARACTERISTICS FIGURE 30-8: OCx/PWMx MODULE TIMING CHARACTERISTICS OCx OC11 OC10 (Output Compare x Note: Refer to Figure 30-1 for load conditions. or PWMx Mode) TABLE 30-27: OUTPUT COMPARE x MODULE TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristic(1) Min. Typ. Max. Units Conditions OC10 TccF OCx Output Fall Time — — — ns See Parameter DO32 OC11 TccR OCx Output Rise Time — — — ns See Parameter DO31 Note 1: These parameters are characterized but not tested in manufacturing. OCFA OCx OC20 OC15 TABLE 30-28: OCx/PWMx MODE TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristic(1) Min. Typ. Max. Units Conditions OC15 TFD Fault Input to PWMx I/O Change — —TCY + 20 ns OC20 TFLT Fault Input Pulse Width TCY + 20 — — ns Note 1: These parameters are characterized but not tested in manufacturing. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 422  2011-2013 Microchip Technology Inc. FIGURE 30-9: HIGH-SPEED PWMx MODULE FAULT TIMING CHARACTERISTICS (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X DEVICES ONLY) FIGURE 30-10: HIGH-SPEED PWMx MODULE TIMING CHARACTERISTICS (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X DEVICES ONLY) TABLE 30-29: HIGH-SPEED PWMx MODULE TIMING REQUIREMENTS (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X DEVICES ONLY) AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristic(1) Min. Typ. Max. Units Conditions MP10 TFPWM PWMx Output Fall Time — — — ns See Parameter DO32 MP11 TRPWM PWMx Output Rise Time — — — ns See Parameter DO31 MP20 TFD Fault Input  to PWMx I/O Change — — 15 ns MP30 TFH Fault Input Pulse Width 15 — — ns Note 1: These parameters are characterized but not tested in manufacturing. Fault Input PWMx MP30 MP20 (active-low) PWMx MP11 MP10 Note: Refer to Figure 30-1 for load conditions.  2011-2013 Microchip Technology Inc. DS70000657H-page 423 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 30-11: TIMERQ (QEI MODULE) EXTERNAL CLOCK TIMING CHARACTERISTICS (dsPIC33EPXXXMC20X/50X AND PIC24EPXXXMC20X DEVICES ONLY) QEB POSCNT TQ10 TQ11 TQ15 TQ20 TABLE 30-30: QEI MODULE EXTERNAL CLOCK TIMING REQUIREMENTS (dsPIC33EPXXXMC20X/50X AND PIC24EPXXXMC20X DEVICES ONLY) AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristic(1) Min. Typ. Max. Units Conditions TQ10 TtQH TQCK High Time Synchronous, with prescaler Greater of 12.5 + 25 or (0.5 TCY/N) + 25 — — ns Must also meet Parameter TQ15 TQ11 TtQL TQCK Low Time Synchronous, with prescaler Greater of 12.5 + 25 or (0.5 TCY/N) + 25 — — ns Must also meet Parameter TQ15 TQ15 TtQP TQCP Input Period Synchronous, with prescaler Greater of 25 + 50 or (1 TCY/N) + 50 — — ns TQ20 TCKEXTMRL Delay from External TQCK Clock Edge to Timer Increment — 1TCY — Note 1: These parameters are characterized but not tested in manufacturing. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 424  2011-2013 Microchip Technology Inc. FIGURE 30-12: QEA/QEB INPUT CHARACTERISTICS (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X DEVICES ONLY) QEA (input) QEB (input) TQ35 TQ30 TQ41 TQ40 TQ35 QEB Internal TQ36 TQ31 TQ31 TQ30 TABLE 30-31: QUADRATURE DECODER TIMING REQUIREMENTS (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X DEVICES ONLY) AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristic(1) Typ.(2) Max. Units Conditions TQ30 TQUL Quadrature Input Low Time 6 TCY — ns TQ31 TQUH Quadrature Input High Time 6 TCY — ns TQ35 TQUIN Quadrature Input Period 12 TCY — ns TQ36 TQUP Quadrature Phase Period 3 TCY — ns TQ40 TQUFL Filter Time to Recognize Low, with Digital Filter 3 * N * TCY — ns N = 1, 2, 4, 16, 32, 64, 128 and 256 (Note 3) TQ41 TQUFH Filter Time to Recognize High, with Digital Filter 3 * N * TCY — ns N = 1, 2, 4, 16, 32, 64, 128 and 256 (Note 3) Note 1: These parameters are characterized but not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. Parameters are for design guidance only and are not tested. 3: N = Index Channel Digital Filter Clock Divide Select bits. Refer to “Quadrature Encoder Interface (QEI)” (DS70601) in the “dsPIC33/PIC24 Family Reference Manual”. Please see the Microchip web site for the latest family reference manual sections.  2011-2013 Microchip Technology Inc. DS70000657H-page 425 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 30-13: QEI MODULE INDEX PULSE TIMING CHARACTERISTICS (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X DEVICES ONLY) QEA (input) QEB (input) Ungated Index Index Internal Position Counter Reset TQ51 TQ50 TQ55 TABLE 30-32: QEI INDEX PULSE TIMING REQUIREMENTS (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X DEVICES ONLY) AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristic(1) Min. Max. Units Conditions TQ50 TqiL Filter Time to Recognize Low, with Digital Filter 3 * N * TCY — ns N = 1, 2, 4, 16, 32, 64, 128 and 256 (Note 2) TQ51 TqiH Filter Time to Recognize High, with Digital Filter 3 * N * TCY — ns N = 1, 2, 4, 16, 32, 64, 128 and 256 (Note 2) TQ55 Tqidxr Index Pulse Recognized to Position Counter Reset (ungated index) 3 TCY — ns Note 1: These parameters are characterized but not tested in manufacturing. 2: Alignment of index pulses to QEA and QEB is shown for position counter Reset timing only. Shown for forward direction only (QEA leads QEB). Same timing applies for reverse direction (QEA lags QEB) but index pulse recognition occurs on the falling edge. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 426  2011-2013 Microchip Technology Inc. TABLE 30-33: SPI2 MAXIMUM DATA/CLOCK RATE SUMMARY FIGURE 30-14: SPI2 MASTER MODE (HALF-DUPLEX, TRANSMIT ONLY, CKE = 0) TIMING CHARACTERISTICS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Maximum Data Rate Master Transmit Only (Half-Duplex) Master Transmit/Receive (Full-Duplex) Slave Transmit/Receive (Full-Duplex) CKE CKP SMP 15 MHz Table 30-33 — — 0,1 0,1 0,1 9 MHz — Table 30-34 — 1 0,1 1 9 MHz — Table 30-35 — 0 0,1 1 15 MHz — — Table 30-36 100 11 MHz — — Table 30-37 110 15 MHz — — Table 30-38 010 11 MHz — — Table 30-39 000 SCK2 (CKP = 0) SCK2 (CKP = 1) SDO2 SP10 SP35 SP20 SP21 SP21 SP20 MSb LSb Bit 14 - - - - - -1 SP30, SP31 SP30, SP31 Note: Refer to Figure 30-1 for load conditions.  2011-2013 Microchip Technology Inc. DS70000657H-page 427 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 30-15: SPI2 MASTER MODE (HALF-DUPLEX, TRANSMIT ONLY, CKE = 1) TIMING CHARACTERISTICS TABLE 30-34: SPI2 MASTER MODE (HALF-DUPLEX, TRANSMIT ONLY) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions SP10 FscP Maximum SCK2 Frequency — — 15 MHz (Note 3) SP20 TscF SCK2 Output Fall Time — — — ns See Parameter DO32 (Note 4) SP21 TscR SCK2 Output Rise Time — — — ns See Parameter DO31 (Note 4) SP30 TdoF SDO2 Data Output Fall Time — — — ns See Parameter DO32 (Note 4) SP31 TdoR SDO2 Data Output Rise Time — — — ns See Parameter DO31 (Note 4) SP35 TscH2doV, TscL2doV SDO2 Data Output Valid after SCK2 Edge — 6 20 ns SP36 TdiV2scH, TdiV2scL SDO2 Data Output Setup to First SCK2 Edge 30 — — ns Note 1: These parameters are characterized, but are not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 3: The minimum clock period for SCK2 is 66.7 ns. Therefore, the clock generated in Master mode must not violate this specification. 4: Assumes 50 pF load on all SPI2 pins. SCK2 (CKP = 0) SCK2 (CKP = 1) SDO2 SP35 SP20 SP21 SP21 SP20 MSb LSb Bit 14 - - - - - -1 SP30, SP31 Note: Refer to Figure 30-1 for load conditions. SP36 SP10 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 428  2011-2013 Microchip Technology Inc. FIGURE 30-16: SPI2 MASTER MODE (FULL-DUPLEX, CKE = 1, CKP = x, SMP = 1) TIMING CHARACTERISTICS TABLE 30-35: SPI2 MASTER MODE (FULL-DUPLEX, CKE = 1, CKP = x, SMP = 1) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions SP10 FscP Maximum SCK2 Frequency — — 9 MHz (Note 3) SP20 TscF SCK2 Output Fall Time — — — ns See Parameter DO32 (Note 4) SP21 TscR SCK2 Output Rise Time — — — ns See Parameter DO31 (Note 4) SP30 TdoF SDO2 Data Output Fall Time — — — ns See Parameter DO32 (Note 4) SP31 TdoR SDO2 Data Output Rise Time — — — ns See Parameter DO31 (Note 4) SP35 TscH2doV, TscL2doV SDO2 Data Output Valid after SCK2 Edge — 6 20 ns SP36 TdoV2sc, TdoV2scL SDO2 Data Output Setup to First SCK2 Edge 30 — — ns SP40 TdiV2scH, TdiV2scL Setup Time of SDI2 Data Input to SCK2 Edge 30 — — ns SP41 TscH2diL, TscL2diL Hold Time of SDI2 Data Input to SCK2 Edge 30 — — ns Note 1: These parameters are characterized, but are not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 3: The minimum clock period for SCK2 is 111 ns. The clock generated in Master mode must not violate this specification. 4: Assumes 50 pF load on all SPI2 pins. SCK2 (CKP = 0) SCK2 (CKP = 1) SDO2 SP35 SP20 SP21 SP21 SP20 MSb LSb Bit 14 - - - - - -1 SP30, SP31 Note: Refer to Figure 30-1 for load conditions. SP36 SP41 SDI2 Bit 14 - - - -1 LSb In SP40 SP10 MSb In  2011-2013 Microchip Technology Inc. DS70000657H-page 429 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 30-17: SPI2 MASTER MODE (FULL-DUPLEX, CKE = 0, CKP = x, SMP = 1) TIMING CHARACTERISTICS TABLE 30-36: SPI2 MASTER MODE (FULL-DUPLEX, CKE = 0, CKP = x, SMP = 1) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions SP10 FscP Maximum SCK2 Frequency — — 9 MHz -40ºC to +125ºC (Note 3) SP20 TscF SCK2 Output Fall Time — — — ns See Parameter DO32 (Note 4) SP21 TscR SCK2 Output Rise Time — — — ns See Parameter DO31 (Note 4) SP30 TdoF SDO2 Data Output Fall Time — — — ns See Parameter DO32 (Note 4) SP31 TdoR SDO2 Data Output Rise Time — — — ns See Parameter DO31 (Note 4) SP35 TscH2doV, TscL2doV SDO2 Data Output Valid after SCK2 Edge — 6 20 ns SP36 TdoV2scH, TdoV2scL SDO2 Data Output Setup to First SCK2 Edge 30 — — ns SP40 TdiV2scH, TdiV2scL Setup Time of SDI2 Data Input to SCK2 Edge 30 — — ns SP41 TscH2diL, TscL2diL Hold Time of SDI2 Data Input to SCK2 Edge 30 — — ns Note 1: These parameters are characterized, but are not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 3: The minimum clock period for SCK2 is 111 ns. The clock generated in Master mode must not violate this specification. 4: Assumes 50 pF load on all SPI2 pins. SCK2 (CKP = 0) SCK2 (CKP = 1) SDO2 SDI2 SP40 SP41 SP35 SP20 SP21 SP21 SP20 MSb LSb Bit 14 - - - - - -1 Bit 14 - - - -1 LSb In SP30, SP31 SP30, SP31 Note: Refer to Figure 30-1 for load conditions. SP36 SP10 MSb In dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 430  2011-2013 Microchip Technology Inc. FIGURE 30-18: SPI2 SLAVE MODE (FULL-DUPLEX, CKE = 1, CKP = 0, SMP = 0) TIMING CHARACTERISTICS SS2 SCK2 (CKP = 0) SCK2 (CKP = 1) SDO2 SP60 SDI2 SP30, SP31 MSb Bit 14 - - - - - -1 LSb SP51 Bit 14 - - - -1 LSb In SP35 SP52 SP72 SP73 SP73 SP72 SP40 SP41 Note: Refer to Figure 30-1 for load conditions. SP36 SP50 SP70 MSb In  2011-2013 Microchip Technology Inc. DS70000657H-page 431 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-37: SPI2 SLAVE MODE (FULL-DUPLEX, CKE = 1, CKP = 0, SMP = 0) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions SP70 FscP Maximum SCK2 Input Frequency — — Lesser of FP or 15 MHz (Note 3) SP72 TscF SCK2 Input Fall Time — — — ns See Parameter DO32 (Note 4) SP73 TscR SCK2 Input Rise Time — — — ns See Parameter DO31 (Note 4) SP30 TdoF SDO2 Data Output Fall Time — — — ns See Parameter DO32 (Note 4) SP31 TdoR SDO2 Data Output Rise Time — — — ns See Parameter DO31 (Note 4) SP35 TscH2doV, TscL2doV SDO2 Data Output Valid after SCK2 Edge — 6 20 ns SP36 TdoV2scH, TdoV2scL SDO2 Data Output Setup to First SCK2 Edge 30 — — ns SP40 TdiV2scH, TdiV2scL Setup Time of SDI2 Data Input to SCK2 Edge 30 — — ns SP41 TscH2diL, TscL2diL Hold Time of SDI2 Data Input to SCK2 Edge 30 — — ns SP50 TssL2scH, TssL2scL SS2  to SCK2  or SCK2  Input 120 — — ns SP51 TssH2doZ SS2  to SDO2 Output High-Impedance 10 — 50 ns (Note 4) SP52 TscH2ssH TscL2ssH SS2 after SCK2 Edge 1.5 TCY + 40 — — ns (Note 4) SP60 TssL2doV SDO2 Data Output Valid after SS2 Edge — — 50 ns Note 1: These parameters are characterized, but are not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 3: The minimum clock period for SCK2 is 66.7 ns. Therefore, the SCK2 clock generated by the master must not violate this specification. 4: Assumes 50 pF load on all SPI2 pins. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 432  2011-2013 Microchip Technology Inc. FIGURE 30-19: SPI2 SLAVE MODE (FULL-DUPLEX, CKE = 1, CKP = 1, SMP = 0) TIMING CHARACTERISTICS SS2 SCK2 (CKP = 0) SCK2 (CKP = 1) SDO2 SP60 SDI2 SP30, SP31 MSb Bit 14 - - - - - -1 LSb SP51 Bit 14 - - - -1 LSb In SP35 SP52 SP72 SP73 SP70 SP73 SP72 SP40 SP41 Note: Refer to Figure 30-1 for load conditions. SP36 SP50 MSb In  2011-2013 Microchip Technology Inc. DS70000657H-page 433 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-38: SPI2 SLAVE MODE (FULL-DUPLEX, CKE = 1, CKP = 1, SMP = 0) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions SP70 FscP Maximum SCK2 Input Frequency — — Lesser of FP or 11 MHz (Note 3) SP72 TscF SCK2 Input Fall Time — — — ns See Parameter DO32 (Note 4) SP73 TscR SCK2 Input Rise Time — — — ns See Parameter DO31 (Note 4) SP30 TdoF SDO2 Data Output Fall Time — — — ns See Parameter DO32 (Note 4) SP31 TdoR SDO2 Data Output Rise Time — — — ns See Parameter DO31 (Note 4) SP35 TscH2doV, TscL2doV SDO2 Data Output Valid after SCK2 Edge — 6 20 ns SP36 TdoV2scH, TdoV2scL SDO2 Data Output Setup to First SCK2 Edge 30 — — ns SP40 TdiV2scH, TdiV2scL Setup Time of SDI2 Data Input to SCK2 Edge 30 — — ns SP41 TscH2diL, TscL2diL Hold Time of SDI2 Data Input to SCK2 Edge 30 — — ns SP50 TssL2scH, TssL2scL SS2  to SCK2  or SCK2  Input 120 — — ns SP51 TssH2doZ SS2  to SDO2 Output High-Impedance 10 — 50 ns (Note 4) SP52 TscH2ssH TscL2ssH SS2 after SCK2 Edge 1.5 TCY + 40 — — ns (Note 4) SP60 TssL2doV SDO2 Data Output Valid after SS2 Edge — — 50 ns Note 1: These parameters are characterized, but are not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 3: The minimum clock period for SCK2 is 91 ns. Therefore, the SCK2 clock generated by the master must not violate this specification. 4: Assumes 50 pF load on all SPI2 pins. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 434  2011-2013 Microchip Technology Inc. FIGURE 30-20: SPI2 SLAVE MODE (FULL-DUPLEX, CKE = 0, CKP = 1, SMP = 0) TIMING CHARACTERISTICS SS2 SCK2 (CKP = 0) SCK2 (CKP = 1) SDO2 SP50 SP40 SP41 SP30, SP31 SP51 SP35 MSb LSb Bit 14 - - - - - -1 Bit 14 - - - -1 LSb In SP52 SP72 SP73 SP73 SP72 Note: Refer to Figure 30-1 for load conditions. SDI2 MSb In SP70 SP36  2011-2013 Microchip Technology Inc. DS70000657H-page 435 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-39: SPI2 SLAVE MODE (FULL-DUPLEX, CKE = 0, CKP = 1, SMP = 0) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions SP70 FscP Maximum SCK2 Input Frequency — — 15 MHz (Note 3) SP72 TscF SCK2 Input Fall Time — — — ns See Parameter DO32 (Note 4) SP73 TscR SCK2 Input Rise Time — — — ns See Parameter DO31 (Note 4) SP30 TdoF SDO2 Data Output Fall Time — — — ns See Parameter DO32 (Note 4) SP31 TdoR SDO2 Data Output Rise Time — — — ns See Parameter DO31 (Note 4) SP35 TscH2doV, TscL2doV SDO2 Data Output Valid after SCK2 Edge — 6 20 ns SP36 TdoV2scH, TdoV2scL SDO2 Data Output Setup to First SCK2 Edge 30 — — ns SP40 TdiV2scH, TdiV2scL Setup Time of SDI2 Data Input to SCK2 Edge 30 — — ns SP41 TscH2diL, TscL2diL Hold Time of SDI2 Data Input to SCK2 Edge 30 — — ns SP50 TssL2scH, TssL2scL SS2  to SCK2  or SCK2  Input 120 — — ns SP51 TssH2doZ SS2  to SDO2 Output High-Impedance 10 — 50 ns (Note 4) SP52 TscH2ssH TscL2ssH SS2 after SCK2 Edge 1.5 TCY + 40 — — ns (Note 4) Note 1: These parameters are characterized, but are not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 3: The minimum clock period for SCK2 is 66.7 ns. Therefore, the SCK2 clock generated by the master must not violate this specification. 4: Assumes 50 pF load on all SPI2 pins. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 436  2011-2013 Microchip Technology Inc. FIGURE 30-21: SPI2 SLAVE MODE (FULL-DUPLEX, CKE = 0, CKP = 0, SMP = 0) TIMING CHARACTERISTICS SS2 SCK2 (CKP = 0) SCK2 (CKP = 1) SDO2 SP50 SP40 SP41 SP30, SP31 SP51 SP35 MSb LSb Bit 14 - - - - - -1 Bit 14 - - - -1 LSb In SP52 SP72 SP73 SP73 SP72 Note: Refer to Figure 30-1 for load conditions. SDI2 SP36 MSb In SP70  2011-2013 Microchip Technology Inc. DS70000657H-page 437 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-40: SPI2 SLAVE MODE (FULL-DUPLEX, CKE = 0, CKP = 0, SMP = 0) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions SP70 FscP Maximum SCK2 Input Frequency — — 11 MHz (Note 3) SP72 TscF SCK2 Input Fall Time — — — ns See Parameter DO32 (Note 4) SP73 TscR SCK2 Input Rise Time — — — ns See Parameter DO31 (Note 4) SP30 TdoF SDO2 Data Output Fall Time — — — ns See Parameter DO31 (Note 4) SP31 TdoR SDO2 Data Output Rise Time — — — ns See Parameter DO31 (Note 4) SP35 TscH2doV, TscL2doV SDO2 Data Output Valid after SCK2 Edge — 6 20 ns SP36 TdoV2scH, TdoV2scL SDO2 Data Output Setup to First SCK2 Edge 30 — — ns SP40 TdiV2scH, TdiV2scL Setup Time of SDI2 Data Input to SCK2 Edge 30 — — ns SP41 TscH2diL, TscL2diL Hold Time of SDI2 Data Input to SCK2 Edge 30 — — ns SP50 TssL2scH, TssL2scL SS2  to SCK2  or SCK2  Input 120 — — ns SP51 TssH2doZ SS2  to SDO2 Output High-Impedance 10 — 50 ns (Note 4) SP52 TscH2ssH TscL2ssH SS2 after SCK2 Edge 1.5 TCY + 40 — — ns (Note 4) Note 1: These parameters are characterized, but are not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 3: The minimum clock period for SCK2 is 91 ns. Therefore, the SCK2 clock generated by the master must not violate this specification. 4: Assumes 50 pF load on all SPI2 pins. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 438  2011-2013 Microchip Technology Inc. TABLE 30-41: SPI1 MAXIMUM DATA/CLOCK RATE SUMMARY FIGURE 30-22: SPI1 MASTER MODE (HALF-DUPLEX, TRANSMIT ONLY, CKE = 0) TIMING CHARACTERISTICS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Maximum Data Rate Master Transmit Only (Half-Duplex) Master Transmit/Receive (Full-Duplex) Slave Transmit/Receive (Full-Duplex) CKE CKP SMP 15 MHz Table 30-42 — — 0,1 0,1 0,1 10 MHz — Table 30-43 — 1 0,1 1 10 MHz — Table 30-44 — 0 0,1 1 15 MHz — — Table 30-45 100 11 MHz — — Table 30-46 110 15 MHz — — Table 30-47 010 11 MHz — — Table 30-48 000 SCK1 (CKP = 0) SCK1 (CKP = 1) SDO1 SP10 SP35 SP20 SP21 SP21 SP20 MSb LSb Bit 14 - - - - - -1 SP30, SP31 SP30, SP31 Note: Refer to Figure 30-1 for load conditions.  2011-2013 Microchip Technology Inc. DS70000657H-page 439 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 30-23: SPI1 MASTER MODE (HALF-DUPLEX, TRANSMIT ONLY, CKE = 1) TIMING CHARACTERISTICS TABLE 30-42: SPI1 MASTER MODE (HALF-DUPLEX, TRANSMIT ONLY) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions SP10 FscP Maximum SCK1 Frequency — — 15 MHz (Note 3) SP20 TscF SCK1 Output Fall Time — — — ns See Parameter DO32 (Note 4) SP21 TscR SCK1 Output Rise Time — — — ns See Parameter DO31 (Note 4) SP30 TdoF SDO1 Data Output Fall Time — — — ns See Parameter DO32 (Note 4) SP31 TdoR SDO1 Data Output Rise Time — — — ns See Parameter DO31 (Note 4) SP35 TscH2doV, TscL2doV SDO1 Data Output Valid after SCK1 Edge — 6 20 ns SP36 TdiV2scH, TdiV2scL SDO1 Data Output Setup to First SCK1 Edge 30 — — ns Note 1: These parameters are characterized, but are not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 3: The minimum clock period for SCK1 is 66.7 ns. Therefore, the clock generated in Master mode must not violate this specification. 4: Assumes 50 pF load on all SPI1 pins. SCK1 (CKP = 0) SCK1 (CKP = 1) SDO1 SP35 SP20 SP21 SP21 SP20 MSb LSb Bit 14 - - - - - -1 SP30, SP31 Note: Refer to Figure 30-1 for load conditions. SP36 SP10 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 440  2011-2013 Microchip Technology Inc. FIGURE 30-24: SPI1 MASTER MODE (FULL-DUPLEX, CKE = 1, CKP = x, SMP = 1) TIMING CHARACTERISTICS TABLE 30-43: SPI1 MASTER MODE (FULL-DUPLEX, CKE = 1, CKP = x, SMP = 1) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions SP10 FscP Maximum SCK1 Frequency — — 10 MHz (Note 3) SP20 TscF SCK1 Output Fall Time — — — ns See Parameter DO32 (Note 4) SP21 TscR SCK1 Output Rise Time — — — ns See Parameter DO31 (Note 4) SP30 TdoF SDO1 Data Output Fall Time — — — ns See Parameter DO32 (Note 4) SP31 TdoR SDO1 Data Output Rise Time — — — ns See Parameter DO31 (Note 4) SP35 TscH2doV, TscL2doV SDO1 Data Output Valid after SCK1 Edge — 6 20 ns SP36 TdoV2sc, TdoV2scL SDO1 Data Output Setup to First SCK1 Edge 30 — — ns SP40 TdiV2scH, TdiV2scL Setup Time of SDI1 Data Input to SCK1 Edge 30 — — ns SP41 TscH2diL, TscL2diL Hold Time of SDI1 Data Input to SCK1 Edge 30 — — ns Note 1: These parameters are characterized, but are not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 3: The minimum clock period for SCK1 is 100 ns. The clock generated in Master mode must not violate this specification. 4: Assumes 50 pF load on all SPI1 pins. SCK1 (CKP = 0) SCK1 (CKP = 1) SDO1 SP35 SP20 SP21 SP21 SP20 MSb LSb Bit 14 - - - - - -1 SP30, SP31 Note: Refer to Figure 30-1 for load conditions. SP36 SP41 SDI1 Bit 14 - - - -1 LSb In SP40 MSb In SP10  2011-2013 Microchip Technology Inc. DS70000657H-page 441 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 30-25: SPI1 MASTER MODE (FULL-DUPLEX, CKE = 0, CKP = x, SMP = 1) TIMING CHARACTERISTICS TABLE 30-44: SPI1 MASTER MODE (FULL-DUPLEX, CKE = 0, CKP = x, SMP = 1) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions SP10 FscP Maximum SCK1 Frequency — — 10 MHz -40ºC to +125ºC (Note 3) SP20 TscF SCK1 Output Fall Time — — — ns See Parameter DO32 (Note 4) SP21 TscR SCK1 Output Rise Time — — — ns See Parameter DO31 (Note 4) SP30 TdoF SDO1 Data Output Fall Time — — — ns See Parameter DO32 (Note 4) SP31 TdoR SDO1 Data Output Rise Time — — — ns See Parameter DO31 (Note 4) SP35 TscH2doV, TscL2doV SDO1 Data Output Valid after SCK1 Edge — 6 20 ns SP36 TdoV2scH, TdoV2scL SDO1 Data Output Setup to First SCK1 Edge 30 — — ns SP40 TdiV2scH, TdiV2scL Setup Time of SDI1 Data Input to SCK1 Edge 30 — — ns SP41 TscH2diL, TscL2diL Hold Time of SDI1 Data Input to SCK1 Edge 30 — — ns Note 1: These parameters are characterized, but are not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 3: The minimum clock period for SCK1 is 100 ns. The clock generated in Master mode must not violate this specification. 4: Assumes 50 pF load on all SPI1 pins. SCK1 (CKP = 0) SCK1 (CKP = 1) SDO1 SDI1 SP40 SP41 SP35 SP20 SP21 SP21 SP20 MSb LSb Bit 14 - - - - - -1 Bit 14 - - - -1 LSb In SP30, SP31 SP30, SP31 Note: Refer to Figure 30-1 for load conditions. SP36 MSb In SP10 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 442  2011-2013 Microchip Technology Inc. FIGURE 30-26: SPI1 SLAVE MODE (FULL-DUPLEX, CKE = 1, CKP = 0, SMP = 0) TIMING CHARACTERISTICS SS1 SCK1 (CKP = 0) SCK1 (CKP = 1) SDO1 SP60 SDI1 SP30, SP31 MSb Bit 14 - - - - - -1 LSb SP51 Bit 14 - - - -1 LSb In SP52 SP72 SP73 SP73 SP72 SP40 SP41 Note: Refer to Figure 30-1 for load conditions. SP36 SP50 SP35 SP70 MSb In  2011-2013 Microchip Technology Inc. DS70000657H-page 443 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-45: SPI1 SLAVE MODE (FULL-DUPLEX, CKE = 1, CKP = 0, SMP = 0) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions SP70 FscP Maximum SCK1 Input Frequency — — Lesser of FP or 15 MHz (Note 3) SP72 TscF SCK1 Input Fall Time — — — ns See Parameter DO32 (Note 4) SP73 TscR SCK1 Input Rise Time — — — ns See Parameter DO31 (Note 4) SP30 TdoF SDO1 Data Output Fall Time — — — ns See Parameter DO32 (Note 4) SP31 TdoR SDO1 Data Output Rise Time — — — ns See Parameter DO31 (Note 4) SP35 TscH2doV, TscL2doV SDO1 Data Output Valid after SCK1 Edge — 6 20 ns SP36 TdoV2scH, TdoV2scL SDO1 Data Output Setup to First SCK1 Edge 30 — — ns SP40 TdiV2scH, TdiV2scL Setup Time of SDI1 Data Input to SCK1 Edge 30 — — ns SP41 TscH2diL, TscL2diL Hold Time of SDI1 Data Input to SCK1 Edge 30 — — ns SP50 TssL2scH, TssL2scL SS1  to SCK1  or SCK1  Input 120 — — ns SP51 TssH2doZ SS1  to SDO1 Output High-Impedance 10 — 50 ns (Note 4) SP52 TscH2ssH TscL2ssH SS1 after SCK1 Edge 1.5 TCY + 40 — — ns (Note 4) SP60 TssL2doV SDO1 Data Output Valid after SS1 Edge — — 50 ns Note 1: These parameters are characterized, but are not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 3: The minimum clock period for SCK1 is 66.7 ns. Therefore, the SCK1 clock generated by the master must not violate this specification. 4: Assumes 50 pF load on all SPI1 pins. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 444  2011-2013 Microchip Technology Inc. FIGURE 30-27: SPI1 SLAVE MODE (FULL-DUPLEX, CKE = 1, CKP = 1, SMP = 0) TIMING CHARACTERISTICS SS1 SCK1 (CKP = 0) SCK1 (CKP = 1) SDO1 SP60 SDI1 SP30, SP31 MSb Bit 14 - - - - - -1 LSb SP51 Bit 14 - - - -1 LSb In SP52 SP72 SP73 SP70 SP73 SP72 SP40 SP41 Note: Refer to Figure 30-1 for load conditions. SP36 SP50 SP35 MSb In  2011-2013 Microchip Technology Inc. DS70000657H-page 445 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-46: SPI1 SLAVE MODE (FULL-DUPLEX, CKE = 1, CKP = 1, SMP = 0) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions SP70 FscP Maximum SCK1 Input Frequency — — Lesser of FP or 11 MHz (Note 3) SP72 TscF SCK1 Input Fall Time — — — ns See Parameter DO32 (Note 4) SP73 TscR SCK1 Input Rise Time — — — ns See Parameter DO31 (Note 4) SP30 TdoF SDO1 Data Output Fall Time — — — ns See Parameter DO32 (Note 4) SP31 TdoR SDO1 Data Output Rise Time — — — ns See Parameter DO31 (Note 4) SP35 TscH2doV, TscL2doV SDO1 Data Output Valid after SCK1 Edge — 6 20 ns SP36 TdoV2scH, TdoV2scL SDO1 Data Output Setup to First SCK1 Edge 30 — — ns SP40 TdiV2scH, TdiV2scL Setup Time of SDI1 Data Input to SCK1 Edge 30 — — ns SP41 TscH2diL, TscL2diL Hold Time of SDI1 Data Input to SCK1 Edge 30 — — ns SP50 TssL2scH, TssL2scL SS1  to SCK1  or SCK1  Input 120 — — ns SP51 TssH2doZ SS1  to SDO1 Output High-Impedance 10 — 50 ns (Note 4) SP52 TscH2ssH, TscL2ssH SS1 after SCK1 Edge 1.5 TCY + 40 — — ns (Note 4) SP60 TssL2doV SDO1 Data Output Valid after SS1 Edge — — 50 ns Note 1: These parameters are characterized, but are not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 3: The minimum clock period for SCK1 is 91 ns. Therefore, the SCK1 clock generated by the master must not violate this specification. 4: Assumes 50 pF load on all SPI1 pins. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 446  2011-2013 Microchip Technology Inc. FIGURE 30-28: SPI1 SLAVE MODE (FULL-DUPLEX, CKE = 0, CKP = 1, SMP = 0) TIMING CHARACTERISTICS SS1 SCK1 (CKP = 0) SCK1 (CKP = 1) SDO1 SP50 SP40 SP41 SP30, SP31 SP51 SP35 MSb LSb Bit 14 - - - - - -1 Bit 14 - - - -1 LSb In SP52 SP72 SP73 SP73 SP72 Note: Refer to Figure 30-1 for load conditions. SDI1 SP70 SP36 MSb In  2011-2013 Microchip Technology Inc. DS70000657H-page 447 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-47: SPI1 SLAVE MODE (FULL-DUPLEX, CKE = 0, CKP = 1, SMP = 0) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions SP70 FscP Maximum SCK1 Input Frequency — — 15 MHz (Note 3) SP72 TscF SCK1 Input Fall Time — — — ns See Parameter DO32 (Note 4) SP73 TscR SCK1 Input Rise Time — — — ns See Parameter DO31 (Note 4) SP30 TdoF SDO1 Data Output Fall Time — — — ns See Parameter DO32 (Note 4) SP31 TdoR SDO1 Data Output Rise Time — — — ns See Parameter DO31 (Note 4) SP35 TscH2doV, TscL2doV SDO1 Data Output Valid after SCK1 Edge — 6 20 ns SP36 TdoV2scH, TdoV2scL SDO1 Data Output Setup to First SCK1 Edge 30 — — ns SP40 TdiV2scH, TdiV2scL Setup Time of SDI1 Data Input to SCK1 Edge 30 — — ns SP41 TscH2diL, TscL2diL Hold Time of SDI1 Data Input to SCK1 Edge 30 — — ns SP50 TssL2scH, TssL2scL SS1  to SCK1  or SCK1  Input 120 — — ns SP51 TssH2doZ SS1  to SDO1 Output High-Impedance 10 — 50 ns (Note 4) SP52 TscH2ssH, TscL2ssH SS1 after SCK1 Edge 1.5 TCY + 40 — — ns (Note 4) Note 1: These parameters are characterized, but are not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 3: The minimum clock period for SCK1 is 66.7 ns. Therefore, the SCK1 clock generated by the master must not violate this specification. 4: Assumes 50 pF load on all SPI1 pins. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 448  2011-2013 Microchip Technology Inc. FIGURE 30-29: SPI1 SLAVE MODE (FULL-DUPLEX, CKE = 0, CKP = 0, SMP = 0) TIMING CHARACTERISTICS SS1 SCK1 (CKP = 0) SCK1 (CKP = 1) SDO1 SP50 SP40 SP41 SP30, SP31 SP51 MSb LSb Bit 14 - - - - - -1 Bit 14 - - - -1 LSb In SP52 SP72 SP73 SP73 SP72 Note: Refer to Figure 30-1 for load conditions. SDI1 SP70 SP35 SP36 MSb In  2011-2013 Microchip Technology Inc. DS70000657H-page 449 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-48: SPI1 SLAVE MODE (FULL-DUPLEX, CKE = 0, CKP = 0, SMP = 0) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions SP70 FscP Maximum SCK1 Input Frequency — — 11 MHz (Note 3) SP72 TscF SCK1 Input Fall Time — — — ns See Parameter DO32 (Note 4) SP73 TscR SCK1 Input Rise Time — — — ns See Parameter DO31 (Note 4) SP30 TdoF SDO1 Data Output Fall Time — — — ns See Parameter DO32 (Note 4) SP31 TdoR SDO1 Data Output Rise Time — — — ns See Parameter DO31 (Note 4) SP35 TscH2doV, TscL2doV SDO1 Data Output Valid after SCK1 Edge — 6 20 ns SP36 TdoV2scH, TdoV2scL SDO1 Data Output Setup to First SCK1 Edge 30 — — ns SP40 TdiV2scH, TdiV2scL Setup Time of SDI1 Data Input to SCK1 Edge 30 — — ns SP41 TscH2diL, TscL2diL Hold Time of SDI1 Data Input to SCK1 Edge 30 — — ns SP50 TssL2scH, TssL2scL SS1  to SCK1  or SCK1  Input 120 — — ns SP51 TssH2doZ SS1  to SDO1 Output High-Impedance 10 — 50 ns (Note 4) SP52 TscH2ssH, TscL2ssH SS1 after SCK1 Edge 1.5 TCY + 40 — — ns (Note 4) Note 1: These parameters are characterized, but are not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. 3: The minimum clock period for SCK1 is 91 ns. Therefore, the SCK1 clock generated by the master must not violate this specification. 4: Assumes 50 pF load on all SPI1 pins. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 450  2011-2013 Microchip Technology Inc. FIGURE 30-30: I2Cx BUS START/STOP BITS TIMING CHARACTERISTICS (MASTER MODE) FIGURE 30-31: I2Cx BUS DATA TIMING CHARACTERISTICS (MASTER MODE) SCLx SDAx Start Condition Stop Condition Note: Refer to Figure 30-1 for load conditions. IM30 IM31 IM33 IM34 IM11 IM10 IM33 IM11 IM10 IM20 IM26 IM25 IM40 IM40 IM45 IM21 SCLx SDAx In SDAx Out Note: Refer to Figure 30-1 for load conditions.  2011-2013 Microchip Technology Inc. DS70000657H-page 451 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-49: I2Cx BUS DATA TIMING REQUIREMENTS (MASTER MODE) AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristic(4) Min.(1) Max. Units Conditions IM10 TLO:SCL Clock Low Time 100 kHz mode TCY/2 (BRG + 2) — s 400 kHz mode TCY/2 (BRG + 2) — s 1 MHz mode(2) TCY/2 (BRG + 2) — s IM11 THI:SCL Clock High Time 100 kHz mode TCY/2 (BRG + 2) — s 400 kHz mode TCY/2 (BRG + 2) — s 1 MHz mode(2) TCY/2 (BRG + 2) — s IM20 TF:SCL SDAx and SCLx Fall Time 100 kHz mode — 300 ns CB is specified to be 400 kHz mode 20 + 0.1 CB 300 ns from 10 to 400 pF 1 MHz mode(2) — 100 ns IM21 TR:SCL SDAx and SCLx Rise Time 100 kHz mode — 1000 ns CB is specified to be 400 kHz mode 20 + 0.1 CB 300 ns from 10 to 400 pF 1 MHz mode(2) — 300 ns IM25 TSU:DAT Data Input Setup Time 100 kHz mode 250 — ns 400 kHz mode 100 — ns 1 MHz mode(2) 40 — ns IM26 THD:DAT Data Input Hold Time 100 kHz mode 0 — s 400 kHz mode 0 0.9 s 1 MHz mode(2) 0.2 — s IM30 TSU:STA Start Condition Setup Time 100 kHz mode TCY/2 (BRG + 2) — s Only relevant for Repeated Start condition 400 kHz mode TCY/2 (BRG + 2) — s 1 MHz mode(2) TCY/2 (BRG + 2) — s IM31 THD:STA Start Condition Hold Time 100 kHz mode TCY/2 (BRG + 2) — s After this period, the first clock pulse is generated 400 kHz mode TCY/2 (BRG +2) — s 1 MHz mode(2) TCY/2 (BRG + 2) — s IM33 TSU:STO Stop Condition Setup Time 100 kHz mode TCY/2 (BRG + 2) — s 400 kHz mode TCY/2 (BRG + 2) — s 1 MHz mode(2) TCY/2 (BRG + 2) — s IM34 THD:STO Stop Condition 100 kHz mode TCY/2 (BRG + 2) — s Hold Time 400 kHz mode TCY/2 (BRG + 2) — s 1 MHz mode(2) TCY/2 (BRG + 2) — s IM40 TAA:SCL Output Valid From Clock 100 kHz mode — 3500 ns 400 kHz mode — 1000 ns 1 MHz mode(2) — 400 ns IM45 TBF:SDA 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 1 MHz mode(2) 0.5 — s IM50 CB Bus Capacitive Loading — 400 pF IM51 TPGD Pulse Gobbler Delay 65 390 ns (Note 3) Note 1: BRG is the value of the I2C™ Baud Rate Generator. Refer to “Inter-Integrated Circuit (I2C™)” (DS70330) in the “dsPIC33/PIC24 Family Reference Manual”. Please see the Microchip web site for the latest family reference manual sections. 2: Maximum pin capacitance = 10 pF for all I2Cx pins (for 1 MHz mode only). 3: Typical value for this parameter is 130 ns. 4: These parameters are characterized, but not tested in manufacturing. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 452  2011-2013 Microchip Technology Inc. FIGURE 30-32: I2Cx BUS START/STOP BITS TIMING CHARACTERISTICS (SLAVE MODE) FIGURE 30-33: I2Cx BUS DATA TIMING CHARACTERISTICS (SLAVE MODE) SCLx SDAx Start Condition Stop Condition IS33 IS34 IS30 IS31 IS30 IS31 IS33 IS11 IS10 IS20 IS25 IS40 IS40 IS45 IS21 SCLx SDAx In SDAx Out IS26  2011-2013 Microchip Technology Inc. DS70000657H-page 453 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-50: I2Cx BUS DATA TIMING REQUIREMENTS (SLAVE MODE) AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. No. Symbol Characteristic(3) Min. Max. Units Conditions IS10 TLO:SCL Clock Low Time 100 kHz mode 4.7 — s 400 kHz mode 1.3 — s 1 MHz mode(1) 0.5 — s IS11 THI:SCL Clock High Time 100 kHz mode 4.0 — s Device must operate at a minimum of 1.5 MHz 400 kHz mode 0.6 — s Device must operate at a minimum of 10 MHz 1 MHz mode(1) 0.5 — s IS20 TF:SCL SDAx and SCLx Fall Time 100 kHz mode — 300 ns CB is specified to be from 400 kHz mode 20 + 0.1 CB 300 ns 10 to 400 pF 1 MHz mode(1) — 100 ns IS21 TR:SCL SDAx and SCLx Rise Time 100 kHz mode — 1000 ns CB is specified to be from 400 kHz mode 20 + 0.1 CB 300 ns 10 to 400 pF 1 MHz mode(1) — 300 ns IS25 TSU:DAT Data Input Setup Time 100 kHz mode 250 — ns 400 kHz mode 100 — ns 1 MHz mode(1) 100 — ns IS26 THD:DAT Data Input Hold Time 100 kHz mode 0 — s 400 kHz mode 0 0.9 s 1 MHz mode(1) 0 0.3 s IS30 TSU:STA Start Condition Setup Time 100 kHz mode 4.7 — s Only relevant for Repeated 400 kHz mode 0.6 — s Start condition 1 MHz mode(1) 0.25 — s IS31 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 1 MHz mode(1) 0.25 — s IS33 TSU:STO Stop Condition Setup Time 100 kHz mode 4.7 — s 400 kHz mode 0.6 — s 1 MHz mode(1) 0.6 — s IS34 THD:STO Stop Condition Hold Time 100 kHz mode 4 — s 400 kHz mode 0.6 — s 1 MHz mode(1) 0.25 s IS40 TAA:SCL Output Valid From Clock 100 kHz mode 0 3500 ns 400 kHz mode 0 1000 ns 1 MHz mode(1) 0 350 ns IS45 TBF:SDA 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 1 MHz mode(1) 0.5 — s IS50 CB Bus Capacitive Loading — 400 pF IS51 TPGD Pulse Gobbler Delay 65 390 ns (Note 2) Note 1: Maximum pin capacitance = 10 pF for all I2Cx pins (for 1 MHz mode only). 2: Typical value for this parameter is 130 ns. 3: These parameters are characterized, but not tested in manufacturing. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 454  2011-2013 Microchip Technology Inc. FIGURE 30-34: ECANx MODULE I/O TIMING CHARACTERISTICS TABLE 30-51: ECANx MODULE I/O TIMING REQUIREMENTS FIGURE 30-35: UARTx MODULE I/O TIMING CHARACTERISTICS TABLE 30-52: UARTx MODULE I/O TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions CA10 TIOF Port Output Fall Time — — — ns See Parameter DO32 CA11 TIOR Port Output Rise Time — — — ns See Parameter DO31 CA20 TCWF Pulse Width to Trigger CAN Wake-up Filter 120 — — ns Note 1: These parameters are characterized but not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. Parameters are for design guidance only and are not tested. AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +125°C Param No. Symbol Characteristic(1) Min. Typ.(2) Max. Units Conditions UA10 TUABAUD UARTx Baud Time 66.67 — — ns UA11 FBAUD UARTx Baud Frequency — — 15 Mbps UA20 TCWF Start Bit Pulse Width to Trigger UARTx Wake-up 500 — — ns Note 1: These parameters are characterized but not tested in manufacturing. 2: Data in “Typical” column is at 3.3V, +25°C unless otherwise stated. Parameters are for design guidance only and are not tested. CxTx Pin (output) CA10, CA11 Old Value New Value CA20 CxRx Pin (input) UA20 UxRX MSb In LSb In Bits 1-6 UA10 UXTX  2011-2013 Microchip Technology Inc. DS70000657H-page 455 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-53: OP AMP/COMPARATOR SPECIFICATIONS DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated)(1) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristic Min. Typ.(2) Max. Units Conditions Comparator AC Characteristics CM10 TRESP Response Time(3) — 19 — ns V+ input step of 100 mV, V- input held at VDD/2 CM11 TMC2OV Comparator Mode Change to Output Valid — — 10 µs Comparator DC Characteristics CM30 VOFFSET Comparator Offset Voltage — ±10 40 mV CM31 VHYST Input Hysteresis Voltage(3) — 30 — mV CM32 TRISE/ TFALL Comparator Output Rise/ Fall Time(3) — 20 — ns 1 pF load capacitance on input CM33 VGAIN Open-Loop Voltage Gain(3) — 90 — db CM34 VICM Input Common-Mode Voltage AVSS — AVDD V Op Amp AC Characteristics CM20 SR Slew Rate(3) — 9 — V/µs 10 pF load CM21a PM Phase Margin (Configuration A)(3,4) — 55 — Degree G = 100V/V; 10 pF load CM21b PM Phase Margin (Configuration B)(3,5) — 40 — Degree G = 100V/V; 10 pF load CM22 GM Gain Margin(3) — 20 — db G = 100V/V; 10 pF load CM23a GBW Gain Bandwidth (Configuration A)(3,4) — 10 — MHz 10 pF load CM23b GBW Gain Bandwidth (Configuration B)(3,5) — 6 — MHz 10 pF load Note 1: Device is functional at VBORMIN < VDD < VDDMIN, but will have degraded performance. Device functionality is tested, but not characterized. Analog modules (ADC, op amp/comparator and comparator voltage reference) may have degraded performance. Refer to Parameter BO10 in Table 30-13 for the minimum and maximum BOR values. 2: Data in “Typ” column is at 3.3V, +25°C unless otherwise stated. 3: Parameter is characterized but not tested in manufacturing. 4: See Figure 25-6 for configuration information. 5: See Figure 25-7 for configuration information. 6: Resistances can vary by ±10% between op amps. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 456  2011-2013 Microchip Technology Inc. Op Amp DC Characteristics CM40 VCMR Common-Mode Input Voltage Range AVSS — AVDD V CM41 CMRR Common-Mode Rejection Ratio(3) — 40 — db VCM = AVDD/2 CM42 VOFFSET Op Amp Offset Voltage(3) — ±5 — mV CM43 VGAIN Open-Loop Voltage Gain(3) — 90 — db CM44 IOS Input Offset Current — — — — See pad leakage currents in Table 30-11 CM45 IB Input Bias Current — — — — See pad leakage currents in Table 30-11 CM46 IOUT Output Current — — 420 µA With minimum value of RFEEDBACK (CM48) CM48 RFEEDBACK Feedback Resistance Value 8 ——k CM49a VOADC Output Voltage Measured at OAx Using ADC(3,4) AVSS + 0.077 AVSS + 0.037 AVSS + 0.018 — — — AVDD – 0.077 AVDD – 0.037 AVDD – 0.018 V V V IOUT = 420 µA IOUT = 200 µA IOUT = 100 µA CM49b VOUT Output Voltage Measured at OAxOUT Pin(3,4,5) AVSS + 0.210 AVSS + 0.100 AVSS + 0.050 — — — AVDD – 0.210 AVDD – 0.100 AVDD – 0.050 V V V IOUT = 420 µA IOUT = 200 µA IOUT = 100 µA CM51 RINT1(6) Internal Resistance 1 (Configuration A and B)(3,4,5) 198 264 317  Min = -40ºC Typ = +25ºC Max = +125ºC TABLE 30-53: OP AMP/COMPARATOR SPECIFICATIONS (CONTINUED) DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated)(1) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristic Min. Typ.(2) Max. Units Conditions Note 1: Device is functional at VBORMIN < VDD < VDDMIN, but will have degraded performance. Device functionality is tested, but not characterized. Analog modules (ADC, op amp/comparator and comparator voltage reference) may have degraded performance. Refer to Parameter BO10 in Table 30-13 for the minimum and maximum BOR values. 2: Data in “Typ” column is at 3.3V, +25°C unless otherwise stated. 3: Parameter is characterized but not tested in manufacturing. 4: See Figure 25-6 for configuration information. 5: See Figure 25-7 for configuration information. 6: Resistances can vary by ±10% between op amps.  2011-2013 Microchip Technology Inc. DS70000657H-page 457 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-55: OP AMP/COMPARATOR VOLTAGE REFERENCE SPECIFICATIONS TABLE 30-54: OP AMP/COMPARATOR VOLTAGE REFERENCE SETTLING TIME SPECIFICATIONS AC CHARACTERISTICS Standard Operating Conditions (see Note 2): 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param. Symbol Characteristic Min. Typ. Max. Units Conditions VR310 TSET Settling Time — 1 10 s (Note 1) Note 1: Settling time is measured while CVRR = 1 and CVR<3:0> bits transition from ‘0000’ to ‘1111’. 2: Device is functional at VBORMIN < VDD < VDDMIN, but will have degraded performance. Device functionality is tested, but not characterized. Analog modules (ADC, op amp/comparator and comparator voltage reference) may have degraded performance. Refer to Parameter BO10 in Table 30-13 for the minimum and maximum BOR values. DC CHARACTERISTICS Standard Operating Conditions (see Note 1): 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Symbol Characteristics Min. Typ. Max. Units Conditions VRD310 CVRES Resolution CVRSRC/24 — CVRSRC/32 LSb VRD311 CVRAA Absolute Accuracy(2) — ±25 — mV CVRSRC = 3.3V VRD313 CVRSRC Input Reference Voltage 0 — AVDD + 0.3 V VRD314 CVROUT Buffer Output Resistance(2) — 1.5k —  Note 1: Device is functional at VBORMIN < VDD < VDDMIN, but will have degraded performance. Device functionality is tested, but not characterized. Analog modules (ADC, op amp/comparator and comparator voltage reference) may have degraded performance. Refer to Parameter BO10 in Table 30-13 for the minimum and maximum BOR values. 2: Parameter is characterized but not tested in manufacturing. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 458  2011-2013 Microchip Technology Inc. TABLE 30-56: CTMU CURRENT SOURCE SPECIFICATIONS DC CHARACTERISTICS Standard Operating Conditions:3.0V to 3.6V (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 CTMU Current Source CTMUI1 IOUT1 Base Range(1) 0.29 — 0.77 µA CTMUICON<9:8> = 01 CTMUI2 IOUT2 10x Range(1) 3.85 — 7.7 µA CTMUICON<9:8> = 10 CTMUI3 IOUT3 100x Range(1) 38.5 — 77 µA CTMUICON<9:8> = 11 CTMUI4 IOUT4 1000x Range(1) 385 — 770 µA CTMUICON<9:8> = 00 CTMUFV1 VF Temperature Diode Forward Voltage(1,2) — 0.598 — V TA = +25°C, CTMUICON<9:8> = 01 — 0.658 — V TA = +25°C, CTMUICON<9:8> = 10 — 0.721 — V TA = +25°C, CTMUICON<9:8> = 11 CTMUFV2 VFVR Temperature Diode Rate of Change(1,2,3) — -1.92 — mV/ºC CTMUICON<9:8> = 01 — -1.74 — mV/ºC CTMUICON<9:8> = 10 — -1.56 — mV/ºC CTMUICON<9:8> = 11 Note 1: Nominal value at center point of current trim range (CTMUICON<15:10> = 000000). 2: Parameters are characterized but not tested in manufacturing. 3: Measurements taken with the following conditions: • VREF+ = AVDD = 3.3V • ADC configured for 10-bit mode • ADC module configured for conversion speed of 500 ksps • All PMDx bits are cleared (PMDx = 0) • Executing a while(1) statement • Device operating from the FRC with no PLL  2011-2013 Microchip Technology Inc. DS70000657H-page 459 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-57: ADC MODULE SPECIFICATIONS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated)(1) 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 Device Supply AD01 AVDD Module VDD Supply Greater of: VDD – 0.3 or 3.0 — Lesser of: VDD + 0.3 or 3.6 V AD02 AVSS Module VSS Supply VSS – 0.3 — VSS + 0.3 V Reference Inputs AD05 VREFH Reference Voltage High AVSS + 2.5 — AVDD V VREFH = VREF+ VREFL = VREF- (Note 1) AD05a 3.0 — 3.6 V VREFH = AVDD VREFL = AVSS = 0 AD06 VREFL Reference Voltage Low AVSS — AVDD – 2.5 V (Note 1) AD06a 0 — 0 V VREFH = AVDD VREFL = AVSS = 0 AD07 VREF Absolute Reference Voltage 2.5 — 3.6 V VREF = VREFH - VREFL AD08 IREF Current Drain — — — — 10 600 A A ADC off ADC on AD09 IAD Operating Current(2) — 5 — mA ADC operating in 10-bit mode (Note 1) — 2 — mA ADC operating in 12-bit mode (Note 1) Analog Input AD12 VINH Input Voltage Range VINH VINL — VREFH V This voltage reflects Sample-andHold Channels 0, 1, 2 and 3 (CH0-CH3), positive input AD13 VINL Input Voltage Range VINL VREFL — AVSS + 1V V This voltage reflects Sample-andHold Channels 0, 1, 2 and 3 (CH0-CH3), negative input AD17 RIN Recommended Impedance of Analog Voltage Source — — 200  Impedance to achieve maximum performance of ADC Note 1: Device is functional at VBORMIN < VDD < VDDMIN, but will have degraded performance. Device functionality is tested, but not characterized. Analog modules (ADC, op amp/comparator and comparator voltage reference) may have degraded performance. Refer to Parameter BO10 in Table 30-13 for the minimum and maximum BOR values. 2: Parameter is characterized but not tested in manufacturing. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 460  2011-2013 Microchip Technology Inc. TABLE 30-58: ADC MODULE SPECIFICATIONS (12-BIT MODE) AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated)(1) 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 ADC Accuracy (12-Bit Mode) AD20a Nr Resolution 12 Data Bits bits AD21a INL Integral Nonlinearity -2.5 — 2.5 LSb -40°C  TA  +85°C (Note 2) -5.5 — 5.5 LSb +85°C  TA  +125°C (Note 2) AD22a DNL Differential Nonlinearity -1 — 1 LSb -40°C  TA  +85°C (Note 2) -1 — 1 LSb +85°C  TA  +125°C (Note 2) AD23a GERR Gain Error(3) -10 — 10 LSb -40°C  TA  +85°C (Note 2) -10 — 10 LSb +85°C  TA  +125°C (Note 2) AD24a EOFF Offset Error -5 — 5 LSb -40°C  TA  +85°C (Note 2) -5 — 5 LSb +85°C  TA  +125°C (Note 2) AD25a — Monotonicity — — — — Guaranteed Dynamic Performance (12-Bit Mode) AD30a THD Total Harmonic Distortion(3) — 75 — dB AD31a SINAD Signal to Noise and Distortion(3) — 68 — dB AD32a SFDR Spurious Free Dynamic Range(3) — 80 — dB AD33a FNYQ Input Signal Bandwidth(3) — 250 — kHz AD34a ENOB Effective Number of Bits(3) 11.09 11.3 — bits Note 1: Device is functional at VBORMIN < VDD < VDDMIN, but will have degraded performance. Device functionality is tested, but not characterized. Analog modules (ADC, op amp/comparator and comparator voltage reference) may have degraded performance. Refer to Parameter BO10 in Table 30-13 for the minimum and maximum BOR values. 2: For all accuracy specifications, VINL = AVSS = VREFL = 0V and AVDD = VREFH = 3.6V. 3: Parameters are characterized but not tested in manufacturing.  2011-2013 Microchip Technology Inc. DS70000657H-page 461 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-59: ADC MODULE SPECIFICATIONS (10-BIT MODE) AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated)(1) 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 ADC Accuracy (10-Bit Mode) AD20b Nr Resolution 10 Data Bits bits AD21b INL Integral Nonlinearity -0.625 — 0.625 LSb -40°C  TA  +85°C (Note 2) -1.5 — 1.5 LSb +85°C  TA  +125°C (Note 2) AD22b DNL Differential Nonlinearity -0.25 — 0.25 LSb -40°C  TA  +85°C (Note 2) -0.25 — 0.25 LSb +85°C  TA  +125°C (Note 2) AD23b GERR Gain Error -2.5 — 2.5 LSb -40°C  TA  +85°C (Note 2) -2.5 — 2.5 LSb +85°C  TA  +125°C (Note 2) AD24b EOFF Offset Error -1.25 — 1.25 LSb -40°C  TA  +85°C (Note 2) -1.25 — 1.25 LSb +85°C  TA  +125°C (Note 2) AD25b — Monotonicity — — — — Guaranteed Dynamic Performance (10-Bit Mode) AD30b THD Total Harmonic Distortion(3) — 64 — dB AD31b SINAD Signal to Noise and Distortion(3) — 57 — dB AD32b SFDR Spurious Free Dynamic Range(3) — 72 — dB AD33b FNYQ Input Signal Bandwidth(3) — 550 — kHz AD34b ENOB Effective Number of Bits(3) — 9.4 — bits Note 1: Device is functional at VBORMIN < VDD < VDDMIN, but will have degraded performance. Device functionality is tested, but not characterized. Analog modules (ADC, op amp/comparator and comparator voltage reference) may have degraded performance. Refer to Parameter BO10 in Table 30-13 for the minimum and maximum BOR values. 2: For all accuracy specifications, VINL = AVSS = VREFL = 0V and AVDD = VREFH = 3.6V. 3: Parameters are characterized but not tested in manufacturing. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 462  2011-2013 Microchip Technology Inc. FIGURE 30-36: ADC CONVERSION (12-BIT MODE) TIMING CHARACTERISTICS (ASAM = 0, SSRC<2:0> = 000, SSRCG = 0) TSAMP AD55 Set SAMP AD61 ADCLK Instruction SAMP AD60 DONE AD1IF 1 2 3 4 5 6 7 8 1 – Software sets AD1CON1. SAMP to start sampling. 2 – Sampling starts after discharge period. TSAMP is described in 3 – Software clears AD1CON1. SAMP to start conversion. 4 – Sampling ends, conversion sequence starts. 5 – Convert bit 11. 9 – One TAD for end of conversion. AD50 9 6 – Convert bit 10. 7 – Convert bit 1. 8 – Convert bit 0. Execution “dsPIC33/PIC24 Family Reference Manual”. “Analog-to-Digital Converter (ADC)” (DS70621) in the Clear SAMP  2011-2013 Microchip Technology Inc. DS70000657H-page 463 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-60: ADC CONVERSION (12-BIT MODE) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated)(1) 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 Clock Parameters AD50 TAD ADC Clock Period 117.6 — — ns AD51 tRC ADC Internal RC Oscillator Period(2) — 250 — ns Conversion Rate AD55 tCONV Conversion Time — 14 TAD ns AD56 FCNV Throughput Rate — — 500 ksps AD57a TSAMP Sample Time when Sampling any ANx Input 3 TAD —— — AD57b TSAMP Sample Time when Sampling the Op Amp Outputs (Configuration A and Configuration B)(4,5) 3 TAD —— — Timing Parameters AD60 tPCS Conversion Start from Sample Trigger(2,3) 2 TAD — 3 TAD — Auto-convert trigger is not selected AD61 tPSS Sample Start from Setting Sample (SAMP) bit(2,3) 2 TAD — 3 TAD — AD62 tCSS Conversion Completion to Sample Start (ASAM = 1) (2,3) — 0.5 TAD — — AD63 tDPU Time to Stabilize Analog Stage from ADC Off to ADC On(2,3) — — 20 s (Note 6) Note 1: Device is functional at VBORMIN < VDD < VDDMIN, but will have degraded performance. Device functionality is tested, but not characterized. Analog modules (ADC, op amp/comparator and comparator voltage reference) may have degraded performance. Refer to Parameter BO10 in Table 30-13 for the minimum and maximum BOR values. 2: Parameters are characterized but not tested in manufacturing. 3: Because the sample caps will eventually lose charge, clock rates below 10 kHz may affect linearity performance, especially at elevated temperatures. 4: See Figure 25-6 for configuration information. 5: See Figure 25-7 for configuration information. 6: The parameter, tDPU, is the time required for the ADC module to stabilize at the appropriate level when the module is turned on (ADON (AD1CON1<15>) = 1). During this time, the ADC result is indeterminate. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 464  2011-2013 Microchip Technology Inc. FIGURE 30-37: ADC CONVERSION (10-BIT MODE) TIMING CHARACTERISTICS (CHPS<1:0> = 01, SIMSAM = 0, ASAM = 0, SSRC<2:0> = 000, SSRCG = 0) FIGURE 30-38: ADC CONVERSION (10-BIT MODE) TIMING CHARACTERISTICS (CHPS<1:0> = 01, SIMSAM = 0, ASAM = 1, SSRC<2:0> = 111, SSRCG = 0, SAMC<4:0> = 00010) TSAMP Set SAMP AD61 ADCLK Instruction SAMP AD60 DONE AD1IF 1 2 3 4 5 6 8 5 6 7 1 – Software sets AD1CON1. SAMP to start sampling. 2 – Sampling starts after discharge period. TSAMP is described in 3 – Software clears AD1CON1. SAMP to start conversion. 4 – Sampling ends, conversion sequence starts. 5 – Convert bit 9. 8 – One TAD for end of conversion. AD50 7 8 6 – Convert bit 8. 7 – Convert bit 0. Execution “dsPIC33/PIC24 Family Reference Manual”. “Analog-to-Digital Converter (ADC)” (DS70621) in the Clear SAMP AD55 AD55 1 2 3 4 5 6 4 5 6 8 1 – Software sets AD1CON1. ADON to start AD operation. 2 – Sampling starts after discharge period. TSAMP is described in 3 – Convert bit 9. 4 – Convert bit 8. 5 – Convert bit 0. 7 3 6 – One TAD for end of conversion. 7 – Begin conversion of next channel. 8 – Sample for time specified by SAMC<4:0>. ADCLK Instruction Set ADON Execution SAMP TSAMP AD1IF DONE AD55 AD55 TSAMP AD55 AD50 “Analog-to-Digital Converter (ADC)” (DS70621) in the “dsPIC33/PIC24 Family Reference Manual”. AD62  2011-2013 Microchip Technology Inc. DS70000657H-page 465 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 30-61: ADC CONVERSION (10-BIT MODE) TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated)(1) 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 Clock Parameters AD50 TAD ADC Clock Period 76 — — ns AD51 tRC ADC Internal RC Oscillator Period(2) — 250 — ns Conversion Rate AD55 tCONV Conversion Time — 12 TAD — — AD56 FCNV Throughput Rate — — 1.1 Msps Using simultaneous sampling AD57a TSAMP Sample Time when Sampling any ANx Input 2 TAD ——— AD57b TSAMP Sample Time when Sampling the Op Amp Outputs (Configuration A and Configuration B)(4,5) 4 TAD ——— Timing Parameters AD60 tPCS Conversion Start from Sample Trigger(2,3) 2 TAD — 3 TAD — Auto-convert trigger is not selected AD61 tPSS Sample Start from Setting Sample (SAMP) bit(2,3)) 2 TAD — 3 TAD — AD62 tCSS Conversion Completion to Sample Start (ASAM = 1) (2,3) — 0.5 TAD — — AD63 tDPU Time to Stabilize Analog Stage from ADC Off to ADC On(2,3) — — 20 s (Note 6) Note 1: Device is functional at VBORMIN < VDD < VDDMIN, but will have degraded performance. Device functionality is tested, but not characterized. Analog modules (ADC, op amp/comparator and comparator voltage reference) may have degraded performance. Refer to Parameter BO10 in Table 30-13 for the minimum and maximum BOR values. 2: Parameters are characterized but not tested in manufacturing. 3: Because the sample caps will eventually lose charge, clock rates below 10 kHz may affect linearity performance, especially at elevated temperatures. 4: See Figure 25-6 for configuration information. 5: See Figure 25-7 for configuration information. 6: The parameter, tDPU, is the time required for the ADC module to stabilize at the appropriate level when the module is turned on (ADON (AD1CON1<15>) = 1). During this time, the ADC result is indeterminate. TABLE 30-62: DMA MODULE TIMING REQUIREMENTS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +85°C for Industrial -40°C  TA  +125°C for Extended Param No. Characteristic Min. Typ.(1) Max. Units Conditions DM1 DMA Byte/Word Transfer Latency 1 TCY(2) — — ns Note 1: These parameters are characterized, but not tested in manufacturing. 2: Because DMA transfers use the CPU data bus, this time is dependent on other functions on the bus. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 466  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 467 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 31.0 HIGH-TEMPERATURE ELECTRICAL CHARACTERISTICS This section provides an overview of dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/ MC20X electrical characteristics for devices operating in an ambient temperature range of -40°C to +150°C. The specifications between -40°C to +150°C are identical to those shown in Section 30.0 “Electrical Characteristics” for operation between -40°C to +125°C, with the exception of the parameters listed in this section. Parameters in this section begin with an H, which denotes High temperature. For example, Parameter DC10 in Section 30.0 “Electrical Characteristics” is the Industrial and Extended temperature equivalent of HDC10. Absolute maximum ratings for the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X high-temperature devices are listed below. Exposure to these maximum rating conditions for extended periods can affect device reliability. Functional operation of the device at these or any other conditions above the parameters indicated in the operation listings of this specification is not implied. Absolute Maximum Ratings(1) Ambient temperature under bias(2) .........................................................................................................-40°C to +150°C Storage temperature .............................................................................................................................. -65°C to +160°C Voltage on VDD with respect to VSS ......................................................................................................... -0.3V to +4.0V Voltage on any pin that is not 5V tolerant with respect to VSS(3) ..................................................... -0.3V to (VDD + 0.3V) Voltage on any 5V tolerant pin with respect to VSS when VDD < 3.0V(3) ..................................................... -0.3V to 3.6V Voltage on any 5V tolerant pin with respect to VSS when VDD  3.0V(3) ..................................................... -0.3V to 5.5V Maximum current out of VSS pin .............................................................................................................................60 mA Maximum current into VDD pin(4) .............................................................................................................................60 mA Maximum junction temperature............................................................................................................................. +155°C Maximum current sourced/sunk by any 4x I/O pin..................................................................................................10 mA Maximum current sourced/sunk by any 8x I/O pin..................................................................................................15 mA Maximum current sunk by all ports combined.........................................................................................................70 mA Maximum current sourced by all ports combined(4) ................................................................................................70 mA Note 1: Stresses above those listed under “Absolute Maximum Ratings” can 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 can affect device reliability. 2: AEC-Q100 reliability testing for devices intended to operate at +150°C is 1,000 hours. Any design in which the total operating time from +125°C to +150°C will be greater than 1,000 hours is not warranted without prior written approval from Microchip Technology Inc. 3: Refer to the “Pin Diagrams” section for 5V tolerant pins. 4: Maximum allowable current is a function of device maximum power dissipation (see Table 31-2). dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 468  2011-2013 Microchip Technology Inc. 31.1 High-Temperature DC Characteristics TABLE 31-1: OPERATING MIPS VS. VOLTAGE TABLE 31-2: THERMAL OPERATING CONDITIONS TABLE 31-3: DC TEMPERATURE AND VOLTAGE SPECIFICATIONS Characteristic VDD Range (in Volts) Temperature Range (in °C) Max MIPS dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X HDC5 3.0 to 3.6V(1) -40°C to +150°C 40 Note 1: Device is functional at VBORMIN < VDD < VDDMIN. Analog modules, such as the ADC, may have degraded performance. Device functionality is tested but not characterized. Rating Symbol Min Typ Max Unit High-Temperature Devices Operating Junction Temperature Range TJ -40 — +155 °C Operating Ambient Temperature Range TA -40 — +150 °C Power Dissipation: Internal Chip Power Dissipation: PINT = VDD x (IDD –  IOH) PD PINT + PI/O W I/O Pin Power Dissipation: I/O =  ({VDD – VOH} x IOH) +  (VOL x IOL) Maximum Allowed Power Dissipation PDMAX (TJ – TA)/JA W DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +150°C Parameter No. Symbol Characteristic Min Typ Max Units Conditions Operating Voltage HDC10 Supply Voltage VDD — 3.0 3.3 3.6 V -40°C to +150°C  2011-2013 Microchip Technology Inc. DS70000657H-page 469 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 31-4: DC CHARACTERISTICS: POWER-DOWN CURRENT (IPD) TABLE 31-5: DC CHARACTERISTICS: IDLE CURRENT (IIDLE) TABLE 31-6: DC CHARACTERISTICS: OPERATING CURRENT (IDD) TABLE 31-7: DC CHARACTERISTICS: DOZE CURRENT (IDOZE) DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +150°C Parameter No. Typical Max Units Conditions Power-Down Current (IPD) HDC60e 1400 2500 A +150°C 3.3V Base Power-Down Current (Notes 1, 3) HDC61c 15 — A +150°C 3.3V Watchdog Timer Current: IWDT (Notes 2, 4) Note 1: Base IPD is measured with all peripherals and clocks shut down. All I/Os are configured as inputs and pulled to VSS. WDT, etc., are all switched off and VREGS (RCON<8>) = 1. 2: The  current is the additional current consumed when the module is enabled. This current should be added to the base IPD current. 3: These currents are measured on the device containing the most memory in this family. 4: These parameters are characterized, but are not tested in manufacturing. DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +150°C Parameter No. Typical Max Units Conditions HDC44e 12 30 mA +150°C 3.3V 40 MIPS DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +150°C Parameter No. Typical Max Units Conditions HDC20 9 15 mA +150°C 3.3V 10 MIPS HDC22 16 25 mA +150°C 3.3V 20 MIPS HDC23 30 50 mA +150°C 3.3V 40 MIPS DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +150°C Parameter No. Typical Max Doze Ratio Units Conditions HDC72a 24 35 1:2 mA HDC72f +150°C 3.3V 40 MIPS (1) 14 — 1:64 mA HDC72g(1) 12 — 1:128 mA Note 1: Parameters with Doze ratios of 1:64 and 1:128 are characterized, but are not tested in manufacturing. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 470  2011-2013 Microchip Technology Inc. TABLE 31-8: DC CHARACTERISTICS: I/O PIN OUTPUT SPECIFICATIONS DC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +150°C Param. Symbol Characteristic Min. Typ. Max. Units Conditions HDO10 VOL Output Low Voltage 4x Sink Driver Pins(2) — — 0.4 V IOL  5 mA, VDD = 3.3V (Note 1) Output Low Voltage 8x Sink Driver Pins(3) — — 0.4 V IOL  8 mA, VDD = 3.3V (Note 1) HDO20 VOH Output High Voltage 4x Source Driver Pins(2) 2.4 — — V IOH  -10 mA, VDD = 3.3V (Note 1) Output High Voltage 8x Source Driver Pins(3) 2.4 — — V IOH  15 mA, VDD = 3.3V (Note 1) HDO20A VOH1 Output High Voltage 4x Source Driver Pins(2) 1.5 — — V IOH  -3.9 mA, VDD = 3.3V (Note 1) 2.0 — — IOH  -3.7 mA, VDD = 3.3V (Note 1) 3.0 — — IOH  -2 mA, VDD = 3.3V (Note 1) Output High Voltage 8x Source Driver Pins(3) 1.5 — — V IOH  -7.5 mA, VDD = 3.3V (Note 1) 2.0 — — IOH  -6.8 mA, VDD = 3.3V (Note 1) 3.0 — — IOH  -3 mA, VDD = 3.3V (Note 1) Note 1: Parameters are characterized, but not tested. 2: Includes all I/O pins that are not 8x Sink Driver pins (see below). 3: Includes the following pins: For devices with less than 64 pins: RA3, RA4, RA9, RB<15:7> and RC3 For 64-pin devices: RA4, RA9, RB<15:7>, RC3 and RC15  2011-2013 Microchip Technology Inc. DS70000657H-page 471 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 31.2 AC Characteristics and Timing Parameters The information contained in this section defines dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X AC characteristics and timing parameters for high-temperature devices. However, all AC timing specifications in this section are the same as those in Section 30.2 “AC Characteristics and Timing Parameters”, with the exception of the parameters listed in this section. Parameters in this section begin with an H, which denotes High temperature. For example, Parameter OS53 in Section 30.2 “AC Characteristics and Timing Parameters” is the Industrial and Extended temperature equivalent of HOS53. TABLE 31-9: TEMPERATURE AND VOLTAGE SPECIFICATIONS – AC FIGURE 31-1: LOAD CONDITIONS FOR DEVICE TIMING SPECIFICATIONS TABLE 31-10: PLL CLOCK TIMING SPECIFICATIONS AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +150°C Operating voltage VDD range as described in Table 31-1. AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +150°C Param No. Symbol Characteristic Min Typ Max Units Conditions HOS53 DCLK CLKO Stability (Jitter)(1) -5 0.5 5 % Measured over 100 ms period Note 1: These parameters are characterized by similarity, but are not tested in manufacturing. This specification is based on clock cycle by clock cycle measurements. To calculate the effective jitter for individual time bases or communication clocks use this formula: VDD/2 CL RL Pin Pin VSS VSS CL RL = 464 CL = 50 pF for all pins except OSC2 15 pF for OSC2 output Load Condition 1 – for all pins except OSC2 Load Condition 2 – for OSC2 Peripheral Clock Jitter DCLK FOSC Peripheral Bit Rate Clock --------------------------------------------------------------     = ------------------------------------------------------------------------ For example: FOSC = 32 MHz, DCLK = 5%, SPIx bit rate clock (i.e., SCKx) is 2 MHz. SPI SCK Jitter DCLK 32 MHz 2 MHz --------------------     ------------------------------ 5% 16 --------- 5% 4 = = == ------- 1.25% dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 472  2011-2013 Microchip Technology Inc. TABLE 31-11: INTERNAL RC ACCURACY AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +150°C Param No. Characteristic Min Typ Max Units Conditions LPRC @ 32.768 kHz(1,2) HF21 LPRC -30 — +30 % -40°C  TA +150°C VDD = 3.0-3.6V Note 1: Change of LPRC frequency as VDD changes. 2: LPRC accuracy impacts the Watchdog Timer Time-out Period (TWDT). See Section 27.5 “Watchdog Timer (WDT)” for more information.  2011-2013 Microchip Technology Inc. DS70000657H-page 473 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TABLE 31-12: ADC MODULE SPECIFICATIONS (12-BIT MODE) TABLE 31-13: ADC MODULE SPECIFICATIONS (10-BIT MODE) AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +150°C Param No. Symbol Characteristic Min Typ Max Units Conditions ADC Accuracy (12-Bit Mode)(1) HAD20a Nr Resolution(3) 12 Data Bits bits HAD21a INL Integral Nonlinearity -5.5 — 5.5 LSb VINL = AVSS = VREFL = 0V, AVDD = VREFH = 3.6V HAD22a DNL Differential Nonlinearity -1 — 1 LSb VINL = AVSS = VREFL = 0V, AVDD = VREFH = 3.6V HAD23a GERR Gain Error -10 — 10 LSb VINL = AVSS = VREFL = 0V, AVDD = VREFH = 3.6V HAD24a EOFF Offset Error -5 — 5 LSb VINL = AVSS = VREFL = 0V, AVDD = VREFH = 3.6V Dynamic Performance (12-Bit Mode)(2) HAD33a FNYQ Input Signal Bandwidth — — 200 kHz Note 1: These parameters are characterized, but are tested at 20 ksps only. 2: These parameters are characterized by similarity, but are not tested in manufacturing. 3: Injection currents > | 0 | can affect the ADC results by approximately 4-6 counts. AC CHARACTERISTICS Standard Operating Conditions: 3.0V to 3.6V (unless otherwise stated) Operating temperature -40°C  TA  +150°C Param No. Symbol Characteristic Min Typ Max Units Conditions ADC Accuracy (10-Bit Mode)(1) HAD20b Nr Resolution(3) 10 Data Bits bits HAD21b INL Integral Nonlinearity -1.5 — 1.5 LSb VINL = AVSS = VREFL = 0V, AVDD = VREFH = 3.6V HAD22b DNL Differential Nonlinearity -0.25 — 0.25 LSb VINL = AVSS = VREFL = 0V, AVDD = VREFH = 3.6V HAD23b GERR Gain Error -2.5 — 2.5 LSb VINL = AVSS = VREFL = 0V, AVDD = VREFH = 3.6V HAD24b EOFF Offset Error -1.25 — 1.25 LSb VINL = AVSS = VREFL = 0V, AVDD = VREFH = 3.6V Dynamic Performance (10-Bit Mode)(2) HAD33b FNYQ Input Signal Bandwidth — — 400 kHz Note 1: These parameters are characterized, but are tested at 20 ksps only. 2: These parameters are characterized by similarity, but are not tested in manufacturing. 3: Injection currents > | 0 | can affect the ADC results by approximately 4-6 counts. dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 474  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 475 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 32.0 DC AND AC DEVICE CHARACTERISTICS GRAPHS FIGURE 32-1: VOH – 4x DRIVER PINS FIGURE 32-2: VOH – 8x DRIVER PINS FIGURE 32-3: VOL – 4x DRIVER PINS FIGURE 32-4: VOL – 8x DRIVER PINS Note: The graphs provided following this note are a statistical summary based on a limited number of samples and are provided for design guidance purposes only. The performance characteristics listed herein are not tested or guaranteed. In some graphs, the data presented may be outside the specified operating range (e.g., outside specified power supply range) and therefore, outside the warranted range. -0.050 -0.045 -0.040 -0.035 -0.030 -0.025 -0.020 IOH(A) VOH (V) -0.050 -0.045 -0.040 -0.035 -0.030 -0.025 -0.020 -0.015 -0.010 -0.005 0.000 0.00 0.50 1.00 1.50 2.00 2.50 3.00 3.50 4.00 IOH(A) VOH (V) 3V 3.3V 3.6V Absolute Maximum -0.080 -0.070 -0.060 -0.050 -0.040 0 030 IOH(A) VOH (V) -0.080 -0.070 -0.060 -0.050 -0.040 -0.030 -0.020 -0.010 0.000 0.00 0.50 1.00 1.50 2.00 2.50 3.00 3.50 4.00 IOH(A) VOH (V) 3V 3.3V 3.6V Absolute Maximum 0.015 0.020 0.025 0.030 0.035 0.040 0.045 0.050 IOH(A) VOL (V) 0.000 0.005 0.010 0.015 0.020 0.025 0.030 0.035 0.040 0.045 0.050 0.00 0.50 1.00 1.50 2.00 2.50 3.00 3.50 4.00 IOH(A) VOL (V) 3V 3.3V 3.6V Absolute Maximum 0 020 0.030 0.040 0.050 0.060 0.070 0.080 IOH(A) VOL (V) 8X 0.000 0.010 0.020 0.030 0.040 0.050 0.060 0.070 0.080 0.00 0.50 1.00 1.50 2.00 2.50 3.00 3.50 4.00 IOH(A) VOL (V) 8X 3V 3.3V 3.6V Absolute Maximum DS70000657H-page 476 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X  2011-2013 Microchip Technology Inc. FIGURE 32-5: TYPICAL IPD CURRENT @ VDD = 3.3V FIGURE 32-6: TYPICAL/MAXIMUM IDD CURRENT @ VDD = 3.3V FIGURE 32-7: TYPICAL IDOZE CURRENT @ VDD = 3.3V FIGURE 32-8: TYPICAL IIDLE CURRENT @ VDD = 3.3V 200.00 300.00 400.00 500.00 600.00 700.00 800.00 IPD Current (µA) 0.00 100.00 200.00 300.00 400.00 500.00 600.00 700.00 800.00 -40 -30 -20 -10 0 10 20 30 40 50 60 70 80 90 100 110 120 IPD Current (µA) Temperature (Celsius) 010203040506070 0 10 20 30 40 50 60 70 80 Typ. Max. MIPS IDD (mA) 15.00 20.00 25.00 30.00 35.00 40.00 45.00 OZE Current (mA) 0.00 5.00 10.00 15.00 20.00 25.00 30.00 35.00 40.00 45.00 1:1 1:2 1:4 1:8 1:16 1:32 1:64 1:128 IDOZE Current (mA) Doze Ratio 10.00 15.00 20.00 25.00 IDLE Current (mA) 0.00 5.00 10.00 15.00 20.00 25.00 0 10 20 30 40 50 60 70 IIDLE Current (mA) MIPS IIDLE (EC) IIDLE (EC+PLL)  2011-2013 Microchip Technology Inc. DS70000657H-page 477 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X FIGURE 32-9: TYPICAL FRC FREQUENCY @ VDD = 3.3V FIGURE 32-10: TYPICAL LPRC FREQUENCY @ VDD = 3.3V FIGURE 32-11: TYPICAL CTMU TEMPERATURE DIODE FORWARD VOLTAGE 7310 7320 7330 7340 7350 7360 7370 7380 FRC Frequency (kHz) 7280 7290 7300 7310 7320 7330 7340 7350 7360 7370 7380 -40 -30 -20 -10 0 10 20 30 40 50 60 70 80 90 100 110 120 FRC Frequency (kHz) Temperature (Celsius) 31 32 33 LPRC Frequency (kHz) 30 -40 -30 -20 -10 0 10 20 30 40 50 60 70 80 90 100 110 120 LPRC Frequency (kHz) Temperature (Celsius) 0.550 0.600 0.650 0.700 0.750 0.800 0.850 Forward Voltage (V) 0.350 0.400 0.450 0.500 0.550 0.600 0.650 0.700 0.750 0.800 0.850 -40 -30 -20 -10 0 10 20 30 40 50 60 70 80 90 100 110 120 130 Forward Voltage (V) Temperature (Celsius) VF = 0.598 VF = 0.658 VF = 0.721 65 µA, VFVR = -1.56 mV/ºC 6.5 µA, VFVR = -1.74 mV/ºC 0.65 µA, VFVR = -1.92 mV/ºC dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 478  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 479 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 33.0 PACKAGING INFORMATION 33.1 Package Marking Information Legend: XX...X Customer-specific information Y Year code (last digit of calendar year) YY Year code (last 2 digits of calendar year) WW Week code (week of January 1 is week ‘01’) NNN Alphanumeric traceability code Pb-free JEDEC designator for Matte Tin (Sn) * This package is Pb-free. The Pb-free JEDEC designator ( ) can be found on the outer packaging for this package. Note: In the event the full Microchip part number cannot be marked on one line, it will be carried over to the next line, thus limiting the number of available characters for customer-specific information. e3 e3 28-Lead SPDIP XXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXX YYWWNNN Example dsPIC33EP64GP 1310017 502-I/SP e3 28-Lead SOIC (.300”) XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXXXXXX YYWWNNN Example dsPIC33EP64GP 1310017 502-I/SO e3 28-Lead SSOP XXXXXXXXXXXX XXXXXXXXXXXX YYWWNNN Example dsPIC33EP64 GP502-I/SS 1310017 e3 XXXXXXXX 28-Lead QFN-S (6x6x0.9 mm) XXXXXXXX YYWWNNN 33EP64GP Example 502-I/MM 1310017 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 480  2011-2013 Microchip Technology Inc. 33.1 Package Marking Information (Continued) XXXXXXXXXX 36-Lead VTLA (TLA) XXXXXXXXXX XXXXXXXXXX YYWWNNN Example XXXXXXXXXX 44-Lead VTLA (TLA) XXXXXXXXXX XXXXXXXXXX YYWWNNN 504-I/TL 1310017 33EP64GP e3 Example 504-I/TL 1310017 33EP64GP e3 44-Lead TQFP XXXXXXXXXX XXXXXXXXXX XXXXXXXXXX YYWWNNN Example 33EP64GP 504-I/PT 1310017 e3 XXXXXXXXXXX 44-Lead QFN (8x8x0.9 mm) XXXXXXXXXXX XXXXXXXXXXX YYWWNNN 33EP64GP Example 504-I/ML 1310017 e3  2011-2013 Microchip Technology Inc. DS70000657H-page 481 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 33.1 Package Marking Information (Continued) XXXXXXXXXXX 64-Lead QFN (9x9x0.9 mm) XXXXXXXXXXX XXXXXXXXXXX YYWWNNN dsPIC33EP Example 64GP506 1310017 -I/MR e3 64-Lead TQFP (10x10x1 mm) XXXXXXXXXX XXXXXXXXXX XXXXXXXXXX YYWWNNN Example dsPIC33EP 64GP506 1310017 -I/PT e3 XXXXXXXXXXX 48-Lead UQFN (6x6x0.5 mm) XXXXXXXXXXX XXXXXXXXXXX YYWWNNN 33EP64GP Example 504-I/MV 1310017 e3 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 482  2011-2013 Microchip Technology Inc. 33.2 Package Details                 !"   !"#$%&" '  ()"&'"!&) &#*&&&#   +%&, & !& - '! !#.#  &"#' #%!  & "! ! #%!  & "! !! &$#/ !#  '! #&   .0 1,2 1!'!   &$& "! **& "&&  ! !" 3 &' !&" &4# *!(!!& 4%&  &#& &&255***'  '54 6&! 7,8. '! 9'&! 7 7: ; 7"') %! 7 < &  1, & &  = =   ##4 4!!   -  1!& &   = =  "# &  "# >#& .  - --  ##4>#& .  <  :  9&  - -?  & & 9  -  9# 4!!  <   6 9#>#& )    9 * 9#>#& )  <  :   *+ 1 = = - NOTE 1 N 1 2 D E1 eB c E L A2 b e A1 b1 A 3       * ,1  2011-2013 Microchip Technology Inc. DS70000657H-page 483 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Note: For the most current package drawings, please see the Microchip Packaging Specification located at http://www.microchip.com/packaging dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 484  2011-2013 Microchip Technology Inc. Note: For the most current package drawings, please see the Microchip Packaging Specification located at http://www.microchip.com/packaging  2011-2013 Microchip Technology Inc. DS70000657H-page 485 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Note: For the most current package drawings, please see the Microchip Packaging Specification located at http://www.microchip.com/packaging dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 486  2011-2013 Microchip Technology Inc.   #$   %     &'    % !"   !"#$%&" '  ()"&'"!&) &#*&&&#   '! !#.#  &"#' #%!  & "! ! #%!  & "! !! &$#'' !# - '! #&   .0 1,2 1!'!   &$& "! **& "&&  ! .32 % '! ("!"*& "&&  (% % '& "  !!  !" 3 &' !&" &4# *!(!!& 4%&  &#& &&255***'  '54 6&! 99. . '! 9'&! 7 7: ; 7"') %! 7 < &  ?1, :  8&  = =   ##4 4!!  ?  < &# %%   = = :  >#& .  < <  ##4>#& .  - ? :  9&     3 &9& 9    3 & & 9 .3 9# 4!!   =  3 & @ @ <@ 9#>#& )  = -< L1 L c A2 A1 A E E1 D N 1 2 NOTE 1 b e φ       * ,-1  2011-2013 Microchip Technology Inc. DS70000657H-page 487 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Note: For the most current package drawings, please see the Microchip Packaging Specification located at http://www.microchip.com/packaging dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 488  2011-2013 Microchip Technology Inc.  2011-2013 Microchip Technology Inc. DS70000657H-page 489 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 490  2011-2013 Microchip Technology Inc.   ( )* !  + ,,  -.-.'/   ()! 0# '1  2   +# !" 3 &' !&" &4# *!(!!& 4%&  &#& &&255***'  '54  2011-2013 Microchip Technology Inc. DS70000657H-page 491 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 492  2011-2013 Microchip Technology Inc.  2011-2013 Microchip Technology Inc. DS70000657H-page 493 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 494  2011-2013 Microchip Technology Inc.  2011-2013 Microchip Technology Inc. DS70000657H-page 495 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 11  3# ( )4 3  5.5.5  * '  3() !"   !"#$%&" '  ()"&'"!&) &#*&&&#   ,'% !&  !  & A!B'   - '! !#.#  &"#' #%!  & "! ! #%!  & "! !! &$#'' !#  '! #&   .0 1,2 1!'!   &$& "! **& "&&  ! .32 % '! ("!"*& "&&  (% % '& "  !!  !" 3 &' !&" &4# *!(!!& 4%&  &#& &&255***'  '54 6&! 99. . '! 9'&! 7 7: ; 7"') %9#! 7  9#&  <1, :  8&  = =   ##4 4!!     &# %%   =  3 &9& 9  ?  3 & & 9 .3 3 & @ -@ @ :  >#& . 1, :  9&  1,  ##4>#& . 1,  ##49&  1, 9# 4!!   =  9#>#& ) - -   # %&   @ @ -@  # %&1 && '  @ @ -@ A E E1 D D1 e b NOTE 1 NOTE 2 N 123 c A1 L A2 L1 α φ β       * ,?1 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 496  2011-2013 Microchip Technology Inc. Note: For the most current package drawings, please see the Microchip Packaging Specification located at http://www.microchip.com/packaging  2011-2013 Microchip Technology Inc. DS70000657H-page 497 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 498  2011-2013 Microchip Technology Inc.  2011-2013 Microchip Technology Inc. DS70000657H-page 499 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 500  2011-2013 Microchip Technology Inc. Note: For the most current package drawings, please see the Microchip Packaging Specification located at http://www.microchip.com/packaging  2011-2013 Microchip Technology Inc. DS70000657H-page 501 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Note: For the most current package drawings, please see the Microchip Packaging Specification located at http://www.microchip.com/packaging dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 502  2011-2013 Microchip Technology Inc.  2011-2013 Microchip Technology Inc. DS70000657H-page 503 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Note: For the most current package drawings, please see the Microchip Packaging Specification located at http://www.microchip.com/packaging dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 504  2011-2013 Microchip Technology Inc. Note: For the most current package drawings, please see the Microchip Packaging Specification located at http://www.microchip.com/packaging  2011-2013 Microchip Technology Inc. DS70000657H-page 505 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X 64-Lead Plastic Thin Quad Flatpack (PT) – 10x10x1 mm Body, 2.00 mm Footprint [TQFP] Notes: 1. Pin 1 visual index feature may vary, but must be located within the hatched area. 2. Chamfers at corners are optional; size may vary. 3. Dimensions D1 and E1 do not include mold flash or protrusions. Mold flash or protrusions shall not exceed 0.25 mm per side. 4. Dimensioning and tolerancing per ASME Y14.5M. BSC: Basic Dimension. Theoretically exact value shown without tolerances. REF: Reference Dimension, usually without tolerance, for information purposes only. Note: For the most current package drawings, please see the Microchip Packaging Specification located at http://www.microchip.com/packaging Units MILLIMETERS Dimension Limits MIN NOM MAX Number of Leads N 64 Lead Pitch e 0.50 BSC Overall Height A – – 1.20 Molded Package Thickness A2 0.95 1.00 1.05 Standoff A1 0.05 – 0.15 Foot Length L 0.45 0.60 0.75 Footprint L1 1.00 REF Foot Angle φ 0° 3.5° 7° Overall Width E 12.00 BSC Overall Length D 12.00 BSC Molded Package Width E1 10.00 BSC Molded Package Length D1 10.00 BSC Lead Thickness c 0.09 – 0.20 Lead Width b 0.17 0.22 0.27 Mold Draft Angle Top α 11° 12° 13° Mold Draft Angle Bottom β 11° 12° 13° D D1 E E1 e b N NOTE 1 123 NOTE 2 c L A1 L1 A2 A φ β α Microchip Technology Drawing C04-085B dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 506  2011-2013 Microchip Technology Inc. Note: For the most current package drawings, please see the Microchip Packaging Specification located at http://www.microchip.com/packaging  2011-2013 Microchip Technology Inc. DS70000657H-page 507 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X APPENDIX A: REVISION HISTORY Revision A (April 2011) This is the initial released version of the document. Revision B (July 2011) This revision includes minor typographical and formatting changes throughout the data sheet text. All other major changes are referenced by their respective section in Table A-1. TABLE A-1: MAJOR SECTION UPDATES Section Name Update Description “High-Performance, 16-bit Digital Signal Controllers and Microcontrollers” Changed all pin diagrams references of VLAP to TLA. Section 4.0 “Memory Organization” Updated the All Resets values for CLKDIV and PLLFBD in the System Control Register Map (see Table 4-35). Section 5.0 “Flash Program Memory” Updated “one word” to “two words” in the first paragraph of Section 5.2 “RTSP Operation”. Section 9.0 “Oscillator Configuration” Updated the PLL Block Diagram (see Figure 9-2). Updated the Oscillator Mode, Fast RC Oscillator (FRC) with divide-by-N and PLL (FRCPLL), by changing (FRCDIVN + PLL) to (FRCPLL). Changed (FRCDIVN + PLL) to (FRCPLL) for COSC<2:0> = 001 and NOSC<2:0> = 001 in the Oscillator Control Register (see Register 9-1). Changed the POR value from 0 to 1 for the DOZE<1:0> bits, from 1 to 0 for the FRCDIV<0> bit, and from 0 to 1 for the PLLPOST<0> bit; Updated the default definitions for the DOZE<2:0> and FRCDIV<2:0> bits and updated all bit definitions for the PLLPOST<1:0> bits in the Clock Divisor Register (see Register 9-2). Changed the POR value from 0 to 1 for the PLLDIV<5:4> bits and updated the default definitions for all PLLDIV<8:0> bits in the PLL Feedback Division Register (see Register 9-2). Section 22.0 “Charge Time Measurement Unit (CTMU)” Updated the bit definitions for the IRNG<1:0> bits in the CTMU Current Control Register (see Register 22-3). Section 25.0 “Op amp/ Comparator Module” Updated the voltage reference block diagrams (see Figure 25-1 and Figure 25-2). dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 508  2011-2013 Microchip Technology Inc. Section 30.0 “Electrical Characteristics” Removed Voltage on VCAP with respect to Vss and added Note 5 in Absolute Maximum Ratings(1). Removed Parameter DC18 (VCORE) and Note 3 from the DC Temperature and Voltage Specifications (see Table 30-4). Updated Note 1 in the DC Characteristics: Operating Current (IDD) (see Table 30-6). Updated Note 1 in the DC Characteristics: Idle Current (IIDLE) (see Table 30-7). Changed the Typical values for Parameters DC60a-DC60d and updated Note 1 in the DC Characteristics: Power-down Current (IPD) (see Table 30-8). Updated Note 1 in the DC Characteristics: Doze Current (IDOZE) (see Table 30-9). Updated Note 2 in the Electrical Characteristics: BOR (see Table 30-12). Updated Parameters CM20 and CM31, and added Parameters CM44 and CM45 in the AC/DC Characteristics: Op amp/Comparator (see Table 30-14). Added the Op amp/Comparator Reference Voltage Settling Time Specifications (see Table 30-15). Added Op amp/Comparator Voltage Reference DC Specifications (see Table 30-16). Updated Internal FRC Accuracy Parameter F20a (see Table 30-21). Updated the Typical value and Units for Parameter CTMUI1, and added Parameters CTMUI4, CTMUFV1, and CTMUFV2 to the CTMU Current Source Specifications (see Table 30-55). Section 31.0 “Packaging Information” Updated packages by replacing references of VLAP with TLA. “Product Identification System” Changed VLAP to TLA. TABLE A-1: MAJOR SECTION UPDATES (CONTINUED) Section Name Update Description  2011-2013 Microchip Technology Inc. DS70000657H-page 509 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Revision C (December 2011) This revision includes typographical and formatting changes throughout the data sheet text. In addition, where applicable, new sections were added to each peripheral chapter that provide information and links to related resources, as well as helpful tips. For examples, see Section 20.1 “UART Helpful Tips” and Section 3.6 “CPU Resources”. All occurrences of TLA were updated to VTLA throughout the document, with the exception of the pin diagrams (updated diagrams were not available at time of publication). A new chapter, Section 31.0 “DC and AC Device Characteristics Graphs”, was added. All other major changes are referenced by their respective section in Table A-2. TABLE A-2: MAJOR SECTION UPDATES Section Name Update Description “16-bit Microcontrollers and Digital Signal Controllers (up to 256-Kbyte Flash and 32-Kbyte SRAM) with HighSpeed PWM, Op amps, and Advanced Analog” The content on the first page of this section was extensively reworked to provide the reader with the key features and functionality of this device family in an “at-a-glance” format. Section 1.0 “Device Overview” Updated the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X, and PIC24EPXXXGP/MC20X Block Diagram (see Figure 1-1), which now contains a CPU block and a reference to the CPU diagram. Updated the description and Note references in the Pinout I/O Descriptions for these pins: C1IN2-, C2IN2-, C3IN2-, OA1OUT, OA2OUT, and OA3OUT (see Table 1-1). Section 2.0 “Guidelines for Getting Started with 16-bit Digital Signal Controllers and Microcontrollers” Updated the Recommended Minimum Connection diagram (see Figure 2-1). Section 3.0 “CPU” Updated the dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X, and PIC24EPXXXGP/MC20X CPU Block Diagram (see Figure 3-1). Updated the Status register definition in the Programmer’s Model (see Figure 3-2). Section 4.0 “Memory Organization” Updated the Data Memory Maps (see Figure 4-6 and Figure 4-11). Removed the DCB<1:0> bits from the OC1CON2, OC2CON2, OC3CON2, and OC4CON2 registers in the Output Compare 1 Through Output Compare 4 Register Map (see Table 4-10). Added the TRIG1 and TRGCON1 registers to the PWM Generator 1 Register Map (see Table 4-13). Added the TRIG2 and TRGCON2 registers to the PWM Generator 2 Register Map (see Table 4-14). Added the TRIG3 and TRGCON3 registers to the PWM Generator 3 Register Map (see Table 4-15). Updated the second note in Section 4.7.1 “Bit-Reversed Addressing Implementation”. Section 8.0 “Direct Memory Access (DMA)” Updated the DMA Controller diagram (see Figure 8-1). Section 14.0 “Input Capture” Updated the bit values for the ICx clock source of the ICTSEL<12:10> bits in the ICxCON1 register (see Register 14-1). Section 15.0 “Output Compare” Updated the bit values for the OCx clock source of the OCTSEL<2:0> bits in the OCxCON1 register (see Register 15-1). Removed the DCB<1:0> bits from the Output Compare x Control Register 2 (see Register 15-2). dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 510  2011-2013 Microchip Technology Inc. Section 16.0 “High-Speed PWM Module (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X Devices Only)” Updated the High-Speed PWM Module Register Interconnection Diagram (see Figure 16-2). Added the TRGCONx and TRIGx registers (see Register 16-12 and Register 16-14, respectively). Section 21.0 “Enhanced CAN (ECAN™) Module (dsPIC33EPXXXGP/MC50X Devices Only)” Updated the CANCKS bit value definitions in CiCTRL1: ECAN Control Register 1 (see Register 21-1). Section 22.0 “Charge Time Measurement Unit (CTMU)” Updated the IRNG<1:0> bit value definitions and added Note 2 in the CTMU Current Control Register (see Register 22-3). Section 25.0 “Op amp/ Comparator Module” Updated the Op amp/Comparator I/O Operating Modes Diagram (see Figure 25-1). Updated the User-programmable Blanking Function Block Diagram (see Figure 25-3). Updated the Digital Filter Interconnect Block Diagram (see Figure 25-4). Added Section 25.1 “Op amp Application Considerations”. Added Note 2 to the Comparator Control Register (see Register 25-2). Updated the bit definitions in the Comparator Mask Gating Control Register (see Register 25-5). Section 27.0 “Special Features” Updated the FICD Configuration Register, updated Note 1, and added Note 3 in the Configuration Byte Register Map (see Table 27-1). Added Section 27.2 “User ID Words”. Section 30.0 “Electrical Characteristics” Updated the following Absolute Maximum Ratings: • Maximum current out of VSS pin • Maximum current into VDD pin Added Note 1 to the Operating MIPS vs. Voltage (see Table 30-1). Updated all Idle Current (IIDLE) Typical and Maximum DC Characteristics values (see Table 30-7). Updated all Doze Current (IDOZE) Typical and Maximum DC Characteristics values (see Table 30-9). Added Note 2, removed Parameter CM24, updated the Typical values Parameters CM10, CM20, CM21, CM32, CM41, CM44, and CM45, and updated the Minimum values for CM40 and CM41, and the Maximum value for CM40 in the AC/DC Characteristics: Op amp/Comparator (see Table 30-14). Updated Note 2 and the Typical value for Parameter VR310 in the Op amp/ Comparator Reference Voltage Settling Time Specifications (see Table 30-15). Added Note 1, removed Parameter VRD312, and added Parameter VRD314 to the Op amp/Comparator Voltage Reference DC Specifications (see Table 30-16). Updated the Minimum, Typical, and Maximum values for Internal LPRC Accuracy (see Table 30-22). Updated the Minimum, Typical, and Maximum values for Parameter SY37 in the Reset, Watchdog Timer, Oscillator Start-up Timer, Power-up Timer Timing Requirements (see Table 30-24). The Maximum Data Rate values were updated for the SPI2 Maximum Data/Clock Rate Summary (see Table 30-35) TABLE A-2: MAJOR SECTION UPDATES (CONTINUED) Section Name Update Description  2011-2013 Microchip Technology Inc. DS70000657H-page 511 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Section 30.0 “Electrical Characteristics” (Continued) These SPI2 Timing Requirements were updated: • Maximum value for Parameter SP10 and the minimum clock period value for SCKx in Note 3 (see Table 30-36, Table 30-37, and Table 30-38) • Maximum value for Parameter SP70 and the minimum clock period value for SCKx in Note 3 (see Table 30-40 and Table 30-42) • The Maximum Data Rate values were updated for the SPI2 Maximum Data/Clock Rate Summary (see Table 30-43) These SPI1 Timing Requirements were updated: • Maximum value for Parameters SP10 and the minimum clock period value for SCKx in Note 3 (see Table 30-44, Table 30-45, and Table 30-46) • Maximum value for Parameters SP70 and the minimum clock period value for SCKx in Note 3 (see Table 30-47 through Table 30-50) • Minimum value for Parameters SP40 and SP41 see Table 30-44 through Table 30-50) Updated all Typical values for the CTMU Current Source Specifications (see Table 30-55). Updated Note1, the Maximum value for Parameter AD06, the Minimum value for AD07, and the Typical values for AD09 in the ADC Module Specifications (see Table 30-56). Added Note 1 to the ADC Module Specifications (12-bit Mode) (see Table 30-57). Added Note 1 to the ADC Module Specifications (10-bit Mode) (see Table 30-58). Updated the Minimum and Maximum values for Parameter AD21b in the 10-bit Mode ADC Module Specifications (see Table 30-58). Updated Note 2 in the ADC Conversion (12-bit Mode) Timing Requirements (see Table 30-59). Updated Note 1 in the ADC Conversion (10-bit Mode) Timing Requirements (see Table 30-60). TABLE A-2: MAJOR SECTION UPDATES (CONTINUED) Section Name Update Description dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 512  2011-2013 Microchip Technology Inc. Revision D (December 2011) This revision includes typographical and formatting changes throughout the data sheet text. All other major changes are referenced by their respective section in Table A-3. TABLE A-3: MAJOR SECTION UPDATES Section Name Update Description “16-bit Microcontrollers and Digital Signal Controllers (up to 512-Kbyte Flash and 48-Kbyte SRAM) with HighSpeed PWM, Op amps, and Advanced Analog” Removed the Analog Comparators column and updated the Op amps/Comparators column in Table 1 and Table 2. Section 21.0 “Enhanced CAN (ECAN™) Module (dsPIC33EPXXXGP/MC50X Devices Only)” Updated the CANCKS bit value definitions in CiCTRL1: ECAN Control Register 1 (see Register 21-1). Section 30.0 “Electrical Characteristics” Updated the VBOR specifications and/or its related note in the following electrical characteristics tables: • Table 30-1 • Table 30-4 • Table 30-12 • Table 30-14 • Table 30-15 • Table 30-16 • Table 30-56 • Table 30-57 • Table 30-58 • Table 30-59 • Table 30-60  2011-2013 Microchip Technology Inc. DS70000657H-page 513 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Revision E (April 2012) This revision includes typographical and formatting changes throughout the data sheet text. All other major changes are referenced by their respective section in Table A-3. TABLE A-4: MAJOR SECTION UPDATES Section Name Update Description “16-bit Microcontrollers and Digital Signal Controllers (up to 512-Kbyte Flash and 48-Kbyte SRAM) with HighSpeed PWM, Op amps, and Advanced Analog” The following 512-Kbyte devices were added to the General Purpose Families table (see Table 1): • PIC24EP512GP202 • PIC24EP512GP204 • PIC24EP512GP206 • dsPIC33EP512GP502 • dsPIC33EP512GP504 • dsPIC33EP512GP506 The following 512-Kbyte devices were added to the Motor Control Families table (see Table 2): • PIC24EP512MC202 • PIC24EP512MC204 • PIC24EP512MC206 • dsPIC33EP512MC202 • dsPIC33EP512MC204 • dsPIC33EP512MC206 • dsPIC33EP512MC502 • dsPIC33EP512MC504 • dsPIC33EP512MC506 Certain Pin Diagrams were updated to include the new 512-Kbyte devices. Section 4.0 “Memory Organization” Added a Program Memory Map for the new 512-Kbyte devices (see Figure 4-4). Added a Data Memory Map for the new dsPIC 512-Kbyte devices (see Figure 4-11). Added a Data Memory Map for the new PIC24 512-Kbyte devices (see Figure 4-16). Section 7.0 “Interrupt Controller” Updated the VECNUM bits in the INTTREG register (see Register 7-7). Section 11.0 “I/O Ports” Added tip 6 to Section 11.5 “I/O Helpful Tips”. Section 27.0 “Special Features” The following modifications were made to the Configuration Byte Register Map (see Table 27-1): • Added the column Device Memory Size (Kbytes) • Removed Notes 1 through 4 • Added addresses for the new 512-Kbyte devices Section 30.0 “Electrical Characteristics” Updated the Minimum value for Parameter DC10 (see Table 30-4). Added Power-Down Current (Ipd) parameters for the new 512-Kbyte devices (see Table 30-8). Updated the Minimum value for Parameter CM34 (see Table 30-53). Updated the Minimum and Maximum values and the Conditions for paramteer SY12 (see Table 30-22). dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 514  2011-2013 Microchip Technology Inc. Revision F (November 2012) Removed “Preliminary” from data sheet footer. Revision G (March 2013) This revision includes the following global changes: • changes “FLTx” pin function to “FLTx” on all occurrences • adds Section 31.0 “High-Temperature Electrical Characteristics” for high-temperature (+150°C) data This revision also includes minor typographical and formatting changes throughout the text. Other major changes are referenced by their respective section in Table A-5. TABLE A-5: MAJOR SECTION UPDATES Section Name Update Description Cover Section • Changes internal oscillator specification to 1.0% • Changes I/O sink/source values to 12 mA or 6 mA • Corrects 44-pin VTLA pin diagram (pin 32 now shows as 5V tolerant) Section 4.0 “Memory Organization” • Deletes references to Configuration Shadow registers • Corrects the spelling of the JTAGIP and PTGWDTIP bits throughout • Corrects the Reset value of all IOCON registers as C000h • Adds footnote to Table 4-42 to indicate the absence of Comparator 3 in 28-pin devices Section 6.0 “Resets” • Removes references to cold and warm Resets, and clarifies the initial configuration of the device clock source on all Resets Section 7.0 “Interrupt Controller” • Corrects the definition of GIE as “Global Interrupt Enable” (not “General”) Section 9.0 “Oscillator Configuration” • Clarifies the behavior of the CF bit when cleared in software • Removes POR behavior footnotes from all control registers • Corrects the tuning range of the TUN<5:0> bits in Register 9-4 to an overall range ±1.5% Section 13.0 “Timer2/3 and Timer4/5” • Clarifies the presence of the ADC Trigger in 16-bit Timer3 and Timer5, as well as the 32-bit timers Section 15.0 “Output Compare” • Corrects the first trigger source for SYNCSEL<4:0> (OCxCON2<4:0>) as OCxRS match Section 16.0 “High-Speed PWM Module” • Clarifies the source of the PWM interrupts in Figure 16-1 • Corrects the Reset states of IOCONx<15:14> in Register 16-13 as ‘11’ Section 17.0 “Quadrature Encoder Interface (QEI) Module” • Clarifies the operation of the IMV<1:0> bits (QEICON<9:8>) with updated text and additional notes • Corrects the first prescaler value for QFVDIV<2:0> (QEI1OC<13:11>), now 1:128 Section 23.0 “10-Bit/12-Bit Analog-to-Digital Converter (ADC)” • Adds note to Figure 23-1 that Op Amp 3 is not available in 28-pin devices • Changes “sample clock” to “sample trigger” in AD1CON1 (Register 23-1) • Clarifies footnotes on op amp usage in Registers 23-5 and 23-6 Section 25.0 “Op Amp/ Comparator Module” • Adds Note text to indicate that Comparator 3 is unavailable in 28-pin devices • Splits Figure 25-1 into two figures for clearer presentation (Figure 25-1 for Op amp/ Comparators 1 through 3, Figure 25-2 for Comparator 4). Subsequent figures are renumbered accordingly. • Corrects reference description in xxxxx (now (AVDD+AVSS)/2) • Changes CMSTAT<15> in Register 25-1 to “PSIDL” Section 27.0 “Special Features” • Corrects the addresses of all Configuration bytes for 512 Kbyte devices  2011-2013 Microchip Technology Inc. DS70000657H-page 515 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X Section 30.0 “Electrical Characteristics” • Throughout: qualifies all footnotes relating to the operation of analog modules below VDDMIN (replaces “will have” with “may have”) • Throughout: changes all references of SPI timing parameter symbol “TscP” to “FscP” • Table 30-1: changes VDD range to 3.0V to 3.6V • Table 30-4: removes Parameter DC12 (RAM Retention Voltage) • Table 30-7: updates Maximum values at 10 and 20 MIPS • Table 30-8: adds Maximum IPD values, and removes all IWDT entries • Adds new Table 30-9 (Watchdog Timer Delta Current) with consolidated values removed from Table 30-8. All subsequent tables are renumbered accordingly. • Table 30-10: adds footnote for all parameters for 1:2 Doze ratio • Table 30-11: - changes Minimum and Maximum values for D120 and D130 - adds Minimum and Maximum values for D131 - adds Minimum and Maximum values for D150 through D156, and removes Typical values • Table 30-12: - reformats table for readability - changes IOL conditions for DO10 • Table 30-14: adds footnote to D135 • Table 30-17: changes Minimum and Maximum values for OS30 • Table 30-19: - splits temperature range and adds new values for F20a - reduces temperature range for F20b to extended temperatures only • Table 30-20: - splits temperature range and adds new values for F21a - reduces temperature range for F20b to extended temperatures only • Table 30-53: - adds Maximum value to CM30 - adds footnote (“Parameter characterized...”) to multiple parameters • Table 30-55: adds Minimum and Maximum values for all CTMUI specifications, and removes Typical values • Table 30-57: adds new footnote to AD09 • Table 30-58: - removes all specifications for accuracy with external voltage references - removes Typical values for AD23a and AD24a - replaces Minimum and Maximum values for AD21a, AD22a, AD23a and AD24a with new values, split by Industrial and Extended temperatures - removes Maximum value of AD30 - removes Minimum values from AD31a and AD32a - adds or changes Typical values for AD30, AD31a, AD32a and AD33a • Table 30-59: - removes all specifications for accuracy with external voltage references - removes Maximum value of AD30 - removes Typical values for AD23b and AD24b - replaces Minimum and Maximum values for AD21b, AD22b, AD23b and AD24b with new values, split by Industrial and Extended temperatures - removes Minimum and Maximum values from AD31b, AD32b, AD33b and AD34b - adds or changes Typical values for AD30, AD31a, AD32a and AD33a • Table 30-61: Adds footnote to AD51 Section 32.0 “DC and AC Device Characteristics Graphs” • Updates Figure 32-6 (Typical IDD @ 3.3V) with individual current vs. processor speed curves for the different program memory sizes Section 33.0 “Packaging Information” • Replaces drawing C04-149C (64-pin QFN, 7.15 x 7.15 exposed pad) with C04-154A (64-pin QFN, 5.4 x 5.4 exposed pad) TABLE A-5: MAJOR SECTION UPDATES (CONTINUED) Section Name Update Description dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 516  2011-2013 Microchip Technology Inc. Revision H (August 2013) This revision includes minor typographical and formatting changes throughout the text. Other major changes are referenced by their respective section in Table A-6. TABLE A-6: MAJOR SECTION UPDATES Section Name Update Description Cover Section • Adds Peripheral Pin Select (PPS) to allow Digital Function Remapping and Change Notification Interrupts to Input/Output section • Adds heading information to 64-Pin TQFP Section 4.0 “Memory Organization” • Corrects Reset values for ANSELE, TRISF, TRISC, ANSELC and TRISA • Corrects address range from 0x2FFF to 0x7FFF • Corrects DSRPAG and DSWPAG (now 3 hex digits) • Changes Call Stack Frame from <15:1> to PC<15:0> • Word length in Figure 4-20 is changed to 50 words for clarity Section 5.0 “Flash Program Memory” • Corrects descriptions of NVM registers Section 9.0 “Oscillator Configuration” • Removes resistor from Figure 9-1 • Adds Fast RC Oscillator with Divide-by-16 (FRCDIV16) row to Table 9-1 • Removes incorrect information from ROI bit in Register 9-2 Section 14.0 “Input Capture” • Changes 31 user-selectable Trigger/Sync interrupts to 19 user-selectable Trigger/ Sync interrupts • Corrects ICTSEL<12:10> bits (now ICTSEL<2:0>) Section 17.0 “Quadrature Encoder Interface (QEI) Module (dsPIC33EPXXXMC20X/50X and PIC24EPXXXMC20X Devices Only)” • Corrects QCAPEN bit description Section 19.0 “InterIntegrated Circuit™ (I2C™)” • Adds note to clarify that 100kbit/sec operation of I2C is not possible at high processor speeds Section 22.0 “Charge Time Measurement Unit (CTMU)” • Clarifies Figure 22-1 to accurately reflect peripheral behavior Section 23.0 “10-Bit/12-Bit Analog-to-Digital Converter (ADC)” • Correct Figure 23-1 (changes CH123x to CH123Sx) Section 24.0 “Peripheral Trigger Generator (PTG) Module” • Adds footnote to Register 24-1 (In order to operate with CVRSS=1, at least one of the comparator modules must be enabled. Section 25.0 “Op Amp/ Comparator Module” • Adds note to Figure 25-3 (In order to operate with CVRSS=1, at least one of the comparator modules must be enabled) • Adds footnote to Register 25-2 (COE is not available when OPMODE (CMxCON<10>) = 1) Section 27.0 “Special Features” • Corrects the bit description for FNOSC<2:0> Section 30.0 “Electrical Characteristics” • Corrects 512K part power-down currents based on test data • Corrects WDT timing limits based on LPRC oscillator tolerance Section 31.0 “HighTemperature Electrical Characteristics” • Adds Table 31-5 (DC Characteristics: Idle Current (IIDLE)  2011-2013 Microchip Technology Inc. DS70000657H-page 517 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X INDEX A Absolute Maximum Ratings .............................................. 401 AC Characteristics .................................................... 413, 471 10-Bit ADC Conversion Requirements ..................... 465 12-Bit ADC Conversion Requirements ..................... 463 ADC Module.............................................................. 459 ADC Module (10-Bit Mode)............................... 461, 473 ADC Module (12-Bit Mode)............................... 460, 473 Capacitive Loading Requirements on Output Pins ....................................................... 413 DMA Module Requirements...................................... 465 ECANx I/O Requirements......................................... 454 External Clock........................................................... 414 High-Speed PWMx Requirements ............................ 422 I/O Timing Requirements.......................................... 416 I2Cx Bus Data Requirements (Master Mode) ........... 451 I2Cx Bus Data Requirements (Slave Mode) ............. 453 Input Capture x Requirements .................................. 420 Internal FRC Accuracy.............................................. 415 Internal LPRC Accuracy............................................ 415 Internal RC Accuracy................................................ 472 Load Conditions................................................ 413, 471 OCx/PWMx Mode Requirements.............................. 421 Op Amp/Comparator Voltage Reference Settling Time Specifications.............................. 457 Output Compare x Requirements ............................. 421 PLL Clock.......................................................... 415, 471 QEI External Clock Requirements ............................ 423 QEI Index Pulse Requirements................................. 425 Quadrature Decoder Requirements.......................... 424 Reset, Watchdog Timer, Oscillator Start-up Timer, Power-up Timer Requirements......................... 417 SPI1 Master Mode (Full-Duplex, CKE = 0, CKP = x, SMP = 1) Requirements ................................... 441 SPI1 Master Mode (Full-Duplex, CKE = 1, CKP = x, SMP = 1) Requirements ................................... 440 SPI1 Master Mode (Half-Duplex, Transmit Only) Requirements ................................................... 439 SPI1 Maximum Data/Clock Rate Summary .............. 438 SPI1 Slave Mode (Full-Duplex, CKE = 0, CKP = 0, SMP = 0) Requirements.................... 449 SPI1 Slave Mode (Full-Duplex, CKE = 0, CKP = 1, SMP = 0) Requirements.................... 447 SPI1 Slave Mode (Full-Duplex, CKE = 1, CKP = 0, SMP = 0) Requirements.................... 443 SPI1 Slave Mode (Full-Duplex, CKE = 1, CKP = 1, SMP = 0) Requirements.................... 445 SPI2 Master Mode (Full-Duplex, CKE = 0, CKP = x, SMP = 1) Requirements ............................................ 429 SPI2 Master Mode (Full-Duplex, CKE = 1, CKP = x, SMP = 1) Requirements .................... 428 SPI2 Master Mode (Half-Duplex, Transmit Only) Requirements ................................................... 427 SPI2 Maximum Data/Clock Rate Summary .............. 426 SPI2 Slave Mode (Full-Duplex, CKE = 0, CKP = 0, SMP = 0) Requirements.................... 437 SPI2 Slave Mode (Full-Duplex, CKE = 0, CKP = 1, SMP = 0) Requirements ............................................ 435 SPI2 Slave Mode (Full-Duplex, CKE = 1, CKP = 0, SMP = 0) Requirements.................... 431 SPI2 Slave Mode (Full-Duplex, CKE = 1, CKP = 1, SMP = 0) Requirements.................... 433 Timer1 External Clock Requirements....................... 418 Timer2/Timer4 External Clock Requirements........... 419 Timer3/Timer5 External Clock Requirements........... 419 UARTx I/O Requirements......................................... 454 ADC Control Registers...................................................... 325 Helpful Tips............................................................... 324 Key Features ............................................................ 321 Resources ................................................................ 324 Arithmetic Logic Unit (ALU) ................................................ 44 Assembler MPASM Assembler .................................................. 398 B Bit-Reversed Addressing.................................................. 115 Example.................................................................... 116 Implementation ......................................................... 115 Sequence Table (16-Entry) ...................................... 116 Block Diagrams Data Access from Program Space Address Generation ................................. 117 16-Bit Timer1 Module ............................................... 203 ADC Conversion Clock Period ................................. 323 ADC with Connection Options for ANx Pins and Op Amps ................................................... 322 Arbiter Architecture................................................... 110 BEMF Voltage Measurement Using ADC................... 34 Boost Converter Implementation ................................ 32 CALL Stack Frame ................................................... 111 Comparator (Module 4) ............................................ 356 Connections for On-Chip Voltage Regulator ............ 384 CPU Core ................................................................... 36 CRC Module ............................................................. 373 CRC Shift Engine ..................................................... 374 CTMU Module .......................................................... 316 Digital Filter Interconnect.......................................... 357 DMA Controller ......................................................... 141 DMA Controller Module ............................................ 139 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X and PIC24EPXXXGP/MC20X ............................ 25 ECAN Module........................................................... 288 EDS Read Address Generation................................ 105 EDS Write Address Generation................................ 106 Example of MCLR Pin Connections ........................... 30 High-Speed PWMx Architectural Overview .............. 227 High-Speed PWMx Register Interconnection ........... 228 I2Cx Module ............................................................. 274 Input Capture x ......................................................... 213 Interleaved PFC.......................................................... 34 Multiphase Synchronous Buck Converter .................. 33 Multiplexing Remappable Output for RPn ................ 180 Op Amp Configuration A........................................... 358 Op Amp Configuration B........................................... 359 Op Amp/Comparator Voltage Reference Module..... 356 Op Amp/Comparator x (Modules 1, 2, 3).................. 355 Oscillator System...................................................... 153 Output Compare x Module ....................................... 219 PLL ........................................................................... 154 Programmer’s Model .................................................. 38 PTG Module ............................................................. 338 Quadrature Encoder Interface .................................. 250 Recommended Minimum Connection ........................ 30 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 518  2011-2013 Microchip Technology Inc. Remappable Input for U1RX..................................... 176 Reset System............................................................ 123 Shared Port Structure ...............................................173 Single-Phase Synchronous Buck Converter............... 33 SPIx Module.............................................................. 266 Suggested Oscillator Circuit Placement...................... 31 Type B Timer (Timer2 and Timer4)........................... 208 Type B/Type C Timer Pair (32-Bit Timer).................. 209 Type C Timer (Timer3 and Timer5) ..........................208 UARTx Module.......................................................... 281 User-Programmable Blanking Function .................... 357 Watchdog Timer (WDT) ............................................ 385 Brown-out Reset (BOR) .................................................... 384 C C Compilers MPLAB XC Compilers...............................................398 Charge Time Measurement Unit. See CTMU. Code Examples IC1 Connection to QEI1 Input on Pin 43 of dsPIC33EPXXXMC206 ..................... 176 Port Write/Read ........................................................ 174 PWMx Write-Protected Register Unlock Sequence.............................................. 226 PWRSAV Instruction Syntax..................................... 163 Code Protection ........................................................ 379, 386 CodeGuard Security.................................................. 379, 386 Configuration Bits.............................................................. 379 Description ................................................................ 381 Configuration Byte Register Map ...................................... 380 Configuring Analog and Digital Port Pins ..........................174 CPU Addressing Modes ...................................................... 35 Clocking System Options.......................................... 154 Fast RC (FRC) Oscillator.................................. 154 FRC Oscillator with PLL.................................... 154 FRC Oscillator with Postscaler ......................... 154 Low-Power RC (LPRC) Oscillator..................... 154 Primary (XT, HS, EC) Oscillator........................ 154 Primary Oscillator with PLL............................... 154 Control Registers ........................................................ 40 Data Space Addressing .............................................. 35 Instruction Set ............................................................. 35 Resources................................................................... 39 CTMU Control Registers ...................................................... 317 Resources................................................................. 316 Customer Change Notification Service ............................. 524 Customer Notification Service........................................... 524 Customer Support............................................................. 524 D Data Address Space ........................................................... 51 Memory Map for dsPIC33EP128MC20X/50X, dsPIC33EP128GP50X Devices .......................... 54 Memory Map for dsPIC33EP256MC20X/50X, dsPIC33EP256GP50X Devices .......................... 55 Memory Map for dsPIC33EP32MC20X/50X, dsPIC33EP32GP50X Devices ............................52 Memory Map for dsPIC33EP512MC20X/50X, dsPIC33EP512GP50X Devices .......................... 56 Memory Map for dsPIC33EP64MC20X/50X, dsPIC33EP64GP50X Devices ............................53 Memory Map for PIC24EP128GP/MC20X/50X Devices ............................................................... 59 Memory Map for PIC24EP256GP/MC20X/50X Devices............................................................... 60 Memory Map for PIC24EP32GP/MC20X/50X Devices............................................................... 57 Memory Map for PIC24EP512GP/MC20X/50X Devices............................................................... 61 Memory Map for PIC24EP64GP/MC20X/50X Devices............................................................... 58 Near Data Space ........................................................ 51 Organization, Alignment ............................................. 51 SFR Space ................................................................. 51 Width .......................................................................... 51 Data Memory Arbitration and Bus Master Priority........................... 110 Data Space Extended X ............................................................... 109 Paged Memory Scheme ........................................... 105 DC and AC Characteristics Graphs...................................................................... 475 DC Characteristics BOR.......................................................................... 411 CTMU Current Source Requirements....................... 458 Doze Current (IDOZE)........................................ 407, 469 High Temperature..................................................... 468 I/O Pin Input Specifications....................................... 408 I/O Pin Output Specifications............................ 411, 470 Idle Current (IIDLE) ............................................ 405, 469 Op Amp/Comparator Requirements ......................... 455 Op Amp/Comparator Voltage Reference Requirements ................................................... 457 Operating Current (IDD) .................................... 404, 469 Operating MIPS vs. Voltage ............................. 402, 468 Power-Down Current (IPD)................................ 406, 469 Program Memory...................................................... 412 Temperature and Voltage......................................... 468 Temperature and Voltage Specifications.................. 403 Thermal Operating Conditions.................................. 468 Watchdog Timer Delta Current................................. 407 Demo/Development Boards, Evaluation and Starter Kits................................................................ 400 Development Support ....................................................... 397 Third-Party Tools ...................................................... 400 DMA Controller Channel to Peripheral Associations.......................... 140 Control Registers...................................................... 141 DMAxCNT ........................................................ 141 DMAxCON........................................................ 141 DMAxPAD ........................................................ 141 DMAxREQ ........................................................ 141 DMAxSTA......................................................... 141 DMAxSTB......................................................... 141 Resources ................................................................ 141 Supported Peripherals.............................................. 139 Doze Mode ....................................................................... 165 DSP Engine ........................................................................ 44 E ECAN Message Buffers Word 0 ...................................................................... 310 Word 1 ...................................................................... 310 Word 2 ...................................................................... 311 Word 3 ...................................................................... 311 Word 4 ...................................................................... 312 Word 5 ...................................................................... 312 Word 6 ...................................................................... 313 Word 7 ...................................................................... 313  2011-2013 Microchip Technology Inc. DS70000657H-page 519 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X ECAN Module Control Registers ...................................................... 290 Modes of Operation .................................................. 289 Overview ................................................................... 287 Resources................................................................. 289 Electrical Characteristics................................................... 401 AC ..................................................................... 413, 471 Enhanced CAN (ECAN) Module ....................................... 287 Equations Device Operating Frequency .................................... 154 FPLLO Calculation...................................................... 154 FVCO Calculation....................................................... 154 Errata .................................................................................. 23 F Filter Capacitor (CEFC) Specifications............................... 403 Flash Program Memory .................................................... 119 Control Registers ...................................................... 120 Programming Operations.......................................... 120 Resources................................................................. 120 RTSP Operation........................................................ 120 Table Instructions...................................................... 119 Flexible Configuration ....................................................... 379 G Guidelines for Getting Started............................................. 29 Application Examples.................................................. 32 Basic Connection Requirements................................. 29 CPU Logic Filter Capacitor Connection (VCAP) .......... 30 Decoupling Capacitors................................................ 29 External Oscillator Pins............................................... 31 ICSP Pins.................................................................... 31 Master Clear (MCLR) Pin............................................ 30 Oscillator Value Conditions on Start-up ...................... 32 Unused I/Os................................................................ 32 H High-Speed PWM ............................................................. 225 Control Registers ...................................................... 230 Faults ........................................................................ 225 Resources................................................................. 229 High-Temperature Electrical Characteristics..................... 467 Absolute Maximum Ratings ...................................... 467 I I/O Ports............................................................................ 173 Helpful Tips............................................................... 181 Parallel I/O (PIO)....................................................... 173 Resources................................................................. 182 Write/Read Timing .................................................... 174 In-Circuit Debugger........................................................... 386 In-Circuit Emulation........................................................... 379 In-Circuit Serial Programming (ICSP) ....................... 379, 386 Input Capture .................................................................... 213 Control Registers ...................................................... 215 Resources................................................................. 214 Input Change Notification (ICN) ........................................ 174 Instruction Addressing Modes........................................... 112 File Register Instructions .......................................... 112 Fundamental Modes Supported................................ 112 MAC Instructions....................................................... 113 MCU Instructions ...................................................... 112 Move and Accumulator Instructions.......................... 113 Other Instructions...................................................... 113 Instruction Set Overview................................................................... 390 Summary .................................................................. 387 Symbols Used in Opcode Descriptions .................... 388 Inter-Integrated Circuit (I2C) ............................................. 273 Control Registers...................................................... 276 Resources ................................................................ 275 Internal RC Oscillator Use with WDT........................................................... 385 Internet Address ............................................................... 524 Interrupt Controller Control and Status Registers.................................... 131 INTCON1.......................................................... 131 INTCON2.......................................................... 131 INTCON3.......................................................... 131 INTCON4.......................................................... 131 INTTREG.......................................................... 131 Interrupt Vector Details............................................. 129 Interrupt Vector Table (IVT)...................................... 127 Reset Sequence ....................................................... 127 Resources ................................................................ 131 J JTAG Boundary Scan Interface........................................ 379 JTAG Interface ................................................................. 386 M Memory Maps Extended Data Space............................................... 109 Memory Organization ......................................................... 45 Resources .................................................................. 62 Microchip Internet Web Site.............................................. 524 Modulo Addressing........................................................... 114 Applicability............................................................... 115 Operation Example................................................... 114 Start and End Address ............................................. 114 W Address Register Selection.................................. 114 MPLAB Assembler, Linker, Librarian................................ 398 MPLAB ICD 3 In-Circuit Debugger ................................... 399 MPLAB PM3 Device Programmer .................................... 399 MPLAB REAL ICE In-Circuit Emulator System ................ 399 MPLAB X Integrated Development Environment Software .............................................. 397 MPLAB X SIM Software Simulator ................................... 399 MPLIB Object Librarian..................................................... 398 MPLINK Object Linker ...................................................... 398 O Op Amp Application Considerations ....................................... 358 Configuration A................................................. 358 Configuration B................................................. 359 Op Amp/Comparator......................................................... 355 Control Registers...................................................... 360 Resources ................................................................ 359 Open-Drain Configuration................................................. 174 Oscillator Control Registers...................................................... 156 Resources ................................................................ 155 Output Compare ............................................................... 219 Control Registers...................................................... 221 Resources ................................................................ 220 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 520  2011-2013 Microchip Technology Inc. P Packaging ......................................................................... 479 Details ....................................................................... 505 Marking ............................................................. 479, 481 Peripheral Module Disable (PMD)..................................... 165 Peripheral Pin Select (PPS).............................................. 175 Available Peripherals ................................................ 175 Available Pins ........................................................... 175 Control ......................................................................175 Control Registers ...................................................... 183 Input Mapping ........................................................... 176 Output Selection for Remappable Pins..................... 180 Pin Selection for Selectable Input Sources............... 178 Selectable Input Sources .......................................... 177 Peripheral Trigger Generator (PTG) Module..................... 337 PICkit 3 In-Circuit Debugger/Programmer ........................ 399 Pinout I/O Descriptions (table) ............................................ 26 Power-Saving Features..................................................... 163 Clock Frequency ....................................................... 163 Clock Switching......................................................... 163 Instruction-Based Modes .......................................... 163 Idle ....................................................................164 Interrupts Coincident with Power Save Instructions ...................................... 164 Sleep................................................................. 164 Resources................................................................. 165 Program Address Space .....................................................45 Construction.............................................................. 117 Data Access from Program Memory Using Table Instructions.............................................. 118 Memory Map (dsPIC33EP128GP50X, dsPIC33EP128MC20X/50X, PIC24EP128GP/MC20X Devices) ...................... 47 Memory Map (dsPIC33EP256GP50X, dsPIC33EP256MC20X/50X, PIC24EP256GP/MC20X Devices) ...................... 48 Memory Map (dsPIC33EP32GP50X, dsPIC33EP32MC20X/50X, PIC24EP32GP/MC20X Devices) ........................ 45 Memory Map (dsPIC33EP512GP50X, dsPIC33EP512MC20X/50X, PIC24EP512GP/MC20X Devices) ...................... 49 Memory Map (dsPIC33EP64GP50X, dsPIC33EP64MC20X/50X, PIC24EP64GP/MC20X Devices) ........................ 46 Table Read High Instructions TBLRDH............................................................ 118 Table Read Low Instructions (TBLRDL) ................... 118 Program Memory Organization................................................................ 50 Reset Vector ............................................................... 50 Programmable CRC Generator......................................... 373 Control Registers ...................................................... 375 Overview ................................................................... 374 Resources................................................................. 374 Programmer’s Model........................................................... 37 Register Descriptions.................................................. 37 PTG Control Registers ...................................................... 340 Introduction ............................................................... 337 Output Descriptions .................................................. 353 Resources................................................................. 339 Step Commands and Format.................................... 350 Q QEI Control Registers...................................................... 252 Resources ................................................................ 251 Quadrature Encoder Interface (QEI)................................. 249 R Register Maps ADC1 .......................................................................... 84 CPU Core (dsPIC33EPXXXMC20X/50X, dsPIC33EPXXXGP50X Devices) ....................... 63 CPU Core (PIC24EPXXXGP/MC20X Devices).......... 65 CRC............................................................................ 88 CTMU ......................................................................... 97 DMAC ......................................................................... 98 ECAN1 (When WIN (C1CTRL1) = 0 or 1) for dsPIC33EPXXXMC/GP50X Devices............. 85 ECAN1 (When WIN (C1CTRL1) = 0) for dsPIC33EPXXXMC/GP50X Devices.................. 85 ECAN1 (WIN (C1CTRL1) = 1) for dsPIC33EPXXXMC/GP50X Devices.................. 86 I2C1 and I2C2 ............................................................ 82 Input Capture 1 through Input Capture 4.................... 76 Interrupt Controller (dsPIC33EPXXXGP50X Devices) ...................... 69 Interrupt Controller (dsPIC33EPXXXMC20X Devices)...................... 71 Interrupt Controller (dsPIC33EPXXXMC50X Devices)...................... 73 Interrupt Controller (PIC24EPXXXGP20X Devices).......................... 66 Interrupt Controller (PIC24EPXXXMC20X Devices) ......................... 67 JTAG Interface ........................................................... 97 NVM............................................................................ 93 Op Amp/Comparator................................................... 97 Output Compare 1 through Output Compare 4 .......... 77 Peripheral Pin Select Input (dsPIC33EPXXXGP50X Devices) ...................... 91 Peripheral Pin Select Input (dsPIC33EPXXXMC20X Devices)...................... 92 Peripheral Pin Select Input (dsPIC33EPXXXMC50X Devices)...................... 91 Peripheral Pin Select Input (PIC24EPXXXGP20X Devices).......................... 90 Peripheral Pin Select Input (PIC24EPXXXMC20X Devices) ......................... 90 Peripheral Pin Select Output (dsPIC33EPXXXGP/MC202/502, PIC24EPXXXGP/MC202 Devices)..................... 88 Peripheral Pin Select Output (dsPIC33EPXXXGP/MC203/503, PIC24EPXXXGP/MC203 Devices)..................... 88 Peripheral Pin Select Output (dsPIC33EPXXXGP/MC204/504, PIC24EPXXXGP/MC204 Devices)..................... 89 Peripheral Pin Select Output (dsPIC33EPXXXGP/MC206/506, PIC24EPXXGP/MC206 Devices) ....................... 89 PMD (dsPIC33EPXXXGP50X Devices) ..................... 95 PMD (dsPIC33EPXXXMC20X Devices)..................... 96 PMD (dsPIC33EPXXXMC50X Devices)..................... 95 PMD (PIC24EPXXXGP20X Devices)......................... 94  2011-2013 Microchip Technology Inc. DS70000657H-page 521 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X PMD (PIC24EPXXXMC20X Devices)......................... 94 PORTA (PIC24EPXXXGP/MC202, dsPIC33EPXXXGP/MC202/502 Devices) ........ 104 PORTA (PIC24EPXXXGP/MC203, dsPIC33EPXXXGP/MC203/503 Devices) ........ 103 PORTA (PIC24EPXXXGP/MC204, dsPIC33EPXXXGP/MC204/504 Devices) ........ 102 PORTA (PIC24EPXXXGP/MC206, dsPIC33EPXXXGP/MC206/506 Devices) .......... 99 PORTB (PIC24EPXXXGP/MC202, dsPIC33EPXXXGP/MC202/502 Devices) ........ 104 PORTB (PIC24EPXXXGP/MC203, dsPIC33EPXXXGP/MC203/503 Devices) ........ 103 PORTB (PIC24EPXXXGP/MC204, dsPIC33EPXXXGP/MC204/504 Devices) ........ 102 PORTB (PIC24EPXXXGP/MC206, dsPIC33EPXXXGP/MC206/506 Devices) .......... 99 PORTC (PIC23EPXXXGP/MC203, dsPIC33EPXXXGP/MC203/503 Devices) ........ 103 PORTC (PIC24EPXXXGP/MC204, dsPIC33EPXXXGP/MC204/504 Devices) ........ 102 PORTC (PIC24EPXXXGP/MC206, dsPIC33EPXXXGP/MC206/506 Devices) .......... 99 PORTD (PIC24EPXXXGP/MC206, dsPIC33EPXXXGP/MC206/506 Devices) ........ 100 PORTE (PIC24EPXXXGP/MC206, dsPIC33EPXXXGP/MC206/506 Devices) ........ 100 PORTF (PIC24EPXXXGP/MC206, dsPIC33EPXXXGP/MC206/506 Devices) ........ 100 PORTG (PIC24EPXXXGP/MC206 and dsPIC33EPXXXGP/MC206/506 Devices) ........ 101 PTG............................................................................. 78 PWM (dsPIC33EPXXXMC20X/50X, PIC24EPXXXMC20X Devices)........................... 79 PWM Generator 1 (dsPIC33EPXXXMC20X/50X, PIC24EPXXXMC20X Devices)........................... 79 PWM Generator 2 (dsPIC33EPXXXMC20X/50X, PIC24EPXXXMC20X Devices)........................... 80 PWM Generator 3 (dsPIC33EPXXXMC20X/50X, PIC24EPXXXMC20X Devices)........................... 80 QEI1 (dsPIC33EPXXXMC20X/50X, PIC24EPXXXMC20X Devices)........................... 81 Reference Clock ......................................................... 93 SPI1 and SPI2 ............................................................ 83 System Control ........................................................... 93 Time1 through Time5.................................................. 75 UART1 and UART2 .................................................... 82 Registers AD1CHS0 (ADC1 Input Channel 0 Select) ............... 333 AD1CHS123 (ADC1 Input Channel 1, 2, 3 Select) ..................................... 331 AD1CON1 (ADC1 Control 1) .................................... 325 AD1CON2 (ADC1 Control 2) .................................... 327 AD1CON3 (ADC1 Control 3) .................................... 329 AD1CON4 (ADC1 Control 4) .................................... 330 AD1CSSH (ADC1 Input Scan Select High) .............. 335 AD1CSSL (ADC1 Input Scan Select Low)................ 336 ALTDTRx (PWMx Alternate Dead-Time) .................. 238 AUXCONx (PWMx Auxiliary Control)........................ 247 CHOP (PWMx Chop Clock Generator)..................... 234 CLKDIV (Clock Divisor)............................................. 158 CM4CON (Comparator 4 Control) ............................ 364 CMSTAT (Op Amp/Comparator Status) ................... 360 CMxCON (Comparator x Control, x = 1,2,3)............. 362 CMxFLTR (Comparator x Filter Control)................... 370 CMxMSKCON (Comparator x Mask Gating Control) ................................................. 368 CMxMSKSRC (Comparator x Mask Source Select Control).................................................. 366 CORCON (Core Control).................................... 42, 133 CRCCON1 (CRC Control 1) ..................................... 375 CRCCON2 (CRC Control 2) ..................................... 376 CRCXORH (CRC XOR Polynomial High) ................ 377 CRCXORL (CRC XOR Polynomial Low).................. 377 CTMUCON1 (CTMU Control 1)................................ 317 CTMUCON2 (CTMU Control 2)................................ 318 CTMUICON (CTMU Current Control)....................... 319 CVRCON (Comparator Voltage Reference Control) ........................................... 371 CxBUFPNT1 (ECANx Filter 0-3 Buffer Pointer 1) ............................................... 300 CxBUFPNT2 (ECANx Filter 4-7 Buffer Pointer 2) ............................................... 301 CxBUFPNT3 (ECANx Filter 8-11 Buffer Pointer 3) ............................................... 301 CxBUFPNT4 (ECANx Filter 12-15 Buffer Pointer 4) ............................................... 302 CxCFG1 (ECANx Baud Rate Configuration 1) ......... 298 CxCFG2 (ECANx Baud Rate Configuration 2) ......... 299 CxCTRL1 (ECANx Control 1) ................................... 290 CxCTRL2 (ECANx Control 2) ................................... 291 CxEC (ECANx Transmit/Receive Error Count) ........ 298 CxFCTRL (ECANx FIFO Control)............................. 293 CxFEN1 (ECANx Acceptance Filter Enable 1)......... 300 CxFIFO (ECANx FIFO Status) ................................. 294 CxFMSKSEL1 (ECANx Filter 7-0 Mask Selection 1)............................................. 304 CxFMSKSEL2 (ECANx Filter 15-8 Mask Selection 2)............................................. 305 CxINTE (ECANx Interrupt Enable) ........................... 297 CxINTF (ECANx Interrupt Flag)................................ 295 CxRXFnEID (ECANx Acceptance Filter n Extended Identifier) .......................................... 304 CxRXFnSID (ECANx Acceptance Filter n Standard Identifier)........................................... 303 CxRXFUL1 (ECANx Receive Buffer Full 1).............. 307 CxRXFUL2 (ECANx Receive Buffer Full 2).............. 307 CxRXMnEID (ECANx Acceptance Filter Mask n Extended Identifier) .......................................... 306 CxRXMnSID (ECANx Acceptance Filter Mask n Standard Identifier)........................................... 306 CxRXOVF1 (ECANx Receive Buffer Overflow 1)............................................. 308 CxRXOVF2 (ECANx Receive Buffer Overflow 2)............................................. 308 CxTRmnCON (ECANx TX/RX Buffer mn Control) ............................................ 309 CxVEC (ECANx Interrupt Code)............................... 292 DEVID (Device ID).................................................... 383 DEVREV (Device Revision)...................................... 383 DMALCA (DMA Last Channel Active Status) ........... 150 DMAPPS (DMA Ping-Pong Status) .......................... 151 DMAPWC (DMA Peripheral Write Collision Status)................................................ 148 DMARQC (DMA Request Collision Status) .............. 149 DMAxCNT (DMA Channel x Transfer Count)........... 146 DMAxCON (DMA Channel x Control)....................... 142 DMAxPAD (DMA Channel x Peripheral Address).......................................... 146 DMAxREQ (DMA Channel x IRQ Select) ................. 143 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 522  2011-2013 Microchip Technology Inc. DMAxSTAH (DMA Channel x Start Address A, High) ...................................... 144 DMAxSTAL (DMA Channel x Start Address A, Low)....................................... 144 DMAxSTBH (DMA Channel x Start Address B, High) ...................................... 145 DMAxSTBL (DMA Channel x Start Address B, Low)....................................... 145 DSADRH (DMA Most Recent RAM High Address) ...................................................147 DSADRL (DMA Most Recent RAM Low Address).................................................... 147 DTRx (PWMx Dead-Time) ........................................ 238 FCLCONx (PWMx Fault Current-Limit Control) ........ 243 I2CxCON (I2Cx Control) ........................................... 276 I2CxMSK (I2Cx Slave Mode Address Mask) ............ 280 I2CxSTAT (I2Cx Status) ........................................... 278 ICxCON1 (Input Capture x Control 1) ....................... 215 ICxCON2 (Input Capture x Control 2) ....................... 216 INDX1CNTH (Index Counter 1 High Word) .............. 259 INDX1CNTL (Index Counter 1 Low Word)................ 259 INDX1HLD (Index Counter 1 Hold)........................... 260 INT1HLDH (Interval 1 Timer Hold High Word).......... 264 INT1HLDL (Interval 1 Timer Hold Low Word) ........... 264 INT1TMRH (Interval 1 Timer High Word).................. 263 INT1TMRL (Interval 1 Timer Low Word)................... 263 INTCON1 (Interrupt Control 1).................................. 134 INTCON2 (Interrupt Control 2).................................. 136 INTCON2 (Interrupt Control 3).................................. 137 INTCON4 (Interrupt Control 4).................................. 137 INTTREG (Interrupt Control and Status)................... 138 IOCONx (PWMx I/O Control) .................................... 240 LEBCONx (PWMx Leading-Edge Blanking Control) .............................................. 245 LEBDLYx (PWMx Leading-Edge Blanking Delay).................................................246 MDC (PWMx Master Duty Cycle)..............................234 NVMADRH (Nonvolatile Memory Address High) ...... 122 NVMADRL (Nonvolatile Memory Address Low)........ 122 NVMCON (Nonvolatile Memory (NVM) Control).......121 NVMKEY (Nonvolatile Memory Key) ........................ 122 OCxCON1 (Output Compare x Control 1) ................ 221 OCxCON2 (Output Compare x Control 2) ................ 223 OSCCON (Oscillator Control) ................................... 156 OSCTUN (FRC Oscillator Tuning) ............................161 PDCx (PWMx Generator Duty Cycle) ....................... 237 PHASEx (PWMx Primary Phase-Shift) ..................... 237 PLLFBD (PLL Feedback Divisor)..............................160 PMD1 (Peripheral Module Disable Control 1)........... 166 PMD2 (Peripheral Module Disable Control 2)........... 168 PMD3 (Peripheral Module Disable Control 3)........... 169 PMD4 (Peripheral Module Disable Control 4)........... 169 PMD6 (Peripheral Module Disable Control 6)........... 170 PMD7 (Peripheral Module Disable Control 7)........... 171 POS1CNTH (Position Counter 1 High Word) ........... 258 POS1CNTL (Position Counter1 Low Word).............. 258 POS1HLD (Position Counter 1 Hold)........................ 258 PTCON (PWMx Time Base Control)......................... 230 PTCON2 (PWMx Primary Master Clock Divider Select 2)................................................ 232 PTGADJ (PTG Adjust) .............................................. 348 PTGBTE (PTG Broadcast Trigger Enable) ............... 343 PTGC0LIM (PTG Counter 0 Limit)............................346 PTGC1LIM (PTG Counter 1 Limit)............................347 PTGCON (PTG Control) ........................................... 342 PTGCST (PTG Control/Status)................................. 340 PTGHOLD (PTG Hold) ............................................. 347 PTGL0 (PTG Literal 0).............................................. 348 PTGQPTR (PTG Step Queue Pointer)..................... 349 PTGQUEx (PTG Step Queue x)............................... 349 PTGSDLIM (PTG Step Delay Limit) ......................... 346 PTGT0LIM (PTG Timer0 Limit)................................. 345 PTGT1LIM (PTG Timer1 Limit)................................. 345 PTPER (PWMx Primary Master Time Base Period)..................................................... 233 PWMCONx (PWMx Control)..................................... 235 QEI1CON (QEI1 Control) ......................................... 252 QEI1GECH (QEI1 Greater Than or Equal Compare High Word)........................................ 262 QEI1GECL (QEI1 Greater Than or Equal Compare Low Word) ........................................ 262 QEI1ICH (QEI1 Initialization/Capture High Word) ....................................................... 260 QEI1ICL (QEI1 Initialization/Capture Low Word) ........................................................ 260 QEI1IOC (QEI1 I/O Control) ..................................... 254 QEI1LECH (QEI1 Less Than or Equal Compare High Word)........................................ 261 QEI1LECL (QEI1 Less Than or Equal Compare Low Word) ........................................ 261 QEI1STAT (QEI1 Status).......................................... 256 RCON (Reset Control).............................................. 125 REFOCON (Reference Oscillator Control) ............... 162 RPINR0 (Peripheral Pin Select Input 0).................... 183 RPINR1 (Peripheral Pin Select Input 1).................... 184 RPINR11 (Peripheral Pin Select Input 11)................ 187 RPINR12 (Peripheral Pin Select Input 12)................ 188 RPINR14 (Peripheral Pin Select Input 14)................ 189 RPINR15 (Peripheral Pin Select Input 15)................ 190 RPINR18 (Peripheral Pin Select Input 18)................ 191 RPINR19 (Peripheral Pin Select Input 19)................ 191 RPINR22 (Peripheral Pin Select Input 22)................ 192 RPINR23 (Peripheral Pin Select Input 23)................ 193 RPINR26 (Peripheral Pin Select Input 26)................ 193 RPINR3 (Peripheral Pin Select Input 3).................... 184 RPINR37 (Peripheral Pin Select Input 37)................ 194 RPINR38 (Peripheral Pin Select Input 38)................ 195 RPINR39 (Peripheral Pin Select Input 39)................ 196 RPINR7 (Peripheral Pin Select Input 7).................... 185 RPINR8 (Peripheral Pin Select Input 8).................... 186 RPOR0 (Peripheral Pin Select Output 0).................. 197 RPOR1 (Peripheral Pin Select Output 1).................. 197 RPOR2 (Peripheral Pin Select Output 2).................. 198 RPOR3 (Peripheral Pin Select Output 3).................. 198 RPOR4 (Peripheral Pin Select Output 4).................. 199 RPOR5 (Peripheral Pin Select Output 5).................. 199 RPOR6 (Peripheral Pin Select Output 6).................. 200 RPOR7 (Peripheral Pin Select Output 7).................. 200 RPOR8 (Peripheral Pin Select Output 8).................. 201 RPOR9 (Peripheral Pin Select Output 9).................. 201 SEVTCMP (PWMx Primary Special Event Compare) ............................................... 233 SPIxCON1 (SPIx Control 1)...................................... 270 SPIxCON2 (SPIx Control 2)...................................... 272 SPIxSTAT (SPIx Status and Control) ....................... 268 SR (CPU STATUS)............................................. 40, 132 T1CON (Timer1 Control) .......................................... 205 TRGCONx (PWMx Trigger Control) ......................... 239 TRIGx (PWMx Primary Trigger Compare Value)...... 242 TxCON (Timer2 and Timer4 Control) ....................... 210  2011-2013 Microchip Technology Inc. DS70000657H-page 523 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X TyCON (Timer3 and Timer5 Control)........................ 211 UxMODE (UARTx Mode).......................................... 283 UxSTA (UARTx Status and Control)......................... 285 VEL1CNT (Velocity Counter 1)................................. 259 Resets............................................................................... 123 Brown-out Reset (BOR)............................................ 123 Configuration Mismatch Reset (CM)......................... 123 Illegal Condition Reset (IOPUWR)............................ 123 Illegal Opcode................................................... 123 Security............................................................. 123 Uninitialized W Register.................................... 123 Master Clear (MCLR) Pin Reset ............................... 123 Power-on Reset (POR)............................................. 123 RESET Instruction (SWR)......................................... 123 Resources................................................................. 124 Trap Conflict Reset (TRAPR).................................... 123 Watchdog Timer Time-out Reset (WDTO)................ 123 Resources Required for Digital PFC............................. 32, 34 Revision History ................................................................ 507 S Serial Peripheral Interface (SPI) ....................................... 265 Software Stack Pointer (SSP)........................................... 111 Special Features of the CPU ............................................ 379 SPI Control Registers ...................................................... 268 Helpful Tips............................................................... 267 Resources................................................................. 267 T Temperature and Voltage Specifications AC ..................................................................... 413, 471 Thermal Operating Conditions .......................................... 402 Thermal Packaging Characteristics .................................. 402 Timer1............................................................................... 203 Control Register........................................................ 205 Resources................................................................. 204 Timer2/3 and Timer4/5...................................................... 207 Control Registers ...................................................... 210 Resources................................................................. 209 Timing Diagrams 10-Bit ADC Conversion (CHPS<1:0> = 01, SIMSAM = 0, ASAM = 0, SSRC<2:0> = 000, SSRCG = 0)...................................................... 464 10-Bit ADC Conversion (CHPS<1:0> = 01, SIMSAM = 0, ASAM = 1, SSRC<2:0> = 111, SSRCG = 0, SAMC<4:0> = 00010) .................. 464 12-Bit ADC Conversion (ASAM = 0, SSRC<2:0> = 000, SSRCG = 0) ...................... 462 BOR and Master Clear Reset ................................... 416 ECANx I/O ................................................................ 454 External Clock........................................................... 414 High-Speed PWMx Fault .......................................... 422 High-Speed PWMx Module....................................... 422 I/O Characteristics .................................................... 416 I2Cx Bus Data (Master Mode) .................................. 450 I2Cx Bus Data (Slave Mode) .................................... 452 I2Cx Bus Start/Stop Bits (Master Mode)................... 450 I2Cx Bus Start/Stop Bits (Slave Mode)..................... 452 Input Capture x (ICx) ................................................ 420 OCx/PWMx............................................................... 421 Output Compare x (OCx).......................................... 421 QEA/QEB Input ........................................................ 424 QEI Module Index Pulse........................................... 425 SPI1 Master Mode (Full-Duplex, CKE = 0, CKP = x, SMP = 1) ........................................... 441 SPI1 Master Mode (Full-Duplex, CKE = 1, CKP = x, SMP = 1) ........................................... 440 SPI1 Master Mode (Half-Duplex, Transmit Only, CKE = 0)........................................................... 438 SPI1 Master Mode (Half-Duplex, Transmit Only, CKE = 1)........................................................... 439 SPI1 Slave Mode (Full-Duplex, CKE = 0, CKP = 0, SMP = 0)........................................... 448 SPI1 Slave Mode (Full-Duplex, CKE = 0, CKP = 1, SMP = 0)........................................... 446 SPI1 Slave Mode (Full-Duplex, CKE = 1, CKP = 0, SMP = 0)........................................... 442 SPI1 Slave Mode (Full-Duplex, CKE = 1, CKP = 1, SMP = 0)........................................... 444 SPI2 Master Mode (Full-Duplex, CKE = 0, CKP = x, SMP = 1) ........................................... 429 SPI2 Master Mode (Full-Duplex, CKE = 1, CKP = x, SMP = 1) ........................................... 428 SPI2 Master Mode (Half-Duplex, Transmit Only, CKE = 0)........................................................... 426 SPI2 Master Mode (Half-Duplex, Transmit Only, CKE = 1)........................................................... 427 SPI2 Slave Mode (Full-Duplex, CKE = 0, CKP = 0, SMP = 0)........................................... 436 SPI2 Slave Mode (Full-Duplex, CKE = 0, CKP = 1, SMP = 0)........................................... 434 SPI2 Slave Mode (Full-Duplex, CKE = 1, CKP = 0, SMP = 0)........................................... 430 SPI2 Slave Mode (Full-Duplex, CKE = 1, CKP = 1, SMP = 0)........................................... 432 Timer1-Timer5 External Clock.................................. 418 TimerQ (QEI Module) External Clock ....................... 423 UARTx I/O ................................................................ 454 U Universal Asynchronous Receiver Transmitter (UART) .................................................. 281 Control Registers...................................................... 283 Helpful Tips............................................................... 282 Resources ................................................................ 282 User ID Words .................................................................. 384 V Voltage Regulator (On-Chip) ............................................ 384 W Watchdog Timer (WDT)............................................ 379, 385 Programming Considerations ................................... 385 WWW Address ................................................................. 524 WWW, On-Line Support ..................................................... 23 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 524  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 525 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X THE MICROCHIP WEB SITE Microchip provides online support via our WWW site at www.microchip.com. This web site is used as a means to make files and information easily available to customers. Accessible by using your favorite Internet browser, the web site contains the following information: • Product Support – Data sheets and errata, application notes and sample programs, design resources, user’s guides and hardware support documents, latest software releases and archived software • General Technical Support – Frequently Asked Questions (FAQ), technical support requests, online discussion groups, Microchip consultant program member listing • Business of Microchip – Product selector and ordering guides, latest Microchip press releases, listing of seminars and events, listings of Microchip sales offices, distributors and factory representatives CUSTOMER CHANGE NOTIFICATION SERVICE Microchip’s customer notification service helps keep customers current on Microchip products. Subscribers will receive e-mail notification whenever there are changes, updates, revisions or errata related to a specified product family or development tool of interest. To register, access the Microchip web site at www.microchip.com. Under “Support”, click on “Customer Change Notification” and follow the registration instructions. CUSTOMER SUPPORT Users of Microchip products can receive assistance through several channels: • Distributor or Representative • Local Sales Office • Field Application Engineer (FAE) • Technical Support Customers should contact their distributor, representative or Field Application Engineer (FAE) for support. Local sales offices are also available to help customers. A listing of sales offices and locations is included in the back of this document. Technical support is available through the web site at: http://microchip.com/support DSPIC33EPXXXGP50X, DSPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 526  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 527 dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X PRODUCT IDENTIFICATION SYSTEM To order or obtain information, e.g., on pricing or delivery, refer to the factory or the listed sales office. Architecture: 33 = 16-bit Digital Signal Controller 24 = 16-bit Microcontroller Flash Memory Family: EP = Enhanced Performance Product Group: GP = General Purpose family MC = Motor Control family Pin Count: 02 = 28-pin 03 = 36-pin 04 = 44-pin 06 = 64-pin Temperature Range: I = -40C to+85C (Industrial) E = -40C to+125C (Extended) Package: ML = Plastic Quad, No Lead Package - (44-pin) 8x8 mm body (QFN) MM = Plastic Quad, No Lead Package - (28-pin) 6x6 mm body (QFN-S) MR = Plastic Quad, No Lead Package - (64-pin) 9x9 mm body (QFN) MV = Thin Quad, No Lead Package - (48-pin) 6x6 mm body (UQFN) PT = Plastic Thin Quad Flatpack - (44-pin) 10x10 mm body (TQFP) PT = Plastic Thin Quad Flatpack - (64-pin) 10x10 mm body (TQFP) SO = Plastic Small Outline, Wide - (28-pin) 7.50 mm body (SOIC) SP = Skinny Plastic Dual In-Line - (28-pin) 300 mil body (SPDIP) SS = Plastic Shrink Small Outline - (28-pin) 5.30 mm body (SSOP) TL = Very Thin Leadless Array - (36-pin) 5x5 mm body (VTLA) TL = Very Thin Leadless Array - (44-pin) 6x6 mm body (VTLA) Examples: dsPIC33EP64MC504-I/PT: dsPIC33, Enhanced Performance, 64-Kbyte Program Memory, Motor Control, 44-Pin, Industrial Temperature, TQFP package. Microchip Trademark Architecture Flash Memory Family Program Memory Size (Kbyte) Product Group Pin Count Temperature Range Package Pattern dsPIC 33 EP 64 MC5 04 T I / PT - XXX Tape and Reel Flag (if applicable) dsPIC33EPXXXGP50X, dsPIC33EPXXXMC20X/50X AND PIC24EPXXXGP/MC20X DS70000657H-page 528  2011-2013 Microchip Technology Inc. NOTES:  2011-2013 Microchip Technology Inc. DS70000657H-page 529 Information contained in this publication regarding device applications and the like is provided only for your convenience and may be superseded by updates. It is your responsibility to ensure that your application meets with your specifications. MICROCHIP MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WHETHER EXPRESS OR IMPLIED, WRITTEN OR ORAL, STATUTORY OR OTHERWISE, RELATED TO THE INFORMATION, INCLUDING BUT NOT LIMITED TO ITS CONDITION, QUALITY, PERFORMANCE, MERCHANTABILITY OR FITNESS FOR PURPOSE. Microchip disclaims all liability arising from this information and its use. Use of Microchip devices in life support and/or safety applications is entirely at the buyer’s risk, and the buyer agrees to defend, indemnify and hold harmless Microchip from any and all damages, claims, suits, or expenses resulting from such use. No licenses are conveyed, implicitly or otherwise, under any Microchip intellectual property rights. Trademarks The Microchip name and logo, the Microchip logo, dsPIC, FlashFlex, KEELOQ, KEELOQ logo, MPLAB, PIC, PICmicro, PICSTART, PIC32 logo, rfPIC, SST, SST Logo, SuperFlash and UNI/O are registered trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. FilterLab, Hampshire, HI-TECH C, Linear Active Thermistor, MTP, SEEVAL and The Embedded Control Solutions Company are registered trademarks of Microchip Technology Incorporated in the U.S.A. Silicon Storage Technology is a registered trademark of Microchip Technology Inc. in other countries. Analog-for-the-Digital Age, Application Maestro, BodyCom, chipKIT, chipKIT logo, CodeGuard, dsPICDEM, dsPICDEM.net, dsPICworks, dsSPEAK, ECAN, ECONOMONITOR, FanSense, HI-TIDE, In-Circuit Serial Programming, ICSP, Mindi, MiWi, MPASM, MPF, MPLAB Certified logo, MPLIB, MPLINK, mTouch, Omniscient Code Generation, PICC, PICC-18, PICDEM, PICDEM.net, PICkit, PICtail, REAL ICE, rfLAB, Select Mode, SQI, Serial Quad I/O, Total Endurance, TSHARC, UniWinDriver, WiperLock, ZENA and Z-Scale are trademarks of Microchip Technology Incorporated in the U.S.A. and other countries. SQTP is a service mark of Microchip Technology Incorporated in the U.S.A. GestIC and ULPP are registered trademarks of Microchip Technology Germany II GmbH & Co. KG, a subsidiary of Microchip Technology Inc., in other countries. All other trademarks mentioned herein are property of their respective companies. © 2011-2013, Microchip Technology Incorporated, Printed in the U.S.A., All Rights Reserved. Printed on recycled paper. ISBN: 9781620773949 Note the following details of the code protection feature on Microchip devices: • Microchip products meet the specification contained in their particular Microchip Data Sheet. • Microchip believes that its family of products is one of the most secure families of its kind on the market today, when used in the intended manner and under normal conditions. • There are dishonest and possibly illegal methods used to breach the code protection feature. All of these methods, to our knowledge, require using the Microchip products in a manner outside the operating specifications contained in Microchip’s Data Sheets. Most likely, the person doing so is engaged in theft of intellectual property. • Microchip is willing to work with the customer who is concerned about the integrity of their code. • Neither Microchip nor any other semiconductor manufacturer can guarantee the security of their code. Code protection does not mean that we are guaranteeing the product as “unbreakable.” Code protection is constantly evolving. We at Microchip are committed to continuously improving the code protection features of our products. Attempts to break Microchip’s code protection feature may be a violation of the Digital Millennium Copyright Act. If such acts allow unauthorized access to your software or other copyrighted work, you may have a right to sue for relief under that Act. Microchip received ISO/TS-16949:2009 certification for its worldwide headquarters, design and wafer fabrication facilities in Chandler and Tempe, Arizona; Gresham, Oregon and design centers in California and India. The Company’s quality system processes and procedures are for its PIC® MCUs and dsPIC® DSCs, KEELOQ® code hopping devices, Serial EEPROMs, microperipherals, nonvolatile memory and analog products. In addition, Microchip’s quality system for the design and manufacture of development systems is ISO 9001:2000 certified. QUALITY MANAGEMENT SYSTEM CERTIFIED BY DNV == ISO/TS 16949 == DS70000657H-page 530 .  2011-2013 Microchip Technology Inc. AMERICAS Corporate Office 2355 West Chandler Blvd. Chandler, AZ 85224-6199 Tel: 480-792-7200 Fax: 480-792-7277 Technical Support: http://www.microchip.com/ support Web Address: www.microchip.com Atlanta Duluth, GA Tel: 678-957-9614 Fax: 678-957-1455 Boston Westborough, MA Tel: 774-760-0087 Fax: 774-760-0088 Chicago Itasca, IL Tel: 630-285-0071 Fax: 630-285-0075 Cleveland Independence, OH Tel: 216-447-0464 Fax: 216-447-0643 Dallas Addison, TX Tel: 972-818-7423 Fax: 972-818-2924 Detroit Farmington Hills, MI Tel: 248-538-2250 Fax: 248-538-2260 Indianapolis Noblesville, IN Tel: 317-773-8323 Fax: 317-773-5453 Los Angeles Mission Viejo, CA Tel: 949-462-9523 Fax: 949-462-9608 Santa Clara Santa Clara, CA Tel: 408-961-6444 Fax: 408-961-6445 Toronto Mississauga, Ontario, Canada Tel: 905-673-0699 Fax: 905-673-6509 ASIA/PACIFIC Asia Pacific Office Suites 3707-14, 37th Floor Tower 6, The Gateway Harbour City, Kowloon Hong Kong Tel: 852-2401-1200 Fax: 852-2401-3431 Australia - Sydney Tel: 61-2-9868-6733 Fax: 61-2-9868-6755 China - Beijing Tel: 86-10-8569-7000 Fax: 86-10-8528-2104 China - Chengdu Tel: 86-28-8665-5511 Fax: 86-28-8665-7889 China - Chongqing Tel: 86-23-8980-9588 Fax: 86-23-8980-9500 China - Hangzhou Tel: 86-571-2819-3187 Fax: 86-571-2819-3189 China - Hong Kong SAR Tel: 852-2943-5100 Fax: 852-2401-3431 China - Nanjing Tel: 86-25-8473-2460 Fax: 86-25-8473-2470 China - Qingdao Tel: 86-532-8502-7355 Fax: 86-532-8502-7205 China - Shanghai Tel: 86-21-5407-5533 Fax: 86-21-5407-5066 China - Shenyang Tel: 86-24-2334-2829 Fax: 86-24-2334-2393 China - Shenzhen Tel: 86-755-8864-2200 Fax: 86-755-8203-1760 China - Wuhan Tel: 86-27-5980-5300 Fax: 86-27-5980-5118 China - Xian Tel: 86-29-8833-7252 Fax: 86-29-8833-7256 China - Xiamen Tel: 86-592-2388138 Fax: 86-592-2388130 China - Zhuhai Tel: 86-756-3210040 Fax: 86-756-3210049 ASIA/PACIFIC India - Bangalore Tel: 91-80-3090-4444 Fax: 91-80-3090-4123 India - New Delhi Tel: 91-11-4160-8631 Fax: 91-11-4160-8632 India - Pune Tel: 91-20-2566-1512 Fax: 91-20-2566-1513 Japan - Osaka Tel: 81-6-6152-7160 Fax: 81-6-6152-9310 Japan - Tokyo Tel: 81-3-6880- 3770 Fax: 81-3-6880-3771 Korea - Daegu Tel: 82-53-744-4301 Fax: 82-53-744-4302 Korea - Seoul Tel: 82-2-554-7200 Fax: 82-2-558-5932 or 82-2-558-5934 Malaysia - Kuala Lumpur Tel: 60-3-6201-9857 Fax: 60-3-6201-9859 Malaysia - Penang Tel: 60-4-227-8870 Fax: 60-4-227-4068 Philippines - Manila Tel: 63-2-634-9065 Fax: 63-2-634-9069 Singapore Tel: 65-6334-8870 Fax: 65-6334-8850 Taiwan - Hsin Chu Tel: 886-3-5778-366 Fax: 886-3-5770-955 Taiwan - Kaohsiung Tel: 886-7-213-7828 Fax: 886-7-330-9305 Taiwan - Taipei Tel: 886-2-2508-8600 Fax: 886-2-2508-0102 Thailand - Bangkok Tel: 66-2-694-1351 Fax: 66-2-694-1350 EUROPE Austria - Wels Tel: 43-7242-2244-39 Fax: 43-7242-2244-393 Denmark - Copenhagen Tel: 45-4450-2828 Fax: 45-4485-2829 France - Paris Tel: 33-1-69-53-63-20 Fax: 33-1-69-30-90-79 Germany - Munich Tel: 49-89-627-144-0 Fax: 49-89-627-144-44 Italy - Milan Tel: 39-0331-742611 Fax: 39-0331-466781 Netherlands - Drunen Tel: 31-416-690399 Fax: 31-416-690340 Spain - Madrid Tel: 34-91-708-08-90 Fax: 34-91-708-08-91 UK - Wokingham Tel: 44-118-921-5869 Fax: 44-118-921-5820 Worldwide Sales and Service 11/29/12

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 ::. The upper left cell is column 0, row 0. An example is given below. The Label Configuration for this table is: 0:0:LABEL A;1:0:LABEL B;0:1:LABEL C;0:2:LABEL D Only the Data cells have endpoints. The label text should not contain colons or semicolons to avoid confusing the Label Configuration parser. Endpoints are shown when the Show Endpoints option is selected. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 97 Configuration Table 3-15. Table Specific Parameters Parameter Type Usage Data Font Size Numeric Sets the size of the font in the data part of a cell Label Font Size Numeric Sets the size of the font in the label part of a cell Data Column Width Numeric Width of the data part of each cell. Note that changing this width will change the total width of the table. Label Column Width Numeric Width of the label part of each cell. Note that changing this width will change the total width of the table. Row Height Numeric Height if each row in the table. Note that changing this height will change the total height of the table. Number of Rows Numeric Number of rows in the table Number of Columns Numeric Number of columns in the table Auto Labels Checkbox Enables the Auto Labels mode. If disabled labels must be configured manually Label Configuration String String configuring the labels when using Manual Labels mode (Auto Labels option disabled). Format is ::;::... Data Bold Checkbox Sets bold style of the font in the data part of each cell Data Italic Checkbox Sets italic style of the font in the data part of each cell Label Bold Checkbox Sets bold style of the font in the label part of each cell Label Italic Checkbox Sets italic style of the font in the label part of each cell Background Color Color Sets the background color of the table Foreground Color Color Sets the color of the table grid and the data and label text Label Horizontal Alignment Drop-down box Selects the placement of the text in the label part of each cell (Left, Center, or Right) Data Horizontal Alignment Drop-down box Selects the placement of the text in the data part of each cell (Left, Center, or Right) 3.5.2 Dashboard Configuration Example This section gives an example on how to configure the Dashboard module. Although the example utilizes only a subset of the available dashboard elements data sources available in the Data Visualizer, the basic principles are applicable to all elements and data sources. This example uses manual configuration of the Dashboard module, but it is also possible to use the Atmel Data Protocol (ADP) to set up a dashboard automatically. For more information on ADP and an example of a automatically configured dashboard, see Atmel Data Protocol. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 98 The target application code used in this example and a description of the hardware setup can be found in Dashboard Example Code. To do:  • Open the configuration panel • Add a new I/O Dashboard component by double-clicking the I/O Dashboard module To do:  • Enable editing the dashboard by clicking the Edit option in the lower left corner of the Dashboard I/O module • Open the Elements panel in the upper right corner of the dashboard and drag elements onto the dashboard. Tip:  To remove an element from the dashboard, select it by left-clicking it, and then right-click the element. Tip:  Changing the parameters in the Configuration section will not take effect until the Set button is clicked. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 99 In this example, three Label elements are added, one as a title for the dashboard and the two others as help text for the slider. A Graph element with one plot was added to be used for the light sensor data. The Y Minimum and Y Maximum values were set to 0 and 255, respectively. A Signal element was added to be able to see which mode is active. When the Night mode is active the signal turns dark blue (Color On) and when the Night mode is inactive the signal turns yellow (Color Off). Finally, a slider was added to make it possible to adjust the Night mode threshold. The Minimum was set to 0 and the Maximum was set to 255. Moving the slider to the left lowers the threshold and results in the Night mode being active at brighter light levels. When the dashboard has been set up it is time to connect the dashboard to the serial interfaces to enable communication with the target application. Before the endpoints in the dashboard can be hooked up, the interfaces between the target board and the host computer must be configured. This example uses the DGI SPI interface and the CDC USART interface. The CDC interface will appear on the host computer as an ordinary serial COM port. To do:  Select correct tool in the DGI Control Panel. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 100 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 101 To do:  • Open the Serial Port Control panel found under External Connection in the Modules section of the Configuration tab in Data Visualizer 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:  • Deselect the Edit option • Click the Show Endpoints option • Drag the SPI source to the graph sink • Drag the serial port source to the signal sink • Drag the slider source to the serial port sink Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 102 Now the dashboard is fully configured and can be used to interact with the Night mode switch application. To do:  • Deselect the Show Endpoints option • Click Start in the DGI Control Panel • Click Connect in the Serial Port Control Panel Now the ADC raw values are shown in the graph and the slider can be adjusted to a suitable threshold for the Night mode switch. The signal element shows the state of the switch. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 103 4. Utilities Utilities are modules that do not fit in the other categories, but are still helpful for analyzing data. The Samplerate Counter provides a measure of how much data is being transmitted. The File Logger module stores incoming data in a file of selectable format. The file contents can then be analyzed in another application. 4.1 Samplerate Counter The samplerate counter module takes an incoming data stream and measures the amount of incoming samples in the stream. To use the samplerate counter simply connect a source to the sink of the samplerate counter module and start the data stream. The samplerate counter can be used with streams of any data type. 4.2 File Logger The File Logger module logs all incoming data to a file of selectable format. Figure 4-1. File Logging 1 2 3 4 1. Output file selection box. 2. Output format selection box. 3. Input sink. 4. Start/Stop button.  4.2.1 Logging to a Binary File • Select output format “BIN” in the Output format selection box • Set the output file by pressing the “...” button in the Output file selection box and selecting a path and name • Connect an external source to the input sink • Press the Start button to begin logging. The button will be replaced by the Stop button. • Press the Stop button to close the file and end logging before inspecting the logged data Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 104 5. Protocols Most communication interfaces use streams of bytes to transfer data. This is enough for single data values of 8-bit precision, but when multiple values are required to be transmitted over the same interface, data must be packed in a protocol. The Data Visualizer supports two such protocols. The Data Stream protocol is using a light-weight framing format to pack several numerical values over one interface. It is only capable of handling incoming data and it only supports synchronous streams (i.e., every data packet must contain one sample from each data stream). The Atmel Data Protocol (ADP) enables streaming of data in both directions. ADP is, in general, more flexible than the Data Stream protocol and it also supports asynchronous streams (i.e., data samples from each data stream can be sent independently). Both protocols can be automatically detected and used to automatically configure the Data Visualizer by defining data streams, configuring a Dashboard and connect the data streams to the Dashboard elements. The main difference is that for the Data Stream protocol, the configuration settings reside in configuration files on the host computer while for ADP the configuration settings are sent from the target application to the host computer. In addition, ADP can configure Graph and Terminal views. The Graph element in the Dashboard view is supported by both protocols. Table 5-1. Protocol Comparison Data Stream Protocol Atmel Data Protocol (ADP) Comment Complexity Simple/Lightweight Complex/Flexible Start/Stop individual streams - X Data input X X Data transmission from target application to host computer Data output - X Data transmission from host computer to target application Support String data type - X Various length strings Configuration settings stored on host computer X - Configuration of Data Visualizer GUI Configuration settings stored in target application - X Configuration of Data Visualizer GUI Dashboard View configuration X X Graph View configuration - X Terminal View configuration - X Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 105 Data Stream Protocol Atmel Data Protocol (ADP) Comment Data bursts - X More than one sample of a data stream can be sent in one package Asynchronous data streams - X Samples from different data streams can be sent independently X = Supported - = Not supported 5.1 Data Stream Protocol The data stream module takes an incoming raw data stream and splits it into multiple data streams. The data stream format is specified by a configuration file provided by the user. 5.1.1 Configuration Format The configuration file is a comma-delimited text file that specifies one data variable per line. Each line starts by specifying the data format of the variable by one of the tags presented in the table below. The position of the variable in the output grid is then given by two coordinates starting at index 1. The final parameter assigns a text string to the variable. Table 5-2. Data Stream Types Type Size Tag Example Unsigned byte 1 B B,1,1,Light Signed byte 1 -B -B,1,1,Encoder Unsigned short 2 D D,1,1,ADC Signed short 2 -D -D,1,1,ADC Unsigned word 4 W W,1,1,Transfer rate Signed word 4 -W -W,1,1,Status code Floating point 4 F F,1,1,Temperature Double-precision floating point 8 DF DF,1,1,Measurement Grid of unsigned bytes 1 * W * D GB GB<10x10>,1,1,Surface Grid of signed bytes 1 * W * D -GB -GB<10x10>,1,1,Surface Grid of unsigned short 2 * W * D GD GD<10x10>,1,1,Surface Grid of signed short 2 * W * D -GD -GD<10x10>,1,1,Surface Grid of unsigned word 4 * W * D GW GW<10x10>,1,1,Surface Grid of signed word 4 * W * D -GW -GW<10x10>,1,1,Surface Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 106 Type Size Tag Example Grid of floating point 8 * W * D GF GF<10x10>,1,1,Surface Grid of double-precision floating point 8 * W * D GDF GDF<10x10>,1,1,Surface This is an example configuration: D,1,1,ADC0 D,1,2,ADC1 D,1,3,ADC2 B,2,1,Prescaler 5.1.2 Stream Format The data stream is processed in the same order as the configuration file specifies. All data must be given as little endian values, meaning that the lowest byte must be sent first. Additionally, a wrapper consisting of one byte before and one byte after the data stream variables must be added. This wrapper is used by the interpreter to synchronize to the data stream. The start byte can be of an arbitrary value except 0x5F, which is reserved for Auto-Configuration, but the end byte must be the inverse of the Start byte. For more information on the Auto-Configuration feature see Auto-Configuration and Auto-Configuration Example. The configuration file shall not define the start and end bytes. Consider the example configuration given in the previous section. The figure below gives an example raw data transmission where ADC0 is 185, ADC1 is 950, ADC2 is 0, and Prescaler is 2. Figure 5-1. Data Streamer Start ADC0 ADC1 ADC2 Prescaler End … 0x03 0xB9 0x00 0xB6 0x03 0x00 0x00 0x02 0xFC … 5.1.3 Basic Usage Figure 5-2. Data Streamer • Press the Open file button (3) • Select the configuration file • Click the Load configuration button (4) • Connect the input sink (5) • Connect one or more output source to a desired sink (1) 5.1.4 Auto-Configuration The Data Stream format can be used to automatically configure the Data Visualizer based on some predefined configuration files. This differs from the Atmel Data Protocol (ADP) auto-configuration where the configuration settings are stored in the target application and sent to the host upon request. The Data Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 107 Stream auto-configuration is limited to setting up a data stream, configure a Dashboard View and connect the data stream output sources to the dashboard elements. 5.1.5 Auto-Configuration Example The purpose of this example is to show how to set up the configuration files required to automatically configure a dashboard with a signal showing the state of a pushbutton on the target hardware and a graph showing the value of a counter in the target application. The screenshot below shows the final dashboard. The target code used in this example can be found in Auto-Configuration Example Code. Three files are required by the Data Visualizer to enable Auto-Configuration, a .ds file describing the data stream content, a .db file describing the dashboard and a .sc file describing the connections between the data stream content and the dashboard elements. All files should be named "C0FFEEC0FFEEC0FFEEC0FFEE" before the extension to match the Auto Configuration ID sent by the application code. The example application generates a data stream with two stream components, an unsigned 16-bit value and an unsigned 8-bit value. To do:  • Create a file called "C0FFEEC0FFEEC0FFEEC0FFEE.ds" and add the content below D,1,1,count B,2,1,button The .ds file will create a table with two sources from the data stream. Column 1 row 1 will contain a source with unsigned 16-bit values named "count" and column 2, row 1 will contain a source with Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 108 unsigned 8-bit values named "button". For more information on the .ds file format see Configuration Format. The easiest way to set up a dashboard for the Auto-Configuration is to draw it in the Data Visualizer GUI and save the configuration to file. To do:  • Open the configuration panel • Add a new I/O Dashboard component by double-clicking the I/O Dashboard module To do:  • Enable editing the dashboard by clicking the Edit option in the lower left corner of the Dashboard I/O module • Open the Elements panel in the upper right corner of the dashboard and drag elements onto the dashboard. Tip:  To remove an element from the dashboard, select it by left-clicking it, and then right-click the element. Tip:  Changing the parameters in the Configuration section will not take effect until the Set button is clicked. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 109 To do:  • Drag a Label element to the dashboard • Select the Label element and set Font Size to 16, Tick the Bold option, set Text field to “Button State” and set Width to 100. • Push Set Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 110 To do:  • Drag a Signal element to the Dashboard and put it below the Button State label • Drag a Graph element to the Dashboard and put it to the right of the Button State label and signal • Select the Graph element and set Title to “count value”, X Maximum to 5, Y Maximum to 66000 • Click Set Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 111 To do:  • Click Save Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 112 To do:  • Save the Dashboard configuration as “C0FFEEC0FFEEC0FFEEC0FFEE.db” in the same folder as the .ds file The .db file content should have content similar to: { 0, '\0', 0, 255, 255, 255, 44, 1, }; { 0, // Dashboard ID 0, // Element ID DB_TYPE_LABEL, // Element Type 0, // Z-Index (GUI stack order) 63, 0, // X-coordinate 48, 0, // Y-coordinate 100, 0, // Width 22, 0, // Height 16, // Font Size 1, 0, // Horizontal Alignment 0, // Vertical Alignment 0, 255, 255, 255, // Background Color 255, 0, 0, 0, // Foreground Color 'B', 'u', 't', 't', 'o', 'n', ' ', 'S', 't', 'a', 't', 'e', '\0', // Text }; { 0, // Dashboard ID 1, // Element ID DB_TYPE_SIGNAL, // Element Type 0, // Z-Index (GUI stack order) 98, 0, // X-coordinate Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 113 78, 0, // Y-coordinate 25, 0, // Width 25, 0, // Height 255, 0, 255, 0, // Color On 255, 255, 0, 0, // Color Off }; { 0, // Dashboard ID 2, // Element ID DB_TYPE_GRAPH, // Element Type 0, // Z-Index (GUI stack order) 206, 0, // X-coordinate 12, 0, // Y-coordinate 64, 1, // Width 240, 0, // Height 255, 255, 255, // Title color 0, 0, 0, // Background color 20, 20, 20, // Graph background color 'c', 'o', 'u', 'n', 't', ' ', 'v', 'a', 'l', 'u', 'e', '\0', // Title 1, // Number of plots 0,0,0,0, // X Minimum 0,0,160,64, // X Maximum 0,0,0,0, // Y Minimum 0,232,128,71, // Y Maximum 1, 1, }; For more information on the Dashboard elements, see Element Types. Finally, the configuration file to connect the data stream sources defined in the .ds file to the Dashboard elements defined in the .db file must be made. To do:  • Create a file called “C0FFEEC0FFEEC0FFEEC0FFEE.sc” in the same folder as the other config files and add the content below: button,1 count,2 The .sc file will connect the stream source named “button” to the Dashboard element with ID 1 (the Signal element) and the stream source named “count” to the Dashboard element with ID 2 (the Graph element). Then it is time to run the example. To do:  • Close the Dashboard panel 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 114 To do:  • Select the correct COM port corresponding to the connected kit • Make sure Autodetect protocols option is checked and the Parity and Stop bits configurations are set according to the target application. The Baud rate will be detected automatically. To do:  • Click Connect • If Data Visualizer cannot find the configuration files for the detected Auto-Configuration ID it will show a pop-up asking for the path to the configuration files. Browse to the folder where the configuration files reside and click OK Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 115 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. After connecting and detecting the Auto-Configuration ID the Data Visualizer should create a Data Stream Control Panel and a Dashboard I/O looking something like the image below. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 116 The Graph element shows a running sawtooth signal which represents the counter continuously counting up until it wraps. The Signal element shows the state of the push button on the ATtiny104 Xplained Nano board. Pushing the button changes the color of the Signal element from red to green. Expanding the Data Stream Control Panel by clicking the down arrow to the right in the panel shows the content of the automatically configured Data Stream. The stream has two sources, one for the counter value and one for the button state. Expanding the Serial Port Control Panel shows that Data Visualizer detected the baud rate to be 38400. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 117 5.1.6 Auto-Configuration Format If the start byte of a Data Stream packet is 0x5F then this packet is a special Configuration packet. Table 5-3. Configuration Packet Format Field Size Values Description Start token 1 byte 0x5F Start token reserved for configuration packets. Checksum format 4 bytes 0xB4 0x00 0x86 0x4A Specifies the checksum format to be used. Currently only LRC8 is supported. Configuration identifier 12 bytes Any value Unique identifier for the configuration. Checksum 1 byte Checksum according to Checksum format Currently only LRC8 checksum format is supported. This is the XOR sum of the packet excluding the start token, the checksum itself and the end token. End token 1 byte 0xA0 Following the Data Stream format the end token is the inverse of the start token. The identifier given in the Configuration packet is used by Data Visualizer to look-up the corresponding configuration files used to configure the Data Visualizer. Three configuration files are needed: • A .ds file defining the Data Stream. This is a normal Data Stream format file and follows the format given in Configuration Format. • A .db file defining the Dashboard. This file follows the format of the files generated when saving a Dashboard to file, see Edit Panel. • A .sc file defining the connections between the Data Stream components defined in the .ds file and the elements of the Dashboard defined in the .db file. The format is defined in Signal Connections File Format. All three configuration files should have a name equal to the hex values of each Configuration identifier byte. As an example, a Configuration identifier of [0x12, 0x34, 0x56, 0x78, 0x9A, 0xBC, 0xDE, 0xF0, 0x12, 0x34, 0x56, 0x78] corresponds to configuration files named 123456789ABCDEF012345678.sc, 123456789ABCDEF012345678.db and 123456789ABCDEF012345678.ds. The Data Streamer Auto-Configuration feature is available both in the DGI Control Panel for all DGI serial interfaces and in the Serial Port Control Panel for COM ports and Virtual COM ports (CDC interface) 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 118 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 5-4. 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. 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. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 119 Important:  All three configuration files must reside in the same folder. 5.1.7 Signal Connections File Format A signal connections file has the file extension .sc and it specifies the connections between the data stream sources defined in a .ds file and the GUI elements in the Dashboard defined in a .db file. The .sc file format is a comma-delimited text file specifying one connection per line. Each line follows the format , . The Stream name is defined in the .ds file and is the text string assigned to each data variable. The Element ID is defined in the .db file for each Dashboard Element. An example of a .sc file content: Plane,0 Delta1,2 Delta2,2 A stream called Plane is connected to an Element with ID 0 and both streams Delta1 and Delta2 are connected to an Element with ID 2. For a full auto-configuration example, see Auto-Configuration Example. The Table Element (see Table) has some extra parameters in addition to the Stream name and Element ID. The column and row of the cell to connect the signal to is given by appending (Column:;Row:) to the lines in the .sc file. The upper left cell is specified by column 0 and row 0. As an example the table is connected to sources by the following .sc file content: Delta1,2(Column:1;Row:1) Delta2,2(Column:1;Row:2) Delta3,2(Column:1;Row:3) Delta4,2(Column:1;Row:4) Delta5,2(Column:1;Row:5) Delta6,2(Column:1;Row:6) Delta7,2(Column:1;Row:7) Delta8,2(Column:1;Row:8) Delta9,2(Column:1;Row:9) Delta10,2(Column:1;Row:10) Note that in the example the Table element is in Auto-Labels mode so each cell has two fields; a label to the left and the actual data to the right. For more information, see Auto Labels. The Graph Element (see Graph) also supports an extra parameter in addition to the Stream name and Element ID. By default, all plots are visible in the Graph element but they can be hidden or shown by the Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 120 user clicking the legend in the Graph view corresponding to a plot. The extra parameter supported makes it possible to change the default behavior to hide plots when doing auto-configuration. This is done by appending (visible:0) to the .sc file. As an example, see the following .sc file Delta1,2(visible:0) Delta2,2 Delta3,2(visible:0) Delta4,2 Delta5,2 Delta6,2 Delta7,2(visible:0) Delta8,2(visible:0) Delta9,2 Delta10,2 results in the graph element looking like this: In the graph the plots named Delta1, Delta3, Delta7, and Delta8 are all hidden and the legends are gray. The user can enable them by clicking the legends. In the same way the visible plots can be hidden by the user clicking the corresponding legends. 5.2 Atmel Data Protocol 5.2.1 Transfer using Atmel Data Protocol The Atmel Data Protocol (ADP) is a content independent protocol intended for transferring data from a target MCU to a host PC through an EDBG-based debugger (EDBG, Atmel-ICE, Power Debugger) using the Data Gateway Interface (DGI, see Embedded Debuggerʼs Data Gateway Interface) or directly to the host computer using a serial port. ADP is content independent and the transfer through the debugger is transparent, meaning that the content is not interpreted by the debugger. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 121 Transferring a single value is quite simple. But to transfer more than one value, they have to be wrapped in some kind of protocol that both the sender and receiver understands. ADP is such a protocol. If the MCU wraps all its data into an ADP packet, it can be decoded in the Data Visualizer and split into separate data streams. Figure 5-3. An ADP Transfer In the figure above, the MCU packs a temperature and a pressure variable inside an ADP packet. In the Data Visualizer, the SPI endpoints in the DGI Control Panel are now connected to the Data endpoints of an ADP Control Panel. The ADP Control Panel will decode the packets into separate temperature and pressure data streams. They can then be connected to two plot lines in the Graph module. The ADP protocol supports data transfer in both directions. In addition, the MCU can send configuration packets describing what modules should be opened in the Data Visualizer, and how to connect them. When the target board is connected to the host computer everything will be configured automatically. 5.2.2 ADP Example For an example of ADP protocol usage, the ADP example application for SAM D21 Xplained Pro can be used. This example can be found in Atmel Software Framework (ASF) in Atmel Studio. It uses a SAM D21 Xplained Pro together with an I/O Xplained Pro board. This example uses the Data Gateway Interface (DGI), see the Embedded Debuggerʼs Data Gateway Interface on the Embedded Debugger (EDBG), but any serial port is sufficient. 5.2.2.1 Requirements • Host computer with Atmel Studio 7 (or later) installed (Data Visualizer is included) • SAM D21 Xplained Pro kit • I/O1 Xplained Pro extension Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 122 5.2.2.2 Hardware Setup To run the example the following hardware setup is required: • I/O1 Xplained Pro extension connected to SAM D21 Xplained Pro EXT1 connector • USB cable connected from host PC to DEBUG USB connector on SAM D21 Xplained Pro A picture of the setup is shown below. 5.2.2.3 Run Example To run the ADP example follow the steps below. To do:  • Open Atmel Studio • Select File → New → Example Project • Browse to, or search for the ADP example application - SAM D21 Xplained Pro and select it • Choose the preferred folder and give the project a name, then click OK to create the project The project will be generated, then it is just a matter of compiling it and programming it into the target board. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 123 To do:  • Open the project properties (right click the project in the Solution Explorer and select Properties) • On the Tool tab, select the appropriate tool and interface To do:  • Click Start Without Debugging (Debug → Start Without Debugging) To do:  Open the Data Visualizer as an extension inside Atmel Studio by selecting it in the Tools menu. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 124 To do:  • In the DGI Control Panel, select SAM D21 Xplained Pro • Select the Autodetect protocols box • Click Connect You should see something like the screenshot below in the Data Visualizer. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 125 5.2.2.4 How it Works As the code for the ADP example is quite extensive, it will not make sense to list it or describe all the details. Especially, details on how to set up the required peripherals on the ATSAMD21 will be left out. The ADP messages required to create the ADP example dashboard will be detailed in the following chapters. Note that, after each message sent to the computer, the target (the SAM D21 device) waits for a MSG_CONF_ACK (MSG_CONF_ACK) before sending the next message. Tip:  This example includes full automatic configuration of a Dashboard. However, the ADP could be used to configure a set of streams to be connected manually to various modules in the Data Visualizer like Graph, Oscilloscope, or Terminal. The ADP Control Panel shows the available sinks and sources for the current ADP instance. These sinks and sources can be used in the same way as the sources and sinks in the DGI Control Panel and the Serial Port Control Panel. For more information, see Atmel Data Protocol. Serial Interface The ADP example uses an SPI interface to stream the ADP data from the SAM D21 to the embedded debugger (EDBG) on the SAM D21 Xplained Pro board. The EDBG uses the Data Gateway Interface (DGI) to stream the data over USB to the host computer. If the target board did not contain a device with DGI capability, ADP could have been streamed directly to the computer over a serial interface. If this was the case the Serial Port Control Panel (Serial Port) would have been used in the Data Visualizer instead of the DGI Control Panel (Data Gateway Interface (DGI)). Initialization After setting up the hardware (e.g., initializing the serial interface, setting up the ADC and I/O ports), the application is ready to start sending the ADP messages. The first message sent is a MSG_REQ_HANDSHAKE. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 126 Table 5-5. MSG_REQ_HANDSHAKE Field Values Description Token 0xFF Message ID 0x00 Data length 10 Protocol version 0x01 The ADP example uses ADP protocol version 1 Options 0x01 GPIO is in use in this application Token {0x58, 0x99, 0xAB, 0xC9, 0x0F, 0xE2, 0xF7, 0xAA} Token used to verify ADP protocol This message is repeated until a MSG_RES_HANDSHAKE (MSG_RES_HANDSHAKE) is received, indicating the host is ready to receive messages. ADP Control Panel The ADP example configures the ADP Control Panel to look something like the screenshot below. Notice:  The appearance of screenshots will vary with operating system version and configuration. The ADP Control Panel is configured by the message detailed in the table below. Table 5-6. MSG_CONF_INFO Field Values Description Token 0xFF Message ID 0x28 Data length 177 Title “Light Sensor Example for Xplained Pro\0” Description “This example demonstrates light intensity measurements through the ADC of a Xplained Pro board. You will need the I/O1 Xplained Pro (EXT1)\0” Short description of the application Light Sensor Dashboard The ADP example sets up a dashboard for the I/O1 Xplained Pro light sensor and LED that looks something like the screenshot below. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 127 Notice:  The appearance of screenshots will vary with operating system version and configuration. The light sensor dashboard is configured by the messages detailed in the tables below. First, the dashboard itself must be set up. Table 5-7. MSG_CONF_DASHBOARD Field Values Description Token 0xFF Message ID 0x2A Data length 38 ID 0x0000 Dashboard ID Label “Light Sensor Example Dashboard\0” Dashboard label Background color 0xFFFFFF (transmitted as 0xFFFFFFFFFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) Background color of dashboard Height 300 Height (in pixels) of dashboard Next, Label elements are added to the dashboard. Table 5-8. MSG_CONF_DASHBOARD_ELEMENT, ELEMENT_TYPE_LABEL Field Values Description Token 0xFF Message ID 0x2B Data length 47 Depending on element type Dashboard ID 0x0000 ID of light sensor dashboard Element ID 0x0000 Unique ID of label element Z-Index 0 Order index, 0 places the element the farthest to the back X-coordinate 5 X-coordinate of element location. 0 is topmost position on dashboard. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 128 Field Values Description Y-coordinate 5 Y-coordinate of element location. 0 is topmost position on dashboard. Width 300 Width of element (pixels) Height 35 Height of element (pixels) Element type 0x00 ELEMENT_TYPE_LABEL Font size 24 Attribute 0x00 Bold = OFF, Italic = OFF Horizontal alignment 1 Center Vertical alignment 1 Center Background transparency 0 Background color 0xFFFFFF (transmitted as 0xFFFFFFFFFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) RGB color of background Foreground transparency 255 (transmitted as 0xFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) Foreground color 0x000000 RGB color of background Label text “Light Sensor Example\0” Table 5-9. MSG_CONF_DASHBOARD_ELEMENT, ELEMENT_TYPE_LABEL Field Values Description Token 0xFF Message ID 0x2B Data length 45 Depending on element type Dashboard ID 0x0000 ID of light sensor dashboard Element ID 0x0001 Unique ID of label element Z-Index 0 Order index, 0 places the element the farthest to the back X-coordinate 5 X-coordinate of element location. 0 is topmost position on dashboard. Y-coordinate 60 Y-coordinate of element location. 0 is topmost position on dashboard. Width 129 Width of element (pixels) Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 129 Field Values Description Height 25 Height of element (pixels) Element type 0x00 ELEMENT_TYPE_LABEL Font size 14 Attribute 0x01 Bold = ON, Italic = OFF Horizontal alignment 0 Left Vertical alignment 1 Center Background transparency 0 Background color 0xFFFFFF (transmitted as 0xFFFFFFFFFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) RGB color of background Foreground transparency 255 (transmitted as 0xFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) Foreground color 0x000000 RGB color of background Label text “Light Sensor Value\0” Table 5-10. MSG_CONF_DASHBOARD_ELEMENT, ELEMENT_TYPE_LABEL Field Values Description Token 0xFF Message ID 0x2B Data length 38 Depending on element type Dashboard ID 0x0000 ID of light sensor dashboard Element ID 0x0002 Unique ID of label element Z-Index 0 Order index, 0 places the element the farthest to the back X-coordinate 5 X-coordinate of element location. 0 is topmost position on dashboard. Y-coordinate 100 Y-coordinate of element location. 0 is topmost position on dashboard. Width 82 Width of element (pixels) Height 25 Height of element (pixels) Element type 0x00 ELEMENT_TYPE_LABEL Font size 14 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 130 Field Values Description Attribute 0x01 Bold = ON, Italic = OFF Horizontal alignment 0 Left Vertical alignment 1 Center Background transparency 0 Background color 0xFFFFFF (transmitted as 0xFFFFFFFFFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) RGB color of background Foreground transparency 255 (transmitted as 0xFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) Foreground color 0x000000 RGB color of background Label text “Night Light\0” Table 5-11. MSG_CONF_DASHBOARD_ELEMENT, ELEMENT_TYPE_LABEL Field Values Description Token 0xFF Message ID 0x2B Data length 38 Depending on element type Dashboard ID 0x0000 ID of light sensor dashboard Element ID 0x0003 Unique ID of label element Z-Index 0 Order index, 0 places the element the farthest to the back X-coordinate 5 X-coordinate of element location. 0 is topmost position on dashboard. Y-coordinate 230 Y-coordinate of element location. 0 is topmost position on dashboard. Width 80 Width of element (pixels) Height 25 Height of element (pixels) Element type 0x00 ELEMENT_TYPE_LABEL Font size 14 Attribute 0x01 Bold = ON, Italic = OFF Horizontal alignment 0 Left Vertical alignment 1 Center Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 131 Field Values Description Background transparency 0 Background color 0xFFFFFF (transmitted as 0xFFFFFFFFFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) RGB color of background Foreground transparency 255 (transmitted as 0xFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) Foreground color 0x000000 RGB color of background Label text “LED Control\0” A stream needs to be set up to receive light sensor data. Table 5-12. MSG_CONF_STREAM Field Values Description Token 0xFF Message ID 0x20 Data length 18 ID 0x0001 ID of the light sensor data stream Type 12 Stream type float Mode 2 Out from target State 0 Stream state ON Label “Light sensor\0” Label of the data stream And a Progress bar to show the light sensor data is added. Table 5-13. MSG_CONF_DASHBOARD_ELEMENT, ELEMENT_TYPE_PROGRESS Field Values Description Token 0xFF Message ID 0x2B Data length 29 Depending on element type Dashboard ID 0x0000 ID of the light sensor dashboard Element ID 0x0004 Unique ID of the progress bar element Z-Index 0 Order index, 0 places the element the farthest to the back X-coordinate 140 X-coordinate of element location. 0 is topmost position on dashboard. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 132 Field Values Description Y-coordinate 60 Y-coordinate of element location. 0 is topmost position on dashboard. Width 145 Width of element (pixels) Height 25 Height of element (pixels) Element type 0x03 ELEMENT_TYPE_PROGRESS Minimum value 0 Maximum value 4 Initial value 0 Color 0x008000 RGB color of progress bar Eventually, the light sensor data stream is connected to the Progress bar element. Table 5-14. MSG_CONF_ADD_STREAM_TO_ELEMENT Field Values Description Message ID 0x2C Data length 6 Dashboard ID 0x0000 ID of the light sensor dashboard Element ID 0x0004 ID of the progress bar element Stream ID 0x0001 ID of the light sensor data stream Next, a Graph element is added to the dashboard. Table 5-15. MSG_CONF_DASHBOARD_ELEMENT, ELEMENT_TYPE_GRAPH Field Values Description Token 0xFF Message ID 0x2B Data length 53 Depending on element type Dashboard ID 0x0000 ID of the light sensor dashboard Element ID 0x0007 Unique ID of graph element Title color 0xFFFFFF (transmitted as 0xFFFFFFFFFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) RGB color of title Background color 0x000000 RGB color of graph frame Graph background color 0x000000 RGB color of graph Title text “Light level\0” Plot count 1 Xmin 0 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 133 Field Values Description Xmax 10 Ymin 0 Ymax 5 Mode 0x00 Mouse interaction OFF Fit graph to right edge of canvas OFF And the light sensor data stream is connected to the Graph. Table 5-16. MSG_CONF_ADD_STREAM_TO_ELEMENT Field Values Description Message ID 0x2C Data length 6 Dashboard ID 0x0000 ID of the light sensor dashboard Element ID 0x0007 ID of the graph element Stream ID 0x0001 ID of the light sensor data stream A separate stream is set up to signal Night mode. Table 5-17. MSG_CONF_STREAM Field Values Description Token 0xFF Message ID 0x20 Data length 16 ID 0x0029 ID of the Night mode stream Type 2 Stream type uint_8 Mode 2 Out from target State 0 Stream state ON Label “Night Mode\0” Label of the data stream A Signal element is added to the dashboard for the Night mode signal. Table 5-18. MSG_CONF_DASHBOARD_ELEMENT, ELEMENT_TYPE_SIGNAL Field Values Description Token 0xFF Message ID 0x2B Data length 22 Depending on element type Dashboard ID 0x0000 ID of the light sensor dashboard Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 134 Field Values Description Element ID 0x0005 Unique ID of the signal element Z-Index 0 Order index, 0 places the element the farthest to the back X-coordinate 140 X-coordinate of element location. 0 is topmost position on dashboard. Y-coordinate 100 Y-coordinate of element location. 0 is topmost position on dashboard. Width 25 Width of element (pixels) Height 25 Height of element (pixels) Element type 0x04 ELEMENT_TYPE_SIGNAL On transparency 255 (transmitted as 0xFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) On color 0x008000 RGB color for ON state Off transparency 255 (transmitted as 0xFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) Off color 0x000000 RGB color for OFF state And the Night mode stream is connected to the Signal element. Table 5-19. MSG_CONF_ADD_STREAM_TO_ELEMENT Field Values Description Message ID 0x2C Data length 6 Dashboard ID 0x0000 ID of the light sensor dashboard Element ID 0x0005 ID of the signal element Stream ID 0x0029 ID of the night mode stream Next, a incoming stream (in to target) is set up to transfer the Button status to the target. Table 5-20. MSG_CONF_STREAM Field Values Description Token 0xFF Message ID 0x20 Data length 16 ID 0x0030 ID of the button stream Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 135 Field Values Description Type 2 Stream type uint_8 Mode 0 In to target State 0 Stream state ON Label “LED Toggle\0” Label of the stream A Button is added to the dashboard to toggle the target LED. Table 5-21. MSG_CONF_DASHBOARD_ELEMENT, ELEMENT_TYPE_BUTTON Field Values Description Token 0xFF Message ID 0x2B Data length 26 Depending on element type Dashboard ID 0x0000 ID of the light sensor dashboard Element ID 0x0006 Unique ID of the signal element Z-Index 0 Order index, 0 places the element the farthest to the back X-coordinate 110 X-coordinate of element location. 0 is topmost position on dashboard. Y-coordinate 230 Y-coordinate of element location. 0 is topmost position on dashboard. Width 75 Width of element (pixels) Height 50 Height of element (pixels) Element type 0x01 ELEMENT_TYPE_BUTTON Font size 10 Button text “LED Toggle\0” Toggle button 0x00 = Normal button 0x01 = Toggle button Normal button And the button stream is connected to the Button element. Table 5-22. MSG_CONF_ADD_STREAM_TO_ELEMENT Field Values Description Message ID 0x2C Data length 6 Dashboard ID 0x0000 ID of the light sensor dashboard Element ID 0x0006 ID of the button element Stream ID 0x0030 ID of the button stream Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 136 Control Dashboard The ADP example sets up a dashboard to control the ADC. The Control dashboard will look something like the screenshot below. Notice:  The appearance of screenshots will vary with operating system version and configuration. The Control dashboard is configured by the messages detailed in the tables below. First, the dashboard itself is set up: Table 5-23. MSG_CONF_DASHBOARD Field Values Description Token 0xFF Message ID 0x2A Data length 25 ID 0x0001 Dashboard ID Label “Control Dashboard\0” Dashboard label Background color 0xFFFFFF (transmitted as 0xFFFFFFFFFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) Background color of dashboard Height 150 Height (in pixels) of dashboard Next, a few labels are added to the dashboard. Table 5-24. MSG_CONF_DASHBOARD_ELEMENT, ELEMENT_TYPE_LABEL Field Values Description Token 0xFF Message ID 0x2B Data length 45 Dashboard ID 0x0001 ID of control dashboard Element ID 0x0008 Unique ID of label element Z-Index 0 Order index, 0 places the element the farthest to the back X-coordinate 5 X-coordinate of element location. 0 is topmost position on dashboard. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 137 Field Values Description Y-coordinate 20 Y-coordinate of element location. 0 is topmost position on dashboard. Width 128 Width of element (pixels) Height 25 Height of element (pixels) Element type 0x00 ELEMENT_TYPE_LABEL Font size 14 Attribute 0x01 Bold = ON, Italic = OFF Horizontal alignment 0 Left Vertical alignment 1 Center Background transparency 0 Background color 0xFFFFFF (transmitted as 0xFFFFFFFFFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) RGB color of background Foreground transparency 255 (transmitted as 0xFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) Foreground color 0x000000 RGB color of background Label text “Hysteresis Values\0” Table 5-25. MSG_CONF_DASHBOARD_ELEMENT, ELEMENT_TYPE_LABEL Field Values Description Token 0xFF Message ID 0x2B Data length 31 Dashboard ID 0x0001 ID of control dashboard Element ID 0x000A Unique ID of label element Z-Index 0 Order index, 0 places the element the farthest to the back X-coordinate 25 X-coordinate of element location. 0 is topmost position on dashboard. Y-coordinate 100 Y-coordinate of element location. 0 is topmost position on dashboard. Width 30 Width of element (pixels) Height 25 Height of element (pixels) Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 138 Field Values Description Element type 0x00 ELEMENT_TYPE_LABEL Font size 14 Attribute 0x02 Bold = OFF, Italic = ON Horizontal alignment 0 Left Vertical alignment 1 Center Background transparency 0 Background color 0xFFFFFF (transmitted as 0xFFFFFFFFFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) RGB color of background Foreground transparency 255 (transmitted as 0xFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) Foreground color 0x000000 RGB color of background Label text “High\0” Table 5-26. MSG_CONF_DASHBOARD_ELEMENT, ELEMENT_TYPE_LABEL Field Values Description Token 0xFF Message ID 0x2B Data length 30 Dashboard ID 0x0001 ID of control dashboard Element ID 0x0009 Unique ID of label element Z-Index 0 Order index, 0 places the element the farthest to the back X-coordinate 25 X-coordinate of element location. 0 is topmost position on dashboard. Y-coordinate 60 Y-coordinate of element location. 0 is topmost position on dashboard. Width 30 Width of element (pixels) Height 25 Height of element (pixels) Element type 0x00 ELEMENT_TYPE_LABEL Font size 14 Attribute 0x02 Bold = OFF, Italic = ON Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 139 Field Values Description Horizontal alignment 0 Left Vertical alignment 1 Center Background transparency 0 Background color 0xFFFFFF (transmitted as 0xFFFFFFFFFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) RGB color of background Foreground transparency 255 Foreground color 0x000000 RGB color of background Label text “Low\0” Table 5-27. MSG_CONF_DASHBOARD_ELEMENT, ELEMENT_TYPE_LABEL Field Values Description Token 0xFF Message ID 0x2B Data length 44 Dashboard ID 0x0001 ID of control dashboard Element ID 0x000B Unique ID of label element Z-Index 0 Order index, 0 places the element the farthest to the back X-coordinate 350 X-coordinate of element location. 0 is topmost position on dashboard. Y-coordinate 20 Y-coordinate of element location. 0 is topmost position on dashboard. Width 130 Width of element (pixels) Height 25 Height of element (pixels) Element type 0x00 ELEMENT_TYPE_LABEL Font size 14 Attribute 0x01 Bold = ON, Italic = OFF Horizontal alignment 0 Left Vertical alignment 1 Center Background transparency 0 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 140 Field Values Description Background color 0xFFFFFF (transmitted as 0xFFFFFFFFFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) RGB color of background Foreground transparency 255 (transmitted as 0xFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) Foreground color 0x000000 RGB color of background Label text “ADC Sample Value\0” Next, a stream is set up to set the high value of the hysteresis. Table 5-28. MSG_CONF_STREAM Field Values Description Token 0xFF Message ID 0x20 Data length 16 ID 0x0010 ID of the hysteresis high value stream Type 4 Stream type uint_16 Mode 0 In to target State 0 Stream state ON Label “Hyst. High\0” Label of the data stream A Slider is added to be able to adjust the high value of the hysteresis from the dashboard. Table 5-29. MSG_CONF_DASHBOARD_ELEMENT, ELEMENT_TYPE_SLIDER Field Values Description Token 0xFF Message ID 0x2B Data length 26 Dashboard ID 0x0001 ID of the control dashboard Element ID 0x000D Unique ID of the slider element Z-Index 0 Order index, 0 places the element the farthest to the back X-coordinate 75 X-coordinate of element location. 0 is topmost position on dashboard. Y-coordinate 100 Y-coordinate of element location. 0 is topmost position on dashboard. Width 156 Width of element (pixels) Height 25 Height of element (pixels) Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 141 Field Values Description Element type 0x02 ELEMENT_TYPE_SLIDER Minimum value 2500 Maximum value 4000 Initial value 3000 And the hysteresis high value stream is connected to the Slider element. Table 5-30. MSG_CONF_ADD_STREAM_TO_ELEMENT Field Values Description Message ID 0x2C Data length 6 Dashboard ID 0x0001 ID of the control dashboard Element ID 0x000D ID of the hysteresis high slider element Stream ID 0x0010 ID of the hysteresis high stream A stream for hysteresis low values is created and added to a Slider element in the same way as for the hysteresis high value above. Table 5-31. MSG_CONF_STREAM Field Values Description Token 0xFF Message ID 0x20 Data length 15 ID 0x0011 ID of the hysteresis low value stream Type 4 Stream type uint_16 Mode 0 In to target State 0 Stream state ON Label “Hyst. Low\0” Label of the data stream Table 5-32. MSG_CONF_DASHBOARD_ELEMENT, ELEMENT_TYPE_SLIDER Field Values Description Token 0xFF Message ID 0x2B Data length 26 Dashboard ID 0x0001 ID of the control dashboard Element ID 0x000C Unique ID of the slider element Z-Index 0 Order index, 0 places the element the farthest to the back Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 142 Field Values Description X-coordinate 75 X-coordinate of element location. 0 is topmost position on dashboard. Y-coordinate 60 Y-coordinate of element location. 0 is topmost position on dashboard. Width 156 Width of element (pixels) Height 25 Height of element (pixels) Element type 0x02 ELEMENT_TYPE_SLIDER Minimum value 1000 Maximum value 2400 Initial value 2000 Table 5-33. MSG_CONF_ADD_STREAM_TO_ELEMENT Field Values Description Message ID 0x2C Data length 6 Dashboard ID 0x0001 ID of the control dashboard Element ID 0x000C ID of the hysteresis low slider element Stream ID 0x0011 ID of the hysteresis low stream A separate stream for the light sensor ADC values to be fed to the Segment display is set up. Table 5-34. MSG_CONF_STREAM Field Values Description Token 0xFF Message ID 0x20 Data length 22 ID 0x0002 ID of the adc value stream Type 4 Stream type uint_16 Mode 2 Out from target State 0 Stream state ON Label “Light Sensor ADC\0” Label of the data stream Next, a Segment display with four segments is added to the dashboard. Table 5-35. MSG_CONF_DASHBOARD_ELEMENT, ELEMENT_TYPE_SEGMENT Field Values Description Token 0xFF Message ID 0x2B Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 143 Field Values Description Data length 20 Dashboard ID 0x0001 ID of the control dashboard Element ID 0x000D Unique ID of the segment display element Z-Index 0 Order index, 0 places the element the farthest to the back X-coordinate 500 X-coordinate of element location. 0 is topmost position on dashboard. Y-coordinate 20 Y-coordinate of element location. 0 is topmost position on dashboard. Width 150 Width of element (pixels) Height 50 Height of element (pixels) Element type 0x05 ELEMENT_TYPE_SEGMENT Count 4 Four segments Base 10 Ordinary decimal base Transparency 0xFF (transmitted as 0xFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) 0 - 255 Color 0xFF0000 (transmitted as 0xFFFF0000 as each 0xFF character must be transmitted as 0xFFFF, see Message Format) RGB color of display And the ADC sample value stream is connected to the Segment display. Table 5-36. MSG_CONF_ADD_STREAM_TO_ELEMENT Field Values Description Message ID 0x2C Data length 6 Dashboard ID 0x0001 ID of the control dashboard Element ID 0x000D ID of the segment display element Stream ID 0x0002 ID of the ADC sample data stream Terminal The ADP example sets up a terminal module that looks something like the screenshot below. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 144 Notice:  The appearance of screenshots will vary with operating system version and configuration. The terminal module is configured by the messages detailed in the tables below. First, a stream is set up to send terminal data to the host computer. Table 5-37. MSG_CONF_STREAM Field Values Description Token 0xFF Message ID 0x20 Data length 21 ID 0x0000 Type 2 UINT_8 stream Mode 2 Outgoing stream (out from target) State 0 Stream state ON Label “Status messages\0” Label of the data stream Next, the terminal itself is configured. Table 5-38. MSG_CONF_TERMINAL Field Values Description Token 0xFF Message ID 0x26 Data length 26 ID 0x0000 ID of terminal Label “Status terminal\0” Terminal label Width 80 Number of characters wide Height 50 Number of lines high Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 145 Field Values Description Background color 0xFFFFFF (transmitted as 0xFFFFFFFFFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) RGB background color Foreground color 0x008000 RGB foreground color Finally, the data stream is connected to the terminal module. Table 5-39. MSG_CONF_ADD_TO_TERMINAL Field Values Description Token 0xFF Message ID 0x27 Data length 27 Terminal ID 0x0000 ID of terminal Stream ID 0x0000 ID of stream Mode 0xFF (transmitted as 0xFFFF as each 0xFF character must be transmitted as 0xFFFF, see Message Format) Implicit newline in incoming text = ON Text color 0x000000 RGB color of the text stream received Tag text “Status messages\0” Tag text color 0x000000 RGB color of the tag text Data Transmission When the terminal module and the two dashboards have been set up as described in the previous sections, the ADP example goes into a mode where it is continuously sending data to the host computer and receiving data from the host computer according to the configured streams. Below are examples of data messages being transmitted from the ATSAMD21 target to the host computer. Table 5-40. Light Sensor ADC Stream Field Values Description Token 0xFF Message ID 0x40 Data length 6 Number of streams (N) 1 Stream ID 0x0002 ID of ADC value stream Num bytes (Xn) 2 Number of bytes from the stream Stream X data sample M 634 (0x027A) The data of the stream (uint_16) Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 146 Table 5-41. Night Mode Stream Field Values Description Token 0xFF Message ID 0x40 Data length 5 Number of streams (N) 1 Stream ID 0x0029 ID of Night mode stream Num bytes (Xn) 1 Number of bytes from the stream Stream X data sample M 0x01 (Bright light, day mode) The data of the stream (uint_8) When the Night mode changes, the example also changes the background color of the terminal module by sending another MSG_CONF_TERMINAL. Table 5-42. MSG_CONF_TERMINAL to update Terminal Background Color to White Field Values Description Token 0xFF Message ID 0x26 Data length 26 ID 0x0000 ID of terminal Label “Status terminal\0” Terminal label Width 80 Number of characters wide Height 50 Number of lines high Background color 0xFFFFFF RGB background color Foreground color 0x008000 RGB foreground color Table 5-43. Status Message Stream Field Values Description Token 0xFF Message ID 0x40 Data length 44 Number of streams (N) 1 Stream ID 0x0000 ID of status message stream Num bytes (Xn) 40 Number of bytes from the stream Stream X data samples “It's bright again... Entered day mode!\r\n” The data of the stream (uint_8) Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 147 Field Values Description {0x49, 0x74, 0x27, 0x73, 0x20, 0x62, 0x72, 0x69, 0x67, 0x68, 0x74, 0x20, 0x61, 0x67, 0x61, 0x69, 0x6E, 0x2E, 0x2E, 0x2E, 0x20, 0x45, 0x6E, 0x74, 0x65, 0x72, 0x65, 0x64, 0x20, 0x64, 0x61, 0x79, 0x20, 0x6D, 0x6F, 0x64, 0x65, 0x21, 0x0D, 0x0A} Examples of data messages for the various streams from the computer to the target can be found in the tables below. Table 5-44. Hysteresis Low Value Stream Data Message Field Values Description Token 0xFF Message ID 0x14 MSG_RES_DATA Data length 5 Stream ID 0x0011 ID of hysteresis low value stream Bytes sent 2 Number of bytes in the data payload Data bytes 0x07C6 The data (uint_16) Table 5-45. Hysteresis High Value Stream Data Message Field Values Description Token 0xFF Message ID 0x14 MSG_RES_DATA Data length 5 Stream ID 0x0002 ID of hysteresis high value stream Bytes sent 2 Number of bytes in the data payload Data bytes 0x0BB7 The data (uint_16) Table 5-46. LED Toggle Stream Data Message Field Values Description Token 0xFF Message ID 0x14 MSG_RES_DATA Data length 5 Stream ID 0x0030 ID of LED toggle stream Bytes sent 1 Number of bytes in the data payload Data bytes 0x00 The data (uint_8) Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 148 5.2.3 Message Flow The target is the master in the system, whereas the host computer is the slave. The target will initiate communication, and the computer will respond. However, the computer will transmit data to the target MCU as soon as data is generated on the computer. Before any data can be exchanged between the target and the computer, the connection must be established using handshake messages. 5.2.4 Message Format The ADP protocol uses a common message format for both directions of communication and all message types. Table 5-47. ADP Message Format Field Size Values Description Token 1 byte 0xFF Start token for ADP data Message ID 1 byte 0x00-0xFE Identifies the type of message being sent Data length 2 bytes 0x0000-0xFFFF Length of data packet (bytes) Data N bytes ... Data content of the message Token The value 0xFF followed by a value other than 0xFF (0xFF is not a valid Message ID), is used to indicate the start of the message. This means that 0xFF must be sent between each message. If the value 0xFF is to be transmitted as part of data or data length, a new 0xFF should be inserted after it. When receiving messages, two 0xFF should be decoded as a single 0xFF. The extra 0xFF bytes are not contributing to the Data length field. For example, a color field with the value 0xFFFFFF will have to be transmitted as 0xFFFFFFFFFFFF, but only contributes to the data length by three bytes. The value 0xFF is not allowed to be used as a message ID. When polling for data over SPI, the 0xFF token must be used as a dummy character to not trigger a command unintentionally. Endianness All message data is ordered using little endian. 5.2.5 Message Types There are three main message types; Request messages, Configuration messages, and Data messages. 5.2.5.1 Request Messages Request messages are used by the target to request information/status from the host PC. These messages are pre-fixed with MSG_REQ. The PC should always respond with the corresponding response message, pre-fixed MSG_RES. Table 5-48. Request Messages and Responses Message Type ID Description MSG_REQ_HANDSHAKE 0x00 Request handshake MSG_RES_HANDSHAKE 0x10 Respond to handshake MSG_REQ_STATUS 0x02 Request status from PC Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 149 Message Type ID Description MSG_RES_STATUS 0x12 Respond to status MSG_RES_DATA 0x14 Raw data from PC to target 5.2.5.2 Configuration Messages Used by target to send configuration settings to the PC. These messages are pre-fixed with MSG_CONF. The PC should respond to these messages with an acknowledge message (MSG_ACK). Table 5-49. Configuration Messages, Target to PC Message type ID Description MSG_CONF_STREAM 0x20 Create a new stream Reserved 0x21 Reserved for future use MSG_CONF_GRAPH 0x22 Create new graph or reconfigure existing one MSG_CONF_ADD_STREAM_T O_AXIS 0x23 Add stream to axis in graph MSG_CONF_CURSOR_TO_GR APH 0x24 Add parameter cursor to graph Reserved 0x25 Reserved for future use MSG_CONF_TERMINAL 0x26 Create new terminal or reconfigure existing one MSG_CONF_ADD_TO_TERMIN AL 0x27 Add stream to terminal MSG_CONF_INFO 0x28 Info about the application MSG_CONF_AXIS 0x29 Create new axis or reconfigure existing one MSG_CONF_DASHBOARD 0x2A Add dashboard container MSG_CONF_DASHBOARD_EL EMENT 0x2B Add element to dashboard container MSG_CONF_ADD_STREAM_T O_ELEMENT 0x2C Tie an already configured stream to an already configured dashboard element. Table 5-50. Configuration Messages, PC to Target Message type ID Description MSG_CONF_ACK 0x30 Status of last received configuration message 5.2.5.3 Data Messages Used by a target to send data to the PC. Prefixed with MSG_DATA. These messages should not be responded too. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 150 Table 5-51. Data Messages Message Type ID Description MSG_DATA_STREAM 0x40 Send data from one or more streams 5.2.5.4 Request Message Details MSG_REQ_HANDSHAKE Before any data can be exchanged between the target and the PC, the connection must be established using handshake messages. Important:  To make sure the handshake message is detected by the Data Visualizer during Auto-Detection, the handshake message should be sent at least twice per second. Field Size Values Description Message ID 1 byte 0x00 Data length 2 bytes 10 Protocol version 1 byte 0x01-0xFF Version of protocol on target Options 1 byte 0xXX Reserved for future use Token 8 bytes {0x58, 0x99, 0xAB, 0xC9, 0x0F, 0xE2, 0xF7, 0xAA} Token used to verify ADP protocol MSG_RES_HANDSHAKE The PC should respond to a handshake request from the target with this packet. The PC should always communicate with the target using the protocol version stated in the targets handshake request message. If the PC for some reason is unable to do this, the handshake request must be rejected. Field Size Values Description Message ID 1 byte 0x10 Data length 2 bytes 1 Handshake status 1 byte 0x00: Handshake accepted 0x01: Handshake rejected. Invalid protocol version. 0x02: Handshake rejected. Other reason. MSG_REQ_STATUS Message used by target to request status from PC. It is good practice to ask for status each time a new configuration message is sent. While sending raw data, it is good practice to ask for status... occasionally. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 151 Field Size Values Description Message ID 1 byte 0x02 Data length 2 bytes 0 This message has no data fields. MSG_RES_STATUS Status message from PC to target. Once a status is requested from the target and this packet is sent, all status flags should be cleared on the PC. Field Size Values Description Message ID 1 byte 0x12 Data length 2 bytes 2 Status code 2 bytes 0x0000 Reserved for future use MSG_RES_DATA Data packet from PC to target MCU. This message can come asynchronously from the PC (i.e., without the target MCU having requested it). Field Size Values Description Message ID 1 byte 0x14 Data length 2 bytes 3 + Data bytes Stream ID 2 bytes ID of stream Bytes sent 1 byte Number of bytes in the data payload. If the target has requested data from an unknown stream, or if the stream has no data to send, this field should be set to 0 and the appropriate status flag should be set. Data bytes N bytes The data 5.2.5.5 Configuration Message Details MSG_CONF_STREAM Used to create a new stream. The type of the stream can be either EVENT, TEXT, or DATA. Each stream must be given a unique ID. Field Size Values Description Message ID 1 byte 0x20 Data length 2 bytes 5 + label length (N) + parameter length (M) Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 152 Field Size Values Description ID 2 bytes 0x0000-0xFFFF ID of stream Type 1 byte STREAM_DATA_TYPE Stream type Mode 1 byte 0 = Incoming (normal) 1 = Incoming (single value) 2 = Outgoing Stream mode/direction Direction is defined seen from target State 1 byte 0 = ON 1= OFF Stream state Label N bytes Null-terminated string Label of the data stream Parameters M bytes Byte array Parameters specific to stream type Table 5-52. STREAM_DATA_TYPE Type code Data type Parameters Data size 0 EVENT None 0 bytes 1 STRING None N bytes 2 UINT_8 None 1 byte 3 INT_8 None 1 byte 4 UINT_16 None 2 bytes 5 INT_16 None 2 bytes 6 UINT_32 None 4 bytes 7 INT_32 None 4 bytes 8 XY_8 None 2 bytes 9 XY_16 None 4 bytes 10 XY_32 None 8 bytes 11 BOOL None 1 byte 12 Float None 4 bytes 13 Double None 8 bytes 20 Grid Base data type (1 byte, e.g. 6 for UINT_32) Width of grid (1 byte) Depth of grid (1 byte) Size of base data type * Width * Depth Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 153 The XY data types are combos of X and Y coordinates. If the format is XY_8 the data will contain one byte of X-coordinate and one byte of Y-coordinate. For XY_16 the data will contain two bytes of Xcoordinate and two bytes of Y-coordinates and for XY_32 each coordinate will be four bytes long. MSG_CONF_GRAPH Used to create a new or reconfigure an existing graph view. The graph view requires an unique ID. Values for range, labels, and background color can also be set. Field Size Values Description Message ID 1 byte 0x22 Data length 2 bytes 23 + label length (N) + Xlabel length (M) ID 2 bytes 0x0000-0xFFFF ID of new graph Label N bytes Null-terminated string Graph label Xmin 4 bytes Range Xmin value Xmax 4 bytes Range Xmax value Xlabel M bytes Null-terminated string X label Xscale numerator 4 bytes X range scale value. Set to 0 to enable autorange. Xscale denumerator 4 bytes X range scale value. Set to 0 to enable autorange. Scale mode 1 byte 0 = scaling off 1 = auto-scale Vertical scaling Background color 3 bytes 0xRRGGBB RGB background color Scroll mode 1 byte 0 = no scrolling 1 = stepping 2 = scroll 3 = circular/sweep Horizontal scrolling MSG_CONF_ADD_STREAM_TO_AXIS Used to add a stream to the specified graph view. Field Size Values Description Message ID 1 byte 0x23 Data length 2 bytes 32 Graph ID 2 bytes 0x0000-0xFFFF ID of graph Axis ID 2 bytes 0x0000-0xFFFF ID of axis Stream ID 2 bytes 0x0000-0xFFFF ID of stream Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 154 Field Size Values Description Sample rate numerator 4 bytes Sample rate of stream, set to 0 if not applicable Sample rate denominator 4 bytes Sample rate of stream, set to 0 in not applicable Yscale numerator 4 bytes Y range scale value. Set to 0 to enable autorange. Yscale denumerator 4 bytes Y range scale value. Set to 0 to enable autorange. Yoffset 4 bytes Offset of values Transparency 1 byte 0 - 255 Adjust the transparency Mode 1 byte For graphs: bit 0 = line ON/OFF bit 1 = points ON/OFF For text: 0 = flag 1 = text Thickness 1 byte 0 - 255 Thickness of line Color 3 bytes 0xRRGGBB RGB color of line MSG_CONF_CURSOR_TO_GRAPH Used to add a parameter cursor to a graph. Field Size Values Description Message ID 1 byte 0x24 Data length 2 bytes 35 + label length (N) Stream ID 2 bytes 0x0000-0xFFFF ID of stream Graph ID 2 bytes 0x0000-0xFFFF ID of graph Axis ID 2 bytes 0x0000-0xFFFF ID of axis Label N bytes Null-terminated string Label of cursor Thickness 1 byte 0 - 255 Thickness of line Color 3 bytes 0xRRGGBB RGB color of cursor Initial value 4 bytes Starting point of cursor Minimum 4 bytes Minimum allowed value Maximum 4 byte Maximum allowed value Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 155 Field Size Values Description Scale numerator 4 bytes Numerator of scaling value Scale denominator 4 bytes Denominator of scaling value Scale offset 4 bytes Offset of scaling value Style 1 byte 0xXX Reserved for future use MSG_CONF_TERMINAL Used to create a new or reconfigure an existing terminal. The terminal requires a unique ID. Values for label and background color must also be set. Field Size Values Description Message ID 1 byte 0x26 Data length 2 bytes 10 + label length (N) ID 2 bytes 0x0000-0xFFFF ID of terminal Label N bytes Null-terminated string Terminal label Width 1 byte 0 - 255 Number of characters wide Height 1 byte 0 - 255 Number of lines high Background color 3 bytes 0xRRGGBB RGB background color Foreground color 3 byte 0xRRGGBB RGB foreground color MSG_CONF_ADD_TO_TERMINAL Used to add a stream to the specified terminal. Field Size Values Description Message ID 1 byte 0x27 Data length 2 bytes 11 + tag length (N) Terminal ID 2 bytes 0x0000-0xFFFF ID of terminal Stream ID 2 bytes 0x0000-0xFFFF ID of stream Mode 1 byte 0bXXXNXXXX N = implicit newline in incoming text Text color 3 bytes 0xRRGGBB RGB color of the text stream received Tag text N bytes Null-terminated string Descriptive tag Tag text color 3 bytes 0xRRGGBB RGB color of the tag text MSG_CONF_INFO Used to send info about the application. For example, a text string describing the example application. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 156 Field Size Values Description Message ID 1 byte 0x28 Data length 2 bytes Title length (N) + Description length (M) Title N bytes Null-terminated string Application title Description M bytes Null-terminated string Short description of the application MSG_CONF_AXIS Used to create a new or reconfigure an existing axis of a graph view. The axis requires a unique ID. Values for range, label, and axis color must also be set. Field Size Values Description Message ID 1 byte 0x29 Data length 2 bytes 24 + label length (N) Axis ID 2 bytes 0x0000-0xFFFF ID of new axis Graph ID 2 bytes 0x0000-0xFFFF ID of graph containing the axis Label N bytes Null-terminated string Axis label Ymin 4 bytes Range Ymin value Ymax 4 bytes Range Ymax value Yscale numerator 4 bytes Y range scale value. Set to 0 to enable autorange. Yscale denominator 4 bytes Y range scale value. Set to 0 to enable autorange. Scale mode 1 byte 0 = scaling off 1 = auto-scale Vertical scaling Axis color 3 bytes 0xRRGGBB RGB color MSG_CONF_DASHBOARD Add a dashboard container where dashboard elements can be placed. Field Size Values Description Message ID 1 byte 0x2A Data length 2 bytes 7 + label length (N) ID 2 bytes 0x0000-0xFFFF Dashboard ID Label N bytes Null-terminated string Dashboard label Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 157 Field Size Values Description Background color 3 bytes 0xRRGGBB Background color of dashboard Height 2 bytes Height (in pixels) of dashboard MSG_CONF_DASHBOARD_ELEMENT Configure a dashboard element and add it to the specified dashboard. The table shows common fields for all dashboard element types. Additional fields must be added, depending on element type. See below. Field Size Values Description Message ID 1 byte 0x2B Data length 2 bytes 14 + element specific length Depending on element type Dashboard ID 2 bytes 0x0000-0xFFFF ID of dashboard to add the element to Element ID 2 bytes 0x0000-0xFFFF Unique ID of element Z-Index 1 byte Order index, 0 places the element the farthest to the back X-coordinate 2 bytes Coordinate value in pixels X-coordinate of element location. 0 is topmost position on dashboard. Y-coordinate 2 bytes Coordinate value in pixels Y-coordinate of element location. 0 is topmost position on dashboard. Width 2 bytes Width in pixels Width of element Height 2 bytes Height in pixels Height of element Element type 1 byte ELEMENT_TYPE See each element type below ELEMENT_TYPE_LABEL The tables below describe the ELEMENT_TYPE_LABEL specific parameters and additional fields for the MSG_CONF_DASHBOARD_ELEMENT message. Table 5-53. ELEMENT_TYPE_LABEL Parameters Parameter Value ELEMENT_TYPE 0x00 Total data length of MSG_CONF_DASHBOARD_ELEMENT when using ELEMENT_TYPE_LABEL 26 + length of default text (N) Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 158 Table 5-54. Additional Data Fields to MSG_CONF_DASHBOARD_ELEMENT Field Size Values Description Font size 1 byte 1-255 Attribute 1 byte Bit 0: Bold ON/OFF Bit 1: Italic ON/OFF Horizontal alignment 1 byte 0 = Left 1 = Center 2 = Right Vertical alignment 1 byte 0 = Top 1 = Center 2 = Bottom Background transparency 1 byte 0 - 255 Background color 3 bytes 0xRRGGBB RGB color of background Foreground transparency 1 byte 0 - 255 Foreground color 3 bytes 0xRRGGBB RGB color of background Label text N bytes Null-terminated string max. 100 bytes Example The picture below shows an example of two labels with the corresponding parameters given in the tables below the picture. Notice:  The appearance of elements will vary with operating system version and configuration. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 159 Table 5-55. Label1 Field Value Z-index 0 X-coordinate 30 Y-coordinate 30 Width 200 Height 100 Element type 0x00 Font size 16 Attribute 0x01 Horizontal alignment 0 Vertical alignment 0 Background transparency 255 Background color 0x64FF64 Foreground transparency 255 Foreground color 0x000000 Label text “Label1\0” Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 160 Table 5-56. Label2 Field Value Z-index 1 X-coordinate 90 Y-coordinate 70 Width 75 Height 25 Element type 0x00 Font size 12 Attribute 0x00 Horizontal alignment 1 Vertical alignment 1 Background transparency 100 Background color 0x646464 Foreground transparency 255 Foreground color 0x7C0000 Label text “Label2\0” ELEMENT_TYPE_BUTTON The tables below describe the ELEMENT_TYPE_BUTTON specific parameters and additional fields for the MSG_CONF_DASHBOARD_ELEMENT message. Table 5-57. ELEMENT_TYPE_BUTTON Specific Parameters Parameter Value ELEMENT_TYPE 0x01 Total data length of MSG_CONF_DASHBOARD_ELEMENT when using ELEMENT_TYPE_BUTTON 16 + length of button text (N) Table 5-58. Additional Data Fields to MSG_CONF_DASHBOARD_ELEMENT for ELEMENT_TYPE_BUTTON Field Size Values Description Font size 1 byte 0-255 Button text N bytes Null-terminated string, max. 20 bytes For toggle button text is selected by '/' delimited text (/) Toggle button 1 byte 0x00 = Normal button 0x01 = Toggle button Change mode to toggle button. Button text is selected by '/' delimited text field. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 161 Example The picture below shows an example of two buttons; one normal button and one toggle button. The element data fields for the example are shown in the tables below the picture. Notice:  The appearance of elements will vary with operating system version and configuration. Table 5-59. Button Field Value Z-index 0 X-coordinate 30 Y-coordinate 30 Width 75 Height 25 Element type 0x01 Font size 12 Button text “Button\0” Toggle button 0x00 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 162 Table 5-60. Toggle Button Field Value Z-index 0 X-coordinate 30 Y-coordinate 70 Width 120 Height 25 Element type 0x01 Font size 12 Button text “ON/OFF\0” Toggle button 0x01 ELEMENT_TYPE_SLIDER The tables below describe the ELEMENT_TYPE_SLIDER specific parameters and additional fields for the MSG_CONF_DASHBOARD_ELEMENT message. Table 5-61. ELEMENT_TYPE_SLIDER Specific Parameters Parameter Value ELEMENT_TYPE 0x02 Total data length of MSG_CONF_DASHBOARD_ELEMENT when using ELEMENT_TYPE_SLIDER 26 Table 5-62. Additional Data Fields to MSG_CONF_DASHBOARD_ELEMENT for ELEMENT_TYPE_SLIDER Field Size Values Description Minimum value 4 bytes Maximum value 4 bytes Initial value 4 byte Example The picture below shows an example of a slider element with a range from 0 to 50 and an initial value of 20. The corresponding element data fields are given in the table below the picture. Notice:  The appearance of elements will vary with operating system version and configuration. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 163 Table 5-63. Slider Field Value Z-index 0 X-coordinate 20 Y-coordinate 20 Width 200 Height 30 Element type 0x02 Minimum value 0 Maximum value 50 Initial value 20 ELEMENT_TYPE_PROGRESS The tables below describe the ELEMENT_TYPE_PROGRESS specific parameters and additional fields for the MSG_CONF_DASHBOARD_ELEMENT message. Table 5-64. ELEMENT_TYPE_PROGRESS Specific Parameters Parameter Value ELEMENT_TYPE 0x03 Total data length of MSG_CONF_DASHBOARD_ELEMENT when using ELEMENT_TYPE_PROGRESS 29 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 164 Table 5-65. Additional Data Fields to MSG_CONF_DASHBOARD_ELEMENT for ELEMENT_TYPE_PROGRESS Field Size Values Description Minimum value 4 bytes Maximum value 4 bytes Initial value 4 byte Color 3 bytes 0xRRGGBB RGB color of progress bar Example The picture below shows an example of a progress bar element. The corresponding element data fields are given in the table below the picture. Notice:  The appearance of elements will vary with operating system version and configuration. Table 5-66. Progress Bar Field Value Z-index 0 X-coordinate 10 Y-coordinate 10 Width 100 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 165 Field Value Height 30 Element type 0x03 Minimum value 0 Maximum value 100 Initial value 50 Color 0x01D328 ELEMENT_TYPE_SIGNAL The tables below describe the ELEMENT_TYPE_SIGNAL specific parameters and additional fields for the MSG_CONF_DASHBOARD_ELEMENT message. Table 5-67. ELEMENT_TYPE_SIGNAL Specific Parameters Parameter Value ELEMENT_TYPE 0x04 Total data length of MSG_CONF_DASHBOARD_ELEMENT when using ELEMENT_TYPE_SIGNAL 22 Table 5-68. Additional Data Fields to MSG_CONF_DASHBOARD_ELEMENT for ELEMENT_TYPE_SIGNAL Field Size Values Description On transparency 1 byte 0 - 255 On color 3 bytes 0xRRGGBB RGB color for on state Off transparency 1 byte Off color 3 bytes 0xRRGGBB RGB color for off state Example The picture below shows an example of a signal element. The corresponding element data fields are given in the table below the picture. Notice:  The appearance of elements will vary with operating system version and configuration. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 166 Table 5-69. Signal Field Value Z-index 0 X-coordinate 20 Y-coordinate 20 Width 50 Height 50 Element type 0x04 On transparency 255 On color 0x00FF00 Off transparency 255 Off Color 0xFF0000 ELEMENT_TYPE_SEGMENT The tables below describe the ELEMENT_TYPE_SEGMENT specific parameters and additional fields for the MSG_CONF_DASHBOARD_ELEMENT message. Table 5-70. ELEMENT_TYPE_SEGMENT Specific Parameters Parameter Value ELEMENT_TYPE 0x05 Total data length of MSG_CONF_DASHBOARD_ELEMENT when using ELEMENT_TYPE_SEGMENT 20 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 167 Table 5-71. Additional Data Fields to MSG_CONF_DASHBOARD_ELEMENT for ELEMENT_TYPE_SEGMENT Field Size Values Description Count 1 byte 1-20 Number of displays Base 1 byte 2-16 Numeric base Transparency 1 byte 0 - 255 Color 3 bytes 0xRRGGBB RGB color of display Example The picture below shows an example of a segment element with two digits. The corresponding element data fields are given in the table below the picture. Notice:  The appearance of elements will vary with operating system version and configuration. Table 5-72. Signal Field Value Z-index 0 X-coordinate 30 Y-coordinate 30 Width 174 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 168 Field Value Height 150 Element type 0x05 Count 2 Base 10 Transparency 255 Color 0xFD0000 ELEMENT_TYPE_GRAPH The tables below describe the ELEMENT_TYPE_GRAPH specific parameters and additional fields for the MSG_CONF_DASHBOARD_ELEMENT message. This element generates a graph that visualizes the data from the target. There will be one input stream for each plot. Table 5-73. ELEMENT_TYPE_GRAPH Specific Parameters Parameter Value ELEMENT_TYPE 0x06 Total data length of MSG_CONF_DASHBOARD_ELEMENT when using ELEMENT_TYPE_GRAPH 41 + length of title (N) Table 5-74. Additional Data Fields to MSG_CONF_DASHBOARD_ELEMENT for ELEMENT_TYPE_GRAPH Field Size Values Description Title color 3 bytes 0xRRGGBB RGB color of title Background color 3 bytes 0xRRGGBB RGB color of graph frame Graph background color 3 bytes 0xRRGGBB RGB color of graph Title text N bytes Null-terminated string max. 20 bytes Plot count 1 byte 1-10 Number of plots Xmin 4 bytes Floating point, seconds Will be converted to : format Xmax 4 bytes Floating point, seconds Will be converted to : format Ymin 4 bytes Floating point Ymax 4 bytes Floating point Mode 1 byte Bit 0: Mouse interaction ON/OFF Bit 1: Fit graph to right edge of canvas Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 169 Example The picture below shows an example of a graph element with tree input plot inputs. The element data fields for the example is shown in the table below the picture. Notice:  The appearance of elements will vary with operating system version and configuration. Table 5-75. Graph Field Value Z-index 0 X-coordinate 10 Y-coordinate 10 Width 500 Height 250 Element type 0x06 Title color 0xFFFFFF Background color 0x000000 Graph background color 0x646464 Title text “Graph\0” Plot count 3 Xmin 0 Xmax 100 Ymin 0 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 170 Field Value Ymax 2.45 Mode 0x01 ELEMENT_TYPE_NUMERICAL_INPUT The tables below describe the ELEMENT_TYPE_NUMERICAL_INPUT specific parameters and additional fields for the MSG_CONF_DASHBOARD_ELEMENT message. This element type is used to output numerical values to the target from the PC. The element is editable in the dashboard. Table 5-76. ELEMENT_TYPE_NUMERICAL_INPUT Specific Parameters Parameter Value ELEMENT_TYPE 0x07 Total data length of MSG_CONF_DASHBOARD_ELEMENT when using ELEMENT_TYPE_NUMERICAL_INPUT 26 Table 5-77. Additional Data Fields to MSG_CONF_DASHBOARD_ELEMENT for ELEMENT_TYPE_NUMERICAL_INPUT Field Size Values Description Minimum 4 bytes Signed 32-bit integer Maximum 4 bytes Signed 32-bit integer Value 4 bytes Signed 32-bit integer Initial value Example The picture below shows an example of a numerical input element with a range of valid values from -100 to 100 and a default value of 30. The element data fields for the example is shown in the table below the picture. Notice:  The appearance of elements will vary with operating system version and configuration. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 171 Table 5-78. Numerical Input Field Value Z-index 0 X-coordinate 20 Y-coordinate 20 Width 50 Height 25 Element type 0x07 Minimum -100 Maximum 100 Value 30 ELEMENT_TYPE_RADIO The tables below describe the ELEMENT_TYPE_RADIO specific parameters and additional fields for the MSG_CONF_DASHBOARD_ELEMENT message. This element generates a group of radio buttons where only one option can be selected. Initially, the first option is selected. Table 5-79. ELEMENT_TYPE_RADIO Specific Parameters Parameter Value ELEMENT_TYPE 0x08 Total data length of MSG_CONF_DASHBOARD_ELEMENT when using ELEMENT_TYPE_RADIO 17 + length of text fields (N) Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 172 Table 5-80. Additional Data Fields to MSG_CONF_DASHBOARD_ELEMENT for ELEMENT_TYPE_RADIO Field Size Values Description Font size 1 byte 0-100 Number of items 1 byte 1-10 Orientation 1 byte 0 = Horizontal 1 = Vertical Text fields N bytes Null-terminated string max. 20 bytes '/' separated option list Example The picture below shows an example of radio button group with three buttons. The corresponding element data fields are given in the table below the picture. Notice:  The appearance of elements will vary with operating system version and configuration. Table 5-81. Radio Button Group Field Value Z-index 0 X-coordinate 20 Y-coordinate 20 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 173 Field Value Width 100 Height 100 Element type 0x08 Font size 16 Number of radio buttons 3 Orientation 1 Text fields “Op 1/Op 2/Op 3\0” ELEMENT_TYPE_PIE The tables below describe the ELEMENT_TYPE_PIE specific parameters and additional fields for the MSG_CONF_DASHBOARD_ELEMENT message. This element generates a pie chart. The size of the slices are updated based on the data from the target to the PC. There will be one data stream input for each slice. Table 5-82. ELEMENT_TYPE_PIE Specific Parameters Parameter Value ELEMENT_TYPE 0x09 Total data length of MSG_CONF_DASHBOARD_ELEMENT when using ELEMENT_TYPE_PIE 21 + length of title (N) Table 5-83. Additional Data Fields to MSG_CONF_DASHBOARD_ELEMENT for ELEMENT_TYPE_PIE Field Size Values Description Background color 3 bytes 0xRRGGBB RGB color of background Title color 3 bytes 0xRRGGBB RGB color of title Title N bytes Null-terminated string max. 20 bytes Number of slices 1 byte 1-10 Example The picture below shows an example of a pie element with three slices. The corresponding element data fields are given in the table below the picture. Notice:  The appearance of elements will vary with operating system version and configuration. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 174 Table 5-84. Numerical Input Field Value Z-index 0 X-coordinate 20 Y-coordinate 20 Width 600 Height 400 Element type 0x09 Background color 0xFFFFFF Title color 0x000000 Title “Pie\0” Number of slices 3 ELEMENT_TYPE_SURFACE The tables below describe the ELEMENT_TYPE_SURFACE specific parameters and additional fields for the MSG_CONF_DASHBOARD_ELEMENT message. This element generates a 3D surface plot that visualizes the grid of data points from the target. There is one input stream that accepts grid type data. Table 5-85. ELEMENT_TYPE_SURFACE Specific Parameters Parameter Value ELEMENT_TYPE 0x0D Total data length of MSG_CONF_DASHBOARD_ELEMENT when using ELEMENT_TYPE_SURFACE 47 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 175 Table 5-86. Additional Data Fields to MSG_CONF_DASHBOARD_ELEMENT for ELEMENT_TYPE_SURFACE Field Size Values Description Fill color 3 bytes 0xRRGGBB RGB color of surface fill Mesh color 3 bytes 0xRRGGBB RGB color of surface mesh Background color 4 bytes 0xAARRGGBB RGB color of background Background gradient color 4 bytes 0xAARRGGBB RGB color of background gradient Axis color 3 bytes 0xRRGGBB RGB color of axes Tick color 3 bytes 0xRRGGBB RGB color of ticks X Rotation 1 byte -90-90 Rotation of view around X axis in degrees Y Rotation 1 byte -90-90 Rotation of view around Y axis in degrees Z Rotation 1 byte -90-90 Rotation of view around Z axis in degrees Attributes 1 byte Bit 0: Show X axis Bit 1: Show Y axis Bit 2: Show Z axis Bit 3: Show fill Bit 4: Show mesh Bit 5: Use palette coloring Scaling mode 1 byte 0 = Static 1 = Scale roof and floor 2 = Scale roof 3 = Scale floor 4 = Sticky scale roof and floor 5 = Sticky scale roof 6 = Sticky scale floor Axis minimum 4 bytes Floating point Minimum value (floor) of Y axis Axis maximum 4 bytes Floating point Maximum value (roof) of Y axis Example The picture below shows an example of a surface element. The element data fields for the example are shown in the table below the picture. Notice:  The appearance of elements will vary with operating system version and configuration. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 176 Table 5-87. Surface Field Value Z-index 0 X-coordinate 5 Y-coordinate 5 Width 750 Height 590 Element type 0x0D Fill color 0x2F4F4F Mesh color 0x000000 Background color 0x00000000 Axis color 0x505050 Tick color 0x505050 Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 177 Field Value X Rotation 35 Y Rotation -70 Z Rotation 0 Attributes 0b00111111 Scaling mode 5 Axis minimum 0 Axis maximum 10 MSG_CONF_ADD_STREAM_TO_ELEMENT This message is used to tie an already configured stream to an already configured dashboard element. Field Size Values Description Message ID 1 byte 0x2C Data length 2 bytes 6 Dashboard ID 2 bytes 0x0000-0xFFFF ID of dashboard of given element Element ID 2 bytes 0x0000-0xFFFF ID of element Stream ID 2 bytes 0x0000-0xFFFF ID of stream for this element MSG_CONF_ACK Sent by PC to target to verify whether the last received configuration message was valid or not. Field Size Values Description Message ID 1 byte 0x30 Data length 2 bytes 1 Status 1 byte 0 = Not OK 1 = OK OK = Last configuration was OK and applied Not OK = Last configuration was invalid and got discarded 5.2.5.6 Data Message Details MSG_DATA_STREAM This message is used to send data from all enabled streams to the PC. It is possible to send one or multiple samples of data from all streams in one single message. Only data from the enabled streams will be sent. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 178 Field Size Values Description Message ID 1 byte 0x40 Data length 2 bytes 1 + number of streams (N) * (2 + num bytes for each stream (Xn) + length of each data sample in the stream (Xd)) Number of streams (N) 1 byte 1 - 255 Stream ID 2 bytes 0x0000-0xFFFF ID of stream X Num bytes (Xn) 1 byte 1-255 Number of bytes from stream X Stream X data sample M Dependent on data type of the stream (Xd) The data of stream X Note that the last row repeats for each sample in the stream and the three last rows repeat for each stream in the message. MSG_DATA_STREAM_SINGLE This message is used to send data from a single enabled stream to the PC. Only data from enabled streams will be sent. Field Size Values Description Message ID 1 byte 0x41 Data length 2 bytes 2 + length of one data sample of the stream (Xd) Stream ID 2 bytes 0x0000-0xFFFF ID of stream Stream data sample Dependent on data type of the stream (Xd) The data of stream Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 179 6. Example Code Snippets This chapter contains the code snippets used in the examples in this user guide. 6.1 Data Polling Example Code A Mass Storage Class example is used 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 trough both the 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. To be able to work through this example, the following is required: • Host computer with Atmel Studio 7 (or later) installed (Data Visualizer is included) • ATSAML21 Xplained Pro kit To do:  • Connect both the Target USB and Debug USB connectors on the SAM L21 Xplained Pro board This example makes use of the USB Device MSC Example from ASF for SAM L21 Xplained Pro. To do:  • In Atmel Studio, create a New Example Project • In the New Example dialog, select the SAM L21 device family (or other relevant device) and filter by the keyword “MSC” • Select the USB Device MSC Example • Build the project/solution (F7) Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 180 To do:  • Open the project properties (right click the project in the Solution Explorer and select Properties) • On the Tool tab, select the appropriate tool and interface Now see how Data Visualizer can poll variables from the target and display their values in graphical form. Important:  Data polling 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 device through the Atmel Studio debugger backend. First, add a few lines of code containing variables to poll. To do:  Open ui.c and add two global variables to the top of the file. volatile uint32_t write_count = 0; volatile uint32_t read_count = 0; 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 thus 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. To do:  Modify the two ̔startʼ functions in ui.c to increment read and write counters on each access started. void ui_start_read(void) { port_pin_set_output_level(EXT1_PIN_GPIO_0, true); Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 181 read_count++; } void ui_start_write(void) { port_pin_set_output_level(EXT1_PIN_GPIO_1, true); write_count++; } To do:  • Build the project/solution (F7) • Open Data Visualizer • Connect For data polling functionality, enable the Code Profiling interface. To do:  • Start the Data Visualizer session • Launch the debug session using Start Debugging and Break (Alt + F5) Data polling operates on SRAM locations, so to find out where variables are located in SRAM we need to use the Atmel Studio Watch window. To do:  • Locate the two global variables added to ui.c • Right-click each variable and select Add to Watch • Examine the type field of each variable in the Watch window to find its location Switch back to the Data Visualizer to set up the Code Profiling interface and to connect the two variables to a graph. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 182 6.1.1 Application Interaction using Dashboard Controls Now see how components placed on a dashboard in Data Visualizer can be hooked up to variables in the application, and how the dashboard can thus interact with the application at run-time. Instead of a predefined interval of 1000 USB sync pulses (1 second), add a variable compare reference to the original code. To do:  Modify ui.c to include a LED blinker in the ui_process() handler as shown here. volatile uint32_t frame_comparator = 100; volatile uint32_t frames_received = 0; void ui_process(uint16_t framenumber) { frames_received++; if (frames_received >= frame_comparator) { LED_Toggle(LED_0_PIN); frames_received = 0; } } To do:  • Build the project/solution (F7) • Launch a debug session using Start Debugging and Break (Alt + F5) • Find the location of the variable uint32_t frame_comparator 6.2 Terminal Example Code A typical use of the Terminal module is print-type debugging. A serial interface is used to print debug messages from the target device to the terminal. In the following example an SPI interface will be used but the procedure will be the same for any serial interface. The target device is an ATmega256RFR2 on an ATmega256RFR2 Xplained Pro kit. As the SPI interface is already wired internally on the board, the only connection needed is the USB cable between the host computer and the Xplained Pro board. To do:  • Make a new project in Atmel Studio (File → New → Project → GCC C Executable Project) • Replace the content of the automatically generated main.c file with the code below #include #include volatile uint8_t led_on; volatile uint8_t send_message; Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 183 volatile uint8_t ticker = 0; const char* message_on = "LED ON "; const char* message_off = "LED OFF "; ISR (INT4_vect) { // Simple debounce if (PINE & (1 << 4)) return; // Update LED if (led_on) PORTB |= (1 << 4); else PORTB &= ~(1 << 4); // Invert led_on led_on = ~led_on; // Flag a message send send_message = 1; // Increment ticker ticker++; // Reset ticker if (ticker >= 10) ticker = 0; } void spi_send (const char data) { PORTB &= ~(1 << PINB0); // Send a character to the USART SPDR = data; // Wait for the character to be sent while (!(SPSR & (1 << SPIF))) ; PORTB |= (1 << PINB0); } int main(void){ // PORTB4 to output DDRB = (1 << PINB4); // LED OFF PORTB |= (1 << PINB4); led_on = 0; // Enable pullup on button pin to avoid floating line PORTE |= (1< uint16_t adc_value = 0; void adc_init(void){ // Internal 1.5V reference, ADC0 as single ended input ADMUX = (1 << REFS1); // Enable the ADC, ADCSRA |= (1< #include const char* message_on = "NIGHT MODE ON"; const char* message_off = "NIGHT MODE OFF"; uint16_t adc_value = 0; uint8_t nightmode_threshold = 40; uint8_t nightmode_active = 0; void adc_init(void){ // Internal 1.5V reference, ADC0 as single ended input ADMUX = (1 << REFS1); // Enable the ADC, ADCSRA |= (1< nightmode_threshold){ if (0x00 == nightmode_active){ // Changing from night mode inactive to active nightmode_active = 0x01; send_message(message_on); } } else { if (0x01 == nightmode_active){ // Changing from night mode active to inactive nightmode_active = 0x00; send_message(message_off); } } } } To do:  • Build the project, program and run the application by simply selecting Continue (F5) in the Debug menu of Atmel Studio 6.3.3 Using Horizontal Cursor Code 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. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 191 First, the code must be extended to accept incoming data on the CDC USART. The output of the horizontal cursor is a 4-byte float value and will be sent over the CDC interface to the target application. This float value will be used as the threshold for the Night mode switch. #include #include const char* message_on = "NIGHT MODE ON"; const char* message_off = "NIGHT MODE OFF"; union u_float{ float flt; char data[4]; }; uint16_t adc_value = 0; uint8_t nightmode_threshold; uint8_t nightmode_active = 0; union u_float cdc_received_data; uint8_t cdc_read_index=0; ISR (USART1_RX_vect){ // A byte is received on the CDC UART, MSB first cdc_received_data.data[cdc_read_index] = UDR1 & 0xFF; if (3 == cdc_read_index){ // A complete float value is received nightmode_threshold = (uint8_t) cdc_received_data.flt; cdc_read_index = 0; } else { cdc_read_index++; } } void adc_init(void){ // Internal 1.5V reference, ADC0 as single ended input ADMUX = (1 << REFS1); // Enable the ADC, ADCSRA |= (1< nightmode_threshold){ if (0x00 == nightmode_active){ // Changing from nightmode inactive to active nightmode_active = 0x01; send_message(message_on); } } else { if (0x01 == nightmode_active){ // Changing from nightmode active to inactive nightmode_active = 0x00; send_message(message_off); } } } } To do:  • Build the project, program and run the application by simply selecting Continue (F5) in the Debug menu of Atmel Studio 6.4 Oscilloscope Example Code To demonstrate how to use the Oscilloscope module a light sensor target application will be used. The light sensor example is a rather generic data source where an Analog-to-Digital Converter is used to sample the sensor, and the example applies to a wide range of other data sources. The example requires the following equipment and software: • Host computer with Atmel Studio 7 or later installed (Data Visualizer is included) • ATmega256RFR2 Xplained Pro kit • I/O1 Xplained Pro extension To run the example, the following hardware setup is required: • I/O1 Xplained Pro extension connected to ATmega256RFR2 Xplained Pro EXT1 connector • USB cable connected from host computer to ATmega256RFR2 Xplained Pro A picture of the setup is shown below. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 193 To be able to view the light sensor data in the Oscilloscope module, the ATmega256RFR2 target has to be programmed with code that samples the light sensor and sends the data to the Embedded Debugger (EDBG) on the ATmega256RFR2 Xplained Pro over a serial interface. The EDBG then uses the Data Gateway Interface (DGI) to send the data to the host computer. First, a new project for the target application code has to be set up in Atmel Studio. To do:  • Make a new project in Atmel Studio (File → New → Project → GCC C Executable Project) • Replace the content of the automatically generated main.c file with the code below #include #include uint16_t adc_value = 0; volatile uint8_t send_data = 0; void adc_init(void){ // Internal 1.5V reference, ADC0 as single ended input ADMUX = (1 << REFS1); // Enable the ADC, auto triggered mode, interrupt on conversion finished ADCSRA |= (1< #include union u_double{ double dbl; char data[8]; }; uint16_t adc_value = 0; uint8_t nightmode_threshold; uint8_t nightmode_active = 0; union u_double cdc_received_data; uint8_t cdc_read_index=0; ISR (USART1_RX_vect){ // A byte is received on the CDC UART, MSB first cdc_received_data.data[cdc_read_index] = UDR1 & 0xFF; if (7 == cdc_read_index){ // A complete double value is received nightmode_threshold = (uint8_t) cdc_received_data.dbl; cdc_read_index = 0; } else { cdc_read_index++; } } void adc_init(void){ Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 198 // Internal 1.5V reference, ADC0 as single ended input ADMUX = (1 << REFS1); // Enable the ADC, ADCSRA |= (1< nightmode_threshold){ if (0x00 == nightmode_active){ // Changing from nightmode inactive to active nightmode_active = 0x01; } } else { if (0x01 == nightmode_active){ // Changing from nightmode active to inactive nightmode_active = 0x00; } } cdc_send(nightmode_active); } } The code samples the ADC continuously and sends the data over the SPI interface to the EDBG (Embedded Debugger) on the ATmega256RFR2 Xplained Pro board. The EDBG then sends the SPI data Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 199 over DGI to the host computer. The ATmega256RFR2 ADC is 10-bit but only the lower 8 bits contain useful data in this example. In addition, the code sets up the CDC USART and sends the state of the Night mode switch as a single byte. The received data on the CDC USART is parsed as a double value and is used as threshold for the Night mode switch. To do:  Build the project/solution (F7). To do:  • Open the project properties (right click the project in the Solution Explorer and select Properties) • On the Tool tab, select the appropriate tool and interface To do:  Program the application into the target and start the debugging by selecting Continue (F5). Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 200 To do:  Open the Data Visualizer as an extension inside Atmel Studio by selecting it in the Tools menu. 6.6 Auto-Configuration Example Code The Auto-Configuration feature of the Data Stream protocol can be used over any DGI serial interface or Serial Port. In this example, the Virtual COM port of an ATtiny104 Xplained Nano board will be used. This board has a built-in debugger (mEDBG) that can be used to program the target ATtiny104 device, and the emEDBG provides a Virtual COM port over USB that is connected to the UART pins of the ATtiny104. Data Visualizer © 2017 Microchip Technology Inc. User Guide DS40001903B-page 201 The only hardware connection required to run this example is to connect a USB cable between the host computer and the Xplained Nano board. The Data Stream protocol will be used to send the state of the button on the Xplained Nano and the value of a 16-bit counter to the host computer. To do:  • Make a new project in Atmel Studio (File → New → Project → GCC C Executable Project) • Replace the content of the automatically generated main.c file with the code below #include uint8_t start_token = 0xAB; uint8_t config_id_packet[] = { /* Token */ 0x5F, /* Specify checksum LRC8 */ 0xB4, 0x00, 0x86, 0x4A, /* Configuration ID */ 0xC0, 0xFF, 0xEE, 0xC0, 0xFF, 0xEE, 0xC0, 0xFF, 0xEE, 0xC0, 0xFF, 0xEE, /* The actual checksum */ 0x78, /* Inverse of Token */ 0xA0 }; uint16_t count = 0; uint8_t send_id = 0; void uart_send(uint8_t byte){ /* Wait for empty transmit buffer */ while ( !( UCSRA & (1<> 8); uart_send (!(PINB & (1< Driver Libraries Help MPLAB Harmony Integrated Software Framework © 2013-2018 Microchip Technology Inc. All rights reserved. Volume V: MPLAB Harmony Framework Reference This volume provides API reference information for the framework libraries included in your installation of MPLAB Harmony. Description This volume is a programmer reference that details the interfaces to the libraries that comprise MPLAB Harmony and explains how to use the libraries individually to accomplish the tasks for which they were designed. Volume V: MPLAB Harmony Framework © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 2 Driver Libraries Help This section provides descriptions of the Driver libraries that are available in MPLAB Harmony. Driver Library Overview This topic provides help for the MPLAB Harmony driver libraries. It includes a general driver usage overview, as well as sections providing a programmer’s reference for each driver that describes its interface and explains how to use it. Introduction Introduces MPLAB Harmony device drivers and explains common usage concepts. Description MPLAB Harmony device drivers (usually referred to as "drivers") provide simple, highly abstracted C-language interfaces to peripherals and other resources. A driver's interface allows applications and other client modules to easily interact with the peripheral it controls using consistent usage models. Some functions are similar on all drivers, while other functions are unique to a particular type of driver or peripheral. However, driver interface functions are generally independent of the details of how a given peripheral is implemented on any specific hardware or of how many instances of that peripheral exist in a given system. Drivers normally utilize MPLAB Harmony Peripheral Libraries (PLIBs) to access and control peripheral hardware that is built into the processor (and is directly addressable by it). However, drivers can also support external peripheral hardware by calling another driver that directly controls a built-in peripheral to which the external peripheral is connected. For example, an SD Card driver may use a SPI driver to access its external SD Card Flash device. A driver may even be completely abstracted away from any hardware (utilizing no peripheral hardware at all), simply controlling some software resource (such as a buffer queue) or providing some service (such as data formatting or encryption). Using this method, driver and other modules may be "stacked" into layers of software, with each responsible for the details of managing its own resources while hiding those details from client modules that use them. Regardless of the type of peripheral or resource that a MPLAB Harmony driver manages, a driver has the following fundamental responsibilities: • Provide a common system-level interface to the resource • Provide a highly abstracted file system style client interface to the resource • Manage the state of the peripheral or resource • Manage access to the resource A driver’s system interface can be thought of as being a horizontal interface and its client interface can be thought of as being a vertical interface, as shown in the following block diagram. The horizontal or "system" interface provides functions to initialize the driver and keep it running. To keep a driver running, a system loop or ISR function (but never both in the same system) calls its state machine "tasks" function repeatedly, as necessary. Therefore, a driver’s system interface is normally only called by code that is generated by the MPLAB Harmony Configurator (MHC) when you select and configure the driver. Its purpose is to ensure that the driver works independently (conceptually in the background), providing the capabilities it implements. By contrast, the application (or any other "client" of the driver) normally only interacts with the driver’s vertical "client" interface (often thought of as the driver’s API). The client interface provides functions to open the driver for use and interact with it, reading or writing data or performing device-type specific operations. The client interface is what allows the application to access the peripheral in a safe and easy way without worrying about the details of the driver or what other clients it may be serving. Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 3 The following sections describe in general terms how to use these two interfaces and give specific examples to help illustrate the concepts. The subsequent help sections for each individual driver describe their specific interfaces in detail; listing all supported functions, parameters, and return values as well as their data types and expected behavior. You may also refer to the MPLAB Harmony Driver Development guide for additional information on MPLAB Harmony drivers and for information on how to develop your own drivers, if needed. Using a Driver's System Interface Introduces the System Interface of a MPLAB Harmony device driver and explains its usage. Description An MPLAB Harmony driver's system interface provides functions to initialize, deinitialize, and reinitialize an instance of a driver, as well as functions to maintain its state machine (and/or implement its Interrupt Service Routine) and check its current "running" status. Normally, as an MPLAB Harmony application developer or a developer of a "client" module that uses the driver, you will not call the system interface functions directly. The MHC generates calls to the system interface functions of any driver that is used in a project when it generates the system configuration files. Exactly which functions are called and exactly how they’re called depends on the configuration options selected in the project’s active configuration. For example, when the box next to “Use Timer Driver?” is selected in the MHC Options tree (within MPLAB Harmony & Application Configuration > Harmony Framework Configuration > Drivers > Timer), as shown in the following figure, the MHC will generate all necessary definitions and function calls for the Timer Driver’s system interface. Example Timer Driver MHC Options These configuration selections, which are set by default once "Use Timer Driver" is selected, will cause the MHC to generate the following definitions in the system_config.h header file for the main project’s current configuration when Generate Code is clicked. Example Driver Options in system_config.h /*** Timer Driver Configuration ***/ #define DRV_TMR_INTERRUPT_MODE true #define DRV_TMR_INSTANCES_NUMBER 1 #define DRV_TMR_CLIENTS_NUMBER 1 /*** Timer Driver 0 Configuration ***/ #define DRV_TMR_PERIPHERAL_ID_IDX0 TMR_ID_1 #define DRV_TMR_INTERRUPT_SOURCE_IDX0 INT_SOURCE_TIMER_1 #define DRV_TMR_CLOCK_SOURCE_IDX0 DRV_TMR_CLKSOURCE_INTERNAL #define DRV_TMR_PRESCALE_IDX0 TMR_PRESCALE_VALUE_256 #define DRV_TMR_OPERATION_MODE_IDX0 DRV_TMR_OPERATION_MODE_16_BIT #define DRV_TMR_ASYNC_WRITE_ENABLE_IDX0 false #define DRV_TMR_POWER_STATE_IDX0 SYS_MODULE_POWER_RUN_FULL It is important to notice that the Driver Implementation selection in the MHC graphical interface does not correlate to a #define statement in the system_config.h file. Instead, it determines which implementation of the driver this configuration will use. Drivers may have more than one implementation. For example, most drivers have both static and dynamic implementations. A static implementation is usually the smaller of the two, but it is only capable of controlling one instance of a peripheral. An equivalent dynamic implementation will be larger, but it is capable of managing multiple instances of the same type of peripheral using a single instance of the source code (and thus, one instance of the object code). Some drivers may have additional implementations, each one optimized for a different usage. The Driver Implementation pull-down control in the MHC graphical interface allows you to select which implementation the current configuration will use. Normally, you can use only a single implementation of a driver in a given configuration. If you change driver implementations, it changes which implementation is used for all all instances of a peripheral. The number of instances option, for example, Number of Timer Driver Instances, which correlates to the DRV_TMR_INSTANCES_NUMBER definition, determines how many instances of a static driver implementation will be generated or how many instances of a peripheral a dynamic driver implementation will manage. Drivers may also be designed to allow multiple different clients (applications or other modules) to share the same instance of a peripheral or resource. Therefore, a driver will have an option to determine a maximum number of simultaneous clients that it Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 4 can support. For example, Number of Clients (DRV_TMR_CLIENTS_NUMBER) in the Timer Driver, which is fixed at one (1) and cannot be changed, which indicates that the Timer Driver is a single-client driver). The last implementation-specific configuration option in this example is the "Interrupt Mode" (DRV_TMR_INTERRUPT_MODE) setting. This option determines if the implementation is configured to run polled or interrupt driven (discussed further, in a following section). MPLAB Harmony drivers are generally designed to run most effectively in an interrupt-driven configuration, but they can also be run in a polled configuration to simplify debugging or to support task prioritization in an RTOS configuration. The remaining configuration options are all instance-specific initialization options. For a dynamic implementation of a driver, these options are passed into the driver’s Initialize function through an "init" data structure, as shown in the following example. Example Driver Init Structure in system_init.c const DRV_TMR_INIT drvTmr0InitData = { .moduleInit.sys.powerState = DRV_TMR_POWER_STATE_IDX0, .tmrId = DRV_TMR_PERIPHERAL_ID_IDX0, .clockSource = DRV_TMR_CLOCK_SOURCE_IDX0, .prescale = DRV_TMR_PRESCALE_IDX0, .mode = DRV_TMR_OPERATION_MODE_16_BIT, .interruptSource = DRV_TMR_INTERRUPT_SOURCE_IDX0, .asyncWriteEnable = false, }; The exact meaning and usage of these options are described in the Configuring the Library section in the Help documentation for each library. The live MHC Help windowpane displays the associated help section whenever you select one of these options in the options tree. There is one instance-specific initialization option of which you should take special notice: the peripheral ID option (.tmrId, in the Timer Driver example shown). This initialization option associates the driver instance (a zero-based index number) with the peripheral-hardware instance number, as defined by the data sheet for the processor in use. For a dynamic driver, this association is actually made when the driver’s initialize function is called and passes a pointer to the init data structure, as shown in the following code example. Example Driver Initialize Call in system_init.c /* Initialize Drivers */ sysObj.drvTmr0 = DRV_TMR_Initialize(DRV_TMR_INDEX_0, (SYS_MODULE_INIT *)&drvTmr0InitData); In this example, the driver index (DRV_TMR_INDEX_0) is defined as a numeric constant with a value of zero (0). This line of code associates driver instance 0 with hardware timer instance 1 by calling the DRV_TMR_Initialize function from the system initialization code and passing a pointer to the drvTmr0InitData structure. As shown earlier, the Timer Driver’s init structure contains the value TMR_ID_1 (defined by the timer peripheral library), in its .tmrId data member. In a static implementation, the driver peripheral ID macro (DRV_TMR_PERIPHERAL_ID_IDX0) defined in system_config.h is hard-coded into the driver’s instance-specific initialization function when it is generated by the MHC, instead of defining an "init" structure, as shown in the following example; however, the effect is the same. Example Static Driver Initialize Function void DRV_TMR0_Initialize(void) { PLIB_TMR_Stop(DRV_TMR_PERIPHERAL_ID_IDX0); PLIB_TMR_ClockSourceSelect(DRV_TMR_PERIPHERAL_ID_IDX0, DRV_TMR_CLOCK_SOURCE_IDX0); PLIB_TMR_PrescaleSelect(DRV_TMR_PERIPHERAL_ID_IDX0, DRV_TMR_PRESCALE_IDX0); PLIB_TMR_Mode16BitEnable(DRV_TMR_PERIPHERAL_ID_IDX0); PLIB_TMR_Counter16BitClear(DRV_TMR_PERIPHERAL_ID_IDX0); PLIB_TMR_Period16BitSet(DRV_TMR_PERIPHERAL_ID_IDX0, 0); } The DRV_TMR0_Initialize function (with an instance number ‘0’ in the name) in the previous example, is a static version of the DRV_TMR_Initialize system interface function. The call to this function is created by the MHC when it generates the system code. Therefore, that call is always generated with the correct name and with the correct instance number in the name. However, when calling client interface functions (open, close, read, write, etc.) from your own applications, you should not use an instance number in the function name. Dynamic drivers implement the client interface functions without any index numbers in their names. Instead, they use an index or handle parameter to identify the instance of the driver with which to interact. Also, when using static implementations of the drivers, the dynamic API functions are mapped (using the index or handle parameter) to the appropriate static function with the index number in its name. Therefore, calling the dynamic API function makes your application always portable, using whichever driver instance is configured to the index value with which you open the driver. Note: Calling the static versions of the interface function (with the index numbers in their names) is not prohibited. However, it will limit the portability of your application. Understanding this mechanism is critical to understanding how to access the desired peripheral hardware instance. Therefore, it is worth looking at a few demonstration applications to see how it is used. Also, refer to Volume IV: MPLAB Harmony Development > Key Concepts > Key One-to-Many Relationships for additional information on the concepts of having multiple implementations, instances, and clients. Something else worth noting about the previous example call to the Timer Driver’s initialize functions is that when using a dynamic implementation, it returns a value called an “object handle”. In the previous example, that object handle was stored in a system configuration object data member (sysObj.drvTmr0). Object handles returned by module initialization functions are stored in a system configuration structure normally named sysObj. The definition of this structure is generated in the system_definitions.h header file the MHC, as shown in the following example. Example System Object Data Structure Definition in system_definitions.h typedef struct { Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 5 SYS_MODULE_OBJ sysDevcon; SYS_MODULE_OBJ drvTmr0; } SYSTEM_OBJECTS; extern SYSTEM_OBJECTS sysObj; As shown in the previous example, this structure is “extern’d” for use by the other system files. It should not be used by application or library files, only by the system files for a single configuration. The sysObj structure is defined (and allocated in memory) by the system_init.c file, as shown in the following example. Example System sysObj Definition in system_init.c /* Structure to hold the object handles for the modules in the system. */ SYSTEM_OBJECTS sysObj; For this discussion, you can ignore the sysDevcon member of the SYSTEM_OBJECTS structure as it will contain the handle for a different library. The important thing to note is that the drvTmr0 member must be passed into the Timer Driver’s other system interface functions so that the driver has access to the data it needs manage that specific instance of itself (and the associated peripheral hardware), as shown by the following timer ISR example. Example Timer ISR in system_interrupt.c void __ISR(_TIMER_1_VECTOR, ipl1AUTO) IntHandlerDrvTmrInstance0(void) { DRV_TMR_Tasks(sysObj.drvTmr0); } In this ISR example, there are three important things to notice. First, the ISR function itself is associated with a specific vector through the __ISR macro. Different interrupt vectors are associated with different peripheral instances and interrupts on different processors. That is why MPLAB Harmony ISR vector functions are generated in the configuration-specific system_interrupt.c file instead of being part of the driver library itself. Second, the DRV_TMR_Tasks function implements the actual ISR logic of the TMR driver. Most MPLAB Harmony drivers are designed to run interrupt driven and their tasks functions implement the software state machine logic necessary to keep the driver’s interrupt sequence moving from one interrupt to the next until the driver’s task is complete. Third, the sysObj.drvTmr0 object handle’s value is passed into the driver’s tasks function so that it has access to the data it requires to control instance zero (0) of the Timer Driver and its associated hardware instance, which must match the ISR vector instance from which it is called. By default, the Timer Driver is configured to run interrupt-driven, as shown previously. This is not necessarily true for all drivers. However, most drivers (including the Timer Driver) can run in a Polled mode by simply changing the configuration settings. For example, by clearing the "Interrupt Mode" option in the MHC configuration tree and regenerating the configuration code, the previous example ISR will be removed from system_interrupt.c and a call to the Timer Driver’s tasks function will be added to the polled system tasks function, as shown by the following system_tasks.c example code. Example Call to Timer Tasks from system_tasks.c void SYS_Tasks ( void ) { /* Maintain system services */ SYS_DEVCON_Tasks(sysObj.sysDevcon); /* Maintain Device Drivers */ DRV_TMR_Tasks(sysObj.drvTmr0); /* Maintain the application's state machine. */ APP_Tasks(); } In this example, the Timer Driver’s tasks function is called from the polled loop in main by the SYS_Tasks function. The driver’s tasks must still receive the sysObj.drvTmr0 object handle value and its logic operates in exactly the same way, with one exception. Because the driver is now polled, the DRV_TMR_INTERRUPT_MODE option is now defined as false. This causes the driver to be built so that it does not enable its own interrupt, allowing it to run in the polled loop and to not require an ISR. For additional information on the device driver system interface, refer to Volume IV: MPLAB Harmony Development > MPLAB Harmony Driver Development Guide > System Interface and to the documentation for the individual system interface functions for the driver in question. Using a Driver's Client Interface Introduces the Client Interface (or API) of a MPLAB Harmony device driver and explains common usage models. Description Applications (or any other “client” of a MPLAB Harmony device driver) normally only interact with the driver’s client interface (often called its API). The client interface provides functions to “open” the driver (creating a link between the client and the driver) and interact with it, to transfer data or perform operations that are specific to a given type of device, and to “close” the driver (releasing the link). Once a driver has been configured and the configuration code has been generated, the application can assume that the driver will be initialized by the system-wide initialization function (SYS_Initialize) and that its tasks functions will be called as required from either the system-wide tasks function (SYS_Tasks) or from the Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 6 appropriate ISR, depending upon how the driver was designed and configured. To interact with the driver, a client must first call the driver’s open function. This is necessary because all other client interface functions require a “handle” to the device driver that is returned by the open function, as shown in the following example. Example Call to a Driver’s Open Function appData.handleTmr = DRV_TMR_Open(APP_TMR_DRV_INDEX, DRV_IO_INTENT_EXCLUSIVE); if( DRV_HANDLE_INVALID != appData.handleTmr ) { // Advance to next application state. } In this example, the first parameter to the DRV_TMR_Open function is the APP_TMR_DRV_INDEX macro, which is a constant defined to the value of the desired driver instance index number in the system_config.h header file. This value must be the same as the index number used when the desired driver was initialized (as shown in the previous section). This is how the client becomes associated with a specific instance of a driver. The second parameter identifies how the client intends to use the driver. Here, the client wants to have exclusive access to the driver. This means that no other client can currently have an active handle to this driver or this call will fail and return a value of DRV_HANDLE_INVALID. Drivers can also be opened as shared, as blocking or non-blocking and for reading, writing, or both. Refer to the help for the DRV_IO_INTENT data type for additional information about the IO intent parameter of driver open functions. This parameter is merely an advisory parameter. How it is used by the driver is implementation dependent and will be described in the driver’s help documentation. Finally, if the open function was successful, the returned value will be a valid handle to the driver instance. This value is opaque and meaningless to the caller, but it must be passed back to the driver as the first parameter to every other client interface function provided by the driver. A valid handle identifies both the instance of the driver with which the caller interacts and it identifies the client performing the call. This means that, two different client applications or modules opening the same driver in the same system at the same time will receive different values for their “opened” handle. If, for any reason, the driver cannot support the “open” request (it is not finished initializing itself, it has already been opened for exclusive access, or cannot accept new open requests for any reason), it will return a value of DRV_HANDLE_INVALID, indicating the client cannot use it at this time. The DRV_HANDLE_INVALID value is the only non-opaque value that a client should consider meaningful. All other values are only meaningful to the driver that provided them. Note: The appData.handleTmr variable in the previous example is a member of the application’s appData structure. This structure is generated by the MHC as part of the initial application template and should be used to hold an applications state variables. When the client is finished using a driver, it may close it, as shown in the following example. Example Call to a Driver’s Close Function DRV_TMR_Close(appData.handleTmr); This action releases the link to the driver, invalidating the handle and releasing any resources allocated by the driver to track requests from the client. Notice that the close function demonstrates the use of the driver handle, requiring it as a parameter. However, after the close function returns, the handle value cannot be used again. Therefore, the client should not call the driver’s close function until it is done using the driver or it will have to call open again and obtain a new handle to use the driver again. In fact, since many embedded applications are always running, they often do not bother to close drivers they use. But, applications that can go idle or that can be stopped and restarted or that need to share a driver with other clients, but want to conserve resources, or that want use the driver exclusively, can close a driver when they are finished with it for a time and reopen it later when needed. In fact, this is a good way to share a single-client driver, or a driver that supports exclusive access, allowing each client to open it and use it only when a valid handle is obtained. Using a Driver in an Application Describes how to write a state-machine based application that uses a MPLAB Harmony driver. Description MPLAB Harmony generally treats all software modules, including applications, as state machines that have an “initialize” function and a “tasks” function. In fact, when not using a RTOS, it essentially treats the entire system as one large state machine that runs in a common super loop in the “main” function, as shown in the following code example. Example Main Function int main ( void ) { SYS_Initialize(NULL); while(true) { SYS_Tasks(); } return (EXIT_FAILURE); } For the purpose of this discussion, it is important to understand that the application’s APP_Initialize function is called from the SYS_Initialize function, along with the initialization of functions of all drivers and other libraries before execution enters the endless while(true) super loop that continuously calls the system-wide SYS_Tasks function. The application’s APP_Tasks function is then called from the SYS_Tasks function Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 7 inside of the super loop, along with all other polled modules in the system. If you are not already familiar with the organization of an MPLAB Harmony project, please refer to Volume I: Getting Started With MPLAB Harmony > What is MPLAB Harmony? for more information. An application that uses a driver must define a DRV_HANDLE variable, as shown in the following example application header file. Example Driver Application Header (app.h) #include "driver/usart/drv_usart.h" typedef enum { APP_STATE_SETUP=0, APP_STATE_MESSAGE_SEND, APP_STATE_MESSAGE_WAIT, APP_STATE_DONE } APP_STATES; typedef struct { APP_STATES state; DRV_HANDLE usart; char * message; } APP_DATA; In this previous example, the driver handle variable is named usart. To keep the application well organized, it is common to keep all of the application’s state variables (including one called “state” that holds the current state of the application’s state machine) in a common structure (APP_DATA). This structure must be allocated in the application’s source file (usually named app.c) and initialized by the application’s initialization function, as shown in the following example. Example Driver Application Initialization APP_DATA appData; void APP_Initialize ( void ) { /* Place the App in its initial state. */ appData.state = APP_STATE_SETUP; appData.usart = DRV_HANDLE_INVALID; appData.message = “Hello World\n”; } The APP_Initialze function must initialize the state variable (appData.state) to put the application’s state machine in its initial state (the APP_STATE_SETUP value from the APP_STATES enumeration). It must also initialize the driver-handle variable (appData.usart), so that the state machine knows it is not yet valid, and any other application variables (like the string pointer, appData.message). Once the application’s data structure has been initialized, it is safe for the system (the main and SYS_Tasks functions) to call the application’s APP_Tasks function from the super loop to keep it running. The APP_Tasks function then executes state transition code as it switches between states, as demonstrated by the following example. Example Application State Machine Using a Driver void APP_Tasks ( void ) { switch ( appData.state ) { case APP_STATE_SETUP: { if (SetupApplication() == true) { appData.state = APP_STATE_MESSAGE_SEND; } break; } case APP_STATE_MESSAGE_SEND: { if (MessageSend() == true) { appData.state = APP_STATE_MESSAGE_WAIT; } break; } case APP_STATE_MESSAGE_WAIT: Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 8 { if (MessageComplete() == true) { appData.state = APP_STATE_DONE; } break; } case APP_STATE_DONE: default: { break; } } } There are numerous ways to implement a state machine. However, in this example, the application changes state when the APP_Tasks function assigns a new value from the APP_STATES enumeration to the appData.states variable. This happens when one of the state transition function returns true. The end result is an overall application state machine execution that retries each state transition until it succeeds before moving on to the next state, as shown in the following diagram. Application State Machine Note: The APP_STATE_ prefix and all inter-word underscores were removed from the state names to simplify the diagram. After APP_Initialize places the state machine in its initial APP_STATE_SETUP state, the APP_Tasks function will call the SetupApplication function when it is called. When SetupApplication returns true indicating it has completed its task, the state machine advances to the next state. Otherwise, it stays in the same state and retries the tasks in the SetupApplication function. This pattern repeats for the APP_STATE_MESSAGE_SEND state and the MessageSend function as well as the APP_STATE_MESSAGE_WAIT state and the MessageComplete function. When all functions have returned true, the state machine to transitions to the APP_STATE_DONE state where it unconditionally stays having completed its tasks. The sum total of the tasks performed by each transition function completes the overall task of the application. For an application that uses a driver like this example, this includes opening the driver, sending the message, and closing the driver when the message has been sent. How each individual transition function in this example application accomplishes its portion of the overall task, is described in the examples in the following sections to demonstrate how drivers are commonly used. Opening a Driver Describes how to open a driver in a state-machine based application. Description To use a MPLAB Harmony driver, an application (or other client) must call the driver’s “open” function and obtain a valid handle to it, as shown by the following code example. Example Opening a Driver static bool SetupApplication ( void ) { if (appData.usart == DRV_HANDLE_INVALID) Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 9 { appData.usart = DRV_USART_Open(APP_USART_DRIVER_INDEX, (DRV_IO_INTENT_READWRITE|DRV_IO_INTENT_NONBLOCKING)); } if (appData.usart == DRV_HANDLE_INVALID) { return false; } return true; } This example demonstrates the implementation of a state-transition function in a state machine-based application (as shown in the previous Using a Driver in an Application section). The SetupApplication function assumes that the appData.usart variable has been initialized to a value of DRV_HANDLE_INVALID when the application’s state machine was initialized. Therefore, it checks this variable every time it is called to see if it has already completed its task. If appData.usart contains a value of DRV_HANDLE_INVALID, this indicates that the driver has not yet been successfully opened, causing the function to attempt to open the driver by calling DRV_USART_Open. If the USART driver is ready and able to support a new client it will return a valid handle. If it is not ready or able to accept a new client, the driver will return DRV_HANDLE_INVALID and the SetupApplication function will return false and the application will stay in the same state and try to open the driver again the next time its state machine tasks function is called. When DRV_USART_Open returns a valid handle (a handle that is not equal to DRV_HANDLE_INVALID), the SetupApplication function returns true, allowing the application’s state machine to advance. This technique allows the application to try repeatedly to open the driver until it succeeds and guarantees that the application’s state machine will not advance until it has done so. A more sophisticated application might use a time-out mechanism or some other error handling logic to take alternative action if it cannot open the driver in an acceptable time period. However, this simple implementation demonstrates the basic concept of how an MPLAB Harmony application (or any other client module) can safely open a driver before attempting to use it. Using Driver Interface Functions Describes how to use a device driver’s synchronous client interface functions, such as those that read and write data. Description To use a MPLAB Harmony driver’s client interface, the application must first obtain a valid handle from the driver’s “open” function. The examples in this section assume that that has already occurred and that the value of the USART driver handle in the appData.usart variable is valid. The following example code demonstrates the implementation of a state transition function in a state machine-based application (as shown in the previous Using a Driver in an Application section) that writes data to a USART driver for transmission on the associated USART peripheral. Example Writing Data To a Driver static bool MessageSend ( void ) { size_t count; size_t length = strlen(appData.message); count = DRV_USART_Write(appData.usart, appData.message, length); appData.message += count; if (count == length) { return true; } return false; } In this example, the appData.message variable is a char pointer pointing to a null-terminated C-language string that was defined and initialized, as shown in the Using a Driver in an Application section. When MessageSend function is first called by the application’s state machine, it points to the first character in the string to be transmitted. The function calculates the current length of the message string (using the standard C-language strlen function) and calls the driver’s DRV_USART_Write function, passing it the valid driver handle (appData.usart) along with the pointer to the message string and its length, to transmit the message string on the associated USART. If the driver is configured for blocking, the DRV_USART_Write function will not return until it has processed all of the data in the message string. However, that usually requires the use of a RTOS. Normally, in a bare-metal system (one that does not use a RTOS), MPLAB Harmony drivers are used in a non-blocking mode. In that case, a driver will perform as much of a task as it can when one of its interface functions is called without blocking. This means that the function will then return immediately, not waiting for the task to complete, and provide information on how much of the task was completed so the client can react appropriately. In this example, the DRV_USART_Write function will return a count of the number of bytes that were processed by the USART driver by this call to the function. The MessageSend function captures the number of bytes processed by the DRV_USART_Write function in a local count variable. It then effectively removes those bytes from the message string by incrementing the pointer by count bytes (appData.message is a char pointer that increments by the size of one byte for every ‘1’ added to it). Then, the MessageSend function checks to see if it was able to write the entire string Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 10 by comparing the value of count to the value of length that it calculated before calling the driver’s write function. If the two are equal, the task is complete and the MessageSend function returns true and the application’s state machine can continue to the next state. If the two values are not equal, this indicates there are remaining bytes in the message string. The MessageSend function returns false and the application must stay in the same state so that the function can attempt to send the remaining bytes next time it is called. A driver only accepts data when it can process it; therefore, the client can call its data transfer function as many times as necessary, even when the function returns bytes processed if it cannot accept more data at that time. When a client has called a driver interface function there are really only two possibilities. Either the operation has completed when the function returns, or the operation continues after the function has returned. If the operation completes immediately, the client can continue on without taking further action. However, in this example, while the USART driver may have accepted some of the bytes in the message string (perhaps copying them to an internal hardware or software FIFO buffer), it still takes some time to transmit the data over the USART peripheral. In many cases the client may need to know when the operation has actually completed. For this reason, most drivers provide one or more status functions that client applications may call to determine the current status of an operation, as demonstrated in the following example. Example Using a Driver Status Function static bool MessageComplete ( void ) { if (DRV_USART_ClientStatus(appData.usart) == DRV_USART_CLIENT_STATUS_BUSY) { return false; } return true; } This example extends the previous one and assumes that the MessageSend function has returned true and the application has moved to a new state where it calls this function to determine when the driver is idle, which indicates that the message has been completely transmitted. To do that, the MessageComplete function calls the DRV_USART_ClientStatus function. If its return value is DRV_USART_CLIENT_STATUS_BUSY, the USART driver is still working on a previous request by the client. If any other status value is returned, this indicates that the driver is no longer busy with a current request and the MessageComplete function returns true so that the client application’s state machine can move on. A more sophisticated example would check for other possible status values that might indicate some error has occurred and take appropriate action. However, this example is sufficient to demonstrate the concept of checking a driver status function to determine when it is safe to move to another state. Since the client application stays in the same state calling the status function each time its tasks function is called until the desired status is returned, it is effectively polling the status as if it were in a while loop. In fact, it is in the system-wide while loop. However, by not trapping the CPU within its own internal while loop, the application allows other modules (including, potentially, the driver it is using) to continue running and servicing requests. Failing to allow the rest of the system to run can result in a deadlock where the polling application is waiting for a status; however, the driver it is polling will never be able to provide the expected status, as the driver’s own tasks function is not allowed to run. This is why it is important to use the technique described here to “poll” status from modules outside of the current module. Using Asynchronous and Callback Functions Describes how to use an asynchronous interface function to start a driver operation and receive a callback when the operation is complete. Description When a client calls a function that is part of an asynchronous interface, the function starts the request and returns immediately, without finishing the request. The client can then either poll a status function to determine when the request has finished (as demonstrated in the Using Driver Interface Functions section) or it can utilize a callback function to receive a notification from the driver when the request has finished. So, the difference between an asynchronous interface and a synchronous interface is that a synchronous interface may finish all or part of the request before returning, whereas an asynchronous interface will always return immediately having only started the request. Determination of when the request has completed is handled separately. The examples in this section reimplement some of the code from the example application described in the previous sections to demonstrate how to use asynchronous queuing and callback interfaces instead of the synchronous status-polling interface demonstrated in the Using Driver Interface Functions section. To use an asynchronous interface, we will first add a couple of new variables to our example application’s data structure, as shown by the following structure definition. Example Driver Application Header (app.h) typedef struct { APP_STATES state; DRV_HANDLE usart; char * message; DRV_USART_BUFFER_HANDLE messageHandle; bool messageDone; } APP_DATA; The state, usart, and message members of the APP_DATA structure are used in exactly the same way as they were in the previous examples. The messageHandle variable will be explained later and the messageDone variable is a Boolean flag used by the callback function to indicate to the application’s state machine that the message has been completely processed by the driver. Using these new mechanisms results in very minor changes to the application’s state machine, as shown in the following example APP_Initialize and APP_Tasks implementations. Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 11 Example Driver Application State Machine (app.c) void APP_Initialize ( void ) { appData.state = APP_STATE_SETUP; appData.usart = DRV_HANDLE_INVALID; appData.message = APP_MESSAGE; appData.messageHandle = DRV_USART_BUFFER_HANDLE_INVALID; } void APP_Tasks ( void ) { switch ( appData.state ) { case APP_STATE_SETUP: { if (SetupApplication() == true) { appData.state = APP_STATE_MESSAGE_SEND; } break; } case APP_STATE_MESSAGE_SEND: { if (MessageSend() == true) { appData.state = APP_STATE_MESSAGE_WAIT; } break; } case APP_STATE_MESSAGE_WAIT: { if (appData.messageDone) { DRV_USART_Close(appData.usart); appData.state = APP_STATE_DONE; } break; } case APP_STATE_DONE: default: { break; } } } As described previously, the SetupApplication state transition function opens the USART driver and the MessageSend function sends the message to it. However, there is no need for a MessageComplete state transition function. Instead, the application must implement a callback function that will set the appData.messageDone Boolean flag when the driver calls the application "back" to indicate that the message has been sent. Note: The AppInitialize function initializes the state, usart, and message members of the appData structure as previously described. And, it also initializes the messageHandle member with an invalid value to indicate that the message has not yet been sent. However, it does not initialize the messageDone flag because it is more appropriate to clear the flag elsewhere, immediately before calling the driver to send the message. To use a callback mechanism requires the client to implement and register a callback function. A client must register this function after opening the driver, but prior to calling the driver to initiate the operation. This is often done in the same state transition that opens the driver, as shown in the following SetupApplication example. Example Registering a Driver Callback Function static void BufferDone ( DRV_USART_BUFFER_EVENT event, DRV_USART_BUFFER_HANDLE bufferHandle, uintptr_t context ) { APP_DATA *pAppData = (APP_DATA *)context; Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 12 if (event == DRV_USART_BUFFER_EVENT_COMPLETE) { if (bufferHandle == pAppData->messageHandle) { pAppData->messageDone = true; return; } } /* Error */ return; } static bool SetupApplication ( void ) { if (appData.usart == DRV_HANDLE_INVALID) { appData.usart = DRV_USART_Open(APP_USART_DRIVER_INDEX, (DRV_IO_INTENT_READWRITE|DRV_IO_INTENT_NONBLOCKING)); } if (appData.usart == DRV_HANDLE_INVALID) { return false; } DRV_USART_BufferEventHandlerSet(appData.usart, BufferDone, (uintptr_t)&appData); return true; } This code block implements both the BufferDone callback function and the application’s SetupApplication state transition function. After successfully opening the driver, the SetupApplication function calls the DRV_USART_BufferEventHandlerSet function and passes it the driver handle (appData.usart) once it is valid, along with the address of the BufferDone callback function and a context value. The context value can be anything that will fit in an integer large enough to hold a pointer (it is a uintptr_t variable). However, this parameter is most commonly used to pass a pointer to the caller’s own data structure as demonstrated here (even though it is not strictly necessary). This is done primarily to support multi-instance clients. (Refer to Volume IV: MPLAB Harmony Development > Key Concepts for information on multiple instances.) A multi-instance client is designed to manage multiple instances of itself by allocating multiple instances of its own data structure, but only one instance of its object code. Passing a pointer to the data structure in the context variable identifies the specific instance that was used when calling the driver. Once the callback function has been registered with the driver, the application can transition to a state where it attempts to initiate an asynchronous operation. The following example demonstrates the use of a buffer-queuing write function to transmit a message over the USART. Example Queuing a Buffer to a Driver static bool MessageSend ( void ) { appData.messageDone = false; DRV_USART_BufferAddWrite(appData.usart, &appData.messageHandle, appData.message, strlen(appData.message)); if (appData.messageHandle == DRV_USART_BUFFER_HANDLE_INVALID) { return false; } return true; } Before attempting to send the message, this implementation of the MessageSend state transition function clears the appData.messageDone flag so it can detect when the message has completed. Then, it calls the DRV_USART_BufferAddWrite function to queue up the buffer containing the message to be transmitted by the USART driver. To that function, it passes the USART driver handle (appData.usart), the address of the appData.messageHandle variable, the pointer to the message buffer (appData.message), and the size of the buffer in bytes as calculated by the strlen function. The USART driver then adds this buffer to its internal queue of buffers to transmit and provides a handle to the caller that identifies that buffer’s place in the queue by storing it to the appData.messageHandle variable. If, for some reason, the driver is unable to successfully queue up the buffer (perhaps the queue is full), it will assign a value of DRV_USART_BUFFER_HANDLE_INVALID to the appData.messageHandle variable. If that happens, the MessageSend function returns false and the application will stay in the same state and retry the operation again next time its tasks function is called. But, if the operation succeeds, the application advances to the next state. Once the driver completes the operation, it will call the client’s callback function. As shown in the BufferDone code example, the driver passes it an enumeration value that identifies which event has just occurred (the DRV_USART_BUFFER_EVENT_COMPLETE value) in the event parameter. It Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 13 also passes it the handle of the buffer that has just completed (bufferHandle). The client can use the bufferHandle value to verify that it matches the value stored in the appData.bufferHandle variable to uniquely identify an individual buffer. This is very useful when a client queues up multiple buffers at the same, which is being shown in this example as a demonstration. The context parameter to the BufferDone function contains a pointer to the application’s global (appData) data structure. (This is the same value that was passed in the context parameter to the DRV_USART_BufferEventHandlerSet function.) While not strictly necessary in this example, it is very useful for multi-instance clients such as dynamic device drivers and middleware to identify which instance of the client requested the operation. The callback function simply casts the context value back into a pointer to the client’s own data structure’s data type (APP_DATA in this example) and uses it to access the structure members. (Again, please refer to Volume IV: MPLAB Harmony Development > Key Concepts for information on multiple instances.) The callback function uses the event parameter to identify why the callback occurred. If it was called to indicate that the buffer has been processed, the event parameter will contain the value DRV_USART_BUFFER_EVENT_COMPLETE. If it contains any other value an error has occurred. The BufferDone callback also checks to verify that the buffer that completed was the same buffer that it queued up by comparing the bufferHandle value it was passed with the value assigned to the appData.messageHandle variable when the application called DRV_USART_BufferAddWrite. It accesses the message handle value it saved using the pAppData pointer given to it through the context parameter just. Once it has verified that the buffer it queued has completed, it sets the pAppData->messageDone flag to notify the application’s state machine and execution returns to the driver. Note: It is important to understand that the MessageDone callback function executes in the context of the driver, not the application. Depending on how the system is configured, this means that it may be called from within the driver’s ISR context or from another thread context if using a RTOS. In this example, the APP_Tasks application state machine function is essentially the same as the state machine for the synchronous example. The only difference is that when the application is in the APP_STATE_MESSAGE_WAIT state, it checks the appData.messageDone flag to determine when to close the driver and transition to the APP_STATE_DONE state instead of calling a transition function. (It could still do this in a state transition function, but it was done differently in this example to emphasize the concept.) The advantage of using an asynchronous interface over a synchronous one is that it allows the client’s state machine to continue on, potentially doing something else while the requested operation completes. Whereas a synchronous interface has the possibility of blocking the client’s state machine until the operation finishes (when used in a RTOS configuration). An asynchronous interface will always return immediately without blocking (whether a RTOS is used or not). Because of this, most asynchronous interfaces will also allow queuing of more than one operation at a time. This allows client applications to keep a driver continuously busy by keeping the driver’s queue full, maximizing data throughput or operation speed. By contrast, a synchronous interface requires one operation to complete before the synchronous function can be called again to cause the next one to begin. The cost of this capability is that an asynchronous interface has the added complexity of a callback function (if the client cares when the operation finishes) and the fact that a callback function may be called from within the driver’s ISR context, depending on how the driver was designed and configured. This fact generally restricts what can be done within the callback function. For example, it is usually a bad idea to perform lengthy processing within a callback function as it will block all lower priority ISRs (as well as the main loop or other threads) while that processing occurs. Also, it is usually best to not call back into the driver’s own interface functions unless those functions are documented as being safe to call from within the driver’s callback context. Many interface functions (particularly data transfer and data queuing functions) must use semaphores or mutexes to protect their internal data structures in RTOS environments and those constructs cannot be used from within an ISR. It is also important to not make non-atomic (read-modify-write) accesses to the client’s own state data from within the callback function, as the client cannot protect itself against an interrupt that is owned by the driver. That is why a separate Boolean flag variable is commonly used to indicate to the client that the callback has occurred. Most other processing should occur in the client’s state machine. It is usually best to simply capture the event and return as quickly as possible from the callback function and let the application’s state machine tasks function perform any lengthy processing or calling back into the driver. Please refer to Volume IV: MPLAB Harmony Development for additional information. Library Interface Constants Name Description DRV_CONFIG_NOT_SUPPORTED Not supported configuration. DRV_HANDLE_INVALID Invalid device handle. DRV_IO_ISBLOCKING Returns if the I/O intent provided is blocking DRV_IO_ISEXCLUSIVE Returns if the I/O intent provided is non-blocking. DRV_IO_ISNONBLOCKING Returns if the I/O intent provided is non-blocking. _DRV_COMMON_H This is macro _DRV_COMMON_H. _PLIB_UNSUPPORTED Abstracts the use of the unsupported attribute defined by the compiler. Data Types Name Description DRV_CLIENT_STATUS Identifies the current status/state of a client's connection to a driver. DRV_HANDLE Handle to an opened device driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 14 DRV_IO_BUFFER_TYPES Identifies to which buffer a device operation will apply. DRV_IO_INTENT Identifies the intended usage of the device when it is opened. Description Data Types DRV_CLIENT_STATUS Enumeration Identifies the current status/state of a client's connection to a driver. File driver_common.h C typedef enum { DRV_CLIENT_STATUS_ERROR_EXTENDED = -10, DRV_CLIENT_STATUS_ERROR = -1, DRV_CLIENT_STATUS_CLOSED = 0, DRV_CLIENT_STATUS_BUSY = 1, DRV_CLIENT_STATUS_READY = 2, DRV_CLIENT_STATUS_READY_EXTENDED = 10 } DRV_CLIENT_STATUS; Members Members Description DRV_CLIENT_STATUS_ERROR_EXTENDED = -10 Indicates that a driver-specific error has occurred. DRV_CLIENT_STATUS_ERROR = -1 An unspecified error has occurred. DRV_CLIENT_STATUS_CLOSED = 0 The driver is closed, no operations for this client are ongoing, and/or the given handle is invalid. DRV_CLIENT_STATUS_BUSY = 1 The driver is currently busy and cannot start additional operations. DRV_CLIENT_STATUS_READY = 2 The module is running and ready for additional operations DRV_CLIENT_STATUS_READY_EXTENDED = 10 Indicates that the module is in a driver-specific ready/run state. Description Driver Client Status This enumeration identifies the current status/state of a client's link to a driver. Remarks The enumeration used as the return type for the client-level status routines defined by each device driver or system module (for example, DRV_USART_ClientStatus) must be based on the values in this enumeration. DRV_HANDLE Type Handle to an opened device driver. File driver_common.h C typedef uintptr_t DRV_HANDLE; Description Device Handle This handle identifies the open instance of a device driver. It must be passed to all other driver routines (except the initialization, deinitialization, or power routines) to identify the caller. Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 15 Remarks Every application or module that wants to use a driver must first call the driver's open routine. This is the only routine that is absolutely required for every driver. If a driver is unable to allow an additional module to use it, it must then return the special value DRV_HANDLE_INVALID. Callers should check the handle returned for this value to ensure this value was not returned before attempting to call any other driver routines using the handle. DRV_IO_BUFFER_TYPES Enumeration Identifies to which buffer a device operation will apply. File driver_common.h C typedef enum { DRV_IO_BUFFER_TYPE_NONE = 0x00, DRV_IO_BUFFER_TYPE_READ = 0x01, DRV_IO_BUFFER_TYPE_WRITE = 0x02, DRV_IO_BUFFER_TYPE_RW = DRV_IO_BUFFER_TYPE_READ|DRV_IO_BUFFER_TYPE_WRITE } DRV_IO_BUFFER_TYPES; Members Members Description DRV_IO_BUFFER_TYPE_NONE = 0x00 Operation does not apply to any buffer DRV_IO_BUFFER_TYPE_READ = 0x01 Operation applies to read buffer DRV_IO_BUFFER_TYPE_WRITE = 0x02 Operation applies to write buffer DRV_IO_BUFFER_TYPE_RW = DRV_IO_BUFFER_TYPE_READ|DRV_IO_BUFFER_TYPE_WRITE Operation applies to both read and write buffers Description Device Driver IO Buffer Identifier This enumeration identifies to which buffer (read, write, both, or neither) a device operation will apply. This is used for "flush" (or similar) operations. DRV_IO_INTENT Enumeration Identifies the intended usage of the device when it is opened. File driver_common.h C typedef enum { DRV_IO_INTENT_READ, DRV_IO_INTENT_WRITE, DRV_IO_INTENT_READWRITE, DRV_IO_INTENT_BLOCKING, DRV_IO_INTENT_NONBLOCKING, DRV_IO_INTENT_EXCLUSIVE, DRV_IO_INTENT_SHARED } DRV_IO_INTENT; Members Members Description DRV_IO_INTENT_READ Read DRV_IO_INTENT_WRITE Write DRV_IO_INTENT_READWRITE Read and Write DRV_IO_INTENT_BLOCKING The driver will block and will return when the operation is complete DRV_IO_INTENT_NONBLOCKING The driver will return immediately DRV_IO_INTENT_EXCLUSIVE The driver will support only one client at a time DRV_IO_INTENT_SHARED The driver will support multiple clients at a time Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 16 Description Device Driver I/O Intent This enumeration identifies the intended usage of the device when the caller opens the device. It identifies the desired behavior of the device driver for the following: • Blocking or non-blocking I/O behavior (do I/O calls such as read and write block until the operation is finished or do they return immediately and require the caller to call another routine to check the status of the operation) • Support reading and/or writing of data from/to the device • Identify the buffering behavior (sometimes called "double buffering" of the driver. Indicates if the driver should maintain its own read/write buffers and copy data to/from these buffers to/from the caller's buffers. • Identify the DMA behavior of the peripheral Remarks The buffer allocation method is not identified by this enumeration. Buffers can be allocated statically at build time, dynamically at run-time, or even allocated by the caller and passed to the driver for its own usage if a driver-specific routine is provided for such. This choice is left to the design of the individual driver and is considered part of its interface. These values can be considered "flags". One selection from each of the groups below can be ORed together to create the complete value passed to the driver's open routine. Constants DRV_CONFIG_NOT_SUPPORTED Macro Not supported configuration. File driver_common.h C #define DRV_CONFIG_NOT_SUPPORTED (((unsigned short) -1)) Description Not supported configuration If the configuration option is not supported on an instance of the peripheral, use this macro to equate to that configuration. This option should be listed as a possible value in the description of that configuration option. DRV_HANDLE_INVALID Macro Invalid device handle. File driver_common.h C #define DRV_HANDLE_INVALID (((DRV_HANDLE) -1)) Description Invalid Device Handle If a driver is unable to allow an additional module to use it, it must then return the special value DRV_HANDLE_INVALID. Callers should check the handle returned for this value to ensure this value was not returned before attempting to call any other driver routines using the handle. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 17 DRV_IO_ISBLOCKING Macro Returns if the I/O intent provided is blocking File driver_common.h C #define DRV_IO_ISBLOCKING(intent) (intent & DRV_IO_INTENT_BLOCKING) Description Device Driver Blocking Status Macro This macro returns if the I/O intent provided is blocking. Remarks None. DRV_IO_ISEXCLUSIVE Macro Returns if the I/O intent provided is non-blocking. File driver_common.h C #define DRV_IO_ISEXCLUSIVE(intent) (intent & DRV_IO_INTENT_EXCLUSIVE) Description Device Driver Exclusive Status Macro This macro returns if the I/O intent provided is non-blocking. Remarks None. DRV_IO_ISNONBLOCKING Macro Returns if the I/O intent provided is non-blocking. File driver_common.h C #define DRV_IO_ISNONBLOCKING(intent) (intent & DRV_IO_INTENT_NONBLOCKING ) Description Device Driver Non Blocking Status Macro This macro returns if the I/ intent provided is non-blocking. Remarks None. _DRV_COMMON_H Macro File driver_common.h C #define _DRV_COMMON_H Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 18 Description This is macro _DRV_COMMON_H. _PLIB_UNSUPPORTED Macro Abstracts the use of the unsupported attribute defined by the compiler. File driver_common.h C #define _PLIB_UNSUPPORTED Description Unsupported Attribute Abstraction This macro nulls the definition of the _PLIB_UNSUPPORTED macro, to support compilation of the drivers for all different variants. Remarks None. Example void _PLIB_UNSUPPORTED PLIB_USART_Enable(USART_MODULE_ID index); This function will not generate a compiler error if the interface is not defined for the selected device. Files Files Name Description driver.h This file aggregates all of the driver library interface headers. driver_common.h This file defines the common macros and definitions used by the driver definition and implementation headers. Description driver.h This file aggregates all of the driver library interface headers. Description Driver Library Interface Header Definitions Driver Library Interface Header This file aggregates all of the driver library interface headers so client code only needs to include this one single header to obtain prototypes and definitions for the interfaces to all driver libraries. A device driver provides a simple well-defined interface to a hardware peripheral that can be used without operating system support or that can be easily ported to a variety of operating systems. A driver has the fundamental responsibilities: • Providing a highly abstracted interface to a peripheral • Controlling access to a peripheral • Managing the state of a peripheral Remarks The directory in which this file resides should be added to the compiler's search path for header files. File Name drv.h Company Microchip Technology Inc. Volume V: MPLAB Harmony Framework Driver Libraries Help Driver Library Overview © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 19 driver_common.h This file defines the common macros and definitions used by the driver definition and implementation headers. Enumerations Name Description DRV_CLIENT_STATUS Identifies the current status/state of a client's connection to a driver. DRV_IO_BUFFER_TYPES Identifies to which buffer a device operation will apply. DRV_IO_INTENT Identifies the intended usage of the device when it is opened. Macros Name Description _DRV_COMMON_H This is macro _DRV_COMMON_H. _PLIB_UNSUPPORTED Abstracts the use of the unsupported attribute defined by the compiler. DRV_CONFIG_NOT_SUPPORTED Not supported configuration. DRV_HANDLE_INVALID Invalid device handle. DRV_IO_ISBLOCKING Returns if the I/O intent provided is blocking DRV_IO_ISEXCLUSIVE Returns if the I/O intent provided is non-blocking. DRV_IO_ISNONBLOCKING Returns if the I/O intent provided is non-blocking. Types Name Description DRV_HANDLE Handle to an opened device driver. Description Driver Common Header Definitions This file defines the common macros and definitions used by the driver definition and the implementation header. Remarks The directory in which this file resides should be added to the compiler's search path for header files. File Name drv_common.h Company Microchip Technology Inc. ADC Driver Library This section describes the Analog-to-Digital Converter (ADC) Driver Library. Introduction This Analog-to-Digital Converter (ADC) driver provides an interface to manage the ADC module on the Microchip family of microcontrollers. Description An ADC is a vital part of any system that interfaces to real-world signals. While there are many techniques for analog-to-digital conversion, the Microchip family of microcontrollers uses Successive Approximation as one of its primary techniques. Through MHC, this driver provides APIs to interact with the ADC module. Note: Only Static implementation is supported for the ADC Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help ADC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 20 Library Interface Functions Name Description DRV_ADC_Deinitialize Deinitializes the DRV_ADC_Initialize driver module Implementation: Static DRV_ADC_Initialize Initializes the ADC driver. Implementation: Static DRV_ADC_SamplesAvailable Identifies if specified ADC Driver input has any samples available to read. Implementation: Static DRV_ADC_SamplesRead Reads the converted sample data from ADC input Data buffer. Implementation: Static DRV_ADC_Start Starts the software trigger for the ADC driver sampling and converting analog to digital values. Implementation: Static DRV_ADC_Stop Stops the Global Software Level Trigger from continuing triggering for converting ADC data. Implementation: Static DRV_ADCx_Close Closes the ADC instance for the specified driver index. Implementation: Static DRV_ADCx_Open Opens the ADC instance for the specified driver index. Implementation: Static Description This section lists the interface routines, data types, constants and macros for the library. Functions DRV_ADC_Deinitialize Function Deinitializes the DRV_ADC_Initialize driver module Implementation: Static File help_drv_adc.h C void DRV_ADC_Deinitialize(); Returns None. Description This function deinitializes the ADC Driver module for the specified driver instance, making it ready for clients to use it. The initialization routine is specified by the MHC parameters. Remarks None. Preconditions None. Function void DRV_ADC_Deinitialize(void) DRV_ADC_Initialize Function Initializes the ADC driver. Implementation: Static Volume V: MPLAB Harmony Framework Driver Libraries Help ADC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 21 File help_drv_adc.h C void DRV_ADC_Initialize(); Returns None. Description This function initializes the ADC Driver module for the specified driver instance, making it ready for clients to use it. The initialization routine is specified by the MHC parameters. Remarks This function must be called before any other ADC function is called. This function should only be called once during system initialization. Preconditions None. Function void DRV_ADC_Initialize(void) DRV_ADC_SamplesAvailable Function Identifies if specified ADC Driver input has any samples available to read. Implementation: Static File help_drv_adc.h C bool DRV_ADC_SamplesAvailable(uint8_t bufIndex); Returns • true - When ADC data buffer is available to be read • false - When ADC data buffer is not available Description This function identifies whether the specified ADC Driver input has any samples available to read. Remarks None. Preconditions The following functions have been called: • DRV_ADC_Initialize • DRV_ADCx_Open • DRV_ADC_Start or other triggered by source setup in MHC Parameters Parameters Description uint8_t bufIndex ADC input number (ANx) Function bool DRV_ADC_SamplesAvailable(uint8_t bufIndex); DRV_ADC_SamplesRead Function Reads the converted sample data from ADC input Data buffer. Implementation: Static Volume V: MPLAB Harmony Framework Driver Libraries Help ADC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 22 File help_drv_adc.h C uint32_t DRV_ADC_SamplesRead(uint8_t bufIndex); Returns uint32_t - ADC converted sample data. Description This function returns the converted sample data from ADC input Data buffer. Remarks None. Preconditions The following functions have been called: • DRV_ADC_Initialize • DRV_ADCx_Open • DRV_ADC_Start or other triggered by source setup in MHC Parameters Parameters Description uint8_t bufIndex Analog input number (ANx) Function uint32_t DRV_ADC_SamplesRead(uint8_t bufIndex); DRV_ADC_Start Function Starts the software trigger for the ADC driver sampling and converting analog to digital values. Implementation: Static File help_drv_adc.h C void DRV_ADC_Start(); Returns None. Description This function provides a global edge and level trigger for the ADC driver to start the conversion. Remarks None. Preconditions The following functions have been called: • DRV_ADC_Initialize • DRV_ADCx_Open Function void DRV_ADC_Start(void); DRV_ADC_Stop Function Stops the Global Software Level Trigger from continuing triggering for converting ADC data. Implementation: Static Volume V: MPLAB Harmony Framework Driver Libraries Help ADC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 23 File help_drv_adc.h C void DRV_ADC_Stop(); Returns None. Description This function stops the Global Software Level Trigger from continuing triggering for converting ADC data. Remarks None. Preconditions The following functions have been called: • DRV_ADC_Initialize • DRV_ADCx_Open Function void DRV_ADC_Stop(void); DRV_ADCx_Close Function Closes the ADC instance for the specified driver index. Implementation: Static File help_drv_adc.h C void DRV_ADCx_Close(); Returns None. Description This function closes the specified driver instance (where 'x' is the instance number) making it ready for clients to use it. Remarks 'x' indicates the instance number. Preconditions DRV_ADC_Initialize has been called. Function void DRV_ADCx_Close(void) DRV_ADCx_Open Function Opens the ADC instance for the specified driver index. Implementation: Static File help_drv_adc.h C void DRV_ADCx_Open(); Volume V: MPLAB Harmony Framework Driver Libraries Help ADC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 24 Returns None. Description This function opens the specified driver instance (where 'x' is the instance number) making it ready for clients to use it. Remarks 'x' indicates the instance number. Preconditions DRV_ADC_Initialize has been called. Function void DRV_ADCx_Open(void) Bluetooth Driver Libraries This section describes the Bluetooth Driver Libraries that are included in your installation of MPLAB Harmony. BM64 Bluetooth Driver Library This section describes the BM64 Bluetooth Driver Library. Introduction This library provides an Applications Programming Interface (API) to manage a BM64 Module that is connected to a Microchip PIC32 microcontroller using UART and I²S for providing Bluetooth solutions for audio and Bluetooth Low Energy (BLE) applications. Description The BM64 is a Bluetooth 4.2 Stereo Module that supports classic A2DP, AVRCP, HFP, HSP, and SPP protocols, as well as Bluetooth Low Energy (BLE). The BM64 streams I2S audio at up to 24-bit and 96 kHz, and uses a UART to receive commands from the host microcontroller (PIC32) and send events back over the same interface. Protocols supported by the BM64 include A2DP, AVRCP, HFP, HSP, SPP, and BLE. However, this version of the driver only supports A2DP, AVRCP, HFP, and BLE. The BM64 can be connected to a microphone (for HFP) and also has line-input; however, the latter is not supported by this driver. The multi-speaker modes of the BM64 are also not handled by this driver. A typical interface of BM64 to a Microchip PIC32 device is provided in the following diagram: Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 25 BM64 to PIC32 Device Interface An example demonstration application using this library to interface with the BM64 for audio is BM64_a2dp_hfp, which runs on the PIC32 Bluetooth Audio Development Kit and is used to stream A2DP audio from a Bluetooth host such as a smartphone to a pair of headphones connected to the Audio DAC Daughter Board which comes with the PIC32 Bluetooth Audio Development Kit. The smartphone is controlled using the AVRCP functions of the library. That demonstration can also automatically answer a voice call coming in via Hands-Free Protocol (HFP), interrupting (and pausing) any A2DP streaming in progress. An example demonstration application using this library to interface with the BM64 for BLE functionality is BM64_ble_comm, which is used to send a string of characters to a smartphone when one of the push buttons is pressed on the PIC32 Bluetooth Audio Development Kit, and to receive a string of characters from the smartphone and display them on the LCD of the PIC32 Bluetooth Audio Development Kit, both using the "Transparent Service" feature of the BM64. The following diagram shows the specific connections used in the PIC32 Bluetooth Audio Development Kit, which uses a PIC32MX470F512L microcontroller: PIC32 Device and Module Connections Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 26 Using the Library This topic describes the basic architecture of the BM64 Bluetooth Driver Library and provides information and examples on its use. Description Interface Header File: drv_bm64.h The interface to the BM64 Bluetooth Driver library is defined in the drv_bm64.h header file. Any C language source (.c) file that uses the BM64 Bluetooth Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Library Source Files: The BM64 Bluetooth Driver Library source files are provided in the \framework\driver\bluetooth\bm64\src directory. This 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. When the library is being used to stream A2DP audio from the BM64 to the PIC32, the BM64 must be configured as a I2S slave device. See the application BM64_bootloader demonstration application for instructions on how to do this. Abstraction Model This library provides a low-level abstraction of the BM64 Bluetooth Driver Library 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 abstraction model shown in the following diagram depicts how the BM64 Bluetooth Driver is positioned in the MPLAB Harmony framework. The BM64 Bluetooth Driver uses the USART Driver Library to control the BM64 and receive event notifications, the I2S Driver Library is used to receive audio from the BM64, and the Timer Driver for periodic timing. BM64 Bluetooth Driver Abstraction Model Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 27 Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The BM64 Bluetooth Driver Library provides an API interface to transfer control commands and digital audio data to the serially interfaced BM64 Bluetooth module. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the BM64 Bluetooth Driver Library. Library Interface Section Description System Functions Provides system module interfaces, device initialization, tasks and status functions. Client Setup Functions Provides open and close functions. Data Transfer Functions Provides data transfer functions. Settings Functions Provides driver specific functions for settings, such as volume control and sampling rate. Bluetooth-specific Functions Provides functions that are Bluetooth-specific. AVRCP Functions Provides functions that are used for AVRCP control. Device Name and Address Functions Provides functions for getting and setting the Bluetooth name and address. BLE Functions Provides BLE-specific functions. How the Library Works Provides information on how the library works. Description The library provides interfaces to support: • System • Client Setup • Data Transfer • Settings • Bluetooth • AVRCP • Device Name and Address • BLE The library can be used by programs providing functionality for audio (A2DP, AVRCP and BLE), or BLE, or both. For audio (A2DP/AVRCP/HFP), typically, there will be one simple state machine for the application and a second state machine just for the audio. After the application initializes, the audio state machine will open the BM64 Bluetooth Driver using a call to its Open function. Then, it will set up callbacks for each of two event handlers, and then open the codec driver using a call to its Open function and set up a callback from it. Then, the driver will wait until the BM64 initialization is complete, at which time the application state machine instructs the audio state machine to perform an initial buffer read from the BM64 using an AddRead call. case AUDIO_STATE_OPEN: { if (SYS_STATUS_READY == DRV_BT_Status()) { // open BT module, including RX audio stream audioData.bt.handle = DRV_BT_Open(DRV_IO_INTENT_READ, DRV_BT_PROTOCOL_ALL); if(audioData.bt.handle != DRV_HANDLE_INVALID) { audioData.state = AUDIO_STATE_SET_BT_BUFFER_HANDLER; } } } break; case AUDIO_STATE_SET_BT_BUFFER_HANDLER: { DRV_BT_BufferEventHandlerSet(audioData.bt.handle, audioData.bt.bufferHandler, audioData.bt.context); DRV_BT_EventHandlerSet(audioData.bt.handle, audioData.bt.eventHandler, (uintptr_t)0); audioData.state = AUDIO_STATE_CODEC_OPEN; } break; case AUDIO_STATE_CODEC_OPEN: Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 28 { audioData.codec.handle = DRV_CODEC_Open(DRV_CODEC_INDEX_0, DRV_IO_INTENT_WRITE | DRV_IO_INTENT_EXCLUSIVE); if(audioData.codec.handle != DRV_HANDLE_INVALID) { audioData.state = AUDIO_STATE_CODEC_SET_BUFFER_HANDLER; } } break; case AUDIO_STATE_CODEC_SET_BUFFER_HANDLER: { _setCodecSamplingRate(DRV_BT_AUDIO_SAMPLING_RATE); DRV_CODEC_BufferEventHandlerSet(audioData.codec.handle, audioData.codec.bufferHandler, audioData.codec.context); audioData.state = AUDIO_STATE_INIT_DONE; } break; case AUDIO_STATE_INIT_DONE: { // waits in this state until BT initialization done and app state machine // calls audioStart() to set state to AUDIO_STATE_BT_SUBMIT_INITIAL_READS break; } After the initial buffer read has been completed, the buffer event handler for the BM64 will get a DRV_BT_BUFFER_EVENT_COMPLETE event. Once the queue has filled up, this will advance the audio state machine’s state so that it adds the buffer to the codec’s queue using its AddWrite function call. It then also makes a new call to the AddRead function to keep the queue filled. When the buffer event handler for the codec gets a DRV_CODEC_BUFFER_EVENT_COMPLETE event, it will mark the buffer free for use again. See the BM64 demonstration application, BM64_a2dp_hfp, for more information and more example code. BLE-only applications are much simpler since they do not have to process any audio. Again typically there will be one simple state machine for the application and a second state machine just for the BLE functionality. After the application initializes, the BLE state machine will open the BM64 Bluetooth driver using a call to its Open function, then it will set up a callback for an event handler. The application will call one of the BLE Send functions to send data to the host (smartphone). The event handler will be called whenever data has been received from the BM64, or when the connection status changes. See the BM64 demonstration application, BM64_ble_comm, for more information and example code. System Functions This section describes the BM64 Bluetooth driver functions for initialization, maintaining task state and returning status. Description Initialization The function DRV_BM64_Initialize is called by the function SYS_Initialize, in the file system_init.c, to initialize the BM64 Bluetooth driver using constants from the generated system_config.h file. Tasks The function DRV_BM64_Tasks is called from the System Task Service via the function SYS_Tasks in the file system_tasks.c to maintain the driver's internal control and data interface state machine. One can use the function DRV_BM64_TasksReq to make a power on/power off task request (DRV_BM64_REQ_SYSTEM_OFF or DRV_BM64_REQ_SYSTEM_ON). Status The function DRV_BM64_Status returns the BM64 Bluetooth driver status, such as SYS_STATUS_READY, SYS_STATUS_BUSY, or SYS_STATUS_ERROR. The driver should not be opened until it has been marked ready. Example: // note generic version of call (DRV_BT instead of DRV_BM64) is used if (SYS_STATUS_READY == DRV_BT_Status()) { // This means the driver can be opened using the // DRV_BT_Open() function. } The BM64-specific function DRV_BM64_GetPowerStatus returns the current power status, e.g. DRV_BM64_STATUS_OFF, DRV_BM64_STATUS_OFF, and DRV_BM64_STATUS_READY. Once it returns a ready status, this means the BM64 driver has completed its internal state machine initialization and can begin processing audio. Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 29 Example: case APP_STATE_WAIT_INIT: { // note generic version of call (DRV_BT instead of DRV_BM64) is used if (DRV_BT_STATUS_READY == DRV_BT_GetPowerStatus()) { appData.state=APP_STATE_IDLE; // can start processing audio } } Client Functions This section describes the BM64 Bluetooth driver functions for client setup (open, close, and setting up event handlers). Description Open and Close For the application to start using an instance of the module, it must call the DRV_BM64_Open function which provides a driver handle to the BM64 Bluetooth driver instance. Note: It is necessary to check the status of driver initialization before opening a driver instance. The status of the BM64 Bluetooth Driver can be known by calling DRV_BM64_Status. Example: case AUDIO_STATE_OPEN: { if (SYS_STATUS_READY == DRV_BT_Status()) { // open BT module, including RX audio stream audioData.bt.handle = DRV_BT_Open(DRV_IO_INTENT_READ, DRV_BT_PROTOCOL_ALL); if(audioData.bt.handle != DRV_HANDLE_INVALID) { audioData.state = AUDIO_STATE_SET_BT_BUFFER_HANDLER; } } } Event Handlers Event handlers are functions in the user’s code that are used as callbacks from the driver when something occurs that the client needs to know about. The function DRV_BM64_BufferEventHandlerSet is called by a client to identify a buffer-related event handling function for the driver to call back. The prototype for the callback is defined by DRV_BM64_BUFFER_EVENT_HANDLER. The callback will be called with the event DRV_BT_BUFFER_EVENT_COMPLETE. The function DRV_BM64_EventHandlerSet is called by a client to identify a general event handling function for the driver to call back. The prototype for the callback is defined by DRV_BM64_EVENT_HANDLER. For audio applications, the callback will be called with events such as DRV_BT_EVENT_VOLUME_CHANGED, DRV_BT_EVENT_SAMPLERATE_CHANGED, and DRV_BT_EVENT_PLAYBACK_STATUS_CHANGED. For BLE applications, the callback will be called for events such as DRV_BT_EVENT_BLESPP_MSG_RECEIVED and DRV_BT_EVENT_BLE_STATUS_CHANGED. Example: case APP_STATE_SET_BT_BUFFER_HANDLER: { // note generic version of calls (DRV_BT instead of DRV_BM64) are used DRV_BT_BufferEventHandlerSet(appData.bt.handle, appData.bt.bufferHandler, appData.bt.context); DRV_BT_EventHandlerSet(appData.bt.handle, appData.bt.eventHandler, (uintptr_t)0); appData.state = APP_STATE_CODEC_OPEN; } Data Transfer Function This section describes the BM64 Bluetooth Driver data transfer function. Description The function DRV_BM64_BufferAddRead schedules a non-blocking read operation. It returns with a valid buffer handle in the bufferHandle Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 30 argument if the read request was scheduled successfully. If the requesting client registered an event callback with the driver, the driver will issue a DRV_BM64_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully or DRV_BM64_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Example: case APP_STATE_BT_BUFFER_COMPLETE: { if (!_bufferUsed[appData.readIndex]) { //Next BT Read Queued // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_BufferAddRead(appData.bt.handle, &appData.bt.readBufHandle, audioBuffer[appData.readIndex], appData.bt.bufferSize); if(appData.bt.readBufHandle != DRV_BT_BUFFER_HANDLE_INVALID) { appData.bt.readBufHandle = DRV_BT_BUFFER_HANDLE_INVALID; _bufferUsed[appData.readIndex] = true; appData.readIndex++; if(appData.readIndex >= AUDIO_QUEUE_SIZE) { appData.readIndex = 0; } appData.state = APP_STATE_BT_WAIT_FOR_BUFFER_COMPLETE; } } } Settings Functions This section describes the BM64 Bluetooth Driver functions for getting and changing settings such as volume and sample rate. Description The function DRV_BM64_VolumeGet returns the volume for the current mode (A2DP or HFP) in percent (0-100), and the corresponding function DRV_BM64_VolumeSet sets the volume in percent. The functions DRV_BM64_VolumeUp and DRV_BM64_VolumeDown turn the volume up and down on the host device (e.g. smartphone) by one increment (about 3% of full-scale). Either of these will result in a callback with the event DRV_BM64_EVENT_VOLUME_CHANGED specifying the new volume setting. Example: case BUTTON_STATE_PRESSED: // (debouncing not shown) { // bump the volume up one notch based on a button press if (BSP_SwitchStateGet(BSP_SWITCH_2)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_volumeUp(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } . . . // later, a call will come back to the event handler callback function // (previously set up via a call to DRV_BM64_EventHandlerSet) static void _BLEEventHandler(DRV_BT_EVENT event, uint32_t param, uintptr_t context) { switch(event) { case DRV_BM64_EVENT_VOLUME_CHANGED: { uint16_t volume7bits = (127*param)/100; // convert to 7 bits DRV_AK4384_VolumeSet(audioData.codec.handle, // update codec’s volume DRV_AK4384_CHANNEL_LEFT_RIGHT,volume7bits); laString tempStr; char buf[5]; sprintf(buf,"%3d%%",param); laWidget_SetVisible((laWidget*)GFX_VOLUME_VALUE, LA_TRUE); tempStr = laString_CreateFromCharBuffer(buf, &LiberationSans12); laLabelWidget_SetText(GFX_VOLUME_VALUE, tempStr); // update screen Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 31 laString_Destroy(&tempStr); } } } Sample Rate This section describes the functions for getting and setting the sampling rate (e.g., 8000, 44100, or 48000 Hz) as a 32-bit integer. Description The function DRV_BM64_EnterBTPairingMode is used to enter into pairing mode. Once the BM64 is paired with a device, it will automatically attempt to connect with it again on the next power cycle. Calling DRV_BM64_DisconnectAllLinks will disconnect the BM64 from the host (smartphone) but will not erase the pairing. So another call to the function DRV_BM64_LinkLastDevice will reconnect. However calling the function DRV_BM64_ForgetAllLinks will erase all pairing information, and another call to DRV_BM64_EnterBTPairingMode will be required to re-establish a connection. Example: case BUTTON_STATE_PRESSED: // (debouncing not shown) { // initiate pairing with a button press if (BSP_SwitchStateGet(BSP_SWITCH_1)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_EnterBTPairingMode(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } The function DRV_BM64_GetLinkStatus returns the current link status, returning an 8-bit value containing the current link status defined by DRV_BM64_LINKSTATUS enum. This can be used to restrict calls to AVRCP functions only when an AVRCP link is established. Example: // note generic version of call (DRV_BT instead of DRV_BM64) is used if (DRV_BT_GetLinkStatus(appData.bt.handle) & DRV_BT_AVRCP_LINK_STATUS) { DRV_BT_CancelForwardOrRewind(appData.bt.handle); } AVRCP Functions This section describes the functions for getting and setting the Bluetooth device’s name and address. Description The function DRV_BM64_SetBDName is called to set a temporary Bluetooth device name from an ASCII string buffer. The function DRV_BM64_GetBDName is called to get the current Bluetooth device name, and DRV_BM64_GetBDAddress is called to get the Bluetooth device address. Example: laString tempStr; char buf [DRV_BT_MAXBDNAMESIZE+1]; // note generic version of calls (DRV_BT instead of DRV_BM64) are used DRV_BT_GetBDName(appData.bt.handle, buf, DRV_BT_MAXBDNAMESIZE+1); tempStr = laString_CreateFromCharBuffer(buf, &LiberationSans12); laLabelWidget_SetText(GFX_BTNAME_VALUE, tempStr); // display BT name laString_Destroy(&tempStr); DRV_BT_GetBDAddress(appData.bt.handle, buf); tempStr = laString_CreateFromCharBuffer(buf, &LiberationSans12); laLabelWidget_SetText(GFX_BTADDRESS_VALUE, tempStr); // display BT address laString_Destroy(&tempStr); BLE Functions This section describes the functions specific to Bluetooth Low Energy (BLE) operations, such as sending and receiving data, and BLE connection-related operations. Description The function DRV_BM64_ReadByteFromBLE is used to receive data one byte at a time; the function DRV_BM64_ReadDataFromBLE is used to receive multiple bytes. Each of them return a Boolean, which is true if data is returned or false if there is no data to return. You can use the function DRV_BM64_ClearBLEData to clear out the receive buffer before starting. Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 32 Example: uint8_t byte; // note generic versions of calls (DRV_BT instead of DRV_BM64) are used DRV_BT_ClearBLEData(appData.bt.handle); // wait for byte to arrive while (!DRV_BT_ReadByteFromBLE(appData.bt.handle, &byte)) { // should have some sort of way to break out of here if byte never arrives } Sending Data The function DRV_BM64_SendByteOverBLE Is used to send one byte of data at a time; the function DRV_BM64_SendDataOverBLE is used to send multiple bytes of data. Example: #define BUFSIZE 100 uint8_t buf [BUFSIZE]; // (code goes here to fill in buffer with data) // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_SendDataOverBLE(appData.bt.handle, buf, BUFSIZE); Connection Status The function DRV_BM64_BLE_EnableAdvertising is called to enable or disable BLE advertising. The function DRV_BM64_BLE_QueryStatus queries the BM64 to respond with a DRV_BM64_EVENT_BLE_STATUS_CHANGED event, which will indicate if the BM64 BLE status is standby, advertising, scanning or connected. Example: // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_BLE_QueryStatus(appData.bt.handle); . . . // later, a call will come back to the event handler callback function // (previously set up via a call to DRV_BM64_EventHandlerSet) static void _BLEEventHandler(DRV_BT_EVENT event, uint32_t param, uintptr_t context) { switch(event) { case DRV_BT_EVENT_BLE_STATUS_CHANGED: { // do case switch based on param variable switch(param) { case DRV_BM64_BLE_STATUS_STANDBY: case DRV_BM64_BLE_STATUS_SCANNING: laWidget_SetVisible((laWidget*)GFX_CONNECTED, LA_FALSE); laWidget_SetVisible((laWidget*)GFX_PAIRED, LA_FALSE); laWidget_SetVisible((laWidget*)GFX_NOPAIR_NOCONNECTION, LA_TRUE); break; case DRV_BM64_BLE_STATUS_ADVERTISING: laWidget_SetVisible((laWidget*)GFX_CONNECTED, LA_FALSE); laWidget_SetVisible((laWidget*)GFX_PAIRED, LA_TRUE); // actually, advertising laWidget_SetVisible((laWidget*)GFX_NOPAIR_NOCONNECTION, LA_FALSE); break; case DRV_BM64_BLE_STATUS_CONNECTED: laWidget_SetVisible((laWidget*)GFX_CONNECTED, LA_TRUE); laWidget_SetVisible((laWidget*)GFX_PAIRED, LA_FALSE); laWidget_SetVisible((laWidget*)GFX_NOPAIR_NOCONNECTION, LA_FALSE); break; } } } Configuring the Library Macros Name Description INCLUDE_BM64_BLE Identifies whether the driver should include BLE Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 33 INCLUDE_BM64_I2S Identifies whether the driver should include HFP,A2DP,AVRCP functionality. INCLUDE_DEPRECATED_MMI_COMMANDS Identifies whether the driver should use deprecated MMI commands. Description The configuration of the BM64 Bluetooth Driver is based on the file system_config.h. This header file contains the configuration selection for the BM64 Bluetooth Driver. Based on the selections made, the driver may support the selected features. These configuration settings will apply to all instances of the BM64 Bluetooth Driver. This header can be placed anywhere, 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. INCLUDE_BM64_BLE Macro Identifies whether the driver should include BLE File drv_bm64_config_template.h C #define INCLUDE_BM64_BLE Description Include BLE features? Identifies whether the driver should include BLE (Bluetooth Low Energy) functions. This option currently does not have any effect on the code size. true (checked, default) - include BLE functionality. false (unchecked) - do not include BLE functionality. Remarks None INCLUDE_BM64_I2S Macro Identifies whether the driver should include HFP,A2DP,AVRCP functionality. File drv_bm64_config_template.h C #define INCLUDE_BM64_I2S Description Include HFP,A2DP,AVRCP protocols? Identifies whether the driver should include the interface to support HFP, A2DP and AVRCP protocols, which by default also brings in the I2S driver and the default codec based on the BSP selected. If you are building a BLE-only application, uncheck this option. true (checked, default) - include HFP,A2DP,AVRCP functionality. false (unchecked) - do not include HFP,A2DP,AVRCP functionality. Remarks None INCLUDE_DEPRECATED_MMI_COMMANDS Macro Identifies whether the driver should use deprecated MMI commands. File drv_bm64_config_template.h C #define INCLUDE_DEPRECATED_MMI_COMMANDS Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 34 Description Use Deprecated MMI Commands? There are currently two versions of the BM64 Audio UART Command Set, which is used by the PIC32 to send commands to the BM64 module and receive responses (events) back from the BM64. The original is version 1.00 and the updated one is version 2.0x. Version 2.0x deprecates some MMI commands, and adds some new commands to replace them. If the DRV_BM64_PlayPreviousSong and DRV_BM64_PlayNextSong functions are not working but other AVRCP functions are working properly, try unchcing this option. true (checked, default) - use deprecated MMI commands. false (unchecked) - do not deprecated MMI commands. Remarks None Configuring the MHC Provides examples on how to configure the MPLAB Harmony Configurator (MHC) for a specific driver. Description The following figure shows an example MHC configuration for the BM64 Bluetooth Driver. The option Include HFP,A2DP,AVRCP protocols? identifies whether the driver should include the interface to support HFP, A2DP and AVRCP protocols, which by default also brings in the I2S driver and the default codec based on the BSP selected. If you are building a BLE-only application, uncheck this option. The option Include BLE features? identifies whether the driver should include BLE functions. If you are not using any BLE functionality, uncheck this option. When Use BM64 Driver? is selected, and you have already selected the PIC32 Bluetooth Audio Development Kit (AK4384), the proper configuration for the AK4384, I2S, and Timer will have already been made for you, including: • Under Drivers/CODEC, • Use_Codec_AK4384 selected • I2S Driver (used for data interface interface) instance set to DRV_I2S_INDEX_1 • Under I2S, • Use I2S Driver Selected • DMA Mode Selected • Transmit DMA Support Selected • Receive DMA Support Selected • Enable DMA Channel Interrupts selected • Sampling Rate set to 8000 • Number of I2S Instances set to 2 • I2S Driver Instance 0 selected • I2S Module ID set to SPI_ID_2 (BM64 Module as wired on BTADK) • Audio Protocol Mode set to DRV_I2S_AUDIO_I2S • I2S Driver Instance 1 selected Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 35 • I2S Module ID set to SPI_ID_1 (AK4384 DAC Module as wired on BTADK) • Audio Protocol Mode set to DRV_I2S_AUDIO_LFET_JUSTIFIED Building the Library This section lists the files that are available in the BM64 Bluetooth Driver Library. Description This section lists the files that are available in the /src folder of the BM64 Bluetooth 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. 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 /framework/driver/bluetooth/bm64. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_bm64.h Header file that exports the driver API. 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 drv_bm64_ble.h Header file for the internal functions of the driver related to BLE. drv_bm64_command_decode.h Header file for the internal functions of the driver for decoding events from the BM64. drv_bm64_command_send.h Header file for the internal functions of the driver for sending commands to the BM64 drv_bm64_gpio.h Header file for the internal functions of the driver related to the BM64’s control pins. drv_bm64_line_in.h Header file for the internal functions of the driver related to the BM64’s line in input. ./src/framework/driver/bluetooth/bm64/ drv_bm64_local.h Header file for the functions local to the BM64 driver (generated from template). drv_bm64_sha1.h Header file for the internal functions of the driver for performing SHA hashes. drv_bm64_uart.h Header file for the internal functions of the driver related to the BM64’s UART interface. ./src/framework/driver/bluetooth/bm64/src/ drv_bm64.c Main source implementation file for the driver (generated from template). src/drv_bm64_ble.c Source file for the internal functions of the driver related to BLE. src/drv_bm64_command_decode.c Source file for the internal functions of the driver for decoding events from the BM64. src/drv_bm64_command_send.c Source file for the internal functions of the driver for sending commands to the BM64 src/drv_bm64_gpio.c Source file for the internal functions of the driver related to the BM64’s control pins. src/drv_bm64_line_in.c Source file for the internal functions of the driver related to the BM64’s line in input. src/drv_bm64_sha1.c Source file for the internal functions of the driver for performing SHA hashs. src/drv_bm64_uart.c Source file for the internal functions of the driver related to the BM64’s UART interface. 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 There are no optional files for this driver. N/A Module Dependencies The BM64 Bluetooth Driver Library depends on the following modules: • I2S Driver Library • Timer Driver Library • USART Driver Library Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 36 Library Interface a) System Functions Name Description DRV_BM64_GetPowerStatus Gets the current status of the BM64 Bluetooth driver module (BM64-specific). DRV_BM64_Initialize Initializes hardware and data for the instance of the BM64 Bluetooth module DRV_BM64_Status Gets the current system status of the BM64 Bluetooth driver module. DRV_BM64_TaskReq Make a power on/power off task request. DRV_BM64_Tasks Maintains the driver's control and data interface state machine. b) Client Setup Functions Name Description DRV_BM64_BufferEventHandlerSet This function allows a client to identify a event handling function for the driver to call back. DRV_BM64_Close Close an opened-instance of the BM64 Bluetooth driver. DRV_BM64_EventHandlerSet This function allows a client to identify an event handling function for the driver to call back. DRV_BM64_Open Open the specified BM64 driver instance and returns a handle to it c) Data Transfer Functions Name Description DRV_BM64_BufferAddRead Schedule a non-blocking driver read operation. d) Settings Functions Name Description DRV_BM64_SamplingRateGet Return the current sampling rate. DRV_BM64_SamplingRateSet Set the current sampling rate. DRV_BM64_volumeDown Turn the volume down on the host device. DRV_BM64_VolumeGet returns 7-bit value 0-127 DRV_BM64_VolumeSet Set current volume. DRV_BM64_volumeUp Turn the volume up on the host device. e) Bluetooth-specific Functions Name Description DRV_BM64_DisconnectAllLinks Disconnect all links. DRV_BM64_EnterBTPairingMode Enter Bluetooth pairing mode. DRV_BM64_ForgetAllLinks Forget all pairings. DRV_BM64_GetLinkStatus Return link status. DRV_BM64_LinkLastDevice Link last device. f) AVRCP Functions Name Description DRV_BM64_CancelForwardOrRewind Cancel previous fast forward or rewind request. DRV_BM64_FastForward Fast forward the media. DRV_BM64_GetPlayingStatus Return the current playing status of the device. DRV_BM64_Pause Pause playback. DRV_BM64_Play Start playback. DRV_BM64_PlayNextSong Play the next song. DRV_BM64_PlayPause Toggle play/pause mode. DRV_BM64_PlayPreviousSong Play the previous song. DRV_BM64_Rewind Rewind the media. DRV_BM64_Stop Stop playback. g) Device Name and Address Functions Name Description DRV_BM64_GetBDAddress Return the Bluetooth address. Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 37 DRV_BM64_GetBDName Return Bluetooth device name. DRV_BM64_SetBDName Set the Bluetooth device name. h) BLE Functions Name Description DRV_BM64_ClearBLEData Clear the BLE receive buffer. DRV_BM64_ReadByteFromBLE Read a byte over BLE. DRV_BM64_ReadDataFromBLE Read data over BLE. DRV_BM64_SendByteOverBLE Send a byte over BLE. DRV_BM64_SendDataOverBLE Send data over BLE. DRV_BM64_BLE_QueryStatus Query BM64 LE status. DRV_BM64_BLE_EnableAdvertising Enable or disable advertising. i) Data Types and Constants Name Description DRV_BM64_BUFFER_EVENT This is macro DRV_BM64_BUFFER_EVENT. DRV_BM64_BUFFER_EVENT_COMPLETE This is macro DRV_BM64_BUFFER_EVENT_COMPLETE. DRV_BM64_BUFFER_HANDLE This is macro DRV_BM64_BUFFER_HANDLE. DRV_BM64_BUFFER_HANDLE_INVALID This is macro DRV_BM64_BUFFER_HANDLE_INVALID. DRV_BM64_DATA32 BM64 defines based on I2S interface DRV_BM64_MAXBDNAMESIZE DRV_BM64_BUFFER_EVENT_HANDLER prototype for callback for DRV_BM64_BufferEventHandlerSet DRV_BM64_DRVR_STATUS BM64 driver status DRV_BM64_EVENT events that can be returned to a client via callback DRV_BM64_EVENT_HANDLER prototype for callback for DRV_BM64_EventHandlerSet DRV_BM64_LINKSTATUS BM64 link status DRV_BM64_PLAYINGSTATUS This is type DRV_BM64_PLAYINGSTATUS. DRV_BM64_PROTOCOL BM64 protocols DRV_BM64_REQUEST BM64 power on/off request DRV_BM64_SAMPLE_FREQUENCY BM64 sample frequency DRV_BM64_BLE_STATUS This is type DRV_BM64_BLE_STATUS. Description This section describes the API functions of the BM64 Bluetooth Driver library. Refer to each section for a detailed description. a) System Functions DRV_BM64_GetPowerStatus Function Gets the current status of the BM64 Bluetooth driver module (BM64-specific). File drv_bm64.h C DRV_BM64_DRVR_STATUS DRV_BM64_GetPowerStatus(); Returns Driver status, encoded as type DRV_BM64_DRVR_STATUS enum. Description Function DRV_BM64_GetPowerStatus: DRV_BM64_DRVR_STATUS DRV_BM64_GetPowerStatus( void ); This routine provides the current status (power on/off/ready) of the BM64 Bluetooth driver module passed back as type DRV_BM64_DRVR_STATUS enum. Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 38 Remarks A status of DRV_BT_STATUS_READY means the drivers state machine has finished initialization and is ready to stream audio. Preconditions DRV_BM64_Initialize must have been called to initialize the driver instance. Example case APP_STATE_WAIT_INIT: { // note generic version of call (DRV_BT instead of DRV_BM64) is used if (DRV_BT_STATUS_READY == DRV_BT_GetPowerStatus()) { appData.state=APP_STATE_IDLE; // start can processing audio } } break; DRV_BM64_Initialize Function Initializes hardware and data for the instance of the BM64 Bluetooth module File drv_bm64.h C void DRV_BM64_Initialize(); Returns None. Description Function DRV_BM64_Initialize: void DRV_BM64_Initialize( void ); This routine initializes the BM64 driver instance for the specified driver index, making it ready for clients to open and use it. The initialization data is specified by the init parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. Remarks This routine must be called before any other BM64 driver routine is called. This routine should only be called once during system initialization. This routine will never block for hardware access. Preconditions None. Example // (in SYS_Initialize, system_init.c)* DRV_BM64_Initialize(); DRV_BM64_Status Function Gets the current system status of the BM64 Bluetooth driver module. File drv_bm64.h C SYS_STATUS DRV_BM64_Status(); Returns Driver status, encoded as type SYS_STATUS enum: Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 39 SYS_STATUS_DEINITIALIZED - Indicates that the driver has been deinitialized SYS_STATUS_READY - Indicates that any previous module operation for the specified module has completed SYS_STATUS_BUSY - Indicates that a previous module operation for the specified module has not yet completed SYS_STATUS_ERROR - Indicates that the specified module is in an error state * Description Function DRV_BM64_Status: SYS_STATUS DRV_BM64_Status( void ); This routine provides the current status of the BM64 Bluetooth driver module, passed back as type SYS_STATUS. Remarks A driver can opened only when its status is SYS_STATUS_READY. Preconditions None. Example * // note generic version of call (DRV_BT instead of DRV_BM64) is used if (SYS_STATUS_READY == DRV_BT_Status()) { // This means the driver can be opened using the // DRV_BT_Open() function. } DRV_BM64_TaskReq Function Make a power on/power off task request. File drv_bm64.h C void DRV_BM64_TaskReq(DRV_BM64_REQUEST request); Returns None. Description Function DRV_BM64_TaskReq: void DRV_BM64_TaskReq(DRV_BM64_REQUEST request); Make a power on/power off task request using the DRV_BM64_REQUEST enum. Remarks None. Preconditions DRV_BM64_Initialize must have been called to initialize the driver instance. Example // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_TaskReq(DRV_BM64_REQ_SYSTEM_ON); Parameters Parameters Description request power on/off request of type DRV_BM64_REQUEST DRV_BM64_Tasks Function Maintains the driver's control and data interface state machine. File drv_bm64.h Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 40 C void DRV_BM64_Tasks(); Returns None. Description Function DRV_BM64_Tasks: void DRV_BM64_Tasks( void ); This routine is used to maintain the driver's internal control and data interface state machine and implement its control and data interface implementations. This function should be called from the SYS_Tasks() function. Remarks This routine is not normally called directly by an application. Instead it is called by the system's Tasks routine (SYS_Tasks). Preconditions None. Example // (in SYS_Tasks, system_tasks.c) // Maintain Device Drivers DRV_BM64_Tasks(); b) Client Setup Functions DRV_BM64_BufferEventHandlerSet Function This function allows a client to identify a event handling function for the driver to call back. File drv_bm64.h C void DRV_BM64_BufferEventHandlerSet(DRV_HANDLE handle, const DRV_BM64_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Returns None. Description Function DRV_BM64_BufferEventHandlerSet: void DRV_BM64_EventHandlerSet(DRV_HANDLE handle, const DRV_BM64_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. When a client calls DRV_BM64_BufferAddRead function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed. The context parameter contains a handle to the client context, provided at the time the event handling function is registered using the DRV_BM64_BufferEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client. The event handler should be set before the client performs any "BM64 Bluetooth Specific Client Routines" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the command has completed, it does not need to register a callback. Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 41 Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case APP_STATE_SET_BT_BUFFER_HANDLER: { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_BufferEventHandlerSet(appData.bt.handle, appData.bt.bufferHandler, appData.bt.context); DRV_BT_EventHandlerSet(appData.bt.handle, appData.bt.eventHandler, (uintptr_t)0); appData.state = APP_STATE_CODEC_OPEN; } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client eventHandler pointer to a function to be called back (prototype defined by DRV_BM64_BUFFER_EVENT_HANDLER) contextHandle handle to the client context DRV_BM64_Close Function Close an opened-instance of the BM64 Bluetooth driver. File drv_bm64.h C void DRV_BM64_Close(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_Close: void DRV_BM64_Close(DRV_HANDLE handle); This routine closes an opened-instance of the BM64 driver, invalidating the handle. Any buffers in the driver queue that were submitted by this client will be removed. After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_BM64_Open before the caller may use the driver again Remarks Usually there is no need for the driver client to verify that the Close operation has completed. The driver will abort any ongoing operations when this routine is called. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_Close(appData.bt.handle); * Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 42 DRV_BM64_EventHandlerSet Function This function allows a client to identify an event handling function for the driver to call back. File drv_bm64.h C void DRV_BM64_EventHandlerSet(DRV_HANDLE handle, const DRV_BM64_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Returns None. Description Function DRV_BM64_EventHandlerSet: void DRV_BM64_EventHandlerSet(DRV_HANDLE handle, const DRV_BM64_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); This function allows a client to identify a command event handling function for the driver to call back when an event has been received from the BM64. The context parameter contains a handle to the client context, provided at the time the event handling function is registered using the DRV_BM64_BufferEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client.* The event handler should be set before the client performs any "BM64 Bluetooth Specific Client Routines" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when an event has occurred, it does not need to register a callback. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case APP_STATE_SET_BT_BUFFER_HANDLER: { DRV_BT_BufferEventHandlerSet(appData.bt.handle, appData.bt.bufferHandler, appData.bt.context); // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_EventHandlerSet(appData.bt.handle, appData.bt.eventHandler, (uintptr_t)0); appData.state = APP_STATE_CODEC_OPEN; } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client eventHandler pointer to a function to be called back (prototype defined by DRV_BM64_EVENT_HANDLER) contextHandle handle to the client context DRV_BM64_Open Function Open the specified BM64 driver instance and returns a handle to it File drv_bm64.h Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 43 C DRV_HANDLE DRV_BM64_Open(const DRV_IO_INTENT ioIntent, const DRV_BM64_PROTOCOL protocol); Returns valid handle to an opened BM64 device driver unique to client Description Function DRV_BM64_Open: DRV_HANDLE DRV_BM64_Open(const DRV_IO_INTENT ioIntent, const DRV_BM64_PROTOCOL protocol); This routine opens the specified BM64 Bluetooth driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. Only DRV_IO_INTENT_READ is a valid ioIntent option as the BM64 Bluetooth driver audio stream is read-only. Specifying a DRV_IO_INTENT_EXCLUSIVE will cause the driver to provide exclusive access to this client. The driver cannot be opened by any other client. Remarks The handle returned is valid until the DRV_BM64_Close routine is called. This routine will never block waiting for hardware. If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. It should not be called in an ISR. Currently only one client is allowed at a time. Preconditions DRV_BM64_Initialize must have been called to initialize the driver instance. Example case APP_STATE_OPEN: { if (SYS_STATUS_READY == DRV_BT_Status()) { // open BT module, including RX audio stream // note generic version of call (DRV_BT instead of DRV_BM64) is used appData.bt.handle = DRV_BT_Open(DRV_IO_INTENT_READ, DRV_BT_PROTOCOL_ALL); if(appData.bt.handle != DRV_HANDLE_INVALID) { appData.state = APP_STATE_SET_BT_BUFFER_HANDLER; } else { // Got an Invalid Handle. Wait for BT module to Initialize } } } break; Parameters Parameters Description ioIntent valid handle to an opened BM64 device driver unique to client protocol specifies which protocol(s) the client intends to use with this driver. One of the various DRV_BM64_PROTOCOL enum values, including DRV_BM64_PROTOCOL_ALL. c) Data Transfer Functions DRV_BM64_BufferAddRead Function Schedule a non-blocking driver read operation. File drv_bm64.h Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 44 C void DRV_BM64_BufferAddRead(const DRV_HANDLE handle, DRV_BM64_BUFFER_HANDLE * bufferHandle, void * buffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_BM64_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking read operation. The function returns with a valid buffer handle in the bufferHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance receive queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_BM64_BUFFER_HANDLE_INVALID • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0. • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_BM64_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_BM64_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the BM64 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another BM64 driver instance. It should not otherwise be called directly in an ISR. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case APP_STATE_BT_BUFFER_COMPLETE: { //BT RX if (!_bufferUsed[appData.readIndex]) { //Next BT Read Queued // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_BufferAddRead(appData.bt.handle, &appData.bt.readBufHandle, audioBuffer[appData.readIndex], appData.bt.bufferSize); if(appData.bt.readBufHandle != DRV_BT_BUFFER_HANDLE_INVALID) { appData.bt.readBufHandle = DRV_BT_BUFFER_HANDLE_INVALID; _bufferUsed[appData.readIndex] = true; //QUEUE HEAD Index (for next BT read) appData.readIndex++; if(appData.readIndex >= AUDIO_QUEUE_SIZE) { appData.readIndex = 0; } appData.state = APP_STATE_BT_WAIT_FOR_BUFFER_COMPLETE; } else { SYS_DEBUG(0, "BT Buffer Read FAILED!!!"); } } else { //Overrun -- Wait for Read buffer to become available. SYS_DEBUG(0, "Buffer Overrunrn"); } } break; Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 45 Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client bufferHandle pointer to an argument that contains the return buffer handle buffer pointer to buffer that will contain received data size buffer size in bytes. Function void DRV_BM64_BufferAddRead(const DRV_HANDLE handle, DRV_BM6_BUFFER_HANDLE *bufferHandle, void *buffer, size_t size) d) Settings Functions DRV_BM64_SamplingRateGet Function Return the current sampling rate. File drv_bm64.h C uint32_t DRV_BM64_SamplingRateGet(DRV_HANDLE handle); Returns None. Description Function DRV_BM64_SamplingRateGet: uint32_t DRV_BM64_SamplingRateGet(DRV_HANDLE handle); Return the current sampling rate as a 32-bit integer. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example uint32_t sampleRate; // note generic version of call (DRV_BT instead of DRV_BM64) is used sampleRate = DRV_BT_SamplingRateGet(appData.bt.handle); Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client DRV_BM64_SamplingRateSet Function Set the current sampling rate. File drv_bm64.h C void DRV_BM64_SamplingRateSet(DRV_HANDLE handle, uint32_t samplingRate); Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 46 Returns None. Description Function DRV_BM64_SamplingRateSet: void DRV_BM64_SamplingRateSet(DRV_HANDLE handle, uint32_t samplingRate); Set the current sampling rate (passed as a 32-bit integer). Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example // set sample rate to 44.1 kHz // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_SamplingRateSet(appData.bt.handle, 44100); Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client samplingRate sampling rate in Hz (8000, 16000, 44100 or 48000) DRV_BM64_volumeDown Function Turn the volume down on the host device. File drv_bm64.h C void DRV_BM64_volumeDown(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_VolumeDown: void DRV_BM64_VolumeDown(const DRV_HANDLE handle); Turn the volume down on the host device by one increment (about 3% of full-scale). Remarks This will result in a callback with the event DRV_BM64_EVENT_VOLUME_CHANGED specifying the new volume setting for the codec. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_2)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_volumeUp(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } break; Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 47 Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client DRV_BM64_VolumeGet Function File drv_bm64.h C uint8_t DRV_BM64_VolumeGet(const DRV_HANDLE handle); Description returns 7-bit value 0-127 DRV_BM64_VolumeSet Function Set current volume. File drv_bm64.h C void DRV_BM64_VolumeSet(const DRV_HANDLE handle, uint8_t volume); Returns None. Description Function DRV_BM64_VolumeSet: void DRV_BM64_VolumeSet(const DRV_HANDLE handle, uint8_t volume); Set volume for current mode (A2DP, HFP etc.) in percent (0-100). Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example // note generic version of call (DRV_BT instead of DRV_BM64) is used * volume = DRV_BT_VolumeGet(appData.bt.handle,50); // set volume to 50% Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client volume volume level in percent, 0-100 DRV_BM64_volumeUp Function Turn the volume up on the host device. File drv_bm64.h C void DRV_BM64_volumeUp(const DRV_HANDLE handle); Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 48 Returns None. Description Function DRV_BM64_VolumeUp: void DRV_BM64_VolumeUp(const DRV_HANDLE handle); Turn the volume up on the host device by one increment (about 3% of full-scale). Remarks This will result in a callback with the event DRV_BM64_EVENT_VOLUME_CHANGED specifying the new volume setting for the codec. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_1)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_volumeUp(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client e) Bluetooth-specific Functions DRV_BM64_DisconnectAllLinks Function Disconnect all links. File drv_bm64.h C void DRV_BM64_DisconnectAllLinks(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_DisconnectAllLinks: void DRV_BM64_DisconnectAllLinks(const DRV_HANDLE handle); Disconnect all current links to a Bluetooth host. Remarks Does not unpair the device, just disconnects. Use DRV_BM64_LinkLastDevice to reconnect. Use DRV_BM64_ForgetAllLinks to forget all pairings. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_2)==BSP_SWITCH_STATE_PRESSED)) Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 49 { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_DisconnectAllLinks(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client DRV_BM64_EnterBTPairingMode Function Enter Bluetooth pairing mode. File drv_bm64.h C void DRV_BM64_EnterBTPairingMode(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_EnterBTPairingMode: void DRV_BM64_EnterBTPairingMode(const DRV_HANDLE handle); Starting the pairing process, making this BM64 available for pairing with a Bluetooth host. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_1)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_EnterBTPairingMode(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client DRV_BM64_ForgetAllLinks Function Forget all pairings. File drv_bm64.h C void DRV_BM64_ForgetAllLinks(const DRV_HANDLE handle); Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 50 Returns None. Description Function DRV_BM64_ForgetAllLinks: void DRV_BM64_ForgetAllLinks(const DRV_HANDLE handle); Forget (erase) all links and pairings stored in EEPROM. Remarks After this is called, one must call DRV_BM64_EnterBTPairingMode to establish a connection to a Bluetooth host again. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_2)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_ForgetAllLinks(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client DRV_BM64_GetLinkStatus Function Return link status. File drv_bm64.h C DRV_BM64_LINKSTATUS DRV_BM64_GetLinkStatus(const DRV_HANDLE handle); Returns 8-bit value defined by DRV_BM64_LINKSTATUS enum. Description Function DRV_BM64_GetLinkStatus: DRV_BM64_LINKSTATUS DRV_BM64_GetLinkStatus(const DRV_HANDLE handle); Returns a 8-bit value containing current link status as bit flags for SCO (bit 0), ACL, HFP, A2DP, AVRCP, SPP, IAP, MAP (bit 7) Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_3)==BSP_SWITCH_STATE_PRESSED)) { DRV_BT_PLAYINGSTATUS playingStatus = DRV_BT_GetPlayingStatus(appData.bt.handle); if ((playingStatus==DRV_BT_PLAYING_FF)||(playingStatus==DRV_BT_PLAYING_FR)) { Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 51 // note generic version of call (DRV_BT instead of DRV_BM64) is used if (DRV_BT_GetLinkStatus(appData.bt.handle) & DRV_BT_AVRCP_LINK_STATUS) { DRV_BT_CancelForwardOrRewind(appData.bt.handle); } } } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client DRV_BM64_LinkLastDevice Function Link last device. File drv_bm64.h C void DRV_BM64_LinkLastDevice(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_LinkLastDevice: void DRV_BM64_LinkLastDevice(const DRV_HANDLE handle); Link (connect) to last device that was previously linked. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_2)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_LinkLastDevice(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client f) AVRCP Functions DRV_BM64_CancelForwardOrRewind Function Cancel previous fast forward or rewind request. Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 52 File drv_bm64.h C void DRV_BM64_CancelForwardOrRewind(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_CancelForwardOrRewind: void DRV_BM64_CancelForwardOrRewind(const DRV_HANDLE handle); Send an AVRCP command to the host device to cancel a previous fast forward or rewind request. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_3)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_CancelForwardOrRewind(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client DRV_BM64_FastForward Function Fast forward the media. File drv_bm64.h C void DRV_BM64_FastForward(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_FastForward: void DRV_BM64_FastForward(const DRV_HANDLE handle); Send an AVRCP command to the host device to Fast forward the media. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 53 Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_5)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_FastForward(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client DRV_BM64_GetPlayingStatus Function Return the current playing status of the device. File drv_bm64.h C DRV_BM64_PLAYINGSTATUS DRV_BM64_GetPlayingStatus(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_GetPlayingStatus: void DRV_BM64_GetPlayingStatus(const DRV_HANDLE handle); Return the current AVRCP playing status of the device, e.g. stopped, playing, paused, fast forward or rewind, encoded as as the enum DRV_BM64_PLAYINGSTATUS. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_3)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_PLAYINGSTATUS playingStatus = DRV_BT_GetPlayingStatus(appData.bt.handle); if ((playingStatus==DRV_BT_PLAYING_FF)||(playingStatus==DRV_BT_PLAYING_FR)) { if (DRV_BT_GetLinkStatus(appData.bt.handle) & DRV_BT_AVRCP_LINK_STATUS) { DRV_BT_CancelForwardOrRewind(appData.bt.handle); } } } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 54 DRV_BM64_Pause Function Pause playback. File drv_bm64.h C void DRV_BM64_Pause(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_Pause: void DRV_BM64_Pause(const DRV_HANDLE handle); Send an AVRCP command to the host device to pause. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_3)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_Pause(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client DRV_BM64_Play Function Start playback. File drv_bm64.h C void DRV_BM64_Play(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_Play: DRV_BM64_Play(const DRV_HANDLE handle); Send an AVRCP command to the host device to initiate or resume playback. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 55 Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_3)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_Play(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client DRV_BM64_PlayNextSong Function Play the next song. File drv_bm64.h C void DRV_BM64_PlayNextSong(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_PlayNextSong: void DRV_BM64_PlayNextSong(const DRV_HANDLE handle); Send an AVRCP command to the host device to play the next song in a playlist. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_3)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_PlayNextSong(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 56 DRV_BM64_PlayPause Function Toggle play/pause mode. File drv_bm64.h C void DRV_BM64_PlayPause(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_PlayPause: void DRV_BM64_PlayPause(const DRV_HANDLE handle); Send an AVRCP command to the host device to toggle the play/pause mode. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_3)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_PlayPause(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client DRV_BM64_PlayPreviousSong Function Play the previous song. File drv_bm64.h C void DRV_BM64_PlayPreviousSong(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_PlayPreviousSong: void DRV_BM64_PlayPreviousSong(const DRV_HANDLE handle); Send an AVRCP command to the host device to play the previous song in a playlist. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 57 Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_5)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_PlayPreviousSong(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client DRV_BM64_Rewind Function Rewind the media. File drv_bm64.h C void DRV_BM64_Rewind(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_Rewind: void DRV_BM64_Rewind(const DRV_HANDLE handle); Send an AVRCP command to the host device to rewind the media. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_5)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_Rewind(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 58 DRV_BM64_Stop Function Stop playback. File drv_bm64.h C void DRV_BM64_Stop(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_Stop: void DRV_BM64_Stop(const DRV_HANDLE handle); Send an AVRCP command to the host device to stop playback. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example case BUTTON_STATE_PRESSED: // (debouncing not shown) { if (BSP_SwitchStateGet(BSP_SWITCH_3)==BSP_SWITCH_STATE_PRESSED)) { // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_Stop(appData.bt.handle); appData.buttonState=BUTTON_STATE_WAIT_FOR_RELEASE; } } break; Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client g) Device Name and Address Functions DRV_BM64_GetBDAddress Function Return the Bluetooth address. File drv_bm64.h C void DRV_BM64_GetBDAddress(const DRV_HANDLE handle, char* buffer); Returns None. Description Function DRV_BM64_GetBDAddress: void DRV_BM64_GetBDAddress(const DRV_HANDLE handle, char* buffer); Return the Bluetooth address of the device as an ASCII string. Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 59 Remarks Buffer must be at least 18 bytes in length (6 octets separated by ?:?, e.g. able to hold "12:34:56:78:90:120"). Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example laString tempStr; char buf [18]; // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_GetBDAddress(appData.bt.handle, buf); tempStr = laString_CreateFromCharBuffer(buf, &LiberationSans12); laLabelWidget_SetText(GFX_BTADDRESS_VALUE, tempStr); // display BT address laString_Destroy(&tempStr); Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client buffer pointer to a char buffer at least 18 bytes long DRV_BM64_GetBDName Function Return Bluetooth device name. File drv_bm64.h C void DRV_BM64_GetBDName(const DRV_HANDLE handle, char* buffer, const uint8_t buflen); Returns None. Description Function DRV_BM64_GetBDName: void DRV_BM64_GetBDName(const DRV_HANDLE handle, char* buffer, const uint8_t buflen); Return the Bluetooth device name as an ASCII string. Remarks If name is longer than buflen-1 bytes long, it will be truncated to fit inside the buffer. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example laString tempStr; char buf [DRV_BT_MAXBDNAMESIZE+1]; // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_GetBDName(appData.bt.handle, buf, DRV_BT_MAXBDNAMESIZE+1); tempStr = laString_CreateFromCharBuffer(buf, &LiberationSans12); laLabelWidget_SetText(GFX_BTNAME_VALUE, tempStr); // display BT name laString_Destroy(&tempStr); Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client buffer pointer to a char buffer at least buflen bytes long buflen length of buffer (including terminating 0 byte) Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 60 DRV_BM64_SetBDName Function Set the Bluetooth device name. File drv_bm64.h C void DRV_BM64_SetBDName(const DRV_HANDLE handle, const char* buffer); Returns None. Description Function DRV_BM64_SetBDName: void DRV_BM64_SetBTName(const DRV_HANDLE handle, const char* buffer); Set a temporary Bluetooth device name from an ASCII string buffer. Remarks The name is set for this session only; if the BM64 is reset (e.g. power is lost) the name will revert to the Bluetooth name stored in EEPROM. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_SetBDName(appData.bt.handle, "Temporary BM64 Name"); Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client buffer pointer to a char buffer containing the new name h) BLE Functions DRV_BM64_ClearBLEData Function Clear the BLE receive buffer. File drv_bm64.h C void DRV_BM64_ClearBLEData(const DRV_HANDLE handle); Returns None. Description Function DRV_BM64_ClearBLEData: void DRV_BM64_ClearBLEData( const DRV_HANDLE handle ); Clears the buffer used when receiving characters via the DRV_BM64_ReadByteFromBLE and DRV_BM64_ReadDataFromBLE calls. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 61 Example uint8_t byte; // note generic versions of calls (DRV_BT instead of DRV_BM64) is used DRV_BT_ClearBLEData(appData.bt.handle); // wait for byte to arrive while (!DRV_BT_ReadByteFromBLE(appData.bt.handle, &byte)) { // should have some sort of way to break out of here if byte never arrives } Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client DRV_BM64_ReadByteFromBLE Function Read a byte over BLE. File drv_bm64.h C bool DRV_BM64_ReadByteFromBLE(const DRV_HANDLE handle, uint8_t* byte); Returns bool - true if a byte was returned, false if receive buffer empty Description Function DRV_BM64_ReadByteFromBLE: bool DRV_BM64_ReadByteFromBLE(const DRV_HANDLE handle, uint8_t* byte); Read one byte over BLE using the BM64's "Transparent Service" feature. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example uint8_t byte; // note generic version of call (DRV_BT instead of DRV_BM64) is used if (DRV_BT_ReadByteFromBLE(appData.bt.handle, &byte)) // if byte received { // do something } Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client byte pointer to a uint8_t to receive the data DRV_BM64_ReadDataFromBLE Function Read data over BLE. File drv_bm64.h Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 62 C bool DRV_BM64_ReadDataFromBLE(const DRV_HANDLE handle, uint8_t* byte, uint16_t size); Returns bool - true if data was returned, false if receive buffer empty Description Function DRV_BM64_ReadDataFromBLE: bool DRV_BM64_ReadDataFromBLE(const DRV_HANDLE handle, uint8_t* bytes, uint16_t size ); Read data over BLE using the BM64's "Transparent Service" feature. Remarks No more than size bytes will be returned, even if more are available. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example #define BUFSIZE 100 uint8_t buf [BUFSIZE]; // note generic version of call (DRV_BT instead of DRV_BM64) is used if (DRV_BT_ReadDataFromBLE(appData.bt.handle, buf, BUFSIZE)) // if data received { // do something } Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client bytes pointer to a uint8_t buffer at least size bytes long size length of buffer (including DRV_BM64_SendByteOverBLE Function Send a byte over BLE. File drv_bm64.h C void DRV_BM64_SendByteOverBLE(const DRV_HANDLE handle, uint8_t byte); Returns None. Description Function DRV_BM64_SendByteOverBLE: void DRV_BM64_SendByteOverBLE(const DRV_HANDLE handle, uint8_t byte); Send one byte over BLE using the BM64's "Transparent Service" feature. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example uint8_t byte; byte = 10; // set to some value Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 63 // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_SendByteOverBLE(appData.bt.handle, byte); Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client byte uint8_t of data to be sent DRV_BM64_SendDataOverBLE Function Send data over BLE. File drv_bm64.h C void DRV_BM64_SendDataOverBLE(const DRV_HANDLE handle, uint8_t* bytes, uint16_t size); Returns None. Description Function DRV_BM64_SendDataOverBLE: void DRV_BM64_SendDataOverBLE(const DRV_HANDLE handle, uint8_t* bytes, uint16_t size); Send data over BLE using the BM64's "Transparent Service" feature. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example #define BUFSIZE 100 uint8_t buf [BUFSIZE]; // (code to fill in buffer with data) // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_SendDataOverBLE(appData.bt.handle, buf, BUFSIZE); Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client bytes pointer to a uint8_t buffer at least size bytes long size length of buffer (including DRV_BM64_BLE_QueryStatus Function Query BM64 LE status. File drv_bm64.h C void DRV_BM64_BLE_QueryStatus(const DRV_HANDLE handle); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 64 Description Function DRV_BM64_BLE_QueryStatus: void DRV_BM64_BLE_QueryStatus(const DRV_HANDLE handle); Queries the BM64 to respond with a DRV_BM64_EVENT_BLE_STATUS_CHANGED event, which will indicate if the BM64 BLE status is standby, advertising, scanning or connected. Remarks RV_BM64_BLE_QueryStatus is non-blocking; it returns right away and sometime later (perhaps tens or hundreds of ms) the event handler callback will be called. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example // note generic version of call (DRV_BT instead of DRV_BM64) is used DRV_BT_BLE_QueryStatus(appData.bt.handle); . . . // later, a call will come back to the event handler callback function // (previously set up via a call to DRV_BM64_EventHandlerSet) static void _BLEEventHandler(DRV_BT_EVENT event, uint32_t param, uintptr_t context) { switch(event) { case DRV_BT_EVENT_BLE_STATUS_CHANGED: { // do case switch based on param variable } } } Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client DRV_BM64_BLE_EnableAdvertising Function Enable or disable advertising. File drv_bm64.h C void DRV_BM64_BLE_EnableAdvertising(const DRV_HANDLE handle, bool enable); Returns None. Description Function DRV_BM64_BLE_EnableAdvertising: void DRV_BM64_BLE_EnableAdvertising(const DRV_HANDLE handle, bool enable); Enable or disable BLE advertising. Remarks None. Preconditions DRV_BM64_Open must have been called to obtain a valid opened device handle. Example // note generic version of call (DRV_BT instead of DRV_BM64) is used Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 65 DRV_BM64_BLE_EnableAdvertising(appData.bt.handle, true); Parameters Parameters Description handle valid handle to an opened BM64 device driver unique to client enable true to enable advertising, false to disable advertising i) Data Types and Constants DRV_BM64_BUFFER_EVENT Macro File drv_bm64.h C #define DRV_BM64_BUFFER_EVENT DRV_I2S_BUFFER_EVENT Description This is macro DRV_BM64_BUFFER_EVENT. DRV_BM64_BUFFER_EVENT_COMPLETE Macro File drv_bm64.h C #define DRV_BM64_BUFFER_EVENT_COMPLETE DRV_I2S_BUFFER_EVENT_COMPLETE Description This is macro DRV_BM64_BUFFER_EVENT_COMPLETE. DRV_BM64_BUFFER_HANDLE Macro File drv_bm64.h C #define DRV_BM64_BUFFER_HANDLE DRV_I2S_BUFFER_HANDLE Description This is macro DRV_BM64_BUFFER_HANDLE. DRV_BM64_BUFFER_HANDLE_INVALID Macro File drv_bm64.h C #define DRV_BM64_BUFFER_HANDLE_INVALID DRV_I2S_BUFFER_HANDLE_INVALID Description This is macro DRV_BM64_BUFFER_HANDLE_INVALID. DRV_BM64_DATA32 Macro File drv_bm64.h Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 66 C #define DRV_BM64_DATA32 DRV_I2S_DATA32 Description BM64 defines based on I2S interface DRV_BM64_MAXBDNAMESIZE Macro File drv_bm64.h C #define DRV_BM64_MAXBDNAMESIZE 32 Section Constants DRV_BM64_BUFFER_EVENT_HANDLER Type File drv_bm64.h C typedef void (* DRV_BM64_BUFFER_EVENT_HANDLER)(DRV_BM64_BUFFER_EVENT event, uintptr_t contextHandle); Description prototype for callback for DRV_BM64_BufferEventHandlerSet DRV_BM64_DRVR_STATUS Enumeration File drv_bm64.h C typedef enum { DRV_BM64_STATUS_NONE, DRV_BM64_STATUS_OFF, DRV_BM64_STATUS_ON, DRV_BM64_STATUS_READY } DRV_BM64_DRVR_STATUS; Description BM64 driver status DRV_BM64_EVENT Enumeration File drv_bm64.h C typedef enum { DRV_BM64_EVENT_NONE = 0, DRV_BM64_EVENT_NSPK_STATUS, DRV_BM64_EVENT_LINE_IN_STATUS, DRV_BM64_EVENT_A2DP_STATUS, DRV_BM64_EVENT_CALL_STATUS_CHANGED, DRV_BM64_EVENT_CODEC_TYPE, DRV_BM64_EVENT_HFP_CONNECTED, DRV_BM64_EVENT_HFP_DISCONNECTED, DRV_BM64_EVENT_A2DP_CONNECTED, DRV_BM64_EVENT_A2DP_DISCONNECTED, DRV_BM64_EVENT_AVRCP_CONNECTED, Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 67 DRV_BM64_EVENT_AVRCP_DISCONNECTED, DRV_BM64_EVENT_SPP_CONNECTED, DRV_BM64_EVENT_IAP_CONNETED, DRV_BM64_EVENT_SPP_IAP_DISCONNECTED, DRV_BM64_EVENT_ACL_CONNECTED, DRV_BM64_EVENT_ACL_DISCONNECTED, DRV_BM64_EVENT_SCO_CONNECTED, DRV_BM64_EVENT_SCO_DISCONNECTED, DRV_BM64_EVENT_MAP_CONNECTED, DRV_BM64_EVENT_MAP_DISCONNECTED, DRV_BM64_EVENT_SYS_POWER_ON, DRV_BM64_EVENT_SYS_POWER_OFF, DRV_BM64_EVENT_SYS_STANDBY, DRV_BM64_EVENT_SYS_PAIRING_START, DRV_BM64_EVENT_SYS_PAIRING_OK, DRV_BM64_EVENT_SYS_PAIRING_FAILED, DRV_BM64_EVENT_LINKBACK_SUCCESS, DRV_BM64_EVENT_LINKBACK_FAILED, DRV_BM64_EVENT_BD_ADDR_RECEIVED, DRV_BM64_EVENT_PAIR_RECORD_RECEIVED, DRV_BM64_EVENT_LINK_MODE_RECEIVED, DRV_BM64_EVENT_PLAYBACK_STATUS_CHANGED, DRV_BM64_EVENT_AVRCP_VOLUME_CTRL, DRV_BM64_EVENT_AVRCP_ABS_VOLUME_CHANGED, DRV_BM64_EVENT_HFP_VOLUME_CHANGED, DRV_BM64_EVENT_VOLUME_CHANGED, DRV_BM64_EVENT_SAMPLERATE_CHANGED, DRV_BM64_EVENT_NSPK_SYNC_POWER_OFF, DRV_BM64_EVENT_NSPK_SYNC_VOL_CTRL, DRV_BM64_EVENT_NSPK_SYNC_INTERNAL_GAIN, DRV_BM64_EVENT_NSPK_SYNC_ABS_VOL, DRV_BM64_EVENT_NSPK_CHANNEL_SETTING, DRV_BM64_EVENT_NSPK_ADD_SPEAKER3, DRV_BM64_EVENT_LE_STATUS_CHANGED, DRV_BM64_EVENT_LE_ADV_CONTROL_REPORT, DRV_BM64_EVENT_LE_CONNECTION_PARA_REPORT, DRV_BM64_EVENT_LE_CONNECTION_PARA_UPDATE_RSP, DRV_BM64_EVENT_GATT_ATTRIBUTE_DATA, DRV_BM64_EVENT_PORT0_INPUT_CHANGED, DRV_BM64_EVENT_PORT1_INPUT_CHANGED, DRV_BM64_EVENT_PORT2_INPUT_CHANGED, DRV_BM64_EVENT_PORT3_INPUT_CHANGED, DRV_BM64_EVENT_BLESPP_MSG_RECEIVED, DRV_BM64_EVENT_BLE_STATUS_CHANGED } DRV_BM64_EVENT; Description events that can be returned to a client via callback DRV_BM64_EVENT_HANDLER Type File drv_bm64.h C typedef void (* DRV_BM64_EVENT_HANDLER)(DRV_BM64_EVENT event, uint32_t param, uintptr_t contextHandle); Description prototype for callback for DRV_BM64_EventHandlerSet DRV_BM64_LINKSTATUS Enumeration File drv_bm64.h C typedef enum { DRV_BM64_NO_LINK_STATUS = 0, DRV_BM64_SCO_LINK_STATUS = 0x01, Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 68 DRV_BM64_ACL_LINK_STATUS = 0x02, DRV_BM64_HFP_LINK_STATUS = 0x04, DRV_BM64_A2DP_LINK_STATUS = 0x08, DRV_BM64_AVRCP_LINK_STATUS = 0x10, DRV_BM64_SPP_LINK_STATUS = 0x20, DRV_BM64_IAP_LINK_STATUS = 0x40, DRV_BM64_MAP_LINK_STATUS = 0x80 } DRV_BM64_LINKSTATUS; Description BM64 link status DRV_BM64_PLAYINGSTATUS Enumeration File drv_bm64.h C typedef enum { DRV_BM64_PLAYING_STOPPED, DRV_BM64_PLAYING_PLAYING, DRV_BM64_PLAYING_PAUSED, DRV_BM64_PLAYING_FF, DRV_BM64_PLAYING_FR, DRV_BM64_PLAYING_ERROR } DRV_BM64_PLAYINGSTATUS; Description This is type DRV_BM64_PLAYINGSTATUS. DRV_BM64_PROTOCOL Enumeration File drv_bm64.h C typedef enum { DRV_BM64_PROTOCOL_A2DP = 1, DRV_BM64_PROTOCOL_AVRCP = 2, DRV_BM64_PROTOCOL_HFP_HSP = 4, DRV_BM64_PROTOCOL_SPP = 8, DRV_BM64_PROTOCOL_BLE = 16, DRV_BM64_PROTOCOL_ALL = 31 } DRV_BM64_PROTOCOL; Description BM64 protocols DRV_BM64_REQUEST Enumeration File drv_bm64.h C typedef enum { DRV_BM64_REQ_NONE = 0, DRV_BM64_REQ_SYSTEM_ON, DRV_BM64_REQ_SYSTEM_OFF } DRV_BM64_REQUEST; Description BM64 power on/off request Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 69 DRV_BM64_SAMPLE_FREQUENCY Enumeration File drv_bm64.h C typedef enum { DRV_BM64_SAMPLEFREQ_8000 = 0, DRV_BM64_SAMPLEFREQ_12000, DRV_BM64_SAMPLEFREQ_16000, DRV_BM64_SAMPLEFREQ_24000, DRV_BM64_SAMPLEFREQ_32000, DRV_BM64_SAMPLEFREQ_48000, DRV_BM64_SAMPLEFREQ_44100, DRV_BM64_SAMPLEFREQ_88000, DRV_BM64_SAMPLEFREQ_96000 } DRV_BM64_SAMPLE_FREQUENCY; Description BM64 sample frequency DRV_BM64_BLE_STATUS Enumeration File drv_bm64.h C typedef enum { DRV_BM64_BLE_STATUS_STANDBY, DRV_BM64_BLE_STATUS_ADVERTISING, DRV_BM64_BLE_STATUS_SCANNING, DRV_BM64_BLE_STATUS_CONNECTED } DRV_BM64_BLE_STATUS; Description This is type DRV_BM64_BLE_STATUS. Files Files Name Description drv_bm64.h BM64 Bluetooth Static Driver main header file drv_bm64_config_template.h BM64 Bluetooth Driver Configuration Template. Description This section lists the source and header files used by the BM64 Bluetooth Driver Library. drv_bm64.h BM64 Bluetooth Static Driver main header file Enumerations Name Description DRV_BM64_BLE_STATUS This is type DRV_BM64_BLE_STATUS. DRV_BM64_DRVR_STATUS BM64 driver status DRV_BM64_EVENT events that can be returned to a client via callback DRV_BM64_LINKSTATUS BM64 link status DRV_BM64_PLAYINGSTATUS This is type DRV_BM64_PLAYINGSTATUS. DRV_BM64_PROTOCOL BM64 protocols DRV_BM64_REQUEST BM64 power on/off request Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 70 DRV_BM64_SAMPLE_FREQUENCY BM64 sample frequency Functions Name Description DRV_BM64_BLE_EnableAdvertising Enable or disable advertising. DRV_BM64_BLE_QueryStatus Query BM64 LE status. DRV_BM64_BufferAddRead Schedule a non-blocking driver read operation. DRV_BM64_BufferEventHandlerSet This function allows a client to identify a event handling function for the driver to call back. DRV_BM64_CancelForwardOrRewind Cancel previous fast forward or rewind request. DRV_BM64_ClearBLEData Clear the BLE receive buffer. DRV_BM64_Close Close an opened-instance of the BM64 Bluetooth driver. DRV_BM64_DisconnectAllLinks Disconnect all links. DRV_BM64_EnterBTPairingMode Enter Bluetooth pairing mode. DRV_BM64_EventHandlerSet This function allows a client to identify an event handling function for the driver to call back. DRV_BM64_FastForward Fast forward the media. DRV_BM64_ForgetAllLinks Forget all pairings. DRV_BM64_GetBDAddress Return the Bluetooth address. DRV_BM64_GetBDName Return Bluetooth device name. DRV_BM64_GetLinkStatus Return link status. DRV_BM64_GetPlayingStatus Return the current playing status of the device. DRV_BM64_GetPowerStatus Gets the current status of the BM64 Bluetooth driver module (BM64-specific). DRV_BM64_Initialize Initializes hardware and data for the instance of the BM64 Bluetooth module DRV_BM64_LinkLastDevice Link last device. DRV_BM64_Open Open the specified BM64 driver instance and returns a handle to it DRV_BM64_Pause Pause playback. DRV_BM64_Play Start playback. DRV_BM64_PlayNextSong Play the next song. DRV_BM64_PlayPause Toggle play/pause mode. DRV_BM64_PlayPreviousSong Play the previous song. DRV_BM64_ReadByteFromBLE Read a byte over BLE. DRV_BM64_ReadDataFromBLE Read data over BLE. DRV_BM64_Rewind Rewind the media. DRV_BM64_SamplingRateGet Return the current sampling rate. DRV_BM64_SamplingRateSet Set the current sampling rate. DRV_BM64_SendByteOverBLE Send a byte over BLE. DRV_BM64_SendDataOverBLE Send data over BLE. DRV_BM64_SetBDName Set the Bluetooth device name. DRV_BM64_Status Gets the current system status of the BM64 Bluetooth driver module. DRV_BM64_Stop Stop playback. DRV_BM64_TaskReq Make a power on/power off task request. DRV_BM64_Tasks Maintains the driver's control and data interface state machine. DRV_BM64_volumeDown Turn the volume down on the host device. DRV_BM64_VolumeGet returns 7-bit value 0-127 DRV_BM64_VolumeSet Set current volume. DRV_BM64_volumeUp Turn the volume up on the host device. Macros Name Description DRV_BM64_BUFFER_EVENT This is macro DRV_BM64_BUFFER_EVENT. DRV_BM64_BUFFER_EVENT_COMPLETE This is macro DRV_BM64_BUFFER_EVENT_COMPLETE. DRV_BM64_BUFFER_HANDLE This is macro DRV_BM64_BUFFER_HANDLE. DRV_BM64_BUFFER_HANDLE_INVALID This is macro DRV_BM64_BUFFER_HANDLE_INVALID. DRV_BM64_DATA32 BM64 defines based on I2S interface DRV_BM64_MAXBDNAMESIZE Volume V: MPLAB Harmony Framework Driver Libraries Help Bluetooth Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 71 Types Name Description DRV_BM64_BUFFER_EVENT_HANDLER prototype for callback for DRV_BM64_BufferEventHandlerSet DRV_BM64_EVENT_HANDLER prototype for callback for DRV_BM64_EventHandlerSet Description BM64 Bluetooth Static Driver implementation This file is the header file for the external (public) API of the static implementation of the BM64 driver. The BM64 is a Bluetooth 4.2 Stereo Module that supports classic A2DP, AVRCP, HFP, HSP, and SPP protocols as well as BLE (Bluetooth Low Energy). The BM64 streams I2S audio at up to 24-bit, 96 kHz. It uses a UART to receive commands from the host microcontroller (PIC32) and and send events back. All functions and constants in this file are named with the format DRV_BM64_xxx, where xxx is a function name or constant. These names are redefined in the appropriate configuration?s system_config.h file to the format DRV_BT_xxx using #defines so that Bluetooth code in the application can be written as generically as possible (e.g. by writing DRV_BT_Open instead of DRV_BM64_Open etc.). File Name drv_bm64.h Company Microchip Technology Inc. drv_bm64_config_template.h BM64 Bluetooth Driver Configuration Template. Macros Name Description INCLUDE_BM64_BLE Identifies whether the driver should include BLE INCLUDE_BM64_I2S Identifies whether the driver should include HFP,A2DP,AVRCP functionality. INCLUDE_DEPRECATED_MMI_COMMANDS Identifies whether the driver should use deprecated MMI commands. Description BM64 Driver Configuration Template These file provides the list of all the configurations that can be used with the driver. This file should not be included in the driver. File Name drv_bm64_config_template.h Company Microchip Technology Inc. Camera Driver Libraries This section describes the Camera Driver Libraries. Introduction This section provides information on the Camera Driver libraries that are provided in MPLAB Harmony and describes the APIs that are common to all drivers. Library Interface a) Common Driver Functions Name Description DRV_CAMERA_Close Closes an opened instance of an CAMERA module driver. DRV_CAMERA_Deinitialize Deinitializes the index instance of the CAMERA module. DRV_CAMERA_Initialize Initializes hardware and data for the index instance of the CAMERA module. Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 72 DRV_CAMERA_Open Opens the specified instance of the Camera driver for use and provides an "open instance" handle. DRV_CAMERA_Reinitialize Reinitializes hardware and data for the index instance of the CAMERA module. DRV_CAMERA_Status Provides the current status of the index instance of the CAMERA module. DRV_CAMERA_Tasks This is function DRV_CAMERA_Tasks. b) Common Data Types and Constants Name Description DRV_CAMERA_INIT Defines the data required to initialize or reinitialize the CAMERA driver. DRV_CAMERA_INTERRUPT_PORT_REMAP Defines the data required to initialize the CAMERA driver interrupt port remap. DRV_CAMERA_INDEX_0 Camera driver index definitions. DRV_CAMERA_INDEX_1 This is macro DRV_CAMERA_INDEX_1. DRV_CAMERA_INDEX_COUNT Number of valid CAMERA driver indices. CAMERA_MODULE_ID This is type CAMERA_MODULE_ID. Description Camera Driver APIs that are common to all Camera drivers. a) Common Driver Functions DRV_CAMERA_Close Function Closes an opened instance of an CAMERA module driver. File drv_camera.h C void DRV_CAMERA_Close(DRV_HANDLE handle); Returns None. Description This function closes an opened instance of an CAMERA module driver, making the specified handle invalid. Remarks None. Preconditions The DRV_CAMERA_Initialize routine must have been called for the specified CAMERA device instance and the DRV_CAMERA_Status must have returned SYS_STATUS_READY. DRV_CAMERA_Open must have been called to obtain a valid opened device handle. Example myCameraHandle = DRV_CAMERA_Open(DRV_CAMERA_ID_1, DRV_IO_INTENT_NONBLOCKING|DRV_IO_INTENT_READWRITE); DRV_CAMERA_Close(myCameraHandle); Parameters Parameters Description drvHandle A valid open-instance handle, returned from the driver's open routine Function void DRV_CAMERA_Close ( const DRV_HANDLE drvHandle ) DRV_CAMERA_Deinitialize Function Deinitializes the index instance of the CAMERA module. Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 73 File drv_camera.h C void DRV_CAMERA_Deinitialize(const SYS_MODULE_INDEX index); Returns None. Description This function deinitializes the index instance of the CAMERA module, disabling its operation (and any hardware for driver modules). It deinitializes only the specified module instance. It also resets all the internal data structures and fields for the specified instance to the default settings. Remarks None. Preconditions The DRV_CAMERA_Initialize function should have been called before calling this function. Example SYS_STATUS cameraStatus; DRV_CAMERA_Deinitialize(DRV_CAMERA_ID_1); cameraStatus = DRV_CAMERA_Status(DRV_CAMERA_ID_1); Parameters Parameters Description index Index, identifying the instance of the CAMERA module to be deinitialized Function void DRV_CAMERA_Deinitialize ( const SYS_MODULE_ID index ) DRV_CAMERA_Initialize Function Initializes hardware and data for the index instance of the CAMERA module. File drv_camera.h C SYS_MODULE_OBJ DRV_CAMERA_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns None. Description This function initializes hardware for the index instance of the CAMERA module, using the hardware initialization given data. It also initializes any internal driver data structures making the driver ready to be opened. Remarks None. Preconditions None. Example DRV_CAMERA_INIT_DATA cameraInitData; SYS_STATUS cameraStatus; // Populate the cameraInitData structure cameraInitData.moduleInit.powerState = SYS_MODULE_POWER_RUN_FULL; Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 74 cameraInitData.moduleInit.moduleCode = (DRV_CAMERA_INIT_DATA_MASTER | DRV_CAMERA_INIT_DATA_SLAVE); DRV_CAMERA_Initialize(DRV_CAMERA_ID_1, (SYS_MODULE_INIT*)&cameraInitData); cameraStatus = DRV_CAMERA_Status(DRV_CAMERA_ID_1); Parameters Parameters Description index Index, identifying the instance of the CAMERA module to be initialized data Pointer to the data structure containing any data necessary to initialize the hardware. This pointer may be null if no data is required and the default initialization is to be used. Function void DRV_CAMERA_Initialize ( const CAMERA_MODULE_ID index, const SYS_MODULE_INIT *const data ) DRV_CAMERA_Open Function Opens the specified instance of the Camera driver for use and provides an "open instance" handle. File drv_camera.h C DRV_HANDLE DRV_CAMERA_Open(const SYS_MODULE_INDEX index, const DRV_IO_INTENT intent); Returns If successful, the routine returns a valid open-instance handle (a value identifying both the caller and the module instance). If an error occurs, the returned value is DRV_HANDLE_INVALID. Description This function opens the specified instance of the Camera module for use and provides a handle that is required to use the remaining driver routines. This function opens a specified instance of the Camera module driver for use by any client module and provides an "open instance" handle that must be provided to any of the other Camera driver operations to identify the caller and the instance of the Camera driver/hardware module. Preconditions The DRV_CAMERA_Initialize routine must have been called for the specified CAMERA device instance and the DRV_CAMERA_Status must have returned SYS_STATUS_READY. Example DRV_HANDLE cameraHandle; DRV_CAMERA_CLIENT_STATUS cameraClientStatus; cameraHandle = DRV_CAMERA_Open(DRV_CAMERA_ID_1, DRV_IO_INTENT_NONBLOCKING|DRV_IO_INTENT_READWRITE); if (DRV_HANDLE_INVALID == cameraHandle) { // Handle open error } cameraClientStatus = DRV_CAMERA_ClientStatus(cameraHandle); // Close the device when it is no longer needed. DRV_CAMERA_Close(cameraHandle); Parameters Parameters Description index Index, identifying the instance of the CAMERA module to be opened. intent Flags parameter identifying the intended usage and behavior of the driver. Multiple flags may be ORed together to specify the intended usage of the device. See the DRV_IO_INTENT definition. Function DRV_HANDLE DRV_CAMERA_Open ( const SYS_MODULE_INDEX index, Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 75 const DRV_IO_INTENT intent ) DRV_CAMERA_Reinitialize Function Reinitializes hardware and data for the index instance of the CAMERA module. File drv_camera.h C void DRV_CAMERA_Reinitialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT *const data); Returns None. Description This function reinitializes hardware for the index instance of the CAMERA module, using the hardware initialization given data. It also reinitializes any internal driver data structures making the driver ready to be opened. Remarks None. Preconditions The DRV_CAMERA_Initialize function should have been called before calling this function. Example SYS_MODULE_INIT cameraInit; SYS_STATUS cameraStatus; DRV_CAMERA_Reinitialize(DRV_CAMERA_ID_1, &cameraStatus); Parameters Parameters Description index Index, identifying the instance of the CAMERA module to be reinitialized data Pointer to the data structure containing any data necessary to reinitialize the hardware. This pointer may be null if no data is required and default configuration is to be used. Function void DRV_CAMERA_Reinitialize( const SYS_MODULE_ID index, const SYS_MODULE_INIT *const data ) DRV_CAMERA_Status Function Provides the current status of the index instance of the CAMERA module. File drv_camera.h C SYS_STATUS DRV_CAMERA_Status(const SYS_MODULE_INDEX index); Returns The current status of the index instance. Description This function provides the current status of the index instance of the CAMERA module. Remarks None. Preconditions The DRV_CAMERA_Initialize function should have been called before calling this function. Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 76 Function SYS_STATUS DRV_CAMERA_Status ( const CAMERA_MODULE_ID index ) DRV_CAMERA_Tasks Function File drv_camera.h C void DRV_CAMERA_Tasks(SYS_MODULE_OBJ object); Description This is function DRV_CAMERA_Tasks. b) Common Data Types and Constants DRV_CAMERA_INIT Structure Defines the data required to initialize or reinitialize the CAMERA driver. File drv_camera.h C typedef struct { SYS_MODULE_INIT moduleInit; int cameraId; SYS_MODULE_OBJ (* drvInitialize)(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); DRV_HANDLE (* drvOpen)(const SYS_MODULE_INDEX index, const DRV_IO_INTENT intent); INT_SOURCE interruptSource; DRV_CAMERA_INTERRUPT_PORT_REMAP interruptPort; uint16_t orientation; uint16_t horizontalResolution; uint16_t verticalResolution; } DRV_CAMERA_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization int cameraId; ID uint16_t orientation; Orientation of the display (given in degrees of 0,90,180,270) uint16_t horizontalResolution; Horizontal Resolution of the displayed orientation in Pixels Description CAMERA Driver Initialization Data This data type defines the data required to initialize or reinitialize the CAMERA driver. If the driver is built statically, the members of this data structure are statically over-ridden by static override definitions in the system_config.h file. Remarks None. DRV_CAMERA_INTERRUPT_PORT_REMAP Structure Defines the data required to initialize the CAMERA driver interrupt port remap. File drv_camera.h C typedef struct { Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 77 PORTS_REMAP_INPUT_FUNCTION inputFunction; PORTS_REMAP_INPUT_PIN inputPin; PORTS_ANALOG_PIN analogPin; PORTS_PIN_MODE pinMode; PORTS_CHANNEL channel; PORTS_DATA_MASK dataMask; } DRV_CAMERA_INTERRUPT_PORT_REMAP; Description CAMERA Driver Interrupt Port Remap Initialization Data This data type defines the data required to initialize the CAMERA driver interrupt port remap. Remarks None. DRV_CAMERA_INDEX_0 Macro Camera driver index definitions. File drv_camera.h C #define DRV_CAMERA_INDEX_0 0 Description Camera Driver Module Index Numbers These constants provide the Camera driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_CAMERA_Initialize and DRV_CAMERA_Open functions to identify the driver instance in use. DRV_CAMERA_INDEX_1 Macro File drv_camera.h C #define DRV_CAMERA_INDEX_1 1 Description This is macro DRV_CAMERA_INDEX_1. DRV_CAMERA_INDEX_COUNT Macro Number of valid CAMERA driver indices. File drv_camera.h C #define DRV_CAMERA_INDEX_COUNT 1 Description CAMERA Driver Module Index Count This constant identifies the number of valid CAMERA driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific header files defined as part of the peripheral libraries. Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 78 CAMERA_MODULE_ID Enumeration File drv_camera.h C typedef enum { CAMERA_MODULE_OVM7690 } CAMERA_MODULE_ID; Description This is type CAMERA_MODULE_ID. Files Files Name Description drv_camera.h Camera device driver interface file. Description drv_camera.h Camera device driver interface file. Enumerations Name Description CAMERA_MODULE_ID This is type CAMERA_MODULE_ID. Functions Name Description DRV_CAMERA_Close Closes an opened instance of an CAMERA module driver. DRV_CAMERA_Deinitialize Deinitializes the index instance of the CAMERA module. DRV_CAMERA_Initialize Initializes hardware and data for the index instance of the CAMERA module. DRV_CAMERA_Open Opens the specified instance of the Camera driver for use and provides an "open instance" handle. DRV_CAMERA_Reinitialize Reinitializes hardware and data for the index instance of the CAMERA module. DRV_CAMERA_Status Provides the current status of the index instance of the CAMERA module. DRV_CAMERA_Tasks This is function DRV_CAMERA_Tasks. Macros Name Description DRV_CAMERA_INDEX_0 Camera driver index definitions. DRV_CAMERA_INDEX_1 This is macro DRV_CAMERA_INDEX_1. DRV_CAMERA_INDEX_COUNT Number of valid CAMERA driver indices. Structures Name Description DRV_CAMERA_INIT Defines the data required to initialize or reinitialize the CAMERA driver. DRV_CAMERA_INTERRUPT_PORT_REMAP Defines the data required to initialize the CAMERA driver interrupt port remap. Description Camera Driver Interface The Camera driver provides a abstraction to all camera drivers. Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 79 File Name drv_camera.h Company Microchip Technology Inc. OVM7690 Camera Driver Library This topic describes the OVM7690 Camera Driver Library. Introduction The OVM7690 Camera Driver provides a high-level interface to manage the OmniVision Technologies, Inc. OVM7690 640x480 CameraCube™ device (referred to as the OVM7690) that is interfaced with serial and parallel ports to a Microchip microcontroller for providing camera solutions. Description The OVM7690 640x480 CameraCube™ device (referred to as the OVM7690) can be interfaced to a Microchip microcontroller using the I2C serial interface and parallel port interface. The I2C serial interface is used for control command transfer. The I2C module from the microcontroller is connected to the SCCB serial interface of the OVM7690. The parallel port interface is used to transfer pixel data from the OVM7690 to the microcontroller. There are few other signals from the camera to be interfaced with the microcontroller. The XVCLK pin of the camera is driven by the Output Compare module. Frame synchronization signals such as HREF and VSYNC from the camera are connected to suitable pins supporting change notification within the microcontroller. The PCLK pin of the camera drives the pixel clock and is connected at the pin of the microcontroller supporting external interrupts. The PWDN pin of the camera supports camera power-down mode and is connected at any output port pin of the microcontroller. A typical interface of the OVM7690 to a PIC32 device is provided in the following diagram: Using the Library This topic describes the basic architecture of the OVM7690 Camera Driver Library and provides information and examples on its use. Description Interface Header File: drv_camera_ovm7690.h The interface to the Camera Driver Library is defined in the drv_camera_ovm7690.h header file. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The library interface routines are divided into various sub-sections, which address the overall operation of the OVM7690 Camera Driver Library. Library Interface Section Description System Functions Provides system module interfaces, device initialization and deinitialization. Client Setup Functions Provides open and close functions. Camera-specific Functions Provides APIs that are camera-specific. Other Functions Provides miscellaneous driver-specific functions such as register set functions, among others. Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 80 Abstraction Model This library provides a low-level abstraction of the OVM7690 Camera Driver Library 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 OVM7690 Camera Driver is modeled using the abstraction model, as shown in the following diagram. How the Library Works Provides information on how the OVM7690 Camera Driver Library works. Description The library provides interfaces to support: • System functionality • Client functionality System Initialization The system performs the Initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization, each instance of the OVM7690 would be initialized with the following configuration settings that are supported by the specific OVM7690 device hardware: • Camera ID: OVM7690 ID • Source Port: Address of source port to which the pixel data is received • Horizontal Sync Channel: Channel of the pin to be configured as horizontal sync • Horizontal Sync Position: Horizontal sync port pin position from selected port channel • Vertical Sync Channel: Channel the pin to be configured as vertical sync • Vertical Sync Position: Vertical sync port pin position from selected port channel • Horizontal Sync Interrupt Source • Vertical Sync Interrupt Source • DMA Channel: DMA channel to transfer pixel data from camera to frame buffer • DMA Channel Trigger Source • Bits Per Pixel: Bits per pixel to define the size of frame line The DRV_CAMERA_OVM7690_Initialize API returns an object handle of the type SYS_MODULE_OBJ. The object handler returned by the Initialize Interface would be used by the other interfaces such as DRV_CAMERA_OVM7690_Deinitialize. Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 81 Client Access For the application to start using an instance of the module, it must call the DRV_CAMERA_OVM7690_Open function. The DRV_CAMERA_OVM7690_Open function provides a driver handle to the OVM7690 Camera Driver instance for operations. If the driver is deinitialized using the function DRV_CAMERA_OVM7690_Deinitialize function, the application must call the DRV_CAMERA_OVM7690_Open function again to set up the instance of the driver. Client Operations Client operations provide the API interface for control command and pixel data transfer from the OVM7690 Camera Driver to the Graphics Frame Buffer. Configuring the Library Macros Name Description DRV_OVM7690_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. Description The configuration of the OVM7690 Camera Driver is based on the file system_config.h. This header file contains the configuration selection for the OVM7690 Camera Driver build. Based on the selections made here and the system setup, the OVM7690 Camera Driver may support the selected features. These configuration settings will apply to all instances of the driver. This header can be placed anywhere in the application specific folders and the path of this header needs to be presented to the include search for a successful build. Refer to the Applications Help section for more details. Control Commands The following OVM7690-specific control commands are provided: • DRV_CAMERA_OVM7690_FrameBufferAddressSet • DRV_CAMERA_OVM7690_Start • DRV_CAMERA_OVM7690_Stop • DRV_CAMERA_OVM7690_FrameRectSet Application Process An application needs to perform following steps: 1. The system should have completed necessary setup initializations. 2. The I2C driver object should have been initialized by calling DRV_I2C_Initialize. 3. The Timer driver object should have been initialized by calling DRV_Timer_Initialize, 4. The Output Control driver object should have been initialized by calling DRV_OC_Initialize, 5. The OVM7690 Camera Driver object should have been initialized by calling DRV_CAMERA_OVM7690_Initialize, 6. Open the OVM7690 Camera Driver client by calling DRV_CAMERA_OVM7690_Open. 7. Pass the Graphics Frame buffer address to OVM7690 Camera Driver by calling DRV_CAMERA_OVM7690_FrameBufferAddressSet. 8. Set the Frame Rectangle area by calling DRV_CAMERA_OVM7690_FrameRectSet. 9. Set Other Camera settings such as: soft reset, enabling pclk, enabling href, enabling vsync, output color format, reversing HREF polarity, gating clock to the HREF, pixel clock frequency, sub-sampling mode by calling DRV_CAMERA_OVM7690_RegisterSet. 10. Start the OVM7690 Camera by calling DRV_CAMERA_OVM7690_Start. DRV_OVM7690_INTERRUPT_MODE Macro Controls operation of the driver in the interrupt or polled mode. File drv_ovm7690_config_template.h C #define DRV_OVM7690_INTERRUPT_MODE false Description OVM7690 Interrupt And Polled Mode Operation Control This macro controls the operation of the driver in the interrupt mode of operation. The possible values of this macro are: • true - Select if interrupt mode of OVM7690 operation is desired Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 82 • false - Select if polling mode of OVM7690 operation is desired Not defining this option to true or false will result in a build error. Remarks None. Building the Library This section lists the files that are available in the OVM7690 Camera Driver Library. 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 /framework/driver/camera/ovm7690. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_camera_ovm7690.h This file provides the interface definitions of the OVM7690 Camera Driver. 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 /src/drv_camera_ovm7690.c This file contains the implementation of the OVM7690 Camera Driver. 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 N/A No optional files are available for this library. Module Dependencies The OVM7690 Camera Driver Library depends on the following modules: • I2C Driver Library • Output Compare Driver Library • Timer Driver Library Library Interface a) System Functions Name Description DRV_CAMERA_OVM7690_Initialize Initializes the OVM7690 Camera instance for the specified driver index. DRV_CAMERA_OVM7690_Deinitialize Deinitializes the specified instance of the OVM7690 Camera Driver module. DRV_CAMERA_OVM7690_RegisterSet Sets the camera OVM7690 configuration registers. DRV_CAMERA_OVM7690_Tasks Maintains the OVM7690 state machine. b) Client Setup Functions Name Description DRV_CAMERA_OVM7690_Open Opens the specified OVM7690 Camera Driver instance and returns a handle to it. DRV_CAMERA_OVM7690_Close Closes an opened instance of the OVM7690 Camera Driver. c) Camera-specific Functions Name Description DRV_CAMERA_OVM7690_FrameBufferAddressSet Sets the framebuffer address. Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 83 DRV_CAMERA_OVM7690_FrameRectSet Sets the frame rectangle set. DRV_CAMERA_OVM7690_Start Starts camera rendering to the display. DRV_CAMERA_OVM7690_Stop Stops rendering the camera Pixel data. d) Other Functions Name Description DRV_CAMERA_OVM7690_HsyncEventHandler Horizontal synchronization event handler. DRV_CAMERA_OVM7690_VsyncEventHandler Vertical synchronization event handler . _DRV_CAMERA_OVM7690_DMAEventHandler This is function _DRV_CAMERA_OVM7690_DMAEventHandler. _DRV_CAMERA_OVM7690_delayMS This is function _DRV_CAMERA_OVM7690_delayMS. _DRV_CAMERA_OVM7690_HardwareSetup This is function _DRV_CAMERA_OVM7690_HardwareSetup. e) Data Types and Constants Name Description DRV_CAMERA_OVM7690_CLIENT_OBJ OVM7690 Camera Driver client object. DRV_CAMERA_OVM7690_CLIENT_STATUS Identifies OVM7690 Camera possible client status. DRV_CAMERA_OVM7690_ERROR Identifies OVM7690 Camera possible errors. DRV_CAMERA_OVM7690_INIT OVM7690 Camera Driver initialization parameters. DRV_CAMERA_OVM7690_OBJ OVM7690 Camera Driver instance object. DRV_CAMERA_OVM7690_RECT OVM7690 Camera window rectangle coordinates. DRV_CAMERA_OVM7690_REG12_OP_FORMAT Lists OVM7690 Camera device register addresses. DRV_CAMERA_OVM7690_INDEX_0 OVM7690 driver index definitions. DRV_CAMERA_OVM7690_INDEX_1 This is macro DRV_CAMERA_OVM7690_INDEX_1. DRV_CAMERA_OVM7690_REG12_SOFT_RESET OVM7690 Camera Driver Register 0x12 Soft reset flag. DRV_CAMERA_OVM7690_SCCB_READ_ID OVM7690 Camera SCCB Interface device Read Slave ID. DRV_CAMERA_OVM7690_SCCB_WRITE_ID OVM7690 Camera SCCB Interface device Write Slave ID. Description This section describes the Application Programming Interface (API) functions of the Camera Driver Library. a) System Functions DRV_CAMERA_OVM7690_Initialize Function Initializes the OVM7690 Camera instance for the specified driver index. File drv_camera_ovm7690.h C SYS_MODULE_OBJ DRV_CAMERA_OVM7690_Initialize(const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, returns SYS_MODULE_OBJ_INVALID. Description This function initializes the OVM7690 Camera Driver instance for the specified driver index, making it ready for clients to open and use it. The initialization data is specified by the init parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. The driver instance index is independent of the OVM7690 Camera module ID. Refer to the description of the DRV_CAMERA_OVM7690_INIT data structure for more details on which members on this data structure are overridden. Remarks This function must be called before any other OVM7690 Camera Driver function is called. This function should only be called once during system initialization unless DRV_CAMERA_OVM7690_Deinitialize is called to deinitialize the driver instance. This function will NEVER block for hardware access. Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 84 Preconditions None. Example // The following code snippet shows an example OVM7690 driver initialization. DRV_CAMERA_OVM7690_INIT cameraInit; SYS_MODULE_OBJ objectHandle; cameraInit.cameraID = CAMERA_MODULE_OVM7690; cameraInit.sourcePort = (void *)&PORTK, cameraInit.hsyncInterruptSource = INT_SOURCE_CHANGE_NOTICE_A, cameraInit.vsyncInterruptSource = INT_SOURCE_CHANGE_NOTICE_J, cameraInit.dmaChannel = DRV_CAMERA_OVM7690_DMA_CHANNEL_INDEX, cameraInit.dmaTriggerSource = DMA_TRIGGER_EXTERNAL_2, cameraInit.bpp = GFX_CONFIG_COLOR_DEPTH, objectHandle = DRV_CAMERA_OVM7690_Initialize( DRV_CAMERA_OVM7690_INDEX_0, (SYS_MODULE_INIT*)&cameraInit); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized init Pointer to a data structure containing any data necessary to initialize the driver. Function SYS_MODULE_OBJ DRV_CAMERA_OVM7690_Initialize ( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ) DRV_CAMERA_OVM7690_Deinitialize Function Deinitializes the specified instance of the OVM7690 Camera Driver module. File drv_camera_ovm7690.h C void DRV_CAMERA_OVM7690_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description This function deinitializes the specified instance of the OVM7690 Camera Driver module, disabling its operation (and any hardware), and invalidates all of the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. Preconditions Function DRV_CAMERA_OVM7690_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_CAMERA_OVM7690_Initialize Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 85 SYS_STATUS status; DRV_CAMERA_OVM7690_Deinitialize(object); status = DRV_CAMERA_OVM7690_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from the DRV_CAMERA_OVM7690_Initialize function Function void DRV_CAMERA_OVM7690_Deinitialize( SYS_MODULE_OBJ object ) DRV_CAMERA_OVM7690_RegisterSet Function Sets the camera OVM7690 configuration registers. File drv_camera_ovm7690.h C DRV_CAMERA_OVM7690_ERROR DRV_CAMERA_OVM7690_RegisterSet(DRV_CAMERA_OVM7690_REGISTER_ADDRESS regIndex, uint8_t regValue); Returns • DRV_CAMERA_OVM7690_ERROR_INVALID_HANDLE - Invalid driver Handle. • DRV_CAMERA_OVM7690_ERROR_NONE - No error. Description This function sets the OVM7690 Camera configuration registers using the SCCB interface. Remarks This function can be used separately or within an interface. Preconditions The DRV_CAMERA_OVM7690_Initialize function must have been called for the specified OVM7690 Camera Driver instance. DRV_CAMERA_OVM7690_Open must have been called to obtain a valid opened device handle. The SCCB interface also must have been initialized to configure the OVM7690 Camera Driver. Example DRV_HANDLE handle; uint8_t reg12 = DRV_CAMERA_OVM7690_REG12_SOFT_RESET; handle = DRV_CAMERA_OVM7690_Open(DRV_CAMERA_OVM7690_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { //error return; } if ( DRV_CAMERA_OVM7690_RegisterSet( DRV_CAMERA_OVM7690_REG12_REG_ADDR, reg12 ) != DRV_CAMERA_OVM7690_ERROR_NONE ) { //error return; } Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 86 Parameters Parameters Description regIndex Defines the OVM7690 configuration register addresses. regValue Defines the register value to be set. Function DRV_CAMERA_OVM7690_ERROR DRV_CAMERA_OVM7690_RegisterSet ( DRV_CAMERA_OVM7690_REGISTER_ADDRESS regIndex, uint8_t regValue ) DRV_CAMERA_OVM7690_Tasks Function Maintains the OVM7690 state machine. File drv_camera_ovm7690.h C void DRV_CAMERA_OVM7690_Tasks(SYS_MODULE_OBJ object); Function void DRV_CAMERA_OVM7690_Tasks(SYS_MODULE_OBJ object ); b) Client Setup Functions DRV_CAMERA_OVM7690_Open Function Opens the specified OVM7690 Camera Driver instance and returns a handle to it. File drv_camera_ovm7690.h C DRV_HANDLE DRV_CAMERA_OVM7690_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent); Returns If successful, the function returns a valid open instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Errors can occur: • if the number of client objects allocated via DRV_CAMERA_OVM7690_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the driver hardware instance being opened is not initialized or is invalid • if the client is trying to open the driver exclusively, but has already been opened in a non exclusive mode by another client • if the driver is not ready to be opened, typically when the initialize function has not completed execution Description This function opens the specified OVM7690 Camera Driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. Remarks The handle returned is valid until the DRV_CAMERA_OVM7690_Close function is called. This function will NEVER block waiting for hardware.If the requested intent flags are not supported, the function will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. Preconditions Function DRV_CAMERA_OVM7690_Initialize must have been called before calling this function. Example DRV_HANDLE handle; Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 87 handle = DRV_CAMERA_OVM7690_Open(DRV_CAMERA_OVM7690_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver // May be the driver is not initialized or the initialization // is not complete. } Parameters Parameters Description index Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver. See function description for details. Function DRV_HANDLE DRV_CAMERA_OVM7690_Open ( const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent ) DRV_CAMERA_OVM7690_Close Function Closes an opened instance of the OVM7690 Camera Driver. File drv_camera_ovm7690.h C void DRV_CAMERA_OVM7690_Close(DRV_HANDLE handle); Returns None. Description This function closes an opened instance of the OVM7690 Camera Driver, invalidating the handle. Any buffers in the driver queue that were submitted by this client will be removed. After calling this function, the handle passed in "handle" must not be used with any of the remaining driver routines (with one possible exception described in the "Remarks" section). A new handle must be obtained by calling DRV_CAMERA_OVM7690_Open before the caller may use the driver again Remarks Usually there is no need for the client to verify that the Close operation has completed. The driver will abort any ongoing operations when this function is called. Preconditions The DRV_CAMERA_OVM7690_Initialize function must have been called for the specified OVM7690 Camera Driver instance. DRV_CAMERA_OVM7690_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_USART_Open DRV_CAMERA_OVM7690_Close(handle); Parameters Parameters Description handle A valid open instance handle, returned from the driver's Open function Function void DRV_CAMERA_OVM7690_Close( DRV_Handle handle ) c) Camera-specific Functions Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 88 DRV_CAMERA_OVM7690_FrameBufferAddressSet Function Sets the framebuffer address. File drv_camera_ovm7690.h C DRV_CAMERA_OVM7690_ERROR DRV_CAMERA_OVM7690_FrameBufferAddressSet(DRV_HANDLE handle, void * frameBuffer); Returns • DRV_CAMERA_OVM7690_ERROR_INVALID_HANDLE - Invalid driver Handle. • DRV_CAMERA_OVM7690_ERROR_NONE - No error. Description This function will set the framebuffer address. This framebuffer address will point to the location at which frame data is to be rendered. This buffer is shared with the display controller to display the frame on the display. Remarks This function is mandatory. A valid framebuffer address must be set to display the camera data. Preconditions The DRV_CAMERA_OVM7690_Initialize function must have been called for the specified OVM7690 Camera Driver instance. DRV_CAMERA_OVM7690_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; uint16_t frameBuffer[DISP_VER_RESOLUTION][DISP_HOR_RESOLUTION]; handle = DRV_CAMERA_OVM7690_Open(DRV_CAMERA_OVM7690_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { //error return; } if ( DRV_CAMERA_OVM7690_FrameBufferAddressSet( handle, (void *) frameBuffer ) != DRV_CAMERA_OVM7690_ERROR_NONE ) { //error return; } Parameters Parameters Description handle A valid open instance handle, returned from the driver's Open function Function DRV_CAMERA_OVM7690_ERROR DRV_CAMERA_OVM7690_FrameBufferAddressSet ( DRV_HANDLE handle, void * frameBuffer ) DRV_CAMERA_OVM7690_FrameRectSet Function Sets the frame rectangle set. File drv_camera_ovm7690.h Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 89 C DRV_CAMERA_OVM7690_ERROR DRV_CAMERA_OVM7690_FrameRectSet(DRV_HANDLE handle, uint32_t left, uint32_t top, uint32_t right, uint32_t bottom); Returns • DRV_CAMERA_OVM7690_ERROR_INVALID_HANDLE - Invalid driver Handle. • DRV_CAMERA_OVM7690_ERROR_NONE - No error. Description This function sets the frame rectangle coordinates. The frame within the rectangle is copied to the framebuffer. The left and top values are expected to be less than right and bottom respectively. Left, top, right, and bottom values are also expected to be within range of screen coordinates. Internally it calls the DRV_CAMERA_OVM7690_RegisterSet function to set the respective registers. The rectangle coordinates are also maintained in the driver object. Remarks This function is optional if default values are expected to be used. Preconditions The DRV_CAMERA_OVM7690_Initialize function must have been called for the specified OVM7690 Camera Driver instance. DRV_CAMERA_OVM7690_Open must have been called to obtain a valid opened device handle. The SCCB interface also must have been initialized to configure the OVM7690 Camera Driver. Example DRV_HANDLE handle; uint32_t left = 0x69; uint32_t top = 0x0E; uint32_t right = DISP_HOR_RESOLUTION + 0x69; uint32_t bottom = DISP_VER_RESOLUTION + 0x69; handle = DRV_CAMERA_OVM7690_Open(DRV_CAMERA_OVM7690_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { //error return; } if ( DRV_CAMERA_OVM7690_FrameRectSet( handle, left, top, right, bottom ) != DRV_CAMERA_OVM7690_ERROR_NONE ) { //error return; } Parameters Parameters Description handle A valid open instance handle, returned from the driver's Open function left left frame coordinate top top frame coordinate right right frame coordinate bottom bottom frame coordinate Function DRV_CAMERA_OVM7690_ERROR DRV_CAMERA_OVM7690_FrameRectSet ( DRV_HANDLE handle, uint32_t left, uint32_t top, uint32_t right, uint32_t bottom ) Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 90 DRV_CAMERA_OVM7690_Start Function Starts camera rendering to the display. File drv_camera_ovm7690.h C DRV_CAMERA_OVM7690_ERROR DRV_CAMERA_OVM7690_Start(DRV_HANDLE handle); Returns • DRV_CAMERA_OVM7690_ERROR_INVALID_HANDLE - Invalid driver Handle. • DRV_CAMERA_OVM7690_ERROR_NONE - No error. Description This function starts the camera rendering to the display by writing the pixel data to the framebuffer. The framebuffer is shared between the OVM7690 Camera and the display controller. Remarks This function is mandatory. Camera module will not update the framebuffer without calling this function. Preconditions The DRV_CAMERA_OVM7690_Initialize function must have been called for the specified OVM7690 Camera Driver instance. DRV_CAMERA_OVM7690_Open must have been called to obtain a valid opened device handle. DRV_CAMERA_OVM7690_FrameBufferAddressSet must have been called to set a valid framebuffer address. Example DRV_HANDLE handle; uint16_t frameBuffer[DISP_VER_RESOLUTION][DISP_HOR_RESOLUTION]; handle = DRV_CAMERA_OVM7690_Open(DRV_CAMERA_OVM7690_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { //error return; } if ( DRV_CAMERA_OVM7690_FrameBufferAddressSet( handle, (void *) frameBuffer ) != DRV_CAMERA_OVM7690_ERROR_NONE ) { //error return; } if ( DRV_CAMERA_OVM7690_Start( handle ) != DRV_CAMERA_OVM7690_ERROR_NONE ) { //error return; } Parameters Parameters Description handle A valid open instance handle, returned from the driver's Open function Function DRV_CAMERA_OVM7690_ERROR DRV_CAMERA_OVM7690_Start ( DRV_HANDLE handle ); Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 91 DRV_CAMERA_OVM7690_Stop Function Stops rendering the camera Pixel data. File drv_camera_ovm7690.h C DRV_CAMERA_OVM7690_ERROR DRV_CAMERA_OVM7690_Stop(DRV_HANDLE handle); Returns • DRV_CAMERA_OVM7690_ERROR_INVALID_HANDLE - Invalid driver Handle. • DRV_CAMERA_OVM7690_ERROR_NONE - No error. Description This function starts the camera rendering to the display by writing the pixel data to the framebuffer. The framebuffer is shared between the OVM7690 Camera and the display controller. Remarks This function only disables the interrupt for HSYNC and VSYNC. To stop the camera the power-down pin needs to be toggled to an active-high value., which will stop the camera internal clock and maintain the register values. Preconditions The DRV_CAMERA_OVM7690_Initialize function must have been called for the specified OVM7690 Camera Driver instance. DRV_CAMERA_OVM7690_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; handle = DRV_CAMERA_OVM7690_Open(DRV_CAMERA_OVM7690_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { //error return; } if ( DRV_CAMERA_OVM7690_Stop( handle ) != DRV_CAMERA_OVM7690_ERROR_NONE ) { //error return; } Parameters Parameters Description handle A valid open instance handle, returned from the driver's Open function. Function DRV_CAMERA_OVM7690_ERROR DRV_CAMERA_OVM7690_Stop ( DRV_HANDLE handle ); d) Other Functions DRV_CAMERA_OVM7690_HsyncEventHandler Function Horizontal synchronization event handler. Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 92 File drv_camera_ovm7690.h C void DRV_CAMERA_OVM7690_HsyncEventHandler(SYS_MODULE_OBJ object); Returns None. Description This function is called when the OVM7690 Camera sends a Horizontal Sync Pulse on the HSYNC line. It sets the next line address in the DMA module. Remarks This function is mandatory. Preconditions The DRV_CAMERA_OVM7690_Initialize function must have been called for the specified OVM7690 Camera Driver instance. DRV_CAMERA_OVM7690_Open must have been called to obtain a valid opened device handle. Example DRV_CAMERA_OVM7690_INIT cameraInit; SYS_MODULE_OBJ objectHandle; cameraInit.cameraID = CAMERA_MODULE_OVM7690; cameraInit.sourcePort = (void *)&PORTK, cameraInit.hsyncInterruptSource = INT_SOURCE_CHANGE_NOTICE_A, cameraInit.vsyncInterruptSource = INT_SOURCE_CHANGE_NOTICE_J, cameraInit.dmaChannel = DRV_CAMERA_OVM7690_DMA_CHANNEL_INDEX, cameraInit.dmaTriggerSource = DMA_TRIGGER_EXTERNAL_2, cameraInit.bpp = GFX_CONFIG_COLOR_DEPTH, objectHandle = DRV_CAMERA_OVM7690_Initialize( DRV_CAMERA_OVM7690_INDEX_0, (SYS_MODULE_INIT*)&cameraInit); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } handle = DRV_CAMERA_OVM7690_Open(DRV_CAMERA_OVM7690_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { //error return; } void __ISR( HSYNC_ISR_VECTOR) _Ovm7690HSyncHandler(void) { DRV_CAMERA_OVM7690_HsyncEventHandler(objectHandle); SYS_INT_SourceStatusClear(HSYNC_INTERRUPT_SOURCE); } Parameters Parameters Description object Driver object handle, returned from the DRV_CAMERA_OVM7690_Initialize function Function void DRV_CAMERA_OVM7690_HsyncEventHandler(SYS_MODULE_OBJ object) DRV_CAMERA_OVM7690_VsyncEventHandler Function Vertical synchronization event handler . Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 93 File drv_camera_ovm7690.h C void DRV_CAMERA_OVM7690_VsyncEventHandler(SYS_MODULE_OBJ object); Returns None. Description This function is called when the OVM7690 Camera sends a Vertical Sync Pulse on the VSYNC line. It clears the number of lines drawn variable. Remarks This function is mandatory. Preconditions The DRV_CAMERA_OVM7690_Initialize function must have been called for the specified OVM7690 Camera Driver instance. DRV_CAMERA_OVM7690_Open must have been called to obtain a valid opened device handle. Example DRV_CAMERA_OVM7690_INIT cameraInit; SYS_MODULE_OBJ objectHandle; cameraInit.cameraID = CAMERA_MODULE_OVM7690; cameraInit.sourcePort = (void *)&PORTK, cameraInit.hsyncInterruptSource = INT_SOURCE_CHANGE_NOTICE_A, cameraInit.vsyncInterruptSource = INT_SOURCE_CHANGE_NOTICE_J, cameraInit.dmaChannel = DRV_CAMERA_OVM7690_DMA_CHANNEL_INDEX, cameraInit.dmaTriggerSource = DMA_TRIGGER_EXTERNAL_2, cameraInit.bpp = GFX_CONFIG_COLOR_DEPTH, objectHandle = DRV_CAMERA_OVM7690_Initialize( DRV_CAMERA_OVM7690_INDEX_0, (SYS_MODULE_INIT*)&cameraInit); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } handle = DRV_CAMERA_OVM7690_Open(DRV_CAMERA_OVM7690_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { //error return; } void __ISR( VSYNC_ISR_VECTOR) _Ovm7690VSyncHandler(void) { DRV_CAMERA_OVM7690_VsyncEventHandler(objectHandle); SYS_INT_SourceStatusClear(VSYNC_INTERRUPT_SOURCE); } Parameters Parameters Description object Driver object handle, returned from the DRV_CAMERA_OVM7690_Initialize function Function void DRV_CAMERA_OVM7690_VsyncEventHandler(SYS_MODULE_OBJ object) Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 94 _DRV_CAMERA_OVM7690_DMAEventHandler Function File drv_camera_ovm7690.h C void _DRV_CAMERA_OVM7690_DMAEventHandler(SYS_DMA_TRANSFER_EVENT event, SYS_DMA_CHANNEL_HANDLE handle, uintptr_t contextHandle); Description This is function _DRV_CAMERA_OVM7690_DMAEventHandler. _DRV_CAMERA_OVM7690_delayMS Function File drv_camera_ovm7690.h C void _DRV_CAMERA_OVM7690_delayMS(unsigned int delayMs); Description This is function _DRV_CAMERA_OVM7690_delayMS. _DRV_CAMERA_OVM7690_HardwareSetup Function File drv_camera_ovm7690.h C void _DRV_CAMERA_OVM7690_HardwareSetup(DRV_CAMERA_OVM7690_OBJ * dObj); Description This is function _DRV_CAMERA_OVM7690_HardwareSetup. e) Data Types and Constants DRV_CAMERA_OVM7690_CLIENT_OBJ Structure OVM7690 Camera Driver client object. File drv_camera_ovm7690.h C typedef struct { DRV_CAMERA_OVM7690_OBJ * hDriver; DRV_IO_INTENT ioIntent; bool inUse; DRV_CAMERA_OVM7690_ERROR error; DRV_CAMERA_OVM7690_CLIENT_STATUS status; } DRV_CAMERA_OVM7690_CLIENT_OBJ; Members Members Description DRV_CAMERA_OVM7690_OBJ * hDriver; The hardware instance object associated with the client DRV_IO_INTENT ioIntent; The I/O intent with which the client was opened bool inUse; This flags indicates if the object is in use or is available DRV_CAMERA_OVM7690_ERROR error; Driver Error Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 95 DRV_CAMERA_OVM7690_CLIENT_STATUS status; Client status Description OVM7690 Camera Driver Client Object. This structure provides a definition of the OVM7690 Camera Driver client object. Remarks These values are been updated into the DRV_CAMERA_OVM7690_Open function. DRV_CAMERA_OVM7690_CLIENT_STATUS Enumeration Identifies OVM7690 Camera possible client status. File drv_camera_ovm7690.h C typedef enum { DRV_CAMERA_OVM7690_CLIENT_STATUS_ERROR = DRV_CLIENT_STATUS_ERROR, DRV_CAMERA_OVM7690_CLIENT_STATUS_CLOSED = DRV_CLIENT_STATUS_CLOSED, DRV_CAMERA_OVM7690_CLIENT_STATUS_BUSY = DRV_CLIENT_STATUS_BUSY, DRV_CAMERA_OVM7690_CLIENT_STATUS_READY = DRV_CLIENT_STATUS_READY } DRV_CAMERA_OVM7690_CLIENT_STATUS; Members Members Description DRV_CAMERA_OVM7690_CLIENT_STATUS_ERROR = DRV_CLIENT_STATUS_ERROR An error has occurred. DRV_CAMERA_OVM7690_CLIENT_STATUS_CLOSED = DRV_CLIENT_STATUS_CLOSED The driver is closed, no operations for this client are ongoing, and/or the given handle is invalid. DRV_CAMERA_OVM7690_CLIENT_STATUS_BUSY = DRV_CLIENT_STATUS_BUSY The driver is currently busy and cannot start additional operations. DRV_CAMERA_OVM7690_CLIENT_STATUS_READY = DRV_CLIENT_STATUS_READY The module is running and ready for additional operations Description OVM7690 Camera Client Status. This enumeration defines possible OVM7690 Camera Client Status. Remarks This enumeration values are set by driver interfaces: DRV_CAMERA_OVM7690_Open and DRV_CAMERA_OVM7690_Close. DRV_CAMERA_OVM7690_ERROR Enumeration Identifies OVM7690 Camera possible errors. File drv_camera_ovm7690.h C typedef enum { DRV_CAMERA_OVM7690_ERROR_INVALID_HANDLE, DRV_CAMERA_OVM7690_ERROR_NONE } DRV_CAMERA_OVM7690_ERROR; Members Members Description DRV_CAMERA_OVM7690_ERROR_INVALID_HANDLE OVM7690 Camera Driver Invalid Handle DRV_CAMERA_OVM7690_ERROR_NONE OVM7690 Camera Driver error none Description OVM7690 Camera Error flag Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 96 This enumeration defines possible OVM7690 Camera errors. Remarks This enumeration values are returned by driver interfaces in case of errors. DRV_CAMERA_OVM7690_INIT Structure OVM7690 Camera Driver initialization parameters. File drv_camera_ovm7690.h C typedef struct { CAMERA_MODULE_ID cameraID; void * sourcePort; PORTS_CHANNEL hsyncChannel; PORTS_BIT_POS hsyncPosition; PORTS_CHANNEL vsyncChannel; PORTS_BIT_POS vsyncPosition; INT_SOURCE hsyncInterruptSource; INT_SOURCE vsyncInterruptSource; DMA_CHANNEL dmaChannel; DMA_TRIGGER_SOURCE dmaTriggerSource; uint16_t bpp; } DRV_CAMERA_OVM7690_INIT; Members Members Description CAMERA_MODULE_ID cameraID; Camera module ID void * sourcePort; Source Port Address PORTS_CHANNEL hsyncChannel; HSYNC pin channel PORTS_BIT_POS hsyncPosition; HSYNC pin bit position PORTS_CHANNEL vsyncChannel; VSYNC pin channel PORTS_BIT_POS vsyncPosition; VSYNC pin bit position INT_SOURCE hsyncInterruptSource; HSYNC Interrupt Source INT_SOURCE vsyncInterruptSource; VSYNC Interrupt Source DMA_CHANNEL dmaChannel; DMA channel DMA_TRIGGER_SOURCE dmaTriggerSource; DMA trigger source uint16_t bpp; Bits per pixel Description OVM7690 Camera Initialization parameters This structure defines OVM7690 Camera Driver initialization parameters. Remarks These values should be passed into the DRV_CAMERA_OVM7690_Initialize function. DRV_CAMERA_OVM7690_OBJ Structure OVM7690 Camera Driver instance object. File drv_camera_ovm7690.h C typedef struct { CAMERA_MODULE_ID moduleId; SYS_STATUS status; bool inUse; bool isExclusive; size_t nClients; PORTS_CHANNEL hsyncChannel; PORTS_BIT_POS hsyncPosition; Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 97 PORTS_CHANNEL vsyncChannel; PORTS_BIT_POS vsyncPosition; INT_SOURCE hsyncInterruptSource; INT_SOURCE vsyncInterruptSource; SYS_DMA_CHANNEL_HANDLE dmaHandle; DMA_CHANNEL dmaChannel; DMA_TRIGGER_SOURCE dmaTriggerSource; bool dmaTransferComplete; void * sourcePort; uint32_t frameLineCount; uint32_t frameLineSize; void * frameLineAddress; void * frameBufferAddress; DRV_CAMERA_OVM7690_RECT rect; uint16_t bpp; } DRV_CAMERA_OVM7690_OBJ; Members Members Description CAMERA_MODULE_ID moduleId; The module index associated with the object SYS_STATUS status; The status of the driver bool inUse; Flag to indicate this object is in use bool isExclusive; Flag to indicate that driver has been opened exclusively. size_t nClients; Keeps track of the number of clients • that have opened this driver PORTS_CHANNEL hsyncChannel; HSYNC pin channel PORTS_BIT_POS hsyncPosition; HSYNC pin bit position PORTS_CHANNEL vsyncChannel; VSYNC pin channel PORTS_BIT_POS vsyncPosition; VSYNC pin bit position INT_SOURCE hsyncInterruptSource; HSYNC Interrupt Source INT_SOURCE vsyncInterruptSource; VSYNC Interrupt Source SYS_DMA_CHANNEL_HANDLE dmaHandle; DMA Handle DMA_CHANNEL dmaChannel; Read DMA channel DMA_TRIGGER_SOURCE dmaTriggerSource; DMA Trigger Source bool dmaTransferComplete; DMA Transfer Complete Flag void * sourcePort; Source Port Address uint32_t frameLineCount; Frame Line Count uint32_t frameLineSize; Frame Line Size void * frameLineAddress; Frame Line Address void * frameBufferAddress; Framebuffer Address DRV_CAMERA_OVM7690_RECT rect; Window Rectangle uint16_t bpp; Bits per pixel supported Description OVM7690 Camera Driver Instance Object This structure provides a definition of the OVM7690 Camera Driver instance object. Remarks These values are been updated into the DRV_CAMERA_OVM7690_Initialize function. DRV_CAMERA_OVM7690_RECT Structure OVM7690 Camera window rectangle coordinates. File drv_camera_ovm7690.h C typedef struct { uint32_t left; uint32_t top; uint32_t right; uint32_t bottom; Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 98 } DRV_CAMERA_OVM7690_RECT; Members Members Description uint32_t left; OVM7690 Camera Window left coordinate uint32_t top; OVM7690 Camera Window top coordinate uint32_t right; OVM7690 Camera Window right coordinate uint32_t bottom; OVM7690 Camera Window bottom coordinate Description OVM7690 Camera Window Rect This structure defines window rectangle co-ordinates as left, right, top, and bottom. Remarks These values should be passed into the DRV_CAMERA_OVM7690_FrameRectSet function. DRV_CAMERA_OVM7690_REG12_OP_FORMAT Enumeration Lists OVM7690 Camera device register addresses. File drv_camera_ovm7690.h C typedef enum { DRV_CAMERA_OVM7690_REG12_OP_FORMAT_RAW_2 } DRV_CAMERA_OVM7690_REG12_OP_FORMAT; Members Members Description DRV_CAMERA_OVM7690_REG12_OP_FORMAT_RAW_2 Bayer Raw Format Description OVM7690 Camera Device Register Addresses. This enumeration defines the list of device register addresses. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_CAMERA_OVM7690_RegisterSet function. Refer to the specific device data sheet for more information. DRV_CAMERA_OVM7690_INDEX_0 Macro OVM7690 driver index definitions. File drv_camera_ovm7690.h C #define DRV_CAMERA_OVM7690_INDEX_0 0 Description OVM7690 Camera Driver Module Index These constants provide OVM7690 Camera Driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_CAMERA_OVM7690_Initialize and DRV_CAMERA_OVM7690_Open routines to identify the driver instance in use. Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 99 DRV_CAMERA_OVM7690_INDEX_1 Macro File drv_camera_ovm7690.h C #define DRV_CAMERA_OVM7690_INDEX_1 1 Description This is macro DRV_CAMERA_OVM7690_INDEX_1. DRV_CAMERA_OVM7690_REG12_SOFT_RESET Macro OVM7690 Camera Driver Register 0x12 Soft reset flag. File drv_camera_ovm7690.h C #define DRV_CAMERA_OVM7690_REG12_SOFT_RESET Description OVM7690 Camera Driver Soft reset flag. This macro provides a definition of the OVM7690 Camera Register 0x12 Soft reset flag. Remarks These constants should be used in place of hard-coded numeric literals. DRV_CAMERA_OVM7690_SCCB_READ_ID Macro OVM7690 Camera SCCB Interface device Read Slave ID. File drv_camera_ovm7690.h C #define DRV_CAMERA_OVM7690_SCCB_READ_ID Description OVM7690 Camera Driver SCCB Read ID This macro provides a definition of the OVM7690 Camera SCCB Interface device Read Slave ID. Remarks These constants should be used in place of hard-coded numeric literals. DRV_CAMERA_OVM7690_SCCB_WRITE_ID Macro OVM7690 Camera SCCB Interface device Write Slave ID. File drv_camera_ovm7690.h C #define DRV_CAMERA_OVM7690_SCCB_WRITE_ID Description OVM7690 Camera Driver SCCB Write ID This macro provides a definition of the OVM7690 Camera SCCB Interface device Write Slave ID. Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 100 Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_CAMERA_OVM7690_RegisterSet function to identify the OVM7690 Camera SCCB Interface device Write Slave ID. Files Files Name Description drv_camera_ovm7690.h OVM7690 Camera Driver local data structures. drv_ovm7690_config_template.h OVM7690 Device Driver configuration template. Description drv_camera_ovm7690.h OVM7690 Camera Driver local data structures. Enumerations Name Description DRV_CAMERA_OVM7690_CLIENT_STATUS Identifies OVM7690 Camera possible client status. DRV_CAMERA_OVM7690_ERROR Identifies OVM7690 Camera possible errors. DRV_CAMERA_OVM7690_REG12_OP_FORMAT Lists OVM7690 Camera device register addresses. Functions Name Description _DRV_CAMERA_OVM7690_delayMS This is function _DRV_CAMERA_OVM7690_delayMS. _DRV_CAMERA_OVM7690_DMAEventHandler This is function _DRV_CAMERA_OVM7690_DMAEventHandler. _DRV_CAMERA_OVM7690_HardwareSetup This is function _DRV_CAMERA_OVM7690_HardwareSetup. DRV_CAMERA_OVM7690_Close Closes an opened instance of the OVM7690 Camera Driver. DRV_CAMERA_OVM7690_Deinitialize Deinitializes the specified instance of the OVM7690 Camera Driver module. DRV_CAMERA_OVM7690_FrameBufferAddressSet Sets the framebuffer address. DRV_CAMERA_OVM7690_FrameRectSet Sets the frame rectangle set. DRV_CAMERA_OVM7690_HsyncEventHandler Horizontal synchronization event handler. DRV_CAMERA_OVM7690_Initialize Initializes the OVM7690 Camera instance for the specified driver index. DRV_CAMERA_OVM7690_Open Opens the specified OVM7690 Camera Driver instance and returns a handle to it. DRV_CAMERA_OVM7690_RegisterSet Sets the camera OVM7690 configuration registers. DRV_CAMERA_OVM7690_Start Starts camera rendering to the display. DRV_CAMERA_OVM7690_Stop Stops rendering the camera Pixel data. DRV_CAMERA_OVM7690_Tasks Maintains the OVM7690 state machine. DRV_CAMERA_OVM7690_VsyncEventHandler Vertical synchronization event handler . Macros Name Description DRV_CAMERA_OVM7690_INDEX_0 OVM7690 driver index definitions. DRV_CAMERA_OVM7690_INDEX_1 This is macro DRV_CAMERA_OVM7690_INDEX_1. DRV_CAMERA_OVM7690_REG12_SOFT_RESET OVM7690 Camera Driver Register 0x12 Soft reset flag. DRV_CAMERA_OVM7690_SCCB_READ_ID OVM7690 Camera SCCB Interface device Read Slave ID. DRV_CAMERA_OVM7690_SCCB_WRITE_ID OVM7690 Camera SCCB Interface device Write Slave ID. Structures Name Description DRV_CAMERA_OVM7690_CLIENT_OBJ OVM7690 Camera Driver client object. DRV_CAMERA_OVM7690_INIT OVM7690 Camera Driver initialization parameters. DRV_CAMERA_OVM7690_OBJ OVM7690 Camera Driver instance object. Volume V: MPLAB Harmony Framework Driver Libraries Help Camera Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 101 DRV_CAMERA_OVM7690_RECT OVM7690 Camera window rectangle coordinates. Description OVM7690 Camera Driver Local Data Structures This header file provides the local data structures for the OVM7690 Camera Driver Library. File Name drv_camera_ovm7690.h Company Microchip Technology Inc. drv_ovm7690_config_template.h OVM7690 Device Driver configuration template. Macros Name Description DRV_OVM7690_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. Description OVM7690 Device Driver Configuration Template This header file contains the build-time configuration selections for the OVM7690 device driver. This is the template file which give all possible configurations that can be made. This file should not be included in any project. File Name drv_ovm7690_config_template.h Company Microchip Technology Inc. CAN Driver Library This section describes the CAN Driver Library. Introduction The CAN Static Driver provides a high-level interface to manage the CAN module on the Microchip family of microcontrollers. Description Through MHC, this driver provides an API to initialize the CAN module, as well as the baud rate. The API also allows simple transmit and receive functionality. Library Interface Function(s) Name Description DRV_CAN_ChannelMessageReceive Receives a message on a channel for the specified driver index. Implementation: Static DRV_CAN_ChannelMessageTransmit Transmits a message on a channel for the specified driver index. Implementation: Static DRV_CAN_Close Closes the CAN instance for the specified driver index. Implementation: Static DRV_CAN_Deinitialize Deinitializes the DRV_CAN_Initialize instance that has been called for the specified driver index. Implementation: Static DRV_CAN_Initialize Initializes the CAN instance for the specified driver index. Implementation: Static Volume V: MPLAB Harmony Framework Driver Libraries Help CAN Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 102 DRV_CAN_Open Opens the CAN instance for the specified driver index. Implementation: Static Description This section describes the Application Programming Interface (API) functions of the CAN Driver Library. Function(s) DRV_CAN_ChannelMessageReceive Function Receives a message on a channel for the specified driver index. Implementation: Static File help_drv_can.h C bool DRV_CAN_ChannelMessageReceive(CAN_CHANNEL channelNum, int address, uint8_t DLC, uint8_t* message); Returns • true - When a message has been received • false - When a message has not been received Description This routine receives data into a buffer from the CAN bus according to the channel, address, and data length given. Remarks This routine receives a standard or extended messages based upon the CAN Driver setup. Preconditions DRV_CAN_Initialize has been called. Parameters Parameters Description CAN_CHANNEL channelNum CAN channel to use int address CAN address to receive on uint8_t DLC Data Length Code of Message uint8_t* message Pointer to put the message data to receive Function bool DRV_CAN_ChannelMessageReceive(CAN_CHANNEL channelNum, int address, uint8_t DLC, uint8_t* message); DRV_CAN_ChannelMessageTransmit Function Transmits a message on a channel for the specified driver index. Implementation: Static File help_drv_can.h C bool DRV_CAN_ChannelMessageTransmit(CAN_CHANNEL channelNum, int address, uint8_t DLC, uint8_t* message); Returns Boolean "true" when a message has been transmitted. Description This routine transmits a data buffer on the CAN bus according to the channel, address, and data length given. Volume V: MPLAB Harmony Framework Driver Libraries Help CAN Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 103 Remarks This routine receives a standard or extended messages based upon the CAN Driver setup. Preconditions DRV_CAN_Initialize has been called. Parameters Parameters Description CAN_CHANNEL channelNum CAN channel to use int address CAN address to transmit on uint8_t DLC Data Length Code of Message uint8_t* message Pointer to the message data to send Function bool DRV_CAN_ChannelMessageTransmit(CAN_CHANNEL channelNum, int address, uint8_t DLC, uint8_t* message); DRV_CAN_Close Function Closes the CAN instance for the specified driver index. Implementation: Static File help_drv_can.h C void DRV_CAN_Close(); Returns None. Description This routine closes the CAN driver instance for the specified driver instance, making it ready for clients to use it. Preconditions DRV_CAN_Initialize has been called. Function void DRV_CAN_Close(void) DRV_CAN_Deinitialize Function Deinitializes the DRV_CAN_Initialize instance that has been called for the specified driver index. Implementation: Static File help_drv_can.h C void DRV_CAN_Deinitialize(); Returns None. Description This routine deinitializes the CAN Driver instance for the specified driver instance, making it ready for clients to use it. The initialization routine is specified by the MHC parameters. Preconditions None. Volume V: MPLAB Harmony Framework Driver Libraries Help CAN Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 104 Function void DRV_CAN_Deinitialize(void) DRV_CAN_Initialize Function Initializes the CAN instance for the specified driver index. Implementation: Static File help_drv_can.h C void DRV_CAN_Initialize(); Returns None. Description This routine initializes the CAN Driver instance for the specified driver instance, making it ready for clients to use it. The initialization routine is specified by the MHC parameters. Remarks This routine must be called before any other CAN routine is called. This routine should only be called once during system initialization. Preconditions None. Function void DRV_CAN_Initialize(void) DRV_CAN_Open Function Opens the CAN instance for the specified driver index. Implementation: Static File help_drv_can.h C void DRV_CAN_Open(); Returns None. Description This routine opens the CAN Driver instance for the specified driver instance, making it ready for clients to use it. Preconditions DRV_CAN_Initialize has been called. Function void DRV_CAN_Open(void) Codec Driver Libraries This section describes the Codec Driver Libraries available in MPLAB Harmony. AK4384 Codec Driver Library This topic describes the AK4384 Codec Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 105 Introduction This library provides an interface to manage the AK4384 106 dB 192 kHz 24-Bit DAC that is serially interfaced to a Microchip microcontroller for providing Audio Solutions. Description The AK4384 module is 24-bit Audio DAC from Asahi Kasei Microdevices Corporation. The AK4384 can be interfaced to Microchip microcontrollers through SPI and I2S serial interfaces. SPI interface is used for control command transfer. The I2S interface is used for Audio data output. A typical interface of AK4384 to a Microchip PIC32 device is provided in the following diagram: Features The AK4384 Codec Driver supports the following features: • Sampling Rate Ranging from 8 kHz to 192 kHz • 128 times Oversampling (Normal Speed mode) • 64 times Oversampling (Double Speed mode) • 32 times Oversampling (Quad Speed mode) • Digital de-emphasis for 32k, 44.1k and 48 kHz sampling • Soft mute • Digital Attenuator (Linear 256 steps) • I/F format: • 24-bit MSB justified • 24/20/16-bit LSB justified • I2S • Master clock: • 256 fs, 384 fs, 512 fs, 768 fs, or 1152 fs (Normal Speed mode) • 128 fs, 192 fs, 256 fs, or 384 fs (Double Speed mode) • 128 fs or 192 fs (Quad Speed mode) Using the Library This topic describes the basic architecture of the AK4384 Codec Driver Library and provides information and examples on its use. Description Interface Header File: drv_ak4384.h The interface to the AK4384 Codec Driver library is defined in the drv_ak4384.h header file. Any C language source (.c) file that uses the AK4384 Codec Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the AK4384 Codec Driver Library 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. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 106 Description The abstraction model shown in the following diagram depicts how the AK4384 Codec Driver is positioned in the MPLAB Harmony framework. The AK4384 Codec Driver uses the SPI and I2S drivers for control and audio data transfers to the AK4384 module. AK4384 Driver Abstraction Model Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The AK4384 Codec Driver Library provides an API interface to transfer control commands and digital audio data to the serially interfaced AK4384 DAC module. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the AK4384 Codec Driver Library. Library Interface Section Description System Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Client Setup Functions Provides open and close functions. Codec Specific Functions Provides functions that are Codec-specific. Data Transfer Functions Provides data transfer functions. Other Functions Provides driver specific miscellaneous functions such as sampling rate setting, control command functions, etc. Data Types and Constants These data types and constants are required while interacting and setting up the AK4384 Codec Driver Library. How the Library Works The library provides interfaces to support: • System Functionality Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 107 • Client Functionality System Access This topic provides information on system initialization, implementations, and provides a system access code example. Description System Initialization The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization, each instance of the AK4384 module would be initialized with the following configuration settings (either passed dynamically at run time using DRV_AK4384_INIT or by using Initialization Overrides) that are supported by the specific AK4384 device hardware: • Device requested power state: one of the System Module Power States. For specific details please refer to Data Types and Constants in the Library Interface section. • SPI driver module index. The module index should be same as the one used in initializing the SPI Driver. • I2S driver module index. The module index should be same as the one used in initializing the I2S Driver. • Sampling rate • Master clock detection mode • Power down pin port initialization • Queue size for the audio data transmit buffer The DRV_AK4384_Initialize API returns an object handle of the type SYS_MODULE_OBJ. The object handle returned by the Initialize interface would be used by the other system interfaces such as DRV_ AK4384_Deinitialize, DRV_ AK4384_Status and DRV_I2S_Tasks. Implementations The AK4384 Codec Driver can have the following implementations: Implementation Description MPLAB Harmony Components Implementation 1 Dedicated hardware for control (SPI) and data (I2S) interface. Standard MPLAB Harmony drivers for SPI and I2S interfaces. Implementation 2 Dedicated hardware for data (I2S) interface. Ports pins for control interface. Standard MPLAB Harmony drivers for I2S interface. Virtual MPLAB Harmony drivers for SPI interface. Implementation 3 Dedicated hardware for data (I2S) interface. Ports pins for control. Standard MPLAB Harmony drivers for I2S interface. An internal bit-banged implementation of control interface in the AK4384 Codec Driver. If Implementation 3 is in use, while initializing fields of DRV_AK4384_INIT structure, the SPI Driver module index initialization is redundant. The user can pass a dummy value. For Implementation 3, the user has to additionally initialize parameters to support bit-banged control interface implementation. These additional parameters can be passed by assigning values to the respective macros in system_config.h. Example: DRV_AK4384_INIT drvak4384Init = { .moduleInit.value = SYS_MODULE_POWER_RUN_FULL, .volume = 120, .mclkMode = DRV_AK4384_MCLK_MODE_MANUAL, .queueSizeTransmit = 2, }; /* The SPI module index should be same as the one used in initializing the SPI driver. The SPI module index initialization is redundant if Implementation 3 is in use. */ drvak4384Init.spiDriverModuleIndex = DRV_SPI_INDEX_0; /* The I2S module index should be same as the one used in initializing the I2S driver. */ drvak4384Init.i2sDriverModuleIndex = DRV_I2S_INDEX_0; ak4384DevObject = DRV_AK4384_Initialize(DRV_AK4384_INDEX_0, (SYS_MODULE_INIT *) &drvak4384Init); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 108 if (SYS_MODULE_OBJ_INVALID == ak4384DevObject) { // Handle error } Task Routine The DRV_AK4384_Tasks will be called from the System Task Service. Client Access This topic describes client access and includes a code example. Description For the application to start using an instance of the module, it must call the DRV_AK4384_Open function. The DRV_AK4384_Open provides a driver handle to the AK4384 Codec Driver instance for operations. If the driver is deinitialized using the function DRV_AK4384_Deinitialize, the application must call the DRV_AK4384_Open function again to set up the instance of the driver. For the various options available for IO_INTENT, please refer to Data Types and Constants in the Library Interface section. Note: It is necessary to check the status of driver initialization before opening a driver instance. The status of the AK4384 Codec Driver can be known by calling DRV_AK4384_Status. Example: DRV_HANDLE handle; SYS_STATUS ak4384Status; ak4384Status = DRV_AK4384_Status(sysObjects.ak4384DevObject); if (SYS_STATUS_READY == ak4384Status) { // The driver can now be opened. appData.ak4384Client.handle = DRV_AK4384_Open (DRV_AK4384_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if(appData.ak4384Client.handle != DRV_HANDLE_INVALID) { appData.state = APP_STATE_AK4384_SET_BUFFER_HANDLER; } else { SYS_DEBUG(0, "Find out what's wrong \r\n"); } } else { /* AK4384 Driver Is not ready */ ; } Client Operations This topic describes client operations and provides a code example. Description Client operations provide the API interface for control command and audio data transfer to the AK4384 Codec. The following AK4384 Codec specific control command functions are provided: Notes: 1. The calling and execution of the following functions does not guarantee that the function (and its associated Codec command) has been set in the Codec peer interfaced through the SPI. It just means that the submission of the command has started over the SPI. 2. Regarding Note 1, the user should not call the following functions consecutively, which could result in unexpected behavior. If needed, the user should confirm the completion status of a function before calling any of the other functions. 3. To know the completion status of the following functions, users can register a command event callback handler by calling the function ‘DRV_AK4384_CommandEventHandlerSet’. The callback handler will be called when the last submitted command (submitted by calling one of the following functions) has completed. • DRV_AK4384_SamplingRateSet • DRV_AK4384_SamplingRateGet • DRV_AK4384_VolumeSet Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 109 • DRV_AK4384_VolumeGet • DRV_AK4384_MuteOn • DRV_AK4384_MuteOff • DRV_AK4384_ZeroDetectEnable • DRV_AK4384_ZeroDetectDisable • DRV_AK4384_ZeroDetectModeSet • DRV_AK4384_ZeroDetectInvertEnable • DRV_AK4384_ZeroDetectInvertDisable • DRV_AK4384_ChannelOutputInvertEnable • DRV_AK4384_ChannelOutputInvertDisable • DRV_AK4384_SlowRollOffFilterEnable • DRV_AK4384_SlowRollOffFilterDisable • DRV_AK4384_DeEmphasisFilterSet These functions schedule a non-blocking control command transfer operation. These functions submit the control command request to the AK4384 Codec. A notification for the submitted requests can be received by registering a command callback event with the driver. The driver notifies by calling the callback on successfully transmitting the command to the AK4384 Codec module. The function DRV_AK4384_BufferAddWrite is a buffered data operation functions. This function schedules non-blocking audio data transfer operation. The function adds the request to the hardware instance queues and returns a buffer handle. The requesting client also registers a callback event with the driver. The driver notifies the client with DRV_AK4384_BUFFER_EVENT_COMPLETE, DRV_AK4384_BUFFER_EVENT_ERROR, or DRV_AK4384_BUFFER_EVENT_ABORT events. The submitted control commands and audio buffer add requests are processed under DRV_AK4384_Tasks function. This function is called from the SYS_Tasks routine. The following diagram illustrates the control commands and audio buffered data operations. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 110 Note: It is not necessary to close and reopen the client between multiple transfers. An application using the buffered functionality needs to perform the following steps: 1. The system should have completed necessary setup and initializations. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 111 2. The I2S Driver object should have been initialized by calling DRV_I2S_Initialize. 3. The SPI Driver object should have been initialized by calling DRV_SPI_Initialize. 4. The AK4384 Codec Driver object should be initialized by calling DRV_AK4384_Initialize. 5. The necessary sampling rate value should be set up by calling DRV_AK4384_ SamplingRateSet. 6. Register buffer event handler for the client handle by calling DRV_AK4384_BufferEventHandlerSet. 7. Register command event handler for the client handle by calling DRV_AK4384_CommandEventHandlerSet. 8. Submit a command by calling specific command API. 9. Add a buffer to initiate the data transfer by calling DRV_AK4384_BufferAddWrite. 10. The submitted command and Audio data processing happens b calling DRV_AK4384_Tasks from SYS_Tasks. 11. Repeat steps 9 through 10 to handle multiple buffer transmission and reception. 12. When the client is done, it can use DRV_AK4384_Close to close the client handle. Example: typedef enum { APP_STATE_AK4384_OPEN, APP_STATE_AK4384_SET_COMMAND_HANDLER, APP_STATE_AK4384_SET_BUFFER_HANDLER, APP_STATE_AK4384_SET_SAMPLING_RATE_COMMAND, APP_STATE_AK4384_ADD_BUFFER, APP_STATE_AK4384_WAIT_FOR_BUFFER_COMPLETE, APP_STATE_AK4384_BUFFER_COMPLETE } APP_STATES; typedef struct { DRV_HANDLE handle; DRV_AK4384_BUFFER_HANDLE writeBufHandle; DRV_AK4384_BUFFER_EVENT_HANDLER bufferHandler; DRV_AK4384_COMMAND_EVENT_HANDLER commandHandler; uintptr_t context; uint8_t *txbufferObject; size_t bufferSize; } APP_AK4384_CLIENT; typedef struct { /* Application's current state*/ APP_STATES state; /* USART client handle */ APP_AK4384_CLIENT ak4384Client; } APP_DATA; APP_DATA appData; SYS_MODULE_OBJ ak4384DevObject; DRV_AK4384_INIT drvak4384Init = { .moduleInit.value = SYS_MODULE_POWER_RUN_FULL, .volume = 120, .mclkMode = DRV_AK4384_MCLK_MODE_MANUAL, .queueSizeTransmit = 2, }; void SYS_Initialize(void * data) { /* The SPI module index should be same as the one used in initializing the SPI driver. The SPI module index initialization is redundant if Implementation 3 (Described in System Access) is in use. */ drvak4384Init.spiDriverModuleIndex = DRV_SPI_INDEX_0; /* The I2S module index should be same as the one used in initializing the I2S driver. */ drvak4384Init.i2sDriverModuleIndex = DRV_I2S_INDEX_0; Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 112 ak4384DevObject = DRV_AK4384_Initialize(DRV_AK4384_INDEX_0, (SYS_MODULE_INIT *) & drvak4384Init); if (SYS_MODULE_OBJ_INVALID == ak4384DevObject) { // Handle error } } void APP_Tasks (void ) { switch(appData.state) { /* Open the ak4384 client and get an Handle */ case APP_STATE_AK4384_OPEN: { SYS_STATUS ak4384Status; ak4384Status = DRV_AK4384_Status(sysObjects.ak4384DevObject); if (SYS_STATUS_READY == ak4384Status) { // This means the driver can now be opened. appData.ak4384Client.handle = DRV_AK4384_Open(DRV_AK4384_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if(appData.ak4384Client.handle != DRV_HANDLE_INVALID) { appData.state = APP_STATE_AK4384_SET_COMMAND_HANDLER; } else { SYS_DEBUG(0, "Find out what is wrong \r\n"); } } else { /* Wait for AK4384 to Initialize */ ; } } break; /* Register a command event handler */ case APP_STATE_AK4384_SET_COMMAND_HANDLER: { DRV_AK4384_CommandEventHandlerSet(appData.ak4384Client.handle, appData.ak4384Client.commandHandler, appData.ak4384Client.context); appData.state = APP_STATE_AK4384_SET_BUFFER_HANDLER; } break; /* Register a buffer event handler */ case APP_STATE_AK4384_SET_BUFFER_HANDLER: { DRV_AK4384_BufferEventHandlerSet(appData.ak4384Client.handle, appData.ak4384Client.bufferHandler, appData.ak4384Client.context); appData.state = APP_STATE_AK4384_SET_SAMPLING_RATE_COMMAND; } break; /* Submit a set sampling rate command */ case APP_STATE_AK4384_SET_SAMPLING_RATE_COMMAND: { DRV_AK4384_SamplingRateSet(appData.ak4384Client.handle,48000); appData.state = APP_STATE_AK4384_ADD_BUFFER; } break; /* Add the Audio buffer to be transmitted */ case APP_STATE_AK4384_ADD_BUFFER: { Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 113 DRV_AK4384_BufferAddWrite(appData.ak4384Client.handle, &appData.ak4384Client.writeBufHandle, appData.ak4384Client.txbufferObject, appData.ak4384Client.bufferSize); if(appData.ak4384Client.writeBufHandle != DRV_AK4384_BUFFER_HANDLE_INVALID) { appData.state = APP_STATE_AK4384_WAIT_FOR_BUFFER_COMPLETE; } else { SYS_DEBUG(0, "Find out what is wrong \r\n"); } } break; /* Audio Buffer transmission under process */ case APP_STATE_AK4384_WAIT_FOR_BUFFER_COMPLETE: { } break; /* Audio Buffer transmission completed */ case APP_STATE_AK4384_BUFFER_COMPLETE: { /* Add another buffer */ appData.state = APP_STATE_AK4384_ADD_BUFFER; } break; default: { } break; } } void APP_AK4384CommandEventHandler(uintptr_t context ) { // Last submitted command successful. Take action as needed. } void APP_AK4384BufferEventHandler(DRV_AK4384_BUFFER_EVENT event, DRV_AK4384_BUFFER_HANDLE handle, uintptr_t context ) { switch(event) { case DRV_AK4384_BUFFER_EVENT_COMPLETE: { // Can set appData.state = APP_STATE_AK4384_BUFFER_COMPLETE; // Take Action as needed } break; case DRV_AK4384_BUFFER_EVENT_ERROR: { // Take Action as needed } break; case DRV_AK4384_BUFFER_EVENT_ABORT: { // Take Action as needed } break; } } Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 114 void SYS_Tasks(void) { DRV_AK4384_Tasks(ak4384DevObject); APP_Tasks(); } Configuring the Library Macros Name Description DRV_AK4384_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_AK4384_CONTROL_CLOCK Sets up clock frequency for the control interface (SPI) DRV_AK4384_INPUT_REFCLOCK Identifies the input REFCLOCK source to generate the MCLK to codec. DRV_AK4384_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_AK4384_TIMER_DRIVER_MODULE_INDEX Identifies the Timer Module Index for custom virtual SPI driver implementation. DRV_AK4384_TIMER_PERIOD Identifies the period for the bit bang timer. DRV_AK4384_BCLK_BIT_CLK_DIVISOR Sets up the BCLK to LRCK Ratio to Generate Audio Stream for 32, 44.1, and 48K sampling frequency DRV_AK4384_MCLK_SAMPLE_FREQ_MULTPLIER Sets up the MCLK to LRCK Ratio to Generate Audio Stream for 32, 44.1 and 48K sampling frequency Description The configuration of the AK4384 Codec Driver is based on the file system_config.h. This header file contains the configuration selection for the AK4384 Codec Driver. Based on the selections made, the driver may support the selected features. These configuration settings will apply to all instances of the AK4384 Codec Driver. This header can be placed anywhere, 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. DRV_AK4384_CLIENTS_NUMBER Macro Sets up the maximum number of clients that can be connected to any hardware instance. File drv_ak4384_config_template.h C #define DRV_AK4384_CLIENTS_NUMBER DRV_AK4384_INSTANCES_NUMBER Description AK4384 Client Count Configuration Sets up the maximum number of clients that can be connected to any hardware instance. Typically only one client could be connected to one hardware instance. This value represents the total number of clients to be supported across all hardware instances. Therefore, if there are five AK4384 hardware interfaces, this number will be 5. Remarks None. DRV_AK4384_CONTROL_CLOCK Macro Sets up clock frequency for the control interface (SPI) File drv_ak4384_config_template.h C #define DRV_AK4384_CONTROL_CLOCK Description AK4384 Control Interface Clock Speed configuration Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 115 Sets up clock frequency for the control interface (SPI). The maximum value supported is 5MHZ. Remarks 1. This Macro is useful only when a hardware SPI module is not available(used) or a virtual SPI driver is not available(used) for the control interface to the AK4384 CODEC. 2. This constant needs to defined only for a bit banged implementation of control interface with in the driver. DRV_AK4384_INPUT_REFCLOCK Macro Identifies the input REFCLOCK source to generate the MCLK to codec. File drv_ak4384_config_template.h C #define DRV_AK4384_INPUT_REFCLOCK Description AK4384 Input reference clock Identifies the input REFCLOCK source to generate the MCLK to codec. Remarks None. DRV_AK4384_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported File drv_ak4384_config_template.h C #define DRV_AK4384_INSTANCES_NUMBER Description AK4384 driver objects configuration Sets up the maximum number of hardware instances that can be supported. It is recommended that this number be set exactly equal to the number of AK4384 CODEC modules that are needed by the application. Hardware Instance support consumes RAM memory space. If this macro is not defined, then the driver will be built statically. Remarks None. DRV_AK4384_TIMER_DRIVER_MODULE_INDEX Macro Identifies the Timer Module Index for custom virtual SPI driver implementation. File drv_ak4384_config_template.h C #define DRV_AK4384_TIMER_DRIVER_MODULE_INDEX Description AK4384 Timer Module Index Identifies the Timer Module Index for custom virtual SPI driver implementation. The AK4384 uses SPI protocol for control interface. The Timer Module Index is needed by AK4384 driver to implement a virtual SPI driver for control command exchange with the AK4384 CODEC. Remarks 1. This Macro is useful only when a hardware SPI module is not available(used) or a virtual SPI driver is not available(used) for the control interface to the AK4384 CODEC. 2. This constant needs to defined only for a bit banged implementation of control interface with in the driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 116 DRV_AK4384_TIMER_PERIOD Macro Identifies the period for the bit bang timer. File drv_ak4384_config_template.h C #define DRV_AK4384_TIMER_PERIOD Description AK4384 Timer Period Identifies the period for the bit bang timer after which the timer interrupt should occur. The value assigned should align with the expected control interface clock defined by AK4384_CONTROL_CLOCK. Remarks 1. This Macro is useful only when a hardware SPI module is not available(used) or a virtual SPI driver is not available(used) for the control interface to the AK4384 CODEC. 2. This constant needs to defined only for a bit banged implementation of control interface with in the driver. DRV_AK4384_BCLK_BIT_CLK_DIVISOR Macro Sets up the BCLK to LRCK Ratio to Generate Audio Stream for 32, 44.1, and 48K sampling frequency File drv_ak4384_config_template.h C #define DRV_AK4384_BCLK_BIT_CLK_DIVISOR Description AK4384 BCLK to LRCK Ratio to Generate Audio Stream Sets up the BCLK to LRCK Ratio to Generate Audio Stream for 32, 44.1 and 48K I2S sampling frequency Following BCLK to LRCK ratios are supported 16bit LSB Justified >=32fs 20bit LSB Justified >=40fs 24bit MSB Justified >=48fs 24bit I2S Compatible >=48fs 24bit LSB Justified >=48fs Typical values for the divisor are 1,2,4 and 8 Remarks None. DRV_AK4384_MCLK_SAMPLE_FREQ_MULTPLIER Macro Sets up the MCLK to LRCK Ratio to Generate Audio Stream for 32, 44.1 and 48K sampling frequency File drv_ak4384_config_template.h C #define DRV_AK4384_MCLK_SAMPLE_FREQ_MULTPLIER Description AK4384 MCLK to LRCK Ratio to Generate Audio Stream Sets up the MCLK to LRCK Ratio to Generate Audio Stream for 32, 44.1, and 48K I2S sampling frequency Supported MCLK to LRCK Ratios are as below 256fs, 384fs, 512fs, 768fs or 1152fs [Normal Speed Mode(8kHz~48kHz)] 128fs, 192fs, 256fs or 384fs [Double Speed Mode(60kHz~96kHz)] 128fs, 192fs [Quad Speed Mode(120kHz~192kHz)] Remarks None Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 117 Configuring the MHC Provides examples on how to configure the MPLAB Harmony Configurator (MHC) for a specific driver. Description The following three figures show examples of MHC configurations for the AK4384 Codec Driver, I2S Driver, and the Timer Driver. Figure 1: AK4384 Codec Driver MHC Configuration Figure 2: I2S Driver MHC Configuration Figure 3: Timer Driver MHC Configuration Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 118 Building the Library This section lists the files that are available in the AK4384 Codec Driver Library. Description This section list the files that are available in the /src folder of the AK4384 Codec 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. 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 /framework/driver/codec/ak4384. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_ak4384.h Header file that exports the driver API. 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 /src/dynamic/drv_ak4384_bit_banged_control_interface.c This file contains implementation of the AK4384 Codec Driver with a custom bit-banged implementation for control interface driver. 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 /src/dynamic/drv_ak4384_virtual_control_interface.c This file contains implementation of the AK4384 Codec Driver with a virtual SPI driver as control interface driver. Note: This file is currently unsupported. /src/dynamic/drv_ak4384.c This file contains the core implementation of the AK4384 Codec Driver Note: This file currently unsupported. Module Dependencies The AK4384 Driver Library depends on the following modules: • I2S Driver Library • SPI Driver Library Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 119 • Timer Driver Library Library Interface a) System Interaction Functions Name Description DRV_AK4384_Initialize Initializes hardware and data for the instance of the AK4384 DAC module. Implementation: Dynamic DRV_AK4384_Deinitialize Deinitializes the specified instance of the AK4384 driver module. Implementation: Dynamic DRV_AK4384_Status Gets the current status of the AK4384 driver module. Implementation: Dynamic DRV_AK4384_Tasks Maintains the driver's control and data interface state machine. Implementation: Dynamic DRV_AK4384_SetAudioCommunicationMode This function provides a run time audio format configuration b) Client Setup Functions Name Description DRV_AK4384_Open Opens the specified AK4384 driver instance and returns a handle to it. Implementation: Dynamic DRV_AK4384_Close Closes an opened-instance of the AK4384 driver. Implementation: Dynamic c) Codec Specific Functions Name Description DRV_AK4384_ChannelOutputInvertDisable Disables output polarity of the selected Channel. Implementation: Dynamic DRV_AK4384_ChannelOutputInvertEnable Enables output polarity of the selected channel. Implementation: Dynamic DRV_AK4384_DeEmphasisFilterSet Allows specifies enabling of digital de-emphasis filter. Implementation: Dynamic DRV_AK4384_MuteOff Disables AK4384 output for soft mute. Implementation: Dynamic DRV_AK4384_MuteOn Allows AK4384 output for soft mute on. Implementation: Dynamic DRV_AK4384_SamplingRateGet This function gets the sampling rate set on the DAC AK4384. Implementation: Dynamic DRV_AK4384_SamplingRateSet This function sets the sampling rate of the media stream. Implementation: Dynamic DRV_AK4384_SlowRollOffFilterDisable Disables Slow Roll-off filter function. Implementation: Dynamic DRV_AK4384_SlowRollOffFilterEnable Enables Slow Roll-off filter function. Implementation: Dynamic DRV_AK4384_VolumeGet This function gets the volume for AK4384 Codec. Implementation: Dynamic DRV_AK4384_VolumeSet This function sets the volume for AK4384 Codec. Implementation: Dynamic DRV_AK4384_ZeroDetectDisable Disables AK4384 channel-independent zeros detect function. Implementation: Dynamic DRV_AK4384_ZeroDetectEnable Enables AK4384 channel-independent zeros detect function. Implementation: Dynamic DRV_AK4384_ZeroDetectInvertDisable Disables inversion of polarity for zero detect function. Implementation: Dynamic DRV_AK4384_ZeroDetectInvertEnable Enables inversion of polarity for zero detect function. Implementation: Dynamic DRV_AK4384_ZeroDetectModeSet Sets mode of AK4384 channel-independent zeros detect function. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 120 d) Data Transfer Functions Name Description DRV_AK4384_BufferAddWrite Schedule a non-blocking driver write operation. Implementation: Dynamic DRV_AK4384_BufferEventHandlerSet This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. Implementation: Dynamic DRV_AK4384_BufferCombinedQueueSizeGet This function returns the number of bytes queued (to be processed) in the buffer queue. Implementation: Dynamic DRV_AK4384_BufferQueueFlush This function flushes off the buffers associated with the client object. Implementation: Dynamic DRV_AK4384_BufferProcessedSizeGet This function returns number of bytes that have been processed for the specified buffer. Implementation: Dynamic e) Other Functions Name Description DRV_AK4384_CommandEventHandlerSet This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. Implementation: Dynamic DRV_AK4384_VersionGet Returns the version of the AK4384 driver. Implementation: Dynamic DRV_AK4384_VersionStrGet Returns the version of AK4384 driver in string format. Implementation: Dynamic f) Data Types and Constants Name Description DRV_AK4384_AUDIO_DATA_FORMAT Identifies the Serial Audio data interface format. DRV_AK4384_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_AK4384_BUFFER_EVENT_HANDLER Pointer to a AK4384 Driver Buffer Event handler function. DRV_AK4384_BUFFER_HANDLE Handle identifying a write buffer passed to the driver. DRV_AK4384_CHANNEL Identifies Left/Right Audio channel DRV_AK4384_COMMAND_EVENT_HANDLER Pointer to a AK4384 Driver Command Event Handler Function DRV_AK4384_DEEMPHASIS_FILTER Identifies de-emphasis filter function. DRV_AK4384_INIT Defines the data required to initialize or reinitialize the AK4384 driver. DRV_AK4384_MCLK_MODE Identifies the mode of master clock to AK4384 DAC. DRV_AK4384_ZERO_DETECT_MODE Identifies Zero Detect Function mode DRV_AK4384_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_AK4384_COUNT Number of valid AK4384 driver indices. DRV_AK4384_INDEX_0 AK4384 driver index definitions. DRV_AK4384_INDEX_1 This is macro DRV_AK4384_INDEX_1. DRV_AK4384_INDEX_2 This is macro DRV_AK4384_INDEX_2. DRV_AK4384_INDEX_3 This is macro DRV_AK4384_INDEX_3. DRV_AK4384_INDEX_4 This is macro DRV_AK4384_INDEX_4. DRV_AK4384_INDEX_5 This is macro DRV_AK4384_INDEX_5. Description This section describes the API functions of the AK4384 Codec Driver library. Refer to each section for a detailed description. a) System Interaction Functions DRV_AK4384_Initialize Function Initializes hardware and data for the instance of the AK4384 DAC module. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 121 Implementation: Dynamic File drv_ak4384.h C SYS_MODULE_OBJ DRV_AK4384_Initialize(const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the AK4384 driver instance for the specified driver index, making it ready for clients to open and use it. The initialization data is specified by the 'init' parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. Remarks This routine must be called before any other AK4384 routine is called. This routine should only be called once during system initialization unless DRV_AK4384_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. Preconditions DRV_I2S_Initialize must be called before calling this function to initialize the data interface of this CODEC driver. DRV_SPI_Initialize must be called if SPI driver is used for handling the control interface of this CODEC driver. Example DRV_AK4384_INIT init; SYS_MODULE_OBJ objectHandle; init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.spiDriverModuleIndex = DRV_SPI_INDEX_0; // This will be ignored for a custom // control interface driver implementation init.i2sDriverModuleIndex = DRV_I2S_INDEX_0; init.mclkMode = DRV_AK4384_MCLK_MODE_MANUAL; init.audioDataFormat = DRV_AK4384_AUDIO_DATA_FORMAT_24BIT_I2S; init.powerDownPortChannel = PORT_CHANNEL_G; init.powerDownBitPosition = PORTS_BIT_POS_15; objectHandle = DRV_AK4384_Initialize(DRV_AK4384_0, (SYS_MODULE_INIT*)init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description drvIndex Identifier for the driver instance to be initialized init Pointer to the data structure containing any data necessary to initialize the hardware. This pointer may be null if no data is required and default initialization is to be used. Function SYS_MODULE_OBJ DRV_AK4384_Initialize ( const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT *const init ); DRV_AK4384_Deinitialize Function Deinitializes the specified instance of the AK4384 driver module. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 122 File drv_ak4384.h C void DRV_AK4384_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the AK4384 driver module, disabling its operation (and any hardware). Invalidates all the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This routine will NEVER block waiting for hardware. Preconditions Function DRV_AK4384_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_AK4384_Initialize SYS_STATUS status; DRV_AK4384_Deinitialize(object); status = DRV_AK4384_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from the DRV_AK4384_Initialize routine Function void DRV_AK4384_Deinitialize( SYS_MODULE_OBJ object) DRV_AK4384_Status Function Gets the current status of the AK4384 driver module. Implementation: Dynamic File drv_ak4384.h C SYS_STATUS DRV_AK4384_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_DEINITIALIZED - Indicates that the driver has been deinitialized SYS_STATUS_READY - Indicates that any previous module operation for the specified module has completed SYS_STATUS_BUSY - Indicates that a previous module operation for the specified module has not yet completed SYS_STATUS_ERROR - Indicates that the specified module is in an error state Description This routine provides the current status of the AK4384 driver module. Remarks A driver can opened only when its status is SYS_STATUS_READY. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 123 Preconditions Function DRV_AK4384_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_AK4384_Initialize SYS_STATUS ak4384Status; ak4384Status = DRV_AK4384_Status(object); if (SYS_STATUS_READY == ak4384Status) { // This means the driver can be opened using the // DRV_AK4384_Open function. } Parameters Parameters Description object Driver object handle, returned from the DRV_AK4384_Initialize routine Function SYS_STATUS DRV_AK4384_Status( SYS_MODULE_OBJ object) DRV_AK4384_Tasks Function Maintains the driver's control and data interface state machine. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_Tasks(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal control and data interface state machine and implement its control and data interface implementations. This function should be called from the SYS_Tasks function. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks). Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_AK4384_Initialize while (true) { DRV_AK4384_Tasks (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_AK4384_Initialize) Function void DRV_AK4384_Tasks(SYS_MODULE_OBJ object); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 124 DRV_AK4384_SetAudioCommunicationMode Function This function provides a run time audio format configuration File drv_ak4384.h C void DRV_AK4384_SetAudioCommunicationMode(DRV_HANDLE handle, const DATA_LENGTH dl, const SAMPLE_LENGTH sl); Returns None Description This function sets up audio mode in I2S protocol Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine dl Data length for I2S audio interface sl Left/Right Sample Length for I2S audio interface Function void DRV_AK4384_SetAudioCommunicationMode ( DRV_HANDLE handle, const DATA_LENGTH dl, const SAMPLE_LENGTH sl ) b) Client Setup Functions DRV_AK4384_Open Function Opens the specified AK4384 driver instance and returns a handle to it. Implementation: Dynamic File drv_ak4384.h C DRV_HANDLE DRV_AK4384_Open(const SYS_MODULE_INDEX iDriver, const DRV_IO_INTENT ioIntent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Errors can occur under following conditions: • if the number of client objects allocated via DRV_AK4384_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the driver hardware instance being opened is not initialized or is invalid • if the ioIntent options passed are not relevant to this driver Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 125 Description This routine opens the specified AK4384 driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. The DRV_IO_INTENT_BLOCKING and DRV_IO_INTENT_NONBLOCKING ioIntent options are not relevant to this driver. All the data transfer functions of this driver are non blocking. Only DRV_IO_INTENT_WRITE is a valid ioIntent option as AK4384 is DAC only. Specifying a DRV_IO_INTENT_EXCLUSIVE will cause the driver to provide exclusive access to this client. The driver cannot be opened by any other client. Remarks The handle returned is valid until the DRV_AK4384_Close routine is called. This routine will NEVER block waiting for hardware.If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. It should not be called in an ISR. Preconditions Function DRV_AK4384_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_AK4384_Open(DRV_AK4384_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver // May be the driver is not initialized or the initialization // is not complete. } Parameters Parameters Description drvIndex Identifier for the object instance to be opened ioIntent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver. See function description for details. Function DRV_HANDLE DRV_AK4384_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent ) DRV_AK4384_Close Function Closes an opened-instance of the AK4384 driver. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_Close(const DRV_HANDLE handle); Returns None. Description This routine closes an opened-instance of the AK4384 driver, invalidating the handle. Any buffers in the driver queue that were submitted by this client will be removed. After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_AK4384_Open before the caller may use the driver again Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 126 Remarks Usually there is no need for the driver client to verify that the Close operation has completed. The driver will abort any ongoing operations when this routine is called. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_AK4384_Open DRV_AK4384_Close(handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4384_Close( DRV_Handle handle ) c) Codec Specific Functions DRV_AK4384_ChannelOutputInvertDisable Function Disables output polarity of the selected Channel. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_ChannelOutputInvertDisable(DRV_HANDLE handle, DRV_AK4384_CHANNEL chan); Returns None. Description This function disables output polarity of the selected Channel. Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. DRV_AK4384_ChannelOutputInvertDisable(myAK4384Handle, DRV_AK4384_CHANNEL_LEFT); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine chan Left or Right channel Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 127 Function void DRV_AK4384_ChannelOutputInvertDisable( DRV_HANDLE handle, DRV_AK4384_CHANNEL chan) DRV_AK4384_ChannelOutputInvertEnable Function Enables output polarity of the selected channel. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_ChannelOutputInvertEnable(DRV_HANDLE handle, DRV_AK4384_CHANNEL chan); Returns None. Description This function enables output polarity of the selected channel. Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. DRV_AK4384_ChannelOutputInvertEnable(myAK4384Handle, DRV_AK4384_CHANNEL_LEFT); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine chan Left or Right channel Function void DRV_AK4384_ChannelOutputInvertEnable( DRV_HANDLE handle, DRV_AK4384_CHANNEL chan) DRV_AK4384_DeEmphasisFilterSet Function Allows specifies enabling of digital de-emphasis filter. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_DeEmphasisFilterSet(DRV_HANDLE handle, DRV_AK4384_DEEMPHASIS_FILTER filter); Returns None. Description This function allows specifies enabling of digital de-emphasis for 32, 44.1 or 48 kHz sampling rates (tc = 50/15 µs) Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 128 Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. DRV_AK4384_DeEmphasisFilterSet(myAK4384Handle, DRV_AK4384_DEEMPHASIS_FILTER_44_1KHZ) Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine filter Specifies Enable of de-emphasis filter Function void DRV_AK4384_DeEmphasisFilterSet ( DRV_HANDLE handle, DRV_AK4384_DEEMPHASIS_FILTER filter ) DRV_AK4384_MuteOff Function Disables AK4384 output for soft mute. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_MuteOff(DRV_HANDLE handle); Returns None. Description This function disables AK4384 output for soft mute. Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. DRV_AK4384_MuteOff(myAK4384Handle); //AK4384 output soft mute disabled Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 129 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4384_MuteOff( DRV_HANDLE handle) DRV_AK4384_MuteOn Function Allows AK4384 output for soft mute on. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_MuteOn(DRV_HANDLE handle); Returns None. Description This function Enables AK4384 output for soft mute. Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. DRV_AK4384_MuteOn(myAK4384Handle); //AK4384 output soft muted Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4384_MuteOn( DRV_HANDLE handle); DRV_AK4384_SamplingRateGet Function This function gets the sampling rate set on the DAC AK4384. Implementation: Dynamic File drv_ak4384.h C uint32_t DRV_AK4384_SamplingRateGet(DRV_HANDLE handle); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 130 Description This function gets the sampling rate set on the DAC AK4384. Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example uint32_t baudRate; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. baudRate = DRV_AK4384_SamplingRateGet(myAK4384Handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function uint32_t DRV_AK4384_SamplingRateGet( DRV_HANDLE handle) DRV_AK4384_SamplingRateSet Function This function sets the sampling rate of the media stream. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_SamplingRateSet(DRV_HANDLE handle, uint32_t samplingRate); Returns None. Description This function sets the media sampling rate for the client handle. Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. DRV_AK4384_SamplingRateSet(myAK4384Handle, 48000); //Sets 48000 media sampling rate Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine baudRate Baud Rate to be set Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 131 Function void DRV_AK4384_SamplingRateSet( DRV_HANDLE handle, uint32_t samplingRate) DRV_AK4384_SlowRollOffFilterDisable Function Disables Slow Roll-off filter function. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_SlowRollOffFilterDisable(DRV_HANDLE handle); Returns None. Description This function disables Slow Roll-off filter function. Sharp Roll-off filter function gets enabled. Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. DRV_AK4384_SlowRollOffFilterDisable(myAK4384Handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4384_SlowRollOffFilterDisable( DRV_HANDLE handle); DRV_AK4384_SlowRollOffFilterEnable Function Enables Slow Roll-off filter function. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_SlowRollOffFilterEnable(DRV_HANDLE handle); Returns None. Description This function enables Slow Roll-off filter function. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 132 Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. DRV_AK4384_SlowRollOffFilterEnable(myAK4384Handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4384_SlowRollOffFilterEnable( DRV_HANDLE handle); DRV_AK4384_VolumeGet Function This function gets the volume for AK4384 Codec. Implementation: Dynamic File drv_ak4384.h C uint8_t DRV_AK4384_VolumeGet(DRV_HANDLE handle, DRV_AK4384_CHANNEL chan); Returns None. Description This functions gets the current volume programmed to the DAC AK4384. Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t volume; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. volume = DRV_AK4384_VolumeGet(myAK4384Handle, DRV_AK4384_CHANNEL_LEFT_RIGHT); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine chan Audio channel volume to get. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 133 Function uint8_t DRV_AK4384_VolumeGet( DRV_HANDLE handle, DRV_AK4384_CHANNEL chan) DRV_AK4384_VolumeSet Function This function sets the volume for AK4384 Codec. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_VolumeSet(DRV_HANDLE handle, DRV_AK4384_CHANNEL chan, uint8_t volume); Returns None. Description This functions sets the volume value from 0-255, which can attenuate from 0 dB to –48 dB and mute. Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. DRV_AK4384_VolumeSet(myAK4384Handle, DRV_AK4384_CHANNEL_LEFT_RIGHT, 120); //Step 120 volume Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine chan Audio channel volume to be set volume volume value from 0-255, which can attenuate from 0 dB to –48 dB and mute Function void DRV_AK4384_VolumeSet( DRV_HANDLE handle, DRV_AK4384_CHANNEL chan, uint8_t volume) DRV_AK4384_ZeroDetectDisable Function Disables AK4384 channel-independent zeros detect function. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_ZeroDetectDisable(DRV_HANDLE handle); Returns None. Description This function disables AK4384 channel-independent zeros detect function. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 134 Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. DRV_AK4384_ZeroDetectDisable(myAK4384Handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4384_ZeroDetectDisable( DRV_HANDLE handle) DRV_AK4384_ZeroDetectEnable Function Enables AK4384 channel-independent zeros detect function. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_ZeroDetectEnable(DRV_HANDLE handle); Returns None. Description This function enables AK4384 channel-independent zeros detect function. Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. DRV_AK4384_ZeroDetectEnable(myAK4384Handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 135 Function void DRV_AK4384_ZeroDetectEnable( DRV_HANDLE handle) DRV_AK4384_ZeroDetectInvertDisable Function Disables inversion of polarity for zero detect function. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_ZeroDetectInvertDisable(DRV_HANDLE handle); Returns None. Description This function disables inversion of polarity for zero detect function. DZF goes “H” at Zero Detection. Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. DRV_AK4384_ZeroDetectInvertDisable(myAK4384Handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4384_ZeroDetectInvertDisable( DRV_HANDLE handle) DRV_AK4384_ZeroDetectInvertEnable Function Enables inversion of polarity for zero detect function. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_ZeroDetectInvertEnable(DRV_HANDLE handle); Returns None. Description This function enables inversion of polarity for zero detect function. DZF goes “L” at Zero Detection Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 136 Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. DRV_AK4384_ZeroDetectInvertEnable(myAK4384Handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4384_ZeroDetectInvertEnable( DRV_HANDLE handle) DRV_AK4384_ZeroDetectModeSet Function Sets mode of AK4384 channel-independent zeros detect function. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_ZeroDetectModeSet(DRV_HANDLE handle, DRV_AK4384_ZERO_DETECT_MODE zdMode); Returns None. Description This function sets mode of AK4384 channel-independent zeros detect function Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. DRV_AK4384_ZeroDetectModeSet(myAK4384Handle, DRV_AK4384_ZERO_DETECT_MODE_ANDED); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine zdMode Specifies zero detect function mode. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 137 Function void DRV_AK4384_ZeroDetectModeSet ( DRV_HANDLE handle, DRV_AK4384_ZERO_DETECT_MODE zdMode ) d) Data Transfer Functions DRV_AK4384_BufferAddWrite Function Schedule a non-blocking driver write operation. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_BufferAddWrite(const DRV_HANDLE handle, DRV_AK4384_BUFFER_HANDLE * bufferHandle, void * buffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_AK4384_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking write operation. The function returns with a valid buffer handle in the bufferHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance transmit queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_AK4384_BUFFER_HANDLE_INVALID if: • a buffer could not be allocated to the request • the input buffer pointer is NULL • the buffer size is '0' • the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_AK4384_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_AK4384_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the AK4384 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another AK4384 driver instance. It should not otherwise be called directly in an ISR. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 device instance and the DRV_AK4384_Status must have returned SYS_STATUS_READY. DRV_AK4384_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE must have been specified in the DRV_AK4384_Open call. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK4384_BUFFER_HANDLE bufferHandle; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. // Client registers an event handler with driver DRV_AK4384_BufferEventHandlerSet(myAK4384Handle, APP_AK4384BufferEventHandler, (uintptr_t)&myAppObj); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 138 DRV_AK4384_BufferAddWrite(myAK4384handle, &bufferHandle myBuffer, MY_BUFFER_SIZE); if(DRV_AK4384_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_AK4384BufferEventHandler(DRV_AK4384_BUFFER_EVENT event, DRV_AK4384_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_AK4384_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_AK4384_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle Handle of the AK4384 instance as return by the DRV_AK4384_Open function. buffer Data to be transmitted. size Buffer size in bytes. bufferHandle Pointer to an argument that will contain the return buffer handle. Function void DRV_AK4384_BufferAddWrite ( const DRV_HANDLE handle, DRV_AK4384_BUFFER_HANDLE *bufferHandle, void *buffer, size_t size ) DRV_AK4384_BufferEventHandlerSet Function This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_BufferEventHandlerSet(DRV_HANDLE handle, const DRV_AK4384_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 139 Description This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. When a client calls DRV_AK4384_BufferAddWrite function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed. The event handler should be set before the client performs any "buffer add" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued buffer transfer has completed, it does not need to register a callback. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK4384_BUFFER_HANDLE bufferHandle; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. // Client registers an event handler with driver DRV_AK4384_BufferEventHandlerSet(myAK4384Handle, APP_AK4384BufferEventHandler, (uintptr_t)&myAppObj); DRV_AK4384_BufferAddWrite(myAK4384handle, &bufferHandle myBuffer, MY_BUFFER_SIZE); if(DRV_AK4384_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_AK4384BufferEventHandler(DRV_AK4384_BUFFER_EVENT event, DRV_AK4384_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_AK4384_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_AK4384_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine eventHandler Pointer to the event handler function. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 140 context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_AK4384_BufferEventHandlerSet ( DRV_HANDLE handle, const DRV_AK4384_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle ) DRV_AK4384_BufferCombinedQueueSizeGet Function This function returns the number of bytes queued (to be processed) in the buffer queue. Implementation: Dynamic File drv_ak4384.h C size_t DRV_AK4384_BufferCombinedQueueSizeGet(DRV_HANDLE handle); Returns Returns the number of the bytes that have been processed for this buffer. Returns 0 for an invalid or an expired client handle. Description This function returns the number of bytes queued (to be processed) in the buffer queue associated with the driver instance to which the calling client belongs. The client can use this function to know number of bytes that is in the queue to be transmitted. Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. One of DRV_AK4384_BufferAddRead/DRV_AK4384_BufferAddWrite function must have been called and buffers should have been queued for transmission. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; size_t bufferQueuedSize; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK4384_BUFFER_HANDLE bufferHandle; // myI2SHandle is the handle returned // by the DRV_AK4384_Open function. // Client registers an event handler with driver. This is done once DRV_AK4384_BufferEventHandlerSet(myAK4384Handle, APP_AK4384BufferEventHandle, (uintptr_t)&myAppObj); DRV_AK4384_BufferAddRead(myAK4384handle,&bufferHandle, myBuffer, MY_BUFFER_SIZE); if(DRV_AK4384_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // The data is being processed after adding the buffer to the queue. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 141 // The user can get to know dynamically available data in the queue to be // transmitted by calling DRV_AK4384_BufferCombinedQueueSizeGet bufferQueuedSize = DRV_AK4384_BufferCombinedQueueSizeGet(myAK4384Handle); Parameters Parameters Description handle Opened client handle associated with a driver object. Function size_t DRV_AK4384_BufferCombinedQueueSizeGet( DRV_HANDLE handle) DRV_AK4384_BufferQueueFlush Function This function flushes off the buffers associated with the client object. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_BufferQueueFlush(const DRV_HANDLE handle); Returns None. Description This function flushes off the buffers associated with the client object and disables the DMA channel used for transmission. Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. One of DRV_AK4384_BufferAddRead/DRV_AK4384_BufferAddWrite function must have been called and buffers should have been queued for transmission. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; size_t bufferQueuedSize; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK4384_BUFFER_HANDLE bufferHandle; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. // Client registers an event handler with driver. This is done once DRV_AK4384_BufferEventHandlerSet(myAK4384Handle, APP_AK4384BufferEventHandle, (uintptr_t)&myAppObj); DRV_AK4384_BufferAddRead(myAK4384handle,&bufferHandle, myBuffer, MY_BUFFER_SIZE); if(DRV_AK4384_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // The data is being processed after adding the buffer to the queue. // The user can stop the data processing and flushoff the data // in the queue by calling DRV_AK4384_BufferQueueFlush DRV_AK4384_BufferQueueFlush(myAK4384Handle); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 142 Parameters Parameters Description handle Opened client handle associated with a driver object. Function void DRV_AK4384_BufferQueueFlush( DRV_HANDLE handle) DRV_AK4384_BufferProcessedSizeGet Function This function returns number of bytes that have been processed for the specified buffer. Implementation: Dynamic File drv_ak4384.h C size_t DRV_AK4384_BufferProcessedSizeGet(DRV_HANDLE handle); Returns Returns the number of the bytes that have been processed for this buffer. Returns 0 for an invalid or an expired buffer handle. Description This function returns number of bytes that have been processed for the specified buffer. The client can use this function, in a case where the buffer has terminated due to an error, to obtain the number of bytes that have been processed. If this function is called on a invalid buffer handle, or if the buffer handle has expired, the function returns 0. Remarks None. Preconditions The DRV_AK4384_Initialize routine must have been called for the specified I2S driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. One of DRV_AK4384_BufferAddRead, DRV_AK4384_BufferAddWrite function must have been called and a valid buffer handle returned. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK4384_BUFFER_HANDLE bufferHandle; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. // Client registers an event handler with driver. This is done once DRV_AK4384_BufferEventHandlerSet(myAK4384Handle, APP_AK4384BufferEventHandle, (uintptr_t)&myAppObj); DRV_AK4384_BufferAddRead(myAK4384handle,&bufferHandle, myBuffer, MY_BUFFER_SIZE); if(DRV_AK4384_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event Processing Technique. Event is received when // the buffer is processed. void APP_AK4384BufferEventHandler(DRV_AK4384_BUFFER_EVENT event, DRV_AK4384_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 143 // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) contextHandle; size_t processedBytes; switch(event) { case DRV_AK4384_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_AK4384_BUFFER_EVENT_ERROR: // Error handling here. // We can find out how many bytes were processed in this // buffer before the error occurred. processedBytes = DRV_AK4384_BufferProcessedSizeGet(myAK4384Handle); break; default: break; } } Parameters Parameters Description bufferhandle Handle of the buffer of which the processed number of bytes to be obtained. Function size_t DRV_AK4384_BufferProcessedSizeGet( DRV_HANDLE handle) e) Other Functions DRV_AK4384_CommandEventHandlerSet Function This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. Implementation: Dynamic File drv_ak4384.h C void DRV_AK4384_CommandEventHandlerSet(DRV_HANDLE handle, const DRV_AK4384_COMMAND_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Returns None. Description This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. When a client calls DRV_AK4384_BufferAddWrite function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed. The event handler should be set before the client performs any "AK4384 CODEC Specific Client Routines" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the command has completed, it does not need to register a callback. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 144 Preconditions The DRV_AK4384_Initialize routine must have been called for the specified AK4384 driver instance. DRV_AK4384_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; // myAK4384Handle is the handle returned // by the DRV_AK4384_Open function. // Client registers an event handler with driver DRV_AK4384_CommandEventHandlerSet(myAK4384Handle, APP_AK4384CommandEventHandler, (uintptr_t)&myAppObj); DRV_AK4384_DeEmphasisFilterSet(myAK4384Handle, DRV_AK4384_DEEMPHASIS_FILTER_44_1KHZ) // Event is received when // the buffer is processed. void APP_AK4384CommandEventHandler(uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { // Last Submitted command is completed. // Perform further processing here } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine eventHandler Pointer to the event handler function. context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_AK4384_CommandEventHandlerSet ( DRV_HANDLE handle, const DRV_AK4384_COMMAND_EVENT_HANDLER eventHandler, const uintptr_t contextHandle ) DRV_AK4384_VersionGet Function Returns the version of the AK4384 driver. Implementation: Dynamic File drv_ak4384.h C uint32_t DRV_AK4384_VersionGet(); Returns Returns the version of AK4384 driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 145 Description The version number returned from the DRV_AK4384_VersionGet function is an unsigned integer in the following decimal format. * 10000 + * 100 + Where the numbers are represented in decimal and the meaning is the same as above. Note that there is no numerical representation of release type. Remarks None. Example 1 For version "0.03a", return: 0 * 10000 + 3 * 100 + 0 For version "1.00", return: 1 * 100000 + 0 * 100 + 0 Example 2 uint32_t ak4384version; ak4384version = DRV_AK4384_VersionGet(); Function uint32_t DRV_AK4384_VersionGet( void ) DRV_AK4384_VersionStrGet Function Returns the version of AK4384 driver in string format. Implementation: Dynamic File drv_ak4384.h C int8_t* DRV_AK4384_VersionStrGet(); Returns returns a string containing the version of AK4384 driver. Description The DRV_AK4384_VersionStrGet function returns a string in the format: ".[.][]" Where: is the AK4384 driver's version number. is the AK4384 driver's version number. is an optional "patch" or "dot" release number (which is not included in the string if it equals '00'). is an optional release type ('a' for alpha, 'b' for beta not the entire word spelled out) that is not included if the release is a production version (i.e., not an alpha or beta). The String does not contain any spaces. Remarks None. Preconditions None. Example 1 "0.03a" "1.00" Example 2 int8_t *ak4384string; ak4384string = DRV_AK4384_VersionStrGet(); Function int8_t* DRV_AK4384_VersionStrGet(void) f) Data Types and Constants DRV_AK4384_AUDIO_DATA_FORMAT Enumeration Identifies the Serial Audio data interface format. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 146 File drv_ak4384.h C typedef enum { DRV_AK4384_AUDIO_DATA_FORMAT_16BIT_RIGHT_JUSTIFIED = 0, DRV_AK4384_AUDIO_DATA_FORMAT_20BIT_RIGHT_JUSTIFIED, DRV_AK4384_AUDIO_DATA_FORMAT_24BIT_LEFT_JUSTIFIED, DRV_AK4384_AUDIO_DATA_FORMAT_24BIT_I2S, DRV_AK4384_AUDIO_DATA_FORMAT_24BIT_RIGHT_JUSTIFIED } DRV_AK4384_AUDIO_DATA_FORMAT; Members Members Description DRV_AK4384_AUDIO_DATA_FORMAT_16BIT_RIGHT_JUSTIFIED = 0 16 bit Right Justified Audio data format DRV_AK4384_AUDIO_DATA_FORMAT_20BIT_RIGHT_JUSTIFIED 20 bit Right Justified Audio data format DRV_AK4384_AUDIO_DATA_FORMAT_24BIT_LEFT_JUSTIFIED 24 bit Left Justified Audio data format DRV_AK4384_AUDIO_DATA_FORMAT_24BIT_I2S 24 bit I2S Audio data format DRV_AK4384_AUDIO_DATA_FORMAT_24BIT_RIGHT_JUSTIFIED 24 bit Right Justified Audio data format Description AK4384 Audio data format This enumeration identifies Serial Audio data interface format. Remarks None. DRV_AK4384_BUFFER_EVENT Enumeration Identifies the possible events that can result from a buffer add request. File drv_ak4384.h C typedef enum { DRV_AK4384_BUFFER_EVENT_COMPLETE, DRV_AK4384_BUFFER_EVENT_ERROR, DRV_AK4384_BUFFER_EVENT_ABORT } DRV_AK4384_BUFFER_EVENT; Members Members Description DRV_AK4384_BUFFER_EVENT_COMPLETE Data was transferred successfully. DRV_AK4384_BUFFER_EVENT_ERROR Error while processing the request DRV_AK4384_BUFFER_EVENT_ABORT Data transfer aborted (Applicable in DMA mode) Description AK4384 Driver Events This enumeration identifies the possible events that can result from a buffer add request caused by the client calling either the DRV_AK4384_BufferAddWrite function. Remarks One of these values is passed in the "event" parameter of the event handling callback function that the client registered with the driver by calling the DRV_AK4384_BufferEventHandlerSet function when a buffer transfer request is completed. DRV_AK4384_BUFFER_EVENT_HANDLER Type Pointer to a AK4384 Driver Buffer Event handler function. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 147 File drv_ak4384.h C typedef void (* DRV_AK4384_BUFFER_EVENT_HANDLER)(DRV_AK4384_BUFFER_EVENT event, DRV_AK4384_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle); Returns None. Description AK4384 Driver Buffer Event Handler Function This data type defines the required function signature for the AK4384 driver buffer event handling callback function. A client must register a pointer to a buffer event handling function whose function signature (parameter and return value types) match the types specified by this function pointer in order to receive buffer related event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks If the event is DRV_AK4384_BUFFER_EVENT_COMPLETE, this means that the data was transferred successfully. If the event is DRV_AK4384_BUFFER_EVENT_ERROR, this means that the data was not transferred successfully. The bufferHandle parameter contains the buffer handle of the buffer that failed. The DRV_AK4384_BufferProcessedSizeGet function can be called to find out how many bytes were processed. The bufferHandle parameter contains the buffer handle of the buffer that associated with the event. The context parameter contains a handle to the client context, provided at the time the event handling function was registered using the DRV_AK4384_BufferEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the buffer add request. The buffer handle in bufferHandle expires after this event handler exits. In that the buffer object that was allocated is deallocated by the driver after the event handler exits. The event handler function executes in the data driver (I2S) peripheral's interrupt context when the driver is configured for interrupt mode operation. It is recommended of the application to not perform process intensive or blocking operations with in this function. DRV_AK4384_BufferAddWrite function can be called in the event handler to add a buffer to the driver queue. Example void APP_MyBufferEventHandler( DRV_AK4384_BUFFER_EVENT event, DRV_AK4384_BUFFER_HANDLE bufferHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_AK4384_BUFFER_EVENT_COMPLETE: // Handle the completed buffer. break; case DRV_AK4384_BUFFER_EVENT_ERROR: default: // Handle error. break; } } Parameters Parameters Description event Identifies the type of event bufferHandle Handle identifying the buffer to which the event relates context Value identifying the context of the application that registered the event handling function. DRV_AK4384_BUFFER_HANDLE Type Handle identifying a write buffer passed to the driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 148 File drv_ak4384.h C typedef uintptr_t DRV_AK4384_BUFFER_HANDLE; Description AK4384 Driver Buffer Handle A buffer handle value is returned by a call to the DRV_AK4384_BufferAddWrite function. This handle is associated with the buffer passed into the function and it allows the application to track the completion of the data from (or into) that buffer. The buffer handle value returned from the "buffer add" function is returned back to the client by the "event handler callback" function registered with the driver. The buffer handle assigned to a client request expires when the client has been notified of the completion of the buffer transfer (after event handler function that notifies the client returns) or after the buffer has been retired by the driver if no event handler callback was set. Remarks None. DRV_AK4384_CHANNEL Enumeration Identifies Left/Right Audio channel File drv_ak4384.h C typedef enum { DRV_AK4384_CHANNEL_LEFT, DRV_AK4384_CHANNEL_RIGHT, DRV_AK4384_CHANNEL_LEFT_RIGHT, DRV_AK4384_NUMBER_OF_CHANNELS } DRV_AK4384_CHANNEL; Description AK4384 Audio Channel This enumeration identifies Left/Right Audio channel Remarks None. DRV_AK4384_COMMAND_EVENT_HANDLER Type Pointer to a AK4384 Driver Command Event Handler Function File drv_ak4384.h C typedef void (* DRV_AK4384_COMMAND_EVENT_HANDLER)(uintptr_t contextHandle); Returns None. Description AK4384 Driver Command Event Handler Function This data type defines the required function signature for the AK4384 driver command event handling callback function. A command is a control instruction to the AK4384 Codec. For example, Mute ON/OFF, Zero Detect Enable/Disable, etc. A client must register a pointer to a command event handling function whose function signature (parameter and return value types) match the types specified by this function pointer in order to receive command related event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks The occurrence of this call back means that the last control command was transferred successfully. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 149 The context parameter contains a handle to the client context, provided at the time the event handling function was registered using the DRV_AK4384_CommandEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) of the client that made the buffer add request. The event handler function executes in the control data driver interrupt context. It is recommended of the application to not perform process intensive or blocking operations with in this function. Example void APP_AK4384CommandEventHandler( uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; // Last Submitted command is completed. // Perform further processing here } Parameters Parameters Description context Value identifying the context of the application that registered the event handling function. DRV_AK4384_DEEMPHASIS_FILTER Enumeration Identifies de-emphasis filter function. File drv_ak4384.h C typedef enum { DRV_AK4384_DEEMPHASIS_FILTER_44_1KHZ, DRV_AK4384_DEEMPHASIS_FILTER_OFF, DRV_AK4384_DEEMPHASIS_FILTER_48KHZ, DRV_AK4384_DEEMPHASIS_FILTER_32KHZ } DRV_AK4384_DEEMPHASIS_FILTER; Members Members Description DRV_AK4384_DEEMPHASIS_FILTER_44_1KHZ De-Emphasis filter for 44.1kHz. DRV_AK4384_DEEMPHASIS_FILTER_OFF De-Emphasis filter Off This is the default setting. DRV_AK4384_DEEMPHASIS_FILTER_48KHZ De-Emphasis filter for 48kHz. DRV_AK4384_DEEMPHASIS_FILTER_32KHZ De-Emphasis filter for 32kHz. Description AK4384 De-Emphasis Filter This enumeration identifies the settings for de-emphasis filter function. Remarks None. DRV_AK4384_INIT Structure Defines the data required to initialize or reinitialize the AK4384 driver. File drv_ak4384.h C typedef struct { SYS_MODULE_INIT moduleInit; SYS_MODULE_INDEX spiDriverModuleIndex; SYS_MODULE_INDEX i2sDriverModuleIndex; uint8_t volume; DRV_AK4384_MCLK_MODE mclkMode; bool delayDriverInitialization; } DRV_AK4384_INIT; Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 150 Members Members Description SYS_MODULE_INIT moduleInit; System module initialization SYS_MODULE_INDEX spiDriverModuleIndex; Identifies control module(SPI) driver ID for control interface of Codec SYS_MODULE_INDEX i2sDriverModuleIndex; Identifies data module(I2S) driver ID for data interface of Codec uint8_t volume; Volume DRV_AK4384_MCLK_MODE mclkMode; Set MCLK mode. bool delayDriverInitialization; true if driver initialization should be delayed due to shared RESET pin Description AK4384 Driver Initialization Data This data type defines the data required to initialize or reinitialize the AK4384 Codec driver. Remarks None. DRV_AK4384_MCLK_MODE Enumeration Identifies the mode of master clock to AK4384 DAC. File drv_ak4384.h C typedef enum { DRV_AK4384_MCLK_MODE_MANUAL, DRV_AK4384_MCLK_MODE_AUTO } DRV_AK4384_MCLK_MODE; Members Members Description DRV_AK4384_MCLK_MODE_MANUAL Master clock frequency mode Manual DRV_AK4384_MCLK_MODE_AUTO Master clock frequency mode Auto This is the default mode. Description AK4384 Master clock frequency mode This enumeration identifies mode of master clock to AK4384 DAC. In Manual Setting Mode, the sampling speed is set by setting DFS0/1 bits in Control Register 2. The frequency of MCLK at each sampling speed is set automatically. In Auto Setting Mode, the MCLK frequency is detected automatically Remarks None. DRV_AK4384_ZERO_DETECT_MODE Enumeration Identifies Zero Detect Function mode File drv_ak4384.h C typedef enum { DRV_AK4384_ZERO_DETECT_MODE_CHANNEL_SEPARATED, DRV_AK4384_ZERO_DETECT_MODE_ANDED } DRV_AK4384_ZERO_DETECT_MODE; Members Members Description DRV_AK4384_ZERO_DETECT_MODE_CHANNEL_SEPARATED Zero Detect channel separated. When the input data at each channel is continuously zeros for 8192 LRCK cycles, DZF pin of each channel goes to “H” This is the default mode. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 151 DRV_AK4384_ZERO_DETECT_MODE_ANDED Zero Detect Anded DZF pins of both channels go to “H” only when the input data at both channels are continuously zeros for 8192 LRCK cycles Description AK4384 Zero Detect mode This enumeration identifies the mode of zero detect function Remarks None. DRV_AK4384_BUFFER_HANDLE_INVALID Macro Definition of an invalid buffer handle. File drv_ak4384.h C #define DRV_AK4384_BUFFER_HANDLE_INVALID ((DRV_AK4384_BUFFER_HANDLE)(-1)) Description AK4384 Driver Invalid Buffer Handle This is the definition of an invalid buffer handle. An invalid buffer handle is returned by DRV_AK4384_BufferAddWrite function if the buffer add request was not successful. Remarks None. DRV_AK4384_COUNT Macro Number of valid AK4384 driver indices. File drv_ak4384.h C #define DRV_AK4384_COUNT Description AK4384 Driver Module Count This constant identifies the maximum number of AK4384 Driver instances that should be defined by the application. Defining more instances than this constant will waste RAM memory space. This constant can also be used by the application to identify the number of AK4384 instances on this microcontroller. Remarks This value is device-specific. DRV_AK4384_INDEX_0 Macro AK4384 driver index definitions. File drv_ak4384.h C #define DRV_AK4384_INDEX_0 0 Description Driver AK4384 Module Index These constants provide AK4384 driver index definition. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 152 Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_AK4384_Initialize and DRV_AK4384_Open routines to identify the driver instance in use. DRV_AK4384_INDEX_1 Macro File drv_ak4384.h C #define DRV_AK4384_INDEX_1 1 Description This is macro DRV_AK4384_INDEX_1. DRV_AK4384_INDEX_2 Macro File drv_ak4384.h C #define DRV_AK4384_INDEX_2 2 Description This is macro DRV_AK4384_INDEX_2. DRV_AK4384_INDEX_3 Macro File drv_ak4384.h C #define DRV_AK4384_INDEX_3 3 Description This is macro DRV_AK4384_INDEX_3. DRV_AK4384_INDEX_4 Macro File drv_ak4384.h C #define DRV_AK4384_INDEX_4 4 Description This is macro DRV_AK4384_INDEX_4. DRV_AK4384_INDEX_5 Macro File drv_ak4384.h C #define DRV_AK4384_INDEX_5 5 Description This is macro DRV_AK4384_INDEX_5. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 153 Files Files Name Description drv_ak4384.h AK4384 Codec Driver Interface header file drv_ak4384_config_template.h AK4384 Codec Driver Configuration Template. Description This section lists the source and header files used by the AK4384Codec Driver Library. drv_ak4384.h AK4384 Codec Driver Interface header file Enumerations Name Description DRV_AK4384_AUDIO_DATA_FORMAT Identifies the Serial Audio data interface format. DRV_AK4384_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_AK4384_CHANNEL Identifies Left/Right Audio channel DRV_AK4384_DEEMPHASIS_FILTER Identifies de-emphasis filter function. DRV_AK4384_MCLK_MODE Identifies the mode of master clock to AK4384 DAC. DRV_AK4384_ZERO_DETECT_MODE Identifies Zero Detect Function mode Functions Name Description DRV_AK4384_BufferAddWrite Schedule a non-blocking driver write operation. Implementation: Dynamic DRV_AK4384_BufferCombinedQueueSizeGet This function returns the number of bytes queued (to be processed) in the buffer queue. Implementation: Dynamic DRV_AK4384_BufferEventHandlerSet This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. Implementation: Dynamic DRV_AK4384_BufferProcessedSizeGet This function returns number of bytes that have been processed for the specified buffer. Implementation: Dynamic DRV_AK4384_BufferQueueFlush This function flushes off the buffers associated with the client object. Implementation: Dynamic DRV_AK4384_ChannelOutputInvertDisable Disables output polarity of the selected Channel. Implementation: Dynamic DRV_AK4384_ChannelOutputInvertEnable Enables output polarity of the selected channel. Implementation: Dynamic DRV_AK4384_Close Closes an opened-instance of the AK4384 driver. Implementation: Dynamic DRV_AK4384_CommandEventHandlerSet This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. Implementation: Dynamic DRV_AK4384_DeEmphasisFilterSet Allows specifies enabling of digital de-emphasis filter. Implementation: Dynamic DRV_AK4384_Deinitialize Deinitializes the specified instance of the AK4384 driver module. Implementation: Dynamic DRV_AK4384_Initialize Initializes hardware and data for the instance of the AK4384 DAC module. Implementation: Dynamic DRV_AK4384_MuteOff Disables AK4384 output for soft mute. Implementation: Dynamic DRV_AK4384_MuteOn Allows AK4384 output for soft mute on. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 154 DRV_AK4384_Open Opens the specified AK4384 driver instance and returns a handle to it. Implementation: Dynamic DRV_AK4384_SamplingRateGet This function gets the sampling rate set on the DAC AK4384. Implementation: Dynamic DRV_AK4384_SamplingRateSet This function sets the sampling rate of the media stream. Implementation: Dynamic DRV_AK4384_SetAudioCommunicationMode This function provides a run time audio format configuration DRV_AK4384_SlowRollOffFilterDisable Disables Slow Roll-off filter function. Implementation: Dynamic DRV_AK4384_SlowRollOffFilterEnable Enables Slow Roll-off filter function. Implementation: Dynamic DRV_AK4384_Status Gets the current status of the AK4384 driver module. Implementation: Dynamic DRV_AK4384_Tasks Maintains the driver's control and data interface state machine. Implementation: Dynamic DRV_AK4384_VersionGet Returns the version of the AK4384 driver. Implementation: Dynamic DRV_AK4384_VersionStrGet Returns the version of AK4384 driver in string format. Implementation: Dynamic DRV_AK4384_VolumeGet This function gets the volume for AK4384 Codec. Implementation: Dynamic DRV_AK4384_VolumeSet This function sets the volume for AK4384 Codec. Implementation: Dynamic DRV_AK4384_ZeroDetectDisable Disables AK4384 channel-independent zeros detect function. Implementation: Dynamic DRV_AK4384_ZeroDetectEnable Enables AK4384 channel-independent zeros detect function. Implementation: Dynamic DRV_AK4384_ZeroDetectInvertDisable Disables inversion of polarity for zero detect function. Implementation: Dynamic DRV_AK4384_ZeroDetectInvertEnable Enables inversion of polarity for zero detect function. Implementation: Dynamic DRV_AK4384_ZeroDetectModeSet Sets mode of AK4384 channel-independent zeros detect function. Implementation: Dynamic Macros Name Description DRV_AK4384_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_AK4384_COUNT Number of valid AK4384 driver indices. DRV_AK4384_INDEX_0 AK4384 driver index definitions. DRV_AK4384_INDEX_1 This is macro DRV_AK4384_INDEX_1. DRV_AK4384_INDEX_2 This is macro DRV_AK4384_INDEX_2. DRV_AK4384_INDEX_3 This is macro DRV_AK4384_INDEX_3. DRV_AK4384_INDEX_4 This is macro DRV_AK4384_INDEX_4. DRV_AK4384_INDEX_5 This is macro DRV_AK4384_INDEX_5. Structures Name Description DRV_AK4384_INIT Defines the data required to initialize or reinitialize the AK4384 driver. Types Name Description DRV_AK4384_BUFFER_EVENT_HANDLER Pointer to a AK4384 Driver Buffer Event handler function. DRV_AK4384_BUFFER_HANDLE Handle identifying a write buffer passed to the driver. DRV_AK4384_COMMAND_EVENT_HANDLER Pointer to a AK4384 Driver Command Event Handler Function Description AK4384 Codec Driver Interface Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 155 The AK4384 Codec device driver interface provides a simple interface to manage the AK4384 106 dB 192 kHz 24-Bit DAC that can be interfaced Microchip Microcontroller. This file provides the interface definition for the AK4384 Codec device driver. File Name drv_ak4384.h Company Microchip Technology Inc. drv_ak4384_config_template.h AK4384 Codec Driver Configuration Template. Macros Name Description DRV_AK4384_BCLK_BIT_CLK_DIVISOR Sets up the BCLK to LRCK Ratio to Generate Audio Stream for 32, 44.1, and 48K sampling frequency DRV_AK4384_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_AK4384_CONTROL_CLOCK Sets up clock frequency for the control interface (SPI) DRV_AK4384_INPUT_REFCLOCK Identifies the input REFCLOCK source to generate the MCLK to codec. DRV_AK4384_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_AK4384_MCLK_SAMPLE_FREQ_MULTPLIER Sets up the MCLK to LRCK Ratio to Generate Audio Stream for 32, 44.1 and 48K sampling frequency DRV_AK4384_TIMER_DRIVER_MODULE_INDEX Identifies the Timer Module Index for custom virtual SPI driver implementation. DRV_AK4384_TIMER_PERIOD Identifies the period for the bit bang timer. Description AK4384 Codec Driver Configuration Template These file provides the list of all the configurations that can be used with the driver. This file should not be included in the driver. File Name drv_ak4384_config_template.h Company Microchip Technology Inc. AK4642 Codec Driver Library This topic describes the AK4642 Codec Driver Library. Introduction This library provides an interface to manage the AK4642 Codec that is serially interfaced to a Microchip microcontroller for providing Audio Solutions. Description The AK4642 module is 16/24-bit Audio Codec from Asahi Kasei Microdevices Corporation. The AK4642 can be interfaced to Microchip microcontrollers through I2C and I2S serial interfaces. The I2C interface is used for control command transfer. The I2S interface is used for Audio data output. A typical interface of AK4642 to a Microchip PIC32 device is provided in the following diagram: Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 156 Features The AK4642 Codec Driver supports the following features: • Audio Interface Format: MSB first • ADC: 16-bit MSB justified, 16/24-bit I2S • DAC: 16-bit MSB justified, 16bit LSB justified, 16/24-bit I2S • Sampling Frequency Range: 8 kHz to 48 kHz • Digital Volume Control: +12dB ~ .115dB, 0.5dB Step • SoftMute: On and Off • Master Clock Frequencies: 32 fs/64 fs/128fs/256fs Using the Library This topic describes the basic architecture of the AK4642 Codec Driver Library and provides information and examples on its use. Description Interface Header File: drv_ak4642.h The interface to the AK4642 Codec Driver library is defined in the drv_ak4642.h header file. Any C language source (.c) file that uses the AK4642 Codec Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the AK4642 Codec Driver Library 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 abstraction model shown in the following diagram depicts how the AK4642 Codec Driver is positioned in the MPLAB Harmony framework. The AK4642 Codec Driver uses the SPI and I2S drivers for control and audio data transfers to the AK4642 module. AK4642 Driver Abstraction Model Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 157 Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The AK4642 Codec Driver Library provides an API interface to transfer control commands and digital audio data to the serially interfaced AK4642 DAC module. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the AK4642 Codec Driver Library. Library Interface Section Description System Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Client Setup Functions Provides open and close functions. Codec Specific Functions Provides functions that are codec specific. Data Transfer Functions Provides data transfer functions. Other Functions Provides driver specific miscellaneous functions such as sampling rate setting, control command functions, etc. Data Types and Constants These data types and constants are required while interacting and setting up the AK4642 Codec Driver Library. How the Library Works The library provides interfaces to support: • System Functionality • Client Functionality Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 158 System Access This topic provides information on system initialization, implementations, and provides a system access code example. Description System Initialization The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization, each instance of the AK4642 module would be initialized with the following configuration settings (either passed dynamically at run time using DRV_AK4642_INIT or by using Initialization Overrides) that are supported by the specific AK4642 device hardware: • Device requested power state: one of the System Module Power States. For specific details please refer to Data Types and Constants in the Library Interface section. • I2C driver module index. The module index should be same as the one used in initializing the I2C Driver. • I2S driver module index. The module index should be same as the one used in initializing the I2S Driver. • Sampling rate • Master clock detection mode • Power down pin port initialization The DRV_AK4642_Initialize API returns an object handle of the type SYS_MODULE_OBJ. The object handle returned by the Initialize interface would be used by the other system interfaces such as DRV_ AK4642_Deinitialize, DRV_ AK4642_Status and DRV_I2S_Tasks. Implementations The AK4642 Codec Driver can have the following implementations: Implementation Description MPLAB Harmony Components Implementation 1 Dedicated hardware for control (I2C) and data (I2S) interface. Standard MPLAB Harmony drivers for I2C and I2S interfaces. Implementation 2 Dedicated hardware for data (I2S) interface. Ports pins for control interface. Standard MPLAB Harmony drivers for I2S interface. Virtual MPLAB Harmony drivers for I2C interface. Example: DRV_AK4642_INIT drvak4642Init = { .moduleInit.value = SYS_MODULE_POWER_RUN_FULL, .i2sDriverModuleIndex = DRV_AK4642_I2S_DRIVER_MODULE_INDEX_IDX0, .i2cDriverModuleIndex = DRV_AK4642_I2C_DRIVER_MODULE_INDEX_IDX0, .volume = DRV_AK4642_VOLUME, }; /* The I2C and I2S module index should be same as the one used in initializing the I2C and I2S drivers. */ ak4642DevObject = DRV_AK4642_Initialize(DRV_AK4642_INDEX_0, (SYS_MODULE_INIT *) &drvak4642Init); if (SYS_MODULE_OBJ_INVALID == ak4642DevObject) { // Handle error } Task Routine The DRV_AK4642_Tasks will be called from the System Task Service. Client Access This topic describes client access and includes a code example. Description For the application to start using an instance of the module, it must call the DRV_AK4642_Open function. The DRV_AK4642_Open provides a driver handle to the AK4642 Codec Driver instance for operations. If the driver is deinitialized using the function DRV_AK4642_Deinitialize, the application must call the DRV_AK4642_Open function again to set up the instance of the driver. For the various options available for IO_INTENT, please refer to Data Types and Constants in the Library Interface section. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 159 Note: It is necessary to check the status of driver initialization before opening a driver instance. The status of the AK4642 Codec Driver can be known by calling DRV_AK4642_Status. Example: DRV_HANDLE handle; SYS_STATUS ak4642Status; ak4642Status = DRV_AK4642_Status(sysObjects.ak4642DevObject); if (SYS_STATUS_READY == ak4642Status) { // The driver can now be opened. appData.ak4642Client.handle = DRV_AK4642_Open (DRV_AK4642_INDEX_0, DRV_IO_INTENT_WRITE | DRV_IO_INTENT_EXCLUSIVE ); if(appData.ak4642Client.handle != DRV_HANDLE_INVALID) { appData.state = APP_STATE_AK4642_SET_BUFFER_HANDLER; } else { SYS_DEBUG(0, "Find out what's wrong \r\n"); } } else { /* AK4642 Driver Is not ready */ ; } Client Operations This topic describes client operations and provides a code example. Description Client operations provide the API interface for control command and audio data transfer to the AK4642 Codec. The following AK4642 Codec specific control command functions are provided: • DRV_AK4642_SamplingRateSet • DRV_AK4642_SamplingRateGet • DRV_AK4642_VolumeSet • DRV_AK4642_VolumeGet • DRV_AK4642_MuteOn • DRV_AK4642_MuteOff • DRV_AK4642_IntExtMicSet • DRV_AK4642_MonoStereoMicSet These functions schedule a non-blocking control command transfer operation. These functions submit the control command request to the I2C Driver transmit queue, where the request is processed immediately if it is the first request, or it is processed when the previous request is complete. DRV_AK4642_BufferAddWrite, DRV_AK4642_BufferAddRead, and DRV_AK4642_BufferAddWriteRead are buffered data operation functions. These functions schedule non-blocking audio data transfer operations. These functions add the request to the I2S Driver transmit or receive buffer queue depending on the request type, and are executed immediately if it is the first buffer, or executed later when the previous buffer is complete. The driver notifies the client with DRV_AK4642_BUFFER_EVENT_COMPLETE, DRV_AK4642_BUFFER_EVENT_ERROR, or DRV_AK4642_BUFFER_EVENT_ABORT events. The following diagram illustrates the control commands and audio buffered data operations. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 160 Note: It is not necessary to close and reopen the client between multiple transfers. An application using the buffered functionality needs to perform the following steps: 1. The system should have completed necessary setup and initializations. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 161 2. The I2S driver object should have been initialized by calling DRV_I2S_Initialize. 3. The I2C driver object should have been initialized by calling DRV_I2C_Initialize. 4. The AK4642 driver object should be initialized by calling DRV_AK4642_Initialize. 5. The necessary sampling rate value should be set up by calling DRV_AK4642_ SamplingRateSet. 6. Register buffer event handler for the client handle by calling DRV_AK4642_BufferEventHandlerSet. 7. Submit a command by calling specific command API. 8. Add a buffer to initiate the data transfer by calling DRV_AK4642_BufferAddWrite, DRV_AK4642_BufferAddRead, and DRV_AK4642_BufferAddWriteRead. 9. Call the DRV_AK4642_BufferAddWrite, DRV_AK4642_BufferAddRead, or DRV_AK4642_BufferAddWriteRead function for handling multiple buffer transmissions or receptions. 10. When the client is done, it can use DRV_AK4642_Close to close the client handle. Example: typedef enum { APP_STATE_AK4642_OPEN, APP_STATE_AK4642_SET_BUFFER_HANDLER, APP_STATE_AK4642_ADD_FIRST_BUFFER_READ, APP_STATE_AK4642_ADD_BUFFER_OUT, APP_STATE_AK4642_ADD_BUFFER_IN, APP_STATE_AK4642_WAIT_FOR_BUFFER_COMPLETE, } APP_STATES; typedef struct { DRV_HANDLE handle; DRV_AK4642_BUFFER_HANDLE writereadBufHandle; DRV_AK4642_BUFFER_EVENT_HANDLER bufferEventHandler; uintptr_t context; uint8_t *txbufferObject; uint8_t *rxbufferObject; size_t bufferSize; } APP_AK4642_CLIENT; typedef struct { /* Application's current state*/ APP_STATES state; /* USART client handle */ APP_AK4642_CLIENT ak4642Client; } APP_DATA; APP_DATA appData; SYS_MODULE_OBJ ak4642DevObject; DRV_AK4642_INIT drvak4642Init = { .moduleInit.value = SYS_MODULE_POWER_RUN_FULL, .i2sDriverModuleIndex = DRV_AK4642_I2S_DRIVER_MODULE_INDEX_IDX0, .i2cDriverModuleIndex = DRV_AK4642_I2C_DRIVER_MODULE_INDEX_IDX0, .volume = DRV_AK4642_VOLUME, }; void SYS_Initialize(void * data) { /* Initialize Drivers */ DRV_I2C0_Initialize(); sysObj.drvI2S0 = DRV_I2S_Initialize(DRV_I2S_INDEX_0, (SYS_MODULE_INIT *) &drvI2S0InitData); sysObj.drvak4642Codec0 = DRV_AK4642_Initialize(DRV_AK4642_INDEX_0, (SYS_MODULE_INIT *)&drvak4642Codec0InitData); /* Initialize System Services */ SYS_INT_Initialize(); } void APP_Tasks (void ) { Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 162 switch(appData.state) { case APP_STATE_AK4642_OPEN: { SYS_STATUS status; status = DRV_CODEC_Status(sysObjdrvCodec0); if (SYS_STATUS_READY == status) { /* A client opens the driver object to get an Handle */ appData.ak4642Client.handle = DRV_AK4642_Open(DRV_AK4642_INDEX_0, DRV_IO_INTENT_WRITE|DRV_IO_INTENT_EXCLUSIVE); if(appData.ak4642Client.handle != DRV_HANDLE_INVALID) { appData.state = APP_STATE_AK4642_SET_BUFFER_HANDLER; } else { /* Got an Invalid Handle. Wait for AK4642 to Initialize */ } } } break; /* Set a handler for the audio buffer completion event */ case APP_STATE_AK4642_SET_BUFFER_HANDLER: { DRV_AK4642_BufferEventHandlerSet(appData.ak4642Client.handle, appData.ak4642Client.bufferEventHandler, appData.ak4642Client.context); appData.state = APP_STATE_AK4642_ADD_FIRST_BUFFER_READ; } break; case APP_STATE_AK4642_ADD_FIRST_BUFFER_READ: { DRV_AK4642_BufferAddWriteRead(appData.ak4642Client.handle, &appData.ak4642Client.writeReadBufHandle, appData.ak4642Client.txbufferObject, appData.ak4642Client.rxbufferObject, appData.ak4642Client.bufferSize); if(appData.ak4642Client.writeReadBufHandle != DRV_AK4642_BUFFER_HANDLE_INVALID) { appData.state = APP_STATE_AK4642_WAIT_FOR_BUFFER_COMPLETE; } else { SYS_DEBUG(0, "Find out what is wrong \r\n"); } } break; /* Add an audio buffer to the ak4642 driver to be transmitted to * AK4642 CODEC */ case APP_STATE_AK4642_ADD_BUFFER_OUT: { DRV_AK4642_BufferAddWrite(appData.ak4642Client.handle, &appData.ak4642Client.writeBufHandle, appData.ak4642Client.txbufferObject, appData.ak4642Client.bufferSize); if(appData.ak4642Client.writeBufHandle != DRV_AK4642_BUFFER_HANDLE_INVALID) { appData.state = APP_STATE_AK4642_WAIT_FOR_BUFFER_COMPLETE; } else { SYS_DEBUG(0, "Find out what is wrong \r\n"); } Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 163 } break; /* Add an audio buffer to the ak4642 driver to be received * AK4642 CODEC */ case APP_STATE_AK4642_ADD_BUFFER_IN: { DRV_AK4642_BufferAddRead(appData.ak4642Client.handle, &appData.ak4642Client.readBufHandle, appData.ak4642Client.rxbufferObject, appData.ak4642Client.bufferSize); if(appData.ak4642Client.readBufHandle != DRV_AK4642_BUFFER_HANDLE_INVALID) { appData.state = APP_STATE_AK4642_ADD_BUFFER_OUT; } else { SYS_DEBUG(0, "Find out what is wrong \r\n"); } } break; /* Audio data Transmission under process */ case APP_STATE_AK4642_WAIT_FOR_BUFFER_COMPLETE: { /*Do nothing*/ } break; default: { } break; } } /********************************************************** * Application AK4642 buffer Event handler. * This function is called back by the AK4642 driver when * a AK4642 data buffer RX completes. **********************************************************/ void APP_AK4642MicBufferEventHandler(DRV_AK4642_BUFFER_EVENT event, DRV_AK4642_BUFFER_HANDLE handle, uintptr_t context ) { static uint8_t cnt = 0; switch(event) { case DRV_AK4642_BUFFER_EVENT_COMPLETE: { bufnum ^= 1; if(bufnum ==0) { appData.ak4642Client.rxbufferObject = (uint8_t *) micbuf1; appData.ak4642Client.txbufferObject = (uint8_t *) micbuf2; } else if(bufnum ==1) { appData.ak4642Client.rxbufferObject = (uint8_t *) micbuf2; appData.ak4642Client.txbufferObject = (uint8_t *) micbuf1; } DRV_AK4642_BufferAddWriteRead(appData.ak4642Client.handle, &appData.ak4642Client.writeReadBufHandle, appData.ak4642Client.txbufferObject, appData.ak4642Client.rxbufferObject, appData.ak4642Client.bufferSize); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 164 appData.state = APP_STATE_AK4642_WAIT_FOR_BUFFER_COMPLETE; } break; case DRV_AK4642_BUFFER_EVENT_ERROR: { } break; case DRV_AK4642_BUFFER_EVENT_ABORT: { } break; } } void SYS_Tasks(void) { DRV_AK4642_Tasks(ak4642DevObject); APP_Tasks(); } Configuring the Library Macros Name Description DRV_AK4642_BCLK_BIT_CLK_DIVISOR Sets up the BCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency DRV_AK4642_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_AK4642_INPUT_REFCLOCK Identifies the input REFCLOCK source to generate the MCLK to codec. DRV_AK4642_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_AK4642_MCLK_SAMPLE_FREQ_MULTPLIER Sets up the MCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency DRV_AK4642_MCLK_SOURCE Indicate the input clock frequency to generate the MCLK to codec. Description The configuration of the AK4642 Codec Driver is based on the file system_config.h. This header file contains the configuration selection for the AK4642 Codec Driver. Based on the selections made, the driver may support the selected features. These configuration settings will apply to all instances of the AK4642 Codec Driver. This header can be placed anywhere, 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. DRV_AK4642_BCLK_BIT_CLK_DIVISOR Macro Sets up the BCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency File drv_ak4642_config_template.h C #define DRV_AK4642_BCLK_BIT_CLK_DIVISOR Description AK4642 BCLK to LRCK Ratio to Generate Audio Stream Sets up the BCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency Following BCLK to LRCK ratios are supported 16bit data 16 bit channel :- 32fs, hence divisor would be 8 16bit data 32 bit channel :- 64fs, hence divisor would be 4 Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 165 DRV_AK4642_CLIENTS_NUMBER Macro Sets up the maximum number of clients that can be connected to any hardware instance. File drv_ak4642_config_template.h C #define DRV_AK4642_CLIENTS_NUMBER DRV_AK4642_INSTANCES_NUMBER Description AK4642 Client Count Configuration Sets up the maximum number of clients that can be connected to any hardware instance. Typically only one client could be connected to one hardware instance. This value represents the total number of clients to be supported across all hardware instances. Therefore, if there are five AK4642 hardware interfaces, this number will be 5. Remarks None. DRV_AK4642_INPUT_REFCLOCK Macro Identifies the input REFCLOCK source to generate the MCLK to codec. File drv_ak4642_config_template.h C #define DRV_AK4642_INPUT_REFCLOCK Description AK4642 Input reference clock Identifies the input REFCLOCK source to generate the MCLK to codec. Remarks None. DRV_AK4642_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported File drv_ak4642_config_template.h C #define DRV_AK4642_INSTANCES_NUMBER Description AK4642 driver objects configuration Sets up the maximum number of hardware instances that can be supported. It is recommended that this number be set exactly equal to the number of AK4642 CODEC modules that are needed by the application. Hardware Instance support consumes RAM memory space. If this macro is not defined, then the driver will be built statically. Remarks None. DRV_AK4642_MCLK_SAMPLE_FREQ_MULTPLIER Macro Sets up the MCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency File drv_ak4642_config_template.h Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 166 C #define DRV_AK4642_MCLK_SAMPLE_FREQ_MULTPLIER Description AK4642 MCLK to LRCK Ratio to Generate Audio Stream Sets up the MCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency I2S sampling frequency Supported MCLK to Sampling frequency Ratios are as below 256fs, 384fs, 512fs, 768fs or 1152fs Remarks None DRV_AK4642_MCLK_SOURCE Macro Indicate the input clock frequency to generate the MCLK to codec. File drv_ak4642_config_template.h C #define DRV_AK4642_MCLK_SOURCE Description AK4642 Data Interface Master Clock Speed configuration Indicate the input clock frequency to generate the MCLK to codec. Remarks None. Configuring the MHC Provides examples on how to configure the MPLAB Harmony Configurator (MHC) for a specific driver. Description The following three figures show examples of MHC configurations for the AK4642 Codec Driver, I2S Driver, and the I2C Driver. Figure 1: AK4642 Codec Driver MHC Configuration Figure 2: I2S Driver MHC Configuration Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 167 Figure 3: I2C Driver MHC Configuration Migrating the AK4642 Driver From Earlier Versions of Microchip Harmony Prior to version 1.08 of MPLAB Harmony, the AK4642 Codec Driver Library used the static I2C driver implementation. Beginning with v1.08 of MPLAB Harmony, applications must use the Dynamic Driver implementation with the MHC configured as shown in Figure 3. In addition, PIC32MZ configurations require the "Include Force Write I2C Function (Master Mode Only - Ignore NACK from Slave)" option to be selected. Building the Library This section lists the files that are available in the AK4642 Codec Driver Library. Description This section list the files that are available in the /src folder of the AK4642 Codec 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. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 168 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 /framework/driver/codec/ak4642. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_ak4642.h Header file that exports the driver API. 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 /src/dynamic/drv_ak4642.c This file contains implementation of the AK4642 Codec Driver. 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 There are no optional files for this driver. N/A Module Dependencies The AK4642 Driver Library depends on the following modules: • I2S Driver Library • I2C Driver Library Library Interface a) System Interaction Functions Name Description DRV_AK4642_Initialize Initializes hardware and data for the instance of the AK4642 DAC module DRV_AK4642_Deinitialize Deinitializes the specified instance of the AK4642 driver module DRV_AK4642_Status Gets the current status of the AK4642 driver module. DRV_AK4642_Tasks Maintains the driver's control and data interface state machine. b) Client Setup Functions Name Description DRV_AK4642_Open Opens the specified AK4642 driver instance and returns a handle to it DRV_AK4642_Close Closes an opened-instance of the AK4642 driver c) Codec Specific Functions Name Description DRV_AK4642_MuteOff This function disables AK4642 output for soft mute. DRV_AK4642_MuteOn This function allows AK4642 output for soft mute on. DRV_AK4642_SamplingRateGet This function gets the sampling rate set on the AK4642. Implementation: Dynamic DRV_AK4642_SamplingRateSet This function sets the sampling rate of the media stream. DRV_AK4642_VolumeGet This function gets the volume for AK4642 CODEC. DRV_AK4642_VolumeSet This function sets the volume for AK4642 CODEC. DRV_AK4642_IntExtMicSet This function sets up the codec for the internal or the external microphone use. DRV_AK4642_MonoStereoMicSet This function sets up the codec for the Mono or Stereo microphone mode. DRV_AK4642_SetAudioCommunicationMode This function provides a run time audio format configuration DRV_AK4642_MicSet This function select the single-ended AK4642 microphone input for the AK4642 Codec Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 169 d) Data Transfer Functions Name Description DRV_AK4642_BufferAddWrite Schedule a non-blocking driver write operation. DRV_AK4642_BufferAddRead Schedule a non-blocking driver read operation. DRV_AK4642_BufferAddWriteRead Schedule a non-blocking driver write-read operation. Implementation: Dynamic DRV_AK4642_BufferEventHandlerSet This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. e) Other Functions Name Description DRV_AK4642_CommandEventHandlerSet This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. DRV_AK4642_VersionGet This function returns the version of AK4642 driver DRV_AK4642_VersionStrGet This function returns the version of AK4642 driver in string format. f) Data Types and Constants Name Description _DRV_AK4642_H Include files. DRV_AK4642_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_AK4642_COUNT Number of valid AK4642 driver indices DRV_AK4642_INDEX_0 AK4642 driver index definitions DRV_AK4642_INDEX_1 This is macro DRV_AK4642_INDEX_1. DRV_AK4642_INDEX_2 This is macro DRV_AK4642_INDEX_2. DRV_AK4642_INDEX_3 This is macro DRV_AK4642_INDEX_3. DRV_AK4642_INDEX_4 This is macro DRV_AK4642_INDEX_4. DRV_AK4642_INDEX_5 This is macro DRV_AK4642_INDEX_5. DRV_AK4642_AUDIO_DATA_FORMAT Identifies the Serial Audio data interface format. DRV_AK4642_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_AK4642_BUFFER_EVENT_HANDLER Pointer to a AK4642 Driver Buffer Event handler function DRV_AK4642_BUFFER_HANDLE Handle identifying a write buffer passed to the driver. DRV_AK4642_CHANNEL Identifies Left/Right Audio channel DRV_AK4642_COMMAND_EVENT_HANDLER Pointer to a AK4642 Driver Command Event Handler Function DRV_AK4642_INIT Defines the data required to initialize or reinitialize the AK4642 driver DRV_AK4642_INT_EXT_MIC Identifies the Mic input source. DRV_AK4642_MONO_STEREO_MIC Identifies the Mic input as Mono / Stereo. DRV_AK4642_MIC This is type DRV_AK4642_MIC. Description This section describes the API functions of the AK4642 Codec Driver library. Refer to each section for a detailed description. a) System Interaction Functions DRV_AK4642_Initialize Function Initializes hardware and data for the instance of the AK4642 DAC module File drv_ak4642.h C SYS_MODULE_OBJ DRV_AK4642_Initialize(const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 170 Description This routine initializes the AK4642 driver instance for the specified driver index, making it ready for clients to open and use it. The initialization data is specified by the init parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. Remarks This routine must be called before any other AK4642 routine is called. This routine should only be called once during system initialization unless DRV_AK4642_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. Preconditions DRV_I2S_Initialize must be called before calling this function to initialize the data interface of this CODEC driver. DRV_I2C_Initialize must be called if SPI driver is used for handling the control interface of this CODEC driver. Example DRV_AK4642_INIT init; SYS_MODULE_OBJ objectHandle; init->inUse = true; init->status = SYS_STATUS_BUSY; init->numClients = 0; init->i2sDriverModuleIndex = ak4642Init->i2sDriverModuleIndex; init->i2cDriverModuleIndex = ak4642Init->i2cDriverModuleIndex; init->samplingRate = DRV_AK4642_AUDIO_SAMPLING_RATE; init->audioDataFormat = DRV_AK4642_AUDIO_DATA_FORMAT_MACRO; init->isInInterruptContext = false; init->commandCompleteCallback = (DRV_AK4642_COMMAND_EVENT_HANDLER)0; init->commandContextData = 0; init->mclk_multiplier = DRV_AK4642_MCLK_SAMPLE_FREQ_MULTPLIER; objectHandle = DRV_AK4642_Initialize(DRV_AK4642_0, (SYS_MODULE_INIT*)init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description drvIndex Identifier for the driver instance to be initialized init Pointer to the data structure containing any data necessary to initialize the hardware. This pointer may be null if no data is required and default initialization is to be used. Function SYS_MODULE_OBJ DRV_AK4642_Initialize ( const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT *const init ); DRV_AK4642_Deinitialize Function Deinitializes the specified instance of the AK4642 driver module File drv_ak4642.h C void DRV_AK4642_Deinitialize(SYS_MODULE_OBJ object); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 171 Returns None. Description Deinitializes the specified instance of the AK4642 driver module, disabling its operation (and any hardware). Invalidates all the internal data. Remarks Once the Initialize operation has been called, the De-initialize operation must be called before the Initialize operation can be called again. This routine will NEVER block waiting for hardware. Preconditions Function DRV_AK4642_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_AK4642_Initialize SYS_STATUS status; DRV_AK4642_Deinitialize(object); status = DRV_AK4642_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from the DRV_AK4642_Initialize routine Function void DRV_AK4642_Deinitialize( SYS_MODULE_OBJ object) DRV_AK4642_Status Function Gets the current status of the AK4642 driver module. File drv_ak4642.h C SYS_STATUS DRV_AK4642_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_DEINITIALIZED - Indicates that the driver has been deinitialized SYS_STATUS_READY - Indicates that any previous module operation for the specified module has completed SYS_STATUS_BUSY - Indicates that a previous module operation for the specified module has not yet completed SYS_STATUS_ERROR - Indicates that the specified module is in an error state Description This routine provides the current status of the AK4642 driver module. Remarks A driver can opened only when its status is SYS_STATUS_READY. Preconditions Function DRV_AK4642_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_AK4642_Initialize SYS_STATUS AK4642Status; Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 172 AK4642Status = DRV_AK4642_Status(object); if (SYS_STATUS_READY == AK4642Status) { // This means the driver can be opened using the // DRV_AK4642_Open() function. } Parameters Parameters Description object Driver object handle, returned from the DRV_AK4642_Initialize routine Function SYS_STATUS DRV_AK4642_Status( SYS_MODULE_OBJ object) DRV_AK4642_Tasks Function Maintains the driver's control and data interface state machine. File drv_ak4642.h C void DRV_AK4642_Tasks(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal control and data interface state machine and implement its control and data interface implementations. This function should be called from the SYS_Tasks() function. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks). Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_AK4642_Initialize while (true) { DRV_AK4642_Tasks (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_AK4642_Initialize) Function void DRV_AK4642_Tasks(SYS_MODULE_OBJ object); b) Client Setup Functions DRV_AK4642_Open Function Opens the specified AK4642 driver instance and returns a handle to it Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 173 File drv_ak4642.h C DRV_HANDLE DRV_AK4642_Open(const SYS_MODULE_INDEX iDriver, const DRV_IO_INTENT ioIntent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Error can occur • if the number of client objects allocated via DRV_AK4642_CLIENTS_NUMBER is insufficient. • if the client is trying to open the driver but driver has been opened exclusively by another client. • if the driver hardware instance being opened is not initialized or is invalid. • if the ioIntent options passed are not relevant to this driver. Description This routine opens the specified AK4642 driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. The DRV_IO_INTENT_BLOCKING and DRV_IO_INTENT_NONBLOCKING ioIntent options are not relevant to this driver. All the data transfer functions of this driver are non blocking. AK4642 can be opened with DRV_IO_INTENT_WRITE, or DRV_IO_INTENT_READ or DRV_IO_INTENT_WRITEREAD io_intent option. This decides whether the driver is used for headphone output, or microphone input or both modes simultaneously. Specifying a DRV_IO_INTENT_EXCLUSIVE will cause the driver to provide exclusive access to this client. The driver cannot be opened by any other client. Remarks The handle returned is valid until the DRV_AK4642_Close routine is called. This routine will NEVER block waiting for hardware.If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. It should not be called in an ISR. Preconditions Function DRV_AK4642_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_AK4642_Open(DRV_AK4642_INDEX_0, DRV_IO_INTENT_WRITEREAD | DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver // May be the driver is not initialized or the initialization // is not complete. } Parameters Parameters Description drvIndex Identifier for the object instance to be opened ioIntent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver. See function description for details. Function DRV_HANDLE DRV_AK4642_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent ) DRV_AK4642_Close Function Closes an opened-instance of the AK4642 driver Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 174 File drv_ak4642.h C void DRV_AK4642_Close(const DRV_HANDLE handle); Returns • None Description This routine closes an opened-instance of the AK4642 driver, invalidating the handle. Any buffers in the driver queue that were submitted by this client will be removed. After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_AK4642_Open before the caller may use the driver again Remarks Usually there is no need for the driver client to verify that the Close operation has completed. The driver will abort any ongoing operations when this routine is called. Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 driver instance. DRV_AK4642_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_AK4642_Open DRV_AK4642_Close(handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4642_Close( DRV_Handle handle ) c) Codec Specific Functions DRV_AK4642_MuteOff Function This function disables AK4642 output for soft mute. File drv_ak4642.h C void DRV_AK4642_MuteOff(DRV_HANDLE handle); Returns None. Description This function disables AK4642 output for soft mute. Remarks None. Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 driver instance. DRV_AK4642_Open must have been called to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 175 Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_BUFFER_HANDLE bufferHandle; // myAK4642Handle is the handle returned // by the DRV_AK4642_Open function. DRV_AK4642_MuteOff(myAK4642Handle); //AK4642 output soft mute disabled Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4642_MuteOff( DRV_HANDLE handle) DRV_AK4642_MuteOn Function This function allows AK4642 output for soft mute on. File drv_ak4642.h C void DRV_AK4642_MuteOn(DRV_HANDLE handle); Returns None. Description This function Enables AK4642 output for soft mute. Remarks None. Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 driver instance. DRV_AK4642_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_BUFFER_HANDLE bufferHandle; // myAK4642Handle is the handle returned // by the DRV_AK4642_Open function. DRV_AK4642_MuteOn(myAK4642Handle); //AK4642 output soft muted Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4642_MuteOn( DRV_HANDLE handle); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 176 DRV_AK4642_SamplingRateGet Function This function gets the sampling rate set on the AK4642. Implementation: Dynamic File drv_ak4642.h C uint32_t DRV_AK4642_SamplingRateGet(DRV_HANDLE handle); Description This function gets the sampling rate set on the DAC AK4642. Remarks None. Example uint32_t baudRate; // myAK4642Handle is the handle returned // by the DRV_AK4642_Open function. baudRate = DRV_AK4642_SamplingRateGet(myAK4642Handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function uint32_t DRV_AK4642_SamplingRateGet( DRV_HANDLE handle) DRV_AK4642_SamplingRateSet Function This function sets the sampling rate of the media stream. File drv_ak4642.h C void DRV_AK4642_SamplingRateSet(DRV_HANDLE handle, uint32_t samplingRate); Returns None. Description This function sets the media sampling rate for the client handle. Remarks None. Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 driver instance. DRV_AK4642_Open must have been called to obtain a valid opened device handle. Example // myAK4642Handle is the handle returned // by the DRV_AK4642_Open function. DRV_AK4642_SamplingRateSet(myAK4642Handle, 48000); //Sets 48000 media sampling rate Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 177 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine samplingRate Sampling frequency in Hz Function void DRV_AK4642_SamplingRateSet( DRV_HANDLE handle, uint32_t samplingRate) DRV_AK4642_VolumeGet Function This function gets the volume for AK4642 CODEC. File drv_ak4642.h C uint8_t DRV_AK4642_VolumeGet(DRV_HANDLE handle, DRV_AK4642_CHANNEL channel); Returns None. Description This functions gets the current volume programmed to the CODEC AK4642. Remarks None. Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 driver instance. DRV_AK4642_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t volume; // myAK4642Handle is the handle returned // by the DRV_AK4642_Open function. volume = DRV_AK4642_VolumeGet(myAK4642Handle, DRV_AK4642_CHANNEL_LEFT); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine channel argument indicating Left or Right or Both channel volume to be modified Function uint8_t DRV_AK4642_VolumeGet( DRV_HANDLE handle, DRV_AK4642_CHANNEL channel) DRV_AK4642_VolumeSet Function This function sets the volume for AK4642 CODEC. File drv_ak4642.h C void DRV_AK4642_VolumeSet(DRV_HANDLE handle, DRV_AK4642_CHANNEL channel, uint8_t volume); Returns None Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 178 Description This functions sets the volume value from 0-255. The codec has DAC value to volume range mapping as :- 00 H : +12dB FF H : -115dB In order to make the volume value to dB mapping monotonically increasing from 00 to FF, re-mapping is introduced which reverses the volume value to dB mapping as well as normalizes the volume range to a more audible dB range. The current driver implementation assumes that all dB values under -60 dB are inaudible to the human ear. Re-Mapped values 00 H : -60 dB FF H : +12 dB Remarks None. Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 driver instance. DRV_AK4642_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_BUFFER_HANDLE bufferHandle; // myAK4642Handle is the handle returned // by the DRV_AK4642_Open function. DRV_AK4642_VolumeSet(myAK4642Handle,DRV_AK4642_CHANNEL_LEFT, 120); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine channel argument indicating Left or Right or Both channel volume to be modified volume volume value specified in the range 0-255 (0x00 to 0xFF) Function void DRV_AK4642_VolumeSet( DRV_HANDLE handle, DRV_AK4642_CHANNEL channel, uint8_t volume); DRV_AK4642_IntExtMicSet Function This function sets up the codec for the internal or the external microphone use. File drv_ak4642.h C void DRV_AK4642_IntExtMicSet(DRV_HANDLE handle, DRV_AK4642_INT_EXT_MIC micInput); Returns None Description This function sets up the codec for the internal or the external microphone use. Remarks None. Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 driver instance. DRV_AK4642_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine micInput INT_MIC or EXT_MIC Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 179 Function void DRV_AK4642_IntExtMicSet( DRV_HANDLE handle, DRV_AK4642_INT_EXT_MIC micInput); DRV_AK4642_MonoStereoMicSet Function This function sets up the codec for the Mono or Stereo microphone mode. File drv_ak4642.h C void DRV_AK4642_MonoStereoMicSet(DRV_HANDLE handle, DRV_AK4642_MONO_STEREO_MIC mono_stereo_mic); Returns None Description This function sets up the codec for the Mono or Stereo microphone mode. Remarks Currently the ak4642 codec does not work in the MONO_LEFT_CHANNEL mode. This issue will be followed up with AKM. Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 driver instance. DRV_AK4642_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine mono_stereo_mic Mono / Stereo mic setup Function void DRV_AK4642_MonoStereoMicSet( DRV_HANDLE handle); DRV_AK4642_SetAudioCommunicationMode Function This function provides a run time audio format configuration File drv_ak4642.h C void DRV_AK4642_SetAudioCommunicationMode(DRV_HANDLE handle, const DATA_LENGTH dl, const SAMPLE_LENGTH sl); Returns None Description This function sets up audio mode in I2S protocol Remarks None. Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 driver instance. DRV_AK4642_Open must have been called to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 180 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine dl Data length for I2S audio interface sl Left/Right Sample Length for I2S audio interface Function void DRV_AK4642_SetAudioCommunicationMode ( DRV_HANDLE handle, const DATA_LENGTH dl, const SAMPLE_LENGTH sl ) DRV_AK4642_MicSet Function This function select the single-ended AK4642 microphone input for the AK4642 Codec File drv_ak4642.h C void DRV_AK4642_MicSet(DRV_HANDLE handle, DRV_AK4642_MIC micInput); Returns None Description This function selects the single-ended AK4642 microphone input for the AK4642 Codec (Where the MEMS mic is MIC1, and the external Microphone input is MIC2 on the AK4642 XC32 Daughter Board) Remarks None. Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 driver instance. DRV_AK4642_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine micInput MIC1 or MIC2 Function void DRV_AK4642_MicSet( DRV_HANDLE handle, DRV_AK4642_MIC micInput); d) Data Transfer Functions DRV_AK4642_BufferAddWrite Function Schedule a non-blocking driver write operation. File drv_ak4642.h C void DRV_AK4642_BufferAddWrite(const DRV_HANDLE handle, DRV_AK4642_BUFFER_HANDLE * bufferHandle, void * buffer, size_t size); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 181 Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_AK4642_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking write operation. The function returns with a valid buffer handle in the bufferHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance transmit queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_AK4642_BUFFER_HANDLE_INVALID: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0. • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_AK4642_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_AK4642_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the AK4642 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another AK4642 driver instance. It should not otherwise be called directly in an ISR. Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 device instance and the DRV_AK4642_Status must have returned SYS_STATUS_READY. DRV_AK4642_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE must have been specified in the DRV_AK4642_Open call. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK4642_BUFFER_HANDLE bufferHandle; // myAK4642Handle is the handle returned // by the DRV_AK4642_Open function. // Client registers an event handler with driver DRV_AK4642_BufferEventHandlerSet(myAK4642Handle, APP_AK4642BufferEventHandler, (uintptr_t)&myAppObj); DRV_AK4642_BufferAddWrite(myAK4642handle, &bufferHandle myBuffer, MY_BUFFER_SIZE); if(DRV_AK4642_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_AK4642BufferEventHandler(DRV_AK4642_BUFFER_EVENT event, DRV_AK4642_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_AK4642_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_AK4642_BUFFER_EVENT_ERROR: Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 182 // Error handling here. break; default: break; } } Parameters Parameters Description handle Handle of the AK4642 instance as return by the DRV_AK4642_Open function. buffer Data to be transmitted. size Buffer size in bytes. bufferHandle Pointer to an argument that will contain the return buffer handle. Function void DRV_AK4642_BufferAddWrite ( const DRV_HANDLE handle, DRV_AK4642_BUFFER_HANDLE *bufferHandle, void *buffer, size_t size ) DRV_AK4642_BufferAddRead Function Schedule a non-blocking driver read operation. File drv_ak4642.h C void DRV_AK4642_BufferAddRead(const DRV_HANDLE handle, DRV_AK4642_BUFFER_HANDLE * bufferHandle, void * buffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_AK4642_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking read operation. The function returns with a valid buffer handle in the bufferHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance receive queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_AK4642_BUFFER_HANDLE_INVALID • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0. • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_AK4642_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_AK4642_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the AK4642 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another AK4642 driver instance. It should not otherwise be called directly in an ISR. Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 device instance and the DRV_AK4642_Status must have returned SYS_STATUS_READY. DRV_AK4642_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ must have been specified in the DRV_AK4642_Open call. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 183 Parameters Parameters Description handle Handle of the AK4642 instance as return by the DRV_AK4642_Open function. buffer Data to be transmitted. size Buffer size in bytes. bufferHandle Pointer to an argument that will contain the return buffer handle. Function void DRV_AK4642_BufferAddRead ( const DRV_HANDLE handle, DRV_AK4642_BUFFER_HANDLE *bufferHandle, void *buffer, size_t size ) DRV_AK4642_BufferAddWriteRead Function Schedule a non-blocking driver write-read operation. Implementation: Dynamic File drv_ak4642.h C void DRV_AK4642_BufferAddWriteRead(const DRV_HANDLE handle, DRV_AK4642_BUFFER_HANDLE * bufferHandle, void * transmitBuffer, void * receiveBuffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_AK4642_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking write-read operation. The function returns with a valid buffer handle in the bufferHandle argument if the write-read request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_AK4642_BUFFER_EVENT_COMPLETE: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the client opened the driver for read only or write only • if the buffer size is 0 • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_AK4642_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_AK4642_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the AK4642 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another AK4642 driver instance. It should not otherwise be called directly in an ISR. This function is useful when there is valid read expected for every AK4642 write. The transmit and receive size must be same. Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 device instance and the DRV_AK4642_Status must have returned SYS_STATUS_READY. DRV_AK4642_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READWRITE must have been specified in the DRV_AK4642_Open call. Example MY_APP_OBJ myAppObj; uint8_t mybufferTx[MY_BUFFER_SIZE]; uint8_t mybufferRx[MY_BUFFER_SIZE]; Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 184 DRV_AK4642_BUFFER_HANDLE bufferHandle; // myak4642Handle is the handle returned // by the DRV_AK4642_Open function. // Client registers an event handler with driver DRV_AK4642_BufferEventHandlerSet(myak4642Handle, APP_AK4642BufferEventHandler, (uintptr_t)&myAppObj); DRV_AK4642_BufferAddWriteRead(myak4642handle, &bufferHandle, mybufferTx,mybufferRx,MY_BUFFER_SIZE); if(DRV_AK4642_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_AK4642BufferEventHandler(DRV_AK4642_BUFFER_EVENT event, DRV_AK4642_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_AK4642_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_AK4642_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle Handle of the AK4642 instance as returned by the DRV_AK4642_Open function bufferHandle Pointer to an argument that will contain the return buffer handle transmitBuffer The buffer where the transmit data will be stored receiveBuffer The buffer where the received data will be stored size Buffer size in bytes Function void DRV_AK4642_BufferAddWriteRead ( const DRV_HANDLE handle, DRV_AK4642_BUFFER_HANDLE *bufferHandle, void *transmitBuffer, void *receiveBuffer, size_t size ) DRV_AK4642_BufferEventHandlerSet Function This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 185 File drv_ak4642.h C void DRV_AK4642_BufferEventHandlerSet(DRV_HANDLE handle, const DRV_AK4642_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Returns None. Description This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. When a client calls DRV_AK4642_BufferAddWrite function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed. The event handler should be set before the client performs any "buffer add" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued buffer transfer has completed, it does not need to register a callback. Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 driver instance. DRV_AK4642_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK4642_BUFFER_HANDLE bufferHandle; // myAK4642Handle is the handle returned // by the DRV_AK4642_Open function. // Client registers an event handler with driver DRV_AK4642_BufferEventHandlerSet(myAK4642Handle, APP_AK4642BufferEventHandler, (uintptr_t)&myAppObj); DRV_AK4642_BufferAddWrite(myAK4642handle, &bufferHandle myBuffer, MY_BUFFER_SIZE); if(DRV_AK4642_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_AK4642BufferEventHandler(DRV_AK4642_BUFFER_EVENT event, DRV_AK4642_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_AK4642_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_AK4642_BUFFER_EVENT_ERROR: // Error handling here. break; Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 186 default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine eventHandler Pointer to the event handler function. context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_AK4642_BufferEventHandlerSet ( DRV_HANDLE handle, const DRV_AK4642_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle ) e) Other Functions DRV_AK4642_CommandEventHandlerSet Function This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. File drv_ak4642.h C void DRV_AK4642_CommandEventHandlerSet(DRV_HANDLE handle, const DRV_AK4642_COMMAND_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Returns None. Description This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. When a client calls DRV_AK4642_BufferAddWrite function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed. The event handler should be set before the client performs any "AK4642 CODEC Specific Client Routines" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the command has completed, it does not need to register a callback. Preconditions The DRV_AK4642_Initialize routine must have been called for the specified AK4642 driver instance. DRV_AK4642_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK4642_BUFFER_HANDLE bufferHandle; // myAK4642Handle is the handle returned Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 187 // by the DRV_AK4642_Open function. // Client registers an event handler with driver DRV_AK4642_CommandEventHandlerSet(myAK4642Handle, APP_AK4642CommandEventHandler, (uintptr_t)&myAppObj); DRV_AK4642_DeEmphasisFilterSet(myAK4642Handle, DRV_AK4642_DEEMPHASIS_FILTER_44_1KHZ) // Event is received when // the buffer is processed. void APP_AK4642CommandEventHandler(uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { // Last Submitted command is completed. // Perform further processing here } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine eventHandler Pointer to the event handler function. context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_AK4642_CommandEventHandlerSet ( DRV_HANDLE handle, const DRV_AK4642_COMMAND_EVENT_HANDLER eventHandler, const uintptr_t contextHandle ) DRV_AK4642_VersionGet Function This function returns the version of AK4642 driver File drv_ak4642.h C uint32_t DRV_AK4642_VersionGet(); Returns returns the version of AK4642 driver. Description The version number returned from the DRV_AK4642_VersionGet function is an unsigned integer in the following decimal format. * 10000 + * 100 + Where the numbers are represented in decimal and the meaning is the same as above. Note that there is no numerical representation of release type. Remarks None. Preconditions None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 188 Example 1 For version "0.03a", return: 0 * 10000 + 3 * 100 + 0 For version "1.00", return: 1 * 100000 + 0 * 100 + 0 Example 2 uint32_t AK4642version; AK4642version = DRV_AK4642_VersionGet(); Function uint32_t DRV_AK4642_VersionGet( void ) DRV_AK4642_VersionStrGet Function This function returns the version of AK4642 driver in string format. File drv_ak4642.h C int8_t* DRV_AK4642_VersionStrGet(); Returns returns a string containing the version of AK4642 driver. Description The DRV_AK4642_VersionStrGet function returns a string in the format: ".[.][]" Where: is the AK4642 driver's version number. is the AK4642 driver's version number. is an optional "patch" or "dot" release number (which is not included in the string if it equals "00"). is an optional release type ("a" for alpha, "b" for beta ? not the entire word spelled out) that is not included if the release is a production version (I.e. Not an alpha or beta). The String does not contain any spaces. For example, "0.03a" "1.00" Remarks None Preconditions None. Example int8_t *AK4642string; AK4642string = DRV_AK4642_VersionStrGet(); Function int8_t* DRV_AK4642_VersionStrGet(void) f) Data Types and Constants _DRV_AK4642_H Macro File drv_ak4642.h C #define _DRV_AK4642_H Description Include files. DRV_AK4642_BUFFER_HANDLE_INVALID Macro Definition of an invalid buffer handle. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 189 File drv_ak4642.h C #define DRV_AK4642_BUFFER_HANDLE_INVALID ((DRV_AK4642_BUFFER_HANDLE)(-1)) Description AK4642 Driver Invalid Buffer Handle This is the definition of an invalid buffer handle. An invalid buffer handle is returned by DRV_AK4642_BufferAddWrite() and the DRV_AK4642_BufferAddRead() function if the buffer add request was not successful. Remarks None. DRV_AK4642_COUNT Macro Number of valid AK4642 driver indices File drv_ak4642.h C #define DRV_AK4642_COUNT Description AK4642 Driver Module Count This constant identifies the maximum number of AK4642 Driver instances that should be defined by the application. Defining more instances than this constant will waste RAM memory space. This constant can also be used by the application to identify the number of AK4642 instances on this microcontroller. Remarks This value is part-specific. DRV_AK4642_INDEX_0 Macro AK4642 driver index definitions File drv_ak4642.h C #define DRV_AK4642_INDEX_0 0 Description Driver AK4642 Module Index These constants provide AK4642 driver index definition. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_AK4642_Initialize and DRV_AK4642_Open routines to identify the driver instance in use. DRV_AK4642_INDEX_1 Macro File drv_ak4642.h C #define DRV_AK4642_INDEX_1 1 Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 190 Description This is macro DRV_AK4642_INDEX_1. DRV_AK4642_INDEX_2 Macro File drv_ak4642.h C #define DRV_AK4642_INDEX_2 2 Description This is macro DRV_AK4642_INDEX_2. DRV_AK4642_INDEX_3 Macro File drv_ak4642.h C #define DRV_AK4642_INDEX_3 3 Description This is macro DRV_AK4642_INDEX_3. DRV_AK4642_INDEX_4 Macro File drv_ak4642.h C #define DRV_AK4642_INDEX_4 4 Description This is macro DRV_AK4642_INDEX_4. DRV_AK4642_INDEX_5 Macro File drv_ak4642.h C #define DRV_AK4642_INDEX_5 5 Description This is macro DRV_AK4642_INDEX_5. DRV_AK4642_AUDIO_DATA_FORMAT Enumeration Identifies the Serial Audio data interface format. File drv_ak4642.h C typedef enum { DRV_AK4642_AUDIO_DATA_FORMAT_NOT_APPLICABLE = 0, DRV_AK4642_AUDIO_DATA_FORMAT_16BITMSB_SDTO_16BITLSB_SDTI, DRV_AK4642_AUDIO_DATA_FORMAT_16BITMSB_SDTO_16BITMSB_SDTI, DRV_AK4642_AUDIO_DATA_FORMAT_I2S Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 191 } DRV_AK4642_AUDIO_DATA_FORMAT; Description AK4642 Audio data format This enumeration identifies Serial Audio data interface format. DRV_AK4642_BUFFER_EVENT Enumeration Identifies the possible events that can result from a buffer add request. File drv_ak4642.h C typedef enum { DRV_AK4642_BUFFER_EVENT_COMPLETE, DRV_AK4642_BUFFER_EVENT_ERROR, DRV_AK4642_BUFFER_EVENT_ABORT } DRV_AK4642_BUFFER_EVENT; Members Members Description DRV_AK4642_BUFFER_EVENT_COMPLETE Data was transferred successfully. DRV_AK4642_BUFFER_EVENT_ERROR Error while processing the request DRV_AK4642_BUFFER_EVENT_ABORT Data transfer aborted (Applicable in DMA mode) Description AK4642 Driver Events This enumeration identifies the possible events that can result from a buffer add request caused by the client calling either the DRV_AK4642_BufferAddWrite() or the DRV_AK4642_BufferAddRead() function. Remarks One of these values is passed in the "event" parameter of the event handling callback function that the client registered with the driver by calling the DRV_AK4642_BufferEventHandlerSet function when a buffer transfer request is completed. DRV_AK4642_BUFFER_EVENT_HANDLER Type Pointer to a AK4642 Driver Buffer Event handler function File drv_ak4642.h C typedef void (* DRV_AK4642_BUFFER_EVENT_HANDLER)(DRV_AK4642_BUFFER_EVENT event, DRV_AK4642_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle); Returns None. Description AK4642 Driver Buffer Event Handler Function This data type defines the required function signature for the AK4642 driver buffer event handling callback function. A client must register a pointer to a buffer event handling function who's function signature (parameter and return value types) match the types specified by this function pointer in order to receive buffer related event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks If the event is DRV_AK4642_BUFFER_EVENT_COMPLETE, this means that the data was transferred successfully. If the event is DRV_AK4642_BUFFER_EVENT_ERROR, this means that the data was not transferred successfully. The bufferHandle parameter contains the buffer handle of the buffer that failed. The DRV_AK4642_BufferProcessedSizeGet() function can be called to find out how many bytes were processed. The bufferHandle parameter contains the buffer handle of the buffer that associated with the event. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 192 The context parameter contains a handle to the client context, provided at the time the event handling function was registered using the DRV_AK4642_BufferEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the buffer add request. The buffer handle in bufferHandle expires after this event handler exits. In that the buffer object that was allocated is deallocated by the driver after the event handler exits. The event handler function executes in the data driver(i2S) peripheral's interrupt context when the driver is configured for interrupt mode operation. It is recommended of the application to not perform process intensive or blocking operations with in this function. DRV_AK4642_BufferAddWrite function can be called in the event handler to add a buffer to the driver queue. Example void APP_MyBufferEventHandler( DRV_AK4642_BUFFER_EVENT event, DRV_AK4642_BUFFER_HANDLE bufferHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_AK4642_BUFFER_EVENT_COMPLETE: // Handle the completed buffer. break; case DRV_AK4642_BUFFER_EVENT_ERROR: default: // Handle error. break; } } Parameters Parameters Description event Identifies the type of event bufferHandle Handle identifying the buffer to which the event relates context Value identifying the context of the application that registered the event handling function. DRV_AK4642_BUFFER_HANDLE Type Handle identifying a write buffer passed to the driver. File drv_ak4642.h C typedef uintptr_t DRV_AK4642_BUFFER_HANDLE; Description AK4642 Driver Buffer Handle A buffer handle value is returned by a call to the DRV_AK4642_BufferAddWrite() or DRV_AK4642_BufferAddRead() function. This handle is associated with the buffer passed into the function and it allows the application to track the completion of the data from (or into) that buffer. The buffer handle value returned from the "buffer add" function is returned back to the client by the "event handler callback" function registered with the driver. The buffer handle assigned to a client request expires when the client has been notified of the completion of the buffer transfer (after event handler function that notifies the client returns) or after the buffer has been retired by the driver if no event handler callback was set. Remarks None DRV_AK4642_CHANNEL Enumeration Identifies Left/Right Audio channel Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 193 File drv_ak4642.h C typedef enum { DRV_AK4642_CHANNEL_LEFT, DRV_AK4642_CHANNEL_RIGHT, DRV_AK4642_CHANNEL_LEFT_RIGHT, DRV_AK4642_NUMBER_OF_CHANNELS } DRV_AK4642_CHANNEL; Description AK4642 Audio Channel This enumeration identifies Left/Right Audio channel Remarks None. DRV_AK4642_COMMAND_EVENT_HANDLER Type Pointer to a AK4642 Driver Command Event Handler Function File drv_ak4642.h C typedef void (* DRV_AK4642_COMMAND_EVENT_HANDLER)(uintptr_t contextHandle); Returns None. Description AK4642 Driver Command Event Handler Function This data type defines the required function signature for the AK4642 driver command event handling callback function. A command is a control instruction to the AK4642 CODEC. Example Mute ON/OFF, Zero Detect Enable/Disable etc. A client must register a pointer to a command event handling function who's function signature (parameter and return value types) match the types specified by this function pointer in order to receive command related event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks The occurrence of this call back means that the last control command was transferred successfully. The context parameter contains a handle to the client context, provided at the time the event handling function was registered using the DRV_AK4642_CommandEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the buffer add request. The event handler function executes in the control data driver interrupt context. It is recommended of the application to not perform process intensive or blocking operations with in this function. Example void APP_AK4642CommandEventHandler( uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; // Last Submitted command is completed. // Perform further processing here } Parameters Parameters Description context Value identifying the context of the application that registered the event handling function. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 194 DRV_AK4642_INIT Structure Defines the data required to initialize or reinitialize the AK4642 driver File drv_ak4642.h C typedef struct { SYS_MODULE_INIT moduleInit; SYS_MODULE_INDEX i2sDriverModuleIndex; SYS_MODULE_INDEX i2cDriverModuleIndex; uint32_t samplingRate; uint8_t volume; DRV_AK4642_AUDIO_DATA_FORMAT audioDataFormat; } DRV_AK4642_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization SYS_MODULE_INDEX i2sDriverModuleIndex; Identifies data module(I2S) driver ID for data interface of CODEC SYS_MODULE_INDEX i2cDriverModuleIndex; Identifies data module(I2C) driver ID for control interface of CODEC uint32_t samplingRate; Sampling rate uint8_t volume; Volume DRV_AK4642_AUDIO_DATA_FORMAT audioDataFormat; Identifies the Audio data format Description AK4642 Driver Initialization Data This data type defines the data required to initialize or reinitialize the AK4642 CODEC driver. Remarks None. DRV_AK4642_INT_EXT_MIC Enumeration Identifies the Mic input source. File drv_ak4642.h C typedef enum { INT_MIC, EXT_MIC } DRV_AK4642_INT_EXT_MIC; Description AK4642 Mic Internal / External Input This enumeration identifies the Mic input source. DRV_AK4642_MONO_STEREO_MIC Enumeration Identifies the Mic input as Mono / Stereo. File drv_ak4642.h C typedef enum { ALL_ZEROS, MONO_RIGHT_CHANNEL, Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 195 MONO_LEFT_CHANNEL, STEREO } DRV_AK4642_MONO_STEREO_MIC; Description AK4642 Mic Mono / Stereo Input This enumeration identifies the Mic input as Mono / Stereo. DRV_AK4642_MIC Enumeration File drv_ak4642.h C typedef enum { MIC1 = 0, MIC2, DRV_AK4642_NUMBER_MIC } DRV_AK4642_MIC; Members Members Description MIC1 = 0 INT_MIC MIC2 EXT_MIC Description This is type DRV_AK4642_MIC. Files Files Name Description drv_ak4642.h AK4642 CODEC Driver Interface header file drv_ak4642_config_template.h AK4642 Codec Driver Configuration Template. Description This section lists the source and header files used by the AK4642 Codec Driver Library. drv_ak4642.h AK4642 CODEC Driver Interface header file Enumerations Name Description DRV_AK4642_AUDIO_DATA_FORMAT Identifies the Serial Audio data interface format. DRV_AK4642_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_AK4642_CHANNEL Identifies Left/Right Audio channel DRV_AK4642_INT_EXT_MIC Identifies the Mic input source. DRV_AK4642_MIC This is type DRV_AK4642_MIC. DRV_AK4642_MONO_STEREO_MIC Identifies the Mic input as Mono / Stereo. Functions Name Description DRV_AK4642_BufferAddRead Schedule a non-blocking driver read operation. DRV_AK4642_BufferAddWrite Schedule a non-blocking driver write operation. DRV_AK4642_BufferAddWriteRead Schedule a non-blocking driver write-read operation. Implementation: Dynamic DRV_AK4642_BufferEventHandlerSet This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 196 DRV_AK4642_Close Closes an opened-instance of the AK4642 driver DRV_AK4642_CommandEventHandlerSet This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. DRV_AK4642_Deinitialize Deinitializes the specified instance of the AK4642 driver module DRV_AK4642_Initialize Initializes hardware and data for the instance of the AK4642 DAC module DRV_AK4642_IntExtMicSet This function sets up the codec for the internal or the external microphone use. DRV_AK4642_MicSet This function select the single-ended AK4642 microphone input for the AK4642 Codec DRV_AK4642_MonoStereoMicSet This function sets up the codec for the Mono or Stereo microphone mode. DRV_AK4642_MuteOff This function disables AK4642 output for soft mute. DRV_AK4642_MuteOn This function allows AK4642 output for soft mute on. DRV_AK4642_Open Opens the specified AK4642 driver instance and returns a handle to it DRV_AK4642_SamplingRateGet This function gets the sampling rate set on the AK4642. Implementation: Dynamic DRV_AK4642_SamplingRateSet This function sets the sampling rate of the media stream. DRV_AK4642_SetAudioCommunicationMode This function provides a run time audio format configuration DRV_AK4642_Status Gets the current status of the AK4642 driver module. DRV_AK4642_Tasks Maintains the driver's control and data interface state machine. DRV_AK4642_VersionGet This function returns the version of AK4642 driver DRV_AK4642_VersionStrGet This function returns the version of AK4642 driver in string format. DRV_AK4642_VolumeGet This function gets the volume for AK4642 CODEC. DRV_AK4642_VolumeSet This function sets the volume for AK4642 CODEC. Macros Name Description _DRV_AK4642_H Include files. DRV_AK4642_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_AK4642_COUNT Number of valid AK4642 driver indices DRV_AK4642_INDEX_0 AK4642 driver index definitions DRV_AK4642_INDEX_1 This is macro DRV_AK4642_INDEX_1. DRV_AK4642_INDEX_2 This is macro DRV_AK4642_INDEX_2. DRV_AK4642_INDEX_3 This is macro DRV_AK4642_INDEX_3. DRV_AK4642_INDEX_4 This is macro DRV_AK4642_INDEX_4. DRV_AK4642_INDEX_5 This is macro DRV_AK4642_INDEX_5. Structures Name Description DRV_AK4642_INIT Defines the data required to initialize or reinitialize the AK4642 driver Types Name Description DRV_AK4642_BUFFER_EVENT_HANDLER Pointer to a AK4642 Driver Buffer Event handler function DRV_AK4642_BUFFER_HANDLE Handle identifying a write buffer passed to the driver. DRV_AK4642_COMMAND_EVENT_HANDLER Pointer to a AK4642 Driver Command Event Handler Function Description AK4642 CODEC Driver Interface The AK4642 CODEC device driver interface provides a simple interface to manage the AK4642 16/24-Bit CODEC that can be interfaced Microchip Microcontroller. This file provides the interface definition for the AK4642 CODEC device driver. File Name drv_ak4642.h Company Microchip Technology Inc. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 197 drv_ak4642_config_template.h AK4642 Codec Driver Configuration Template. Macros Name Description DRV_AK4642_BCLK_BIT_CLK_DIVISOR Sets up the BCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency DRV_AK4642_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_AK4642_INPUT_REFCLOCK Identifies the input REFCLOCK source to generate the MCLK to codec. DRV_AK4642_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_AK4642_MCLK_SAMPLE_FREQ_MULTPLIER Sets up the MCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency DRV_AK4642_MCLK_SOURCE Indicate the input clock frequency to generate the MCLK to codec. Description AK4642 Codec Driver Configuration Template These file provides the list of all the configurations that can be used with the driver. This file should not be included in the driver. File Name drv_ak4642_config_template.h Company Microchip Technology Inc. AK4953 Codec Driver Library This topic describes the AK4953 Codec Driver Library. Introduction This library provides an interface to manage the AK4953 Codec that is serially interfaced to a Microchip microcontroller for providing Audio Solutions. Description The AK4953 module is 16/24-bit Audio Codec from Asahi Kasei Microdevices Corporation. The AK4953 can be interfaced to Microchip microcontrollers through I2C and I2S serial interfaces. The I2C interface is used for control command transfer. The I2S interface is used for Audio data output. A typical interface of AK4953 to a Microchip PIC32 device is provided in the following diagram: Features The AK4953 Codec supports the following features: • Audio Interface Format: MSB first • ADC: 24-bit MSB justified, 16/24-bit I2S Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 198 • DAC: 24-bit MSB justified, 1-6bit LSB justified, 24-bit LSB justified, 16/24-bit I2S • Sampling Frequency Range: 8 kHz to 192 kHz • Digital Volume Control: +12dB ~ .115dB, 0.5dB Step • SoftMute: On and Off • Master Clock Frequencies: 32 fs/64 fs/128 fs/256 fs Using the Library This topic describes the basic architecture of the AK4953 Codec Driver Library and provides information and examples on its use. Description Interface Header File: drv_AK4953.h The interface to the AK4953 Codec Driver library is defined in the drv_AK4953.h header file. Any C language source (.c) file that uses the AK4953 Codec Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The AK4953 Codec Driver Library provides an API interface to transfer control commands and digital audio data to the serially interfaced AK4953 DAC module. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the AK4953 Codec Driver Library. Library Interface Section Description System Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Status Functions Provides status functions. Other Functions Provides driver specific miscellaneous functions such as sampling rate setting, control command functions, etc. Data Types and Constants These data types and constants are required while interacting and setting up the AK4953 Codec Driver Library. Abstraction Model This library provides a low-level abstraction of the AK4953 Codec Driver Library 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 abstraction model shown in the following diagram depicts how the AK4953 Codec Driver is positioned in the MPLAB Harmony framework. The AK4953 Codec Driver uses the SPI and I2S drivers for control and audio data transfers to the AK4953 module. AK4953 Driver Abstraction Model Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 199 How the Library Works The library provides interfaces to support: • System Functionality • Client Functionality System Access This topic describes system initialization, implementations, and includes a system access code example. Description System Initialization The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization, each instance of the AK4953 module would be initialized with the following configuration settings (either passed dynamically at run time using DRV_AK4953_INIT or by using Initialization Overrides) that are supported by the specific AK4953 device hardware: • Device requested power state: one of the System Module Power States. For specific details please refer to Data Types and Constants in the Library Interface section. • I2C driver module index. The module index should be same as the one used in initializing the I2C Driver. • I2S driver module index. The module index should be same as the one used in initializing the I2S Driver. • Sampling rate • Audio data format. The audio data format should match with the audio data format settings done in I2S driver initialization • Power down pin port initialization • Queue size for the audio data transmit buffer The DRV_AK4953_Initialize API returns an object handle of the type SYS_MODULE_OBJ. The object handle returned by the Initialize interface would be used by the other system interfaces such as DRV_ AK4953_Deinitialize, DRV_ AK4953_Status and DRV_I2S_Tasks. Implementations The AK4953 Codec Driver can has the following implementation: Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 200 Description MPLAB Harmony Components Dedicated hardware for control (I2C) and data (I2S) interface. Standard MPLAB Harmony drivers for I2C and I2S interfaces. Example: DRV_AK4953_INIT drvak4953Codec0InitData = { .moduleInit.value = SYS_MODULE_POWER_RUN_FULL, .i2sDriverModuleIndex = DRV_AK4953_I2S_DRIVER_MODULE_INDEX_IDX0, .i2cDriverModuleIndex = DRV_AK4953_I2C_DRIVER_MODULE_INDEX_IDX0, .volume = DRV_AK4953_VOLUME, .queueSizeTransmit = DRV_AK4953_TRANSMIT_QUEUE_SIZE, }; // Initialize the I2C driver DRV_I2C0_Initialize(); // Initialize the I2S driver. The I2S module index should be same as the one used in initializing // the I2S driver. sysObj.drvI2S0 = DRV_I2S_Initialize(DRV_I2S_INDEX_0, (SYS_MODULE_INIT *)&drvI2S0InitData); // Initialize the Codec driver sysObj.drvak4953Codec0 = DRV_AK4953_Initialize(DRV_AK4953_INDEX_0, (SYS_MODULE_INIT *)&drvak4953Codec0InitData); if (SYS_MODULE_OBJ_INVALID == AK4953DevObject) { // Handle error } Task Routine The DRV_AK4953_Tasks will be called from the System Task Service. Client Access For the application to start using an instance of the module, it must call the DRV_AK4953_Open function. The DRV_AK4953_Open provides a driver handle to the AK4953 Codec Driver instance for operations. If the driver is deinitialized using the function DRV_AK4953_Deinitialize, the application must call the DRV_AK4953_Open function again to set up the instance of the driver. For the various options available for IO_INTENT, please refer to Data Types and Constants in the Library Interface section. Client Operations This topic provides information on client operations and includes a control command and audio buffered data operation flow diagram. Description Client operations provide the API interface for control command and audio data transfer to the AK4953 Codec. The following AK4953 Codec specific control command functions are provided: • DRV_AK4953_SamplingRateSet • DRV_AK4953_SamplingRateGet • DRV_AK4953_VolumeSet • DRV_AK4953_VolumeGet • DRV_AK4953_MuteOn • DRV_AK4953_MuteOff • DRV_AK4953_IntExtMicSet • DRV_AK4953_MonoStereoMicSet These functions schedule a non-blocking control command transfer operation. These functions submit the control command request to the AK4953 Codec. These functions submit the control command request to I2C Driver transmit queue, the request is processed immediately if it is the first request, or processed when the previous request is complete. DRV_AK4953_BufferAddWrite, DRV_AK4953_BufferAddRead, and DRV_AK4953_BufferAddWriteRead are buffered data operation functions. These functions schedule non-blocking audio data transfer operations. These functions add the request to I2S Driver transmit or receive buffer queue depends on the request type, and are executed immediately if it is the first buffer, or executed later when the previous buffer is complete. The driver notifies the client with DRV_AK4953_BUFFER_EVENT_COMPLETE, DRV_AK4953_BUFFER_EVENT_ERROR, or DRV_AK4953_BUFFER_EVENT_ABORT events. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 201 The following diagram illustrates the control commands and audio buffered data operations. Note: It is not necessary to close and reopen the client between multiple transfers. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 202 Configuring the Library Macros Name Description DRV_AK4953_BCLK_BIT_CLK_DIVISOR Sets up the BCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency DRV_AK4953_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_AK4953_INPUT_REFCLOCK Identifies the input REFCLOCK source to generate the MCLK to codec. DRV_AK4953_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_AK4953_MCLK_SAMPLE_FREQ_MULTPLIER Sets up the MCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency DRV_AK4953_MCLK_SOURCE Indicate the input clock frequency to generate the MCLK to codec. DRV_AK4953_QUEUE_DEPTH_COMBINED Number of entries of all queues in all instances of the driver. Description The configuration of the AK4953 Codec Driver is based on the file system_config.h. This header file contains the configuration selection for the AK4953 Codec Driver. Based on the selections made, the driver may support the selected features. These configuration settings will apply to all instances of the AK4953 Codec Driver. This header can be placed anywhere, 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. DRV_AK4953_BCLK_BIT_CLK_DIVISOR Macro Sets up the BCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency File drv_ak4953_config_template.h C #define DRV_AK4953_BCLK_BIT_CLK_DIVISOR Description AK4953 BCLK to LRCK Ratio to Generate Audio Stream Sets up the BCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency Following BCLK to LRCK ratios are supported 16bit data 16 bit channel :- 32fs, hence divisor would be 8 16bit data 32 bit channel :- 64fs, hence divisor would be 4 Remarks None. DRV_AK4953_CLIENTS_NUMBER Macro Sets up the maximum number of clients that can be connected to any hardware instance. File drv_ak4953_config_template.h C #define DRV_AK4953_CLIENTS_NUMBER DRV_AK4953_INSTANCES_NUMBER Description AK4953 Client Count Configuration Sets up the maximum number of clients that can be connected to any hardware instance. Typically only one client could be connected to one hardware instance. This value represents the total number of clients to be supported across all hardware instances. Therefore, if there are five AK4953 hardware interfaces, this number will be 5. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 203 DRV_AK4953_INPUT_REFCLOCK Macro Identifies the input REFCLOCK source to generate the MCLK to codec. File drv_ak4953_config_template.h C #define DRV_AK4953_INPUT_REFCLOCK Description AK4953 Input reference clock Identifies the input REFCLOCK source to generate the MCLK to codec. Remarks None. DRV_AK4953_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported File drv_ak4953_config_template.h C #define DRV_AK4953_INSTANCES_NUMBER Description AK4953 driver objects configuration Sets up the maximum number of hardware instances that can be supported. It is recommended that this number be set exactly equal to the number of AK4953 CODEC modules that are needed by the application. Hardware Instance support consumes RAM memory space. If this macro is not defined, then the driver will be built statically. Remarks None. DRV_AK4953_MCLK_SAMPLE_FREQ_MULTPLIER Macro Sets up the MCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency File drv_ak4953_config_template.h C #define DRV_AK4953_MCLK_SAMPLE_FREQ_MULTPLIER Description AK4953 MCLK to LRCK Ratio to Generate Audio Stream Sets up the MCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency I2S sampling frequency Supported MCLK to Sampling frequency Ratios are as below 256fs, 384fs, 512fs, 768fs or 1152fs Remarks None DRV_AK4953_MCLK_SOURCE Macro Indicate the input clock frequency to generate the MCLK to codec. File drv_ak4953_config_template.h Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 204 C #define DRV_AK4953_MCLK_SOURCE Description AK4953 Data Interface Master Clock Speed configuration Indicate the input clock frequency to generate the MCLK to codec. Remarks None. DRV_AK4953_QUEUE_DEPTH_COMBINED Macro Number of entries of all queues in all instances of the driver. File drv_ak4953_config_template.h C #define DRV_AK4953_QUEUE_DEPTH_COMBINED Description AK4953 Driver Buffer Queue Entries This macro defined the number of entries of all queues in all instances of the driver. Each hardware instance supports a buffer queue for transmit operations. The size of queue is specified either in driver initialization (for dynamic build) or by macros (for static build). The hardware instance transmit buffer queue will queue transmit buffers submitted by the DRV_AK4953_BufferAddWrite function. A buffer queue will contains buffer queue entries, each related to a BufferAdd request. This configuration macro defines total number of buffer entries that will be available for use between all AK4953 driver hardware instances. The buffer queue entries are allocated to individual hardware instances as requested by hardware instances. Once the request is processed, the buffer queue entry is free for use by other hardware instances. The total number of buffer entries in the system determines the ability of the driver to service non blocking write requests. If a free buffer entry is not available, the driver will not add the request and will return an invalid buffer handle. More the number of buffer entries, greater the ability of the driver to service and add requests to its queue. A hardware instance additionally can queue up as many buffer entries as specified by its transmit buffer queue size. As an example, consider the case of static single client driver application where full duplex non blocking operation is desired without queuing, the minimum transmit queue depth and minimum receive queue depth should be 1. Hence the total number of buffer entries should be 2. As an example, consider the case of a dynamic driver (say two instances) where instance one will queue up to three write requests and up to two read requests, and instance two will queue up to two write requests and up to six read requests, the value of this macro should be 13 (2 + 3 + 2 + 6). Configuring the MHC Provides examples on how to configure the MPLAB Harmony Configurator (MHC) for a specific driver. Description The following three figures show examples of MHC configurations for the AK4953 Codec Driver, I2S Driver, and the I2C Driver. Figure 1: AK4953 Codec Driver MHC Configuration Figure 2: I2S Driver MHC Configuration Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 205 Figure 3: I2C Driver MHC Configuration Migrating the AK4953 Driver From Earlier Versions of Microchip Harmony Prior to version 1.08 of MPLAB Harmony, the AK4953 Codec Driver Library used the static I2C driver implementation. Beginning with v1.08 of MPLAB Harmony, applications must use the Dynamic Driver implementation with the MHC configured as shown in Figure 3. In addition, PIC32MZ configurations require the "Include Force Write I2C Function (Master Mode Only - Ignore NACK from Slave)" option to be selected. Building the Library This section lists the files that are available in the AK4953 Codec Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 206 Description This section list the files that are available in the /src folder of the AK4953 Codec 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. 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 /framework/driver/codec/ak4953. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_ak4953.h Header file that exports the driver API. 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 /src/dynamic/drv_ak4953.c This file contains implementation of the AK4953 Codec Driver. 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 N/A No optional files are available for this library. Module Dependencies The AK4953 Codec Driver Library depends on the following modules: • I2S Driver Library • I2C Driver Library Library Interface a) System Interaction Functions Name Description DRV_AK4953_Initialize Initializes hardware and data for the instance of the AK4953 DAC module. Implementation: Dynamic DRV_AK4953_Deinitialize Deinitializes the specified instance of the AK4953 driver module. Implementation: Dynamic DRV_AK4953_Open Opens the specified AK4953 driver instance and returns a handle to it. Implementation: Dynamic DRV_AK4953_Close Closes an opened-instance of the AK4953 driver. Implementation: Dynamic DRV_AK4953_Tasks Maintains the driver's control and data interface state machine. Implementation: Dynamic DRV_AK4953_CommandEventHandlerSet This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. Implementation: Dynamic DRV_AK4953_BufferEventHandlerSet This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. DRV_AK4953_SamplingRateSet This function sets the sampling rate of the media stream. Implementation: Dynamic DRV_AK4953_SetAudioCommunicationMode This function provides a run time audio format configuration Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 207 b) Status Functions Name Description DRV_AK4953_SamplingRateGet This function gets the sampling rate set on the DAC AK4953. Implementation: Dynamic DRV_AK4953_Status Gets the current status of the AK4953 driver module. Implementation: Dynamic DRV_AK4953_VersionGet This function returns the version of AK4953 driver. Implementation: Dynamic DRV_AK4953_VersionStrGet This function returns the version of AK4953 driver in string format. Implementation: Dynamic DRV_AK4953_VolumeGet This function gets the volume for AK4953 CODEC. Implementation: Dynamic c) Other Functions Name Description DRV_AK4953_BufferAddWrite Schedule a non-blocking driver write operation. Implementation: Dynamic DRV_AK4953_BufferAddWriteRead Schedule a non-blocking driver write-read operation. Implementation: Dynamic DRV_AK4953_MuteOff This function disables AK4953 output for soft mute. Implementation: Dynamic DRV_AK4953_MuteOn This function allows AK4953 output for soft mute on. Implementation: Dynamic DRV_AK4953_VolumeSet This function sets the volume for AK4953 CODEC. Implementation: Dynamic DRV_AK4953_BufferAddRead Schedule a non-blocking driver read operation. DRV_AK4953_IntExtMicSet This function sets up the codec for the X32 DB internal or the external microphone use. DRV_AK4953_MonoStereoMicSet This function sets up the codec for the Mono or Stereo microphone mode. DRV_AK4953_MicSet This function sets up the codec for the internal or the AK4953 Mic1 or Mic2 input. d) Data Types and Constants Name Description DRV_AK4953_AUDIO_DATA_FORMAT Identifies the Serial Audio data interface format. DRV_AK4953_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_AK4953_BUFFER_EVENT_HANDLER Pointer to a AK4953 Driver Buffer Event handler function DRV_AK4953_BUFFER_HANDLE Handle identifying a write buffer passed to the driver. DRV_AK4953_COMMAND_EVENT_HANDLER Pointer to a AK4953 Driver Command Event Handler Function DRV_AK4953_DIGITAL_BLOCK_CONTROL Identifies Bass-Boost Control function DRV_AK4953_INIT Defines the data required to initialize or reinitialize the AK4953 driver _DRV_AK4953_H Include files. DRV_AK4953_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_AK4953_COUNT Number of valid AK4953 driver indices DRV_AK4953_INDEX_0 AK4953 driver index definitions DRV_AK4953_INDEX_1 This is macro DRV_AK4953_INDEX_1. DRV_AK4953_INDEX_2 This is macro DRV_AK4953_INDEX_2. DRV_AK4953_INDEX_3 This is macro DRV_AK4953_INDEX_3. DRV_AK4953_INDEX_4 This is macro DRV_AK4953_INDEX_4. DRV_AK4953_INDEX_5 This is macro DRV_AK4953_INDEX_5. DRV_AK4953_CHANNEL Identifies Left/Right Audio channel DRV_AK4953_INT_EXT_MIC Identifies the Mic input source. DRV_AK4953_MONO_STEREO_MIC Identifies the Mic input as Mono / Stereo. DRV_AK4953_MIC This is type DRV_AK4953_MIC. Description This section describes the API functions of the AK4953 Codec Driver library. Refer to each section for a detailed description. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 208 a) System Interaction Functions DRV_AK4953_Initialize Function Initializes hardware and data for the instance of the AK4953 DAC module. Implementation: Dynamic File drv_ak4953.h C SYS_MODULE_OBJ DRV_AK4953_Initialize(const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the AK4953 driver instance for the specified driver index, making it ready for clients to open and use it. The initialization data is specified by the init parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. Remarks This routine must be called before any other AK4953 routine is called. This routine should only be called once during system initialization unless DRV_AK4953_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. Preconditions DRV_I2S_Initialize must be called before calling this function to initialize the data interface of this CODEC driver. Also DRV_I2C_Initialize must be called before calling this function to initialize the control interface of this CODEC driver. Example DRV_AK4953_INIT init; SYS_MODULE_OBJ objectHandle; init->inUse = true; init->status = SYS_STATUS_BUSY; init->numClients = 0; init->i2sDriverModuleIndex = ak4953Init->i2sDriverModuleIndex; init->i2cDriverModuleIndex = ak4953Init->i2cDriverModuleIndex; init->samplingRate = DRV_AK4953_AUDIO_SAMPLING_RATE; init->audioDataFormat = DRV_AK4953_AUDIO_DATA_FORMAT_MACRO; for(index=0; index < DRV_AK4953_NUMBER_OF_CHANNELS; index++) { init->volume[index] = ak4953Init->volume; } init->isInInterruptContext = false; init->commandCompleteCallback = (DRV_AK4953_COMMAND_EVENT_HANDLER)0; init->commandContextData = 0; init->mclk_multiplier = DRV_AK4953_MCLK_SAMPLE_FREQ_MULTPLIER; objectHandle = DRV_AK4953_Initialize(DRV_AK4953_0, (SYS_MODULE_INIT*)init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description drvIndex Identifier for the driver instance to be initialized Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 209 init Pointer to the data structure containing any data necessary to initialize the hardware. This pointer may be null if no data is required and default initialization is to be used. Function SYS_MODULE_OBJ DRV_AK4953_Initialize ( const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT *const init ); DRV_AK4953_Deinitialize Function Deinitializes the specified instance of the AK4953 driver module. Implementation: Dynamic File drv_ak4953.h C void DRV_AK4953_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the AK4953 driver module, disabling its operation (and any hardware). Invalidates all the internal data. Remarks Once the Initialize operation has been called, the De-initialize operation must be called before the Initialize operation can be called again. This routine will NEVER block waiting for hardware. Preconditions Function DRV_AK4953_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_AK4953_Initialize SYS_STATUS status; DRV_AK4953_Deinitialize(object); status = DRV_AK4953_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from the DRV_AK4953_Initialize routine Function void DRV_AK4953_Deinitialize( SYS_MODULE_OBJ object) DRV_AK4953_Open Function Opens the specified AK4953 driver instance and returns a handle to it. Implementation: Dynamic File drv_ak4953.h Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 210 C DRV_HANDLE DRV_AK4953_Open(const SYS_MODULE_INDEX iDriver, const DRV_IO_INTENT ioIntent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Error can occur • if the number of client objects allocated via DRV_AK4953_CLIENTS_NUMBER is insufficient. • if the client is trying to open the driver but driver has been opened exclusively by another client. • if the driver hardware instance being opened is not initialized or is invalid. • if the ioIntent options passed are not relevant to this driver. Description This routine opens the specified AK4953 driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. The DRV_IO_INTENT_BLOCKING and DRV_IO_INTENT_NONBLOCKING ioIntent options are not relevant to this driver. All the data transfer functions of this driver are non blocking. AK4953 can be opened with DRV_IO_INTENT_WRITE, or DRV_IO_INTENT_READ or DRV_IO_INTENT_WRITEREAD io_intent option. This decides whether the driver is used for headphone output, or microphone input or both modes simultaneously. Specifying a DRV_IO_INTENT_EXCLUSIVE will cause the driver to provide exclusive access to this client. The driver cannot be opened by any other client. Remarks The handle returned is valid until the DRV_AK4953_Close routine is called. This routine will NEVER block waiting for hardware.If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. It should not be called in an ISR. Preconditions Function DRV_AK4953_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_AK4953_Open(DRV_AK4953_INDEX_0, DRV_IO_INTENT_WRITEREAD | DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver // May be the driver is not initialized or the initialization // is not complete. } Parameters Parameters Description drvIndex Identifier for the object instance to be opened ioIntent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver. See function description for details. Function DRV_HANDLE DRV_AK4953_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent ) DRV_AK4953_Close Function Closes an opened-instance of the AK4953 driver. Implementation: Dynamic File drv_ak4953.h Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 211 C void DRV_AK4953_Close(const DRV_HANDLE handle); Returns None. Description This routine closes an opened-instance of the AK4953 driver, invalidating the handle. Any buffers in the driver queue that were submitted by this client will be removed. After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_AK4953_Open before the caller may use the driver again Remarks Usually there is no need for the driver client to verify that the Close operation has completed. The driver will abort any ongoing operations when this routine is called. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 driver instance. DRV_AK4953_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_AK4953_Open DRV_AK4953_Close(handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4953_Close( DRV_Handle handle ) DRV_AK4953_Tasks Function Maintains the driver's control and data interface state machine. Implementation: Dynamic File drv_ak4953.h C void DRV_AK4953_Tasks(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal control and data interface state machine and implement its control and data interface implementations. This function should be called from the SYS_Tasks() function. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks). Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_AK4953_Initialize while (true) { DRV_AK4953_Tasks (object); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 212 // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_AK4953_Initialize) Function void DRV_AK4953_Tasks(SYS_MODULE_OBJ object); DRV_AK4953_CommandEventHandlerSet Function This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. Implementation: Dynamic File drv_ak4953.h C void DRV_AK4953_CommandEventHandlerSet(DRV_HANDLE handle, const DRV_AK4953_COMMAND_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Returns None. Description This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. When a client calls DRV_AK4953_BufferAddWrite function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed. The event handler should be set before the client performs any "AK4953 CODEC Specific Client Routines" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the command has completed, it does not need to register a callback. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 driver instance. DRV_AK4953_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK4953_BUFFER_HANDLE bufferHandle; // myAK4953Handle is the handle returned // by the DRV_AK4953_Open function. // Client registers an event handler with driver DRV_AK4953_CommandEventHandlerSet(myAK4953Handle, APP_AK4953CommandEventHandler, (uintptr_t)&myAppObj); DRV_AK4953_DeEmphasisFilterSet(myAK4953Handle, DRV_AK4953_DEEMPHASIS_FILTER_44_1KHZ) // Event is received when // the buffer is processed. void APP_AK4953CommandEventHandler(uintptr_t contextHandle) { // contextHandle points to myAppObj. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 213 switch(event) { // Last Submitted command is completed. // Perform further processing here } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine eventHandler Pointer to the event handler function. context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_AK4953_CommandEventHandlerSet ( DRV_HANDLE handle, const DRV_AK4953_COMMAND_EVENT_HANDLER eventHandler, const uintptr_t contextHandle ) DRV_AK4953_BufferEventHandlerSet Function This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. File drv_ak4953.h C void DRV_AK4953_BufferEventHandlerSet(DRV_HANDLE handle, const DRV_AK4953_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Returns None. Description This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. When a client calls DRV_AK4953_BufferAddRead function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed. The event handler should be set before the client performs any "buffer add" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued buffer transfer has completed, it does not need to register a callback. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 driver instance. DRV_AK4953_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK4953_BUFFER_HANDLE bufferHandle; // myAK4953Handle is the handle returned // by the DRV_AK4953_Open function. // Client registers an event handler with driver DRV_AK4953_BufferEventHandlerSet(myAK4953Handle, Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 214 APP_AK4953BufferEventHandler, (uintptr_t)&myAppObj); DRV_AK4953_BufferAddRead(myAK4953handle, &bufferHandle myBuffer, MY_BUFFER_SIZE); if(DRV_AK4953_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_AK4953BufferEventHandler(DRV_AK4953_BUFFER_EVENT event, DRV_AK4953_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_AK4953_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_AK4953_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine eventHandler Pointer to the event handler function. context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_AK4953_BufferEventHandlerSet ( DRV_HANDLE handle, const DRV_AK4953_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle ) DRV_AK4953_SamplingRateSet Function This function sets the sampling rate of the media stream. Implementation: Dynamic File drv_ak4953.h C void DRV_AK4953_SamplingRateSet(DRV_HANDLE handle, uint32_t samplingRate); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 215 Returns None. Description This function sets the media sampling rate for the client handle. Remarks None. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 driver instance. DRV_AK4953_Open must have been called to obtain a valid opened device handle. Example // myAK4953Handle is the handle returned // by the DRV_AK4953_Open function. DRV_AK4953_SamplingRateSet(myAK4953Handle, 48000); //Sets 48000 media sampling rate Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4953_SamplingRateSet( DRV_HANDLE handle, uint32_t samplingRate) DRV_AK4953_SetAudioCommunicationMode Function This function provides a run time audio format configuration File drv_ak4953.h C void DRV_AK4953_SetAudioCommunicationMode(DRV_HANDLE handle, const DATA_LENGTH dl, const SAMPLE_LENGTH sl); Returns None Description This function sets up audio mode in I2S protocol Remarks None. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 driver instance. DRV_AK4953_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine dl Data length for I2S audio interface sl Left/Right Sample Length for I2S audio interface Function void DRV_AK4953_SetAudioCommunicationMode ( DRV_HANDLE handle, const DATA_LENGTH dl, Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 216 const SAMPLE_LENGTH sl ) b) Status Functions DRV_AK4953_SamplingRateGet Function This function gets the sampling rate set on the DAC AK4953. Implementation: Dynamic File drv_ak4953.h C uint32_t DRV_AK4953_SamplingRateGet(DRV_HANDLE handle); Returns None. Description This function gets the sampling rate set on the DAC AK4953. Remarks None. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 driver instance. DRV_AK4953_Open must have been called to obtain a valid opened device handle. Example uint32_t baudRate; // myAK4953Handle is the handle returned // by the DRV_AK4953_Open function. baudRate = DRV_AK4953_SamplingRateGet(myAK4953Handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function uint32_t DRV_AK4953_SamplingRateGet( DRV_HANDLE handle) DRV_AK4953_Status Function Gets the current status of the AK4953 driver module. Implementation: Dynamic File drv_ak4953.h C SYS_STATUS DRV_AK4953_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_DEINITIALIZED - Indicates that the driver has been deinitialized SYS_STATUS_READY - Indicates that any previous module operation for the specified module has completed SYS_STATUS_BUSY - Indicates that a previous module operation for the specified module has not yet completed SYS_STATUS_ERROR - Indicates that the specified module is in an error state Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 217 Description This routine provides the current status of the AK4953 driver module. Remarks A driver can opened only when its status is SYS_STATUS_READY. Preconditions Function DRV_AK4953_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_AK4953_Initialize SYS_STATUS AK4953Status; AK4953Status = DRV_AK4953_Status(object); if (SYS_STATUS_READY == AK4953Status) { // This means the driver can be opened using the // DRV_AK4953_Open() function. } Parameters Parameters Description object Driver object handle, returned from the DRV_AK4953_Initialize routine Function SYS_STATUS DRV_AK4953_Status( SYS_MODULE_OBJ object) DRV_AK4953_VersionGet Function This function returns the version of AK4953 driver. Implementation: Dynamic File drv_ak4953.h C uint32_t DRV_AK4953_VersionGet(); Returns returns the version of AK4953 driver. Description The version number returned from the DRV_AK4953_VersionGet function is an unsigned integer in the following decimal format. * 10000 + * 100 + Where the numbers are represented in decimal and the meaning is the same as above. Note that there is no numerical representation of release type. Remarks None. Preconditions None. Example 1 For version "0.03a", return: 0 * 10000 + 3 * 100 + 0 For version "1.00", return: 1 * 100000 + 0 * 100 + 0 Example 2 uint32_t AK4953version; AK4953version = DRV_AK4953_VersionGet(); Function uint32_t DRV_AK4953_VersionGet( void ) Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 218 DRV_AK4953_VersionStrGet Function This function returns the version of AK4953 driver in string format. Implementation: Dynamic File drv_ak4953.h C int8_t* DRV_AK4953_VersionStrGet(); Returns returns a string containing the version of AK4953 driver. Description The DRV_AK4953_VersionStrGet function returns a string in the format: ".[.][]" Where: is the AK4953 driver's version number. is the AK4953 driver's version number. is an optional "patch" or "dot" release number (which is not included in the string if it equals "00"). is an optional release type ("a" for alpha, "b" for beta ? not the entire word spelled out) that is not included if the release is a production version (I.e. Not an alpha or beta). The String does not contain any spaces. Remarks None. Preconditions None. Example 1 "0.03a" "1.00" Example 2 int8_t *AK4953string; AK4953string = DRV_AK4953_VersionStrGet(); Function int8_t* DRV_AK4953_VersionStrGet(void) DRV_AK4953_VolumeGet Function This function gets the volume for AK4953 CODEC. Implementation: Dynamic File drv_ak4953.h C uint8_t DRV_AK4953_VolumeGet(DRV_HANDLE handle, DRV_AK4953_CHANNEL chan); Returns None. Description This functions gets the current volume programmed to the CODEC AK4953. Remarks None. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 driver instance. DRV_AK4953_Open must have been called to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 219 Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t volume; // myAK4953Handle is the handle returned // by the DRV_AK4953_Open function. volume = DRV_AK4953_VolumeGet(myAK4953Handle,DRV_AK4953_CHANNEL_LEFT); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine chan Audio channel volume to be set Function uint8_t DRV_AK4953_VolumeGet( DRV_HANDLE handle, DRV_AK4953_CHANNEL chan) c) Other Functions DRV_AK4953_BufferAddWrite Function Schedule a non-blocking driver write operation. Implementation: Dynamic File drv_ak4953.h C void DRV_AK4953_BufferAddWrite(const DRV_HANDLE handle, DRV_AK4953_BUFFER_HANDLE * bufferHandle, void * buffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_AK4953_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking write operation. The function returns with a valid buffer handle in the bufferHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance transmit queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_AK4953_BUFFER_HANDLE_INVALID • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0. • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_AK4953_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_AK4953_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the AK4953 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another AK4953 driver instance. It should not otherwise be called directly in an ISR. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 device instance and the DRV_AK4953_Status must have returned SYS_STATUS_READY. DRV_AK4953_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE must have been specified in the DRV_AK4953_Open call. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 220 Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK4953_BUFFER_HANDLE bufferHandle; // myAK4953Handle is the handle returned // by the DRV_AK4953_Open function. // Client registers an event handler with driver DRV_AK4953_BufferEventHandlerSet(myAK4953Handle, APP_AK4953BufferEventHandler, (uintptr_t)&myAppObj); DRV_AK4953_BufferAddWrite(myAK4953handle, &bufferHandle myBuffer, MY_BUFFER_SIZE); if(DRV_AK4953_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_AK4953BufferEventHandler(DRV_AK4953_BUFFER_EVENT event, DRV_AK4953_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_AK4953_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_AK4953_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle Handle of the AK4953 instance as return by the DRV_AK4953_Open function. buffer Data to be transmitted. size Buffer size in bytes. bufferHandle Pointer to an argument that will contain the return buffer handle. Function void DRV_AK4953_BufferAddWrite ( const DRV_HANDLE handle, DRV_AK4953_BUFFER_HANDLE *bufferHandle, void *buffer, size_t size ) DRV_AK4953_BufferAddWriteRead Function Schedule a non-blocking driver write-read operation. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 221 Implementation: Dynamic File drv_ak4953.h C void DRV_AK4953_BufferAddWriteRead(const DRV_HANDLE handle, DRV_AK4953_BUFFER_HANDLE * bufferHandle, void * transmitBuffer, void * receiveBuffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_AK4953_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking write-read operation. The function returns with a valid buffer handle in the bufferHandle argument if the write-read request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_AK4953_BUFFER_EVENT_COMPLETE: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the client opened the driver for read only or write only • if the buffer size is 0 • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_AK4953_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_AK4953_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the AK4953 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another AK4953 driver instance. It should not otherwise be called directly in an ISR. This function is useful when there is valid read expected for every AK4953 write. The transmit and receive size must be same. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 device instance and the DRV_AK4953_Status must have returned SYS_STATUS_READY. DRV_AK4953_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READWRITE must have been specified in the DRV_AK4953_Open call. Example MY_APP_OBJ myAppObj; uint8_t mybufferTx[MY_BUFFER_SIZE]; uint8_t mybufferRx[MY_BUFFER_SIZE]; DRV_AK4953_BUFFER_HANDLE bufferHandle; // myak4953Handle is the handle returned // by the DRV_AK4953_Open function. // Client registers an event handler with driver DRV_AK4953_BufferEventHandlerSet(myak4953Handle, APP_AK4953BufferEventHandler, (uintptr_t)&myAppObj); DRV_AK4953_BufferAddWriteRead(myak4953handle, &bufferHandle, mybufferTx,mybufferRx,MY_BUFFER_SIZE); if(DRV_AK4953_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_AK4953BufferEventHandler(DRV_AK4953_BUFFER_EVENT event, DRV_AK4953_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 222 { // contextHandle points to myAppObj. switch(event) { case DRV_AK4953_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_AK4953_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle Handle of the AK4953 instance as returned by the DRV_AK4953_Open function bufferHandle Pointer to an argument that will contain the return buffer handle transmitBuffer The buffer where the transmit data will be stored receiveBuffer The buffer where the received data will be stored size Buffer size in bytes Function void DRV_AK4953_BufferAddWriteRead ( const DRV_HANDLE handle, DRV_AK4953_BUFFER_HANDLE *bufferHandle, void *transmitBuffer, void *receiveBuffer, size_t size ) DRV_AK4953_MuteOff Function This function disables AK4953 output for soft mute. Implementation: Dynamic File drv_ak4953.h C void DRV_AK4953_MuteOff(DRV_HANDLE handle); Returns None. Description This function disables AK4953 output for soft mute. Remarks None. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 driver instance. DRV_AK4953_Open must have been called to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 223 Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_BUFFER_HANDLE bufferHandle; // myAK4953Handle is the handle returned // by the DRV_AK4953_Open function. DRV_AK4953_MuteOff(myAK4953Handle); //AK4953 output soft mute disabled Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4953_MuteOff( DRV_HANDLE handle) DRV_AK4953_MuteOn Function This function allows AK4953 output for soft mute on. Implementation: Dynamic File drv_ak4953.h C void DRV_AK4953_MuteOn(DRV_HANDLE handle); Returns None. Description This function Enables AK4953 output for soft mute. Remarks None. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 driver instance. DRV_AK4953_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_BUFFER_HANDLE bufferHandle; // myAK4953Handle is the handle returned // by the DRV_AK4953_Open function. DRV_AK4953_MuteOn(myAK4953Handle); //AK4953 output soft muted Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4953_MuteOn( DRV_HANDLE handle); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 224 DRV_AK4953_VolumeSet Function This function sets the volume for AK4953 CODEC. Implementation: Dynamic File drv_ak4953.h C void DRV_AK4953_VolumeSet(DRV_HANDLE handle, DRV_AK4953_CHANNEL channel, uint8_t volume); Returns None. Description This functions sets the volume value from 0-255. The codec has DAC value to volume range mapping as :- 00 H : +12dB FF H : -115dB In order to make the volume value to dB mapping monotonically increasing from 00 to FF, re-mapping is introduced which reverses the volume value to dB mapping as well as normalizes the volume range to a more audible dB range. The current driver implementation assumes that all dB values under -60 dB are inaudible to the human ear. Re-Mapped values 00 H : -60 dB FF H : +12 dB Remarks None. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 driver instance. DRV_AK4953_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_BUFFER_HANDLE bufferHandle; // myAK4953Handle is the handle returned // by the DRV_AK4953_Open function. DRV_AK4953_VolumeSet(myAK4953Handle, DRV_AK4953_CHANNEL_LEFT, 120); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine chan Audio channel volume to be set volume volume value specified in the range 0-255 (0x00 to 0xFF) Function void DRV_AK4953_VolumeSet( DRV_HANDLE handle, DRV_AK4953_CHANNEL channel, uint8_t volume); DRV_AK4953_BufferAddRead Function Schedule a non-blocking driver read operation. File drv_ak4953.h C void DRV_AK4953_BufferAddRead(const DRV_HANDLE handle, DRV_AK4953_BUFFER_HANDLE * bufferHandle, void * buffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_AK4953_BUFFER_HANDLE_INVALID if the function was not successful. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 225 Description This function schedules a non-blocking read operation. The function returns with a valid buffer handle in the bufferHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance receive queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_AK4953_BUFFER_HANDLE_INVALID • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0. • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_AK4953_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_AK4953_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the AK4953 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another AK4953 driver instance. It should not otherwise be called directly in an ISR. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 device instance and the DRV_AK4953_Status must have returned SYS_STATUS_READY. DRV_AK4953_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ must have been specified in the DRV_AK4953_Open call. Parameters Parameters Description handle Handle of the AK4953 instance as return by the DRV_AK4953_Open function. buffer Data to be transmitted. size Buffer size in bytes. bufferHandle Pointer to an argument that will contain the return buffer handle. Function void DRV_AK4953_BufferAddRead ( const DRV_HANDLE handle, DRV_AK4953_BUFFER_HANDLE *bufferHandle, void *buffer, size_t size ) DRV_AK4953_IntExtMicSet Function This function sets up the codec for the X32 DB internal or the external microphone use. File drv_ak4953.h C void DRV_AK4953_IntExtMicSet(DRV_HANDLE handle, DRV_AK4953_INT_EXT_MIC micInput); Returns None Description This function sets up the codec for the internal or the external microphone use. Remarks None. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 driver instance. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 226 DRV_AK4953_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine micInput Internal vs External mic input Function void DRV_AK4953_IntExtMicSet DRV_AK4953_MonoStereoMicSet Function This function sets up the codec for the Mono or Stereo microphone mode. File drv_ak4953.h C void DRV_AK4953_MonoStereoMicSet(DRV_HANDLE handle, DRV_AK4953_MONO_STEREO_MIC mono_stereo_mic); Returns None Description This function sets up the codec for the Mono or Stereo microphone mode. Remarks None. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 driver instance. DRV_AK4953_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4953_MonoStereoMicSet( DRV_HANDLE handle); DRV_AK4953_MicSet Function This function sets up the codec for the internal or the AK4953 Mic1 or Mic2 input. File drv_ak4953.h C void DRV_AK4953_MicSet(DRV_HANDLE handle, DRV_AK4953_MIC micInput); Returns None Description This function sets up the codec. Remarks None. Preconditions The DRV_AK4953_Initialize routine must have been called for the specified AK4953 driver instance. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 227 DRV_AK4953_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine micInput Internal vs External mic input Function void DRV_AK4953_IntMic12Set d) Data Types and Constants DRV_AK4953_AUDIO_DATA_FORMAT Enumeration Identifies the Serial Audio data interface format. File drv_ak4953.h C typedef enum { DRV_AK4953_AUDIO_DATA_FORMAT_24BIT_MSB_SDTO_24BIT_LSB_SDTI = 0, DRV_AK4953_AUDIO_DATA_FORMAT_24BIT_MSB_SDTO_16BIT_LSB_SDTI, DRV_AK4953_AUDIO_DATA_FORMAT_24BIT_MSB_SDTO_24BIT_MSB_SDTI, DRV_AK4953_AUDIO_DATA_FORMAT_I2S } DRV_AK4953_AUDIO_DATA_FORMAT; Description AK4953 Audio data format This enumeration identifies Serial Audio data interface format. DRV_AK4953_BUFFER_EVENT Enumeration Identifies the possible events that can result from a buffer add request. File drv_ak4953.h C typedef enum { DRV_AK4953_BUFFER_EVENT_COMPLETE, DRV_AK4953_BUFFER_EVENT_ERROR, DRV_AK4953_BUFFER_EVENT_ABORT } DRV_AK4953_BUFFER_EVENT; Members Members Description DRV_AK4953_BUFFER_EVENT_COMPLETE Data was transferred successfully. DRV_AK4953_BUFFER_EVENT_ERROR Error while processing the request DRV_AK4953_BUFFER_EVENT_ABORT Data transfer aborted (Applicable in DMA mode) Description AK4953 Driver Events This enumeration identifies the possible events that can result from a buffer add request caused by the client calling either the DRV_AK4953_BufferAddWrite() function. Remarks One of these values is passed in the "event" parameter of the event handling callback function that the client registered with the driver by calling the DRV_AK4953_BufferEventHandlerSet function when a buffer transfer request is completed. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 228 DRV_AK4953_BUFFER_EVENT_HANDLER Type Pointer to a AK4953 Driver Buffer Event handler function File drv_ak4953.h C typedef void (* DRV_AK4953_BUFFER_EVENT_HANDLER)(DRV_AK4953_BUFFER_EVENT event, DRV_AK4953_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle); Returns None. Description AK4953 Driver Buffer Event Handler Function This data type defines the required function signature for the AK4953 driver buffer event handling callback function. A client must register a pointer to a buffer event handling function who's function signature (parameter and return value types) match the types specified by this function pointer in order to receive buffer related event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks If the event is DRV_AK4953_BUFFER_EVENT_COMPLETE, this means that the data was transferred successfully. If the event is DRV_AK4953_BUFFER_EVENT_ERROR, this means that the data was not transferred successfully. The bufferHandle parameter contains the buffer handle of the buffer that failed. The DRV_AK4953_BufferProcessedSizeGet() function can be called to find out how many bytes were processed. The bufferHandle parameter contains the buffer handle of the buffer that associated with the event. The context parameter contains a handle to the client context, provided at the time the event handling function was registered using the DRV_AK4953_BufferEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the buffer add request. The buffer handle in bufferHandle expires after this event handler exits. In that the buffer object that was allocated is deallocated by the driver after the event handler exits. The event handler function executes in the data driver (I2S) peripheral's interrupt context when the driver is configured for interrupt mode operation. It is recommended of the application to not perform process intensive or blocking operations with in this function. DRV_AK4953_BufferAddWrite function can be called in the event handler to add a buffer to the driver queue. Example void APP_MyBufferEventHandler( DRV_AK4953_BUFFER_EVENT event, DRV_AK4953_BUFFER_HANDLE bufferHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_AK4953_BUFFER_EVENT_COMPLETE: // Handle the completed buffer. break; case DRV_AK4953_BUFFER_EVENT_ERROR: default: // Handle error. break; } } Parameters Parameters Description event Identifies the type of event bufferHandle Handle identifying the buffer to which the event relates context Value identifying the context of the application that registered the event handling function. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 229 DRV_AK4953_BUFFER_HANDLE Type Handle identifying a write buffer passed to the driver. File drv_ak4953.h C typedef uintptr_t DRV_AK4953_BUFFER_HANDLE; Description AK4953 Driver Buffer Handle A buffer handle value is returned by a call to the DRV_AK4953_BufferAddWrite() function. This handle is associated with the buffer passed into the function and it allows the application to track the completion of the data from (or into) that buffer. The buffer handle value returned from the "buffer add" function is returned back to the client by the "event handler callback" function registered with the driver. The buffer handle assigned to a client request expires when the client has been notified of the completion of the buffer transfer (after event handler function that notifies the client returns) or after the buffer has been retired by the driver if no event handler callback was set. Remarks None DRV_AK4953_COMMAND_EVENT_HANDLER Type Pointer to a AK4953 Driver Command Event Handler Function File drv_ak4953.h C typedef void (* DRV_AK4953_COMMAND_EVENT_HANDLER)(uintptr_t contextHandle); Returns None. Description AK4953 Driver Command Event Handler Function This data type defines the required function signature for the AK4953 driver command event handling callback function. A command is a control instruction to the AK4953 CODEC. Example Mute ON/OFF, Zero Detect Enable/Disable etc. A client must register a pointer to a command event handling function who's function signature (parameter and return value types) match the types specified by this function pointer in order to receive command related event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks The occurrence of this call back means that the last control command was transferred successfully. The context parameter contains a handle to the client context, provided at the time the event handling function was registered using the DRV_AK4953_CommandEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the buffer add request. The event handler function executes in the control data driver interrupt context. It is recommended of the application to not perform process intensive or blocking operations with in this function. Example void APP_AK4953CommandEventHandler( uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; // Last Submitted command is completed. // Perform further processing here } Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 230 Parameters Parameters Description context Value identifying the context of the application that registered the event handling function. DRV_AK4953_DIGITAL_BLOCK_CONTROL Enumeration Identifies Bass-Boost Control function File drv_ak4953.h C typedef enum { DRV_AK4953_RECORDING_MODE, DRV_AK4953_PLAYBACK_MODE, DRV_AK4953_RECORDING_PLAYBACK_2_MODE, DRV_AK4953_LOOPBACK_MODE } DRV_AK4953_DIGITAL_BLOCK_CONTROL; Members Members Description DRV_AK4953_RECORDING_MODE This is the default setting DRV_AK4953_PLAYBACK_MODE Min control DRV_AK4953_RECORDING_PLAYBACK_2_MODE Medium control DRV_AK4953_LOOPBACK_MODE Maximum control Description AK4953 Bass-Boost Control This enumeration identifies the settings for Bass-Boost Control function. Remarks None. DRV_AK4953_INIT Structure Defines the data required to initialize or reinitialize the AK4953 driver File drv_ak4953.h C typedef struct { SYS_MODULE_INIT moduleInit; SYS_MODULE_INDEX i2sDriverModuleIndex; SYS_MODULE_INDEX i2cDriverModuleIndex; uint32_t samplingRate; uint8_t volume; DRV_AK4953_AUDIO_DATA_FORMAT audioDataFormat; } DRV_AK4953_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization SYS_MODULE_INDEX i2sDriverModuleIndex; Identifies data module(I2S) driver ID for data interface of CODEC SYS_MODULE_INDEX i2cDriverModuleIndex; Identifies data module(I2C) driver ID for control interface of CODEC uint32_t samplingRate; Sampling rate uint8_t volume; Volume DRV_AK4953_AUDIO_DATA_FORMAT audioDataFormat; Identifies the Audio data format Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 231 Description AK4953 Driver Initialization Data This data type defines the data required to initialize or reinitialize the AK4953 CODEC driver. Remarks None. _DRV_AK4953_H Macro File drv_ak4953.h C #define _DRV_AK4953_H Description Include files. DRV_AK4953_BUFFER_HANDLE_INVALID Macro Definition of an invalid buffer handle. File drv_ak4953.h C #define DRV_AK4953_BUFFER_HANDLE_INVALID ((DRV_AK4953_BUFFER_HANDLE)(-1)) Description AK4953 Driver Invalid Buffer Handle This is the definition of an invalid buffer handle. An invalid buffer handle is returned by DRV_AK4953_BufferAddWrite() function if the buffer add request was not successful. Remarks None DRV_AK4953_COUNT Macro Number of valid AK4953 driver indices File drv_ak4953.h C #define DRV_AK4953_COUNT Description AK4953 Driver Module Count This constant identifies the maximum number of AK4953 Driver instances that should be defined by the application. Defining more instances than this constant will waste RAM memory space. This constant can also be used by the application to identify the number of AK4953 instances on this microcontroller. Remarks This value is part-specific. DRV_AK4953_INDEX_0 Macro AK4953 driver index definitions Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 232 File drv_ak4953.h C #define DRV_AK4953_INDEX_0 0 Description Driver AK4953 Module Index These constants provide AK4953 driver index definition. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_AK4953_Initialize and DRV_AK4953_Open routines to identify the driver instance in use. DRV_AK4953_INDEX_1 Macro File drv_ak4953.h C #define DRV_AK4953_INDEX_1 1 Description This is macro DRV_AK4953_INDEX_1. DRV_AK4953_INDEX_2 Macro File drv_ak4953.h C #define DRV_AK4953_INDEX_2 2 Description This is macro DRV_AK4953_INDEX_2. DRV_AK4953_INDEX_3 Macro File drv_ak4953.h C #define DRV_AK4953_INDEX_3 3 Description This is macro DRV_AK4953_INDEX_3. DRV_AK4953_INDEX_4 Macro File drv_ak4953.h C #define DRV_AK4953_INDEX_4 4 Description This is macro DRV_AK4953_INDEX_4. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 233 DRV_AK4953_INDEX_5 Macro File drv_ak4953.h C #define DRV_AK4953_INDEX_5 5 Description This is macro DRV_AK4953_INDEX_5. DRV_AK4953_CHANNEL Enumeration Identifies Left/Right Audio channel File drv_ak4953.h C typedef enum { DRV_AK4953_CHANNEL_LEFT, DRV_AK4953_CHANNEL_RIGHT, DRV_AK4953_CHANNEL_LEFT_RIGHT, DRV_AK4953_NUMBER_OF_CHANNELS } DRV_AK4953_CHANNEL; Description AK4953 Audio Channel This enumeration identifies Left/Right Audio channel Remarks None. DRV_AK4953_INT_EXT_MIC Enumeration Identifies the Mic input source. File drv_ak4953.h C typedef enum { INT_MIC, EXT_MIC } DRV_AK4953_INT_EXT_MIC; Description AK4953 Mic Internal / External Input This enumeration identifies the Mic input source. DRV_AK4953_MONO_STEREO_MIC Enumeration Identifies the Mic input as Mono / Stereo. File drv_ak4953.h C typedef enum { ALL_ZEROS, MONO_RIGHT_CHANNEL, MONO_LEFT_CHANNEL, Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 234 STEREO } DRV_AK4953_MONO_STEREO_MIC; Description AK4953 Mic Mono / Stereo Input This enumeration identifies the Mic input as Mono / Stereo. DRV_AK4953_MIC Enumeration File drv_ak4953.h C typedef enum { MIC1 = 0, MIC2, MIC3, DRV_AK4953_NUMBER_OF_MIC } DRV_AK4953_MIC; Members Members Description MIC1 = 0 INT_MIC MIC2 EXT_MIC MIC3 LINE-IN Description This is type DRV_AK4953_MIC. Files Files Name Description drv_ak4953.h AK4953 CODEC Driver Interface header file drv_ak4953_config_template.h AK4953 Codec Driver Configuration Template. Description This section lists the source and header files used by the AK4953Codec Driver Library. drv_ak4953.h AK4953 CODEC Driver Interface header file Enumerations Name Description DRV_AK4953_AUDIO_DATA_FORMAT Identifies the Serial Audio data interface format. DRV_AK4953_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_AK4953_CHANNEL Identifies Left/Right Audio channel DRV_AK4953_DIGITAL_BLOCK_CONTROL Identifies Bass-Boost Control function DRV_AK4953_INT_EXT_MIC Identifies the Mic input source. DRV_AK4953_MIC This is type DRV_AK4953_MIC. DRV_AK4953_MONO_STEREO_MIC Identifies the Mic input as Mono / Stereo. Functions Name Description DRV_AK4953_BufferAddRead Schedule a non-blocking driver read operation. DRV_AK4953_BufferAddWrite Schedule a non-blocking driver write operation. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 235 DRV_AK4953_BufferAddWriteRead Schedule a non-blocking driver write-read operation. Implementation: Dynamic DRV_AK4953_BufferEventHandlerSet This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. DRV_AK4953_Close Closes an opened-instance of the AK4953 driver. Implementation: Dynamic DRV_AK4953_CommandEventHandlerSet This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. Implementation: Dynamic DRV_AK4953_Deinitialize Deinitializes the specified instance of the AK4953 driver module. Implementation: Dynamic DRV_AK4953_Initialize Initializes hardware and data for the instance of the AK4953 DAC module. Implementation: Dynamic DRV_AK4953_IntExtMicSet This function sets up the codec for the X32 DB internal or the external microphone use. DRV_AK4953_MicSet This function sets up the codec for the internal or the AK4953 Mic1 or Mic2 input. DRV_AK4953_MonoStereoMicSet This function sets up the codec for the Mono or Stereo microphone mode. DRV_AK4953_MuteOff This function disables AK4953 output for soft mute. Implementation: Dynamic DRV_AK4953_MuteOn This function allows AK4953 output for soft mute on. Implementation: Dynamic DRV_AK4953_Open Opens the specified AK4953 driver instance and returns a handle to it. Implementation: Dynamic DRV_AK4953_SamplingRateGet This function gets the sampling rate set on the DAC AK4953. Implementation: Dynamic DRV_AK4953_SamplingRateSet This function sets the sampling rate of the media stream. Implementation: Dynamic DRV_AK4953_SetAudioCommunicationMode This function provides a run time audio format configuration DRV_AK4953_Status Gets the current status of the AK4953 driver module. Implementation: Dynamic DRV_AK4953_Tasks Maintains the driver's control and data interface state machine. Implementation: Dynamic DRV_AK4953_VersionGet This function returns the version of AK4953 driver. Implementation: Dynamic DRV_AK4953_VersionStrGet This function returns the version of AK4953 driver in string format. Implementation: Dynamic DRV_AK4953_VolumeGet This function gets the volume for AK4953 CODEC. Implementation: Dynamic DRV_AK4953_VolumeSet This function sets the volume for AK4953 CODEC. Implementation: Dynamic Macros Name Description _DRV_AK4953_H Include files. DRV_AK4953_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_AK4953_COUNT Number of valid AK4953 driver indices DRV_AK4953_INDEX_0 AK4953 driver index definitions DRV_AK4953_INDEX_1 This is macro DRV_AK4953_INDEX_1. DRV_AK4953_INDEX_2 This is macro DRV_AK4953_INDEX_2. DRV_AK4953_INDEX_3 This is macro DRV_AK4953_INDEX_3. DRV_AK4953_INDEX_4 This is macro DRV_AK4953_INDEX_4. DRV_AK4953_INDEX_5 This is macro DRV_AK4953_INDEX_5. Structures Name Description DRV_AK4953_INIT Defines the data required to initialize or reinitialize the AK4953 driver Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 236 Types Name Description DRV_AK4953_BUFFER_EVENT_HANDLER Pointer to a AK4953 Driver Buffer Event handler function DRV_AK4953_BUFFER_HANDLE Handle identifying a write buffer passed to the driver. DRV_AK4953_COMMAND_EVENT_HANDLER Pointer to a AK4953 Driver Command Event Handler Function Description AK4953 CODEC Driver Interface The AK4953 CODEC device driver interface provides a simple interface to manage the AK4953 106dB 192kHz 24-Bit DAC that can be interfaced Microchip Microcontroller. This file provides the interface definition for the AK4953 CODEC device driver. File Name drv_AK4953.h Company Microchip Technology Inc. drv_ak4953_config_template.h AK4953 Codec Driver Configuration Template. Macros Name Description DRV_AK4953_BCLK_BIT_CLK_DIVISOR Sets up the BCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency DRV_AK4953_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_AK4953_INPUT_REFCLOCK Identifies the input REFCLOCK source to generate the MCLK to codec. DRV_AK4953_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_AK4953_MCLK_SAMPLE_FREQ_MULTPLIER Sets up the MCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency DRV_AK4953_MCLK_SOURCE Indicate the input clock frequency to generate the MCLK to codec. DRV_AK4953_QUEUE_DEPTH_COMBINED Number of entries of all queues in all instances of the driver. Description AK4953 Codec Driver Configuration Template These file provides the list of all the configurations that can be used with the driver. This file should not be included in the driver. File Name drv_ak4953_config_template.h Company Microchip Technology Inc. AK4954 Codec Driver Library This topic describes the AK4954 Codec Driver Library. Introduction This library provides an interface to manage the AK4954 Codec that is serially interfaced to a Microchip microcontroller for providing Audio Solutions. Description The AK4954 module is 16/24-bit Audio Codec from Asahi Kasei Microdevices Corporation. The AK4954 can be interfaced to Microchip microcontrollers through I2C and I2S serial interfaces. The I2C interface is used for control command transfer. The I2S interface is used for Audio data output. A typical interface of AK4954 to a Microchip PIC32 device is provided in the following diagram: Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 237 Features The AK4954 Codec supports the following features: • Audio Interface Format: MSB first • ADC: 24-bit MSB justified, 16/24-bit I2S • DAC: 24-bit MSB justified, 1-6bit LSB justified, 24-bit LSB justified, 16/24-bit I2S • Sampling Frequency Range: 8 kHz to 192 kHz • Digital Volume Control: +12dB ~ .115dB, 0.5dB Step • SoftMute: On and Off • Master Clock Frequencies: 32 fs/64 fs/128 fs/256 fs Using the Library This topic describes the basic architecture of the AK4954 Codec Driver Library and provides information and examples on its use. Description Interface Header File: drv_ak4954.h The interface to the AK4954 Codec Driver library is defined in the drv_ak4954.h header file. Any C language source (.c) file that uses the AK4954 Codec Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the AK4954 Codec Driver Library 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 abstraction model shown in the following diagram depicts how the AK4954 Codec Driver is positioned in the MPLAB Harmony framework. The AK4954 Codec Driver uses the SPI and I2S drivers for control and audio data transfers to the AK4954 module. AK4954 Driver Abstraction Model Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 238 Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The AK4954 Codec Driver Library provides an API interface to transfer control commands and digital audio data to the serially interfaced AK4954 DAC module. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the AK4954 Codec Driver Library. Library Interface Section Description System Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Status Functions Provides status functions. Other Functions Provides driver specific miscellaneous functions such as sampling rate setting, control command functions, etc. Data Types and Constants These data types and constants are required while interacting and setting up the AK4954 Codec Driver Library. How the Library Works The library provides interfaces to support: • System Functionality • Client Functionality System Access This topic describes system initialization, implementations, and includes a system access code example. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 239 Description System Initialization The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization, each instance of the AK4954 module would be initialized with the following configuration settings (either passed dynamically at run time using DRV_AK4954_INIT or by using Initialization Overrides) that are supported by the specific AK4954 device hardware: • Device requested power state: one of the System Module Power States. For specific details please refer to Data Types and Constants in the Library Interface section. • I2C driver module index. The module index should be same as the one used in initializing the I2C Driver. • I2S driver module index. The module index should be same as the one used in initializing the I2S Driver. • Sampling rate • Audio data format. The audio data format should match with the audio data format settings done in I2S driver initialization • Power down pin port initialization • Queue size for the audio data transmit buffer The DRV_AK4954_Initialize API returns an object handle of the type SYS_MODULE_OBJ. The object handle returned by the Initialize interface would be used by the other system interfaces such as DRV_ AK4954_Deinitialize, DRV_ AK4954_Status and DRV_I2S_Tasks. Implementations The AK4954 Codec Driver can has the following implementation: Description MPLAB Harmony Components Dedicated hardware for control (I2C) and data (I2S) interface. Standard MPLAB Harmony drivers for I2C and I2S interfaces. Example: DRV_AK4954_INIT drvak4954Codec0InitData = { .moduleInit.value = SYS_MODULE_POWER_RUN_FULL, .i2sDriverModuleIndex = DRV_AK4954_I2S_DRIVER_MODULE_INDEX_IDX0, .i2cDriverModuleIndex = DRV_AK4954_I2C_DRIVER_MODULE_INDEX_IDX0, .volume = DRV_AK4954_VOLUME, .queueSizeTransmit = DRV_AK4954_TRANSMIT_QUEUE_SIZE, }; // Initialize the I2C driver DRV_I2C0_Initialize(); // Initialize the I2S driver. The I2S module index should be same as the one used in initializing // the I2S driver. sysObj.drvI2S0 = DRV_I2S_Initialize(DRV_I2S_INDEX_0, (SYS_MODULE_INIT *)&drvI2S0InitData); // Initialize the Codec driver sysObj.drvak4954Codec0 = DRV_AK4954_Initialize(DRV_AK4954_INDEX_0, (SYS_MODULE_INIT *)&drvak4954Codec0InitData); if (SYS_MODULE_OBJ_INVALID == AK4954DevObject) { // Handle error } Task Routine The DRV_AK4954_Tasks will be called from the System Task Service. Client Access For the application to start using an instance of the module, it must call the DRV_AK4954_Open function. The DRV_AK4954_Open provides a driver handle to the AK4954 Codec Driver instance for operations. If the driver is deinitialized using the function DRV_AK4954_Deinitialize, the application must call the DRV_AK4954_Open function again to set up the instance of the driver. For the various options available for IO_INTENT, please refer to Data Types and Constants in the Library Interface section. Client Operations This topic provides information on client operations and includes a control command and audio buffered data operation flow diagram. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 240 Description Client operations provide the API interface for control command and audio data transfer to the AK4954 Codec. The following AK4954 Codec specific control command functions are provided: • DRV_AK4954_SamplingRateSet • DRV_AK4954_SamplingRateGet • DRV_AK4954_VolumeSet • DRV_AK4954_VolumeGet • DRV_AK4954_MuteOn • DRV_AK4954_MuteOff • DRV_AK4954_IntExtMicSet • DRV_AK4954_MonoStereoMicSet These functions schedule a non-blocking control command transfer operation. These functions submit the control command request to the AK4954 Codec. These functions submit the control command request to I2C Driver transmit queue, the request is processed immediately if it is the first request, or processed when the previous request is complete. DRV_AK4954_BufferAddWrite, DRV_AK4954_BufferAddRead, and DRV_AK4954_BufferAddWriteRead are buffered data operation functions. These functions schedule non-blocking audio data transfer operations. These functions add the request to I2S Driver transmit or receive buffer queue depends on the request type, and are executed immediately if it is the first buffer, or executed later when the previous buffer is complete. The driver notifies the client with DRV_AK4954_BUFFER_EVENT_COMPLETE, DRV_AK4954_BUFFER_EVENT_ERROR, or DRV_AK4954_BUFFER_EVENT_ABORT events. The following diagram illustrates the control commands and audio buffered data operations. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 241 Note: It is not necessary to close and reopen the client between multiple transfers. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 242 Configuring the Library Macros Name Description DRV_AK4954_BCLK_BIT_CLK_DIVISOR Indicates whether the initilization of the AK4954 codec should be delayed. DRV_AK4954_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_AK4954_INPUT_REFCLOCK Identifies the input REFCLOCK source to generate the MCLK to codec. DRV_AK4954_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_AK4954_MCLK_SAMPLE_FREQ_MULTPLIER Sets up the MCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency DRV_AK4954_MCLK_SOURCE Indicate the input clock frequency to generate the MCLK to codec. DRV_AK4954_QUEUE_DEPTH_COMBINED Number of entries of all queues in all instances of the driver. Description The configuration of the AK4954 Codec Driver is based on the file system_config.h. This header file contains the configuration selection for the AK4954 Codec Driver. Based on the selections made, the driver may support the selected features. These configuration settings will apply to all instances of the AK4954 Codec Driver. This header can be placed anywhere, 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. DRV_AK4954_BCLK_BIT_CLK_DIVISOR Macro Indicates whether the initilization of the AK4954 codec should be delayed. File drv_ak4954_config_template.h C #define DRV_AK4954_BCLK_BIT_CLK_DIVISOR Description AK4954 Delay Initialization If the AK4954 Codec shares its RESET pin with another peripheral, such as a Bluetooth module, then this define should be true, in order to indicate the AK4954 Codec should starts its initialization only after the other peripheral has completed theirs. It is set in the MHC menu with the checkbox: "Delay driver initialization (due to shared RESET pin)" Remarks This needs to be set, for example, in the case where the AK4954 and the BM64 share a common PDN (power down) or RESET pin on the PIC32 Bluetooth Audio Development Kit (BTADK). DRV_AK4954_CLIENTS_NUMBER Macro Sets up the maximum number of clients that can be connected to any hardware instance. File drv_ak4954_config_template.h C #define DRV_AK4954_CLIENTS_NUMBER DRV_AK4954_INSTANCES_NUMBER Description AK4954 Client Count Configuration Sets up the maximum number of clients that can be connected to any hardware instance. Typically only one client could be connected to one hardware instance. This value represents the total number of clients to be supported across all hardware instances. Therefore, if there are five AK4954 hardware interfaces, this number will be 5. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 243 DRV_AK4954_INPUT_REFCLOCK Macro Identifies the input REFCLOCK source to generate the MCLK to codec. File drv_ak4954_config_template.h C #define DRV_AK4954_INPUT_REFCLOCK Description AK4954 Input reference clock Identifies the input REFCLOCK source to generate the MCLK to codec. Remarks None. DRV_AK4954_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported File drv_ak4954_config_template.h C #define DRV_AK4954_INSTANCES_NUMBER Description AK4954 driver objects configuration Sets up the maximum number of hardware instances that can be supported. It is recommended that this number be set exactly equal to the number of AK4954 CODEC modules that are needed by the application. Hardware Instance support consumes RAM memory space. If this macro is not defined, then the driver will be built statically. Remarks None. DRV_AK4954_MCLK_SAMPLE_FREQ_MULTPLIER Macro Sets up the MCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency File drv_ak4954_config_template.h C #define DRV_AK4954_MCLK_SAMPLE_FREQ_MULTPLIER Description AK4954 MCLK to LRCK Ratio to Generate Audio Stream Sets up the MCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency I2S sampling frequency Supported MCLK to Sampling frequency Ratios are as below 256fs, 384fs, 512fs, 768fs or 1152fs Remarks None DRV_AK4954_MCLK_SOURCE Macro Indicate the input clock frequency to generate the MCLK to codec. File drv_ak4954_config_template.h Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 244 C #define DRV_AK4954_MCLK_SOURCE Description AK4954 Data Interface Master Clock Speed configuration Indicate the input clock frequency to generate the MCLK to codec. Remarks None. DRV_AK4954_QUEUE_DEPTH_COMBINED Macro Number of entries of all queues in all instances of the driver. File drv_ak4954_config_template.h C #define DRV_AK4954_QUEUE_DEPTH_COMBINED Description AK4954 Driver Buffer Queue Entries This macro defined the number of entries of all queues in all instances of the driver. Each hardware instance supports a buffer queue for transmit operations. The size of queue is specified either in driver initialization (for dynamic build) or by macros (for static build). The hardware instance transmit buffer queue will queue transmit buffers submitted by the DRV_AK4954_BufferAddWrite function. A buffer queue will contains buffer queue entries, each related to a BufferAdd request. This configuration macro defines total number of buffer entries that will be available for use between all AK4954 driver hardware instances. The buffer queue entries are allocated to individual hardware instances as requested by hardware instances. Once the request is processed, the buffer queue entry is free for use by other hardware instances. The total number of buffer entries in the system determines the ability of the driver to service non blocking write requests. If a free buffer entry is not available, the driver will not add the request and will return an invalid buffer handle. More the number of buffer entries, greater the ability of the driver to service and add requests to its queue. A hardware instance additionally can queue up as many buffer entries as specified by its transmit buffer queue size. As an example, consider the case of static single client driver application where full duplex non blocking operation is desired without queuing, the minimum transmit queue depth and minimum receive queue depth should be 1. Hence the total number of buffer entries should be 2. As an example, consider the case of a dynamic driver (say two instances) where instance one will queue up to three write requests and up to two read requests, and instance two will queue up to two write requests and up to six read requests, the value of this macro should be 13 (2 + 3 + 2 + 6). Configuring the MHC Provides examples on how to configure the MPLAB Harmony Configurator (MHC) for a specific driver. Description The following three figures show examples of MHC configurations for the AK4954 Codec Driver, I2S Driver, and the I2C Driver. Figure 1: AK4954 Codec Driver MHC Configuration Figure 2: I2S Driver MHC Configuration Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 245 Figure 3: I2C Driver MHC Configuration Migrating the AK4954 Driver From Earlier Versions of Microchip Harmony Prior to version 1.08 of MPLAB Harmony, the AK4954 Codec Driver Library used the static I2C driver implementation. Beginning with v1.08 of MPLAB Harmony, applications must use the Dynamic Driver implementation with the MHC configured as shown in Figure 3. In addition, PIC32MZ configurations require the "Include Force Write I2C Function (Master Mode Only - Ignore NACK from Slave)" option to be selected. Building the Library This section lists the files that are available in the AK4954 Codec Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 246 Description This section list the files that are available in the /src folder of the AK4954 Codec 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. 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 /framework/driver/codec/ak4954. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_ak4954.h Header file that exports the driver API. 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 /src/dynamic/drv_ak4954.c This file contains implementation of the AK4954 Codec Driver. 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 N/A No optional files are available for this library. Module Dependencies The AK4954 Codec Driver Library depends on the following modules: • I2S Driver Library • I2C Driver Library Library Interface a) System Interaction Functions Name Description DRV_AK4954_Initialize Initializes hardware and data for the instance of the AK4954 DAC module. Implementation: Dynamic DRV_AK4954_Deinitialize Deinitializes the specified instance of the AK4954 driver module. Implementation: Dynamic DRV_AK4954_Open Opens the specified AK4954 driver instance and returns a handle to it. Implementation: Dynamic DRV_AK4954_Close Closes an opened-instance of the AK4954 driver. Implementation: Dynamic DRV_AK4954_Tasks Maintains the driver's control and data interface state machine. Implementation: Dynamic DRV_AK4954_CommandEventHandlerSet This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. Implementation: Dynamic DRV_AK4954_BufferEventHandlerSet This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. DRV_AK4954_SamplingRateSet This function sets the sampling rate of the media stream. Implementation: Dynamic DRV_AK4954_SetAudioCommunicationMode This function provides a run time audio format configuration Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 247 b) Status Functions Name Description DRV_AK4954_SamplingRateGet This function gets the sampling rate set on the DAC AK4954. Implementation: Dynamic DRV_AK4954_Status Gets the current status of the AK4954 driver module. Implementation: Dynamic DRV_AK4954_VersionGet This function returns the version of AK4954 driver. Implementation: Dynamic DRV_AK4954_VersionStrGet This function returns the version of AK4954 driver in string format. Implementation: Dynamic DRV_AK4954_VolumeGet This function gets the volume for AK4954 CODEC. Implementation: Dynamic c) Other Functions Name Description DRV_AK4954_VolumeSet This function sets the volume for AK4954 CODEC. Implementation: Dynamic DRV_AK4954_BufferAddRead Schedule a non-blocking driver read operation. DRV_AK4954_BufferAddWrite Schedule a non-blocking driver write operation. Implementation: Dynamic DRV_AK4954_BufferAddWriteRead Schedule a non-blocking driver write-read operation. Implementation: Dynamic DRV_AK4954_IntExtMicSet This function sets up the codec for the X32 DB internal or the external microphone use. DRV_AK4954_MicSet This function sets up the codec for the internal or the AK4954 Mic1 or Mic2 input. DRV_AK4954_MonoStereoMicSet This function sets up the codec for the Mono or Stereo microphone mode. DRV_AK4954_MuteOff This function disables AK4954 output for soft mute. Implementation: Dynamic DRV_AK4954_MuteOn This function allows AK4954 output for soft mute on. Implementation: Dynamic d) Data Types and Constants Name Description DRV_AK4954_AUDIO_DATA_FORMAT Identifies the Serial Audio data interface format. DRV_AK4954_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_AK4954_BUFFER_EVENT_HANDLER Pointer to a AK4954 Driver Buffer Event handler function DRV_AK4954_BUFFER_HANDLE Handle identifying a write buffer passed to the driver. DRV_AK4954_CHANNEL Identifies Left/Right Audio channel DRV_AK4954_COMMAND_EVENT_HANDLER Pointer to a AK4954 Driver Command Event Handler Function DRV_AK4954_DIGITAL_BLOCK_CONTROL Identifies Bass-Boost Control function DRV_AK4954_INIT Defines the data required to initialize or reinitialize the AK4954 driver DRV_AK4954_INT_EXT_MIC Identifies the Mic input source. DRV_AK4954_MIC This is type DRV_AK4954_MIC. DRV_AK4954_MONO_STEREO_MIC Identifies the Mic input as Mono / Stereo. DRV_AK4954_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_AK4954_COUNT Number of valid AK4954 driver indices DRV_AK4954_INDEX_0 AK4954 driver index definitions DRV_AK4954_INDEX_1 This is macro DRV_AK4954_INDEX_1. DRV_AK4954_INDEX_2 This is macro DRV_AK4954_INDEX_2. DRV_AK4954_INDEX_3 This is macro DRV_AK4954_INDEX_3. DRV_AK4954_INDEX_4 This is macro DRV_AK4954_INDEX_4. DRV_AK4954_INDEX_5 This is macro DRV_AK4954_INDEX_5. Description This section describes the API functions of the AK4954 Codec Driver library. Refer to each section for a detailed description. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 248 a) System Interaction Functions DRV_AK4954_Initialize Function Initializes hardware and data for the instance of the AK4954 DAC module. Implementation: Dynamic File drv_ak4954.h C SYS_MODULE_OBJ DRV_AK4954_Initialize(const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the AK4954 driver instance for the specified driver index, making it ready for clients to open and use it. The initialization data is specified by the init parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. Remarks This routine must be called before any other AK4954 routine is called. This routine should only be called once during system initialization unless DRV_AK4954_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. Preconditions DRV_I2S_Initialize must be called before calling this function to initialize the data interface of this CODEC driver. Also DRV_I2C_Initialize must be called before calling this function to initialize the control interface of this CODEC driver. Example DRV_AK4954_INIT init; SYS_MODULE_OBJ objectHandle; init->inUse = true; init->status = SYS_STATUS_BUSY; init->numClients = 0; init->i2sDriverModuleIndex = ak4954Init->i2sDriverModuleIndex; init->i2cDriverModuleIndex = ak4954Init->i2cDriverModuleIndex; init->samplingRate = DRV_AK4954_AUDIO_SAMPLING_RATE; init->audioDataFormat = DRV_AK4954_AUDIO_DATA_FORMAT_MACRO; for(index=0; index < DRV_AK4954_NUMBER_OF_CHANNELS; index++) { init->volume[index] = ak4954Init->volume; } init->isInInterruptContext = false; init->commandCompleteCallback = (DRV_AK4954_COMMAND_EVENT_HANDLER)0; init->commandContextData = 0; init->mclk_multiplier = DRV_AK4954_MCLK_SAMPLE_FREQ_MULTPLIER; objectHandle = DRV_AK4954_Initialize(DRV_AK4954_0, (SYS_MODULE_INIT*)init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description drvIndex Identifier for the driver instance to be initialized Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 249 init Pointer to the data structure containing any data necessary to initialize the hardware. This pointer may be null if no data is required and default initialization is to be used. Function SYS_MODULE_OBJ DRV_AK4954_Initialize ( const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT *const init ); DRV_AK4954_Deinitialize Function Deinitializes the specified instance of the AK4954 driver module. Implementation: Dynamic File drv_ak4954.h C void DRV_AK4954_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the AK4954 driver module, disabling its operation (and any hardware). Invalidates all the internal data. Remarks Once the Initialize operation has been called, the De-initialize operation must be called before the Initialize operation can be called again. This routine will NEVER block waiting for hardware. Preconditions Function DRV_AK4954_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_AK4954_Initialize SYS_STATUS status; DRV_AK4954_Deinitialize(object); status = DRV_AK4954_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from the DRV_AK4954_Initialize routine Function void DRV_AK4954_Deinitialize( SYS_MODULE_OBJ object) DRV_AK4954_Open Function Opens the specified AK4954 driver instance and returns a handle to it. Implementation: Dynamic File drv_ak4954.h Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 250 C DRV_HANDLE DRV_AK4954_Open(const SYS_MODULE_INDEX iDriver, const DRV_IO_INTENT ioIntent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Error can occur • if the number of client objects allocated via DRV_AK4954_CLIENTS_NUMBER is insufficient. • if the client is trying to open the driver but driver has been opened exclusively by another client. • if the driver hardware instance being opened is not initialized or is invalid. • if the ioIntent options passed are not relevant to this driver. Description This routine opens the specified AK4954 driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. The DRV_IO_INTENT_BLOCKING and DRV_IO_INTENT_NONBLOCKING ioIntent options are not relevant to this driver. All the data transfer functions of this driver are non blocking. AK4954 can be opened with DRV_IO_INTENT_WRITE, or DRV_IO_INTENT_READ or DRV_IO_INTENT_WRITEREAD io_intent option. This decides whether the driver is used for headphone output, or microphone input or both modes simultaneously. Specifying a DRV_IO_INTENT_EXCLUSIVE will cause the driver to provide exclusive access to this client. The driver cannot be opened by any other client. Remarks The handle returned is valid until the DRV_AK4954_Close routine is called. This routine will NEVER block waiting for hardware.If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. It should not be called in an ISR. Preconditions Function DRV_AK4954_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_AK4954_Open(DRV_AK4954_INDEX_0, DRV_IO_INTENT_WRITEREAD | DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver // May be the driver is not initialized or the initialization // is not complete. } Parameters Parameters Description drvIndex Identifier for the object instance to be opened ioIntent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver. See function description for details. Function DRV_HANDLE DRV_AK4954_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent ) DRV_AK4954_Close Function Closes an opened-instance of the AK4954 driver. Implementation: Dynamic File drv_ak4954.h Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 251 C void DRV_AK4954_Close(const DRV_HANDLE handle); Returns None. Description This routine closes an opened-instance of the AK4954 driver, invalidating the handle. Any buffers in the driver queue that were submitted by this client will be removed. After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_AK4954_Open before the caller may use the driver again Remarks Usually there is no need for the driver client to verify that the Close operation has completed. The driver will abort any ongoing operations when this routine is called. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 driver instance. DRV_AK4954_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_AK4954_Open DRV_AK4954_Close(handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4954_Close( DRV_Handle handle ) DRV_AK4954_Tasks Function Maintains the driver's control and data interface state machine. Implementation: Dynamic File drv_ak4954.h C void DRV_AK4954_Tasks(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal control and data interface state machine and implement its control and data interface implementations. This function should be called from the SYS_Tasks() function. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks). Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_AK4954_Initialize while (true) { DRV_AK4954_Tasks (object); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 252 // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_AK4954_Initialize) Function void DRV_AK4954_Tasks(SYS_MODULE_OBJ object); DRV_AK4954_CommandEventHandlerSet Function This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. Implementation: Dynamic File drv_ak4954.h C void DRV_AK4954_CommandEventHandlerSet(DRV_HANDLE handle, const DRV_AK4954_COMMAND_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Returns None. Description This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. When a client calls DRV_AK4954_BufferAddWrite function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed. The event handler should be set before the client performs any "AK4954 CODEC Specific Client Routines" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the command has completed, it does not need to register a callback. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 driver instance. DRV_AK4954_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK4954_BUFFER_HANDLE bufferHandle; // myAK4954Handle is the handle returned // by the DRV_AK4954_Open function. // Client registers an event handler with driver DRV_AK4954_CommandEventHandlerSet(myAK4954Handle, APP_AK4954CommandEventHandler, (uintptr_t)&myAppObj); DRV_AK4954_DeEmphasisFilterSet(myAK4954Handle, DRV_AK4954_DEEMPHASIS_FILTER_44_1KHZ) // Event is received when // the buffer is processed. void APP_AK4954CommandEventHandler(uintptr_t contextHandle) { // contextHandle points to myAppObj. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 253 switch(event) { // Last Submitted command is completed. // Perform further processing here } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine eventHandler Pointer to the event handler function. context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_AK4954_CommandEventHandlerSet ( DRV_HANDLE handle, const DRV_AK4954_COMMAND_EVENT_HANDLER eventHandler, const uintptr_t contextHandle ) DRV_AK4954_BufferEventHandlerSet Function This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. File drv_ak4954.h C void DRV_AK4954_BufferEventHandlerSet(DRV_HANDLE handle, const DRV_AK4954_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Returns None. Description This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. When a client calls DRV_AK4954_BufferAddRead function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed. The event handler should be set before the client performs any "buffer add" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued buffer transfer has completed, it does not need to register a callback. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 driver instance. DRV_AK4954_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK4954_BUFFER_HANDLE bufferHandle; // myAK4954Handle is the handle returned // by the DRV_AK4954_Open function. // Client registers an event handler with driver DRV_AK4954_BufferEventHandlerSet(myAK4954Handle, Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 254 APP_AK4954BufferEventHandler, (uintptr_t)&myAppObj); DRV_AK4954_BufferAddRead(myAK4954handle, &bufferHandle myBuffer, MY_BUFFER_SIZE); if(DRV_AK4954_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_AK4954BufferEventHandler(DRV_AK4954_BUFFER_EVENT event, DRV_AK4954_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_AK4954_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_AK4954_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine eventHandler Pointer to the event handler function. context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_AK4954_BufferEventHandlerSet ( DRV_HANDLE handle, const DRV_AK4954_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle ) DRV_AK4954_SamplingRateSet Function This function sets the sampling rate of the media stream. Implementation: Dynamic File drv_ak4954.h C void DRV_AK4954_SamplingRateSet(DRV_HANDLE handle, uint32_t samplingRate); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 255 Returns None. Description This function sets the media sampling rate for the client handle. Remarks None. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 driver instance. DRV_AK4954_Open must have been called to obtain a valid opened device handle. Example // myAK4954Handle is the handle returned // by the DRV_AK4954_Open function. DRV_AK4954_SamplingRateSet(myAK4954Handle, 48000); //Sets 48000 media sampling rate Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4954_SamplingRateSet( DRV_HANDLE handle, uint32_t samplingRate) DRV_AK4954_SetAudioCommunicationMode Function This function provides a run time audio format configuration File drv_ak4954.h C void DRV_AK4954_SetAudioCommunicationMode(DRV_HANDLE handle, const DATA_LENGTH dl, const SAMPLE_LENGTH sl); Returns None Description This function sets up audio mode in I2S protocol Remarks None. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 driver instance. DRV_AK4954_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine dl Data length for I2S audio interface sl Left/Right Sample Length for I2S audio interface Function void DRV_AK4954_SetAudioCommunicationMode ( DRV_HANDLE handle, const DATA_LENGTH dl, Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 256 const SAMPLE_LENGTH sl ) b) Status Functions DRV_AK4954_SamplingRateGet Function This function gets the sampling rate set on the DAC AK4954. Implementation: Dynamic File drv_ak4954.h C uint32_t DRV_AK4954_SamplingRateGet(DRV_HANDLE handle); Returns None. Description This function gets the sampling rate set on the DAC AK4954. Remarks None. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 driver instance. DRV_AK4954_Open must have been called to obtain a valid opened device handle. Example uint32_t baudRate; // myAK4954Handle is the handle returned // by the DRV_AK4954_Open function. baudRate = DRV_AK4954_SamplingRateGet(myAK4954Handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function uint32_t DRV_AK4954_SamplingRateGet( DRV_HANDLE handle) DRV_AK4954_Status Function Gets the current status of the AK4954 driver module. Implementation: Dynamic File drv_ak4954.h C SYS_STATUS DRV_AK4954_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_DEINITIALIZED - Indicates that the driver has been deinitialized SYS_STATUS_READY - Indicates that any previous module operation for the specified module has completed SYS_STATUS_BUSY - Indicates that a previous module operation for the specified module has not yet completed SYS_STATUS_ERROR - Indicates that the specified module is in an error state Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 257 Description This routine provides the current status of the AK4954 driver module. Remarks A driver can opened only when its status is SYS_STATUS_READY. Preconditions Function DRV_AK4954_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_AK4954_Initialize SYS_STATUS AK4954Status; AK4954Status = DRV_AK4954_Status(object); if (SYS_STATUS_READY == AK4954Status) { // This means the driver can be opened using the // DRV_AK4954_Open() function. } Parameters Parameters Description object Driver object handle, returned from the DRV_AK4954_Initialize routine Function SYS_STATUS DRV_AK4954_Status( SYS_MODULE_OBJ object) DRV_AK4954_VersionGet Function This function returns the version of AK4954 driver. Implementation: Dynamic File drv_ak4954.h C uint32_t DRV_AK4954_VersionGet(); Returns returns the version of AK4954 driver. Description The version number returned from the DRV_AK4954_VersionGet function is an unsigned integer in the following decimal format. * 10000 + * 100 + Where the numbers are represented in decimal and the meaning is the same as above. Note that there is no numerical representation of release type. Remarks None. Preconditions None. Example 1 For version "0.03a", return: 0 * 10000 + 3 * 100 + 0 For version "1.00", return: 1 * 100000 + 0 * 100 + 0 Example 2 uint32_t AK4954version; AK4954version = DRV_AK4954_VersionGet(); Function uint32_t DRV_AK4954_VersionGet( void ) Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 258 DRV_AK4954_VersionStrGet Function This function returns the version of AK4954 driver in string format. Implementation: Dynamic File drv_ak4954.h C int8_t* DRV_AK4954_VersionStrGet(); Returns returns a string containing the version of AK4954 driver. Description The DRV_AK4954_VersionStrGet function returns a string in the format: ".[.][]" Where: is the AK4954 driver's version number. is the AK4954 driver's version number. is an optional "patch" or "dot" release number (which is not included in the string if it equals "00"). is an optional release type ("a" for alpha, "b" for beta ? not the entire word spelled out) that is not included if the release is a production version (I.e. Not an alpha or beta). The String does not contain any spaces. Remarks None. Preconditions None. Example 1 "0.03a" "1.00" Example 2 int8_t *AK4954string; AK4954string = DRV_AK4954_VersionStrGet(); Function int8_t* DRV_AK4954_VersionStrGet(void) DRV_AK4954_VolumeGet Function This function gets the volume for AK4954 CODEC. Implementation: Dynamic File drv_ak4954.h C uint8_t DRV_AK4954_VolumeGet(DRV_HANDLE handle, DRV_AK4954_CHANNEL chan); Returns None. Description This functions gets the current volume programmed to the CODEC AK4954. Remarks None. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 driver instance. DRV_AK4954_Open must have been called to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 259 Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t volume; // myAK4954Handle is the handle returned // by the DRV_AK4954_Open function. volume = DRV_AK4954_VolumeGet(myAK4954Handle,DRV_AK4954_CHANNEL_LEFT); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine chan Audio channel volume to be set Function uint8_t DRV_AK4954_VolumeGet( DRV_HANDLE handle, DRV_AK4954_CHANNEL chan) c) Other Functions DRV_AK4954_VolumeSet Function This function sets the volume for AK4954 CODEC. Implementation: Dynamic File drv_ak4954.h C void DRV_AK4954_VolumeSet(DRV_HANDLE handle, DRV_AK4954_CHANNEL channel, uint8_t volume); Returns None. Description This functions sets the volume value from 0-255. The codec has DAC value to volume range mapping as :- 00 H : +12dB FF H : -115dB In order to make the volume value to dB mapping monotonically increasing from 00 to FF, re-mapping is introduced which reverses the volume value to dB mapping as well as normalizes the volume range to a more audible dB range. The current driver implementation assumes that all dB values under -60 dB are inaudible to the human ear. Re-Mapped values 00 H : -60 dB FF H : +12 dB Remarks None. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 driver instance. DRV_AK4954_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_BUFFER_HANDLE bufferHandle; // myAK4954Handle is the handle returned // by the DRV_AK4954_Open function. DRV_AK4954_VolumeSet(myAK4954Handle, DRV_AK4954_CHANNEL_LEFT, 120); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 260 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine chan Audio channel volume to be set volume volume value specified in the range 0-255 (0x00 to 0xFF) Function void DRV_AK4954_VolumeSet( DRV_HANDLE handle, DRV_AK4954_CHANNEL channel, uint8_t volume); DRV_AK4954_BufferAddRead Function Schedule a non-blocking driver read operation. File drv_ak4954.h C void DRV_AK4954_BufferAddRead(const DRV_HANDLE handle, DRV_AK4954_BUFFER_HANDLE * bufferHandle, void * buffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_AK4954_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking read operation. The function returns with a valid buffer handle in the bufferHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance receive queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_AK4954_BUFFER_HANDLE_INVALID • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0. • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_AK4954_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_AK4954_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the AK4954 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another AK4954 driver instance. It should not otherwise be called directly in an ISR. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 device instance and the DRV_AK4954_Status must have returned SYS_STATUS_READY. DRV_AK4954_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ must have been specified in the DRV_AK4954_Open call. Parameters Parameters Description handle Handle of the AK4954 instance as return by the DRV_AK4954_Open function. buffer Data to be transmitted. size Buffer size in bytes. bufferHandle Pointer to an argument that will contain the return buffer handle. Function void DRV_AK4954_BufferAddRead ( const DRV_HANDLE handle, DRV_AK4954_BUFFER_HANDLE *bufferHandle, Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 261 void *buffer, size_t size ) DRV_AK4954_BufferAddWrite Function Schedule a non-blocking driver write operation. Implementation: Dynamic File drv_ak4954.h C void DRV_AK4954_BufferAddWrite(const DRV_HANDLE handle, DRV_AK4954_BUFFER_HANDLE * bufferHandle, void * buffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_AK4954_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking write operation. The function returns with a valid buffer handle in the bufferHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance transmit queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_AK4954_BUFFER_HANDLE_INVALID • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0. • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_AK4954_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_AK4954_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the AK4954 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another AK4954 driver instance. It should not otherwise be called directly in an ISR. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 device instance and the DRV_AK4954_Status must have returned SYS_STATUS_READY. DRV_AK4954_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE must have been specified in the DRV_AK4954_Open call. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK4954_BUFFER_HANDLE bufferHandle; // myAK4954Handle is the handle returned // by the DRV_AK4954_Open function. // Client registers an event handler with driver DRV_AK4954_BufferEventHandlerSet(myAK4954Handle, APP_AK4954BufferEventHandler, (uintptr_t)&myAppObj); DRV_AK4954_BufferAddWrite(myAK4954handle, &bufferHandle myBuffer, MY_BUFFER_SIZE); if(DRV_AK4954_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 262 // the buffer is processed. void APP_AK4954BufferEventHandler(DRV_AK4954_BUFFER_EVENT event, DRV_AK4954_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_AK4954_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_AK4954_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle Handle of the AK4954 instance as return by the DRV_AK4954_Open function. buffer Data to be transmitted. size Buffer size in bytes. bufferHandle Pointer to an argument that will contain the return buffer handle. Function void DRV_AK4954_BufferAddWrite ( const DRV_HANDLE handle, DRV_AK4954_BUFFER_HANDLE *bufferHandle, void *buffer, size_t size ) DRV_AK4954_BufferAddWriteRead Function Schedule a non-blocking driver write-read operation. Implementation: Dynamic File drv_ak4954.h C void DRV_AK4954_BufferAddWriteRead(const DRV_HANDLE handle, DRV_AK4954_BUFFER_HANDLE * bufferHandle, void * transmitBuffer, void * receiveBuffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_AK4954_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking write-read operation. The function returns with a valid buffer handle in the bufferHandle argument if the write-read request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_AK4954_BUFFER_EVENT_COMPLETE: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the client opened the driver for read only or write only Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 263 • if the buffer size is 0 • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_AK4954_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_AK4954_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the AK4954 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another AK4954 driver instance. It should not otherwise be called directly in an ISR. This function is useful when there is valid read expected for every AK4954 write. The transmit and receive size must be same. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 device instance and the DRV_AK4954_Status must have returned SYS_STATUS_READY. DRV_AK4954_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READWRITE must have been specified in the DRV_AK4954_Open call. Example MY_APP_OBJ myAppObj; uint8_t mybufferTx[MY_BUFFER_SIZE]; uint8_t mybufferRx[MY_BUFFER_SIZE]; DRV_AK4954_BUFFER_HANDLE bufferHandle; // myak4954Handle is the handle returned // by the DRV_AK4954_Open function. // Client registers an event handler with driver DRV_AK4954_BufferEventHandlerSet(myak4954Handle, APP_AK4954BufferEventHandler, (uintptr_t)&myAppObj); DRV_AK4954_BufferAddWriteRead(myak4954handle, &bufferHandle, mybufferTx,mybufferRx,MY_BUFFER_SIZE); if(DRV_AK4954_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_AK4954BufferEventHandler(DRV_AK4954_BUFFER_EVENT event, DRV_AK4954_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_AK4954_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_AK4954_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 264 Parameters Parameters Description handle Handle of the AK4954 instance as returned by the DRV_AK4954_Open function bufferHandle Pointer to an argument that will contain the return buffer handle transmitBuffer The buffer where the transmit data will be stored receiveBuffer The buffer where the received data will be stored size Buffer size in bytes Function void DRV_AK4954_BufferAddWriteRead ( const DRV_HANDLE handle, DRV_AK4954_BUFFER_HANDLE *bufferHandle, void *transmitBuffer, void *receiveBuffer, size_t size ) DRV_AK4954_IntExtMicSet Function This function sets up the codec for the X32 DB internal or the external microphone use. File drv_ak4954.h C void DRV_AK4954_IntExtMicSet(DRV_HANDLE handle, DRV_AK4954_INT_EXT_MIC micInput); Returns None Description This function sets up the codec for the internal or the external microphone use. Remarks None. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 driver instance. DRV_AK4954_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine micInput Internal vs External mic input Function void DRV_AK4954_IntExtMicSet DRV_AK4954_MicSet Function This function sets up the codec for the internal or the AK4954 Mic1 or Mic2 input. File drv_ak4954.h C void DRV_AK4954_MicSet(DRV_HANDLE handle, DRV_AK4954_MIC micInput); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 265 Returns None Description This function sets up the codec. Remarks None. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 driver instance. DRV_AK4954_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine micInput Internal vs External mic input Function void DRV_AK4954_IntMic12Set DRV_AK4954_MonoStereoMicSet Function This function sets up the codec for the Mono or Stereo microphone mode. File drv_ak4954.h C void DRV_AK4954_MonoStereoMicSet(DRV_HANDLE handle, DRV_AK4954_MONO_STEREO_MIC mono_stereo_mic); Returns None Description This function sets up the codec for the Mono or Stereo microphone mode. Remarks None. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 driver instance. DRV_AK4954_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4954_MonoStereoMicSet( DRV_HANDLE handle); DRV_AK4954_MuteOff Function This function disables AK4954 output for soft mute. Implementation: Dynamic File drv_ak4954.h Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 266 C void DRV_AK4954_MuteOff(DRV_HANDLE handle); Returns None. Description This function disables AK4954 output for soft mute. Remarks None. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 driver instance. DRV_AK4954_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_BUFFER_HANDLE bufferHandle; // myAK4954Handle is the handle returned // by the DRV_AK4954_Open function. DRV_AK4954_MuteOff(myAK4954Handle); //AK4954 output soft mute disabled Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4954_MuteOff( DRV_HANDLE handle) DRV_AK4954_MuteOn Function This function allows AK4954 output for soft mute on. Implementation: Dynamic File drv_ak4954.h C void DRV_AK4954_MuteOn(DRV_HANDLE handle); Returns None. Description This function Enables AK4954 output for soft mute. Remarks None. Preconditions The DRV_AK4954_Initialize routine must have been called for the specified AK4954 driver instance. DRV_AK4954_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 267 uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_BUFFER_HANDLE bufferHandle; // myAK4954Handle is the handle returned // by the DRV_AK4954_Open function. DRV_AK4954_MuteOn(myAK4954Handle); //AK4954 output soft muted Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_AK4954_MuteOn( DRV_HANDLE handle); d) Data Types and Constants DRV_AK4954_AUDIO_DATA_FORMAT Enumeration Identifies the Serial Audio data interface format. File drv_ak4954.h C typedef enum { DRV_AK4954_AUDIO_DATA_FORMAT_24BIT_MSB_SDTO_24BIT_LSB_SDTI = 0, DRV_AK4954_AUDIO_DATA_FORMAT_24BIT_MSB_SDTO_16BIT_LSB_SDTI, DRV_AK4954_AUDIO_DATA_FORMAT_24BIT_MSB_SDTO_24BIT_MSB_SDTI, DRV_AK4954_AUDIO_DATA_FORMAT_I2S_16BIT_24BIT, DRV_AK4954_AUDIO_DATA_FORMAT_32BIT_MSB_SDTO_32BIT_MSB_SDTI = 6, DRV_AK4954_AUDIO_DATA_FORMAT_I2S_32BIT } DRV_AK4954_AUDIO_DATA_FORMAT; Description AK4954 Audio data format This enumeration identifies Serial Audio data interface format. DRV_AK4954_BUFFER_EVENT Enumeration Identifies the possible events that can result from a buffer add request. File drv_ak4954.h C typedef enum { DRV_AK4954_BUFFER_EVENT_COMPLETE, DRV_AK4954_BUFFER_EVENT_ERROR, DRV_AK4954_BUFFER_EVENT_ABORT } DRV_AK4954_BUFFER_EVENT; Members Members Description DRV_AK4954_BUFFER_EVENT_COMPLETE Data was transferred successfully. DRV_AK4954_BUFFER_EVENT_ERROR Error while processing the request DRV_AK4954_BUFFER_EVENT_ABORT Data transfer aborted (Applicable in DMA mode) Description AK4954 Driver Events This enumeration identifies the possible events that can result from a buffer add request caused by the client calling either the Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 268 DRV_AK4954_BufferAddWrite() function. Remarks One of these values is passed in the "event" parameter of the event handling callback function that the client registered with the driver by calling the DRV_AK4954_BufferEventHandlerSet function when a buffer transfer request is completed. DRV_AK4954_BUFFER_EVENT_HANDLER Type Pointer to a AK4954 Driver Buffer Event handler function File drv_ak4954.h C typedef void (* DRV_AK4954_BUFFER_EVENT_HANDLER)(DRV_AK4954_BUFFER_EVENT event, DRV_AK4954_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle); Returns None. Description AK4954 Driver Buffer Event Handler Function This data type defines the required function signature for the AK4954 driver buffer event handling callback function. A client must register a pointer to a buffer event handling function who's function signature (parameter and return value types) match the types specified by this function pointer in order to receive buffer related event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks If the event is DRV_AK4954_BUFFER_EVENT_COMPLETE, this means that the data was transferred successfully. If the event is DRV_AK4954_BUFFER_EVENT_ERROR, this means that the data was not transferred successfully. The bufferHandle parameter contains the buffer handle of the buffer that failed. The DRV_AK4954_BufferProcessedSizeGet() function can be called to find out how many bytes were processed. The bufferHandle parameter contains the buffer handle of the buffer that associated with the event. The context parameter contains a handle to the client context, provided at the time the event handling function was registered using the DRV_AK4954_BufferEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the buffer add request. The buffer handle in bufferHandle expires after this event handler exits. In that the buffer object that was allocated is deallocated by the driver after the event handler exits. The event handler function executes in the data driver (I2S) peripheral's interrupt context when the driver is configured for interrupt mode operation. It is recommended of the application to not perform process intensive or blocking operations with in this function. DRV_AK4954_BufferAddWrite function can be called in the event handler to add a buffer to the driver queue. Example void APP_MyBufferEventHandler( DRV_AK4954_BUFFER_EVENT event, DRV_AK4954_BUFFER_HANDLE bufferHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_AK4954_BUFFER_EVENT_COMPLETE: // Handle the completed buffer. break; case DRV_AK4954_BUFFER_EVENT_ERROR: default: // Handle error. break; } } Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 269 Parameters Parameters Description event Identifies the type of event bufferHandle Handle identifying the buffer to which the event relates context Value identifying the context of the application that registered the event handling function. DRV_AK4954_BUFFER_HANDLE Type Handle identifying a write buffer passed to the driver. File drv_ak4954.h C typedef uintptr_t DRV_AK4954_BUFFER_HANDLE; Description AK4954 Driver Buffer Handle A buffer handle value is returned by a call to the DRV_AK4954_BufferAddWrite() function. This handle is associated with the buffer passed into the function and it allows the application to track the completion of the data from (or into) that buffer. The buffer handle value returned from the "buffer add" function is returned back to the client by the "event handler callback" function registered with the driver. The buffer handle assigned to a client request expires when the client has been notified of the completion of the buffer transfer (after event handler function that notifies the client returns) or after the buffer has been retired by the driver if no event handler callback was set. Remarks None DRV_AK4954_CHANNEL Enumeration Identifies Left/Right Audio channel File drv_ak4954.h C typedef enum { DRV_AK4954_CHANNEL_LEFT, DRV_AK4954_CHANNEL_RIGHT, DRV_AK4954_CHANNEL_LEFT_RIGHT, DRV_AK4954_NUMBER_OF_CHANNELS } DRV_AK4954_CHANNEL; Description AK4954 Audio Channel This enumeration identifies Left/Right Audio channel Remarks None. DRV_AK4954_COMMAND_EVENT_HANDLER Type Pointer to a AK4954 Driver Command Event Handler Function File drv_ak4954.h C typedef void (* DRV_AK4954_COMMAND_EVENT_HANDLER)(uintptr_t contextHandle); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 270 Description AK4954 Driver Command Event Handler Function This data type defines the required function signature for the AK4954 driver command event handling callback function. A command is a control instruction to the AK4954 CODEC. Example Mute ON/OFF, Zero Detect Enable/Disable etc. A client must register a pointer to a command event handling function who's function signature (parameter and return value types) match the types specified by this function pointer in order to receive command related event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks The occurrence of this call back means that the last control command was transferred successfully. The context parameter contains a handle to the client context, provided at the time the event handling function was registered using the DRV_AK4954_CommandEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the buffer add request. The event handler function executes in the control data driver interrupt context. It is recommended of the application to not perform process intensive or blocking operations with in this function. Example void APP_AK4954CommandEventHandler( uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; // Last Submitted command is completed. // Perform further processing here } Parameters Parameters Description context Value identifying the context of the application that registered the event handling function. DRV_AK4954_DIGITAL_BLOCK_CONTROL Enumeration Identifies Bass-Boost Control function File drv_ak4954.h C typedef enum { DRV_AK4954_RECORDING_MODE, DRV_AK4954_PLAYBACK_MODE, DRV_AK4954_RECORDING_PLAYBACK_2_MODE, DRV_AK4954_LOOPBACK_MODE } DRV_AK4954_DIGITAL_BLOCK_CONTROL; Members Members Description DRV_AK4954_RECORDING_MODE This is the default setting DRV_AK4954_PLAYBACK_MODE Min control DRV_AK4954_RECORDING_PLAYBACK_2_MODE Medium control DRV_AK4954_LOOPBACK_MODE Maximum control Description AK4954 Bass-Boost Control This enumeration identifies the settings for Bass-Boost Control function. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 271 DRV_AK4954_INIT Structure Defines the data required to initialize or reinitialize the AK4954 driver File drv_ak4954.h C typedef struct { SYS_MODULE_INIT moduleInit; SYS_MODULE_INDEX i2sDriverModuleIndex; SYS_MODULE_INDEX i2cDriverModuleIndex; uint32_t samplingRate; uint8_t volume; DRV_AK4954_AUDIO_DATA_FORMAT audioDataFormat; bool delayDriverInitialization; } DRV_AK4954_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization SYS_MODULE_INDEX i2sDriverModuleIndex; Identifies data module(I2S) driver ID for data interface of CODEC SYS_MODULE_INDEX i2cDriverModuleIndex; Identifies data module(I2C) driver ID for control interface of CODEC uint32_t samplingRate; Sampling rate uint8_t volume; Volume DRV_AK4954_AUDIO_DATA_FORMAT audioDataFormat; Identifies the Audio data format bool delayDriverInitialization; true if driver initialization should be delayed due to shared RESET pin Description AK4954 Driver Initialization Data This data type defines the data required to initialize or reinitialize the AK4954 CODEC driver. Remarks None. DRV_AK4954_INT_EXT_MIC Enumeration Identifies the Mic input source. File drv_ak4954.h C typedef enum { INT_MIC, EXT_MIC } DRV_AK4954_INT_EXT_MIC; Description AK4954 Mic Internal / External Input This enumeration identifies the Mic input source. DRV_AK4954_MIC Enumeration File drv_ak4954.h C typedef enum { MIC1 = 0, MIC2, Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 272 MIC3, DRV_AK4954_NUMBER_OF_MIC } DRV_AK4954_MIC; Members Members Description MIC1 = 0 INT_MIC MIC2 EXT_MIC MIC3 LINE-IN Description This is type DRV_AK4954_MIC. DRV_AK4954_MONO_STEREO_MIC Enumeration Identifies the Mic input as Mono / Stereo. File drv_ak4954.h C typedef enum { ALL_ZEROS, MONO_RIGHT_CHANNEL, MONO_LEFT_CHANNEL, STEREO } DRV_AK4954_MONO_STEREO_MIC; Description AK4954 Mic Mono / Stereo Input This enumeration identifies the Mic input as Mono / Stereo. DRV_AK4954_BUFFER_HANDLE_INVALID Macro Definition of an invalid buffer handle. File drv_ak4954.h C #define DRV_AK4954_BUFFER_HANDLE_INVALID ((DRV_AK4954_BUFFER_HANDLE)(-1)) Description AK4954 Driver Invalid Buffer Handle This is the definition of an invalid buffer handle. An invalid buffer handle is returned by DRV_AK4954_BufferAddWrite() function if the buffer add request was not successful. Remarks None DRV_AK4954_COUNT Macro Number of valid AK4954 driver indices File drv_ak4954.h C #define DRV_AK4954_COUNT Description AK4954 Driver Module Count This constant identifies the maximum number of AK4954 Driver instances that should be defined by the application. Defining more instances than Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 273 this constant will waste RAM memory space. This constant can also be used by the application to identify the number of AK4954 instances on this microcontroller. Remarks This value is part-specific. DRV_AK4954_INDEX_0 Macro AK4954 driver index definitions File drv_ak4954.h C #define DRV_AK4954_INDEX_0 0 Description Driver AK4954 Module Index These constants provide AK4954 driver index definition. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_AK4954_Initialize and DRV_AK4954_Open routines to identify the driver instance in use. DRV_AK4954_INDEX_1 Macro File drv_ak4954.h C #define DRV_AK4954_INDEX_1 1 Description This is macro DRV_AK4954_INDEX_1. DRV_AK4954_INDEX_2 Macro File drv_ak4954.h C #define DRV_AK4954_INDEX_2 2 Description This is macro DRV_AK4954_INDEX_2. DRV_AK4954_INDEX_3 Macro File drv_ak4954.h C #define DRV_AK4954_INDEX_3 3 Description This is macro DRV_AK4954_INDEX_3. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 274 DRV_AK4954_INDEX_4 Macro File drv_ak4954.h C #define DRV_AK4954_INDEX_4 4 Description This is macro DRV_AK4954_INDEX_4. DRV_AK4954_INDEX_5 Macro File drv_ak4954.h C #define DRV_AK4954_INDEX_5 5 Description This is macro DRV_AK4954_INDEX_5. Files Files Name Description drv_ak4954.h AK4954 CODEC Driver Interface header file drv_ak4954_config_template.h AK4954 Codec Driver Configuration Template. Description This section lists the source and header files used by the AK4954Codec Driver Library. drv_ak4954.h AK4954 CODEC Driver Interface header file Enumerations Name Description DRV_AK4954_AUDIO_DATA_FORMAT Identifies the Serial Audio data interface format. DRV_AK4954_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_AK4954_CHANNEL Identifies Left/Right Audio channel DRV_AK4954_DIGITAL_BLOCK_CONTROL Identifies Bass-Boost Control function DRV_AK4954_INT_EXT_MIC Identifies the Mic input source. DRV_AK4954_MIC This is type DRV_AK4954_MIC. DRV_AK4954_MONO_STEREO_MIC Identifies the Mic input as Mono / Stereo. Functions Name Description DRV_AK4954_BufferAddRead Schedule a non-blocking driver read operation. DRV_AK4954_BufferAddWrite Schedule a non-blocking driver write operation. Implementation: Dynamic DRV_AK4954_BufferAddWriteRead Schedule a non-blocking driver write-read operation. Implementation: Dynamic DRV_AK4954_BufferEventHandlerSet This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. DRV_AK4954_Close Closes an opened-instance of the AK4954 driver. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 275 DRV_AK4954_CommandEventHandlerSet This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. Implementation: Dynamic DRV_AK4954_Deinitialize Deinitializes the specified instance of the AK4954 driver module. Implementation: Dynamic DRV_AK4954_Initialize Initializes hardware and data for the instance of the AK4954 DAC module. Implementation: Dynamic DRV_AK4954_IntExtMicSet This function sets up the codec for the X32 DB internal or the external microphone use. DRV_AK4954_MicSet This function sets up the codec for the internal or the AK4954 Mic1 or Mic2 input. DRV_AK4954_MonoStereoMicSet This function sets up the codec for the Mono or Stereo microphone mode. DRV_AK4954_MuteOff This function disables AK4954 output for soft mute. Implementation: Dynamic DRV_AK4954_MuteOn This function allows AK4954 output for soft mute on. Implementation: Dynamic DRV_AK4954_Open Opens the specified AK4954 driver instance and returns a handle to it. Implementation: Dynamic DRV_AK4954_SamplingRateGet This function gets the sampling rate set on the DAC AK4954. Implementation: Dynamic DRV_AK4954_SamplingRateSet This function sets the sampling rate of the media stream. Implementation: Dynamic DRV_AK4954_SetAudioCommunicationMode This function provides a run time audio format configuration DRV_AK4954_Status Gets the current status of the AK4954 driver module. Implementation: Dynamic DRV_AK4954_Tasks Maintains the driver's control and data interface state machine. Implementation: Dynamic DRV_AK4954_VersionGet This function returns the version of AK4954 driver. Implementation: Dynamic DRV_AK4954_VersionStrGet This function returns the version of AK4954 driver in string format. Implementation: Dynamic DRV_AK4954_VolumeGet This function gets the volume for AK4954 CODEC. Implementation: Dynamic DRV_AK4954_VolumeSet This function sets the volume for AK4954 CODEC. Implementation: Dynamic Macros Name Description DRV_AK4954_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_AK4954_COUNT Number of valid AK4954 driver indices DRV_AK4954_INDEX_0 AK4954 driver index definitions DRV_AK4954_INDEX_1 This is macro DRV_AK4954_INDEX_1. DRV_AK4954_INDEX_2 This is macro DRV_AK4954_INDEX_2. DRV_AK4954_INDEX_3 This is macro DRV_AK4954_INDEX_3. DRV_AK4954_INDEX_4 This is macro DRV_AK4954_INDEX_4. DRV_AK4954_INDEX_5 This is macro DRV_AK4954_INDEX_5. Structures Name Description DRV_AK4954_INIT Defines the data required to initialize or reinitialize the AK4954 driver Types Name Description DRV_AK4954_BUFFER_EVENT_HANDLER Pointer to a AK4954 Driver Buffer Event handler function DRV_AK4954_BUFFER_HANDLE Handle identifying a write buffer passed to the driver. DRV_AK4954_COMMAND_EVENT_HANDLER Pointer to a AK4954 Driver Command Event Handler Function Description AK4954 CODEC Driver Interface Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 276 The AK4954 CODEC device driver interface provides a simple interface to manage the AK4954 106dB 192kHz 24-Bit DAC that can be interfaced Microchip Microcontroller. This file provides the interface definition for the AK4954 CODEC device driver. File Name drv_AK4954.h Company Microchip Technology Inc. drv_ak4954_config_template.h AK4954 Codec Driver Configuration Template. Macros Name Description DRV_AK4954_BCLK_BIT_CLK_DIVISOR Indicates whether the initilization of the AK4954 codec should be delayed. DRV_AK4954_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_AK4954_INPUT_REFCLOCK Identifies the input REFCLOCK source to generate the MCLK to codec. DRV_AK4954_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_AK4954_MCLK_SAMPLE_FREQ_MULTPLIER Sets up the MCLK to LRCK Ratio to Generate Audio Stream for specified sampling frequency DRV_AK4954_MCLK_SOURCE Indicate the input clock frequency to generate the MCLK to codec. DRV_AK4954_QUEUE_DEPTH_COMBINED Number of entries of all queues in all instances of the driver. Description AK4954 Codec Driver Configuration Template These file provides the list of all the configurations that can be used with the driver. This file should not be included in the driver. File Name drv_ak4954_config_template.h Company Microchip Technology Inc. AK7755 Codec Driver Library This topic describes the AK7755 Codec Driver Library. Introduction This library provides an interface to manage the AK7755 Codec that is serially interfaced to a Microchip microcontroller for providing Audio Solutions. Description The AK7755 module is 16/20/24-bit Audio Codec from Asahi Kasei Microdevices Corporation. The AK7755 can be interfaced to Microchip microcontrollers through I2C and I2S serial interfaces. The I2C interface is used for control command transfer. The I2S interface is used for Audio data output. A typical interface of the AK7755 Codec to a Microchip PIC32 device is provided in the following diagram: Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 277 Features The AK7755 Codec supports the following features: • Two Digital Interfaces (I/F1, I/F2): • 4-channel/6-channel Digital Signal Input Port: MSB justified 24-bit, LSB justified 24/20/16-bit, I2S • Short/Long Frame • 24-bit linear, 8-bit A-law, 8-bit µ-law • TDM 256 fs (8-channel) MSB Justified and I2S Formats • SoftMute: On and Off • Stereo 24-bit ADC: • Sampling Frequency: fs = 8 kHz ~96 kHz • ADC Characteristics S/(N+D): 91 dB, DR, S/N: 102 dB • Two-Channel Analog Input Selector (Differential, Single-ended Input) • Channel Independent Microphone Analog Gain Amplifier (0 ~18 dB (2 dB Step), 18 ~36 dB (3 dB Step)) • Analog DRC (Dynamic Range Control) • Channel Independent Digital Volume (24 ~-103 dB, 0.5 dB Step Mute) • Digital HPF for DC Offset Cancelling • Mono 24-bit ADC: • Sampling Frequency: 8 kHz ~ 96 kHz • ADC Characteristics S/(N+D): 90 dB; DR, S/N: 100 dB • Line Amplifier: 21 dB ~ -21 dB, 3 dB Step • Digital Volume (24 dB ~ -103 dB, 0.5 dB step, Mute) • Digital HPF for DC Offset Cancelling • Stereo 24-bit DAC: • Sampling Frequency: fs = 8 kHz ~ 96 kHz • Digital Volume (12 dB ~ -115 dB, 0.5 step, Mute) • Digital De-emphasis Filter (tc = 50/15 µs, fs = 32 kHz, 44.1 kHz, 48 kHz) • Master Clock: 2560 fs (internally generated by PLL from 32, 48, 64, 128, 256 and 384 fs clock) Using the Library This topic describes the basic architecture of the AK7755 Codec Driver Library and provides information and examples on its use. Description Interface Header File: drv_AK7755.h The interface to the AK7755 Codec Driver library is defined in the drv_AK7755.h header file. Any C language source (.c) file that uses the AK7755 Codec Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the AK7755 Codec Driver Library 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 abstraction model shown in the following diagram depicts how the AK7755 Codec Driver is positioned in the MPLAB Harmony framework. The AK7755 Codec Driver uses the SPI and I2S drivers for control and audio data transfers to the AK7755 module. AK7755 Driver Abstraction Model Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 278 Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The AK7755 Codec Driver Library provides an API interface to transfer control commands and digital audio data to the serially interfaced AK7755 DAC module. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the AK7755 Codec Driver Library. Library Interface Section Description System Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Status Functions Provides status functions. Other Functions Provides driver specific miscellaneous functions such as sampling rate setting, control command functions, etc. Data Types and Constants These data types and constants are required while interacting and setting up the AK7755 Codec Driver Library. How the Library Works The library provides interfaces to support: • System Functionality • Client Functionality System Access This topic describes system initialization, implementations, and includes a system access code example. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 279 Description System Initialization The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization, each instance of the AK7755 module would be initialized with the following configuration settings (either passed dynamically at run time using DRV_AK7755_INIT or by using Initialization Overrides) that are supported by the specific AK7755 device hardware: • Device requested power state: one of the System Module Power States. For specific details please refer to Data Types and Constants in the Library Interface section. • I2C driver module index. The module index should be same as the one used in initializing the I2C Driver. • I2S driver module index. The module index should be same as the one used in initializing the I2S Driver. • Sampling rate • Audio data format. The audio data format should match with the audio data format settings done in I2S driver initialization • Power down pin port initialization • Queue size for the audio data transmit buffer The DRV_AK7755_Initialize API returns an object handle of the type SYS_MODULE_OBJ. The object handle returned by the Initialize interface would be used by the other system interfaces such as DRV_ AK7755_Deinitialize, DRV_ AK7755_Status and DRV_I2S_Tasks. Implementations The AK7755 Codec Driver can has the following implementation: Description MPLAB Harmony Components Dedicated hardware for control (I2C) and data (I2S) interface. Standard MPLAB Harmony drivers for I2C and I2S interfaces. Example: DRV_AK7755_INIT drvak7755Codec0InitData = { .moduleInit.value = SYS_MODULE_POWER_RUN_FULL, .i2sDriverModuleIndex = DRV_AK7755_I2S_DRIVER_MODULE_INDEX_IDX0, .i2cDriverModuleIndex = DRV_AK7755_I2C_DRIVER_MODULE_INDEX_IDX0, .volume = DRV_AK7755_VOLUME, .queueSizeTransmit = DRV_AK7755_TRANSMIT_QUEUE_SIZE, }; // Initialize the I2C driver DRV_I2C0_Initialize(); // Initialize the I2S driver. The I2S module index should be same as the one used in initializing // the I2S driver. sysObj.drvI2S0 = DRV_I2S_Initialize(DRV_I2S_INDEX_0, (SYS_MODULE_INIT *)&drvI2S0InitData); // Initialize the Codec driver sysObj.drvak7755Codec0 = DRV_AK7755_Initialize(DRV_AK7755_INDEX_0, (SYS_MODULE_INIT *)&drvak7755Codec0InitData); if (SYS_MODULE_OBJ_INVALID == AK7755DevObject) { // Handle error } Task Routine The DRV_AK7755_Tasks will be called from the System Task Service. Client Access For the application to start using an instance of the module, it must call the DRV_AK7755_Open function. The DRV_AK7755_Open provides a driver handle to the AK7755 Codec Driver instance for operations. If the driver is deinitialized using the function DRV_AK7755_Deinitialize, the application must call the DRV_AK7755_Open function again to set up the instance of the driver. For the various options available for IO_INTENT, please refer to Data Types and Constants in the Library Interface section. Client Operations This topic provides information on client operations and includes a control command and audio buffered data operation flow diagram. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 280 Description Client operations provide the API interface for control command and audio data transfer to the AK7755 Codec. The following AK7755 Codec specific control command functions are provided: • DRV_AK7755_SamplingRateSet • DRV_AK7755_SamplingRateGet • DRV_AK7755_VolumeSet • DRV_AK7755_VolumeGet • DRV_AK7755_MuteOn • DRV_AK7755_MuteOff • DRV_AK7755_IntExtMicSet • DRV_AK7755_MonoStereoMicSet These functions schedule a non-blocking control command transfer operation. These functions submit the control command request to the AK7755 Codec. These functions submit the control command request to I2C Driver transmit queue, the request is processed immediately if it is the first request, or processed when the previous request is complete. DRV_AK7755_BufferAddWrite, DRV_AK7755_BufferAddRead, and DRV_AK7755_BufferAddWriteRead are buffered data operation functions. These functions schedule non-blocking audio data transfer operations. These functions add the request to I2S Driver transmit or receive buffer queue depends on the request type, and are executed immediately if it is the first buffer, or executed later when the previous buffer is complete. The driver notifies the client with DRV_AK7755_BUFFER_EVENT_COMPLETE, DRV_AK7755_BUFFER_EVENT_ERROR, or DRV_AK7755_BUFFER_EVENT_ABORT events. The following diagram illustrates the control commands and audio buffered data operations. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 281 Note: It is not necessary to close and reopen the client between multiple transfers. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 282 Configuring the Library Macros Name Description DRV_AK7755_BCLK_BIT_CLK_DIVISOR Sets up the BCLK to LRCK ratio to generate the audio stream for the specified sampling frequency. DRV_AK7755_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_AK7755_INPUT_REFCLOCK Identifies the input REFCLOCK source to generate the MCLK to the codec. DRV_AK7755_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_AK7755_MCLK_SAMPLE_FREQ_MULTPLIER Sets up the MCLK to LRCK ratio to generate the audio stream for the specified sampling frequency. DRV_AK7755_MCLK_SOURCE Indicates the input clock frequency to generate the MCLK to the codec. Description The configuration of the AK7755 Codec Driver is based on the file system_config.h. This header file contains the configuration selection for the AK7755 Codec Driver. Based on the selections made, the driver may support the selected features. These configuration settings will apply to all instances of the AK7755 Codec Driver. This header can be placed anywhere, 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. DRV_AK7755_BCLK_BIT_CLK_DIVISOR Macro Sets up the BCLK to LRCK ratio to generate the audio stream for the specified sampling frequency. File drv_ak7755_config_template.h C #define DRV_AK7755_BCLK_BIT_CLK_DIVISOR Description AK7755 BCLK to LRCK Ratio to Generate Audio Stream This macro sets up the BCLK to LRCK ratio to generate the audio stream for the specified sampling frequency. The following BCLK to LRCK ratios are supported: • 16-bit data 16-bit channel: 32 fs; therefore, the divisor would be 8 • 16-bit data 32-bit channel: 64 fs; therefore, the divisor would be 4 Remarks None. DRV_AK7755_CLIENTS_NUMBER Macro Sets up the maximum number of clients that can be connected to any hardware instance. File drv_ak7755_config_template.h C #define DRV_AK7755_CLIENTS_NUMBER DRV_AK7755_INSTANCES_NUMBER Description AK7755 Client Count Configuration This macro sets up the maximum number of clients that can be connected to any hardware instance. Typically only one client could be connected to one hardware instance. This value represents the total number of clients to be supported across all hardware instances. Therefore, if there are five AK7755 hardware interfaces, this number will be 5. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 283 DRV_AK7755_INPUT_REFCLOCK Macro Identifies the input REFCLOCK source to generate the MCLK to the codec. File drv_ak7755_config_template.h C #define DRV_AK7755_INPUT_REFCLOCK Description AK7755 Input reference clock This macro identifies the input REFCLOCK source to generate the MCLK to the codec. Remarks None. DRV_AK7755_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported File drv_ak7755_config_template.h C #define DRV_AK7755_INSTANCES_NUMBER Description AK7755 driver objects configuration This macro sets up the maximum number of hardware instances that can be supported. It is recommended that this number be set exactly equal to the number of AK7755 Codec modules that are needed by the application. Hardware Instance support consumes RAM memory space. If this macro is not defined, the driver will be built statically. Remarks None. DRV_AK7755_MCLK_SAMPLE_FREQ_MULTPLIER Macro Sets up the MCLK to LRCK ratio to generate the audio stream for the specified sampling frequency. File drv_ak7755_config_template.h C #define DRV_AK7755_MCLK_SAMPLE_FREQ_MULTPLIER Description AK7755 MCLK to LRCK Ratio to Generate Audio Stream This macro sets up the MCLK to LRCK ratio to generate the audio stream for the specified I2S sampling frequency. The supported MCLK to sampling frequency ratios are as follows: • 256 fs • 384 fs • 512 fs • 768 fs • 1152 fs Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 284 DRV_AK7755_MCLK_SOURCE Macro Indicates the input clock frequency to generate the MCLK to the codec. File drv_ak7755_config_template.h C #define DRV_AK7755_MCLK_SOURCE Description AK7755 Data Interface Master Clock Speed configuration This macro indicates the input clock frequency to generate the MCLK to the codec. Remarks None. Configuring the MHC Description The following three figures show examples of MHC configurations for the AK7755 Codec Driver, I2S Driver, and the I2C Driver. Figure 1: AK7755 Codec Driver MHC Configuration Figure 2: I2S Driver MHC Configuration Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 285 Figure 3: I2C Driver MHC Configuration Migrating the AK7755 Driver From Earlier Versions of Microchip Harmony Prior to version 1.08 of MPLAB Harmony, the AK7755 Codec Driver Library used the static I2C driver implementation. Beginning with v1.08 of MPLAB Harmony, applications must use the Dynamic Driver implementation with the MHC configured as shown in Figure 3. In addition, PIC32MZ configurations require the "Include Force Write I2C Function (Master Mode Only - Ignore NACK from Slave)" option to be selected. Building the Library This section lists the files that are available in the AK7755 Codec Driver Library. Description This section list the files that are available in the /src folder of the AK7755 Codec 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. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 286 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 /framework/driver/codec/ak7755. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_ak7755.h Header file that exports the driver API. 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 /src/dynamic/drv_ak7755.c This file contains implementation of the AK7755 Codec Driver. 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 N/A No optional files are available for this library. Module Dependencies The AK7755 Codec Driver Library depends on the following modules: • I2S Driver Library • I2C Driver Library Library Interface a) System Interaction Functions Name Description DRV_AK7755_Close Closes an opened-instance of the AK7755 Codec Driver. DRV_AK7755_Deinitialize Deinitializes the specified instance of the AK7755 Codec Driver module. DRV_AK7755_Initialize Initializes hardware and data for the instance of the AK7755 DAC module DRV_AK7755_Open Opens the specified AK7755 Codec Driver instance and returns a handle to it DRV_AK7755_Tasks Maintains the driver's control and data interface state machine. DRV_AK7755_BufferEventHandlerSet This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. DRV_AK7755_CommandEventHandlerSet Allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. DRV_AK7755_SamplingRateSet This function sets the sampling rate of the media stream. DRV_AK7755_SetAudioCommunicationMode This function provides a run time audio format configuration b) Status Functions Name Description DRV_AK7755_SamplingRateGet This function gets the sampling rate set on the AK7755. Implementation: Dynamic DRV_AK7755_Status Gets the current status of the AK7755 Codec Driver module. DRV_AK7755_VersionGet Returns the version of the AK7755 Codec Driver. DRV_AK7755_VersionStrGet This function returns the version of AK7755 Codec Driver in string format. DRV_AK7755_VolumeGet Gets the volume for the AK7755 Codec Driver. c) Other Functions Name Description DRV_AK7755_VolumeSet This function sets the volume for AK7755 CODEC. DRV_AK7755_BufferAddRead Schedule a non-blocking driver read operation. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 287 DRV_AK7755_BufferAddWrite Schedule a non-blocking driver write operation. DRV_AK7755_BufferAddWriteRead This is function DRV_AK7755_BufferAddWriteRead. DRV_AK7755_IntExtMicSet Sets up the codec for the internal or the external microphone use. DRV_AK7755_MonoStereoMicSet Sets up the codec for the Mono or Stereo microphone mode. DRV_AK7755_MuteOff Disables AK7755 output for soft mute. DRV_AK7755_MuteOn Allows AK7755 output for soft mute on. d) Data Types and Constants Name Description _DRV_AK7755_H Include files. DRV_AK7755_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_AK7755_COUNT Number of valid AK7755 Codec Driver indices DRV_AK7755_INDEX_0 AK7755 driver index definitions DRV_AK7755_INDEX_1 This is macro DRV_AK7755_INDEX_1. DRV_AK7755_INDEX_2 This is macro DRV_AK7755_INDEX_2. DRV_AK7755_INDEX_3 This is macro DRV_AK7755_INDEX_3. DRV_AK7755_INDEX_4 This is macro DRV_AK7755_INDEX_4. DRV_AK7755_INDEX_5 This is macro DRV_AK7755_INDEX_5. DRV_AK7755_BICK_FS_FORMAT This is type DRV_AK7755_BICK_FS_FORMAT. DRV_AK7755_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_AK7755_BUFFER_EVENT_HANDLER Pointer to a AK7755 Driver Buffer Event handler function. DRV_AK7755_BUFFER_HANDLE Handle identifying a write buffer passed to the driver. DRV_AK7755_CHANNEL Identifies left/right audio channel. DRV_AK7755_COMMAND_EVENT_HANDLER Pointer to a AK7755 Codec Driver command event handler function. DRV_AK7755_DAC_INPUT_FORMAT Identifies the Serial Audio data interface format. DRV_AK7755_DSP_DIN1_INPUT_FORMAT This is type DRV_AK7755_DSP_DIN1_INPUT_FORMAT. DRV_AK7755_DSP_DOUT1_OUTPUT_FORMAT This is type DRV_AK7755_DSP_DOUT1_OUTPUT_FORMAT. DRV_AK7755_DSP_DOUT4_OUTPUT_FORMAT This is type DRV_AK7755_DSP_DOUT4_OUTPUT_FORMAT. DRV_AK7755_DSP_PROGRAM This is type DRV_AK7755_DSP_PROGRAM. DRV_AK7755_INIT Defines the data required to initialize or reinitialize the AK7755 Codec Driver. DRV_AK7755_INT_EXT_MIC Identifies the Mic input source. DRV_AK7755_LRCK_IF_FORMAT This is type DRV_AK7755_LRCK_IF_FORMAT. DRV_AK7755_MONO_STEREO_MIC Identifies the Mic input as Mono/Stereo. DRV_I2C_INDEX This is macro DRV_I2C_INDEX. DATA_LENGTH in bits SAMPLE_LENGTH in bits Description This section describes the API functions of the AK7755 Codec Driver library. Refer to each section for a detailed description. a) System Interaction Functions DRV_AK7755_Close Function Closes an opened-instance of the AK7755 Codec Driver. File drv_ak7755.h C void DRV_AK7755_Close(const DRV_HANDLE handle); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 288 Description This function closes an opened-instance of the AK7755 Codec Driver, invalidating the handle. Any buffers in the driver queue that were submitted by this client will be removed. After calling this function, the handle passed in "handle" must not be used with any of the remaining driver functions. A new handle must be obtained by calling DRV_AK7755_Open before the caller may use the driver again. Remarks Usually there is no need for the driver client to verify that the Close operation has completed. The driver will abort any ongoing operations when this function is called. Preconditions The DRV_AK7755_Initialize function must have been called for the specified AK7755 Codec Driver instance. DRV_AK7755_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_AK7755_Open DRV_AK7755_Close(handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function void DRV_AK7755_Close( DRV_Handle handle ) DRV_AK7755_Deinitialize Function Deinitializes the specified instance of the AK7755 Codec Driver module. File drv_ak7755.h C void DRV_AK7755_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description This function deinitializes the specified instance of the AK7755 Codec Driver module, disabling its operation (and any hardware). Invalidates all the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. Preconditions The DRV_AK7755_Initialize function should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_AK7755_Initialize SYS_STATUS status; DRV_AK7755_Deinitialize(object-->); status = DRV_AK7755_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 289 Parameters Parameters Description object Driver object handle, returned from the DRV_AK4642_Initialize routine Function void DRV_AK7755_Deinitialize( SYS_MODULE_OBJ object) DRV_AK7755_Initialize Function Initializes hardware and data for the instance of the AK7755 DAC module File drv_ak7755.h C SYS_MODULE_OBJ DRV_AK7755_Initialize(const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Description This function initializes the AK7755 Codec Driver instance for the specified driver index, making it ready for clients to open and use it. The initialization data is specified by the init parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. Remarks This function must be called before any other AK7755 function is called. This function should only be called once during system initialization unless DRV_AK7755_Deinitialize is called to deinitialize the driver instance. This function will NEVER block for hardware access. Preconditions DRV_I2S_Initialize must be called before calling this function to initialize the data interface of this codec driver. DRV_SPI_Initialize must be called if SPI driver is used for handling the control interface of this codec driver. Example DRV_AK7755_INIT init; SYS_MODULE_OBJ objectHandle; init->inUse = true; init->status = SYS_STATUS_BUSY; init->numClients = 0; init->i2sDriverModuleIndex = ak7755Init->i2sDriverModuleIndex; init->i2cDriverModuleIndex = ak7755Init->i2cDriverModuleIndex; init->samplingRate = DRV_AK7755_AUDIO_SAMPLING_RATE; init->audioDataFormat = DRV_AK7755_AUDIO_DATA_FORMAT_MACRO; init->isInInterruptContext = false; init->commandCompleteCallback = (DRV_AK7755_COMMAND_EVENT_HANDLER)0; init->commandContextData = 0; init->mclk_multiplier = DRV_AK7755_MCLK_SAMPLE_FREQ_MULTPLIER; objectHandle = DRV_AK7755_Initialize(DRV_AK7755_0, (SYS_MODULE_INIT*)init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description drvIndex Identifier for the driver instance to be initialized Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 290 init Pointer to the data structure containing any data necessary to initialize the hardware. This pointer may be null if no data is required and default initialization is to be used. Function SYS_MODULE_OBJ DRV_AK7755_Initialize ( const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT *const init ); DRV_AK7755_Open Function Opens the specified AK7755 Codec Driver instance and returns a handle to it File drv_ak7755.h C DRV_HANDLE DRV_AK7755_Open(const SYS_MODULE_INDEX iDriver, const DRV_IO_INTENT ioIntent); Returns If successful, the function returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Error can occur • if the number of client objects allocated via DRV_AK7755_CLIENTS_NUMBER is insufficient. • if the client is trying to open the driver but driver has been opened exclusively by another client. • if the driver hardware instance being opened is not initialized or is invalid. • if the ioIntent options passed are not relevant to this driver. Description This function opens the specified AK7755 Codec Driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. The DRV_IO_INTENT_BLOCKING and DRV_IO_INTENT_NONBLOCKING ioIntent options are not relevant to this driver. All the data transfer functions of this driver are non blocking. Only DRV_IO_INTENT_WRITE is a valid ioIntent option as AK7755 is DAC only. Specifying a DRV_IO_INTENT_EXCLUSIVE will cause the driver to provide exclusive access to this client. The driver cannot be opened by any other client. Remarks The handle returned is valid until the DRV_AK7755_Close function is called. This function will NEVER block waiting for hardware.If the requested intent flags are not supported, the function will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. It should not be called in an ISR. Preconditions The DRV_AK7755_Initialize function must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_AK7755_Open(DRV_AK7755_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver // May be the driver is not initialized or the initialization // is not complete. } Parameters Parameters Description drvIndex Identifier for the object instance to be opened ioIntent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver. See function description for details. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 291 Function DRV_HANDLE DRV_AK7755_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent ) DRV_AK7755_Tasks Function Maintains the driver's control and data interface state machine. File drv_ak7755.h C void DRV_AK7755_Tasks(SYS_MODULE_OBJ object); Returns None. Description This function is used to maintain the driver's internal control and data interface state machine and implement its control and data interface implementations. This function should be called from the SYS_Tasks function. Remarks This function is normally not called directly by an application. It is called by the system's Tasks function (SYS_Tasks). Preconditions The DRV_AK7755_Initialize function must have been called for the specified AK7755 Codec Driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_AK7755_Initialize while (true) { DRV_AK7755_Tasks (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_AK7755_Initialize) Function void DRV_AK7755_Tasks(SYS_MODULE_OBJ object); DRV_AK7755_BufferEventHandlerSet Function This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. File drv_ak7755.h C void DRV_AK7755_BufferEventHandlerSet(DRV_HANDLE handle, const DRV_AK7755_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 292 Description This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. When a client calls DRV_AK7755_BufferAddWrite function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed. The event handler should be set before the client performs any "buffer add" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued buffer transfer has completed, it does not need to register a callback. Preconditions The DRV_AK7755_Initialize function must have been called for the specified AK7755 Codec Driver instance. DRV_AK7755_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK7755_BUFFER_HANDLE bufferHandle; // myAK7755Handle is the handle returned // by the DRV_AK7755_Open function. // Client registers an event handler with driver DRV_AK7755_BufferEventHandlerSet(myAK7755Handle, APP_AK7755BufferEventHandler, (uintptr_t)&myAppObj); DRV_AK7755_BufferAddWrite(myAK7755handle, &bufferHandle myBuffer, MY_BUFFER_SIZE); if(DRV_AK7755_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_AK7755BufferEventHandler(DRV_AK7755_BUFFER_EVENT event, DRV_AK7755_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_AK7755_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_AK7755_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function eventHandler Pointer to the event handler function. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 293 context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_AK7755_BufferEventHandlerSet ( DRV_HANDLE handle, const DRV_AK7755_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle ) DRV_AK7755_CommandEventHandlerSet Function Allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. File drv_ak7755.h C void DRV_AK7755_CommandEventHandlerSet(DRV_HANDLE handle, const DRV_AK7755_COMMAND_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Returns None. Description This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. When a client calls DRV_AK7755_BufferAddWrite function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed. The event handler should be set before the client performs any "AK7755 CODEC Specific Client Routines" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the command has completed, it does not need to register a callback. Preconditions The DRV_AK7755_Initialize function must have been called for the specified AK7755 Codec Driver instance. DRV_AK7755_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK7755_BUFFER_HANDLE bufferHandle; // myAK7755Handle is the handle returned // by the DRV_AK7755_Open function. // Client registers an event handler with driver DRV_AK7755_CommandEventHandlerSet(myAK7755Handle, APP_AK7755CommandEventHandler, (uintptr_t)&myAppObj); DRV_AK7755_DeEmphasisFilterSet(myAK7755Handle, DRV_AK7755_DEEMPHASIS_FILTER_44_1KHZ) // Event is received when // the buffer is processed. void APP_AK7755CommandEventHandler(uintptr_t contextHandle) { // contextHandle points to myAppObj. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 294 switch(event) { // Last Submitted command is completed. // Perform further processing here } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function eventHandler Pointer to the event handler function. context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_AK7755_CommandEventHandlerSet ( DRV_HANDLE handle, const DRV_AK7755_COMMAND_EVENT_HANDLER eventHandler, const uintptr_t contextHandle ) DRV_AK7755_SamplingRateSet Function This function sets the sampling rate of the media stream. File drv_ak7755.h C void DRV_AK7755_SamplingRateSet(DRV_HANDLE handle, uint32_t samplingRate); Returns None. Description This function sets the media sampling rate for the client handle. Remarks None. Preconditions The DRV_AK7755_Initialize function must have been called for the specified AK7755 Codec Driver instance. DRV_AK7755_Open must have been called to obtain a valid opened device handle. Example // myAK7755Handle is the handle returned // by the DRV_AK7755_Open function. DRV_AK7755_SamplingRateSet(myAK7755Handle, 48000); //Sets 48000 media sampling rate Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function samplingRate Sampling frequency in Hz Function void DRV_AK7755_SamplingRateSet( DRV_HANDLE handle, uint32_t samplingRate) Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 295 DRV_AK7755_SetAudioCommunicationMode Function This function provides a run time audio format configuration File drv_ak7755.h C void DRV_AK7755_SetAudioCommunicationMode(DRV_HANDLE handle, const DATA_LENGTH dl, const SAMPLE_LENGTH sl); Returns None Description This function sets up audio mode in I2S protocol Remarks None. Preconditions The DRV_AK7755_Initialize routine must have been called for the specified AK7755 driver instance. DRV_AK7755_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine dl Data length for I2S audio interface sl Left/Right Sample Length for I2S audio interface Function void DRV_AK7755_SetAudioCommunicationMode ( DRV_HANDLE handle, const DATA_LENGTH dl, const SAMPLE_LENGTH sl ) b) Status Functions DRV_AK7755_SamplingRateGet Function This function gets the sampling rate set on the AK7755. Implementation: Dynamic File drv_ak7755.h C uint32_t DRV_AK7755_SamplingRateGet(DRV_HANDLE handle); Description This function gets the sampling rate set on the DAC AK7755. Remarks None. Example uint32_t baudRate; Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 296 // myAK7755Handle is the handle returned // by the DRV_AK7755_Open function. baudRate = DRV_AK7755_SamplingRateGet(myAK7755Handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function uint32_t DRV_AK7755_SamplingRateGet( DRV_HANDLE handle) DRV_AK7755_Status Function Gets the current status of the AK7755 Codec Driver module. File drv_ak7755.h C SYS_STATUS DRV_AK7755_Status(SYS_MODULE_OBJ object); Returns • SYS_STATUS_DEINITIALIZED - Indicates that the driver has been deinitialized • SYS_STATUS_READY - Indicates that any previous module operation for the specified module has completed • SYS_STATUS_BUSY - Indicates that a previous module operation for the specified module has not yet completed • SYS_STATUS_ERROR - Indicates that the specified module is in an error state Description This function provides the current status of the AK7755 Codec Driver module. Remarks A driver can be opened only when its status is SYS_STATUS_READY. Preconditions The DRV_AK7755_Initialize function should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_AK7755_Initialize SYS_STATUS AK7755Status; AK7755Status = DRV_AK7755_Status(object); if (SYS_STATUS_READY == AK7755Status) { // This means the driver can be opened using the // DRV_AK7755_Open function. } Parameters Parameters Description object Driver object handle, returned from the DRV_AK4642_Initialize routine Function SYS_STATUS DRV_AK7755_Status( SYS_MODULE_OBJ object) DRV_AK7755_VersionGet Function Returns the version of the AK7755 Codec Driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 297 File drv_ak7755.h C uint32_t DRV_AK7755_VersionGet(); Returns Returns the version of the AK7755 Codec Driver. Description The version number returned from the DRV_AK7755_VersionGet function is an unsigned integer in the following decimal format: • * 10000 + * 100 + Where the numbers are represented in decimal and the meaning is the same as above. Note that there is no numerical representation of release type. Remarks None. Preconditions None. Example 1 • For version "0.03a", return: 0 * 10000 + 3 * 100 + 0 • For version "1.00", return: 1 * 100000 + 0 * 100 + 0 Example 2 uint32_t AK7755version; AK7755version = DRV_AK7755_VersionGet(); Function uint32_t DRV_AK7755_VersionGet( void ) DRV_AK7755_VersionStrGet Function This function returns the version of AK7755 Codec Driver in string format. File drv_ak7755.h C int8_t* DRV_AK7755_VersionStrGet(); Returns returns a string containing the version of the AK7755 Codec Driver. Description The DRV_AK7755_VersionStrGet function returns a string in the format: ".[.][]" Where: • is the AK7755 Codec Driver's version number. • is the AK7755 Codec Driver's version number. • is an optional "patch" or "dot" release number (which is not included in the string if it equals "00"). • is an optional release type ("a" for alpha, "b" for beta ? not the entire word spelled out) that is not included if the release is a production version (I.e. Not an alpha or beta). The String does not contain any spaces. For example, "0.03a" "1.00" Remarks None Preconditions None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 298 Example int8_t *AK7755string; AK7755string = DRV_AK7755_VersionStrGet(); Function int8_t* DRV_AK7755_VersionStrGet(void) DRV_AK7755_VolumeGet Function Gets the volume for the AK7755 Codec Driver. File drv_ak7755.h C uint8_t DRV_AK7755_VolumeGet(DRV_HANDLE handle, DRV_AK7755_CHANNEL channel); Returns None. Description This functions gets the current volume programmed to the AK7755 Codec Driver. Remarks None. Preconditions The DRV_AK7755_Initialize function must have been called for the specified AK7755 Codec Driver instance. DRV_AK7755_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t volume; // myAK7755Handle is the handle returned // by the DRV_AK7755_Open function. volume = DRV_AK7755_VolumeGet(myAK7755Handle, DRV_AK7755_CHANNEL_LEFT); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function channel argument indicating Left or Right or Both channel volume to be modified Function uint8_t DRV_AK7755_VolumeGet( DRV_HANDLE handle, DRV_AK7755_CHANNEL channel) c) Other Functions DRV_AK7755_VolumeSet Function This function sets the volume for AK7755 CODEC. File drv_ak7755.h C void DRV_AK7755_VolumeSet(DRV_HANDLE handle, DRV_AK7755_CHANNEL channel, uint8_t volume); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 299 Returns None Description This functions sets the volume value from 0-255, which can attenuate from -115 dB to +12 dB. All decibels below approximately -50 dB are inaudible. Remarks None. Preconditions The DRV_AK7755_Initialize function must have been called for the specified AK7755 Codec Driver instance. DRV_AK7755_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_BUFFER_HANDLE bufferHandle; // myAK7755Handle is the handle returned // by the DRV_AK7755_Open function. DRV_AK7755_VolumeSet(myAK7755Handle,DRV_AK7755_CHANNEL_LEFT, 120); //Step 120 volume Parameters Parameters Description handle A valid open-instance handle, returned from the driver's Open function channel argument indicating Left or Right or Both channel volume to be modified volume Updated volume specified in the range 0-255 Function void DRV_AK7755_VolumeSet( DRV_HANDLE handle, DRV_AK7755_CHANNEL channel, uint8_t volume); DRV_AK7755_BufferAddRead Function Schedule a non-blocking driver read operation. File drv_ak7755.h C void DRV_AK7755_BufferAddRead(const DRV_HANDLE handle, DRV_AK7755_BUFFER_HANDLE * bufferHandle, void * buffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_AK7755_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking read operation. The function returns with a valid buffer handle in the bufferHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance receive queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_AK7755_BUFFER_HANDLE_INVALID • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0. • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_AK7755_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_AK7755_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 300 Remarks This function is thread safe in a RTOS application. It can be called from within the AK7755 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another AK7755 Codec Driver instance. It should not otherwise be called directly in an ISR. Preconditions The DRV_AK7755_Initialize function must have been called for the specified AK7755 device instance and the DRV_AK7755_Status must have returned SYS_STATUS_READY. DRV_AK7755_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ must have been specified in the DRV_AK7755_Open call. Parameters Parameters Description handle Handle of the AK7755 instance as return by the DRV_AK7755_Open function. buffer Data to be transmitted. size Buffer size in bytes. bufferHandle Pointer to an argument that will contain the return buffer handle. Function void DRV_AK7755_BufferAddRead ( const DRV_HANDLE handle, DRV_AK7755_BUFFER_HANDLE *bufferHandle, void *buffer, size_t size ) DRV_AK7755_BufferAddWrite Function Schedule a non-blocking driver write operation. File drv_ak7755.h C void DRV_AK7755_BufferAddWrite(const DRV_HANDLE handle, DRV_AK7755_BUFFER_HANDLE * bufferHandle, void * buffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_AK7755_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking write operation. The function returns with a valid buffer handle in the bufferHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance transmit queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_AK7755_BUFFER_HANDLE_INVALID: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0 • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_AK7755_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_AK7755_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the AK7755 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another AK7755 Codec Driver instance. It should not otherwise be called directly in an ISR. Preconditions The DRV_AK7755_Initialize function must have been called for the specified AK7755 device instance and the DRV_AK7755_Status must have Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 301 returned SYS_STATUS_READY. DRV_AK7755_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE must have been specified in the DRV_AK7755_Open call. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_AK7755_BUFFER_HANDLE bufferHandle; // myAK7755Handle is the handle returned // by the DRV_AK7755_Open function. // Client registers an event handler with driver DRV_AK7755_BufferEventHandlerSet(myAK7755Handle, APP_AK7755BufferEventHandler, (uintptr_t)&myAppObj); DRV_AK7755_BufferAddWrite(myAK7755handle, &bufferHandle myBuffer, MY_BUFFER_SIZE); if(DRV_AK7755_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when the buffer is processed. void APP_AK7755BufferEventHandler(DRV_AK7755_BUFFER_EVENT event, DRV_AK7755_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_AK7755_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_AK7755_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle Handle of the AK7755 instance as return by the DRV_AK7755_Open function. buffer Data to be transmitted. size Buffer size in bytes. bufferHandle Pointer to an argument that will contain the return buffer handle. Function void DRV_AK7755_BufferAddWrite ( const DRV_HANDLE handle, DRV_AK7755_BUFFER_HANDLE *bufferHandle, void *buffer, size_t size ) Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 302 DRV_AK7755_BufferAddWriteRead Function File drv_ak7755.h C void DRV_AK7755_BufferAddWriteRead(const DRV_HANDLE handle, DRV_AK7755_BUFFER_HANDLE * bufferHandle, void * transmitBuffer, void * receiveBuffer, size_t size); Description This is function DRV_AK7755_BufferAddWriteRead. DRV_AK7755_IntExtMicSet Function Sets up the codec for the internal or the external microphone use. File drv_ak7755.h C void DRV_AK7755_IntExtMicSet(DRV_HANDLE handle, DRV_AK7755_INT_EXT_MIC micInput); Returns None. Description This function sets up the codec for the internal or the external microphone use. Remarks None. Preconditions The DRV_AK7755_Initialize function must have been called for the specified AK7755 Codec Driver instance. DRV_AK7755_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function micInput Internal vs. External microphone input Function void DRV_AK7755_IntExtMicSet( DRV_HANDLE handle); DRV_AK7755_MonoStereoMicSet Function Sets up the codec for the Mono or Stereo microphone mode. File drv_ak7755.h C void DRV_AK7755_MonoStereoMicSet(DRV_HANDLE handle, DRV_AK7755_MONO_STEREO_MIC mono_stereo_mic); Returns None. Description This function sets up the codec for the Mono or Stereo microphone mode. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 303 Remarks None. Preconditions The DRV_AK7755_Initialize function must have been called for the specified AK7755 Codec Driver instance. DRV_AK7755_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function mono_stereo_mic Mono/Stereo microphone setup Function void DRV_AK7755_MonoStereoMicSet( DRV_HANDLE handle); DRV_AK7755_MuteOff Function Disables AK7755 output for soft mute. File drv_ak7755.h C void DRV_AK7755_MuteOff(DRV_HANDLE handle); Returns None. Description This function disables AK7755 output for soft mute. Remarks None. Preconditions The DRV_AK7755_Initialize function must have been called for the specified AK7755 Codec Driver instance. DRV_AK7755_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_BUFFER_HANDLE bufferHandle; // myAK7755Handle is the handle returned // by the DRV_AK7755_Open function. DRV_AK7755_MuteOff(myAK7755Handle); //AK7755 output soft mute disabled Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function void DRV_AK7755_MuteOff( DRV_HANDLE handle) DRV_AK7755_MuteOn Function Allows AK7755 output for soft mute on. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 304 File drv_ak7755.h C void DRV_AK7755_MuteOn(DRV_HANDLE handle); Returns None. Description This function enables AK7755 output for soft mute. Remarks None. Preconditions The DRV_AK7755_Initialize function must have been called for the specified AK7755 Codec Driver instance. DRV_AK7755_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_BUFFER_HANDLE bufferHandle; // myAK7755Handle is the handle returned // by the DRV_AK7755_Open function. DRV_AK7755_MuteOn(myAK7755Handle); //AK7755 output soft muted Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function void DRV_AK7755_MuteOn( DRV_HANDLE handle); d) Data Types and Constants _DRV_AK7755_H Macro File drv_ak7755.h C #define _DRV_AK7755_H Description Include files. DRV_AK7755_BUFFER_HANDLE_INVALID Macro Definition of an invalid buffer handle. File drv_ak7755.h C #define DRV_AK7755_BUFFER_HANDLE_INVALID ((DRV_AK7755_BUFFER_HANDLE)(-1)) Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 305 Description AK7755 Driver Invalid Buffer Handle This is the definition of an invalid buffer handle. An invalid buffer handle is returned by DRV_AK7755_BufferAddWrite and the DRV_AK7755_BufferAddRead function if the buffer add request was not successful. Remarks None. DRV_AK7755_COUNT Macro Number of valid AK7755 Codec Driver indices File drv_ak7755.h C #define DRV_AK7755_COUNT Description AK7755 Driver Module Count This constant identifies the maximum number of AK7755 Codec Driver instances that should be defined by the application. Defining more instances than this constant will waste RAM memory space. This constant can also be used by the application to identify the number of AK7755 instances on this microcontroller. Remarks This value is device-specific. DRV_AK7755_INDEX_0 Macro AK7755 driver index definitions File drv_ak7755.h C #define DRV_AK7755_INDEX_0 0 Description Driver AK7755 Module Index These constants provide AK7755 Codec Driver index definition. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_AK7755_Initialize and DRV_AK7755_Open functions to identify the driver instance in use. DRV_AK7755_INDEX_1 Macro File drv_ak7755.h C #define DRV_AK7755_INDEX_1 1 Description This is macro DRV_AK7755_INDEX_1. DRV_AK7755_INDEX_2 Macro File drv_ak7755.h Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 306 C #define DRV_AK7755_INDEX_2 2 Description This is macro DRV_AK7755_INDEX_2. DRV_AK7755_INDEX_3 Macro File drv_ak7755.h C #define DRV_AK7755_INDEX_3 3 Description This is macro DRV_AK7755_INDEX_3. DRV_AK7755_INDEX_4 Macro File drv_ak7755.h C #define DRV_AK7755_INDEX_4 4 Description This is macro DRV_AK7755_INDEX_4. DRV_AK7755_INDEX_5 Macro File drv_ak7755.h C #define DRV_AK7755_INDEX_5 5 Description This is macro DRV_AK7755_INDEX_5. DRV_AK7755_BICK_FS_FORMAT Enumeration File drv_ak7755.h C typedef enum { DRV_AK7755_BICK_64FS, DRV_AK7755_BICK_48FS, DRV_AK7755_BICK_32FS, DRV_AK7755_BICK_256FS } DRV_AK7755_BICK_FS_FORMAT; Description This is type DRV_AK7755_BICK_FS_FORMAT. DRV_AK7755_BUFFER_EVENT Enumeration Identifies the possible events that can result from a buffer add request. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 307 File drv_ak7755.h C typedef enum { DRV_AK7755_BUFFER_EVENT_COMPLETE, DRV_AK7755_BUFFER_EVENT_ERROR, DRV_AK7755_BUFFER_EVENT_ABORT } DRV_AK7755_BUFFER_EVENT; Members Members Description DRV_AK7755_BUFFER_EVENT_COMPLETE Data was transferred successfully. DRV_AK7755_BUFFER_EVENT_ERROR Error while processing the request DRV_AK7755_BUFFER_EVENT_ABORT Data transfer aborted (Applicable in DMA mode) Description AK7755 Driver Events This enumeration identifies the possible events that can result from a buffer add request caused by the client calling either the DRV_AK7755_BufferAddWrite or the DRV_AK7755_BufferAddRead function. Remarks One of these values is passed in the "event" parameter of the event handling callback function that the client registered with the driver by calling the DRV_AK7755_BufferEventHandlerSet function when a buffer transfer request is completed. DRV_AK7755_BUFFER_EVENT_HANDLER Type Pointer to a AK7755 Driver Buffer Event handler function. File drv_ak7755.h C typedef void (* DRV_AK7755_BUFFER_EVENT_HANDLER)(DRV_AK7755_BUFFER_EVENT event, DRV_AK7755_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle); Returns None. Description AK7755 Driver Buffer Event Handler Function This data type defines the required function signature for the AK7755 Codec Driver buffer event handling callback function. A client must register a pointer to a buffer event handling function whose function signature (parameter and return value types) match the types specified by this function pointer in order to receive buffer related event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks If the event is DRV_AK7755_BUFFER_EVENT_COMPLETE, this means that the data was transferred successfully. If the event is DRV_AK7755_BUFFER_EVENT_ERROR, this means that the data was not transferred successfully. The bufferHandle parameter contains the buffer handle of the buffer that failed. The DRV_AK7755_BufferProcessedSizeGet function can be called to find out how many bytes were processed. The bufferHandle parameter contains the buffer handle of the buffer that associated with the event. The context parameter contains a handle to the client context, provided at the time the event handling function was registered using the DRV_AK7755_BufferEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the buffer add request. The buffer handle in bufferHandle expires after this event handler exits. In that the buffer object that was allocated is deallocated by the driver after the event handler exits. The event handler function executes in the data driver (i.e., I2S) peripheral's interrupt context when the driver is configured for interrupt mode operation. It is recommended of the application to not perform process intensive or blocking operations with in this function. DRV_AK7755_BufferAddWrite function can be called in the event handler to add a buffer to the driver queue. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 308 Example void APP_MyBufferEventHandler( DRV_AK7755_BUFFER_EVENT event, DRV_AK7755_BUFFER_HANDLE bufferHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_AK7755_BUFFER_EVENT_COMPLETE: // Handle the completed buffer. break; case DRV_AK7755_BUFFER_EVENT_ERROR: default: // Handle error. break; } } Parameters Parameters Description event Identifies the type of event bufferHandle Handle identifying the buffer to which the event relates context Value identifying the context of the application that registered the event handling function. DRV_AK7755_BUFFER_HANDLE Type Handle identifying a write buffer passed to the driver. File drv_ak7755.h C typedef uintptr_t DRV_AK7755_BUFFER_HANDLE; Description AK7755 Driver Buffer Handle A buffer handle value is returned by a call to the DRV_AK7755_BufferAddWrite or DRV_AK7755_BufferAddRead function. This handle is associated with the buffer passed into the function and it allows the application to track the completion of the data from (or into) that buffer. The buffer handle value returned from the "buffer add" function is returned back to the client by the "event handler callback" function registered with the driver. The buffer handle assigned to a client request expires when the client has been notified of the completion of the buffer transfer (after event handler function that notifies the client returns) or after the buffer has been retired by the driver if no event handler callback was set. Remarks None. DRV_AK7755_CHANNEL Enumeration Identifies left/right audio channel. File drv_ak7755.h C typedef enum { DRV_AK7755_CHANNEL_LEFT, DRV_AK7755_CHANNEL_RIGHT, DRV_AK7755_CHANNEL_LEFT_RIGHT, DRV_AK7755_NUMBER_OF_CHANNELS } DRV_AK7755_CHANNEL; Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 309 Description AK7755 Audio Channel This enumeration identifies the left/right audio channel. Remarks None. DRV_AK7755_COMMAND_EVENT_HANDLER Type Pointer to a AK7755 Codec Driver command event handler function. File drv_ak7755.h C typedef void (* DRV_AK7755_COMMAND_EVENT_HANDLER)(uintptr_t contextHandle); Returns None. Description AK7755 Driver Command Event Handler Function This data type defines the required function signature for the AK7755 Codec Driver command event handling callback function. A command is a control instruction to the AK7755 Codec. For example, Mute ON/OFF, Zero Detect Enable/Disable, etc. A client must register a pointer to a command event handling function whose function signature (parameter and return value types) match the types specified by this function pointer in order to receive command related event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks The occurrence of this call back means that the last control command was transferred successfully. The context parameter contains a handle to the client context, provided at the time the event handling function was registered using the DRV_AK7755_CommandEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the buffer add request. The event handler function executes in the control data driver interrupt context. It is recommended of the application to not perform process intensive or blocking operations with in this function. Example void APP_AK7755CommandEventHandler( uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; // Last Submitted command is completed. // Perform further processing here } Parameters Parameters Description context Value identifying the context of the application that registered the event handling function. DRV_AK7755_DAC_INPUT_FORMAT Enumeration Identifies the Serial Audio data interface format. File drv_ak7755.h C typedef enum { DRV_AK7755_DAC_INPUT_24BITMSB, DRV_AK7755_DAC_INPUT_24BITLSB, Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 310 DRV_AK7755_DAC_INPUT_20BITLSB, DRV_AK7755_DAC_INPUT_16BITLSB } DRV_AK7755_DAC_INPUT_FORMAT; Members Members Description DRV_AK7755_DAC_INPUT_20BITLSB not supported Description AK7755 Audio Data Format This enumeration identifies the Serial Audio data interface format. DRV_AK7755_DSP_DIN1_INPUT_FORMAT Enumeration File drv_ak7755.h C typedef enum { DRV_AK7755_DSP_DIN1_INPUT_24BITMSB, DRV_AK7755_DSP_DIN1_INPUT_24BITLSB, DRV_AK7755_DSP_DIN1_INPUT_20BITLSB, DRV_AK7755_DSP_DIN1_INPUT_16BITLSB } DRV_AK7755_DSP_DIN1_INPUT_FORMAT; Description This is type DRV_AK7755_DSP_DIN1_INPUT_FORMAT. DRV_AK7755_DSP_DOUT1_OUTPUT_FORMAT Enumeration File drv_ak7755.h C typedef enum { DRV_AK7755_DSP_DOUT1_OUTPUT_24BITMSB, DRV_AK7755_DSP_DOUT1_OUTPUT_24BITLSB, DRV_AK7755_DSP_DOUT1_OUTPUT_20BITLSB, DRV_AK7755_DSP_DOUT1_OUTPUT_16BITLSB } DRV_AK7755_DSP_DOUT1_OUTPUT_FORMAT; Description This is type DRV_AK7755_DSP_DOUT1_OUTPUT_FORMAT. DRV_AK7755_DSP_DOUT4_OUTPUT_FORMAT Enumeration File drv_ak7755.h C typedef enum { DRV_AK7755_DSP_DOUT4_OUTPUT_24BITMSB, DRV_AK7755_DSP_DOUT4_OUTPUT_24BITLSB, DRV_AK7755_DSP_DOUT4_OUTPUT_20BITLSB, DRV_AK7755_DSP_DOUT4_OUTPUT_16BITLSB } DRV_AK7755_DSP_DOUT4_OUTPUT_FORMAT; Description This is type DRV_AK7755_DSP_DOUT4_OUTPUT_FORMAT. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 311 DRV_AK7755_DSP_PROGRAM Enumeration File drv_ak7755.h C typedef enum { DRV_AK7755_DSP_ECHO_CANCELLATION, DRV_AK7755_DSP_REGULAR } DRV_AK7755_DSP_PROGRAM; Description This is type DRV_AK7755_DSP_PROGRAM. DRV_AK7755_INIT Structure Defines the data required to initialize or reinitialize the AK7755 Codec Driver. File drv_ak7755.h C typedef struct { SYS_MODULE_INIT moduleInit; SYS_MODULE_INDEX i2sDriverModuleIndex; SYS_MODULE_INDEX i2cDriverModuleIndex; uint32_t samplingRate; uint8_t volume; } DRV_AK7755_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization SYS_MODULE_INDEX i2sDriverModuleIndex; Identifies data module (I2S) driver ID for data interface of CODEC SYS_MODULE_INDEX i2cDriverModuleIndex; Identifies data module (I2C) driver ID for control interface of CODEC uint32_t samplingRate; Sampling rate uint8_t volume; Volume Description AK7755 Driver Initialization Data This data type defines the data required to initialize or reinitialize the AK7755 Codec Driver. Remarks None. DRV_AK7755_INT_EXT_MIC Enumeration Identifies the Mic input source. File drv_ak7755.h C typedef enum { INT_MIC, EXT_MIC } DRV_AK7755_INT_EXT_MIC; Description AK7755 Mic Internal / External Input This enumeration identifies the Mic input source. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 312 Remarks None. DRV_AK7755_LRCK_IF_FORMAT Enumeration File drv_ak7755.h C typedef enum { DRV_AK7755_LRCK_IF_STANDARD, DRV_AK7755_LRCK_IF_I2S_COMPATIBLE, DRV_AK7755_LRCK_IF_PCM_SHORT_FRAME, DRV_AK7755_LRCK_IF_PCM_LONG_FRAME } DRV_AK7755_LRCK_IF_FORMAT; Description This is type DRV_AK7755_LRCK_IF_FORMAT. DRV_AK7755_MONO_STEREO_MIC Enumeration Identifies the Mic input as Mono/Stereo. File drv_ak7755.h C typedef enum { ALL_ZEROS, MONO_RIGHT_CHANNEL, MONO_LEFT_CHANNEL, STEREO } DRV_AK7755_MONO_STEREO_MIC; Description AK7755 Mic Mono/Stereo Input This enumeration identifies the Mic input as Mono/Stereo. Remarks None. DRV_I2C_INDEX Macro File drv_wm8904.h C #define DRV_I2C_INDEX DRV_WM8904_I2C_INSTANCES_NUMBER Description This is macro DRV_I2C_INDEX. DATA_LENGTH Enumeration File drv_wm8904.h C typedef enum { DATA_LENGTH_16, DATA_LENGTH_24, DATA_LENGTH_32 Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 313 } DATA_LENGTH; Description in bits SAMPLE_LENGTH Enumeration File drv_ak7755.h C typedef enum { SAMPLE_LENGTH_16, SAMPLE_LENGTH_32 } SAMPLE_LENGTH; Description in bits Files Files Name Description drv_ak7755.h AK7755 CODEC Driver Interface header file drv_ak7755_config_template.h AK7755 Codec Driver configuration template. Description This section lists the source and header files used by the AK7755Codec Driver Library. drv_ak7755.h AK7755 CODEC Driver Interface header file Enumerations Name Description DRV_AK7755_BICK_FS_FORMAT This is type DRV_AK7755_BICK_FS_FORMAT. DRV_AK7755_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_AK7755_CHANNEL Identifies left/right audio channel. DRV_AK7755_DAC_INPUT_FORMAT Identifies the Serial Audio data interface format. DRV_AK7755_DSP_DIN1_INPUT_FORMAT This is type DRV_AK7755_DSP_DIN1_INPUT_FORMAT. DRV_AK7755_DSP_DOUT1_OUTPUT_FORMAT This is type DRV_AK7755_DSP_DOUT1_OUTPUT_FORMAT. DRV_AK7755_DSP_DOUT4_OUTPUT_FORMAT This is type DRV_AK7755_DSP_DOUT4_OUTPUT_FORMAT. DRV_AK7755_DSP_PROGRAM This is type DRV_AK7755_DSP_PROGRAM. DRV_AK7755_INT_EXT_MIC Identifies the Mic input source. DRV_AK7755_LRCK_IF_FORMAT This is type DRV_AK7755_LRCK_IF_FORMAT. DRV_AK7755_MONO_STEREO_MIC Identifies the Mic input as Mono/Stereo. SAMPLE_LENGTH in bits Functions Name Description DRV_AK7755_BufferAddRead Schedule a non-blocking driver read operation. DRV_AK7755_BufferAddWrite Schedule a non-blocking driver write operation. DRV_AK7755_BufferAddWriteRead This is function DRV_AK7755_BufferAddWriteRead. DRV_AK7755_BufferEventHandlerSet This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. DRV_AK7755_Close Closes an opened-instance of the AK7755 Codec Driver. DRV_AK7755_CommandEventHandlerSet Allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 314 DRV_AK7755_Deinitialize Deinitializes the specified instance of the AK7755 Codec Driver module. DRV_AK7755_Initialize Initializes hardware and data for the instance of the AK7755 DAC module DRV_AK7755_IntExtMicSet Sets up the codec for the internal or the external microphone use. DRV_AK7755_MonoStereoMicSet Sets up the codec for the Mono or Stereo microphone mode. DRV_AK7755_MuteOff Disables AK7755 output for soft mute. DRV_AK7755_MuteOn Allows AK7755 output for soft mute on. DRV_AK7755_Open Opens the specified AK7755 Codec Driver instance and returns a handle to it DRV_AK7755_SamplingRateGet This function gets the sampling rate set on the AK7755. Implementation: Dynamic DRV_AK7755_SamplingRateSet This function sets the sampling rate of the media stream. DRV_AK7755_SetAudioCommunicationMode This function provides a run time audio format configuration DRV_AK7755_Status Gets the current status of the AK7755 Codec Driver module. DRV_AK7755_Tasks Maintains the driver's control and data interface state machine. DRV_AK7755_VersionGet Returns the version of the AK7755 Codec Driver. DRV_AK7755_VersionStrGet This function returns the version of AK7755 Codec Driver in string format. DRV_AK7755_VolumeGet Gets the volume for the AK7755 Codec Driver. DRV_AK7755_VolumeSet This function sets the volume for AK7755 CODEC. Macros Name Description _DRV_AK7755_H Include files. DRV_AK7755_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_AK7755_COUNT Number of valid AK7755 Codec Driver indices DRV_AK7755_INDEX_0 AK7755 driver index definitions DRV_AK7755_INDEX_1 This is macro DRV_AK7755_INDEX_1. DRV_AK7755_INDEX_2 This is macro DRV_AK7755_INDEX_2. DRV_AK7755_INDEX_3 This is macro DRV_AK7755_INDEX_3. DRV_AK7755_INDEX_4 This is macro DRV_AK7755_INDEX_4. DRV_AK7755_INDEX_5 This is macro DRV_AK7755_INDEX_5. Structures Name Description DRV_AK7755_INIT Defines the data required to initialize or reinitialize the AK7755 Codec Driver. Types Name Description DRV_AK7755_BUFFER_EVENT_HANDLER Pointer to a AK7755 Driver Buffer Event handler function. DRV_AK7755_BUFFER_HANDLE Handle identifying a write buffer passed to the driver. DRV_AK7755_COMMAND_EVENT_HANDLER Pointer to a AK7755 Codec Driver command event handler function. Description AK7755 CODEC Driver Interface The AK7755 CODEC device driver interface provides a simple interface to manage the AK7755 16/24-Bit Codec that can be interfaced Microchip Microcontroller. This file provides the interface definition for the AK7755 Codec device driver. File Name drv_ak7755.h Company Microchip Technology Inc. drv_ak7755_config_template.h AK7755 Codec Driver configuration template. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 315 Macros Name Description DRV_AK7755_BCLK_BIT_CLK_DIVISOR Sets up the BCLK to LRCK ratio to generate the audio stream for the specified sampling frequency. DRV_AK7755_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_AK7755_INPUT_REFCLOCK Identifies the input REFCLOCK source to generate the MCLK to the codec. DRV_AK7755_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_AK7755_MCLK_SAMPLE_FREQ_MULTPLIER Sets up the MCLK to LRCK ratio to generate the audio stream for the specified sampling frequency. DRV_AK7755_MCLK_SOURCE Indicates the input clock frequency to generate the MCLK to the codec. Description AK7755 Codec Driver Configuration Template These file provides the list of all the configurations that can be used with the driver. This file should not be included in the driver. File Name drv_ak7755_config_template.h Company Microchip Technology Inc. WM8904 Codec Driver Library This topic describes the WM8904 Codec Driver Library. Introduction This library provides an Applications Programming Interface (API) to manage the WM8904 Codec that is serially interfaced to the I2C and I2S peripherals of a Microchip PIC32 microcontroller for the purpose of providing audio solutions. Description The WM8904 module is 24-bit Audio Codec from Cirrus Logic, which can operate in 16-, 20-, 24-, and 32-bit audio modes. The WM8904 can be interfaced to Microchip microcontrollers through I2C and I2S serial interfaces. The I2C interface is used to send commands and receive status, and the I2S interface is used for audio data output (to headphones or line-out) and input (from microphone or line-in). The WM8904 can be configured as either an I2S clock slave (receives all clocks from the host), or I2S clock master (generates I2S clocks from a master clock input MCLK). Currently the driver only supports master mode with headphone output and (optionally) microphone input. A typical interface of WM8904 to a Microchip PIC32 device using an I2C and SSC interface (configured as I2S), with the WM8904 set up as the I2S clock master, is provided in the following diagram: Features The WM8904 Codec supports the following features: • Audio Interface Format: 16-/20-/24-/32-bit interface, LSB justified or I2S format Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 316 • Sampling Frequency Range: 8 kHz to 96 kHz • Digital Volume Control: -71.625 to 0 dB in 192 steps • Soft mute capability Using the Library This topic describes the basic architecture of the WM8904 Codec Driver Library and provides information and examples on its use. Description Interface Header File: drv_WM8904.h The interface to the WM8904 Codec Driver library is defined in the drv_WM8904.h header file. Any C language source (.c) file that uses the WM8904 Codec Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the WM8904 Codec Driver Library 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 abstraction model shown in the following diagram depicts how the WM8904 Codec Driver is positioned in the MPLAB Harmony framework. The WM8904 Codec Driver uses the I2C and I2S drivers for control and audio data transfers to the WM8904 module. WM8904 Driver Abstraction Model Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The WM8904 Codec Driver Library provides an API interface to transfer control commands and digital audio data to the serially interfaced WM8904 Codec module. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the WM8904 Codec Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 317 Library Interface Section Description System Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Client Setup Functions Provides open and close functions. Data Transfer Functions Provides data transfer functions, such as Buffer Read and Write. Settings Functions Provides driver specific functions for settings, such as volume control and sampling rate. Other Functions Miscellaneous functions, such as getting the driver’s version number. Data Types and Constants These data types and constants are required while interacting and setting up the WM8904 Codec Driver Library. Note: All functions and constants in this section are named with the format DRV_ WM8904_xxx, where 'xxx' is a function name or constant. These names are redefined in the appropriate configuration’s system_config.h file to the format DRV_CODEC_xxx using #defines so that code in the application that references the library can be written as generically as possible (e.g., by writing DRV_CODEC_Open instead of DRV_ WM8904_Open etc.). This allows the codec type to be changed in the MHC without having to modify the application’s source code. How the Library Works The library provides interfaces to support: • System Functionality • Client Functionality System Access This topic describes system initialization, implementations, and includes a system access code example. Description System Initialization The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization in the system_init.c file, each instance of the WM8904 module would be initialized with the following configuration settings (either passed dynamically at run time using DRV_WM8904_INIT or by using Initialization Overrides) that are supported by the specific WM8904 device hardware: • Device requested power state: one of the System Module Power States. For specific details please refer to Data Types and Constants in the Library Interface section. • I2C driver module index. The module index should be same as the one used in initializing the I2C Driver • I2S driver module index. The module index should be same as the one used in initializing the I2S Driver • Sampling rate • Volume • Audio data format. The audio data format should match with the audio data format settings done in I2S driver initialization • Determines whether or not the microphone input is enabled The DRV_WM8904_Initialize API returns an object handle of the type SYS_MODULE_OBJ. The object handle returned by the Initialize interface would be used by the other system interfaces such as DRV_ WM8904_Deinitialize, DRV_ WM8904_Status and DRV_I2S_Tasks. Implementations The WM8904 Codec Driver can has the following implementation: Description MPLAB Harmony Components Dedicated hardware for control (I2C) and data (I2S) interface. Standard MPLAB Harmony drivers for I2C and I2S interfaces. Example: SYS_STATUS status; status = DRV_CODEC_Status(sysObjdrvCodec0); // see if codec is done initializing if (SYS_STATUS_READY == status) { // The driver can now be opened. codecData->codecClient.handle = DRV_CODEC_Open (DRV_CODEC_INDEX_0, DRV_IO_INTENT_WRITE | DRV_IO_INTENT_EXCLUSIVE); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 318 if(appData.wm8904Client.handle != DRV_HANDLE_INVALID) { appData.state = APP_STATE_WM8904_SET_BUFFER_HANDLER; } else { SYS_DEBUG(0, "Find out what's wrong \r\n"); } } else { /* driver is not ready */ } Task Routine The DRV_WM8904_Tasks will be called from the System Task Service. Client Access This topic describes driver initialization and provides a code example. Description For the application to start using an instance of the module, it must call the DRV_WM8904_Open function. The DRV_WM8904_Open function provides a driver handle to the WM8904 Codec Driver instance for operations. If the driver is deinitialized using the function DRV_WM8904_Deinitialize, the application must call the DRV_WM8904_Open function again to set up the instance of the driver. For the various options available for IO_INTENT, please refer to Data Types and Constants in the Library Interface section. Note: It is necessary to check the status of driver initialization before opening a driver instance. The status of the WM8904 Codec Driver can be known by calling DRV_ WM8904_Status. Example: DRV_HANDLE handle; SYS_STATUS wm8904Status; wm8904Status Status = DRV_WM8904_Status(sysObjects.wm8904Status DevObject); if (SYS_STATUS_READY == wm8904Status) { // The driver can now be opened. appData.wm8904Client.handle = DRV_WM8904_Open (DRV_WM8904_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if(appData.wm8904Client.handle != DRV_HANDLE_INVALID) { appData.state = APP_STATE_WM8904_SET_BUFFER_HANDLER; } else { SYS_DEBUG(0, "Find out what's wrong \r\n"); } } else { /* WM8904 Driver Is not ready */ } Client Operations This topic provides information on client operations and includes a control command and audio buffered data operation flow diagram. Description Client operations provide the API interface for control command and audio data transfer to the WM8904 Codec. The following WM8904 Codec specific control command functions are provided: • DRV_WM8904_SamplingRateSet • DRV_WM8904_SamplingRateGet • DRV_WM8904_VolumeSet • DRV_WM8904_VolumeGet Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 319 • DRV_WM8904_MuteOn • DRV_WM8904_MuteOff These functions schedule a non-blocking control command transfer operation. These functions submit the control command request to the WM8904 Codec. These functions submit the control command request to I2C Driver transmit queue, the request is processed immediately if it is the first request, or processed when the previous request is complete. DRV_WM8904_BufferAddWrite, DRV_WM8904_BufferAddRead, and DRV_WM8904_BufferAddWriteRead are buffered data operation functions. These functions schedule non-blocking audio data transfer operations. These functions add the request to I2S Driver transmit or receive buffer queue depends on the request type, and are executed immediately if it is the first buffer, or executed later when the previous buffer is complete. The driver notifies the client with DRV_WM8904_BUFFER_EVENT_COMPLETE, DRV_WM8904_BUFFER_EVENT_ERROR, or DRV_WM8904_BUFFER_EVENT_ABORT events. Note: It is not necessary to close and reopen the client between multiple transfers. Configuring the Library Enumerations Name Description DRV_WM8904_AUDIO_DATA_FORMAT Identifies the Serial Audio data interface format. Macros Name Description _DRV_WM8904_CONFIG_TEMPLATE_H This is macro _DRV_WM8904_CONFIG_TEMPLATE_H. DRV_CODEC_WM8904_MODE Specifies if codec is in Master or Slave mode. DRV_WM8904_BAUD_RATE Specifies the initial baud rate for the codec. DRV_WM8904_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_WM8904_ENABLE_MIC_INPUT Specifies whether to enable the microphone input. DRV_WM8904_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_WM8904_VOLUME Specifies the initial volume level. Description The configuration of the WM8904 Codec Driver is based on the file system_config.h. This header file contains the configuration selection for the WM8904 Codec Driver. Based on the selections made, the driver may support the selected features. These configuration settings will apply to all instances of the WM8904 Codec Driver. This header can be placed anywhere, 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. _DRV_WM8904_CONFIG_TEMPLATE_H Macro File drv_wm8904_config_template.h C #define _DRV_WM8904_CONFIG_TEMPLATE_H Description This is macro _DRV_WM8904_CONFIG_TEMPLATE_H. DRV_CODEC_WM8904_MODE Macro Specifies if codec is in Master or Slave mode. File drv_wm8904_config_template.h C #define DRV_CODEC_WM8904_MODE Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 320 Description WM8904 Codec Master/Slave Mode Indicates whether the codec is to be operating in a Master mode (generating word and bit clock as outputs) or Slave mode receiving word and bit clock as inputs). Remarks Only Master mode is supported at this time. DRV_WM8904_AUDIO_DATA_FORMAT Enumeration Identifies the Serial Audio data interface format. File drv_wm8904.h C typedef enum { DATA_16_BIT_LEFT_JUSTIFIED, DATA_16_BIT_I2S, DATA_32_BIT_LEFT_JUSTIFIED, DATA_32_BIT_I2S } DRV_WM8904_AUDIO_DATA_FORMAT; Description WM8904 Audio data format This enumeration identifies Serial Audio data interface format. DRV_WM8904_BAUD_RATE Macro Specifies the initial baud rate for the codec. File drv_wm8904_config_template.h C #define DRV_WM8904_BAUD_RATE Description WM8904 Baud Rate Sets the initial baud rate (sampling rate) for the codec. Typical values are 8000, 16000, 44100, 48000, 88200 and 96000. Remarks None. DRV_WM8904_CLIENTS_NUMBER Macro Sets up the maximum number of clients that can be connected to any hardware instance. File drv_wm8904_config_template.h C #define DRV_WM8904_CLIENTS_NUMBER Description WM8904 Client Count Configuration Sets up the maximum number of clients that can be connected to any hardware instance. Typically only one client could be connected to one hardware instance. This value represents the total number of clients to be supported across all hardware instances. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 321 DRV_WM8904_ENABLE_MIC_INPUT Macro Specifies whether to enable the microphone input. File drv_wm8904_config_template.h C #define DRV_WM8904_ENABLE_MIC_INPUT Description WM8904 Microphone Enable Indicates whether the ADC inputs for the two microphone channels (L-R) should be enabled. Remarks None. DRV_WM8904_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported File drv_wm8904_config_template.h C #define DRV_WM8904_INSTANCES_NUMBER Description WM8904 driver objects configuration Sets up the maximum number of hardware instances that can be supported. It is recommended that this number be set exactly equal to the number of WM8904 Codec modules that are needed by an application, namely one. Remarks None. DRV_WM8904_VOLUME Macro Specifies the initial volume level. File drv_wm8904_config_template.h C #define DRV_WM8904_VOLUME Description WM8904 Volume Sets the initial volume level, in the range 0-255. Remarks The value is mapped to an internal WM8904 volume level in the range 0-192 using a logarithmic table so the input scale appears linear (128 is half volume). Configuring the MHC Provides examples on how to configure the MPLAB Harmony Configurator (MHC) for a specific driver. Description The following figure shows an example of an MHC configuration for the WM8904 Codec Driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 322 Building the Library This section lists the files that are available in the WM8904 Codec Driver Library. Description This section list the files that are available in the /src folder of the WM8904 Codec 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. 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 /framework/driver/codec/wm8904. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_wm8904.h Header file that exports the driver API. 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 /src/dynamic/drv_wm8904.c This file contains implementation of the WM8904 Codec Driver. 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 N/A No optional files are available for this library. Module Dependencies The WM8904 Codec Driver Library depends on the following modules: • I2S Driver Library • I2C Driver Library Library Interface a) System Interaction Functions Name Description DRV_WM8904_Initialize Initializes hardware and data for the instance of the WM8904 DAC module DRV_WM8904_Deinitialize Deinitializes the specified instance of the WM8904 driver module DRV_WM8904_Status Gets the current status of the WM8904 driver module. DRV_WM8904_Tasks Maintains the driver's control and data interface state machine. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 323 b) Client Setup Functions Name Description DRV_WM8904_Open Opens the specified WM8904 driver instance and returns a handle to it DRV_WM8904_Close Closes an opened-instance of the WM8904 driver DRV_WM8904_BufferEventHandlerSet This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. DRV_WM8904_CommandEventHandlerSet This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. c) Data Transfer Functions Name Description DRV_WM8904_BufferAddRead Schedule a non-blocking driver read operation. DRV_WM8904_BufferAddWrite Schedule a non-blocking driver write operation. DRV_WM8904_BufferAddWriteRead Schedule a non-blocking driver write-read operation. Implementation: Dynamic d) Settings Functions Name Description DRV_WM8904_MuteOff This function disables WM8904 output for soft mute. DRV_WM8904_MuteOn This function allows WM8904 output for soft mute on. DRV_WM8904_SamplingRateGet This function gets the sampling rate set on the WM8904. Implementation: Dynamic DRV_WM8904_SamplingRateSet This function sets the sampling rate of the media stream. DRV_WM8904_SetAudioCommunicationMode This function provides a run time audio format configuration DRV_WM8904_VolumeGet This function gets the volume for WM8904 Codec. DRV_WM8904_VolumeSet This function sets the volume for WM8904 Codec. e) Other Functions Name Description DRV_WM8904_VersionGet This function returns the version of WM8904 driver DRV_WM8904_VersionStrGet This function returns the version of WM8904 driver in string format. f) Data Types and Constants Name Description _DRV_WM8904_H Include files. DRV_WM8904_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_WM8904_COUNT Number of valid WM8904 driver indices DRV_WM8904_INDEX_0 WM8904 driver index definitions DRV_WM8904_INDEX_1 This is macro DRV_WM8904_INDEX_1. DRV_WM8904_INDEX_2 This is macro DRV_WM8904_INDEX_2. DRV_WM8904_INDEX_3 This is macro DRV_WM8904_INDEX_3. DRV_WM8904_INDEX_4 This is macro DRV_WM8904_INDEX_4. DRV_WM8904_INDEX_5 This is macro DRV_WM8904_INDEX_5. DRV_WM8904_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_WM8904_BUFFER_EVENT_HANDLER Pointer to a WM8904 Driver Buffer Event handler function DRV_WM8904_BUFFER_HANDLE Handle identifying a write buffer passed to the driver. DRV_WM8904_CHANNEL Identifies Left/Right Audio channel DRV_WM8904_COMMAND_EVENT_HANDLER Pointer to a WM8904 Driver Command Event Handler Function DRV_WM8904_INIT Defines the data required to initialize or reinitialize the WM8904 driver Description This section describes the API functions of the WM8904 Codec Driver library. Refer to each section for a detailed description. a) System Interaction Functions Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 324 DRV_WM8904_Initialize Function Initializes hardware and data for the instance of the WM8904 DAC module File drv_wm8904.h C SYS_MODULE_OBJ DRV_WM8904_Initialize(const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the WM8904 driver instance for the specified driver index, making it ready for clients to open and use it. The initialization data is specified by the init parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. Remarks This routine must be called before any other WM8904 routine is called. This routine should only be called once during system initialization unless DRV_WM8904_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. Preconditions DRV_I2S_Initialize must be called before calling this function to initialize the data interface of this Codec driver. DRV_I2C_Initialize must be called if SPI driver is used for handling the control interface of this Codec driver. Example DRV_WM8904_INIT init; SYS_MODULE_OBJ objectHandle; init->inUse = true; init->status = SYS_STATUS_BUSY; init->numClients = 0; init->i2sDriverModuleIndex = wm8904Init->i2sDriverModuleIndex; init->i2cDriverModuleIndex = wm8904Init->i2cDriverModuleIndex; init->samplingRate = DRV_WM8904_AUDIO_SAMPLING_RATE; init->audioDataFormat = DRV_WM8904_AUDIO_DATA_FORMAT_MACRO; init->isInInterruptContext = false; init->commandCompleteCallback = (DRV_WM8904_COMMAND_EVENT_HANDLER)0; init->commandContextData = 0; init->mclk_multiplier = DRV_WM8904_MCLK_SAMPLE_FREQ_MULTPLIER; objectHandle = DRV_WM8904_Initialize(DRV_WM8904_0, (SYS_MODULE_INIT*)init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description drvIndex Identifier for the driver instance to be initialized init Pointer to the data structure containing any data necessary to initialize the hardware. This pointer may be null if no data is required and default initialization is to be used. Function SYS_MODULE_OBJ DRV_WM8904_Initialize ( const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT *const init Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 325 ); DRV_WM8904_Deinitialize Function Deinitializes the specified instance of the WM8904 driver module File drv_wm8904.h C void DRV_WM8904_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the WM8904 driver module, disabling its operation (and any hardware). Invalidates all the internal data. Remarks Once the Initialize operation has been called, the De-initialize operation must be called before the Initialize operation can be called again. This routine will NEVER block waiting for hardware. Preconditions Function DRV_WM8904_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_WM8904_Initialize SYS_STATUS status; DRV_WM8904_Deinitialize(object); status = DRV_WM8904_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from the DRV_WM8904_Initialize routine Function void DRV_WM8904_Deinitialize( SYS_MODULE_OBJ object) DRV_WM8904_Status Function Gets the current status of the WM8904 driver module. File drv_wm8904.h C SYS_STATUS DRV_WM8904_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_DEINITIALIZED - Indicates that the driver has been deinitialized SYS_STATUS_READY - Indicates that any previous module operation for the specified module has completed SYS_STATUS_BUSY - Indicates that a previous module operation for the specified module has not yet completed SYS_STATUS_ERROR - Indicates that the specified module is in an error state Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 326 Description This routine provides the current status of the WM8904 driver module. Remarks A driver can opened only when its status is SYS_STATUS_READY. Preconditions Function DRV_WM8904_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_WM8904_Initialize SYS_STATUS WM8904Status; WM8904Status = DRV_WM8904_Status(object); if (SYS_STATUS_READY == WM8904Status) { // This means the driver can be opened using the // DRV_WM8904_Open() function. } Parameters Parameters Description object Driver object handle, returned from the DRV_WM8904_Initialize routine Function SYS_STATUS DRV_WM8904_Status( SYS_MODULE_OBJ object) DRV_WM8904_Tasks Function Maintains the driver's control and data interface state machine. File drv_wm8904.h C void DRV_WM8904_Tasks(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal control and data interface state machine and implement its control and data interface implementations. This function should be called from the SYS_Tasks() function. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks). Preconditions The DRV_WM8904_Initialize routine must have been called for the specified WM8904 driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_WM8904_Initialize while (true) { DRV_WM8904_Tasks (object); // Do other tasks } Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 327 Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_WM8904_Initialize) Function void DRV_WM8904_Tasks(SYS_MODULE_OBJ object); b) Client Setup Functions DRV_WM8904_Open Function Opens the specified WM8904 driver instance and returns a handle to it File drv_wm8904.h C DRV_HANDLE DRV_WM8904_Open(const SYS_MODULE_INDEX iDriver, const DRV_IO_INTENT ioIntent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Error can occur • if the number of client objects allocated via DRV_WM8904_CLIENTS_NUMBER is insufficient. • if the client is trying to open the driver but driver has been opened exclusively by another client. • if the driver hardware instance being opened is not initialized or is invalid. • if the ioIntent options passed are not relevant to this driver. Description This routine opens the specified WM8904 driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. The DRV_IO_INTENT_BLOCKING and DRV_IO_INTENT_NONBLOCKING ioIntent options are not relevant to this driver. All the data transfer functions of this driver are non blocking. WM8904 can be opened with DRV_IO_INTENT_WRITE, or DRV_IO_INTENT_READ or DRV_IO_INTENT_WRITEREAD io_intent option. This decides whether the driver is used for headphone output, or microphone input or both modes simultaneously. Specifying a DRV_IO_INTENT_EXCLUSIVE will cause the driver to provide exclusive access to this client. The driver cannot be opened by any other client. Remarks The handle returned is valid until the DRV_WM8904_Close routine is called. This routine will NEVER block waiting for hardware.If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. It should not be called in an ISR. Preconditions Function DRV_WM8904_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_WM8904_Open(DRV_WM8904_INDEX_0, DRV_IO_INTENT_WRITEREAD | DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver // May be the driver is not initialized or the initialization // is not complete. } Parameters Parameters Description drvIndex Identifier for the object instance to be opened Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 328 ioIntent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver. See function description for details. Function DRV_HANDLE DRV_WM8904_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent ) DRV_WM8904_Close Function Closes an opened-instance of the WM8904 driver File drv_wm8904.h C void DRV_WM8904_Close(const DRV_HANDLE handle); Returns • None Description This routine closes an opened-instance of the WM8904 driver, invalidating the handle. Any buffers in the driver queue that were submitted by this client will be removed. After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_WM8904_Open before the caller may use the driver again Remarks Usually there is no need for the driver client to verify that the Close operation has completed. The driver will abort any ongoing operations when this routine is called. Preconditions The DRV_WM8904_Initialize routine must have been called for the specified WM8904 driver instance. DRV_WM8904_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_WM8904_Open DRV_WM8904_Close(handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_WM8904_Close( DRV_Handle handle ) DRV_WM8904_BufferEventHandlerSet Function This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. File drv_wm8904.h C void DRV_WM8904_BufferEventHandlerSet(DRV_HANDLE handle, const DRV_WM8904_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 329 Description This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. When a client calls DRV_WM8904_BufferAddWrite function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed. The event handler should be set before the client performs any "buffer add" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued buffer transfer has completed, it does not need to register a callback. Preconditions The DRV_WM8904_Initialize routine must have been called for the specified WM8904 driver instance. DRV_WM8904_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_WM8904_BUFFER_HANDLE bufferHandle; // myWM8904Handle is the handle returned // by the DRV_WM8904_Open function. // Client registers an event handler with driver DRV_WM8904_BufferEventHandlerSet(myWM8904Handle, APP_WM8904BufferEventHandler, (uintptr_t)&myAppObj); DRV_WM8904_BufferAddWrite(myWM8904handle, &bufferHandle myBuffer, MY_BUFFER_SIZE); if(DRV_WM8904_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_WM8904BufferEventHandler(DRV_WM8904_BUFFER_EVENT event, DRV_WM8904_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_WM8904_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_WM8904_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine eventHandler Pointer to the event handler function. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 330 context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_WM8904_BufferEventHandlerSet ( DRV_HANDLE handle, const DRV_WM8904_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle ) DRV_WM8904_CommandEventHandlerSet Function This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. File drv_wm8904.h C void DRV_WM8904_CommandEventHandlerSet(DRV_HANDLE handle, const DRV_WM8904_COMMAND_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Returns None. Description This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. The event handler should be set before the client performs any "WM8904 Codec Specific Client Routines" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the command has completed, it does not need to register a callback. Preconditions The DRV_WM8904_Initialize routine must have been called for the specified WM8904 driver instance. DRV_WM8904_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_WM8904_BUFFER_HANDLE bufferHandle; // myWM8904Handle is the handle returned // by the DRV_WM8904_Open function. // Client registers an event handler with driver DRV_WM8904_CommandEventHandlerSet(myWM8904Handle, APP_WM8904CommandEventHandler, (uintptr_t)&myAppObj); DRV_WM8904_DeEmphasisFilterSet(myWM8904Handle, DRV_WM8904_DEEMPHASIS_FILTER_44_1KHZ) // Event is received when // the buffer is processed. void APP_WM8904CommandEventHandler(uintptr_t contextHandle) { // contextHandle points to myAppObj. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 331 switch(event) { // Last Submitted command is completed. // Perform further processing here } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine eventHandler Pointer to the event handler function. context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_WM8904_CommandEventHandlerSet ( DRV_HANDLE handle, const DRV_WM8904_COMMAND_EVENT_HANDLER eventHandler, const uintptr_t contextHandle ) c) Data Transfer Functions DRV_WM8904_BufferAddRead Function Schedule a non-blocking driver read operation. File drv_wm8904.h C void DRV_WM8904_BufferAddRead(const DRV_HANDLE handle, DRV_WM8904_BUFFER_HANDLE * bufferHandle, void * buffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_WM8904_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking read operation. The function returns with a valid buffer handle in the bufferHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance receive queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_WM8904_BUFFER_HANDLE_INVALID • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0. • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_WM8904_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_WM8904_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the WM8904 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another WM8904 driver instance. It should not otherwise be called directly in an ISR. Preconditions The DRV_WM8904_Initialize routine must have been called for the specified WM8904 device instance and the DRV_WM8904_Status must have returned SYS_STATUS_READY. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 332 DRV_WM8904_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ must have been specified in the DRV_WM8904_Open call. Parameters Parameters Description handle Handle of the WM8904 instance as return by the DRV_WM8904_Open function. buffer Data to be transmitted. size Buffer size in bytes. bufferHandle Pointer to an argument that will contain the return buffer handle. Function void DRV_WM8904_BufferAddRead ( const DRV_HANDLE handle, DRV_WM8904_BUFFER_HANDLE *bufferHandle, void *buffer, size_t size ) DRV_WM8904_BufferAddWrite Function Schedule a non-blocking driver write operation. File drv_wm8904.h C void DRV_WM8904_BufferAddWrite(const DRV_HANDLE handle, DRV_WM8904_BUFFER_HANDLE * bufferHandle, void * buffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_WM8904_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking write operation. The function returns with a valid buffer handle in the bufferHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance transmit queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_WM8904_BUFFER_HANDLE_INVALID: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0. • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_WM8904_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_WM8904_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the WM8904 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another WM8904 driver instance. It should not otherwise be called directly in an ISR. Preconditions The DRV_WM8904_Initialize routine must have been called for the specified WM8904 device instance and the DRV_WM8904_Status must have returned SYS_STATUS_READY. DRV_WM8904_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE must have been specified in the DRV_WM8904_Open call. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_WM8904_BUFFER_HANDLE bufferHandle; Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 333 // myWM8904Handle is the handle returned // by the DRV_WM8904_Open function. // Client registers an event handler with driver DRV_WM8904_BufferEventHandlerSet(myWM8904Handle, APP_WM8904BufferEventHandler, (uintptr_t)&myAppObj); DRV_WM8904_BufferAddWrite(myWM8904handle, &bufferHandle myBuffer, MY_BUFFER_SIZE); if(DRV_WM8904_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_WM8904BufferEventHandler(DRV_WM8904_BUFFER_EVENT event, DRV_WM8904_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_WM8904_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_WM8904_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle Handle of the WM8904 instance as return by the DRV_WM8904_Open function. buffer Data to be transmitted. size Buffer size in bytes. bufferHandle Pointer to an argument that will contain the return buffer handle. Function void DRV_WM8904_BufferAddWrite ( const DRV_HANDLE handle, DRV_WM8904_BUFFER_HANDLE *bufferHandle, void *buffer, size_t size ) DRV_WM8904_BufferAddWriteRead Function Schedule a non-blocking driver write-read operation. Implementation: Dynamic File drv_wm8904.h Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 334 C void DRV_WM8904_BufferAddWriteRead(const DRV_HANDLE handle, DRV_WM8904_BUFFER_HANDLE * bufferHandle, void * transmitBuffer, void * receiveBuffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_WM8904_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking write-read operation. The function returns with a valid buffer handle in the bufferHandle argument if the write-read request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_WM8904_BUFFER_EVENT_COMPLETE: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the client opened the driver for read only or write only • if the buffer size is 0 • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_WM8904_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_WM8904_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the WM8904 Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another WM8904 driver instance. It should not otherwise be called directly in an ISR. This function is useful when there is valid read expected for every WM8904 write. The transmit and receive size must be same. Preconditions The DRV_WM8904_Initialize routine must have been called for the specified WM8904 device instance and the DRV_WM8904_Status must have returned SYS_STATUS_READY. DRV_WM8904_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READWRITE must have been specified in the DRV_WM8904_Open call. Example MY_APP_OBJ myAppObj; uint8_t mybufferTx[MY_BUFFER_SIZE]; uint8_t mybufferRx[MY_BUFFER_SIZE]; DRV_WM8904_BUFFER_HANDLE bufferHandle; // mywm8904Handle is the handle returned // by the DRV_WM8904_Open function. // Client registers an event handler with driver DRV_WM8904_BufferEventHandlerSet(mywm8904Handle, APP_WM8904BufferEventHandler, (uintptr_t)&myAppObj); DRV_WM8904_BufferAddWriteRead(mywm8904handle, &bufferHandle, mybufferTx,mybufferRx,MY_BUFFER_SIZE); if(DRV_WM8904_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_WM8904BufferEventHandler(DRV_WM8904_BUFFER_EVENT event, DRV_WM8904_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 335 { case DRV_WM8904_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_WM8904_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle Handle of the WM8904 instance as returned by the DRV_WM8904_Open function bufferHandle Pointer to an argument that will contain the return buffer handle transmitBuffer The buffer where the transmit data will be stored receiveBuffer The buffer where the received data will be stored size Buffer size in bytes Function void DRV_WM8904_BufferAddWriteRead ( const DRV_HANDLE handle, DRV_WM8904_BUFFER_HANDLE *bufferHandle, void *transmitBuffer, void *receiveBuffer, size_t size ) d) Settings Functions DRV_WM8904_MuteOff Function This function disables WM8904 output for soft mute. File drv_wm8904.h C void DRV_WM8904_MuteOff(DRV_HANDLE handle); Returns None. Description This function disables WM8904 output for soft mute. Remarks None. Preconditions The DRV_WM8904_Initialize routine must have been called for the specified WM8904 driver instance. DRV_WM8904_Open must have been called to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 336 Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_BUFFER_HANDLE bufferHandle; // myWM8904Handle is the handle returned // by the DRV_WM8904_Open function. DRV_WM8904_MuteOff(myWM8904Handle); //WM8904 output soft mute disabled Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_WM8904_MuteOff( DRV_HANDLE handle) DRV_WM8904_MuteOn Function This function allows WM8904 output for soft mute on. File drv_wm8904.h C void DRV_WM8904_MuteOn(DRV_HANDLE handle); Returns None. Description This function Enables WM8904 output for soft mute. Remarks None. Preconditions The DRV_WM8904_Initialize routine must have been called for the specified WM8904 driver instance. DRV_WM8904_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_BUFFER_HANDLE bufferHandle; // myWM8904Handle is the handle returned // by the DRV_WM8904_Open function. DRV_WM8904_MuteOn(myWM8904Handle); //WM8904 output soft muted Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_WM8904_MuteOn( DRV_HANDLE handle); Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 337 DRV_WM8904_SamplingRateGet Function This function gets the sampling rate set on the WM8904. Implementation: Dynamic File drv_wm8904.h C uint32_t DRV_WM8904_SamplingRateGet(DRV_HANDLE handle); Description This function gets the sampling rate set on the DAC WM8904. Remarks None. Example uint32_t baudRate; // myWM8904Handle is the handle returned // by the DRV_WM8904_Open function. baudRate = DRV_WM8904_SamplingRateGet(myWM8904Handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function uint32_t DRV_WM8904_SamplingRateGet( DRV_HANDLE handle) DRV_WM8904_SamplingRateSet Function This function sets the sampling rate of the media stream. File drv_wm8904.h C void DRV_WM8904_SamplingRateSet(DRV_HANDLE handle, uint32_t samplingRate); Returns None. Description This function sets the media sampling rate for the client handle. Remarks None. Preconditions The DRV_WM8904_Initialize routine must have been called for the specified WM8904 driver instance. DRV_WM8904_Open must have been called to obtain a valid opened device handle. Example // myWM8904Handle is the handle returned // by the DRV_WM8904_Open function. DRV_WM8904_SamplingRateSet(myWM8904Handle, 48000); //Sets 48000 media sampling rate Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 338 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine samplingRate Sampling frequency in Hz Function void DRV_WM8904_SamplingRateSet( DRV_HANDLE handle, uint32_t samplingRate) DRV_WM8904_SetAudioCommunicationMode Function This function provides a run time audio format configuration File drv_wm8904.h C void DRV_WM8904_SetAudioCommunicationMode(DRV_HANDLE handle, const DATA_LENGTH dl, const SAMPLE_LENGTH sl); Returns None Description This function sets up audio mode in I2S protocol Remarks None. Preconditions The DRV_WM8904_Initialize routine must have been called for the specified WM8904 driver instance. DRV_WM8904_Open must have been called to obtain a valid opened device handle. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine dl Data length for I2S audio interface sl Left/Right Sample Length for I2S audio interface Function void DRV_WM8904_SetAudioCommunicationMode ( DRV_HANDLE handle, const DATA_LENGTH dl, const SAMPLE_LENGTH sl ) DRV_WM8904_VolumeGet Function This function gets the volume for WM8904 Codec. File drv_wm8904.h C uint8_t DRV_WM8904_VolumeGet(DRV_HANDLE handle, DRV_WM8904_CHANNEL channel); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 339 Description This functions gets the current volume programmed to the Codec WM8904. Remarks None. Preconditions The DRV_WM8904_Initialize routine must have been called for the specified WM8904 driver instance. DRV_WM8904_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t volume; // myWM8904Handle is the handle returned // by the DRV_WM8904_Open function. volume = DRV_WM8904_VolumeGet(myWM8904Handle, DRV_WM8904_CHANNEL_LEFT); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine channel argument indicating Left or Right or Both channel volume to be modified Function uint8_t DRV_WM8904_VolumeGet( DRV_HANDLE handle, DRV_WM8904_CHANNEL channel) DRV_WM8904_VolumeSet Function This function sets the volume for WM8904 Codec. File drv_wm8904.h C void DRV_WM8904_VolumeSet(DRV_HANDLE handle, DRV_WM8904_CHANNEL channel, uint8_t volume); Returns None Description This functions sets the volume value from 0-255. The codec has DAC value to volume range mapping as :- 00 H : +12dB FF H : -115dB In order to make the volume value to dB mapping monotonically increasing from 00 to FF, re-mapping is introduced which reverses the volume value to dB mapping as well as normalizes the volume range to a more audible dB range. The current driver implementation assumes that all dB values under -60 dB are inaudible to the human ear. Re-Mapped values 00 H : -60 dB FF H : +12 dB Remarks None. Preconditions The DRV_WM8904_Initialize routine must have been called for the specified WM8904 driver instance. DRV_WM8904_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_BUFFER_HANDLE bufferHandle; // myWM8904Handle is the handle returned Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 340 // by the DRV_WM8904_Open function. DRV_WM8904_VolumeSet(myWM8904Handle,DRV_WM8904_CHANNEL_LEFT, 120); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine channel argument indicating Left or Right or Both channel volume to be modified volume volume value specified in the range 0-255 (0x00 to 0xFF) Function void DRV_WM8904_VolumeSet( DRV_HANDLE handle, DRV_WM8904_CHANNEL channel, uint8_t volume); e) Other Functions DRV_WM8904_VersionGet Function This function returns the version of WM8904 driver File drv_wm8904.h C uint32_t DRV_WM8904_VersionGet(); Returns returns the version of WM8904 driver. Description The version number returned from the DRV_WM8904_VersionGet function is an unsigned integer in the following decimal format. * 10000 + * 100 + Where the numbers are represented in decimal and the meaning is the same as above. Note that there is no numerical representation of release type. Remarks None. Preconditions None. Example 1 For version "0.03a", return: 0 * 10000 + 3 * 100 + 0 For version "1.00", return: 1 * 100000 + 0 * 100 + 0 Example 2 uint32_t WM8904version; WM8904version = DRV_WM8904_VersionGet(); Function uint32_t DRV_WM8904_VersionGet( void ) DRV_WM8904_VersionStrGet Function This function returns the version of WM8904 driver in string format. File drv_wm8904.h C int8_t* DRV_WM8904_VersionStrGet(); Returns returns a string containing the version of WM8904 driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 341 Description The DRV_WM8904_VersionStrGet function returns a string in the format: ".[.][]" Where: is the WM8904 driver's version number. is the WM8904 driver's version number. is an optional "patch" or "dot" release number (which is not included in the string if it equals "00"). is an optional release type ("a" for alpha, "b" for beta ? not the entire word spelled out) that is not included if the release is a production version (I.e. Not an alpha or beta). The String does not contain any spaces. For example, "0.03a" "1.00" Remarks None Preconditions None. Example int8_t *WM8904string; WM8904string = DRV_WM8904_VersionStrGet(); Function int8_t* DRV_WM8904_VersionStrGet(void) f) Data Types and Constants _DRV_WM8904_H Macro File drv_wm8904.h C #define _DRV_WM8904_H Description Include files. DRV_WM8904_BUFFER_HANDLE_INVALID Macro Definition of an invalid buffer handle. File drv_wm8904.h C #define DRV_WM8904_BUFFER_HANDLE_INVALID ((DRV_WM8904_BUFFER_HANDLE)(-1)) Description WM8904 Driver Invalid Buffer Handle This is the definition of an invalid buffer handle. An invalid buffer handle is returned by DRV_WM8904_BufferAddWrite() and the DRV_WM8904_BufferAddRead() function if the buffer add request was not successful. Remarks None. DRV_WM8904_COUNT Macro Number of valid WM8904 driver indices File drv_wm8904.h C #define DRV_WM8904_COUNT Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 342 Description WM8904 Driver Module Count This constant identifies the maximum number of WM8904 Driver instances that should be defined by the application. Defining more instances than this constant will waste RAM memory space. This constant can also be used by the application to identify the number of WM8904 instances on this microcontroller. Remarks This value is part-specific. DRV_WM8904_INDEX_0 Macro WM8904 driver index definitions File drv_wm8904.h C #define DRV_WM8904_INDEX_0 0 Description Driver WM8904 Module Index These constants provide WM8904 driver index definition. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_WM8904_Initialize and DRV_WM8904_Open routines to identify the driver instance in use. DRV_WM8904_INDEX_1 Macro File drv_wm8904.h C #define DRV_WM8904_INDEX_1 1 Description This is macro DRV_WM8904_INDEX_1. DRV_WM8904_INDEX_2 Macro File drv_wm8904.h C #define DRV_WM8904_INDEX_2 2 Description This is macro DRV_WM8904_INDEX_2. DRV_WM8904_INDEX_3 Macro File drv_wm8904.h C #define DRV_WM8904_INDEX_3 3 Description This is macro DRV_WM8904_INDEX_3. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 343 DRV_WM8904_INDEX_4 Macro File drv_wm8904.h C #define DRV_WM8904_INDEX_4 4 Description This is macro DRV_WM8904_INDEX_4. DRV_WM8904_INDEX_5 Macro File drv_wm8904.h C #define DRV_WM8904_INDEX_5 5 Description This is macro DRV_WM8904_INDEX_5. DRV_WM8904_BUFFER_EVENT Enumeration Identifies the possible events that can result from a buffer add request. File drv_wm8904.h C typedef enum { DRV_WM8904_BUFFER_EVENT_COMPLETE, DRV_WM8904_BUFFER_EVENT_ERROR, DRV_WM8904_BUFFER_EVENT_ABORT } DRV_WM8904_BUFFER_EVENT; Members Members Description DRV_WM8904_BUFFER_EVENT_COMPLETE Data was transferred successfully. DRV_WM8904_BUFFER_EVENT_ERROR Error while processing the request DRV_WM8904_BUFFER_EVENT_ABORT Data transfer aborted (Applicable in DMA mode) Description WM8904 Driver Events This enumeration identifies the possible events that can result from a buffer add request caused by the client calling either the DRV_WM8904_BufferAddWrite() or the DRV_WM8904_BufferAddRead() function. Remarks One of these values is passed in the "event" parameter of the event handling callback function that the client registered with the driver by calling the DRV_WM8904_BufferEventHandlerSet function when a buffer transfer request is completed. DRV_WM8904_BUFFER_EVENT_HANDLER Type Pointer to a WM8904 Driver Buffer Event handler function File drv_wm8904.h C typedef void (* DRV_WM8904_BUFFER_EVENT_HANDLER)(DRV_WM8904_BUFFER_EVENT event, DRV_WM8904_BUFFER_HANDLE Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 344 bufferHandle, uintptr_t contextHandle); Returns None. Description WM8904 Driver Buffer Event Handler Function This data type defines the required function signature for the WM8904 driver buffer event handling callback function. A client must register a pointer to a buffer event handling function who's function signature (parameter and return value types) match the types specified by this function pointer in order to receive buffer related event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks If the event is DRV_WM8904_BUFFER_EVENT_COMPLETE, this means that the data was transferred successfully. If the event is DRV_WM8904_BUFFER_EVENT_ERROR, this means that the data was not transferred successfully. The bufferHandle parameter contains the buffer handle of the buffer that failed. The DRV_WM8904_BufferProcessedSizeGet() function can be called to find out how many bytes were processed. The bufferHandle parameter contains the buffer handle of the buffer that associated with the event. The context parameter contains a handle to the client context, provided at the time the event handling function was registered using the DRV_WM8904_BufferEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the buffer add request. The buffer handle in bufferHandle expires after this event handler exits. In that the buffer object that was allocated is deallocated by the driver after the event handler exits. The event handler function executes in the data driver(i2S) peripheral's interrupt context when the driver is configured for interrupt mode operation. It is recommended of the application to not perform process intensive or blocking operations with in this function. DRV_WM8904_BufferAddWrite function can be called in the event handler to add a buffer to the driver queue. Example void APP_MyBufferEventHandler( DRV_WM8904_BUFFER_EVENT event, DRV_WM8904_BUFFER_HANDLE bufferHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_WM8904_BUFFER_EVENT_COMPLETE: // Handle the completed buffer. break; case DRV_WM8904_BUFFER_EVENT_ERROR: default: // Handle error. break; } } Parameters Parameters Description event Identifies the type of event bufferHandle Handle identifying the buffer to which the event relates context Value identifying the context of the application that registered the event handling function. DRV_WM8904_BUFFER_HANDLE Type Handle identifying a write buffer passed to the driver. File drv_wm8904.h C typedef uintptr_t DRV_WM8904_BUFFER_HANDLE; Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 345 Description WM8904 Driver Buffer Handle A buffer handle value is returned by a call to the DRV_WM8904_BufferAddWrite() or DRV_WM8904_BufferAddRead() function. This handle is associated with the buffer passed into the function and it allows the application to track the completion of the data from (or into) that buffer. The buffer handle value returned from the "buffer add" function is returned back to the client by the "event handler callback" function registered with the driver. The buffer handle assigned to a client request expires when the client has been notified of the completion of the buffer transfer (after event handler function that notifies the client returns) or after the buffer has been retired by the driver if no event handler callback was set. Remarks None DRV_WM8904_CHANNEL Enumeration Identifies Left/Right Audio channel File drv_wm8904.h C typedef enum { DRV_WM8904_CHANNEL_LEFT, DRV_WM8904_CHANNEL_RIGHT, DRV_WM8904_CHANNEL_LEFT_RIGHT, DRV_WM8904_NUMBER_OF_CHANNELS } DRV_WM8904_CHANNEL; Description WM8904 Audio Channel This enumeration identifies Left/Right Audio channel Remarks None. DRV_WM8904_COMMAND_EVENT_HANDLER Type Pointer to a WM8904 Driver Command Event Handler Function File drv_wm8904.h C typedef void (* DRV_WM8904_COMMAND_EVENT_HANDLER)(uintptr_t contextHandle); Returns None. Description WM8904 Driver Command Event Handler Function This data type defines the required function signature for the WM8904 driver command event handling callback function. A command is a control instruction to the WM8904 Codec. Example Mute ON/OFF, Zero Detect Enable/Disable etc. A client must register a pointer to a command event handling function who's function signature (parameter and return value types) match the types specified by this function pointer in order to receive command related event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks The occurrence of this call back means that the last control command was transferred successfully. The context parameter contains a handle to the client context, provided at the time the event handling function was registered using the DRV_WM8904_CommandEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the buffer add request. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 346 The event handler function executes in the control data driver interrupt context. It is recommended of the application to not perform process intensive or blocking operations with in this function. Example void APP_WM8904CommandEventHandler( uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; // Last Submitted command is completed. // Perform further processing here } Parameters Parameters Description context Value identifying the context of the application that registered the event handling function. DRV_WM8904_INIT Structure Defines the data required to initialize or reinitialize the WM8904 driver File drv_wm8904.h C typedef struct { SYS_MODULE_INIT moduleInit; SYS_MODULE_INDEX i2sDriverModuleIndex; SYS_MODULE_INDEX i2cDriverModuleIndex; uint32_t samplingRate; uint8_t volume; DRV_WM8904_AUDIO_DATA_FORMAT audioDataFormat; bool enableMicInput; } DRV_WM8904_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization SYS_MODULE_INDEX i2sDriverModuleIndex; Identifies data module(I2S) driver ID for data interface of Codec SYS_MODULE_INDEX i2cDriverModuleIndex; Identifies data module(I2C) driver ID for control interface of Codec uint32_t samplingRate; Sampling rate uint8_t volume; Volume DRV_WM8904_AUDIO_DATA_FORMAT audioDataFormat; Identifies the Audio data format bool enableMicInput; true if mic input path enabled Description WM8904 Driver Initialization Data This data type defines the data required to initialize or reinitialize the WM8904 Codec driver. Remarks None. Files Files Name Description drv_wm8904_config_template.h WM8904 Codec Driver Configuration Template. drv_wm8904.h WM8904 Codec Driver Interface header file Description This section lists the source and header files used by the WM8904Codec Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 347 drv_wm8904_config_template.h WM8904 Codec Driver Configuration Template. Macros Name Description _DRV_WM8904_CONFIG_TEMPLATE_H This is macro _DRV_WM8904_CONFIG_TEMPLATE_H. DRV_CODEC_WM8904_MODE Specifies if codec is in Master or Slave mode. DRV_WM8904_BAUD_RATE Specifies the initial baud rate for the codec. DRV_WM8904_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_WM8904_ENABLE_MIC_INPUT Specifies whether to enable the microphone input. DRV_WM8904_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_WM8904_VOLUME Specifies the initial volume level. Description WM8904 Codec Driver Configuration Template These file provides the list of all the configurations that can be used with the driver. This file should not be included in the driver. File Name drv_wm8904_config_template.h Company Microchip Technology Inc. drv_wm8904.h WM8904 Codec Driver Interface header file Enumerations Name Description DATA_LENGTH in bits DRV_WM8904_AUDIO_DATA_FORMAT Identifies the Serial Audio data interface format. DRV_WM8904_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_WM8904_CHANNEL Identifies Left/Right Audio channel Functions Name Description DRV_WM8904_BufferAddRead Schedule a non-blocking driver read operation. DRV_WM8904_BufferAddWrite Schedule a non-blocking driver write operation. DRV_WM8904_BufferAddWriteRead Schedule a non-blocking driver write-read operation. Implementation: Dynamic DRV_WM8904_BufferEventHandlerSet This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. DRV_WM8904_Close Closes an opened-instance of the WM8904 driver DRV_WM8904_CommandEventHandlerSet This function allows a client to identify a command event handling function for the driver to call back when the last submitted command have finished. DRV_WM8904_Deinitialize Deinitializes the specified instance of the WM8904 driver module DRV_WM8904_Initialize Initializes hardware and data for the instance of the WM8904 DAC module DRV_WM8904_MuteOff This function disables WM8904 output for soft mute. DRV_WM8904_MuteOn This function allows WM8904 output for soft mute on. DRV_WM8904_Open Opens the specified WM8904 driver instance and returns a handle to it DRV_WM8904_SamplingRateGet This function gets the sampling rate set on the WM8904. Implementation: Dynamic DRV_WM8904_SamplingRateSet This function sets the sampling rate of the media stream. DRV_WM8904_SetAudioCommunicationMode This function provides a run time audio format configuration DRV_WM8904_Status Gets the current status of the WM8904 driver module. Volume V: MPLAB Harmony Framework Driver Libraries Help Codec Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 348 DRV_WM8904_Tasks Maintains the driver's control and data interface state machine. DRV_WM8904_VersionGet This function returns the version of WM8904 driver DRV_WM8904_VersionStrGet This function returns the version of WM8904 driver in string format. DRV_WM8904_VolumeGet This function gets the volume for WM8904 Codec. DRV_WM8904_VolumeSet This function sets the volume for WM8904 Codec. Macros Name Description _DRV_WM8904_H Include files. DRV_I2C_INDEX This is macro DRV_I2C_INDEX. DRV_WM8904_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_WM8904_COUNT Number of valid WM8904 driver indices DRV_WM8904_INDEX_0 WM8904 driver index definitions DRV_WM8904_INDEX_1 This is macro DRV_WM8904_INDEX_1. DRV_WM8904_INDEX_2 This is macro DRV_WM8904_INDEX_2. DRV_WM8904_INDEX_3 This is macro DRV_WM8904_INDEX_3. DRV_WM8904_INDEX_4 This is macro DRV_WM8904_INDEX_4. DRV_WM8904_INDEX_5 This is macro DRV_WM8904_INDEX_5. Structures Name Description DRV_WM8904_INIT Defines the data required to initialize or reinitialize the WM8904 driver Types Name Description DRV_WM8904_BUFFER_EVENT_HANDLER Pointer to a WM8904 Driver Buffer Event handler function DRV_WM8904_BUFFER_HANDLE Handle identifying a write buffer passed to the driver. DRV_WM8904_COMMAND_EVENT_HANDLER Pointer to a WM8904 Driver Command Event Handler Function Description WM8904 Codec Driver Interface The WM8904 Codec device driver interface provides a simple interface to manage the WM8904 16/24/32-Bit Codec that can be interfaced to a Microchip microcontroller. This file provides the public interface definitions for the WM8904 Codec device driver. File Name drv_wm8904.h Company Microchip Technology Inc. Comparator Driver Library This section describes the Comparator Driver Library. Introduction The Comparator Static Driver provides a high-level interface to manage the Comparator module on the Microchip family of microcontrollers. Description Through MHC, this driver provides an API to initialize the Comparator module, as well as reference channels, CVREF, inputs, and interrupts. Library Interface Function(s) Name Description DRV_CMP_Initialize Initializes the Comparator instance for the specified driver index. Implementation: Static Volume V: MPLAB Harmony Framework Driver Libraries Help Comparator Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 349 Description This section describes the Application Programming Interface (API) functions of the Comparator Driver Library. Function(s) DRV_CMP_Initialize Function Initializes the Comparator instance for the specified driver index. Implementation: Static File help_drv_cmp.h C void DRV_CMP_Initialize(); Returns None. Description This routine initializes the Comparator driver instance for the specified driver instance, making it ready for clients to use it. The initialization routine is specified by the MHC parameters. The driver instance index is independent of the Comparator module ID. For example, driver instance 0 can be assigned to Comparator 2. Remarks This routine must be called before any other Comparator routine is called. This routine should only be called once during system initialization. Preconditions None. Function void DRV_CMP_Initialize( void ) CPLD XC2C64A Driver Library This section describes the CPLD XC2C64A Driver Library. Introduction This library provides an interface to manage the CPLD XC2C64A devices on Microchip starter kits. Description A CPLD is provided on the Multimedia Expansion Board (MEB), which can be used to configure the graphics controller bus interface, SPI channel and Chip Selects used for SPI Flash, the MRF24WBOMA, and the expansion slot. The general I/O inputs are used to change the configuration, which can be done at run-time. Specific CPLD configuration information is available in the "Multimedia Expansion Board (MEB) User's Guide" (DS60001160), which is available from the MEB product page: http://www.microchip.com/Developmenttools/ProductDetails.aspx?PartNO=DM320005 Using the Library This topic describes the basic architecture of the CPLD XC2C64A Driver Library and provides information and examples on its use. Description Interface Header File: drv_xc2c64a.h The interface to the CPLD XC2C64A Driver Library is defined in the drv_xc2c64a.h header file. Any C language source (.c) file that uses the CPLD XC2C64A Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Volume V: MPLAB Harmony Framework Driver Libraries Help CPLD XC2C64A Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 350 Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the CPLD XC2C64A Driver. Library Interface Section Description Functions Provides CPLD XC2C64A initialization and configuration functions. Configuring the Library The configuration of the CPLD XC2C64A Driver is based on the file system_config.h. This header file contains the configuration selection for the CPLD XC2C64A Driver. Based on the selections made, the CPLD XC2C64A may support the selected features. These configuration settings will apply to all instances of the CPLD XC2C64A Driver. This header can be placed anywhere, 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 in the CPLD XC2C64A Driver Library. Description This section list the files that are available in the /src folder of the CPLD XC2C64A 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. 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 /framework/driver/cpld/xc2c64a. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_xc2c64a.h Header file that exports the CPLD XC2C64A Driver API. 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 /src/dynamic/drv_xc2c64a.c Basic CPLD XC2C64A Driver implementation file. 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 N/A No optional files are available for this library Module Dependencies The CPLD XC2C64A Driver Library is not dependent on other modules. Library Interface a) Functions Name Description CPLDGetDeviceConfiguration Returns the selected device. Implementation: Static Volume V: MPLAB Harmony Framework Driver Libraries Help CPLD XC2C64A Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 351 CPLDGetGraphicsConfiguration Returns the selected PMP bus, 8 or 16-bit, interface to the graphics controller. Implementation: Static CPLDGetSPIConfiguration Returns the selected SPI Channel. Implementation: Static CPLDInitialize Initializes the control I/O to the CPLD and places the CPLD in a known state. Implementation: Static CPLDSetGraphicsConfiguration Selects the PMP bus, 8 or 16-bit, interface to the graphic controller. Implementation: Static CPLDSetSPIFlashConfiguration Selects the SPI Flash device. Implementation: Static CPLDSetWiFiConfiguration Selects the Wi-Fi device. Implementation: Static CPLDSetZigBeeConfiguration Selects the ZigBee/MiWi device. Implementation: Static b) Data Types and Constants Name Description CPLD_DEVICE_CONFIGURATION CPLD device configuration. CPLD_GFX_CONFIGURATION CPLD graphics controller PMP bus configuration. CPLD_SPI_CONFIGURATION CPLD SPI channel selection. Description This section describes the API functions of the CPLD XC2C64A Driver Library. Refer to each section for a detailed description. a) Functions CPLDGetDeviceConfiguration Function Returns the selected device. Implementation: Static File drv_xc2c64a.h C CPLD_DEVICE_CONFIGURATION CPLDGetDeviceConfiguration(); Returns • CPLD_DEVICE_SPI_FLASH - SPI Flash. • CPLD_DEVICE_WiFi - Zero G 802.11 Wi-Fi. • CPLD_DEVICE_ZIGBEE - ZigBee/MiWi. Description This routine returns the selected CPLD device. Remarks None. Preconditions The initialization routine, CPLDInitialize, must be called. Example // Initialize the CPLD CPLDInitialize(); if(CPLDGetDeviceConfiguration() != CPLD_DEVICE_SPI_FLASH) { // error - not setup as default Volume V: MPLAB Harmony Framework Driver Libraries Help CPLD XC2C64A Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 352 } Function CPLD_DEVICE_CONFIGURATION CPLDGetDeviceConfiguration(void) CPLDGetGraphicsConfiguration Function Returns the selected PMP bus, 8 or 16-bit, interface to the graphics controller. Implementation: Static File drv_xc2c64a.h C CPLD_GFX_CONFIGURATION CPLDGetGraphicsConfiguration(); Returns • CPLD_GFX_CONFIG_8BIT - Graphics controller is configured for 8-bit PMP data bus interface. • CPLD_GFX_CONFIG_16BIT - Graphics controller is configured for 16-bit PMP data bus interface. Description This routine gets the configuration of the PMP, 8 or 16-bit, data bus interface. Remarks None. Preconditions The initialization routine, CPLDInitialize, must be called. Example // Initialize the CPLD CPLDInitialize(); if(CPLDGetGraphicsConfiguration() != CPLD_GFX_CONFIG_8BIT) { // error - not setup as default } Function CPLD_GFX_CONFIGURATION CPLDGetGraphicsConfiguration(void) CPLDGetSPIConfiguration Function Returns the selected SPI Channel. Implementation: Static File drv_xc2c64a.h C CPLD_SPI_CONFIGURATION CPLDGetSPIConfiguration(); Returns • CPLD_SPI2A - SPI Channel 2A with chip select PORT G bit 9 and external interrupt 1 or 3 • CPLD_SPI3A - SPI Channel 3A with chip select PORT F bit 12 and change notice 9 • CPLD_SPI2 - SPI Channel 2 with chip select PORT G bit 9 and external interrupt 1 or 3 Description This routine returns the selected SPI channel. Volume V: MPLAB Harmony Framework Driver Libraries Help CPLD XC2C64A Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 353 Remarks SPI channels 2 and 2A are located on the same pins. SPI channels 2A and 3A are only available on PIC32MX5xx/6xx/7xx series parts. Preconditions The initialization routine, CPLDInitialize, must be called. Example // Initialize the CPLD CPLDInitialize(); if(CPLDGetSPIConfiguration() != CPLD_SPI2A) { // error - not setup as default } Function CPLD_SPI_CONFIGURATION CPLDGetSPIConfiguration(void) CPLDInitialize Function Initializes the control I/O to the CPLD and places the CPLD in a known state. Implementation: Static File drv_xc2c64a.h C void CPLDInitialize(); Returns None. Description This routine configures the control I/O and places the CPLD in a known state. • Graphics Controller Bus - 8-bit PMP data interface. • SPI Channel - SPI2/SPI2A. • Chip Select - PORT G bit 9. • External Interrupt 1 or 3 • Device - SPI Flash. Remarks None. Preconditions None. Example // Initialize the CPLD CPLDInitialize(); // CPLD is configured in the default state Function void CPLDInitialize(void) CPLDSetGraphicsConfiguration Function Selects the PMP bus, 8 or 16-bit, interface to the graphic controller. Volume V: MPLAB Harmony Framework Driver Libraries Help CPLD XC2C64A Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 354 Implementation: Static File drv_xc2c64a.h C void CPLDSetGraphicsConfiguration(CPLD_GFX_CONFIGURATION configuration); Returns None. Description This routine sets the configuration pins on the graphics controller to select between an 8 or 16-bit data bus interface. Remarks The graphics controller interface configuration must be done before initializing the graphics controller. Preconditions The initialization routine, CPLDInitialize, must be called. Example Setting the graphics controller to a 16-bit interface // Initialize the CPLD CPLDInitialize(); // configure the graphics controller for a 16-bit PMP interface. CPLDSetGraphicsConfiguration(CPLD_GFX_CONFIG_16BIT); Setting the graphics controller to a 8-bit interface // Initialize the CPLD CPLDInitialize(); // configure the graphics controller for a 8-bit PMP interface. CPLDSetGraphicsConfiguration(CPLD_GFX_CONFIG_8BIT); Parameters Parameters Description configuration the type of interface configuration. Function void CPLDSetGraphicsConfiguration( CPLD_GFX_CONFIGURATION configuration) CPLDSetSPIFlashConfiguration Function Selects the SPI Flash device. Implementation: Static File drv_xc2c64a.h C void CPLDSetSPIFlashConfiguration(CPLD_SPI_CONFIGURATION configuration); Returns None. Description This routine configures the CPLD to communicate to the SPI Flash device with the selected SPI channel and Chip Select. Remarks SPI channels 2 and 2A are located on the same pins. SPI channels 2A and 3A are only available on PIC32MX5xx/6xx/7xx series parts. Volume V: MPLAB Harmony Framework Driver Libraries Help CPLD XC2C64A Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 355 Preconditions The initialization routine, CPLDInitialize, must be called. Example Setting CPLD to SPI Flash using SPI channel 2 and chip select PORT G bit 9 // Initialize the CPLD CPLDInitialize(); // configure the SPI Flash to use SPI channel 2 and chip select PORT G bit 9 CPLDSetSPIFlashConfiguration(CPLD_SPI2); Setting CPLD to SPI Flash using SPI channel 2A and chip select PORT G bit 9 // Initialize the CPLD CPLDInitialize(); // configure the SPI Flash to use SPI channel 2A and chip select PORT G bit 9 CPLDSetSPIFlashConfiguration(CPLD_SPI2A); Setting CPLD to SPI Flash using SPI channel 3A and chip select PORT F bit 12 // Initialize the CPLD CPLDInitialize(); // configure the SPI Flash to use SPI channel 3A and chip select PORT F bit 12 CPLDSetSPIFlashConfiguration(CPLD_SPI3A); Parameters Parameters Description configuration the type of SPI channel used by the SPI Flash device. Function void CPLDSetSPIFlashConfiguration( CPLD_SPI_CONFIGURATION configuration) CPLDSetWiFiConfiguration Function Selects the Wi-Fi device. Implementation: Static File drv_xc2c64a.h C void CPLDSetWiFiConfiguration(CPLD_SPI_CONFIGURATION configuration); Returns None. Description This routine configures the CPLD to communicate to the Wi-Fi device with the selected SPI channel, chip select and external interrupt or change notice. Remarks SPI channels 2 and 2A are located on the same pins. SPI channels 2A and 3A are only available on PIC32MX5xx/6xx/7xx series parts. Preconditions The initialization routine, CPLDInitialize, must be called. Example Setting CPLD to Wi-Fi using SPI channel 2, chip select PORT G bit 9 and external interrupt 3 // Initialize the CPLD CPLDInitialize(); // configure the Wi-Fi to use SPI channel 2, chip select PORT G bit 9 and external interrupt 3 CPLDSetWiFiConfiguration(CPLD_SPI2); Volume V: MPLAB Harmony Framework Driver Libraries Help CPLD XC2C64A Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 356 Setting CPLD to Wi-Fi using SPI channel 2A, chip select PORT G bit 9 and external interrupt 3 // Initialize the CPLD CPLDInitialize(); // configure the Wi-Fi to use SPI channel 2A, chip select PORT G bit 9 and external interrupt 3 CPLDSetWiFiConfiguration(CPLD_SPI2A); Setting CPLD to Wi-Fi using SPI channel 3A, chip select PORT F bit 12 and change notice 9 // Initialize the CPLD CPLDInitialize(); // configure the Wi-Fi to use SPI channel 3A, chip select PORT F bit 12 and change notice 9 CPLDSetWiFiConfiguration(CPLD_SPI3A); Parameters Parameters Description configuration the type of SPI channel used by the Wi-Fi device. Function void CPLDSetWiFiConfiguration( CPLD_SPI_CONFIGURATION configuration) CPLDSetZigBeeConfiguration Function Selects the ZigBee/MiWi device. Implementation: Static File drv_xc2c64a.h C void CPLDSetZigBeeConfiguration(CPLD_SPI_CONFIGURATION configuration); Returns None. Description This routine configures the CPLD to communicate to the ZigBee/MiWi device with the selected SPI channel, chip select and external interrupt or change notice. Remarks SPI channels 2 and 2A are located on the same pins. SPI channels 2A and 3A are only available on PIC32MX5xx/6xx/7xx series parts. Preconditions The initialization routine, CPLDInitialize, must be called. Example Setting CPLD to ZigBee/MiWi using SPI channel 2, chip select PORT G bit 9 and external interrupt 3 // Initialize the CPLD CPLDInitialize(); // configure the ZigBee/MiWi to use SPI channel 2, chip select PORT G bit 9 and external interrupt 3 CPLDSetZigBeeConfiguration(CPLD_SPI2); Setting CPLD to ZigBee/MiWi using SPI channel 2A, chip select PORT G bit 9 and external interrupt 3 // Initialize the CPLD CPLDInitialize(); // configure the ZigBee/MiWi to use SPI channel 2A, chip select PORT G bit 9 and external interrupt 3 CPLDSetZigBeeConfiguration(CPLD_SPI2A); Setting CPLD to ZigBee/MiWi using SPI channel 3A, chip select PORT F bit 12 and change notice 9 // Initialize the CPLD CPLDInitialize(); // configure the ZigBee/MiWi to use SPI channel 3A, chip select PORT F bit 12 and change notice 9 CPLDSetZigBeeConfiguration(CPLD_SPI3A); Volume V: MPLAB Harmony Framework Driver Libraries Help CPLD XC2C64A Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 357 Parameters Parameters Description configuration the type of SPI channel used by the ZigBee/MiWi device. Function void CPLDSetZigBeeConfiguration( CPLD_SPI_CONFIGURATION configuration) b) Data Types and Constants CPLD_DEVICE_CONFIGURATION Enumeration CPLD device configuration. File drv_xc2c64a.h C typedef enum { CPLD_DEVICE_SPI_FLASH, CPLD_DEVICE_WiFi, CPLD_DEVICE_ZIGBEE } CPLD_DEVICE_CONFIGURATION; Members Members Description CPLD_DEVICE_SPI_FLASH SPI Flash CPLD_DEVICE_WiFi Zero G Wi-Fi CPLD_DEVICE_ZIGBEE ZigBee/MiWi Description The CPLD can be configured to communicate to three different devices. The application may call routine, CPLDGetDeviceConfiguration, to obtain what device the CPLD is configured to communicate with. Remarks None. Example // select 16-bit PMP data bus if(CPLDGetDeviceConfiguration() != CPLD_DEVICE_SPI_FLASH) { // error - not default configuration } CPLD_GFX_CONFIGURATION Enumeration CPLD graphics controller PMP bus configuration. File drv_xc2c64a.h C typedef enum { CPLD_GFX_CONFIG_8BIT, CPLD_GFX_CONFIG_16BIT } CPLD_GFX_CONFIGURATION; Members Members Description CPLD_GFX_CONFIG_8BIT Configure the Graphics Controller to use 8-bit PMP data bus Volume V: MPLAB Harmony Framework Driver Libraries Help CPLD XC2C64A Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 358 CPLD_GFX_CONFIG_16BIT Configure the Graphics Controller to use 16-bit PMP data bus Description The application can select what PMP bus configuration, 8 or 16-bit data bus, when interfacing with the graphics controller. Remarks None. Example // select 16-bit PMP data bus CPLDSetGraphicsConfiguration(CPLD_GFX_CONFIG_16BIT); CPLD_SPI_CONFIGURATION Enumeration CPLD SPI channel selection. File drv_xc2c64a.h C typedef enum { CPLD_SPI2A, CPLD_SPI3A, CPLD_SPI2 } CPLD_SPI_CONFIGURATION; Members Members Description CPLD_SPI2A PIC32 SPI Channel 2A and chip select PORT G bit 9 CPLD_SPI3A PIC32 SPI Channel 3A and chip select PORT F bit 12 CPLD_SPI2 PIC32 SPI Channel 2 and chip select PORT G bit 9 Description The application can select what SPI channel will be used as the communication interface. It will also select the Chip Select use for the device. Remarks Only one SPI channel can be select for a device. SPI channels 2 and 2A are located on the same pins. SPI channels 2A and 3A are only available on PIC32MX5xx/6xx/7xx series devices. Example // select SPI channel two for SPI Flash CPLDSetSPIFlashConfiguration(CPLD_SPI2); Files Files Name Description drv_xc2c64a.h This file contains the interface definition for the CUPLD controller. Description This section lists the source and header files used by the SPI Flash Driver Library. drv_xc2c64a.h This file contains the interface definition for the CUPLD controller. Enumerations Name Description CPLD_DEVICE_CONFIGURATION CPLD device configuration. CPLD_GFX_CONFIGURATION CPLD graphics controller PMP bus configuration. Volume V: MPLAB Harmony Framework Driver Libraries Help CPLD XC2C64A Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 359 CPLD_SPI_CONFIGURATION CPLD SPI channel selection. Functions Name Description CPLDGetDeviceConfiguration Returns the selected device. Implementation: Static CPLDGetGraphicsConfiguration Returns the selected PMP bus, 8 or 16-bit, interface to the graphics controller. Implementation: Static CPLDGetSPIConfiguration Returns the selected SPI Channel. Implementation: Static CPLDInitialize Initializes the control I/O to the CPLD and places the CPLD in a known state. Implementation: Static CPLDSetGraphicsConfiguration Selects the PMP bus, 8 or 16-bit, interface to the graphic controller. Implementation: Static CPLDSetSPIFlashConfiguration Selects the SPI Flash device. Implementation: Static CPLDSetWiFiConfiguration Selects the Wi-Fi device. Implementation: Static CPLDSetZigBeeConfiguration Selects the ZigBee/MiWi device. Implementation: Static Description CUPLD Controller Interface File. This library provides a low-level abstraction of the CUPLD device. It can be used to simplify low-level access to the device without the necessity of interacting directly with the communication module's registers, thus hiding differences from one serial device variant to another. File Name drv_xc2c64a.h Company Microchip Technology Inc. CTR Driver Library This section describes the Cycle Time Register (CTR) Driver Library. Introduction This library provides a low-level abstraction of the Cycle Time Register (CTR) 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 CTR is a hardware block that can be used to track specific signals from subsystems to internally log corresponding system time. Subsystems can include network clock synchronization, Media Clock synchronization, USB start of frame (SoF), and so on. Using the Library This section describes the basic architecture of the CTR Driver Library and provides information and examples on its use. Description Interface Header File: drv_ctr.h The interface to the CTR Module Library is defined in the drv_ctr.h header file. Any C language source (.c) file that uses the CTR Driver Library should include this header. Refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the CTR Driver Library 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. Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 360 Description The CTR driver provides an interface to perform a one-time configuration of the CTR peripheral. Initialization steps include selecting the mode of operation, interrupt and trigger sources, latch configurations, and so on. In addition, the driver allows the client to register a callback that is executed when the desired event has been triggered. Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the CTR module. Library Interface Section Description System Interaction Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Other Functions Provides driver miscellaneous functions, data transfer status function, version identification functions, and so on. Data Types and Constants Provides data types and macros. How the Library Works The library provides interfaces to support: • System Functionality • Client Functionality Note: Not all modes are available on all devices, please refer to the specific device data sheet to determine the modes that are supported for your device. Configuring the Library The configuration of the driver is based on the file system_config.h. Description The header file contains the configuration selection for the driver. Based on the selections made, the driver may support the selected features. These configuration settings will apply to all instances of the driver. This header can be placed anywhere, 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 in the CTR Driver Library. Description This section list the files that are available in the /src folder of the CTR Driver Library. 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. 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 /framework/driver/ctr/. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_ctr.h Header file that exports the driver API. 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. Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 361 Source File Name Description /src/dynamic/drv_ctr.c Basic CTR Driver implementation file. 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 N/A No optional files are available for this library Module Dependencies The CTR Driver Library depends on the following modules: • Clock System Service Library Optional Dependencies • DMA System Service Library (used when operating in DMA mode) • Interrupt System Service Library (used when task is running in Interrupt mode) Library Interface This section describes the API functions of the CTR Driver Library. Refer to each section for a detailed description. a) System Interaction Functions Functions Name Description DRV_CTR_Deinitialize Deinitializes the specified instance of the CTR driver module. Implementation: Dynamic DRV_CTR_Initialize Initializes the CTR Driver instance for the specified driver index. Implementation: Dynamic DRV_CTR_Status Gets the current status of the CTR Driver module. Implementation: Dynamic Description DRV_CTR_Deinitialize Function Deinitializes the specified instance of the CTR driver module. Implementation: Dynamic File drv_ctr.h C void DRV_CTR_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the CTR Driver module, disabling its operation (and any hardware) and invalidates all of the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. Preconditions Function DRV_CTR_Initialize should have been called before calling this function. Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 362 Example // This code snippet shows an example of deinitializing the driver. SYS_MODULE_OBJ object; // Returned from DRV_CTR_Initialize SYS_STATUS status; DRV_CTR_Deinitialize(object); status = DRV_CTR_Status(object); if (SYS_STATUS_UNINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from the DRV_CTR_Initialize Function void DRV_CTR_Deinitialize( SYS_MODULE_OBJ object ) DRV_CTR_Initialize Function Initializes the CTR Driver instance for the specified driver index. Implementation: Dynamic File drv_ctr.h C SYS_MODULE_OBJ DRV_CTR_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Description This function initializes the CTR driver instance for the specified driver index, making it ready for clients to open and use it. Remarks This function must be called before any other CTR function is called. This function should only be called once during system initialization unless DRV_CTR_Deinitialize is called to deinitialize the driver instance. Preconditions None. Example // This code snippet shows an example of initializing the CTR Driver. All the CTR initialization is done in #defines mentioned, and the init structure is initialized with corresponding #defines and then passed to initialize function. // ***************************************************************************** // CTR Driver Configuration Options #define DRV_CTR_POWER_STATE SYS_MODULE_POWER_RUN_FULL #define DRV_CTR_MODULE_ID CTR_ID_0 #define DRV_CTR_CLIENTS_NUMBER 1 #define DRV_CTR_INSTANCES_NUMBER 1 #define DRV_CTR_EVENT_INTERRUPT_SOURCE INT_SOURCE_CTR1_EVENT #define DRV_CTR_EVENT_INTERRUPT_MODE CTR_LATCH_TRIG Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 363 #define DRV_CTR_TRIGGER_INTERRUPT_SOURCE INT_SOURCE_CTR1_TRG #define DRV_CTR_M_0 0x000000 #define DRV_CTR_N_0 0x000000 #define DRV_CTR_LSB_0 0x00 #define DRV_CTR_MODE_0 CTR_US #define DRV_CTR_M_1 0x000000 #define DRV_CTR_N_1 0x000000 #define DRV_CTR_LSB_1 0x00 #define DRV_CTR_MODE_1 CTR_US #define DRV_CTR_COUNTER_SEL CTR_CTR0_LIN #define DRV_CTR_DIVIDER 0 #define DRIVER_MODE WIFI_MODE #define DRV_CTR_LATCH0_TRIG CTR_WIFI_TM_1 #define DRV_CTR_LATCH1_TRIG CTR_WIFI_TM_2 #define DRV_CTR_LATCH2_TRIG CTR_WIFI_TM_3 #define DRV_CTR_LATCH3_TRIG CTR_WIFI_TM_4 #define DRV_CTR_TRIGGER_SOURCE CTR_CTR0_LIN #define DRV_CTR_TRIGGER_PHASE 0x000 DRV_CTR_INIT CTRInitData; SYS_MODULE_OBJ objectHandle; CTRInitData.moduleInit = DRV_CTR_POWER_STATE, CTRInitData.ctrEventInterruptSource = DRV_CTR_EVENT_INTERRUPT_SOURCE, CTRInitData.ctrLatchEventMode = DRV_CTR_EVENT_INTERRUPT_MODE, CTRInitData.ctrTriggerInterruptSource = DRV_CTR_TRIGGER_INTERRUPT_SOURCE, CTRInitData.ctrCounter[0].M = DRV_CTR_M_0, CTRInitData.ctrCounter[0].N = DRV_CTR_N_0, CTRInitData.ctrCounter[0].LSB = DRV_CTR_LSB_0, CTRInitData.ctrCounter[1].M = DRV_CTR_M_1, CTRInitData.ctrCounter[1].N = DRV_CTR_N_1, CTRInitData.ctrCounter[1].LSB = DRV_CTR_LSB_1, CTRInitData.ctrLatch[0].ctrSel = DRV_CTR_COUNTER_SEL, CTRInitData.ctrLatch[1].ctrSel = DRV_CTR_COUNTER_SEL, CTRInitData.ctrLatch[2].ctrSel = DRV_CTR_COUNTER_SEL, CTRInitData.ctrLatch[3].ctrSel = DRV_CTR_COUNTER_SEL, CTRInitData.ctrLatch[0].trigSel = DRV_CTR_LATCH0_TRIG, CTRInitData.ctrLatch[1].trigSel = DRV_CTR_LATCH1_TRIG, CTRInitData.ctrLatch[2].trigSel = DRV_CTR_LATCH2_TRIG, CTRInitData.ctrLatch[3].trigSel = DRV_CTR_LATCH3_TRIG, CTRInitData.ctrLatch[0].divider = DRV_CTR_DIVIDER, CTRInitData.ctrLatch[1].divider = DRV_CTR_DIVIDER, CTRInitData.ctrLatch[2].divider = DRV_CTR_DIVIDER, CTRInitData.ctrLatch[3].divider = DRV_CTR_DIVIDER, CTRInitData.ctrTrigger.trigSource = DRV_CTR_TRIGGER_SOURCE, CTRInitData.ctrTrigger.phase = DRV_CTR_TRIGGER_PHASE, CTRInitData.drvMode = DRIVER_MODE objectHandle = DRV_CTR_Initialize(DRV_CTR_INDEX_0, (SYS_MODULE_INIT*)CTRInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized init Pointer to a data structure containing data necessary to initialize the driver. Function SYS_MODULE_OBJ DRV_CTR_Initialize ( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 364 DRV_CTR_Status Function Gets the current status of the CTR Driver module. Implementation: Dynamic File drv_ctr.h C SYS_STATUS DRV_CTR_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is ready and accept requests for new operations SYS_STATUS_UNINITIALIZED - Indicates that the driver is not initialized Description This function provides the current status of the CTR Driver module. Remarks A driver can only be opened when its status is SYS_STATUS_READY. Preconditions Function DRV_CTR_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_CTR_Initialize SYS_STATUS CTRStatus; CTRStatus = DRV_CTR_Status(object); if (SYS_STATUS_ERROR == CTRStatus) { // Handle error } Parameters Parameters Description object Driver object handle, returned from the DRV_CTR_Initialize Function SYS_STATUS DRV_CTR_Status( SYS_MODULE_OBJ object ) b) Other Functions Functions Name Description DRV_CTR_Adjust Sets the adjust value for a given CTR counter. Implementation: Dynamic DRV_CTR_ClientStatus Gets current client-specific status of the CTR driver. Implementation: Dynamic DRV_CTR_Close Closes an opened-instance of the CTR driver. Implementation: Dynamic DRV_CTR_Drift Sets the drift value for a given CTR counter. Implementation: Dynamic DRV_CTR_EventISR Interrupt Service Routine called for the CTR event interrupt. Implementation: Dynamic DRV_CTR_Open Opens the specified CTR driver instance and returns a handle to it. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 365 DRV_CTR_RegisterCallBack Registers a callback function for the event interrupt of CTR. Implementation: Dynamic DRV_CTR_TriggerISR Interrupt Service Routine called for the CTR Trigger interrupt. Implementation: Dynamic Description DRV_CTR_Adjust Function Sets the adjust value for a given CTR counter. Implementation: Dynamic File drv_ctr.h C void DRV_CTR_Adjust(DRV_HANDLE handle, CTR_LATCH_CTR_SELECT ctrSel, uint16_t adjustVal); Returns None. Description This function sets the adjust value for a given CTR counter. Preconditions The DRV_CTR_Initialize function must have been called. DRV_CTR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // handle returned by open function uint16_t adjustVal = 0xFFF; DRV_CTR_Adjust(handle, CTR_CTR0_LIN, adjustVal); Parameters Parameters Description handle A valid open instance handle, returned from the driver's open Function void DRV_CTR_Adjust( DRV_HANDLE handle, CTR_LATCH_CTR_SELECT ctrSel, uint16_t adjustVal); ctrSel - CTR counter to be selected out of the 4 counters available. adjustVal - Adjust value to be set DRV_CTR_ClientStatus Function Gets current client-specific status of the CTR driver. Implementation: Dynamic File drv_ctr.h C DRV_CTR_CLIENT_STATUS DRV_CTR_ClientStatus(const DRV_HANDLE handle); Returns A DRV_CTR_CLIENT_STATUS value describing the current status of the driver. Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 366 Description This function gets the client-specific status of the CTR driver associated with the given handle. Remarks This function will not block for hardware access and will immediately return the current status. Preconditions The DRV_CTR_Initialize function must have been called. DRV_CTR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_CTR_Open DRV_CTR_CLIENT_STATUS clientStatus; clientStatus = DRV_CTR_ClientStatus(handle); if(DRV_CTR_CLIENT_STATUS_READY == clientStatus) { // do the tasks } Parameters Parameters Description handle A valid open instance handle, returned from the driver's open Function DRV_CTR_CLIENT_STATUS DRV_CTR_ClientStatus(DRV_HANDLE handle); DRV_CTR_Close Function Closes an opened-instance of the CTR driver. Implementation: Dynamic File drv_ctr.h C void DRV_CTR_Close(const DRV_HANDLE handle); Returns None. Description This function closes an opened-instance of the CTR driver, invalidating the handle. Remarks After calling this function, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_CTR_Open before the caller may use the driver again. Usually, there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_CTR_Initialize function must have been called for the specified CTR driver instance. DRV_CTR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_CTR_Open DRV_CTR_Close(handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 367 Function void DRV_CTR_Close( DRV_Handle handle ); DRV_CTR_Drift Function Sets the drift value for a given CTR counter. Implementation: Dynamic File drv_ctr.h C void DRV_CTR_Drift(DRV_HANDLE handle, CTR_LATCH_CTR_SELECT ctrSel, uint32_t driftVal); Returns None. Description This function sets the drift value for a given CTR counter. Preconditions The DRV_CTR_Initialize function must have been called. DRV_CTR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // handle returned by open function uint16_t driftVal = 0xFFF; DRV_CTR_Drift(handle, CTR_CTR0_LIN, driftVal); Parameters Parameters Description handle A valid open instance handle, returned from the driver's open Function void DRV_CTR_Drift( DRV_HANDLE handle, CTR_LATCH_CTR_SELECT ctrSel, uint16_t driftVal); ctrSel - CTR counter to be selected out of the 4 counters available. adjustVal - Drift value to be set DRV_CTR_EventISR Function Interrupt Service Routine called for the CTR event interrupt. Implementation: Dynamic File drv_ctr.h C void DRV_CTR_EventISR(SYS_MODULE_OBJ object); Returns None. Description This function is called when the interrupt is generated for CTR event interrupt. The latch buffers are read and stored in a local buffer, and all the registered client callback functions will be called from this function. The number of latches to be read depends upon the use-case configured. For wifi, 4 latches are read, and for USBSoF and GPIO, only 1 latch is read. Number of buffers to read in each latch depends on the interrupt mode configuration. For Full, all 4 buffers needs to be read, whereas for half-full, only 2 buffers needs to be read and for every trigger, only 1 buffer is Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 368 read. Remarks All the handling specific for a client should be done in the respective callback functions. This function should not be modified. Preconditions None. Example This function is not called from clients/system. This function will be called when the interrupt for event is generated. Parameters Parameters Description object The driver instance handle returned after the initialization. Function void DRV_CTR_EventISR(SYS_MODULE_OBJ object); DRV_CTR_Open Function Opens the specified CTR driver instance and returns a handle to it. Implementation: Dynamic File drv_ctr.h C DRV_HANDLE DRV_CTR_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent); Returns If successful, the function returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Errors can occur under the following circumstances: • if the number of client objects allocated via DRV_CTR_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the driver hardware instance being opened is not initialized or is invalid • if the client is trying to open the driver exclusively, but has already been opened in a non exclusive mode by another client. • if the driver status is not ready. Description This function opens the specified CTR driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Remarks The driver will always work in Non-Blocking mode even if IO-intent is selected as blocking. The handle returned is valid until the DRV_CTR_Close function is called. This function will NEVER block waiting for hardware. Preconditions Function DRV_CTR_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_CTR_Open(DRV_CTR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 369 Parameters Parameters Description drvIndex Identifier for the object instance to be opened ioIntent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver Function DRV_HANDLE DRV_CTR_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent ); DRV_CTR_RegisterCallBack Function Registers a callback function for the event interrupt of CTR. Implementation: Dynamic File drv_ctr.h C void DRV_CTR_RegisterCallBack(const DRV_HANDLE handle, const DRV_CTR_CALLBACK callback, const bool oneTimeCallback, const uintptr_t context); Returns None. Description This function registers a client callback function for the event interrupt associated with the use-case. For Wifi usecase, Only Latch 3 interrupt will be enabled, as the last event timestamp will be filled in latch 3 for IEEE 802.11v. For USBSoF and GPIO use-cases, only one latch is needed and the interrupt will be enabled for the same latch. As per user's configuration of interrupt mode for full, half-full or every trigger, the interrupt will be generated and the client callback functions will be called from the ISR. The flag oneTimeCallback is passed as an argument for this function. If the value of this flag is TRUE, then the callback will be called only once. If client needs one more callback, he needs to register the callback once more. If this value is false, then whenever interrupt is generated, the callback function will be called until the client call the close function. Remarks The registered callback function will be called from ISR. So, it is recommended to keep the callback functions light and not process intensive. Preconditions The DRV_CTR_Initialize function must have been called. DRV_CTR_Open must have been called to obtain a valid opened device handle. Example #define CLIENT_ID 0x01 DRV_HANDLE handle; // Returned from DRV_CTR_Open void ClientCallack( uintptr_t context, uint32_t * timestampbuffer, uint8_t BufferSize); DRV_CTR_RegisterCallBack(handle, ClientCallack, FALSE, CLIENT_ID); Parameters Parameters Description handle A valid open instance handle, returned from the driver's open Function void DRV_CTR_RegisterCallBack( const DRV_HANDLE handle, const DRV_CTR_CALLBACK callback, const bool oneTimeCallback, Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 370 const uintptr_t context ); callback - A function pointer for client callback function oneTimeCallback - If client needs callback to be called only once, then this flag must be true. context - The value of parameter will be passed back to the client unchanged, when the callback function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). DRV_CTR_TriggerISR Function Interrupt Service Routine called for the CTR Trigger interrupt. Implementation: Dynamic File drv_ctr.h C void DRV_CTR_TriggerISR(SYS_MODULE_OBJ object); Returns None. Description This function is called when the interrupt is generated for CTR trigger interrupt. The interrupt handling for this interrupt is application specific. So, this function is kept open for the clients to modify. Remarks Specific interrupt handling can be taken care of by application developer, as the need for this interrupt is application specific. Preconditions None. Example This function is not called from clients/system. This function will be called when the interrupt for event is generated. Parameters Parameters Description object The driver instance handle returned after the initialization. Function void DRV_CTR_TriggerISR(SYS_MODULE_OBJ object); c) Data Types and Constants Enumerations Name Description DRV_CTR_CLIENT_STATUS Defines the client status. Implementation: Dynamic DRV_MODE Defines the driver mode. Implementation: Dynamic Macros Name Description DRV_CTR_COUNTER_NUM Number of counters in CTR module Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 371 DRV_CTR_INDEX_0 CTR driver index definitions DRV_CTR_LATCH_FIFO_CNT FIFO size for each latch in CTR module DRV_CTR_LATCH_NUM Number of latches in CTR module Structures Name Description DRV_CTR_COUNTER Contains all the data necessary to initialize the CTR counter. Implementation: Dynamic DRV_CTR_INIT Contains all the data necessary to initialize the CTR. Implementation: Dynamic DRV_CTR_LATCH Contains all the data necessary to initialize the CTR Latches. Implementation: Dynamic DRV_CTR_TRIGGER Contains all the data necessary to initialize the CTR Triggers. Implementation: Dynamic Types Name Description DRV_CTR_CALLBACK Callback function definition for CTR event interrupt. Implementation: Dynamic Description DRV_CTR_CALLBACK Type Callback function definition for CTR event interrupt. Implementation: Dynamic File drv_ctr.h C typedef void (* DRV_CTR_CALLBACK)(uintptr_t context, uint32_t * timestampbuffer, uint8_t BufferSize); Description CTR Event interrupt callback function The clients must define their callback functions in the same prototype as DRV_CTR_CALLBACK. All the registered callbacks will be called from drive ISR for CTR event. Remarks This structure is a part of initialization structure, which is used to initialize the CTR module. DRV_CTR_CLIENT_STATUS Enumeration Defines the client status. Implementation: Dynamic File drv_ctr.h C typedef enum { DRV_CTR_CLIENT_STATUS_READY = DRV_CLIENT_STATUS_READY+0, DRV_CTR_CLIENT_STATUS_BUSY = DRV_CLIENT_STATUS_BUSY, DRV_CTR_CLIENT_STATUS_CLOSED = DRV_CLIENT_STATUS_CLOSED, DRV_CTR_CLIENT_STATUS_ERROR = DRV_CLIENT_STATUS_ERROR } DRV_CTR_CLIENT_STATUS; Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 372 Members Members Description DRV_CTR_CLIENT_STATUS_READY = DRV_CLIENT_STATUS_READY+0 Up and running, ready to start new operations DRV_CTR_CLIENT_STATUS_BUSY = DRV_CLIENT_STATUS_BUSY Operation in progress, unable to start a new one DRV_CTR_CLIENT_STATUS_CLOSED = DRV_CLIENT_STATUS_CLOSED Client is closed DRV_CTR_CLIENT_STATUS_ERROR = DRV_CLIENT_STATUS_ERROR Client Error Description CTR Client Status Defines the various client status codes. Remarks None. DRV_CTR_COUNTER Structure Contains all the data necessary to initialize the CTR counter. Implementation: Dynamic File drv_ctr.h C typedef struct { uint32_t M; uint32_t N; uint8_t LSB; CTR_MODE_SELECT Mode; } DRV_CTR_COUNTER; Description CTR Counter init structure This structure contains all of the data necessary to initialize the CTR counter increment steps and the resolution. Remarks This structure is a part of initialization structure, which is used to initialize the CTR module. DRV_CTR_INIT Structure Contains all the data necessary to initialize the CTR. Implementation: Dynamic File drv_ctr.h C typedef struct { SYS_MODULE_INIT moduleInit; CTR_MODULE_ID ctrId; INT_SOURCE ctrEventInterruptSource; CTR_LATCH_INT_MODE ctrLatchEventMode; INT_SOURCE ctrTriggerInterruptSource; DRV_CTR_COUNTER ctrCounter[DRV_CTR_COUNTER_NUM]; DRV_CTR_LATCH ctrLatch[DRV_CTR_LATCH_NUM]; DRV_CTR_TRIGGER ctrTrigger; DRV_MODE drvMode; } DRV_CTR_INIT; Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 373 Members Members Description SYS_MODULE_INIT moduleInit; System module initialization CTR_MODULE_ID ctrId; Identifies the CTR peripheral instance INT_SOURCE ctrEventInterruptSource; CTR Event Interrupt Source CTR_LATCH_INT_MODE ctrLatchEventMode; CTR Event Interrupt Mode INT_SOURCE ctrTriggerInterruptSource; CTR Triggetr Interrupt Source DRV_CTR_COUNTER ctrCounter[DRV_CTR_COUNTER_NUM]; Counter Init Data DRV_CTR_LATCH ctrLatch[DRV_CTR_LATCH_NUM]; Latch Init Data DRV_MODE drvMode; Driver Mode Description CTR Driver Initialization Data This structure contains all of the data necessary to initialize the CTR. Remarks A pointer to a structure of this format containing the desired initialization data must be passed into the DRV_CTR_Initialize function. DRV_CTR_LATCH Structure Contains all the data necessary to initialize the CTR Latches. Implementation: Dynamic File drv_ctr.h C typedef struct { CTR_LATCH_TRIGGER_SELECT trigSel; CTR_LATCH_CTR_SELECT ctrSel; uint8_t divider; } DRV_CTR_LATCH; Description CTR Latch init structure This structure contains all of the data necessary to initialize the CTR Latches for mapping the trigger source and counter for a given latch. Remarks This structure is a part of initialization structure, which is used to initialize the CTR module. DRV_CTR_TRIGGER Structure Contains all the data necessary to initialize the CTR Triggers. Implementation: Dynamic File drv_ctr.h C typedef struct { CTR_LATCH_CTR_SELECT trigSource; uint16_t phase; } DRV_CTR_TRIGGER; Description CTR Trigger init structure This structure contains all of the data necessary to initialize the CTR Triggers for generating triggers from CTR. Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 374 Remarks This structure is a part of initialization structure, which is used to initialize the CTR module. DRV_MODE Enumeration Defines the driver mode. Implementation: Dynamic File drv_ctr.h C typedef enum { WIFI_MODE = 0, USB_MODE, GPIO_MODE } DRV_MODE; Description CTR Driver mode Driver can be configured to use for either of Wifi, USB or GPIO. Remarks None. DRV_CTR_COUNTER_NUM Macro Number of counters in CTR module File drv_ctr.h C #define DRV_CTR_COUNTER_NUM 2 Description Counters present in the CTR module These constants provide Number of counters in CTR module. Remarks These constants should be used in place of hard-coded numeric literals. DRV_CTR_INDEX_0 Macro CTR driver index definitions File drv_ctr.h C #define DRV_CTR_INDEX_0 0 Description Driver CTR Module Index reference These constants provide CTR driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_CTR_Initialize and DRV_CTR_Open routines to identify the driver instance in use. Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 375 DRV_CTR_LATCH_FIFO_CNT Macro FIFO size for each latch in CTR module File drv_ctr.h C #define DRV_CTR_LATCH_FIFO_CNT 4 Description FIFO size for each latch in the CTR module These constants provide Number of FIFO location available in each latch in CTR module. Remarks These constants should be used in place of hard-coded numeric literals. DRV_CTR_LATCH_NUM Macro Number of latches in CTR module File drv_ctr.h C #define DRV_CTR_LATCH_NUM 6 Description Latches present in the CTR module These constants provide Number of latches in CTR module. Remarks These constants should be used in place of hard-coded numeric literals. Files Files Name Description drv_ctr.h CTR Driver Interface Definition Description This section lists the source and header files used by the CTR Driver Library. drv_ctr.h CTR Driver Interface Definition Enumerations Name Description DRV_CTR_CLIENT_STATUS Defines the client status. Implementation: Dynamic DRV_MODE Defines the driver mode. Implementation: Dynamic Functions Name Description DRV_CTR_Adjust Sets the adjust value for a given CTR counter. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help CTR Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 376 DRV_CTR_ClientStatus Gets current client-specific status of the CTR driver. Implementation: Dynamic DRV_CTR_Close Closes an opened-instance of the CTR driver. Implementation: Dynamic DRV_CTR_Deinitialize Deinitializes the specified instance of the CTR driver module. Implementation: Dynamic DRV_CTR_Drift Sets the drift value for a given CTR counter. Implementation: Dynamic DRV_CTR_EventISR Interrupt Service Routine called for the CTR event interrupt. Implementation: Dynamic DRV_CTR_Initialize Initializes the CTR Driver instance for the specified driver index. Implementation: Dynamic DRV_CTR_Open Opens the specified CTR driver instance and returns a handle to it. Implementation: Dynamic DRV_CTR_RegisterCallBack Registers a callback function for the event interrupt of CTR. Implementation: Dynamic DRV_CTR_Status Gets the current status of the CTR Driver module. Implementation: Dynamic DRV_CTR_TriggerISR Interrupt Service Routine called for the CTR Trigger interrupt. Implementation: Dynamic Macros Name Description DRV_CTR_COUNTER_NUM Number of counters in CTR module DRV_CTR_INDEX_0 CTR driver index definitions DRV_CTR_LATCH_FIFO_CNT FIFO size for each latch in CTR module DRV_CTR_LATCH_NUM Number of latches in CTR module Structures Name Description DRV_CTR_COUNTER Contains all the data necessary to initialize the CTR counter. Implementation: Dynamic DRV_CTR_INIT Contains all the data necessary to initialize the CTR. Implementation: Dynamic DRV_CTR_LATCH Contains all the data necessary to initialize the CTR Latches. Implementation: Dynamic DRV_CTR_TRIGGER Contains all the data necessary to initialize the CTR Triggers. Implementation: Dynamic Types Name Description DRV_CTR_CALLBACK Callback function definition for CTR event interrupt. Implementation: Dynamic Description CTR Driver Interface Definition The CTR device driver provides a simple interface to manage the CTR Module This file defines the interface definition for the CTR Driver. File Name drv_CTR.h Company Microchip Technology Inc. Data EEPROM Driver Library This section describes the Data EEPROM Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 377 Introduction The MPLAB Harmony Data EEPROM Driver provides a high-level interface to manage the Data EEPROM module on the Microchip family of microcontrollers. Description The Data EEPROM Driver provides the following features: • Application-ready routines to perform block operations on the Data EEPROM • Multi-client operation support • Data transfer events • Supports Non-blocking mode of operation only The Data EEPROM Driver supports multi-client operation, which allows multiple application clients to access the same memory device. Multiple instances of the driver can be used when multiple EEPROM devices are required to be part of the system. Using the Library This topic describes the basic architecture of the Data EEPROM Driver Library and provides information and examples on its use. Description Interface Header File: drv_eeprom.h The interface to the EEPROM Driver Library is defined in the drv_eeprom.h header file. Any C language source (.c) file that uses the Data EPROM Driver Library should include drv_eeprom.h. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the Data EEPROM Driver Library 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 Data EEPROM driver provides a set of APIs that can be used to perform Erase, Write, and Read operations. The following diagram depicts the communication between different modules. As shown in the diagram, the Data EEPROM Driver sits between the Peripheral Libraries and the application or system layer to facilitate block and file access to the EEPROM. Data EEPROM Driver Abstraction Model Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 378 Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Data EEPROM Driver. Library Interface Section Description System Interaction Functions Provides system module interfaces, device initialization, deinitialization, tasks, and status functions. Client Core Functions Provides open, close, and other setup functions. Block Operation Functions Provides read, write, and erase functions to perform data transfer operations on the EEPROM device. Media Interface Functions Provides functions to query the EEPROM geometry and media status. How the Library Works Provides information on system, client core, block operation, and media interface functions. Description System Functions Data EEPROM Driver Initialization The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 379 system initialization, each instance of the Data EEPROM Driver would be initialized with the following configuration settings passed dynamically at run time using DRV_EEPROM_INIT, that are supported by the specific EEPROM driver: • Device requested power state: One of the system module power states. For specific details please refer to "Data Types and Constants" in the Library Interfacesection. • The actual peripheral ID enumerated as the PLIB level module ID (e.g., NVM_ID_0) • EEPROM Media Geometry The DRV_EEPROM_Initialize function configures and initializes the EEPROM driver using the configuration information provided. It returns an object handle of the type SYS_MODULE_OBJ. This object handle would be used by other system interfaces such as DRV_EEPROM_Status, DRV_EEPROM_Tasks and DRV_EEPROM_Deinitialize. Example: /*** Data EEPROM Driver Initialization Data ***/ SYS_FS_MEDIA_REGION_GEOMETRY EEPROMGeometryTable[3] = { { .blockSize = 4, .numBlocks = (DRV_EEPROM_MEDIA_SIZE * 1024), }, { .blockSize = 4, .numBlocks = ((DRV_EEPROM_MEDIA_SIZE * 1024)/4) }, { .blockSize = 4, .numBlocks = ((DRV_EEPROM_MEDIA_SIZE * 1024)/4) } }; const SYS_FS_MEDIA_GEOMETRY EEPROMGeometry = { .mediaProperty = SYS_FS_MEDIA_WRITE_IS_BLOCKING, .numReadRegions = 1, .numWriteRegions = 1, .numEraseRegions = 1, .geometryTable = (SYS_FS_MEDIA_REGION_GEOMETRY *)&EEPROMGeometryTable }; const DRV_EEPROM_INIT drvEepromInit = { .moduleInit.sys.powerState = SYS_MODULE_POWER_RUN_FULL, .eepromId = NVM_ID_0, .eepromMediaGeometry = (SYS_FS_MEDIA_GEOMETRY *)&EEPROMGeometry }; /* Initialize the Data EEPROM Driver */ sysObj.drvEeprom = DRV_EEPROM_Initialize(DRV_EEPROM_INDEX_0, (SYS_MODULE_INIT *)&drvEepromInit); Data EEPROM Driver Task Routine The Data EEPROM Driver task routine DRV_EEPROM_Tasks, will be called from the system task routine, SYS_Tasks. The driver task routine is responsible maintaining the driver state machine. The block operation requests from the application or from other modules are added to the driver queue. Data EEPROM Driver Status DRV_EEPROM_Status() returns the current status of the Data EEPROM Driver and is called by the MPLAB Harmony System. The application may not find the need to call this function directly. Example: SYS_MODULE_OBJ object; // Returned from DRV_EEPROM_Initialize SYS_STATUS eepromStatus; eepromStatus = DRV_EEPROM_Status(object); if (SYS_STATUS_ERROR >= eepromStatus) { // Handle error } Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 380 Client Core Functions Opening the Driver For the application to start using an instance of the module, it must call the DRV_EEPROM_Open function repeatedly until a valid handle is returned by the driver. The application client uses this driver handle to access the driver functions. For the various options available for I/O INTENT please refer to Data Types and Constants in the Library Interface section. Example: eepromHandle = DRV_EEPROM_Open(DRV_EEPROM_INDEX_0, DRV_IO_INTENT_READWRITE); if (DRV_HANDLE_INVALID == eepromHandle) { /* Call until the function returns a valid handle. */ } else { /* Do further processing. */ } Closing the Driver Closes an opened-instance of the Data EEPROM Driver. This invalidates the driver handle. The application must open the driver again to obtain a valid handle. Example: DRV_HANDLE eepromHandle; // Returned from DRV_EEPROM_Open DRV_EEPROM_Close(eepromHandle); Client Block Operation Functions The driver provides client interfaces to perform operations in terms of blocks. A block is a unit that represents the minimum amount of data that can be erased, written, or read. The block sizes may differ for Erase, Write, and Read operations. The DRV_EEPROM_GeometryGet function can be used to read out the geometry of the EEPROM device. The geometry indicates the number of read, write and erase regions, blocks per region and the size of each block. The DRV_EEPROM_Erase, DRV_EEPROM_Write, and DRV_EEPROM_Read functions are used to erase, write, and read the data to/from EEPROM devices. In addition to these functions, the driver also provides the DRV_EEPROM_BulkErase function that erases the entire EEPROM. These functions are non-blocking in nature and queue the operation request into the driver queue. All of the requests in the queue are executed by the DRV_EEPROM_Tasks function one-by-one. A command handle associated with the operation request is returned to the application client when the operation request is queued at the driver. This handle allows the application client to track the request as it progresses through the queue. The handle expires when the request processing is complete. The driver provides events (DRV_EEPROM_EVENT) that indicate the completion of the requests. The following steps can be performed for a simple Block Data Operation: 1. The system should have completed necessary initialization of the Data EEPROM Driver, and the DRV_EEPROM_Tasks function should be running in a polled environment. 2. Open the driver using DRV_EEPROM_Open with the necessary intent. 3. Set an event handler callback using the function DRV_EEPROM_EventHandlerSet. 4. Request for block operations using the functions, DRV_EEPROM_Erase, DRV_EEPROM_Write, DRV_EEPROM_Read and DRV_EEPROM_BulkErase with the appropriate parameters. 5. Wait for event handler callback to occur and check the status of the block operation using the callback function parameter of type DRV_EEPROM_ EVENT. 6. After performing the required block operations, the client can close the driver using the function , DRV_EEPROM_Close . Example: // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; uint8_t myBuffer[MY_BUFFER_SIZE]; uint32_t blockStart, nBlock; DRV_EEPROM_COMMAND_HANDLE commandHandle; // drvEEPROMHandle is the handle returned by the DRV_EEPROM_Open // function. Client registers an event handler with driver. This // is done once. DRV_EEPROM_EventHandlerSet(drvEEPROMHandle, APP_EEPROMEventHandler, (uintptr_t)&myAppObj); DRV_EEPROM_Read(drvEEPROMHandle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_EEPROM_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 381 } // Event Processing Technique. Event is received when operation // is done. void APP_EEPROMEventHandler ( DRV_EEPROM_EVENT event, DRV_EEPROM_COMMAND_HANDLE commandHandle, uintptr_t contextHandle ) { // The context handle was set to an application specific // object. It is now retrievable easily in the event // handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) context; switch(event) { case DRV_EEPROM_EVENT_COMMAND_COMPLETE: // Operation completed successfully. break; case DRV_EEPROM_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Media Interface Functions Reading the Device Geometry The application can call the DRV_EEPROM_GeometryGet function to obtain the geometry of the EEPROM device. The geometry indicates the number of read, write and erase regions, number of blocks per region and the size of each block. Example: SYS_FS_MEDIA_GEOMETRY * eepromGeometry; uint32_t readBlockSize, writeBlockSize, eraseBlockSize; uint32_t nReadBlocks, nReadRegions, totalSize; eepromGeometry = DRV_EEPROM_GeometryGet(eepromOpenHandle1); readBlockSize = eepromGeometry->geometryTable->blockSize; nReadBlocks = eepromGeometry->geometryTable->numBlocks; nReadRegions = eepromGeometry->numReadRegions; writeBlockSize = (eepromGeometry->geometryTable +1)->blockSize; eraseBlockSize = (eepromGeometry->geometryTable +2)->blockSize; //The below expression provides the EEPROM memory size. totalSize = readBlockSize * nReadBlocks * nReadRegions; Configuring the Library Macros Name Description DRV_EEPROM_BUFFER_OBJECT_NUMBER Selects the maximum number of buffer objects DRV_EEPROM_CLIENTS_NUMBER Selects the maximum number of clients DRV_EEPROM_INSTANCES_NUMBER Selects the maximum number of Driver instances that can be supported by the dynamic driver. DRV_EEPROM_MEDIA_SIZE Specifies the EEPROM Media size. DRV_EEPROM_SYS_FS_REGISTER Register to use with the File system Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 382 Description The configuration of the Data EEPROM Driver is based on the file system_config.h. This header file contains the configuration selection for the Data EEPROM Driver. Based on the selections made, the Data EEPROM Driver may support the selected features. These configuration settings will apply to all instances of the Data EEPROM Driver. This header can be placed anywhere, 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. DRV_EEPROM_BUFFER_OBJECT_NUMBER Macro Selects the maximum number of buffer objects File drv_eeprom_config_template.h C #define DRV_EEPROM_BUFFER_OBJECT_NUMBER 5 Description EEPROM Driver maximum number of buffer objects This definition selects the maximum number of buffer objects. This indirectly also specifies the queue depth. The EEPROM Driver can queue up to DRV_EEPROM_BUFFER_OBJECT_NUMBER of read/write requests before returning a DRV_EEPROM_BUFFER_HANDLE_INVALID due to the queue being full. Buffer objects are shared by all instances of the driver. Increasing this number increases the RAM requirement of the driver. Remarks This macro is mandatory when building the driver for dynamic operation. DRV_EEPROM_CLIENTS_NUMBER Macro Selects the maximum number of clients File drv_eeprom_config_template.h C #define DRV_EEPROM_CLIENTS_NUMBER 1 Description EEPROM maximum number of clients This definition selects the maximum number of clients that the EEPROM driver can support at run time. This constant defines the total number of EEPROM driver clients that will be available to all instances of the EEPROM driver. Remarks This macro is mandatory when building the driver for dynamic operation. DRV_EEPROM_INSTANCES_NUMBER Macro Selects the maximum number of Driver instances that can be supported by the dynamic driver. File drv_eeprom_config_template.h C #define DRV_EEPROM_INSTANCES_NUMBER 1 Description EEPROM Driver instance configuration This definition selects the maximum number of Driver instances that can be supported by the dynamic driver. In case of this driver, multiple instances of the driver could use the same hardware instance. Remarks This macro is mandatory when building the driver for dynamic operation. Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 383 DRV_EEPROM_MEDIA_SIZE Macro Specifies the EEPROM Media size. File drv_eeprom_config_template.h C #define DRV_EEPROM_MEDIA_SIZE 32 Description EEPROM Media Size This definition specifies the EEPROM Media Size to be used. The size is specified in number of Kilo Bytes. The media size MUST never exceed physical available EEPROM Memory size. Application code requirements should be kept in mind while defining this parameter. Remarks This macro is mandatory when building the driver for dynamic operation. DRV_EEPROM_SYS_FS_REGISTER Macro Register to use with the File system File drv_eeprom_config_template.h C #define DRV_EEPROM_SYS_FS_REGISTER Description EEPROM Driver Register with File System Specifying this macro enables the EEPROM driver to register its services with the SYS FS. Remarks This macro is optional and should be specified only if the EEPROM driver is to be used with the File System. Building the Library This section lists the files that are available in the Data EEPROM Driver Library. Description This section lists the files that are available in the \src folder of the Data EEPROM 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. 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 /framework/driver/eeprom. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_eeprom.h Header file that exports the driver API. 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 /src/dynamic/drv_eeprom.c Basic Data EEPROM Driver implementation file. Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 384 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 N/A No optional files are available for this library Module Dependencies The Data EEPROM Driver Library is not dependent upon any modules. Library Interface a) System Functions Name Description DRV_EEPROM_Initialize Initializes the EEPROM instance for the specified driver index. DRV_EEPROM_Deinitialize Deinitializes the specified instance of the EEPROM driver module DRV_EEPROM_Status Gets the current status of the EEPROM driver module. DRV_EEPROM_Tasks Handles the read or write requests queued to the driver. b) Client Core Functions Name Description DRV_EEPROM_Close Closes an opened-instance of the EEPROM driver DRV_EEPROM_Open Opens the specified EEPROM driver instance and returns a handle to it c) Block Operation Functions Name Description DRV_EEPROM_BulkErase Performs a bulk erase of the entire Data EEPROM. DRV_EEPROM_Erase Erases blocks of data starting from the specified block address. DRV_EEPROM_Read Reads blocks of data from the specified address in EEPROM memory. DRV_EEPROM_Write Writes blocks of data starting from the specified address in EEPROM memory. d) Media Interface Functions Name Description DRV_EEPROM_AddressGet Returns the EEPROM media start address DRV_EEPROM_CommandStatus Gets the current status of the command. DRV_EEPROM_EventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. DRV_EEPROM_GeometryGet Returns the geometry of the device. DRV_EEPROM_IsAttached Returns the physical attach status of the EEPROM. DRV_EEPROM_IsWriteProtected Returns the write protect status of the EEPROM. e) Data Types and Constants Name Description DRV_EEPROM_COMMAND_HANDLE_INVALID This value defines the EEPROM Driver's Invalid Command Handle. DRV_EEPROM_INDEX_0 EEPROM driver index definition DRV_EEPROM_COMMAND_HANDLE Handle identifying commands queued in the driver. DRV_EEPROM_COMMAND_STATUS Specifies the status of the command for read or write requests. DRV_EEPROM_EVENT Identifies the possible events that can result from a request. DRV_EEPROM_EVENT_HANDLER Pointer to a EEPROM Driver Event handler function DRV_EEPROM_INIT Defines the data required to initialize the EEPROM driver Description This section describes the Application Programming Interface (API) functions of the Data EEPROM Driver Library. a) System Functions Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 385 DRV_EEPROM_Initialize Function Initializes the EEPROM instance for the specified driver index. File drv_eeprom.h C SYS_MODULE_OBJ DRV_EEPROM_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise it returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the EEPROM driver instance for the specified driver index, making it ready for clients to open and use it. Remarks This routine must be called before any other EEPROM routine is called. This routine should only be called once during system initialization unless DRV_EEPROM_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. The system must use DRV_EEPROM_Status to find out when the driver is in the ready state. Build configuration options may be used to statically override options in the "init" structure and will take precedence over initialization data passed using this routine. Preconditions None. Example // This code snippet shows an example of initializing the EEPROM Driver. SYS_MODULE_OBJ objectHandle; SYS_FS_MEDIA_REGION_GEOMETRY EEPROMGeometryTable[3] = { { .blockSize = 4, .numBlocks = (DRV_EEPROM_MEDIA_SIZE * 1024), }, { .blockSize = 4, .numBlocks = ((DRV_EEPROM_MEDIA_SIZE * 1024)/4) }, { .blockSize = 4, .numBlocks = ((DRV_EEPROM_MEDIA_SIZE * 1024)/4) } }; const SYS_FS_MEDIA_GEOMETRY EEPROMGeometry = { .mediaProperty = SYS_FS_MEDIA_WRITE_IS_BLOCKING, .numReadRegions = 1, .numWriteRegions = 1, .numEraseRegions = 1, .geometryTable = (SYS_FS_MEDIA_REGION_GEOMETRY *)&EEPROMGeometryTable }; // EEPROM Driver Initialization Data const DRV_EEPROM_INIT drvEepromInit = { .moduleInit.sys.powerState = SYS_MODULE_POWER_RUN_FULL, .eepromId = NVM_ID_0, .eepromMediaGeometry = (SYS_FS_MEDIA_GEOMETRY *)&EEPROMGeometry }; Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 386 objectHandle = DRV_EEPROM_Initialize(DRV_EEPROM_INDEX_0, (SYS_MODULE_INIT*)&drvEepromInit); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized. init Pointer to a data structure containing any data necessary to initialize the driver. Function SYS_MODULE_OBJ DRV_EEPROM_Initialize ( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); DRV_EEPROM_Deinitialize Function Deinitializes the specified instance of the EEPROM driver module File drv_eeprom.h C void DRV_EEPROM_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the EEPROM driver module, disabling its operation. Invalidates all the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. Preconditions Function DRV_EEPROM_Initialize should have been called before calling this function. Parameter: object - Driver object handle, returned from the DRV_EEPROM_Initialize routine Example // This code snippet shows an example of deinitializing the driver. SYS_MODULE_OBJ object; // Returned from DRV_EEPROM_Initialize SYS_STATUS status; DRV_EEPROM_Deinitialize(object); status = DRV_EEPROM_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know when the driver is // deinitialized. } Function void DRV_EEPROM_Deinitialize ( SYS_MODULE_OBJ object ); Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 387 DRV_EEPROM_Status Function Gets the current status of the EEPROM driver module. File drv_eeprom.h C SYS_STATUS DRV_EEPROM_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is ready and accept requests for new operations. SYS_STATUS_UNINITIALIZED - Indicates the driver is not initialized. Description This routine provides the current status of the EEPROM driver module. Remarks None. Preconditions Function DRV_EEPROM_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_EEPROM_Initialize SYS_STATUS EEPROMStatus; EEPROMStatus = DRV_EEPROM_Status(object); if (EEPROMStatus == SYS_STATUS_READY) { // Driver is ready to perform operations. } else { // Driver is not ready. } Parameters Parameters Description object Driver object handle, returned from the DRV_EEPROM_Initialize routine Function SYS_STATUS DRV_EEPROM_Status ( SYS_MODULE_OBJ object ); DRV_EEPROM_Tasks Function Handles the read or write requests queued to the driver. File drv_eeprom.h C void DRV_EEPROM_Tasks(SYS_MODULE_OBJ object); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 388 Description This routine is used to handle the read or write requests queued to the driver. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks). Preconditions The DRV_EEPROM_Initialize routine must have been called for the specified EEPROM driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_EEPROM_Initialize while (true) { DRV_EEPROM_Tasks (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_EEPROM_Initialize) Function void DRV_EEPROM_Tasks ( SYS_MODULE_OBJ object ); b) Client Core Functions DRV_EEPROM_Close Function Closes an opened-instance of the EEPROM driver File drv_eeprom.h C void DRV_EEPROM_Close(const DRV_HANDLE handle); Returns None Description This routine closes an opened-instance of the EEPROM driver, invalidating the handle. Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_EEPROM_Open before the caller may use the driver again. Usually there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_EEPROM_Initialize routine must have been called for the specified EEPROM driver instance. DRV_EEPROM_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_EEPROM_Open DRV_EEPROM_Close(handle); Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 389 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_EEPROM_Close ( const DRV_HANDLE handle ); DRV_EEPROM_Open Function Opens the specified EEPROM driver instance and returns a handle to it File drv_eeprom.h C DRV_HANDLE DRV_EEPROM_Open(const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, DRV_HANDLE_INVALID is returned. Errors can occur under the following circumstances: • if the number of client objects allocated via DRV_EEPROM_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the client is trying to open the driver exclusively, but has already been opened in a non exclusive mode by another client. • if the driver hardware instance being opened is invalid Description This routine opens the specified EEPROM driver instance and provides a handle. This handle must be provided to all other client-level operations to identify the caller and the instance of the driver. Remarks The handle returned is valid until the DRV_EEPROM_Close routine is called. This routine will NEVER block waiting for hardware. If the driver has already been opened, it cannot be opened exclusively. Preconditions DRV_EEPROM_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_EEPROM_Open(DRV_EEPROM_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } Parameters Parameters Description index Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver Function DRV_HANDLE DRV_EEPROM_Open ( const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent ); Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 390 c) Block Operation Functions DRV_EEPROM_BulkErase Function Performs a bulk erase of the entire Data EEPROM. File drv_eeprom.h C void DRV_EEPROM_BulkErase(const DRV_HANDLE handle, DRV_EEPROM_COMMAND_HANDLE * commandHandle); Returns If the request was queued successfully then a valid command handle is returned in the commandHandle argument. Otherwise DRV_EEPROM_COMMAND_HANDLE_INVALID is returned if the request was not successful. Description This function schedules a non-blocking bulk erase operation of the entire Data EEPROM. The function returns with a valid handle in the commandHandle argument if the erase request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. The function returns DRV_EEPROM_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer object could not be allocated to the request • if the client opened the driver for read only • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_EEPROM_EVENT_COMMAND_COMPLETE event if the command was processed successfully or DRV_EEPROM_EVENT_COMMAND_ERROR event if the command was not processed successfully. Remarks None Refer to drv_eeprom.h for usage information. Preconditions The DRV_EEPROM_Initialize() routine must have been called for the specified EEPROM driver instance. DRV_EEPROM_Open() routine must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified as a parameter to this routine. Example DRV_EEPROM_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // myEEPROMHandle is the handle returned by the DRV_EEPROM_Open function. // Client registers an event handler with driver DRV_EEPROM_EventHandlerSet(myEEPROMHandle, APP_EEPROMEventHandler, (uintptr_t)&myAppObj); DRV_EEPROM_BulkErase(myEEPROMHandle, &commandHandle); if(DRV_EEPROM_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when the buffer is processed. void APP_EEPROMEventHandler ( DRV_EEPROM_EVENT event, DRV_EEPROM_COMMAND_HANDLE commandHandle, uintptr_t context ) { Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 391 // context points to myAppObj. switch(event) { case DRV_EEPROM_EVENT_COMMAND_COMPLETE: // Bulk Erase operation is complete. break; case DRV_EEPROM_EVENT_COMMAND_ERROR: // Bulk Erase operation failed. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle Function void DRV_EEPROM_BulkErase ( const DRV_HANDLE handle, DRV_EEPROM_COMMAND_HANDLE * commandHandle ); DRV_EEPROM_Erase Function Erases blocks of data starting from the specified block address. File drv_eeprom.h C void DRV_EEPROM_Erase(const DRV_HANDLE handle, DRV_EEPROM_COMMAND_HANDLE * commandHandle, uint32_t blockStart, uint32_t nBlock); Returns If the request was queued successfully then a valid command handle is returned in the commandHandle argument. Otherwise DRV_EEPROM_COMMAND_HANDLE_INVALID is returned if the request was not successful. Description This function schedules a non-blocking erase operation for erasing blocks of memory. The function returns with a valid handle in the commandHandle argument if the erase request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. The function returns DRV_EEPROM_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer object could not be allocated to the request • if the client opened the driver for read only • if the number of blocks to be erased is either zero or more than the number of blocks actually available • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_EEPROM_EVENT_COMMAND_COMPLETE event if the command was processed successfully or DRV_EEPROM_EVENT_COMMAND_ERROR event if the command was not processed successfully. Remarks None Preconditions The DRV_EEPROM_Initialize() routine must have been called for the specified EEPROM driver instance. Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 392 DRV_EEPROM_Open() routine must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified as a parameter to this routine. Example uint32_t blockStart = 0; uint32_t nBlock = 2; DRV_EEPROM_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // myEEPROMHandle is the handle returned by the DRV_EEPROM_Open function. // Client registers an event handler with driver DRV_EEPROM_EventHandlerSet(myEEPROMHandle, APP_EEPROMEventHandler, (uintptr_t)&myAppObj); DRV_EEPROM_Erase(myEEPROMHandle, &commandHandle, blockStart, nBlock); if(DRV_EEPROM_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when the buffer is processed. void APP_EEPROMEventHandler ( DRV_EEPROM_EVENT event, DRV_EEPROM_COMMAND_HANDLE commandHandle, uintptr_t context ) { // context points to myAppObj. switch(event) { case DRV_EEPROM_EVENT_COMMAND_COMPLETE: // Erase operation is complete. break; case DRV_EEPROM_EVENT_COMMAND_ERROR: // Erase operation failed. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle blockStart block start addess for the erase operation. nBlock Total number of blocks to be erased. Function void DRV_EEPROM_Erase ( const DRV_HANDLE handle, DRV_EEPROM_COMMAND_HANDLE * commandHandle, uint32_t blockStart, uint32_t nBlock ); Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 393 DRV_EEPROM_Read Function Reads blocks of data from the specified address in EEPROM memory. File drv_eeprom.h C void DRV_EEPROM_Read(const DRV_HANDLE handle, DRV_EEPROM_COMMAND_HANDLE * commandHandle, void * buffer, uint32_t blockStart, uint32_t nBlock); Returns If the request was queued successfully then a valid command handle is returned in the commandHandle argument. Otherwise DRV_EEPROM_COMMAND_HANDLE_INVALID is returned if the request was not successful. Description This function schedules a non-blocking read operation for reading blocks of data from the EEPROM memory. The function returns with a valid handle in the commandHandle argument if the read request was scheduled successfully. The function adds the request to the driver instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_EEPROM_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer object could not be allocated to the request • if the buffer pointer is NULL • if the queue size is full or queue depth is insufficient • if the driver handle is invalid • if the number of blocks to be read is zero or more than the actual number of blocks available • if the client opened the driver in write only mode If the requesting client registered an event callback with the driver, the driver will issue a DRV_EEPROM_EVENT_COMMAND_COMPLETE event if the command was processed successfully or DRV_EEPROM_EVENT_COMMAND_ERROR event if the command was not processed successfully. Remarks None. Preconditions The DRV_EEPROM_Initialize routine must have been called for the specified EEPROM driver instance. DRV_EEPROM_Open must have been called with DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE as the ioIntent to obtain a valid opened device handle. Example uint8_t myBuffer[MY_BUFFER_SIZE]; // address should be block aligned. uint32_t blockStart = EEPROM_BASE_ADDRESS_TO_READ_FROM; uint32_t nBlock = 2; DRV_EEPROM_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // myEEPROMHandle is the handle returned by the DRV_EEPROM_Open function. DRV_EEPROM_EventHandlerSet(myEEPROMHandle, APP_EEPROMEventHandler, (uintptr_t)&myAppObj); DRV_EEPROM_Read(myEEPROMHandle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_EEPROM_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } else { // Read queued successfully. } // Event is received when the buffer is processed. void APP_EEPROMEventHandler ( DRV_EEPROM_EVENT event, Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 394 DRV_EEPROM_COMMAND_HANDLE commandHandle, uintptr_t context ) { // context points to myAppObj. switch(event) { case DRV_EEPROM_EVENT_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_EEPROM_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle buffer Buffer into which the data read from the EEPROM memory will be placed blockStart Start block address in EEPROM memory from where the read should begin. nBlock Total number of blocks to be read. Function void DRV_EEPROM_Read ( const DRV_HANDLE handle, DRV_EEPROM_COMMAND_HANDLE * commandHandle, void * buffer, uint32_t blockStart, uint32_t nBlock ); DRV_EEPROM_Write Function Writes blocks of data starting from the specified address in EEPROM memory. File drv_eeprom.h C void DRV_EEPROM_Write(const DRV_HANDLE handle, DRV_EEPROM_COMMAND_HANDLE * commandHandle, void * buffer, uint32_t blockStart, uint32_t nBlock); Returns If the request was queued successfully then a valid command handle is returned in the commandHandle argument. Otherwise DRV_EEPROM_COMMAND_HANDLE_INVALID is returned if the request was not successful. Description This function schedules a non-blocking write operation for writing blocks of data into memory. The function returns with a valid handle in the commandHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_EEPROM_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer object could not be allocated to the request • if the buffer pointer is NULL Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 395 • if the client opened the driver for read only • if the number of blocks to be written is either zero or more than the number of blocks actually available • if the write queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_EEPROM_EVENT_COMMAND_COMPLETE event if the command was processed successfully or DRV_EEPROM_EVENT_COMMAND_ERROR event if the command was not processed successfully. Remarks None Preconditions The DRV_EEPROM_Initialize() routine must have been called for the specified EEPROM driver instance. DRV_EEPROM_Open() routine must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified as a parameter to this routine. Example uint8_t myBuffer[MY_BUFFER_SIZE]; uint32_t blockStart = EEPROM_BASE_ADDRESS_TO_WRITE_TO; uint32_t nBlock = 2; DRV_EEPROM_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // myEEPROMHandle is the handle returned by the DRV_EEPROM_Open function. // Client registers an event handler with driver DRV_EEPROM_EventHandlerSet(myEEPROMHandle, APP_EEPROMEventHandler, (uintptr_t)&myAppObj); DRV_EEPROM_Write(myEEPROMHandle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_EEPROM_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when the buffer is processed. void APP_EEPROMEventHandler ( DRV_EEPROM_EVENT event, DRV_EEPROM_COMMAND_HANDLE commandHandle, uintptr_t context ) { // context points to myAppObj. switch(event) { case DRV_EEPROM_EVENT_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_EEPROM_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 396 buffer The buffer containing data to be programmed into EEPROM memory blockStart Start block address of EEPROM memory where the write should begin. nBlock Total number of blocks to be written. Function void DRV_EEPROM_Write ( const DRV_HANDLE handle, DRV_EEPROM_COMMAND_HANDLE * commandHandle, void * buffer, uint32_t blockStart, uint32_t nBlock ); d) Media Interface Functions DRV_EEPROM_AddressGet Function Returns the EEPROM media start address File drv_eeprom.h C uintptr_t DRV_EEPROM_AddressGet(const DRV_HANDLE handle); Returns Start address of the EEPROM Media if the handle is valid otherwise NULL. Description This function returns the EEPROM Media start address. Remarks None. Preconditions The DRV_EEPROM_Initialize() routine must have been called for the specified EEPROM driver instance. The DRV_EEPROM_Open() routine must have been called to obtain a valid opened device handle. Example uintptr_t startAddress; startAddress = DRV_EEPROM_AddressGet(drvEEPROMHandle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function uintptr_t DRV_EEPROM_AddressGet ( const DRV_HANDLE handle ); DRV_EEPROM_CommandStatus Function Gets the current status of the command. Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 397 File drv_eeprom.h C DRV_EEPROM_COMMAND_STATUS DRV_EEPROM_CommandStatus(const DRV_HANDLE handle, const DRV_EEPROM_COMMAND_HANDLE commandHandle); Returns A DRV_EEPROM_COMMAND_STATUS value describing the current status of the command. Description This routine gets the current status of the command. The application must use this routine where the status of a scheduled command needs to be polled on. The function may return DRV_EEPROM_COMMAND_HANDLE_INVALID in a case where the command handle has expired. A command handle expires when the internal buffer object is re-assigned to another read, write or erase request. It is recommended that this function be called regularly in order to track the command status correctly. The application can alternatively register an event handler to receive read, write or erase operation completion events. Remarks This routine will not block for hardware access and will immediately return the current status. Preconditions The DRV_EEPROM_Initialize() routine must have been called. The DRV_EEPROM_Open() must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_EEPROM_Open DRV_EEPROM_COMMAND_HANDLE commandHandle; DRV_EEPROM_COMMAND_STATUS status; status = DRV_EEPROM_CommandStatus(handle, commandHandle); if(status == DRV_EEPROM_COMMAND_COMPLETED) { // Operation Done } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine commandHandle A valid command handle returned from read, write or erase request. Function DRV_EEPROM_COMMAND_STATUS DRV_EEPROM_CommandStatus ( const DRV_HANDLE handle, const DRV_EEPROM_COMMAND_HANDLE commandHandle ); DRV_EEPROM_EventHandlerSet Function Allows a client to identify an event handling function for the driver to call back when queued operation has completed. File drv_eeprom.h C void DRV_EEPROM_EventHandlerSet(const DRV_HANDLE handle, const void * eventHandler, const uintptr_t context); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 398 Description This function allows a client to identify an event handling function for the driver to call back when queued operation has completed. When a client calls a read, write or a erase function, it is provided with a handle identifying the command that was added to the driver's command queue. The driver will pass this handle back to the client by calling "eventHandler" function when the queued operation has completed. The event handler should be set before the client performs any read, write or erase operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued operation has completed, it does not need to register a callback. Preconditions The DRV_EEPROM_Initialize() routine must have been called for the specified EEPROM driver instance. The DRV_EEPROM_Open() routine must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; uint8_t myBuffer[MY_BUFFER_SIZE]; uint32_t blockStart, nBlock; DRV_EEPROM_COMMAND_HANDLE commandHandle; // drvEEPROMHandle is the handle returned by the DRV_EEPROM_Open function. // Client registers an event handler with driver. This is done once. DRV_EEPROM_EventHandlerSet(drvEEPROMHandle, APP_EEPROMEventHandler, (uintptr_t)&myAppObj); DRV_EEPROM_Read(drvEEPROMHandle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_EEPROM_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event Processing Technique. Event is received when operation is done. void APP_EEPROMEventHandler ( DRV_EEPROM_EVENT event, DRV_EEPROM_COMMAND_HANDLE commandHandle, uintptr_t context ) { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) context; switch(event) { case DRV_EEPROM_EVENT_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_EEPROM_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 399 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function eventHandler Pointer to the event handler function implemented by the user context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_EEPROM_EventHandlerSet ( const DRV_HANDLE handle, const void * eventHandler, const uintptr_t context ); DRV_EEPROM_GeometryGet Function Returns the geometry of the device. File drv_eeprom.h C SYS_FS_MEDIA_GEOMETRY * DRV_EEPROM_GeometryGet(const DRV_HANDLE handle); Returns SYS_FS_MEDIA_GEOMETRY - Pointer to structure which holds the media geometry information. Description This API gives the following geometrical details of the EEPROM memory: • Media Property • Number of Read/Write/Erase regions • Number of Blocks and their size in each region of the device Remarks None. Preconditions The DRV_EEPROM_Initialize() routine must have been called for the specified EEPROM driver instance. The DRV_EEPROM_Open() routine must have been called to obtain a valid opened device handle. Example SYS_FS_MEDIA_GEOMETRY * eepromGeometry; uint32_t readBlockSize, writeBlockSize, eraseBlockSize; uint32_t nReadBlocks, nReadRegions, totalSize; eepromGeometry = DRV_EEPROM_GeometryGet(eepromOpenHandle1); readBlockSize = eepromGeometry->geometryTable->blockSize; nReadBlocks = eepromGeometry->geometryTable->numBlocks; nReadRegions = eepromGeometry->numReadRegions; writeBlockSize = (eepromGeometry->geometryTable +1)->blockSize; eraseBlockSize = (eepromGeometry->geometryTable +2)->blockSize; totalSize = readBlockSize * nReadBlocks * nReadRegions; Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 400 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function SYS_FS_MEDIA_GEOMETRY * DRV_EEPROM_GeometryGet ( const DRV_HANDLE handle ); DRV_EEPROM_IsAttached Function Returns the physical attach status of the EEPROM. File drv_eeprom.h C bool DRV_EEPROM_IsAttached(const DRV_HANDLE handle); Returns Returns true always Description This function returns the physical attach status of the EEPROM. Remarks None. Preconditions The DRV_EEPROM_Initialize() routine must have been called for the specified EEPROM driver instance. The DRV_EEPROM_Open() routine must have been called to obtain a valid opened device handle. Example // The EEPROM media is always attached and so the below always returns // true. bool isEEPROMAttached; isEEPROMAttached = DRV_EEPROM_isAttached(drvEEPROMHandle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function bool DRV_EEPROM_IsAttached ( const DRV_HANDLE handle ); DRV_EEPROM_IsWriteProtected Function Returns the write protect status of the EEPROM. File drv_eeprom.h C bool DRV_EEPROM_IsWriteProtected(const DRV_HANDLE handle); Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 401 Returns Always returns false. Description This function returns the physical attach status of the EEPROM. This function always returns false. Remarks None. Preconditions The DRV_EEPROM_Initialize() routine must have been called for the specified EEPROM driver instance. The DRV_EEPROM_Open() routine must have been called to obtain a valid opened device handle. Example // The EEPROM media is treated as always writeable. bool isWriteProtected; isWriteProtected = DRV_EEPROM_IsWriteProtected(drvEEPROMHandle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function bool DRV_EEPROM_IsWriteProtected ( const DRV_HANDLE handle ); e) Data Types and Constants DRV_EEPROM_COMMAND_HANDLE_INVALID Macro This value defines the EEPROM Driver's Invalid Command Handle. File drv_eeprom.h C #define DRV_EEPROM_COMMAND_HANDLE_INVALID SYS_FS_MEDIA_BLOCK_COMMAND_HANDLE_INVALID Description EEPROM Driver Invalid Command Handle. This value defines the EEPROM Driver Invalid Command Handle. This value is returned by read or write routines when the command request was not accepted. Remarks None. DRV_EEPROM_INDEX_0 Macro EEPROM driver index definition File drv_eeprom.h C #define DRV_EEPROM_INDEX_0 0 Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 402 Description Driver EEPROM Module Index reference This constant provides EEPROM driver index definition. Remarks This constant should be used in place of hard-coded numeric literals. This value should be passed into the DRV_EEPROM_Initialize and DRV_EEPROM_Open routines to identify the driver instance in use. DRV_EEPROM_COMMAND_HANDLE Type Handle identifying commands queued in the driver. File drv_eeprom.h C typedef SYS_FS_MEDIA_BLOCK_COMMAND_HANDLE DRV_EEPROM_COMMAND_HANDLE; Description EEPROM Driver command handle. A command handle is returned by a call to the read or write functions. This handle allows the application to track the completion of the operation. This command handle is also returned to the client along with the event that has occurred with respect to the command. This allows the application to connect the event to a specific command in case where multiple commands are queued. The command handle associated with the command request expires when the client has been notified of the completion of the command (after event handler function that notifies the client returns) or after the command has been retired by the driver if no event handler callback was set. Remarks None. DRV_EEPROM_COMMAND_STATUS Enumeration Specifies the status of the command for read or write requests. File drv_eeprom.h C typedef enum { DRV_EEPROM_COMMAND_COMPLETED = SYS_FS_MEDIA_COMMAND_COMPLETED, DRV_EEPROM_COMMAND_QUEUED = SYS_FS_MEDIA_COMMAND_QUEUED, DRV_EEPROM_COMMAND_IN_PROGRESS = SYS_FS_MEDIA_COMMAND_IN_PROGRESS, DRV_EEPROM_COMMAND_ERROR_UNKNOWN = SYS_FS_MEDIA_COMMAND_UNKNOWN } DRV_EEPROM_COMMAND_STATUS; Members Members Description DRV_EEPROM_COMMAND_COMPLETED = SYS_FS_MEDIA_COMMAND_COMPLETED Done OK and ready DRV_EEPROM_COMMAND_QUEUED = SYS_FS_MEDIA_COMMAND_QUEUED Scheduled but not started DRV_EEPROM_COMMAND_IN_PROGRESS = SYS_FS_MEDIA_COMMAND_IN_PROGRESS Currently being in transfer DRV_EEPROM_COMMAND_ERROR_UNKNOWN = SYS_FS_MEDIA_COMMAND_UNKNOWN Unknown Command Description EEPROM Driver Command Status EEPROM Driver command Status This type specifies the status of the command for the read or write requests. Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 403 Remarks None. DRV_EEPROM_EVENT Enumeration Identifies the possible events that can result from a request. File drv_eeprom.h C typedef enum { DRV_EEPROM_EVENT_COMMAND_COMPLETE = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_COMPLETE, DRV_EEPROM_EVENT_COMMAND_ERROR = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_ERROR } DRV_EEPROM_EVENT; Members Members Description DRV_EEPROM_EVENT_COMMAND_COMPLETE = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_COMPLETE Operation has been completed successfully. DRV_EEPROM_EVENT_COMMAND_ERROR = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_ERROR There was an error during the operation Description EEPROM Driver Events This enumeration identifies the possible events that can result from a read or write request caused by the client. Remarks One of these values is passed in the "event" parameter of the event handling callback function that client registered with the driver by calling the DRV_EEPROM_EventHandlerSet function when a request is completed. DRV_EEPROM_EVENT_HANDLER Type Pointer to a EEPROM Driver Event handler function File drv_eeprom.h C typedef SYS_FS_MEDIA_EVENT_HANDLER DRV_EEPROM_EVENT_HANDLER; Returns None. Description EEPROM Driver Event Handler Function Pointer This data type defines the required function signature for the EEPROM event handling callback function. A client must register a pointer to an event handling function whose function signature (parameter and return value types) match the types specified by this function pointer in order to receive event callbacks from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks If the event is DRV_EEPROM_EVENT_COMMAND_COMPLETE, it means that the scheduled operation was completed successfully. If the event is DRV_EEPROM_EVENT_COMMAND_ERROR, it means that the scheduled operation was not completed successfully. The context parameter contains the handle to the client context, provided at the time the event handling function was registered using the DRV_EEPROM_EventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that scheduled the request. The event handler function executes in the driver's context. It is recommended of the application to not perform process intensive or blocking operations within this function. Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 404 Example void APP_MyEepromEventHandler ( DRV_EEPROM_EVENT event, DRV_EEPROM_COMMAND_HANDLE commandHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_EEPROM_EVENT_COMMAND_COMPLETE: // Handle the completed buffer. break; case DRV_EEPROM_EVENT_COMMAND_ERROR: default: // Handle error. break; } } Parameters Parameters Description event Identifies the type of event commandHandle Handle returned from the Read or Write requests context Value identifying the context of the application that registered the event handling function DRV_EEPROM_INIT Structure Defines the data required to initialize the EEPROM driver File drv_eeprom.h C typedef struct { SYS_MODULE_INIT moduleInit; NVM_MODULE_ID eepromId; const SYS_FS_MEDIA_GEOMETRY * eepromMediaGeometry; } DRV_EEPROM_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization NVM_MODULE_ID eepromId; Identifies hardware module (PLIB-level) ID const SYS_FS_MEDIA_GEOMETRY * eepromMediaGeometry; EEPROM Media geometry object. Description EEPROM Driver Initialization Data This data type defines the data required to initialize the EEPROM driver. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 405 Files Files Name Description drv_eeprom.h EEPROM Driver Interface Definition drv_eeprom_config_template.h EEPROM driver configuration definitions. Description drv_eeprom.h EEPROM Driver Interface Definition Enumerations Name Description DRV_EEPROM_COMMAND_STATUS Specifies the status of the command for read or write requests. DRV_EEPROM_EVENT Identifies the possible events that can result from a request. Functions Name Description DRV_EEPROM_AddressGet Returns the EEPROM media start address DRV_EEPROM_BulkErase Performs a bulk erase of the entire Data EEPROM. DRV_EEPROM_Close Closes an opened-instance of the EEPROM driver DRV_EEPROM_CommandStatus Gets the current status of the command. DRV_EEPROM_Deinitialize Deinitializes the specified instance of the EEPROM driver module DRV_EEPROM_Erase Erases blocks of data starting from the specified block address. DRV_EEPROM_EventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. DRV_EEPROM_GeometryGet Returns the geometry of the device. DRV_EEPROM_Initialize Initializes the EEPROM instance for the specified driver index. DRV_EEPROM_IsAttached Returns the physical attach status of the EEPROM. DRV_EEPROM_IsWriteProtected Returns the write protect status of the EEPROM. DRV_EEPROM_Open Opens the specified EEPROM driver instance and returns a handle to it DRV_EEPROM_Read Reads blocks of data from the specified address in EEPROM memory. DRV_EEPROM_Status Gets the current status of the EEPROM driver module. DRV_EEPROM_Tasks Handles the read or write requests queued to the driver. DRV_EEPROM_Write Writes blocks of data starting from the specified address in EEPROM memory. Macros Name Description DRV_EEPROM_COMMAND_HANDLE_INVALID This value defines the EEPROM Driver's Invalid Command Handle. DRV_EEPROM_INDEX_0 EEPROM driver index definition Structures Name Description DRV_EEPROM_INIT Defines the data required to initialize the EEPROM driver Types Name Description DRV_EEPROM_COMMAND_HANDLE Handle identifying commands queued in the driver. DRV_EEPROM_EVENT_HANDLER Pointer to a EEPROM Driver Event handler function Description EEPROM Driver Interface Definition The EEPROM driver provides a simple interface to manage the EEPROM Memory on Microchip microcontrollers. This file defines the interface Volume V: MPLAB Harmony Framework Driver Libraries Help Data EEPROM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 406 definition for the EEPROM driver. File Name drv_eeprom.h Company Microchip Technology Inc. drv_eeprom_config_template.h EEPROM driver configuration definitions. Macros Name Description DRV_EEPROM_BUFFER_OBJECT_NUMBER Selects the maximum number of buffer objects DRV_EEPROM_CLIENTS_NUMBER Selects the maximum number of clients DRV_EEPROM_INSTANCES_NUMBER Selects the maximum number of Driver instances that can be supported by the dynamic driver. DRV_EEPROM_MEDIA_SIZE Specifies the EEPROM Media size. DRV_EEPROM_SYS_FS_REGISTER Register to use with the File system Description EEPROM Driver Configuration Template Header file. This template file describes all the mandatory and optional configuration macros that are needed for building the EEPROM driver. Do not include this file in source code. File Name drv_eeprom_config_template.h Company Microchip Technology Inc. ENC28J60 Driver Library Help This section provides information on the ENC28J60 Driver Library. Introduction This library provides a driver-level abstraction of the ENC28J60 integrated Ethernet MAC and 10Base-T PHY that can be connected to the PIC32. The driver implements the virtual MAC driver model that the MPLAB Harmony TCP/IP Stack requires. Please see the TCP/IP Stack Library MAC Driver Module for details. The "Host-To-Network"_layer of a TCP/IP stack organization covers the Data Link and Physical Layers of the standard OSI stack. The Ethernet Controller provides the Data Link or Media Access Control Layer, in addition to other functions discussed in this section. Description The ENC28J60 External MAC and PHY is an external module to the PIC32 that is connected through a Serial Peripheral Interface (SPI). This driver interfaces with the SPI driver to communicate with the external device to implement a complete Ethernet node in a system. The following are some of the key features of this module: • Supports 10 Mbps physical-to-physical layer Ethernet data transfer • Full-Duplex and Half-Duplex operation • Broadcast, Multicast and Unicast packets • Hardware flow control for both Full and Half-Duplex mode • Fully configurable interrupts • Configurable receive packet filtering using: • 64-bit Hash Table • 64-byte Pattern Match • Magic Packet™ Filtering • Supports Packet Payload Checksum calculation • CRC Check • Supports SPI interface Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 407 Using the Library This topic describes the basic architecture and functionality of the software driver for the ENC28J60 stand-alone Ethernet Controller with SPI, and is meant for advanced users or TCP/IP stack driver developers. Description The user of this driver is the MPLAB Harmony TCP/IP stack. This Ethernet driver is not intended as a system-wide driver that the application or other system modules may use. It is intended for the sole use of the MPLAB Harmony TCP/IP stack and implements the virtual MAC model required by the stack. Interface Header File: drv_enc28j60.h The interface to the ENC28J60 Driver Library is defined in the drv_enc28j60.h header file. Any C language source (.c) file that uses the ENC28J60 Driver Library should include drv_enc28j60.h. Library File: The ENC28J60 Driver Library archive (.a) file is installed with MPLAB Harmony. Please refer to the Understanding MPLAB Harmony section for how the driver interacts with the framework. Abstraction Model The ENC28J60 Driver Library provides the low-level abstraction of the communications protocol to communicate to the ENC28J60 external MAC though the SPI peripheral 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 ENC28J60 Driver Library interface. Description The ENC28J60 Driver library has several different layers to it, as illustrated in the following figure. The interface layer has two main sections that are used the most often: The Tasks function, and the TCP/IP Send and Receive functions. The Tasks function manages the internal state machine which detects, resets, and then configures the ENC28J60 External MAC. It also handles the monitoring of the hardware status, sending and receiving packets. The TCP/IP Send and Receive functions interact with the RAM-based queue of packets that are queued to send and packets that have been queued waiting for pick-up by the stack. The main state machine does not interface directly to the SPI bus, but instead, interfaces to a virtual bus abstraction layer that allows for the replacement of the specific underlying bus implementation. Abstraction Model Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 408 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The library interface routines are divided into various sub-sections, each sub-section addresses one of the blocks or the overall operation of the ENC28J60 Driver Library. Library Interface Section Description System Interaction Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Data Transfer Functions Provides data transfer functions available in the configuration. Status Functions Provides status functions. Miscellaneous Functions Provides miscellaneous driver functions. How the Library Works The library provides interfaces to support the TCP/IP virtual MAC interface. Configuring the SPI Driver This section describes the configuration settings for the ENC28J60 Driver Library. Description Configuration The ENC hardware requires a specific configuration of the SPI driver to work correctly. Inside the MHC SPI Driver configuration be sure to select: • Run the SPI at frequencies of at least 8 MHz • Clock mode of DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_FALL • Input phase of SPI_INPUT_SAMPLING_PHASE_AT_END Recommended Settings • Interrupt Driver mode • Enhanced Buffer mode • DMA mode enabled: • DMA block transfer size of at least 1600 bytes • Size of DMA buffer for dummy data of at least 1600 bytes • Ensure when setting up DMA in interrupt mode that the DMA interrupts are a higher priority than the SPI Driver interrupt Example: /*** SPI Driver Static Allocation Options ***/ #define DRV_SPI_INSTANCES_NUMBER 1 #define DRV_SPI_CLIENTS_NUMBER 1 #define DRV_SPI_ELEMENTS_PER_QUEUE 30 /*** SPI Driver DMA Options ***/ #define DRV_SPI_DMA_TXFER_SIZE 2048 #define DRV_SPI_DMA_DUMMY_BUFFER_SIZE 2048 /* SPI Driver Instance 0 Configuration */ #define DRV_SPI_SPI_ID_IDX0 SPI_ID_1 #define DRV_SPI_TASK_MODE_IDX0 DRV_SPI_TASK_MODE_ISR #define DRV_SPI_SPI_MODE_IDX0 DRV_SPI_MODE_MASTER #define DRV_SPI_ALLOW_IDLE_RUN_IDX0 false #define DRV_SPI_SPI_PROTOCOL_TYPE_IDX0 DRV_SPI_PROTOCOL_TYPE_STANDARD #define DRV_SPI_SPI_PROTOCOL_TYPE_IDX0 DRV_SPI_PROTOCOL_TYPE_STANDARD #define DRV_SPI_COMM_WIDTH_IDX0 SPI_COMMUNICATION_WIDTH_8BITS #define DRV_SPI_SPI_CLOCK_IDX0 CLK_BUS_PERIPHERAL_2 #define DRV_SPI_BAUD_RATE_IDX0 13333333 #define DRV_SPI_BUFFER_TYPE_IDX0 DRV_SPI_BUFFER_TYPE_ENHANCED #define DRV_SPI_CLOCK_MODE_IDX0 DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_FALL #define DRV_SPI_INPUT_PHASE_IDX0 SPI_INPUT_SAMPLING_PHASE_AT_END #define DRV_SPI_TX_INT_SOURCE_IDX0 INT_SOURCE_SPI_1_TRANSMIT Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 409 #define DRV_SPI_RX_INT_SOURCE_IDX0 INT_SOURCE_SPI_1_RECEIVE #define DRV_SPI_ERROR_INT_SOURCE_IDX0 INT_SOURCE_SPI_1_ERROR #define DRV_SPI_INT_VECTOR_IDX0 INT_VECTOR_SPI1 #define DRV_SPI_INT_PRIORITY_IDX0 INT_PRIORITY_LEVEL1 #define DRV_SPI_INT_SUB_PRIORITY_IDX0 INT_SUBPRIORITY_LEVEL0 #define DRV_SPI_QUEUE_SIZE_IDX0 30 #define DRV_SPI_RESERVED_JOB_IDX0 1 #define DRV_SPI_TX_DMA_CHANNEL_IDX0 DMA_CHANNEL_1 #define DRV_SPI_TX_DMA_THRESHOLD_IDX0 16 #define DRV_SPI_RX_DMA_CHANNEL_IDX0 DMA_CHANNEL_0 #define DRV_SPI_RX_DMA_THRESHOLD_IDX0 16 Driver Library Configuring the Library Macros Name Description DRV_ENC28J60_CLIENT_INSTANCES Selects the maximum number of clients. DRV_ENC28J60_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver. Description The configuration of the ENC28J60 Driver Library is based on the file sys_config.h. This header file contains the configuration selection for the ENC28J60 Driver Library. Based on the selections made, the ENC28J60 Driver Library may support the selected features. These configuration settings will apply to all instances of the ENC28J60 Driver 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. DRV_ENC28J60_CLIENT_INSTANCES Macro Selects the maximum number of clients. File drv_enc28j60_config_template.h C #define DRV_ENC28J60_CLIENT_INSTANCES 1 Description enc28j60 maximum number of clients This definition selects the maximum number of clients that the enc28j60 driver can support at run-time. Remarks Mandatory definition. DRV_ENC28J60_INSTANCES_NUMBER Macro Selects the maximum number of hardware instances that can be supported by the dynamic driver. File drv_enc28j60_config_template.h C #define DRV_ENC28J60_INSTANCES_NUMBER 1 Description enc28j60 hardware instance configuration This definition selects the maximum number of hardware instances that can be supported by the dynamic driver. Remarks Mandatory definition. Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 410 Building the Library This section lists the files that are available in the ENC28J60 Driver Library. 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 /framework/driver/enc28j60. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source Folder Name Description /drv_enc28j60.h This file provides the interface definitions of the ENC28J60 Driver. Required File(s) 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. All of the required files listed in the following table are automatically loaded into the MPLAB X IDE project by the MHC. Source Folder Name Description /src/dynamic/drv_drv_enc28j60_api.c This file contains the API function implementations. /src/dynamic/drv_enc28j60_main_state.c This file contains the main state machine functions. /src/dynamic/drv_enc28j60_utils.c This file contains functions that are used throughout the driver. /src/dynamic/bus/spi/drv_enc28j60_spi_bus.c This file contains the functions to interface with the SPI bus. /src/dynamic/closed_state/drv_enc28j60_closed_state.c This file contains the functions for handling the driver closed state. /src/dynamic/initialization_state/drv_enc28j60_configure_state.c This file contains the functions for configuring the ENC hardware. /src/dynamic/initialization_state/drv_enc28j60_detect_state.c This file contains the functions for detecting the ENC hardware. /src/dynamic/initialization_state/drv_enc28j60_initialization_state.c This file contains the functions for the initialization state machine. /src/dynamic/initialization_state/drv_enc28j60_reset_state.c This file contains the functions for resetting the ENC hardware. /src/dynamic/packet/drv_enc28j60_rx_packet.c This file contains the functions for receiving a packet from the ENC hardware. /src/dynamic/packet/drv_enc28j60_tx_packet.c This file contains the functions for sending a packet to the ENC hardware. /src/dynamic/running_state/drv_enc28j60_change_duplex_state.c This file contains the functions for configuring the duplex mode of the ENC hardware. /src/dynamic/running_state/drv_enc28j60_check_int_state.c This file contains the functions for checking and processing the ENC hardware interrupts. /src/dynamic/running_state/drv_enc28j60_check_status_state.c This file contains the functions for checking the status of the ENC hardware. /src/dynamic/running_state/drv_enc28j60_check_tx_status_state.c This file contains the functions for checking the status of a transmitted packet. /src/dynamic/running_state/drv_enc28j60_running_state.c This file contains the functions for managing the running state machine. /src/dynamic/running_state/drv_enc28j60_reset_rx_state.c This file contains the functions for managing the RX state machine reset requirement during run-time. Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 411 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 Folder Name Description N/A No optional files exist for this library. Module Dependencies The ENC28J60 Driver Library depends on the following modules: • SPI Driver Library • TCP/IP Stack Library • TCP/IP Stack MAC Driver Module Library Interface a) System Interaction Functions Name Description DRV_ENC28J60_Deinitialize Deinitializes the ENC28J60 Driver Instance. Implementation: Dynamic DRV_ENC28J60_Initialize Initializes the ENC28J60 Driver Instance, with the configuration data. Implementation: Dynamic DRV_ENC28J60_Process Additional processing that happens outside the tasks function. Implementation: Dynamic DRV_ENC28J60_Reinitialize Reinitializes the instance of the ENC28J60 driver. Implementation: Dynamic DRV_ENC28J60_SetMacCtrlInfo This function sets the MAC control information for the driver. Implementation: Dynamic DRV_ENC28J60_StackInitialize This function initializes the driver with a TCPIP_MAC_INIT object. Implementation: Dynamic DRV_ENC28J60_Tasks Main task function for the driver. Implementation: Dynamic b) Client Level Functions Name Description DRV_ENC28J60_Close Closes a client handle to the driver. Implementation: Dynamic DRV_ENC28J60_ConfigGet Gets the current configuration. Implementation: Dynamic DRV_ENC28J60_LinkCheck This function returns the status of the link. Implementation: Dynamic DRV_ENC28J60_Open This function is called by the client to open a handle to a driver instance. Implementation: Dynamic DRV_ENC28J60_ParametersGet Get the parameters of the device. Implementation: Dynamic DRV_ENC28J60_PowerMode This function sets the power mode of the device. Implementation: Dynamic DRV_ENC28J60_RegisterStatisticsGet Get the register statistics. Implementation: Dynamic DRV_ENC28J60_StatisticsGet Retrieve the devices statistics. Implementation: Dynamic DRV_ENC28J60_Status Gets the current status of the driver. Implementation: Dynamic c) Receive Functions Name Description DRV_ENC28J60_PacketRx Receive a packet from the driver. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 412 DRV_ENC28J60_RxFilterHashTableEntrySet This function adds an entry to the hash table. Implementation: Dynamic d) Transmit Functions Name Description DRV_ENC28J60_PacketTx This function queues a packet for transmission. Implementation: Dynamic e) Event Functions Name Description DRV_ENC28J60_EventAcknowledge Acknowledges an event. Implementation: Dynamic DRV_ENC28J60_EventMaskSet Sets the event mask. Implementation: Dynamic DRV_ENC28J60_EventPendingGet Gets the current events. Implementation: Dynamic f) Data Types and Constants Name Description _DRV_ENC28J60_Configuration Defines the data required to initialize or reinitialize the ENC28J60 Driver. DRV_ENC28J60_Configuration Defines the data required to initialize or reinitialize the ENC28J60 Driver. DRV_ENC28J60_MDIX_TYPE Defines the enumeration for controlling the MDIX select. DRV_ENC28J60_MACObject ENC28J60 External MAC Virtualization Table Description This section describes the Application Programming Interface (API) functions of the ENC28J60 Driver Library. Refer to each section for a detailed description. a) System Interaction Functions DRV_ENC28J60_Deinitialize Function Deinitializes the ENC28J60 Driver Instance. Implementation: Dynamic File drv_enc28j60.h C void DRV_ENC28J60_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description ENC28J60 Deinitialization This function deallocates any resources allocated by the initialization function. Preconditions The driver had to be successfully initialized with DRV_ENC28J60_Initialize. Parameters Parameters Description Object the valid object returned from DRV_ENC28J60_Initialize Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 413 DRV_ENC28J60_Initialize Function Initializes the ENC28J60 Driver Instance, with the configuration data. Implementation: Dynamic File drv_enc28j60.h C SYS_MODULE_OBJ DRV_ENC28J60_Initialize(SYS_MODULE_INDEX index, SYS_MODULE_INIT * init); Returns • Valid handle to the driver instance - If successful • SYS_MODULE_OBJ_INVALID - If unsuccessful Description ENC28J60 Initialization This function initializes the ENC28J60 Driver with configuration data passed into it by either the system_init function or by the DRV_ENC28J60_StackInitialize function. Calling this function alone is not enough to initialize the driver, DRV_ENC28J60_SetMacCtrlInfo must be called with valid data before the driver is ready to be opened. Preconditions None. Parameters Parameters Description index This is the index of the driver instance to be initialized. The definition DRV_ENC28J60_NUM_DRV_INSTANCES controls how many instances are available. init This is a pointer to a DRV_ENC28J60_CONFIG structure. DRV_ENC28J60_Process Function Additional processing that happens outside the tasks function. Implementation: Dynamic File drv_enc28j60.h C TCPIP_MAC_RES DRV_ENC28J60_Process(DRV_HANDLE hMac); Returns • TCPIP_MAC_RES_TYPE_ERR - if the hMac is invalid • TCPIP_MAC_RES_OP_ERR - if the hMac is valid Description ENC28J60 Process This function does additional processing that is not done inside the tasks function. Remarks This function does nothing in the first release. Preconditions The client had to be successfully opened with DRV_ENC28J60_Open. Parameters Parameters Description hMac the successfully opened handle Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 414 DRV_ENC28J60_Reinitialize Function Reinitializes the instance of the ENC28J60 driver. Implementation: Dynamic File drv_enc28j60.h C void DRV_ENC28J60_Reinitialize(SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init); Returns None Description ENC28J60 Reinitialization This function will deinitialize and initialize the driver instance. As with DRV_ENC28J60_Initialize DRV_ENC28J60_SetMacCtrlInfo must be called for the driver to be useful. Remarks This function is not planned to be implemented for the first release. Preconditions The driver had to be successfully initialized with DRV_ENC28J60_Initialize. DRV_ENC28J60_SetMacCtrlInfo Function This function sets the MAC control information for the driver. Implementation: Dynamic File drv_enc28j60.h C void DRV_ENC28J60_SetMacCtrlInfo(SYS_MODULE_OBJ object, TCPIP_MAC_MODULE_CTRL * init); Returns None. Description ENC28J60 Set MAC Control Information This function is used to pass in the TCPIP_MAC_CONTROL_INIT information that is used for allocation and deallocation of memory, event signaling, etc. This function is needed to be called so that the driver can enter initialization state when the tasks function is called. Preconditions The driver had to be successfully initialized with ENC28J60_Initialize. DRV_ENC28J60_StackInitialize Function This function initializes the driver with a TCPIP_MAC_INIT object. Implementation: Dynamic File drv_enc28j60.h C SYS_MODULE_OBJ DRV_ENC28J60_StackInitialize(SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns Returns a valid handle to the driver instance - If successful SYS_MODULE_OBJ_INVALID - If unsuccessful Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 415 Description ENC28J60 Stack Initialization This function is used by the TCP/IP stack to fully initialize the driver with both the ENC28J60 specific configuration and the MAC control information. With this function there is no need to call DRV_ENC28J60_SetMacCtrlInfo. Preconditions None. Parameters Parameters Description index This is the index of the driver instance to be initialized. The definition DRV_ENC28J60_NUM_DRV_INSTANCES controls how many instances are available. init This is a pointer to a TCPIP_MAC_INIT structure. DRV_ENC28J60_Tasks Function Main task function for the driver. Implementation: Dynamic File drv_enc28j60.h C void DRV_ENC28J60_Tasks(SYS_MODULE_OBJ object); Returns None. Description ENC28J60 Tasks This function will execute the main state machine for the ENC28J60 driver. Preconditions The driver had to be successfully initialized with DRV_ENC28J60_Initialize. Parameters Parameters Description object The object valid passed back to DRV_ENC28J60_Initialize b) Client Level Functions DRV_ENC28J60_Close Function Closes a client handle to the driver. Implementation: Dynamic File drv_enc28j60.h C void DRV_ENC28J60_Close(DRV_HANDLE handle); Returns None. Description ENC28J60 Close This function closes a handle to the driver. If it is the last client open, the driver will send an RX Disable command to the ENC hardware and move Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 416 to the closed state. Preconditions The client had to be successfully opened with DRV_ENC28J60_Open. Parameters Parameters Description handle The successfully opened handle DRV_ENC28J60_ConfigGet Function Gets the current configuration. Implementation: Dynamic File drv_enc28j60.h C size_t DRV_ENC28J60_ConfigGet(DRV_HANDLE hMac, void* configBuff, size_t buffSize, size_t* pConfigSize); Returns Number of bytes copied to the buffer Description ENC28J60 Get Configuration Gets the current configuration. Remarks This function does nothing in the first release. Preconditions The client had to be successfully opened with DRV_ENC28J60_Open. Parameters Parameters Description hMac the successfully opened handle configBuff location to copy the configuration too buffSize buffer size pConfigSize configuration size needed DRV_ENC28J60_LinkCheck Function This function returns the status of the link. Implementation: Dynamic File drv_enc28j60.h C bool DRV_ENC28J60_LinkCheck(DRV_HANDLE hMac); Returns • true - if the link is active • false - all other times Description ENC28J60 Link Check This function checks the status of the link and returns it to the caller. Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 417 Preconditions The client had to be successfully opened with DRV_ENC28J60_Open. Parameters Parameters Description hMac the successfully opened handle DRV_ENC28J60_Open Function This function is called by the client to open a handle to a driver instance. Implementation: Dynamic File drv_enc28j60.h C DRV_HANDLE DRV_ENC28J60_Open(SYS_MODULE_INDEX index, DRV_IO_INTENT intent); Returns Returns a valid handle - If successful INVALID_HANDLE - If unsuccessful Description ENC28J60 Open The client will call this function to open a handle to the driver. When the first instance is opened than the driver will send the RX enabled command to the ENC hardware. Preconditions The driver had to be successfully initialized with DRV_ENC28J60_Initialize. Parameters Parameters Description index This is the index of the driver instance to be initialized. The definition DRV_ENC28J60_NUM_DRV_INSTANCES controls how many instances are available. intent The intent to use when opening the driver. Only exclusive is supported DRV_ENC28J60_ParametersGet Function Get the parameters of the device. Implementation: Dynamic File drv_enc28j60.h C TCPIP_MAC_RES DRV_ENC28J60_ParametersGet(DRV_HANDLE hMac, TCPIP_MAC_PARAMETERS* pMacParams); Returns • TCPIP_MAC_RES_TYPE_ERR - if the hMac is invalid • TCPIP_MAC_RES_OK - if the hMac is valid Description ENC28J60 Get Parameters Get the parameters of the device, which includes that it is an Ethernet device and what it's MAC address is. Users of the ENC28J60 must generate a unique MAC address for each controller used. The client had to be successfully opened with DRV_ENC28J60_Open. Parameters Parameters Description hMac the successfully opened handle Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 418 pMacParams pointer to put the parameters DRV_ENC28J60_PowerMode Function This function sets the power mode of the device. Implementation: Dynamic File drv_enc28j60.h C bool DRV_ENC28J60_PowerMode(DRV_HANDLE hMac, TCPIP_MAC_POWER_MODE pwrMode); Returns • false - This functionality is not supported in this version of the driver Description ENC28J60 Power Mode This function sets the power mode of the ENC28J60. Remarks This functionality is not implemented in the first release. Preconditions The client had to be successfully opened with DRV_ENC28J60_Open. Parameters Parameters Description hMac the successfully opened handle pwrMode the power mode to set DRV_ENC28J60_RegisterStatisticsGet Function Get the register statistics. Implementation: Dynamic File drv_enc28j60.h C TCPIP_MAC_RES DRV_ENC28J60_RegisterStatisticsGet(DRV_HANDLE hMac, TCPIP_MAC_STATISTICS_REG_ENTRY* pRegEntries, int nEntries, int* pHwEntries); Returns • TCPIP_MAC_RES_TYPE_ERR - if the hMac is invalid • TCPIP_MAC_RES_OP_ERR - if the hMac is valid Description ENC28J60 Get Register Statistics Get the device specific statistics. Remarks Statistics are not planned for the first release Preconditions The client had to be successfully opened with DRV_ENC28J60_Open. Parameters Parameters Description hMac the successfully opened handle Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 419 pRegEntries nEntries pHwEntries DRV_ENC28J60_StatisticsGet Function Retrieve the devices statistics. Implementation: Dynamic File drv_enc28j60.h C TCPIP_MAC_RES DRV_ENC28J60_StatisticsGet(DRV_HANDLE hMac, TCPIP_MAC_RX_STATISTICS* pRxStatistics, TCPIP_MAC_TX_STATISTICS* pTxStatistics); Returns • TCPIP_MAC_RES_TYPE_ERR - if the hMac is invalid • TCPIP_MAC_RES_OP_ERR - if the hMac is valid Description ENC28J60 Get Statistics Get the current statistics stored in the driver. Remarks Statistics are not planned for the first release. Preconditions The client had to be successfully opened with DRV_ENC28J60_Open. Parameters Parameters Description hMac the successfully opened handle DRV_ENC28J60_Status Function Gets the current status of the driver. Implementation: Dynamic File drv_enc28j60.h C SYS_STATUS DRV_ENC28J60_Status(SYS_MODULE_OBJ obect); Returns • SYS_STATUS_ERROR - if an invalid handle has been passed in • SYS_STATUS_UNINITIALIZED - if the driver has not completed initialization • SYS_STATUS_BUSY - if the driver is closing and moving to the closed state • SYS_STATUS_READY - if the driver is ready for client commands Description ENC28J60 Status This function will get the status of the driver instance. Preconditions The driver had to be successfully initialized with DRV_ENC28J60_Initialize(). Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 420 Parameters Parameters Description object The object valid passed back to DRV_ENC28J60_Initialize() c) Receive Functions DRV_ENC28J60_PacketRx Function Receive a packet from the driver. Implementation: Dynamic File drv_enc28j60.h C TCPIP_MAC_PACKET* DRV_ENC28J60_PacketRx(DRV_HANDLE hMac, TCPIP_MAC_RES* pRes, const TCPIP_MAC_PACKET_RX_STAT** ppPktStat); Returns • Pointer to a valid packet - if successful • NULL - if unsuccessful Description ENC28J60 Receive Packet This function retrieves a packet from the driver. The packet needs to be acknowledged with the linked acknowledge function so it can be reused. Remarks ppPktStat is ignored in the first release. Preconditions The client had to be successfully opened with DRV_ENC28J60_Open. Parameters Parameters Description hMac the successfully opened handle pRes the result of the operation ppPktStat pointer to the receive statistics DRV_ENC28J60_RxFilterHashTableEntrySet Function This function adds an entry to the hash table. Implementation: Dynamic File drv_enc28j60.h C TCPIP_MAC_RES DRV_ENC28J60_RxFilterHashTableEntrySet(DRV_HANDLE hMac, const TCPIP_MAC_ADDR* DestMACAddr); Returns • TCPIP_MAC_RES_TYPE_ERR - if the hMac is invalid • TCPIP_MAC_RES_OP_ERR - if the hMac is valid Description ENC28J60 Receive Filter Hash Table Entry Set This function adds to the MAC's hash table for hash table matching. Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 421 Remarks This functionality is not implemented in the first release. Preconditions The client had to be successfully opened with DRV_ENC28J60_Open. Parameters Parameters Description hMac the successfully opened handle DestMACAddr MAC address to add to the hash table d) Transmit Functions DRV_ENC28J60_PacketTx Function This function queues a packet for transmission. Implementation: Dynamic File drv_enc28j60.h C TCPIP_MAC_RES DRV_ENC28J60_PacketTx(DRV_HANDLE hMac, TCPIP_MAC_PACKET * ptrPacket); Returns • TCPIP_MAC_RES_OP_ERR - if the client handle is invalid • TCPIP_MAC_RES_IS_BUSY - if the driver is not in the run state • TCPIP_MAC_RES_QUEUE_TX_FULL - if there are no free descriptors • TCPIP_MAC_RES_OK - on successful queuing of the packet Description ENC28J60 Packet Transmit This function will take a packet and add it to the queue for transmission. When the packet has finished transmitting the driver will call the packets acknowledge function. When that acknowledge function is complete the driver will forget about the packet. Preconditions The client had to be successfully opened with DRV_ENC28J60_Open. Parameters Parameters Description hMac the successfully opened handle ptrPacket pointer to the packet e) Event Functions DRV_ENC28J60_EventAcknowledge Function Acknowledges an event. Implementation: Dynamic File drv_enc28j60.h C bool DRV_ENC28J60_EventAcknowledge(DRV_HANDLE hMac, TCPIP_MAC_EVENT macEvents); Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 422 Returns • true - if successful • false - if not successful Description ENC28J60 Acknowledge Event This function acknowledges an event. Preconditions The client had to be successfully opened with DRV_ENC28J60_Open. Parameters Parameters Description hMac the successfully opened handle macEvents the events to acknowledge DRV_ENC28J60_EventMaskSet Function Sets the event mask. Implementation: Dynamic File drv_enc28j60.h C bool DRV_ENC28J60_EventMaskSet(DRV_HANDLE hMac, TCPIP_MAC_EVENT macEvents, bool enable); Returns • true - if the mask could be set • false - if the mast could not be set Description ENC28J60 Set Event Mask Sets the event mask to what is passed in. Preconditions The client had to be successfully opened with DRV_ENC28J60_Open. Parameters Parameters Description hMac the successfully opened handle macEvents the mask to enable or disable enable to enable or disable events DRV_ENC28J60_EventPendingGet Function Gets the current events. Implementation: Dynamic File drv_enc28j60.h C TCPIP_MAC_EVENT DRV_ENC28J60_EventPendingGet(DRV_HANDLE hMac); Returns • TCPIP_MAC_EV_NONE - Returned on an error • List of events - Returned on event other than an error Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 423 Description ENC28J60 Get Events This function gets the current events. Preconditions The client had to be successfully opened with DRV_ENC28J60_Open. Parameters Parameters Description hMac the successfully opened handle f) Data Types and Constants DRV_ENC28J60_Configuration Structure Defines the data required to initialize or reinitialize the ENC28J60 Driver. File drv_enc28j60.h C typedef struct _DRV_ENC28J60_Configuration { uint16_t txDescriptors; uint16_t rxDescriptors; uint16_t rxDescBufferSize; SYS_MODULE_INDEX spiDrvIndex; uint32_t spiBps; uint16_t rxBufferSize; uint16_t maxFrameSize; PORTS_MODULE_ID spiSSPortModule; PORTS_CHANNEL spiSSPortChannel; PORTS_BIT_POS spiSSPortPin; bool intEnable; PORTS_MODULE_ID intPortModule; PORTS_CHANNEL intPortChannel; PORTS_BIT_POS intPortPin; DRV_ENC28J60_MDIX_TYPE mdixControl; PORTS_MODULE_ID mdixPortModule; PORTS_CHANNEL mdixPortChannel; PORTS_BIT_POS mdixPortPin; } DRV_ENC28J60_Configuration; Members Members Description uint16_t txDescriptors; Number of TX Descriptors to Allocate uint16_t rxDescriptors; Number of RX Descriptors to Allocate uint16_t rxDescBufferSize; Size of the buffer each RX Descriptor will use. Make sure its not smaller than maxFrameSize SYS_MODULE_INDEX spiDrvIndex; Index of the SPI driver to use uint32_t spiBps; Bus speed to use for the SPI interface. Section 1.0 of the ENC28J60 data sheets says the maximum is 20000000 Hz. It is not recommended to go above this value. uint16_t rxBufferSize; The ENC28J60 hardware has a 8 k dram. rxBufferSize defines how much of that memory is used by the rxBuffer uint16_t maxFrameSize; The maximum frame size to be supported by the hardware. 1536 is the default PORTS_MODULE_ID spiSSPortModule; Port Module of the GPIO pin hooked up to the CS/SS pin of the ENC28J60 PORTS_CHANNEL spiSSPortChannel; Port Channel of the GPIO pin hooked up to the CS/SS pin of the ENC28J60 PORTS_BIT_POS spiSSPortPin; Pin position of the GPIO pin hooked up to the CS/SS pin of the ENC28J60 bool intEnable; Use Interrupts or not. PORTS_MODULE_ID intPortModule; Port Module of the GPIO pin hooked up to the INT pin of the ENC28J60 PORTS_CHANNEL intPortChannel; Port Channel of the GPIO pin hooked up to the INT pin of the ENC28J60 PORTS_BIT_POS intPortPin; Pin Position of the GPIO pin hooked up to the INT pin of the ENC28J60 Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 424 DRV_ENC28J60_MDIX_TYPE mdixControl; To select the control type of the MDIX. This is only needed for hooking up to switches that don't have auto-mdix. PORTS_MODULE_ID mdixPortModule; Port Module of the GPIO pin hooked up to the MDIX select pin PORTS_CHANNEL mdixPortChannel; Port Channel of the GPIO pin hooked up to the MDIX select pin PORTS_BIT_POS mdixPortPin; Pin Position of the GPIO pin hooked up to the MDIX select pin Description ENC28J60 Driver Initialization Data This data type defines the data required to initialize or reinitialize the ENC28J60 driver. If the driver is built statically, the members of this data structure are statically over-ridden by static override definitions in the system_config.h file. Remarks None. DRV_ENC28J60_MDIX_TYPE Enumeration Defines the enumeration for controlling the MDIX select. File drv_enc28j60.h C typedef enum { DRV_ENC28J60_NO_CONTROL = 0, DRV_ENC28J60_NORMAL, DRV_ENC28J60_REVERSE = 0 } DRV_ENC28J60_MDIX_TYPE; Members Members Description DRV_ENC28J60_NO_CONTROL = 0 No Control DRV_ENC28J60_NORMAL Normal MDIX DRV_ENC28J60_REVERSE = 0 Reverse MDIX Description ENC28J60 Driver MDIX Control type This type defines the enumeration for controlling the MDIX select. Remarks None. DRV_ENC28J60_MACObject Variable File drv_enc28j60.h C const TCPIP_MAC_OBJECT DRV_ENC28J60_MACObject; Description ENC28J60 External MAC Virtualization Table Files Files Name Description drv_enc28j60.h ENC28J60 Driver interface definition. drv_enc28j60_config_template.h enc28j60 Driver configuration definitions template. Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 425 Description drv_enc28j60.h ENC28J60 Driver interface definition. Enumerations Name Description DRV_ENC28J60_MDIX_TYPE Defines the enumeration for controlling the MDIX select. Functions Name Description DRV_ENC28J60_Close Closes a client handle to the driver. Implementation: Dynamic DRV_ENC28J60_ConfigGet Gets the current configuration. Implementation: Dynamic DRV_ENC28J60_Deinitialize Deinitializes the ENC28J60 Driver Instance. Implementation: Dynamic DRV_ENC28J60_EventAcknowledge Acknowledges an event. Implementation: Dynamic DRV_ENC28J60_EventMaskSet Sets the event mask. Implementation: Dynamic DRV_ENC28J60_EventPendingGet Gets the current events. Implementation: Dynamic DRV_ENC28J60_Initialize Initializes the ENC28J60 Driver Instance, with the configuration data. Implementation: Dynamic DRV_ENC28J60_LinkCheck This function returns the status of the link. Implementation: Dynamic DRV_ENC28J60_Open This function is called by the client to open a handle to a driver instance. Implementation: Dynamic DRV_ENC28J60_PacketRx Receive a packet from the driver. Implementation: Dynamic DRV_ENC28J60_PacketTx This function queues a packet for transmission. Implementation: Dynamic DRV_ENC28J60_ParametersGet Get the parameters of the device. Implementation: Dynamic DRV_ENC28J60_PowerMode This function sets the power mode of the device. Implementation: Dynamic DRV_ENC28J60_Process Additional processing that happens outside the tasks function. Implementation: Dynamic DRV_ENC28J60_RegisterStatisticsGet Get the register statistics. Implementation: Dynamic DRV_ENC28J60_Reinitialize Reinitializes the instance of the ENC28J60 driver. Implementation: Dynamic DRV_ENC28J60_RxFilterHashTableEntrySet This function adds an entry to the hash table. Implementation: Dynamic DRV_ENC28J60_SetMacCtrlInfo This function sets the MAC control information for the driver. Implementation: Dynamic DRV_ENC28J60_StackInitialize This function initializes the driver with a TCPIP_MAC_INIT object. Implementation: Dynamic DRV_ENC28J60_StatisticsGet Retrieve the devices statistics. Implementation: Dynamic DRV_ENC28J60_Status Gets the current status of the driver. Implementation: Dynamic DRV_ENC28J60_Tasks Main task function for the driver. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help ENC28J60 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 426 Structures Name Description _DRV_ENC28J60_Configuration Defines the data required to initialize or reinitialize the ENC28J60 Driver. DRV_ENC28J60_Configuration Defines the data required to initialize or reinitialize the ENC28J60 Driver. Variables Name Description DRV_ENC28J60_MACObject ENC28J60 External MAC Virtualization Table Description ENC28J60 Driver Public Interface This file defines the interface definition for the ENC28J60 Driver. File Name drv_enc28j60.h Company Microchip Technology Inc. drv_enc28j60_config_template.h enc28j60 Driver configuration definitions template. Macros Name Description DRV_ENC28J60_CLIENT_INSTANCES Selects the maximum number of clients. DRV_ENC28J60_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver. Description enc28j60 Driver Configuration Definitions for the Template Version These definitions statically define the driver's mode of operation. File Name drv_enc28j60_config_template.h Company Microchip Technology Inc. ENCx24J600 Driver Library Help This section provides information on the ENCx24J600 Driver Library. Introduction This library provides a driver-level abstraction of the ENCx24J600 Ethernet MAC that can be connected to the PIC32. The driver implements the virtual MAC driver model that the MPLAB Harmony TCP/IP Stack requires. Please see the TCP/IP Stack Library MAC Driver Module for details. The "Host-To-Network"_layer of a TCP/IP stack organization covers the Data Link and Physical Layers of the standard OSI stack. The Ethernet Controller provides the Data Link or Media Access Control Layer, in addition to other functions discussed in this section. Description The ENCx24J600 External MAC is an external module to the PIC32 that is connected through a SPI or PSP interface. This driver interfaces with the SPI driver to communicate with the external device to implement a complete Ethernet node in a system. The following are some of the key features of this module: • Supports 10/100 Ethernet • Full-Duplex and Half-Duplex operation • Broadcast, Multicast and Unicast packets • Manual and automatic flow control • Supports Auto-MDIX Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 427 • Fully configurable interrupts • Configurable receive packet filtering using: • 64-bit Hash Table • 64-byte Pattern Match • Magic Packet™ Filtering • Runt Packet Detection and Filtering • Supports Packet Payload Checksum calculation • CRC Check • Supports SPI interface Using the Library This topic describes the basic architecture and functionality of the Ethernet MAC driver and is meant for advanced users or TCP/IP stack driver developers. Description The user of this driver is the MPLAB Harmony TCP/IP stack. This Ethernet driver is not intended as a system-wide driver that the application or other system modules may use. It is intended for the sole use of the MPLAB Harmony TCP/IP stack and implements the virtual MAC model required by the stack. Interface Header File: drv_encx24j600.h The interface to the ENCx24J600 Driver Library is defined in the drv_encx24j600.h header file. Any C language source (.c) file that uses the ENCx24J600 Driver Library should include drv_encx24j600.h. Library File: The ENCx24J600 Driver Library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model The ENCx24J600 Driver Library provides the low-level abstraction of the communications protocol to communicate to the ENCx24J600 external MAC though the SPI peripheral 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 ENCx24J600 Driver Library interface. Description The ENCx24J600 Driver library has several different layers to it, as illustrated in the following figure. The interface layer has two main sections that are used the most often: The Tasks function, and the TCP/IP Send and Receive functions. The Tasks function manages the internal state machine which detects, resets, and then configures the ENCx24J600 External MAC. It also handles the monitoring of the hardware status, sending and receiving packets. The TCP/IP Send and Receive functions interact with the RAM-based queue of packets that are queued to send and packets that have been queued waiting for pick-up by the stack. The main state machine does not interface directly to the SPI bus, but instead, interfaces to a virtual bus abstraction layer that allows for the replacement of the specific underlying bus implementation. Abstraction Model Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 428 Library Overview Refer to the section Driver Overview for how the driver operates in a system. The library interface routines are divided into various sub-sections, each sub-section addresses one of the blocks or the overall operation of the ENCx24J600 Driver Library. Library Interface Section Description System Interaction Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Data Transfer Functions Provides data transfer functions available in the configuration. Status Functions Provides status functions. Miscellaneous Functions Provides miscellaneous driver functions. How the Library Works The library provides interfaces to support the TCP/IP virtual MAC interface. Configuring the SPI Driver This section describes the configuration settings for the ENCx24J600 Driver Library. Description Configuration The ENC hardware requires a specific configuration of the SPI driver to work correctly. Inside the MHC SPI Driver configuration be sure to select: • SPI clock rate of 14000000 or less. With a PB clock of 80 MHz, 13333333 is the clock rate. • Clock mode of DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_FALL • Input phase of SPI_INPUT_SAMPLING_PHASE_AT_END Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 429 Recommended Settings • Interrupt Driver mode • Enhanced Buffer mode • DMA mode enabled: • DMA block transfer size of at least 1600 bytes • Size of DMA buffer for dummy data of at least 1600 bytes • Ensure when setting up DMA in interrupt mode that the DMA interrupts are a higher priority than the SPI Driver interrupt Example: /*** SPI Driver Static Allocation Options ***/ #define DRV_SPI_INSTANCES_NUMBER 1 #define DRV_SPI_CLIENTS_NUMBER 1 #define DRV_SPI_ELEMENTS_PER_QUEUE 30 /*** SPI Driver DMA Options ***/ #define DRV_SPI_DMA_TXFER_SIZE 2048 #define DRV_SPI_DMA_DUMMY_BUFFER_SIZE 2048 /* SPI Driver Instance 0 Configuration */ #define DRV_SPI_SPI_ID_IDX0 SPI_ID_1 #define DRV_SPI_TASK_MODE_IDX0 DRV_SPI_TASK_MODE_ISR #define DRV_SPI_SPI_MODE_IDX0 DRV_SPI_MODE_MASTER #define DRV_SPI_ALLOW_IDLE_RUN_IDX0 false #define DRV_SPI_SPI_PROTOCOL_TYPE_IDX0 DRV_SPI_PROTOCOL_TYPE_STANDARD #define DRV_SPI_SPI_PROTOCOL_TYPE_IDX0 DRV_SPI_PROTOCOL_TYPE_STANDARD #define DRV_SPI_COMM_WIDTH_IDX0 SPI_COMMUNICATION_WIDTH_8BITS #define DRV_SPI_SPI_CLOCK_IDX0 CLK_BUS_PERIPHERAL_2 #define DRV_SPI_BAUD_RATE_IDX0 13333333 #define DRV_SPI_BUFFER_TYPE_IDX0 DRV_SPI_BUFFER_TYPE_ENHANCED #define DRV_SPI_CLOCK_MODE_IDX0 DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_FALL #define DRV_SPI_INPUT_PHASE_IDX0 SPI_INPUT_SAMPLING_PHASE_AT_END #define DRV_SPI_TX_INT_SOURCE_IDX0 INT_SOURCE_SPI_1_TRANSMIT #define DRV_SPI_RX_INT_SOURCE_IDX0 INT_SOURCE_SPI_1_RECEIVE #define DRV_SPI_ERROR_INT_SOURCE_IDX0 INT_SOURCE_SPI_1_ERROR #define DRV_SPI_INT_VECTOR_IDX0 INT_VECTOR_SPI1 #define DRV_SPI_INT_PRIORITY_IDX0 INT_PRIORITY_LEVEL1 #define DRV_SPI_INT_SUB_PRIORITY_IDX0 INT_SUBPRIORITY_LEVEL0 #define DRV_SPI_QUEUE_SIZE_IDX0 30 #define DRV_SPI_RESERVED_JOB_IDX0 1 #define DRV_SPI_TX_DMA_CHANNEL_IDX0 DMA_CHANNEL_1 #define DRV_SPI_TX_DMA_THRESHOLD_IDX0 16 #define DRV_SPI_RX_DMA_CHANNEL_IDX0 DMA_CHANNEL_0 #define DRV_SPI_RX_DMA_THRESHOLD_IDX0 16 Driver Library Configuring the Library The configuration of the ENCx24J600 Driver Library is based on the file sys_config.h. This header file contains the configuration selection for the ENCX24J600 Driver Library. Based on the selections made, the ENCx24J600 Driver Library may support the selected features. These configuration settings will apply to all instances of the ENCx24J600 Driver 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 in the ENCx24J600 Driver Library. 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 /framework/driver/encx24j600. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 430 Source Folder Name Description /drv_encx24j600.h This file provides the interface definitions of the ENCx24J600 Driver. Required File(s) 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. 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. Source Folder Name Description /src/dynamic/drv_drv_encx24J600_api.c This file contains the API function implementations. /src/dynamic/drv_encx24J600_main_state.c This file contains the main state machine functions. /src/dynamic/drv_encx24J600_utils.c This file contains functions that are used throughout the driver. /src/dynamic/bus/spi/drv_encx24J600_spi_bus.c This file contains the functions to interface with the SPI bus. /src/dynamic/closed_state/drv_encx24J600_closed_state.c This file contains the functions for handling the driver closed state. /src/dynamic/initialization_state/drv_encx24J600_configure_state.c This file contains the functions for configuring the ENC hardware. /src/dynamic/initialization_state/drv_encx24J600_detect_state.c This file contains the functions for detecting the ENC hardware. /src/dynamic/initialization_state/drv_encx24J600_initialization_state.c This file contains the functions for the initialization state machine. /src/dynamic/initialization_state/drv_encx24J600_reset_state.c This file contains the functions for resetting the ENC hardware. /src/dynamic/packet/drv_encx24J600_rx_packet.c This file contains the functions for receiving a packet from the ENC hardware. /src/dynamic/packet/drv_encx24J600_tx_packet.c This file contains the functions for sending a packet to the ENC hardware. /src/dynamic/running_state/drv_encx24J600_change_duplex_state.c This file contains the functions for configuring the duplex mode of the ENC hardware. /src/dynamic/running_state/drv_encx24J600_check_int_state.c This file contains the functions for checking and processing the ENC hardware interrupts. /src/dynamic/running_state/drv_encx24J600_check_status_state.c This file contains the functions for checking the status of the ENC hardware. /src/dynamic/running_state/drv_encx24J600_check_tx_status_state.c This file contains the functions for checking the status of a transmitted packet. /src/dynamic/running_state/drv_encx24J600_running_state.c This file contains the functions for managing the running state machine. 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 Folder Name Description N/A No optional files exist for this library. Module Dependencies The ENCx24J600 Driver Library depends on the following modules: • SPI Driver Library • TCP/IP Stack Library • TCP/IP Stack MAC Driver Module Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 431 Library Interface a) System Interaction Functions Name Description DRV_ENCX24J600_Deinitialize Deinitializes the ENCx24J600 Driver Instance. Implementation: Dynamic DRV_ENCX24J600_Initialize Initializes the ENCx24J600 Driver Instance, with the configuration data. Implementation: Dynamic DRV_ENCX24J600_Reinitialize Reinitializes the instance of the ENCX24J600 driver. Implementation: Dynamic DRV_ENCX24J600_Tasks Main task function for the driver. Implementation: Dynamic DRV_ENCX24J600_SetMacCtrlInfo This function sets the MAC control information for the driver. Implementation: Dynamic DRV_ENCX24J600_StackInitialize This function initializes the driver with a TCPIP_MAC_INIT object. Implementation: Dynamic DRV_ENCX24J600_Process Additional processing that happens outside the tasks function. Implementation: Dynamic b) Client Level Functions Name Description DRV_ENCX24J600_Close Closes a client handle to the driver. Implementation: Dynamic DRV_ENCX24J600_ConfigGet Gets the current configuration. Implementation: Dynamic DRV_ENCX24J600_LinkCheck This function returns the status of the link. Implementation: Dynamic DRV_ENCX24J600_Open This function is called by the client to open a handle to a driver instance. Implementation: Dynamic DRV_ENCX24J600_ParametersGet Get the parameters of the device. Implementation: Dynamic DRV_ENCX24J600_PowerMode This function sets the power mode of the device. Implementation: Dynamic DRV_ENCX24J600_RegisterStatisticsGet Get the register statistics. Implementation: Dynamic DRV_ENCX24J600_StatisticsGet Retrieve the devices statistics. Implementation: Dynamic DRV_ENCX24J600_Status Gets the current status of the driver. Implementation: Dynamic c) Receive Functions Name Description DRV_ENCX24J600_PacketRx Receive a packet from the driver. Implementation: Dynamic DRV_ENCX24J600_RxFilterHashTableEntrySet This function adds an entry to the hash table. Implementation: Dynamic d) Transmit Functions Name Description DRV_ENCX24J600_PacketTx This function queues a packet for transmission. Implementation: Dynamic e) Event Functions Name Description DRV_ENCX24J600_EventAcknowledge Acknowledges an event. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 432 DRV_ENCX24J600_EventMaskSet Sets the event mask. Implementation: Dynamic DRV_ENCX24J600_EventPendingGet Gets the current events. Implementation: Dynamic f) Data Types and Constants Name Description _DRV_ENCX24J600_Configuration Defines the data required to initialize or reinitialize the ENCX24J600 Driver. DRV_ENCX24J600_Configuration Defines the data required to initialize or reinitialize the ENCX24J600 Driver. DRV_ENCX24J600_MDIX_TYPE Defines the enumeration for controlling the MDIX select. Description This section describes the Application Programming Interface (API) functions of the ENCx24J600 Driver Library. Refer to each section for a detailed description. a) System Interaction Functions DRV_ENCX24J600_Deinitialize Function Deinitializes the ENCx24J600 Driver Instance. Implementation: Dynamic File drv_encx24j600.h C void DRV_ENCX24J600_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description ENCX24J600 Deinitialization This function deallocates any resources allocated by the initialization function. Preconditions The driver had to be successfully initialized with DRV_ENCX24J600_Initialize. Parameters Parameters Description Object the valid object returned from DRV_ENCX24J600_Initialize DRV_ENCX24J600_Initialize Function Initializes the ENCx24J600 Driver Instance, with the configuration data. Implementation: Dynamic File drv_encx24j600.h C SYS_MODULE_OBJ DRV_ENCX24J600_Initialize(SYS_MODULE_INDEX index, SYS_MODULE_INIT * init); Returns • Valid handle to the driver instance - If successful • SYS_MODULE_OBJ_INVALID - If unsuccessful Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 433 Description ENCX24J600 Initialization This function initializes the ENCx24J600 Driver with configuration data passed into it by either the system_init function or by the DRV_ENCX24J600_StackInitialize function. Calling this function alone is not enough to initialize the driver, DRV_ENCX24J600_SetMacCtrlInfo must be called with valid data before the driver is ready to be opened. Preconditions None. Parameters Parameters Description index This is the index of the driver instance to be initialized. The definition DRV_ENCX24J600_NUM_DRV_INSTANCES controls how many instances are available. init This is a pointer to a DRV_ENX24J600_CONFIG structure. DRV_ENCX24J600_Reinitialize Function Reinitializes the instance of the ENCX24J600 driver. Implementation: Dynamic File drv_encx24j600.h C void DRV_ENCX24J600_Reinitialize(SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init); Returns None Description ENCX24J600 Reinitialization This function will deinitialize and initialize the driver instance. As with DRV_ENCX24J600_Initialize DRV_ENCX24J600_SetMacCtrlInfo must be called for the driver to be useful. Remarks This function is not planned to be implemented for the first release. Preconditions The driver had to be successfully initialized with DRV_ENCX24J600_Initialize. DRV_ENCX24J600_Tasks Function Main task function for the driver. Implementation: Dynamic File drv_encx24j600.h C void DRV_ENCX24J600_Tasks(SYS_MODULE_OBJ object); Returns None. Description ENCX24J600 Tasks This function will execute the main state machine for the ENCX24J600 driver. Preconditions The driver had to be successfully initialized with DRV_ENCX24J600_Initialize. Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 434 Parameters Parameters Description object The object valid passed back to DRV_ENCX24J600_Initialize DRV_ENCX24J600_SetMacCtrlInfo Function This function sets the MAC control information for the driver. Implementation: Dynamic File drv_encx24j600.h C void DRV_ENCX24J600_SetMacCtrlInfo(SYS_MODULE_OBJ object, TCPIP_MAC_MODULE_CTRL * init); Returns None. Description ENCX24J600 Set MAC Control Information This function is used to pass in the TCPIP_MAC_CONTROL_INIT information that is used for allocation and deallocation of memory, event signaling, etc. This function is needed to be called so that the driver can enter initialization state when the tasks function is called. Preconditions The driver had to be successfully initialized with DRV_ENCX24J600_Initialize. DRV_ENCX24J600_StackInitialize Function This function initializes the driver with a TCPIP_MAC_INIT object. Implementation: Dynamic File drv_encx24j600.h C SYS_MODULE_OBJ DRV_ENCX24J600_StackInitialize(SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns Returns a valid handle to the driver instance - If successful SYS_MODULE_OBJ_INVALID - If unsuccessful Description ENCX24J600 Stack Initialization This function is used by the TCP/IP stack to fully initialize the driver with both the ENCX24J600 specific configuration and the MAC control information. With this function there is no need to call DRV_ENCX24J600_SetMacCtrlInfo. Preconditions None. Parameters Parameters Description index This is the index of the driver instance to be initialized. The definition DRV_ENCX24J600_NUM_DRV_INSTANCES controls how many instances are available. init This is a pointer to a TCPIP_MAC_INIT structure. DRV_ENCX24J600_Process Function Additional processing that happens outside the tasks function. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 435 File drv_encx24j600.h C TCPIP_MAC_RES DRV_ENCX24J600_Process(DRV_HANDLE hMac); Returns • TCPIP_MAC_RES_TYPE_ERR - if the hMac is invalid • TCPIP_MAC_RES_OP_ERR - if the hMac is valid Description ENCX24J600 Process This function does additional processing that is not done inside the tasks function. Remarks This function does nothing in the first release. Preconditions The client had to be successfully opened with DRV_ENCX24J600_Open. Parameters Parameters Description hMac the successfully opened handle b) Client Level Functions DRV_ENCX24J600_Close Function Closes a client handle to the driver. Implementation: Dynamic File drv_encx24j600.h C void DRV_ENCX24J600_Close(DRV_HANDLE handle); Returns None. Description ENCX24J600 Close This function closes a handle to the driver. If it is the last client open, the driver will send an RX Disable command to the ENC hardware and move to the closed state. Preconditions The client had to be successfully opened with DRV_ENCX24J600_Open. Parameters Parameters Description handle The successfully opened handle DRV_ENCX24J600_ConfigGet Function Gets the current configuration. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 436 File drv_encx24j600.h C size_t DRV_ENCX24J600_ConfigGet(DRV_HANDLE hMac, void* configBuff, size_t buffSize, size_t* pConfigSize); Returns Number of bytes copied to the buffer Description ENCX24J600 Get Configuration Gets the current configuration. Remarks This function does nothing in the first release. Preconditions The client had to be successfully opened with DRV_ENCX24J600_Open. Parameters Parameters Description hMac the successfully opened handle configBuff location to copy the configuration too buffSize buffer size pConfigSize configuration size needed DRV_ENCX24J600_LinkCheck Function This function returns the status of the link. Implementation: Dynamic File drv_encx24j600.h C bool DRV_ENCX24J600_LinkCheck(DRV_HANDLE hMac); Returns • true - if the link is active • false - all other times Description ENCX24J600 Link Check This function checks the status of the link and returns it to the caller. Preconditions The client had to be successfully opened with DRV_ENCX24J600_Open. Parameters Parameters Description hMac the successfully opened handle DRV_ENCX24J600_Open Function This function is called by the client to open a handle to a driver instance. Implementation: Dynamic File drv_encx24j600.h Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 437 C DRV_HANDLE DRV_ENCX24J600_Open(SYS_MODULE_INDEX index, DRV_IO_INTENT intent); Returns Returns a valid handle - If successful INVALID_HANDLE - If unsuccessful Description ENCX24J600 Open The client will call this function to open a handle to the driver. When the first instance is opened than the driver will send the RX enabled command to the ENC hardware. Preconditions The driver had to be successfully initialized with DRV_ENCX24J600_Initialize. Parameters Parameters Description index This is the index of the driver instance to be initialized. The definition DRV_ENCX24J600_NUM_DRV_INSTANCES controls how many instances are available. intent The intent to use when opening the driver. Only exclusive is supported DRV_ENCX24J600_ParametersGet Function Get the parameters of the device. Implementation: Dynamic File drv_encx24j600.h C TCPIP_MAC_RES DRV_ENCX24J600_ParametersGet(DRV_HANDLE hMac, TCPIP_MAC_PARAMETERS* pMacParams); Returns • TCPIP_MAC_RES_TYPE_ERR - if the hMac is invalid • TCPIP_MAC_RES_OK - if the hMac is valid Description ENCX24J600 Get Parameters Get the parameters of the device, which includes that it is an Ethernet device and what it's MAC address is. Preconditions The client had to be successfully opened with DRV_ENCX24J600_Open. Parameters Parameters Description hMac the successfully opened handle pMacParams pointer to put the parameters DRV_ENCX24J600_PowerMode Function This function sets the power mode of the device. Implementation: Dynamic File drv_encx24j600.h C bool DRV_ENCX24J600_PowerMode(DRV_HANDLE hMac, TCPIP_MAC_POWER_MODE pwrMode); Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 438 Returns • false - This functionality is not supported in this version of the driver Description ENCX24J600 Power Mode This function sets the power mode of the ENCX24J600. Remarks This functionality is not implemented in the first release. Preconditions The client had to be successfully opened with DRV_ENCX24J600_Open. Parameters Parameters Description hMac the successfully opened handle pwrMode the power mode to set DRV_ENCX24J600_RegisterStatisticsGet Function Get the register statistics. Implementation: Dynamic File drv_encx24j600.h C TCPIP_MAC_RES DRV_ENCX24J600_RegisterStatisticsGet(DRV_HANDLE hMac, TCPIP_MAC_STATISTICS_REG_ENTRY* pRegEntries, int nEntries, int* pHwEntries); Returns • TCPIP_MAC_RES_TYPE_ERR - if the hMac is invalid • TCPIP_MAC_RES_OP_ERR - if the hMac is valid Description ENCX24J600 Get Register Statistics Get the device specific statistics. Remarks Statistics are not planned for the first release Preconditions The client had to be successfully opened with DRV_ENCX24J600_Open. Parameters Parameters Description hMac the successfully opened handle pRegEntries nEntries pHwEntries DRV_ENCX24J600_StatisticsGet Function Retrieve the devices statistics. Implementation: Dynamic File drv_encx24j600.h Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 439 C TCPIP_MAC_RES DRV_ENCX24J600_StatisticsGet(DRV_HANDLE hMac, TCPIP_MAC_RX_STATISTICS* pRxStatistics, TCPIP_MAC_TX_STATISTICS* pTxStatistics); Returns • TCPIP_MAC_RES_TYPE_ERR - if the hMac is invalid • TCPIP_MAC_RES_OP_ERR - if the hMac is valid Description ENCX24J600 Get Statistics Get the current statistics stored in the driver. Remarks Statistics are not planned for the first release. Preconditions The client had to be successfully opened with DRV_ENCX24J600_Open. Parameters Parameters Description hMac the successfully opened handle DRV_ENCX24J600_Status Function Gets the current status of the driver. Implementation: Dynamic File drv_encx24j600.h C SYS_STATUS DRV_ENCX24J600_Status(SYS_MODULE_OBJ obect); Returns • SYS_STATUS_ERROR - if an invalid handle has been passed in • SYS_STATUS_UNINITIALIZED - if the driver has not completed initialization • SYS_STATUS_BUSY - if the driver is closing and moving to the closed state • SYS_STATUS_READY - if the driver is ready for client commands Description ENCX24J600 Status This function will get the status of the driver instance. Preconditions The driver had to be successfully initialized with DRV_ENCX24J600_Initialize(). Parameters Parameters Description object The object valid passed back to DRV_ENCX24J600_Initialize() c) Receive Functions DRV_ENCX24J600_PacketRx Function Receive a packet from the driver. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 440 File drv_encx24j600.h C TCPIP_MAC_PACKET* DRV_ENCX24J600_PacketRx(DRV_HANDLE hMac, TCPIP_MAC_RES* pRes, const TCPIP_MAC_PACKET_RX_STAT** ppPktStat); Returns • Pointer to a valid packet - if successful • NULL - if unsuccessful Description ENCX24J600 Receive Packet This function retrieves a packet from the driver. The packet needs to be acknowledged with the linked acknowledge function so it can be reused. Remarks ppPktStat is ignored in the first release. Preconditions The client had to be successfully opened with DRV_ENCX24J600_Open. Parameters Parameters Description hMac the successfully opened handle pRes the result of the operation ppPktStat pointer to the receive statistics DRV_ENCX24J600_RxFilterHashTableEntrySet Function This function adds an entry to the hash table. Implementation: Dynamic File drv_encx24j600.h C TCPIP_MAC_RES DRV_ENCX24J600_RxFilterHashTableEntrySet(DRV_HANDLE hMac, const TCPIP_MAC_ADDR* DestMACAddr); Returns • TCPIP_MAC_RES_TYPE_ERR - if the hMac is invalid • TCPIP_MAC_RES_OP_ERR - if the hMac is valid Description ENCX24J600 Receive Filter Hash Table Entry Set This function adds to the MAC's hash table for hash table matching. Remarks This functionality is not implemented in the first release. Preconditions The client had to be successfully opened with DRV_ENCX24J600_Open. Parameters Parameters Description hMac the successfully opened handle DestMACAddr MAC address to add to the hash table d) Transmit Functions Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 441 DRV_ENCX24J600_PacketTx Function This function queues a packet for transmission. Implementation: Dynamic File drv_encx24j600.h C TCPIP_MAC_RES DRV_ENCX24J600_PacketTx(DRV_HANDLE hMac, TCPIP_MAC_PACKET * ptrPacket); Returns • TCPIP_MAC_RES_OP_ERR - if the client handle is invalid • TCPIP_MAC_RES_IS_BUSY - if the driver is not in the run state • TCPIP_MAC_RES_QUEUE_TX_FULL - if there are no free descriptors • TCPIP_MAC_RES_OK - on successful queuing of the packet Description ENCX24J600 Packet Transmit This function will take a packet and add it to the queue for transmission. When the packet has finished transmitting the driver will call the packets acknowledge function. When that acknowledge function is complete the driver will forget about the packet. Preconditions The client had to be successfully opened with DRV_ENCX24J600_Open. Parameters Parameters Description hMac the successfully opened handle ptrPacket pointer to the packet e) Event Functions DRV_ENCX24J600_EventAcknowledge Function Acknowledges an event. Implementation: Dynamic File drv_encx24j600.h C bool DRV_ENCX24J600_EventAcknowledge(DRV_HANDLE hMac, TCPIP_MAC_EVENT macEvents); Returns • true - if successful • false - if not successful Description ENCX24J600 Acknowledge Event This function acknowledges an event. Preconditions The client had to be successfully opened with DRV_ENCX24J600_Open. Parameters Parameters Description hMac the successfully opened handle macEvents the events to acknowledge Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 442 DRV_ENCX24J600_EventMaskSet Function Sets the event mask. Implementation: Dynamic File drv_encx24j600.h C bool DRV_ENCX24J600_EventMaskSet(DRV_HANDLE hMac, TCPIP_MAC_EVENT macEvents, bool enable); Returns • true - if the mask could be set • false - if the mast could not be set Description ENCX24J600 Set Event Mask Sets the event mask to what is passed in. Preconditions The client had to be successfully opened with DRV_ENCX24J600_Open. Parameters Parameters Description hMac the successfully opened handle macEvents the mask to enable or disable enable to enable or disable events DRV_ENCX24J600_EventPendingGet Function Gets the current events. Implementation: Dynamic File drv_encx24j600.h C TCPIP_MAC_EVENT DRV_ENCX24J600_EventPendingGet(DRV_HANDLE hMac); Returns • TCPIP_MAC_EV_NONE - Returned on an error • List of events - Returned on event other than an error Description ENCX24J600 Get Events This function gets the current events. Preconditions The client had to be successfully opened with DRV_ENCX24J600_Open. Parameters Parameters Description hMac the successfully opened handle f) Data Types and Constants Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 443 DRV_ENCX24J600_Configuration Structure Defines the data required to initialize or reinitialize the ENCX24J600 Driver. File drv_encx24j600.h C typedef struct _DRV_ENCX24J600_Configuration { uint16_t txDescriptors; uint16_t rxDescriptors; uint16_t rxDescBufferSize; SYS_MODULE_INDEX spiDrvIndex; uint32_t spiBps; uint16_t rxBufferSize; uint16_t maxFrameSize; PORTS_MODULE_ID spiSSPortModule; PORTS_CHANNEL spiSSPortChannel; PORTS_BIT_POS spiSSPortPin; bool intEnable; PORTS_MODULE_ID intPortModule; PORTS_CHANNEL intPortChannel; PORTS_BIT_POS intPortPin; DRV_ENCX24J600_MDIX_TYPE mdixControl; PORTS_MODULE_ID mdixPortModule; PORTS_CHANNEL mdixPortChannel; PORTS_BIT_POS mdixPortPin; TCPIP_ETH_OPEN_FLAGS ethType; TCPIP_ETH_OPEN_FLAGS dupMode; } DRV_ENCX24J600_Configuration; Members Members Description uint16_t txDescriptors; Number of TX Descriptors to Allocate uint16_t rxDescriptors; Number of RX Descriptors to Allocate uint16_t rxDescBufferSize; Size of the buffer each RX Descriptor will use. Make sure its not smaller that maxFrameSize SYS_MODULE_INDEX spiDrvIndex; Index of the SPI driver to use uint32_t spiBps; Bus speed to use for the SPI interface. Section 1.0 of the ENCX24J600 data sheets says the maximum is 14000000 Hz. It is not recommended to go above this value. uint16_t rxBufferSize; The ENCX24J600 hardware has a 22 k dram. rxBufferSize defines how much of that memory is used by the rxBuffer uint16_t maxFrameSize; The maximum frame size to be supported by the hardware. 1536 is the default PORTS_MODULE_ID spiSSPortModule; Port Module of the GPIO pin hooked up to the CS/SS pin of the ENCX24J600 PORTS_CHANNEL spiSSPortChannel; Port Channel of the GPIO pin hooked up to the CS/SS pin of the ENCX24J600 PORTS_BIT_POS spiSSPortPin; Pin position of the GPIO pin hooked up to the CS/SS pin of the ENCX24J600 bool intEnable; Use Interrupts or not. PORTS_MODULE_ID intPortModule; Port Module of the GPIO pin hooked up to the INT pin of the ENCX24J600 PORTS_CHANNEL intPortChannel; Port Channel of the GPIO pin hooked up to the INT pin of the ENCX24J600 PORTS_BIT_POS intPortPin; Pin Position of the GPIO pin hooked up to the INT pin of the ENCX24J600 DRV_ENCX24J600_MDIX_TYPE mdixControl; To select the control type of the MDIX. This is only needed for hooking up to switches that don't have auto-mdix. PORTS_MODULE_ID mdixPortModule; Port Module of the GPIO pin hooked up to the MDIX select pin PORTS_CHANNEL mdixPortChannel; Port Channel of the GPIO pin hooked up to the MDIX select pin PORTS_BIT_POS mdixPortPin; Pin Position of the GPIO pin hooked up to the MDIX select pin TCPIP_ETH_OPEN_FLAGS ethType; Ethernet type TCPIP_ETH_OPEN_FLAGS dupMode; Duplex Mode Description ENCX24J600 Driver Initialization Data This data type defines the data required to initialize or reinitialize the ENCX24J600 driver. If the driver is built statically, the members of this data structure are statically over-ridden by static override definitions in the system_config.h file. Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 444 Remarks None. DRV_ENCX24J600_MDIX_TYPE Enumeration Defines the enumeration for controlling the MDIX select. File drv_encx24j600.h C typedef enum { DRV_ENCX24J600_NO_CONTROL = 0, DRV_ENCX24J600_NORMAL, DRV_ENCX24J600_REVERSE = 0 } DRV_ENCX24J600_MDIX_TYPE; Members Members Description DRV_ENCX24J600_NO_CONTROL = 0 No Control DRV_ENCX24J600_NORMAL Normal MDIX DRV_ENCX24J600_REVERSE = 0 Reverse MDIX Description ENCX24J600 Driver MDIX Control type This type defines the enumeration for controlling the MDIX select. Remarks None. Files Files Name Description drv_encx24j600.h ENCx24J600 Driver interface definition. Description drv_encx24j600.h ENCx24J600 Driver interface definition. Enumerations Name Description DRV_ENCX24J600_MDIX_TYPE Defines the enumeration for controlling the MDIX select. Functions Name Description DRV_ENCX24J600_Close Closes a client handle to the driver. Implementation: Dynamic DRV_ENCX24J600_ConfigGet Gets the current configuration. Implementation: Dynamic DRV_ENCX24J600_Deinitialize Deinitializes the ENCx24J600 Driver Instance. Implementation: Dynamic DRV_ENCX24J600_EventAcknowledge Acknowledges an event. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help ENCx24J600 Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 445 DRV_ENCX24J600_EventMaskSet Sets the event mask. Implementation: Dynamic DRV_ENCX24J600_EventPendingGet Gets the current events. Implementation: Dynamic DRV_ENCX24J600_Initialize Initializes the ENCx24J600 Driver Instance, with the configuration data. Implementation: Dynamic DRV_ENCX24J600_LinkCheck This function returns the status of the link. Implementation: Dynamic DRV_ENCX24J600_Open This function is called by the client to open a handle to a driver instance. Implementation: Dynamic DRV_ENCX24J600_PacketRx Receive a packet from the driver. Implementation: Dynamic DRV_ENCX24J600_PacketTx This function queues a packet for transmission. Implementation: Dynamic DRV_ENCX24J600_ParametersGet Get the parameters of the device. Implementation: Dynamic DRV_ENCX24J600_PowerMode This function sets the power mode of the device. Implementation: Dynamic DRV_ENCX24J600_Process Additional processing that happens outside the tasks function. Implementation: Dynamic DRV_ENCX24J600_RegisterStatisticsGet Get the register statistics. Implementation: Dynamic DRV_ENCX24J600_Reinitialize Reinitializes the instance of the ENCX24J600 driver. Implementation: Dynamic DRV_ENCX24J600_RxFilterHashTableEntrySet This function adds an entry to the hash table. Implementation: Dynamic DRV_ENCX24J600_SetMacCtrlInfo This function sets the MAC control information for the driver. Implementation: Dynamic DRV_ENCX24J600_StackInitialize This function initializes the driver with a TCPIP_MAC_INIT object. Implementation: Dynamic DRV_ENCX24J600_StatisticsGet Retrieve the devices statistics. Implementation: Dynamic DRV_ENCX24J600_Status Gets the current status of the driver. Implementation: Dynamic DRV_ENCX24J600_Tasks Main task function for the driver. Implementation: Dynamic Structures Name Description _DRV_ENCX24J600_Configuration Defines the data required to initialize or reinitialize the ENCX24J600 Driver. DRV_ENCX24J600_Configuration Defines the data required to initialize or reinitialize the ENCX24J600 Driver. Description ENCx24J600 Driver Public Interface This file defines the interface definition for the ENCx24J600 Driver. File Name drv_encx24j600.h Company Microchip Technology Inc. Ethernet MAC Driver Library This section describes the Ethernet MAC Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 446 Introduction This library provides a driver-level abstraction of the on-chip Ethernet Controller found on many PIC32 devices. The driver implements the virtual MAC driver model that the MPLAB Harmony TCP/IP Stack requires. Please see the TCP/IP Stack Library MAC Driver Module help for details. The "Host-To-Network"_layer of a TCP/IP stack organization covers the Data Link and Physical Layers of the standard OSI stack. The Ethernet Controller provides the Data Link or Media Access Control Layer, in addition to other functions discussed in this section. An external Ethernet "PHY" provides the Physical_layer, providing conversion between the digital and analog. Description The PIC32 Ethernet Controller is a bus master module that interfaces with an off-chip PHY to implement a complete Ethernet node in a system. The following are some of the key features of this module: • Supports 10/100 Ethernet • Full-Duplex and Half-Duplex operation • Broadcast, Multicast and Unicast packets • Manual and automatic flow control • Supports Auto-MDIX enabled PHYs • Reduced Media Independent Interface (RMII) and Media Independent Interface (MII) PHY data interfaces • Performance statistics metrics in hardware. • RAM descriptor based DMA operation for both receive and transmit path • Fully configurable interrupts • Configurable receive packet filtering using: • 64-bit Hash Table • 64-byte Pattern Match • Magic Packet™ Filtering • Runt Packet Detection and Filtering • Supports Packet Payload Checksum calculation • CRC Check Support for the Serial Management Interface (SMI) (also known as the MIIM interface) is provided by the Ethernet PHY Driver Library. Using the Library The user of this driver is the MPLAB Harmony TCP/IP stack. This Ethernet driver is not intended as a system wide driver that the application or other system modules may use. It is intended for the sole use of the MPLAB Harmony TCP/IP stack and implements the virtual MAC model required by the stack. This topic describes the basic architecture and functionality of the Ethernet MAC driver and is meant for advanced users or TCP/IP stack driver developers. Interface Header File: drv_ethmac.h The interface to the Ethernet MAC library is defined in the drv_ethmac.h header file, which is included by the MPLAB Harmony TCP/IP stack. Please refer to the What is MPLAB Harmony? section for how the library interacts with the framework. Abstraction Model This library provides a low-level abstraction of the Ethernet MAC Driver Library 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 Ethernet Controller provides the modules needed to implement a 10/100 Mbps Ethernet node using an external Ethernet PHY chip. The PHY chip provides a digital-analog interface as part of the Physical Layer and the controller provides the Media Access Controller (MAC)_layer above the PHY. As shown in Figure 1, 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: Responsible for control of the transmission of PAUSE frames. (Reception of PAUSE frames 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 • TX DMA/TX Buffer Management 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 Buffer Management Engine: The RX DMA and RX Buffer Management engines transfer receive packets from the MAC to the memory (using descriptor tables) Figure 1: Ethernet Controller Block Diagram Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 447 For completeness, we also need to look at the interface diagram of a representative Ethernet PHY. As shown in Figure 2, the PHY has two interfaces, one for configuring and managing the PHY (SMI/MIIM) and another for transmit and receive data (RMII or MII). The SMI/MIIM interface is the responsibility of the Ethernet PHY Driver Library. When setting up the Ethernet PHY, this Ethernet driver calls primitives from the Ethernet PHY Driver library. The RMII/MII data interface is the responsibility of the Ethernet MAC Driver Library (this library). Figure 2: Ethernet PHY Interfaces Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 448 Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. Refer to the TCP/IP Stack Library MAC Driver Module help for the interface that the Ethernet driver has to implement in a MPLAB Harmony system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Ethernet MAC Driver Library. Library Interface Section Description Client Level Functions DRV_ETHMAC_PIC32MACOpen, DRV_ETHMAC_PIC32MACClose, and DRV_ETHMAC_PIC32MACSetup to support the TCP/IP Stack. Plus link status and power options. Receive Functions Receive routines. Transmit Functions Transmit routines. Event Functions Ethernet event support routines. Other Functions Additional routines. Data Types and Constants Typedefs and #defines. Configuring the Library Macros Name Description DRV_ETHMAC_CLIENTS_NUMBER Selects the maximum number of clients. DRV_ETHMAC_INDEX Ethernet MAC static index selection. DRV_ETHMAC_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver. DRV_ETHMAC_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_ETHMAC_INTERRUPT_SOURCE Defines an override of the interrupt source in case of static driver. DRV_ETHMAC_PERIPHERAL_ID Defines an override of the peripheral ID. DRV_ETHMAC_POWER_STATE Defines an override of the power state of the Ethernet MAC driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 449 Description The configuration of the Ethernet MAC driver is done as part of the MPLAB Harmony TCP/IP Stack configuration and is based on the system_config.h file, which may include the tcpip_mac_config.h. See the TCP/IP Stack Library MAC Driver Module help file for configuration options. This header file contains the configuration selection for the Ethernet MAC Driver. 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. DRV_ETHMAC_CLIENTS_NUMBER Macro Selects the maximum number of clients. File drv_ethmac_config.h C #define DRV_ETHMAC_CLIENTS_NUMBER 1 Description Ethernet MAC Maximum Number of Clients This definition select the maximum number of clients that the Ethernet MAC driver can support at run time. Remarks The MAC driver is not a true multi-client driver. Under normal usage, the only client of the MAC driver is the TCP/IP stack. After the MAC driver provided an DRV_HANDLE as a result of an Open operation, any other attempt to call Open will return a invalid handle. Default value should be 1. However, for allowing other modules to interface directly with the MAC driver while the TCP/IP stack currently uses the the MAC driver this symbol can have a value greater than 1. But the returned handle is the same one as the TCP/IP stack uses. DRV_ETHMAC_INDEX Macro Ethernet MAC static index selection. File drv_ethmac_config.h C #define DRV_ETHMAC_INDEX DRV_ETHMAC_INDEX_1 Description Ethernet MAC Static Index Selection This definition selects the Ethernet MAC static index for the driver object reference Remarks This index is required to make a reference to the driver object. DRV_ETHMAC_INSTANCES_NUMBER Macro Selects the maximum number of hardware instances that can be supported by the dynamic driver. File drv_ethmac_config.h C #define DRV_ETHMAC_INSTANCES_NUMBER 1 Description Ethernet MAC hardware instance configuration This definition selects the maximum number of hardware instances that can be supported by the dynamic driver. Not defining it means using a static driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 450 Remarks None. DRV_ETHMAC_INTERRUPT_MODE Macro Controls operation of the driver in the interrupt or polled mode. File drv_ethmac_config.h C #define DRV_ETHMAC_INTERRUPT_MODE true Description Ethernet MAC Interrupt And Polled Mode Operation Control This macro controls the operation of the driver in the interrupt mode of operation. The possible values of this macro are: • true - Select if interrupt mode of timer operation is desired • false - Select if polling mode of timer operation is desired Not defining this option to true or false will result in a build error. Remarks None. DRV_ETHMAC_INTERRUPT_SOURCE Macro Defines an override of the interrupt source in case of static driver. File drv_ethmac_config.h C #define DRV_ETHMAC_INTERRUPT_SOURCE INT_SOURCE_ETH_1 Description Ethernet MAC Interrupt Source Defines an override of the interrupt source in case of static driver. Remarks Refer to the INT PLIB document for more information on INT_SOURCE enumeration. DRV_ETHMAC_PERIPHERAL_ID Macro Defines an override of the peripheral ID. File drv_ethmac_config.h C #define DRV_ETHMAC_PERIPHERAL_ID ETHMAC_ID_1 Description Ethernet MAC Peripheral ID Selection Defines an override of the peripheral ID, using macros. Remarks Some devices also support ETHMAC_ID_0 Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 451 DRV_ETHMAC_POWER_STATE Macro Defines an override of the power state of the Ethernet MAC driver. File drv_ethmac_config.h C #define DRV_ETHMAC_POWER_STATE SYS_MODULE_POWER_IDLE_STOP Description Ethernet MAC power state configuration Defines an override of the power state of the Ethernet MAC driver. Remarks This feature may not be available in the device or the Ethernet MAC module selected. Building the Library This section lists the files that are available in the Ethernet MAC Driver Library. 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 /framework/driver/ethmac. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_ethmac.h Header file that exports the driver API. 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 /src/dynamic/drv_ethmac.c PIC32 internal Ethernet driver virtual MAC implementation file. /src/dynamic/drv_ethmac_lib.c PIC32 internal Ethernet driver controller implementation file. 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 N/A No optional files are available for this library Module Dependencies The Ethernet MAC Driver Library depends on the following modules: • Ethernet PHY Driver Library • Interrupt System Service Library • Timer System Service Library • Ethernet Peripheral Library Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 452 Library Interface a) Client Level Functions Name Description DRV_ETHMAC_PIC32MACClose Closes a client instance of the PIC32 MAC Driver. Implementation: Dynamic DRV_ETHMAC_PIC32MACDeinitialize Deinitializes the PIC32 Ethernet MAC. Implementation: Dynamic DRV_ETHMAC_PIC32MACInitialize Initializes the PIC32 Ethernet MAC. Implementation: Dynamic DRV_ETHMAC_PIC32MACLinkCheck Checks current link status. Implementation: Dynamic DRV_ETHMAC_PIC32MACOpen Opens a client instance of the PIC32 MAC Driver. Implementation: Dynamic DRV_ETHMAC_PIC32MACParametersGet MAC parameter get function. Implementation: Dynamic DRV_ETHMAC_PIC32MACPowerMode Selects the current power mode for the Ethernet MAC. Implementation: Dynamic DRV_ETHMAC_PIC32MACProcess MAC periodic processing function. Implementation: Dynamic DRV_ETHMAC_PIC32MACStatisticsGet Gets the current MAC statistics. Implementation: Dynamic DRV_ETHMAC_PIC32MACStatus Provides the current status of the MAC driver module. Implementation: Dynamic DRV_ETHMAC_PIC32MACConfigGet Gets the current MAC driver configuration. Implementation: Dynamic DRV_ETHMAC_PIC32MACRegisterStatisticsGet Gets the current MAC hardware statistics registers. Implementation: Dynamic DRV_ETHMAC_PIC32MACReinitialize Reinitializes the PIC32 Ethernet MAC. Implementation: Dynamic b) Receive Functions Name Description DRV_ETHMAC_PIC32MACPacketRx This is the MAC receive function. Implementation: Dynamic DRV_ETHMAC_PIC32MACRxFilterHashTableEntrySet Sets the current MAC hash table receive filter. Implementation: Dynamic c) Transmit Functions Name Description DRV_ETHMAC_PIC32MACPacketTx MAC driver transmit function. Implementation: Dynamic d) Event Functions Name Description DRV_ETHMAC_PIC32MACEventAcknowledge Acknowledges and re-enables processed events. Implementation: Dynamic DRV_ETHMAC_PIC32MACEventMaskSet Enables/disables the MAC events. Implementation: Dynamic DRV_ETHMAC_PIC32MACEventPendingGet Returns the currently pending events. Implementation: Dynamic e) Other Functions Name Description DRV_ETHMAC_Tasks_ISR Ethernet MAC driver interrupt function. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 453 DRV_ETHMAC_PIC32MACTasks Maintains the EThernet MAC driver's state machine. Implementation: Dynamic f) Data Types and Constants Name Description DRV_ETHMAC_INDEX_1 This is macro DRV_ETHMAC_INDEX_1. DRV_ETHMAC_INDEX_0 Ethernet driver index definitions. DRV_ETHMAC_INDEX_COUNT Number of valid Ethernet driver indices. Description This section lists the interface routines, data types, constants and macros for the library. a) Client Level Functions DRV_ETHMAC_PIC32MACClose Function Closes a client instance of the PIC32 MAC Driver. Implementation: Dynamic File drv_ethmac.h C void DRV_ETHMAC_PIC32MACClose(DRV_HANDLE hMac); Returns None Description This function closes a client instance of the PIC32 MAC Driver. Remarks None Preconditions DRV_ETHMAC_PIC32MACOpen() should have been called. Example Parameters Parameters Description hMac valid MAC handle, obtained by a call to DRV_ETHMAC_PIC32MACOpen Function void DRV_ETHMAC_PIC32MACClose( DRV_HANDLE hMac ) DRV_ETHMAC_PIC32MACDeinitialize Function Deinitializes the PIC32 Ethernet MAC. Implementation: Dynamic File drv_ethmac.h C void DRV_ETHMAC_PIC32MACDeinitialize(SYS_MODULE_OBJ object); Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 454 Returns None. Description This function supports teardown of the PIC32 Ethernet MAC (opposite of set up). Used by tcpip_module_manager. Remarks This function deinitializes the Ethernet controller, the MAC and the associated PHY. It should be called to be release any resources allocated by the initialization and return the MAC and the PHY to the idle/power down state. Preconditions DRV_ETHMAC_PIC32MACInitialize must have been called to set up the driver. Example Function void DRV_ETHMAC_PIC32MACDeinitialize(SYS_MODULE_OBJ object); DRV_ETHMAC_PIC32MACInitialize Function Initializes the PIC32 Ethernet MAC. Implementation: Dynamic File drv_ethmac.h C SYS_MODULE_OBJ DRV_ETHMAC_PIC32MACInitialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns • a valid handle to a driver object, if successful. • SYS_MODULE_OBJ_INVALID if initialization failed. Description This function supports the initialization of the PIC32 Ethernet MAC. Used by tcpip_module_manager. Remarks This function initializes the Ethernet controller, the MAC and the associated PHY. It should be called to be able to schedule any Ethernet transmit or receive operation. Preconditions None Example Function SYS_MODULE_OBJ DRV_ETHMAC_PIC32MACInitialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); DRV_ETHMAC_PIC32MACLinkCheck Function Checks current link status. Implementation: Dynamic File drv_ethmac.h C bool DRV_ETHMAC_PIC32MACLinkCheck(DRV_HANDLE hMac); Returns • true - If the link is up Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 455 • false - If the link is not up Description This function checks the link status of the associated network interface. Remarks The function will automatically perform a MAC reconfiguration if the link went up after being down and the PHY auto negotiation is enabled. Preconditions DRV_ETHMAC_PIC32MACInitialize must have been called to set up the driver. DRV_ETHMAC_PIC32MACOpen() should have been called to obtain a valid handle. Example Parameters Parameters Description hMac Ethernet MAC client handle Function bool DRV_ETHMAC_PIC32MACLinkCheck( DRV_HANDLE hMac ) DRV_ETHMAC_PIC32MACOpen Function Opens a client instance of the PIC32 MAC Driver. Implementation: Dynamic File drv_ethmac.h C DRV_HANDLE DRV_ETHMAC_PIC32MACOpen(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); Returns • DRV_HANDLE - handle (pointer) to MAC client • 0 if call failed Description This function opens a client instance of the PIC32 MAC Driver. Used by tcpip_module_manager. Remarks The intent parameter is not used in the current implementation and is maintained only for compatibility with the generic driver Open function signature. Preconditions DRV_ETHMAC_PIC32MACInitialize() should have been called. Example Function DRV_HANDLE DRV_ETHMAC_PIC32MACOpen(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); DRV_ETHMAC_PIC32MACParametersGet Function MAC parameter get function. Implementation: Dynamic File drv_ethmac.h C TCPIP_MAC_RES DRV_ETHMAC_PIC32MACParametersGet(DRV_HANDLE hMac, TCPIP_MAC_PARAMETERS* pMacParams); Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 456 Returns • TCPIP_MAC_RES_OK if pMacParams updated properly • a TCPIP_MAC_RES error code if processing failed for some reason Description MAC Parameter Get function TCPIP_MAC_RES DRV_ETHMAC_PIC32MACParametersGet(DRV_HANDLE hMac, TCPIP_MAC_PARAMETERS* pMacParams); This is a function that returns the run time parameters of the MAC driver. Remarks None. Preconditions DRV_ETHMAC_PIC32MACInitialize() should have been called. DRV_ETHMAC_PIC32MACOpen() should have been called to obtain a valid handle. DRV_ETHMAC_PIC32MACPowerMode Function Selects the current power mode for the Ethernet MAC. Implementation: Dynamic File drv_ethmac.h C bool DRV_ETHMAC_PIC32MACPowerMode(DRV_HANDLE hMac, TCPIP_MAC_POWER_MODE pwrMode); Returns • true if the call succeeded. • false if the call failed Description This function sets the power mode for the Ethernet MAC. Remarks This function is not currently supported by the Ethernet MAC and will always return true. Preconditions DRV_ETHMAC_PIC32MACInitialize must have been called to set up the driver. DRV_ETHMAC_PIC32MACOpen() should have been called to obtain a valid handle. Example Function bool DRV_ETHMAC_PIC32MACPowerMode( DRV_HANDLE hMac, TCPIP_MAC_POWER_MODE pwrMode ) DRV_ETHMAC_PIC32MACProcess Function MAC periodic processing function. Implementation: Dynamic File drv_ethmac.h C TCPIP_MAC_RES DRV_ETHMAC_PIC32MACProcess(DRV_HANDLE hMac); Returns • TCPIP_MAC_RES_OK if all processing went on OK • a TCPIP_MAC_RES error code if processing failed for some reason Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 457 Description This is a function that allows for internal processing by the MAC driver. It is meant for processing that cannot be done from within ISR. Normally this function will be called in response to an TX and/or RX event signaled by the driver. This is specified by the MAC driver at initialization time using TCPIP_MAC_MODULE_CTRL. Remarks • The MAC driver may use the DRV_ETHMAC_PIC32MACProcess() for: • Processing its pending TX queues • RX buffers replenishing functionality. If the number of packets in the RX queue falls below a specified limit, the MAC driver may use this function to allocate some extra RX packets. Similarly, if there are too many allocated RX packets, the MAC driver can free some of them. Preconditions DRV_ETHMAC_PIC32MACInitialize() should have been called. DRV_ETHMAC_PIC32MACOpen() should have been called to obtain a valid handle. Example Parameters Parameters Description hMac Ethernet MAC client handle Function TCPIP_MAC_RES DRV_ETHMAC_PIC32MACProcess( DRV_HANDLE hMac); DRV_ETHMAC_PIC32MACStatisticsGet Function Gets the current MAC statistics. Implementation: Dynamic File drv_ethmac.h C TCPIP_MAC_RES DRV_ETHMAC_PIC32MACStatisticsGet(DRV_HANDLE hMac, TCPIP_MAC_RX_STATISTICS* pRxStatistics, TCPIP_MAC_TX_STATISTICS* pTxStatistics); Returns • TCPIP_MAC_RES_OK if all processing went on OK. • TCPIP_MAC_RES_OP_ERR error code if function not supported by the driver. Description This function will get the current value of the statistic counters maintained by the MAC driver. Remarks • The reported values are info only and change dynamically. Preconditions DRV_ETHMAC_PIC32MACInitialize() should have been called. DRV_ETHMAC_PIC32MACOpen() should have been called to obtain a valid handle. Example Function TCPIP_MAC_RES DRV_ETHMAC_PIC32MACStatisticsGet( DRV_HANDLE hMac, TCPIP_MAC_RX_STATISTICS* pRxStatistics, TCPIP_MAC_TX_STATISTICS* pTxStatistics); DRV_ETHMAC_PIC32MACStatus Function Provides the current status of the MAC driver module. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 458 File drv_ethmac.h C SYS_STATUS DRV_ETHMAC_PIC32MACStatus(SYS_MODULE_OBJ object); Returns • SYS_STATUS_READY - Indicates that any previous module operation for the specified module has completed • SYS_STATUS_BUSY - Indicates that a previous module operation for the specified module has not yet completed • SYS_STATUS_ERROR - Indicates that the specified module is in an error state Description This function provides the current status of the MAC driver module. Remarks None. Preconditions The DRV_ETHMAC_PIC32MACInitialize function must have been called before calling this function. Example Parameters Parameters Description object Driver object handle, returned from DRV_ETHMAC_PIC32MACInitialize Function SYS_STATUS DRV_ETHMAC_PIC32MACStatus ( SYS_MODULE_OBJ object ) DRV_ETHMAC_PIC32MACConfigGet Function Gets the current MAC driver configuration. Implementation: Dynamic File drv_ethmac.h C size_t DRV_ETHMAC_PIC32MACConfigGet(DRV_HANDLE hMac, void* configBuff, size_t buffSize, size_t* pConfigSize); Returns • number of bytes copied into the supplied storage buffer Description This function will get the current MAC driver configuration and store it into a supplied buffer. Remarks • None Preconditions DRV_ETHMAC_PIC32MACInitialize() should have been called. DRV_ETHMAC_PIC32MACOpen() should have been called to obtain a valid handle. Example Function size_t DRV_ETHMAC_PIC32MACConfigGet( DRV_HANDLE hMac, void* configBuff, size_t buffSize, size_t* pConfigSize); Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 459 DRV_ETHMAC_PIC32MACRegisterStatisticsGet Function Gets the current MAC hardware statistics registers. Implementation: Dynamic File drv_ethmac.h C TCPIP_MAC_RES DRV_ETHMAC_PIC32MACRegisterStatisticsGet(DRV_HANDLE hMac, TCPIP_MAC_STATISTICS_REG_ENTRY* pRegEntries, int nEntries, int* pHwEntries); Returns • TCPIP_MAC_RES_OK if all processing went on OK. • TCPIP_MAC_RES_OP_ERR error code if function not supported by the driver. Description This function will get the current value of the statistic registers of the associated MAC controller. Remarks • The reported values are info only and change dynamically. Preconditions DRV_ETHMAC_PIC32MACInitialize() should have been called. DRV_ETHMAC_PIC32MACOpen() should have been called to obtain a valid handle. Example Function TCPIP_MAC_RES DRV_ETHMAC_PIC32MACRegisterStatisticsGet( DRV_HANDLE hMac, TCPIP_MAC_STATISTICS_REG_ENTRY* pRegEntries, int nEntries, int* pHwEntries); DRV_ETHMAC_PIC32MACReinitialize Function Reinitializes the PIC32 Ethernet MAC. Implementation: Dynamic File drv_ethmac.h C void DRV_ETHMAC_PIC32MACReinitialize(SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init); Returns None. Description This function supports re-initialization of the PIC32 Ethernet MAC (opposite of set up). Remarks This function is not supported yet. Preconditions DRV_ETHMAC_PIC32MACInitialize must have been called to set up the driver. Example Function void DRV_ETHMAC_PIC32MACReinitialize(SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init); b) Receive Functions Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 460 DRV_ETHMAC_PIC32MACPacketRx Function This is the MAC receive function. Implementation: Dynamic File drv_ethmac.h C TCPIP_MAC_PACKET* DRV_ETHMAC_PIC32MACPacketRx(DRV_HANDLE hMac, TCPIP_MAC_RES* pRes, const TCPIP_MAC_PACKET_RX_STAT** ppPktStat); Returns • a valid pointer to an available RX packet • 0 if no packet pending/available Description This function will return a packet if such a pending packet exists. Additional information about the packet is available by providing the pRes and ppPktStat fields. Remarks • Once a pending packet is available in the MAC driver internal RX queues this function will dequeue the packet and hand it over to the MAC driver's client - i.e., the stack - for further processing. • The flags for a RX packet are updated by the MAC driver: • TCPIP_MAC_PKT_FLAG_RX will be set • TCPIP_MAC_PKT_FLAG_UNICAST is set if that packet is a unicast packet • TCPIP_MAC_PKT_FLAG_BCAST is set if that packet is a broadcast packet • TCPIP_MAC_PKT_FLAG_MCAST is set if that packet is a multicast packet • TCPIP_MAC_PKT_FLAG_QUEUED is set • TCPIP_MAC_PKT_FLAG_SPLIT is set if the packet has multiple data segments • The MAC driver dequeues and return to the caller just one single packet. That is the packets are not chained. • The packet buffers are allocated by the Ethernet MAC driver itself, Once the higher level layers in the stack are done with processing the RX packet, they have to call the corresponding packet acknowledgment function that tells the MAC driver that it can resume control of that packet. • Once the stack modules are done processing the RX packets and the acknowledge function is called the MAC driver will reuse the RX packets. • The MAC driver may use the DRV_ETHMAC_PIC32MACProcess() for obtaining new RX packets if needed. Preconditions DRV_ETHMAC_PIC32MACInitialize() should have been called. DRV_ETHMAC_PIC32MACOpen() should have been called to obtain a valid handle. Example Function TCPIP_MAC_PACKET* DRV_ETHMAC_PIC32MACPacketRx ( DRV_HANDLE hMac, TCPIP_MAC_RES* pRes, const TCPIP_MAC_PACKET_RX_STAT** ppPktStat); DRV_ETHMAC_PIC32MACRxFilterHashTableEntrySet Function Sets the current MAC hash table receive filter. Implementation: Dynamic File drv_ethmac.h Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 461 C TCPIP_MAC_RES DRV_ETHMAC_PIC32MACRxFilterHashTableEntrySet(DRV_HANDLE hMac, const TCPIP_MAC_ADDR* DestMACAddr); Returns • TCPIP_MAC_RES_OK if success • a TCPIP_MAC_RES error value if failed Description This function sets the MAC hash table filtering to allow packets sent to DestMACAddr to be received. It calculates a CRC-32 using polynomial 0x4C11DB7 over the 6 byte MAC address and then, using bits 28:23 of the CRC, will set the appropriate bits in the hash table filter registers ( ETHHT0-ETHHT1). The function will enable/disable the Hash Table receive filter if needed. Remarks • Sets the appropriate bit in the ETHHT0/1 registers to allow packets sent to DestMACAddr to be received and enabled the Hash Table receive filter. • There is no way to individually remove destination MAC addresses from the hash table since it is possible to have a hash collision and therefore multiple MAC addresses relying on the same hash table bit. • A workaround is to have the stack store each enabled MAC address and to perform the comparison at run time. • A call to DRV_ETHMAC_PIC32MACRxFilterHashTableEntrySet() using a 00-00-00-00-00-00 destination MAC address, which will clear the entire hash table and disable the hash table filter. This will allow the receive of all packets, regardless of their destination Preconditions DRV_ETHMAC_PIC32MACInitialize() should have been called. DRV_ETHMAC_PIC32MACOpen() should have been called to obtain a valid handle. Example Function TCPIP_MAC_RES DRV_ETHMAC_PIC32MACRxFilterHashTableEntrySet( DRV_HANDLE hMac, const TCPIP_MAC_ADDR* DestMACAddr) c) Transmit Functions DRV_ETHMAC_PIC32MACPacketTx Function MAC driver transmit function. Implementation: Dynamic File drv_ethmac.h C TCPIP_MAC_RES DRV_ETHMAC_PIC32MACPacketTx(DRV_HANDLE hMac, TCPIP_MAC_PACKET * ptrPacket); Returns • TCPIP_MAC_RES_OK if success • a TCPIP_MAC_RES error value if failed Description This is the MAC transmit function. Using this function a packet is submitted to the MAC driver for transmission. Remarks • The MAC driver supports internal queuing. A packet is rejected only if it's not properly formatted. Otherwise it will be scheduled for transmission and queued internally if needed. • Once the packet is scheduled for transmission the MAC driver will set the TCPIP_MAC_PKT_FLAG_QUEUED flag so that the stack is aware that this packet is under processing and cannot be modified. • Once the packet is transmitted, the TCPIP_MAC_PKT_FLAG_QUEUED will be cleared, the proper packet acknowledgment result (ackRes) will Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 462 be set and the packet acknowledgment function (ackFunc) will be called. Preconditions DRV_ETHMAC_PIC32MACInitialize() should have been called. DRV_ETHMAC_PIC32MACOpen() should have been called to obtain a valid handle. Example Function TCPIP_MAC_RES DRV_ETHMAC_PIC32MACPacketTx( DRV_HANDLE hMac, TCPIP_MAC_PACKET * ptrPacket); d) Event Functions DRV_ETHMAC_PIC32MACEventAcknowledge Function Acknowledges and re-enables processed events. Implementation: Dynamic File drv_ethmac.h C bool DRV_ETHMAC_PIC32MACEventAcknowledge(DRV_HANDLE hMac, TCPIP_MAC_EVENT tcpAckEv); Returns • true if events acknowledged • false if no events to be acknowledged Description This function acknowledges and re-enables processed events. Multiple events can be ORed together as they are processed together. The events acknowledged by this function should be the events that have been retrieved from the stack by calling DRV_ETHMAC_PIC32MACEventPendingGet() or have been passed to the stack by the driver using the registered notification handler and have been processed and have to be re-enabled. Remarks • All events should be acknowledged, in order to be re-enabled. • Some events are fatal errors and should not be acknowledged ( TCPIP_MAC_EV_RX_BUSERR, TCPIP_MAC_EV_TX_BUSERR). Driver/stack re-initialization is needed under such circumstances. • Some events are just system/application behavior and they are intended only as simple info (TCPIP_MAC_EV_RX_OVFLOW, TCPIP_MAC_EV_RX_BUFNA, TCPIP_MAC_EV_TX_ABORT, TCPIP_MAC_EV_RX_ACT). • The TCPIP_MAC_EV_RX_FWMARK and TCPIP_MAC_EV_RX_EWMARK events are part of the normal flow control operation (if auto flow control was enabled). They should be enabled alternatively, if needed. • The events are persistent. They shouldn't be re-enabled unless they have been processed and the condition that generated them was removed. Re-enabling them immediately without proper processing will have dramatic effects on system performance. Preconditions DRV_ETHMAC_PIC32MACInitialize() should have been called. DRV_ETHMAC_PIC32MACOpen() should have been called to obtain a valid handle. Example DRV_ETHMAC_PIC32MACEventAcknowledge( hMac, stackNewEvents ); Function bool DRV_ETHMAC_PIC32MACEventAcknowledge( DRV_HANDLE hMac, TCPIP_MAC_EVENT tcpAckEv); Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 463 DRV_ETHMAC_PIC32MACEventMaskSet Function Enables/disables the MAC events. Implementation: Dynamic File drv_ethmac.h C bool DRV_ETHMAC_PIC32MACEventMaskSet(DRV_HANDLE hMac, TCPIP_MAC_EVENT macEvents, bool enable); Returns always true, operation succeeded. Description This is a function that enables or disables the events to be reported to the Ethernet MAC client (TCP/IP stack). All events that are to be enabled will be added to the notification process. All events that are to be disabled will be removed from the notification process. The stack has to catch the events that are notified and process them. After that the stack should call DRV_ETHMAC_PIC32MACEventAcknowledge() so that the events can be re-enable The stack should process at least the following transfer events: • TCPIP_MAC_EV_RX_PKTPEND • TCPIP_MAC_EV_RX_DONE • TCPIP_MAC_EV_TX_DONE Remarks • The event notification system enables the user of the TCP/IP stack to call into the stack for processing only when there are relevant events rather than being forced to periodically call from within a loop. • If the notification events are nil, the interrupt processing will be disabled. Otherwise, the event notification will be enabled and the interrupts relating to the requested events will be enabled. • Note that once an event has been caught by the stack ISR (and reported if a notification handler is in place) it will be disabled until the DRV_ETHMAC_PIC32MACEventAcknowledge() is called. Preconditions DRV_ETHMAC_PIC32MACInitialize() should have been called. DRV_ETHMAC_PIC32MACOpen() should have been called to obtain a valid handle. Example DRV_ETHMAC_PIC32MACEventMaskSet( hMac, TCPIP_MAC_EV_RX_OVFLOW | TCPIP_MAC_EV_RX_BUFNA, true ); Function bool DRV_ETHMAC_PIC32MACEventMaskSet( DRV_HANDLE hMac, TCPIP_MAC_EVENT macEvents, bool enable); DRV_ETHMAC_PIC32MACEventPendingGet Function Returns the currently pending events. Implementation: Dynamic File drv_ethmac.h C TCPIP_MAC_EVENT DRV_ETHMAC_PIC32MACEventPendingGet(DRV_HANDLE hMac); Returns The currently stack pending events. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 464 Description This function returns the currently pending Ethernet MAC events. Multiple events will be ORed together as they accumulate. The stack should perform processing whenever a transmission related event (TCPIP_MAC_EV_RX_PKTPEND, TCPIP_MAC_EV_TX_DONE) is present. The other, non critical events, may not be managed by the stack and passed to an user. They will have to be eventually acknowledged if re-enabling is needed. Remarks • This is the preferred method to get the current pending MAC events. The stack maintains a proper image of the events from their occurrence to their acknowledgment. • Even with a notification handler in place it's better to use this function to get the current pending events rather than using the events passed by the notification handler which could be stale. • The events are persistent. They shouldn't be re-enabled unless they have been processed and the condition that generated them was removed. Re-enabling them immediately without proper processing will have dramatic effects on system performance. • The returned value is just a momentary value. The pending events can change any time. Preconditions DRV_ETHMAC_PIC32MACInitialize() should have been called. DRV_ETHMAC_PIC32MACOpen() should have been called to obtain a valid handle. Example TCPIP_MAC_EVENT currEvents = DRV_ETHMAC_PIC32MACEventPendingGet( hMac); Function TCPIP_MAC_EVENT DRV_ETHMAC_PIC32MACEventPendingGet( DRV_HANDLE hMac) e) Other Functions DRV_ETHMAC_Tasks_ISR Function Ethernet MAC driver interrupt function. Implementation: Dynamic File drv_ethmac.h C void DRV_ETHMAC_Tasks_ISR(SYS_MODULE_OBJ macIndex); Returns None. Description This is the Ethernet MAC driver interrupt service routine. It processes the Ethernet related interrupts and notifies the events to the driver user (the TCP/IP stack). Remarks None. Preconditions DRV_ETHMAC_PIC32MACInitialize() should have been called. The TCP/IP stack event notification should be enabled. Function void DRV_ETHMAC_Tasks_ISR( SYS_MODULE_OBJ macIndex ) Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 465 DRV_ETHMAC_PIC32MACTasks Function Maintains the EThernet MAC driver's state machine. Implementation: Dynamic File drv_ethmac.h C void DRV_ETHMAC_PIC32MACTasks(SYS_MODULE_OBJ object); Returns None Description This function is used to maintain the driver's internal state machine Remarks None. Preconditions The DRV_ETHMAC_PIC32MACInitialize routine must have been called for the specified MAC driver instance. Example Function void DRV_ETHMAC_PIC32MACTasks( SYS_MODULE_OBJ object ) f) Data Types and Constants DRV_ETHMAC_INDEX_1 Macro File drv_ethmac.h C #define DRV_ETHMAC_INDEX_1 1 Description This is macro DRV_ETHMAC_INDEX_1. DRV_ETHMAC_INDEX_0 Macro Ethernet driver index definitions. File drv_ethmac.h C #define DRV_ETHMAC_INDEX_0 0 Description Ethernet Driver Module Index Numbers These constants provide Ethernet driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the MAC initialization routines to identify the driver instance in use. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 466 DRV_ETHMAC_INDEX_COUNT Macro Number of valid Ethernet driver indices. File drv_ethmac.h C #define DRV_ETHMAC_INDEX_COUNT ETH_NUMBER_OF_MODULES Description Ethernet Driver Module Index Count This constant identifies number of valid Ethernet driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from part-specific header files defined as part of the peripheral libraries. Files Files Name Description drv_ethmac.h Ethernet MAC device driver interface file drv_ethmac_config.h Ethernet MAC driver configuration definitions template. Description This section lists the source and header files used by the Ethernet MAC Driver Library. drv_ethmac.h Ethernet MAC device driver interface file Functions Name Description DRV_ETHMAC_PIC32MACClose Closes a client instance of the PIC32 MAC Driver. Implementation: Dynamic DRV_ETHMAC_PIC32MACConfigGet Gets the current MAC driver configuration. Implementation: Dynamic DRV_ETHMAC_PIC32MACDeinitialize Deinitializes the PIC32 Ethernet MAC. Implementation: Dynamic DRV_ETHMAC_PIC32MACEventAcknowledge Acknowledges and re-enables processed events. Implementation: Dynamic DRV_ETHMAC_PIC32MACEventMaskSet Enables/disables the MAC events. Implementation: Dynamic DRV_ETHMAC_PIC32MACEventPendingGet Returns the currently pending events. Implementation: Dynamic DRV_ETHMAC_PIC32MACInitialize Initializes the PIC32 Ethernet MAC. Implementation: Dynamic DRV_ETHMAC_PIC32MACLinkCheck Checks current link status. Implementation: Dynamic DRV_ETHMAC_PIC32MACOpen Opens a client instance of the PIC32 MAC Driver. Implementation: Dynamic DRV_ETHMAC_PIC32MACPacketRx This is the MAC receive function. Implementation: Dynamic DRV_ETHMAC_PIC32MACPacketTx MAC driver transmit function. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 467 DRV_ETHMAC_PIC32MACParametersGet MAC parameter get function. Implementation: Dynamic DRV_ETHMAC_PIC32MACPowerMode Selects the current power mode for the Ethernet MAC. Implementation: Dynamic DRV_ETHMAC_PIC32MACProcess MAC periodic processing function. Implementation: Dynamic DRV_ETHMAC_PIC32MACRegisterStatisticsGet Gets the current MAC hardware statistics registers. Implementation: Dynamic DRV_ETHMAC_PIC32MACReinitialize Reinitializes the PIC32 Ethernet MAC. Implementation: Dynamic DRV_ETHMAC_PIC32MACRxFilterHashTableEntrySet Sets the current MAC hash table receive filter. Implementation: Dynamic DRV_ETHMAC_PIC32MACStatisticsGet Gets the current MAC statistics. Implementation: Dynamic DRV_ETHMAC_PIC32MACStatus Provides the current status of the MAC driver module. Implementation: Dynamic DRV_ETHMAC_PIC32MACTasks Maintains the EThernet MAC driver's state machine. Implementation: Dynamic DRV_ETHMAC_Tasks_ISR Ethernet MAC driver interrupt function. Implementation: Dynamic Macros Name Description DRV_ETHMAC_INDEX_0 Ethernet driver index definitions. DRV_ETHMAC_INDEX_1 This is macro DRV_ETHMAC_INDEX_1. DRV_ETHMAC_INDEX_COUNT Number of valid Ethernet driver indices. Description Ethernet MAC Device Driver Interface The Ethernet MAC device driver provides a simple interface to manage the Ethernet peripheral. This file defines the interface definitions and prototypes for the Ethernet MAC driver. File Name drv_ethmac.h Company Microchip Technology Inc. drv_ethmac_config.h Ethernet MAC driver configuration definitions template. Macros Name Description DRV_ETHMAC_CLIENTS_NUMBER Selects the maximum number of clients. DRV_ETHMAC_INDEX Ethernet MAC static index selection. DRV_ETHMAC_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver. DRV_ETHMAC_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_ETHMAC_INTERRUPT_SOURCE Defines an override of the interrupt source in case of static driver. DRV_ETHMAC_PERIPHERAL_ID Defines an override of the peripheral ID. DRV_ETHMAC_POWER_STATE Defines an override of the power state of the Ethernet MAC driver. Description ETHMAC Driver Configuration Definitions for the template version These definitions statically define the driver's mode of operation. File Name drv_ethmac_config.h Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet MAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 468 Company Microchip Technology Inc. Ethernet PHY Driver Library This section describes the Ethernet PHY Driver Library. Introduction This library provides a low-level abstraction of the Ethernet PHY Driver 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 This library provides a software abstraction for configuring external Ethernet PHY devices for use with the on-chip PIC32 Ethernet Controller. Using the Library The user of this driver is the MPLAB Harmony TCP/IP Stack through its Ethernet MAC driver. This Ethernet PHY driver is not intended as a system wide driver that the application or other system modules may use. It is intended for the sole use of the MPLAB Harmony TCP/IP stack and implements the PHY driver required by the Ethernet MAC. This topic describes the basic architecture and functionality of the Ethernet PHY driver and is meant for advanced users or TCP/IP Stack driver developers. Interface Header File: drv_ethphy.h The interface to the Ethernet PHY library is defined in the drv_ethphy.h header file, which is included by the MPLAB Harmony TCP/IP stack. Please refer to the What is MPLAB Harmony? section for how the library interacts with the framework. Abstraction Model This library provides a low-level abstraction of the Ethernet PHY Driver Library 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 To understand how this library works you must first understand how an external Ethernet PHY interfaces with the Ethernet Controller. As shown in Figure 1, the PHY has two interfaces, one for managing the PHY, known as the Serial Management Interface (SMI), for configuring the device and a second, known as the Reduced Media Independent Interface (RMII), for transmit and receive data. Figure 1: Typical External PHY Interface Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 469 The block diagram also shows an interrupt signal (nINT) going to a external interrupt pin on the host device and signals going to on-board LEDs to show link state and link activity. The SMI interface is also known as the MII Management (MIIM) interface. This control interface is standardized for all PHYs by Clause 22 of the 802.3 standard. It provides up to 32 16-bit registers on the PHY. The following table provides a summary of all 32 registers. Consult the data sheet for the PHY device for the specific bit fields in each register. Register Address Register Name Register Type 0 Control Basic 1 Status Basic 2, 3 PHY Identifier Extended 4 Auto-Negotiation Advertisement Extended 5 Auto-Negotiation Link Partner Base Page Ability Extended 6 Auto-Negotiation Expansion Extended 7 Auto-Negotiation Next Page Transmit Extended 8 Auto-Negotiation Link Partner Received Next Page Extended 9 MASTER-SLAVE Control Register Extended 10 MASTER-SLAVE Status Register Extended 11-14 Reserved Extended 15 Extended Status Reserved 16-31 Vendor Specific Extended Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 470 Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Ethernet PHY Driver Library Library Interface Section Description System Level Functions Routines that integrate the driver into the MPLAB Harmony framework. Client Level Functions Open, Close, Link Status, Auto Negotiation. SMI/MIIM Functions SMI/MIIM Management Interface. External PHY Support Functions Provides the API for PHY support routines that the driver will call when setting up the PHY. The driver library provides support for four PHYs. Other Functions Functions that provide software version information. Data Types and Constants C language typedefs and enums used by this library. Configuring the Library Macros Name Description DRV_ETHPHY_CLIENTS_NUMBER Selects the maximum number of clients. DRV_ETHPHY_INDEX Ethernet PHY static index selection. DRV_ETHPHY_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver. DRV_ETHPHY_PERIPHERAL_ID Defines an override of the peripheral ID. DRV_ETHPHY_NEG_DONE_TMO Value of the PHY negotiation complete time out as per IEEE 802.3 spec. DRV_ETHPHY_NEG_INIT_TMO Value of the PHY negotiation initiation time out as per IEEE 802.3 spec. DRV_ETHPHY_RESET_CLR_TMO Value of the PHY Reset self clear time out as per IEEE 802.3 spec. Description The configuration of the Ethernet PHY Driver Library is based on the file system_config.h. This header file contains the configuration selection for the Ethernet PHY Driver Library. Based on the selections made, the Ethernet PHY Driver Library may support the selected features. 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. DRV_ETHPHY_CLIENTS_NUMBER Macro Selects the maximum number of clients. File drv_ethphy_config.h C #define DRV_ETHPHY_CLIENTS_NUMBER 1 Description Ethernet PHY Maximum Number of Clients This definition select the maximum number of clients that the Ethernet PHY driver can support at run time. Not defining it means using a single client. Remarks The MAC driver is the client of the PHY driver. Multiple clients may be needed when access to MIIM bus (for PHY vendor specific functionality) is needed through the PHY driver. However MIIM operations are not supported when the PHY driver uses the MIIM driver for MIIM bus accesses. In this case the number of clients should be 1 and the DRV_MIIM should be used for accessing the MIIM bus. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 471 DRV_ETHPHY_INDEX Macro Ethernet PHY static index selection. File drv_ethphy_config.h C #define DRV_ETHPHY_INDEX DRV_ETHPHY_INDEX_1 Description Ethernet PHY Static Index Selection This definition selects the Ethernet PHY static index for the driver object reference. Remarks This index is required to make a reference to the driver object. DRV_ETHPHY_INSTANCES_NUMBER Macro Selects the maximum number of hardware instances that can be supported by the dynamic driver. File drv_ethphy_config.h C #define DRV_ETHPHY_INSTANCES_NUMBER 1 Description Ethernet PHY hardware instance configuration This definition selects the maximum number of hardware instances that can be supported by the dynamic driver. Not defining it means using a static driver. Remarks None. DRV_ETHPHY_PERIPHERAL_ID Macro Defines an override of the peripheral ID. File drv_ethphy_config.h C #define DRV_ETHPHY_PERIPHERAL_ID ETHPHY_ID_1 Description Ethernet PHY Peripheral ID Selection Defines an override of the peripheral ID, using macros. Remarks Some devices also support ETHPHY_ID_0 DRV_ETHPHY_NEG_DONE_TMO Macro Value of the PHY negotiation complete time out as per IEEE 802.3 spec. File drv_ethphy_config.h Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 472 C #define DRV_ETHPHY_NEG_DONE_TMO (2000) Description Ethernet PHY Negotiation Complete time out This definition sets the time out of the PHY negotiation complete, in ms. Remarks See IEEE 802.3 Clause 28 Table 28-9 autoneg_wait_timer value (max 1s). DRV_ETHPHY_NEG_INIT_TMO Macro Value of the PHY negotiation initiation time out as per IEEE 802.3 spec. File drv_ethphy_config.h C #define DRV_ETHPHY_NEG_INIT_TMO (1) Description Ethernet PHY Negotiation Initiation time out This definition sets the time out of the PHY negotiation initiation, in ms. Remarks None. DRV_ETHPHY_RESET_CLR_TMO Macro Value of the PHY Reset self clear time out as per IEEE 802.3 spec. File drv_ethphy_config.h C #define DRV_ETHPHY_RESET_CLR_TMO (500) Description Ethernet PHY Reset self clear time out This definition sets the time out of the PHY Reset self clear, in ms. Remarks See IEEE 802.3 Clause 22 Table 22-7 and paragraph "22.2.4.1.1 Reset" (max 0.5s) Building the Library This section lists the files that are available in the Ethernet PHY Driver Library. 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 /framework/driver/ethphy. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_ethphy.h Header file that exports the driver API. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 473 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 /src/dynamic/drv_extphy.c Basic PHY driver implementation file. 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 /src/dynamic/drv_extphy_smsc8700.c SMSC 8700 PHY implementation file. /src/dynamic/drv_extphy_smsc8720.c SMSC 8720 PHY implementation file. /src/dynamic/drv_extphy_smsc8720.c SMSC 8740 PHY implementation file. /src/dynamic/drv_extphy_ip101gr.c IP101GR PHY implementation file. /src/dynamic/drv_extphy_dp83640.c National DP83640 PHY implementation file. /src/dynamic/drv_extphy_dp83848.c National DP83848 PHY implementation file. Module Dependencies The Ethernet MAC Driver Library depends on the following modules: • Ethernet MAC Driver Library • Clock System Service Library • Ports System Service Library • Timer System Service Library • Ethernet Peripheral Library Library Interface a) System Level Functions Name Description DRV_ETHPHY_Initialize Initializes the Ethernet PHY driver. Implementation: Dynamic DRV_ETHPHY_Deinitialize Deinitializes the specified instance of the Ethernet PHY driver module. Implementation: Dynamic DRV_ETHPHY_Reinitialize Reinitializes the driver and refreshes any associated hardware settings. Implementation: Dynamic DRV_ETHPHY_Status Provides the current status of the Ethernet PHY driver module. Implementation: Dynamic DRV_ETHPHY_Tasks Maintains the driver's state machine and implements its ISR. Implementation: Dynamic DRV_ETHPHY_HWConfigFlagsGet Returns the current Ethernet PHY hardware MII/RMII and ALTERNATE/DEFAULT configuration flags. Implementation: Dynamic DRV_ETHPHY_Setup Initializes Ethernet PHY configuration and set up procedure. Implementation: Dynamic b) Client Level Functions Name Description DRV_ETHPHY_ClientStatus Gets the current client-specific status the Ethernet PHY driver. Implementation: Dynamic DRV_ETHPHY_Close Closes an opened instance of the Ethernet PHY driver. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 474 DRV_ETHPHY_Open Opens the specified Ethernet PHY driver instance and returns a handle to it. Implementation: Dynamic DRV_ETHPHY_Reset Immediately resets the Ethernet PHY. Implementation: Dynamic DRV_ETHPHY_ClientOperationAbort Aborts a current client operation initiated by the Ethernet PHY driver. Implementation: Dynamic DRV_ETHPHY_ClientOperationResult Gets the result of a client operation initiated by the Ethernet PHY driver. Implementation: Dynamic c) SMI/MIIM Functions Name Description DRV_ETHPHY_SMIScanStatusGet Gets the status of the SMI/MIIM scan data. Implementation: Dynamic DRV_ETHPHY_SMIScanStop Stops the scan of a previously requested SMI/MIIM register. Implementation: Dynamic DRV_ETHPHY_SMIClockSet Sets the SMI/MIIM interface clock. Implementation: Dynamic DRV_ETHPHY_SMIScanStart Starts the scan of a requested SMI/MIIM register. Implementation: Dynamic DRV_ETHPHY_SMIRead Initiates a SMI/MIIM read transaction. Implementation: Dynamic DRV_ETHPHY_SMIScanDataGet Gets the latest SMI/MIIM scan data result. Implementation: Dynamic DRV_ETHPHY_SMIStatus Returns the current status of the SMI/MIIM interface. Implementation: Dynamic DRV_ETHPHY_SMIWrite Initiates a SMI/MIIM write transaction. Implementation: Dynamic d) Vendor Functions Name Description DRV_ETHPHY_VendorDataGet Returns the current value of the vendor data. Implementation: Dynamic DRV_ETHPHY_VendorDataSet Returns the current value of the vendor data. Implementation: Dynamic DRV_ETHPHY_VendorSMIReadResultGet Reads the result of a previous vendor initiated SMI read transfer with DRV_ETHPHY_VendorSMIReadStart. Implementation: Dynamic DRV_ETHPHY_VendorSMIReadStart Starts a vendor SMI read transfer. Data will be available with DRV_ETHPHY_VendorSMIReadResultGet. Implementation: Dynamic DRV_ETHPHY_VendorSMIWriteStart Starts a vendor SMI write transfer. Implementation: Dynamic e) Other Functions Name Description DRV_ETHPHY_LinkStatusGet Returns the current link status. Implementation: Dynamic DRV_ETHPHY_NegotiationIsComplete Returns the results of a previously initiated Ethernet PHY negotiation. Implementation: Dynamic DRV_ETHPHY_NegotiationResultGet Returns the result of a completed negotiation. Implementation: Dynamic DRV_ETHPHY_PhyAddressGet Returns the PHY address. Implementation: Dynamic DRV_ETHPHY_RestartNegotiation Restarts auto-negotiation of the Ethernet PHY link. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 475 f) Data Types and Constants Name Description DRV_ETHPHY_CLIENT_STATUS Identifies the client-specific status of the Ethernet PHY driver. DRV_ETHPHY_INIT Contains all the data necessary to initialize the Ethernet PHY device. DRV_ETHPHY_NEGOTIATION_RESULT Contains all the data necessary to get the Ethernet PHY negotiation result DRV_ETHPHY_SETUP Contains all the data necessary to set up the Ethernet PHY device. DRV_ETHPHY_VENDOR_MDIX_CONFIGURE Pointer to function that configures the MDIX mode for the Ethernet PHY. DRV_ETHPHY_VENDOR_MII_CONFIGURE Pointer to function to configure the Ethernet PHY in one of the MII/RMII operation modes. DRV_ETHPHY_VENDOR_SMI_CLOCK_GET Pointer to a function to return the SMI/MIIM maximum clock speed in Hz of the Ethernet PHY. DRV_ETHPHY_INDEX_0 Ethernet PHY driver index definitions. DRV_ETHPHY_INDEX_1 This is macro DRV_ETHPHY_INDEX_1. DRV_ETHPHY_INDEX_COUNT Number of valid Ethernet PHY driver indices. DRV_ETHPHY_LINK_STATUS Defines the possible status flags of PHY Ethernet link. DRV_ETHPHY_CONFIG_FLAGS Defines configuration options for the Ethernet PHY. DRV_ETHPHY_OBJECT Identifies the interface of a Ethernet PHY vendor driver. DRV_ETHPHY_VENDOR_WOL_CONFIGURE Pointer to a function to configure the PHY WOL functionality DRV_ETHPHY_OBJECT_BASE_TYPE Identifies the base interface of a Ethernet PHY driver. DRV_ETHPHY_OBJECT_BASE Identifies the base interface of a Ethernet PHY driver. DRV_ETHPHY_RESET_FUNCTION Pointer to a function to perform an additional PHY reset DRV_ETHPHY_RESULT Defines the possible results of Ethernet operations that can succeed or fail DRV_ETHPHY_USE_DRV_MIIM Defines the way the PHY driver accesses the MIIM bus to communicate with the PHY. DRV_ETHPHY_INTERFACE_INDEX Defines the index type for a PHY interface. DRV_ETHPHY_INTERFACE_TYPE Defines the type of interface a PHY supports. Description This section describes the Application Programming Interface (API) functions of the Ethernet PHY Driver Library. Refer to each section for a detailed description. a) System Level Functions DRV_ETHPHY_Initialize Function Initializes the Ethernet PHY driver. Implementation: Dynamic File drv_ethphy.h C SYS_MODULE_OBJ DRV_ETHPHY_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns • a valid handle to a driver object, if successful. • SYS_MODULE_OBJ_INVALID if initialization failed. Description This function initializes the Ethernet PHY driver, making it ready for clients to open and use it. Remarks • This function must be called before any other Ethernet PHY routine is called. • This function should only be called once during system initialization unless DRV_ETHPHY_Deinitialize is called to deinitialize the driver instance. • The returned object must be passed as argument to DRV_ETHPHY_Reinitialize, DRV_ETHPHY_Deinitialize, DRV_ETHPHY_Tasks and DRV_ETHPHY_Status routines. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 476 Preconditions None. Example DRV_ETHPHY_INIT init; SYS_MODULE_OBJ objectHandle; // Populate the Ethernet PHY initialization structure init.phyId = ETHPHY_ID_0; // Populate the Ethernet PHY initialization structure init.phyId = ETHPHY_ID_2; init.pPhyObject = &DRV_ETHPHY_OBJECT_SMSC_LAN8720; // Do something objectHandle = DRV_ETHPHY_Initialize(DRV_ETHPHY_INDEX_0, (SYS_MODULE_INIT*)&init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Function SYS_MODULE_OBJ DRV_ETHPHY_Initialize( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ) DRV_ETHPHY_Deinitialize Function Deinitializes the specified instance of the Ethernet PHY driver module. Implementation: Dynamic File drv_ethphy.h C void DRV_ETHPHY_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description This function deinitializes the specified instance of the Ethernet PHY driver module, disabling its operation (and any hardware) and invalidates all of the internal data. Remarks • Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. Preconditions The DRV_ETHPHY_Initialize function must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Example SYS_MODULE_OBJ object; // Returned from DRV_ETHPHY_Initialize SYS_STATUS status; DRV_ETHPHY_Deinitialize(object); status = DRV_ETHPHY_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 477 Function void DRV_ETHPHY_Deinitialize ( SYS_MODULE_OBJ object ) DRV_ETHPHY_Reinitialize Function Reinitializes the driver and refreshes any associated hardware settings. Implementation: Dynamic File drv_ethphy.h C void DRV_ETHPHY_Reinitialize(SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init); Returns None. Description This function reinitializes the driver and refreshes any associated hardware settings using the initialization data given, but it will not interrupt any ongoing operations. Remarks • This function can be called multiple times to reinitialize the module. • This operation can be used to refresh any supported hardware registers as specified by the initialization data or to change the power state of the module. Preconditions The DRV_ETHPHY_Initialize function must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Example DRV_ETHPHY_INIT init; SYS_MODULE_OBJ objectHandle; // Populate the Ethernet PHY initialization structure init.phyId = ETHPHY_ID_2; init.pPhyObject = &DRV_ETHPHY_OBJECT_SMSC_LAN8720; DRV_ETHPHY_Reinitialize(objectHandle, (SYS_MODULE_INIT*)&init); phyStatus = DRV_ETHPHY_Status(objectHandle); if (SYS_STATUS_BUSY == phyStatus) { // Check again later to ensure the driver is ready } else if (SYS_STATUS_ERROR >= phyStatus) { // Handle error } Function void DRV_ETHPHY_Reinitialize( SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init ) DRV_ETHPHY_Status Function Provides the current status of the Ethernet PHY driver module. Implementation: Dynamic File drv_ethphy.h Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 478 C SYS_STATUS DRV_ETHPHY_Status(SYS_MODULE_OBJ object); Returns • SYS_STATUS_READY - Indicates that any previous module operation for the specified module has completed • SYS_STATUS_BUSY - Indicates that a previous module operation for the specified module has not yet completed • SYS_STATUS_ERROR - Indicates that the specified module is in an error state Description This function provides the current status of the Ethernet PHY driver module. Remarks • Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. • SYS_STATUS_BUSY - Indicates that the driver is busy with a previous system level operation and cannot start another • SYS_STATUS_ERROR - Indicates that the driver is in an error state • Any value less than SYS_STATUS_ERROR is also an error state. • SYS_MODULE_DEINITIALIZED - Indicates that the driver has been deinitialized • The this operation can be used to determine when any of the driver's module level operations has completed. • If the status operation returns SYS_STATUS_BUSY, the a previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. • The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. • This function will NEVER block waiting for hardware. • If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Preconditions The DRV_ETHPHY_Initialize function must have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_ETHPHY_Initialize SYS_STATUS status; status = DRV_ETHPHY_Status(object); if (SYS_STATUS_ERROR >= status) { // Handle error } Parameters Parameters Description object Driver object handle, returned from DRV_ETHPHY_Initialize Function SYS_STATUS DRV_ETHPHY_Status ( SYS_MODULE_OBJ object ) DRV_ETHPHY_Tasks Function Maintains the driver's state machine and implements its ISR. Implementation: Dynamic File drv_ethphy.h C void DRV_ETHPHY_Tasks(SYS_MODULE_OBJ object); Returns None Description This function is used to maintain the driver's internal state machine and implement its ISR for interrupt-driven implementations. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 479 Remarks • This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) • This function will never block or access any resources that may cause it to block. Preconditions The DRV_ETHPHY_Initialize routine must have been called for the specified Ethernet PHY driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_ETHPHY_Initialize while (true) { DRV_ETHPHY_Tasks (object); // Do other tasks } Function void DRV_ETHPHY_Tasks( SYS_MODULE_OBJ object ) DRV_ETHPHY_HWConfigFlagsGet Function Returns the current Ethernet PHY hardware MII/RMII and ALTERNATE/DEFAULT configuration flags. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_HWConfigFlagsGet(DRV_HANDLE handle, DRV_ETHPHY_CONFIG_FLAGS* pFlags); Returns DRV_ETHPHY_RES_OK - if the configuration flags successfully stored at pFlags DRV_ETHPHY_RESULT error code otherwise Description This function returns the current Ethernet PHY hardware MII/RMII and ALTERNATE/DEFAULT configuration flags from the Device Configuration Fuse bits. Remarks None. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY Example Parameters Parameters Description handle Client's driver handle (returned from DRV_ETHPHY_Open) pFlags address to store the hardware configuration Function DRV_ETHPHY_RESULT DRV_ETHPHY_HWConfigFlagsGet( DRV_HANDLE handle, DRV_ETHPHY_CONFIG_FLAGS* pFlags ) DRV_ETHPHY_Setup Function Initializes Ethernet PHY configuration and set up procedure. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 480 File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_Setup(DRV_HANDLE handle, DRV_ETHPHY_SETUP* pSetUp, TCPIP_ETH_OPEN_FLAGS* pSetupFlags); Returns • DRV_ETHPHY_RES_PENDING operation has been scheduled successfully • an DRV_ETHPHY_RESULT error code if the set up procedure failed. Description This function initializes the Ethernet PHY communication. It tries to detect the external Ethernet PHY, to read the capabilities and find a match with the requested features. Then, it programs the Ethernet PHY accordingly. Remarks PHY configuration may be a lengthy operation due to active negotiation that the PHY has to perform with the link party. The DRV_ETHPHY_ClientStatus will repeatedly return DRV_ETHPHY_CLIENT_STATUS_BUSY until the set up procedure is complete (unless an error detected at which an error code will be returned immediately). Use DRV_ETHPHY_ClientStatus() and DRV_ETHPHY_ClientOperationResult() to check when the operation was completed and its outcome. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_Setup( DRV_HANDLE handle, DRV_ETHPHY_SETUP* pSetUp, TCPIP_ETH_OPEN_FLAGS* pSetupFlags) b) Client Level Functions DRV_ETHPHY_ClientStatus Function Gets the current client-specific status the Ethernet PHY driver. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_CLIENT_STATUS DRV_ETHPHY_ClientStatus(DRV_HANDLE handle); Returns • DRV_ETHPHY_CLIENT_STATUS value describing the current status of the driver. Description This function gets the client-specific status of the Ethernet PHY driver associated with the given handle. Remarks This function will not block for hardware access and will immediately return the current status. This function has to be used to check that a driver operation has completed. It will return DRV_ETHPHY_CLIENT_STATUS_BUSY when an operation is in progress. It will return DRV_ETHPHY_CLIENT_STATUS_READY when the operation has completed. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE phyHandle; // Returned from DRV_ETHPHY_Open Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 481 DRV_ETHPHY_CLIENT_STATUS phyClientStatus; phyClientStatus = DRV_ETHPHY_ClientStatus(phyHandle); if(DRV_ETHPHY_CLIENT_STATUS_ERROR >= phyClientStatus) { // Handle the error } Function DRV_ETHPHY_CLIENT_STATUS DRV_ETHPHY_ClientStatus( DRV_HANDLE handle ) DRV_ETHPHY_Close Function Closes an opened instance of the Ethernet PHY driver. Implementation: Dynamic File drv_ethphy.h C void DRV_ETHPHY_Close(DRV_HANDLE handle); Returns None Description This function closes an opened instance of the Ethernet PHY driver, invalidating the handle. Remarks • After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_ETHPHY_Open before the caller may use the driver again. • Usually there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_ETHPHY_Initialize routine must have been called for the specified Ethernet PHY driver instance. DRV_ETHPHY_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_ETHPHY_Open DRV_ETHPHY_Close(handle); Function void DRV_ETHPHY_Close( DRV_HANDLE handle ) DRV_ETHPHY_Open Function Opens the specified Ethernet PHY driver instance and returns a handle to it. Implementation: Dynamic File drv_ethphy.h C DRV_HANDLE DRV_ETHPHY_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); Returns • valid open-instance handle if successful (a number identifying both the caller and the module instance). • DRV_HANDLE_INVALID if an error occurs Description This function opens the specified Ethernet PHY driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 482 Remarks The handle returned is valid until the DRV_ETHPHY_Close routine is called. This function will NEVER block waiting for hardware. The intent parameter is not used. The PHY driver implements a non-blocking behavior. Preconditions The DRV_ETHPHY_Initialize function must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_ETHPHY_Open(DRV_ETHPHY_INDEX_0, 0); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } Function DRV_HANDLE DRV_ETHPHY_Open( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ) DRV_ETHPHY_Reset Function Immediately resets the Ethernet PHY. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_Reset(DRV_HANDLE handle, bool waitComplete); Returns • DRV_ETHPHY_RES_PENDING for ongoing, in progress operation • DRV_ETHPHY_RES_OPERATION_ERR - invalid parameter or operation in the current context Description This function immediately resets the Ethernet PHY, optionally waiting for a reset to complete. Remarks Use DRV_ETHPHY_ClientStatus() and DRV_ETHPHY_ClientOperationResult() to check when the operation was completed and its outcome. When operation is completed but failed, DRV_ETHPHY_ClientOperationResult will return: • DRV_ETHPHY_RES_DTCT_ERR if the PHY failed to respond Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_Reset( DRV_HANDLE handle, bool waitComplete ) DRV_ETHPHY_ClientOperationAbort Function Aborts a current client operation initiated by the Ethernet PHY driver. Implementation: Dynamic File drv_ethphy.h Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 483 C DRV_ETHPHY_RESULT DRV_ETHPHY_ClientOperationAbort(DRV_HANDLE handle); Returns • DRV_ETHPHY_RESULT value describing the current operation result: DRV_ETHPHY_RES_OK for success; operation has been aborted an DRV_ETHPHY_RESULT error code if the operation failed. Description Aborts a current client operation initiated by the Ethernet PHY driver. Remarks None Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid opened device handle. • A driver operation was started Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_ClientOperationAbort( DRV_HANDLE handle) DRV_ETHPHY_ClientOperationResult Function Gets the result of a client operation initiated by the Ethernet PHY driver. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_ClientOperationResult(DRV_HANDLE handle); Returns • DRV_ETHPHY_RESULT value describing the current operation result: DRV_ETHPHY_RES_OK for success; operation has been completed successfully DRV_ETHPHY_RES_PENDING operation is in progress an DRV_ETHPHY_RESULT error code if the operation failed. Description Returns the result of a client operation initiated by the Ethernet PHY driver. Remarks This function will not block for hardware access and will immediately return the current status. This function returns the result of the last driver operation. It will return DRV_ETHPHY_RES_PENDING if an operation is still in progress. Otherwise a DRV_ETHPHY_RESULT describing the operation outcome. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid opened device handle. • A driver operation was started and completed Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_ClientOperationResult( DRV_HANDLE handle) c) SMI/MIIM Functions DRV_ETHPHY_SMIScanStatusGet Function Gets the status of the SMI/MIIM scan data. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 484 Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_SMIScanStatusGet(DRV_HANDLE handle); Returns DRV_ETHPHY_RES_OPERATION_ERR - no scan operation currently in progress DRV_ETHPHY_RES_OK - scan data is available DRV_ETHPHY_RES_PENDING - scan data is not yet available < 0 - an error has occurred and the operation could not be completed Description This function gets the status of the SMI/MIIM scan data. Remarks This operation is not supported when the PHY driver uses the MIIM driver for MIIM bus accesses. Use the DRV_MIIM for accessing the MIIM bus. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY • DRV_ETHPHY_SMIScanStart() has been called. Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_SMIScanStatusGet( DRV_HANDLE handle ) DRV_ETHPHY_SMIScanStop Function Stops the scan of a previously requested SMI/MIIM register. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_SMIScanStop(DRV_HANDLE handle); Returns DRV_ETHPHY_RES_OPERATION_ERR - no scan operation currently in progress DRV_ETHPHY_RES_OK - the scan transaction has been stopped successfully < 0 - an error has occurred and the operation could not be completed Description This function stops the current scan of a SMI/MIIM register. Remarks This operation is not supported when the PHY driver uses the MIIM driver for MIIM bus accesses. Use the DRV_MIIM for accessing the MIIM bus. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY • DRV_ETHPHY_SMIScanStart was called to start a scan Example Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 485 Function DRV_ETHPHY_RESULT DRV_ETHPHY_SMIScanStop( DRV_HANDLE handle ) DRV_ETHPHY_SMIClockSet Function Sets the SMI/MIIM interface clock. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_SMIClockSet(DRV_HANDLE handle, uint32_t hostClock, uint32_t maxSMIClock); Returns DRV_ETHPHY_RES_HANDLE_ERR - passed in handle was invalid DRV_ETHPHY_RES_OK - operation successful < 0 - an error has occurred and the operation could not be completed Description This function sets SMI/MIIM interface clock base on host clock and maximum supported SMI/MIIM interface clock speed. Remarks This operation is not supported when the PHY driver uses the MIIM driver for MIIM bus accesses. Use the DRV_MIIM for accessing the MIIM bus. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_SMIClockSet( DRV_HANDLE handle, uint32_t hostClock, uint32_t maxSMIClock ) DRV_ETHPHY_SMIScanStart Function Starts the scan of a requested SMI/MIIM register. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_SMIScanStart(DRV_HANDLE handle, unsigned int rIx); Returns DRV_ETHPHY_RES_PENDING - the scan transaction was initiated and is ongoing < 0 - an error has occurred and the operation could not be completed Description This function starts the scan of a requested SMI/MIIM register. Remarks Use DRV_ETHPHY_ClientStatus() and DRV_ETHPHY_ClientOperationResult() to check when the operation was completed and its outcome. However, the client status will always be DRV_ETHPHY_CLIENT_STATUS_BUSY and the client result will always show DRV_ETHPHY_RES_PENDING for as long as the scan is active. Use DRV_ETHPHY_SMIScanStop() to stop a scan in progress. Use DRV_ETHPHY_SMIScanStatusGet() to check is there is scan data available. Use DRV_ETHPHY_SMIScanDataGet() to retrieve the scan data. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 486 This operation is not supported when the PHY driver uses the MIIM driver for MIIM bus accesses. Use the DRV_MIIM for accessing the MIIM bus. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_SMIScanStart( DRV_HANDLE handle, unsigned int rIx) DRV_ETHPHY_SMIRead Function Initiates a SMI/MIIM read transaction. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_SMIRead(DRV_HANDLE handle, unsigned int rIx, uint16_t* pSmiRes, int phyAdd); Returns DRV_ETHPHY_RES_PENDING - the transaction was initiated and is ongoing < 0 - an error has occurred and the operation could not be completed Description This function initiates a SMI/MIIM read transaction for a given PHY register. Remarks In most situations the PHY address to be used for this function should be the one returned by DRV_ETHPHY_PhyAddressGet(). However this function allows using a different PHY address for advanced operation. Use DRV_ETHPHY_ClientStatus() and DRV_ETHPHY_ClientOperationResult() to check when the operation was completed and its outcome. This operation is not supported when the PHY driver uses the MIIM driver for MIIM bus accesses. Use the DRV_MIIM for accessing the MIIM bus. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid opened device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_SMIRead( DRV_HANDLE handle, unsigned int rIx, uint16_t* pSmiRes, int phyAdd) DRV_ETHPHY_SMIScanDataGet Function Gets the latest SMI/MIIM scan data result. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_SMIScanDataGet(DRV_HANDLE handle, uint16_t* pScanRes); Returns DRV_ETHPHY_RES_OPERATION_ERR - no scan operation currently in progress DRV_ETHPHY_RES_OK - scan data is available and stored at pScanRes DRV_ETHPHY_RES_PENDING - scan data is not yet available < 0 - an error has occurred and the operation could not be completed Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 487 Description This function gets the latest SMI/MIIM scan data result. Remarks This operation is not supported when the PHY driver uses the MIIM driver for MIIM bus accesses. Use the DRV_MIIM for accessing the MIIM bus. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY • DRV_ETHPHY_SMIScanStart() has been called • Data is available if DRV_ETHPHY_SMIScanStatusGet() previously returned DRV_ETHPHY_RES_OK Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_SMIScanDataGet( DRV_HANDLE handle, uint16_t* pScanRes ) DRV_ETHPHY_SMIStatus Function Returns the current status of the SMI/MIIM interface. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_SMIStatus(DRV_HANDLE handle); Returns • DRV_ETHPHY_RES_BUSY - if the SMI/MIIM interface is busy • DRV_ETHPHY_RES_OK - if the SMI/MIIM is not busy < 0 - an error has occurred and the operation could not be completed Description This function checks if the SMI/MIIM interface is busy with a transaction. Remarks This function is info only and returns the momentary status of the SMI bus. Even if the bus is free there is no guarantee it will be free later on especially if the driver is on going some operation. This operation is not supported when the PHY driver uses the MIIM driver for MIIM bus accesses. Use the DRV_MIIM for accessing the MIIM bus. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_SMIStatus( DRV_HANDLE handle ) DRV_ETHPHY_SMIWrite Function Initiates a SMI/MIIM write transaction. Implementation: Dynamic File drv_ethphy.h Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 488 C DRV_ETHPHY_RESULT DRV_ETHPHY_SMIWrite(DRV_HANDLE handle, unsigned int rIx, uint16_t wData, int phyAdd, bool waitComplete); Returns DRV_ETHPHY_RES_OK - the write transaction has been scheduled/completed successfully DRV_ETHPHY_RES_PENDING - the transaction was initiated and is ongoing < 0 - an error has occurred and the operation could not be completed Description This function initiates a SMI/MIIM write transaction for a given PHY register. Remarks In most situations the PHY address to be used for this function should be the one returned by DRV_ETHPHY_PhyAddressGet(). However this function allows using a different PHY address for advanced operation. Use DRV_ETHPHY_ClientStatus() and DRV_ETHPHY_ClientOperationResult() to check when the operation was completed and its outcome. This operation is not supported when the PHY driver uses the MIIM driver for MIIM bus accesses. Use the DRV_MIIM for accessing the MIIM bus. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_SMIWrite( DRV_HANDLE handle, unsigned int rIx, uint16_t wData, int phyAdd, bool waitComplete) d) Vendor Functions DRV_ETHPHY_VendorDataGet Function Returns the current value of the vendor data. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_VendorDataGet(DRV_HANDLE handle, uint32_t* pVendorData); Returns DRV_ETHPHY_RES_OK - if the vendor data is stored at the pVendorData address DRV_ETHPHY_RES_HANDLE_ERR - handle error Description This function returns the current value of the vendor data. Each DRV_ETHPHY client object maintains data that could be used for vendor specific operations. This routine allows retrieving of the vendor specific data. Remarks The PHY driver will clear the vendor specific data before any call to a vendor specific routine. Otherwise the PHY driver functions do not touch this value. The DRV_ETHPHY_VendorDataSet can be used for writing data into this field. Currently only a 32 bit value is supported. The function is intended for implementing vendor specific functions, like DRV_EXTPHY_MIIConfigure and DRV_EXTPHY_MDIXConfigure, that need a way of maintaining their own data and state machine. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 489 Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_VendorDataGet( DRV_HANDLE handle, uint32_t* pVendorData ) DRV_ETHPHY_VendorDataSet Function Returns the current value of the vendor data. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_VendorDataSet(DRV_HANDLE handle, uint32_t vendorData); Returns DRV_ETHPHY_RES_OK - if the vendor data is stored in the client object DRV_ETHPHY_RES_HANDLE_ERR - handle error Description This function returns the current value of the vendor data. Each DRV_ETHPHY client object maintains data that could be used for vendor specific operations. This routine allows retrieving of the vendor specific data. Remarks The PHY driver will clear the vendor specific data before any call to a vendor specific routine. Otherwise the PHY driver functions do not touch this value. The DRV_ETHPHY_VendorDataGet can be used for reading data into this field. Currently only a 32 bit value is supported. The function is intended for implementing vendor specific functions, like DRV_EXTPHY_MIIConfigure and DRV_EXTPHY_MDIXConfigure, that need a way of maintaining their own data and state machine. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_VendorDataSet( DRV_HANDLE handle, uint32_t vendorData ) DRV_ETHPHY_VendorSMIReadResultGet Function Reads the result of a previous vendor initiated SMI read transfer with DRV_ETHPHY_VendorSMIReadStart. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_VendorSMIReadResultGet(DRV_HANDLE handle, uint16_t* pSmiRes); Returns DRV_ETHPHY_RES_OK - transaction complete and result deposited at pSmiRes. DRV_ETHPHY_RES_PENDING - if the vendor transaction is still ongoing The call needs to be retried. < 0 - some error and the DRV_EXTPHY_MIIConfigure/DRV_EXTPHY_MDIXConfigure has to return error to be aborted by the DRV_ETHPHY_Setup Description This function will return the data of a SMI read transfer. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 490 Remarks The function is intended for implementing vendor SMI transfers within DRV_EXTPHY_MIIConfigure and DRV_EXTPHY_MDIXConfigure. It has to be called from within the DRV_EXTPHY_MIIConfigure or DRV_EXTPHY_MDIXConfigure functions (which are called, in turn, by the DRV_ETHPHY_Setup procedure) otherwise the call will fail. The DRV_ETHPHY_RES_OK and DRV_ETHPHY_RES_PENDING significance is changed from the general driver API. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup is in progress and configures the PHY • The vendor implementation of the DRV_EXTPHY_MIIConfigure/DRV_EXTPHY_MDIXConfigure is running and a SMI transfer is needed • DRV_ETHPHY_VendorSMIReadStart should have been called to initiate a transfer Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_VendorSMIReadResultGet( DRV_HANDLE handle, uint16_t* pSmiRes) DRV_ETHPHY_VendorSMIReadStart Function Starts a vendor SMI read transfer. Data will be available with DRV_ETHPHY_VendorSMIReadResultGet. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_VendorSMIReadStart(DRV_HANDLE handle, uint16_t rIx, int phyAddress); Returns DRV_ETHPHY_RES_OK - the vendor transaction is started DRV_ETHPHY_VendorSMIReadResultGet() needs to be called for the transaction to complete and to retrieve the result DRV_ETHPHY_RES_PENDING - the SMI bus is busy and the call needs to be retried < 0 - some error and the DRV_EXTPHY_MIIConfigure/DRV_EXTPHY_MDIXConfigure has to return error to be aborted by the DRV_ETHPHY_Setup Description This function will start a SMI read transfer. Remarks The function is intended for implementing vendor SMI transfers within DRV_EXTPHY_MIIConfigure and DRV_EXTPHY_MDIXConfigure. It has to be called from within the DRV_EXTPHY_MIIConfigure or DRV_EXTPHY_MDIXConfigure functions (which are called, in turn, by the DRV_ETHPHY_Setup procedure) otherwise the call will fail. The DRV_ETHPHY_RES_OK and DRV_ETHPHY_RES_PENDING significance is changed from the general driver API. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup is in progress and configures the PHY • The vendor implementation of the DRV_EXTPHY_MIIConfigure/DRV_EXTPHY_MDIXConfigure is running and a SMI transfer is needed Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_VendorSMIReadStart( DRV_HANDLE handle, uint16_t rIx, int phyAddress ) DRV_ETHPHY_VendorSMIWriteStart Function Starts a vendor SMI write transfer. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 491 File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_VendorSMIWriteStart(DRV_HANDLE handle, uint16_t rIx, uint16_t wData, int phyAddress); Returns DRV_ETHPHY_RES_OK - if the vendor SMI write transfer is started DRV_ETHPHY_RES_PENDING - the SMI bus was busy and the call needs to be retried < 0 - some error and the DRV_EXTPHY_MIIConfigure/DRV_EXTPHY_MDIXConfigure has to return error to be aborted by the DRV_ETHPHY_Setup Description This function will start a SMI write transfer. Remarks The function is intended for implementing vendor SMI transfers within DRV_EXTPHY_MIIConfigure and DRV_EXTPHY_MDIXConfigure. It has to be called from within the DRV_EXTPHY_MIIConfigure or DRV_EXTPHY_MDIXConfigure functions (which are called, in turn, by the DRV_ETHPHY_Setup procedure) otherwise the call will fail. The DRV_ETHPHY_RES_OK and DRV_ETHPHY_RES_PENDING significance is changed from the general driver API. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup is in progress and configures the PHY • The vendor implementation of the DRV_EXTPHY_MIIConfigure/DRV_EXTPHY_MDIXConfigure is running and a SMI transfer is needed Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_VendorSMIWriteStart( DRV_HANDLE handle, uint16_t rIx, uint16_t wData, int phyAddress ) e) Other Functions DRV_ETHPHY_LinkStatusGet Function Returns the current link status. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_LinkStatusGet(DRV_HANDLE handle, DRV_ETHPHY_INTERFACE_INDEX portIndex, DRV_ETHPHY_LINK_STATUS* pLinkStat, bool refresh); Returns • DRV_ETHPHY_RES_PENDING for ongoing, in progress operation • an DRV_ETHPHY_RESULT error code if the link status get procedure failed. Description This function returns the current link status. Remarks This function reads the Ethernet PHY to get current link status. If refresh is specified then, if the link is down a second read will be performed to return the current link status. Use DRV_ETHPHY_ClientStatus() and DRV_ETHPHY_ClientOperationResult() to check when the operation was completed and its outcome. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 492 Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_LinkStatusGet( DRV_HANDLE handle, DRV_ETHPHY_LINK_STATUS* pLinkStat, bool refresh ) DRV_ETHPHY_NegotiationIsComplete Function Returns the results of a previously initiated Ethernet PHY negotiation. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_NegotiationIsComplete(DRV_HANDLE handle, DRV_ETHPHY_INTERFACE_INDEX portIndex, bool waitComplete); Returns • DRV_ETHPHY_RES_PENDING operation is ongoing • an DRV_ETHPHY_RESULT error code if the procedure failed. Description This function returns the results of a previously initiated Ethernet PHY negotiation. Remarks Use DRV_ETHPHY_ClientStatus() and DRV_ETHPHY_ClientOperationResult() to check when the operation was completed and its outcome. When operation is completed but negotiation has failed, DRV_ETHPHY_ClientOperationResult will return: • DRV_ETHPHY_RES_NEGOTIATION_INACTIVE if no negotiation in progress • DRV_ETHPHY_RES_NEGOTIATION_NOT_STARTED if negotiation not yet started yet (means time out if waitComplete was requested) • DRV_ETHPHY_RES_NEGOTIATION_ACTIVE if negotiation ongoing (means time out if waitComplete was requested). See also DRV_ETHPHY_NegotiationResultGet. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY • DRV_ETHPHY_RestartNegotiation should have been called. Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_NegotiationIsComplete( DRV_HANDLE handle, bool waitComplete ) DRV_ETHPHY_NegotiationResultGet Function Returns the result of a completed negotiation. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_NegotiationResultGet(DRV_HANDLE handle, DRV_ETHPHY_INTERFACE_INDEX portIndex, DRV_ETHPHY_NEGOTIATION_RESULT* pNegResult); Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 493 Returns • DRV_ETHPHY_RES_PENDING operation is ongoing • an DRV_ETHPHY_RESULT error code if the procedure failed. Description This function returns the PHY negotiation data gathered after a completed negotiation. Remarks Use DRV_ETHPHY_ClientStatus() and DRV_ETHPHY_ClientOperationResult() to check when the operation was completed and its outcome. When operation is completed but negotiation has failed, DRV_ETHPHY_ClientOperationResult will return: • DRV_ETHPHY_RES_NEGOTIATION_INACTIVE if no negotiation in progress • DRV_ETHPHY_RES_NEGOTIATION_NOT_STARTED if negotiation not yet started yet (means time out if waitComplete was requested) • DRV_ETHPHY_RES_NEGOTIATION_ACTIVE if negotiation ongoing The returned value for the negotiation flags is valid only if the negotiation was completed successfully. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY • DRV_ETHPHY_RestartNegotiation, and DRV_ETHPHY_NegotiationIsComplete should have been called. Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_NegotiationResultGet( DRV_HANDLE handle, DRV_ETHPHY_NEGOTIATION_RESULT* pNegResult) DRV_ETHPHY_PhyAddressGet Function Returns the PHY address. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_PhyAddressGet(DRV_HANDLE handle, DRV_ETHPHY_INTERFACE_INDEX portIndex, int* pPhyAddress); Returns DRV_ETHPHY_RES_OK - operation successful and the PHY address stored at DRV_ETHPHY_RES_HANDLE_ERR - passed in handle was invalid pPhyAddress Description This function returns the current PHY address as set by the DRV_ETHPHY_Setup procedure. Remarks None. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_PhyAddressGet( DRV_HANDLE handle, int* pPhyAddress); Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 494 DRV_ETHPHY_RestartNegotiation Function Restarts auto-negotiation of the Ethernet PHY link. Implementation: Dynamic File drv_ethphy.h C DRV_ETHPHY_RESULT DRV_ETHPHY_RestartNegotiation(DRV_HANDLE handle, DRV_ETHPHY_INTERFACE_INDEX portIndex); Returns • DRV_ETHPHY_RES_PENDING operation has been scheduled successfully • an DRV_ETHPHY_RESULT error code if the procedure failed. Description This function restarts auto-negotiation of the Ethernet PHY link. Remarks Use DRV_ETHPHY_ClientStatus() and DRV_ETHPHY_ClientOperationResult() to check when the operation was completed and its outcome. Preconditions • The DRV_ETHPHY_Initialize routine must have been called. • DRV_ETHPHY_Open must have been called to obtain a valid device handle. • DRV_ETHPHY_Setup must have been called to properly configure the PHY Example Function DRV_ETHPHY_RESULT DRV_ETHPHY_RestartNegotiation( DRV_HANDLE handle ) f) Data Types and Constants DRV_ETHPHY_CLIENT_STATUS Enumeration Identifies the client-specific status of the Ethernet PHY driver. File drv_ethphy.h C typedef enum { DRV_ETHPHY_CLIENT_STATUS_ERROR, DRV_ETHPHY_CLIENT_STATUS_CLOSED, DRV_ETHPHY_CLIENT_STATUS_BUSY, DRV_ETHPHY_CLIENT_STATUS_READY } DRV_ETHPHY_CLIENT_STATUS; Members Members Description DRV_ETHPHY_CLIENT_STATUS_ERROR Unspecified error condition DRV_ETHPHY_CLIENT_STATUS_CLOSED Client is not open DRV_ETHPHY_CLIENT_STATUS_BUSY An operation is currently in progress DRV_ETHPHY_CLIENT_STATUS_READY Up and running, no operations running Description Ethernet PHY Driver Client Status This enumeration identifies the client-specific status of the Ethernet PHY driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 495 Remarks None. DRV_ETHPHY_INIT Structure Contains all the data necessary to initialize the Ethernet PHY device. File drv_ethphy.h C struct DRV_ETHPHY_INIT { SYS_MODULE_INIT moduleInit; uintptr_t ethphyId; uint16_t phyAddress; DRV_ETHPHY_CONFIG_FLAGS phyFlags; const DRV_ETHPHY_OBJECT* pPhyObject; DRV_ETHPHY_RESET_FUNCTION resetFunction; const struct DRV_MIIM_OBJECT_BASE* pMiimObject; const struct DRV_MIIM_INIT* pMiimInit; SYS_MODULE_INDEX miimIndex; }; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization uintptr_t ethphyId; Identifies peripheral (PLIB-level) ID uint16_t phyAddress; PHY address, as configured on the board. All PHYs respond to address 0 DRV_ETHPHY_CONFIG_FLAGS phyFlags; PHY configuration const DRV_ETHPHY_OBJECT* pPhyObject; Non-volatile pointer to the PHY object providing vendor functions for this PHY DRV_ETHPHY_RESET_FUNCTION resetFunction; Function to be called when the PHY is reset/initialized. Could be NULL if no special reset functionality needed - default const struct DRV_MIIM_OBJECT_BASE* pMiimObject; Non-volatile pointer to the DRV_MIIM object providing MIIM access for this PHY Could be NULL if the MIIM driver is not used const struct DRV_MIIM_INIT* pMiimInit; Non-volatile pointer to the DRV_MIIM initialization data Could be NULL if the MIIM driver is not used SYS_MODULE_INDEX miimIndex; MIIM module index to be used Not needed if the MIIM driver is not used Description Ethernet PHY Device Driver Initialization Data This data structure contains all the data necessary to initialize the Ethernet PHY device. Remarks A pointer to a structure of this format containing the desired initialization data must be passed into the DRV_ETHPHY_Initialize routine. DRV_ETHPHY_NEGOTIATION_RESULT Structure Contains all the data necessary to get the Ethernet PHY negotiation result File drv_ethphy.h C typedef struct { DRV_ETHPHY_LINK_STATUS linkStatus; TCPIP_ETH_OPEN_FLAGS linkFlags; TCPIP_ETH_PAUSE_TYPE pauseType; } DRV_ETHPHY_NEGOTIATION_RESULT; Members Members Description DRV_ETHPHY_LINK_STATUS linkStatus; link status after a completed negotiation Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 496 TCPIP_ETH_OPEN_FLAGS linkFlags; the negotiation result flags TCPIP_ETH_PAUSE_TYPE pauseType; pause type supported by the link partner Description Ethernet PHY Device Driver Negotiation result Data Contains all the data necessary to get the Ethernet PHY negotiation result Remarks A pointer to a structure of this format must be passed into the DRV_ETHPHY_NegotiationResultGet routine. DRV_ETHPHY_SETUP Structure Contains all the data necessary to set up the Ethernet PHY device. File drv_ethphy.h C typedef struct { int phyAddress; TCPIP_ETH_OPEN_FLAGS openFlags; DRV_ETHPHY_CONFIG_FLAGS configFlags; TCPIP_ETH_PAUSE_TYPE macPauseType; DRV_ETHPHY_RESET_FUNCTION resetFunction; } DRV_ETHPHY_SETUP; Members Members Description int phyAddress; the address the PHY is configured for TCPIP_ETH_OPEN_FLAGS openFlags; the capability flags: FD/HD, 100/100Mbps, etc. DRV_ETHPHY_CONFIG_FLAGS configFlags; configuration flags: MII/RMII, I/O setup TCPIP_ETH_PAUSE_TYPE macPauseType; MAC requested pause type DRV_ETHPHY_RESET_FUNCTION resetFunction; If ! NULL, function to be called when the PHY is reset/initialized Description Ethernet PHY Device Driver Set up Data This data structure contains all the data necessary to configure the Ethernet PHY device. Remarks A pointer to a structure of this format containing the desired initialization data must be passed into the DRV_ETHPHY_Setup routine. DRV_ETHPHY_VENDOR_MDIX_CONFIGURE Type Pointer to function that configures the MDIX mode for the Ethernet PHY. File drv_ethphy.h C typedef DRV_ETHPHY_RESULT (* DRV_ETHPHY_VENDOR_MDIX_CONFIGURE)(const struct DRV_ETHPHY_OBJECT_BASE_TYPE* pBaseObj, DRV_HANDLE handle, TCPIP_ETH_OPEN_FLAGS oFlags); Returns • DRV_ETHPHY_RES_OK - if success, operation complete • DRV_ETHPHY_RES_PENDING - if function needs to be called again < 0 - on failure: configuration not supported or some other error Description Pointer To Function: typedef DRV_ETHPHY_RESULT (* DRV_ETHPHY_VENDOR_MDIX_CONFIGURE) ( const struct DRV_ETHPHY_OBJECT_BASE_TYPE* pBaseObj, DRV_HANDLE handle, TCPIP_ETH_OPEN_FLAGS oFlags ); This type describes a pointer to a function that configures the MDIX mode for the Ethernet PHY. This configuration function is PHY specific and Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 497 every PHY driver has to provide their own implementation. Remarks The PHY driver consists of 2 modules: • the main/base PHY driver which uses standard IEEE PHY registers • the vendor specific functionality This function provides vendor specific functionality. Every PHY driver has to expose this vendor specific function as part of its interface. Traditionally the name used for this function is DRV_EXTPHY_MDIXConfigure but any name can be used. The function can use all the vendor specific functions to store/retrieve specific data or start SMI transactions (see Vendor Interface Routines). The function should not block but return DRV_ETHPHY_RES_PENDING if waiting for SMI transactions. Preconditions Communication to the PHY should have been established. DRV_ETHPHY_VENDOR_MII_CONFIGURE Type Pointer to function to configure the Ethernet PHY in one of the MII/RMII operation modes. File drv_ethphy.h C typedef DRV_ETHPHY_RESULT (* DRV_ETHPHY_VENDOR_MII_CONFIGURE)(const struct DRV_ETHPHY_OBJECT_BASE_TYPE* pBaseObj, DRV_HANDLE handle, DRV_ETHPHY_CONFIG_FLAGS cFlags); Returns • DRV_ETHPHY_RES_OK - if success, operation complete • DRV_ETHPHY_RES_PENDING - if function needs to be called again < 0 - on failure: configuration not supported or some other error Description Pointer To Function: typedef DRV_ETHPHY_RESULT (* DRV_ETHPHY_VENDOR_MII_CONFIGURE) (const struct DRV_ETHPHY_OBJECT_BASE_TYPE* pBaseObj, DRV_HANDLE handle, DRV_ETHPHY_CONFIG_FLAGS cFlags ); This type describes a pointer to a function that configures the Ethernet PHY in one of the MII/RMII operation modes. This configuration function is PHY specific and every PHY driver has to provide their own implementation. Remarks The PHY driver consists of 2 modules: • the main/base PHY driver which uses standard IEEE PHY registers • the vendor specific functionality This function provides vendor specific functionality. Every PHY driver has to expose this vendor specific function as part of its interface. Traditionally the name used for this function is DRV_EXTPHY_MIIConfigure but any name can be used. The PHY driver will call the vendor set up functions after the communication to the PHY has been established. The function can use all the vendor specific functions to store/retrieve specific data or start SMI transactions (see Vendor Interface Routines). The function should not block but return DRV_ETHPHY_RES_PENDING if waiting for SMI transactions. Preconditions Communication to the PHY should have been established. DRV_ETHPHY_VENDOR_SMI_CLOCK_GET Type Pointer to a function to return the SMI/MIIM maximum clock speed in Hz of the Ethernet PHY. File drv_ethphy.h C typedef unsigned int (* DRV_ETHPHY_VENDOR_SMI_CLOCK_GET)(const struct DRV_ETHPHY_OBJECT_BASE_TYPE* pBaseObj, DRV_HANDLE handle); Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 498 Returns The maximum SMI/MIIM clock speed as an unsigned integer. Description Pointer to Function: typedef unsigned int (* DRV_ETHPHY_VENDOR_SMI_CLOCK_GET) ( const struct DRV_ETHPHY_OBJECT_BASE_TYPE* pBaseObj, DRV_HANDLE handle ); This type describes a pointer to a function that returns the SMI/MIIM maximum clock speed in Hz of the Ethernet PHY. This configuration function is PHY specific and every PHY driver has to provide their own implementation. Remarks The PHY driver consists of 2 modules: • the main/base PHY driver which uses standard IEEE PHY registers • the vendor specific functionality This function provides vendor specific functionality. Every PHY driver has to expose this vendor specific function as part of its interface. This value is PHY specific. All PHYs are requested to support 2.5 MHz. Traditionally the name used for this function is DRV_EXTPHY_SMIClockGet but any name can be used. The PHY driver will call the vendor set up functions after the communication to the PHY has been established. The function should not block but return immediately. The function cannot start SMI transactions and cannot use the vendor specific functions to store/retrieve specific data (see Vendor Interface Routines). Preconditions Communication to the PHY should have been established. DRV_ETHPHY_INDEX_0 Macro Ethernet PHY driver index definitions. File drv_ethphy.h C #define DRV_ETHPHY_INDEX_0 0 Description Ethernet PHY Driver Module Index Numbers These constants provide the Ethernet PHY driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_ETHPHY_Initialize and DRV_ETHPHY_Open routines to identify the driver instance in use. DRV_ETHPHY_INDEX_1 Macro File drv_ethphy.h C #define DRV_ETHPHY_INDEX_1 1 Description This is macro DRV_ETHPHY_INDEX_1. DRV_ETHPHY_INDEX_COUNT Macro Number of valid Ethernet PHY driver indices. File drv_ethphy.h Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 499 C #define DRV_ETHPHY_INDEX_COUNT 1 Description Ethernet PHY Driver Module Index Count This constant identifies the number of valid Ethernet PHY driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from part-specific header files defined as part of the peripheral libraries. DRV_ETHPHY_LINK_STATUS Enumeration Defines the possible status flags of PHY Ethernet link. File drv_ethphy.h C typedef enum { DRV_ETHPHY_LINK_ST_DOWN, DRV_ETHPHY_LINK_ST_UP, DRV_ETHPHY_LINK_ST_LP_NEG_UNABLE, DRV_ETHPHY_LINK_ST_REMOTE_FAULT, DRV_ETHPHY_LINK_ST_PDF, DRV_ETHPHY_LINK_ST_LP_PAUSE, DRV_ETHPHY_LINK_ST_LP_ASM_DIR, DRV_ETHPHY_LINK_ST_NEG_TMO, DRV_ETHPHY_LINK_ST_NEG_FATAL_ERR } DRV_ETHPHY_LINK_STATUS; Members Members Description DRV_ETHPHY_LINK_ST_DOWN No connection to the LinkPartner DRV_ETHPHY_LINK_ST_UP Link is up DRV_ETHPHY_LINK_ST_LP_NEG_UNABLE LP non negotiation able DRV_ETHPHY_LINK_ST_REMOTE_FAULT LP fault during negotiation DRV_ETHPHY_LINK_ST_PDF Parallel Detection Fault encountered (when DRV_ETHPHY_LINK_ST_LP_NEG_UNABLE) DRV_ETHPHY_LINK_ST_LP_PAUSE LP supports symmetric pause DRV_ETHPHY_LINK_ST_LP_ASM_DIR LP supports asymmetric TX/RX pause operation DRV_ETHPHY_LINK_ST_NEG_TMO LP not there DRV_ETHPHY_LINK_ST_NEG_FATAL_ERR An unexpected fatal error occurred during the negotiation Description Ethernet PHY Device Link Status Codes This enumeration defines the flags describing the status of the PHY Ethernet link. Remarks Multiple flags can be set. DRV_ETHPHY_CONFIG_FLAGS Enumeration Defines configuration options for the Ethernet PHY. File drv_ethphy.h C typedef enum { DRV_ETHPHY_CFG_RMII, DRV_ETHPHY_CFG_MII, Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 500 DRV_ETHPHY_CFG_ALTERNATE, DRV_ETHPHY_CFG_DEFAULT, DRV_ETHPHY_CFG_AUTO } DRV_ETHPHY_CONFIG_FLAGS; Members Members Description DRV_ETHPHY_CFG_RMII RMII data interface in configuration fuses. DRV_ETHPHY_CFG_MII MII data interface in configuration fuses. DRV_ETHPHY_CFG_ALTERNATE Configuration fuses is ALT DRV_ETHPHY_CFG_DEFAULT Configuration fuses is DEFAULT DRV_ETHPHY_CFG_AUTO Use the fuses configuration to detect if you are RMII/MII and ALT/DEFAULT configuration Description Ethernet PHY Configuration Flags This enumeration defines configuration options for the Ethernet PHY. Used by: DRV_ETHPHY_MIIConfigure, DRV_ETHPHY_INIT structure, DRV_ETHPHY_Setup, Returned by: DRV_ETHPHY_HWConfigFlagsGet DRV_ETHPHY_OBJECT Structure Identifies the interface of a Ethernet PHY vendor driver. File drv_ethphy.h C typedef struct { DRV_ETHPHY_VENDOR_MII_CONFIGURE miiConfigure; DRV_ETHPHY_VENDOR_MDIX_CONFIGURE mdixConfigure; DRV_ETHPHY_VENDOR_SMI_CLOCK_GET smiClockGet; DRV_ETHPHY_VENDOR_WOL_CONFIGURE wolConfigure; } DRV_ETHPHY_OBJECT; Members Members Description DRV_ETHPHY_VENDOR_MII_CONFIGURE miiConfigure; PHY driver function to configure the operation mode: MII/RMII DRV_ETHPHY_VENDOR_MDIX_CONFIGURE mdixConfigure; PHY driver function to configure the MDIX mode DRV_ETHPHY_VENDOR_SMI_CLOCK_GET smiClockGet; PHY driver function to get the SMI clock rate DRV_ETHPHY_VENDOR_WOL_CONFIGURE wolConfigure; PHY driver function to configure the WOL functionality Description Ethernet PHY Driver Vendor Object This data structure identifies the required interface of the Ethernet PHY driver. Any PHY vendor driver has to export this interface. Remarks The PHY driver consists of 2 modules: • the main/base PHY driver which uses standard IEEE PHY registers • the vendor specific functionality This object provides vendor specific functionality. Every PHY driver has to expose this vendor specific functionality as part of its interface. DRV_ETHPHY_VENDOR_WOL_CONFIGURE Type Pointer to a function to configure the PHY WOL functionality File drv_ethphy.h Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 501 C typedef void (* DRV_ETHPHY_VENDOR_WOL_CONFIGURE)(const struct DRV_ETHPHY_OBJECT_BASE_TYPE* pBaseObj, DRV_HANDLE handle, unsigned char bAddr[]); Returns None Description Pointer to Function: typedef void (* DRV_ETHPHY_VENDOR_WOL_CONFIGURE) ( const struct DRV_ETHPHY_OBJECT_BASE_TYPE* pBaseObj, DRV_HANDLE handle, unsigned char bAddr[]); This type describes a pointer to a function that configures the PHY WOL functionality of the Ethernet PHY. Configures the WOL of the PHY with a Source MAC address or a 6 byte magic packet mac address. This configuration function is PHY specific and every PHY driver has to provide their own implementation. Remarks The PHY driver consists of 2 modules: • the main/base PHY driver which uses standard IEEE PHY registers • the vendor specific functionality This function provides vendor specific functionality. Every PHY driver has to expose this vendor specific function as part of its interface. Traditionally the name used for this function is DRV_EXTPHY_WOLConfiguration but any name can be used. The PHY driver will call the vendor set up functions after the communication to the PHY has been established. The function can use all the vendor specific functions to store/retrieve specific data or start SMI transactions (see Vendor Interface Routines). The function should not block but return DRV_ETHPHY_RES_PENDING if waiting for SMI transactions. This feature is not currently supported for all PHYs. Preconditions Communication to the PHY should have been established. DRV_ETHPHY_OBJECT_BASE Structure Identifies the base interface of a Ethernet PHY driver. File drv_ethphy.h C typedef struct DRV_ETHPHY_OBJECT_BASE_TYPE { SYS_MODULE_OBJ (* DRV_ETHPHY_Initialize)(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); void (* DRV_ETHPHY_Reinitialize)(SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init); void (* DRV_ETHPHY_Deinitialize)(SYS_MODULE_OBJ object); SYS_STATUS (* DRV_ETHPHY_Status)(SYS_MODULE_OBJ object); void (* DRV_ETHPHY_Tasks)(SYS_MODULE_OBJ object); DRV_HANDLE (* DRV_ETHPHY_Open)(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); void (* DRV_ETHPHY_Close)(DRV_HANDLE handle); DRV_ETHPHY_CLIENT_STATUS (* DRV_ETHPHY_ClientStatus)(DRV_HANDLE handle); DRV_ETHPHY_RESULT (* DRV_ETHPHY_ClientOperationResult)(DRV_HANDLE handle); DRV_ETHPHY_RESULT (* DRV_ETHPHY_ClientOperationAbort)(DRV_HANDLE handle); DRV_ETHPHY_RESULT (* DRV_ETHPHY_SMIRead)(DRV_HANDLE handle, unsigned int rIx, uint16_t* pSmiRes, int phyAdd); DRV_ETHPHY_RESULT (* DRV_ETHPHY_SMIWrite)(DRV_HANDLE handle, unsigned int rIx, uint16_t wData, int phyAdd, bool waitComplete); DRV_ETHPHY_RESULT (* DRV_ETHPHY_SMIScanStart)(DRV_HANDLE handle, unsigned int rIx); DRV_ETHPHY_RESULT (* DRV_ETHPHY_SMIScanStop)(DRV_HANDLE handle); DRV_ETHPHY_RESULT (* DRV_ETHPHY_SMIScanStatusGet)(DRV_HANDLE handle); DRV_ETHPHY_RESULT (* DRV_ETHPHY_SMIScanDataGet)(DRV_HANDLE handle, uint16_t* pScanRes); DRV_ETHPHY_RESULT (* DRV_ETHPHY_SMIStatus)(DRV_HANDLE handle); DRV_ETHPHY_RESULT (* DRV_ETHPHY_SMIClockSet)(DRV_HANDLE handle, uint32_t hostClock, uint32_t maxSMIClock); DRV_ETHPHY_RESULT (* DRV_ETHPHY_PhyAddressGet)(DRV_HANDLE handle, DRV_ETHPHY_INTERFACE_INDEX portIndex, int* pPhyAddress); DRV_ETHPHY_RESULT (* DRV_ETHPHY_Setup)(DRV_HANDLE handle, DRV_ETHPHY_SETUP* pSetUp, TCPIP_ETH_OPEN_FLAGS* pSetupFlags); DRV_ETHPHY_RESULT (* DRV_ETHPHY_RestartNegotiation)(DRV_HANDLE handle, DRV_ETHPHY_INTERFACE_INDEX portIndex); DRV_ETHPHY_RESULT (* DRV_ETHPHY_HWConfigFlagsGet)(DRV_HANDLE handle, DRV_ETHPHY_CONFIG_FLAGS* pFlags); Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 502 DRV_ETHPHY_RESULT (* DRV_ETHPHY_NegotiationIsComplete)(DRV_HANDLE handle, DRV_ETHPHY_INTERFACE_INDEX portIndex, bool waitComplete); DRV_ETHPHY_RESULT (* DRV_ETHPHY_NegotiationResultGet)(DRV_HANDLE handle, DRV_ETHPHY_INTERFACE_INDEX portIndex, DRV_ETHPHY_NEGOTIATION_RESULT* pNegResult); DRV_ETHPHY_RESULT (* DRV_ETHPHY_LinkStatusGet)(DRV_HANDLE handle, DRV_ETHPHY_INTERFACE_INDEX portIndex, DRV_ETHPHY_LINK_STATUS* pLinkStat, bool refresh); DRV_ETHPHY_RESULT (* DRV_ETHPHY_Reset)(DRV_HANDLE handle, bool waitComplete); DRV_ETHPHY_RESULT (* DRV_ETHPHY_VendorDataGet)(DRV_HANDLE handle, uint32_t* pVendorData); DRV_ETHPHY_RESULT (* DRV_ETHPHY_VendorDataSet)(DRV_HANDLE handle, uint32_t vendorData); DRV_ETHPHY_RESULT (* DRV_ETHPHY_VendorSMIReadStart)(DRV_HANDLE handle, uint16_t rIx, int phyAddress); DRV_ETHPHY_RESULT (* DRV_ETHPHY_VendorSMIReadResultGet)(DRV_HANDLE handle, uint16_t* pSmiRes); DRV_ETHPHY_RESULT (* DRV_ETHPHY_VendorSMIWriteStart)(DRV_HANDLE handle, uint16_t rIx, uint16_t wData, int phyAddress); } DRV_ETHPHY_OBJECT_BASE; Description Ethernet PHY Driver Base Object This data structure identifies the required interface of the Ethernet PHY driver. Any dynamic PHY driver has to export this interface. Remarks The PHY driver consists of 2 modules: • the main/base PHY driver which uses standard IEEE PHY registers • the vendor specific functionality This object provides the base functionality. Every dynamic PHY driver has to expose this basic functionality as part of its interface. See above the description of each function that's part of the base PHY driver. DRV_ETHPHY_RESET_FUNCTION Type Pointer to a function to perform an additional PHY reset File drv_ethphy.h C typedef void (* DRV_ETHPHY_RESET_FUNCTION)(const struct DRV_ETHPHY_OBJECT_BASE_TYPE* pBaseObj); Returns None Description Pointer to Function: typedef void (* DRV_ETHPHY_RESET_FUNCTION) ( const struct DRV_ETHPHY_OBJECT_BASE_TYPE* pBaseObj); This type describes a pointer to a function that is called by the driver before starting the detection and initialization process to the PHY - as a result of the DRV_ETHPHY_Setup call. Remarks The PHY driver will call this function as part of its detection and initialization procedure. It can be used for implementing extra steps that the user needs, before the driver starts talking to the PHY. For example, if a hard reset needs to be applied to the PHY. The function should be short and not block. It is meant just for short I/O operations, not for lengthy processing. Preconditions None DRV_ETHPHY_RESULT Enumeration Defines the possible results of Ethernet operations that can succeed or fail File drv_ethphy.h C typedef enum { } DRV_ETHPHY_RESULT; Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 503 Description Ethernet PHY Driver Operation Result * PHY Driver Operation Result Codes This enumeration defines the possible results of any of the PHY driver operations that have the possibility of failing. This result should be checked to ensure that the operation achieved the desired result. DRV_ETHPHY_USE_DRV_MIIM Macro Defines the way the PHY driver accesses the MIIM bus to communicate with the PHY. File drv_ethphy_config.h C #define DRV_ETHPHY_USE_DRV_MIIM true Description Ethernet MIIM access configuration Defines the way the PHY driver accesses the MIIM bus to communicate with the PHY: • either using direct access to the ETH plibs • using the MIIM driver - preferred way Remarks Using the MIIM driver to perform MIIM bus operations is more versatile and preferred. DRV_ETHPHY_INTERFACE_INDEX Enumeration Defines the index type for a PHY interface. File drv_ethphy.h C typedef enum { DRV_ETHPHY_INF_IDX_ALL_EXTERNAL, DRV_ETHPHY_INF_IDX_PORT_0, DRV_ETHPHY_INF_IDX_PORT_1, DRV_ETHPHY_INF_IDX_PORT_2, DRV_ETHPHY_INF_IDX_PORT_3, DRV_ETHPHY_INF_IDX_PORT_4, DRV_ETHPHY_INF_IDX_PORT_5 } DRV_ETHPHY_INTERFACE_INDEX; Members Members Description DRV_ETHPHY_INF_IDX_ALL_EXTERNAL All External Interfaces DRV_ETHPHY_INF_IDX_PORT_0 Port 0 interface DRV_ETHPHY_INF_IDX_PORT_1 Port 1 interface DRV_ETHPHY_INF_IDX_PORT_2 Port 2 interface DRV_ETHPHY_INF_IDX_PORT_3 Port 3 interface DRV_ETHPHY_INF_IDX_PORT_4 Port 4 interface DRV_ETHPHY_INF_IDX_PORT_5 Port 5 interface Description Ethernet PHY Interface Index This enumeration defines the index type supported by the PHY Used by: DRV_ETHPHY_PhyAddressGet, DRV_ETHPHY_RestartNegotiation, DRV_ETHPHY_NegotiationIsComplete, DRV_ETHPHY_LinkStatusGet Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 504 DRV_ETHPHY_INTERFACE_TYPE Enumeration Defines the type of interface a PHY supports. File drv_ethphy.h C typedef enum { DRV_ETHPHY_INF_TYPE_EXTERNAL, DRV_ETHPHY_INF_TYPE_INTERNAL, DRV_ETHPHY_INF_TYPE_NOT_SUPPORTED } DRV_ETHPHY_INTERFACE_TYPE; Members Members Description DRV_ETHPHY_INF_TYPE_EXTERNAL External Interface DRV_ETHPHY_INF_TYPE_INTERNAL Internal Interface DRV_ETHPHY_INF_TYPE_NOT_SUPPORTED Not Supported Description Ethernet PHY Interface Type This enumeration defines the type of interface supported by the PHY Returned by: DRV_ETHPHY_GetInterfaceType Files Files Name Description drv_ethphy.h Ethernet ETHPHY Device Driver Interface File drv_ethphy_config.h Ethernet PHY driver configuration definitions template. Description This section lists the source and header files used by the Ethernet PHY Driver Library. drv_ethphy.h Ethernet ETHPHY Device Driver Interface File Enumerations Name Description DRV_ETHPHY_CLIENT_STATUS Identifies the client-specific status of the Ethernet PHY driver. DRV_ETHPHY_CONFIG_FLAGS Defines configuration options for the Ethernet PHY. DRV_ETHPHY_INTERFACE_INDEX Defines the index type for a PHY interface. DRV_ETHPHY_INTERFACE_TYPE Defines the type of interface a PHY supports. DRV_ETHPHY_LINK_STATUS Defines the possible status flags of PHY Ethernet link. DRV_ETHPHY_RESULT Defines the possible results of Ethernet operations that can succeed or fail Functions Name Description DRV_ETHPHY_ClientOperationAbort Aborts a current client operation initiated by the Ethernet PHY driver. Implementation: Dynamic DRV_ETHPHY_ClientOperationResult Gets the result of a client operation initiated by the Ethernet PHY driver. Implementation: Dynamic DRV_ETHPHY_ClientStatus Gets the current client-specific status the Ethernet PHY driver. Implementation: Dynamic DRV_ETHPHY_Close Closes an opened instance of the Ethernet PHY driver. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 505 DRV_ETHPHY_Deinitialize Deinitializes the specified instance of the Ethernet PHY driver module. Implementation: Dynamic DRV_ETHPHY_HWConfigFlagsGet Returns the current Ethernet PHY hardware MII/RMII and ALTERNATE/DEFAULT configuration flags. Implementation: Dynamic DRV_ETHPHY_Initialize Initializes the Ethernet PHY driver. Implementation: Dynamic DRV_ETHPHY_LinkStatusGet Returns the current link status. Implementation: Dynamic DRV_ETHPHY_NegotiationIsComplete Returns the results of a previously initiated Ethernet PHY negotiation. Implementation: Dynamic DRV_ETHPHY_NegotiationResultGet Returns the result of a completed negotiation. Implementation: Dynamic DRV_ETHPHY_Open Opens the specified Ethernet PHY driver instance and returns a handle to it. Implementation: Dynamic DRV_ETHPHY_PhyAddressGet Returns the PHY address. Implementation: Dynamic DRV_ETHPHY_Reinitialize Reinitializes the driver and refreshes any associated hardware settings. Implementation: Dynamic DRV_ETHPHY_Reset Immediately resets the Ethernet PHY. Implementation: Dynamic DRV_ETHPHY_RestartNegotiation Restarts auto-negotiation of the Ethernet PHY link. Implementation: Dynamic DRV_ETHPHY_Setup Initializes Ethernet PHY configuration and set up procedure. Implementation: Dynamic DRV_ETHPHY_SMIClockSet Sets the SMI/MIIM interface clock. Implementation: Dynamic DRV_ETHPHY_SMIRead Initiates a SMI/MIIM read transaction. Implementation: Dynamic DRV_ETHPHY_SMIScanDataGet Gets the latest SMI/MIIM scan data result. Implementation: Dynamic DRV_ETHPHY_SMIScanStart Starts the scan of a requested SMI/MIIM register. Implementation: Dynamic DRV_ETHPHY_SMIScanStatusGet Gets the status of the SMI/MIIM scan data. Implementation: Dynamic DRV_ETHPHY_SMIScanStop Stops the scan of a previously requested SMI/MIIM register. Implementation: Dynamic DRV_ETHPHY_SMIStatus Returns the current status of the SMI/MIIM interface. Implementation: Dynamic DRV_ETHPHY_SMIWrite Initiates a SMI/MIIM write transaction. Implementation: Dynamic DRV_ETHPHY_Status Provides the current status of the Ethernet PHY driver module. Implementation: Dynamic DRV_ETHPHY_Tasks Maintains the driver's state machine and implements its ISR. Implementation: Dynamic DRV_ETHPHY_VendorDataGet Returns the current value of the vendor data. Implementation: Dynamic DRV_ETHPHY_VendorDataSet Returns the current value of the vendor data. Implementation: Dynamic DRV_ETHPHY_VendorSMIReadResultGet Reads the result of a previous vendor initiated SMI read transfer with DRV_ETHPHY_VendorSMIReadStart. Implementation: Dynamic DRV_ETHPHY_VendorSMIReadStart Starts a vendor SMI read transfer. Data will be available with DRV_ETHPHY_VendorSMIReadResultGet. Implementation: Dynamic DRV_ETHPHY_VendorSMIWriteStart Starts a vendor SMI write transfer. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 506 Macros Name Description DRV_ETHPHY_INDEX_0 Ethernet PHY driver index definitions. DRV_ETHPHY_INDEX_1 This is macro DRV_ETHPHY_INDEX_1. DRV_ETHPHY_INDEX_COUNT Number of valid Ethernet PHY driver indices. Structures Name Description DRV_ETHPHY_INIT Contains all the data necessary to initialize the Ethernet PHY device. DRV_ETHPHY_OBJECT_BASE_TYPE Identifies the base interface of a Ethernet PHY driver. DRV_ETHPHY_NEGOTIATION_RESULT Contains all the data necessary to get the Ethernet PHY negotiation result DRV_ETHPHY_OBJECT Identifies the interface of a Ethernet PHY vendor driver. DRV_ETHPHY_OBJECT_BASE Identifies the base interface of a Ethernet PHY driver. DRV_ETHPHY_SETUP Contains all the data necessary to set up the Ethernet PHY device. Types Name Description DRV_ETHPHY_RESET_FUNCTION Pointer to a function to perform an additional PHY reset DRV_ETHPHY_VENDOR_MDIX_CONFIGURE Pointer to function that configures the MDIX mode for the Ethernet PHY. DRV_ETHPHY_VENDOR_MII_CONFIGURE Pointer to function to configure the Ethernet PHY in one of the MII/RMII operation modes. DRV_ETHPHY_VENDOR_SMI_CLOCK_GET Pointer to a function to return the SMI/MIIM maximum clock speed in Hz of the Ethernet PHY. DRV_ETHPHY_VENDOR_WOL_CONFIGURE Pointer to a function to configure the PHY WOL functionality Description Ethernet ETHPHY Device Driver Interface The Ethernet ETHPHY device driver provides a simple interface to manage an Ethernet ETHPHY peripheral using MIIM (or SMI) interface. This file defines the interface definitions and prototypes for the Ethernet ETHPHY driver. File Name drv_ethphy.h Company Microchip Technology Inc. drv_ethphy_config.h Ethernet PHY driver configuration definitions template. Macros Name Description DRV_ETHPHY_CLIENTS_NUMBER Selects the maximum number of clients. DRV_ETHPHY_INDEX Ethernet PHY static index selection. DRV_ETHPHY_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver. DRV_ETHPHY_NEG_DONE_TMO Value of the PHY negotiation complete time out as per IEEE 802.3 spec. DRV_ETHPHY_NEG_INIT_TMO Value of the PHY negotiation initiation time out as per IEEE 802.3 spec. DRV_ETHPHY_PERIPHERAL_ID Defines an override of the peripheral ID. DRV_ETHPHY_RESET_CLR_TMO Value of the PHY Reset self clear time out as per IEEE 802.3 spec. DRV_ETHPHY_USE_DRV_MIIM Defines the way the PHY driver accesses the MIIM bus to communicate with the PHY. Description Ethernet PHY Driver Configuration Definitions for the Template Version These definitions statically define the driver's mode of operation. File Name drv_ethphy_config.h Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet PHY Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 507 Company Microchip Technology Inc. Flash Driver Library This section describes the Flash Driver Library. Introduction The Flash Driver Library provides functions that allow low-level interface with the on-chip Flash. Description Through MHC, this driver provides low-level functions for writing and erasing sections of the Flash memory. 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, restricting memory access, and therefore preventing code execution. This is controlled by an internal programming timer. Library Interface Functions Name Description DRV_FLASH_ErasePage Erases a page of Flash. Implementation: Static DRV_FLASH_GetPageSize Returns the size in bytes of a single "Page" which can be erased in the flash. Implementation: Static DRV_FLASH_GetRowSize Returns the size in bytes of a single "Row" which can be written to the flash. Implementation: Static DRV_FLASH_Initialize Initializes the Flash instance for the specified driver index. Implementation: Static DRV_FLASH_IsBusy Returns true if the Flash device is still busy writing or is erasing. Implementation: Static DRV_FLASH_Open Initializes a channel to the appropriate flash device. DRV_FLASH_WriteQuadWord Writes four 4-byte words to the Flash at the (word-aligned) flashAddr. Implementation: Static DRV_FLASH_WriteRow Writes an DRV_FLASH_ROW_SIZE bytes to the Flash at the (word-aligned) flashAddr. Implementation: Static DRV_FLASH_WriteWord Writes a 4-byte Word to the Flash at the (word-aligned) flashAddr. Implementation: Static Data Types and Constants Name Description DRV_FLASH_INDEX_0 FLASH driver index definitions DRV_FLASH_PAGE_SIZE Specifies the FLASH Driver Program Page Size in bytes. DRV_FLASH_ROW_SIZE Specifies the FLASH Driver Program Row Size in bytes. Description This section describes the Application Programming Interface (API) functions of the Flash Driver Library. Refer to each section for a detailed description. Functions Volume V: MPLAB Harmony Framework Driver Libraries Help Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 508 DRV_FLASH_ErasePage Function Erases a page of Flash. Implementation: Static File drv_flash.h C void DRV_FLASH_ErasePage(const DRV_HANDLE handle, uint32_t flashAddr); Returns None. Description This function starts the process of erasing a page of Flash. It does not wait for the erase operation to be done. That is left to the user. It does not verify that the erase was successful. That is left to the user. It always erases a single page. The size of a page in bytes will vary by device. It will be available in the DRV_FLASH_PAGE_SIZE parameter. Remarks Most devices will be running for code stored in the Flash. This means that any erases of the Flash will necessarily be writes to program space. As such, they will prevent the CPU from reading further instructions until the write is done. However, some devices may have more than one Flash such that it can run from one while writing to another. Additionally, if the application is small enough, it may run out of a cache. In any case, it is up to the user to wait for an operation to complete and or to decide that such a wait is unnecessary. Preconditions The flashAddr is taken as a valid Flash address. No range checking occurs. Any previous Flash operations (write or erase) must be completed or this will fail silently. The Flash must be correctly erased at flashAddr. Example flashAddr = 0x9d008000; DRV_FLASH_Erase_Page(handle, flashAddr); Function void DRV_FLASH_Erase_Page(uint32_t flashAddr); DRV_FLASH_GetPageSize Function Returns the size in bytes of a single "Page" which can be erased in the flash. Implementation: Static File drv_flash.h C uint32_t DRV_FLASH_GetPageSize(const DRV_HANDLE handle); Returns None. Description This function allows the user to get the size of a flash Page. Remarks None. Preconditions None Function uint32_t DRV_FLASH_GetPageSize( const DRV_HANDLE handle ) Volume V: MPLAB Harmony Framework Driver Libraries Help Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 509 DRV_FLASH_GetRowSize Function Returns the size in bytes of a single "Row" which can be written to the flash. Implementation: Static File drv_flash.h C uint32_t DRV_FLASH_GetRowSize(const DRV_HANDLE handle); Returns None. Description This function allows the user to get the size of a flash Row. Remarks None. Preconditions None Function uint32_t DRV_FLASH_GetRowSize( const DRV_HANDLE handle ) DRV_FLASH_Initialize Function Initializes the Flash instance for the specified driver index. Implementation: Static File drv_flash.h C SYS_MODULE_OBJ DRV_FLASH_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, returns SYS_MODULE_OBJ_INVALID. Description This function initializes the Flash Driver instance for the specified driver instance, making it ready for clients to use it. The initialization routine is specified by the MHC parameters. Remarks This function must be called before any other Flash function is called. This function should only be called once during system initialization. Preconditions None. Parameters Parameters Description index Identifier for the instance to be initialized init Pointer to a data structure containing any data necessary to initialize the driver. Function SYS_MODULE_OBJ DRV_FLASH_Initialize( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ) Volume V: MPLAB Harmony Framework Driver Libraries Help Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 510 DRV_FLASH_IsBusy Function Returns true if the Flash device is still busy writing or is erasing. Implementation: Static File drv_flash.h C bool DRV_FLASH_IsBusy(const DRV_HANDLE handle); Returns • true - Indicates the Flash is busy • false - Indicates the Flash is not busy Description This function checks whether the process of programming a Word into the Flash is still operating. Remarks Most devices will be running for code stored in the Flash. This means that any writes to the Flash will necessarily be writes to program space. As such, they will prevent the CPU from reading further instructions until the write is done. However, some devices may have more than one Flash such that it can run from one while writing to another. Additionally, if the application is small enough, it may run out of a cache. In any case, it is up to the user to wait for an operation to complete and or to decide that such a wait is unnecessary. Preconditions None. Example flashAddr = 0x9d008000; sourceData = 0x12345678; DRV_FLASH_Write_Word(flashAddr, sourceData); DRV_FLASH_IsBusy( void ); Function bool DRV_FLASH_IsBusy( void ) DRV_FLASH_Open Function Initializes a channel to the appropriate flash device. File drv_flash.h C DRV_HANDLE DRV_FLASH_Open(const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent); Returns Handle for future calls to the driver's operations. Preconditions None Function DRV_HANDLE DRV_FLASH_Open( const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent ); DRV_FLASH_WriteQuadWord Function Writes four 4-byte words to the Flash at the (word-aligned) flashAddr. Volume V: MPLAB Harmony Framework Driver Libraries Help Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 511 Implementation: Static File drv_flash.h C void DRV_FLASH_WriteQuadWord(const DRV_HANDLE handle, uint32_t flashAddr, uint32_t * sourceData); Returns None. Description This function starts the process of programming a word into the Flash. It does not wait for the write operation to be done, which is left to the user. It does not verify that the write was successful, which is left to the user. Remarks Most devices will be running for code stored in the Flash. This means that any writes to the Flash will necessarily be writes to program space. As such, they will prevent the CPU from reading further instructions until the write is done. However, some devices may have more than one Flash such that it can run from one while writing to another. Additionally, if the application is small enough, it may run out of a cache. In any case, it is up to the user to wait for an operation to complete and or to decide that such a wait is unnecessary. Preconditions The flashAddr is taken as a valid Flash address. No range checking occurs. Any previous Flash operations (write or erase) must be completed or this will fail silently. The Flash must be correctly erased at flashAddr. Example flashAddr = 0x9d008000; sourceData[4] = {0x12345678,0x9ABCDEF0,0x55AAAA55,0x11111111}; DRV_FLASH_WriteQuadWord(handle, flashAddr, sourceData); Function void DRV_FLASH_WriteQuadWord( const DRV_HANDLE handle, uint32_t flashAddr, uint32_t sourceData) DRV_FLASH_WriteRow Function Writes an DRV_FLASH_ROW_SIZE bytes to the Flash at the (word-aligned) flashAddr. Implementation: Static File drv_flash.h C void DRV_FLASH_WriteRow(const DRV_HANDLE handle, uint32_t flashAddr, uint32_t sourceData); Returns None. Description This function starts the process of programming a buffer into the Flash. It does not wait for the write operation to be done, which is left to the user. It does not verify that the write was successful, which is left to the user. Remarks Most devices will be running for code stored in the Flash. This means that any writes to the Flash will necessarily be writes to program space. As such, they will prevent the CPU from reading further instructions until the write is done. However, some devices may have more than one Flash such that it can run from one while writing to another. Additionally, if the application is small enough, it may run out of a cache. In any case, it is up to the user to wait for an operation to complete and or to decide that such a wait is unnecessary. Preconditions The flashAddr is taken as a valid Flash address. No range checking occurs. The memory pointed to by sourceData must be valid memory for at least DRV_FLASH_ROW_SIZE bytes. Any previous Flash operations (write or erase) must be completed or this will fail silently. The Flash must be correctly erased at flashAddr. Example flashAddr = 0x9d008000; Volume V: MPLAB Harmony Framework Driver Libraries Help Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 512 uint32_t dataStore[DRV_FLASH_ROW_SIZE] = {0,1,2,3,4,5}; DRV_FLASH_Write_Row( const DRV_HANDLE handle, flashAddr, dataStore); Function void DRV_FLASH_WriteRow( const DRV_HANDLE handle, uint32_t flashAddr, uint32_t sourceData) DRV_FLASH_WriteWord Function Writes a 4-byte Word to the Flash at the (word-aligned) flashAddr. Implementation: Static File drv_flash.h C void DRV_FLASH_WriteWord(const DRV_HANDLE handle, uint32_t flashAddr, uint32_t sourceData); Returns None. Description This function starts the process of programming a Word into the Flash. It does not wait for the write operation to be done, which is left to the user. It does not verify that the write was successful, which is left to the user. Remarks Most devices will be running for code stored in the Flash. This means that any writes to the Flash will necessarily be writes to program space. As such, they will prevent the CPU from reading further instructions until the write is done. However, some devices may have more than one Flash such that it can run from one while writing to another. Additionally, if the application is small enough, it may run out of a cache. In any case, it is up to the user to wait for an operation to complete and or to decide that such a wait is unnecessary. Preconditions The flashAddr is taken as a valid Flash address. No range checking occurs. Any previous Flash operations (write or erase) must be completed or this will fail silently. The Flash must be correctly erased at flashAddr. Example flashAddr = 0x9d008000; sourceData = 0x12345678; DRV_FLASH_WriteWord(handle, flashAddr, sourceData); Function void DRV_FLASH_WriteWord( const DRV_HANDLE handle, uint32_t flashAddr, uint32_t sourceData) Data Types and Constants DRV_FLASH_INDEX_0 Macro FLASH driver index definitions File drv_flash.h C #define DRV_FLASH_INDEX_0 0 Description These constants provide FLASH driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_FLASH_Initialize and DRV_FLASH_Open routines to identify the driver instance in use. Volume V: MPLAB Harmony Framework Driver Libraries Help Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 513 Section Constants ************************************************************************ ************************************************************************ *************************************************************************** Driver FLASH Module Index DRV_FLASH_PAGE_SIZE Macro Specifies the FLASH Driver Program Page Size in bytes. File drv_flash.h C #define DRV_FLASH_PAGE_SIZE (NVM_PAGE_SIZE) Description FLASH Driver Program Page Size. This definition specifies the FLASH Driver Program Page Size in bytes. This parameter is device specific and is obtained from the device specific processor header file. Remarks None DRV_FLASH_ROW_SIZE Macro Specifies the FLASH Driver Program Row Size in bytes. File drv_flash.h C #define DRV_FLASH_ROW_SIZE (NVM_ROW_SIZE) Description FLASH Driver Program Row Size. This definition specifies the FLASH Driver Program Row Size in bytes. This parameter is device specific and is obtained from the device specific processor header file. The Program Row Size is the maximum block size that can be programmed in one program operation. Remarks None Files Files Name Description drv_flash.h Flash Driver interface declarations for the static single instance driver. Description drv_flash.h Flash Driver interface declarations for the static single instance driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 514 Functions Name Description DRV_FLASH_ErasePage Erases a page of Flash. Implementation: Static DRV_FLASH_GetPageSize Returns the size in bytes of a single "Page" which can be erased in the flash. Implementation: Static DRV_FLASH_GetRowSize Returns the size in bytes of a single "Row" which can be written to the flash. Implementation: Static DRV_FLASH_Initialize Initializes the Flash instance for the specified driver index. Implementation: Static DRV_FLASH_IsBusy Returns true if the Flash device is still busy writing or is erasing. Implementation: Static DRV_FLASH_Open Initializes a channel to the appropriate flash device. DRV_FLASH_WriteQuadWord Writes four 4-byte words to the Flash at the (word-aligned) flashAddr. Implementation: Static DRV_FLASH_WriteRow Writes an DRV_FLASH_ROW_SIZE bytes to the Flash at the (word-aligned) flashAddr. Implementation: Static DRV_FLASH_WriteWord Writes a 4-byte Word to the Flash at the (word-aligned) flashAddr. Implementation: Static Macros Name Description DRV_FLASH_INDEX_0 FLASH driver index definitions DRV_FLASH_PAGE_SIZE Specifies the FLASH Driver Program Page Size in bytes. DRV_FLASH_ROW_SIZE Specifies the FLASH Driver Program Row Size in bytes. Description Flash Driver Interface Declarations for Static Single Instance Driver The Flash device driver provides a simple interface to manage the Flash Controller on Microchip microcontrollers. This file defines the interface Declarations for the Flash driver. Remarks Static interfaces incorporate the driver instance number within the names of the routines, eliminating the need for an object ID or object handle. Static single-open interfaces also eliminate the need for the open handle. File Name drv_flash.h Company Microchip Technology Inc. Ethernet GMAC Driver Library This section describes the Ethernet MAC Driver Library. Introduction This library provides a driver-level abstraction of the on-chip Ethernet Controller found on many PIC32 devices. The driver implements the virtual MAC driver model that the MPLAB Harmony TCP/IP Stack requires. Please see the TCP/IP Stack Library MAC Driver Module help for details. The "Host-To-Network"_layer of a TCP/IP stack organization covers the Data Link and Physical Layers of the standard OSI stack. The Ethernet Controller provides the Data Link or Media Access Control Layer, in addition to other functions discussed in this section. An external Ethernet "PHY" provides the Physical_layer, providing conversion between the digital and analog. Description The Ethernet Media Access Controller (GMAC) module implements a 10/100 Mbps Ethernet MAC, compatible with the IEEE 802.3 standard. The GMAC can operate in either half or full duplex mode at all supported speeds. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet GMAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 515 Embedded Characteristics • Compatible with IEEE Standard 802.3 • 10, 100 Mbps operation • Full and half duplex operation at all supported speeds of operation • Statistics Counter Registers for RMON/MIB • MII interface to the physical layer • Integrated physical coding • Direct memory access (DMA) interface to external memory • Support for 6 priority queues in DMA • 8 KB transmit RAM and 4 KB receive RAM • Programmable burst length and endianism for DMA • Interrupt generation to signal receive and transmit completion, errors or other events • Automatic pad and cyclic redundancy check (CRC) generation on transmitted frames • Automatic discard of frames received with errors • Receive and transmit IP, TCP and UDP checksum offload. Both IPv4 and IPv6 packet types supported • Address checking logic for four specific 48-bit addresses, four type IDs, promiscuous mode, hash matching of unicast and multicast destination addresses and Wake-on-LAN • Management Data Input/Output (MDIO) interface for physical layer management • Support for jumbo frames up to 10240 Bytes • Full duplex flow control with recognition of incoming pause frames and hardware generation of transmitted pause frames • Half duplex flow control by forcing collisions on incoming frames • Support for 802.1Q VLAN tagging with recognition of incoming VLAN and priority tagged frames • Support for 802.1Qbb priority-based flow control • Programmable Inter Packet Gap (IPG) Stretch • Recognition of IEEE 1588 PTP frames • IEEE 1588 time stamp unit (TSU) • Support for 802.1AS timing and synchronization • Supports 802.1Qav traffic shaping on two highest priority queues Using the Library The user of this driver is the MPLAB Harmony TCP/IP stack. This Ethernet driver is not intended as a system wide driver that the application or other system modules may use. It is intended for the sole use of the MPLAB Harmony TCP/IP stack and implements the virtual MAC model required by the stack. This topic describes the basic architecture and functionality of the Ethernet MAC driver and is meant for advanced users or TCP/IP stack driver developers. Interface Header File: drv_gmac.h The interface to the Ethernet MAC library is defined in the drv_gmac.h header file, which is included by the MPLAB Harmony TCP/IP stack. Please refer to the What is MPLAB Harmony? section for how the library interacts with the framework. Abstraction Model This library provides a low-level abstraction of the Ethernet GMAC Driver Library 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 Ethernet Controller provides the modules needed to implement a 10/100 Mbps Ethernet node using an external Ethernet PHY chip. The PHY chip provides a digital-analog interface as part of the Physical Layer and the controller provides the Media Access Controller (MAC)_layer above the PHY. As shown in Figure 1, 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: Responsible for control of the transmission of PAUSE frames. (Reception of PAUSE frames 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 • TX DMA/TX Buffer Management 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 Buffer Management Engine: The RX DMA and RX Buffer Management engines transfer receive packets from the MAC to the memory (using descriptor tables) Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet GMAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 516 Figure 1: Ethernet Controller Block Diagram For completeness, we also need to look at the interface diagram of a representative Ethernet PHY. As shown in Figure 2, the PHY has two interfaces, one for configuring and managing the PHY (SMI/MIIM) and another for transmit and receive data (RMII or MII). The SMI/MIIM interface is the responsibility of the Ethernet PHY Driver Library. When setting up the Ethernet PHY, this Ethernet driver calls primitives from the Ethernet PHY Driver library. The RMII/MII data interface is the responsibility of the Ethernet MAC Driver Library (this library). Figure 2: Ethernet PHY Interfaces Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet GMAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 517 Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. Refer to the TCP/IP Stack Library MAC Driver Module help for the interface that the Ethernet driver has to implement in a MPLAB Harmony system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Ethernet GMAC Driver Library. Library Interface Section Description Client Level Functions Open, Close, Initialize, Reinitialize, and Deinitialize functions to support the TCP/IP Stack. Plus link status and power options. Receive Functions Receive routines. Transmit Functions Transmit routines. Event Functions Ethernet event support routines. Other Functions Additional routines. Data Types and Constants Typedefs and #defines. Configuring the Library The configuration of the Ethernet MAC driver is done as part of the MPLAB Harmony TCP/IP Stack configuration and is based on the system_config.h file, which may include the tcpip_mac_config.h. See the TCP/IP Stack Library MAC Driver Module help file for configuration options. This header file contains the configuration selection for the Ethernet GMAC Driver. 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 in the Ethernet GMAC Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet GMAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 518 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 /framework/driver/gmac. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_gmac.h Header file that exports the driver API. 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 /src/dynamic/drv_gmac.c PIC32 internal Ethernet driver virtual GMAC implementation file. /src/dynamic/drv_gmac_lib.c PIC32 internal Ethernet driver controller implementation file. 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 N/A No optional files are available for this library Module Dependencies The Ethernet MAC Driver Library depends on the following modules: • Ethernet PHY Driver Library • Interrupt System Service Library • Timer System Service Library • Ethernet Peripheral Library Library Interface This section lists the interface routines, data types, constants and macros for the library. a) Client Level Functions b) Receive Functions c) Transmit Functions d) Event Functions e) Other Functions f) Data Types and Constants Volume V: MPLAB Harmony Framework Driver Libraries Help Ethernet GMAC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 519 Files Files Name Description drv_gmac.h This is file drv_gmac.h. Description This section lists the source and header files used by the Ethernet MAC Driver Library. drv_gmac.h This is file drv_gmac.h. I2C Driver Library Help This section describes the I2C Driver Library. Introduction This library provides an interface to manage the data transfer operations using the I2C module on the Microchip family of microcontrollers. Description The driver communicates using the concept of transactions. In instances where the I2C operates in Master mode, the driver sends the start signal, followed by a slave device address (including a Read/Write bit), followed by a number of bytes written to or read from the slave. The transaction is completed by sending the stop signal. When the driver operates in the Slave mode, it will either read data or write data to the master. This driver library provides application ready routines to read and write data using the I2C protocol, thus minimizing developer’s awareness of the working of the I2C protocol. • Provides read/write and buffer data transfer models • Supports interrupt and Polled modes of operation • Support multi-client and multi-instance operation • Provides data transfer events • Supports blocking and non-blocking operation • Supports baud rate setting • Supports bit bang mode. Using the Library This topic describes the basic architecture of the I2C Driver Library and provides information and examples on its use. Description Interface Header File: drv_i2c.h The interface to the I2C Driver Library is defined in the drv_i2c.h header file. Any C language source (.c) file that uses the I2C Driver Library should include drv_i2c.h. Library File: The I2C Driver Library archive (.a) file is installed with MPLAB Harmony. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model The I2C Driver Library provides the low-level abstraction of the I2C 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 I2C Driver Library interface. Description The I2C Driver Library features routines to perform two functions, driver maintenance and data transfer: Driver Maintenance The Driver initialization routines allow the application to initialize the driver. The initialization data configures the I2C module as a Master or a Slave and sets the necessary parameters required for operation in the particular mode. The driver must be initialized before it can be used by the application. After the end of operation, the driver can be deinitialized. Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 520 Data Transfer Data transfer is accomplished by separate Write and Read functions through a data buffer. The read and write function makes the user transparent to the internal working of the I2C protocol. The user can use callback mechanisms or use polling to check status of transfer. The following diagrams illustrate the model used by the I2C Driver for transmitter and receiver. Note: The driver can be configured to use either the SOC peripheral, or in Bit Bang mode. Bit Bang mode uses CPU resources to process the data bits onto or off of the I2C I/O pins. Be aware that and I2C driver configured this way uses a large amount of CPU resources. Receiver Abstraction Model Transmitter Abstraction Model 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 Driver Library. Library Interface Section Description System Interaction Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Client Setup Functions Provides open, close, status and other setup functions. Data Transfer Functions Provides data transfer functions available in the configuration. Miscellaneous Functions Provides miscellaneous driver functions. How the Library Works The library provides interfaces to support: • System Functionality • Client Functionality Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 521 System Access This section provides information on system access. Description System Access The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization, each instance of the I2C module would be initialized with the following configuration settings (either passed dynamically at run-time using DRV_I2C_INIT or by using initialization overrides) that are supported by the specific I2C device hardware: • Device requested power state: one of the System Module Power States. For specific details please refer to Data Types and Constants in the Library Interface section. • The actual peripheral ID enumerated as the PLIB level module ID (e.g., I2C_ID_2) • Master or Slave mode of operation and their associated parameters • Defining the respective interrupt sources for Master, Slave, and Error Interrupt The DRV_I2C_Initialize API returns an object handle of the type SYS_MODULE_OBJ. After this, the object handle returned by the Initialize interface would be used by the other system interfaces like DRV_I2C_Deinitialize, DRV_I2C_Status, and DRV_I2C_Tasks. Note: The system initialization settings, only affect the instance of the peripheral that is being initialized. Example: DRV_I2C_INIT i2c_init_data; SYS_MODULE_OBJ objectHandle; i2c_init_data.i2cId = DRV_I2C_PERIPHERAL_ID_IDX0, i2c_init_data.i2cMode = DRV_I2C_MODE_MASTER, OR i2c_init_data.i2cMode = DRV_I2C_MODE_SLAVE, /* Master mode parameters */ i2c_init_data.baudRate = 100000, i2c_init_data.busspeed = DRV_I2C_SLEW_RATE_CONTROL_IDX0, i2c_init_data.buslevel = DRV_I2C_SMBus_SPECIFICATION_IDX0, /* Master mode parameters */ i2c_init_data.addWidth = DRV_I2C_7BIT_SLAVE, i2c_init_data.reservedaddenable = false, i2c_init_data.generalcalladdress = false, i2c_init_data.slaveaddvalue = 0x0060, //interrupt sources i2c_init_data.mstrInterruptSource = INT_SOURCE_I2C_2_MASTER, i2c_init_data.slaveInterruptSource = INT_SOURCE_I2C_2_ERROR, i2c_init_data.errInterruptSource = INT_SOURCE_I2C_2_ERROR, i2c_init_data.queueSize = 1, /* callback for Master (Master mode can use callbacks if needed) */ i2c_init_data.operationStarting = NULL, /* Slave mode callbacks needed */ i2c_init_data.operationStarting = APP_I2CSlaveFunction, objectHandle = DRV_I2C_Initialize(DRV_I2C_INDEX_0, (SYS_MODULE_INIT *)&drvI2C0InitData) if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Since the I2C bus is controlled by the Master, the Slave should respond to a read or write request whenever the Master makes the request. Thus, the slave does not have driver states like the Master. The operation of the I2C Driver when used in Slave mode is handled using callbacks. The callback, OperationStarting, must be configured during system initialization when in Slave mode. This callback is provided so that the application can respond appropriately when a read or write request is received from the Master. Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 522 Client Access This section provides information on client access. Description For the application to start using an instance of the module, it must call the DRV_I2C_Open function. This provides the configuration required to open the I2C instance for operation. If the driver is deinitialized using the function DRV_I2C_Deinitialize, the application must call the DRV_I2C_Open function again to set up the instance of the I2C. For the various options available for IO_INTENT, please refer to Data Types and Constants in the Library Interface section. After a client instance is opened, DRV_I2C_ClientSetup can be called to set up client-specific parameters. In I2C Slave mode, this is used to set-up the IRQ logic so that the slave can toggle this line to request Master to send a Read command. As during initialization, when the I2C module operates in the Slave mode, only the Master can terminate a transaction with the Slave. In this case, the driver provides a callback to the application after the reception of each byte from the Master or after transmission of a byte to the Master. Example: /* I2C Driver Handle */ DRV_HANDLE drvI2CHandle; /* Open the I2C Driver */ appData.drvI2CHandle = DRV_I2C_Open( DRV_I2C_INDEX_0,DRV_IO_INTENT_WRITE ); if (drvI2CHandle != DRV_HANDLE_VALID) { //Client cannot open instance } Client Transfer This section provides information on client transfer functionality. Description Core Functionality Client basic functionality provides an extremely basic interface for the driver operation. The following diagram illustrates the byte/word model used for the data transfer. Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 523 Client Data Transfer Functionality Applications using the I2C driver need to perform the following: 1. The system should have completed necessary initialization and the DRV_I2C_Tasks should either be running in polled environment, or in an interrupt environment. 2. Open the driver using DRV_I2C_Open with the necessary intent. 3. Add a buffer using the DRV_I2C_Receive, DRV_I2C_Transmit, and DRV_I2C_TransmitThenReceive functions. An optional callback can be provided that will be called when the buffer/job is complete using DRV_I2C_BufferEventHandlerSet. 4. Check for the current transfer status using DRV_I2C_TransferStatusGet or wait for the callback to be called with buffer transfer status set to DRV_I2C_BUFFER_EVENT_COMPLETE or DRV_I2C_BUFFER_EVENT_ERROR. 5. Buffer status DRV_I2C_BUFFER_EVENT_COMPLETE implies that the I2C transaction has been completed without any errors. Buffer status DRV_I2C_BUFFER_EVENT_ERROR indicates that the I2C transaction was aborted and the entire contents of the buffer were not transferred. 6. In Master mode, common cases for DRV_I2C_BUFFER_EVENT_ERROR to be set are: • Slave is non-operational • Slave is performing an internal operation and cannot accept any more I2C messages from the Master until the operation completes. In such a case, if the Master tries to address the Slave and is attempting to transfer data, the Slave NACKs the transfer. This will result in the Master prematurely terminating the transaction and setting the DRV_I2C_BUFFER_EVENT_FLAG. In the application level, the Master can continuously attempt to send the transaction until transfer status changes from for DRV_I2C_BUFFER_EVENT_ERROR to DRV_I2C_BUFFER_EVENT_COMPLETE. This will in effect perform the so-called "Acknowledge Polling". An example of a Slave device that depicts this behavior is an EEPROM. Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 524 7. The client will be able to close the driver using DRV_I2C_Close when required. Example: /* This example demonstrates the I2C driver setup of one instance of I2C acting as a Master to another instance of the I2C Driver acting as a Slave. In the Slave initialization data structure in system_init.c, the member operationStarting should be assigned a function pointer. This function will be called when the Slave receives an address match. Based on the R/W bit in the address, the transmit or receive function will be called by the Slave (e.g., .operationStarting = APP_SlaveDataforMaster) */ SYS_MODULE_OBJ i2cMasterObject; SYS_MODULE_OBJ i2cSlaveObject; /* function prototype of callback function */ void I2CMasterOpStatusCb ( DRV_I2C_BUFFER_EVENT event, DRV_I2C_BUFFER_HANDLE bufferHandle, uintptr_t context); int main( void ) { while ( 1 ) { appTask (); } } void appTask () { #define MY_BUFFER_SIZE 5 #define RTCC_SLAVE_ADDRESS 0xDE /* initialize slave address value */ unsigned char address = RTCC_SLAVE_ADDRESS; /*Initialize myBuffer with MY_BUFFER_SIZE bytes of valid data */ char myBuffer[MY_BUFFER_SIZE] = { 11, 22, 33, 44, 55}; unsigned int numBytes; DRV_HANDLE drvI2CMasterHandle; //Returned from DRV_I2C_Open for I2C Master DRV_I2C_BUFFER_HANDLE bufHandle_M1; //Returned from calling a Data Transfer function uintptr_t i2cOpStatus; //Operation status of I2C operation returned from callback DRV_HANDLE drvI2CSlaveHandle; //Returned from DRV_I2C_Open for I2C Slave DRV_I2C_BUFFER_HANDLE bufHandle_S1; //Returned from calling a Data Transfer function DRV_I2C_BUFFER_HANDLE bufHandle_S2; //Returned from calling a Data Transfer function while( 1 ) { switch( state ) { case APP_STATE_INIT: { /* Initialize the Master I2C Driver */ i2cMasterObject = DRV_I2C_Initialize( DRV_I2C_INDEX_0, (SYS_MODULE_INIT *)&drvI2C0InitData ); /* Initialize the Slave I2C Driver */ i2cSlaveObject = DRV_I2C_Initialize(DRV_I2C_INDEX_1, (SYS_MODULE_INIT *)&drvI2C1InitData); /* Check for the System Status */ if( SYS_STATUS_READY != DRV_I2C_Status( i2cObject ) ) return 0; /* Open the Driver for I2C Master */ drvI2CMasterHandle = DRV_I2C_Open( DRV_I2C_INDEX_0,DRV_IO_INTENT_WRITE ); Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 525 if ( drvI2CMasterHandle != (DRV_HANDLE)NULL ) { /* event-handler set up receive callback from DRV_I2C_Tasks */ /* Event handler need to be set up only if needed */ DRV_I2C_BufferEventHandlerSet(drvI2CMasterHandle, I2CMasterOpStatusCb, i2cOpStatus ); /* Update the state to transfer data */ state = APP_STATE_DATA_PUT; } else { state = APP_STATE_ERROR; } /* Open the I2C Driver for Slave on the same device */ drvI2CSlaveHandle = DRV_I2C_Open( DRV_I2C_INDEX_1,DRV_IO_INTENT_WRITE ); if ( drvI2CMasterHandle != (DRV_HANDLE)NULL ) { /* event-handler set up receive callback from DRV_I2C_Tasks */ /* Event handler need to be set up only if needed */ DRV_I2C_BufferEventHandlerSet(drvI2CMasterHandle, I2CMasterOpStatusCb, i2cOpStatus ); /* Update the state to transfer data */ state = APP_STATE_DATA_PUT; } else { state = APP_STATE_ERROR; } break; } case APP_STATE_DATA_PUT: { /* I2C master writes data onto I2C bus */ bufHandle_M1 = DRV_I2C_Transmit ( drvI2CMasterHandle , address, &myBuffer[], 5, NULL ); /* Update the state to status check */ state = APP_STATE_DATA_CHECK; break; } case APP_STATE_DATA_CHECK: { /* Check for the successful data transfer */ if( DRV_I2C_BUFFER_EVENT_COMPLETE == DRV_I2C_TransferStatusGet (drvI2CMasterHandle, bufHandle_M1) ) { /* Do this repeatedly */ state = APP_STATE_DATA_PUT; } break; } case APP_STATE_ERROR: { //include any error handling routines here break; } default: { break; } } } Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 526 /****************************************************************************/ // Function: I2CMasterOpStatusCb // // Callback called in Master mode from the DRV_I2C_Tasks function. This // callback is invoked when the Master has to indicate to the application // that the BUFFER event is COMPLETE or there was an error in transmission. //****************************************************************************/ void I2CMasterOpStatusCb ( DRV_I2C_BUFFER_EVENT event, DRV_I2C_BUFFER_HANDLE bufferHandle, uintptr_t context) { switch(event) { case DRV_I2C_BUFFER_EVENT_COMPLETE: //this indicates that the I2C transaction has completed //DRV_I2C_BUFFER_EVENT_COMPLETE can be handled in the callback //or by checking for this event using the API DRV_I2C_BufferStatus /* include any callback event handling code here if needed */ break; case DRV_I2C_BUFFER_EVENT_ERROR: //this indicates that the I2C transaction has completed //and a STOP condition has been asserted on the bus. //However the slave has NACKED either the address or data //byte. /* include any callback event handling code here if needed */ default: break; } } //****************************************************************************/ // Function: APP_SlaveDataforMaster // // Callback function from DRV_I2C_Tasks when operating as a Slave. When an // address match is received by the Slave, this callback is executed and // the buffer event depends on the R/W bit. If R/W = 0, DRV_I2C_Receive is // called implying the Slave is going to read data send from the Master. // If R/W = 1, DRV_I2C_Transmit is called implying the Slave is going to send // data to the Master. //****************************************************************************/ void APP_SlaveDataforMaster(DRV_I2C_BUFFER_EVENT event, void * context) { switch (event) { case DRV_I2C_BUFFER_SLAVE_READ_REQUESTED: deviceAddressPIC32 = PIC32_SLAVE_ADDRESS; bufHandle_S1 = DRV_I2C_Receive( drvI2CSlaveHandle, deviceAddressPIC32, &SlaveRxbuffer[0], NUMBER_OF_UNKNOWN_BYTES_TO_SLAVE, NULL ); break; case DRV_I2C_BUFFER_SLAVE_WRITE_REQUESTED: deviceAddressPIC32 = PIC32_SLAVE_ADDRESS; bufHandle_S2 = DRV_I2C_Transmit ( drvI2CSlaveHandle, deviceAddressPIC32, &SlaveTxbuffer[0], NUMBER_OF_UNKNOWN_BYTES_TO_SLAVE, NULL ); break; default: break; } Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 527 } void __ISR(_I2C_2_VECTOR, ipl4AUTO) _IntHandlerDrvI2CInstance0(void) { DRV_I2C_Tasks(i2cMasterObject); } void __ISR(_I2C1_SLAVE_VECTOR, ipl6AUTO) _IntHandlerDrvI2CSlaveInstance1(void) { DRV_I2C_Tasks(i2cSlaveObject); } Configuring the Library Macros Name Description DRV_DYNAMIC_BUILD Dynamic driver build, dynamic device instance parameters. DRV_I2C_CONFIG_BUILD_TYPE Selects static or dynamic driver build configuration. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_BASIC Enables the device driver to support basic transfer mode. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_BLOCKING Enables the device driver to support blocking operations. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_EXCLUSIVE Enables the device driver to support operation in Exclusive mode. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_MASTER Enables the device driver to support operation in Master mode. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_NON_BLOCKING Enables the device driver to support non-blocking during operations DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_READ Enables the device driver to support read operations. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_SLAVE Enables the device driver to support operation in Slave mode. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_WRITE Enables the device driver to support write operations. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_WRITE_READ Enables the device driver to support write followed by read. DRV_STATIC_BUILD Static driver build, static device instance parameters. DRV_I2C_FORCED_WRITE Includes function that writes to slave irrespective of whether receiving a ACK or NACK from slave I2C_STATIC_DRIVER_MODE Selects the type of STATIC driver Description The configuration of the I2C Driver Library is based on the file sys_config.h. This header file contains the configuration selection for the I2C Driver Library. Based on the selections made, the I2C Driver Library may support the selected features. These configuration settings will apply to all instances of the I2C Driver 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. DRV_DYNAMIC_BUILD Macro Dynamic driver build, dynamic device instance parameters. File drv_i2c_config_template.h C #define DRV_DYNAMIC_BUILD 1 Description Dynamic Driver Build Configuration This value, if used to identify the build type for a driver, will cause the driver to be built to dynamically, identify the instance of the peripheral at run-time using the parameter passed into its API routines. Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 528 DRV_I2C_CONFIG_BUILD_TYPE Macro Selects static or dynamic driver build configuration. File drv_i2c_config_template.h C #define DRV_I2C_CONFIG_BUILD_TYPE DRV_DYNAMIC_BUILD Description I2C Driver Build Configuration Type This definition selects if I2C device driver is to be used with static or dynamic build parameters. Must be equated to one of the following values: • DRV_STATIC_BUILD - Build the driver using static accesses to the peripheral identified by the DRV_I2C_INSTANCE macro • DRV_DYNAMIC_BUILD - Build the driver using dynamic accesses to the peripherals Affects all the drv_i2c.h driver functions. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_BASIC Macro Enables the device driver to support basic transfer mode. File drv_i2c_config_template.h C #define DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_BASIC Description Support Basic Transfer Mode This definition enables the device driver to support basic transfer mode. Remarks The device driver can support multiple modes within a single build. This definition affects the following functions: • DRV_I2C_TransmitThenReceive Refer to the description of each function in the corresponding help file for details. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_BLOCKING Macro Enables the device driver to support blocking operations. File drv_i2c_config_template.h C #define DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_BLOCKING Description Support Blocking Operations This definition enables the device driver to support blocking operations. Remarks The device driver can support multiple modes within a single build. This definition affects the following functions: • DRV_I2C_Open • DRV_I2C_Close • DRV_I2C_Receive Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 529 • DRV_I2C_Transmit • DRV_I2C_TransmitThenReceive Refer to the description of each function in the corresponding help file for details. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_EXCLUSIVE Macro Enables the device driver to support operation in Exclusive mode. File drv_i2c_config_template.h C #define DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_EXCLUSIVE Description Support Exclusive Mode This definition enables the device driver to support operation in Exclusive mode. Remarks The device driver can support multiple modes within a single build. This definition affects the following functions: • DRV_I2C_Open Refer to the description of each function in the corresponding help file for details. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_MASTER Macro Enables the device driver to support operation in Master mode. File drv_i2c_config_template.h C #define DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_MASTER Description Support Master Mode This definition enables the device driver to support operation in Master mode. Remarks During the configuration phase, the driver selects a list of operation modes that can be supported. While initializing a hardware instance, the device driver will properly perform the initialization base on the selected modes. The device driver can support multiple modes within a single build. Refer to the description of each function in the corresponding help file for details. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_NON_BLOCKING Macro Enables the device driver to support non-blocking during operations File drv_i2c_config_template.h C #define DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_NON_BLOCKING Description Support Non-Blocking Operations This definition enables the device driver to support non-blocking operations. Remarks The device driver can support multiple modes within a single build. This definition affects the following functions: Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 530 • DRV_I2C_Open • DRV_I2C_Close Refer to the description of each function in the corresponding help file for details. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_READ Macro Enables the device driver to support read operations. File drv_i2c_config_template.h C #define DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_READ Description Support Read Mode This definition enables the device driver to support read operations. Remarks The device driver can support multiple modes within a single build. This definition affects the following functions: • DRV_I2C_Receive Refer to the description of each function in the corresponding help file for details. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_SLAVE Macro Enables the device driver to support operation in Slave mode. File drv_i2c_config_template.h C #define DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_SLAVE Description Support Slave Mode This definition enables the device driver to support operation in Slave mode. Remarks During the configuration phase, the driver selects a list of operation modes that can be supported. While initializing a hardware instance, the device driver will properly perform the initialization base on the selected modes. The device driver can support multiple modes within a single build. Refer to the description of each function in the corresponding help file for details. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_WRITE Macro Enables the device driver to support write operations. File drv_i2c_config_template.h C #define DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_WRITE Description Support Write Mode This definition enables the device driver to support write operations. Remarks The device driver can support multiple modes within a single build. This definition affects the following functions: Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 531 • DRV_I2C_Transmit Refer to the description of each function in the corresponding help file for details. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_WRITE_READ Macro Enables the device driver to support write followed by read. File drv_i2c_config_template.h C #define DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_WRITE_READ Description Support Write followed by a Read using Restart This definition enables the device driver to support write followed by read without relinquishing control of the bus. Restart is issued instead of Stop at the end of write. Stop is issued after read operation. Remarks The device driver can support multiple modes within a single build. This definition affects the following functions: • DRV_I2C_TransmitThenReceive Refer to the description of each function in the corresponding help file for details. DRV_STATIC_BUILD Macro Static driver build, static device instance parameters. File drv_i2c_config_template.h C #define DRV_STATIC_BUILD 0 Description Static Driver Build Configuration This value, if used to identify the build type for a driver, will cause the driver to be built using a specific statically identified instance of the peripheral. DRV_I2C_FORCED_WRITE Macro Includes function that writes to slave irrespective of whether receiving a ACK or NACK from slave File drv_i2c_config_template.h C #define DRV_I2C_FORCED_WRITE true Description I2C driver objects configuration When this option is checked, this will include Forced Write function. The Force Write function will send all data bytes to the slave irrespective of receiving ACK or NACK from slave. If writing data to the slave is invoked using DRV_I2C_Transfer, the transaction will be aborted if the Slave NACKs address or any data byte and a STOP condition will be send. This function is typically included for Slaves that require a special reset sequence. Remarks None I2C_STATIC_DRIVER_MODE Macro Selects the type of STATIC driver Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 532 File drv_i2c_config_template.h C #define I2C_STATIC_DRIVER_MODE BUFFER_MODEL_STATIC Description I2C Static Driver type This selects either the BYTE_MODEL_STATIC or BUFFER_MODEL_STATIC version of I2C driver. The BYTE_MODEL_STATIC version is equivalent to and is referred to as STATIC driver implementation in Harmony Versions 1.06.02 and below. This version of STATIC driver is not recommended for new design and will be deprecated in future release. The BUFFER_MODEL_STATIC supports transfer of buffers and is API compatible with the DYNAMIC implementation of I2C. Building the Library This section lists the files that are available in the I2C Driver Library. 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 /framework/driver/i2c. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_i2c.h This file provides the interface definitions of the I2C driver. /drv_i2c_bb.h This file provides interface definitions that are transparent to the user when the I2C Driver is used in Bit-bang mode. /src/drv_i2c_local.h This file provides definitions of the data types that are used in the driver object. 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 /src/dynamic/drv_i2c.c This file contains the core implementation of the I2C driver. /src/dynamic/drv_i2c_bb.c This file implements the I2C Driver in Bit-bang mode. 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 N/A No optional files exist for this library. Module Dependencies The I2C Driver Library depends on the following modules: • Clock System Service Library Library Interface a) System Interaction Functions Name Description DRV_I2C_Deinitialize Deinitializes the index instance of the I2C module. Implementation: Static/Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 533 DRV_I2C_Initialize Initializes hardware and data for the index instance of the I2C module. Implementation: Static/Dynamic DRV_I2C_Tasks Maintains the State Machine of the I2C driver and performs all the protocol level actions. Implementation: Dynamic b) Client Setup Functions Name Description DRV_I2C_Close Closes an opened instance of an I2C module driver. Implementation: Dynamic DRV_I2C_Open Opens the specified instance of the I2C driver for use and provides an "open-instance" handle. Implementation: Dynamic c) Data Transfer Functions Name Description DRV_I2C_BufferEventHandlerSet Allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. Implementation: Dynamic DRV_I2C_BytesTransferred Returns the number of bytes transmitted or received in a particular I2C transaction. The transaction is identified by the handle. DRV_I2C_Receive This function reads data written from either Master or Slave. Implementation: Dynamic DRV_I2C_Transmit This function writes data to Master or Slave. Implementation: Dynamic DRV_I2C_TransmitThenReceive This function writes data to Slave, inserts restart and requests read from slave. Implementation: Dynamic DRV_I2C_TransmitForced This function writes data to Master or Slave. Implementation: Dynamic d) Status Functions Name Description DRV_I2C_TransferStatusGet Returns status of data transfer when Master or Slave acts either as a transmitter or a receiver. Implementation: Dynamic DRV_I2C_Status Provides the current status of the index instance of the I2C module. Implementation: Dynamic e) Miscellaneous Functions Name Description DRV_I2C_QueueFlush The existing transactions in the queue are voided and the queue pointers are reset to their initial state. This renders the queue empty. DRV_I2C_SlaveCallbackSet Allows a client to identify a Slave Callback function for the driver to call back when drivers needs to initiate a read or write operation. f) Data Types and Constants Name Description DRV_I2C_BUFFER_QUEUE_SUPPORT Specifies if the Buffer Queue support should be enabled. DRV_I2C_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_I2C_INTERRUPT_MODE Macro controls interrupt based operation of the driver DRV_I2C_QUEUE_DEPTH_COMBINED Number of entries of all queues in all instances of the driver. DRV_I2C_BB_H This is macro DRV_I2C_BB_H. Description This section describes the Application Programming Interface (API) functions of the I2C Driver Library. Refer to each section for a detailed description. a) System Interaction Functions Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 534 DRV_I2C_Deinitialize Function Deinitializes the index instance of the I2C module. Implementation: Static/Dynamic File drv_i2c.h C void DRV_I2C_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description This function deinitializes the index instance of the I2C module, disabling its operation (and any hardware for driver modules). It deinitializes only the specified module instance. It also resets all the internal data structures and fields for the specified instance to the default settings. Remarks If the module instance has to be used again, DRV_I2C_Initialize should be called again to initialize the module instance structures. This function may block if the driver is running in an OS environment that supports blocking operations and the driver requires system resources access. However, the routine will NEVER block for hardware I2C access. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_I2C_Status operation. The driver client must always use DRV_I2C_Status to find out when the module is in the ready state. Preconditions The DRV_I2C_Initialize function should have been called before calling this function. Example SYS_STATUS i2c_status; DRV_I2C_Deinitialize(I2C_ID_1); i2c_status = DRV_I2C_Status(I2C_ID_1); if (SYS_STATUS_BUSY == i2c_status) { // Do something else and check back later } else if (SYS_STATUS_ERROR >= i2c_status) { // Handle error } Parameters Parameters Description index Index, identifying the instance of the I2C module to be deinitialized Function void DRV_I2C_Deinitialize ( SYS_MODULE_OBJ object ) DRV_I2C_Initialize Function Initializes hardware and data for the index instance of the I2C module. Implementation: Static/Dynamic File drv_i2c.h C SYS_MODULE_OBJ DRV_I2C_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 535 Returns None. Description This function initializes hardware for the index instance of the I2C module, using the hardware initialization given data. It also initializes any internal driver data structures making the driver ready to be opened. Remarks This function must be called before any other I2C function is called. This function should only be called once during system initialization unless DRV_I2C_Deinitialize is first called to deinitialize the device instance before reinitializing it. This function may block if the driver is running in an OS environment that supports blocking operations and the driver requires system resources access. However, the routine will NEVER block for hardware I2C access. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_I2C_Status operation. The driver client must always use DRV_I2C_Status to find out when the module is in the ready state. Whenever a call to DRV_I2C_Initialize is made with a SYS_MODULE_INIT* data == 0 the following default configuration will be used. Adjust this configuration at build time as needed. Preconditions None. Example DRV_I2C_INIT i2c_init_data; SYS_MODULE_OBJ objectHandle; i2c_init_data.i2cId = DRV_I2C_PERIPHERAL_ID_IDX0, i2c_init_data.i2cMode = DRV_I2C_MODE_MASTER, OR i2c_init_data.i2cMode = DRV_I2C_MODE_SLAVE, //Master mode parameters i2c_init_data.baudRate = 100000, i2c_init_data.busspeed = DRV_I2C_SLEW_RATE_CONTROL_IDX0, i2c_init_data.buslevel = DRV_I2C_SMBus_SPECIFICATION_IDX0, //Slave mode parameters i2c_init_data.addWidth = DRV_I2C_7BIT_SLAVE, i2c_init_data.reservedaddenable = false, i2c_init_data.generalcalladdress = false, i2c_init_data.slaveaddvalue = 0x0060, //interrupt sources i2c_init_data.mstrInterruptSource = INT_SOURCE_I2C_2_MASTER, i2c_init_data.slaveInterruptSource = INT_SOURCE_I2C_2_ERROR, i2c_init_data.errInterruptSource = INT_SOURCE_I2C_2_ERROR, i2c_init_data.queueSize = 1, //callback for Master (Master mode can use callbacks if needed) i2c_init_data.operationStarting = NULL, // Slave mode callbacks needed i2c_init_data.operationStarting = APP_I2CSlaveFunction(), i2c_init_data.operationEnded = NULL objectHandle = DRV_I2C_Initialize(DRV_I2C_INDEX_0, (SYS_MODULE_INIT *)&drvI2C0InitData) if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Index, identifying the instance of the I2C module to be initialized Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 536 data Pointer to the data structure containing any data necessary to initialize the hardware. This pointer may be null if no data is required and the default initialization is to be used. Function void DRV_I2C_Initialize ( const I2C_MODULE_ID index, const SYS_MODULE_INIT *const data ) DRV_I2C_Tasks Function Maintains the State Machine of the I2C driver and performs all the protocol level actions. Implementation: Dynamic File drv_i2c.h C void DRV_I2C_Tasks(SYS_MODULE_OBJ object); Description This functions maintains the internal state machine of the I2C driver. This function acts as the I2C Master or Slave ISR. When used in polling mode, this function needs to be called repeatedly to achieve I2C data transfer. This function implements all the protocol level details like setting the START condition, sending the address with with R/W request, writing data to the SFR, checking for acknowledge and setting the STOP condition. Preconditions The DRV_I2C_Initialize routine must have been called for the specified I2C device instance. Example SYS_MODULE_OBJ object; while (true) { DRV_I2C_Tasks ( object ); Function void DRV_I2C_Tasks (SYS_MODULE_OBJ object) b) Client Setup Functions DRV_I2C_Close Function Closes an opened instance of an I2C module driver. Implementation: Dynamic File drv_i2c.h C void DRV_I2C_Close(DRV_HANDLE handle); Returns None. Description This function closes an opened instance of an I2C module driver, making the specified handle invalid. Remarks After calling This function, the handle passed into drvHandle must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_I2C_Open before the caller may use the driver again. Preconditions The DRV_I2C_Initialize routine must have been called for the specified I2C device instance and the DRV_I2C_Status must have returned SYS_STATUS_READY. DRV_I2C_Open must have been called to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 537 Example myI2CHandle = DRV_I2C_Open(I2C_ID_1, DRV_IO_INTENT_NONBLOCKING|DRV_IO_INTENT_READWRITE); // Perform data transfer operations DRV_I2C_Close(myI2CHandle); Parameters Parameters Description drvHandle A valid open-instance handle, returned from the driver's open routine Function void DRV_I2C_Close ( const DRV_HANDLE drvHandle ) DRV_I2C_Open Function Opens the specified instance of the I2C driver for use and provides an "open-instance" handle. Implementation: Dynamic File drv_i2c.h C DRV_HANDLE DRV_I2C_Open(const SYS_MODULE_INDEX index, const DRV_IO_INTENT intent); Returns If successful, the routine returns a valid open-instance handle (a value identifying both the caller and the module instance). If an error occurs, the returned value is DRV_HANDLE_INVALID. If an error occurs, the return value is DRV_HANDLE_INVALID. An error can occur when the following is true: • if the number of client objects allocated via DRV_I2C_INSTANCES_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the driver hardware instance being opened is not initialized or is invalid Description This function opens the specified instance of the I2C module for use and provides a handle that is required to use the remaining driver routines. This function opens a specified instance of the I2C module driver for use by any client module and provides an "open-instance" handle that must be provided to any of the other I2C driver operations to identify the caller and the instance of the I2C driver/hardware module. Remarks The handle returned is valid until the DRV_I2C_Close routine is called. This function may block if the driver is running in an OS environment that supports blocking operations and the driver requires system resources access. Regarding the hardware I2C access the operation will behave as instructed by the DRV_IO_INTENT parameter. Preconditions The DRV_I2C_Initialize routine must have been called for the specified I2C device instance and the DRV_I2C_Status must have returned SYS_STATUS_READY. Example DRV_HANDLE i2c_handle; i2c_handle = DRV_I2C_Open(I2C_ID_1, DRV_IO_INTENT_NONBLOCKING|DRV_IO_INTENT_READWRITE); if (DRV_HANDLE_INVALID == i2c_handle) { // Handle open error } // Close the device when it is no longer needed. DRV_I2C_Close(i2c_handle); Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 538 Parameters Parameters Description index Index, identifying the instance of the I2C module to be opened. intent Flags parameter identifying the intended usage and behavior of the driver. Multiple flags may be ORed together to specify the intended usage of the device. See the DRV_IO_INTENT definition. Function DRV_HANDLE DRV_I2C_Open ( const I2C_MODULE_ID index, const DRV_IO_INTENT intent ) c) Data Transfer Functions DRV_I2C_BufferEventHandlerSet Function Allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. Implementation: Dynamic File drv_i2c.h C void DRV_I2C_BufferEventHandlerSet(const DRV_HANDLE handle, const DRV_I2C_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t context); Returns None. Description This function allows a client to identify a buffer event handling function for the driver to call back when a queued buffer transfer has finished. When a client calls either the DRV_I2C_Receive, DRV_I2C_Transmit or DRV_I2C_TransmiThenReceive function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed. The event handler should be set before the client performs any transmision or reception operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). When in Master mode, a callback event is registered to let the application know that the buffer has been transmitted. DRV_I2C_BUFFER_EVENT_COMPLETE is set when the buffer has been transmitted without any errors. DRV_I2C_BUFFER_EVENT_ERROR is set when buffer transmission or reception has been aborted. When in Slave mode, since the Master controls when a transmit or receive operation is terminated, a callback is registered every time a byte is written or read from the slave. Remarks If the client does not want to be notified when the queued buffer transfer has completed, it does not need to register a callback. This function is thread safe when called in a RTOS application. Preconditions The DRV_I2C_Initialize routine must have been called for the specified I2C driver instance. DRV_I2C_Open must have been called to obtain a valid opened device handle. Example #define MY_BUFFER_SIZE 10 // function prototype of Event Handler Function void APP_I2CBufferEventFunction ( DRV_I2C_BUFFER_EVENT event, DRV_I2C_BUFFER_HANDLE bufferHandle, uintptr_t context ); //Returned from DRV_I2C_Open DRV_HANDLE drvI2Chandle; // myAppObj is an application specific state data object. Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 539 DRV_I2C_BUFFER_EVENT operationStatus; uint8_t appBuffer[MY_BUFFER_SIZE]; DRV_I2C_BUFFER_HANDLE drvI2CRDBUFHandle // Opens an instance of I2C driver drvI2Chandle = DRV_I2C_Open( DRV_I2C_INDEX_0,DRV_IO_INTENT_WRITE ); // Client registers an event handler with driver. This is done once. DRV_I2C_BufferEventHandlerSet( drvI2Chandle, APP_I2CBufferEventFunction, operationStatus ); drvI2CRDBUFHandle = DRV_I2C_Receive ( drvI2CHandle, slaveaddress &appBuffer[], MY_BUFFER_SIZE, NULL ); if(NULL == drvI2CRDBUFHandle) { // Error handling here } // Event Processing Technique. Event is received when // the buffer is processed. void APP_I2CBufferEventFunction( DRV_I2C_BUFFER_EVENT event, DRV_I2C_BUFFER_HANDLE handle, uintptr_t context) { switch(event) { case DRV_I2C_BUFFER_EVENT_COMPLETE: //perform appropriate action break; case DRV_I2C_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine eventHandler Pointer to the event handler function. context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_I2C_BufferEventHandlerSet ( const DRV_HANDLE handle, const DRV_I2C_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t context ) DRV_I2C_BytesTransferred Function Returns the number of bytes transmitted or received in a particular I2C transaction. The transaction is identified by the handle. Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 540 File drv_i2c.h C uint32_t DRV_I2C_BytesTransferred(DRV_HANDLE handle, DRV_I2C_BUFFER_HANDLE bufferHandle); Returns The number of bytes transferred in a particular I2C transaction. numOfBytes = DRV_I2C_BytesTransferred (drvI2CHandle_Master,drvBufferHandle); Description This returns the transmitter and receiver transfer status. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine bufferHandle A valid buffer handle obtained when calling Transmit/Receive/TransmitThenReceive/TransmitForced or BufferAddRead/BufferAddWrite/BufferAddReadWrite function Function uint32_t DRV_I2C_BytesTransferred ( DRV_I2C_BUFFER_HANDLE bufferHandle ) DRV_I2C_Receive Function This function reads data written from either Master or Slave. Implementation: Dynamic File drv_i2c.h C DRV_I2C_BUFFER_HANDLE DRV_I2C_Receive(DRV_HANDLE handle, uint16_t address, void * buffer, size_t size, void * callbackContext); Returns A valid BUFFER HANDLE, NULL if the handle is not obtained. Description Master calls this function to read data send by Slave. The Slave calls this function to read data send by Master. In case of Master, a START condition is initiated on the I2C bus. Remarks The handle that is passed into the function, drvI2CHandle is obtained by calling the DRV_I2C_OPEN function. If the function could not return a valid buffer handle, then a NULL value is returned. If the slave NACKs the address byte, then further read is not attempted. Master asserts STOP condition and DRV_I2C_BUFFER_EVENT_ERROR is set as the buffer-status. If all the requisite number of bytes have been read then DRV_I2C_BUFFER_EVENT_COMPLETE is set as the buffer status. Preconditions The DRV_I2C_Initialize routine must have been called for the specified I2C device instance and the DRV_I2C_Status must have returned SYS_STATUS_READY. DRV_I2C_Open must have been called to obtain a valid opened device handle. Example drvI2CRDBUFHandle = DRV_I2C_Receive( drvI2CHandle, deviceaddress, &rxbuffer[0], num_of_bytes, NULL ); Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 541 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine address Device address of slave shifted so that bits 7 - 1 are address bits A6 A0. This value is Ignored in slave mode. buffer This buffer holds data is received size The number of bytes that the Master expects to read from Slave. This value can be kept as the MAX BUFFER SIZE for slave. This is because the Master controls when the READ operation is terminated. callbackContext Not implemented, future expansion Function DRV_I2C_BUFFER_HANDLE DRV_I2C_Receive ( DRV_HANDLE handle, uint16_t slaveaddress, void *rxBuffer, size_t size, void * callbackContext ) DRV_I2C_Transmit Function This function writes data to Master or Slave. Implementation: Dynamic File drv_i2c.h C DRV_I2C_BUFFER_HANDLE DRV_I2C_Transmit(DRV_HANDLE handle, uint16_t slaveaddress, void * buffer, size_t size, void * context); Returns A valid BUFFER HANDLE, NULL if the handle is not obtained. Description Master calls this function to write data to Slave. The Slave calls this function to write data to Master. Remarks The handle that is passed into the function, drvI2CHandle is obtained by calling the DRV_I2C_OPEN function. If the function could not return a valid buffer handle, then a NULL value is returned. If the slave NACKs the address byte or any data bytes, then further write is not attempted. Master asserts STOP condition and DRV_I2C_BUFFER_EVENT_ERROR is set as the buffer-status. If all the requisite number of bytes have been transmitted to the Slave, then DRV_I2C_BUFFER_EVENT_COMPLETE is set as the buffer status. Preconditions The DRV_I2C_Initialize routine must have been called for the specified I2C device instance and the DRV_I2C_Status must have returned SYS_STATUS_READY. DRV_I2C_Open must have been called to obtain a valid opened device handle. Example drvI2CWRBUFHandle = DRV_I2C_Transmit( drvI2CHandle, deviceaddress, &txBuffer[0], num_of_bytes, NULL); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine address Device address of slave shifted so that bits 7 - 1 are address bits A6 A0. This value is Ignored in slave mode. buffer Contains data to be transferred Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 542 size The number of bytes that the Master expects to write to Slave. This value can be kept as the MAX BUFFER SIZE for slave. This is because the Master controls when the WRITE operation is terminated. callbackContext Not implemented, future expansion Function DRV_I2C_BUFFER_HANDLE DRV_I2C_Transmit( DRV_HANDLE handle, uint16_t slaveaddress, void *txBuffer, size_t size, void *context); DRV_I2C_TransmitThenReceive Function This function writes data to Slave, inserts restart and requests read from slave. Implementation: Dynamic File drv_i2c.h C DRV_I2C_BUFFER_HANDLE DRV_I2C_TransmitThenReceive(DRV_HANDLE handle, uint16_t address, void * writeBuffer, size_t writeSize, void * readBuffer, size_t readSize, void * callbackContext); Returns A valid BUFFER HANDLE, NULL if the handle is not obtained. Description Master calls this function to send a register address value to the slave and then queries the slave with a read request to read the contents indexed by the register location. The Master sends a restart condition after the initial write before sending the device address with R/W = 1. The restart condition prevents the Master from relinquishing the control of the bus. The slave should not use this function. Remarks The handle that is passed into the function, drvI2CHandle is obtained by calling the DRV_I2C_OPEN function. If the function could not return a valid buffer handle, then a NULL value is returned. If there is any error condition during transmission then further transmission or reception is not attempted and STOP condition is asserted on the bus. In case of error condition, DRV_I2C_BUFFER_EVENT_ERROR is set as the buffer-status. If the I2C bus transaction is completed as requested then the buffer status, is set as DRV_I2C_BUFFER_EVENT_COMPLETE. Preconditions The DRV_I2C_Initialize routine must have been called for the specified I2C device instance and the DRV_I2C_Status must have returned SYS_STATUS_READY. DRV_I2C_Open must have been called to obtain a valid opened device handle. Example drvI2CRDBUFHandle = DRV_I2C_TransmiThenReceive( appData.drvI2CHandle, deviceaddress, &drvI2CTXbuffer[0], registerbytesize, rxbuffer, num_of_bytes, NULL ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine address Device address of slave shifted so that bits 7 - 1 are address bits A6 A0. This value is Ignored in slave mode. writeBuffer Contains data to be transferred writeSize The number of bytes that the Master expects to write to Slave. This value can be kept as the MAX BUFFER SIZE for slave. This is because the Master controls when the WRITE operation is terminated. readBuffer This buffer holds data that is send back from slave after read operation. Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 543 readSize The number of bytes the Master expects to be read from the slave callbackContext Not implemented, future expansion Function DRV_I2C_BUFFER_HANDLE DRV_I2C_TransmiThenReceive ( DRV_HANDLE handle, uint16_t deviceaddress, void *txBuffer, size_t writeSize, void *rxBuffer, size_t readSize, void *context) DRV_I2C_TransmitForced Function This function writes data to Master or Slave. Implementation: Dynamic File drv_i2c.h C DRV_I2C_BUFFER_HANDLE DRV_I2C_TransmitForced(DRV_HANDLE handle, uint16_t deviceaddress, void* txBuffer, size_t txbuflen, DRV_I2C_BUS_ERROR_EVENT eventFlag, void * calbackContext); Returns A valid BUFFER HANDLE, NULL if the handle is not obtained. Description Master calls this function to transmit the entire buffer to the slave even if the slave ACKs or NACKs the address or any of the data bytes. This is typically used for slaves that have to initiate a reset sequence by sending a dummy I2C transaction. Since the slave is still in reset, any or all the bytes can be NACKed. In the normal operation of the driver if the address or data byte is NACKed, then the transmission is aborted and a STOP condition is asserted on the bus. Remarks The handle that is passed into the function, drvI2CHandle is obtained by calling the DRV_I2C_OPEN function. If the function could not return a valid buffer handle, then a NULl value is returned. Once all the bytes are transferred the buffer status is set as then DRV_I2C_BUFFER_EVENT_COMPLETE . Preconditions The DRV_I2C_Initialize routine must have been called for the specified I2C device instance and the DRV_I2C_Status must have returned SYS_STATUS_READY. DRV_I2C_Open must have been called to obtain a valid opened device handle. Example drvI2CWRBUFHandle = DRV_I2C_TransmitForced ( handle, deviceaddress, &txBuffer[0], txbuflen, NULL, NULL) Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine address Device address of slave shifted so that bits 7 - 1 are address bits A6 A0. This value is Ignored in slave mode. buffer Contains data to be transferred size The number of bytes that the Master expects to write to Slave. This value can be kept as the MAX BUFFER SIZE for slave. This is because the Master controls when the WRITE operation is terminated. eventFlag This field is left for future implementation Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 544 callbackContext Not implemented, future expansion Function DRV_I2C_BUFFER_HANDLE DRV_I2C_TransmitForced ( DRV_HANDLE handle, uint16_t deviceaddress, uint8_t* txBuffer, uint16_t txbuflen, DRV_I2C_BUS_ERROR_EVENT eventFlag, void * calbackContext) d) Status Functions DRV_I2C_TransferStatusGet Function Returns status of data transfer when Master or Slave acts either as a transmitter or a receiver. Implementation: Dynamic File drv_i2c.h C DRV_I2C_BUFFER_EVENT DRV_I2C_TransferStatusGet(DRV_HANDLE handle, DRV_I2C_BUFFER_HANDLE bufferHandle); Returns A DRV_I2C_TRANSFER_STATUS value describing the current status of the transfer. Description The bufferHandle parameter contains the buffer handle of the buffer that associated with the event. If the event is DRV_I2C_BUFFER_EVENT_COMPLETE, it means that the data was transferred successfully. If the event is DRV_I2C_BUFFER_EVENT_ERROR, it means that the data was not transferred successfully. Remarks The handle that is passed into the function, drvI2CBUFHandle is obtained by calling one of the data transfer functions. The drvI2CBUFHandle should be a valid handle and not a NULL value. The DRV_I2C_BufferStatus can be called to check the progress of the data transfer operation. If the buffer is transferred without any error, then DRV_I2C_BUFFER_EVENT_COMPLETE is returned. If an error condition is present, then DRV_I2C_BUFFER_EVENT_ERROR is returned. Example if(DRV_I2C_BUFFER_EVENT_COMPLETE == DRV_I2C_TransferStatusGet ( handle, bufferHandle )) { //perform action return true; } else { //perform action return false; } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine bufferHandle A valid buffer handle obtained when calling Transmit/Receive/TransmitThenReceive/TransmitForced or BufferAddRead/BufferAddWrite/BufferAddReadWrite function Function DRV_I2C_BUFFER_EVENT DRV_I2C_TransferStatusGet ( DRV_HANDLE handle, DRV_I2C_BUFFER_HANDLE bufferHandle ) Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 545 DRV_I2C_Status Function Provides the current status of the index instance of the I2C module. Implementation: Dynamic File drv_i2c.h C SYS_STATUS DRV_I2C_Status(SYS_MODULE_OBJ object); Returns • SYS_STATUS_READY - Indicates that any previous module operation for the specified I2Cmodule has completed. • SYS_STATUS_BUSY - Indicates that a previous module operation for the specified I2C module has not yet completed • SYS_STATUS_ERROR - Indicates that the specified I2C module is in an error state Description This function provides the current status of the index instance of the I2C module. Remarks The DRV_I2C_Status operation can be used to determine when any of the I2C module level operations has completed. The value returned by the DRV_I2C_Status routine hast to be checked after calling any of the I2C module operations to find out when they have completed. If the DRV_I2C_Status operation returns SYS_STATUS_BUSY, the previous operation has not yet completed. Once the DRV_I2C_Status operation return SYS_STATUS_READY, any previous operations have completed. The DRV_I2C_Status function will NEVER block. If the DRV_I2C_Status operation returns an error value, the error may be cleared by calling the DRV_I2C_Initialize operation. If that fails, the DRV_I2C_Deinitialize operation will need to be called, followed by the DRV_I2C_Initialize operation to return to normal operations. Preconditions The DRV_I2C_Initialize function should have been called before calling this function. Example SYS_MODULE_OBJ object; SYS_STATUS i2c_status; i2c_status = DRV_I2C_Status(object); if (SYS_STATUS_BUSY == i2c_status) { // Do something else and check back later } else if (SYS_STATUS_ERROR >= status) { // Handle error } Parameters Parameters Description index Index, identifying the instance of the I2C module to get status for. Function SYS_STATUS DRV_I2C_Status ( SYS_MODULE_OBJ object ) e) Miscellaneous Functions DRV_I2C_QueueFlush Function The existing transactions in the queue are voided and the queue pointers are reset to their initial state. This renders the queue empty. Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 546 File drv_i2c.h C void DRV_I2C_QueueFlush(DRV_HANDLE handle); Returns None //Opens an instance of I2C driver drvI2Chandle = DRV_I2C_Open( DRV_I2C_INDEX_0,DRV_IO_INTENT_WRITE ); DRV_I2C_QueueFlush ( drvI2CHandle ); Description The existing transactions in the queue are voided and the queue pointers are reset to their initial state. This renders the queue empty. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_I2C_QueueFlush ( DRV_HANDLE handle ) DRV_I2C_SlaveCallbackSet Function Allows a client to identify a Slave Callback function for the driver to call back when drivers needs to initiate a read or write operation. File drv_i2c.h C void DRV_I2C_SlaveCallbackSet(const DRV_HANDLE handle, const DRV_I2C_CallBack callback, const uintptr_t context); Returns None #define APP_I2C_BUFFER_SIZE 10 void APP_I2C_SlaveTransferCallback( DRV_I2C_BUFFER_EVENT event, void * context ); uint8_t slaveBuffer[ APP_I2C_BUFFER_SIZE ]; DRV_HANDLE drvI2CHandle; void APP_I2C_SlaveTransferCallback( DRV_I2C_BUFFER_EVENT event, void * context ) { switch (event) { case DRV_I2C_BUFFER_SLAVE_READ_REQUESTED: { appData.bufferReceive = DRV_I2C_Receive( drvI2CHandle, 0, &slaveBuffer[0], APP_I2C_BUFFER_SIZE, NULL ); break; } case DRV_I2C_BUFFER_SLAVE_WRITE_REQUESTED: { appData.bufferTransmit = DRV_I2C_Transmit ( drvI2CHandle, 0, &slaveBuffer[0], APP_I2C_BUFFER_SIZE, Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 547 NULL ); break; } default: { break; } } return; } // Opens an instance of I2C driver drvI2Chandle = DRV_I2C_Open( DRV_I2C_INDEX_0, DRV_IO_INTENT_READWRITE ); // Set the operation callback DRV_I2C_SlaveCallbackSet( drvI2Chandle, APP_I2C_SlaveTransferCallback, 0); Description This function allows a client to identify a Slave Callback function for the driver to call back when drivers needs to initiate a read or write operation. When the I2C Slave driver receives a read or write event from master the callback is called to initiate the user defined action. The callback should be set before the master requests for read or write operations. The event handler once set, persists until the client closes the driver or sets another event handler. In Slave mode, a callback event is registered to let the application know that master has requested for either read or write operation. DRV_I2C_BUFFER_SLAVE_READ_REQUESTED is set when the master sends data and wants slave to read. DRV_I2C_BUFFER_SLAVE_WRITE_REQUESTED is set when the master tries to read data from slave and wants slave to send the data. Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine callback pointer to the callback function. context The value of parameter will be passed back to the client unchanged, when the callback function is called. It can be used to identify any client specific data Function void DRV_I2C_SlaveCallbackSet ( const DRV_HANDLE handle, const DRV_I2C_CallBack callback, const uintptr_t context ) f) Data Types and Constants DRV_I2C_BUFFER_QUEUE_SUPPORT Macro Specifies if the Buffer Queue support should be enabled. File drv_i2c_config_template.h C #define DRV_I2C_BUFFER_QUEUE_SUPPORT false Description I2C Driver Buffer Queue Support This macro defines if Buffer Queue support should be enabled. Setting this macro to true will enable buffer queue support and all buffer related driver function. Remarks None Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 548 DRV_I2C_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported File drv_i2c_config_template.h C #define DRV_I2C_INSTANCES_NUMBER 5 Description I2C driver objects configuration Sets up the maximum number of hardware instances that can be supported. It is recommended that this number be set exactly equal to the number of I2C modules that are needed by the application. Hardware Instance support consumes RAM memory space. If this macro is not defined, then the driver will be built statically. Remarks None DRV_I2C_INTERRUPT_MODE Macro Macro controls interrupt based operation of the driver File drv_i2c_config_template.h C #define DRV_I2C_INTERRUPT_MODE true Description I2C Interrupt Mode Operation Control This macro controls the interrupt based operation of the driver. The possible values it can take are • true - Enables the interrupt mode • false - Enables the polling mode If the macro value is true, then Interrupt Service Routine for the interrupt should be defined in the application. The DRV_I2C_Tasks() routine should be called in the ISR. Remarks None DRV_I2C_QUEUE_DEPTH_COMBINED Macro Number of entries of all queues in all instances of the driver. File drv_i2c_config_template.h C #define DRV_I2C_QUEUE_DEPTH_COMBINED 7 Description I2C Driver Instance combined queue depth. This macro defines the number of entries of all queues in all instances of the driver. Each hardware instance supports a buffer queue for transmit and receive operations. The size of queue is specified either in driver initialization (for dynamic build) or by macros (for static build). The hardware instance transmit buffer queue will queue transmit buffers submitted by the DRV_I2C_Transmit() function. The hardware instance receive buffer queue will queue receive buffers submitted by the DRV_I2C_Receive() function. A buffer queue will contain buffer queue entries, each related to a BufferAdd request. This configuration macro defines total number of buffer entries that will be available for use between all I2C driver hardware instances. The buffer queue entries are allocated to individual hardware instances as requested by hardware instances. Once the request is processed, the buffer queue entry is free for use by other hardware instances. Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 549 The total number of buffer entries in the system determines the ability of the driver to service non blocking read and write requests. If a free buffer entry is not available, the driver will not add the request and will return an invalid buffer handle. More the number of buffer entries, greater the ability of the driver to service and add requests to its queue. A hardware instance additionally can queue up as many buffer entries as specified by its transmit and receive buffer queue size. As an example, consider the case of static single client driver application where full duplex non blocking operation is desired without queuing, the minimum transmit queue depth and minimum receive queue depth should be 1. Hence the total number of buffer entries should be 2. In the current implementation of I2C driver, queueing of Buffers is not supported. This will be added in a future release. Remarks None DRV_I2C_BB_H Macro File drv_i2c_bb.h C #define DRV_I2C_BB_H Description This is macro DRV_I2C_BB_H. Files Files Name Description drv_i2c.h I2C module driver interface header. drv_i2c_bb.h Contains prototypes for the I2C functions drv_i2c_config_template.h I2C device driver configuration file. Description drv_i2c.h I2C module driver interface header. Functions Name Description DRV_I2C_BufferEventHandlerSet Allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. Implementation: Dynamic DRV_I2C_BytesTransferred Returns the number of bytes transmitted or received in a particular I2C transaction. The transaction is identified by the handle. DRV_I2C_Close Closes an opened instance of an I2C module driver. Implementation: Dynamic DRV_I2C_Deinitialize Deinitializes the index instance of the I2C module. Implementation: Static/Dynamic DRV_I2C_Initialize Initializes hardware and data for the index instance of the I2C module. Implementation: Static/Dynamic DRV_I2C_Open Opens the specified instance of the I2C driver for use and provides an "open-instance" handle. Implementation: Dynamic DRV_I2C_QueueFlush The existing transactions in the queue are voided and the queue pointers are reset to their initial state. This renders the queue empty. DRV_I2C_Receive This function reads data written from either Master or Slave. Implementation: Dynamic DRV_I2C_SlaveCallbackSet Allows a client to identify a Slave Callback function for the driver to call back when drivers needs to initiate a read or write operation. Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 550 DRV_I2C_Status Provides the current status of the index instance of the I2C module. Implementation: Dynamic DRV_I2C_Tasks Maintains the State Machine of the I2C driver and performs all the protocol level actions. Implementation: Dynamic DRV_I2C_TransferStatusGet Returns status of data transfer when Master or Slave acts either as a transmitter or a receiver. Implementation: Dynamic DRV_I2C_Transmit This function writes data to Master or Slave. Implementation: Dynamic DRV_I2C_TransmitForced This function writes data to Master or Slave. Implementation: Dynamic DRV_I2C_TransmitThenReceive This function writes data to Slave, inserts restart and requests read from slave. Implementation: Dynamic Description I2C Device Driver Interface Header File This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the I2C module driver. File Name drv_i2c.h Company Microchip Technology Inc. drv_i2c_bb.h Contains prototypes for the I2C functions Macros Name Description DRV_I2C_BB_H This is macro DRV_I2C_BB_H. Description I2C Bit Bang Functions Header File File Name drv_i2c_bb.h Company Microchip Technology Inc. drv_i2c_config_template.h I2C device driver configuration file. Macros Name Description DRV_DYNAMIC_BUILD Dynamic driver build, dynamic device instance parameters. DRV_I2C_BUFFER_QUEUE_SUPPORT Specifies if the Buffer Queue support should be enabled. DRV_I2C_CONFIG_BUILD_TYPE Selects static or dynamic driver build configuration. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_BASIC Enables the device driver to support basic transfer mode. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_BLOCKING Enables the device driver to support blocking operations. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_EXCLUSIVE Enables the device driver to support operation in Exclusive mode. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_MASTER Enables the device driver to support operation in Master mode. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_NON_BLOCKING Enables the device driver to support non-blocking during operations Volume V: MPLAB Harmony Framework Driver Libraries Help I2C Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 551 DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_READ Enables the device driver to support read operations. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_SLAVE Enables the device driver to support operation in Slave mode. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_WRITE Enables the device driver to support write operations. DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_WRITE_READ Enables the device driver to support write followed by read. DRV_I2C_FORCED_WRITE Includes function that writes to slave irrespective of whether receiving a ACK or NACK from slave DRV_I2C_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_I2C_INTERRUPT_MODE Macro controls interrupt based operation of the driver DRV_I2C_QUEUE_DEPTH_COMBINED Number of entries of all queues in all instances of the driver. DRV_STATIC_BUILD Static driver build, static device instance parameters. I2C_STATIC_DRIVER_MODE Selects the type of STATIC driver Description I2C Device Driver Configuration These file provides the list of all the configurations that can be used with the driver. This file should not be included in the driver. File Name drv_i2c_config.h Company Microchip Technology Inc. I2S Driver Library Help This section describes the I2S Driver Library. Introduction This library provides an interface to manage the Audio Protocol Interface Modes of the Serial Peripheral Interface (SPI) module on the Microchip family of microcontrollers. Description The SPI module can be interfaced to most available codec devices to provide microcontroller-based audio solutions. 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 (ADCDAT) • SDOx: Serial Data Output for transmitting digital audio data (DACDAT) • SCKx: Serial Clock, also known as bit clock (BCLK) • /SSx: Left/Right Channel Clock (LRCK) BCLK provides the clock required to drive the data out or into the module, while LRCK provides the synchronization of the frame based on the protocol mode selected. In Master mode, the module generates both the BCLK on the SCKx pin and the LRCK on the /SSx pin. In certain devices, while in Slave mode, the module receives these two clocks from its I2S partner, which is operating in Master mode. When configured in Master mode, the leading edge of SCK and the LRCK are driven out within one SCK period of starting the audio protocol. Serial data is shifted in or out with timings determined by the protocol mode set. In Slave mode, the peripheral drives zeros out SDO, but does not transmit the contents of the transmit FIFO until it sees the leading edge of the LRCK, after which time it starts receiving data. Master Mode Master Generating its Own Clock – Output BCLK and LRCK Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 552 Slave Mode Codec Device as Master Derives MCLK from PIC32 Reference Clock Out Audio Protocol Modes The SPI module supports four audio protocol modes and can be operated in any one of these modes: • I2S mode • Left-Justified mode • Right-Justified mode • PCM/DSP mode Using the Library This topic describes the basic architecture of the I2S Driver Library and provides information and examples on its use. Description Interface Header File: drv_i2s.h The interface to the I2S Driver Library is defined in the drv_i2s.h header file. Any C language source (.c) file that uses the I2S Driver Library should include drv_i2s.h. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model The SPI Peripheral Library provides the low-level abstraction of the SPI 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 I2S Driver Library interface. Description I2S Software Abstraction Block Diagram Different types of SPIs are available on Microchip microcontrollers. Some have an internal buffer mechanism and some do not. The buffer depth varies across part families. The SPI Peripheral Library provides the ability to access these buffers. The I2S Driver Library abstracts out these differences and provides a unified model for audio data transfer across different types of SPI modules. Both the transmitter and receiver provide a buffer in the driver, which transmits and receives data to/from the hardware. The I2S Driver Library provides a set of interfaces to perform the read and the write. The following diagrams illustrate the model used by the I2S Driver Library for the transmitter and receiver. Receiver Abstraction Model Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 553 Transmitter Abstraction Model Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The I2S driver library provides an API interface to transfer/receive digital audio data using supported Audio protocols. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the I2S Driver Library. Library Interface Section Description System Interaction Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Client Setup Functions Provides open and close functions. Data Transfer Functions Provides data transfer functions. Miscellaneous Functions Provides driver miscellaneous functions such as baud rate setting, get error functions, etc. Data Types and Constants These data types and constants are required while interacting and setting up the I2S Driver Library. How the Library Works The library provides interfaces to support: • System Functionality • Client Functionality Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. System Access This section provides information on system access. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 554 Description System Initialization The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization, each instance of the I2S module would be initialized with the following configuration settings (either passed dynamically at run time using DRV_I2S_INIT or by using Initialization Overrides) that are supported by the specific I2S device hardware: • Device requested power state: one of the System Module Power States. For specific details please refer to Data Types and Constants in the Library Interface section. • The actual peripheral ID enumerated as the PLIB level module ID (e.g., SPI_ID_2) • Defining the respective interrupt sources for TX, RX, DMA TX Channel, DMA RX Channel and Error Interrupt The DRV_I2S_Initialize API returns an object handle of the type SYS_MODULE_OBJ. The object handle returned by the Initialize interface would be used by the other system interfaces such as DRV_I2S_Deinitialize, DRV_I2S_Status, DRV_I2S_Tasks, and DRV_I2S_TasksError. Notes: 1. The system initialization setting only effect the instance of the peripheral that is being initialized. 2. Configuration of the dynamic driver for DMA mode(uses DMA channel for data transfer) or Non DMA mode can be performed by appropriately setting the 'dmaChannelTransmit' and 'dmaChannelReceive' variables of the DRV_I2S_INIT structure. For example the TX will be in DMA mode when 'dmaChannelTransmit' is initialized to a valid supported channel number from the enum DMA_CHANNEL. TX will be in Non DMA mode when 'dmaChannelTransmit' is initialized to 'DMA_CHANNEL_NONE'. Example: DRV_I2S_INIT init; SYS_MODULE_OBJ objectHandle; init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.spiID = SPI_ID_1; init.usageMode = DRV_I2S_MODE_MASTER; init.baudClock = SPI_BAUD_RATE_MCLK_CLOCK; init.baud = 48000; init.clockMode = DRV_I2S_CLOCK_MODE_IDLE_HIGH_EDGE_FALL; init.audioCommWidth = SPI_AUDIO_COMMUNICATION_24DATA_32FIFO_32CHANNEL; init.audioTransmitMode = SPI_AUDIO_TRANSMIT_STEREO; init.inputSamplePhase = SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE; init.protocolMode = DRV_I2S_AUDIO_I2S; init.txInterruptSource = INT_SOURCE_SPI_1_TRANSMIT; init.rxInterruptSource = INT_SOURCE_SPI_1_RECEIVE; init.errorInterruptSource = INT_SOURCE_SPI_1_ERROR; init.queueSizeTransmit = 3; init.queueSizeReceive = 2; init.dmaChannelTransmit = DMA_CHANNEL_NONE; init.dmaChannelReceive = DMA_CHANNEL_NONE; objectHandle = DRV_I2S_Initialize(DRV_I2S_INDEX_1, (SYS_MODULE_INIT*)init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Task Routine In a polled environment, the system will call DRV_I2S_Tasks and DRV_I2S_TasksError from the System Task Service. In an interrupt-based implementation, DRV_I2S_Tasks and DRV_I2S_TasksError will be called from the Interrupt Service Routine of the I2S. When a DMA channel is used for transmission/reception DRV_I2S_Tasks and DRV_I2S_TasksError will be internally called by the driver from the DMA channel event handler. Client Access This section provides information on general client operation. Description General Client Operation For the application to start using an instance of the module, it must call the DRV_I2S_Open function. This provides the settings required to open the I2S instance for operation. If the driver is deinitialized using the function DRV_I2S_Deinitialize, the application must call the DRV_I2S_Open function again to set up the instance of the I2S. For the various options available for IO_INTENT, please refer to Data Types and Constants in the Library Interface section. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 555 Example: DRV_HANDLE handle; handle = DRV_I2S_Open(DRV_I2S_INDEX_0, (DRV_IO_INTENT_WRITE | DRV_IO_INTENT_NONBLOCKING)); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver // May be the driver is not initialized or the initialization // is not complete. } Client Operations - Buffered This section provides information on buffered client operations. Description Client Operations - Buffered Client buffered operations provide a the typical audio interface. The functions DRV_I2S_BufferAddRead, DRV_I2S_BufferAddWrite, and DRV_I2S_BufferAddWriteRead are the buffered data operation functions. The buffered functions schedules non-blocking operations. The function adds the request to the hardware instance queues and returns a buffer handle. The requesting client also registers a callback event with the driver. The driver notifies the client with DRV_I2S_BUFFER_EVENT_COMPLETE, DRV_I2S_BUFFER_EVENT_ERROR or DRV_I2S_BUFFER_EVENT_ABORT events. The buffer add requests are processed under DRV_I2S_Tasks, DRV_I2S_TasksError functions. These functions are called from the I2S channel ISR in interrupt mode or from SYS_Tasks routine in Polled mode. When a DMA channel is used for transmission/reception DRV_I2S_Tasks and DRV_I2S_TasksError will be internally called by the driver from the DMA channel event handler. The following diagram illustrates the buffered data operations Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 556 Note: It is not necessary to close and reopen the client between multiple transfers. An application using the buffered functionality needs to perform the following steps: 1. The system should have completed necessary setup and initializations. 2. If DMA mode is desired, the DMA should be initialized by calling SYS_DMA_Initialize. 3. The necessary ports setup and remapping must be done for I2S lines: ADCDAT, DACDAT, BCLK, LRCK and MCLK (if required). 4. The driver object should have been initialized by calling DRV_I2S_Initialize. If DMA mode is desired, related attributes in the init structure must be set. 5. Open the driver using DRV_I2S_Open with the necessary ioIntent to get a client handle. 6. The necessary BCLK, LRCK, and MCLK should be set up so as to generate the required media bit rate. 7. The necessary Baud rate value should be set up by calling DRV_I2S_BaudrateSet. 8. The Register and event handler for the client handle should be set up by calling DRV_I2S_BufferEventHandlerSet. 9. Add a buffer to initiate the data transfer by calling DRV_I2S_BufferAddWrite/DRV_I2S_BufferAddRead/DRV_I2S_BufferAddWriteRead. 10. Based on polling or interrupt mode service the data processing should be set up by calling DRV_I2S_Tasks, DRV_I2S_TasksError from system tasks or I2S ISR. When a DMA channel is used for transmission/reception system calls SYS_DMA_Tasks(), SYS_DMA_TasksError() from the system tasks or DMA channel ISR, DRV_I2S_Tasks and DRV_I2S_TasksError will be internally called by the driver from the DMA channel event handler. 11. Repeat step 9 through step 10 to handle multiple buffer transmission and reception. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 557 12. When the client is done it can use DRV_I2S_Close to close the client handle. Example 1: // The following is an example for a Polled mode buffered transmit #define SYS_I2S_DRIVER_INDEX DRV_I2S_1 // I2S Uses SPI Hardware #define BUFFER_SIZE 1000 // I2S initialization structure. // This should be populated with necessary settings. // attributes dmaChannelTransmit/dmaChannelReceive // and dmaInterruptTransmitSource/dmaInterruptReceiveSource // must be set if DMA mode of operation is desired. DRV_I2S_INIT i2sInit; SYS_MODULE_OBJ sysObj; //I2S module object DRV_HANDLE handle; //Client handle uint32_t i2sClock; //BCLK frequency uint32_t baudrate; //baudrate uint16_t myAudioBuffer[BUFFER_SIZE]; //Audio buffer to be transmitted DRV_I2S_BUFFER_HANDLE bufferHandle; APP_DATA_S state; //Application specific state uintptr_t contextHandle; void SYS_Initialize ( void* data ) { // The system should have completed necessary setup and initializations. // Necessary ports setup and remapping must be done for I2S lines ADCDAT, // DACDAT, BCLK, LRCK and MCLK sysObj = DRV_I2S_Initialize(SYS_I2S_DRIVER_INDEX, (SYS_MODULE_INIT*)&i2sInit); if (SYS_MODULE_OBJ_INVALID == sysObj) { // Handle error } } void App_Task(void) { switch(state) { case APP_STATE_INIT: { handle = DRV_I2S_Open(SYS_I2S_DRIVER_INDEX, (DRV_IO_INTENT_WRITE | DRV_IO_INTENT_NONBLOCKING)); if(handle != DRV_HANDLE_INVALID ) { /* Update the state */ state = APP_STATE_WAIT_FOR_READY; } } break; case APP_STATE_WAIT_FOR_READY: { // Necessary clock settings must be done to generate // required MCLK, BCLK and LRCK DRV_I2S_BaudrateSet(handle, i2sClock, baudrate); /* Set the Event handler */ DRV_I2S_BufferEventHandlerSet(handle,App_BufferEventHandler, contextHandle); /* Add a buffer to write*/ DRV_I2S_BufferAddWrite(handle, &bufferHandle myAudioBuffer, BUFFER_SIZE); if(DRV_I2S_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 558 } state = APP_STATE_IDLE; } break; case APP_STATE_WAIT_FOR_DONE: state = APP_STATE_DONE; break; case APP_STATE_DONE: // Close done DRV_I2S_Close(handle); break; case APP_STATE_IDLE: // Do nothing break; default: break; } } void App_BufferEventHandler(DRV_I2S_BUFFER_EVENT event, DRV_I2S_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { uint8_t temp; if(DRV_I2S_BUFFER_EVENT_COMPLETE == event) { // Can set state = APP_STATE_WAIT_FOR_DONE; // Take Action as needed } else if(DRV_I2S_BUFFER_EVENT_ERROR == event) { // Take Action as needed } else if(DRV_I2S_BUFFER_EVENT_ABORT == event) { // Take Action as needed } else { // Do nothing } } void SYS_Tasks ( void ) { DRV_I2S_Tasks((SYS_MODULE_OBJ)sysObj); DRV_I2S_TasksError((SYS_MODULE_OBJ)sysObj); /* Call the application's tasks routine */ APP_Tasks ( ); } Example 2: // The following is an example for interrupt mode buffered transmit #define SYS_I2S_DRIVER_INDEX DRV_I2S_1 // I2S Uses SPI Hardware #define BUFFER_SIZE 1000 // I2S initialization structure. // This should be populated with necessary settings. // attributes dmaChannelTransmit/dmaChannelReceive // and dmaInterruptTransmitSource/dmaInterruptReceiveSource // must be set if DMA mode of operation is desired. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 559 DRV_I2S_INIT i2sInit; SYS_MODULE_OBJ sysObj; //I2S module object DRV_HANDLE handle; //Client handle uint32_t i2sClock; //BCLK frequency uint32_t baudrate; //baudrate uint16_t myAudioBuffer[BUFFER_SIZE]; //Audio buffer to be transmitted DRV_I2S_BUFFER_HANDLE bufferHandle; APP_DATA_S state; //Application specific state uintptr_t contextHandle; void SYS_Initialize ( void* data ) { // The system should have completed necessary setup and initializations. // Necessary ports setup and remapping must be done for I2S lines ADCDAT, // DACDAT, BCLK, LRCK and MCLK sysObj = DRV_I2S_Initialize(SYS_I2S_DRIVER_INDEX, (SYS_MODULE_INIT*)&i2sInit); if (SYS_MODULE_OBJ_INVALID == sysObj) { // Handle error } } void App_Task(void) { switch(state) { case APP_STATE_INIT: { handle = DRV_I2S_Open(SYS_I2S_DRIVER_INDEX, (DRV_IO_INTENT_WRITE | DRV_IO_INTENT_NONBLOCKING)); if(handle != DRV_HANDLE_INVALID ) { /* Update the state */ state = APP_STATE_WAIT_FOR_READY; } } break; case APP_STATE_WAIT_FOR_READY: { // Necessary clock settings must be done to generate // required MCLK, BCLK and LRCK DRV_I2S_BaudrateSet(handle, i2sClock, baudrate); /* Set the Event handler */ DRV_I2S_BufferEventHandlerSet(handle,App_BufferEventHandler, contextHandle); /* Add a buffer to write*/ DRV_I2S_BufferAddWrite(handle, &bufferHandle myAudioBuffer, BUFFER_SIZE); if(DRV_I2S_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } state = APP_STATE_IDLE; } break; case APP_STATE_WAIT_FOR_DONE: state = APP_STATE_DONE; break; case APP_STATE_DONE: { Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 560 // Close done DRV_I2S_Close(handle); } break; case APP_STATE_IDLE: // Do nothing break; default: break; } } void App_BufferEventHandler(DRV_I2S_BUFFER_EVENT event, DRV_I2S_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { uint8_t temp; if(DRV_I2S_BUFFER_EVENT_COMPLETE == event) { // Can set state = APP_STATE_WAIT_FOR_DONE; // Take Action as needed } else if(DRV_I2S_BUFFER_EVENT_ERROR == event) { // Take Action as needed } else if(DRV_I2S_BUFFER_EVENT_ABORT == event) { // Take Action as needed } else { // Do nothing } } void SYS_Tasks ( void ) { /* Call the application's tasks routine */ APP_Tasks ( ); } void __ISR ( _SPI1_VECTOR ) _InterruptHandler_I2S1 ( void ) { // Call the "tasks" functions for I2S module DRV_I2S_Tasks((SYS_MODULE_OBJ)sysObj); DRV_I2S_TasksError((SYS_MODULE_OBJ)sysObj); } // If DMA Channel 1 was setup during initialization instead of the previous I2S ISR, the following should be implemented void __ISR ( _DMA1_VECTOR ) _InterruptHandler_DMA_CHANNEL_1 ( void ) { // Call the DMA system tasks which internally will call the I2S Tasks. SYS_DMA_Tasks((SYS_MODULE_OBJ)sysObj); SYS_DMA_TasksError((SYS_MODULE_OBJ)sysObj); } Client Operations - Non-buffered This section provides information on non-buffered client operations. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 561 Description Client Operations - Non-buffered Client non-buffered operations provide a basic interface for the driver operation. This interface could be used by applications which have do not have buffered data transfer requirements. The functions DRV_I2S_Read and DRV_I2S_Write are the non-buffered data operation functions. The non-buffered functions are blocking/non-blocking depending upon the mode (ioIntent) the client was opened. If the client was opened for blocking mode these functions will only return when (or will block until) the specified data operation is completed or if an error occurred. If the client was opened for non-blocking mode, these functions will return with the number of bytes that were actually accepted for operation. The function will not wait until the data operation has completed. Note: Non-buffered functions do not support interrupt/DMA mode. The following diagram illustrates the non-buffered data operations Note: It is not necessary to close and reopen the client between multiple transfers. An application using the non-buffered functionality needs to perform the following steps: 1. The system should have completed necessary setup and initializations. 2. The necessary ports setup and remapping must be done for I2S lines: ADCDAT, DACDAT, BCLK, LRCK and MCLK (if required). 3. The driver object should have been initialized by calling DRV_I2S_Initialize. 4. Open the driver using DRV_I2S_Open with the necessary ioIntent to get a client handle. 5. The necessary BCLK, LRCK, and MCLK should be set up so as to generate the required media bit rate. 6. The necessary Baud rate value should be set up by calling DRV_I2S_BaudrateSet. 7. The Transmit/Receive data should be set up by calling DRV_I2S_Write/DRV_I2S_Read. 8. Repeat step 5 through step 7 to handle multiple buffer transmission and reception. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 562 9. When the client is done it can use DRV_I2S_Close to close the client handle. Example 1: // The following is an example for a blocking transmit #define SYS_I2S_DRIVER_INDEX DRV_I2S_1 // I2S Uses SPI Hardware #define BUFFER_SIZE 1000 DRV_I2S_INIT i2sInit; //I2S initialization structure //This should be populated with necessary settings SYS_MODULE_OBJ sysObj; //I2S module object APP_DATA_S state; //Application specific state DRV_HANDLE handle; //Client handle uint32_t i2sClock; //BCLK frequency uint32_t baudrate; //baudrate uint16_t myAudioBuffer[BUFFER_SIZE]; //Audio buffer to be transmitted uint32_t count; // The system should have completed necessary setup and initializations. // Necessary ports setup and remapping must be done for // I2S lines ADCDAT, DACDAT, BCLK, LRCK and MCLK sysObj = DRV_I2S_Initialize(SYS_I2S_DRIVER_INDEX, (SYS_MODULE_INIT*)&i2sInit); if (SYS_MODULE_OBJ_INVALID == sysObj) { // Handle error } while(1) { switch(state) { case APP_STATE_INIT: { handle = DRV_I2S_Open(SYS_I2S_DRIVER_INDEX, (DRV_IO_INTENT_WRITE | DRV_IO_INTENT_BLOCKING)); if(handle != DRV_HANDLE_INVALID ) { /* Update the state */ state = APP_STATE_WAIT_FOR_READY; } } break; case APP_STATE_WAIT_FOR_READY: { // Necessary clock settings must be done to generate // required MCLK, BCLK and LRCK DRV_I2S_BaudrateSet(handle, i2sClock, baudrate); // Blocks here and transfer the buffer count = DRV_I2S_Write(handle, &myAudioBuffer,BUFFER_SIZE); if(count == DRV_I2S_WRITE_ERROR) { //Handle Error } else { // Transfer Done state = APP_STATE_DONE; } } break; case APP_STATE_DONE: { // Close done DRV_I2S_Close(handle); } break; default: break; } } Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 563 Example 2: // Following is an example for a non blocking transmit #define SYS_I2S_DRIVER_INDEX DRV_I2S_1 //I2S Uses SPI Hardware #define BUFFER_SIZE 1000 DRV_I2S_INIT i2sInit; //I2S initialization structure. // This should be populated with necessary settings SYS_MODULE_OBJ sysObj; //I2S module object APP_DATA_S state; //Application specific state DRV_HANDLE handle; //Client handle uint32_t i2sClock; //BCLK frequency uint32_t baudrate; //baudrate uint16_t myAudioBuffer[BUFFER_SIZE]; //Audio buffer to be transmitted uint32_t count,total,size; total = 0; size = BUFFER_SIZE; // The system should have completed necessary setup and initializations. // Necessary ports setup and remapping must be done for I2S lines ADCDAT, // DACDAT, BCLK, LRCK and MCLK sysObj = DRV_I2S_Initialize(SYS_I2S_DRIVER_INDEX, (SYS_MODULE_INIT*)&i2sInit); if (SYS_MODULE_OBJ_INVALID == sysObj) { // Handle error } while(1) { switch(state) { case APP_STATE_INIT: { handle = DRV_I2S_Open(SYS_I2S_DRIVER_INDEX, (DRV_IO_INTENT_WRITE | DRV_IO_INTENT_NONBLOCKING)); if(handle != DRV_HANDLE_INVALID ) { /* Update the state */ state = APP_STATE_WAIT_FOR_READY; } } break; case APP_STATE_WAIT_FOR_READY: { // Necessary clock settings must be done to generate // required MCLK, BCLK and LRCK DRV_I2S_BaudrateSet(handle, i2sClock, baudrate); // Transfer whatever possible number of bytes count = DRV_I2S_Write(handle, &myAudioBuffer,size); if(count == DRV_I2S_WRITE_ERROR) { //Handle Error } else { // 'count' bytes transferred state = APP_STATE_WAIT_FOR_DONE; } } break; case APP_STATE_WAIT_FOR_DONE: // Can perform other Application tasks here // ......................... // ......................... // ......................... size = size - count; if(size!=0) { Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 564 // Change the state so as to submit // another possible transmission state = APP_STATE_WAIT_FOR_READY; } else { // We are done state = APP_STATE_DONE; } break; case APP_STATE_DONE: { if(DRV_I2S_CLOSE_FAILURE == DRV_I2S_Close(handle)) { // Handle error } else { // Close done } } break; default: break; } } Configuring the Library Client Configuration Name Description DRV_I2S_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_I2S_QUEUE_DEPTH_COMBINED Number of entries of all queues in all instances of the driver. System Configuration Name Description DRV_I2S_INDEX I2S Static Index selection DRV_I2S_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_I2S_INTERRUPT_MODE Macro controls interrupt based operation of the driver DRV_I2S_INTERRUPT_SOURCE_ERROR Defines the interrupt source for the error interrupt DRV_I2S_INTERRUPT_SOURCE_RECEIVE Macro to define the Receive interrupt source in case of static driver DRV_I2S_INTERRUPT_SOURCE_TRANSMIT Macro to define the Transmit interrupt source in case of static driver DRV_I2S_PERIPHERAL_ID Configures the I2S PLIB Module ID DRV_I2S_RECEIVE_DMA_CHANNEL Macro to defines the I2S Driver Receive DMA Channel in case of static driver DRV_I2S_STOP_IN_IDLE Identifies whether the driver should stop operations in stop in Idle mode. DRV_I2S_TRANSMIT_DMA_CHANNEL Macro to defines the I2S Driver Transmit DMA Channel in case of static driver DRV_I2S_RECEIVE_DMA_CHAINING_CHANNEL Macro to defines the I2S Driver Receive DMA Chaining Channel in case of static driver Description The configuration of the I2S Driver Library is based on the file sys_config.h. This header file contains the configuration selection for the I2S Driver Library. Based on the selections made, the I2S Driver Library may support the selected features. These configuration settings will apply to all instances of the I2S Driver 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. System Configuration Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 565 DRV_I2S_INDEX Macro I2S Static Index selection File drv_i2s_config_template.h C #define DRV_I2S_INDEX Description Index - Used for static drivers I2S Static Index selection for the driver object reference. This macro defines the driver index in case of static and static multi-client build. For example, if this macro is set to DRV_I2S_INDEX_2, then static driver APIs would be DRV_I2S2_Initialize(), DRV_I2S2_Open() etc. When building static drivers, this macro should be different for each static build of the I2S driver that needs to be included in the project. Remarks This index is required to make a reference to the driver object DRV_I2S_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported File drv_i2s_config_template.h C #define DRV_I2S_INSTANCES_NUMBER Description I2S driver objects configuration Sets up the maximum number of hardware instances that can be supported. It is recommended that this number be set exactly equal to the number of I2S modules that are needed by the application. Hardware Instance support consumes RAM memory space. If this macro is not defined, then the driver will be built statically. Remarks None DRV_I2S_INTERRUPT_MODE Macro Macro controls interrupt based operation of the driver File drv_i2s_config_template.h C #define DRV_I2S_INTERRUPT_MODE Description I2S Interrupt Mode Operation Control This macro controls the interrupt based operation of the driver. The possible values it can take are • true - Enables the interrupt mode • false - Enables the polling mode If the macro value is true, then Interrupt Service Routine for the interrupt should be defined in the application. The DRV_I2S_Tasks() routine should be called in the ISR. DRV_I2S_INTERRUPT_SOURCE_ERROR Macro Defines the interrupt source for the error interrupt Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 566 File drv_i2s_config_template.h C #define DRV_I2S_INTERRUPT_SOURCE_ERROR Description Error Interrupt Source Macro to define the Error interrupt source in case of static driver. The interrupt source defined by this macro will override the errorInterruptSource member of the DRV_I2S_INIT initialization data structure in the driver initialization routine. This value should be set to the I2S module error interrupt enumeration in the Interrupt PLIB for the microcontroller. DRV_I2S_INTERRUPT_SOURCE_RECEIVE Macro Macro to define the Receive interrupt source in case of static driver File drv_i2s_config_template.h C #define DRV_I2S_INTERRUPT_SOURCE_RECEIVE Description Receive Interrupt Source Macro to define the Receive interrupt source in case of static driver. The interrupt source defined by this macro will override the rxInterruptSource member of the DRV_I2S_INIT initialization data structure in the driver initialization routine. This value should be set to the I2S module receive interrupt enumeration in the Interrupt PLIB for the microcontroller. Remarks None. DRV_I2S_INTERRUPT_SOURCE_TRANSMIT Macro Macro to define the Transmit interrupt source in case of static driver File drv_i2s_config_template.h C #define DRV_I2S_INTERRUPT_SOURCE_TRANSMIT Description Transmit Interrupt Source Macro to define the TX interrupt source in case of static driver. The interrupt source defined by this macro will override the txInterruptSource member of the DRV_I2S_INIT initialization data structure in the driver initialization routine. This value should be set to the I2S module transmit interrupt enumeration in the Interrupt PLIB for the microcontroller. Remarks None. DRV_I2S_PERIPHERAL_ID Macro Configures the I2S PLIB Module ID File drv_i2s_config_template.h C #define DRV_I2S_PERIPHERAL_ID Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 567 Description I2S Peripheral Library Module ID This macro configures the PLIB ID if the driver is built statically. This value will override the I2SID member of the DRV_I2S_INIT initialization data structure. In that when the driver is built statically, the I2SID member of the DRV_I2S_INIT data structure will be ignored by the driver initialization routine and this macro will be considered. This should be set to the PLIB ID of I2S module (I2S_ID_1, I2S_ID_2 and so on). DRV_I2S_RECEIVE_DMA_CHANNEL Macro Macro to defines the I2S Driver Receive DMA Channel in case of static driver File drv_i2s_config_template.h C #define DRV_I2S_RECEIVE_DMA_CHANNEL Description I2S Driver Receive DMA Channel Macro to define the I2S Receive DMA Channel in case of static driver. The DMA channel defined by this macro will override the dmaChannelReceive member of the DRV_I2S_INIT initialization data structure in the driver initialization routine. This value should be set to the DMA channel in the DMA PLIB for the microcontroller. Remarks None. DRV_I2S_STOP_IN_IDLE Macro Identifies whether the driver should stop operations in stop in Idle mode. File drv_i2s_config_template.h C #define DRV_I2S_STOP_IN_IDLE Description I2S driver objects configuration Identifies whether the driver should stop operations in stop in Idle mode. true - Indicates stop in idle mode. false - Indicates do not stop in Idle mode. Remarks None DRV_I2S_TRANSMIT_DMA_CHANNEL Macro Macro to defines the I2S Driver Transmit DMA Channel in case of static driver File drv_i2s_config_template.h C #define DRV_I2S_TRANSMIT_DMA_CHANNEL Description I2S Driver Transmit DMA Channel Macro to define the I2S Transmit DMA Channel in case of static driver. The DMA channel defined by this macro will override the dmaChannelTransmit member of the DRV_I2S_INIT initialization data structure in the driver initialization routine. This value should be set to the DMA channel in the DMA PLIB for the microcontroller. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 568 DRV_I2S_RECEIVE_DMA_CHAINING_CHANNEL Macro Macro to defines the I2S Driver Receive DMA Chaining Channel in case of static driver File drv_i2s_config_template.h C #define DRV_I2S_RECEIVE_DMA_CHAINING_CHANNEL Description I2S Driver Receive DMA Chaining Channel Macro to define the I2S Receive DMA Chaining Channel in case of static driver. The DMA channel defined by this macro will override the dmaChaningChannelReceive member of the DRV_I2S_INIT initialization data structure in the driver initialization routine. This value should be set to the DMA channel in the DMA PLIB for the microcontroller. Remarks None. Client Configuration DRV_I2S_CLIENTS_NUMBER Macro Sets up the maximum number of clients that can be connected to any hardware instance. File drv_i2s_config_template.h C #define DRV_I2S_CLIENTS_NUMBER Description I2S Client Count Configuration Sets up the maximum number of clients that can be connected to any hardware instance. This value represents the total number of clients to be supported across all hardware instances. So if I2S1 will be accessed by 2 clients and I2S2 will accessed by 3 clients, then this number should be 5. It is recommended that this be set exactly equal to the number of expected clients. Client support consumes RAM memory space. If this macro is not defined and the DRV_I2S_INSTANCES_NUMBER macro is not defined, then the driver will be built for static - single client operation. If this macro is defined and the DRV_I2S_INSTANCES_NUMBER macro is not defined, then the driver will be built for static - multi client operation. Remarks None DRV_I2S_QUEUE_DEPTH_COMBINED Macro Number of entries of all queues in all instances of the driver. File drv_i2s_config_template.h C #define DRV_I2S_QUEUE_DEPTH_COMBINED Description I2S Driver Buffer Queue Entries This macro defined the number of entries of all queues in all instances of the driver. Each hardware instance supports a buffer queue for transmit and receive operations. The size of queue is specified either in driver initialization (for dynamic build) or by macros (for static build). The hardware instance transmit buffer queue will queue transmit buffers submitted by the DRV_I2S_BufferAddWrite() function. The hardware instance receive buffer queue will queue receive buffers submitted by the DRV_I2S_BufferAddRead() function. A buffer queue will contains buffer queue entries, each related to a BufferAdd request. This configuration macro defines total number of buffer Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 569 entries that will be available for use between all I2S driver hardware instances. The buffer queue entries are allocated to individual hardware instances as requested by hardware instances. Once the request is processed, the buffer queue entry is free for use by other hardware instances. The total number of buffer entries in the system determines the ability of the driver to service non blocking read and write requests. If a free buffer entry is not available, the driver will not add the request and will return an invalid buffer handle. More the number of buffer entries, greater the ability of the driver to service and add requests to its queue. A hardware instance additionally can queue up as many buffer entries as specified by its transmit and receive buffer queue size. As an example, consider the case of static single client driver application where full duplex non blocking operation is desired without queuing, the minimum transmit queue depth and minimum receive queue depth should be 1. Hence the total number of buffer entries should be 2. As an example, consider the case of a dynamic driver (say 2 instances) where instance 1 will queue up to 3 write requests and up to 2 read requests, and instance 2 will queue up to 2 write requests and up to 6 read requests, the value of this macro should be 13 (2 + 3 + 2 + 6). Remarks The maximum combined queue depth should not be greater than 0xFFFF(ie 65535) Building the Library This section lists the files that are available in the I2S Driver Library. 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 /framework/driver/i2s. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_i2s.h This file provides the interface definitions of the I2S driver. 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 /src/dynamic/drv_i2s_dma.c This file contains the core implementation of the I2S driver with DMA support. 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 /src/dynamic/drv_i2s_dma_advanced.c This file contains the implementation of the I2S driver with DMA support using the channel chaining feature. /src/dynamic/drv_i2s.c This file contains the implementation of the I2S driver without DMA support. /src/dynamic/drv_i2s_read_write.c This file contains the basic read/write implementation of the I2S driver. Module Dependencies The I2S Driver Library depends on the following modules: • SPI Peripheral Library • DMA Peripheral Library Library Interface a) System Interaction Functions Name Description DRV_I2S_Deinitialize Deinitializes the specified instance of the I2S driver module. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 570 DRV_I2S_Initialize Initializes hardware and data for the instance of the I2S module. Implementation: Dynamic DRV_I2S_Status Gets the current status of the I2S driver module. Implementation: Dynamic DRV_I2S_Tasks Maintains the driver's receive state machine and implements its ISR. Implementation: Dynamic DRV_I2S_TasksError Maintains the driver's error state machine and implements its ISR. Implementation: Dynamic b) Client Setup Functions Name Description DRV_I2S_Close Closes an opened-instance of the I2S driver. Implementation: Dynamic DRV_I2S_Open Opens the specified I2S driver instance and returns a handle to it. Implementation: Dynamic c) Data Transfer Functions Name Description DRV_I2S_BufferAddRead Schedule a non-blocking driver read operation. Implementation: Dynamic DRV_I2S_BufferAddWrite Schedule a non-blocking driver write operation. Implementation: Dynamic DRV_I2S_BufferAddWriteRead Schedule a non-blocking driver write-read operation. Implementation: Dynamic DRV_I2S_BufferEventHandlerSet This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. Implementation: Dynamic DRV_I2S_BufferCombinedQueueSizeGet This function returns the number of bytes queued (to be processed) in the buffer queue. Implementation: Dynamic DRV_I2S_BufferQueueFlush This function flushes off the buffers associated with the client object. Implementation: Dynamic DRV_I2S_Read Reads data from the I2S. Implementation: Dynamic DRV_I2S_Write Writes data to the I2S. Implementation: Dynamic DRV_I2S_BufferProcessedSizeGet This function returns number of bytes that have been processed for the specified buffer. Implementation: Dynamic d) Miscellaneous Functions Name Description DRV_I2S_BaudSet This function sets the baud. Implementation: Dynamic DRV_I2S_ErrorGet This function returns the error(if any) associated with the last client request. Implementation: Dynamic DRV_I2S_ReceiveErrorIgnore This function enable/disable ignoring of the receive overflow error. Implementation: Dynamic DRV_I2S_TransmitErrorIgnore This function enable/disable ignoring of the transmit underrun error. Implementation: Dynamic e) Data Types and Constants Name Description DRV_I2S_AUDIO_PROTOCOL_MODE Identifies the Audio Protocol Mode of the I2S module. DRV_I2S_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_I2S_BUFFER_EVENT_HANDLER Pointer to a I2S Driver Buffer Event handler function DRV_I2S_BUFFER_HANDLE Handle identifying a read or write buffer passed to the driver. DRV_I2S_CLOCK_MODE Identifies the various clock modes of the I2S module. DRV_I2S_DATA16 Defines the left and right channel data for 16-bit audio data DRV_I2S_DATA24 Defines the left and right channel data for 24-bit audio data Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 571 DRV_I2S_DATA32 Defines the left and right channel data for 32-bit audio data DRV_I2S_ERROR Defines the possible errors that can occur during driver operation. DRV_I2S_MODE Identifies the usage modes of the I2S module. DRV_I2S_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_I2S_COUNT Number of valid I2S driver indices DRV_I2S_READ_ERROR I2S Driver Read Error. DRV_I2S_WRITE_ERROR I2S Driver Write Error. DRV_I2S_INDEX_0 I2S driver index definitions DRV_I2S_INDEX_1 This is macro DRV_I2S_INDEX_1. DRV_I2S_INDEX_2 This is macro DRV_I2S_INDEX_2. DRV_I2S_INDEX_3 This is macro DRV_I2S_INDEX_3. DRV_I2S_INDEX_4 This is macro DRV_I2S_INDEX_4. DRV_I2S_INDEX_5 This is macro DRV_I2S_INDEX_5. DRV_I2S_INTERFACE This structure defines a structure of I2S Driver function pointers. Description This section describes the Application Programming Interface (API) functions of the I2S Driver Library. Refer to each section for a detailed description. a) System Interaction Functions DRV_I2S_Deinitialize Function Deinitializes the specified instance of the I2S driver module. Implementation: Dynamic File drv_i2s.h C void DRV_I2S_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the I2S driver module, disabling its operation (and any hardware). Invalidates all the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This routine will NEVER block waiting for hardware. Preconditions Function DRV_I2S_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_I2S_Initialize SYS_STATUS status; DRV_I2S_Deinitialize(object); status = DRV_I2S_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 572 Parameters Parameters Description object Driver object handle, returned from the DRV_I2S_Initialize routine Function void DRV_I2S_Deinitialize( SYS_MODULE_OBJ object ) DRV_I2S_Initialize Function Initializes hardware and data for the instance of the I2S module. Implementation: Dynamic File drv_i2s.h C SYS_MODULE_OBJ DRV_I2S_Initialize(const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT *const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the I2S driver instance for the specified driver index, making it ready for clients to open and use it. The initialization data is specified by the init parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. The driver instance index is independent of the I2S module ID. For example, driver instance 0 can be assigned to I2S2. If the driver is built statically, then some of the initialization parameters are overridden by configuration macros. Refer to the description of the DRV_I2S_INIT data structure for more details on which members on this data structure are overridden. Remarks This routine must be called before any other I2S routine is called. This routine should only be called once during system initialization unless DRV_I2S_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. To Enable the DMA mode of operation the init parameters 'dmaChannelTransmit' /'dmaChannelReceive' must be set to valid DMA channel. When DMA mode of operation is enabled, the normal mode(Usual TX and RX) operation is inhibited. When 'dmaChannelTransmit'/'dmaChannelReceive' are set to valid channel numbers the related DMA interrupt source parameters 'dmaInterruptTransmitSource'/ 'dmaInterruptReceiveSource' must be set with appropriate DMA channel interrupt source. Preconditions If DMA mode of operation is intended, SYS_DMA_Initialize should have been called before calling this function. Example DRV_I2S_INIT init; SYS_MODULE_OBJ objectHandle; init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.spiID = SPI_ID_1; init.usageMode = DRV_I2S_MODE_MASTER; init.baudClock = SPI_BAUD_RATE_MCLK_CLOCK; init.baud = 48000; init.clockMode = DRV_I2S_CLOCK_MODE_IDLE_HIGH_EDGE_FALL; init.audioCommWidth = SPI_AUDIO_COMMUNICATION_24DATA_32FIFO_32CHANNEL; init.audioTransmitMode = SPI_AUDIO_TRANSMIT_STEREO; init.inputSamplePhase = SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE; init.protocolMode = DRV_I2S_AUDIO_I2S; init.txInterruptSource = INT_SOURCE_SPI_1_TRANSMIT; init.rxInterruptSource = INT_SOURCE_SPI_1_RECEIVE; init.errorInterruptSource = INT_SOURCE_SPI_1_ERROR; init.queueSizeTransmit = 3; init.queueSizeReceive = 2; init.dmaChannelTransmit = DMA_CHANNEL_NONE; init.dmaChannelReceive = DMA_CHANNEL_NONE; objectHandle = DRV_I2S_Initialize(DRV_I2S_INDEX_1, (SYS_MODULE_INIT*)init); Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 573 if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description drvIndex Identifier for the driver instance to be initialized init Pointer to the data structure containing any data necessary to initialize the hardware. This pointer may be null if no data is required and default initialization is to be used. Function SYS_MODULE_OBJ DRV_I2S_Initialize ( const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT *const init ); DRV_I2S_Status Function Gets the current status of the I2S driver module. Implementation: Dynamic File drv_i2s.h C SYS_STATUS DRV_I2S_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_DEINITIALIZED - Indicates that the driver has been deinitialized SYS_STATUS_READY - Indicates that any previous module operation for the specified module has completed SYS_STATUS_BUSY - Indicates that a previous module operation for the specified module has not yet completed SYS_STATUS_ERROR - Indicates that the specified module is in an error state Description This routine provides the current status of the I2S driver module. Remarks A driver can opened only when its status is SYS_STATUS_READY. Preconditions Function DRV_I2S_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_I2S_Initialize SYS_STATUS i2sStatus; i2sStatus = DRV_I2S_Status(object); if (SYS_STATUS_READY == i2sStatus) { // This means the driver can be opened using the // DRV_I2S_Open() function. } Parameters Parameters Description object Driver object handle, returned from the DRV_I2S_Initialize routine Function SYS_STATUS DRV_I2S_Status( SYS_MODULE_OBJ object ) Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 574 DRV_I2S_Tasks Function Maintains the driver's receive state machine and implements its ISR. Implementation: Dynamic File drv_i2s.h C void DRV_I2S_Tasks(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal receive state machine and implement its transmit and receive ISR for interrupt-driven implementations. In polling mode, this function should be called from the SYS_Tasks function. In interrupt mode, this function should be called from the interrupt service routine of the I2S that is associated with this I2S driver hardware instance. In DMA mode of operation, this function should be called from the interrupt service routine of the channel associated with the transmission/reception of the I2s driver hardware instance. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the appropriate raw ISR. This routine may execute in an ISR context and will never block or access any resources that may cause it to block. Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_I2S_Initialize while (true) { DRV_I2S_Tasks (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_I2S_Initialize) Function void DRV_I2S_Tasks(SYS_MODULE_OBJ object ) DRV_I2S_TasksError Function Maintains the driver's error state machine and implements its ISR. Implementation: Dynamic File drv_i2s.h C void DRV_I2S_TasksError(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal error state machine and implement its error ISR for interrupt-driven implementations. In polling Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 575 mode, this function should be called from the SYS_Tasks() function. In interrupt mode, this function should be called in the error interrupt service routine of the I2S that is associated with this I2S driver hardware instance. In DMA mode of operation, this function should be called from the interrupt service routine of the channel associated with the transmission/reception of the I2s driver hardware instance. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the appropriate raw ISR. This routine may execute in an ISR context and will never block or access any resources that may cause it to block. Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_I2S_Initialize while (true) { DRV_I2S_TasksError (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_I2S_Initialize) Function void DRV_I2S_TasksError (SYS_MODULE_OBJ object ) b) Client Setup Functions DRV_I2S_Close Function Closes an opened-instance of the I2S driver. Implementation: Dynamic File drv_i2s.h C void DRV_I2S_Close(const DRV_HANDLE handle); Returns • None Description This routine closes an opened-instance of the I2S driver, invalidating the handle. Any buffers in the driver queue that were submitted by this client will be removed. After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_I2S_Open before the caller may use the driver again Remarks Usually there is no need for the driver client to verify that the Close operation has completed. The driver will abort any ongoing operations when this routine is called. Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S driver instance. DRV_I2S_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_I2S_Open Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 576 DRV_I2S_Close(handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_I2S_Close( DRV_Handle handle ) DRV_I2S_Open Function Opens the specified I2S driver instance and returns a handle to it. Implementation: Dynamic File drv_i2s.h C DRV_HANDLE DRV_I2S_Open(const SYS_MODULE_INDEX iDriver, const DRV_IO_INTENT ioIntent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Error can occur • if the number of client objects allocated via DRV_I2S_CLIENTS_NUMBER is insufficient. • if the client is trying to open the driver but driver has been opened exclusively by another client. • if the driver hardware instance being opened is not initialized or is invalid. Description This routine opens the specified I2S driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. The DRV_IO_INTENT_BLOCKING and DRV_IO_INTENT_NONBLOCKING ioIntent options additionally affect the behavior of the DRV_I2S_Read() and DRV_I2S_Write() functions. If the ioIntent is DRV_IO_INTENT_NONBLOCKING, then these function will not block even if the required amount of data could not be processed. If the ioIntent is DRV_IO_INTENT_BLOCKING, these functions will block until the required amount of data is processed. If ioIntent is DRV_IO_INTENT_READ, the client will only be read from the driver. If ioIntent is DRV_IO_INTENT_WRITE, the client will only be able to write to the driver. If the ioIntent in DRV_IO_INTENT_READWRITE, the client will be able to do both, read and write. Specifying a DRV_IO_INTENT_EXCLUSIVE will cause the driver to provide exclusive access to this client. The driver cannot be opened by any other client. Remarks The handle returned is valid until the DRV_I2S_Close routine is called. This routine will NEVER block waiting for hardware.If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. It should not be called in an ISR. Preconditions Function DRV_I2S_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_I2S_Open(DRV_I2S_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver // May be the driver is not initialized or the initialization // is not complete. } Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 577 Parameters Parameters Description drvIndex Identifier for the object instance to be opened ioIntent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver. See function description for details. Function DRV_HANDLE DRV_I2S_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent ) c) Data Transfer Functions DRV_I2S_BufferAddRead Function Schedule a non-blocking driver read operation. Implementation: Dynamic File drv_i2s.h C void DRV_I2S_BufferAddRead(const DRV_HANDLE handle, DRV_I2S_BUFFER_HANDLE * bufferHandle, void * buffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_I2S_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking read operation. The function returns with a valid buffer handle in the bufferHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance receive queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_I2S_BUFFER_HANDLE_INVALID: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the client opened the driver for write-only • if the buffer size is 0 • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_I2S_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_I2S_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the I2S Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another I2S driver instance. It should not otherwise be called directly in an ISR. This function supports DMA mode of operation. Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S device instance and the DRV_I2S_Status must have returned SYS_STATUS_READY. DRV_I2S_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_I2S_Open call. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_I2S_BUFFER_HANDLE bufferHandle; Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 578 // myI2SHandle is the handle returned // by the DRV_I2S_Open function. // Client registers an event handler with driver DRV_I2S_BufferEventHandlerSet(myI2SHandle, APP_I2SBufferEventHandler, (uintptr_t)&myAppObj); DRV_I2S_BufferAddRead(myI2Shandle, &bufferHandle, myBuffer, MY_BUFFER_SIZE); if(DRV_I2S_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_I2SBufferEventHandler(DRV_I2S_BUFFER_EVENT event, DRV_I2S_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_I2S_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_I2S_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle Handle of the I2S instance as returned by the DRV_I2S_Open function buffer Buffer where the received data will be stored. size Buffer size in bytes bufferHandle Pointer to an argument that will contain the return buffer handle Function void DRV_I2S_BufferAddRead ( const DRV_HANDLE handle, DRV_I2S_BUFFER_HANDLE *bufferHandle, void * buffer, size_t size ) DRV_I2S_BufferAddWrite Function Schedule a non-blocking driver write operation. Implementation: Dynamic File drv_i2s.h Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 579 C void DRV_I2S_BufferAddWrite(const DRV_HANDLE handle, DRV_I2S_BUFFER_HANDLE * bufferHandle, void * buffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_I2S_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking write operation. The function returns with a valid buffer handle in the bufferHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance transmit queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_I2S_BUFFER_HANDLE_INVALID: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the client opened the driver for read-only • if the buffer size is 0 • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_I2S_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_I2S_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the I2S Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another I2S driver instance. It should not otherwise be called directly in an ISR. This function supports DMA mode of operation. Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S device instance and the DRV_I2S_Status must have returned SYS_STATUS_READY. DRV_I2S_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_I2S_Open call. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_I2S_BUFFER_HANDLE bufferHandle; // myI2SHandle is the handle returned // by the DRV_I2S_Open function. // Client registers an event handler with driver DRV_I2S_BufferEventHandlerSet(myI2SHandle, APP_I2SBufferEventHandler, (uintptr_t)&myAppObj); DRV_I2S_BufferAddWrite(myI2Shandle, &bufferHandle myBuffer, MY_BUFFER_SIZE); if(DRV_I2S_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_I2SBufferEventHandler(DRV_I2S_BUFFER_EVENT event, DRV_I2S_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_I2S_BUFFER_EVENT_COMPLETE: Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 580 // This means the data was transferred. break; case DRV_I2S_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle Handle of the I2S instance as return by the DRV_I2S_Open function buffer Data to be transmitted size Buffer size in bytes bufferHandle Pointer to an argument that will contain the return buffer handle Function void DRV_I2S_BufferAddWrite ( const DRV_HANDLE handle, DRV_I2S_BUFFER_HANDLE *bufferHandle, void * buffer, size_t size ); DRV_I2S_BufferAddWriteRead Function Schedule a non-blocking driver write-read operation. Implementation: Dynamic File drv_i2s.h C void DRV_I2S_BufferAddWriteRead(const DRV_HANDLE handle, DRV_I2S_BUFFER_HANDLE * bufferHandle, void * transmitBuffer, void * receiveBuffer, size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_I2S_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking write-read operation. The function returns with a valid buffer handle in the bufferHandle argument if the write-read request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_I2S_BUFFER_HANDLE_INVALID: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the client opened the driver for read only or write only • if the buffer size is 0 • if the queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_I2S_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_I2S_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the I2S Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another I2S driver instance. It should not otherwise be called directly in an ISR. This function is useful when there is valid read expected for every I2S write. The transmit and receive size must be same. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 581 Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S device instance and the DRV_I2S_Status must have returned SYS_STATUS_READY. DRV_I2S_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READWRITE must have been specified in the DRV_I2S_Open call. Example MY_APP_OBJ myAppObj; uint8_t mybufferTx[MY_BUFFER_SIZE]; uint8_t mybufferRx[MY_BUFFER_SIZE]; DRV_I2S_BUFFER_HANDLE bufferHandle; // myI2SHandle is the handle returned // by the DRV_I2S_Open function. // Client registers an event handler with driver DRV_I2S_BufferEventHandlerSet(myI2SHandle, APP_I2SBufferEventHandler, (uintptr_t)&myAppObj); DRV_I2S_BufferAddWriteRead(myI2Shandle, &bufferHandle, mybufferTx,mybufferRx,MY_BUFFER_SIZE); if(DRV_I2S_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_I2SBufferEventHandler(DRV_I2S_BUFFER_EVENT event, DRV_I2S_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_I2S_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_I2S_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle Handle of the I2S instance as returned by the DRV_I2S_Open function bufferHandle Pointer to an argument that will contain the return buffer handle transmitBuffer Buffer where the transmit data will be stored receiveBuffer Buffer where the received data will be stored size Buffer size in bytes Function void DRV_I2S_BufferAddWriteRead ( Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 582 const DRV_HANDLE handle, DRV_I2S_BUFFER_HANDLE *bufferHandle, void *transmitBuffer, void *receiveBuffer, size_t size ) DRV_I2S_BufferEventHandlerSet Function This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. Implementation: Dynamic File drv_i2s.h C void DRV_I2S_BufferEventHandlerSet(DRV_HANDLE handle, const DRV_I2S_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Returns None. Description This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. When a client calls either the DRV_I2S_BufferAddRead, DRV_I2S_BufferAddWrite or DRV_I2S_BufferAddWriteRead function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed. The event handler should be set before the client performs any "buffer add" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued buffer transfer has completed, it does not need to register a callback. Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S driver instance. DRV_I2S_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_I2S_BUFFER_HANDLE bufferHandle; // myI2SHandle is the handle returned // by the DRV_I2S_Open function. // Client registers an event handler with driver. This is done once DRV_I2S_BufferEventHandlerSet(myI2SHandle, APP_I2SBufferEventHandler, (uintptr_t)&myAppObj); DRV_I2S_BufferAddRead(myI2Shandle,&bufferHandle, myBuffer, MY_BUFFER_SIZE); if(DRV_I2S_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event Processing Technique. Event is received when // the buffer is processed. void APP_I2SBufferEventHandler(DRV_I2S_BUFFER_EVENT event, DRV_I2S_BUFFER_HANDLE handle, uintptr_t contextHandle) Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 583 { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) contextHandle; switch(event) { case DRV_I2S_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_I2S_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine eventHandler Pointer to the event handler function. context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_I2S_BufferEventHandlerSet ( const DRV_HANDLE handle, DRV_I2S_BUFFER_EVENT_HANDLER eventHandler, uintptr_t contextHandle ) DRV_I2S_BufferCombinedQueueSizeGet Function This function returns the number of bytes queued (to be processed) in the buffer queue. Implementation: Dynamic File drv_i2s.h C size_t DRV_I2S_BufferCombinedQueueSizeGet(DRV_HANDLE handle); Returns Returns the number of the bytes that have been processed for this buffer. Returns 0 for an invalid or an expired client handle. Description This function returns the number of bytes queued (to be processed) in the buffer queue of the driver instance associated with the calling client. The client can use this function to know number of remaining bytes (from the buffers submitted by it)is in the queue to be transmitted. Remarks None. Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S driver instance. DRV_I2S_Open must have been called to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 584 One of DRV_I2S_BufferAddRead/DRV_I2S_BufferAddWrite function must have been called and buffers should have been queued for transmission. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; size_t bufferQueuedSize; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_I2S_BUFFER_HANDLE bufferHandle; // myI2SHandle is the handle returned // by the DRV_I2S_Open function. // Client registers an event handler with driver. This is done once DRV_I2S_BufferEventHandlerSet(myI2SHandle, APP_I2SBufferEventHandle, (uintptr_t)&myAppObj); DRV_I2S_BufferAddRead(myI2Shandle,&bufferHandle, myBuffer, MY_BUFFER_SIZE); if(DRV_I2S_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // The data is being processed after adding the buffer to the queue. // The user can get to know dynamically available data in the queue to be // transmitted by calling DRV_I2S_BufferCombinedQueueSizeGet bufferQueuedSize = DRV_I2S_BufferCombinedQueueSizeGet(myI2SHandle); Parameters Parameters Description handle Opened client handle associated with a driver object. Function size_t DRV_I2S_BufferCombinedQueueSizeGet( DRV_HANDLE handle) DRV_I2S_BufferQueueFlush Function This function flushes off the buffers associated with the client object. Implementation: Dynamic File drv_i2s.h C void DRV_I2S_BufferQueueFlush(DRV_HANDLE handle); Returns None. Description This function flushes off the buffers associated with the client object and disables the DMA channel used for transmission. Remarks None. Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S driver instance. DRV_I2S_Open must have been called to obtain a valid opened device handle. One of DRV_I2S_BufferAddRead/DRV_I2S_BufferAddWrite function must have been called and buffers should have been queued for transmission. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 585 Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; size_t bufferQueuedSize; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_I2S_BUFFER_HANDLE bufferHandle; // myI2SHandle is the handle returned // by the DRV_I2S_Open function. // Client registers an event handler with driver. This is done once DRV_I2S_BufferEventHandlerSet(myI2SHandle, APP_I2SBufferEventHandle, (uintptr_t)&myAppObj); DRV_I2S_BufferAddRead(myI2Shandle,&bufferHandle, myBuffer, MY_BUFFER_SIZE); if(DRV_I2S_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // The data is being processed after adding the buffer to the queue. // The user can stop the data processing and flushoff the data // in the queue by calling DRV_I2S_BufferQueueFlush DRV_I2S_BufferQueueFlush(myI2SHandle); Parameters Parameters Description handle Opened client handle associated with a driver object. Function void DRV_I2S_BufferQueueFlush( DRV_HANDLE handle) DRV_I2S_Read Function Reads data from the I2S. Implementation: Dynamic File drv_i2s.h C size_t DRV_I2S_Read(const DRV_HANDLE handle, uint8_t * buffer, const size_t numBytes); Returns Number of bytes actually copied into the caller's buffer. Returns DRV_I2S_READ_ERROR in case of an error. Description This routine reads data from the I2S. This function is blocking if the driver was opened by the client for blocking operation. This function will not block if the driver was opened by the client for non blocking operation. If the ioIntent parameter at the time of opening the driver was DRV_IO_INTENT_BLOCKING, this function will only return when (or will block until) numBytes of bytes have been received or if an error occurred. If the ioIntent parameter at the time of opening the driver was DRV_IO_INTENT_NON_BLOCKING, this function will return with the number of bytes that were actually read. The function will not wait until numBytes of bytes have been read. Remarks This function is thread safe in a RTOS application. It is recommended that this function not be called in I2S Driver Event Handler due to the potential blocking nature of the function. This function should not be called directly in an ISR. It should not be called in the event handler associated with another I2S driver instance. This function does not supports DMA mode of operation. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 586 Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S driver instance. DRV_I2S_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_I2S_Open call. Example DRV_HANDLE myI2SHandle; // Returned from DRV_I2S_Open char myBuffer[MY_BUFFER_SIZE]; unsigned int count; unsigned int total; total = 0; do { count = DRV_I2S_Read(myI2SHandle, &myBuffer[total], MY_BUFFER_SIZE - total); total += count; if(count == DRV_I2S_READ_ERROR) { // Handle error ... } else { // Do what needs to be.. } } while( total < MY_BUFFER_SIZE ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine buffer Buffer into which the data read from the I2S instance will be placed. numBytes Total number of bytes that need to be read from the module instance (must be equal to or less than the size of the buffer) Function size_t DRV_I2S_Read ( const DRV_HANDLE handle, uint8_t *buffer, const size_t numBytes ) DRV_I2S_Write Function Writes data to the I2S. Implementation: Dynamic File drv_i2s.h C size_t DRV_I2S_Write(const DRV_HANDLE handle, uint8_t * buffer, const size_t numBytes); Returns Number of bytes actually written to the driver. Return DRV_I2S_WRITE_ERROR in case of an error. Description This routine writes data to the I2S. This function is blocking if the driver was opened by the client for blocking operation. This function will not block if the driver was opened by the client for non blocking operation. If the ioIntent parameter at the time of opening the driver was DRV_IO_INTENT_BLOCKING, this function will only return when (or will block until) numbytes of bytes have been transmitted or if an error occurred. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 587 If the ioIntent parameter at the time of opening the driver was DRV_IO_INTENT_NON_BLOCKING, this function will return with the number of bytes that were actually accepted for transmission. The function will not wait until numBytes of bytes have been transmitted. Remarks This function is thread safe in a RTOS application. It is recommended that this function not be called in I2S Driver Event Handler due to the potential blocking nature of the function. This function should not be called directly in an ISR. It should not be called in the event handler associated with another USART driver instance. This function does not supports DMA mode of operation. Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S driver instance. DRV_I2S_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_I2S_Open call. Example DRV_HANDLE myI2SHandle; // Returned from DRV_I2S_Open char myBuffer[MY_BUFFER_SIZE]; int count; unsigned int total; total = 0; do { count = DRV_I2S_Write(myI2SHandle, &myBuffer[total], MY_BUFFER_SIZE - total); total += count; if(count == DRV_I2S_WRITE_ERROR) { // Handle error ... } else { // Do what needs to be .. } } while( total < MY_BUFFER_SIZE ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine buffer Buffer containing the data to written. numbytes size of the buffer Function size_t DRV_I2S_Write ( const DRV_HANDLE handle, void * buffer, const size_t numbytes ) DRV_I2S_BufferProcessedSizeGet Function This function returns number of bytes that have been processed for the specified buffer. Implementation: Dynamic File drv_i2s.h C size_t DRV_I2S_BufferProcessedSizeGet(DRV_HANDLE handle); Returns Returns the number of the bytes that have been processed for this buffer. Returns 0 for an invalid or an expired buffer handle. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 588 Description This function returns number of bytes that have been processed for the specified buffer. The client can use this function, in a case where the buffer has terminated due to an error, to obtain the number of bytes that have been processed. If this function is called on a invalid buffer handle, or if the buffer handle has expired, the function returns 0. Remarks None. Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S driver instance. DRV_I2S_Open must have been called to obtain a valid opened device handle. One of DRV_I2S_BufferAddRead, DRV_I2S_BufferAddWrite or DRV_I2S_BufferAddWriteRead function must have been called and a valid buffer handle returned. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_I2S_BUFFER_HANDLE bufferHandle; // myI2SHandle is the handle returned // by the DRV_I2S_Open function. // Client registers an event handler with driver. This is done once DRV_I2S_BufferEventHandlerSet(myI2SHandle, APP_I2SBufferEventHandle, (uintptr_t)&myAppObj); DRV_I2S_BufferAddRead(myI2Shandle,&bufferHandle, myBuffer, MY_BUFFER_SIZE); if(DRV_I2S_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event Processing Technique. Event is received when // the buffer is processed. void APP_I2SBufferEventHandler(DRV_I2S_BUFFER_EVENT event, DRV_I2S_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) contextHandle; size_t processedBytes; switch(event) { case DRV_I2S_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_I2S_BUFFER_EVENT_ERROR: // Error handling here. // We can find out how many bytes were processed in this // buffer before the error occurred. processedBytes = DRV_I2S_BufferProcessedSizeGet(myI2SHandle); break; default: Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 589 break; } } Parameters Parameters Description bufferhandle Handle of the buffer of which the processed number of bytes to be obtained. Function size_t DRV_I2S_BufferProcessedSizeGet( DRV_HANDLE handle) d) Miscellaneous Functions DRV_I2S_BaudSet Function This function sets the baud. Implementation: Dynamic File drv_i2s.h C void DRV_I2S_BaudSet(DRV_HANDLE handle, uint32_t spiClock, uint32_t baud); Returns None Description This function sets the baud rate for the I2S operation. Remarks None. Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S driver instance. DRV_I2S_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_HANDLE handle; uint32_t baud; uint32_t clock; // myI2SHandle is the handle returned // by the DRV_I2S_Open function. // Client registers an event handler with driver. This is done once DRV_I2S_BufferEventHandlerSet(myI2SHandle, APP_I2SBufferEventHandle, (uintptr_t)&myAppObj); // Sets the baud rate to a new value as below baud = 115200; clock = 40000000UL; DRV_I2S_BaudSet(myI2SHandle, clock, baud); // Further perform the operation needed DRV_I2S_BufferAddRead(myI2Shandle,&bufferHandle, myBuffer, MY_BUFFER_SIZE); Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 590 if(DRV_I2S_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event Processing Technique. Event is received when // the buffer is processed. void APP_I2SBufferEventHandler(DRV_I2S_BUFFER_EVENT event, DRV_I2S_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) contextHandle; size_t processedBytes; switch(event) { case DRV_I2S_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_I2S_BUFFER_EVENT_ERROR: // Error handling here. // We can find out how many bytes were processed in this // buffer before the error occurred. processedBytes = DRV_I2S_BufferProcessedSizeGet(myI2SHandle); break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine i2sClock The Source clock frequency to the i2S module. baud The baud to be set. Function void DRV_I2S_BaudSet( DRV_HANDLE handle, uint32_t spiClock, uint32_t baud) DRV_I2S_ErrorGet Function This function returns the error(if any) associated with the last client request. Implementation: Dynamic File drv_i2s.h C DRV_I2S_ERROR DRV_I2S_ErrorGet(DRV_HANDLE handle); Returns A DRV_I2S_ERROR type indicating last known error status. Description This function returns the error(if any) associated with the last client request. The DRV_I2S_Read() and DRV_I2S_Write() will update the client error status when these functions return DRV_I2S_READ_ERROR and DRV_I2S_WRITE_ERROR, respectively. If the driver send a Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 591 DRV_I2S_BUFFER_EVENT_ERROR to the client, the client can call this function to know the error cause. The error status will be updated on every operation and should be read frequently (ideally immediately after the driver operation has completed) to know the relevant error status. Remarks It is the client's responsibility to make sure that the error status is obtained frequently. The driver will update the client error status regardless of whether this has been examined by the client. Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S driver instance. DRV_I2S_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_I2S_BUFFER_HANDLE bufferHandle; // myI2SHandle is the handle returned // by the DRV_I2S_Open function. // Client registers an event handler with driver. This is done once DRV_I2S_BufferEventHandlerSet( myI2SHandle, APP_I2SBufferEventHandle, (uintptr_t)&myAppObj ); DRV_I2S_BufferAddRead( myI2Shandle,&bufferHandle, myBuffer, MY_BUFFER_SIZE ); if(DRV_I2S_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event Processing Technique. Event is received when // the buffer is processed. void APP_I2SBufferEventHandler( DRV_I2S_BUFFER_EVENT event, DRV_I2S_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle ) { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) contextHandle; size_t processedBytes; switch(event) { case DRV_I2S_BUFFER_EVENT_SUCCESS: // This means the data was transferred. break; case DRV_I2S_BUFFER_EVENT_FAILURE: // Error handling here. // We can find out how many bytes were processed in this // buffer before the error occurred. We can also find // the error cause. processedBytes = DRV_I2S_BufferProcessedSizeGet(myI2SHandle); if(DRV_I2S_ERROR_RECEIVE_OVERRUN == DRV_I2S_ErrorGet(myI2SHandle)) { // There was an receive over flow error. // Do error handling here. } break; Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 592 default: break; } } Parameters Parameters Description bufferhandle Handle of the buffer of which the processed number of bytes to be obtained. Function DRV_I2S_ERROR DRV_I2S_ErrorGet(DRV_HANDLE handle) DRV_I2S_ReceiveErrorIgnore Function This function enable/disable ignoring of the receive overflow error. Implementation: Dynamic File drv_i2s.h C void DRV_I2S_ReceiveErrorIgnore(DRV_HANDLE handle, bool errorEnable); Returns None Description A receive overflow is not a critical error; during receive overflow data in the FIFO is not overwritten by receive data. Ignore receive overflow is needed for cases when there is a general performance problem in the system that software must handle properly. Remarks None. Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S driver instance. DRV_I2S_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_HANDLE handle; uint32_t baud; uint32_t baud;* // myI2SHandle is the handle returned // by the DRV_I2S_Open function. // Client registers an event handler with driver. This is done once DRV_I2S_BufferEventHandlerSet(myI2SHandle, APP_I2SBufferEventHandle, (uintptr_t)&myAppObj); // Enable ignoring of receive overflow error DRV_I2S_ReceiveErrorIgnore(myI2SHandle, true); // Further perform the operation needed DRV_I2S_BufferAddRead(myI2Shandle,&bufferHandle, myBuffer, MY_BUFFER_SIZE); if(DRV_I2S_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 593 // Event Processing Technique. Event is received when // the buffer is processed. void APP_I2SBufferEventHandler(DRV_I2S_BUFFER_EVENT event, DRV_I2S_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) contextHandle; size_t processedBytes; switch(event) { case DRV_I2S_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_I2S_BUFFER_EVENT_ERROR: // Error handling here. // We can find out how many bytes were processed in this // buffer before the error occurred. processedBytes = DRV_I2S_BufferProcessedSizeGet(bufferHandle); break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine errorIgnore When set to 'true' enables ignoring of transmit underrun error. When set to 'false' disables ignoring of transmit underrun error. Function void DRV_I2S_ReceiveErrorIgnore( DRV_HANDLE handle, bool errorEnable) DRV_I2S_TransmitErrorIgnore Function This function enable/disable ignoring of the transmit underrun error. Implementation: Dynamic File drv_i2s.h C void DRV_I2S_TransmitErrorIgnore(DRV_HANDLE handle, bool errorIgnore); Returns None Description A Transmit underrun error is not a critical error and zeros are transmitted until the SPIxTXB is not empty. Ignore Transmit underrun error is needed for cases when software does not care or does not need to know about underrun conditions. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 594 Preconditions The DRV_I2S_Initialize routine must have been called for the specified I2S driver instance. DRV_I2S_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_HANDLE handle; uint32_t baud; uint32_t baud;* // myI2SHandle is the handle returned // by the DRV_I2S_Open function. // Client registers an event handler with driver. This is done once DRV_I2S_BufferEventHandlerSet(myI2SHandle, APP_I2SBufferEventHandle, (uintptr_t)&myAppObj); // Enable ignoring of transmit underrun error DRV_I2S_TransmitErrorIgnore(myI2SHandle, true); // Further perform the operation needed DRV_I2S_BufferAddRead(myI2Shandle,&bufferHandle, myBuffer, MY_BUFFER_SIZE); if(DRV_I2S_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event Processing Technique. Event is received when // the buffer is processed. void APP_I2SBufferEventHandler(DRV_I2S_BUFFER_EVENT event, DRV_I2S_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) contextHandle; size_t processedBytes; switch(event) { case DRV_I2S_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_I2S_BUFFER_EVENT_ERROR: // Error handling here. // We can find out how many bytes were processed in this // buffer before the error occurred. processedBytes = DRV_I2S_BufferProcessedSizeGet(bufferHandle); break; default: break; } } Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 595 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine errorIgnore When set to 'true' enables ignoring of transmit underrun error. When set to 'false' disables ignoring of transmit underrun error. Function void DRV_I2S_TransmitErrorIgnore( DRV_HANDLE handle, bool errorIgnore) e) Data Types and Constants DRV_I2S_AUDIO_PROTOCOL_MODE Enumeration Identifies the Audio Protocol Mode of the I2S module. File drv_i2s.h C typedef enum { DRV_I2S_AUDIO_I2S, DRV_I2S_AUDIO_LFET_JUSTIFIED, DRV_I2S_AUDIO_RIGHT_JUSTIFIED, DRV_I2S_AUDIO_PCM_DSP } DRV_I2S_AUDIO_PROTOCOL_MODE; Members Members Description DRV_I2S_AUDIO_I2S I2S Audio Protocol DRV_I2S_AUDIO_LFET_JUSTIFIED Left Justified Audio Protocol DRV_I2S_AUDIO_RIGHT_JUSTIFIED Right Justified Audio Protocol DRV_I2S_AUDIO_PCM_DSP PCM/DSP Audio Protocol Description I2S Audio Protocol Mode This enumeration identifies Audio Protocol Mode of the I2S module. Remarks None. DRV_I2S_BUFFER_EVENT Enumeration Identifies the possible events that can result from a buffer add request. File drv_i2s.h C typedef enum { DRV_I2S_BUFFER_EVENT_COMPLETE, DRV_I2S_BUFFER_EVENT_ERROR, DRV_I2S_BUFFER_EVENT_ABORT } DRV_I2S_BUFFER_EVENT; Members Members Description DRV_I2S_BUFFER_EVENT_COMPLETE Data was transferred successfully. DRV_I2S_BUFFER_EVENT_ERROR Error while processing the request DRV_I2S_BUFFER_EVENT_ABORT Data transfer aborted (Applicable in DMA mode) Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 596 Description I2S Driver Events This enumeration identifies the possible events that can result from a buffer add request caused by the client calling either the DRV_I2S_BufferAddRead, DRV_I2S_BufferAddWrite or DRV_I2S_BufferAddWriteRead functions. Remarks One of these values is passed in the "event" parameter of the event handling callback function that the client registered with the driver by calling the DRV_I2S_BufferEventHandlerSet function when a buffer transfer request is completed. DRV_I2S_BUFFER_EVENT_HANDLER Type Pointer to a I2S Driver Buffer Event handler function File drv_i2s.h C typedef void (* DRV_I2S_BUFFER_EVENT_HANDLER)(DRV_I2S_BUFFER_EVENT event, DRV_I2S_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle); Returns None. Description I2S Driver Buffer Event Handler Function This data type defines the required function signature for the I2S driver buffer event handling callback function. A client must register a pointer to a buffer event handling function whose function signature (parameter and return value types) match the types specified by this function pointer in order to receive buffer related event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks If the event is DRV_I2S_BUFFER_EVENT_COMPLETE, this means that the data was transferred successfully. If the event is DRV_I2S_BUFFER_EVENT_ERROR, this means that the data was not transferred successfully. The bufferHandle parameter contains the buffer handle of the buffer that failed. The DRV_I2S_ErrorGet function can be called to know the error. The DRV_I2S_BufferProcessedSizeGet function can be called to find out how many bytes were processed. The bufferHandle parameter contains the buffer handle of the buffer that associated with the event. The context parameter contains a handle to the client context, provided at the time the event handling function was registered using the DRV_I2S_BufferEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the buffer add request. The buffer handle in bufferHandle expires after this event handler exits. In that the buffer object that was allocated is deallocated by the driver after the event handler exits. The event handler function executes in the driver peripheral's interrupt context when the driver is configured for interrupt mode operation. It is recommended of the application to not perform process intensive or blocking operations with in this function. The DRV_I2S_BufferAddRead, DRV_I2S_BufferAddWrite and DRV_I2S_BufferAddWriteRead functions can be called in the event handler to add a buffer to the driver queue. These functions can only be called to add buffers to the driver whose event handler is running. For example, buffers cannot be added I2S2 driver in I2S1 driver event handler. Example void APP_MyBufferEventHandler ( DRV_I2S_BUFFER_EVENT event, DRV_I2S_BUFFER_HANDLE bufferHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_I2S_BUFFER_EVENT_COMPLETE: // Handle the completed buffer. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 597 break; case DRV_I2S_BUFFER_EVENT_ERROR: default: // Handle error. break; } } Parameters Parameters Description event Identifies the type of event bufferHandle Handle identifying the buffer to which the event relates context Value identifying the context of the application that registered the event handling function. DRV_I2S_BUFFER_HANDLE Type Handle identifying a read or write buffer passed to the driver. File drv_i2s.h C typedef uintptr_t DRV_I2S_BUFFER_HANDLE; Description I2S Driver Buffer Handle A buffer handle value is returned by a call to the DRV_I2S_BufferAddRead, DRV_I2S_BufferAddWrite, and DRV_I2S_BufferAddWriteRead functions. This handle is associated with the buffer passed into the function and it allows the application to track the completion of the data from (or into) that buffer. The buffer handle value returned from the "buffer add" function is returned back to the client by the "event handler callback" function registered with the driver. The buffer handle assigned to a client request expires when the client has been notified of the completion of the buffer transfer (after event handler function that notifies the client returns) or after the buffer has been retired by the driver if no event handler callback was set. Remarks None DRV_I2S_CLOCK_MODE Enumeration Identifies the various clock modes of the I2S module. File drv_i2s.h C typedef enum { DRV_I2S_CLOCK_MODE_IDLE_LOW_EDGE_RISE, DRV_I2S_CLOCK_MODE_IDLE_LOW_EDGE_FALL, DRV_I2S_CLOCK_MODE_IDLE_HIGH_EDGE_FALL, DRV_I2S_CLOCK_MODE_IDLE_HIGH_EDGE_RISE } DRV_I2S_CLOCK_MODE; Members Members Description DRV_I2S_CLOCK_MODE_IDLE_LOW_EDGE_RISE I2S Clock Mode 0 - Idle State Low & Sampling on Rising Edge DRV_I2S_CLOCK_MODE_IDLE_LOW_EDGE_FALL I2S Clock Mode 1 - Idle State Low & Sampling on Falling Edge DRV_I2S_CLOCK_MODE_IDLE_HIGH_EDGE_FALL I2S Clock Mode 2 - Idle State High & Sampling on Falling Edge DRV_I2S_CLOCK_MODE_IDLE_HIGH_EDGE_RISE I2S Clock Mode 3 - Idle State High & Sampling on Rising Edge Description I2S Clock Mode Selection Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 598 This enumeration identifies the supported clock modes of the I2S module. Remarks None. DRV_I2S_DATA16 Structure Defines the left and right channel data for 16-bit audio data File drv_i2s.h C typedef struct { int16_t leftData; int16_t rightData; } DRV_I2S_DATA16; Members Members Description int16_t leftData; Left channel data int16_t rightData; Right channel data Description I2S Driver Audio Data 16 Defines the left and right channel data for 16-bit audio data Remarks None. DRV_I2S_DATA24 Structure Defines the left and right channel data for 24-bit audio data File drv_i2s.h C typedef struct { int32_t leftData : 24; int32_t leftDataPad : 8; int32_t rightData : 24; int32_t rightDataPad : 8; } DRV_I2S_DATA24; Members Members Description int32_t leftData : 24; Left channel data int32_t leftDataPad : 8; Left channel data pad int32_t rightData : 24; Right channel data int32_t rightDataPad : 8; Right channel data pad Description I2S Driver Audio Data 24 Defines the left and right channel data for 24-bit audio data Remarks None. DRV_I2S_DATA32 Structure Defines the left and right channel data for 32-bit audio data Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 599 File drv_i2s.h C typedef struct { int32_t leftData; int32_t rightDataPad; } DRV_I2S_DATA32; Members Members Description int32_t leftData; Left channel data int32_t rightDataPad; Right channel data Description I2S Driver Audio Data 32 Defines the left and right channel data for 32-bit audio data Remarks None. DRV_I2S_ERROR Enumeration Defines the possible errors that can occur during driver operation. File drv_i2s.h C typedef enum { DRV_I2S_ERROR_NONE, DRV_I2S_ERROR_RECEIVE_OVERFLOW, DRV_I2S_ERROR_TRANSMIT_UNDERUN, DRV_I2S_ERROR_FRAMING, DRV_I2S_ERROR_ADDRESS } DRV_I2S_ERROR; Members Members Description DRV_I2S_ERROR_NONE Data was transferred successfully. DRV_I2S_ERROR_RECEIVE_OVERFLOW Receive overflow error. DRV_I2S_ERROR_TRANSMIT_UNDERUN Transmit underrun error. DRV_I2S_ERROR_FRAMING Framing error. DRV_I2S_ERROR_ADDRESS Channel address error (Applicable in DMA mode) Description I2S Driver Error This data type defines the possible errors that can occur when occur during USART driver operation. These values are returned by DRV_I2S_ErrorGet function. Remarks None. DRV_I2S_MODE Enumeration Identifies the usage modes of the I2S module. File drv_i2s.h Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 600 C typedef enum { DRV_I2S_MODE_SLAVE, DRV_I2S_MODE_MASTER } DRV_I2S_MODE; Members Members Description DRV_I2S_MODE_SLAVE I2S Mode Slave DRV_I2S_MODE_MASTER I2S Mode Master Description I2S Usage Modes Enumeration This enumeration identifies the whether the I2S module will be used as a master or slave. Remarks None. DRV_I2S_BUFFER_HANDLE_INVALID Macro Definition of an invalid buffer handle. File drv_i2s.h C #define DRV_I2S_BUFFER_HANDLE_INVALID ((DRV_I2S_BUFFER_HANDLE)(-1)) Description I2S Driver Invalid Buffer Handle This is the definition of an invalid buffer handle. An invalid buffer handle is returned by DRV_I2S_BufferAddRead, DRV_I2S_BufferAddWrite and DRV_I2S_BufferAddWriteRead functions if the buffer add request was not successful. Remarks None DRV_I2S_COUNT Macro Number of valid I2S driver indices File drv_i2s.h C #define DRV_I2S_COUNT Description I2S Driver Module Count This constant identifies the maximum number of I2S Driver instances that should be defined by the application. Defining more instances than this constant will waste RAM memory space. This constant can also be used by the application to identify the number of I2S instances on this microcontroller. Remarks This value is part-specific. DRV_I2S_READ_ERROR Macro I2S Driver Read Error. File drv_i2s.h Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 601 C #define DRV_I2S_READ_ERROR ((size_t)(-1)) Description I2S Driver Read Error This constant is returned by DRV_I2S_Read function when an error occurs. Remarks None. DRV_I2S_WRITE_ERROR Macro I2S Driver Write Error. File drv_i2s.h C #define DRV_I2S_WRITE_ERROR ((size_t)(-1)) Description I2S Driver Write Error This constant is returned by DRV_I2S_Write() function when an error occurs. Remarks None. DRV_I2S_INDEX_0 Macro I2S driver index definitions File drv_i2s.h C #define DRV_I2S_INDEX_0 0 Description Driver I2S Module Index These constants provide I2S driver index definition. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_I2S_Initialize and DRV_I2S_Open routines to identify the driver instance in use. DRV_I2S_INDEX_1 Macro File drv_i2s.h C #define DRV_I2S_INDEX_1 1 Description This is macro DRV_I2S_INDEX_1. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 602 DRV_I2S_INDEX_2 Macro File drv_i2s.h C #define DRV_I2S_INDEX_2 2 Description This is macro DRV_I2S_INDEX_2. DRV_I2S_INDEX_3 Macro File drv_i2s.h C #define DRV_I2S_INDEX_3 3 Description This is macro DRV_I2S_INDEX_3. DRV_I2S_INDEX_4 Macro File drv_i2s.h C #define DRV_I2S_INDEX_4 4 Description This is macro DRV_I2S_INDEX_4. DRV_I2S_INDEX_5 Macro File drv_i2s.h C #define DRV_I2S_INDEX_5 5 Description This is macro DRV_I2S_INDEX_5. DRV_I2S_INTERFACE Structure This structure defines a structure of I2S Driver function pointers. File drv_i2s.h C typedef struct { SYS_MODULE_OBJ (* initialize)(const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init); void (* deinitialize)(SYS_MODULE_OBJ); SYS_STATUS (* status)(SYS_MODULE_OBJ object); void (* tasks)(SYS_MODULE_OBJ object); void (* tasksError)(SYS_MODULE_OBJ object); DRV_HANDLE (* open)(const SYS_MODULE_INDEX iDriver, const DRV_IO_INTENT ioIntent); Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 603 void (* close)(const DRV_HANDLE handle); void (* bufferAddWrite)(const DRV_HANDLE handle, DRV_I2S_BUFFER_HANDLE *bufferHandle, void *buffer, size_t size); void (* bufferAddRead)(const DRV_HANDLE handle, DRV_I2S_BUFFER_HANDLE *bufferHandle, void *buffer, size_t size); void (* bufferAddWriteRead)(const DRV_HANDLE handle, DRV_I2S_BUFFER_HANDLE *bufferHandle, void *transmitBuffer, void *receiveBuffer, size_t size); size_t (* read)(const DRV_HANDLE handle, uint8_t *buffer, const size_t numBytes); size_t (* write)(const DRV_HANDLE handle, uint8_t *buffer, const size_t numBytes); void (* eventHandlerSet)(DRV_HANDLE handle, const DRV_I2S_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); size_t (* bufferProcessedSizeGet)(DRV_HANDLE handle); size_t (* bufferCombinedQueueSizeGet)(DRV_HANDLE handle); void (* bufferQueueFlush)(DRV_HANDLE handle); DRV_I2S_ERROR (* errorGet)(DRV_HANDLE handle); void (* baudSet)(DRV_HANDLE handle, uint32_t peripheralClock, uint32_t baud); void (* setAudioCommunicationMode)(DRV_HANDLE handle, uint8_t audioCommWidth); void (* transmitErrorIgnore)(DRV_HANDLE handle, bool errorIgnore); void (* receiveErrorIgnore)(DRV_HANDLE handle, bool errorEnable); } DRV_I2S_INTERFACE; Members Members Description SYS_MODULE_OBJ (* initialize)(const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init); Pointer to the driver Initialization function void (* deinitialize)(SYS_MODULE_OBJ); Pointer to the driver Deinitialization function SYS_STATUS (* status)(SYS_MODULE_OBJ object); Pointer to the driver Status function void (* tasks)(SYS_MODULE_OBJ object); Pointer to the Tasks function void (* tasksError)(SYS_MODULE_OBJ object); Pointer to the Error Tasks function DRV_HANDLE (* open)(const SYS_MODULE_INDEX iDriver, const DRV_IO_INTENT ioIntent); Pointer to the Open function void (* close)(const DRV_HANDLE handle); Pointer to the Close function void (* bufferAddWrite)(const DRV_HANDLE handle, DRV_I2S_BUFFER_HANDLE *bufferHandle, void *buffer, size_t size); Pointer to the Buffer Add Write function void (* bufferAddRead)(const DRV_HANDLE handle, DRV_I2S_BUFFER_HANDLE *bufferHandle, void *buffer, size_t size); Pointer to the Buffer Add Read function void (* bufferAddWriteRead)(const DRV_HANDLE handle, DRV_I2S_BUFFER_HANDLE *bufferHandle, void *transmitBuffer, void *receiveBuffer, size_t size); Pointer to the buffer Add Read Write function size_t (* read)(const DRV_HANDLE handle, uint8_t *buffer, const size_t numBytes); Pointer to the driver Read function size_t (* write)(const DRV_HANDLE handle, uint8_t *buffer, const size_t numBytes); Pointer to the driver Write function void (* eventHandlerSet)(DRV_HANDLE handle, const DRV_I2S_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t contextHandle); Pointer to the driver Buffer Event Handler Set function size_t (* bufferProcessedSizeGet)(DRV_HANDLE handle); Pointer to the driver Buffer Processed Size Get function size_t (* bufferCombinedQueueSizeGet)(DRV_HANDLE handle); Pointer to the driver Buffer Combined Queue Size Get Function void (* bufferQueueFlush)(DRV_HANDLE handle); Pointer to the driver Buffer Queue Flush Function DRV_I2S_ERROR (* errorGet)(DRV_HANDLE handle); Pointer to the driver Error Get function void (* baudSet)(DRV_HANDLE handle, uint32_t peripheralClock, uint32_t baud); Pointer to the driver Baud Set function void (* setAudioCommunicationMode)(DRV_HANDLE handle, uint8_t audioCommWidth); Pointer to the driver Set Audio Communication mode function Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 604 void (* transmitErrorIgnore)(DRV_HANDLE handle, bool errorIgnore); Pointer to the driver Transmit Error Ignore function void (* receiveErrorIgnore)(DRV_HANDLE handle, bool errorEnable); Pointer to the driver Receive Error Ignore function Description I2S Driver Interface This structure defines a structure of I2S Driver function pointers. A driver of any peripheral that supports the I2S protocol can export such a structure. The top level I2S Driver abstraction layer will then use this structure to map a I2S Driver call to underlying peripheral driver. Remarks None. Files Files Name Description drv_i2s.h I2S Driver Interface header file drv_i2s_config_template.h I2S Driver Configuration Template. Description drv_i2s.h I2S Driver Interface header file Enumerations Name Description DRV_I2S_AUDIO_PROTOCOL_MODE Identifies the Audio Protocol Mode of the I2S module. DRV_I2S_BUFFER_EVENT Identifies the possible events that can result from a buffer add request. DRV_I2S_CLOCK_MODE Identifies the various clock modes of the I2S module. DRV_I2S_ERROR Defines the possible errors that can occur during driver operation. DRV_I2S_MODE Identifies the usage modes of the I2S module. Functions Name Description DRV_I2S_BaudSet This function sets the baud. Implementation: Dynamic DRV_I2S_BufferAddRead Schedule a non-blocking driver read operation. Implementation: Dynamic DRV_I2S_BufferAddWrite Schedule a non-blocking driver write operation. Implementation: Dynamic DRV_I2S_BufferAddWriteRead Schedule a non-blocking driver write-read operation. Implementation: Dynamic DRV_I2S_BufferCombinedQueueSizeGet This function returns the number of bytes queued (to be processed) in the buffer queue. Implementation: Dynamic DRV_I2S_BufferEventHandlerSet This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. Implementation: Dynamic DRV_I2S_BufferProcessedSizeGet This function returns number of bytes that have been processed for the specified buffer. Implementation: Dynamic DRV_I2S_BufferQueueFlush This function flushes off the buffers associated with the client object. Implementation: Dynamic DRV_I2S_Close Closes an opened-instance of the I2S driver. Implementation: Dynamic DRV_I2S_Deinitialize Deinitializes the specified instance of the I2S driver module. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 605 DRV_I2S_ErrorGet This function returns the error(if any) associated with the last client request. Implementation: Dynamic DRV_I2S_Initialize Initializes hardware and data for the instance of the I2S module. Implementation: Dynamic DRV_I2S_Open Opens the specified I2S driver instance and returns a handle to it. Implementation: Dynamic DRV_I2S_Read Reads data from the I2S. Implementation: Dynamic DRV_I2S_ReceiveErrorIgnore This function enable/disable ignoring of the receive overflow error. Implementation: Dynamic DRV_I2S_Status Gets the current status of the I2S driver module. Implementation: Dynamic DRV_I2S_Tasks Maintains the driver's receive state machine and implements its ISR. Implementation: Dynamic DRV_I2S_TasksError Maintains the driver's error state machine and implements its ISR. Implementation: Dynamic DRV_I2S_TransmitErrorIgnore This function enable/disable ignoring of the transmit underrun error. Implementation: Dynamic DRV_I2S_Write Writes data to the I2S. Implementation: Dynamic Macros Name Description DRV_I2S_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_I2S_COUNT Number of valid I2S driver indices DRV_I2S_INDEX_0 I2S driver index definitions DRV_I2S_INDEX_1 This is macro DRV_I2S_INDEX_1. DRV_I2S_INDEX_2 This is macro DRV_I2S_INDEX_2. DRV_I2S_INDEX_3 This is macro DRV_I2S_INDEX_3. DRV_I2S_INDEX_4 This is macro DRV_I2S_INDEX_4. DRV_I2S_INDEX_5 This is macro DRV_I2S_INDEX_5. DRV_I2S_READ_ERROR I2S Driver Read Error. DRV_I2S_WRITE_ERROR I2S Driver Write Error. Structures Name Description DRV_I2S_DATA16 Defines the left and right channel data for 16-bit audio data DRV_I2S_DATA24 Defines the left and right channel data for 24-bit audio data DRV_I2S_DATA32 Defines the left and right channel data for 32-bit audio data DRV_I2S_INTERFACE This structure defines a structure of I2S Driver function pointers. Types Name Description DRV_I2S_BUFFER_EVENT_HANDLER Pointer to a I2S Driver Buffer Event handler function DRV_I2S_BUFFER_HANDLE Handle identifying a read or write buffer passed to the driver. Description I2S Driver Interface The I2S device driver provides a simple interface to manage the I2S module on Microchip microcontrollers. This file provides the interface definition for the I2S driver. File Name drv_i2s.h Company Microchip Technology Inc. Volume V: MPLAB Harmony Framework Driver Libraries Help I2S Driver Library Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 606 drv_i2s_config_template.h I2S Driver Configuration Template. Macros Name Description DRV_I2S_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_I2S_INDEX I2S Static Index selection DRV_I2S_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_I2S_INTERRUPT_MODE Macro controls interrupt based operation of the driver DRV_I2S_INTERRUPT_SOURCE_ERROR Defines the interrupt source for the error interrupt DRV_I2S_INTERRUPT_SOURCE_RECEIVE Macro to define the Receive interrupt source in case of static driver DRV_I2S_INTERRUPT_SOURCE_TRANSMIT Macro to define the Transmit interrupt source in case of static driver DRV_I2S_PERIPHERAL_ID Configures the I2S PLIB Module ID DRV_I2S_QUEUE_DEPTH_COMBINED Number of entries of all queues in all instances of the driver. DRV_I2S_RECEIVE_DMA_CHAINING_CHANNEL Macro to defines the I2S Driver Receive DMA Chaining Channel in case of static driver DRV_I2S_RECEIVE_DMA_CHANNEL Macro to defines the I2S Driver Receive DMA Channel in case of static driver DRV_I2S_STOP_IN_IDLE Identifies whether the driver should stop operations in stop in Idle mode. DRV_I2S_TRANSMIT_DMA_CHANNEL Macro to defines the I2S Driver Transmit DMA Channel in case of static driver Description I2S Driver Configuration Template These file provides the list of all the configurations that can be used with the driver. This file should not be included in the driver. File Name drv_i2s_config_template.h Company Microchip Technology Inc. Input Capture Driver Library This section describes the Input Capture Driver Library. Introduction The Input Capture Static Driver provides a high-level interface to manage the Input Capture module on the Microchip family of microcontrollers. Description Through the MHC, this driver provides APIs for the following: • Initializing the module • Starting/Stopping of the capture • 16/32-bit data reads • Buffer empty status Library Interface Functions Name Description DRV_IC_Initialize Initializes the Input Capture instance for the specified driver index. Implementation: Static DRV_IC_BufferIsEmpty Returns the Input Capture instance buffer empty status for the specified driver index. Implementation: Static DRV_IC_Capture16BitDataRead Reads the 16-bit Input Capture for the specified driver index. Implementation: Static Volume V: MPLAB Harmony Framework Driver Libraries Help Input Capture Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 607 DRV_IC_Capture32BitDataRead Reads the 32-bit Input Capture for the specified driver index. Implementation: Static DRV_IC_Start Starts the Input Capture instance for the specified driver index. Implementation: Static DRV_IC_Stop Stops the Input Capture instance for the specified driver index. Implementation: Static Description This section describes the Application Programming Interface (API) functions of the Input Capture Driver Library. Functions DRV_IC_Initialize Function Initializes the Input Capture instance for the specified driver index. Implementation: Static File help_drv_ic.h C void DRV_IC_Initialize(); Returns None. Description This routine initializes the Input Capture driver instance for the specified driver instance, making it ready for clients to use it. The initialization routine is specified by the MHC parameters. The driver instance index is independent of the Input Capture module ID. For example, driver instance 0 can be assigned to Input Capture 2. Remarks This routine must be called before any other Input Capture routine is called. This routine should only be called once during system initialization. Preconditions None. Function void DRV_IC_Initialize( void ) DRV_IC_BufferIsEmpty Function Returns the Input Capture instance buffer empty status for the specified driver index. Implementation: Static File help_drv_ic.h C bool DRV_IC_BufferIsEmpty(); Returns Boolean • 1 - Buffer is empty • 0 - Buffer is not empty Description Returns the Input Capture instance buffer empty status for the specified driver index. The function should be called to determine whether or not the IC buffer has data. Volume V: MPLAB Harmony Framework Driver Libraries Help Input Capture Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 608 Remarks None. Preconditions DRV_IC_Initialize has been called. Function bool DRV_IC_BufferIsEmpty( void ) DRV_IC_Capture16BitDataRead Function Reads the 16-bit Input Capture for the specified driver index. Implementation: Static File help_drv_ic.h C uint16_t DRV_IC_Capture16BitDataRead(); Returns uint16_t value of the data read from the Input Capture. Description This routine reads the 16-bit data for the specified driver index. Remarks None. Preconditions DRV_IC_Initialize has been called. Function uint16_t DRV_IC_Capture16BitDataRead( void ) DRV_IC_Capture32BitDataRead Function Reads the 32-bit Input Capture for the specified driver index. Implementation: Static File help_drv_ic.h C uint32_t DRV_IC_Capture32BitDataRead(); Returns uint32_t value of the data read from the Input Capture. Description This routine reads the 32-bit data for the specified driver index Remarks None. Preconditions DRV_IC_Initialize has been called. Function uint32_t DRV_IC_Capture32BitDataRead( void ) Volume V: MPLAB Harmony Framework Driver Libraries Help Input Capture Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 609 DRV_IC_Start Function Starts the Input Capture instance for the specified driver index. Implementation: Static File help_drv_ic.h C void DRV_IC_Start(); Returns None. Description This routine starts the Input Capture driver for the specified driver index, starting an input capture. Remarks None. Preconditions DRV_IC_Initialize has been called. Function void DRV_IC_Start( void ) DRV_IC_Stop Function Stops the Input Capture instance for the specified driver index. Implementation: Static File help_drv_ic.h C void DRV_IC_Stop(); Returns None. Description This routine stops the Input Capture driver for the specified driver index, stopping an input capture. Remarks None. Preconditions DRV_IC_Initialize has been called. Function void DRV_IC_Stop( void ) Input System Service Touch Driver Library This section describes the Touch Driver Libraries that support the Input System Service. These libraries are variants of libraries previously created to support the Touch System Service, which is being deprecated by the Input System Service. Touch Driver Libraries in service of the Touch System Service: ADC Touch Driver Library This topic describes the ADC Touch Driver Library. mXT336T Touch Driver Library This topic describes the mXT336T Touch Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help Input System Service Touch Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 610 Input System Service Touch ADC Driver Library This touch driver library establishes a software resistive touch controller using the Analog-to-Digital Converter (ADC) module. This driver provides application routines to read touch input data from the touch screen. Touch events are detected using an interrupt service routine rather than polling. This driver also allows provides the capability to set translation coefficients that allow an application to map a raw screen values to actual native display size using through 4-point calibration technique. Using the Library This topic describes the basic architecture of the Touch ADC Driver Library for the Input System Service and provides information and examples on its use. Interface Header File: /firmware/src/system_config//driver/input/touch_adc/drv_touch_adc.h The interface to the Touch ADC Driver library is defined in the drv_touch_adc.h header file related to the currently active project target configuration. This file is automatically generated by MHGC. Any C language source (.c) file that uses the ADC Touch Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This topic describes the components of the Touch ADC solution in support of the Input System Service. • Touch ADC Driver – Finite-State machine that biases the x-axis and y-axis analog pins to measure resistance on a touch screen. Identifies touch events up, down or move. Forwards events to Harmony Service, Input System. • ADC Driver – Provides the 4-wire resistive touch interface. It is used to driver hardware pin configuration to sample and measure touch screen resistance. • Input system Service – Client level service which makes available touch events to the graphics library. Touch ADC Driver Abstraction Model. Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Touch ADC Driver module. Volume V: MPLAB Harmony Framework Driver Libraries Help Input System Service Touch Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 611 Library Interface Section Description System Functions Provides system interfaces, device initialization, deinitialization, open, close, task, and status functions. How the Library Works The library provides interfaces to support: • System functions, which provide system module interfaces, device initialization, deinitialization, open, close, and status functions. • Timer – rate at which to detect a new position Of note are the following routine, which are found in: /firmware/src/system_config//driver/input/touch_adc/src/drv_touch_adc.c: • DRV_TOUCH_ADC_Tasks() - sends a move, release, or press event to SYS_Input Services. It is called from system_tasks.c. • DRV_TOUCH_ADC_PositionDetect() – performs resistance measurements to determine x and y positions. • DRV_TOUCH_ADC_TouchGetX() – returns the x coordinate. • DRV_TOUCH_ADC_TouchGetY() – returns the y coordinate. • DRV_TOUCH_ADCCoefficientSet() – stores 4-translation calibrate coefficients Initializing the Driver Before the Touch ADC Driver can be opened, it must be configured and initialized. MHGC automatically includes the needed #define constants and source code into the project’s system_init.c file. The driver initialization is configured through the DRV_TOUCH_ADC_INIT data structure that is passed to the DRV_TOUCH_ADC_Initialize function. Opening the Driver To use the Touch ADC Driver, the application must open the driver. This is done by calling the DRV_TOUCH_ADC_Open function. If successful, the DRV_TOUCH_ADC_Open function will return a handle to the driver. This handle records the association between the client and the driver instance that was opened. The DRV_TOUCH_ADC_Open function may return DRV_HANDLE_INVALID in the situation where the driver is not ready to be opened. When this occurs, the application can try opening the driver again. Note that the open function may return an invalid handle in other (error) cases as well. The following code shows an example of the driver being opened. DRV_HANDLE handle; handle = DRV_TOUCH_ADC_Open( DRV_TOUCH_ADC_INDEX_0,DRV_IO_INTENT_EXCLUSIVE ); if( DRV_HANDLE_INVALID == handle ) { // Unable } Tasks Routine This routine communicates with the System Input Service on the state of the current X and Y positions detected. The routine checks 4 different conditions: 1. Invalid position – does not send an event upstream. 2. Same position – sends a still event to input system service 3. Move position – sends a move event to input system service. 4. Release condition – sends a release event to input system service 5. Press condition- sends a press event to input system service. Touch Detection This routine uses the services of the Touch ADC to establish a voltage divider on 4 ADC pins. The table below shows the pin configurations required to read the x and y values. The X value is read by a bias on x-axis and a measurement on ADC Y+ pin. The Y value is read by a bias on the y-axis and a measurement on ADC X+ pin. Operation X+ Pin Action Y+Pin Action X-GPIO Pin State Y-GPIO Pin State Get X Pin Output (set) Pin Input (Read X value) Pin Input Pin Output (clear) Get Y Pin Input (read Y value) Pin Output (set) Pin Output (clear) Pin Input Volume V: MPLAB Harmony Framework Driver Libraries Help Input System Service Touch Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 612 (Here "set" means SYS_PORTS_PinSet() and "clear" means SYS_PORTS_PinClear().) Configuring the Library The configuration of the Touch ADC Driver is performed using the MPLAB Harmony Configurator. Building the Library The section lists the files that are available in the Touch ADC Library. Description The section 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. The following tables list and describe the header (.h) and source (.c) files that implement this library. The parent folder for these files is /framework/driver/input/drv_touch_adc.h Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Note this file is automatically included in the project by MHGC. Source File Name /firmware/src/system_config//driver/input/touch_adc/drv_touch_adc.h Required File(s) All of the required files listed below 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 /firmware/src/system_config//driver/input/touch_adc/src/drv_touch_adc.c 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 N/A No optional files are available for this library. Module Dependencies The ADC Touch Driver Library depends on the following modules: • Interrupt System Service Library • Ports System Service Library • Input System Service Library • ADC Driver Library Library Interface Files Files Name Description drv_touch_adc.h Touch ADC Driver interface file. Volume V: MPLAB Harmony Framework Driver Libraries Help Input System Service Touch Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 613 Description drv_touch_adc.h Touch ADC Driver interface file. Description Touch ADC Driver Interface File This is a simple 4-wire resistive touch screen driver. The file consist of touch controller ADC driver interfaces. It implements the driver interfaces which read the touch input data from display overlay through the ADC peripheral. Remarks This driver is based on the MPLAB Harmony ADC driver. File Name drv_touch_adc.c Input System Service mXT336T Touch Driver Library This topic describes the mXT336T Touch Driver Library that supports theInput System Service. The library provides an interface to manage the mXT336T Touch Driver module on the Microchip family of microcontrollers in different modes of operation. It supports the Input System Service as a client by providing touch events detected by the maXTouch® mXT336T Capacitive Touch Controller. Description The MPLAB Harmony mXT336T Touch Driver provides a high-level interface to the mXT336T Capacitive Touch Controller. This driver provides application routines to read the touch input data from the touch screen. Currently, the mXT336T Touch Driver supports non-gestural single-fingered and gestural two-finger touch inputs. The mXT336T Capacitive Touch Controller notifies the host of the availability of touch input data through an external interrupt on the host. The mXT336T driver allows the application to map a controller pin as the external interrupt pin used by the mXT336T. The driver contains the standard MPLAB Harmony driver interfaces including: initialization, destruction, status, tasks, open, close, and interrupt-driven read. The driver contains no direct access to input events. All driver output is directed towards the MPLAB Harmony Input System Service and applications desiring to listen to input events must register with that service. The aria_quickstart demonstration interfaces with the mXT336T Touch Driver Library. Please refer to the What is MPLAB Harmony? section in Volume I of MPLAB Harmony’s built-in documentation for how the driver interacts with the framework. Using the Library This topic describes the basis architecture of the mXT336T Touch Driver Library that supports the Input System Service and provides information and examples on its use. Description Interface Header File: ./framework/driver/input/touch/mxt336t/drv_mxt336t.h The interface to the mXT336T Touch Driver library is defined in the drv_mxt336t.h header file. Any C language source (.c) file that uses the mXT336T Touch Driver library should include this header. The mXT336T Touch Driver is based on the Object Protocol for the maXTouch® mXT336T Touchscreen Controller. The aria_quickstart demonstration interfaces with the mXT336T Touch Driver Library. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the mXT336T Touch Driver Library on the Microchip family microcontrollers. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The mXT336T Touch Driver has routines to perform the following operations: • Sending read request Volume V: MPLAB Harmony Framework Driver Libraries Help Input System Service Touch Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 614 • Reading the touch input data • Access to the touch input data The driver initialization routines allow the application to initialize the driver. The driver must be initialized before it can be used by application. Once the touch input is available (by the assertion of the external interrupt input to the host) a touch input read request is sent to the mXT336t and input data is retrieved in a buffer. The buffer data is then decoded to get the x and y coordinate of the touch screen in the form of the number of pixels. After touch event data has been received it is propagated to the Input System Service which then distributes it to all interested parts of the application. mXT336T Driver Abstraction Model Library Overview This section contains information about how the Touch Driver operates in a system. Description The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the mXT336T Touch Driver. Library Interface Section Description Device-Specific Functions Provides mXT336T-specific system module interfaces, device initialization, deinitialization, open, close, task, and status functions. Generic Functions Provides generic system module interfaces, device initialization, deinitialization, open, close, task, and status functions. How the Library Works This section describes the workings of this Touch Driver library. Volume V: MPLAB Harmony Framework Driver Libraries Help Input System Service Touch Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 615 Description The library provides interfaces to support: • System functions, which provide system module interfaces, device initialization, deinitialization, open, close, task, and status functions. • Read Request function, which provides Touch input data read request function. Initializing the Driver Before the mXT336T Touch Driver can be opened, it must be configured and initialized. The driver build time configuration is defined by the configuration macros. Refer to the Building the Library section for the location of and more information on the various configuration macros and how these macros should be designed. The driver initialization is configured through the DRV_MXT336T_INIT data structure that is passed to the DRV_MXT336T_Initialize function. The initialization parameters include the interrupt source, interrupt pin remap configuration and touch screen resolution. The following code shows an example of initializing the mXT336T Touch Driver. Example: /* The following code shows an example of designing the * DRV_TOUCH_INIT data structure. It also shows how an example * usage of the DRV_TOUCH_MXT336T_Initialize function. */ This entire example section can be replaced with: const DRV_MXT336T_INIT drvMXT336TInitData = { .drvOpen = DRV_I2C_Open, .orientation = 0, .horizontalResolution = 480, .verticalResolution = 272, }; sysObj.drvMXT336T = DRV_MXT336T_Initialize(0, (SYS_MODULE_INIT *)&drvMXT336TInitData); Touch Input Read Request To read the touch input from the mXT336T touch controller device, a read request must be registered. This is done by calling DRV_MXT336T_ReadRequest. If successful, it registers a buffer read request to the I2C command queue. It also adds an input decode command to the mXT336T command queue once the I2C returns with touch input data. It can return error if the driver instance object is invalid or the mXT336T command queue is full. The read request is to be called from the mXT336T ISR. This ISR is triggered once the touch input is available. The following code shows an example of a mXT336T read request registration: SYS_MODULE_OBJ object; // Returned from DRV_TOUCH_MXT336T_Initialize void ISR(_EXTERNAL_INT_VECTOR, ipl5) _IntHandlerDrvMxt336t(void) { DRV__MXT336T_ReadRequest ( object ); // Do Other Tasks . . . } Tasks Routine This routine processes the mXT336T commands from the command queue. If the state of the command is initialize or done it returns. If the read request registration is successful the state of command is to decode input. The tasks routine decodes the input and updates the global variables storing the touch input data in form of x and y coordinates. The mXT336T Touch Driver task routine is to be called from SYS_Tasks. The following code shows an example: SYS_MODULE_OBJ drvMXT336T; SYS_MODULE_OBJ drvMxt0;; // Returned from DRV_TOUCH_MXT336T_Initialize void SYS_Tasks( void ) { DRV_MXT336T_Tasks(sysObj.drvMXT336T); DRV_MXT_Tasks(sysObj.drvMxt0); // Do other tasks } Volume V: MPLAB Harmony Framework Driver Libraries Help Input System Service Touch Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 616 Configuring in MPLAB Harmony Configurator The graphics demo aria_quickstart has several target configurations that provide examples of driver setup. Any configuration ending in meb2 or _meb2_wvga can be used. The MPLAB Harmony Configurator Pin Settings tab should be configured to select the correct pin for the external interrupt. For example, pic32mk_gp_db: 91 RF6 5V MXT336T_TOUCH_INT GPIO_CN pic32mz_da_sk_extddr: A14 RB1 - MXT336T_TOUCH_INT INT4 pic32mz_da_sk_intddr, pic32mz_da_noddr: B9 RB1 - MXT336T_TOUCH_INT INT4 pic32mz_ef_sk: 23 RE8 - MXT336T_TOUCH_INT INT1 Library Interface Files Files Name Description drv_input_mxt336t.h Touch controller MXT336T Driver interface header file. Description drv_input_mxt336t.h Touch controller MXT336T Driver interface header file. Description Touch Controller MXT336T Driver Interface File This header file describes the macros, data structure and prototypes of the touch controller MXT336T driver interface. File Name drv_MXT336T.c MIIM Driver Library This section describes the MII Management (MIIM) Driver Library. Introduction The MIIM Driver library provides access to the MII Management interface (MIIM) of the Microchip PIC32 microcontrollers. Description The MIIM Driver is implemented as a driver object that provides APIs for: • Asynchronous read/write and scan operations for accessing the external PHY registers • Notification when MIIM operations have completed Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 617 • Driver status information • Possibility to query or abort an ongoing operation. Using the Library This topic describes the basic architecture of the MIIM Driver Library and provides information and examples about its use. Description Interface Header File: drv_miim.h The interface to the MIIM library is defined in the drv_miim.h header file. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the MIIM 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 MIIM driver clients access PHY registers using the MIIM Driver API. The driver abstracts out the hardware details of the MIIM interface and provides a PHY register access mechanism to the application. The MIIM Driver provides read, write, and scan access to the PHY registers, together with driver and operation status APIs. The driver schedules operations requested by multiple clients and performs them sequentially, informing the clients about the operations outcome. The user can poll for a certain operation status or can register callbacks to be notified of the completion of a scheduled operation. A scheduled operation can be aborted, if not yet started. MIIM Driver Abstraction Model Library Overview Refer to the Driver Library Overview section for information about how the driver operates in a system. Description The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the MIIM module. Library Interface Section Description Functions This section provides general interface routines. Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 618 Data Types and Constants This section provides various definitions describing this API. Configuring the Library This section contains related configuration macros. Macros Name Description DRV_MIIM_INDEX_0 MIIM driver index definitions. DRV_MIIM_INDEX_COUNT Number of valid MIIM driver indices. _DRV_MIIM_CONFIG_H This is macro _DRV_MIIM_CONFIG_H. DRV_MIIM_CLIENT_OP_PROTECTION Enables/Disables Client Operation Protection feature. DRV_MIIM_COMMANDS Enables/Disables MIIM commands feature. DRV_MIIM_INSTANCE_CLIENTS Selects the maximum number of clients. DRV_MIIM_INSTANCE_OPERATIONS Selects the maximum number of simultaneous operations for an instance. DRV_MIIM_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver. Description The configuration of the MIIM Driver is based on the file system_config.h. This header file contains the configuration selection for the MIIM Driver. Based on the selections made, the MIIM Driver may support the selected features. These configuration settings will apply to all instances of the MIIM Driver. 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. DRV_MIIM_INDEX_0 Macro MIIM driver index definitions. File drv_miim.h C #define DRV_MIIM_INDEX_0 0 Description MIIM Driver Module Index Numbers These constants provide the MIIM driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_MIIM_Initialize and DRV_MIIM_Open routines to identify the driver instance in use. DRV_MIIM_INDEX_COUNT Macro Number of valid MIIM driver indices. File drv_miim.h C #define DRV_MIIM_INDEX_COUNT 1 Description MIIM Driver Module Index Count This constant identifies the number of valid MIIM driver indices. Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 619 Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from part-specific header files defined as part of the peripheral libraries. _DRV_MIIM_CONFIG_H Macro File drv_miim_config.h C #define _DRV_MIIM_CONFIG_H Description This is macro _DRV_MIIM_CONFIG_H. DRV_MIIM_CLIENT_OP_PROTECTION Macro Enables/Disables Client Operation Protection feature. File drv_miim_config.h C #define DRV_MIIM_CLIENT_OP_PROTECTION 0 Description MIIM client Operation Protection Because of the recirculation of the operation handles and client handles the possibility exists that a misbehaved client inadvertently gets the results of a previous completed operations that now belongs to a different client. When this feature is enabled, extra protection is added for an operation handle to uniquely identify a client that has started the operation and extra check is done that operation belongs to the client that asks for the result. Remarks Set the value to 1 to enable, 0 to disable the feature. Enabling this feature requires a small overhead in code and data size. DRV_MIIM_COMMANDS Macro Enables/Disables MIIM commands feature. File drv_miim_config.h C #define DRV_MIIM_COMMANDS 0 Description MIIM PHY Commands Adds a MIIM command to the TCP/IP command menu allowing to read/write a PHY register. Remarks Set the value to 1 to enable, 0 to disable the feature. Currently the MIIM commands are integrated in the TCP/IP commands. To have the MIIM commands available the TCP/IP commands need to be enabled. DRV_MIIM_INSTANCE_CLIENTS Macro Selects the maximum number of clients. File drv_miim_config.h Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 620 C #define DRV_MIIM_INSTANCE_CLIENTS 2 Description MIIM number of clients This definition select the MIIM Maximum Number of Clients per instance. Remarks By default the 1st MIIM client is the DRV_ETHPHY. An extra client is allowed. DRV_MIIM_INSTANCE_OPERATIONS Macro Selects the maximum number of simultaneous operations for an instance. File drv_miim_config.h C #define DRV_MIIM_INSTANCE_OPERATIONS 4 Description MIIM instance operations This definition selects the maximum number of simultaneous operations that can be supported by this driver. Note that this represents operations for all clients Remarks None. DRV_MIIM_INSTANCES_NUMBER Macro Selects the maximum number of hardware instances that can be supported by the dynamic driver. File drv_miim_config.h C #define DRV_MIIM_INSTANCES_NUMBER 1 Description MIIM hardware instance configuration This definition selects the maximum number of hardware instances that can be supported by the dynamic driver. Usually set to 1. Remarks None. Building the Library This section lists the files that are available in the MIIM Driver Library. 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 /framework/driver/miim/. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_miim.h This is the MIIM Driver Library's interface header file. /config/drv_miim.config.h This file contains the configuration macros. Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 621 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 /src/dynamic/drv_miim.c This file contains the source code for the dynamic implementation of the MIIM Driver. 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 N/A No optional files are available for this library. Library Interface This section describes the Application Programming Interface (API) functions of the MIIM Driver Library. Refer to each section for a detailed description. a) Functions Name Description DRV_MIIM_ClientStatus Gets the current client-specific status the MIIM driver. DRV_MIIM_Close Closes an opened instance of the MIIM driver. DRV_MIIM_Deinitialize Deinitializes the specified instance of the MIIM driver module. DRV_MIIM_DeregisterCallback Deregisters an notification callback function for the client operations. DRV_MIIM_Initialize Initializes the MIIM driver. DRV_MIIM_Open Opens the specified MIIM driver instance and returns a handle to it. DRV_MIIM_OperationAbort Aborts a current client operation initiated by the MIIM driver. DRV_MIIM_OperationResult Gets the result of a client operation initiated by the MIIM driver. DRV_MIIM_Read Initiates a SMI/MIIM read transaction. DRV_MIIM_RegisterCallback Registers an notification callback function for the client operations. DRV_MIIM_Reinitialize Reinitializes the driver and refreshes any associated hardware settings. DRV_MIIM_Scan Initiates a SMI/MIIM scan (periodic read)transaction. DRV_MIIM_Setup Sets up a MIIM client. DRV_MIIM_Status Provides the current status of the MIIM driver module. DRV_MIIM_Tasks Maintains the driver's state machine. DRV_MIIM_Write Initiates a SMI/MIIM write transaction. b) Data Types and Constants Name Description DRV_MIIM_INIT Contains all the data necessary to initialize the MIIM device. DRV_MIIM_OBJECT_BASE Declaration of a MIIM base object. DRV_MIIM_CALLBACK_HANDLE Handle that identifies a client registration operation. DRV_MIIM_CLIENT_STATUS Defines the possible results of operations that can succeed or fail DRV_MIIM_OPERATION_CALLBACK Notification function that will be called when a MIIM operation is completed and the driver client needs to be notified. DRV_MIIM_OPERATION_FLAGS List of flags that apply to a client operation. DRV_MIIM_OPERATION_HANDLE MIIM operation handle. DRV_MIIM_SETUP Contains all the data necessary to set up the MIIM device. DRV_MIIM_SETUP_FLAGS List of flags that apply to a client setup operation. DRV_MIIM_OBJECT_BASE_Default The supported basic MIIM driver (DRV_MIIM_OBJECT_BASE). This object is implemented by default as using the standard MIIM interface. It can be overwritten dynamically when needed. Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 622 a) Functions DRV_MIIM_ClientStatus Function Gets the current client-specific status the MIIM driver. File drv_miim.h C DRV_MIIM_CLIENT_STATUS DRV_MIIM_ClientStatus(DRV_HANDLE handle); Returns • DRV_MIIM_CLIENT_STATUS_READY - if the client handle represents a valid MIIM client • DRV_MIIM_CLIENT_STATUS_ERROR - if the client handle is an invalid MIIM client Description This function gets the client-specific status of the MIIM driver associated with the given handle. Remarks This function can be used to check that a client handle points to a valid MIIM client. The MIIM driver queues operations so it will always return DRV_MIIM_CLIENT_STATUS_READY. Preconditions • The DRV_MIIM_Initialize routine must have been called. • DRV_MIIM_Open must have been called to obtain a valid opened device handle. Example Function DRV_MIIM_CLIENT_STATUS DRV_MIIM_ClientStatus(DRV_HANDLE handle ) DRV_MIIM_Close Function Closes an opened instance of the MIIM driver. File drv_miim.h C void DRV_MIIM_Close(DRV_HANDLE handle); Returns None Description This function closes an opened instance of the MIIM driver, invalidating the handle. Remarks • After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_MIIM_Open before the caller may use the driver again. • Usually there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_MIIM_Initialize routine must have been called for the specified MIIM driver instance. DRV_MIIM_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_MIIM_Open Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 623 DRV_MIIM_Close(handle); Function void DRV_MIIM_Close( DRV_HANDLE handle ) DRV_MIIM_Deinitialize Function Deinitializes the specified instance of the MIIM driver module. File drv_miim.h C void DRV_MIIM_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description This function deinitializes the specified instance of the MIIM driver module, disabling its operation (and any hardware)and invalidates all of the internal data. Remarks • Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. Preconditions The DRV_MIIM_Initialize function must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Example Function void DRV_MIIM_Deinitialize (SYS_MODULE_OBJ object ) DRV_MIIM_DeregisterCallback Function Deregisters an notification callback function for the client operations. File drv_miim.h C DRV_MIIM_RESULT DRV_MIIM_DeregisterCallback(DRV_HANDLE handle, DRV_MIIM_CALLBACK_HANDLE cbHandle); Returns • DRV_MIIM_RES_OK if the operation succeeded. • an error code otherwise Description This function deregisters a previously registered client notification callback function. Remarks There is only one notification callback function available per client. To register a new callback function use DRV_MIIM_DeregisterCallback first. Preconditions • The DRV_MIIM_Initialize routine must have been called. • DRV_MIIM_Open must have been called to obtain a valid opened device handle. Example Function DRV_MIIM_RESULT DRV_MIIM_DeregisterCallback( DRV_HANDLE handle, DRV_MIIM_CALLBACK_HANDLE cbHandle); Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 624 DRV_MIIM_Initialize Function Initializes the MIIM driver. File drv_miim.h C SYS_MODULE_OBJ DRV_MIIM_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns • a valid handle to a driver object, if successful. • SYS_MODULE_OBJ_INVALID if initialization failed. Description This function initializes the MIIM driver, making it ready for clients to open and use it. Remarks • This function must be called before any other MIIM routine is called. • This function should only be called once during system initialization unless DRV_MIIM_Deinitialize is called to deinitialize the driver instance. • The returned object must be passed as argument to DRV_MIIM_Reinitialize, DRV_MIIM_Deinitialize, DRV_MIIM_Tasks and DRV_MIIM_Status routines. Preconditions None. Example Function SYS_MODULE_OBJ DRV_MIIM_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ) DRV_MIIM_Open Function Opens the specified MIIM driver instance and returns a handle to it. File drv_miim.h C DRV_HANDLE DRV_MIIM_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); Returns • valid open-instance handle if successful (a number identifying both the caller and the module instance). • DRV_HANDLE_INVALID if an error occurs Description This function opens the specified MIIM driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Remarks The handle returned is valid until the DRV_MIIM_Close routine is called. This function will NEVER block waiting for hardware. Preconditions The DRV_MIIM_Initialize function must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_MIIM_Open(DRV_MIIM_INDEX_0, 0); if (DRV_HANDLE_INVALID == handle) Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 625 { // Unable to open the driver } Function DRV_HANDLE DRV_MIIM_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ) DRV_MIIM_OperationAbort Function Aborts a current client operation initiated by the MIIM driver. File drv_miim.h C DRV_MIIM_RESULT DRV_MIIM_OperationAbort(DRV_HANDLE handle, DRV_MIIM_OPERATION_HANDLE opHandle); Returns DRV_MIIM_RES_OK for success; operation has been aborted < 0 - an error has occurred and the operation could not be completed Description Aborts a current client operation initiated by the MIIM driver. Remarks This operation will stop/abort a scan operation started by DRV_MIIM_Scan. Preconditions • The DRV_MIIM_Initialize routine must have been called. • DRV_MIIM_Open must have been called to obtain a valid opened device handle. • A driver operation was started Example Function DRV_MIIM_RESULT DRV_MIIM_OperationAbort( DRV_HANDLE handle, DRV_MIIM_OPERATION_HANDLE opHandle) DRV_MIIM_OperationResult Function Gets the result of a client operation initiated by the MIIM driver. File drv_miim.h C DRV_MIIM_RESULT DRV_MIIM_OperationResult(DRV_HANDLE handle, DRV_MIIM_OPERATION_HANDLE opHandle, uint16_t* pOpData); Returns • DRV_MIIM_RESULT value describing the current operation result: DRV_MIIM_RES_OK for success; operation has been completed successfully and pOpData updated DRV_MIIM_RES_PENDING operation is in progress an DRV_MIIM_RESULT error code if the operation failed. Description Returns the result of a client operation initiated by the MIIM driver. Remarks This function will not block for hardware access and will immediately return the current status. This function returns the result of the last driver operation. It will return DRV_MIIM_RES_PENDING if an operation is still in progress. Otherwise a DRV_MIIM_RESULT describing the operation outcome. Note that for a scan operation DRV_MIIM_RES_PENDING will be returned when there's no new scan data available. DRV_MIIM_RES_OK means the scan data is fresh. Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 626 Preconditions • The DRV_MIIM_Initialize routine must have been called. • DRV_MIIM_Open must have been called to obtain a valid opened device handle. • A driver operation was started Example Function DRV_MIIM_RESULT DRV_MIIM_OperationResult( DRV_HANDLE handle, DRV_MIIM_OPERATION_HANDLE opHandle, uint16_t* pOpData) DRV_MIIM_Read Function Initiates a SMI/MIIM read transaction. File drv_miim.h C DRV_MIIM_OPERATION_HANDLE DRV_MIIM_Read(DRV_HANDLE handle, unsigned int rIx, unsigned int phyAdd, DRV_MIIM_OPERATION_FLAGS opFlags, DRV_MIIM_RESULT* pOpResult); Returns A not NULL DRV_MIIM_OPERATION_HANDLE if the operation was successfully scheduled. NULL if the operation failed. More details in pOpResult. Description This function initiates a SMI/MIIM read transaction for a given MIIM register. Remarks If operation was scheduled successfully, the result will be DRV_MIIM_RES_PENDING. Otherwise an error code will be returned. Upon the operation completion: • If the operation is to be discarded (DRV_MIIM_OPERATION_FLAG_DISCARD is set) there will be no notification to the client. The operation associated resources will be released. • If the operation is not to be discarded, then: • if the client has registered an operation notification callback (DRV_MIIM_RegisterCallback) then the callback will be called. After that the operation associated resources will be released. • if there is no notification callback the MIIM driver will wait for the client to poll and read the operation result using DRV_MIIM_OperationResult(). Only then the operation will be released. A completed non-discardable operation will remain available for returning the result until the client is somehow notified of the operation result. When polling is used, DRV_MIIM_OperationResult() needs to be called to free the operation associated resources. Preconditions • The DRV_MIIM_Initialize routine must have been called. • DRV_MIIM_Open must have been called to obtain a valid opened device handle. Example Function DRV_MIIM_OPERATION_HANDLE DRV_MIIM_Read(DRV_HANDLE handle, unsigned int rIx, unsigned int phyAdd, DRV_MIIM_OPERATION_FLAGS opFlags, DRV_MIIM_RESULT* pOpResult); DRV_MIIM_RegisterCallback Function Registers an notification callback function for the client operations. File drv_miim.h Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 627 C DRV_MIIM_CALLBACK_HANDLE DRV_MIIM_RegisterCallback(DRV_HANDLE handle, DRV_MIIM_OPERATION_CALLBACK cbFunction, DRV_MIIM_RESULT* pRegResult); Returns • a valid DRV_MIIM_CALLBACK_HANDLE if the operation succeeded. • NULL otherwise Description This function registers a client callback function. The function will be called by the MIIM driver when a scheduled operation is completed. Remarks There is only one notification callback function available per client. To register a new callback function use DRV_MIIM_DeregisterCallback first. Preconditions • The DRV_MIIM_Initialize routine must have been called. • DRV_MIIM_Open must have been called to obtain a valid opened device handle. Example Function DRV_MIIM_CALLBACK_HANDLE DRV_MIIM_RegisterCallback(DRV_HANDLE handle, DRV_MIIM_OPERATION_CALLBACK cbFunction, DRV_MIIM_RESULT* pRegResult); DRV_MIIM_Reinitialize Function Reinitializes the driver and refreshes any associated hardware settings. File drv_miim.h C void DRV_MIIM_Reinitialize(SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init); Returns None. Description This function reinitializes the driver and refreshes any associated hardware settings using the initialization data given, but it will not interrupt any ongoing operations. Remarks • This function can be called multiple times to reinitialize the module. • This operation can be used to refresh any supported hardware registers as specified by the initialization data or to change the power state of the module. • This function is currently NOT IMPLEMENTED. Preconditions The DRV_MIIM_Initialize function must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Example Function void DRV_MIIM_Reinitialize(SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init ) DRV_MIIM_Scan Function Initiates a SMI/MIIM scan (periodic read)transaction. Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 628 File drv_miim.h C DRV_MIIM_OPERATION_HANDLE DRV_MIIM_Scan(DRV_HANDLE handle, unsigned int rIx, unsigned int phyAdd, DRV_MIIM_OPERATION_FLAGS opFlags, DRV_MIIM_RESULT* pOpResult); Returns A not NULL DRV_MIIM_OPERATION_HANDLE if the operation was successfully scheduled. NULL if the operation failed. More details in pOpResult. Description This function initiates a SMI/MIIM scan transaction for a given MIIM register. Remarks If operation was scheduled successfully, the result will be DRV_MIIM_RES_PENDING. Otherwise an error code will be returned. When a new scan result is available: • If the operation is to be discarded (DRV_MIIM_OPERATION_FLAG_DISCARD is set) there will be no notification to the client. • If the operation is not to be discarded, then: • if the client has registered an operation notification callback (DRV_MIIM_RegisterCallback) then the notification callback will be called. • if there is no notification callback the MIIM driver will wait for the client to poll and read the operation result using DRV_MIIM_OperationResult(). Only then the operation will be released. A scheduled scan operation will remain active in the background and will be available for returning the scan results. When polling is used, DRV_MIIM_OperationResult()will return the latest scan result. The operation associated resources will be released and scan stopped only when DRV_MIIM_OperationAbort() is called. While scan is active all other transactions (including from other clients) will be inhibited! Use carefully! Preconditions • The DRV_MIIM_Initialize routine must have been called. • DRV_MIIM_Open must have been called to obtain a valid opened device handle. Example Function DRV_MIIM_OPERATION_HANDLE DRV_MIIM_Scan(DRV_HANDLE handle, unsigned int rIx, unsigned int phyAdd, DRV_MIIM_OPERATION_FLAGS opFlags, DRV_MIIM_RESULT* pOpResult); DRV_MIIM_Setup Function Sets up a MIIM client. File drv_miim.h C DRV_MIIM_RESULT DRV_MIIM_Setup(DRV_HANDLE handle, const DRV_MIIM_SETUP* pSetUp); Returns • DRV_MIIM_RES_OK if the setup operation has been performed successfully • an DRV_MIIM_RESULT error code if the set up procedure failed. Description This function performs the set up of a MIIM client. It programs the MIIM operation using the supplied frequencies. Remarks None. Preconditions • The DRV_MIIM_Initialize routine must have been called. Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 629 • DRV_MIIM_Open must have been called to obtain a valid device handle. Example Function DRV_MIIM_RESULT DRV_MIIM_Setup( DRV_HANDLE handle, const DRV_MIIM_SETUP* pSetUp) DRV_MIIM_Status Function Provides the current status of the MIIM driver module. File drv_miim.h C SYS_STATUS DRV_MIIM_Status(SYS_MODULE_OBJ object); Returns • SYS_STATUS_READY - Indicates that any previous module operation for the specified module has completed • SYS_STATUS_BUSY - Indicates that a previous module operation for the specified module has not yet completed • SYS_STATUS_ERROR - Indicates that the specified module is in an error state Description This function provides the current status of the MIIM driver module. Remarks • Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. • SYS_STATUS_BUSY - Indicates that the driver is busy with a previous system level operation and cannot start another • SYS_STATUS_ERROR - Indicates that the driver is in an error state • Any value less than SYS_STATUS_ERROR is also an error state. • SYS_MODULE_DEINITIALIZED - Indicates that the driver has been deinitialized • If the status operation returns SYS_STATUS_BUSY, the a previous system level operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. • The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. • This function will NEVER block waiting for hardware. • If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Preconditions The DRV_MIIM_Initialize function must have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_MIIM_Initialize SYS_STATUS status; status = DRV_MIIM_Status(object); if (SYS_STATUS_ERROR >= status) { // Handle error } Parameters Parameters Description object Driver object handle, returned from DRV_MIIM_Initialize Function SYS_STATUS DRV_MIIM_Status (SYS_MODULE_OBJ object ) Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 630 DRV_MIIM_Tasks Function Maintains the driver's state machine. File drv_miim.h C void DRV_MIIM_Tasks(SYS_MODULE_OBJ object); Returns None Description This function is used to maintain the driver's internal state machine. Remarks • This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) • This function will never block or access any resources that may cause it to block. Preconditions The DRV_MIIM_Initialize routine must have been called for the specified MIIM driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_MIIM_Initialize while (true) { DRV_MIIM_Tasks (object); // Do other tasks } Function void DRV_MIIM_Tasks(SYS_MODULE_OBJ object ) DRV_MIIM_Write Function Initiates a SMI/MIIM write transaction. File drv_miim.h C DRV_MIIM_OPERATION_HANDLE DRV_MIIM_Write(DRV_HANDLE handle, unsigned int rIx, unsigned int phyAdd, uint16_t wData, DRV_MIIM_OPERATION_FLAGS opFlags, DRV_MIIM_RESULT* pOpResult); Returns A not NULL DRV_MIIM_OPERATION_HANDLE if the operation was successfully scheduled. NULL if the operation failed. More details in pOpResult. Description This function initiates a SMI/MIIM write transaction for a given MIIM register. Remarks If operation was scheduled successfully, the result will be DRV_MIIM_RES_PENDING. Otherwise an error code will be returned. Upon the operation completion: • If the operation is to be discarded (DRV_MIIM_OPERATION_FLAG_DISCARD is set) there will be no notification to the client. The operation associated resources will be released. • If the operation is not to be discarded, then: Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 631 • if the client has registered an operation notification callback (DRV_MIIM_RegisterCallback) then the notification callback will be called. After that the operation associated resources will be released. • if there is no notification callback the MIIM driver will wait for the client to poll and read the operation result using DRV_MIIM_OperationResult(). Only then the operation will be released. A completed non-discardable operation will remain available for returning the result until the client is somehow notified of the operation result. When polling is used, DRV_MIIM_OperationResult() needs to be called to free the operation associated resources. A write operation normally uses DRV_MIIM_OPERATION_FLAG_DISCARD if it is not interested when the operation has completed. Preconditions • The DRV_MIIM_Initialize routine must have been called. • DRV_MIIM_Open must have been called to obtain a valid opened device handle. Example Function DRV_MIIM_OPERATION_HANDLE DRV_MIIM_Write(DRV_HANDLE handle, unsigned int rIx, unsigned int phyAdd, uint16_t wData, DRV_MIIM_OPERATION_FLAGS opFlags, DRV_MIIM_RESULT* pOpResult); b) Data Types and Constants DRV_MIIM_INIT Structure Contains all the data necessary to initialize the MIIM device. File drv_miim.h C struct DRV_MIIM_INIT { SYS_MODULE_INIT moduleInit; uintptr_t ethphyId; }; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization uintptr_t ethphyId; Identifies peripheral (PLIB-level) ID Description MIIM Device Driver Initialization Data This data structure contains all the data necessary to initialize the MIIM device. Remarks A pointer to a structure of this format containing the desired initialization data must be passed into the DRV_MIIM_Initialize routine. DRV_MIIM_OBJECT_BASE Structure Declaration of a MIIM base object. File drv_miim.h C struct DRV_MIIM_OBJECT_BASE { SYS_MODULE_OBJ (* DRV_MIIM_Initialize)(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); void (* DRV_MIIM_Reinitialize)(SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init); void (* DRV_MIIM_Deinitialize)(SYS_MODULE_OBJ object); SYS_STATUS (* DRV_MIIM_Status)(SYS_MODULE_OBJ object); void (* DRV_MIIM_Tasks)(SYS_MODULE_OBJ object); DRV_HANDLE (* DRV_MIIM_Open)(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); DRV_MIIM_RESULT (* DRV_MIIM_Setup)(DRV_HANDLE handle, const DRV_MIIM_SETUP* pSetUp); void (* DRV_MIIM_Close)(DRV_HANDLE handle); Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 632 DRV_MIIM_CLIENT_STATUS (* DRV_MIIM_ClientStatus)(DRV_HANDLE handle); DRV_MIIM_CALLBACK_HANDLE (* DRV_MIIM_RegisterCallback)(DRV_HANDLE handle, DRV_MIIM_OPERATION_CALLBACK cbFunction, DRV_MIIM_RESULT* pRegResult); DRV_MIIM_RESULT (* DRV_MIIM_DeregisterCallback)(DRV_HANDLE handle, DRV_MIIM_CALLBACK_HANDLE cbHandle); DRV_MIIM_OPERATION_HANDLE (* DRV_MIIM_Read)(DRV_HANDLE handle, unsigned int rIx, unsigned int phyAdd, DRV_MIIM_OPERATION_FLAGS opFlags, DRV_MIIM_RESULT* pOpResult); DRV_MIIM_OPERATION_HANDLE (* DRV_MIIM_Write)(DRV_HANDLE handle, unsigned int rIx, unsigned int phyAdd, uint16_t wData, DRV_MIIM_OPERATION_FLAGS opFlags, DRV_MIIM_RESULT* pOpResult); DRV_MIIM_OPERATION_HANDLE (* DRV_MIIM_Scan)(DRV_HANDLE handle, unsigned int rIx, unsigned int phyAdd, DRV_MIIM_OPERATION_FLAGS opFlags, DRV_MIIM_RESULT* pOpResult); DRV_MIIM_RESULT (* DRV_MIIM_OperationResult)(DRV_HANDLE handle, DRV_MIIM_OPERATION_HANDLE opHandle, uint16_t* pOpData); DRV_MIIM_RESULT (* DRV_MIIM_OperationAbort)(DRV_HANDLE handle, DRV_MIIM_OPERATION_HANDLE opHandle); }; Description MIIM Driver Base Object This data structure identifies the required basic interface of the MIIM driver. Any dynamic MIIM driver has to export this interface. Remarks This object provides the basic MIIM functionality. Any derived driver can override the basic functionality while maintaining the required interface. DRV_MIIM_CALLBACK_HANDLE Type Handle that identifies a client registration operation. File drv_miim.h C typedef const void* DRV_MIIM_CALLBACK_HANDLE; Description Type: MIIM Callback Registration handle A handle that a client obtains when calling DRV_MIIM_RegisterCallback. It can be used to deregister the notification callback: DRV_MIIM_DeregisterCallback Remarks A valid registration handle is not NULL. An invalid registration handle == 0. DRV_MIIM_CLIENT_STATUS Enumeration Defines the possible results of operations that can succeed or fail File drv_miim.h C typedef enum { DRV_MIIM_CLIENT_STATUS_ERROR, DRV_MIIM_CLIENT_STATUS_READY } DRV_MIIM_CLIENT_STATUS; Members Members Description DRV_MIIM_CLIENT_STATUS_ERROR Unspecified error condition. Client does not exist DRV_MIIM_CLIENT_STATUS_READY Up and running, can accept operations Description MIIM Driver Operation Result * MIIM Driver Operation Result Codes This enumeration defines the possible results of any of the MIIM driver operations that have the possibility of failing. This result should be checked to ensure that the operation achieved the desired result. Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 633 DRV_MIIM_OPERATION_CALLBACK Type Notification function that will be called when a MIIM operation is completed and the driver client needs to be notified. File drv_miim.h C typedef void (* DRV_MIIM_OPERATION_CALLBACK)(DRV_HANDLE cliHandle, DRV_MIIM_OPERATION_HANDLE opHandle, DRV_MIIM_RESULT opResult, uint16_t opData); Description Type: MIIM Driver Operation Complete Callback The format of an operation callback notification function registered with the MIIM driver. Remarks None. Parameters Parameters Description cliHandle the client handle. This is the handle that identifies the client (obtained with DRV_MIIM_Open) that initiated the operation. opHandle the operation handle. This is the handle that identifies the operation (obtained with DRV_MIIM_Read, DRV_MIIM_Write, etc.) opResult operation result DRV_MIIM_RES_OK if operation completed successfully, otherwise an error code opData operation specific data, only if the result is DRV_MIIM_RES_OK For read/scan operation this is the MIIM read data. For write operation this is that data that was written with MIIM. DRV_MIIM_OPERATION_FLAGS Enumeration List of flags that apply to a client operation. File drv_miim.h C typedef enum { DRV_MIIM_OPERATION_FLAG_NONE, DRV_MIIM_OPERATION_FLAG_DISCARD } DRV_MIIM_OPERATION_FLAGS; Members Members Description DRV_MIIM_OPERATION_FLAG_NONE No flag specified DRV_MIIM_OPERATION_FLAG_DISCARD Upon completion discard the operation result. The client will not poll to check the result nor will need notification This allows dummy operations, discarded as they complete Description MIIM Driver Operation flags This enumeration identifies the operation-specific flags supported by the MIIM driver. Remarks Currently only 8 bit flags are supported. Multiple flags can be simultaneously set. DRV_MIIM_OPERATION_HANDLE Type MIIM operation handle. Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 634 File drv_miim.h C typedef const void* DRV_MIIM_OPERATION_HANDLE; Description Type: DRV_MIIM_OPERATION_HANDLE A handle that identifies an operation started by a client. This handle can be used by the client to query the operation status, result, etc. It is also used when the operation complete notification occurs. Remarks A valid operation handle is not NULL. An invalid operation handle == 0. DRV_MIIM_SETUP Structure Contains all the data necessary to set up the MIIM device. File drv_miim.h C typedef struct { uint32_t hostClockFreq; uint32_t maxBusFreq; DRV_MIIM_SETUP_FLAGS setupFlags; } DRV_MIIM_SETUP; Members Members Description uint32_t hostClockFreq; The clock frequency on which this MIIM module operates on, Hz uint32_t maxBusFreq; The MIIM bus maximum supported frequency, Hz This is a maximum value. The actual generated value may differ. DRV_MIIM_SETUP_FLAGS setupFlags; Setup flags Description MIIM Device Driver Set up Data This data structure contains all the data necessary to configure the MIIM device. Remarks A pointer to a structure of this format containing the desired initialization data must be passed into the DRV_MIIM_Setup routine. DRV_MIIM_SETUP_FLAGS Enumeration List of flags that apply to a client setup operation. File drv_miim.h C typedef enum { DRV_MIIM_SETUP_FLAG_NONE, DRV_MIIM_SETUP_FLAG_PREAMBLE_SUPPRESSED, DRV_MIIM_SETUP_FLAG_PREAMBLE_DEFAULT, DRV_MIIM_SETUP_FLAG_SCAN_ADDRESS_INCREMENT, DRV_MIIM_SETUP_FLAG_SCAN_ADDRESS_DEFAULT } DRV_MIIM_SETUP_FLAGS; Members Members Description DRV_MIIM_SETUP_FLAG_NONE No flag specified. Default value Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 635 DRV_MIIM_SETUP_FLAG_PREAMBLE_SUPPRESSED Suppress the normal 32 bit MIIM preamble field. Some PHYs support suppressed preamble DRV_MIIM_SETUP_FLAG_PREAMBLE_DEFAULT Include the 32 bit MIIM preamble field. Default operation. DRV_MIIM_SETUP_FLAG_SCAN_ADDRESS_INCREMENT Scan operation will read across a range of PHY addresses Scan will start with address 1 through the address set in the scan operation DRV_MIIM_SETUP_FLAG_SCAN_ADDRESS_DEFAULT Scan operation will read just one PHY address. Default operation. Description MIIM Driver Set up flags This enumeration identifies the setup specific flags supported by the MIIM driver. Remarks Multiple flags can be simultaneously set. DRV_MIIM_OBJECT_BASE_Default Variable File drv_miim.h C const DRV_MIIM_OBJECT_BASE DRV_MIIM_OBJECT_BASE_Default; Description The supported basic MIIM driver (DRV_MIIM_OBJECT_BASE). This object is implemented by default as using the standard MIIM interface. It can be overwritten dynamically when needed. Files Files Name Description drv_miim.h MIIM Device Driver Interface File drv_miim_config.h MIIM driver configuration definitions template. Description This section lists the source and header files used by the Media Interface Independent Management (MIIM)Driver Library. drv_miim.h MIIM Device Driver Interface File Enumerations Name Description DRV_MIIM_CLIENT_STATUS Defines the possible results of operations that can succeed or fail DRV_MIIM_OPERATION_FLAGS List of flags that apply to a client operation. DRV_MIIM_SETUP_FLAGS List of flags that apply to a client setup operation. Functions Name Description DRV_MIIM_ClientStatus Gets the current client-specific status the MIIM driver. DRV_MIIM_Close Closes an opened instance of the MIIM driver. DRV_MIIM_Deinitialize Deinitializes the specified instance of the MIIM driver module. DRV_MIIM_DeregisterCallback Deregisters an notification callback function for the client operations. DRV_MIIM_Initialize Initializes the MIIM driver. DRV_MIIM_Open Opens the specified MIIM driver instance and returns a handle to it. DRV_MIIM_OperationAbort Aborts a current client operation initiated by the MIIM driver. DRV_MIIM_OperationResult Gets the result of a client operation initiated by the MIIM driver. DRV_MIIM_Read Initiates a SMI/MIIM read transaction. Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 636 DRV_MIIM_RegisterCallback Registers an notification callback function for the client operations. DRV_MIIM_Reinitialize Reinitializes the driver and refreshes any associated hardware settings. DRV_MIIM_Scan Initiates a SMI/MIIM scan (periodic read)transaction. DRV_MIIM_Setup Sets up a MIIM client. DRV_MIIM_Status Provides the current status of the MIIM driver module. DRV_MIIM_Tasks Maintains the driver's state machine. DRV_MIIM_Write Initiates a SMI/MIIM write transaction. Macros Name Description DRV_MIIM_INDEX_0 MIIM driver index definitions. DRV_MIIM_INDEX_COUNT Number of valid MIIM driver indices. Structures Name Description DRV_MIIM_INIT Contains all the data necessary to initialize the MIIM device. DRV_MIIM_OBJECT_BASE Declaration of a MIIM base object. DRV_MIIM_SETUP Contains all the data necessary to set up the MIIM device. Types Name Description DRV_MIIM_CALLBACK_HANDLE Handle that identifies a client registration operation. DRV_MIIM_OPERATION_CALLBACK Notification function that will be called when a MIIM operation is completed and the driver client needs to be notified. DRV_MIIM_OPERATION_HANDLE MIIM operation handle. Variables Name Description DRV_MIIM_OBJECT_BASE_Default The supported basic MIIM driver (DRV_MIIM_OBJECT_BASE). This object is implemented by default as using the standard MIIM interface. It can be overwritten dynamically when needed. Description MIIM Device Driver Interface The MIIM device driver provides a simple interface to manage an MIIM peripheral using MIIM (SMI)interface. This file defines the interface definitions and prototypes for the MIIM driver. File Name drv_miim.h Company Microchip Technology Inc. drv_miim_config.h MIIM driver configuration definitions template. Macros Name Description _DRV_MIIM_CONFIG_H This is macro _DRV_MIIM_CONFIG_H. DRV_MIIM_CLIENT_OP_PROTECTION Enables/Disables Client Operation Protection feature. DRV_MIIM_COMMANDS Enables/Disables MIIM commands feature. DRV_MIIM_INSTANCE_CLIENTS Selects the maximum number of clients. DRV_MIIM_INSTANCE_OPERATIONS Selects the maximum number of simultaneous operations for an instance. DRV_MIIM_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver. Volume V: MPLAB Harmony Framework Driver Libraries Help MIIM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 637 Description MIIM Driver Configuration Definitions for the Template Version These definitions statically define the driver's mode of operation. File Name drv_miim_config.h Company Microchip Technology Inc. Motor Control PWM (MCPWM) Driver Library This section describes the MCPWM Driver Library. Introduction The MCPWM Static Driver provides a high-level interface to manage the MCPWM module on the Microchip family of microcontrollers. Description Through MHC, this driver provides APIs to initialize, enable, and disable the MCPWM module. Library Interface Function(s) Name Description DRV_MCPWM_Disable Disables the MCPWM instance for the specified driver index. Implementation: Static DRV_MCPWM_Enable Enables the MCPWM instance for the specified driver index. Implementation: Static DRV_MCPWM_Initialize Initializes the MCPWM instance for the specified driver index. Implementation: Static Description This section describes the Application Programming Interface (API) functions of the MCPWM Driver Library. Function(s) DRV_MCPWM_Disable Function Disables the MCPWM instance for the specified driver index. Implementation: Static File drv_mcpwm.h C void DRV_MCPWM_Disable(); Returns None. Description This routine disables the MCPWM Driver instance for the specified driver instance. Preconditions DRV_MCPWM_Initialize has been called. Volume V: MPLAB Harmony Framework Driver Libraries Help Motor Control PWM (MCPWM) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 638 Function void DRV_MCPWM_Disable(void) DRV_MCPWM_Enable Function Enables the MCPWM instance for the specified driver index. Implementation: Static File drv_mcpwm.h C void DRV_MCPWM_Enable(); Returns None. Description This routine enables the MCPWM Driver instance for the specified driver instance, making it ready for clients to use it. The enable routine is specified by the MHC parameters. Preconditions DRV_MCPWM_Initialize has been called. Function void DRV_MCPWM_Enable(void) DRV_MCPWM_Initialize Function Initializes the MCPWM instance for the specified driver index. Implementation: Static File drv_mcpwm.h C void DRV_MCPWM_Initialize(); Returns None. Description This routine initializes the MCPWM Driver instance for the specified driver instance, making it ready for clients to use it. The initialization routine is specified by the MHC parameters. Remarks This routine must be called before any other MCPWM routine is called. This routine should only be called once during system initialization. Preconditions None. Function void DRV_MCPWM_Initialize(void) Files Files Name Description drv_mcpwm.h MCPWM driver interface declarations for the static single instance driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Motor Control PWM (MCPWM) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 639 Description drv_mcpwm.h MCPWM driver interface declarations for the static single instance driver. Functions Name Description DRV_MCPWM_Disable Disables the MCPWM instance for the specified driver index. Implementation: Static DRV_MCPWM_Enable Enables the MCPWM instance for the specified driver index. Implementation: Static DRV_MCPWM_Initialize Initializes the MCPWM instance for the specified driver index. Implementation: Static Description Motor Control PWM (MCPWM) Driver Interface Declarations for Static Single Instance Driver The MCPWM device driver provides a simple interface to manage the MCPWM module on Microchip microcontrollers. This file defines the interface Declarations for the MCPWM driver. Remarks Static interfaces incorporate the driver instance number within the names of the routines, eliminating the need for an object ID or object handle. Static single-open interfaces also eliminate the need for the open handle. File Name drv_mcpwm.h Company Microchip Technology Inc. NVM Driver Library This section describes the Non-volatile Memory (NVM) Driver Library. Migrating Applications from v1.03.01 and Earlier Releases of MPLAB Harmony Provides information on migrating applications from v1.03.01 and earlier releases of MPLAB Harmony to release v1.04 and later. Description The NVM Driver Library APIs have changed beginning with the v1.04 release of MPLAB Harmony. Applications that were developed using the earlier version of the MPLAB Harmony NVM Driver (v1.03.01 and earlier) will not build unless the application calls to NVM Driver are updated. While the MHC utility provides an option to continue creating applications using the v1.03.01 and earlier NVM Driver API, it is recommended that existing applications migrate to the latest API to take advantage of the latest features in the NVM Driver. The following sections describe the API changes and other considerations while updating the application for changes in the NVM Driver. All NVM Driver Demonstration Applications and NVM Driver related documentation have been updated to the latest (new) API. The following sections do not discuss changes in the NVM Driver configuration related code. This code is updated automatically when the project is regenerated using the MHC utility. Only the application related API changes are discussed. The following table shows the beta API and corresponding v1.04 and Later MPLAB Harmony NVM Driver API. v1.03.01 and Earlier NVM Driver API v1.04 and Later NVM Driver API v1.04 and Later API Notes DRV_NVM_Initialize DRV_NVM_Initialize The init structure now has additional members that allow the NVM media address and geometry to be specified. DRV_NVM_Deinitialize DRV_NVM_Deinitialize No change. DRV_NVM_Status DRV_NVM_Status No change. DRV_NVM_Open DRV_NVM_Open No change. DRV_NVM_Close DRV_NVM_Close No change. Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 640 DRV_NVM_Read DRV_NVM_Read Parameters have changed: • Returns the command handle associated with the read operation as an output parameter • Data is now read in terms of blocks. The read block size is specified in the NVM Geometry. DRV_NVM_Write DRV_NVM_Write Parameters have changed: • Returns the command handle associated with the write operation as an output parameter • Data is now written in terms of blocks. The write block size is specified in the NVM Geometry. DRV_NVM_Erase DRV_NVM_Erase Parameters have changed: • Returns the command handle associated with the erase operation as an output parameter • NVM Flash is erased in terms of blocks. The erase block size is specified in the NVM Geometry. DRV_NVM_EraseWrite DRV_NVM_EraseWrite Parameters have changed: • Returns the command handle associated with the Erase/Write operation as an output parameter. • Data is now written in terms of blocks. The write block size is specified in the NVM Geometry. DRV_NVM_BlockEventHandlerSet DRV_NVM_EventHandlerSet Function name and parameter type have changed. DRV_NVM_ClientStatus Not Available This API is no longer available. DRV_NVM_BufferStatus DRV_NVM_CommandStatus The DRV_NVM_Read, DRV_NVM_Write, DRV_NVM_Erase, and DRV_NVM_EraseWrite functions now return a command handle associated with the operation. The status of the operation can be checked by passing the command handle to this function. Not Available DRV_NVM_GeometryGet This API gives the following geometrical details of the NVM Flash: • Media Property • Number of Read/Write/Erase regions in the flash device • Number of Blocks and their size in each region of the device Not Available DRV_NVM_IsAttached Returns the physical attach status of the NVM Flash. Not Available DRV_NVM_IsWriteProtected Returns the write protect status of the NVM Flash. Not Available DRV_NVM_AddressGet Returns the NVM Media Start address. NVM Driver Initialization DRV_NVM_INIT now takes the following two additional initialization parameters: • mediaStartAddress - NVM Media Start address. The driver treats this address as the start address for read, write and erase operations. • nvmMediaGeometry - Indicates the layout of the media in terms of read, write and erase regions. The following code examples show how the driver initialization was performed with 1.03 APIs and how it is performed with the 1.04 APIs: Example 1: v1.03 and Earlier Code const DRV_NVM_INIT drvNvmInit = { .moduleInit.sys.powerState = SYS_MODULE_POWER_RUN_FULL, .nvmID = NVM_ID_0, .interruptSource = INT_SOURCE_FLASH_CONTROL, }; void SYS_Initialize (void *data) { . . // Initialize NVM Driver Layer sysObj.drvNvm = DRV_NVM_Initialize(DRV_NVM_INDEX_0, (SYS_MODULE_INIT *)&drvNvmInit); . } Example: v1.04 and Later Code /* NVM Geometry structure */ SYS_FS_MEDIA_REGION_GEOMETRY NVMGeometryTable[3] = { { .blockSize = 1, Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 641 .numBlocks = (DRV_NVM_MEDIA_SIZE * 1024), }, { .blockSize = DRV_NVM_ROW_SIZE, .numBlocks = ((DRV_NVM_MEDIA_SIZE * 1024)/DRV_NVM_ROW_SIZE) }, { .blockSize = DRV_NVM_PAGE_SIZE, .numBlocks = ((DRV_NVM_MEDIA_SIZE * 1024)/DRV_NVM_PAGE_SIZE) } }; const SYS_FS_MEDIA_GEOMETRY NVMGeometry = { .mediaProperty = SYS_FS_MEDIA_WRITE_IS_BLOCKING, .numReadRegions = 1, .numWriteRegions = 1, .numEraseRegions = 1, .geometryTable = (SYS_FS_MEDIA_REGION_GEOMETRY *)&NVMGeometryTable }; const DRV_NVM_INIT drvNvmInit = { .moduleInit.sys.powerState = SYS_MODULE_POWER_RUN_FULL, .nvmID = NVM_ID_0, .interruptSource = INT_SOURCE_FLASH_CONTROL, .mediaStartAddress = 0x9D010000, .nvmMediaGeometry = (SYS_FS_MEDIA_GEOMETRY *)&NVMGeometry }; void SYS_Initialize (void *data) { . . // Initialize NVM Driver Layer sysObj.drvNvm = DRV_NVM_Initialize(DRV_NVM_INDEX_0, (SYS_MODULE_INIT *)&drvNvmInit); . . } Addressing in NVM Driver The v1.03.01 and earlier Read, Write, Erase and EraseWrite APIs took the actual address on which the operation was to be performed. The unit of access was bytes. In v1.04 the addressing mechanism has been modified. The media start address is set in the DRV_NVM_Initialize. This address is used as the base address for the Read, Write, Erase and EraseWrite APIs. The unit of access is in terms of blocks. The NVM Geometry specifies the media layout in terms of: • Number of erase, read and write regions • Block size for erase, read and write operations. • Number of blocks in erase, read and write regions For example, in PIC32MZ family devices: • Read block size = 1 byte • Write block size = ROW Size = 2048 bytes • Erase block size = PAGE Size = 16384 bytes If the size of media is 32 KB then the following table illustrates the address range and number of blocks for the read, write and erase regions: Region Type Block Size Number of blocks Address range Read Region 1 Byte 32 KB / Read block size = 32768 0–32767 Write Region 2048 Bytes 32 KB / Write block size = 16 blocks 0–15 Erase Region 16384 Bytes 32 KB / Erase block size = 2 blocks 0–1 Erasing Data on NVM Flash The NVM Geometry indicates the number of erase blocks and the size of a single erase block. The Erase API takes in the erase block start address and the number of blocks to be erased. The following code examples show how to perform the erase operation in v1.03.01 and earlier and how to perform it with v1.04 and later. Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 642 Example: v1.03.01 and Earlier Code DRV_HANDLE myNVMHandle; // Returned from DRV_NVM_Open DRV_NVM_BUFFER_HANDLE bufferHandle; bufferHandle = DRV_NVM_Erase(myNVMHandle, (uint8_t*)NVM_BASE_ADDRESS, DRV_NVM_PAGE_SIZE); if(DRV_NVM_BUFFER_HANDLE_INVALID == bufferHandle) { // Do error handling here } // Wait until the buffer completes. This should not // be a while loop if a part of cooperative multi-tasking // routine. In that case, it should be invoked in task // state machine. while(DRV_NVM_BufferStatus(bufferHandle) != DRV_NVM_BUFFER_COMPLETED); Example: v1.04 and Later Code /* This code example shows how to erase NVM Media data */ DRV_HANDLE nvmHandle; DRV_NVM_COMMAND_HANDLE nvmCommandHandle; DRV_NVM_COMMAND_STATUS commandStatus; uint32_t blockAddress; uint32_t nBlocks; blockAddress = 0; nBlocks = 1; DRV_NVM_Erase(nvmHandle, &nvmCommandHandle, blockAddress, nBlocks); if(DRV_NVM_COMMAND_HANDLE_INVALID == nvmCommandHandle) { /* Failed to queue the erase request. Handle the error. */ } // Wait until the command completes. This should not // be a while loop if a part of cooperative multi-tasking // routine. In that case, it should be invoked in task // state machine. commandStatus = DRV_NVM_CommandStatus(nvmHandle, nvmCommandHandle); if(DRV_NVM_COMMAND_COMPLETED == commandStatus) { /* Erase completed */ } else if (DRV_NVM_COMMAND_ERROR_UNKNOWN == commandStatus) { /* Erase Failed */ } Writing Data to NVM Flash The NVM Geometry indicates the number of write blocks and the size of a single write block. The Write API takes in the write block start address and the number of blocks to be written. The following code examples show how the write operation was performed in v1.03.01 and earlier and how to perform it with v1.04 and later APIs: Example : v1.03.01 and Earlier Code DRV_HANDLE myNVMHandle; // Returned from DRV_NVM_Open char myBuffer[2 * DRV_NVM_ROW_SIZE]; // Destination address should be row aligned. char *destAddress = (char *)NVM_BASE_ADDRESS_TO_WRITE; unsigned int count = 2 * MY_BUFFER_SIZE; DRV_NVM_BUFFER_HANDLE bufferHandle; bufferHandle = DRV_NVM_Write(myNVMHandle, destAddress, &myBuffer[total], count); if(DRV_NVM_BUFFER_HANDLE_INVALID == bufferHandle) { // Do error handling here } // Wait until the buffer completes. This should not // be a while loop if a part of cooperative multi-tasking Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 643 // routine. In that case, it should be invoked in task // state machine. while(DRV_NVM_BufferStatus(bufferHandle) != DRV_NVM_BUFFER_COMPLETED); Example: v1.04 and Later Code /* This code example shows how to write data to NVM Media */ DRV_HANDLE nvmHandle; DRV_NVM_COMMAND_HANDLE nvmCommandHandle; DRV_NVM_COMMAND_STATUS commandStatus; uint8_t writeBuf[DRV_NVM_ROW_SIZE]; uint32_t blockAddress; uint32_t nBlocks; blockAddress = 0; nBlocks = 1; DRV_NVM_Write(nvmHandle, &nvmCommandHandle, (uint8_t *)writeBuf, blockAddress, nBlocks); if(DRV_NVM_COMMAND_HANDLE_INVALID == nvmCommandHandle) { /* Failed to queue the write request. Handle the error. */ } // Wait until the command completes. This should not // be a while loop if a part of cooperative multi-tasking // routine. In that case, it should be invoked in task // state machine. commandStatus = DRV_NVM_CommandStatus(nvmHandle, nvmCommandHandle); if(DRV_NVM_COMMAND_COMPLETED == commandStatus) { /* Write completed */ } else if (DRV_NVM_COMMAND_ERROR_UNKNOWN == commandStatus) { /* Write Failed */ } Reading Data from NVM Flash The NVM Geometry indicates the number of read blocks and the size of a single read block. The Read API takes in the read block start address and the number of blocks to be read. The following code examples show how the read operation was performed with v1.03.01 and earlier APIs and how to perform the same with v1.04 and later APIs: Example: v1.03.01 and Earlier Code DRV_HANDLE myNVMHandle; // Returned from DRV_NVM_Open char myBuffer[MY_BUFFER_SIZE]; char *srcAddress = NVM_BASE_ADDRESS_TO_READ_FROM; unsigned int count = MY_BUFFER_SIZE; DRV_NVM_BUFFER_HANDLE bufferHandle; bufferHandle = DRV_NVM_Read(myNVMHandle, &myBuffer[total], srcAddress, count); if(DRV_NVM_BUFFER_HANDLE_INVALID == bufferHandle) { // Do error handling here } // Wait until the buffer completes. This should not // be a while loop if a part of cooperative multi-tasking // routine. In that case, it should be invoked in task // state machine. while(DRV_NVM_BufferStatus(bufferHandle) != DRV_NVM_BUFFER_COMPLETED); Example: v1.04 and Later Code /* This code example shows how to read data from NVM Media */ DRV_HANDLE nvmHandle; DRV_NVM_COMMAND_HANDLE nvmCommandHandle; DRV_NVM_COMMAND_STATUS commandStatus; uint8_t readBuf[DRV_NVM_ROW_SIZE]; uint32_t blockAddress; uint32_t nBlocks; blockAddress = 0; Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 644 nBlocks = DRV_NVM_ROW_SIZE; DRV_NVM_Read(nvmHandle, &nvmCommandHandle, (uint8_t *)readBuf, blockAddress, nBlocks); if(DRV_NVM_COMMAND_HANDLE_INVALID == nvmCommandHandle) { /* Failed to queue the read request. Handle the error. */ } // Wait until the command completes. This should not // be a while loop if a part of cooperative multi-tasking // routine. In that case, it should be invoked in task // state machine. commandStatus = DRV_NVM_CommandStatus(nvmHandle, nvmCommandHandle); if(DRV_NVM_COMMAND_COMPLETED == commandStatus) { /* Read completed */ } else if (DRV_NVM_COMMAND_ERROR_UNKNOWN == commandStatus) { /* Read Failed */ } Introduction The NVM Driver library provides APIs that can be used to interface with the NVM module (controller plus memory) for memory needs. Description The NVM Driver provides APIs for block access of the physical media through NVM Driver APIs. As shown in the NVM Driver Abstraction Model, an application or a client can access the physical media using multiple methods, which eventually are facilitated through the NVM Driver. Memory Devices for PIC Microcontrollers Depending on the device, there are two primary forms of on-chip memory: Programmable Flash memory and data EEPROM memory. The access mechanism for both of these types are varied. 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, restricting memory access, and therefore preventing code execution. This is controlled by an internal programming timer. There are three processor dependant methods for program memory modification: • Run-Time Self-Programming (RTSP) • In-Circuit Serial Programming (ICSP) • EJTAG programming This section describes the RTSP techniques. Using the Library This topic describes the basic architecture of the NVM Driver Library and provides information and examples on its use. Description Interface Header Files: drv_nvm.h The interface to the NVM Driver Library is defined in the drv_nvm.h header file. Any C language source (.c) file that uses the NVM Driver library should include drv_nvm.h. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. 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. Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 645 Description NVM Driver Abstraction Model Abstraction Model As shown in the previous diagram, the NVM Driver sits between the Peripheral Libraries and the application or system layer to facilitate block and file access to the NVM media (currently Flash). The application scenarios show how different layers can be accessed by different applications with certain needs. For example, APP1 can access the NVM Driver directly to erase, write, or read NVM with direct addressing. APP2, in this case TCP/IP, can bypass the system layer and access the NVM Driver layer if necessary to fulfill its robust data needs. Finally, APP3 accesses the NVM Driver through the File System Layer using block access methods, so the application does not need to keep track of the physical layout of the media. Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. 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 System Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Client Core Functions Provides open, close, status and other setup functions. Client Block Transfer Functions Provides buffered data operation functions available in the core configuration. Miscellaneous Functions Provides driver miscellaneous functions related to versions and others. How the Library Works The library provides interfaces to support: • System Functionality • Client Functionality • Media Functionality Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 646 Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the modes supported for your device. NVM System Initialization This section provides information for system initialization and reinitialization. Description The system performs the initialization and the reinitialization of the device driver with settings that affect only the instance of the device that is being initialized or reinitialized. During system initialization each instance of the NVM module would be initialized with the following configuration settings (either passed dynamically at run time using DRV_NVM_INIT or by using initialization overrides) that are supported by the specific NVM device hardware: • Device requested power state: One of the system module power states. For specific details please refer to Data Types and Constants in the Library Interface section. • The actual peripheral ID enumerated as the PLIB level module ID (e.g., NVM_ID_0) • Defining the respective interrupt sources • NVM Media Start Address • NVM Media Geometry The DRV_NVM_Initialize function returns an object handle of the type SYS_MODULE_OBJ. After this, the object handle returned by the initialize interface would be used by the other system interfaces, such as DRV_NVM_Deinitialize, DRV_NVM_Status, and DRV_NVM_Tasks. Note: The system initialization and the reinitialization settings, only affect the instance of the peripheral that is being initialized or reinitialized. The SYS_MODULE_INDEX is passed to the DRV_NVM_Initialize function to determine which type of memory is selected using: DRV_NVM_INDEX_0 - FLASH Example: const DRV_NVM_INIT drvNvmInit = { .moduleInit.sys.powerState = SYS_MODULE_POWER_RUN_FULL, .nvmID = NVM_ID_0, .interruptSource = INT_SOURCE_FLASH_CONTROL, .mediaStartAddress = 0x9D010000, .nvmMediaGeometry = (SYS_FS_MEDIA_GEOMETRY *)&NVMGeometry }; void SYS_Initialize (void *data) { . . . // Initialize NVM Driver Layer sysObj.drvNvm = DRV_NVM_Initialize(DRV_NVM_INDEX_0, (SYS_MODULE_INIT *)&drvNvmInit); . . . } Tasks Routine The system will call DRV_NVM_Tasks, from system task service (in a polled environment) or DRV_NVM_Tasks will be called from the Interrupt Service Routine (ISR) of the NVM. Client Access Operation This section provides information for general client operation. Description General Client Operation For the application to start using an instance of the module, it must call the DRV_NVM_Open function. This provides the configuration required to open the NVM instance for operation. If the driver is deinitialized using the function DRV_NVM_Deinitialize, the application must call the DRV_NVM_Open function again to set up the instance of the NVM. For the various options available for I/O INTENT please refer to Data Types and Constants in the Library Interface section. Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 647 Example: DRV_HANDLE handle; handle = DRV_NVM_Open(DRV_NVM_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } Client Block Data Operation This topic provides information on client block data operation. Description The NVM Driver provides a block interface to access the NVM media. The interface provides functionality to read, write, erase, and erase-write the NVM media. These interface functions depend on the block sizes and boundaries of the individual devices. The interfaces are responsible for keeping this information transparent from the application. Erasing Data on the NVM: The following steps outline the sequence for erasing data on the NVM media: 1. The system should have completed necessary initialization and DRV_NVM_Tasks should either be running in a polled environment, or in an interrupt environment. 2. The driver should have been opened with the necessary intent. 3. Provide the block start address and the number of blocks to be erased and begin the erase process using the DRV_NVM_Erase. 4. The client can check the state of the erase request by invoking the DRV_NVM_CommandStatus and passing the command handle returned by the erase request. 5. The client will be able to close itself by calling the DRV_NVM_Close. Example: // This code shows how to erase NVM Media data DRV_HANDLE nvmHandle; DRV_NVM_COMMAND_HANDLE nvmCommandHandle; DRV_NVM_COMMAND_STATUS commandStatus; uint32_t blockAddress; uint32_t nBlocks; blockAddress = 0; nBlocks = 1; DRV_NVM_Erase(nvmHandle, &nvmCommandHandle, blockAddress, nBlocks); if(DRV_NVM_COMMAND_HANDLE_INVALID == nvmCommandHandle) { /* Failed to queue the erase request. Handle the error. */ } // Wait until the command completes. This should not // be a while loop if a part of cooperative multi-tasking // routine. In that case, it should be invoked in task // state machine. commandStatus = DRV_NVM_CommandStatus(nvmHandle, nvmCommandHandle); if(DRV_NVM_COMMAND_COMPLETED == commandStatus) { /* Erase completed */ } else if (DRV_NVM_COMMAND_ERROR_UNKNOWN == commandStatus) { /* Erase Failed */ } Writing Data to the NVM: The following steps outline the sequence to be followed for writing data to the NVM Media: 1. The system should have completed necessary initialization and DRV_NVM_Tasks should either be running in a polled environment, or in an interrupt environment. Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 648 2. The driver should have been opened with the necessary intent. 3. The client should ensure that blocks of addresses to which write is being performed should be in the erased state. 4. Provide the data to be written, block start address and the number of blocks to be written and begin write using the DRV_NVM_Write. 5. The client can check the state of the write request by invoking the DRV_NVM_CommandStatus and passing the command handle returned by the write request. 6. The client will be able to close itself by calling the DRV_NVM_Close. Example: // This code shows how to write data to NVM Media DRV_HANDLE nvmHandle; DRV_NVM_COMMAND_HANDLE nvmCommandHandle; DRV_NVM_COMMAND_STATUS commandStatus; uint8_t writeBuf[DRV_NVM_ROW_SIZE]; uint32_t blockAddress; uint32_t nBlocks; blockAddress = 0; nBlocks = 1; DRV_NVM_Write(nvmHandle, &nvmCommandHandle, (uint8_t *)writeBuf, blockAddress, nBlocks); if(DRV_NVM_COMMAND_HANDLE_INVALID == nvmCommandHandle) { /* Failed to queue the write request. Handle the error. */ } // Wait until the command completes. This should not // be a while loop if a part of cooperative multi-tasking // routine. In that case, it should be invoked in task // state machine. commandStatus = DRV_NVM_CommandStatus(nvmHandle, nvmCommandHandle); if(DRV_NVM_COMMAND_COMPLETED == commandStatus) { /* Write completed */ } else if (DRV_NVM_COMMAND_ERROR_UNKNOWN == commandStatus) { /* Write Failed */ } Reading Data from the NVM: The following steps outline the sequence to be followed for reading data from the NVM Media: 1. The system should have completed necessary initialization and DRV_NVM_Tasks should either be running in a polled environment, or in an interrupt environment. 2. The driver should have been opened with the necessary intent. 3. Provide the target buffer, block start address and the number of blocks to be read and begin reading using the DRV_NVM_Read. 4. The client can check the state of the read request by invoking the DRV_NVM_CommandStatus and passing the command handle returned by the read request. 5. The client will be able to close itself by calling the DRV_NVM_Close. Example: // This code shows how to read data from NVM Media DRV_HANDLE nvmHandle; DRV_NVM_COMMAND_HANDLE nvmCommandHandle; DRV_NVM_COMMAND_STATUS commandStatus; uint8_t readBuf[DRV_NVM_ROW_SIZE]; uint32_t blockAddress; uint32_t nBlocks; blockAddress = 0; nBlocks = DRV_NVM_ROW_SIZE; DRV_NVM_Read(nvmHandle, &nvmCommandHandle, (uint8_t *)readBuf, blockAddress, nBlocks); Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 649 if(DRV_NVM_COMMAND_HANDLE_INVALID == nvmCommandHandle) { /* Failed to queue the read request. Handle the error. */ } // Wait until the command completes. This should not // be a while loop if a part of cooperative multi-tasking // routine. In that case, it should be invoked in task // state machine. commandStatus = DRV_NVM_CommandStatus(nvmHandle, nvmCommandHandle); if(DRV_NVM_COMMAND_COMPLETED == commandStatus) { /* Read completed */ } else if (DRV_NVM_COMMAND_ERROR_UNKNOWN == commandStatus) { /* Read Failed */ } Configuring the Library Macros Name Description DRV_NVM_BUFFER_OBJECT_NUMBER Selects the maximum number of buffer objects DRV_NVM_CLIENTS_NUMBER Selects the maximum number of clients DRV_NVM_INSTANCES_NUMBER Selects the maximum number of Driver instances that can be supported by the dynamic driver. DRV_NVM_INTERRUPT_MODE Macro specifies operation of the driver to be in the interrupt mode or polled mode DRV_NVM_ROW_SIZE Specifies the NVM Driver Program Row Size in bytes. DRV_NVM_ERASE_WRITE_ENABLE Enables support for NVM Driver Erase Write Feature. DRV_NVM_PAGE_SIZE Specifies the NVM Driver Program Page Size in bytes. DRV_NVM_DISABLE_ERROR_CHECK Disables the error checks in the driver. DRV_NVM_MEDIA_SIZE Specifies the NVM Media size. DRV_NVM_MEDIA_START_ADDRESS Specifies the NVM Media start address. DRV_NVM_SYS_FS_REGISTER Register to use with the File system Description The configuration of the NVM Driver is based on the file system_config.h. This header file contains the configuration selection for the NVM Driver. Based on the selections made, the NVM Driver may support the selected features. These configuration settings will apply to all instances of the NVM Driver. 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. DRV_NVM_BUFFER_OBJECT_NUMBER Macro Selects the maximum number of buffer objects File drv_nvm_config_template.h C #define DRV_NVM_BUFFER_OBJECT_NUMBER 5 Description NVM Driver maximum number of buffer objects This definition selects the maximum number of buffer objects. This indirectly also specifies the queue depth. The NVM Driver can queue up DRV_NVM_BUFFER_OBJECT_NUMBER of read/write/erase requests before return a DRV_NVM_BUFFER_HANDLE_INVALID due to the queue being full. Buffer objects are shared by all instances of the driver. Increasing this number increases the RAM requirement of the driver. Remarks This macro is mandatory when building the driver for dynamic operation. Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 650 DRV_NVM_CLIENTS_NUMBER Macro Selects the maximum number of clients File drv_nvm_config_template.h C #define DRV_NVM_CLIENTS_NUMBER 1 Description NVM maximum number of clients This definition selects the maximum number of clients that the NVM driver can supported at run time. This constant defines the total number of NVM driver clients that will be available to all instances of the NVM driver. Remarks This macro is mandatory when building the driver for dynamic operation. DRV_NVM_INSTANCES_NUMBER Macro Selects the maximum number of Driver instances that can be supported by the dynamic driver. File drv_nvm_config_template.h C #define DRV_NVM_INSTANCES_NUMBER 1 Description NVM Driver instance configuration This definition selects the maximum number of Driver instances that can be supported by the dynamic driver. In case of this driver, multiple instances of the driver could use the same hardware instance. Remarks This macro is mandatory when building the driver for dynamic operation. DRV_NVM_INTERRUPT_MODE Macro Macro specifies operation of the driver to be in the interrupt mode or polled mode File drv_nvm_config_template.h C #define DRV_NVM_INTERRUPT_MODE true Description NVM interrupt and polled mode operation control This macro specifies operation of the driver to be in the interrupt mode or polled mode • true - Select if interrupt mode of NVM operation is desired • false - Select if polling mode of NVM operation is desired Not defining this option to true or false will result in build error. Remarks This macro is mandatory when building the driver for dynamic operation. DRV_NVM_ROW_SIZE Macro Specifies the NVM Driver Program Row Size in bytes. Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 651 File drv_nvm.h C #define DRV_NVM_ROW_SIZE (NVM_ROW_SIZE) Description NVM Driver Program Row Size. This definition specifies the NVM Driver Program Row Size in bytes. This parameter is device specific and is obtained from the device specific processor header file. The Program Row Size is the minimum block size that can be programmed in one program operation. Remarks None DRV_NVM_ERASE_WRITE_ENABLE Macro Enables support for NVM Driver Erase Write Feature. File drv_nvm_config_template.h C #define DRV_NVM_ERASE_WRITE_ENABLE Description NVM Driver Erase Write Feature Enable Specifying this macro enable row erase write feature. If this macro is specified, the drv_nvm_erasewrite.c file should be added in the project. Support for DRV_NVM_EraseWrite() function then gets enabled. Remarks This macro is optional and should be specified only if the DRV_NVM_EraseWrite() function is required. DRV_NVM_PAGE_SIZE Macro Specifies the NVM Driver Program Page Size in bytes. File drv_nvm.h C #define DRV_NVM_PAGE_SIZE (NVM_PAGE_SIZE) Description NVM Driver Program Page Size. This definition specifies the NVM Driver Program Page Size in bytes. This parameter is device specific and is obtained from the device specific processor header file. Remarks None DRV_NVM_DISABLE_ERROR_CHECK Macro Disables the error checks in the driver. File drv_nvm_config_template.h C #define DRV_NVM_DISABLE_ERROR_CHECK Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 652 Description NVM Driver Disable Error Checks Specifying this macro disables the error checks in the driver. Error checks like parameter validation, NULL checks etc, will be disabled in the driver in order to optimize the code space. Remarks This macro is optional and should be specified only if code space is a constraint. DRV_NVM_MEDIA_SIZE Macro Specifies the NVM Media size. File drv_nvm_config_template.h C #define DRV_NVM_MEDIA_SIZE 32 Description NVM Media Size This definition specifies the NVM Media Size to be used. The size is specified in number of Kilo Bytes. The media size MUST never exceed physical available NVM Memory size. Application code requirements should be kept in mind while defining this parameter. Remarks This macro is mandatory when building the driver for dynamic operation. DRV_NVM_MEDIA_START_ADDRESS Macro Specifies the NVM Media start address. File drv_nvm_config_template.h C #define DRV_NVM_MEDIA_START_ADDRESS 0x9D010000 Description NVM Media Start Address This definition specifies the NVM Media Start address parameter. Remarks This macro is mandatory when building the driver for dynamic operation. DRV_NVM_SYS_FS_REGISTER Macro Register to use with the File system File drv_nvm_config_template.h C #define DRV_NVM_SYS_FS_REGISTER Description NVM Driver Register with File System Specifying this macro enables the NVM driver to register its services with the SYS FS. Remarks This macro is optional and should be specified only if the NVM driver is to be used with the File System. Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 653 Building the Library This section lists the files that are available in the NVM Driver Library. Description 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. 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 /framework/driver/nvm. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_nvm.h Header file that exports the driver API. 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 /src/dynamic/drv_nvm.c /src/dynamic/drv_nvm_erasewrite.c Dynamic NVM Driver implementation file. Dynamic NVM Driver Erase/Write implementation file. /src/static/drv_nvm_static.c Static NVM Driver implementation file for single clients. /src/static_multi/drv_nvm_static_multi.c Static NVM Driver implementation file for multiple clients. 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 N/A No optional files are available for this library. Module Dependencies The NVM Driver Library depends on the following modules: • Interrupt System Service Library • Ports System Service Library Library Interface a) System Functions Name Description DRV_NVM_Initialize Initializes the NVM instance for the specified driver index Implementation: Static/Dynamic DRV_NVM_Deinitialize Deinitializes the specified instance of the NVM driver module Implementation: Static/Dynamic DRV_NVM_Status Gets the current status of the NVM driver module. Implementation: Static/Dynamic b) Client Core Functions Name Description DRV_NVM_Open Opens the specified NVM driver instance and returns a handle to it Implementation: Static/Dynamic DRV_NVM_Close Closes an opened-instance of the NVM driver Implementation: Static/Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 654 DRV_NVM_Read Reads blocks of data from the specified address in memory. Implementation: Static/Dynamic DRV_NVM_Write Writes blocks of data starting from the specified address in flash memory. Implementation: Static/Dynamic DRV_NVM_Erase Erase the specified number of blocks of the Flash memory. Implementation: Static/Dynamic DRV_NVM_EraseWrite Erase and Write blocks of data starting from a specified address in flash memory. Implementation: Static/Dynamic DRV_NVM_EventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. Implementation: Static/Dynamic c) Client Block Data Functions Name Description DRV_NVM_Tasks Maintains the driver's erase and write state machine and implements its ISR. Implementation: Static/Dynamic d) Status Functions Name Description DRV_NVM_AddressGet Returns the NVM media start address Implementation: Static/Dynamic DRV_NVM_CommandStatus Gets the current status of the command. Implementation: Static/Dynamic DRV_NVM_GeometryGet Returns the geometry of the device. Implementation: Static/Dynamic e) Miscellaneous Functions Name Description DRV_NVM_IsAttached Returns the physical attach status of the NVM. Implementation: Static/Dynamic DRV_NVM_IsWriteProtected Returns the write protect status of the NVM. Implementation: Static/Dynamic f) Data Types and Constants Name Description DRV_NVM_INDEX_0 NVM driver index definitions DRV_NVM_INIT Defines the data required to initialize or reinitialize the NVM driver DRV_NVM_INDEX_1 This is macro DRV_NVM_INDEX_1. DRV_NVM_EVENT Identifies the possible events that can result from a request. DRV_NVM_EVENT_HANDLER Pointer to a NVM Driver Event handler function DRV_NVM_COMMAND_HANDLE Handle identifying commands queued in the driver. DRV_NVM_COMMAND_STATUS Specifies the status of the command for the read, write and erase operations. DRV_NVM_COMMAND_HANDLE_INVALID This value defines the NVM Driver's Invalid Command Handle. Description This section describes the Application Programming Interface (API) functions of the NVM Driver Library. Refer to each section for a detailed description. a) System Functions DRV_NVM_Initialize Function Initializes the NVM instance for the specified driver index Implementation: Static/Dynamic File drv_nvm.h Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 655 C SYS_MODULE_OBJ DRV_NVM_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise it returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the NVM driver instance for the specified driver index, making it ready for clients to open and use it. Remarks This routine must be called before any other NVM routine is called. This routine should only be called once during system initialization unless DRV_NVM_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. If the operation requires time to allow the hardware to reinitialize, it will be reported by the DRV_NVM_Status operation. The system must use DRV_NVM_Status to find out when the driver is in the ready state. Build configuration options may be used to statically override options in the "init" structure and will take precedence over initialization data passed using this routine. Preconditions None. Example // This code snippet shows an example // of initializing the NVM Driver. SYS_MODULE_OBJ objectHandle; SYS_FS_MEDIA_REGION_GEOMETRY gNvmGeometryTable[3] = { { // Read Region Geometry .blockSize = 1, .numBlocks = (DRV_NVM_MEDIA_SIZE * 1024), }, { // Write Region Geometry .blockSize = DRV_NVM_ROW_SIZE, .numBlocks = ((DRV_NVM_MEDIA_SIZE * 1024)/DRV_NVM_ROW_SIZE) }, { // Erase Region Geometry .blockSize = DRV_NVM_PAGE_SIZE, .numBlocks = ((DRV_NVM_MEDIA_SIZE * 1024)/DRV_NVM_PAGE_SIZE) } }; const SYS_FS_MEDIA_GEOMETRY gNvmGeometry = { .mediaProperty = SYS_FS_MEDIA_WRITE_IS_BLOCKING, // Number of read, write and erase entries in the table .numReadRegions = 1, .numWriteRegions = 1, .numEraseRegions = 1, .geometryTable = &gNvmGeometryTable }; // FLASH Driver Initialization Data const DRV_NVM_INIT drvNvmInit = { .moduleInit.sys.powerState = SYS_MODULE_POWER_RUN_FULL, .nvmID = NVM_ID_0, .interruptSource = INT_SOURCE_FLASH_CONTROL, .mediaStartAddress = NVM_BASE_ADDRESS, .nvmMediaGeometry = &gNvmGeometry }; Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 656 //usage of DRV_NVM_INDEX_0 indicates usage of Flash-related APIs objectHandle = DRV_NVM_Initialize(DRV_NVM_INDEX_0, (SYS_MODULE_INIT*)&drvNVMInit); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized also the type of memory used init Pointer to a data structure containing any data necessary to initialize the driver. Function SYS_MODULE_OBJ DRV_NVM_Initialize ( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); DRV_NVM_Deinitialize Function Deinitializes the specified instance of the NVM driver module Implementation: Static/Dynamic File drv_nvm.h C void DRV_NVM_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the NVM driver module, disabling its operation (and any hardware). Invalidates all the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. Preconditions Function DRV_NVM_Initialize should have been called before calling this function. Parameter: object - Driver object handle, returned from the DRV_NVM_Initialize routine Example // This code snippet shows an example // of deinitializing the driver. SYS_MODULE_OBJ object; // Returned from DRV_NVM_Initialize SYS_STATUS status; DRV_NVM_Deinitialize(object); status = DRV_NVM_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Function void DRV_NVM_Deinitialize ( Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 657 SYS_MODULE_OBJ object ); DRV_NVM_Status Function Gets the current status of the NVM driver module. Implementation: Static/Dynamic File drv_nvm.h C SYS_STATUS DRV_NVM_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is ready and accept requests for new operations. SYS_STATUS_UNINITIALIZED - Indicates the driver is not initialized. Description This routine provides the current status of the NVM driver module. Remarks This routine will NEVER block waiting for hardware. Preconditions Function DRV_NVM_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_NVM_Initialize SYS_STATUS NVMStatus; NVMStatus = DRV_NVM_Status(object); else if (SYS_STATUS_ERROR >= NVMStatus) { // Handle error } Parameters Parameters Description object Driver object handle, returned from the DRV_NVM_Initialize routine Function SYS_STATUS DRV_NVM_Status ( SYS_MODULE_OBJ object ); b) Client Core Functions DRV_NVM_Open Function Opens the specified NVM driver instance and returns a handle to it Implementation: Static/Dynamic File drv_nvm.h C DRV_HANDLE DRV_NVM_Open(const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent); Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 658 Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, DRV_HANDLE_INVALID is returned. Errors can occur under the following circumstances: • if the number of client objects allocated via DRV_NVM_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the client is trying to open the driver exclusively, but has already been opened in a non exclusive mode by another client. • if the driver hardware instance being opened is not initialized or is invalid Description This routine opens the specified NVM driver instance and provides a handle. This handle must be provided to all other client-level operations to identify the caller and the instance of the driver. Remarks The handle returned is valid until the DRV_NVM_Close routine is called. This routine will NEVER block waiting for hardware. If the driver has has already been opened, it cannot be opened exclusively. Preconditions Function DRV_NVM_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_NVM_Open(DRV_NVM_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } Parameters Parameters Description index Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver Function DRV_HANDLE DRV_NVM_Open ( const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent ); DRV_NVM_Close Function Closes an opened-instance of the NVM driver Implementation: Static/Dynamic File drv_nvm.h C void DRV_NVM_Close(const DRV_HANDLE handle); Returns None Description This routine closes an opened-instance of the NVM driver, invalidating the handle. Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_NVM_Open before the caller may use the driver again. Usually there is no need for the driver client to verify that the Close Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 659 operation has completed. Preconditions The DRV_NVM_Initialize routine must have been called for the specified NVM driver instance. DRV_NVM_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_NVM_Open DRV_NVM_Close(handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_NVM_Close ( const DRV_HANDLE handle ); DRV_NVM_Read Function Reads blocks of data from the specified address in memory. Implementation: Static/Dynamic File drv_nvm.h C void DRV_NVM_Read(const DRV_HANDLE handle, DRV_NVM_COMMAND_HANDLE * commandHandle, void * targetBuffer, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It will be DRV_NVM_COMMAND_HANDLE_INVALID if the request was not successful. Description This routine reads blocks of data from the specified address in memory. This operation is blocking and returns with the required data in the target buffer. If an event handler is registered with the driver the event handler would be invoked from within this function to indicate the status of the operation. This function should not be used to read areas of memory which are queued to be programmed or erased. If required, the program or erase operations should be allowed to complete. The function returns DRV_NVM_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if the driver handle is invalid • if the target buffer pointer is NULL • if the number of blocks to be read is zero or more than the actual number of blocks available • if a buffer object could not be allocated to the request • if the client opened the driver in write only mode Remarks None. Preconditions The DRV_NVM_Initialize routine must have been called for the specified NVM driver instance. DRV_NVM_Open must have been called with DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE as the ioIntent to obtain a valid opened device handle. Example uint8_t myBuffer[MY_BUFFER_SIZE]; // address should be block aligned. uint32_t blockStart = NVM_BASE_ADDRESS_TO_READ_FROM; Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 660 uint32_t nBlock = 2; DRV_NVM_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // myNVMHandle is the handle returned // by the DRV_NVM_Open function. DRV_NVM_Read(myNVMHandle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_NVM_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } else { // Read Successful } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle targetBuffer Buffer into which the data read from the NVM Flash instance will be placed blockStart Start block address in NVM memory from where the read should begin. It can be any address of the flash. nBlock Total number of blocks to be read. Each Read block is of 1 byte. Function void DRV_NVM_Read ( const DRV_HANDLE handle, DRV_NVM_COMMAND_HANDLE * commandHandle, void * targetBuffer, uint32_t blockStart, uint32_t nBlock ); DRV_NVM_Write Function Writes blocks of data starting from the specified address in flash memory. Implementation: Static/Dynamic File drv_nvm.h C void DRV_NVM_Write(const DRV_HANDLE handle, DRV_NVM_COMMAND_HANDLE * commandHandle, void * sourceBuffer, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It will be DRV_NVM_COMMAND_HANDLE_INVALID if the request was not successful. Description This function schedules a non-blocking write operation for writing blocks of data into flash memory. The function returns with a valid buffer handle in the commandHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_NVM_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer object could not be allocated to the request • if the source buffer pointer is NULL • if the client opened the driver for read only • if the number of blocks to be written is either zero or more than the number of blocks actually available Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 661 • if the write queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_NVM_EVENT_COMMAND_COMPLETE event if the buffer was processed successfully or DRV_NVM_EVENT_COMMAND_ERROR event if the buffer was not processed successfully. Remarks Performing a flash programming operation while executing (fetching) instructions from program Flash memory, the CPU stalls (waits) until the programming operation is finished. The CPU will not execute any instruction, or respond to interrupts, during this time. If any interrupts occur during the programming cycle, they remain pending until the cycle completes. This makes the NVM write operation blocking in nature. Preconditions The DRV_NVM_Initialize() routine must have been called for the specified NVM driver instance. DRV_NVM_Open() routine must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified as a parameter to this routine. The flash address location which has to be written, must have be erased before using the DRV_NVM_Erase() routine. Example uint8_t myBuffer[MY_BUFFER_SIZE]; // address should be block aligned. uint32_t blockStart = NVM_BASE_ADDRESS_TO_WRITE_TO; uint32_t nBlock = 2; DRV_NVM_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // myNVMHandle is the handle returned // by the DRV_NVM_Open function. // Client registers an event handler with driver DRV_NVM_EventHandlerSet(myNVMHandle, APP_NVMEventHandler, (uintptr_t)&myAppObj); DRV_NVM_Write(myNVMHandle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_NVM_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_NVMEventHandler(DRV_NVM_EVENT event, DRV_NVM_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_NVM_EVENT_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_NVM_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 662 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle sourceBuffer The source buffer containing data to be programmed into NVM Flash blockStart Start block address of NVM Flash where the write should begin. This address should be aligned on a block boundary. nBlock Total number of blocks to be written. Function void DRV_NVM_Write ( const DRV_HANDLE handle, DRV_NVM_COMMAND_HANDLE * commandHandle, void * sourceBuffer, uint32_t blockStart, uint32_t nBlock ); DRV_NVM_Erase Function Erase the specified number of blocks of the Flash memory. Implementation: Static/Dynamic File drv_nvm.h C void DRV_NVM_Erase(const DRV_HANDLE handle, DRV_NVM_COMMAND_HANDLE * commandHandle, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It Will be DRV_NVM_COMMAND_HANDLE_INVALID if the request was not queued. Description This function schedules a non-blocking erase operation of flash memory. The function returns with a valid erase handle in the commandHandle argument if the erase request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. The function returns DRV_NVM_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer object could not be allocated to the request • if the client opened the driver for read only • if the number of blocks to be erased is either zero or more than the number of blocks actually available • if the erase queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_NVM_EVENT_COMMAND_COMPLETE event if the erase operation was successful or DRV_NVM_EVENT_COMMAND_ERROR event if the erase operation was not successful. Remarks Performing a flash erase operation while executing (fetching) instructions from program Flash memory, the CPU stalls (waits) until the erase operation is finished. The CPU will not execute any instruction, or respond to interrupts, during this time. If any interrupts occur during the programming cycle, they remain pending until the cycle completes. This make the NVM erase operation blocking in nature. Preconditions The DRV_NVM_Initialize() routine must have been called for the specified NVM driver instance. The DRV_NVM_Open() routine must have been called with DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 663 Example // Destination address should be block aligned. uint32_t blockStart; uint32_t nBlock; DRV_NVM_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // myNVMHandle is the handle returned // by the DRV_NVM_Open function. // Client registers an event handler with driver DRV_NVM_EventHandlerSet(myNVMHandle, APP_NVMEventHandler, (uintptr_t)&myAppObj); DRV_NVM_Erase( myNVMHandle, &commandHandle, blockStart, nBlock ); if(DRV_NVM_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when // the buffer queue is processed. void APP_NVMEventHandler(DRV_NVM_EVENT event, DRV_NVM_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_NVM_EVENT_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_NVM_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle blockStart Start block address in NVM memory from where the erase should begin. This should be aligned on a DRV_NVM_PAGE_SIZE byte boundary. nBlock Total number of blocks to be erased. Function void DRV_NVM_Erase ( const DRV_HANDLE handle, DRV_NVM_COMMAND_HANDLE * commandHandle, uint32_t blockStart, uint32_t nBlock ); Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 664 DRV_NVM_EraseWrite Function Erase and Write blocks of data starting from a specified address in flash memory. Implementation: Static/Dynamic File drv_nvm.h C void DRV_NVM_EraseWrite(const DRV_HANDLE handle, DRV_NVM_COMMAND_HANDLE * commandHandle, void * sourceBuffer, uint32_t writeBlockStart, uint32_t nWriteBlock); Returns The buffer handle is returned in the commandHandle argument. It Will be DRV_NVM_COMMAND_HANDLE_INVALID if the request was not queued. Description This function combines the step of erasing a page and then writing the row. The application can use this function if it wants to avoid having to explicitly delete a page in order to update the rows contained in the page. This function schedules a non-blocking operation to erase and write blocks of data into flash memory. The function returns with a valid buffer handle in the commandHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_NVM_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the client opened the driver for read only • if the buffer size is 0 • if the write queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_NVM_EVENT_COMMAND_COMPLETE event if the buffer was processed successfully or DRV_NVM_EVENT_COMMAND_ERROR event if the buffer was not processed successfully. Remarks In order to use this function, the DRV_NVM_ERASE_WRITE_ENABLE must be defined in system_config.h and the drv_nvm_erasewrite.c file must be included in the project. Preconditions The DRV_NVM_Initialize() routine must have been called for the specified NVM driver instance. The DRV_NVM_Open() must have been called with DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE as a parameter to obtain a valid opened device handle. Example uint8_t myBuffer[MY_BUFFER_SIZE]; // address should be block aligned. uint32_t blockStart = NVM_BASE_ADDRESS_TO_WRITE_TO; uint32_t nBlock = 2; DRV_NVM_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // myNVMHandle is the handle returned // by the DRV_NVM_Open function. // Client registers an event handler with driver DRV_NVM_EventHandlerSet(myNVMHandle, APP_NVMEventHandler, (uintptr_t)&myAppObj); DRV_NVM_EraseWrite(myNVMHandle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_NVM_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 665 // Event is received when // the buffer is processed. void APP_NVMEventHandler(DRV_NVM_EVENT event, DRV_NVM_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_NVM_EVENT_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_NVM_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle. If NULL, then buffer handle is not returned. sourceBuffer The source buffer containing data to be programmed into NVM Flash writeBlockStart Start block address of NVM Flash where the write should begin. This address should be aligned on a DRV_NVM_ROW_SIZE byte boundary. nWriteBlock Total number of blocks to be written. Function void DRV_NVM_EraseWrite ( const DRV_HANDLE handle, DRV_NVM_COMMAND_HANDLE * commandHandle, void * sourceBuffer, uint32_t writeBlockStart, uint32_t nWriteBlock ); DRV_NVM_EventHandlerSet Function Allows a client to identify an event handling function for the driver to call back when queued operation has completed. Implementation: Static/Dynamic File drv_nvm.h C void DRV_NVM_EventHandlerSet(const DRV_HANDLE handle, const void * eventHandler, const uintptr_t context); Returns None. Description This function allows a client to identify an event handling function for the driver to call back when queued operation has completed. When a client calls a write or erase function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 666 handle back to the client by calling "eventHandler" function when the queued operation has completed. The event handler should be set before the client performs any write or erase operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued operation has completed, it does not need to register a callback. Preconditions The DRV_NVM_Initialize() routine must have been called for the specified NVM driver instance. The DRV_NVM_Open() routine must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; uint8_t myBuffer[MY_BUFFER_SIZE]; uint32_t blockStart, nBlock; DRV_NVM_COMMAND_HANDLE commandHandle; // drvNVMHandle is the handle returned // by the DRV_NVM_Open function. // Client registers an event handler with driver. This is done once. DRV_NVM_EventHandlerSet(drvNVMHandle, APP_NVMEventHandler, (uintptr_t)&myAppObj); DRV_NVM_Read(drvNVMHandle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_NVM_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event Processing Technique. Event is received when operation is done. void APP_NVMEventHandler(DRV_NVM_EVENT event, DRV_NVM_COMMAND_HANDLE handle, uintptr_t context) { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) context; switch(event) { case DRV_NVM_EVENT_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_NVM_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function eventHandler Pointer to the event handler function implemented by the user Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 667 context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_NVM_EventHandlerSet ( const DRV_HANDLE handle, const void * eventHandler, const uintptr_t context ); c) Client Block Data Functions DRV_NVM_Tasks Function Maintains the driver's erase and write state machine and implements its ISR. Implementation: Static/Dynamic File drv_nvm.h C void DRV_NVM_Tasks(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal write and erase state machine and implement its ISR for interrupt-driven implementations. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the appropriate raw ISR. This routine may execute in an ISR context and will never block or access any resources that may cause it to block. Preconditions The DRV_NVM_Initialize routine must have been called for the specified NVM driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_NVM_Initialize while (true) { DRV_NVM_Tasks (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_NVM_Initialize) Function void DRV_NVM_Tasks ( SYS_MODULE_OBJ object ); Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 668 d) Status Functions DRV_NVM_AddressGet Function Returns the NVM media start address Implementation: Static/Dynamic File drv_nvm.h C uintptr_t DRV_NVM_AddressGet(const DRV_HANDLE handle); Returns Start address of the NVM Media if the handle is valid otherwise NULL. Description This function returns the NVM Media start address. Remarks None. Preconditions The DRV_NVM_Initialize() routine must have been called for the specified NVM driver instance. The DRV_NVM_Open() routine must have been called to obtain a valid opened device handle. Example uintptr_t startAddress; startAddress = DRV_NVM_AddressGet(drvNVMHandle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function uintptr_t DRV_NVM_AddressGet ( const DRV_HANDLE handle ); DRV_NVM_CommandStatus Function Gets the current status of the command. Implementation: Static/Dynamic File drv_nvm.h C DRV_NVM_COMMAND_STATUS DRV_NVM_CommandStatus(const DRV_HANDLE handle, const DRV_NVM_COMMAND_HANDLE commandHandle); Returns A DRV_NVM_COMMAND_STATUS value describing the current status of the command. Returns DRV_NVM_COMMAND_HANDLE_INVALID if the client handle or the command handle is not valid. Description This routine gets the current status of the command. The application must use this routine where the status of a scheduled command needs to polled on. The function may return DRV_NVM_COMMAND_HANDLE_INVALID in a case where the command handle has expired. A command Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 669 handle expires when the internal buffer object is re-assigned to another erase or write request. It is recommended that this function be called regularly in order to track the command status correctly. The application can alternatively register an event handler to receive write or erase operation completion events. Remarks This routine will not block for hardware access and will immediately return the current status. Preconditions The DRV_NVM_Initialize() routine must have been called. The DRV_NVM_Open() must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_NVM_Open DRV_NVM_COMMAND_HANDLE commandHandle; DRV_NVM_COMMAND_STATUS status; status = DRV_NVM_CommandStatus(handle, commandHandle); if(status == DRV_NVM_COMMAND_COMPLETED) { // Operation Done } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function DRV_NVM_COMMAND_STATUS DRV_NVM_CommandStatus ( const DRV_HANDLE handle, const DRV_NVM_COMMAND_HANDLE commandHandle ); DRV_NVM_GeometryGet Function Returns the geometry of the device. Implementation: Static/Dynamic File drv_nvm.h C SYS_FS_MEDIA_GEOMETRY * DRV_NVM_GeometryGet(const DRV_HANDLE handle); Returns SYS_FS_MEDIA_GEOMETRY - Pointer to structure which holds the media geometry information. Description This API gives the following geometrical details of the NVM Flash: • Media Property • Number of Read/Write/Erase regions in the flash device • Number of Blocks and their size in each region of the device Remarks None. Preconditions The DRV_NVM_Initialize() routine must have been called for the specified NVM driver instance. The DRV_NVM_Open() routine must have been called to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 670 Example SYS_FS_MEDIA_GEOMETRY * nvmFlashGeometry; uint32_t readBlockSize, writeBlockSize, eraseBlockSize; uint32_t nReadBlocks, nReadRegions, totalFlashSize; nvmFlashGeometry = DRV_NVM_GeometryGet(nvmOpenHandle1); readBlockSize = nvmFlashGeometry->geometryTable->blockSize; nReadBlocks = nvmFlashGeometry->geometryTable->numBlocks; nReadRegions = nvmFlashGeometry->numReadRegions; writeBlockSize = (nvmFlashGeometry->geometryTable +1)->blockSize; eraseBlockSize = (nvmFlashGeometry->geometryTable +2)->blockSize; totalFlashSize = readBlockSize * nReadBlocks * nReadRegions; Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function SYS_FS_MEDIA_GEOMETRY * DRV_NVM_GeometryGet ( const DRV_HANDLE handle ); e) Miscellaneous Functions DRV_NVM_IsAttached Function Returns the physical attach status of the NVM. Implementation: Static/Dynamic File drv_nvm.h C bool DRV_NVM_IsAttached(const DRV_HANDLE handle); Returns Returns false if the handle is invalid otherwise returns true. Description This function returns the physical attach status of the NVM. Remarks None. Preconditions The DRV_NVM_Initialize() routine must have been called for the specified NVM driver instance. The DRV_NVM_Open() routine must have been called to obtain a valid opened device handle. Example // The NVM media is always attached and so the below // always returns true. bool isNVMAttached; isNVMAttached = DRV_NVM_isAttached(drvNVMHandle); Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 671 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function bool DRV_NVM_IsAttached ( const DRV_HANDLE handle ); DRV_NVM_IsWriteProtected Function Returns the write protect status of the NVM. Implementation: Static/Dynamic File drv_nvm.h C bool DRV_NVM_IsWriteProtected(const DRV_HANDLE handle); Returns Always returns false. Description This function returns the physical attach status of the NVM. This function always returns false. Remarks None. Preconditions The DRV_NVM_Initialize() routine must have been called for the specified NVM driver instance. The DRV_NVM_Open() routine must have been called to obtain a valid opened device handle. Example // The NVM media is treated as always writeable. bool isWriteProtected; isWriteProtected = DRV_NVM_IsWriteProtected(drvNVMHandle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function bool DRV_NVM_IsWriteProtected ( const DRV_HANDLE handle ); f) Data Types and Constants DRV_NVM_INDEX_0 Macro NVM driver index definitions File drv_nvm.h Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 672 C #define DRV_NVM_INDEX_0 0 Description Driver NVM Module Index reference These constants provide NVM driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_NVM_Initialize and DRV_NVM_Open routines to identify the driver instance in use. DRV_NVM_INIT Structure Defines the data required to initialize or reinitialize the NVM driver File drv_nvm.h C typedef struct { SYS_MODULE_INIT moduleInit; NVM_MODULE_ID nvmID; INT_SOURCE interruptSource; uint32_t mediaStartAddress; const SYS_FS_MEDIA_GEOMETRY * nvmMediaGeometry; } DRV_NVM_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization NVM_MODULE_ID nvmID; Identifies NVM hardware module (PLIB-level) ID INT_SOURCE interruptSource; Interrupt Source for Write Interrupt uint32_t mediaStartAddress; NVM Media start address. The driver treats this address as • block 0 address for read, write and erase operations. const SYS_FS_MEDIA_GEOMETRY * nvmMediaGeometry; NVM Media geometry object. Description NVM Driver Initialization Data This data type defines the data required to initialize or reinitialize the NVM driver. Remarks Not all initialization features are available for all devices. Please refer to the specific device data sheet to determine availability. DRV_NVM_INDEX_1 Macro File drv_nvm.h C #define DRV_NVM_INDEX_1 1 Description This is macro DRV_NVM_INDEX_1. DRV_NVM_EVENT Enumeration Identifies the possible events that can result from a request. File drv_nvm.h Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 673 C typedef enum { DRV_NVM_EVENT_COMMAND_COMPLETE = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_COMPLETE, DRV_NVM_EVENT_COMMAND_ERROR = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_ERROR } DRV_NVM_EVENT; Members Members Description DRV_NVM_EVENT_COMMAND_COMPLETE = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_COMPLETE Operation has been completed successfully. DRV_NVM_EVENT_COMMAND_ERROR = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_ERROR There was an error during the operation Description NVM Driver Events This enumeration identifies the possible events that can result from a Write or Erase request caused by the client. Remarks One of these values is passed in the "event" parameter of the event handling callback function that client registered with the driver by calling the DRV_NVM_EventHandlerSet function when a request is completed. DRV_NVM_EVENT_HANDLER Type Pointer to a NVM Driver Event handler function File drv_nvm.h C typedef SYS_FS_MEDIA_EVENT_HANDLER DRV_NVM_EVENT_HANDLER; Returns None. Description NVM Driver Event Handler Function Pointer This data type defines the required function signature for the NVM event handling callback function. A client must register a pointer to an event handling function whose function signature (parameter and return value types) match the types specified by this function pointer in order to receive event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks If the event is DRV_NVM_EVENT_COMMAND_COMPLETE, it means that the write or a erase operation was completed successfully. If the event is DRV_NVM_EVENT_COMMAND_ERROR, it means that the scheduled operation was not completed successfully. The context parameter contains the handle to the client context, provided at the time the event handling function was registered using the DRV_NVM_EventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the read/write/erase request. The event handler function executes in the driver peripheral's interrupt context when the driver is configured for interrupt mode operation. It is recommended of the application to not perform process intensive or blocking operations within this function. Example void APP_MyNvmEventHandler ( DRV_NVM_EVENT event, DRV_NVM_COMMAND_HANDLE commandHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 674 { case DRV_NVM_EVENT_COMMAND_COMPLETE: // Handle the completed buffer. break; case DRV_NVM_EVENT_COMMAND_ERROR: default: // Handle error. break; } } Parameters Parameters Description event Identifies the type of event commandHandle Handle returned from the Read/Write/Erase requests context Value identifying the context of the application that registered the event handling function DRV_NVM_COMMAND_HANDLE Type Handle identifying commands queued in the driver. File drv_nvm.h C typedef SYS_FS_MEDIA_BLOCK_COMMAND_HANDLE DRV_NVM_COMMAND_HANDLE; Description NVM Driver command handle. A command handle is returned by a call to the Read, Write or Erase functions. This handle allows the application to track the completion of the operation. This command handle is also returned to the client along with the event that has occurred with respect to the command. This allows the application to connect the event to a specific command in case where multiple commands are queued. The command handle associated with the command request expires when the client has been notified of the completion of the command (after event handler function that notifies the client returns) or after the command has been retired by the driver if no event handler callback was set. Remarks None. DRV_NVM_COMMAND_STATUS Enumeration Specifies the status of the command for the read, write and erase operations. File drv_nvm.h C typedef enum { DRV_NVM_COMMAND_COMPLETED = SYS_FS_MEDIA_COMMAND_COMPLETED, DRV_NVM_COMMAND_QUEUED = SYS_FS_MEDIA_COMMAND_QUEUED, DRV_NVM_COMMAND_IN_PROGRESS = SYS_FS_MEDIA_COMMAND_IN_PROGRESS, DRV_NVM_COMMAND_ERROR_UNKNOWN = SYS_FS_MEDIA_COMMAND_UNKNOWN } DRV_NVM_COMMAND_STATUS; Members Members Description DRV_NVM_COMMAND_COMPLETED = SYS_FS_MEDIA_COMMAND_COMPLETED Done OK and ready DRV_NVM_COMMAND_QUEUED = SYS_FS_MEDIA_COMMAND_QUEUED Scheduled but not started Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 675 DRV_NVM_COMMAND_IN_PROGRESS = SYS_FS_MEDIA_COMMAND_IN_PROGRESS Currently being in transfer DRV_NVM_COMMAND_ERROR_UNKNOWN = SYS_FS_MEDIA_COMMAND_UNKNOWN Unknown Command Description NVM Driver Command Status NVM Driver command Status This type specifies the status of the command for the read, write and erase operations. Remarks None. DRV_NVM_COMMAND_HANDLE_INVALID Macro This value defines the NVM Driver's Invalid Command Handle. File drv_nvm.h C #define DRV_NVM_COMMAND_HANDLE_INVALID SYS_FS_MEDIA_BLOCK_COMMAND_HANDLE_INVALID Description NVM Driver Invalid Command Handle. This value defines the NVM Driver Invalid Command Handle. This value is returned by read/write/erase routines when the command request was not accepted. Remarks None. Files Files Name Description drv_nvm.h NVM Driver Interface Definition drv_nvm_config_template.h NVM driver configuration definitions. Description This section lists the source and header files used by the NVM Driver Library. drv_nvm.h NVM Driver Interface Definition Enumerations Name Description DRV_NVM_COMMAND_STATUS Specifies the status of the command for the read, write and erase operations. DRV_NVM_EVENT Identifies the possible events that can result from a request. Functions Name Description DRV_NVM_AddressGet Returns the NVM media start address Implementation: Static/Dynamic DRV_NVM_Close Closes an opened-instance of the NVM driver Implementation: Static/Dynamic DRV_NVM_CommandStatus Gets the current status of the command. Implementation: Static/Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 676 DRV_NVM_Deinitialize Deinitializes the specified instance of the NVM driver module Implementation: Static/Dynamic DRV_NVM_Erase Erase the specified number of blocks of the Flash memory. Implementation: Static/Dynamic DRV_NVM_EraseWrite Erase and Write blocks of data starting from a specified address in flash memory. Implementation: Static/Dynamic DRV_NVM_EventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. Implementation: Static/Dynamic DRV_NVM_GeometryGet Returns the geometry of the device. Implementation: Static/Dynamic DRV_NVM_Initialize Initializes the NVM instance for the specified driver index Implementation: Static/Dynamic DRV_NVM_IsAttached Returns the physical attach status of the NVM. Implementation: Static/Dynamic DRV_NVM_IsWriteProtected Returns the write protect status of the NVM. Implementation: Static/Dynamic DRV_NVM_Open Opens the specified NVM driver instance and returns a handle to it Implementation: Static/Dynamic DRV_NVM_Read Reads blocks of data from the specified address in memory. Implementation: Static/Dynamic DRV_NVM_Status Gets the current status of the NVM driver module. Implementation: Static/Dynamic DRV_NVM_Tasks Maintains the driver's erase and write state machine and implements its ISR. Implementation: Static/Dynamic DRV_NVM_Write Writes blocks of data starting from the specified address in flash memory. Implementation: Static/Dynamic Macros Name Description DRV_NVM_COMMAND_HANDLE_INVALID This value defines the NVM Driver's Invalid Command Handle. DRV_NVM_INDEX_0 NVM driver index definitions DRV_NVM_INDEX_1 This is macro DRV_NVM_INDEX_1. DRV_NVM_PAGE_SIZE Specifies the NVM Driver Program Page Size in bytes. DRV_NVM_ROW_SIZE Specifies the NVM Driver Program Row Size in bytes. Structures Name Description DRV_NVM_INIT Defines the data required to initialize or reinitialize the NVM driver Types Name Description DRV_NVM_COMMAND_HANDLE Handle identifying commands queued in the driver. DRV_NVM_EVENT_HANDLER Pointer to a NVM Driver Event handler function Description NVM Driver Interface Definition The NVM driver provides a simple interface to manage the Non Volatile Flash Memory on Microchip microcontrollers. This file defines the interface definition for the NVM driver. File Name drv_nvm.h Company Microchip Technology Inc. Volume V: MPLAB Harmony Framework Driver Libraries Help NVM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 677 drv_nvm_config_template.h NVM driver configuration definitions. Macros Name Description DRV_NVM_BUFFER_OBJECT_NUMBER Selects the maximum number of buffer objects DRV_NVM_CLIENTS_NUMBER Selects the maximum number of clients DRV_NVM_DISABLE_ERROR_CHECK Disables the error checks in the driver. DRV_NVM_ERASE_WRITE_ENABLE Enables support for NVM Driver Erase Write Feature. DRV_NVM_INSTANCES_NUMBER Selects the maximum number of Driver instances that can be supported by the dynamic driver. DRV_NVM_INTERRUPT_MODE Macro specifies operation of the driver to be in the interrupt mode or polled mode DRV_NVM_MEDIA_SIZE Specifies the NVM Media size. DRV_NVM_MEDIA_START_ADDRESS Specifies the NVM Media start address. DRV_NVM_SYS_FS_REGISTER Register to use with the File system Description NVM Driver Configuration Template Header file. This template file describes all the mandatory and optional configuration macros that are needed for building the NVM driver. Do not include this file in source code. File Name drv_nvm_config_template.h Company Microchip Technology Inc. Output Compare Driver Library This section describes the Output Compare Driver Library. Introduction The Output Compare Static Driver provides a high-level interface to manage the Output Compare module on the Microchip family of microcontrollers. Description Through the MHC, this driver provides APIs for the following: • Initializing the module • Enabling/Disabling of the output compare • Starting/Stopping of the output compare • Fault checking Library Interface Functions Name Description DRV_OC_Disable Disables the Output Compare instance for the specified driver index. Implementation: Static DRV_OC_Enable Enables the Output Compare for the specified driver index. Implementation: Static DRV_OC_FaultHasOccurred Checks if a Fault has occurred for the specified driver index. Implementation: Static DRV_OC_Initialize Initializes the Comparator instance for the specified driver index. Implementation: Static Volume V: MPLAB Harmony Framework Driver Libraries Help Output Compare Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 678 DRV_OC_Start Starts the Comparator instance for the specified driver index. Implementation: Static DRV_OC_Stop Stops the Output Compare instance for the specified driver index. Implementation: Static Description This section describes the Application Programming Interface (API) functions of the Output Compare Driver Library. Functions DRV_OC_Disable Function Disables the Output Compare instance for the specified driver index. Implementation: Static File help_drv_oc.h C void DRV_OC_Disable(); Returns None. Description This routine disables the Output Compare for the specified driver instance, making it ready for clients to use it. The initialization routine is specified by the MHC parameters. Remarks None. Preconditions DRV_OC_Initialize has been called. Function void DRV_OC_Disable( void ) DRV_OC_Enable Function Enables the Output Compare for the specified driver index. Implementation: Static File help_drv_oc.h C void DRV_OC_Enable(); Returns None. Description This routine enables the Output Compare for the specified driver instance, making it ready for clients to use it. The initialization routine is specified by the MHC parameters. Remarks None. Preconditions DRV_OC_Initialize has been called. Volume V: MPLAB Harmony Framework Driver Libraries Help Output Compare Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 679 Function void DRV_OC_Enable( void ) DRV_OC_FaultHasOccurred Function Checks if a Fault has occurred for the specified driver index. Implementation: Static File help_drv_oc.h C bool DRV_OC_FaultHasOccurred(); Returns Boolean • 1 - A Fault has occurred • 0 - A Fault has not occurred Description This routine checks whether or not a Fault has occurred for the specified driver index. The initialization routine is specified by the MHC parameters. Remarks None. Preconditions DRV_OC_Initialize has been called. Function bool DRV_OC_FaultHasOccurred( void ) DRV_OC_Initialize Function Initializes the Comparator instance for the specified driver index. Implementation: Static File help_drv_oc.h C void DRV_OC_Initialize(); Returns None. Description This routine initializes the Output Compare driver instance for the specified driver instance, making it ready for clients to use it. The initialization routine is specified by the MHC parameters. The driver instance index is independent of the Output Compare module ID. For example, driver instance 0 can be assigned to Output Compare 1. Remarks This routine must be called before any other Comparator routine is called. This routine should only be called once during system initialization. Preconditions None. Function void DRV_OC_Initialize( void ) Volume V: MPLAB Harmony Framework Driver Libraries Help Output Compare Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 680 DRV_OC_Start Function Starts the Comparator instance for the specified driver index. Implementation: Static File help_drv_oc.h C void DRV_OC_Start(); Returns None. Description This routine starts the Output Compare for the specified driver instance. Remarks None. Preconditions DRV_OC_Initialize has been called. Function void DRV_OC_Start( void ) DRV_OC_Stop Function Stops the Output Compare instance for the specified driver index. Implementation: Static File help_drv_oc.h C void DRV_OC_Stop(); Returns None. Description This routine stops the Output Compare for the specified driver instance. Remarks None. Preconditions DRV_OC_Initialize has been called. Function void DRV_OC_Stop( void ) Parallel Master Port (PMP) Driver Library This section describes the Parallel Master Port Driver Library. Introduction This library provides an interface to manage the Parallel Master Port (PMP) module on Microchip family of microcontrollers in different modes of operation. Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 681 Description The Parallel Master Port (PMP) is a parallel 8-bit/16-bit I/O module specifically designed to communicate with a wide variety of parallel devices such as communications peripherals, LCDs, external memory devices and microcontrollers. Because the interfaces to parallel peripherals vary significantly, the PMP module is highly configurable. The following figure shows a generic block diagram, which illustrates the ways the PMP module can be used: The PMP module can be used in different modes. Master and Slave are the two modes that can have additional sub-modes, depending on the different microcontroller families. Master Mode: In Master mode, the PMP module can provide a 8-bit or 16-bit data bus, up to 16 bits of address, and all of the necessary control signals to operate a variety of external parallel devices such as memory devices, peripherals and slave microcontrollers. The PMP master modes provide a simple interface for reading and writing data, but not executing program instructions from external devices, such as SRAM or Flash memories. Slave Mode: Slave mode only supports 8-bit data and the module control pins are automatically dedicated when this mode is selected. Using the Library This topic describes the basic architecture of the PMP Driver Library and provides information and examples on its use. Description Interface Header File: drv_pmp.h The interface to the PMP Driver library is defined in the drv_pmp.h header file. This file is included by the drv.h file. Any C language source (.c) file that uses the PMP Driver Library should include drv.h. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. 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 Hardware Abstraction Model Description Depending on the device,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. The desired timing wait states to suit different peripheral timings can also be programmed using the PMP module. Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 682 PMP Hardware Abstraction Model Diagram Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. 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 System Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks, and status functions. Client Interaction Functions Provides open, close, client status and client mode configuration functions. Client Transfer Functions Provides interface for data transfer in master and slave mode. Miscellaneous Provides driver miscellaneous functions, version identification functions, etc. How the Library Works This section describes how the PMP Driver Library operates. Description Before the driver is ready for use, its should be configured (compile time configuration). Refer to the Configuring the Library section for more details on how to configure the driver. There are few run-time configuration items that are done during initialization of the driver instance, and a few that are client-specific and are done using dedicated functions. To use the PMP Driver, initialization and client functions should be invoked in a specific sequence to ensure correct operation. The following is the sequence in which various routines should be called: 1. Call DRV_PMP_Initialize to initialize the PMP Driver. Note that this may be performed by the MPLAB Harmony system module. The DRV_PMP_Status function may be used to check the status of the initialization. 2. Once initialization for a particular driver instance is done, the client wanting to use the driver can open it using DRV_PMP_Open. 3. The DRV_PMP_ModeConfig function should now be called, which will configure the driver for the exact mode of operation required by that client. 4. After configuring the mode, DRV_PMP_Write and/or DRV_PMP_Read can be called by the user application to Write/Read using the PMP module. Calling these functions does not start the PMP transfer immediately in non-interrupt mode. Instead, all of these transfer tasks are queued in an internal queue. Actual transfer starts only when the PMP Task function is called by the system/user. In interrupt mode, although transfer tasks are queued, the actual transfer starts immediately. 5. PMP Write and Read functions return an ID of that particular transfer, which should be saved by user to get the status of that transfer later. 6. The system will either call DRV_PMP_Tasks from the System Task Service (in a polled environment), or it will be called from the ISR of the PMP. 7. At any time status of the transfer can be obtained by using DRV_PMP_TransferStatus. Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. System Initialization This section describes initialization and reinitialization features. Description Initialization and Reinitialization The system performs the initialization and the reinitialization of the device driver with settings that affect only the instance of the device that is being initialized or reinitialized. During system initialization each instance of the PMP device will be initialized with the following configuration settings: Initialization Member Description moduleInit System module initialization of the power state. pmpId PMP hardware module ID (peripheral library-level ID). stopInIdle Decide whether or not the module should be stopped in Idle mode. muxMode To select one of the different multiplexing modes possible for PMP module. inputBuffer Select the type of Input Buffer (TTL or Schmitt Trigger). Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 683 polarity Select polarity of different PMP pins. ports Set the pins the user wants to use as port or PMP pins. The DRV_PMP_Initialize function returns an object handle of the type SYS_MODULE_OBJ. After this, the object handle returned by the initialize interface would be used by the other system interfaces, such as DRV_PMP_Reinitialize, DRV_PMP_Deinitialize, DRV_PMP_Status, and DRV_PMP_Tasks. Example for PMP Initialization Through the DRV_PMP_INIT Structure DRV_PMP_INIT init; SYS_MODULE_OBJ object; SYS_STATUS pmpStatus; // populate the PMP init configuration structure init.inputBuffer = PMP_INPUT_BUFFER_TTL; init.polarity.addressLatchPolarity = PMP_POLARITY_ACTIVE_HIGH; init.polarity.rwStrobePolarity = PMP_POLARITY_ACTIVE_LOW; init.polarity.writeEnableStrobePolarity = PMP_POLARITY_ACTIVE_LOW; init.polarity.chipselect1Polarity = PMP_POLARITY_ACTIVE_HIGH; init.polarity.chipselect2Polarity = PMP_POLARITY_ACTIVE_LOW; init.ports.addressPortsMask = PMP_PMA0_PORT | PMP_PMA1_PORT | PMP_PMA2_TO_PMA13_PORTS | PMP_PMA14_PORT; init.ports.readWriteStrobe = PORT_ENABLE; init.ports.writeEnableStrobe = PORT_ENABLE; init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.pmpID = PMP_ID_0; init.stopInIdle = false; init.muxMode = PMP_MUX_NONE; object = DRV_PMP_Initialize (DRV_PMP_INDEX_0, (SYS_MODULE_INIT *)&init); pmpStatus = DRV_PMP_Status(object); if ( SYS_STATUS_READY != pmpStatus) { // Handle error } Deinitialization Once the initialize operation has been called, the deinitialize operation must be called before the initialize operation can be called again. This routine may block if the driver is running in an OS environment that supports blocking operations and the driver requires system resources access. However, the function will never block for hardware PMP access. If the operation requires time to allow the hardware to complete, which will be reported by DRV_PMP_Status. Status PMP status is available to query the module state before, during and after initialization, deinitialization, and reinitialization. Tasks Routine The DRV_PMP_Tasks function will see the queue status and perform the task of transferring the data accordingly. In the Blocking mode when interrupts are disabled, it will finish one of the tasks completely (that means emptying one space in queue), and then return back. Whereas in Non-Blocking mode, it will return back just after starting one word (8-bit or 16-bit) of transfer (may not be emptying one space in the queue, as that task may not be completely finished). The DRV_PMP_Tasks function can be called in two ways: • By the system task service in a polled environment • By the ISR of the PMP in an interrupt-based system Example: Polling int main( void ) { SYS_MODULE_OBJ object; object = DRV_PMP_Initialize( DRV_PMP_INDEX_0, (SYS_MODULE_INIT *) &initConf ); if( SYS_STATUS_READY != DRV_PMP_Status( object ) ) return 0; while (1) { DRV_PMP_Tasks (object); Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 684 } } Example: Interrupt int main( void ) { SYS_MODULE_OBJ object; object = DRV_PMP_Initialize( DRV_PMP_INDEX_0, (SYS_MODULE_INIT *) &initConf ); if( SYS_STATUS_READY != DRV_PMP_Status( object ) ) return 0; while (1); } /* Sample interrupt routine not specific to any device family */ void ISR PMPInterrupt(void) { //Call the PMP Tasks routine DRV_PMP_Tasks(object); } Note: A PMP transfer in Blocking mode in an interrupt environment is not supported. Transfer Operation This section describes transfer operation. Description Once the PMP Driver is open and configured for a client, it is set to start Reading/Writing through DRV_PMP_Read and DRV_PMP_Write. However, these functions will not directly start reading or writing. These will just put the relevant information in a queue in non-interrupt mode and return an ID that can be used later for checking the transfer status. In Interrupt mode, the Read/Write functions will trigger the transfer immediately after storing the transfer information in the queue. The user must use a buffer pointing to character for data values. The repeatCount parameter allows the user to repeatedly write the same nBytes of data into the slave devices. Example: unsigned char myReadBuffer[300], myWriteBuffer[100]; // has to be 'char' arrays uint32_t deviceAddress, nBytes, repeatCount, i; uint32_t writeID, readID; DRV_HANDLE handle; //initialize, open and configure the driver/client /* ... */ deviceAddress = 0x0206; nBytes = 100; repeatCount = 0x01; for (i=0; i/framework/driver/pmp. Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 689 Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_pmp.h This file provides the interface definitions of the PMP driver 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 /src/dynamic/drv_pmp_dynamic.c This file contains the core implementation of the PMP driver. 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 N/A No optional files are available for this library Module Dependencies The PMP Driver Library depends on the following modules: • PMP Peripheral Library • Interrupt System Service Library Library Interface a) System Functions Name Description DRV_PMP_Deinitialize Deinitializes the specified instance of the PMP driver module. Implementation: Dynamic DRV_PMP_Initialize Initializes the PMP driver. Implementation: Static/Dynamic DRV_PMP_Reinitialize Reinitializes the driver and refreshes any associated hardware settings. Implementation: Dynamic DRV_PMP_Status Provides the current status of the PMP driver module. Implementation: Dynamic DRV_PMP_Tasks Maintains the driver's state machine and implements its ISR. Implementation: Dynamic DRV_PMP_TimingSet Sets PMP timing parameters. Implementation: Static b) Client Interaction Functions Name Description DRV_PMP_ClientStatus Gets the current client-specific status of the PMP driver. Implementation: Dynamic DRV_PMP_Close Closes an opened instance of the PMP driver. Implementation: Dynamic DRV_PMP_ModeConfig Configures the PMP modes. Implementation: Static/Dynamic DRV_PMP_Open Opens the specified PMP driver instance and returns a handle to it. Implementation: Dynamic DRV_PMP_Read Read the data from external device. Implementation: Static/Dynamic DRV_PMP_Write Transfers the data from the MCU to the external device. Implementation: Static/Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 690 c) Client Transfer Functions Name Description DRV_PMP_TransferStatus Returns the transfer status. Implementation: Dynamic e) Data Types and Constants Name Description DRV_PMP_INDEX_COUNT Number of valid PMP driver indices. DRV_PMP_CHIPX_STROBE_MODE PMP writeEnable/ReadWrite strobes. DRV_PMP_CLIENT_STATUS PMP client status definitions. DRV_PMP_ENDIAN_MODE PMP Endian modes. DRV_PMP_INDEX PMP driver index definitions. DRV_PMP_INIT Defines the PMP driver initialization data. DRV_PMP_MODE_CONFIG PMP modes configuration. DRV_PMP_POLARITY_OBJECT PMP polarity object. DRV_PMP_PORT_CONTROL PMP port enable/disable definitions. DRV_PMP_PORTS PMP port configuration. DRV_PMP_QUEUE_ELEMENT_OBJ Defines the object for PMP queue element. _DRV_PMP_QUEUE_ELEMENT_OBJ Defines the object for PMP queue element. DRV_PMP_TRANSFER_STATUS Defines the PMP transfer status. DRV_PMP_WAIT_STATES PMP wait states object. MAX_NONBUFFERED_BYTE_COUNT After this number the PMP transfer should be polled to guarantee data transfer DRV_PMP_TRANSFER_TYPE This is type DRV_PMP_TRANSFER_TYPE. PMP_QUEUE_ELEMENT_OBJECT Defines the structure required for maintaining the queue element. Description This section describes the Application Programming Interface (API) functions of the PMP Driver. Refer to each section for a detailed description. a) System Functions DRV_PMP_Deinitialize Function Deinitializes the specified instance of the PMP driver module. Implementation: Dynamic File drv_pmp.h C void DRV_PMP_Deinitialize(const SYS_MODULE_OBJ pmpDriverObject); Returns None. Description This function deinitializes the specified instance of the PMP driver module, disabling its operation (and any hardware). All internal data is invalidated. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_PMP_Status operation. The system has to use DRV_PMP_Status to find out when the module is in the ready state. Preconditions The DRV_PMP_Initialize function must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 691 Example SYS_MODULE_OBJ pmpDriverObject; // Returned from DRV_PMP_Initialize SYS_STATUS status; DRV_PMP_Deinitialize(pmpDriverObject); status = DRV_PMP_Status(pmpDriverObject); if (SYS_MODULE_DEINITIALIZED == status) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description pmpDriverObject Driver object handle, returned from the DRV_PMP_Initialize Function void DRV_PMP_Deinitialize ( SYS_MODULE_OBJ pmpDriverObject ) DRV_PMP_Initialize Function Initializes the PMP driver. Implementation: Static/Dynamic File drv_pmp.h C SYS_MODULE_OBJ DRV_PMP_Initialize(const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init); Returns If successful, it returns a valid handle to a driver object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. The returned object must be passed as argument to DRV_PMP_Reinitialize, DRV_PMP_Deinitialize, DRV_PMP_Tasks and DRV_PMP_Status routines. Description This function initializes the PMP driver, making it ready for clients to open and use it. Remarks This function must be called before any other PMP function is called. This function should only be called once during system initialization unless DRV_PMP_Deinitialize is called to deinitialize the driver instance. This function will NEVER block for hardware access. If the operation requires time to allow the hardware to reinitialize, it will be reported by the DRV_PMP_Status operation. The system must use DRV_PMP_Status to find out when the driver is in the ready state. Build configuration options may be used to statically override options in the "init" structure and will take precedence over initialization data passed using this function. Preconditions None. Example DRV_PMP_INIT init; SYS_MODULE_OBJ objectHandle; // Populate the initialization structure init.inputBuffer = PMP_INPUT_BUFFER_TTL; init.polarity.addressLatchPolarity = PMP_POLARITY_ACTIVE_HIGH; init.polarity.rwStrobePolarity = PMP_POLARITY_ACTIVE_LOW; init.polarity.writeEnableStrobePolarity = PMP_POLARITY_ACTIVE_LOW; init.polarity.chipselect1Polarity = PMP_POLARITY_ACTIVE_HIGH; init.polarity.chipselect2Polarity = PMP_POLARITY_ACTIVE_LOW; init.ports.addressPortsMask = PMP_PMA0_PORT | PMP_PMA1_PORT | PMP_PMA2_TO_PMA13_PORTS | PMP_PMA14_PORT; init.ports.readWriteStrobe = PORT_ENABLE; init.ports.writeEnableStrobe = PORT_ENABLE; Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 692 init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.pmpID = PMP_ID_0; init.stopInIdle = false; init.muxMode = PMP_MUX_NONE; // Do something objectHandle = DRV_PMP_Initialize(DRV_PMP_INDEX_0, (SYS_MODULE_INIT*)&init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description drvIndex Index for the driver instance to be initialized init Pointer to a data structure containing any data necessary to initialize the driver Function SYS_MODULE_OBJ DRV_PMP_Initialize( const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init ) DRV_PMP_Reinitialize Function Reinitializes the driver and refreshes any associated hardware settings. Implementation: Dynamic File drv_pmp.h C void DRV_PMP_Reinitialize(const SYS_MODULE_OBJ pmpDriverObject, const SYS_MODULE_INIT * const init); Returns None. Description This function reinitializes the driver and refreshes any associated hardware settings using the specified initialization data, but it will not interrupt any ongoing operations. Remarks This function can be called multiple times to reinitialize the module. This operation can be used to refresh any supported hardware registers as specified by the initialization data or to change the power state of the module. This function will NEVER block for hardware access. If the operation requires time to allow the hardware to re-initialize, it will be reported by the DRV_PMP_Status operation. The system must use DRV_PMP_Status to find out when the driver is in the ready state. Build configuration options may be used to statically override options in the "init" structure and will take precedence over initialization data passed using this function. Preconditions The DRV_PMP_Initialize function must have been called before calling this function and a valid SYS_MODULE_OBJ must have been returned. Example DRV_PMP_INIT init; SYS_MODULE_OBJ pmpDriverObject; SYS_STATUS pmpStatus; // Populate the initialization structure init.inputBuffer = PMP_INPUT_BUFFER_TTL; init.polarity.addressLatchPolarity = PMP_POLARITY_ACTIVE_HIGH; init.polarity.rwStrobePolarity = PMP_POLARITY_ACTIVE_LOW; init.polarity.writeEnableStrobePolarity = PMP_POLARITY_ACTIVE_LOW; Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 693 init.polarity.chipselect1Polarity = PMP_POLARITY_ACTIVE_HIGH; init.polarity.chipselect2Polarity = PMP_POLARITY_ACTIVE_LOW; init.ports.addressPortsMask = PMP_PMA0_PORT | PMP_PMA1_PORT | PMP_PMA2_TO_PMA13_PORTS | PMP_PMA14_PORT; init.ports.readWriteStrobe = PORT_ENABLE; init.ports.writeEnableStrobe = PORT_ENABLE; init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.pmpID = PMP_ID_0; init.stopInIdle = false; init.muxMode = PMP_MUX_NONE; DRV_PMP_Reinitialize(pmpDriverObject, (SYS_MODULE_INIT*)&init); pmpStatus = DRV_PMP_Status(pmpDriverObject); if (SYS_STATUS_BUSY == pmpStatus) { // Check again later to ensure the driver is ready } else if (SYS_STATUS_ERROR >= pmpStatus) { // Handle error } Parameters Parameters Description pmpDriverObject Driver object handle, returned from the DRV_PMP_Initialize Function void DRV_PMP_Reinitialize ( SYS_MODULE_OBJ pmpDriverObject, const SYS_MODULE_INIT * const init ) init - Pointer to the initialization data structure DRV_PMP_Status Function Provides the current status of the PMP driver module. Implementation: Dynamic File drv_pmp.h C SYS_STATUS DRV_PMP_Status(const SYS_MODULE_OBJ pmpDriverObject); Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system level operation and cannot start another Description This function provides the current status of the PMP driver module. Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_STATUS_BUSY - Indicates that the driver is busy with a previous system level operation and cannot start another SYS_STATUS_ERROR - Indicates that the driver is in an error state Any value less than SYS_STATUS_ERROR is also an error state. SYS_MODULE_DEINITIALIZED - Indicates that the driver has been deinitialized This value is less than SYS_STATUS_ERROR. This operation can be used to determine when any of the driver's module level operations has completed. If the status operation returns SYS_STATUS_BUSY, a previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This function will NEVER block waiting for hardware. Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 694 If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Preconditions The DRV_PMP_Initialize function must have been called before calling this function. Example SYS_MODULE_OBJ pmpDriverObject; // Returned from DRV_PMP_Initialize SYS_STATUS status; status = DRV_PMP_Status(pmpDriverObject); else if (SYS_STATUS_ERROR >= status) { // Handle error } Parameters Parameters Description pmpDriverObject Driver object handle, returned from the DRV_PMP_Initialize routine Function SYS_STATUS DRV_PMP_Status ( SYS_MODULE_OBJ pmpDriverObject ) DRV_PMP_Tasks Function Maintains the driver's state machine and implements its ISR. Implementation: Dynamic File drv_pmp.h C void DRV_PMP_Tasks(SYS_MODULE_OBJ pmpDriverObject); Returns None. Description This function is used to maintain the queue and execute the tasks stored in the queue. It resides in the ISR of the PMP for interrupt-driven implementations. Remarks This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the appropriate raw ISR. This function may execute in an ISR context and will never block or access any resources that may cause it to block. Preconditions The DRV_PMP_Initialize function must have been called for the specified PMP driver instance. Example SYS_MODULE_OBJ pmpDriverObject; // Returned from DRV_PMP_Initialize while (true) { DRV_PMP_Tasks (pmpDriverObject); // Do other tasks } Parameters Parameters Description pmpDriverObject Object handle for the specified driver instance (returned from DRV_PMP_Initialize) Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 695 Function void DRV_PMP_Tasks ( SYS_MODULE_OBJ pmpDriverObject ); DRV_PMP_TimingSet Function Sets PMP timing parameters. Implementation: Static File drv_pmp.h C void DRV_PMP_TimingSet(PMP_DATA_WAIT_STATES dataWait, PMP_STROBE_WAIT_STATES strobeWait, PMP_DATA_HOLD_STATES dataHold); Returns None. Description This function sets the PMP timing parameters. Remarks None. Preconditions The DRV_PMP_Initialize function must have been called. Example DRV_PMP0_TimingSet(PMP_DATA_WAIT_THREE,PMP_STROBE_WAIT_6,PMP_DATA_HOLD_4); Parameters Parameters Description dataWait Data setup to read/write strobe wait states strobeWait Read/write strobe wait states dataHold Data hold time after read/write strobe wait states Function void DRV_PMP_TimingSet( PMP_DATA_WAIT_STATES dataWait, PMP_STROBE_WAIT_STATES strobeWait, PMP_DATA_HOLD_STATES dataHold ) b) Client Interaction Functions DRV_PMP_ClientStatus Function Gets the current client-specific status of the PMP driver. Implementation: Dynamic File drv_pmp.h C DRV_PMP_CLIENT_STATUS DRV_PMP_ClientStatus(DRV_HANDLE hClient); Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 696 Returns A DRV_PMP_CLIENT_STATUS value describing the current status of the driver. Description This function gets the client-specific status of the PMP driver associated with the specified handle. Remarks This function will not block for hardware access and will immediately return the current status. Preconditions The DRV_PMP_Initialize routine must have been called. DRV_PMP_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE hClient; // Returned from DRV_PMP_Open DRV_PMP_CLIENT_STATUS pmpClientStatus; pmpClientStatus = DRV_PMP_ClientStatus(hClient); if(DRV_PMP_CLIENT_STATUS_ERROR >= pmpClientStatus) { // Handle the error } Parameters Parameters Description hClient A valid open-instance handle, returned from the driver's open routine Function DRV_PMP_CLIENT_STATUS DRV_PMP_ClientStatus ( DRV_HANDLE hClient ) DRV_PMP_Close Function Closes an opened instance of the PMP driver. Implementation: Dynamic File drv_pmp.h C void DRV_PMP_Close(const DRV_HANDLE hClient); Returns None Description This function closes an opened instance of the PMP driver, invalidating the handle. Remarks After calling this function, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_PMP_Open before the caller may use the driver again. If DRV_IO_INTENT_BLOCKING was requested and the driver was built appropriately to support blocking behavior call may block until the operation is complete. If DRV_IO_INTENT_NON_BLOCKING request the driver client can call the DRV_PMP_Status operation to find out when the module is in the ready state (the handle is no longer valid). Usually there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_PMP_Initialize routine must have been called for the specified PMP driver instance. DRV_PMP_Open must have been called to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 697 Example DRV_HANDLE hClient; // Returned from DRV_PMP_Open DRV_PMP_Close(hClient); Parameters Parameters Description hClient A valid open instance handle, returned from the driver's open routine Function void DRV_PMP_Close ( DRV_HANDLE hClient ) DRV_PMP_ModeConfig Function Configures the PMP modes. Implementation: Static/Dynamic File drv_pmp.h C void DRV_PMP_ModeConfig(DRV_HANDLE hClient, DRV_PMP_MODE_CONFIG config); Returns None. Description This function configures the modes for client in which it wants to operate. Different master-slave modes, 8/16 data bits selection, address increment/decrement, interrupt mode, wait states, etc., can be configured through this function. Remarks This function will NEVER block waiting for hardware. If this API is called more than once for a particular client handle, previous config setting of that client will be overwritten. Preconditions Function DRV_PMP_Initialize must have been called. DRV_PMP_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE hClient; DRV_PMP_MODE_CONFIG config; config.chipSelect = PMCS1_AND_PMCS2_AS_CHIP_SELECT; config.endianMode = LITTLE_ENDIAN; config.incrementMode = PMP_ADDRESS_AUTO_INCREMENT; config.intMode = PMP_INTERRUPT_NONE; config.pmpMode = PMP_MASTER_READ_WRITE_STROBES_INDEPENDENT; config.portSize = PMP_DATA_SIZE_8_BITS; config.waitStates.dataHoldWait = PMP_DATA_HOLD_2; config.waitStates.dataWait = PMP_DATA_WAIT_THREE; config.waitStates.strobeWait = PMP_STROBE_WAIT_5; DRV_PMP_ModeConfig ( hClient, config ); Parameters Parameters Description hClient Client handle obtained from DRV_PMP_Open API config Structure which will have all the required PMP modes configuration Function void DRV_PMP_ModeConfig ( DRV_HANDLE hClient, DRV_PMP_MODE_CONFIG config ) Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 698 DRV_PMP_Open Function Opens the specified PMP driver instance and returns a handle to it. Implementation: Dynamic File drv_pmp.h C DRV_HANDLE DRV_PMP_Open(const SYS_MODULE_INDEX index, const DRV_IO_INTENT intent); Returns If successful, the function returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Description This function opens the specified PMP driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Remarks The handle returned is valid until the DRV_PMP_Close routine is called. This function will NEVER block waiting for hardware. If the DRV_IO_INTENT_BLOCKING is requested and the driver was built appropriately to support blocking behavior, other client-level operations may block waiting on hardware until they are complete. If DRV_IO_INTENT_NON_BLOCKING is requested the driver client can call the DRV_PMP_ClientStatus operation to find out when the module is in the ready state. If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. Preconditions The DRV_PMP_Initialize function must have been called before calling this function. Example DRV_HANDLE hClient; hClient = DRV_PMP_Open(DRV_PMP_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == hClient) { // Unable to open the driver } Parameters Parameters Description drvIndex Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT ORed together to indicate the intended use of the driver Function DRV_HANDLE DRV_PMP_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ) DRV_PMP_Read Function Read the data from external device. Implementation: Static/Dynamic File drv_pmp.h C PMP_QUEUE_ELEMENT_OBJECT* DRV_PMP_Read(DRV_HANDLE hClient, uint32_t address, uint16_t* buffer, uint32_t Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 699 nBytes); Returns Returns the position number of the queue, where the data element was stored. Returns '0' when there is no place in the queue to store the data. Description This function reads the given number of data bytes from the given address of the external device to the MCU buffer through the selected PMP instance. This function should be used for all the master and slave modes. Proper configuration should be done using DRV_PMP_ModeConfig before calling this function. Preconditions The DRV_PMP_Initialize routine must have been called. DRV_PMP_Open must have been called to obtain a valid opened device handle. DRV_PMP_ModeConfig must have been called to configure the desired mode Example DRV_HANDLE hClient; // Returned from DRV_PMP_Open uint32_t deviceAddress; uint32_t nBytes; unsigned char myBuffer[nBytes]; uint32_t transferID; transferID = DRV_PMP_Read ( hClient, deviceAddress, &myBuffer, nBytes); Parameters Parameters Description hClient A valid open-instance handle, returned from the driver's open routine address Starting address of the slave device from where data has to be read. It does not have any significance for legacy slave mode and buffer mode. In PMP enhanced slave mode i.e. addressable buffer slave mode, this parameter should be the buffer number to be used. buffer Pointer to the buffer into which the data read through the PMP instance will be placed. Even if only one word has to be transferred, pointer should be used. nBytes Number of bytes that need to be read through the PMP instance Function uint32_t DRV_PMP_Read ( DRV_HANDLE hClient, uint32_t address, unsigned char* buffer, uint32_t nBytes) DRV_PMP_Write Function Transfers the data from the MCU to the external device. Implementation: Static/Dynamic File drv_pmp.h C PMP_QUEUE_ELEMENT_OBJECT* DRV_PMP_Write(DRV_HANDLE* hClient, bool address, uint32_t * buffer, uint32_t nBytes, uint32_t repeatCount); Returns Returns a 32-bit ID with which status of the transfer can be checked later. Returns '0' when there is no place in the queue to store the data. Description This function transfer the given number of data bytes from the MCU buffer location to the defined address of the external device through the selected PMP instance. It repeats the operation n (=repeatCount) number of times as well. This function should be used for all the master and slave modes. Proper configuration should be done using DRV_PMP_ModeConfig before calling this function. Preconditions The DRV_PMP_Initialize routine must have been called. DRV_PMP_Open must have been called to obtain a valid opened device handle. DRV_PMP_ModeConfig must have been called to configure the desired mode. Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 700 Example DRV_HANDLE hClient; // Returned from DRV_PMP_Open uint32_t deviceAddress; uint32_t nBytes; unsigned char myBuffer[nBytes]; uint32_t repeatCount; uint32_t transferID; transferID = DRV_PMP_MasterWrite ( hClient, deviceAddress, &myBuffer, nBytes, repeatCount); Parameters Parameters Description hClient A valid open-instance handle, returned from the driver's open routine address Starting address of the slave device where data has to be written. It does not have any significance for legacy slave mode and buffer mode. In PMP enhanced slave mode (i.e., addressable buffer slave mode), this parameter should be the buffer number to be used. buffer Pointer to MCU Buffer from which the data will be written through the PMP instance. even if only one word has to be transferred, pointer should be used. nBytes Total number of bytes that need to be written through the PMP instance repeatCount Number of times the data set (nBytes of data) to be repeatedly written. This value should be 0 if user does not want any repetition. If repeatCount is greater than 0, then after writing every nBytes of data, the buffer starts pointing to its first element. Ideally, PMP Address should be in auto increment/decrement mode for repeatCount greater than 0. Function uint32_t DRV_PMP_Write ( DRV_HANDLE hClient, uint32_t address, unsigned char* buffer, uint32_t nBytes, uint32_t repeatCount) c) Client Transfer Functions DRV_PMP_TransferStatus Function Returns the transfer status. Implementation: Dynamic File drv_pmp.h C DRV_PMP_TRANSFER_STATUS DRV_PMP_TransferStatus(PMP_QUEUE_ELEMENT_OBJECT* queueObject); Returns A DRV_PMP_TRANSFER_STATUS value describing the current status of the transfer. Description This function returns the status of a particular transfer whose ID has been specified as input. Example uint32_8 seqID; DRV_PMP_TRANSFER_STATUS transferStatus; transferStatus = DRV_PMP_TransferStatus( DRV_PMP_INDEX_0, seqID); Parameters Parameters Description drvIndex Identifier for the object instance to be opened Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 701 seqID A valid ID returned from read/write transfer functions Function DRV_PMP_TRANSFER_STATUS DRV_PMP_TransferStatus( DRV_HANDLE hClient ) d) Miscellaneous Functions e) Data Types and Constants DRV_PMP_INDEX_COUNT Macro Number of valid PMP driver indices. File drv_pmp.h C #define DRV_PMP_INDEX_COUNT _PMP_EXISTS Description PMP Driver Module Index Count This constant identifies the number of valid PMP driver indices. Remarks The value of "_PMP_EXISTS" is derived from device-specific header files defined as part of the peripheral libraries. DRV_PMP_CHIPX_STROBE_MODE Enumeration PMP writeEnable/ReadWrite strobes. File drv_pmp.h C typedef enum { PMP_RW_STROBE_WITH_ENABLE_STROBE, PMP_READ_AND_WRITE_STROBES } DRV_PMP_CHIPX_STROBE_MODE; Members Members Description PMP_RW_STROBE_WITH_ENABLE_STROBE One strobe for read/write and another for enable PMP_READ_AND_WRITE_STROBES Separate strobes for read and write operations Description PMP writeEnable/ReadWrite strobes This enumeration provides ReadWrite/WriteEnable Strobe definitions. DRV_PMP_CLIENT_STATUS Enumeration PMP client status definitions. File drv_pmp.h C typedef enum { DRV_PMP_CLIENT_STATUS_INVALID, PMP_CLIENT_STATUS_CLOSED, Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 702 DRV_PMP_CLIENT_STATUS_OPEN } DRV_PMP_CLIENT_STATUS; Description PMP Client Status This enumeration provides various client status possibilities. DRV_PMP_ENDIAN_MODE Enumeration PMP Endian modes. File drv_pmp.h C typedef enum { LITTLE, BIG } DRV_PMP_ENDIAN_MODE; Members Members Description LITTLE Little Endian BIG Big Endian Description PMP Endian modes This enumeration holds the Endian configuration options. DRV_PMP_INDEX Enumeration PMP driver index definitions. File drv_pmp.h C typedef enum { DRV_PMP_INDEX_0, DRV_PMP_INDEX_1 } DRV_PMP_INDEX; Members Members Description DRV_PMP_INDEX_0 First PMP instance DRV_PMP_INDEX_1 Second PMP instance (not available for now) Description PMP Driver Module Index Numbers These constants provide PMP driver index definitions. Remarks These values should be passed into the DRV_PMP_Initialize and DRV_PMP_Open functions to identify the driver instance in use. DRV_PMP_INIT Structure Defines the PMP driver initialization data. File drv_pmp.h Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 703 C typedef struct { SYS_MODULE_INIT moduleInit; PMP_MODULE_ID pmpID; bool stopInIdle; PMP_MUX_MODE muxMode; PMP_INPUT_BUFFER_TYPE inputBuffer; DRV_PMP_POLARITY_OBJECT polarity; DRV_PMP_PORTS ports; } DRV_PMP_INIT; Members Members Description SYS_MODULE_INIT moduleInit; module power state info PMP_MODULE_ID pmpID; module PLIB ID bool stopInIdle; Stop in Idle enable PMP_MUX_MODE muxMode; MUX mode PMP_INPUT_BUFFER_TYPE inputBuffer; Input buffer type to be used DRV_PMP_POLARITY_OBJECT polarity; Polarity settings DRV_PMP_PORTS ports; PMP port settings Description PMP Driver Initialize Data This data type defines data required to initialize or reinitialize the PMP driver. Remarks Not all the initialization features are available for all devices. DRV_PMP_MODE_CONFIG Structure PMP modes configuration. File drv_pmp.h C typedef struct { PMP_OPERATION_MODE pmpMode; PMP_INTERRUPT_MODE intMode; PMP_INCREMENT_MODE incrementMode; DRV_PMP_ENDIAN_MODE endianMode; PMP_DATA_SIZE portSize; DRV_PMP_WAIT_STATES waitStates; PMP_CHIPSELECT_FUNCTION chipSelect; } DRV_PMP_MODE_CONFIG; Members Members Description PMP_OPERATION_MODE pmpMode; PMP Usage Mode Type PMP_INTERRUPT_MODE intMode; Interrupt mode PMP_INCREMENT_MODE incrementMode; should be appropriately selected based on read/write requirements and operation mode setting */ address/buffer increment mode DRV_PMP_ENDIAN_MODE endianMode; it does not have any significance in PMP slave mode or 8bit data mode */ Endian modes PMP_DATA_SIZE portSize; Data Port Size DRV_PMP_WAIT_STATES waitStates; Wait states PMP_CHIPSELECT_FUNCTION chipSelect; use this when PLIB is fixed Description PMP modes configuration This data type controls the configuration of PMP modes. Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 704 DRV_PMP_POLARITY_OBJECT Structure PMP polarity object. File drv_pmp.h C typedef struct { PMP_POLARITY_LEVEL addressLatchPolarity; PMP_POLARITY_LEVEL byteEnablePolarity; PMP_POLARITY_LEVEL rwStrobePolarity; PMP_POLARITY_LEVEL writeEnableStrobePolarity; PMP_POLARITY_LEVEL chipselect1Polarity; PMP_POLARITY_LEVEL chipselect2Polarity; } DRV_PMP_POLARITY_OBJECT; Members Members Description PMP_POLARITY_LEVEL addressLatchPolarity; Address latch polarity PMP_POLARITY_LEVEL byteEnablePolarity; ByteEnable port polarity PMP_POLARITY_LEVEL rwStrobePolarity; Read/Write strobe polarity PMP_POLARITY_LEVEL writeEnableStrobePolarity; Write/Enable strobe polarity PMP_POLARITY_LEVEL chipselect1Polarity; ChipSelect-1 Polarity PMP_POLARITY_LEVEL chipselect2Polarity; chipSelect-2 Polarity Description PMP polarity object This structure holds the polarities of different entities to be configured. DRV_PMP_PORT_CONTROL Enumeration PMP port enable/disable definitions. File drv_pmp.h C typedef enum { PORT_ENABLE, PORT_DISABLE } DRV_PMP_PORT_CONTROL; Members Members Description PORT_ENABLE Enable the given port PORT_DISABLE Disable the given port Description PMP port enable/disable. This enumeration provides port enable/disable values. DRV_PMP_PORTS Structure PMP port configuration. File drv_pmp.h Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 705 C typedef struct { PMP_ADDRESS_PORT addressPortsMask; PMP_PMBE_PORT byteEnablePort; DRV_PMP_PORT_CONTROL readWriteStrobe; DRV_PMP_PORT_CONTROL writeEnableStrobe; } DRV_PMP_PORTS; Members Members Description PMP_ADDRESS_PORT addressPortsMask; User needs to put the address lines which he wants to use in ORed fashion * Address ports PMP_PMBE_PORT byteEnablePort; Byte enable ports DRV_PMP_PORT_CONTROL readWriteStrobe; READ/WRITE Strobe PORT DRV_PMP_PORT_CONTROL writeEnableStrobe; WRITE/ENABLE strobe port Description PMP Ports This structure holds the ports (including the address ports) to be configured by the application to function as general purpose I/O (GPIO) or part of the PMP. DRV_PMP_QUEUE_ELEMENT_OBJ Structure Defines the object for PMP queue element. File drv_pmp.h C typedef struct _DRV_PMP_QUEUE_ELEMENT_OBJ { struct _DRV_PMP_CLIENT_OBJ * hClient; uint32_t buffer; uint16_t* addressBuffer; uint32_t nTransfers; int32_t nRepeats; DRV_PMP_TRANSFER_TYPE type; } DRV_PMP_QUEUE_ELEMENT_OBJ; Members Members Description struct _DRV_PMP_CLIENT_OBJ * hClient; handle of the client object returned from open API uint32_t buffer; pointer to the buffer holding the transmitted data uint16_t* addressBuffer; pointer to the buffer holding the transmitted data uint32_t nTransfers; number of bytes to be transferred int32_t nRepeats; number of times the data set has to be transferred repeatedly DRV_PMP_TRANSFER_TYPE type; PMP Read or Write Description PMP Driver Queue Element Object This defines the object structure for each queue element of PMP. This object gets created for every Read/Write operations APIs. Remarks None DRV_PMP_TRANSFER_STATUS Enumeration Defines the PMP transfer status. File drv_pmp.h Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 706 C typedef enum { MASTER_8BIT_TRANSFER_IN_PROGRESS = PMP_DATA_SIZE_8_BITS, MASTER_16BIT_TRANSFER_IN_PROGRESS = PMP_DATA_SIZE_16_BITS, MASTER_8BIT_BUFFER_IN_PROGRESS, MASTER_16BIT_BUFFER_IN_PROGRESS, MASTER_8BIT_TRANSFER_CONTINUE, MASTER_8BIT_BUFFER_CONTINUE, QUEUED_BUT_PMP_TRANSFER_NOT_STARTED, PMP_TRANSFER_FINISHED } DRV_PMP_TRANSFER_STATUS; Description Queue Element Transfer Status This enumeration defines the PMP transfer status. DRV_PMP_WAIT_STATES Structure PMP wait states object. File drv_pmp.h C typedef struct { PMP_DATA_HOLD_STATES dataHoldWait; PMP_STROBE_WAIT_STATES strobeWait; PMP_DATA_WAIT_STATES dataWait; } DRV_PMP_WAIT_STATES; Members Members Description PMP_DATA_HOLD_STATES dataHoldWait; data hold wait states PMP_STROBE_WAIT_STATES strobeWait; read/write strobe wait states PMP_DATA_WAIT_STATES dataWait; data wait strobe wait sates Description PMP wait states object This structure holds the different wait states to be configured. Refer to the PMP PLIB help document for the possible values and meaning of the different wait states. MAX_NONBUFFERED_BYTE_COUNT Macro File drv_pmp.h C #define MAX_NONBUFFERED_BYTE_COUNT 4 /********************************************************************** After this number the PMP transfer should be polled to guarantee data transfer ********************************************************************* */ Description After this number the PMP transfer should be polled to guarantee data transfer DRV_PMP_TRANSFER_TYPE Enumeration File drv_pmp.h Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 707 C typedef enum { ADDRESS, READ, WRITE, BUFFERED_WRITE } DRV_PMP_TRANSFER_TYPE; Members Members Description ADDRESS PMP Address needs to be updated READ PMP Read Transfer WRITE PMP Write Transfer BUFFERED_WRITE PMP Array Write Transfer Description This is type DRV_PMP_TRANSFER_TYPE. PMP_QUEUE_ELEMENT_OBJECT Structure Defines the structure required for maintaining the queue element. File drv_pmp.h C typedef struct { DRV_PMP_QUEUE_ELEMENT_OBJ data; DRV_PMP_TRANSFER_STATUS eTransferStatus; uint32_t nTransfersDone; } PMP_QUEUE_ELEMENT_OBJECT; Members Members Description DRV_PMP_QUEUE_ELEMENT_OBJ data; The PMP Q Element DRV_PMP_TRANSFER_STATUS eTransferStatus; Flag to indicate that the element is in use uint32_t nTransfersDone; sequence id Description Queue Element Object This defines the structure required for maintaining the queue element. Remarks None Files Files Name Description drv_pmp.h Parallel Master Port (PMP) device driver interface file. drv_pmp_config.h PMP driver configuration definitions template Description This section lists the source and header files used by the PMP Driver Library. drv_pmp.h Parallel Master Port (PMP) device driver interface file. Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 708 Enumerations Name Description DRV_PMP_CHIPX_STROBE_MODE PMP writeEnable/ReadWrite strobes. DRV_PMP_CLIENT_STATUS PMP client status definitions. DRV_PMP_ENDIAN_MODE PMP Endian modes. DRV_PMP_INDEX PMP driver index definitions. DRV_PMP_PORT_CONTROL PMP port enable/disable definitions. DRV_PMP_TRANSFER_STATUS Defines the PMP transfer status. DRV_PMP_TRANSFER_TYPE This is type DRV_PMP_TRANSFER_TYPE. Functions Name Description DRV_PMP_ClientStatus Gets the current client-specific status of the PMP driver. Implementation: Dynamic DRV_PMP_Close Closes an opened instance of the PMP driver. Implementation: Dynamic DRV_PMP_Deinitialize Deinitializes the specified instance of the PMP driver module. Implementation: Dynamic DRV_PMP_Initialize Initializes the PMP driver. Implementation: Static/Dynamic DRV_PMP_ModeConfig Configures the PMP modes. Implementation: Static/Dynamic DRV_PMP_Open Opens the specified PMP driver instance and returns a handle to it. Implementation: Dynamic DRV_PMP_Read Read the data from external device. Implementation: Static/Dynamic DRV_PMP_Reinitialize Reinitializes the driver and refreshes any associated hardware settings. Implementation: Dynamic DRV_PMP_Status Provides the current status of the PMP driver module. Implementation: Dynamic DRV_PMP_Tasks Maintains the driver's state machine and implements its ISR. Implementation: Dynamic DRV_PMP_TimingSet Sets PMP timing parameters. Implementation: Static DRV_PMP_TransferStatus Returns the transfer status. Implementation: Dynamic DRV_PMP_Write Transfers the data from the MCU to the external device. Implementation: Static/Dynamic Macros Name Description DRV_PMP_INDEX_COUNT Number of valid PMP driver indices. MAX_NONBUFFERED_BYTE_COUNT After this number the PMP transfer should be polled to guarantee data transfer Structures Name Description _DRV_PMP_QUEUE_ELEMENT_OBJ Defines the object for PMP queue element. DRV_PMP_INIT Defines the PMP driver initialization data. DRV_PMP_MODE_CONFIG PMP modes configuration. DRV_PMP_POLARITY_OBJECT PMP polarity object. DRV_PMP_PORTS PMP port configuration. DRV_PMP_QUEUE_ELEMENT_OBJ Defines the object for PMP queue element. DRV_PMP_WAIT_STATES PMP wait states object. PMP_QUEUE_ELEMENT_OBJECT Defines the structure required for maintaining the queue element. Volume V: MPLAB Harmony Framework Driver Libraries Help Parallel Master Port (PMP) Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 709 Description PMP Device Driver Interface The PMP device driver provides a simple interface to manage the Parallel Master and Slave ports. This file defines the interface definitions and prototypes for the PMP driver. File Name drv_pmp.h Company Microchip Technology Inc. drv_pmp_config.h PMP driver configuration definitions template Macros Name Description DRV_PMP_CLIENTS_NUMBER Selects the maximum number of clients. DRV_PMP_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver. DRV_PMP_QUEUE_SIZE PMP queue size for different instances. Description PMP Driver Configuration Definitions for the Template Version These definitions statically define the driver's mode of operation. File Name drv_pmp_config_template.h Company Microchip Technology Inc. RTCC Driver Library This section describes the RTCC Driver Library. Introduction The Real-Time Clock Calendar (RTCC) Static Driver provides a high-level interface to manage the RTCC module on the Microchip family of microcontrollers. Description Through the MHC, this driver provides APIs for the following: • Initializing the module • Starting/Stopping the RTCC • Status functions to yield the date/time • Status functions to yield the alarm date/time • Clock output control Library Interface System Interaction Functions Name Description DRV_RTCC_AlarmDateGet Gets the Alarm Date of the RTCC. Implementation: Static DRV_RTCC_AlarmTimeGet Gets the Alarm Time of the RTCC. Implementation: Static Volume V: MPLAB Harmony Framework Driver Libraries Help RTCC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 710 DRV_RTCC_ClockOutput Enables Clock Output for the RTCC. Implementation: Static DRV_RTCC_DateGet Gets the Date of the RTCC. Implementation: Static DRV_RTCC_Initialize Initializes the RTCC instance for the specified driver index. Implementation: Static DRV_RTCC_Start Starts the RTCC. Implementation: Static DRV_RTCC_Stop Stops the RTCC. Implementation: Static DRV_RTCC_TimeGet Gets the time of the RTCC. Implementation: Static Description This section describes the Application Programming Interface (API) functions of the RTCC Driver Library. System Interaction Functions DRV_RTCC_AlarmDateGet Function Gets the Alarm Date of the RTCC. Implementation: Static File help_drv_rtcc.h C uint32_t DRV_RTCC_AlarmDateGet(); Returns uint32_t alarm date value Description This routine gets the RTCC alarm date. Remarks None. Preconditions DRV_RTCC_Initialize has been called. Function uint32_t DRV_RTCC_AlarmDateGet( void ) DRV_RTCC_AlarmTimeGet Function Gets the Alarm Time of the RTCC. Implementation: Static File help_drv_rtcc.h C uint32_t DRV_RTCC_AlarmTimeGet(); Returns uint32_t alarm time value Volume V: MPLAB Harmony Framework Driver Libraries Help RTCC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 711 Description This routine gets the RTCC alarm time. Remarks None. Preconditions DRV_RTCC_Initialize has been called. Function uint32_t DRV_RTCC_AlarmTimeGet( void ) DRV_RTCC_ClockOutput Function Enables Clock Output for the RTCC. Implementation: Static File help_drv_rtcc.h C void DRV_RTCC_ClockOutput(); Returns None. Description This routine enables the clock output for the RTCC Remarks None. Preconditions DRV_RTCC_Initialize has been called. Function void DRV_RTCC_ClockOutput( void ) DRV_RTCC_DateGet Function Gets the Date of the RTCC. Implementation: Static File help_drv_rtcc.h C uint32_t DRV_RTCC_DateGet(); Returns uint32_t date value Description This routine gets the RTCC date. Remarks None. Preconditions DRV_RTCC_Initialize has been called. Volume V: MPLAB Harmony Framework Driver Libraries Help RTCC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 712 Function uint32_t DRV_RTCC_DateGet( void ) DRV_RTCC_Initialize Function Initializes the RTCC instance for the specified driver index. Implementation: Static File help_drv_rtcc.h C void DRV_RTCC_Initialize(); Returns None. Description This routine initializes the RTCC driver instance for the specified driver instance, making it ready for clients to use it. The initialization routine is specified by the MHC parameters. Remarks This routine must be called before any other RTCC routine is called. This routine should only be called once during system initialization. Preconditions None. Function void DRV_RTCC_Initialize( void ) DRV_RTCC_Start Function Starts the RTCC. Implementation: Static File help_drv_rtcc.h C void DRV_RTCC_Start(); Returns None. Description This routine starts the RTCC, making it ready for clients to use it. Remarks None. Preconditions DRV_RTCC_Initialize has been called. Function void DRV_RTCC_Start( void ) DRV_RTCC_Stop Function Stops the RTCC. Implementation: Static Volume V: MPLAB Harmony Framework Driver Libraries Help RTCC Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 713 File help_drv_rtcc.h C void DRV_RTCC_Stop(); Returns None. Description This routine stops the RTCC. Remarks None. Preconditions DRV_RTCC_Initialize has been called. Function void DRV_RTCC_Stop( void ) DRV_RTCC_TimeGet Function Gets the time of the RTCC. Implementation: Static File help_drv_rtcc.h C uint32_t DRV_RTCC_TimeGet(); Returns uint32_t time value Description This routine gets the RTCC time. Remarks None. Preconditions DRV_RTCC_Initialize has been called. Function uint32_t DRV_RTCC_TimeGet( void ) Secure Digital (SD) Card Driver Library This section describes the Secure Digital (SD) Card Driver Library. Introduction The SD Card driver provides the necessary interfaces to interact with an SD card. It provides the necessary abstraction for the higher_layer. Description A SD Card is a non-volatile memory (Flash memory) card designed to provide high-capacity memory in a small size. Its applications include digital video camcorders, digital cameras, handheld computers, audio players, and mobile phones. Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 714 Using the Library This topic describes the basic architecture of the SD Card Driver Library and provides information and examples on its use. Description Interface Header File: drv_sdcard.h The interface to the SD Card Driver library is defined in the drv_sdcard.h header file. This file is included by the drv.h file. Any C language source (.c) file that uses the SD Card Driver library should include drv.h. Please refer to the What is MPLAB Harmony? section for how the Driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the SD Card Driver Library 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 SD Card driver comes in the_layer below the Partition Manager in the MPLAB Harmony file system architecture and it uses the SPI Driver to interact with the SD card. SD Card Driver Software Abstraction Block Diagram Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 715 Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the SD Card module. Library Interface Section Description System Level Functions Includes functions for initialize the module. Client Level Functions Functions to open and close a client. Operation Functions Functions for read and write operations Module Information Functions Functions for information about the module. Version Information Functions Functions to get the software version. How the Library Works This section describes how the SD Card Driver Library operates. Description Note: Not all modes are available on all devices. Please refer to the specific device data sheet to determine the supported modes. The library provides interfaces that support: • Driver Initialization Functionality • Client Block Data Functionality • Client Access Functionality Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 716 SD Card Driver Initialization This section provides information for system initialization and reinitialization. Description The system performs the initialization and the reinitialization of the device driver with settings that affect only the instance of the device that is being initialized or reinitialized. During system initialization each instance of the SD Card module would be initialized with the following configuration settings (either passed dynamically at run time using DRV_SDCARD_INIT or by using initialization overrides) that are supported by the specific SD Card device hardware: • SPI Peripheral ID: Identifies the SPI Peripheral ID to be used for the SD Card Driver • SPI Index: SPI Driver Index • SD Card frequency: SD Card communication speed • SPI Clock source: Peripheral clock used by the SPI • Write-Protect Port: Port used to check if the SD Card is write protected • Write-Protect Pin: Pin used to check if the SD Card is write protected • Chip Select Port: Port used for the SPI Chip Select • Chip Select Pin: Pin used for the SPI Chip Select The DRV_SDCARD_Initialize function returns an object handle of the type SYS_MODULE_OBJ. After this, the object handle returned by the initialize interface would be used by the other system interfaces, such as DRV_SDCARD_Deinitialize, DRV_SDCARD_Status, and DRV_SDCARD_Tasks. Note: The system initialization and the reinitialization settings, only affect the instance of the peripheral that is being initialized or reinitialized. Example: const DRV_SDCARD_INIT drvSDCardInit = { .spiId = SPI_ID_2, .spiIndex = 0, .sdcardSpeedHz = 20000000, .spiClk = CLK_BUS_PERIPHERAL_2, .writeProtectPort = PORT_CHANNEL_F, .writeProtectBitPosition = PORTS_BIT_POS_1, .chipSelectPort = PORT_CHANNEL_B, .chipSelectBitPosition = PORTS_BIT_POS_14, }; void SYS_Initialize (void *data) { . . sysObj.drvSDCard = DRV_SDCARD_Initialize(DRV_SDCARD_INDEX_0,(SYS_MODULE_INIT *)&drvSDCardInit); . . } Tasks Routine The system will call DRV_SDCARD_Tasks, from system task service to maintain the driver's state machine. Client Access Operation This section provides information for general client operation. Description General Client Operation For the application to start using an instance of the module, it must call the DRV_SDCARD_Open function. This provides the configuration required to open the SD Card instance for operation. If the driver is deinitialized using the function DRV_SDCARD_Deinitialize, the application must call the DRV_SDCARD_Open function again to set up the instance of the SDCARD. For the various options available for I/O INTENT please refer to Data Types and Constants in the Library Interface section. Example: DRV_HANDLE handle; handle = DRV_SDCARD_Open(DRV_SDCARD_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 717 if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } Client Block Data Operation This topic provides information on client block data operation. Description The SDCARD Driver provides a block interface to access the SD Card. The interface provides functionality to read from and write to the SD Card. Reading Data from the SD Card: The following steps outline the sequence to be followed for reading data from the SD Card: 1. The system should have completed necessary initialization and DRV_SDCARD_Tasks should either be running in a polled environment, or in an interrupt environment. 2. The driver should have been opened with the necessary intent. 3. Invoke the DRV_SDCARD_Read function and pass the pointer where the data is to be stored, block start address and the number of blocks of data to be read. 4. The client should validate the command handle returned by the DRV_SDCARD_Read function. DRV_SDCARD_COMMAND_HANDLE_INVALID value indicates that an error has occurred which the client needs to handle. 5. If the request was successful then the client can check the status of the request by invoking the DRV_SDCARD_CommandStatus and passing the command handle returned by the read request. Alternately the client could use the event handler for notifications from the driver. 6. The client will be able to close itself by calling the DRV_SDCARD_Close. Example: // This code shows how to read data from the SD Card DRV_HANDLE sdcardHandle; DRV_SDCARD_COMMAND_HANDLE sdcardCommandHandle; DRV_SDCARD_COMMAND_STATUS commandStatus; uint8_t readBuf[512]; uint32_t blockAddress; uint32_t nBlocks; /* Initialize the block start address and the number of blocks to be read */ blockAddress = 0; nBlocks = 1; DRV_SDCARD_Read(sdcardHandle, &sdcardCommandHandle, (uint8_t *)readBuf, blockAddress, nBlocks); if(DRV_SDCARD_COMMAND_HANDLE_INVALID == sdcardCommandHandle) { /* Failed to queue the read request. Handle the error. */ } // Wait until the command completes. This should not // be a while loop if part of cooperative multi-tasking // routine. In that case, it should be invoked in task // state machine. commandStatus = DRV_SDCARD_CommandStatus(sdcardHandle, sdcardCommandHandle); if(DRV_SDCARD_COMMAND_COMPLETED == commandStatus) { /* Read completed */ } else if (DRV_SDCARD_COMMAND_ERROR_UNKNOWN == commandStatus) { /* Read Failed */ } Writing Data to the SD Card: The following steps outline the sequence to be followed for writing data to the SD Card: 1. The system should have completed necessary initialization and DRV_SDCARD_Tasks should either be running in a polled environment, or in an interrupt environment. 2. The driver should have been opened with the necessary intent. 3. Invoke the DRV_SDCARD_Write function and pass the pointer to the data to be written, block start address and the number of blocks of data to be written. 4. The client should validate the command handle returned by the DRV_SDCARD_Write function. DRV_SDCARD_COMMAND_HANDLE_INVALID value indicates that an error has occurred which the client needs to handle. 5. If the request was successful then the client can check the status of the request by invoking the DRV_SDCARD_CommandStatus and passing the command handle returned by the write request. Alternately, the client could use the event handler for notifications from the driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 718 6. The client will be able to close itself by calling the DRV_SDCARD_Close. Example: // This code shows how to write data to the SD Card DRV_HANDLE sdcardHandle; DRV_SDCARD_COMMAND_HANDLE sdcardCommandHandle; DRV_SDCARD_COMMAND_STATUS commandStatus; uint8_t writeBuf[512]; uint32_t blockAddress; uint32_t nBlocks; /* Initialize the block start address and the number of blocks to be written */ blockAddress = 0; nBlocks = 1; /* Populate writeBuf with the data to be written */ DRV_SDCARD_Write(sdcardHandle, &sdcardCommandHandle, (uint8_t *)writeBuf, blockAddress, nBlocks); if(DRV_SDCARD_COMMAND_HANDLE_INVALID == sdcardCommandHandle) { /* Failed to queue the write request. Handle the error. */ } // Wait until the command completes. This should not // be a while loop if part of cooperative multi-tasking // routine. In that case, it should be invoked in task // state machine. commandStatus = DRV_SDCARD_CommandStatus(sdcardHandle, sdcardCommandHandle); if(DRV_SDCARD_COMMAND_COMPLETED == commandStatus) { /* Write completed */ } else if (DRV_SDCARD_COMMAND_ERROR_UNKNOWN == commandStatus) { /* Write Failed */ } Configuring the Library Macros Name Description DRV_SDCARD_CLIENTS_NUMBER Selects the miximum number of clients DRV_SDCARD_INDEX_MAX SD Card Static Index selection DRV_SDCARD_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver DRV_SDCARD_POWER_STATE Defines an override of the power state of the SD Card driver. DRV_SDCARD_SYS_FS_REGISTER Register to use with the File system DRV_SDCARD_ENABLE_WRITE_PROTECT_CHECK Enable SD Card write protect check. Description The configuration of the SD Card Driver is based on the file system_config.h. This header file contains the configuration selection for the SD Card Driver. Based on the selections made, the SD Card Driver may support the selected features. These configuration settings will apply to all instances of the SD Card. 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. DRV_SDCARD_CLIENTS_NUMBER Macro Selects the miximum number of clients File drv_sdcard_config_template.h C #define DRV_SDCARD_CLIENTS_NUMBER 1 Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 719 Description SD Card Maximum Number of Clients This definition select the maximum number of clients that the SD Card driver can support at run time. Not defining it means using a single client. Remarks None. DRV_SDCARD_INDEX_MAX Macro SD Card Static Index selection File drv_sdcard_config_template.h C #define DRV_SDCARD_INDEX_MAX 1 Description SD Card Static Index Selection SD Card Static Index selection for the driver object reference Remarks This index is required to make a reference to the driver object DRV_SDCARD_INSTANCES_NUMBER Macro Selects the maximum number of hardware instances that can be supported by the dynamic driver File drv_sdcard_config_template.h C #define DRV_SDCARD_INSTANCES_NUMBER 1 Description SD Card hardware instance configuration This definition selects the maximum number of hardware instances that can be supported by the dynamic driver. Not defining it means using a static driver. Remarks None DRV_SDCARD_POWER_STATE Macro Defines an override of the power state of the SD Card driver. File drv_sdcard_config_template.h C #define DRV_SDCARD_POWER_STATE SYS_MODULE_POWER_IDLE_STOP Description SD Card power state configuration Defines an override of the power state of the SD Card driver. Remarks This feature may not be available in the device or the SD Card module selected. Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 720 DRV_SDCARD_SYS_FS_REGISTER Macro Register to use with the File system File drv_sdcard_config_template.h C #define DRV_SDCARD_SYS_FS_REGISTER Description SDCARD Driver Register with File System Specifying this macro enables the SDCARD driver to register its services with the SYS FS. Remarks This macro is optional and should be specified only if the SDCARD driver is to be used with the File System. DRV_SDCARD_ENABLE_WRITE_PROTECT_CHECK Macro Enable SD Card write protect check. File drv_sdcard_config_template.h C #define DRV_SDCARD_ENABLE_WRITE_PROTECT_CHECK Description SDCARD Driver Enable Write Protect Check Specifying this macro enables the SDCARD driver to check whether the SD card is write protected. Remarks None Building the Library This section lists the files that are available in the SD Card Driver Library. 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 /framework/driver/sdcard. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_sdcard.h This file provides the interface definitions of the SD Card driver 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 /src/dynamic/drv_sdcard.c This file contains the core implementation of the SD Card driver. Optional File(s) This table lists and describes the source and header files that may optionally be included if required for the desired implementation. Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 721 Source File Name Description N/A No optional files are available for this library Module Dependencies The SD Card Driver Library depends on the following modules: • SPI Driver Library • Clock System Service Library • Interrupt System Service Library • Ports System Service Library • Timer System Service Library • Timer Driver Library Library Interface a) System Level Functions Name Description DRV_SDCARD_Initialize Initializes the SD Card driver. Implementation: Dynamic DRV_SDCARD_Deinitialize Deinitializes the specified instance of the SD Card driver module. Implementation: Dynamic DRV_SDCARD_Reinitialize Reinitializes the driver and refreshes any associated hardware settings. Implementation: Dynamic DRV_SDCARD_Status Provides the current status of the SD Card driver module. Implementation: Dynamic DRV_SDCARD_Tasks Maintains the driver's state machine. Implementation: Dynamic b) Client Level Functions Name Description DRV_SDCARD_Close Closes an opened-instance of the SD Card driver. Implementation: Dynamic DRV_SDCARD_Open Opens the specified SD Card driver instance and returns a handle to it. Implementation: Dynamic DRV_SDCARD_Read Reads blocks of data from the specified block address of the SD Card. DRV_SDCARD_Write Writes blocks of data starting at the specified address of the SD Card. DRV_SDCARD_EventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. c) Status Functions Name Description DRV_SDCARD_IsAttached Returns the physical attach status of the SD Card. DRV_SDCARD_IsWriteProtected Returns the write protect status of the SDCARD. DRV_SDCARD_CommandStatus Gets the current status of the command. DRV_SDCARD_GeometryGet Returns the geometry of the device. d) Data Types and Constants Name Description DRV_SDCARD_INDEX_0 SD Card driver index definitions DRV_SDCARD_INDEX_COUNT Number of valid SD Card driver indices DRV_SDCARD_INIT Contains all the data necessary to initialize the SD Card device _DRV_SDCARD_INIT Contains all the data necessary to initialize the SD Card device SDCARD_DETECTION_LOGIC Defines the different system events SDCARD_MAX_LIMIT Maximum allowed SD card instances DRV_SDCARD_INDEX_1 This is macro DRV_SDCARD_INDEX_1. DRV_SDCARD_INDEX_2 This is macro DRV_SDCARD_INDEX_2. DRV_SDCARD_INDEX_3 This is macro DRV_SDCARD_INDEX_3. Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 722 DRV_SDCARD_COMMAND_HANDLE_INVALID SDCARD Driver's Invalid Command Handle. DRV_SDCARD_COMMAND_HANDLE Handle identifying commands queued in the driver. DRV_SDCARD_COMMAND_STATUS Identifies the possible events that can result from a request. DRV_SDCARD_EVENT Identifies the possible events that can result from a request. DRV_SDCARD_EVENT_HANDLER Pointer to a SDCARDDriver Event handler function Description This section describes the Application Programming Interface (API) functions of the SD Card Driver. Refer to each section for a detailed description. a) System Level Functions DRV_SDCARD_Initialize Function Initializes the SD Card driver. Implementation: Dynamic File drv_sdcard.h C SYS_MODULE_OBJ DRV_SDCARD_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT *const init); Returns If successful, returns a valid handle to a driver object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the SD Card driver, making it ready for clients to open and use the driver. Remarks This routine must be called before any other SD Card routine is called. This routine should only be called once during system initialization unless DRV_SDCARD_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. If the operation requires time to allow the hardware to reinitialize, it will be reported by the DRV_SDCARD_Status operation. The system must use DRV_SDCARD_Status to find out when the driver is in the ready state. Preconditions None. Example DRV_SDCARD_INIT init; SYS_MODULE_OBJ objectHandle; // Populate the SD Card initialization structure objectHandle = DRV_SDCARD_Initialize(DRV_SDCARD_INDEX_0, (SYS_MODULE_INIT*)&init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description drvIndex Index for the driver instance to be initialized init Pointer to a data structure containing any data necessary to initialize the driver. Function SYS_MODULE_OBJ DRV_SDCARD_Initialize ( const SYS_MODULE_INDEX index, Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 723 const SYS_MODULE_INIT * const init ); DRV_SDCARD_Deinitialize Function Deinitializes the specified instance of the SD Card driver module. Implementation: Dynamic File drv_sdcard.h C void DRV_SDCARD_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the SD Card driver module, disabling its operation (and any hardware). Invalidates all the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This routine will NEVER block waiting for hardware. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_SDCARD_Status operation. The system has to use DRV_SDCARD_Status to check if the de-initialization is complete. Preconditions Function DRV_SDCARD_Initialize must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Example SYS_MODULE_OBJ objectHandle; // Returned from DRV_SDCARD_Initialize SYS_STATUS status; DRV_SDCARD_Deinitialize(objectHandle); status = DRV_SDCARD_Status(objectHandle); if (SYS_MODULE_UNINITIALIZED == status) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from the DRV_SDCARD_Initialize routine. Function void DRV_SDCARD_Deinitialize ( SYS_MODULE_OBJ object ); DRV_SDCARD_Reinitialize Function Reinitializes the driver and refreshes any associated hardware settings. Implementation: Dynamic File drv_sdcard.h C void DRV_SDCARD_Reinitialize(SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init); Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 724 Returns None Description This routine reinitializes the driver and refreshes any associated hardware settings using the given initialization data, but it will not interrupt any ongoing operations. Remarks This function can be called multiple times to reinitialize the module. This operation can be used to refresh any supported hardware registers as specified by the initialization data or to change the power state of the module. This routine will NEVER block for hardware access. If the operation requires time to allow the hardware to reinitialize, it will be reported by the DRV_SDCARD_Status operation. The system must use DRV_SDCARD_Status to find out when the driver is in the ready state. Preconditions Function DRV_SDCARD_Initialize must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Example DRV_SDCARD_INIT init; SYS_MODULE_OBJ objectHandle; // Returned from DRV_SDCARD_Initialize // Update the required fields of the SD Card initialization structure DRV_SDCARD_Reinitialize (objectHandle, (SYS_MODULE_INIT*)&init); Parameters Parameters Description object Driver object handle, returned from the DRV_SDCARD_Initialize routine init Pointer to the initialization data structure Function void DRV_SDCARD_Reinitialize ( SYS_MODULE_OBJ object, const SYS_MODULE_INIT * const init ); DRV_SDCARD_Status Function Provides the current status of the SD Card driver module. Implementation: Dynamic File drv_sdcard.h C SYS_STATUS DRV_SDCARD_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system level operation and cannot start another Note Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_STATUS_BUSY - Indicates that the driver is busy with a previous system level operation and cannot start another SYS_STATUS_ERROR - Indicates that the driver is in an error state Description This routine provides the current status of the SD Card driver module. Remarks Any value less than SYS_STATUS_ERROR is also an error state. SYS_MODULE_DEINITIALIZED - Indicates that the driver has been deinitialized Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 725 This value is less than SYS_STATUS_ERROR This operation can be used to determine when any of the driver's module level operations has completed. If the status operation returns SYS_STATUS_BUSY, then a previous operation has not yet completed. If the status operation returns SYS_STATUS_READY, then it indicates that all previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This routine will NEVER block waiting for hardware. If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Preconditions Function DRV_SDCARD_Initialize must have been called before calling this Example SYS_MODULE_OBJ object; // Returned from DRV_SDCARD_Initialize SYS_STATUS status; status = DRV_SDCARD_Status(object); if (SYS_MODULE_UNINITIALIZED == status) { // Check again later if you need to know // when the driver is deinitialized. } else if (SYS_STATUS_ERROR >= status) { // Handle error } Parameters Parameters Description object Driver object handle, returned from the DRV_SDCARD_Initialize routine Function SYS_STATUS DRV_SDCARD_Status ( SYS_MODULE_OBJ object ); DRV_SDCARD_Tasks Function Maintains the driver's state machine. Implementation: Dynamic File drv_sdcard.h C void DRV_SDCARD_Tasks(SYS_MODULE_OBJ object); Returns None Description This routine is used to maintain the driver's internal state machine. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the appropriate raw ISR. This routine may execute in an ISR context and will never block or access any resources that may cause it to block. Preconditions The DRV_SDCARD_Initialize routine must have been called for the specified SDCARD driver instance. Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 726 Example SYS_MODULE_OBJ object; // Returned from DRV_SDCARD_Initialize while (true) { DRV_SDCARD_Tasks (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_SDCARD_Initialize) Function void DRV_SDCARD_Tasks ( SYS_MODULE_OBJ object ); b) Client Level Functions DRV_SDCARD_Close Function Closes an opened-instance of the SD Card driver. Implementation: Dynamic File drv_sdcard.h C void DRV_SDCARD_Close(DRV_HANDLE handle); Returns None Description This routine closes an opened-instance of the SD Card driver, invalidating the handle. Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_SDCARD_Open before the caller may use the driver again. If DRV_IO_INTENT_BLOCKING was requested and the driver was built appropriately to support blocking behavior call may block until the operation is complete. If DRV_IO_INTENT_NON_BLOCKING request the driver client can call the DRV_SDCARD_Status operation to find out when the module is in the ready state (the handle is no longer valid). Usually there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_SDCARD_Initialize routine must have been called for the specified SD Card driver instance. DRV_SDCARD_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SDCARD_Open DRV_SDCARD_Close (handle); Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 727 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_SDCARD_Close ( DRV_HANDLE handle ); DRV_SDCARD_Open Function Opens the specified SD Card driver instance and returns a handle to it. Implementation: Dynamic File drv_sdcard.h C DRV_HANDLE DRV_SDCARD_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Description This routine opens the specified SD Card driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Remarks The handle returned is valid until the DRV_SDCARD_Close routine is called. This routine will NEVER block waiting for hardware. If the DRV_IO_INTENT_BLOCKING is requested and the driver was built appropriately to support blocking behavior, then other client-level operations may block waiting on hardware until they are complete. If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. Preconditions Function DRV_SDCARD_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_SDCARD_Open (DRV_SDCARD_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } Parameters Parameters Description drvIndex Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver Function DRV_HANDLE DRV_SDCARD_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 728 ); DRV_SDCARD_Read Function Reads blocks of data from the specified block address of the SD Card. File drv_sdcard.h C void DRV_SDCARD_Read(DRV_HANDLE handle, DRV_SDCARD_COMMAND_HANDLE * commandHandle, void * targetBuffer, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It will be DRV_SDCARD_COMMAND_HANDLE_INVALID if the request was not successful. Description This function schedules a non-blocking read operation for reading blocks of data from the SD Card. The function returns with a valid buffer handle in the commandHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_SDCARD_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if the driver handle is invalid • if the target buffer pointer is NULL • if the number of blocks to be read is zero or more than the actual number of blocks available • if a buffer object could not be allocated to the request • if the client opened the driver in write only mode If the requesting client registered an event callback with the driver, the driver will issue a DRV_SDCARD_EVENT_COMMAND_COMPLETE event if the buffer was processed successfully or DRV_SDCARD_EVENT_COMMAND_ERROR event if the buffer was not processed successfully. Remarks None. Preconditions The DRV_SDCARD_Initialize routine must have been called for the specified SDCARD driver instance. DRV_SDCARD_Open must have been called with DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE as the ioIntent to obtain a valid opened device handle. Example uint8_t myBuffer[MY_BUFFER_SIZE]; // address should be block aligned. uint32_t blockStart = 0x00; uint32_t nBlock = 2; DRV_SDCARD_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySDCARDHandle is the handle returned // by the DRV_SDCARD_Open function. DRV_SDCARD_Read(mySDCARDHandle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_SDCARD_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } else { // Read Successful } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 729 commandHandle Pointer to an argument that will contain the return buffer handle targetBuffer Buffer into which the data read from the SD Card will be placed blockStart Start block address of the SD Card from where the read should begin. nBlock Total number of blocks to be read. Function void DRV_SDCARD_Read ( const DRV_HANDLE handle, DRV_SDCARD_COMMAND_HANDLE * commandHandle, void * targetBuffer, uint32_t blockStart, uint32_t nBlock ); DRV_SDCARD_Write Function Writes blocks of data starting at the specified address of the SD Card. File drv_sdcard.h C void DRV_SDCARD_Write(DRV_HANDLE handle, DRV_SDCARD_COMMAND_HANDLE * commandHandle, void * sourceBuffer, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It will be DRV_SDCARD_COMMAND_HANDLE_INVALID if the request was not successful. Description This function schedules a non-blocking write operation for writing blocks of data to the SD Card. The function returns with a valid buffer handle in the commandHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_SDCARD_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer object could not be allocated to the request • if the source buffer pointer is NULL • if the client opened the driver for read only • if the number of blocks to be written is either zero or more than the number of blocks actually available • if the write queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_SDCARD_EVENT_COMMAND_COMPLETE event if the buffer was processed successfully or DRV_SDCARD_EVENT_COMMAND_ERROR event if the buffer was not processed successfully. Remarks None. Preconditions The DRV_SDCARD_Initialize() routine must have been called for the specified SDCARD driver instance. DRV_SDCARD_Open() routine must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified as a parameter to this routine. Example uint8_t myBuffer[MY_BUFFER_SIZE]; // address should be block aligned. uint32_t blockStart = 0x00; uint32_t nBlock = 2; DRV_SDCARD_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 730 // mySDCARDHandle is the handle returned // by the DRV_SDCARD_Open function. // Client registers an event handler with driver DRV_SDCARD_EventHandlerSet(mySDCARDHandle, APP_SDCARDEventHandler, (uintptr_t)&myAppObj); DRV_SDCARD_Write(mySDCARDHandle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_SDCARD_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_SDCARDEventHandler(DRV_SDCARD_EVENT event, DRV_SDCARD_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_SDCARD_EVENT_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_SDCARD_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle sourceBuffer The source buffer containing data to be programmed to the SD Card. blockStart Start block address of SD Card where the writes should begin. nBlock Total number of blocks to be written. Function void DRV_SDCARD_Write ( const DRV_HANDLE handle, DRV_SDCARD_COMMAND_HANDLE * commandHandle, void * sourceBuffer, uint32_t blockStart, uint32_t nBlock ); DRV_SDCARD_EventHandlerSet Function Allows a client to identify an event handling function for the driver to call back when queued operation has completed. File drv_sdcard.h Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 731 C void DRV_SDCARD_EventHandlerSet(const DRV_HANDLE handle, const void * eventHandler, const uintptr_t context); Returns None. Description This function allows a client to identify an event handling function for the driver to call back when queued operation has completed. When a client queues a request for a read or a write operation, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the queued operation has completed. The event handler should be set before the client performs any read or write operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued operation has completed, it does not need to register a callback. Preconditions The DRV_SDCARD_Initialize() routine must have been called for the specified SDCARD driver instance. The DRV_SDCARD_Open() routine must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; uint8_t myBuffer[MY_BUFFER_SIZE]; uint32_t blockStart, nBlock; DRV_SDCARD_COMMAND_HANDLE commandHandle; // drvSDCARDHandle is the handle returned // by the DRV_SDCARD_Open function. // Client registers an event handler with driver. This is done once. DRV_SDCARD_EventHandlerSet(drvSDCARDHandle, APP_SDCARDEventHandler, (uintptr_t)&myAppObj); DRV_SDCARD_Read(drvSDCARDHandle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_SDCARD_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event Processing Technique. Event is received when operation is done. void APP_SDCARDEventHandler(DRV_SDCARD_EVENT event, DRV_SDCARD_COMMAND_HANDLE handle, uintptr_t context) { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) context; switch(event) { case DRV_SDCARD_EVENT_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_SDCARD_EVENT_COMMAND_ERROR: // Error handling here. break; default: Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 732 break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function eventHandler Pointer to the event handler function implemented by the user context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_SDCARD_EventHandlerSet ( const DRV_HANDLE handle, const void * eventHandler, const uintptr_t context ); c) Status Functions DRV_SDCARD_IsAttached Function Returns the physical attach status of the SD Card. File drv_sdcard.h C bool DRV_SDCARD_IsAttached(const DRV_HANDLE handle); Returns Returns false if the handle is invalid otherwise returns the attach status of the SD Card. Returns true if the SD Card is attached and initialized by the SDCARD driver otherwise returns false. Description This function returns the physical attach status of the SD Card. Remarks None. Preconditions The DRV_SDCARD_Initialize() routine must have been called for the specified SDCARD driver instance. The DRV_SDCARD_Open() routine must have been called to obtain a valid opened device handle. Example bool isSDCARDAttached; isSDCARDAttached = DRV_SDCARD_isAttached(drvSDCARDHandle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function bool DRV_SDCARD_IsAttached ( const DRV_HANDLE handle Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 733 ); DRV_SDCARD_IsWriteProtected Function Returns the write protect status of the SDCARD. File drv_sdcard.h C bool DRV_SDCARD_IsWriteProtected(const DRV_HANDLE handle); Returns Returns true if the attached SD Card is write protected. Returns false if the handle is not valid, or if the SD Card is not write protected. Description This function returns true if the SD Card is write protected otherwise it returns false. Remarks None. Preconditions The DRV_SDCARD_Initialize() routine must have been called for the specified SDCARD driver instance. The DRV_SDCARD_Open() routine must have been called to obtain a valid opened device handle. Example bool isWriteProtected; isWriteProtected = DRV_SDCARD_IsWriteProtected(drvSDCARDHandle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function bool DRV_SDCARD_IsWriteProtected ( const DRV_HANDLE handle ); DRV_SDCARD_CommandStatus Function Gets the current status of the command. File drv_sdcard.h C DRV_SDCARD_COMMAND_STATUS DRV_SDCARD_CommandStatus(const DRV_HANDLE handle, const DRV_SDCARD_COMMAND_HANDLE commandHandle); Returns A DRV_SDCARD_COMMAND_STATUS value describing the current status of the command. Returns DRV_SDCARD_COMMAND_HANDLE_INVALID if the client handle or the command handle is not valid. Description This routine gets the current status of the command. The application must use this routine where the status of a scheduled command needs to be polled on. The function may return DRV_SDCARD_COMMAND_HANDLE_INVALID in a case where the command handle has expired. A command handle expires when the internal buffer object is re-assigned to another read or write request. It is recommended that this function be called regularly in order to track the command status correctly. The application can alternatively register an event handler to receive read or write operation completion events. Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 734 Remarks This routine will not block for hardware access and will immediately return the current status. Preconditions The DRV_SDCARD_Initialize() routine must have been called. The DRV_SDCARD_Open() must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SDCARD_Open DRV_SDCARD_COMMAND_HANDLE commandHandle; DRV_SDCARD_COMMAND_STATUS status; status = DRV_SDCARD_CommandStatus(handle, commandHandle); if(status == DRV_SDCARD_COMMAND_COMPLETED) { // Operation Done } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function DRV_SDCARD_COMMAND_STATUS DRV_SDCARD_CommandStatus ( const DRV_HANDLE handle, const DRV_SDCARD_COMMAND_HANDLE commandHandle ); DRV_SDCARD_GeometryGet Function Returns the geometry of the device. File drv_sdcard.h C SYS_FS_MEDIA_GEOMETRY * DRV_SDCARD_GeometryGet(const DRV_HANDLE handle); Returns SYS_FS_MEDIA_GEOMETRY - Pointer to structure which holds the media geometry information. Description This API gives the following geometrical details of the SD Card. • Media Property • Number of Read/Write/Erase regions in the SD Card • Number of Blocks and their size in each region of the device Remarks None. Preconditions The DRV_SDCARD_Initialize() routine must have been called for the specified SDCARD driver instance. The DRV_SDCARD_Open() routine must have been called to obtain a valid opened device handle. Example SYS_FS_MEDIA_GEOMETRY * SDCARDGeometry; uint32_t readBlockSize, writeBlockSize, eraseBlockSize; uint32_t nReadBlocks, nReadRegions, totalSize; SDCARDGeometry = DRV_SDCARD_GeometryGet(SDCARDOpenHandle1); Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 735 readBlockSize = SDCARDGeometry->geometryTable->blockSize; nReadBlocks = SDCARDGeometry->geometryTable->numBlocks; nReadRegions = SDCARDGeometry->numReadRegions; writeBlockSize = (SDCARDGeometry->geometryTable +1)->blockSize; eraseBlockSize = (SDCARDGeometry->geometryTable +2)->blockSize; totalSize = readBlockSize * nReadBlocks * nReadRegions; Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function SYS_FS_MEDIA_GEOMETRY * DRV_SDCARD_GeometryGet ( const DRV_HANDLE handle ); d) Data Types and Constants DRV_SDCARD_INDEX_0 Macro SD Card driver index definitions File drv_sdcard.h C #define DRV_SDCARD_INDEX_0 0 Description SD Card Driver Module Index Numbers These constants provide SD Card driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_SDCARD_Initialize and DRV_SDCARD_Open routines to identify the driver instance in use. DRV_SDCARD_INDEX_COUNT Macro Number of valid SD Card driver indices File drv_sdcard.h C #define DRV_SDCARD_INDEX_COUNT DRV_SDCARD_INDEX_MAX Description SD Card Driver Module Index Count This constant identifies number of valid SD Card driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from part-specific header files defined as part of the peripheral libraries. Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 736 DRV_SDCARD_INIT Structure Contains all the data necessary to initialize the SD Card device File drv_sdcard.h C typedef struct _DRV_SDCARD_INIT { SYS_MODULE_INIT moduleInit; SYS_MODULE_INDEX spiIndex; SPI_MODULE_ID spiId; CLK_BUSES_PERIPHERAL spiClk; uint32_t sdcardSpeedHz; SDCARD_DETECTION_LOGIC sdCardPinActiveLogic; PORTS_CHANNEL cardDetectPort; PORTS_BIT_POS cardDetectBitPosition; PORTS_CHANNEL writeProtectPort; PORTS_BIT_POS writeProtectBitPosition; PORTS_CHANNEL chipSelectPort; PORTS_BIT_POS chipSelectBitPosition; } DRV_SDCARD_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization SYS_MODULE_INDEX spiIndex; SPI driver index SPI_MODULE_ID spiId; Identifies peripheral (PLIB-level) ID CLK_BUSES_PERIPHERAL spiClk; Peripheral clock used by the SPI uint32_t sdcardSpeedHz; SD card communication speed SDCARD_DETECTION_LOGIC sdCardPinActiveLogic; SD Card Pin Detection Logic PORTS_CHANNEL cardDetectPort; Card detect port PORTS_BIT_POS cardDetectBitPosition; Card detect pin PORTS_CHANNEL writeProtectPort; Write protect port PORTS_BIT_POS writeProtectBitPosition; Write protect pin PORTS_CHANNEL chipSelectPort; Chip select port PORTS_BIT_POS chipSelectBitPosition; Chip select pin Description SD Card Device Driver Initialization Data This structure contains all the data necessary to initialize the SD Card device. Remarks A pointer to a structure of this format containing the desired initialization data must be passed into the DRV_SDCARD_Initialize routine. SDCARD_DETECTION_LOGIC Enumeration Defines the different system events File drv_sdcard.h C typedef enum { SDCARD_DETECTION_LOGIC_ACTIVE_LOW, SDCARD_DETECTION_LOGIC_ACTIVE_HIGH } SDCARD_DETECTION_LOGIC; Members Members Description SDCARD_DETECTION_LOGIC_ACTIVE_LOW The media event is SD Card attach Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 737 SDCARD_DETECTION_LOGIC_ACTIVE_HIGH The media event is SD Card detach Description System events This enum defines different system events. Remarks None. SDCARD_MAX_LIMIT Macro Maximum allowed SD card instances File drv_sdcard.h C #define SDCARD_MAX_LIMIT 2 Description SD Card Driver Maximum allowed limit This constant identifies number of valid SD Card driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from part-specific header files defined as part of the peripheral libraries. DRV_SDCARD_INDEX_1 Macro File drv_sdcard.h C #define DRV_SDCARD_INDEX_1 1 Description This is macro DRV_SDCARD_INDEX_1. DRV_SDCARD_INDEX_2 Macro File drv_sdcard.h C #define DRV_SDCARD_INDEX_2 2 Description This is macro DRV_SDCARD_INDEX_2. DRV_SDCARD_INDEX_3 Macro File drv_sdcard.h C #define DRV_SDCARD_INDEX_3 3 Description This is macro DRV_SDCARD_INDEX_3. Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 738 DRV_SDCARD_COMMAND_HANDLE_INVALID Macro SDCARD Driver's Invalid Command Handle. File drv_sdcard.h C #define DRV_SDCARD_COMMAND_HANDLE_INVALID SYS_FS_MEDIA_BLOCK_COMMAND_HANDLE_INVALID Description SDCARD Driver Invalid Command Handle. This value defines the SDCARD Driver Invalid Command Handle. This value is returned by read or write routines when the command request was not accepted. Remarks None. DRV_SDCARD_COMMAND_HANDLE Type Handle identifying commands queued in the driver. File drv_sdcard.h C typedef SYS_FS_MEDIA_BLOCK_COMMAND_HANDLE DRV_SDCARD_COMMAND_HANDLE; Description SDCARD Driver command handle. A command handle is returned by a call to the Read or Write functions. This handle allows the application to track the completion of the operation. This command handle is also returned to the client along with the event that has occurred with respect to the command. This allows the application to connect the event to a specific command in case where multiple commands are queued. The command handle associated with the command request expires when the client has been notified of the completion of the command (after event handler function that notifies the client returns) or after the command has been retired by the driver if no event handler callback was set. Remarks None. DRV_SDCARD_COMMAND_STATUS Enumeration Identifies the possible events that can result from a request. File drv_sdcard.h C typedef enum { DRV_SDCARD_COMMAND_COMPLETED = SYS_FS_MEDIA_COMMAND_COMPLETED, DRV_SDCARD_COMMAND_QUEUED = SYS_FS_MEDIA_COMMAND_QUEUED, DRV_SDCARD_COMMAND_IN_PROGRESS = SYS_FS_MEDIA_COMMAND_IN_PROGRESS, DRV_SDCARD_COMMAND_ERROR_UNKNOWN = SYS_FS_MEDIA_COMMAND_UNKNOWN } DRV_SDCARD_COMMAND_STATUS; Members Members Description DRV_SDCARD_COMMAND_COMPLETED = SYS_FS_MEDIA_COMMAND_COMPLETED Done OK and ready DRV_SDCARD_COMMAND_QUEUED = SYS_FS_MEDIA_COMMAND_QUEUED Scheduled but not started Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 739 DRV_SDCARD_COMMAND_IN_PROGRESS = SYS_FS_MEDIA_COMMAND_IN_PROGRESS Currently being in transfer DRV_SDCARD_COMMAND_ERROR_UNKNOWN = SYS_FS_MEDIA_COMMAND_UNKNOWN Unknown Command Description SDCARD Driver Events This enumeration identifies the possible events that can result from a read or a write request made by the client. Remarks One of these values is passed in the "event" parameter of the event handling callback function that client registered with the driver by calling the DRV_SDCARD_EventHandlerSet function when a request is completed. DRV_SDCARD_EVENT Enumeration Identifies the possible events that can result from a request. File drv_sdcard.h C typedef enum { DRV_SDCARD_EVENT_COMMAND_COMPLETE = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_COMPLETE, DRV_SDCARD_EVENT_COMMAND_ERROR = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_ERROR } DRV_SDCARD_EVENT; Members Members Description DRV_SDCARD_EVENT_COMMAND_COMPLETE = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_COMPLETE Operation has been completed successfully. DRV_SDCARD_EVENT_COMMAND_ERROR = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_ERROR There was an error during the operation Description SDCARD Driver Events This enumeration identifies the possible events that can result from a read or a write request issued by the client. Remarks One of these values is passed in the "event" parameter of the event handling callback function that client registered with the driver by calling the DRV_SDCARD_EventHandlerSet function when a request is completed. DRV_SDCARD_EVENT_HANDLER Type Pointer to a SDCARDDriver Event handler function File drv_sdcard.h C typedef SYS_FS_MEDIA_EVENT_HANDLER DRV_SDCARD_EVENT_HANDLER; Returns None. Description SDCARD Driver Event Handler Function Pointer This data type defines the required function signature for the SDCARD event handling callback function. A client must register a pointer to an event handling function whose function signature (parameter and return value types) match the types specified by this function pointer in order to receive event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 740 Remarks If the event is DRV_SDCARD_EVENT_COMMAND_COMPLETE, it means that the write or a erase operation was completed successfully. If the event is DRV_SDCARD_EVENT_COMMAND_ERROR, it means that the scheduled operation was not completed successfully. The context parameter contains the handle to the client context, provided at the time the event handling function was registered using the DRV_SDCARD_EventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the read/write/erase request. Example void APP_MySDCARDEventHandler ( DRV_SDCARD_EVENT event, DRV_SDCARD_COMMAND_HANDLE commandHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_SDCARD_EVENT_COMMAND_COMPLETE: // Handle the completed buffer. break; case DRV_SDCARD_EVENT_COMMAND_ERROR: default: // Handle error. break; } } Parameters Parameters Description event Identifies the type of event commandHandle Handle returned from the Read/Write requests context Value identifying the context of the application that registered the event handling function Files Files Name Description drv_sdcard.h SD Card Device Driver Interface File drv_sdcard_config_template.h SD Card driver configuration definitions template Description This section lists the source and header files used by the SD Card Driver Library. drv_sdcard.h SD Card Device Driver Interface File Enumerations Name Description DRV_SDCARD_COMMAND_STATUS Identifies the possible events that can result from a request. DRV_SDCARD_EVENT Identifies the possible events that can result from a request. SDCARD_DETECTION_LOGIC Defines the different system events Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 741 Functions Name Description DRV_SDCARD_Close Closes an opened-instance of the SD Card driver. Implementation: Dynamic DRV_SDCARD_CommandStatus Gets the current status of the command. DRV_SDCARD_Deinitialize Deinitializes the specified instance of the SD Card driver module. Implementation: Dynamic DRV_SDCARD_EventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. DRV_SDCARD_GeometryGet Returns the geometry of the device. DRV_SDCARD_Initialize Initializes the SD Card driver. Implementation: Dynamic DRV_SDCARD_IsAttached Returns the physical attach status of the SD Card. DRV_SDCARD_IsWriteProtected Returns the write protect status of the SDCARD. DRV_SDCARD_Open Opens the specified SD Card driver instance and returns a handle to it. Implementation: Dynamic DRV_SDCARD_Read Reads blocks of data from the specified block address of the SD Card. DRV_SDCARD_Reinitialize Reinitializes the driver and refreshes any associated hardware settings. Implementation: Dynamic DRV_SDCARD_Status Provides the current status of the SD Card driver module. Implementation: Dynamic DRV_SDCARD_Tasks Maintains the driver's state machine. Implementation: Dynamic DRV_SDCARD_Write Writes blocks of data starting at the specified address of the SD Card. Macros Name Description DRV_SDCARD_COMMAND_HANDLE_INVALID SDCARD Driver's Invalid Command Handle. DRV_SDCARD_INDEX_0 SD Card driver index definitions DRV_SDCARD_INDEX_1 This is macro DRV_SDCARD_INDEX_1. DRV_SDCARD_INDEX_2 This is macro DRV_SDCARD_INDEX_2. DRV_SDCARD_INDEX_3 This is macro DRV_SDCARD_INDEX_3. DRV_SDCARD_INDEX_COUNT Number of valid SD Card driver indices SDCARD_MAX_LIMIT Maximum allowed SD card instances Structures Name Description _DRV_SDCARD_INIT Contains all the data necessary to initialize the SD Card device DRV_SDCARD_INIT Contains all the data necessary to initialize the SD Card device Types Name Description DRV_SDCARD_COMMAND_HANDLE Handle identifying commands queued in the driver. DRV_SDCARD_EVENT_HANDLER Pointer to a SDCARDDriver Event handler function Description SD Card Device Driver Interface The SD Card device driver provides a simple interface to manage the "SD Card" peripheral. This file defines the interface definitions and prototypes for the SD Card driver. File Name drv_sdcard.h Company Microchip Technology Inc. Volume V: MPLAB Harmony Framework Driver Libraries Help Secure Digital (SD) Card Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 742 drv_sdcard_config_template.h SD Card driver configuration definitions template Macros Name Description DRV_SDCARD_CLIENTS_NUMBER Selects the miximum number of clients DRV_SDCARD_ENABLE_WRITE_PROTECT_CHECK Enable SD Card write protect check. DRV_SDCARD_INDEX_MAX SD Card Static Index selection DRV_SDCARD_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver DRV_SDCARD_POWER_STATE Defines an override of the power state of the SD Card driver. DRV_SDCARD_SYS_FS_REGISTER Register to use with the File system Description SD Card Driver Configuration Definitions for the template version These definitions statically define the driver's mode of operation. File Name drv_sdcard_config_template.h Company Microchip Technology Inc. SPI Driver Library This section describes the Serial Peripheral Interface (SPI) Driver Library. Introduction This library provides an interface to manage the Serial Peripheral Interface (SPI) module on the Microchip family of microcontrollers in different modes of operation. Description The SPI module is a full duplex synchronous serial interface useful for communicating with other peripherals or microcontrollers in master/slave relationship and it can transfer data over short distances at high speeds. The peripheral devices may be serial EEPROMs, shift registers, display drivers, analog-to-digital converters, etc. The SPI module is compatible with Motorola’s SPI and SIOP interfaces. During data transfer devices can work either in master or in Slave mode. The source of synchronization is the system clock, which is generated by the master. The SPI module allows one or more slave devices to be connected to a single master device via the same bus. The SPI serial interface consists of four pins, which are further sub-divided into data and control lines: Data Lines: • MOSI – Master Data Output, Slave Data Input • MISO – Master Data Input, Slave Data Output Control Lines: • SCLK – Serial Clock • /SS – Slave Select (no addressing) SPI Master-Slave Relationship Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 743 The SPI module can be configured to operate using two, three, or four pins. In the 3-pin mode, the Slave Select line is not used. In the 2-pin mode, both the MOSI and /SS lines are not used. Note: Third-party trademarks are property of their respective owners. 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 SPI Driver Library and provides information and examples on its use. Description Interface Header File: drv_spi.h The interface to the SPI Driver library is defined in the drv_spi.h header file. Any C language source (.c) file that uses the SPI Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the Driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the SPI Driver Library 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 Different types of SPIs are available on Microchip microcontrollers. Some have an internal buffer mechanism and some do not. The buffer depth varies across part families. The SPI driver abstracts out these differences and provides a unified model for data transfer across different types of SPIs available. Both transmitter and receiver provides a buffer in the driver which transmits and receives data to/from the hardware. The SPI driver provides a set of interfaces to perform the read and the write. The following diagrams illustrate the model used by the SPI driver for transmitter and receiver. Receiver Abstraction Model Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 744 Transmitter Abstraction Model Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. 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 System Interaction Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Client Setup Functions Provides open, close, status and other setup functions. Data Transfer Functions Provides data transfer functions available in the configuration. Miscellaneous Provides driver miscellaneous functions, data transfer status function, version identification functions etc. How the Library Works The library provides interfaces to support: • System Functionality • Client Functionality Note: Not all modes are available on all devices, please refer to the specific device data sheet to determine the modes that are supported for your device. System Access System Initialization and Reinitialization The system performs the initialization and the reinitialization of the device driver with settings that affect only the instance of the device that is being initialized or reinitialized. During system initialization each instance of the SPI module would be initialized with the following configuration Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 745 settings (either passed dynamically at run time using DRV_SPI_INIT or by using Initialization Overrides) that are supported by the specific SPI device hardware: • Device requested power state: one of the System Module Power States. For specific details please refer to Data Types and Constants in the Library Interface section • The actual peripheral ID enumerated as the PLIB level module ID (e.g., SPI_ID_2) • Defining the respective interrupt sources for TX, RX, and Error Interrupt The DRV_SPI_Initialize API returns an object handle of the type SYS_MODULE_OBJ. After this, the object handle returned by the Initialize interface would be used by the other system interfaces like DRV_SPI_Deinitialize, DRV_SPI_Status, and DRV_SPI_Tasks. Note: The system initialization and the reinitialization settings, only affect the instance of the peripheral that is being initialized or reinitialized. Example: DRV_SPI_INIT spiInitData; SYS_MODULE_OBJ objectHandle; spiInitData.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; spiInitData.spiId = SPI_ID_1; spiInitData.taskMode = DRV_SPI_TASK_MODE_POLLED; spiInitData.spiMode = DRV_SPI_MODE_MASTER; spiInitData.spiProtocolType = DRV_SPI_PROTOCOL_TYPE_STANDARD; spiInitData.commWidth = SPI_COMMUNICATION_WIDTH_8BITS; spiInitData.baudRate = 5000; spiInitData.bufferType = DRV_SPI_BUFFER_TYPE_STANDARD; // It is highly recommended to set this to // DRV_SPI_BUFFER_TYPE_ENHANCED for hardware // that supports it spiInitData.inputSamplePhase = SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE; spiInitData.clockMode = DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_RISE; spiInitData.txInterruptSource = INT_SOURCE_SPI_1_TRANSMIT; spiInitData.rxInterruptSource = INT_SOURCE_SPI_1_RECEIVE; spiInitData.errInterruptSource = INT_SOURCE_SPI_1_ERROR; spiInitData.queueSize = 10; spiInitData.jobQueueReserveSize = 1; objectHandle = DRV_SPI_Initialize(DRV_SPI_INDEX_1, (SYS_MODULE_INIT*)&spiInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Tasks Routine The system will either call DRV_SPI_Tasks, from System Task Service (in a polled environment) or DRV_SPI_Tasks will be called from the ISR of the SPI. Client Access General Client Operation For the application to start using an instance of the module, it must call the DRV_SPI_Open function. This provides the configuration required to open the SPI instance for operation. If the driver is deinitialized using the function DRV_SPI_Deinitialize, the application must call the DRV_SPI_Open function again to set up the instance of the SPI. For the various options available for IO_INTENT, please refer to Data Types and Constants in the Library Interface section. After a client instance is opened, DRV_SPI_ClientConfigure can be called to set a client-specific bps, OperationStarting and OperationEnded callbacks. The OperationStarting callback will be called before the first bit is put onto the SPI bus, allowing for the slave select line to be toggled to active. The OperationEnded callback will be called after the last bit is received, allowing for the slave select line to be toggled to inactive. These two callbacks will be called from the ISR, if the SPI driver is operating in ISR mode, care should be taken that they do the minimum needed. For example, OSAL calls make cause exceptions in ISR context. Example: DRV_HANDLE handle; // Configure the instance DRV_SPI_INDEX_1 with the configuration handle = DRV_SPI_Open(DRV_SPI_INDEX_1, DRV_IO_INTENT_READWRITE); if(handle == DRV_HANDLE_INVALID) { // Client cannot open the instance. } Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 746 Client Transfer - Core Client basic functionality provides a extremely basic interface for the driver operation. The following diagram illustrates the byte/word model used for the data transfer. Note: It is not necessary to close and reopen the client between multiple transfers. Client Data Transfer Functionality Applications using the SPI byte/word functionality, need to perform the following: 1. The system should have completed necessary initialization and the DRV_SPI_Tasks should either be running in polled environment, or in an interrupt environment. 2. Open_the driver using DRV_SPI_Open with the necessary intent. 3. Optionally configure the client with DRV_SPI_ClientConfigure to set up OperationStarting and OperationEnded callbacks to handle selecting and deselecting the slave select pin. 4. Add a buffer using the DRV_SPI_BufferAddRead/DRV_SPI_BufferAddWrite/DRV_SPI_BufferAddWriteRead functions. An optional callback can be provided that will be called when the buffer/job is complete. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 747 5. Check for the current transfer status using DRV_SPI_BufferStatus until the transfer progress is DRV_SPI_BUFFER_EVENT_COMPLETE, or wait for the callback to be called. If the SPI driver is configured in Polled more, ensure that DRV_SPI_Tasks is called regularly to handle the buffer/job. 6. The client will be able to close the driver using DRV_SPI_Close when required. Example: SYS_MODULE_OBJ spiObject; int main( void ) { while ( 1 ) { appTask (); DRV_SPI_Tasks(spiObject); } } void appTask () { #define MY_BUFFER_SIZE 5 DRV_HANDLE handle; // Returned from DRV_SPI_Open char myBuffer[MY_BUFFER_SIZE] = { 11, 22, 33, 44, 55}; unsigned int numBytes; DRV_SPI_BUFFER_HANDLE bufHandle; // Preinitialize myBuffer with MY_BUFFER_SIZE bytes of valid data. while( 1 ) { switch( state ) { case APP_STATE_INIT: /* Initialize the SPI Driver */ spiObject = DRV_SPI_Initialize( DRV_SPI_INDEX_1, ( SYS_MODULE_INIT * ) &initConf_1 ); /* Check for the System Status */ if( SYS_STATUS_READY != DRV_SPI_Status( spiObject ) ) return 0; /* Open the Driver */ handle = DRV_SPI_Open( DRV_SPI_INDEX_1, DRV_IO_INTENT_EXCLUSIVE ); /* Enable/Activate the CS */ /* Update the state to transfer data */ state = APP_STATE_DATA_PUT; break; case APP_STATE_DATA_PUT: bufHandle = DRV_SPI_BufferAddWrite ( handle, myBuffer, 5, NULL, NULL ); /* Update the state to status check */ state = APP_STATE_DATA_CHECK; break; case APP_STATE_DATA_CHECK: /* Check for the successful data transfer */ if( DRV_SPI_BUFFER_EVENT_COMPLETE & DRV_SPI_BufferStatus( bufhandle ) ) { /* Do this repeatedly */ state = APP_STATE_DATA_PUT; } break; default: break; } } Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 748 Configuring the Library Miscellaneous Configuration Name Description DRV_SPI_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver . DRV_SPI_CLIENTS_NUMBER Selects the maximum number of clients. System Configuration Name Description DRV_SPI_16BIT Controls the compilation of 16 Bit mode DRV_SPI_32BIT Controls the compilation of 32 Bit mode DRV_SPI_8BIT Controls the compilation of 8 Bit mode DRV_SPI_DMA Controls the compilation of DMA support DRV_SPI_DMA_DUMMY_BUFFER_SIZE Controls the size of DMA dummy buffer DRV_SPI_DMA_TXFER_SIZE Controls the size of DMA transfers DRV_SPI_EBM Controls the compilation of Enhanced Buffer Mode mode DRV_SPI_ELEMENTS_PER_QUEUE Controls the number of elements that are allocated. DRV_SPI_ISR Controls the compilation of ISR mode DRV_SPI_MASTER Controls the compilation of master mode DRV_SPI_POLLED Controls the compilation of Polled mode DRV_SPI_RM Controls the compilation of Standard Buffer mode DRV_SPI_SLAVE Controls the compilation of slave mode Description The configuration of the SPI driver is based on the file system_config.h. This header file contains the configuration selection for the SPI driver. Based on the selections made, the SPI driver may support the selected features. These configuration settings will apply to all instances of the SPI driver. This header can be placed anywhere, 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. System Configuration DRV_SPI_16BIT Macro Controls the compilation of 16 Bit mode File drv_spi_config_template.h C #define DRV_SPI_16BIT 1 Description SPI 16 Bit Mode Enable This definition controls whether or not 16 Bit mode functionality is built as part of the driver. With it set to 1 then 16 Bit mode will be compiled and commWidth = SPI_COMMUNICATION_WIDTH_16BITS will be accepted by SPI_DRV_Initialize(). With it set to 0 SPI_DRV_Initialize() will cause an assert. With this set the BufferAdd functions will only accept buffer sizes of multiples of 2 (16 bit words) Remarks Optional definition DRV_SPI_32BIT Macro Controls the compilation of 32 Bit mode Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 749 File drv_spi_config_template.h C #define DRV_SPI_32BIT 1 Description SPI 32 Bit Mode Enable This definition controls whether or not 32 Bit mode functionality is built as part of the driver. With it set to 1 then 32 Bit mode will be compiled and commWidth = SPI_COMMUNICATION_WIDTH_32BITS will be accepted by SPI_DRV_Initialize(). With it set to 0 SPI_DRV_Initialize() will cause an assert. With this set the BufferAdd functions will only accept buffer sizes of multiples of 4 (32 bit words) Remarks Optional definition DRV_SPI_8BIT Macro Controls the compilation of 8 Bit mode File drv_spi_config_template.h C #define DRV_SPI_8BIT 1 Description SPI 8 Bit Mode Enable This definition controls whether or not 8 Bit mode functionality is built as part of the driver. With it set to 1 then 8 Bit mode will be compiled and commWidth = SPI_COMMUNICATION_WIDTH_8BITS will be accepted by SPI_DRV_Initialize(). With it set to 0 SPI_DRV_Initialize() will cause an assert. Remarks Optional definition DRV_SPI_DMA Macro Controls the compilation of DMA support File drv_spi_config_template.h C #define DRV_SPI_DMA 1 Description SPI DMA Enable This definition controls whether or not DMA functionality is built as part of the driver. With it set to 1 then DMA will be compiled. Remarks Optional definition DRV_SPI_DMA_DUMMY_BUFFER_SIZE Macro Controls the size of DMA dummy buffer File drv_spi_config_template.h C #define DRV_SPI_DMA_DUMMY_BUFFER_SIZE 256 Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 750 Description SPI DMA Dummy Buffer Size This controls the size of the buffer the SPI driver uses to give to the DMA service when it is to send and receive invalid data on the bus. This occurs when the number of bytes to be read are different than the number of bytes transmitted. Remarks Optional definition DRV_SPI_DMA_TXFER_SIZE Macro Controls the size of DMA transfers File drv_spi_config_template.h C #define DRV_SPI_DMA_TXFER_SIZE 256 Description SPI DMA Transfer Size This definition controls the maximum number of bytes to transfer per DMA transfer. Remarks Optional definition DRV_SPI_EBM Macro Controls the compilation of Enhanced Buffer Mode mode File drv_spi_config_template.h C #define DRV_SPI_EBM 1 Description SPI Enhanced Buffer Mode Enable (Hardware FIFO) This definition controls whether or not Enhanced Buffer mode functionality is built as part of the driver. With it set to 1 then enhanced buffer mode will be compiled and bufferType = DRV_SPI_BUFFER_TYPE_ENHANCED will be accepted by SPI_DRV_Initialize(). With it set to 0 SPI_DRV_Initialize() will cause an assert. This mode is not available on all PIC32s. Trying to use this mode on PICMX3XX/4XX will cause compile time warnings and errors. Remarks Optional definition DRV_SPI_ELEMENTS_PER_QUEUE Macro Controls the number of elements that are allocated. File drv_spi_config_template.h C #define DRV_SPI_ELEMENTS_PER_QUEUE 10 Description SPI Buffer Queue Depth This definition along with DRV_SPI_INSTANCES_NUMBER and DRV_SPI_CLIENT_NUMBER controls how many buffer queue elements are created. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 751 Remarks Optional definition DRV_SPI_ISR Macro Controls the compilation of ISR mode File drv_spi_config_template.h C #define DRV_SPI_ISR 1 Description SPI ISR Mode Enable This definition controls whether or not ISR mode functionality is built as part of the driver. With it set to 1 then ISR mode will be compiled and taskMode = DRV_SPI_TASK_MODE_ISR will be accepted by SPI_DRV_Initialize(). With it set to 0 SPI_DRV_Initialize() will cause an assert Remarks Optional definition DRV_SPI_MASTER Macro Controls the compilation of master mode File drv_spi_config_template.h C #define DRV_SPI_MASTER 1 Description SPI Master Mode Enable This definition controls whether or not master mode functionality is built as part of the driver. With it set to 1 then master mode will be compiled and spiMode = DRV_SPI_MODE_MASTER will be accepted by SPI_DRV_Initialize(). With it set to 0 SPI_DRV_Initialize() will cause an assert Remarks Optional definition DRV_SPI_POLLED Macro Controls the compilation of Polled mode File drv_spi_config_template.h C #define DRV_SPI_POLLED 1 Description SPI Polled Mode Enable This definition controls whether or not polled mode functionality is built as part of the driver. With it set to 1 then polled mode will be compiled and taskMode = DRV_SPI_TASK_MODE_POLLED will be accepted by SPI_DRV_Initialize(). With it set to 0 SPI_DRV_Initialize() will cause an assert Remarks Optional definition DRV_SPI_RM Macro Controls the compilation of Standard Buffer mode Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 752 File drv_spi_config_template.h C #define DRV_SPI_RM 1 Description SPI Standard Buffer Mode Enable This definition controls whether or not Standard Buffer mode functionality is built as part of the driver. With it set to 1 then standard buffer mode will be compiled and bufferType = DRV_SPI_BUFFER_TYPE_STANDARD will be accepted by SPI_DRV_Initialize(). With it set to 0 SPI_DRV_Initialize() will cause an assert. This mode is available on all PIC32s Remarks Optional definition DRV_SPI_SLAVE Macro Controls the compilation of slave mode File drv_spi_config_template.h C #define DRV_SPI_SLAVE 1 Description SPI Slave Mode Enable This definition controls whether or not slave mode functionality is built as part of the driver. With it set to 1 then slave mode will be compiled and spiMode = DRV_SPI_MODE_SLAVE will be accepted by SPI_DRV_Initialize(). With it set to 0 SPI_DRV_Initialize() will cause an assert Remarks Optional definition Miscellaneous Configuration DRV_SPI_INSTANCES_NUMBER Macro Selects the maximum number of hardware instances that can be supported by the dynamic driver . File drv_spi_config_template.h C #define DRV_SPI_INSTANCES_NUMBER 1 Description SPI hardware instance configuration This definition selects the maximum number of hardware instances that can be supported by the dynamic driver. Remarks Mandatory definition DRV_SPI_CLIENTS_NUMBER Macro Selects the maximum number of clients. File drv_spi_config_template.h Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 753 C #define DRV_SPI_CLIENTS_NUMBER 1 Description SPI maximum number of clients This definition selects the maximum number of clients that the SPI driver can support at run time. Remarks Mandatory definition Building the Library This section lists the files that are available in the SPI Driver Library. Description This section list the files that are available in the \src folder of the SPI 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. 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 /framework/driver/spi. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_spi.h Header file that exports the driver API. 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 /src/dynamic/drv_spi.c Basic SPI Driver implementation file. /src/dynamic/drv_spi_api.c Functions used by the driver API. /src/drv_spi_sys_queue_fifo.c Queue implementation used by the SPI Driver. 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 N/A No optional files are available for this library Module Dependencies The SPI Driver Library depends on the following modules: • Clock System Service Library Optional Dependencies • DMA System Service Library (used when operating in DMA mode) • Interrupt System Service Library (used when task is running in Interrupt mode) Library Interface a) System Interaction Functions Name Description DRV_SPI_Initialize Initializes the SPI instance for the specified driver index. Implementation: Static/Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 754 DRV_SPI_Deinitialize Deinitializes the specified instance of the SPI driver module. Implementation: Static/Dynamic DRV_SPI_Status Provides the current status of the SPI driver module. Implementation: Static/Dynamic DRV_SPI_Tasks Maintains the driver's state machine and implements its ISR. Implementation: Static/Dynamic b) Client Setup Functions Name Description DRV_SPI_Close Closes an opened instance of the SPI driver. Implementation: Static/Dynamic DRV_SPI_Open Opens the specified SPI driver instance and returns a handle to it. Implementation: Static/Dynamic DRV_SPI_ClientConfigure Configures a SPI client with specific data. Implementation: Static/Dynamic c) Data Transfer Functions Name Description DRV_SPI_BufferStatus Returns the transmitter and receiver transfer status. Implementation: Static/Dynamic DRV_SPI_BufferAddRead Registers a buffer for a read operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic DRV_SPI_BufferAddWrite Registers a buffer for a write operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic DRV_SPI_BufferAddWriteRead Registers a buffer for a read and write operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic DRV_SPI_BufferAddRead2 Registers a buffer for a read operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic DRV_SPI_BufferAddWrite2 Registers a buffer for a write operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic DRV_SPI_BufferAddWriteRead2 Registers a buffer for a read and write operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic DRV_SPIn_ReceiverBufferIsFull Returns the receive buffer status. 'n' represents the instance of the SPI driver used. Implementation: Static DRV_SPIn_TransmitterBufferIsFull Returns the transmit buffer status. 'n' represents the instance of the SPI driver used. Implementation: Static Description This section describes the API functions of the SPI Driver library. Refer to each section for a detailed description. a) System Interaction Functions DRV_SPI_Initialize Function Initializes the SPI instance for the specified driver index. Implementation: Static/Dynamic File drv_spi.h C SYS_MODULE_OBJ DRV_SPI_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns • If successful - returns a valid handle to a driver instance object Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 755 • If unsuccessful - returns SYS_MODULE_OBJ_INVALID Description This routine initializes the SPI driver instance for the specified driver index, making it ready for clients to open and use it. The initialization data is specified by the 'init' parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. The driver instance index is independent of the SPI module ID. For example, driver instance 0 can be assigned to SPI2. If the driver is built statically, then some of the initialization parameters are overridden by configuration macros. Refer to the description of the DRV_SPI_INIT data structure for more details on which members on this data structure are overridden. Remarks This routine must be called before any other SPI routine is called. This routine should only be called once during system initialization unless DRV_SPI_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. Preconditions None. Example DRV_SPI_INIT init; SYS_MODULE_OBJ objectHandle; // Populate the SPI initialization structure init.spiId = SPI_ID_1, init.taskMode = DRV_SPI_TASK_MODE_ISR, init.spiMode = DRV_SPI_MODE_MASTER, init.allowIdleRun = false, init.spiProtocolType = DRV_SPI_PROTOCOL_TYPE_STANDARD, init.commWidth = SPI_COMMUNICATION_WIDTH_8BITS, init.baudClockSource = SPI_BAUD_RATE_PBCLK_CLOCK; init.spiClk = CLK_BUS_PERIPHERAL_2, init.baudRate = 10000000, init.bufferType = DRV_SPI_BUFFER_TYPE_ENHANCED, init.clockMode = DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_FALL, init.inputSamplePhase = SPI_INPUT_SAMPLING_PHASE_IN_MIDDLE, init.txInterruptSource = INT_SOURCE_SPI_1_TRANSMIT, init.rxInterruptSource = INT_SOURCE_SPI_1_RECEIVE, init.errInterruptSource = INT_SOURCE_SPI_1_ERROR, init.dummyByteValue = 0xFF, init.queueSize = 10, init.jobQueueReserveSize = 1, objectHandle = DRV_SPI_Initialize(DRV_SPI_INDEX_1, (SYS_MODULE_INIT*)usartInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized. Please note this is not the SPI id. The hardware SPI id is set in the initialization structure. This is the index of the driver index to use. init Pointer to a data structure containing any data necessary to initialize the driver. If this pointer is NULL, the driver uses the static initialization override macros for each member of the initialization data structure. Function SYS_MODULE_OBJ DRV_SPI_Initialize( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ) DRV_SPI_Deinitialize Function Deinitializes the specified instance of the SPI driver module. Implementation: Static/Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 756 File drv_spi.h C void DRV_SPI_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the SPI driver module, disabling its operation (and any hardware) and invalidates all of the internal data. Remarks Once the Initialize operation has been called, the De-initialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_SPI_Status operation. The system has to use DRV_SPI_Status to find out when the module is in the ready state. Preconditions Function DRV_SPI_Initialize must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Example SYS_MODULE_OBJ object; // Returned from DRV_SPI_Initialize SYS_STATUS status; DRV_SPI_Deinitialize ( object ); status = DRV_SPI_Status( object ); if( SYS_MODULE_UNINITIALIZED == status ) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from DRV_SPI_Initialize Function void DRV_SPI_Deinitialize ( SYS_MODULE_OBJ object ) DRV_SPI_Status Function Provides the current status of the SPI driver module. Implementation: Static/Dynamic File drv_spi.h C SYS_STATUS DRV_SPI_Status(SYS_MODULE_OBJ object); Returns • SYS_STATUS_READY - Indicates that the driver is busy with a previous system level operation and cannot start another Description This function provides the current status of the SPI driver module. Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_MODULE_UNINITIALIZED - Indicates that the driver has been deinitialized Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 757 This value is less than SYS_STATUS_ERROR. This function can be used to determine when any of the driver's module level operations has completed. If the status operation returns SYS_STATUS_BUSY, the previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This function will NEVER block waiting for hardware. If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Preconditions The DRV_SPI_Initialize function must have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_SPI_Initialize SYS_STATUS status; status = DRV_SPI_Status( object ); if( SYS_STATUS_READY != status ) { // Handle error } Parameters Parameters Description object Driver object handle, returned from DRV_SPI_Initialize Function SYS_STATUS DRV_SPI_Status ( SYS_MODULE_OBJ object ) DRV_SPI_Tasks Function Maintains the driver's state machine and implements its ISR. Implementation: Static/Dynamic File drv_spi.h C void DRV_SPI_Tasks(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal state machine and implement its transmit ISR for interrupt-driven implementations. In polling mode, this function should be called from the SYS_Tasks() function. In interrupt mode, this function should be called in the transmit interrupt service routine of the USART that is associated with this USART driver hardware instance. Remarks This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the appropriate raw ISR. This function may execute in an ISR context and will never block or access any resources that may cause it to block. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_SPI_Initialize while( true ) { DRV_SPI_Tasks ( object ); // Do other tasks Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 758 } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_SPI_Initialize) Function void DRV_SPI_Tasks ( SYS_MODULE_OBJ object ); b) Client Setup Functions DRV_SPI_Close Function Closes an opened instance of the SPI driver. Implementation: Static/Dynamic File drv_spi.h C void DRV_SPI_Close(DRV_HANDLE handle); Returns None. Description This function closes an opened instance of the SPI driver, invalidating the handle. Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_SPI_Open before the caller may use the driver again. This function is thread safe in a RTOS application. Usually there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. DRV_SPI_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SPI_Open DRV_SPI_Close ( handle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_SPI_Close ( DRV_HANDLE handle ) DRV_SPI_Open Function Opens the specified SPI driver instance and returns a handle to it. Implementation: Static/Dynamic File drv_spi.h C DRV_HANDLE DRV_SPI_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent); Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 759 Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. An error can occur when the following is true: • if the number of client objects allocated via DRV_SPI_INSTANCES_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the driver hardware instance being opened is not initialized or is invalid Description This routine opens the specified SPI driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. If ioIntent is DRV_IO_INTENT_READ, the client will only be read from the driver. If ioIntent is DRV_IO_INTENT_WRITE, the client will only be able to write to the driver. If the ioIntent in DRV_IO_INTENT_READWRITE, the client will be able to do both, read and write. Specifying a DRV_IO_INTENT_EXCLUSIVE will cause the driver to provide exclusive access to this client. The driver cannot be opened by any other client. Remarks The handle returned is valid until the DRV_SPI_Close routine is called. This routine will NEVER block waiting for hardware. If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. It should not be called in an ISR. Preconditions The DRV_SPI_Initialize function must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_SPI_Open( DRV_SPI_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); if( DRV_HANDLE_INVALID == handle ) { // Unable to open the driver } Parameters Parameters Description drvIndex Index of the driver initialized with DRV_SPI_Initialize(). Please note this is not the SPI ID. ioIntent Zero or more of the values from the enumeration DRV_IO_INTENT ORed together to indicate the intended use of the driver Function DRV_HANDLE DRV_SPI_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent ) DRV_SPI_ClientConfigure Function Configures a SPI client with specific data. Implementation: Static/Dynamic File drv_spi.h C int32_t DRV_SPI_ClientConfigure(DRV_HANDLE handle, const DRV_SPI_CLIENT_DATA * cfgData); Returns • If successful - the routing will return greater than or equal to zero • If an error occurs - the return value is negative Description This routine takes a DRV_SPI_CLIENT_DATA structure and sets client specific options. Whenever a new SPI job is started these values will be used. Passing in NULL will reset the client back to configuration parameters passed to driver initialization. A zero in any of the structure elements Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 760 will reset that specific configuration back to the driver default. Preconditions The DRV_SPI_Open function must have been called before calling this function. Parameters Parameters Description handle handle of the client returned by DRV_SPI_Open. cfgData Client-specific configuration data. Function int32_t DRV_SPI_ClientConfigure ( DRV_HANDLE handle, const DRV_SPI_CLIENT_DATA * cfgData ) c) Data Transfer Functions DRV_SPI_BufferStatus Function Returns the transmitter and receiver transfer status. Implementation: Static/Dynamic File drv_spi.h C DRV_SPI_BUFFER_EVENT DRV_SPI_BufferStatus(DRV_SPI_BUFFER_HANDLE bufferHandle); Returns A DRV_SPI_BUFFER_STATUS value describing the current status of the transfer. Description This returns the transmitter and receiver transfer status. Remarks The returned status may contain a value with more than one of the bits specified in the DRV_SPI_BUFFER_STATUS enumeration set. The caller should perform an AND with the bit of interest and verify if the result is non-zero (as shown in the example) to verify the desired status bit. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. DRV_SPI_Open must have been called to obtain a valid opened device handle. DRV_SPI_BufferAddmust have been called to obtain the buffer handle associated with that transfer. Example // Buffer handle returned from the data transfer function DRV_SPI_BUFFER_HANDLE bufferHandle; if(DRV_SPI_BufferStatus(bufferHandle) == DRV_SPI_BUFFER_EVENT_COMPLETE) { // All transmitter data has been sent. } Parameters Parameters Description bufferHandle A valid buffer handle, returned from the driver's data transfer routine Function DRV_SPI_BUFFER_EVENT DRV_SPI_BufferStatus ( DRV_SPI_BUFFER_HANDLE bufferHandle ) Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 761 DRV_SPI_BufferAddRead Function Registers a buffer for a read operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic File drv_spi.h C DRV_SPI_BUFFER_HANDLE DRV_SPI_BufferAddRead(DRV_HANDLE handle, void * rxBuffer, size_t size, DRV_SPI_BUFFER_EVENT_HANDLER completeCB, void * context); Returns If the buffer add request is successful, a valid buffer handle is returned. If request is not queued up, DRV_SPI_BUFFER_HANDLE_INVALID is returned. Description Registers a buffer for a read operation. Actual transfer will happen in the Task function. The status of this operation can be monitored using DRV_SPI_BufferStatus function. A optional callback can also be provided that will be called when the operation is complete. Remarks This API will be deprecated soon, so avoid using it. Use "DRV_SPI_BufferAddRead2" instead of it. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. DRV_SPI_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SPI_Open call. Example DRV_HANDLE handle; // Returned from DRV_SPI_Open char myBuffer[MY_BUFFER_SIZE], state = 0; DRV_SPI_BUFFER_HANDLE bufferHandle; switch ( state ) { case 0: bufferHandle = DRV_SPI_BufferAddRead( handle, myBuffer, 10, NULL, NULL ); if(bufferHandle != DRV_SPI_BUFFER_HANDLE_INVALID ) { state++; } break; case 1: if(DRV_SPI_BufferStatus(bufferHandle) == DRV_SPI_BUFFER_EVENT_COMPLETE) { state++; // All transmitter data has been sent successfully. } break; } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine rxBuffer The buffer to which the data should be written to. size Number of bytes to be read from the SPI bus. completeCB Pointer to a function to be called when this queued operation is complete. context unused by the driver but this is passed to the callback when it is called. Function DRV_SPI_BUFFER_HANDLE DRV_SPI_BufferAddRead ( DRV_HANDLE handle, void *rxBuffer, size_t size, DRV_SPI_BUFFER_EVENT_HANDLER completeCB, Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 762 void * context ) DRV_SPI_BufferAddWrite Function Registers a buffer for a write operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic File drv_spi.h C DRV_SPI_BUFFER_HANDLE DRV_SPI_BufferAddWrite(DRV_HANDLE handle, void * txBuffer, size_t size, DRV_SPI_BUFFER_EVENT_HANDLER completeCB, void * context); Returns If the buffer add request is successful, a valid buffer handle is returned. If request is not queued up, DRV_SPI_BUFFER_HANDLE_INVALID is returned. Description Registers a buffer for a write operation. Actual transfer will happen in the Task function. The status of this operation can be monitored using DRV_SPI_BufferStatus function. A optional callback can also be provided that will be called when the operation is complete. Remarks This API will be deprecated soon, so avoid using it. Use "DRV_SPI_BufferAddWrite2" instead of it. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. DRV_SPI_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SPI_Open call. Example DRV_HANDLE handle; // Returned from DRV_SPI_Open char myBuffer[MY_BUFFER_SIZE], state = 0; DRV_SPI_BUFFER_HANDLE bufferHandle; switch ( state ) { case 0: bufferHandle = DRV_SPI_BufferAddWrite( handle, myBuffer, 10, NULL, NULL ); if(bufferHandle != DRV_SPI_BUFFER_HANDLE_INVALID ) { state++; } break; case 1: if(DRV_SPI_BufferStatus(bufferHandle) == DRV_SPI_BUFFER_EVENT_COMPLETE) { state++; // All transmitter data has been sent successfully. } break; } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine txBuffer The buffer which hold the data. size Number of bytes to be written to the SPI bus. completeCB Pointer to a function to be called when this queued operation is complete context unused by the driver but this is passed to the callback when it is called Function DRV_SPI_BUFFER_HANDLE DRV_SPI_BufferAddWrite ( DRV_HANDLE handle, void *txBuffer, Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 763 size_t size, DRV_SPI_BUFFER_EVENT_HANDLER completeCB, void * context ) DRV_SPI_BufferAddWriteRead Function Registers a buffer for a read and write operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic File drv_spi.h C DRV_SPI_BUFFER_HANDLE DRV_SPI_BufferAddWriteRead(DRV_HANDLE handle, void * txBuffer, size_t txSize, void * rxBuffer, size_t rxSize, DRV_SPI_BUFFER_EVENT_HANDLER completeCB, void * context); Returns If the buffer add request is successful, a valid buffer handle is returned. If request is not queued up, DRV_SPI_BUFFER_HANDLE_INVALID is returned. Description Registers a buffer for a read and write operation. Actual transfer will happen in the Task function. The status of this operation can be monitored using DRV_SPI_BufferStatus function. A optional callback can also be provided that will be called when the operation is complete. Remarks This API will be deprecated soon, so avoid using it. Use "DRV_SPI_BufferAddWriteRead2" instead of it. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. DRV_SPI_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SPI_Open char myReadBuffer[MY_BUFFER_SIZE], myWriteBuffer[MY_BUFFER_SIZE], state = 0; DRV_SPI_BUFFER_HANDLE bufferHandle; switch ( state ) { case 0: bufferHandle = DRV_SPI_BufferAddWriteRead( handle, myWriteBuffer, 10, myReadBuffer, 10, NULL, NULL ); if(bufferHandle != DRV_SPI_BUFFER_HANDLE_INVALID ) { state++; } break; case 1: if(DRV_SPI_BufferStatus(bufferHandle) == DRV_SPI_BUFFER_EVENT_COMPLETE) { state++; // All transmitter data has been sent successfully. } break; } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine txBuffer The buffer which hold the data. txSize Number of bytes to be written to the SPI bus. rxBuffer The buffer to which the data should be written to. rxSize Number of bytes to be read from the SPI bus completeCB Pointer to a function to be called when this queued operation is complete context unused by the driver but this is passed to the callback when it is called Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 764 Function DRV_SPI_BUFFER_HANDLE DRV_SPI_BufferAddWriteRead( DRV_HANDLE handle, void *txBuffer, void *rxBuffer, size_t size, ) DRV_SPI_BufferAddRead2 Function Registers a buffer for a read operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic File drv_spi.h C DRV_SPI_BUFFER_HANDLE DRV_SPI_BufferAddRead2(DRV_HANDLE handle, void * rxBuffer, size_t size, DRV_SPI_BUFFER_EVENT_HANDLER completeCB, void * context, DRV_SPI_BUFFER_HANDLE * jobHandle); Returns If the buffer add request is successful, a valid buffer handle is returned. If request is not queued up, DRV_SPI_BUFFER_HANDLE_INVALID is returned. Description Registers a buffer for a read operation. Actual transfer will happen in the Task function. The status of this operation can be monitored using DRV_SPI_BufferStatus function. A optional callback can also be provided that will be called when the operation is complete. Remarks None. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. DRV_SPI_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SPI_Open call. Example DRV_HANDLE handle; // Returned from DRV_SPI_Open char myBuffer[MY_BUFFER_SIZE], state = 0; DRV_SPI_BUFFER_HANDLE bufferHandle, bufferHandle2; switch ( state ) { case 0: bufferHandle = DRV_SPI_BufferAddRead2( handle, myBuffer, 10, NULL, NULL, &bufferHandle2 ); if(bufferHandle2 != DRV_SPI_BUFFER_HANDLE_INVALID ) { state++; } break; case 1: if(DRV_SPI_BufferStatus(bufferHandle2) == DRV_SPI_BUFFER_EVENT_COMPLETE) { state++; // All transmitter data has been sent successfully. } break; } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine rxBuffer The buffer to which the data should be written to. size Number of bytes to be read from the SPI bus. completeCB Pointer to a function to be called when this queued operation is complete context unused by the driver but this is passed to the callback when it is called Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 765 jobHandle pointer to the buffer handle, this will be set before the function returns and can be used in the ISR callback. Function DRV_SPI_BUFFER_HANDLE DRV_SPI_BufferAddRead2 ( DRV_HANDLE handle, void *rxBuffer, size_t size, DRV_SPI_BUFFER_EVENT_HANDLER completeCB, void * context, DRV_SPI_BUFFER_HANDLE * jobHandle ) DRV_SPI_BufferAddWrite2 Function Registers a buffer for a write operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic File drv_spi.h C DRV_SPI_BUFFER_HANDLE DRV_SPI_BufferAddWrite2(DRV_HANDLE handle, void * txBuffer, size_t size, DRV_SPI_BUFFER_EVENT_HANDLER completeCB, void * context, DRV_SPI_BUFFER_HANDLE * jobHandle); Returns If the buffer add request is successful, a valid buffer handle is returned. If request is not queued up, DRV_SPI_BUFFER_HANDLE_INVALID is returned. Description Registers a buffer for a write operation. Actual transfer will happen in the Task function. The status of this operation can be monitored using DRV_SPI_BufferStatus function. A optional callback can also be provided that will be called when the operation is complete. Remarks None. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. DRV_SPI_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SPI_Open call. Example DRV_HANDLE handle; // Returned from DRV_SPI_Open char myBuffer[MY_BUFFER_SIZE], state = 0; DRV_SPI_BUFFER_HANDLE bufferHandle, bufferHandle2; switch ( state ) { case 0: bufferHandle = DRV_SPI_BufferAddWrite2( handle, myBuffer, 10, NULL, NULL, &bufferHandle2 ); if(bufferHandle2 != DRV_SPI_BUFFER_HANDLE_INVALID ) { state++; } break; case 1: if(DRV_SPI_BufferStatus(bufferHandle2) == DRV_SPI_BUFFER_EVENT_COMPLETE) { state++; // All transmitter data has been sent successfully. } break; } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine txBuffer The buffer which hold the data. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 766 size Number of bytes to be written to the SPI bus. completeCB Pointer to a function to be called when this queued operation is complete context unused by the driver but this is passed to the callback when it is called jobHandle pointer to the buffer handle, this will be set before the function returns and can be used in the ISR callback. Function DRV_SPI_BUFFER_HANDLE DRV_SPI_BufferAddWrite2 ( DRV_HANDLE handle, void *txBuffer, size_t size, DRV_SPI_BUFFER_EVENT_HANDLER completeCB, void * context, DRV_SPI_BUFFER_HANDLE * jobHandle ) DRV_SPI_BufferAddWriteRead2 Function Registers a buffer for a read and write operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic File drv_spi.h C DRV_SPI_BUFFER_HANDLE DRV_SPI_BufferAddWriteRead2(DRV_HANDLE handle, void * txBuffer, size_t txSize, void * rxBuffer, size_t rxSize, DRV_SPI_BUFFER_EVENT_HANDLER completeCB, void * context, DRV_SPI_BUFFER_HANDLE * jobHandle); Returns If the buffer add request is successful, a valid buffer handle is returned. If request is not queued up, DRV_SPI_BUFFER_HANDLE_INVALID is returned. Description Registers a buffer for a read and write operation. Actual transfer will happen in the Task function. The status of this operation can be monitored using DRV_SPI_BufferStatus function. A optional callback can also be provided that will be called when the operation is complete. Remarks None. Preconditions The DRV_SPI_Initialize routine must have been called for the specified SPI driver instance. DRV_SPI_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SPI_Open char myReadBuffer[MY_BUFFER_SIZE], myWriteBuffer[MY_BUFFER_SIZE], state = 0; DRV_SPI_BUFFER_HANDLE bufferHandle, bufferHandle2; switch ( state ) { case 0: bufferHandle = DRV_SPI_BufferAddWriteRead2( handle, myWriteBuffer, 10, myReadBuffer, 10, NULL, NULL, &bufferHandle2 ); if(bufferHandle2 != DRV_SPI_BUFFER_HANDLE_INVALID ) { state++; } break; case 1: if(DRV_SPI_BufferStatus(bufferHandle2) == DRV_SPI_BUFFER_EVENT_COMPLETE) { state++; // All transmitter data has been sent successfully. } break; } Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 767 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine txBuffer The buffer which hold the data. txSize Number of bytes to be written to the SPI bus. rxBuffer The buffer to which the data should be written to. rxSize Number of bytes to be read from the SPI bus completeCB Pointer to a function to be called when this queued operation is complete context unused by the driver but this is passed to the callback when it is called jobHandle pointer to the buffer handle, this will be set before the function returns and can be used in the ISR callback. Function DRV_SPI_BUFFER_HANDLE DRV_SPI_BufferAddWriteRead2( DRV_HANDLE handle, void *txBuffer, void *rxBuffer, size_t size, DRV_SPI_BUFFER_EVENT_HANDLER completeCB, void * context, DRV_SPI_BUFFER_HANDLE * jobHandle ) DRV_SPIn_ReceiverBufferIsFull Function Returns the receive buffer status. 'n' represents the instance of the SPI driver used. Implementation: Static File drv_spi.h C bool DRV_SPIn_ReceiverBufferIsFull(); Returns Receive Buffer Status • 1 - Full • 0 - Empty Description This function returns the receive buffer status (full/empty). Remarks None. Preconditions None. Example bool rxBufStat; // Using instance 1 of SPI driver, that is n = 1 rxBufStat = DRV_SPI1_ReceiverBufferIsFull(); if (rxBufStat) { ... } Function bool DRV_SPIn_ReceiverBufferIsFull(void) DRV_SPIn_TransmitterBufferIsFull Function Returns the transmit buffer status. 'n' represents the instance of the SPI driver used. Implementation: Static Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 768 File drv_spi.h C bool DRV_SPIn_TransmitterBufferIsFull(); Returns Transmit Buffer Status • 1 - Full • 0 - Empty Description This function returns the transmit buffer status (full/empty). Remarks None. Preconditions None. Example bool txBufStat; // Using instance 1 of SPI driver, that is n = 1 txBufStat = DRV_SPI1_TransmitterBufferIsFull(); if (txBufStat) { ... } Function bool DRV_SPIn_TransmitterBufferIsFull(void) d) Miscellaneous Functions e) Data Types and Constants Files Files Name Description drv_spi.h SPI device driver interface file. drv_spi_config_template.h SPI Driver configuration definitions template. Description This section lists the source and header files used by the SPI Driver Library. drv_spi.h SPI device driver interface file. Functions Name Description DRV_SPI_BufferAddRead Registers a buffer for a read operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic DRV_SPI_BufferAddRead2 Registers a buffer for a read operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 769 DRV_SPI_BufferAddWrite Registers a buffer for a write operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic DRV_SPI_BufferAddWrite2 Registers a buffer for a write operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic DRV_SPI_BufferAddWriteRead Registers a buffer for a read and write operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic DRV_SPI_BufferAddWriteRead2 Registers a buffer for a read and write operation. Actual transfer will happen in the Task function. Implementation: Static/Dynamic DRV_SPI_BufferStatus Returns the transmitter and receiver transfer status. Implementation: Static/Dynamic DRV_SPI_ClientConfigure Configures a SPI client with specific data. Implementation: Static/Dynamic DRV_SPI_Close Closes an opened instance of the SPI driver. Implementation: Static/Dynamic DRV_SPI_Deinitialize Deinitializes the specified instance of the SPI driver module. Implementation: Static/Dynamic DRV_SPI_Initialize Initializes the SPI instance for the specified driver index. Implementation: Static/Dynamic DRV_SPI_Open Opens the specified SPI driver instance and returns a handle to it. Implementation: Static/Dynamic DRV_SPI_Status Provides the current status of the SPI driver module. Implementation: Static/Dynamic DRV_SPI_Tasks Maintains the driver's state machine and implements its ISR. Implementation: Static/Dynamic DRV_SPIn_ReceiverBufferIsFull Returns the receive buffer status. 'n' represents the instance of the SPI driver used. Implementation: Static DRV_SPIn_TransmitterBufferIsFull Returns the transmit buffer status. 'n' represents the instance of the SPI driver used. Implementation: Static Description SPI Driver Interface The SPI driver provides a simple interface to manage the SPI module. This file defines the interface definitions and prototypes for the SPI driver. File Name drv_spi.h Company Microchip Technology Inc. drv_spi_config_template.h SPI Driver configuration definitions template. Macros Name Description DRV_SPI_16BIT Controls the compilation of 16 Bit mode DRV_SPI_32BIT Controls the compilation of 32 Bit mode DRV_SPI_8BIT Controls the compilation of 8 Bit mode DRV_SPI_CLIENTS_NUMBER Selects the maximum number of clients. DRV_SPI_DMA Controls the compilation of DMA support DRV_SPI_DMA_DUMMY_BUFFER_SIZE Controls the size of DMA dummy buffer DRV_SPI_DMA_TXFER_SIZE Controls the size of DMA transfers DRV_SPI_EBM Controls the compilation of Enhanced Buffer Mode mode DRV_SPI_ELEMENTS_PER_QUEUE Controls the number of elements that are allocated. DRV_SPI_INSTANCES_NUMBER Selects the maximum number of hardware instances that can be supported by the dynamic driver . DRV_SPI_ISR Controls the compilation of ISR mode Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 770 DRV_SPI_MASTER Controls the compilation of master mode DRV_SPI_POLLED Controls the compilation of Polled mode DRV_SPI_RM Controls the compilation of Standard Buffer mode DRV_SPI_SLAVE Controls the compilation of slave mode Description SPI Driver Configuration Definitions for the Template Version These definitions statically define the driver's mode of operation. File Name drv_spi_config_template.h Company Microchip Technology Inc. SPI Flash Driver Library This section describes the Serial Peripheral Interface (SPI) Flash Driver Library. Introduction This library provides an interface to manage the SST SPI Flash modules (SST25VF020B, SST25VF016B, and SST25VF064C) in different modes of operation. Description The SPI Flash Driver uses SPI interface to establish the communication between SST Flash and Microchip microcontrollers. The SPI module of the controller works as a Master device and the Flash module works as a Slave. The following diagram shows the pin connections that are required to make the driver operational: The SPI Flash Driver is dynamic in nature, so single instance of it can support multiple clients that want to use the same Flash. Multiple instances of the driver can be used when multiple Flash devices are required to be part of the system. The SPI Driver, which is used by the SPI Flash Driver, can be configured for use in either Polled or Interrupt mode. Using the Library This topic describes the basic architecture of the SPI Flash Driver Library and provides information and examples on its use. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 771 Description Interface Header Files: drv_sst25vf016b.h, drv_sst25vf020b.h, or drv_sst25vf064c.h The interface to the SPI Flash Driver Library is defined in the header file. Any C language source (.c) file that uses the SPI Flash Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the SPI Flash Driver Library with a convenient C language interface. This topic describes how that abstraction is modeled in software. Description The SST SPI Flash needs a specific set of commands to be given on its SPI interface along with the required address and data to do different operations. This driver abstracts these requirements and provide simple APIs that can be used to perform Erase, Write, and Read operations. The SPI Driver is used for this purpose. The following layered diagram depicts the communication between different modules. Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the SPI Flash module. Library Interface Section Description System Functions These functions are accessed by the MPLAB Harmony System module and allow the driver to be initialized, deinitialized, and maintained. Core Client Functions These functions allow the application client to open and close the driver. Block Operation Functions These functions enable the Flash module to be erased, written, and read (to/from). Media Interface Functions These functions provide media status and the Flash geometry. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 772 How the Library Works The library provides interfaces to support: • System Initialization/Deinitialization • Opening the Driver • Block Operations System Initialization and Deinitialization Provides information on initializing the system. Description System Initialization and Deinitialization The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization each instance of the SST Flash module would be initialized with the following configuration settings (either passed dynamically at run-time using DRV_SST25VF020B_INIT, DRV_SST25VF016B_INIT, or DRV_SST25VF064C_INIT, or by using Initialization Overrides) that are supported or used by the specific SST Flash device hardware: • Device requested power state: one of the System Module Power States. For specific details please refer to Data Types and Constants in the Library Interface section • The SPI Driver Module Index which is intended to be used to communicate with SST Flash (e.g., DRV_SPI_INDEX_0) • Port Pins of the microcontroller to be used for Chip Select, Write Protection, and Hold operations on the SST Flash device • Maximum Buffer Queue Size for that instance of the SST Flash Driver Using the SST25VF020B as an example, the DRV_SST25VF020B_Initialize function returns an object handle of the type SYS_MODULE_OBJ. After this, the object handle returned by the Initialize interface would be used by the other system interfaces like DRV_SST25VF020B_Deinitialize, DRV_SST25VF020B_Status, and DRV_SST25VF020B_Tasks. Note: The system initialization and the deinitialization settings, only affect the instance of the peripheral that is being initialized or deinitialized. Example: // This code example shows the initialization of the SST25VF020B SPI Flash // Driver. SPI driver index 0 is used for the purpose. Pin numbers 1, 2, // and 3 of PORTB are configured for the Hold pin, Write Protection pin, and // the Chip Select pin, respectively. The maximum buffer queue size is set to 5. DRV_SST25VF020B_INIT SST25VF020BInitData; SYS_MODULE_OBJ objectHandle; SST25VF020BInitData.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; SST25VF020BInitData.spiDriverModuleIndex = DRV_SPI_INDEX_0; SST25VF020BInitData.holdPortChannel = PORT_CHANNEL_B; SST25VF020BInitData.holdBitPosition = PORTS_BIT_POS_1; SST25VF020BInitData.writeProtectPortChannel = PORT_CHANNEL_B; SST25VF020BInitData.writeProtectBitPosition = PORTS_BIT_POS_2; SST25VF020BInitData.chipSelectPortChannel = PORT_CHANNEL_F; SST25VF020BInitData.chipSelectBitPosition = PORTS_BIT_POS_2; SST25VF020BInitData.queueSize = 5; objectHandle = DRV_SST25VF020B_Initialize(DRV_SST25VF020B_INDEX_0, (SYS_MODULE_INIT*)SST25VF020BInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Tasks Routine The system will either call DRV_SST25VF020B_Tasks, from SYS_Tasks (in a polled environment) or DRV_SST25VF020B_Tasks will be called from the ISR of the SPI module in use. Opening the Driver Provides information on opening the driver. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 773 Description To use the SST Flash driver, the application must open the driver. Using the SST25VF020B as an example, this is done by calling the DRV_SST25VF020B_Open function. Calling this function with DRV_IO_INTENT_NONBLOCKING will cause the driver to be opened in non blocking mode. Then DRV_SST25VF020B_BlockErase, DRV_SST25VF020B_BlockWrite and DRV_SST25VF020B_BlockRead functions when called by this client will be non-blocking. The client can also open the driver in Read-only mode (DRV_IO_INTENT_READ), Write-only mode (DRV_IO_INTENT_WRITE), and Exclusive mode (DRV_IO_INTENT_EXCLUSIVE). If the driver has been opened exclusively by a client, it cannot be opened again by another client. If successful, the DRV_SST25VF020B_Open function will return a handle to the driver. This handle records the association between the client and the driver instance that was opened. The DRV_SST25VF020B_Open function may return DRV_HANDLE_INVALID in the situation where the driver is not ready to be opened. When this occurs, the application can try opening the driver again. Note that the open function may return an invalid handle in other (error) cases as well. The following code shows an example of the driver being opened in different modes. DRV_HANDLE sstHandle1, sstHandle2; /* Client 1 opens the SST driver in non blocking mode */ sstHandle1 = DRV_SST25VF020B_Open(DRV_SST25VF020B_INDEX_0, DRV_IO_INTENT_NONBLOCKING); /* Check if the handle is valid */ if(DRV_HANDLE_INVALID == sstHandle1) { /* The driver was not opened successfully. The client * can try opening it again */ } /* Client 2 opens the SST driver in Exclusive Write only mode */ sstHandle2 = DRV_SST25VF020B_Open(DRV_SST25VF020B_INDEX_0, DRV_IO_INTENT_WRITE | DRV_IO_INTENT_EXCLUSIVE); /* Check if the handle is valid */ if(DRV_HANDLE_INVALID == sstHandle2) { /* The driver was not opened successfully. The client * can try opening it again */ } Block Operations Provides information on block operations. Description This driver provides simple client interfaces to Erase, Write, and Read the SST flash in blocks. A block is the unit to represent minimum amount of data that can be erased, written, or read. Block size may differ for Erase, Write, and Read operations. Using the SST25VF020B as an example, the DRV_SST25VF020B_GeometryGet function can be used to determine the different block sizes for the driver. The DRV_SST25VF020B_BlockErase, DRV_SST25VF020B_BlockWrite, and DRV_SST25VF020B_BlockRead functions are used to erase, write, and read the data to/from SST SPI Flash. These functions are always non-blocking. All of these functions follow a standard queue model to read, write, and erase. When any of these functions are called (i.e., a block request is made), the request is queued. The size of the queue is determined by the queueSize member of the DRV_SST25VF020B_INIT data structure. All of the requests in the queue are executed by the DRV_SST25VF020B_Tasks function one-by-one. When the driver adds a request to the queue, it returns a buffer handle. This handle allows the client to track the request as it progresses through the queue. The buffer handle expires when the event associated with the buffer completes. The driver provides driver events (DRV_SST25VF020B_BLOCK_EVENT) that indicate termination of the buffer requests. The following steps can be performed for a simple Block Data Operation: 1. The system should have completed necessary initialization of the SPI Driver and the SST Flash Driver, and the DRV_SST25VF020B_Tasks function should be running in a polled environment. 2. The DRV_SPI_Tasks function should be running in either a polled environment or an interrupt environment. 3. Open the driver using DRV_SST25VF020B_Open with the necessary intent. 4. Set an event handler callback using the function DRV_SST25VF020B_BlockEventHandlerSet. 5. Request for block operations using the functions, DRV_SST25VF020B_BlockErase, DRV_SST25VF020B_BlockWrite, and DRV_SST25VF020B_BlockRead, with the appropriate parameters. 6. Wait for event handler callback to occur and check the status of the block operation using the callback function parameter of type DRV_SST25VF020B_BLOCK_EVENT. 7. The client will be able to close the driver using the function, DRV_SST25VF020B_Close, when required. Example: /* This code example shows usage of the block operations * on the SPI Flash SST25VF020B device */ Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 774 DRV_HANDLE sstHandle1; uint8_t myData1[10], myData2[10]; DRV_SST25VF020B_BLOCK_COMMAND_HANDLE blockHandle1, blockHandle2, blockHandle3; /* The driver is opened for read-write in Exclusive mode */ sstHandle1 = DRV_SST25VF020B_Open(DRV_SST25VF020B_INDEX_0, DRV_IO_INTENT_READWRITE | DRV_IO_INTENT_EXCLUSIVE); /* Check if the driver was opened successfully */ if(DRV_HANDLE_INVALID == sstHandle1) { /* The driver could not be opened successfully */ } /* Register a Buffer Event Handler with SST25VF020B driver. * This event handler function will be called whenever * there is a buffer event. An application defined * context can also be specified. This is returned when * the event handler is called. * */ DRV_SST25VF020B_BlockEventHandlerSet(sstHandle1, APP_SSTBufferEventHandler, NULL); /* Request for all the three block operations one by one */ /* first block API to erase 1 block of the flash starting from address 0x0, each block is of 4kbyte */ DRV_SST25VF020B_BlockErase(sstHandle1, &blockHandle1, 0x0, 1); /* 2nd block API to write myData1 in the first 10 locations of the flash */ DRV_SST25VF020B_BlockWrite(sstHandle1, &blockHandle2, &myData1[0], 0x0, 10); /* 3rd block API to read the first 10 locations of the flash into myData2 */ DRV_SST25VF020B_BlockRead(sstHandle1, &blockHandle3, &myData2[0], 0x0, 10); /* This is the Driver Event Handler */ void APP_SSTBufferEventHandler(DRV_SST25VF020B_BLOCK_EVENT event, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE blockHandle, uintptr_t contextHandle) { switch(event) { case DRV_SST25VF020B_EVENT_BLOCK_COMMAND_COMPLETE: if ( blockHandle == blockHandle3) { /* This means the data was read */ /* Do data verification/processing */ } break; case DRV_SST25VF020B_EVENT_BLOCK_COMMAND_ERROR: /* Error handling here. */ break; default: break; } } Configuring the Library SST25VF016B Configuration Name Description DRV_SST25VF016B_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_SST25VF016B_HARDWARE_HOLD_ENABLE Specifies if the hardware hold feature is enabled or not. DRV_SST25VF016B_HARDWARE_WRITE_PROTECTION_ENABLE Specifies if the hardware write protect feature is enabled or not. DRV_SST25VF016B_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 775 DRV_SST25VF016B_MODE Determines whether the driver is implemented as static or dynamic DRV_SST25VF016B_QUEUE_DEPTH_COMBINED Number of entries of queues in all instances of the driver. SST25VF020B Configuration Name Description DRV_SST25VF020B_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_SST25VF020B_HARDWARE_HOLD_ENABLE Specifies if the hardware hold feature is enabled or not. DRV_SST25VF020B_HARDWARE_WRITE_PROTECTION_ENABLE Specifies if the hardware write protect feature is enabled or not. DRV_SST25VF020B_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported. DRV_SST25VF020B_MODE Determines whether the driver is implemented as static or dynamic. DRV_SST25VF020B_QUEUE_DEPTH_COMBINED Number of entries of queues in all instances of the driver. SST25VF064C Configuration Name Description DRV_SST25VF064C_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_SST25VF064C_HARDWARE_HOLD_ENABLE Specifies whether or not the hardware hold feature is enabled. DRV_SST25VF064C_HARDWARE_WRITE_PROTECTION_ENABLE Specifies whether or not the hardware write protect feature is enabled. DRV_SST25VF064C_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported. DRV_SST25VF064C_MODE Determines whether the driver is implemented as static or dynamic. DRV_SST25VF064C_QUEUE_DEPTH_COMBINED Number of entries of queues in all instances of the driver. Description The SST Flash Driver requires the specification of compile-time configuration macros. These macros define resource usage, feature availability, and dynamic behavior of the driver. These configuration macros should be defined in the system_config.h file. This header can be placed anywhere, 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. SST25VF016B Configuration DRV_SST25VF016B_CLIENTS_NUMBER Macro Sets up the maximum number of clients that can be connected to any hardware instance. File drv_sst25vf016b_config_template.h C #define DRV_SST25VF016B_CLIENTS_NUMBER 4 Description SST25VF016B Client Count Configuration Sets up the maximum number of clients that can be connected to any hardware instance. This value represents the total number of clients to be supported across all hardware instances. So if SST25VF016B-1 will be accessed by 2 clients and SST25VF016B-2 will accessed by 3 clients, then this number should be 5. It is recommended that this be set exactly equal to the number of expected clients. Client support consumes RAM memory space. If this macro is not defined and the DRV_SST25VF016B_INSTANCES_NUMBER macro is not defined, then the driver will be built for static - single client operation. If this macro is defined and the DRV_SST25VF016B_INSTANCES_NUMBER macro is not defined, then the driver will be built for static - multi client operation. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 776 DRV_SST25VF016B_HARDWARE_HOLD_ENABLE Macro Specifies if the hardware hold feature is enabled or not. File drv_sst25vf016b_config_template.h C #define DRV_SST25VF016B_HARDWARE_HOLD_ENABLE false Description SST25VF016B Hardware HOLD Support This macro defines if the hardware hold feature is enabled or not. If hardware hold is enabled, then user must provide a port pin corresponding to HOLD pin on the flash Remarks None DRV_SST25VF016B_HARDWARE_WRITE_PROTECTION_ENABLE Macro Specifies if the hardware write protect feature is enabled or not. File drv_sst25vf016b_config_template.h C #define DRV_SST25VF016B_HARDWARE_WRITE_PROTECTION_ENABLE false Description SST25VF016B Hardware Write Protect Support This macro defines if the hardware Write Protect feature is enabled or not. If hardware write protection is enabled, then user must provide a port pin corresponding to WP pin on the flash Remarks None. DRV_SST25VF016B_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported File drv_sst25vf016b_config_template.h C #define DRV_SST25VF016B_INSTANCES_NUMBER 2 Description SST25VF016B driver objects configuration Sets up the maximum number of hardware instances that can be supported. It is recommended that this number be set exactly equal to the number of SST25VF016B modules that are needed by the application. Hardware Instance support consumes RAM memory space. If this macro is not defined, then the driver will be built statically. Remarks None. DRV_SST25VF016B_MODE Macro Determines whether the driver is implemented as static or dynamic File drv_sst25vf016b_config_template.h Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 777 C #define DRV_SST25VF016B_MODE DYNAMIC Description SST25VF016B mode Determines whether the driver is implemented as static or dynamic. Static drivers control the peripheral directly with peripheral library routines. Remarks None. DRV_SST25VF016B_QUEUE_DEPTH_COMBINED Macro Number of entries of queues in all instances of the driver. File drv_sst25vf016b_config_template.h C #define DRV_SST25VF016B_QUEUE_DEPTH_COMBINED 7 Description SST25VF016B Driver Instance combined queue depth. This macro defines the number of entries of all queues in all instances of the driver. Each hardware instance supports a buffer queue for all the read/write/erase operations. The size of queue is specified either in driver initialization (for dynamic build) or by macros (for static build). A buffer queue will contain buffer queue entries, each related to a BufferAdd request. This configuration macro defines total number of buffer entries that will be available for use between all SST25VF016B driver hardware instances. The buffer queue entries are allocated to individual hardware instances as requested by hardware instances. Once the request is processed, the buffer queue entry is free for use by other hardware instances. The total number of buffer entries in the system determines the ability of the driver to service non blocking erase/write/read requests. If a free buffer entry is not available, the driver will not add the request and will return an invalid buffer handle. More the number of buffer entries, greater the ability of the driver to service and add requests to its queue. A hardware instance additionally can queue up as many buffer entries as specified by its buffer queue size. SST25VF020B Configuration DRV_SST25VF020B_CLIENTS_NUMBER Macro Sets up the maximum number of clients that can be connected to any hardware instance. File drv_sst25vf020b_config_template.h C #define DRV_SST25VF020B_CLIENTS_NUMBER 4 Description SST25VF020B Client Count Configuration Sets up the maximum number of clients that can be connected to any hardware instance. This value represents the total number of clients to be supported across all hardware instances. So if SST25VF020B-1 will be accessed by 2 clients and SST25VF020B-2 will accessed by 3 clients, then this number should be 5. It is recommended that this be set exactly equal to the number of expected clients. Client support consumes RAM memory space. If this macro is not defined and the DRV_SST25VF020B_INSTANCES_NUMBER macro is not defined, then the driver will be built for static - single client operation. If this macro is defined and the DRV_SST25VF020B_INSTANCES_NUMBER macro is not defined, then the driver will be built for static - multi client operation. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 778 DRV_SST25VF020B_HARDWARE_HOLD_ENABLE Macro Specifies if the hardware hold feature is enabled or not. File drv_sst25vf020b_config_template.h C #define DRV_SST25VF020B_HARDWARE_HOLD_ENABLE false Description SST25VF020B Hardware HOLD Support This macro defines if the hardware hold feature is enabled or not. If hardware hold is enabled, then user must provide a port pin corresponding to HOLD pin on the flash Remarks None. DRV_SST25VF020B_HARDWARE_WRITE_PROTECTION_ENABLE Macro Specifies if the hardware write protect feature is enabled or not. File drv_sst25vf020b_config_template.h C #define DRV_SST25VF020B_HARDWARE_WRITE_PROTECTION_ENABLE false Description SST25VF020B Hardware Write Protect Support This macro defines if the hardware Write Protect feature is enabled or not. If hardware write protection is enabled, then user must provide a port pin corresponding to WP pin on the flash Remarks None. DRV_SST25VF020B_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported. File drv_sst25vf020b_config_template.h C #define DRV_SST25VF020B_INSTANCES_NUMBER 2 Description SST25VF020B driver objects configuration Sets up the maximum number of hardware instances that can be supported. It is recommended that this number be set exactly equal to the number of SST25VF020B modules that are needed by the application. Hardware Instance support consumes RAM memory space. If this macro is not defined, then the driver will be built statically. Remarks None. DRV_SST25VF020B_MODE Macro Determines whether the driver is implemented as static or dynamic. File drv_sst25vf020b_config_template.h Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 779 C #define DRV_SST25VF020B_MODE DYNAMIC Description SST25VF020B mode Determines whether the driver is implemented as static or dynamic. Static drivers control the peripheral directly with peripheral library routines. Remarks None. DRV_SST25VF020B_QUEUE_DEPTH_COMBINED Macro Number of entries of queues in all instances of the driver. File drv_sst25vf020b_config_template.h C #define DRV_SST25VF020B_QUEUE_DEPTH_COMBINED 7 Description SST25VF020B Driver Instance combined queue depth. This macro defines the number of entries of all queues in all instances of the driver. Each hardware instance supports a buffer queue for all the read/write/erase operations. The size of queue is specified either in driver initialization (for dynamic build) or by macros (for static build). A buffer queue will contain buffer queue entries, each related to a BufferAdd request. This configuration macro defines total number of buffer entries that will be available for use between all SST25VF020B driver hardware instances. The buffer queue entries are allocated to individual hardware instances as requested by hardware instances. Once the request is processed, the buffer queue entry is free for use by other hardware instances. The total number of buffer entries in the system determines the ability of the driver to service non blocking erase/write/read requests. If a free buffer entry is not available, the driver will not add the request and will return an invalid buffer handle. More the number of buffer entries, greater the ability of the driver to service and add requests to its queue. A hardware instance additionally can queue up as many buffer entries as specified by its buffer queue size. SST25VF064C Configuration DRV_SST25VF064C_CLIENTS_NUMBER Macro Sets up the maximum number of clients that can be connected to any hardware instance. File drv_sst25vf064c_config_template.h C #define DRV_SST25VF064C_CLIENTS_NUMBER 4 Description SST25VF064C Client Count Configuration Sets up the maximum number of clients that can be connected to any hardware instance. This value represents the total number of clients to be supported across all hardware instances. So if SST25VF064C-1 will be accessed by 2 clients and SST25VF064C-2 will accessed by 3 clients, then this number should be 5. It is recommended that this be set exactly equal to the number of expected clients. Client support consumes RAM memory space. If this macro is not defined and the DRV_SST25VF064C_INSTANCES_NUMBER macro is not defined, then the driver will be built for static - single client operation. If this macro is defined and the DRV_SST25VF064C_INSTANCES_NUMBER macro is not defined, then the driver will be built for static - multi client operation. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 780 DRV_SST25VF064C_HARDWARE_HOLD_ENABLE Macro Specifies whether or not the hardware hold feature is enabled. File drv_sst25vf064c_config_template.h C #define DRV_SST25VF064C_HARDWARE_HOLD_ENABLE false Description SST25VF064C Hardware HOLD Support This macro defines whether or not the hardware hold feature is enabled. If hardware hold is enabled, the user must provide a port pin corresponding to the HOLD pin on the Flash device. Remarks None. DRV_SST25VF064C_HARDWARE_WRITE_PROTECTION_ENABLE Macro Specifies whether or not the hardware write protect feature is enabled. File drv_sst25vf064c_config_template.h C #define DRV_SST25VF064C_HARDWARE_WRITE_PROTECTION_ENABLE false Description SST25VF064C Hardware Write Protect Support This macro defines whether or not the hardware Write Protect feature is enabled. If hardware write protection is enabled, the user must provide a port pin corresponding to the WP pin on the Flash device. Remarks None. DRV_SST25VF064C_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported. File drv_sst25vf064c_config_template.h C #define DRV_SST25VF064C_INSTANCES_NUMBER 2 Description SST25VF064C driver objects configuration Sets up the maximum number of hardware instances that can be supported. It is recommended that this number be set exactly equal to the number of SST25VF064C modules that are needed by the application. Hardware Instance support consumes RAM memory space. If this macro is not defined, then the driver will be built statically. Remarks None. DRV_SST25VF064C_MODE Macro Determines whether the driver is implemented as static or dynamic. File drv_sst25vf064c_config_template.h Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 781 C #define DRV_SST25VF064C_MODE DYNAMIC Description SST25VF064C mode Determines whether the driver is implemented as static or dynamic. Static drivers control the peripheral directly with peripheral library routines. Remarks None. DRV_SST25VF064C_QUEUE_DEPTH_COMBINED Macro Number of entries of queues in all instances of the driver. File drv_sst25vf064c_config_template.h C #define DRV_SST25VF064C_QUEUE_DEPTH_COMBINED 7 Description SST25VF064C Driver Instance combined queue depth. This macro defines the number of entries of all queues in all instances of the driver. Each hardware instance supports a buffer queue for all the read/write/erase operations. The size of queue is specified either in driver initialization (for dynamic build) or by macros (for static build). A buffer queue will contain buffer queue entries, each related to a BufferAdd request. This configuration macro defines total number of buffer entries that will be available for use between all SST25VF064C driver hardware instances. The buffer queue entries are allocated to individual hardware instances as requested by hardware instances. Once the request is processed, the buffer queue entry is free for use by other hardware instances. The total number of buffer entries in the system determines the ability of the driver to service non blocking erase/write/read requests. If a free buffer entry is not available, the driver will not add the request and will return an invalid buffer handle. More the number of buffer entries, greater the ability of the driver to service and add requests to its queue. A hardware instance additionally can queue up as many buffer entries as specified by its buffer queue size. Building the Library This section lists the files that are available in the SPI Flash Driver Library. Description This section list the files that are available in the /src folder of the SPI Flash 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. 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 /framework/driver/spi_flash. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description sst25vf016b/drv_sst25vf016b.h Header file that exports the SST25VF016B driver API. sst25vf020b/drv_sst25vf020b.h Header file that exports the SST25VF020B driver API. sst25vf064c/drv_sst25vf064c.h Header file that exports the SST25VF064C driver API. 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 sst25vf016b/src/dynamic/drv_sst25vf016b.c Basic SPI Flash Driver SST25VF016B implementation file. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 782 sst25vf020b/src/dynamic/drv_sst25vf020b.c Basic SPI Flash Driver SST25VF020B implementation file. sst25vf064c/src/dynamic/drv_sst25vf064c.c Basic SPI Flash Driver SST25VF064C implementation file. 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 sst25vf020b/src/dynamic/drv_sst25vf020b_erasewrite.c This file implements an optional BlockEraseWrite feature for the SST25VF020B driver. Module Dependencies The SPI Flash Driver Library depends on the following modules: • SPI Driver Library • Ports System Service Library Library Interface This section describes the API functions of the SPI Flash Driver Library. Refer to each section for a detailed description. SST25FV016B API a) System Functions Name Description DRV_SST25VF016B_Initialize Initializes the SST25VF016B SPI Flash Driver instance for the specified driver index. Implementation: Dynamic DRV_SST25VF016B_Deinitialize Deinitializes the specified instance of the SPI Flash driver module. Implementation: Dynamic DRV_SST25VF016B_Status Gets the current status of the SPI Flash Driver module. Implementation: Dynamic DRV_SST25VF016B_Tasks Maintains the driver's read, erase, and write state machine and implements its ISR. Implementation: Dynamic b) Core Client Functions Name Description DRV_SST25VF016B_Close Closes an opened-instance of the SPI Flash driver. Implementation: Dynamic DRV_SST25VF016B_Open Opens the specified SPI Flash driver instance and returns a handle to it. Implementation: Dynamic DRV_SST25VF016B_ClientStatus Gets current client-specific status of the SPI Flash driver. Implementation: Dynamic c) Block Operation Functions Name Description DRV_SST25VF016B_BlockErase Erase the specified number of blocks in Flash memory. Implementation: Dynamic DRV_SST25VF016B_BlockEventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. Implementation: Dynamic DRV_SST25VF016B_BlockRead Reads blocks of data starting from the specified address in Flash memory. Implementation: Dynamic DRV_SST25VF016B_BlockWrite Write blocks of data starting from a specified address in Flash memory. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 783 d) Media Interface Functions Name Description DRV_SST25VF016B_GeometryGet Returns the geometry of the device. Implementation: Dynamic DRV_SST25VF016B_MediaIsAttached Returns the status of the media. Implementation: Dynamic e) Data Types and Constants Name Description DRV_SST25VF016B_BLOCK_COMMAND_HANDLE Handle identifying block commands of the driver. DRV_SST25VF016B_BLOCK_EVENT Identifies the possible events that can result from a request. DRV_SST25VF016B_CLIENT_STATUS Defines the client status. Implementation: Dynamic DRV_SST25VF016B_EVENT_HANDLER Pointer to a SST25VF016B SPI Flash Driver Event handler function. Implementation: Dynamic DRV_SST25VF016B_INIT Contains all the data necessary to initialize the SPI Flash device. Implementation: Dynamic DRV_SST25VF016B_BLOCK_COMMAND_HANDLE_INVALID This value defines the SPI Flash Driver Block Command Invalid handle. DRV_SST25VF016B_INDEX_0 SPI Flash driver index definitions DRV_SST25VF016B_INDEX_1 This is macro DRV_SST25VF016B_INDEX_1. Description This section contains the SST25V016B Flash device API. a) System Functions DRV_SST25VF016B_Initialize Function Initializes the SST25VF016B SPI Flash Driver instance for the specified driver index. Implementation: Dynamic File drv_sst25vf016b.h C SYS_MODULE_OBJ DRV_SST25VF016B_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Description This function initializes the SPI Flash driver instance for the specified driver index, making it ready for clients to open and use it. Remarks This function must be called before any other SPI Flash function is called. This function should only be called once during system initialization unless DRV_SST25VF016B_Deinitialize is called to deinitialize the driver instance. Build configuration options may be used to statically override options in the "init" structure and will take precedence over initialization data passed using this function. Preconditions None. Example // This code snippet shows an example of initializing the SST25VF016B SPI // Flash Driver. SPI driver index 0 is used for the purpose. Pin numbers 1, 2 // and 3 of port channel B are configured for hold pin, write protection pin Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 784 // and chip select pin respectively. Maximum buffer queue size is set 5. DRV_SST25VF016B_INIT SST25VF016BInitData; SYS_MODULE_OBJ objectHandle; SST25VF016BInitData.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; SST25VF016BInitData.spiDriverModuleIndex = DRV_SPI_INDEX_0; SST25VF016BInitData.holdPortChannel = PORT_CHANNEL_B; SST25VF016BInitData.holdBitPosition = PORTS_BIT_POS_1; SST25VF016BInitData.writeProtectPortChannel = PORT_CHANNEL_B; SST25VF016BInitData.writeProtectBitPosition = PORTS_BIT_POS_2; SST25VF016BInitData.chipSelectPortChannel = PORT_CHANNEL_F; SST25VF016BInitData.chipSelectBitPosition = PORTS_BIT_POS_2; SST25VF016BInitData.queueSize = 5; objectHandle = DRV_SST25VF016B_Initialize(DRV_SST25VF016B_INDEX_0, (SYS_MODULE_INIT*)SST25VF016BInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized init Pointer to a data structure containing data necessary to initialize the driver. Function SYS_MODULE_OBJ DRV_SST25VF016B_Initialize ( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); DRV_SST25VF016B_Deinitialize Function Deinitializes the specified instance of the SPI Flash driver module. Implementation: Dynamic File drv_sst25vf016b.h C void DRV_SST25VF016B_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the SPI Flash Driver module, disabling its operation (and any hardware) and invalidates all of the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. Preconditions Function DRV_SST25VF016B_Initialize should have been called before calling this function. Example // This code snippet shows an example of deinitializing the driver. SYS_MODULE_OBJ object; // Returned from DRV_SST25VF016B_Initialize SYS_STATUS status; Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 785 DRV_SST25VF016B_Deinitialize(object); status = DRV_SST25VF016B_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from the DRV_SST25VF016B_Initialize Function void DRV_SST25VF016B_Deinitialize( SYS_MODULE_OBJ object ) DRV_SST25VF016B_Status Function Gets the current status of the SPI Flash Driver module. Implementation: Dynamic File drv_sst25vf016b.h C SYS_STATUS DRV_SST25VF016B_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is ready and accept requests for new operations SYS_STATUS_UNINITIALIZED - Indicates that the driver is not initialized Description This function provides the current status of the SPI Flash Driver module. Remarks A driver can only be opened when its status is SYS_STATUS_READY. Preconditions Function DRV_SST25VF016B_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_SST25VF016B_Initialize SYS_STATUS SST25VF016BStatus; SST25VF016BStatus = DRV_SST25VF016B_Status(object); else if (SYS_STATUS_ERROR >= SST25VF016BStatus) { // Handle error } Parameters Parameters Description object Driver object handle, returned from the DRV_SST25VF016B_Initialize Function SYS_STATUS DRV_SST25VF016B_Status( SYS_MODULE_OBJ object ) Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 786 DRV_SST25VF016B_Tasks Function Maintains the driver's read, erase, and write state machine and implements its ISR. Implementation: Dynamic File drv_sst25vf016b.h C void DRV_SST25VF016B_Tasks(SYS_MODULE_OBJ object); Returns None. Description This function is used to maintain the driver's internal state machine and should be called from the system's Tasks function. Remarks This function is normally not called directly by an application. It is called by the system's Tasks function (SYS_Tasks). Preconditions The DRV_SST25VF016B_Initialize function must have been called for the specified SPI Flash driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_SST25VF016B_Initialize while (true) { DRV_SST25VF016B_Tasks (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_SST25VF016B_Initialize) Function void DRV_SST25VF016B_Tasks ( SYS_MODULE_OBJ object ); b) Core Client Functions DRV_SST25VF016B_Close Function Closes an opened-instance of the SPI Flash driver. Implementation: Dynamic File drv_sst25vf016b.h C void DRV_SST25VF016B_Close(const DRV_HANDLE handle); Returns None. Description This function closes an opened-instance of the SPI Flash driver, invalidating the handle. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 787 Remarks After calling this function, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_SST25VF016B_Open before the caller may use the driver again. Usually, there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_SST25VF016B_Initialize function must have been called for the specified SPI Flash driver instance. DRV_SST25VF016B_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SST25VF016B_Open DRV_SST25VF016B_Close(handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function void DRV_SST25VF016B_Close( DRV_Handle handle ); DRV_SST25VF016B_Open Function Opens the specified SPI Flash driver instance and returns a handle to it. Implementation: Dynamic File drv_sst25vf016b.h C DRV_HANDLE DRV_SST25VF016B_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent); Returns If successful, the function returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Errors can occur under the following circumstances: • if the number of client objects allocated via DRV_SST25VF016B_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the driver hardware instance being opened is not initialized or is invalid • if the client is trying to open the driver exclusively, but has already been opened in a non exclusive mode by another client. • if the driver status is not ready. The driver status becomes ready inside "DRV_SST25VF016B_Tasks" function. To make the SST Driver status ready and hence successfully "Open" the driver, "Task" routine need to be called periodically. Description This function opens the specified SPI Flash driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Remarks The driver will always work in Non-Blocking mode even if IO-intent is selected as blocking. The handle returned is valid until the DRV_SST25VF016B_Close function is called. This function will NEVER block waiting for hardware. Preconditions Function DRV_SST25VF016B_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_SST25VF016B_Open(DRV_SST25VF016B_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 788 if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } Parameters Parameters Description drvIndex Identifier for the object instance to be opened ioIntent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver Function DRV_HANDLE DRV_SST25VF016B_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent ); DRV_SST25VF016B_ClientStatus Function Gets current client-specific status of the SPI Flash driver. Implementation: Dynamic File drv_sst25vf016b.h C DRV_SST25VF016B_CLIENT_STATUS DRV_SST25VF016B_ClientStatus(const DRV_HANDLE handle); Returns A DRV_SST25VF016B_CLIENT_STATUS value describing the current status of the driver. Description This function gets the client-specific status of the SPI Flash driver associated with the given handle. Remarks This function will not block for hardware access and will immediately return the current status. Preconditions The DRV_SST25VF016B_Initialize function must have been called. DRV_SST25VF016B_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SST25VF016B_Open DRV_SST25VF016B_CLIENT_STATUS clientStatus; clientStatus = DRV_SST25VF016B_ClientStatus(handle); if(DRV_SST25VF016B_CLIENT_STATUS_READY == clientStatus) { // do the tasks } Parameters Parameters Description handle A valid open instance handle, returned from the driver's open Function DRV_SST25VF016B_CLIENT_STATUS DRV_SST25VF016B_ClientStatus(DRV_HANDLE handle); c) Block Operation Functions Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 789 DRV_SST25VF016B_BlockErase Function Erase the specified number of blocks in Flash memory. Implementation: Dynamic File drv_sst25vf016b.h C void DRV_SST25VF016B_BlockErase(const DRV_HANDLE handle, DRV_SST25VF016B_BLOCK_COMMAND_HANDLE * commandHandle, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It Will be DRV_BUFFER_HANDLE_INVALID if the request was not queued. Description This function schedules a non-blocking erase operation in flash memory. The function returns with a valid erase handle in the commandHandle argument if the erase request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. The function returns DRV_SST25VF016B_BLOCK_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if the client opened the driver for read only • if nBlock is 0 • if the queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_SST25VF016B_EVENT_ERASE_COMPLETE event if the erase operation was successful or DRV_SST25VF016B_EVENT_ERASE_ERROR event if the erase operation was not successful. Remarks Write Protection will be disabled for the complete flash memory region in the beginning by default. Preconditions The DRV_SST25VF016B_Initialize function must have been called for the specified SPI Flash driver instance. DRV_SST25VF016B_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SST25VF016B_Open call. Example // Destination address should be block aligned. uint32_t blockStart; uint32_t nBlock; DRV_SST25VF016B_BLOCK_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySST25VF016BHandle is the handle returned // by the DRV_SST25VF016B_Open function. // Client registers an event handler with driver DRV_SST25VF016B_BlockEventHandlerSet(mySST25VF016BHandle, APP_SST25VF016BEventHandler, (uintptr_t)&myAppObj); DRV_SST25VF016B_BlockErase( mySST25VF016BHandle, commandHandle, blockStart, nBlock ); if(DRV_SST25VF016B_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when // the buffer queue is processed. void APP_SST25VF016BEventHandler(DRV_SST25VF016B_BLOCK_EVENT event, DRV_SST25VF016B_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 790 // contextHandle points to myAppObj. switch(event) { case DRV_SST25VF016B_EVENT_ERASE_COMPLETE: // This means the data was transferred. break; case DRV_SST25VF016B_EVENT_ERASE_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle blockStart Start block address in SST25VF016B memory from where the erase should begin. LSBs (A0-A11) of block start address will be ignored to align it with Erase block size boundary. nBlock Total number of blocks to be erased. Each Erase block is of size 4 KByte. Function void DRV_SST25VF016B_BlockErase ( const DRV_HANDLE handle, DRV_SST25VF016B_BLOCK_COMMAND_HANDLE * commandHandle, uint32_t blockStart, uint32_t nBlock ); DRV_SST25VF016B_BlockEventHandlerSet Function Allows a client to identify an event handling function for the driver to call back when queued operation has completed. Implementation: Dynamic File drv_sst25vf016b.h C void DRV_SST25VF016B_BlockEventHandlerSet(const DRV_HANDLE handle, const DRV_SST25VF016B_EVENT_HANDLER eventHandler, const uintptr_t context); Returns None. Description This function allows a client to identify an event handling function for the driver to call back when queued operation has completed. When a client calls any read, write or erase function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the queued operation has completed. The event handler should be set before the client performs any read/write/erase operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued operation has completed, it does not need to register a callback. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 791 Preconditions The DRV_SST25VF016B_Initialize function must have been called for the specified SPI FLash driver instance. DRV_SST25VF016B_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; uint8_t myBuffer[MY_BUFFER_SIZE]; uint32_t blockStart, nBlock; DRV_SST25VF016B_BLOCK_COMMAND_HANDLE commandHandle; // mySST25VF016BHandle is the handle returned // by the DRV_SST25VF016B_Open function. // Client registers an event handler with driver. This is done once. DRV_SST25VF016B_BlockEventHandlerSet( mySST25VF016BHandle, APP_SST25VF016BEventHandler, (uintptr_t)&myAppObj ); DRV_SST25VF016B_BlockRead( mySST25VF016BHandle, commandHandle, &myBuffer, blockStart, nBlock ); if(DRV_SST25VF016B_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event Processing Technique. Event is received when operation is done. void APP_SST25VF016BEventHandler(DRV_SST25VF016B_BLOCK_EVENT event, DRV_SST25VF016B_BLOCK_COMMAND_HANDLE handle, uintptr_t context) { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) context; switch(event) { case DRV_SST25VF016B_EVENT_BLOCK_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_SST25VF016B_EVENT_BLOCK_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function eventHandler Pointer to the event handler function implemented by the user context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_SST25VF016B_BlockEventHandlerSet Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 792 ( const DRV_HANDLE handle, const DRV_SST25VF016B_EVENT_HANDLER eventHandler, const uintptr_t context ); DRV_SST25VF016B_BlockRead Function Reads blocks of data starting from the specified address in Flash memory. Implementation: Dynamic File drv_sst25vf016b.h C void DRV_SST25VF016B_BlockRead(const DRV_HANDLE handle, DRV_SST25VF016B_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t * targetBuffer, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It will be DRV_BUFFER_HANDLE_INVALID if the request was not successful. Description This function schedules a non-blocking read operation for reading blocks of data from flash memory. The function returns with a valid handle in the commandHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_SST25VF016B_BLOCK_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer could not be allocated to the request • if the target buffer pointer is NULL • if the client opened the driver for write only • if the buffer size is 0 • if the read queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_SST25VF016B_EVENT_BLOCK_COMMAND_COMPLETE event if the buffer was processed successfully of DRV_SST25VF016B_EVENT_BLOCK_COMMAND_ERROR event if the buffer was not processed successfully. Remarks The maximum read speed is 33 MHz. Preconditions The DRV_SST25VF016B_Initialize function must have been called for the specified SPI Flash driver instance. DRV_SST25VF016B_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SST25VF016B_Open call. Example uint8_t myBuffer[MY_BUFFER_SIZE]; // address should be block aligned. uint32_t blockStart = SST25VF016B_BASE_ADDRESS_TO_READ_FROM; uint32_t nBlock = 2; DRV_SST25VF016B_BLOCK_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySST25VF016BHandle is the handle returned // by the DRV_SST25VF016B_Open function. // Client registers an event handler with driver DRV_SST25VF016B_BlockEventHandlerSet(mySST25VF016BHandle, APP_SST25VF016BEventHandler, (uintptr_t)&myAppObj); DRV_SST25VF016B_BlockRead( mySST25VF016BHandle, commandHandle, &myBuffer, blockStart, nBlock ); Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 793 if(DRV_SST25VF016B_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when the buffer is processed. void APP_SST25VF016BEventHandler(DRV_SST25VF016B_BLOCK_EVENT event, DRV_SST25VF016B_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_SST25VF016B_EVENT_BLOCK_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_SST25VF016B_EVENT_BLOCK_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle *targetBuffer Buffer into which the data read from the SPI Flash instance will be placed blockStart Start block address in SST25VF016B memory from where the read should begin. It can be any address of the flash. nBlock Total number of blocks to be read. Each Read block is of 1 byte. Function void DRV_SST25VF016B_BlockRead ( const DRV_HANDLE handle, DRV_SST25VF016B_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t *targetBuffer, uint32_t blockStart, uint32_t nBlock ); DRV_SST25VF016B_BlockWrite Function Write blocks of data starting from a specified address in Flash memory. Implementation: Dynamic File drv_sst25vf016b.h C void DRV_SST25VF016B_BlockWrite(DRV_HANDLE handle, DRV_SST25VF016B_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t * sourceBuffer, uint32_t blockStart, uint32_t nBlock); Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 794 Returns The buffer handle is returned in the commandHandle argument. It will be DRV_BUFFER_HANDLE_INVALID if the request was not successful. Description This function schedules a non-blocking write operation for writing blocks of data into flash memory. The function returns with a valid buffer handle in the commandHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_SST25VF016B_BLOCK_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the client opened the driver for read only • if the buffer size is 0 • if the write queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_SST25VF016B_EVENT_BLOCK_COMMAND_COMPLETE event if the buffer was processed successfully or DRV_SST25VF016B_EVENT_BLOCK_COMMAND_ERROR event if the buffer was not processed successfully. Remarks In the case of multi bytes write operation, byte by byte writing will happen instead of Address auto Increment writing. Write Protection will be disabled for the complete flash memory region in the beginning by default. Preconditions The DRV_SST25VF016B_Initialize function must have been called for the specified SPI Flash driver instance. DRV_SST25VF016B_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SST25VF016B_Open call. The flash address location which has to be written, must be erased before using the API DRV_SST25VF016B_BlockErase(). Example uint8_t myBuffer[MY_BUFFER_SIZE]; // address should be block aligned. uint32_t blockStart = SST25VF016B_BASE_ADDRESS_TO_WRITE_TO; uint32_t nBlock = 2; DRV_SST25VF016B_BLOCK_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySST25VF016BHandle is the handle returned // by the DRV_SST25VF016B_Open function. // Client registers an event handler with driver DRV_SST25VF016B_BlockEventHandlerSet(mySST25VF016BHandle, APP_SST25VF016BEventHandler, (uintptr_t)&myAppObj); DRV_SST25VF016B_BlockWrite( mySST25VF016BHandle, commandHandle, &myBuffer, blockStart, nBlock ); if(DRV_SST25VF016B_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_SST25VF016BEventHandler(DRV_SST25VF016B_BLOCK_EVENT event, DRV_SST25VF016B_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_SST25VF016B_EVENT_BLOCK_COMMAND_COMPLETE: Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 795 // This means the data was transferred. break; case DRV_SST25VF016B_EVENT_BLOCK_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle -Pointer to an argument that will contain the return buffer handle sourceBuffer The source buffer containing data to be programmed into SPI Flash blockStart Start block address of SST25VF016B Flash where the write should begin. It can be any address of the flash. nBlock Total number of blocks to be written. Each write block is of 1 byte. Function void DRV_SST25VF016B_BlockWrite ( DRV_HANDLE handle, DRV_SST25VF016B_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t *sourceBuffer, uint32_t blockStart, uint32_t nBlock ); d) Media Interface Functions DRV_SST25VF016B_GeometryGet Function Returns the geometry of the device. Implementation: Dynamic File drv_sst25vf016b.h C SYS_FS_MEDIA_GEOMETRY * DRV_SST25VF016B_GeometryGet(DRV_HANDLE handle); Returns SYS_FS_MEDIA_GEOMETRY - Structure which holds the media geometry information. Description This API gives the following geometrical details of the SST25VF016B Flash: • Media Property • Number of Read/Write/Erase regions in the flash device • Number of Blocks and their size in each region of the device Remarks This function is typically used by File System Media Manager. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 796 Preconditions None. Example SYS_FS_MEDIA_GEOMETRY * sstFlashGeometry; uint32_t readBlockSize, writeBlockSize, eraseBlockSize; uint32_t nReadBlocks, nReadRegions, totalFlashSize; sstFlashGeometry = DRV_SST25VF016B_GeometryGet(sstOpenHandle1); // read block size should be 1 byte readBlockSize = sstFlashGeometry->geometryTable->blockSize; nReadBlocks = sstFlashGeometry->geometryTable->numBlocks; nReadRegions = sstFlashGeometry->numReadRegions; // write block size should be 1 byte writeBlockSize = (sstFlashGeometry->geometryTable +1)->blockSize; // erase block size should be 4k byte eraseBlockSize = (sstFlashGeometry->geometryTable +2)->blockSize; // total flash size should be 256k byte totalFlashSize = readBlockSize * nReadBlocks * nReadRegions; Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function SYS_FS_MEDIA_GEOMETRY DRV_SST25VF016B_GeometryGet( DRV_HANDLE handle ); DRV_SST25VF016B_MediaIsAttached Function Returns the status of the media. Implementation: Dynamic File drv_sst25vf016b.h C bool DRV_SST25VF016B_MediaIsAttached(DRV_HANDLE handle); Returns • True - Media is attached • False - Media is not attached Description This API tells if the media is attached or not. Remarks This function is typically used by File System Media Manager. Preconditions None. Example if (DRV_SST25VF016B_MediaIsAttached(handle)) { // Do Something } Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 797 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function bool DRV_SST25VF016B_MediaIsAttached( DRV_HANDLE handle); e) Data Types and Constants DRV_SST25VF016B_BLOCK_COMMAND_HANDLE Type Handle identifying block commands of the driver. File drv_sst25vf016b.h C typedef SYS_FS_MEDIA_BLOCK_COMMAND_HANDLE DRV_SST25VF016B_BLOCK_COMMAND_HANDLE; Description SPI Flash Driver Block Command Handle A block command handle is returned by a call to the Read, Write, or Erase functions. This handle allows the application to track the completion of the operation. The handle is returned back to the client by the "event handler callback" function registered with the driver. The handle assigned to a client request expires when the client has been notified of the completion of the operation (after event handler function that notifies the client returns) or after the buffer has been retired by the driver if no event handler callback was set. Remarks None. DRV_SST25VF016B_BLOCK_EVENT Enumeration Identifies the possible events that can result from a request. File drv_sst25vf016b.h C typedef enum { DRV_SST25VF016B_EVENT_BLOCK_COMMAND_COMPLETE, DRV_SST25VF016B_EVENT_BLOCK_COMMAND_ERROR } DRV_SST25VF016B_BLOCK_EVENT; Members Members Description DRV_SST25VF016B_EVENT_BLOCK_COMMAND_COMPLETE Block operation has been completed successfully. Read/Write/Erase Complete DRV_SST25VF016B_EVENT_BLOCK_COMMAND_ERROR There was an error during the block operation Read/Write/Erase Error Description SST25VF016B SPI Flash Driver Events This enumeration identifies the possible events that can result from a Read, Write, or Erase request caused by the client. Remarks One of these values is passed in the "event" parameter of the event handling callback function that client registered with the driver by calling the DRV_SST25VF016B_BlockEventHandlerSet function when a block request is completed. DRV_SST25VF016B_CLIENT_STATUS Enumeration Defines the client status. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 798 File drv_sst25vf016b.h C typedef enum { DRV_SST25VF016B_CLIENT_STATUS_READY = DRV_CLIENT_STATUS_READY+0, DRV_SST25VF016B_CLIENT_STATUS_BUSY = DRV_CLIENT_STATUS_BUSY, DRV_SST25VF016B_CLIENT_STATUS_CLOSED = DRV_CLIENT_STATUS_CLOSED, DRV_SST25VF016B_CLIENT_STATUS_ERROR = DRV_CLIENT_STATUS_ERROR } DRV_SST25VF016B_CLIENT_STATUS; Members Members Description DRV_SST25VF016B_CLIENT_STATUS_READY = DRV_CLIENT_STATUS_READY+0 Up and running, ready to start new operations DRV_SST25VF016B_CLIENT_STATUS_BUSY = DRV_CLIENT_STATUS_BUSY Operation in progress, unable to start a new one DRV_SST25VF016B_CLIENT_STATUS_CLOSED = DRV_CLIENT_STATUS_CLOSED Client is closed DRV_SST25VF016B_CLIENT_STATUS_ERROR = DRV_CLIENT_STATUS_ERROR Client Error Description SPI Flash Client Status Defines the various client status codes. Remarks None. DRV_SST25VF016B_EVENT_HANDLER Type Pointer to a SST25VF016B SPI Flash Driver Event handler function. Implementation: Dynamic File drv_sst25vf016b.h C typedef void (* DRV_SST25VF016B_EVENT_HANDLER)(DRV_SST25VF016B_BLOCK_EVENT event, DRV_SST25VF016B_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t context); Returns None. Description SST25VF016B SPI Flash Driver Event Handler Function Pointer This data type defines the required function signature for the SST25VF016B SPI Flash driver event handling callback function. A client must register a pointer to an event handling function whose function signature (parameter and return value types) match the types specified by this function pointer in order to receive event calls back from the driver. The parameters and return values and return value are described here and a partial example implementation is provided. Remarks If the event is DRV_SST25VF016B_EVENT_BLOCK_COMMAND_COMPLETE, it means that the data was transferred successfully. If the event is DRV_SST25VF016B_EVENT_BLOCK_COMMAND_ERROR, it means that the data was not transferred successfully. The context parameter contains the a handle to the client context, provided at the time the event handling function was registered using the DRV_SST25VF016B_BlockEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the read/write/erase request. The event handler function executes in the driver peripheral's interrupt context when the driver is configured for interrupt mode operation. It is recommended of the application to not perform process intensive or blocking operations with in this function. The Read, Write, and Erase functions can be called in the event handler to add a buffer to the driver queue. These functions can only be called to add buffers to the driver whose event handler is running. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 799 Example void APP_MyBufferEventHandler ( DRV_SST25VF016B_BLOCK_EVENT event, DRV_SST25VF016B_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_SST25VF016B_EVENT_BLOCK_COMMAND_COMPLETE: // Handle the completed buffer. break; case DRV_SST25VF016B_EVENT_BLOCK_COMMAND_ERROR: default: // Handle error. break; } } Parameters Parameters Description event Identifies the type of event commandHandle Handle returned from the Read/Write/Erase requests context Value identifying the context of the application that registered the event handling function DRV_SST25VF016B_INIT Structure Contains all the data necessary to initialize the SPI Flash device. Implementation: Dynamic File drv_sst25vf016b.h C typedef struct { SYS_MODULE_INIT moduleInit; SYS_MODULE_INDEX spiDriverModuleIndex; PORTS_CHANNEL holdPortChannel; PORTS_BIT_POS holdBitPosition; PORTS_CHANNEL writeProtectPortChannel; PORTS_BIT_POS writeProtectBitPosition; PORTS_CHANNEL chipSelectPortChannel; PORTS_BIT_POS chipSelectBitPosition; uint32_t queueSize; } DRV_SST25VF016B_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization SYS_MODULE_INDEX spiDriverModuleIndex; Identifies the SPI driver to be used PORTS_CHANNEL holdPortChannel; HOLD pin port channel PORTS_BIT_POS holdBitPosition; HOLD pin port position PORTS_CHANNEL writeProtectPortChannel; Write protect pin port channel PORTS_BIT_POS writeProtectBitPosition; Write Protect Bit pin position PORTS_CHANNEL chipSelectPortChannel; Chip select pin port channel PORTS_BIT_POS chipSelectBitPosition; Chip Select Bit pin position Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 800 uint32_t queueSize; This is the buffer queue size. This is the maximum number of requests that this instance of the driver will queue. For a static build of the driver, this is overridden by the DRV_SST25VF016B_QUEUE_SIZE macro in system_config.h Description SST SPI Flash Driver Initialization Data This structure contains all of the data necessary to initialize the SPI Flash device. Remarks A pointer to a structure of this format containing the desired initialization data must be passed into the DRV_SST25VF016B_Initialize function. DRV_SST25VF016B_BLOCK_COMMAND_HANDLE_INVALID Macro This value defines the SPI Flash Driver Block Command Invalid handle. File drv_sst25vf016b.h C #define DRV_SST25VF016B_BLOCK_COMMAND_HANDLE_INVALID Description SPI Flash Driver Block Event Invalid Handle This value defines the SPI Flash Driver Block Command Invalid handle. It is returned by read/write/erase routines when the request could not be taken. Remarks None. DRV_SST25VF016B_INDEX_0 Macro SPI Flash driver index definitions File drv_sst25vf016b.h C #define DRV_SST25VF016B_INDEX_0 0 Description Driver SPI Flash Module Index reference These constants provide SST25VF016B SPI Flash driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_SST25VF016B_Initialize and DRV_SST25VF016B_Open routines to identify the driver instance in use. DRV_SST25VF016B_INDEX_1 Macro File drv_sst25vf016b.h C #define DRV_SST25VF016B_INDEX_1 1 Description This is macro DRV_SST25VF016B_INDEX_1. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 801 SST25VF020B API a) System Functions Name Description DRV_SST25VF020B_Initialize Initializes the SST25VF020B SPI Flash Driver instance for the specified driver index. Implementation: Dynamic DRV_SST25VF020B_Deinitialize Deinitializes the specified instance of the SPI Flash driver module. Implementation: Dynamic DRV_SST25VF020B_Status Gets the current status of the SPI Flash Driver module. Implementation: Dynamic DRV_SST25VF020B_Tasks Maintains the driver's read, erase, and write state machine and implements its ISR. Implementation: Dynamic b) Core Client Functions Name Description DRV_SST25VF020B_ClientStatus Gets current client-specific status of the SPI Flash driver. Implementation: Dynamic DRV_SST25VF020B_CommandStatus Gets the current status of the command. DRV_SST25VF020B_Close Closes an opened-instance of the SPI Flash driver. Implementation: Dynamic DRV_SST25VF020B_Open Opens the specified SPI Flash driver instance and returns a handle to it. Implementation: Dynamic c) Block Operation Functions Name Description DRV_SST25VF020B_BlockErase Erase the specified number of blocks in Flash memory. Implementation: Dynamic DRV_SST25VF020B_BlockEventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. Implementation: Dynamic DRV_SST25VF020B_BlockRead Reads blocks of data starting from the specified address in Flash memory. Implementation: Dynamic DRV_SST25VF020B_BlockWrite Write blocks of data starting from a specified address in Flash memory. Implementation: Dynamic DRV_SST25VF020B_BlockEraseWrite Erase and Write blocks of data starting from a specified address in SST flash memory. d) Media Interface Functions Name Description DRV_SST25VF020B_GeometryGet Returns the geometry of the device. Implementation: Dynamic DRV_SST25VF020B_MediaIsAttached Returns the status of the media. Implementation: Dynamic e) Data Types and Constants Name Description DRV_SST25VF020B_BLOCK_COMMAND_HANDLE Handle identifying block commands of the driver. DRV_SST25VF020B_BLOCK_EVENT Identifies the possible events that can result from a request. DRV_SST25VF020B_CLIENT_STATUS Defines the client status. DRV_SST25VF020B_EVENT_HANDLER Pointer to a SST25VF020B SPI Flash Driver Event handler function. DRV_SST25VF020B_INIT Contains all the data necessary to initialize the SPI Flash device. DRV_SST25VF020B_COMMAND_STATUS Specifies the status of the command for the read, write and erase operations. DRV_SST25VF020B_BLOCK_COMMAND_HANDLE_INVALID This value defines the SPI Flash Driver Block Command Invalid handle. DRV_SST25VF020B_INDEX_0 SPI Flash driver index definitions. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 802 DRV_SST25VF020B_INDEX_1 This is macro DRV_SST25VF020B_INDEX_1. Description This section contains the SST25V020B Flash device API. a) System Functions DRV_SST25VF020B_Initialize Function Initializes the SST25VF020B SPI Flash Driver instance for the specified driver index. Implementation: Dynamic File drv_sst25vf020b.h C SYS_MODULE_OBJ DRV_SST25VF020B_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Description This function initializes the SPI Flash driver instance for the specified driver index, making it ready for clients to open and use it. Remarks This function must be called before any other SPI Flash function is called. This function should only be called once during system initialization unless DRV_SST25VF020B_Deinitialize is called to deinitialize the driver instance. Build configuration options may be used to statically override options in the "init" structure and will take precedence over initialization data passed using this function. Preconditions None. Example // This code snippet shows an example of initializing the SST25VF020B SPI // Flash Driver. SPI driver index 0 is used for the purpose. Pin numbers 1, 2 // and 3 of port channel B are configured for hold pin, write protection pin // and chip select pin respectively. Maximum buffer queue size is set 5. DRV_SST25VF020B_INIT SST25VF020BInitData; SYS_MODULE_OBJ objectHandle; SST25VF020BInitData.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; SST25VF020BInitData.spiDriverModuleIndex = DRV_SPI_INDEX_0; SST25VF020BInitData.holdPortChannel = PORT_CHANNEL_B; SST25VF020BInitData.holdBitPosition = PORTS_BIT_POS_1; SST25VF020BInitData.writeProtectPortChannel = PORT_CHANNEL_B; SST25VF020BInitData.writeProtectBitPosition = PORTS_BIT_POS_2; SST25VF020BInitData.chipSelectPortChannel = PORT_CHANNEL_F; SST25VF020BInitData.chipSelectBitPosition = PORTS_BIT_POS_2; SST25VF020BInitData.queueSize = 5; objectHandle = DRV_SST25VF020B_Initialize(DRV_SST25VF020B_INDEX_0, (SYS_MODULE_INIT*)SST25VF020BInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 803 Parameters Parameters Description index Identifier for the instance to be initialized init Pointer to a data structure containing data necessary to initialize the driver. Function SYS_MODULE_OBJ DRV_SST25VF020B_Initialize ( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); DRV_SST25VF020B_Deinitialize Function Deinitializes the specified instance of the SPI Flash driver module. Implementation: Dynamic File drv_sst25vf020b.h C void DRV_SST25VF020B_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the SPI Flash Driver module, disabling its operation (and any hardware) and invalidates all of the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. Preconditions Function DRV_SST25VF020B_Initialize should have been called before calling this function. Example // This code snippet shows an example of deinitializing the driver. SYS_MODULE_OBJ object; // Returned from DRV_SST25VF020B_Initialize SYS_STATUS status; DRV_SST25VF020B_Deinitialize(object); status = DRV_SST25VF020B_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from the DRV_SST25VF020B_Initialize Function void DRV_SST25VF020B_Deinitialize( SYS_MODULE_OBJ object ) Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 804 DRV_SST25VF020B_Status Function Gets the current status of the SPI Flash Driver module. Implementation: Dynamic File drv_sst25vf020b.h C SYS_STATUS DRV_SST25VF020B_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is ready and accept requests for new operations SYS_STATUS_UNINITIALIZED - Indicates that the driver is not initialized Description This function provides the current status of the SPI Flash Driver module. Remarks A driver can only be opened when its status is SYS_STATUS_READY. Preconditions Function DRV_SST25VF020B_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_SST25VF020B_Initialize SYS_STATUS SST25VF020BStatus; SST25VF020BStatus = DRV_SST25VF020B_Status(object); else if (SYS_STATUS_ERROR >= SST25VF020BStatus) { // Handle error } Parameters Parameters Description object Driver object handle, returned from the DRV_SST25VF020B_Initialize Function SYS_STATUS DRV_SST25VF020B_Status( SYS_MODULE_OBJ object ) DRV_SST25VF020B_Tasks Function Maintains the driver's read, erase, and write state machine and implements its ISR. Implementation: Dynamic File drv_sst25vf020b.h C void DRV_SST25VF020B_Tasks(SYS_MODULE_OBJ object); Returns None. Description This function is used to maintain the driver's internal state machine and should be called from the system's Tasks function. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 805 Remarks This function is normally not called directly by an application. It is called by the system's Tasks function (SYS_Tasks). Preconditions The DRV_SST25VF020B_Initialize function must have been called for the specified SPI Flash driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_SST25VF020B_Initialize while (true) { DRV_SST25VF020B_Tasks (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_SST25VF020B_Initialize) Function void DRV_SST25VF020B_Tasks ( SYS_MODULE_OBJ object ); b) Core Client Functions DRV_SST25VF020B_ClientStatus Function Gets current client-specific status of the SPI Flash driver. Implementation: Dynamic File drv_sst25vf020b.h C DRV_SST25VF020B_CLIENT_STATUS DRV_SST25VF020B_ClientStatus(const DRV_HANDLE handle); Returns A DRV_SST25VF020B_CLIENT_STATUS value describing the current status of the driver. Description This function gets the client-specific status of the SPI Flash driver associated with the given handle. Remarks This function will not block for hardware access and will immediately return the current status. Preconditions The DRV_SST25VF020B_Initialize function must have been called. DRV_SST25VF020B_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SST25VF020B_Open DRV_SST25VF020B_CLIENT_STATUS clientStatus; clientStatus = DRV_SST25VF020B_ClientStatus(handle); if(DRV_SST25VF020B_CLIENT_STATUS_READY == clientStatus) { // do the tasks } Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 806 Parameters Parameters Description handle A valid open instance handle, returned from the driver's open Function DRV_SST25VF020B_CLIENT_STATUS DRV_SST25VF020B_ClientStatus(DRV_HANDLE handle); DRV_SST25VF020B_CommandStatus Function Gets the current status of the command. File drv_sst25vf020b.h C DRV_SST25VF020B_COMMAND_STATUS DRV_SST25VF020B_CommandStatus(const DRV_HANDLE handle, const DRV_SST25VF020B_BLOCK_COMMAND_HANDLE commandHandle); Returns A DRV_SST25VF020B_COMMAND_STATUS value describing the current status of the buffer. Returns DRV_SST25VF020B_BLOCK_COMMAND_HANDLE_INVALID if the client handle or the command handle is not valid. Description This routine gets the current status of the buffer. The application must use this routine where the status of a scheduled buffer needs to polled on. The function may return DRV_SST25VF020B_BLOCK_COMMAND_HANDLE_INVALID in a case where the buffer handle has expired. A buffer handle expires when the internal buffer object is re-assigned to another erase, read or write request. It is recommended that this function be called regularly in order to track the buffer status correctly. The application can alternatively register an event handler to receive write, read or erase operation completion events. Remarks This function will not block for hardware access and will immediately return the current status. Preconditions Block command request must have been made using Erase, Read or Write APIs to get a valid command handle. Example DRV_HANDLE sstOpenHandle; // Returned from DRV_SST25VF020B_Open DRV_SST25VF020B_BLOCK_COMMAND_HANDLE commandHandle; DRV_SST25VF020B_BlockErase ( sstOpenHandle, &commandHandle, 0, 1 ); if(DRV_SST25VF020B_CommandStatus(sstOpenHandle, commandHandle) == DRV_SST25VF020B_COMMAND_COMPLETED ); { // do something } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine commandHandle A valid command handle, returned from Read/Write/Erase APIs. Function DRV_SST25VF020B_COMMAND_STATUS DRV_SST25VF020B_CommandStatus ( Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 807 const DRV_HANDLE handle, const DRV_SST25VF020B_BLOCK_COMMAND_HANDLE commandHandle ); DRV_SST25VF020B_Close Function Closes an opened-instance of the SPI Flash driver. Implementation: Dynamic File drv_sst25vf020b.h C void DRV_SST25VF020B_Close(const DRV_HANDLE handle); Returns None. Description This function closes an opened-instance of the SPI Flash driver, invalidating the handle. Remarks After calling this function, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_SST25VF020B_Open before the caller may use the driver again. Usually, there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_SST25VF020B_Initialize function must have been called for the specified SPI Flash driver instance. DRV_SST25VF020B_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SST25VF020B_Open DRV_SST25VF020B_Close(handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function void DRV_SST25VF020B_Close( DRV_Handle handle ); DRV_SST25VF020B_Open Function Opens the specified SPI Flash driver instance and returns a handle to it. Implementation: Dynamic File drv_sst25vf020b.h C DRV_HANDLE DRV_SST25VF020B_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent); Returns If successful, the function returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Errors can occur under the following circumstances: • if the number of client objects allocated via DRV_SST25VF020B_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the driver hardware instance being opened is not initialized or is invalid • if the client is trying to open the driver exclusively, but has already been opened in a non exclusive mode by another client. • if the driver status is not ready. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 808 The driver status becomes ready inside "DRV_SST25VF020B_Tasks" function. To make the SST Driver status ready and hence successfully "Open" the driver, "Task" routine need to be called periodically. Description This function opens the specified SPI Flash driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Remarks The driver will always work in Non-Blocking mode even if IO-intent is selected as blocking. The handle returned is valid until the DRV_SST25VF020B_Close function is called. This function will NEVER block waiting for hardware. Preconditions Function DRV_SST25VF020B_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_SST25VF020B_Open(DRV_SST25VF020B_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } Parameters Parameters Description drvIndex Identifier for the object instance to be opened ioIntent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver Function DRV_HANDLE DRV_SST25VF020B_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent ); c) Block Operation Functions DRV_SST25VF020B_BlockErase Function Erase the specified number of blocks in Flash memory. Implementation: Dynamic File drv_sst25vf020b.h C void DRV_SST25VF020B_BlockErase(const DRV_HANDLE handle, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE * commandHandle, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It Will be DRV_BUFFER_HANDLE_INVALID if the request was not queued. Description This function schedules a non-blocking erase operation in flash memory. The function returns with a valid erase handle in the commandHandle argument if the erase request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. The function returns DRV_SST25VF020B_BLOCK_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 809 • if the client opened the driver for read only • if nBlock is 0 • if the queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_SST25VF020B_EVENT_ERASE_COMPLETE event if the erase operation was successful or DRV_SST25VF020B_EVENT_ERASE_ERROR event if the erase operation was not successful. Remarks Write Protection will be disabled for the complete flash memory region in the beginning by default. Preconditions The DRV_SST25VF020B_Initialize function must have been called for the specified SPI Flash driver instance. DRV_SST25VF020B_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SST25VF020B_Open call. Example // Destination address should be block aligned. uint32_t blockStart; uint32_t nBlock; DRV_SST25VF020B_BLOCK_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySST25VF020BHandle is the handle returned // by the DRV_SST25VF020B_Open function. // Client registers an event handler with driver DRV_SST25VF020B_BlockEventHandlerSet(mySST25VF020BHandle, APP_SST25VF020BEventHandler, (uintptr_t)&myAppObj); DRV_SST25VF020B_BlockErase( mySST25VF020BHandle, commandHandle, blockStart, nBlock ); if(DRV_SST25VF020B_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when // the buffer queue is processed. void APP_SST25VF020BEventHandler(DRV_SST25VF020B_BLOCK_EVENT event, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_SST25VF020B_EVENT_ERASE_COMPLETE: // This means the data was transferred. break; case DRV_SST25VF020B_EVENT_ERASE_ERROR: // Error handling here. break; default: break; } } Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 810 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle blockStart Start block address in SST25VF020B memory from where the erase should begin. LSBs (A0-A11) of block start address will be ignored to align it with Erase block size boundary. nBlock Total number of blocks to be erased. Each Erase block is of size 4 KByte. Function void DRV_SST25VF020B_BlockErase ( const DRV_HANDLE handle, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE * commandHandle, uint32_t blockStart, uint32_t nBlock ); DRV_SST25VF020B_BlockEventHandlerSet Function Allows a client to identify an event handling function for the driver to call back when queued operation has completed. Implementation: Dynamic File drv_sst25vf020b.h C void DRV_SST25VF020B_BlockEventHandlerSet(const DRV_HANDLE handle, const DRV_SST25VF020B_EVENT_HANDLER eventHandler, const uintptr_t context); Returns None. Description This function allows a client to identify an event handling function for the driver to call back when queued operation has completed. When a client calls any read, write or erase function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the queued operation has completed. The event handler should be set before the client performs any read/write/erase operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued operation has completed, it does not need to register a callback. Preconditions The DRV_SST25VF020B_Initialize function must have been called for the specified SPI FLash driver instance. DRV_SST25VF020B_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; uint8_t myBuffer[MY_BUFFER_SIZE]; uint32_t blockStart, nBlock; DRV_SST25VF020B_BLOCK_COMMAND_HANDLE commandHandle; // mySST25VF020BHandle is the handle returned // by the DRV_SST25VF020B_Open function. // Client registers an event handler with driver. This is done once. DRV_SST25VF020B_BlockEventHandlerSet( mySST25VF020BHandle, Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 811 APP_SST25VF020BEventHandler, (uintptr_t)&myAppObj ); DRV_SST25VF020B_BlockRead( mySST25VF020BHandle, commandHandle, &myBuffer, blockStart, nBlock ); if(DRV_SST25VF020B_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event Processing Technique. Event is received when operation is done. void APP_SST25VF020BEventHandler(DRV_SST25VF020B_BLOCK_EVENT event, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE handle, uintptr_t context) { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) context; switch(event) { case DRV_SST25VF020B_EVENT_BLOCK_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_SST25VF020B_EVENT_BLOCK_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function eventHandler Pointer to the event handler function implemented by the user context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_SST25VF020B_BlockEventHandlerSet ( const DRV_HANDLE handle, const DRV_SST25VF020B_EVENT_HANDLER eventHandler, const uintptr_t context ); DRV_SST25VF020B_BlockRead Function Reads blocks of data starting from the specified address in Flash memory. Implementation: Dynamic File drv_sst25vf020b.h C void DRV_SST25VF020B_BlockRead(const DRV_HANDLE handle, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t * targetBuffer, uint32_t blockStart, uint32_t nBlock); Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 812 Returns The buffer handle is returned in the commandHandle argument. It will be DRV_BUFFER_HANDLE_INVALID if the request was not successful. Description This function schedules a non-blocking read operation for reading blocks of data from flash memory. The function returns with a valid handle in the commandHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_SST25VF020B_BLOCK_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer could not be allocated to the request • if the target buffer pointer is NULL • if the client opened the driver for write only • if the buffer size is 0 • if the read queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_SST25VF020B_EVENT_BLOCK_COMMAND_COMPLETE event if the buffer was processed successfully of DRV_SST25VF020B_EVENT_BLOCK_COMMAND_ERROR event if the buffer was not processed successfully. Remarks The maximum read speed is 33 MHz. Preconditions The DRV_SST25VF020B_Initialize function must have been called for the specified SPI Flash driver instance. DRV_SST25VF020B_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SST25VF020B_Open call. Example uint8_t myBuffer[MY_BUFFER_SIZE]; // address should be block aligned. uint32_t blockStart = SST25VF020B_BASE_ADDRESS_TO_READ_FROM; uint32_t nBlock = 2; DRV_SST25VF020B_BLOCK_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySST25VF020BHandle is the handle returned // by the DRV_SST25VF020B_Open function. // Client registers an event handler with driver DRV_SST25VF020B_BlockEventHandlerSet(mySST25VF020BHandle, APP_SST25VF020BEventHandler, (uintptr_t)&myAppObj); DRV_SST25VF020B_BlockRead( mySST25VF020BHandle, commandHandle, &myBuffer, blockStart, nBlock ); if(DRV_SST25VF020B_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when the buffer is processed. void APP_SST25VF020BEventHandler(DRV_SST25VF020B_BLOCK_EVENT event, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_SST25VF020B_EVENT_BLOCK_COMMAND_COMPLETE: // This means the data was transferred. break; Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 813 case DRV_SST25VF020B_EVENT_BLOCK_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle *targetBuffer Buffer into which the data read from the SPI Flash instance will be placed blockStart Start block address in SST25VF020B memory from where the read should begin. It can be any address of the flash. nBlock Total number of blocks to be read. Each Read block is of 1 byte. Function void DRV_SST25VF020B_BlockRead ( const DRV_HANDLE handle, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t *targetBuffer, uint32_t blockStart, uint32_t nBlock ); DRV_SST25VF020B_BlockWrite Function Write blocks of data starting from a specified address in Flash memory. Implementation: Dynamic File drv_sst25vf020b.h C void DRV_SST25VF020B_BlockWrite(DRV_HANDLE handle, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t * sourceBuffer, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It will be DRV_BUFFER_HANDLE_INVALID if the request was not successful. Description This function schedules a non-blocking write operation for writing blocks of data into flash memory. The function returns with a valid buffer handle in the commandHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_SST25VF020B_BLOCK_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the client opened the driver for read only • if the buffer size is 0 • if the write queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_SST25VF020B_EVENT_BLOCK_COMMAND_COMPLETE event if the buffer was processed successfully or DRV_SST25VF020B_EVENT_BLOCK_COMMAND_ERROR event if the buffer was not processed successfully. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 814 Remarks In the case of multi bytes write operation, byte by byte writing will happen instead of Address auto Increment writing. Write Protection will be disabled for the complete flash memory region in the beginning by default. Preconditions The DRV_SST25VF020B_Initialize function must have been called for the specified SPI Flash driver instance. DRV_SST25VF020B_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SST25VF020B_Open call. The flash address location which has to be written, must be erased before using the API DRV_SST25VF020B_BlockErase(). Example uint8_t myBuffer[MY_BUFFER_SIZE]; // address should be block aligned. uint32_t blockStart = SST25VF020B_BASE_ADDRESS_TO_WRITE_TO; uint32_t nBlock = 2; DRV_SST25VF020B_BLOCK_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySST25VF020BHandle is the handle returned // by the DRV_SST25VF020B_Open function. // Client registers an event handler with driver DRV_SST25VF020B_BlockEventHandlerSet(mySST25VF020BHandle, APP_SST25VF020BEventHandler, (uintptr_t)&myAppObj); DRV_SST25VF020B_BlockWrite( mySST25VF020BHandle, commandHandle, &myBuffer, blockStart, nBlock ); if(DRV_SST25VF020B_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_SST25VF020BEventHandler(DRV_SST25VF020B_BLOCK_EVENT event, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_SST25VF020B_EVENT_BLOCK_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_SST25VF020B_EVENT_BLOCK_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle -Pointer to an argument that will contain the return buffer handle Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 815 sourceBuffer The source buffer containing data to be programmed into SPI Flash blockStart Start block address of SST25VF020B Flash where the write should begin. It can be any address of the flash. nBlock Total number of blocks to be written. Each write block is of 1 byte. Function void DRV_SST25VF020B_BlockWrite ( DRV_HANDLE handle, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t *sourceBuffer, uint32_t blockStart, uint32_t nBlock ); DRV_SST25VF020B_BlockEraseWrite Function Erase and Write blocks of data starting from a specified address in SST flash memory. File drv_sst25vf020b.h C void DRV_SST25VF020B_BlockEraseWrite(DRV_HANDLE hClient, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t * sourceBuffer, uint32_t blockStart, uint32_t nBlock); Description This function combines the step of erasing blocks of SST Flash and then writing the data. The application can use this function if it wants to avoid having to explicitly delete a block in order to update the bytes contained in the block. This function schedules a non-blocking operation to erase and write blocks of data into SST flash. The function returns with a valid buffer handle in the commandHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_SST25VF020B_BLOCK_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the client opened the driver for read only • if the buffer size is 0 • if the queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_SST25VF020B_EVENT_BLOCK_COMMAND_COMPLETE event if the buffer was processed successfully or DRV_SST25VF020B_EVENT_ERASE_ERROR event if the buffer was not processed successfully. Remarks Refer to drv_sst25vf020b.h for usage information. Function void DRV_SST25VF020B_BlockEraseWrite ( const DRV_HANDLE handle, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE * commandHandle, void * sourceBuffer, uint32_t writeBlockStart, uint32_t nWriteBlock ) d) Media Interface Functions Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 816 DRV_SST25VF020B_GeometryGet Function Returns the geometry of the device. Implementation: Dynamic File drv_sst25vf020b.h C SYS_FS_MEDIA_GEOMETRY * DRV_SST25VF020B_GeometryGet(DRV_HANDLE handle); Returns SYS_FS_MEDIA_GEOMETRY - Structure which holds the media geometry information. Description This API gives the following geometrical details of the SST25VF020B Flash: • Media Property • Number of Read/Write/Erase regions in the flash device • Number of Blocks and their size in each region of the device Remarks This function is typically used by File System Media Manager. Preconditions None. Example SYS_FS_MEDIA_GEOMETRY * sstFlashGeometry; uint32_t readBlockSize, writeBlockSize, eraseBlockSize; uint32_t nReadBlocks, nReadRegions, totalFlashSize; sstFlashGeometry = DRV_SST25VF020B_GeometryGet(sstOpenHandle1); // read block size should be 1 byte readBlockSize = sstFlashGeometry->geometryTable->blockSize; nReadBlocks = sstFlashGeometry->geometryTable->numBlocks; nReadRegions = sstFlashGeometry->numReadRegions; // write block size should be 1 byte writeBlockSize = (sstFlashGeometry->geometryTable +1)->blockSize; // erase block size should be 4k byte eraseBlockSize = (sstFlashGeometry->geometryTable +2)->blockSize; // total flash size should be 256k byte totalFlashSize = readBlockSize * nReadBlocks * nReadRegions; Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function SYS_FS_MEDIA_GEOMETRY DRV_SST25VF020B_GeometryGet( DRV_HANDLE handle ); DRV_SST25VF020B_MediaIsAttached Function Returns the status of the media. Implementation: Dynamic File drv_sst25vf020b.h Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 817 C bool DRV_SST25VF020B_MediaIsAttached(DRV_HANDLE handle); Returns • True - Media is attached • False - Media is not attached Description This function determines whether or not the media is attached. Remarks This function is typically used by File System Media Manager. Preconditions None. Example if (DRV_SST25VF020B_MediaIsAttached(handle)) { // Do Something } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function bool DRV_SST25VF020B_MediaIsAttached( DRV_HANDLE handle); e) Data Types and Constants DRV_SST25VF020B_BLOCK_COMMAND_HANDLE Type Handle identifying block commands of the driver. File drv_sst25vf020b.h C typedef SYS_FS_MEDIA_BLOCK_COMMAND_HANDLE DRV_SST25VF020B_BLOCK_COMMAND_HANDLE; Description SPI Flash Driver Block Command Handle A block command handle is returned by a call to the Read, Write, or Erase functions. This handle allows the application to track the completion of the operation. The handle is returned back to the client by the "event handler callback" function registered with the driver. The handle assigned to a client request expires when the client has been notified of the completion of the operation (after event handler function that notifies the client returns) or after the buffer has been retired by the driver if no event handler callback was set. Remarks None. DRV_SST25VF020B_BLOCK_EVENT Enumeration Identifies the possible events that can result from a request. File drv_sst25vf020b.h C typedef enum { Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 818 DRV_SST25VF020B_EVENT_BLOCK_COMMAND_COMPLETE, DRV_SST25VF020B_EVENT_BLOCK_COMMAND_ERROR } DRV_SST25VF020B_BLOCK_EVENT; Members Members Description DRV_SST25VF020B_EVENT_BLOCK_COMMAND_COMPLETE Block operation has been completed successfully. Read/Write/Erase Complete DRV_SST25VF020B_EVENT_BLOCK_COMMAND_ERROR There was an error during the block operation Read/Write/Erase Error Description SST25VF020B SPI Flash Driver Events This enumeration identifies the possible events that can result from a Read, Write, or Erase request caused by the client. Remarks One of these values is passed in the "event" parameter of the event handling callback function that client registered with the driver by calling the DRV_SST25VF020B_BlockEventHandlerSet function when a block request is completed. DRV_SST25VF020B_CLIENT_STATUS Enumeration Defines the client status. File drv_sst25vf020b.h C typedef enum { DRV_SST25VF020B_CLIENT_STATUS_READY = DRV_CLIENT_STATUS_READY+0, DRV_SST25VF020B_CLIENT_STATUS_BUSY = DRV_CLIENT_STATUS_BUSY, DRV_SST25VF020B_CLIENT_STATUS_CLOSED = DRV_CLIENT_STATUS_CLOSED, DRV_SST25VF020B_CLIENT_STATUS_ERROR = DRV_CLIENT_STATUS_ERROR } DRV_SST25VF020B_CLIENT_STATUS; Members Members Description DRV_SST25VF020B_CLIENT_STATUS_READY = DRV_CLIENT_STATUS_READY+0 Up and running, ready to start new operations DRV_SST25VF020B_CLIENT_STATUS_BUSY = DRV_CLIENT_STATUS_BUSY Operation in progress, unable to start a new one DRV_SST25VF020B_CLIENT_STATUS_CLOSED = DRV_CLIENT_STATUS_CLOSED Client is closed DRV_SST25VF020B_CLIENT_STATUS_ERROR = DRV_CLIENT_STATUS_ERROR Client Error Description SPI Flash Client Status Defines the various client status codes. Remarks None. DRV_SST25VF020B_EVENT_HANDLER Type Pointer to a SST25VF020B SPI Flash Driver Event handler function. File drv_sst25vf020b.h C typedef void (* DRV_SST25VF020B_EVENT_HANDLER)(DRV_SST25VF020B_BLOCK_EVENT event, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t context); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 819 Description SST25VF020B SPI Flash Driver Event Handler Function Pointer This data type defines the required function signature for the SST25VF020B SPI Flash driver event handling callback function. A client must register a pointer to an event handling function whose function signature (parameter and return value types) match the types specified by this function pointer in order to receive event calls back from the driver. The parameters and return values and return value are described here and a partial example implementation is provided. Remarks If the event is DRV_SST25VF020B_EVENT_BLOCK_COMMAND_COMPLETE, it means that the data was transferred successfully. If the event is DRV_SST25VF020B_EVENT_BLOCK_COMMAND_ERROR, it means that the data was not transferred successfully. The context parameter contains the a handle to the client context, provided at the time the event handling function was registered using the DRV_SST25VF020B_BlockEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the read/write/erase request. The event handler function executes in the driver peripheral's interrupt context when the driver is configured for interrupt mode operation. It is recommended of the application to not perform process intensive or blocking operations with in this function. The Read, Write, and Erase functions can be called in the event handler to add a buffer to the driver queue. These functions can only be called to add buffers to the driver whose event handler is running. Example void APP_MyBufferEventHandler ( DRV_SST25VF020B_BLOCK_EVENT event, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_SST25VF020B_EVENT_BLOCK_COMMAND_COMPLETE: // Handle the completed buffer. break; case DRV_SST25VF020B_EVENT_BLOCK_COMMAND_ERROR: default: // Handle error. break; } } Parameters Parameters Description event Identifies the type of event commandHandle Handle returned from the Read/Write/Erase requests context Value identifying the context of the application that registered the event handling function DRV_SST25VF020B_INIT Structure Contains all the data necessary to initialize the SPI Flash device. File drv_sst25vf020b.h C typedef struct { SYS_MODULE_INIT moduleInit; SYS_MODULE_INDEX spiDriverModuleIndex; PORTS_CHANNEL holdPortChannel; PORTS_BIT_POS holdBitPosition; Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 820 PORTS_CHANNEL writeProtectPortChannel; PORTS_BIT_POS writeProtectBitPosition; PORTS_CHANNEL chipSelectPortChannel; PORTS_BIT_POS chipSelectBitPosition; uint32_t queueSize; } DRV_SST25VF020B_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization SYS_MODULE_INDEX spiDriverModuleIndex; Identifies the SPI driver to be used PORTS_CHANNEL holdPortChannel; HOLD pin port channel PORTS_BIT_POS holdBitPosition; HOLD pin port position PORTS_CHANNEL writeProtectPortChannel; Write protect pin port channel PORTS_BIT_POS writeProtectBitPosition; Write Protect Bit pin position PORTS_CHANNEL chipSelectPortChannel; Chip select pin port channel PORTS_BIT_POS chipSelectBitPosition; Chip Select Bit pin position uint32_t queueSize; This is the buffer queue size. This is the maximum number of requests that this instance of the driver will queue. For a static build of the driver, this is overridden by the DRV_SST25VF020B_QUEUE_SIZE macro in system_config.h Description SST SPI Flash Driver Initialization Data This structure contains all of the data necessary to initialize the SPI Flash device. Remarks A pointer to a structure of this format containing the desired initialization data must be passed into the DRV_SST25VF020B_Initialize function. DRV_SST25VF020B_COMMAND_STATUS Enumeration Specifies the status of the command for the read, write and erase operations. File drv_sst25vf020b.h C typedef enum { DRV_SST25VF020B_COMMAND_COMPLETED, DRV_SST25VF020B_COMMAND_QUEUED, DRV_SST25VF020B_COMMAND_IN_PROGRESS, DRV_SST25VF020B_COMMAND_ERROR_UNKNOWN } DRV_SST25VF020B_COMMAND_STATUS; Members Members Description DRV_SST25VF020B_COMMAND_COMPLETED Requested operation is completed DRV_SST25VF020B_COMMAND_QUEUED Scheduled but not started DRV_SST25VF020B_COMMAND_IN_PROGRESS Currently being in transfer DRV_SST25VF020B_COMMAND_ERROR_UNKNOWN Unknown Command Description SST Flash Driver Command Status SST Flash Driver command Status This type specifies the status of the command for the read, write and erase operations. Remarks None. DRV_SST25VF020B_BLOCK_COMMAND_HANDLE_INVALID Macro This value defines the SPI Flash Driver Block Command Invalid handle. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 821 File drv_sst25vf020b.h C #define DRV_SST25VF020B_BLOCK_COMMAND_HANDLE_INVALID Description SPI Flash Driver Block Event Invalid Handle This value defines the SPI Flash Driver Block Command Invalid handle. It is returned by read/write/erase routines when the request could not be taken. Remarks None. DRV_SST25VF020B_INDEX_0 Macro SPI Flash driver index definitions. File drv_sst25vf020b.h C #define DRV_SST25VF020B_INDEX_0 0 Description Driver SPI Flash Module Index reference These constants provide SST25VF020B SPI Flash driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_SST25VF020B_Initialize and DRV_SST25VF020B_Open routines to identify the driver instance in use. DRV_SST25VF020B_INDEX_1 Macro File drv_sst25vf020b.h C #define DRV_SST25VF020B_INDEX_1 1 Description This is macro DRV_SST25VF020B_INDEX_1. SST25VF064C API a) System Functions Name Description DRV_SST25VF064C_Initialize Initializes the SST25VF064C SPI Flash Driver instance for the specified driver index. DRV_SST25VF064C_Deinitialize Deinitializes the specified instance of the SPI Flash driver module. DRV_SST25VF064C_Status Gets the current status of the SPI Flash Driver module. DRV_SST25VF064C_Tasks Maintains the driver's read, erase, and write state machine and implements its ISR. b) Core Client Functions Name Description DRV_SST25VF064C_ClientStatus Gets current client-specific status of the SPI Flash driver. DRV_SST25VF064C_Close Closes an opened-instance of the SPI Flash driver. DRV_SST25VF064C_CommandStatus Gets the current status of the command. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 822 DRV_SST25VF064C_Open Opens the specified SPI Flash driver instance and returns a handle to it. c) Block Operation Functions Name Description DRV_SST25VF064C_BlockErase Erase the specified number of blocks in Flash memory. DRV_SST25VF064C_BlockEventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. DRV_SST25VF064C_BlockRead Reads blocks of data starting from the specified address in Flash memory. DRV_SST25VF064C_BlockWrite Write blocks of data starting from a specified address in Flash memory. d) Media Interface Functions Name Description DRV_SST25VF064C_GeometryGet Returns the geometry of the device. DRV_SST25VF064C_MediaIsAttached Returns the status of the media. e) Data Types and Constants Name Description DRV_SST25VF064C_BLOCK_COMMAND_HANDLE Handle identifying block commands of the driver. DRV_SST25VF064C_BLOCK_EVENT Identifies the possible events that can result from a request. DRV_SST25VF064C_CLIENT_STATUS Defines the client status. DRV_SST25VF064C_COMMAND_STATUS Specifies the status of the command for the read, write and erase operations. DRV_SST25VF064C_EVENT_HANDLER Pointer to a SST25VF064C SPI Flash Driver Event handler function. DRV_SST25VF064C_INIT Contains all the data necessary to initialize the SPI Flash device. DRV_SST25VF064C_BLOCK_COMMAND_HANDLE_INVALID This value defines the SPI Flash Driver Block Command Invalid handle. DRV_SST25VF064C_INDEX_0 SPI Flash driver index definitions. DRV_SST25VF064C_INDEX_1 This is macro DRV_SST25VF064C_INDEX_1. Description a) System Functions DRV_SST25VF064C_Initialize Function Initializes the SST25VF064C SPI Flash Driver instance for the specified driver index. File drv_sst25vf064c.h C SYS_MODULE_OBJ DRV_SST25VF064C_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Description This function initializes the SPI Flash driver instance for the specified driver index, making it ready for clients to open and use it. Remarks This function must be called before any other SPI Flash function is called. This function should only be called once during system initialization unless DRV_SST25VF064C_Deinitialize is called to deinitialize the driver instance. Build configuration options may be used to statically override options in the "init" structure and will take precedence over initialization data passed using this function. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 823 Preconditions None. Example // This code snippet shows an example of initializing the SST25VF064C SPI // Flash Driver. SPI driver index 0 is used for the purpose. Pin numbers 1, 2 // and 3 of port channel B are configured for hold pin, write protection pin // and chip select pin respectively. Maximum buffer queue size is set 5. DRV_SST25VF064C_INIT SST25VF064CInitData; SYS_MODULE_OBJ objectHandle; SST25VF064CInitData.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; SST25VF064CInitData.spiDriverModuleIndex = DRV_SPI_INDEX_0; SST25VF064CInitData.holdPortChannel = PORT_CHANNEL_B; SST25VF064CInitData.holdBitPosition = PORTS_BIT_POS_1; SST25VF064CInitData.writeProtectPortChannel = PORT_CHANNEL_B; SST25VF064CInitData.writeProtectBitPosition = PORTS_BIT_POS_2; SST25VF064CInitData.chipSelectPortChannel = PORT_CHANNEL_F; SST25VF064CInitData.chipSelectBitPosition = PORTS_BIT_POS_2; SST25VF064CInitData.queueSize = 5; objectHandle = DRV_SST25VF064C_Initialize(DRV_SST25VF064C_INDEX_0, (SYS_MODULE_INIT*)SST25VF064CInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized init Pointer to a data structure containing data necessary to initialize the driver. Function SYS_MODULE_OBJ DRV_SST25VF064C_Initialize ( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); DRV_SST25VF064C_Deinitialize Function Deinitializes the specified instance of the SPI Flash driver module. File drv_sst25vf064c.h C void DRV_SST25VF064C_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the SPI Flash Driver module, disabling its operation (and any hardware) and invalidates all of the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 824 Preconditions Function DRV_SST25VF064C_Initialize should have been called before calling this function. Example // This code snippet shows an example of deinitializing the driver. SYS_MODULE_OBJ object; // Returned from DRV_SST25VF064C_Initialize SYS_STATUS status; DRV_SST25VF064C_Deinitialize(object); status = DRV_SST25VF064C_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from the DRV_SST25VF064C_Initialize Function void DRV_SST25VF064C_Deinitialize( SYS_MODULE_OBJ object ) DRV_SST25VF064C_Status Function Gets the current status of the SPI Flash Driver module. File drv_sst25vf064c.h C SYS_STATUS DRV_SST25VF064C_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is ready and accept requests for new operations SYS_STATUS_UNINITIALIZED - Indicates that the driver is not initialized Description This function provides the current status of the SPI Flash Driver module. Remarks A driver can only be opened when its status is SYS_STATUS_READY. Preconditions Function DRV_SST25VF064C_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_SST25VF064C_Initialize SYS_STATUS SST25VF064CStatus; SST25VF064CStatus = DRV_SST25VF064C_Status(object); else if (SYS_STATUS_ERROR >= SST25VF064CStatus) { // Handle error } Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 825 Parameters Parameters Description object Driver object handle, returned from the DRV_SST25VF064C_Initialize Function SYS_STATUS DRV_SST25VF064C_Status( SYS_MODULE_OBJ object ) DRV_SST25VF064C_Tasks Function Maintains the driver's read, erase, and write state machine and implements its ISR. File drv_sst25vf064c.h C void DRV_SST25VF064C_Tasks(SYS_MODULE_OBJ object); Returns None. Description This function is used to maintain the driver's internal state machine and should be called from the system's Tasks function. Remarks This function is normally not called directly by an application. It is called by the system's Tasks function (SYS_Tasks). Preconditions The DRV_SST25VF064C_Initialize function must have been called for the specified SPI Flash driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_SST25VF064C_Initialize while (true) { DRV_SST25VF064C_Tasks (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_SST25VF064C_Initialize) Function void DRV_SST25VF064C_Tasks ( SYS_MODULE_OBJ object ); b) Core Client Functions DRV_SST25VF064C_ClientStatus Function Gets current client-specific status of the SPI Flash driver. File drv_sst25vf064c.h C DRV_SST25VF064C_CLIENT_STATUS DRV_SST25VF064C_ClientStatus(const DRV_HANDLE handle); Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 826 Returns A DRV_SST25VF064C_CLIENT_STATUS value describing the current status of the driver. Description This function gets the client-specific status of the SPI Flash driver associated with the given handle. Remarks This function will not block for hardware access and will immediately return the current status. Preconditions The DRV_SST25VF064C_Initialize function must have been called. DRV_SST25VF064C_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SST25VF064C_Open DRV_SST25VF064C_CLIENT_STATUS clientStatus; clientStatus = DRV_SST25VF064C_ClientStatus(handle); if(DRV_SST25VF064C_CLIENT_STATUS_READY == clientStatus) { // do the tasks } Parameters Parameters Description handle A valid open instance handle, returned from the driver's open Function DRV_SST25VF064C_CLIENT_STATUS DRV_SST25VF064C_ClientStatus(DRV_HANDLE handle); DRV_SST25VF064C_Close Function Closes an opened-instance of the SPI Flash driver. File drv_sst25vf064c.h C void DRV_SST25VF064C_Close(const DRV_HANDLE handle); Returns None. Description This function closes an opened-instance of the SPI Flash driver, invalidating the handle. Remarks After calling this function, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_SST25VF064C_Open before the caller may use the driver again. Usually, there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_SST25VF064C_Initialize function must have been called for the specified SPI Flash driver instance. DRV_SST25VF064C_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SST25VF064C_Open DRV_SST25VF064C_Close(handle); Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 827 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function void DRV_SST25VF064C_Close( DRV_Handle handle ); DRV_SST25VF064C_CommandStatus Function Gets the current status of the command. File drv_sst25vf064c.h C DRV_SST25VF064C_COMMAND_STATUS DRV_SST25VF064C_CommandStatus(const DRV_HANDLE handle, const DRV_SST25VF064C_BLOCK_COMMAND_HANDLE commandHandle); Returns A DRV_SST25VF064C_COMMAND_STATUS value describing the current status of the buffer. Returns DRV_SST25VF064C_BLOCK_COMMAND_HANDLE_INVALID if the client handle or the command handle is not valid. Description This routine gets the current status of the buffer. The application must use this routine where the status of a scheduled buffer needs to polled on. The function may return DRV_SST25VF064C_BLOCK_COMMAND_HANDLE_INVALID in a case where the buffer handle has expired. A buffer handle expires when the internal buffer object is re-assigned to another erase, read or write request. It is recommended that this function be called regularly in order to track the buffer status correctly. The application can alternatively register an event handler to receive write, read or erase operation completion events. Remarks This function will not block for hardware access and will immediately return the current status. Preconditions Block command request must have been made using Erase, Read or Write APIs to get a valid command handle. Example DRV_HANDLE sstOpenHandle; // Returned from DRV_SST25VF064C_Open DRV_SST25VF064C_BLOCK_COMMAND_HANDLE commandHandle; DRV_SST25VF064C_BlockErase ( sstOpenHandle, &commandHandle, 0, 1 ); if(DRV_SST25VF064C_CommandStatus(sstOpenHandle, commandHandle) == DRV_SST25VF064C_COMMAND_COMPLETED ); { // do something } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine commandHandle A valid command handle, returned from Read/Write/Erase APIs. Function DRV_SST25VF064C_COMMAND_STATUS DRV_SST25VF064C_CommandStatus ( const DRV_HANDLE handle, const DRV_SST25VF064C_BLOCK_COMMAND_HANDLE commandHandle Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 828 ); DRV_SST25VF064C_Open Function Opens the specified SPI Flash driver instance and returns a handle to it. File drv_sst25vf064c.h C DRV_HANDLE DRV_SST25VF064C_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent); Returns If successful, the function returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Errors can occur under the following circumstances: • if the number of client objects allocated via DRV_SST25VF064C_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the driver hardware instance being opened is not initialized or is invalid • if the client is trying to open the driver exclusively, but has already been opened in a non exclusive mode by another client. Description This function opens the specified SPI Flash driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Remarks The driver will always work in Non-Blocking mode even if IO-intent is selected as blocking. The handle returned is valid until the DRV_SST25VF064C_Close function is called. This function will NEVER block waiting for hardware. Preconditions Function DRV_SST25VF064C_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_SST25VF064C_Open(DRV_SST25VF064C_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } Parameters Parameters Description drvIndex Identifier for the object instance to be opened ioIntent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver Function DRV_HANDLE DRV_SST25VF064C_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent ); c) Block Operation Functions DRV_SST25VF064C_BlockErase Function Erase the specified number of blocks in Flash memory. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 829 File drv_sst25vf064c.h C void DRV_SST25VF064C_BlockErase(const DRV_HANDLE handle, DRV_SST25VF064C_BLOCK_COMMAND_HANDLE * commandHandle, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It Will be DRV_BUFFER_HANDLE_INVALID if the request was not queued. Description This function schedules a non-blocking erase operation in Flash memory. The function returns with a valid erase handle in the commandHandle argument if the erase request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. The function returns DRV_SST25VF064C_BLOCK_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if the client opened the driver for read only • if nBlock is 0 • if the queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_SST25VF064C_EVENT_ERASE_COMPLETE event if the erase operation was successful or DRV_SST25VF064C_EVENT_ERASE_ERROR event if the erase operation was not successful. Remarks Write Protection will be disabled for the complete Flash memory region in the beginning by default. Preconditions The DRV_SST25VF064C_Initialize function must have been called for the specified SPI Flash driver instance. DRV_SST25VF064C_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SST25VF064C_Open call. Example // Destination address should be block aligned. uint32_t blockStart; uint32_t nBlock; DRV_SST25VF064C_BLOCK_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySST25VF064CHandle is the handle returned // by the DRV_SST25VF064C_Open function. // Client registers an event handler with driver DRV_SST25VF064C_BlockEventHandlerSet(mySST25VF064CHandle, APP_SST25VF064CEventHandler, (uintptr_t)&myAppObj); DRV_SST25VF064C_BlockErase( mySST25VF064CHandle, commandHandle, blockStart, nBlock ); if(DRV_SST25VF064C_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when // the buffer queue is processed. void APP_SST25VF064CEventHandler(DRV_SST25VF064C_BLOCK_EVENT event, DRV_SST25VF064C_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_SST25VF064C_EVENT_ERASE_COMPLETE: Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 830 // This means the data was transferred. break; case DRV_SST25VF064C_EVENT_ERASE_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle blockStart Start block address in SST25VF064C memory from where the erase should begin. LSBs (A0-A11) of block start address will be ignored to align it with Erase block size boundary. nBlock Total number of blocks to be erased. Each Erase block is of size 4 KByte. Function void DRV_SST25VF064C_BlockErase ( const DRV_HANDLE handle, DRV_SST25VF064C_BLOCK_COMMAND_HANDLE * commandHandle, uint32_t blockStart, uint32_t nBlock ); DRV_SST25VF064C_BlockEventHandlerSet Function Allows a client to identify an event handling function for the driver to call back when queued operation has completed. File drv_sst25vf064c.h C void DRV_SST25VF064C_BlockEventHandlerSet(const DRV_HANDLE handle, const DRV_SST25VF064C_EVENT_HANDLER eventHandler, const uintptr_t context); Returns None. Description This function allows a client to identify an event handling function for the driver to call back when queued operation has completed. When a client calls any read, write or erase function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the queued operation has completed. The event handler should be set before the client performs any read/write/erase operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued operation has completed, it does not need to register a callback. Preconditions The DRV_SST25VF064C_Initialize function must have been called for the specified SPI FLash driver instance. DRV_SST25VF064C_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific state data object. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 831 MY_APP_OBJ myAppObj; uint8_t myBuffer[MY_BUFFER_SIZE]; uint32_t blockStart, nBlock; DRV_SST25VF064C_BLOCK_COMMAND_HANDLE commandHandle; // mySST25VF064CHandle is the handle returned // by the DRV_SST25VF064C_Open function. // Client registers an event handler with driver. This is done once. DRV_SST25VF064C_BlockEventHandlerSet( mySST25VF064CHandle, APP_SST25VF064CEventHandler, (uintptr_t)&myAppObj ); DRV_SST25VF064C_BlockRead( mySST25VF064CHandle, commandHandle, &myBuffer, blockStart, nBlock ); if(DRV_SST25VF064C_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event Processing Technique. Event is received when operation is done. void APP_SST25VF064CEventHandler(DRV_SST25VF064C_BLOCK_EVENT event, DRV_SST25VF064C_BLOCK_COMMAND_HANDLE handle, uintptr_t context) { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) context; switch(event) { case DRV_SST25VF064C_EVENT_BLOCK_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_SST25VF064C_EVENT_BLOCK_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function eventHandler Pointer to the event handler function implemented by the user context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_SST25VF064C_BlockEventHandlerSet ( const DRV_HANDLE handle, const DRV_SST25VF064C_EVENT_HANDLER eventHandler, const uintptr_t context ); Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 832 DRV_SST25VF064C_BlockRead Function Reads blocks of data starting from the specified address in Flash memory. File drv_sst25vf064c.h C void DRV_SST25VF064C_BlockRead(const DRV_HANDLE handle, DRV_SST25VF064C_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t * targetBuffer, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It will be DRV_BUFFER_HANDLE_INVALID if the request was not successful. Description This function schedules a non-blocking read operation for reading blocks of data from Flash memory. The function returns with a valid handle in the commandHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_SST25VF064C_BLOCK_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer could not be allocated to the request • if the target buffer pointer is NULL • if the client opened the driver for write only • if the buffer size is 0 • if the read queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_SST25VF064C_EVENT_BLOCK_COMMAND_COMPLETE event if the buffer was processed successfully of DRV_SST25VF064C_EVENT_BLOCK_COMMAND_ERROR event if the buffer was not processed successfully. Remarks The maximum read speed is 33 MHz. Preconditions The DRV_SST25VF064C_Initialize function must have been called for the specified SPI Flash driver instance. DRV_SST25VF064C_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SST25VF064C_Open call. Example uint8_t myBuffer[MY_BUFFER_SIZE]; // address should be block aligned. uint32_t blockStart = SST25VF064C_BASE_ADDRESS_TO_READ_FROM; uint32_t nBlock = 2; DRV_SST25VF064C_BLOCK_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySST25VF064CHandle is the handle returned // by the DRV_SST25VF064C_Open function. // Client registers an event handler with driver DRV_SST25VF064C_BlockEventHandlerSet(mySST25VF064CHandle, APP_SST25VF064CEventHandler, (uintptr_t)&myAppObj); DRV_SST25VF064C_BlockRead( mySST25VF064CHandle, commandHandle, &myBuffer, blockStart, nBlock ); if(DRV_SST25VF064C_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when the buffer is processed. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 833 void APP_SST25VF064CEventHandler(DRV_SST25VF064C_BLOCK_EVENT event, DRV_SST25VF064C_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_SST25VF064C_EVENT_BLOCK_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_SST25VF064C_EVENT_BLOCK_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle *targetBuffer Buffer into which the data read from the SPI Flash instance will be placed blockStart Start block address in SST25VF064C memory from where the read should begin. It can be any address of the Flash. nBlock Total number of blocks to be read. Each Read block is of 1 byte. Function void DRV_SST25VF064C_BlockRead ( const DRV_HANDLE handle, DRV_SST25VF064C_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t *targetBuffer, uint32_t blockStart, uint32_t nBlock ); DRV_SST25VF064C_BlockWrite Function Write blocks of data starting from a specified address in Flash memory. File drv_sst25vf064c.h C void DRV_SST25VF064C_BlockWrite(DRV_HANDLE handle, DRV_SST25VF064C_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t * sourceBuffer, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It will be DRV_BUFFER_HANDLE_INVALID if the request was not successful. Description This function schedules a non-blocking write operation for writing blocks of data into Flash memory. The function returns with a valid buffer handle in the commandHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_SST25VF064C_BLOCK_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer could not be allocated to the request Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 834 • if the input buffer pointer is NULL • if the client opened the driver for read only • if the buffer size is 0 • if the write queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_SST25VF064C_EVENT_BLOCK_COMMAND_COMPLETE event if the buffer was processed successfully or DRV_SST25VF064C_EVENT_BLOCK_COMMAND_ERROR event if the buffer was not processed successfully. Remarks In the case of multi bytes write operation, byte by byte writing will happen instead of Address auto Increment writing. Write Protection will be disabled for the complete Flash memory region in the beginning by default. Preconditions The DRV_SST25VF064C_Initialize function must have been called for the specified SPI Flash driver instance. DRV_SST25VF064C_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_SST25VF064C_Open call. The Flash address location which has to be written, must be erased before using the API DRV_SST25VF064C_BlockErase(). Example uint8_t myBuffer[MY_BUFFER_SIZE]; // address should be block aligned. uint32_t blockStart = SST25VF064C_BASE_ADDRESS_TO_WRITE_TO; uint32_t nBlock = 2; DRV_SST25VF064C_BLOCK_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySST25VF064CHandle is the handle returned // by the DRV_SST25VF064C_Open function. // Client registers an event handler with driver DRV_SST25VF064C_BlockEventHandlerSet(mySST25VF064CHandle, APP_SST25VF064CEventHandler, (uintptr_t)&myAppObj); DRV_SST25VF064C_BlockWrite( mySST25VF064CHandle, commandHandle, &myBuffer, blockStart, nBlock ); if(DRV_SST25VF064C_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_SST25VF064CEventHandler(DRV_SST25VF064C_BLOCK_EVENT event, DRV_SST25VF064C_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_SST25VF064C_EVENT_BLOCK_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_SST25VF064C_EVENT_BLOCK_COMMAND_ERROR: // Error handling here. break; default: Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 835 break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle -Pointer to an argument that will contain the return buffer handle sourceBuffer The source buffer containing data to be programmed into SPI Flash blockStart Start block address of SST25VF064C Flash where the write should begin. It can be any address of the Flash. nBlock Total number of blocks to be written. Each write block is of 1 byte. Function void DRV_SST25VF064C_BlockWrite ( DRV_HANDLE handle, DRV_SST25VF064C_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t *sourceBuffer, uint32_t blockStart, uint32_t nBlock ); d) Media Interface Functions DRV_SST25VF064C_GeometryGet Function Returns the geometry of the device. File drv_sst25vf064c.h C SYS_FS_MEDIA_GEOMETRY * DRV_SST25VF064C_GeometryGet(DRV_HANDLE handle); Returns SYS_FS_MEDIA_GEOMETRY - Structure which holds the media geometry information. Description This API gives the following geometrical details of the SST25VF064C Flash: • Media Property • Number of Read/Write/Erase regions in the Flash device • Number of Blocks and their size in each region of the device Remarks This function is typically used by File System Media Manager. Preconditions None. Example SYS_FS_MEDIA_GEOMETRY * sstFlashGeometry; uint32_t readBlockSize, writeBlockSize, eraseBlockSize; uint32_t nReadBlocks, nReadRegions, totalFlashSize; sstFlashGeometry = DRV_SST25VF064C_GeometryGet(sstOpenHandle1); // read block size should be 1 byte readBlockSize = sstFlashGeometry->geometryTable->blockSize; nReadBlocks = sstFlashGeometry->geometryTable->numBlocks; Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 836 nReadRegions = sstFlashGeometry->numReadRegions; // write block size should be 1 byte writeBlockSize = (sstFlashGeometry->geometryTable +1)->blockSize; // erase block size should be 4k byte eraseBlockSize = (sstFlashGeometry->geometryTable +2)->blockSize; // total Flash size should be 8 MB totalFlashSize = readBlockSize * nReadBlocks * nReadRegions; Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function SYS_FS_MEDIA_GEOMETRY DRV_SST25VF064C_GeometryGet( DRV_HANDLE handle ); DRV_SST25VF064C_MediaIsAttached Function Returns the status of the media. File drv_sst25vf064c.h C bool DRV_SST25VF064C_MediaIsAttached(DRV_HANDLE handle); Returns • True - Media is attached • False - Media is not attached Description This function determines whether or not the media is attached. Remarks This function is typically used by File System Media Manager. Preconditions None. Example if (DRV_SST25VF064C_MediaIsAttached(handle)) { // Do Something } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function bool DRV_SST25VF064C_MediaIsAttached( DRV_HANDLE handle); e) Data Types and Constants DRV_SST25VF064C_BLOCK_COMMAND_HANDLE Type Handle identifying block commands of the driver. File drv_sst25vf064c.h Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 837 C typedef SYS_FS_MEDIA_BLOCK_COMMAND_HANDLE DRV_SST25VF064C_BLOCK_COMMAND_HANDLE; Description SPI Flash Driver Block Command Handle A block command handle is returned by a call to the Read, Write, or Erase functions. This handle allows the application to track the completion of the operation. The handle is returned back to the client by the "event handler callback" function registered with the driver. The handle assigned to a client request expires when the client has been notified of the completion of the operation (after event handler function that notifies the client returns) or after the buffer has been retired by the driver if no event handler callback was set. Remarks None. DRV_SST25VF064C_BLOCK_EVENT Enumeration Identifies the possible events that can result from a request. File drv_sst25vf064c.h C typedef enum { DRV_SST25VF064C_EVENT_BLOCK_COMMAND_COMPLETE, DRV_SST25VF064C_EVENT_BLOCK_COMMAND_ERROR } DRV_SST25VF064C_BLOCK_EVENT; Members Members Description DRV_SST25VF064C_EVENT_BLOCK_COMMAND_COMPLETE Block operation has been completed successfully. Read/Write/Erase Complete DRV_SST25VF064C_EVENT_BLOCK_COMMAND_ERROR There was an error during the block operation Read/Write/Erase Error Description SST25VF064C SPI Flash Driver Events This enumeration identifies the possible events that can result from a Read, Write, or Erase request caused by the client. Remarks One of these values is passed in the "event" parameter of the event handling callback function that client registered with the driver by calling the DRV_SST25VF064C_BlockEventHandlerSet function when a block request is completed. DRV_SST25VF064C_CLIENT_STATUS Enumeration Defines the client status. File drv_sst25vf064c.h C typedef enum { DRV_SST25VF064C_CLIENT_STATUS_READY = DRV_CLIENT_STATUS_READY+0, DRV_SST25VF064C_CLIENT_STATUS_BUSY = DRV_CLIENT_STATUS_BUSY, DRV_SST25VF064C_CLIENT_STATUS_CLOSED = DRV_CLIENT_STATUS_CLOSED, DRV_SST25VF064C_CLIENT_STATUS_ERROR = DRV_CLIENT_STATUS_ERROR } DRV_SST25VF064C_CLIENT_STATUS; Members Members Description DRV_SST25VF064C_CLIENT_STATUS_READY = DRV_CLIENT_STATUS_READY+0 Up and running, ready to start new operations DRV_SST25VF064C_CLIENT_STATUS_BUSY = DRV_CLIENT_STATUS_BUSY Operation in progress, unable to start a new one DRV_SST25VF064C_CLIENT_STATUS_CLOSED = DRV_CLIENT_STATUS_CLOSED Client is closed Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 838 DRV_SST25VF064C_CLIENT_STATUS_ERROR = DRV_CLIENT_STATUS_ERROR Client Error Description SPI Flash Client Status Defines the various client status codes. Remarks None. DRV_SST25VF064C_COMMAND_STATUS Enumeration Specifies the status of the command for the read, write and erase operations. File drv_sst25vf064c.h C typedef enum { DRV_SST25VF064C_COMMAND_COMPLETED, DRV_SST25VF064C_COMMAND_QUEUED, DRV_SST25VF064C_COMMAND_IN_PROGRESS, DRV_SST25VF064C_COMMAND_ERROR_UNKNOWN } DRV_SST25VF064C_COMMAND_STATUS; Members Members Description DRV_SST25VF064C_COMMAND_COMPLETED Requested operation is completed DRV_SST25VF064C_COMMAND_QUEUED Scheduled but not started DRV_SST25VF064C_COMMAND_IN_PROGRESS Currently being in transfer DRV_SST25VF064C_COMMAND_ERROR_UNKNOWN Unknown Command Description SST Flash Driver Command Status SST Flash Driver command Status. This type specifies the status of the command for the read, write and erase operations. Remarks None. DRV_SST25VF064C_EVENT_HANDLER Type Pointer to a SST25VF064C SPI Flash Driver Event handler function. File drv_sst25vf064c.h C typedef void (* DRV_SST25VF064C_EVENT_HANDLER)(DRV_SST25VF064C_BLOCK_EVENT event, DRV_SST25VF064C_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t context); Returns None. Description SST25VF064C SPI Flash Driver Event Handler Function Pointer This data type defines the required function signature for the SST25VF064C SPI Flash driver event handling callback function. A client must register a pointer to an event handling function whose function signature (parameter and return value types) match the types specified by this function pointer in order to receive event calls back from the driver. The parameters and return values and return value are described here and a partial example implementation is provided. Remarks If the event is DRV_SST25VF064C_EVENT_BLOCK_COMMAND_COMPLETE, it means that the data was transferred successfully. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 839 If the event is DRV_SST25VF064C_EVENT_BLOCK_COMMAND_ERROR, it means that the data was not transferred successfully. The context parameter contains the a handle to the client context, provided at the time the event handling function was registered using the DRV_SST25VF064C_BlockEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the read/write/erase request. The event handler function executes in the driver peripheral's interrupt context when the driver is configured for interrupt mode operation. It is recommended of the application to not perform process intensive or blocking operations with in this function. The Read, Write, and Erase functions can be called in the event handler to add a buffer to the driver queue. These functions can only be called to add buffers to the driver whose event handler is running. Example void APP_MyBufferEventHandler ( DRV_SST25VF064C_BLOCK_EVENT event, DRV_SST25VF064C_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_SST25VF064C_EVENT_BLOCK_COMMAND_COMPLETE: // Handle the completed buffer. break; case DRV_SST25VF064C_EVENT_BLOCK_COMMAND_ERROR: default: // Handle error. break; } } Parameters Parameters Description event Identifies the type of event commandHandle Handle returned from the Read/Write/Erase requests context Value identifying the context of the application that registered the event handling function DRV_SST25VF064C_INIT Structure Contains all the data necessary to initialize the SPI Flash device. File drv_sst25vf064c.h C typedef struct { SYS_MODULE_INIT moduleInit; SYS_MODULE_INDEX spiDriverModuleIndex; PORTS_CHANNEL holdPortChannel; PORTS_BIT_POS holdBitPosition; PORTS_CHANNEL writeProtectPortChannel; PORTS_BIT_POS writeProtectBitPosition; PORTS_CHANNEL chipSelectPortChannel; PORTS_BIT_POS chipSelectBitPosition; uint32_t queueSize; } DRV_SST25VF064C_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization SYS_MODULE_INDEX spiDriverModuleIndex; Identifies the SPI driver to be used Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 840 PORTS_CHANNEL holdPortChannel; HOLD pin port channel PORTS_BIT_POS holdBitPosition; HOLD pin port position PORTS_CHANNEL writeProtectPortChannel; Write protect pin port channel PORTS_BIT_POS writeProtectBitPosition; Write Protect Bit pin position PORTS_CHANNEL chipSelectPortChannel; Chip select pin port channel PORTS_BIT_POS chipSelectBitPosition; Chip Select Bit pin position uint32_t queueSize; This is the buffer queue size. This is the maximum number of requests that this instance of the driver will queue. For a static build of the driver, this is overridden by the DRV_SST25VF064C_QUEUE_SIZE macro in system_config.h Description SST SPI Flash Driver Initialization Data This structure contains all of the data necessary to initialize the SPI Flash device. Remarks A pointer to a structure of this format containing the desired initialization data must be passed into the DRV_SST25VF064C_Initialize function. DRV_SST25VF064C_BLOCK_COMMAND_HANDLE_INVALID Macro This value defines the SPI Flash Driver Block Command Invalid handle. File drv_sst25vf064c.h C #define DRV_SST25VF064C_BLOCK_COMMAND_HANDLE_INVALID Description SPI Flash Driver Block Event Invalid Handle This value defines the SPI Flash Driver Block Command Invalid handle. It is returned by read/write/erase routines when the request could not be taken. Remarks None. DRV_SST25VF064C_INDEX_0 Macro SPI Flash driver index definitions. File drv_sst25vf064c.h C #define DRV_SST25VF064C_INDEX_0 0 Description Driver SPI Flash Module Index reference These constants provide SST25VF064C SPI Flash driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_SST25VF064C_Initialize and DRV_SST25VF064C_Open routines to identify the driver instance in use. DRV_SST25VF064C_INDEX_1 Macro File drv_sst25vf064c.h Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 841 C #define DRV_SST25VF064C_INDEX_1 1 Description This is macro DRV_SST25VF064C_INDEX_1. Files Files Name Description drv_sst25vf016b.h SPI Flash Driver Interface Definition drv_sst25vf016b_config_template.h SST25VF016B Driver Configuration Template. drv_sst25vf020b.h SPI Flash Driver Interface Definition drv_sst25vf020b_config_template.h SST25VF020B Driver Configuration Template. drv_sst25vf064c.h SPI Flash Driver Interface Definition drv_sst25vf064c_config_template.h SST25VF064C Driver Configuration Template. Description This section lists the source and header files used by the SPI Flash Driver Library. drv_sst25vf016b.h SPI Flash Driver Interface Definition Enumerations Name Description DRV_SST25VF016B_BLOCK_EVENT Identifies the possible events that can result from a request. DRV_SST25VF016B_CLIENT_STATUS Defines the client status. Implementation: Dynamic Functions Name Description DRV_SST25VF016B_BlockErase Erase the specified number of blocks in Flash memory. Implementation: Dynamic DRV_SST25VF016B_BlockEventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. Implementation: Dynamic DRV_SST25VF016B_BlockRead Reads blocks of data starting from the specified address in Flash memory. Implementation: Dynamic DRV_SST25VF016B_BlockWrite Write blocks of data starting from a specified address in Flash memory. Implementation: Dynamic DRV_SST25VF016B_ClientStatus Gets current client-specific status of the SPI Flash driver. Implementation: Dynamic DRV_SST25VF016B_Close Closes an opened-instance of the SPI Flash driver. Implementation: Dynamic DRV_SST25VF016B_Deinitialize Deinitializes the specified instance of the SPI Flash driver module. Implementation: Dynamic DRV_SST25VF016B_GeometryGet Returns the geometry of the device. Implementation: Dynamic DRV_SST25VF016B_Initialize Initializes the SST25VF016B SPI Flash Driver instance for the specified driver index. Implementation: Dynamic DRV_SST25VF016B_MediaIsAttached Returns the status of the media. Implementation: Dynamic DRV_SST25VF016B_Open Opens the specified SPI Flash driver instance and returns a handle to it. Implementation: Dynamic DRV_SST25VF016B_Status Gets the current status of the SPI Flash Driver module. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 842 DRV_SST25VF016B_Tasks Maintains the driver's read, erase, and write state machine and implements its ISR. Implementation: Dynamic Macros Name Description DRV_SST25VF016B_BLOCK_COMMAND_HANDLE_INVALID This value defines the SPI Flash Driver Block Command Invalid handle. DRV_SST25VF016B_INDEX_0 SPI Flash driver index definitions DRV_SST25VF016B_INDEX_1 This is macro DRV_SST25VF016B_INDEX_1. Structures Name Description DRV_SST25VF016B_INIT Contains all the data necessary to initialize the SPI Flash device. Implementation: Dynamic Types Name Description DRV_SST25VF016B_BLOCK_COMMAND_HANDLE Handle identifying block commands of the driver. DRV_SST25VF016B_EVENT_HANDLER Pointer to a SST25VF016B SPI Flash Driver Event handler function. Implementation: Dynamic Description SPI Flash Driver Interface Definition The SPI Flash device driver provides a simple interface to manage the SPI Flash modules which are external to Microchip Controllers. This file defines the interface definition for the SPI Flash Driver. File Name drv_sst25vf016b.h Company Microchip Technology Inc. drv_sst25vf016b_config_template.h SST25VF016B Driver Configuration Template. Macros Name Description DRV_SST25VF016B_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_SST25VF016B_HARDWARE_HOLD_ENABLE Specifies if the hardware hold feature is enabled or not. DRV_SST25VF016B_HARDWARE_WRITE_PROTECTION_ENABLE Specifies if the hardware write protect feature is enabled or not. DRV_SST25VF016B_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_SST25VF016B_MODE Determines whether the driver is implemented as static or dynamic DRV_SST25VF016B_QUEUE_DEPTH_COMBINED Number of entries of queues in all instances of the driver. Description SST25VF016B Driver Configuration Template These file provides the list of all the configurations that can be used with the driver. This file should not be included in the driver. File Name drv_sst25vf016b_config_template.h Company Microchip Technology Inc. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 843 drv_sst25vf020b.h SPI Flash Driver Interface Definition Enumerations Name Description DRV_SST25VF020B_BLOCK_EVENT Identifies the possible events that can result from a request. DRV_SST25VF020B_CLIENT_STATUS Defines the client status. DRV_SST25VF020B_COMMAND_STATUS Specifies the status of the command for the read, write and erase operations. Functions Name Description DRV_SST25VF020B_BlockErase Erase the specified number of blocks in Flash memory. Implementation: Dynamic DRV_SST25VF020B_BlockEraseWrite Erase and Write blocks of data starting from a specified address in SST flash memory. DRV_SST25VF020B_BlockEventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. Implementation: Dynamic DRV_SST25VF020B_BlockRead Reads blocks of data starting from the specified address in Flash memory. Implementation: Dynamic DRV_SST25VF020B_BlockWrite Write blocks of data starting from a specified address in Flash memory. Implementation: Dynamic DRV_SST25VF020B_ClientStatus Gets current client-specific status of the SPI Flash driver. Implementation: Dynamic DRV_SST25VF020B_Close Closes an opened-instance of the SPI Flash driver. Implementation: Dynamic DRV_SST25VF020B_CommandStatus Gets the current status of the command. DRV_SST25VF020B_Deinitialize Deinitializes the specified instance of the SPI Flash driver module. Implementation: Dynamic DRV_SST25VF020B_GeometryGet Returns the geometry of the device. Implementation: Dynamic DRV_SST25VF020B_Initialize Initializes the SST25VF020B SPI Flash Driver instance for the specified driver index. Implementation: Dynamic DRV_SST25VF020B_MediaIsAttached Returns the status of the media. Implementation: Dynamic DRV_SST25VF020B_Open Opens the specified SPI Flash driver instance and returns a handle to it. Implementation: Dynamic DRV_SST25VF020B_Status Gets the current status of the SPI Flash Driver module. Implementation: Dynamic DRV_SST25VF020B_Tasks Maintains the driver's read, erase, and write state machine and implements its ISR. Implementation: Dynamic Macros Name Description DRV_SST25VF020B_BLOCK_COMMAND_HANDLE_INVALID This value defines the SPI Flash Driver Block Command Invalid handle. DRV_SST25VF020B_INDEX_0 SPI Flash driver index definitions. DRV_SST25VF020B_INDEX_1 This is macro DRV_SST25VF020B_INDEX_1. Structures Name Description DRV_SST25VF020B_INIT Contains all the data necessary to initialize the SPI Flash device. Types Name Description DRV_SST25VF020B_BLOCK_COMMAND_HANDLE Handle identifying block commands of the driver. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 844 DRV_SST25VF020B_EVENT_HANDLER Pointer to a SST25VF020B SPI Flash Driver Event handler function. Description SPI Flash Driver Interface Definition The SPI Flash device driver provides a simple interface to manage the SPI Flash modules which are external to Microchip Controllers. This file defines the interface definition for the SPI Flash Driver. File Name drv_sst25vf020b.h Company Microchip Technology Inc. drv_sst25vf020b_config_template.h SST25VF020B Driver Configuration Template. Macros Name Description DRV_SST25VF020B_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_SST25VF020B_HARDWARE_HOLD_ENABLE Specifies if the hardware hold feature is enabled or not. DRV_SST25VF020B_HARDWARE_WRITE_PROTECTION_ENABLE Specifies if the hardware write protect feature is enabled or not. DRV_SST25VF020B_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported. DRV_SST25VF020B_MODE Determines whether the driver is implemented as static or dynamic. DRV_SST25VF020B_QUEUE_DEPTH_COMBINED Number of entries of queues in all instances of the driver. Description SST25VF020B Driver Configuration Template These file provides the list of all the configurations that can be used with the driver. This file should not be included in the driver. File Name drv_sst25vf020b_config_template.h Company Microchip Technology Inc. drv_sst25vf064c.h SPI Flash Driver Interface Definition Enumerations Name Description DRV_SST25VF064C_BLOCK_EVENT Identifies the possible events that can result from a request. DRV_SST25VF064C_CLIENT_STATUS Defines the client status. DRV_SST25VF064C_COMMAND_STATUS Specifies the status of the command for the read, write and erase operations. Functions Name Description DRV_SST25VF064C_BlockErase Erase the specified number of blocks in Flash memory. DRV_SST25VF064C_BlockEventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. DRV_SST25VF064C_BlockRead Reads blocks of data starting from the specified address in Flash memory. DRV_SST25VF064C_BlockWrite Write blocks of data starting from a specified address in Flash memory. DRV_SST25VF064C_ClientStatus Gets current client-specific status of the SPI Flash driver. DRV_SST25VF064C_Close Closes an opened-instance of the SPI Flash driver. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 845 DRV_SST25VF064C_CommandStatus Gets the current status of the command. DRV_SST25VF064C_Deinitialize Deinitializes the specified instance of the SPI Flash driver module. DRV_SST25VF064C_GeometryGet Returns the geometry of the device. DRV_SST25VF064C_Initialize Initializes the SST25VF064C SPI Flash Driver instance for the specified driver index. DRV_SST25VF064C_MediaIsAttached Returns the status of the media. DRV_SST25VF064C_Open Opens the specified SPI Flash driver instance and returns a handle to it. DRV_SST25VF064C_Status Gets the current status of the SPI Flash Driver module. DRV_SST25VF064C_Tasks Maintains the driver's read, erase, and write state machine and implements its ISR. Macros Name Description DRV_SST25VF064C_BLOCK_COMMAND_HANDLE_INVALID This value defines the SPI Flash Driver Block Command Invalid handle. DRV_SST25VF064C_INDEX_0 SPI Flash driver index definitions. DRV_SST25VF064C_INDEX_1 This is macro DRV_SST25VF064C_INDEX_1. Structures Name Description DRV_SST25VF064C_INIT Contains all the data necessary to initialize the SPI Flash device. Types Name Description DRV_SST25VF064C_BLOCK_COMMAND_HANDLE Handle identifying block commands of the driver. DRV_SST25VF064C_EVENT_HANDLER Pointer to a SST25VF064C SPI Flash Driver Event handler function. Description SPI Flash Driver Interface Definition The SPI Flash device driver provides a simple interface to manage the SPI Flash modules which are external to Microchip Controllers. This file defines the interface definition for the SPI Flash Driver. File Name drv_sst25vf064c.h Company Microchip Technology Inc. drv_sst25vf064c_config_template.h SST25VF064C Driver Configuration Template. Macros Name Description DRV_SST25VF064C_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_SST25VF064C_HARDWARE_HOLD_ENABLE Specifies whether or not the hardware hold feature is enabled. DRV_SST25VF064C_HARDWARE_WRITE_PROTECTION_ENABLE Specifies whether or not the hardware write protect feature is enabled. DRV_SST25VF064C_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported. DRV_SST25VF064C_MODE Determines whether the driver is implemented as static or dynamic. DRV_SST25VF064C_QUEUE_DEPTH_COMBINED Number of entries of queues in all instances of the driver. Description SST25VF064C Driver Configuration Template These file provides the list of all the configurations that can be used with the driver. This file should not be included in the driver. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 846 File Name drv_sst25vf064c_config_template.h Company Microchip Technology Inc. SPI PIC32WK IPF Flash Driver Library This section describes the Serial Peripheral Interface (SPI) Flash driver library for the PIC32WK IPF (in-package flash) module. Introduction This library provides an interface to manage the PIC32WK IPF module in different modes of operation. Description PIC32WK consists of an in-package flash (IPF) that is interfaced to the core using SPI, specifically the SPI0 instance. For more information, refer to the PIC32WK Silicon Data Sheet. The SPI module of the controller operates as a master device and the IPF module operates as a slave. The PIC32WK IPF driver is dynamic in nature, therefore a single instance of it can support multiple clients that want to use the same flash. Multiple instances of the driver can be used when multiple flash devices are required to be part of the system. The SPI driver, which is used by the PIC32WK IPF driver, can be configured for use in either Polled or Interrupt mode. Using the Library This topic describes the basic architecture of the SPI PIC32WK IPF Flash Driver Library and provides information and examples about how to use it. Description Interface Header File: drv_ipf.h The interface to the SPI PIC32WK IPF Flash Driver Library is defined in the drv_ipf.h header file. Any C language source (.c) file that uses the SPI PIC32WK IPF Flash Driver Library should include this header file. Refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Library Source Files The SPI PIC32WK IPF Flash Driver Library source files are provided in the /framework/driver/spi_flash/pic32wk_ipf/src folder. This folder may contain optional files and alternate Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 847 implementations. Refer to Configuring the Library for instructions about how to select optional features, and Building the Library for instructions about how to build the library. Abstraction Model This section provides a low-level abstraction of the SPI PIC32WK IPF Flash Driver Library with a convenient C language interface. This topic describes how that abstraction is modeled in software. Description To perform a particular operation, the SPI PIC32WK IPF Flash Driver Library needs a specific set of commands to be given on its SPI interface along with the required address and data. The driver abstracts these requirements and provides simple APIs that can be used to perform Erase, Write, Read and memory protect operations. The SPI Driver is used for this purpose. The following layered diagram depicts the communication between different modules. SPI PIC32WK IPF Flash Driver Library Abstraction Model Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. Description The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the SPI PIC32WK IPF Flash Driver Library. Library Interface Section Description System Functions Accessed by the MPLAB Harmony system module and allow the driver to be initialized, de-initialized, and maintained. Core Client Functions Allow the application client to open and close the driver. Block Operation Functions Enable the Flash module to be erased, written, and read (to/from). Media Interface Functions Provide media status and the Flash geometry. Memory Protection Functions Functions protect or unprotect the required block of memory. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 848 Pin Control Functions Functions provide a means of controlling WP and Hold Pins. How the Library Works This topic describes the basic architecture of the SPI PIC32WK IPF Flash Driver Library and provides information and examples about its use. Description The library provides interfaces to support: • System Initialization/Deinitialization • Opening the Driver • Block Operations System Initialization/Deinitialization This section provides information about initializing the system. Description The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization, the SPI PIC32WK IPF Flash Driver is initialized with the following configuration settings (either passed dynamically at runtime by using DRV_IPF_INIT or by using Initialization Overrides) that are supported or used by the IPF: • Device-requested power state: one of the System Module Power States. For specific details please refer to "Data Types and Constants" in the Library Interface section. • The SPI Driver Module Index, which is intended to be used to communicate with the IPF (for example, DRV_SPI_INDEX_0) • Port Pins of the microcontroller to be used for Chip Select, Write Protection, and Hold operations on the IPF. • Maximum Buffer Queue Size for that instance of the IPF. The DRV_IPF_Initialize function returns an object handle of the type SYS_MODULE_OBJ. After this, the object handle returned by the Initialize interface is used by the other system interfaces such as DRV_IPF_Deinitialize, DRV_ IPF _Status, and DRV_ IPF _Tasks. Notes: 1. The system initialization and deinitialization settings affect only the instance of the peripheral that is being initialized or deinitialized. 2. As Hold, WP, and Chip select pins are internally routed, these are not configurable. Refer to the PIC32WK Silicon Data Sheet for more information. Example: // This code example shows the initialization of the In-Package Flash // Driver. SPI driver index 0 is used for the purpose. Pin numbers 1, 2, // and 3 of PORTB are configured for the Hold pin, Write Protection pin, and // the Chip Select pin, respectively. The maximum buffer queue size is set to 5. DRV_IPF_INIT IPFInitData; SYS_MODULE_OBJ objectHandle; IPFInitData.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; IPFInitData.spiDriverModuleIndex = DRV_SPI_INDEX_0; IPFInitData.holdPortChannel = PORT_CHANNEL_K; IPFInitData.holdBitPosition = PORTS_BIT_POS_14; IPFInitData.writeProtectPortChannel = PORT_CHANNEL_K; IPFInitData.writeProtectBitPosition = PORTS_BIT_POS_13; IPFInitData.chipSelectPortChannel = PORT_CHANNEL_K; IPFInitData.chipSelectBitPosition = PORTS_BIT_POS_15; IPFInitData.queueSize = 5; objectHandle = DRV_IPF_Initialize(DRV_IPF_INDEX_0,(SYS_MODULE_INIT*)IPFInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Tasks Routine The system will call DRV_IPF_Tasks, from SYS_Tasks. . Opening the Driver This section provides information about opening the driver. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 849 Description To use the SST Flash driver, the application must open the driver. Using the SST25VF020B as an example, this is done by calling the DRV_IPF_Open function. Calling this function with DRV_IO_INTENT_NONBLOCKING will cause the driver to be opened in non blocking mode. Then DRV_IPF_BlockErase, DRV_IPF_BlockWrite and DRV_IPF_BlockRead functions when called by this client will be non-blocking. The client can also open the driver in Read-only mode (DRV_IO_INTENT_READ), Write-only mode (DRV_IO_INTENT_WRITE), and Exclusive mode (DRV_IO_INTENT_EXCLUSIVE). If the driver has been opened exclusively by a client, it cannot be opened again by another client. If successful, the DRV_IPF_Open function will return a handle to the driver. This handle records the association between the client and the driver instance that was opened. The DRV_IPF_Open function may return DRV_HANDLE_INVALID in the situation where the driver is not ready to be opened. When this occurs, the application can try opening the driver again. Note that the open function may return and invalid handle in other (error) cases as well. The following code shows an example of the driver being opened in different modes. DRV_HANDLE ipfHandle1, ipfHandle2; /* Client 1 opens the IPF driver in non blocking mode */ ipfHandle1 = DRV_IPF_Open(DRV_IPF_INDEX_0, DRV_IO_INTENT_NONBLOCKING); /* Check if the handle is valid */ if(DRV_HANDLE_INVALID == ipfHandle1) { /* The driver was not opened successfully. The client * can try opening it again */ } /* Client 2 opens the IPF driver in Exclusive Write only mode */ ipfHandle2 = DRV_IPF_Open(DRV_IPF_INDEX_0, DRV_IO_INTENT_WRITE | DRV_IO_INTENT_EXCLUSIVE); /* Check if the handle is valid */ if(DRV_HANDLE_INVALID == ipfHandle2) { /* The driver was not opened successfully. The client * can try opening it again */ } Block Operations This section provides information about block operations. Description This driver provides simple client interfaces to Erase, Write, and Read the IPF in blocks. A block is the unit to represent minimum amount of data that can be erased, written, or read. Block size may differ for Erase, Write, and Read operations. The DRV_IPF_GeometryGet function can be used to determine the different block sizes for the driver. The DRV_IPF_BlockErase, DRV_IPF_BlockWrite, and DRV_IPF_BlockRead functions are used to erase, write, and read the data to/from IPF. These functions are always non-blocking. All of these functions follow a standard queue model to read, write, and erase. When any of these functions are called (i.e., a block request is made), the request is queued. The size of the queue is determined by the queueSize member of the DRV_IPF_INIT data structure. All of the requests in the queue are executed by the DRV_IPF_Tasks function one-by-one. When the driver adds a request to the queue, it returns a buffer handle. This handle allows the client to track the request as it progresses through the queue. The buffer handle expires when the event associated with the buffer completes. The driver provides driver events (DRV_IPF_BLOCK_EVENT) that indicate termination of the buffer requests. For a simple Block Data Operation, perform the following steps : 1. The system should have completed necessary initialization of the SPI Driver and the IPF Driver, and the DRV_IPF_Tasks function should be running in a polled environment. 2. The DRV_SPI_Tasks function should be running in either a polled environment or an interrupt environment. 3. Open the driver using DRV_IPF_Open with the necessary intent. 4. Set an event handler callback using the function DRV_IPF_BlockEventHandlerSet. 5. Request for block operations using the functions, DRV_IPF_BlockErase, DRV_IPF_BlockWrite, and DRV_IPF_BlockRead, with the appropriate parameters. 6. Wait for event handler callback to occur and check the status of the block operation using the callback function parameter of type DRV_IPF_BLOCK_EVENT. 7. The client will be able to close the driver using the function, DRV_IPF_Close, when required. Example: /* This code example shows usage of the block operations * on the PIC32WK IPF */ DRV_HANDLE ipfHandle1; uint8_t myData1[10], myData2[10]; DRV_IPF_BLOCK_COMMAND_HANDLE blockHandle1, blockHandle2, blockHandle3; /* The driver is opened for read-write in Exclusive mode */ ipfHandle1 = DRV_IPF_Open(DRV_IPF_INDEX_0, Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 850 DRV_IO_INTENT_READWRITE | DRV_IO_INTENT_EXCLUSIVE); /* Check if the driver was opened successfully */ if(DRV_HANDLE_INVALID == ipfHandle1) { /* The driver could not be opened successfully */ } /* Register a Buffer Event Handler with IPF driver. * This event handler function will be called whenever * there is a buffer event. An application defined * context can also be specified. This is returned when * the event handler is called. * */ DRV_IPF_BlockEventHandlerSet(sstHandle1,APP_IPFBufferEventHandler, NULL); /* Request for all the three block operations one by one */ /* first block API to erase 1 block of the flash starting from address 0x0, each block is of 4kbyte */ DRV_IPF_BlockErase(ipfHandle1, &blockHandle1, 0x0, 1); /* 2nd block API to write myData1 in the first 10 locations of the flash */ DRV_SST25VF020B_BlockWrite(ipfHandle1, &blockHandle2, &myData1[0], 0x0, 10); /* 3rd block API to read the first 10 locations of the flash into myData2 */ DRV_SST25VF020B_BlockRead(ipfHandle1, &blockHandle3, &myData2[0], 0x0, 10); /* This is the Driver Event Handler */ void APP_IPFBufferEventHandler(DRV_SST25VF020B_BLOCK_EVENT event, DRV_SST25VF020B_BLOCK_COMMAND_HANDLE blockHandle, uintptr_t contextHandle) { switch(event) { case DRV_IPF_EVENT_BLOCK_COMMAND_COMPLETE: if ( blockHandle == blockHandle3) { /* This means the data was read */ /* Do data verification/processing */ } break; case DRV_IPF_EVENT_BLOCK_COMMAND_ERROR: /* Error handling here. */ break; default: break; } Configuring the Library Use this section for the drivers and system services and middleware. This section will contain any related configuration macros imported into the project from the companion _config_template.h file into this topic, if applicable. Description The SPI PIC32WK IPF Flash Driver Library requires the specification of compile-time configuration macros. These macros define resource usage, feature availability, and dynamic behavior of the driver. These configuration macros should be defined in the system_config.h file. This header can be placed anywhere, 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. Building the Library This section lists the files that are available in the SPI PIC32WK IPF Flash Driver Library. Description This section list the files that are available in the \src folder of the SPI PIC32WK IPF Flash 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. 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 /framework/driver/spi_flash/pic32wk_ipf. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 851 Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_ipf.h Header file that exports the driver API. 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 /src/dynamic/drv_ipf.c Basic SPI PIC32WK IPF Flash Driver implementation file. /src/dynamic/drv_ipf_fs.c File system functions used by the driver API. /src/drv_ipf_prot.c Protocol implementation used by the driver. 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 N/A No optional files are available for this library Module Dependencies The SPI PIC32WK IPF Flash Driver Library depends on the following modules: • Clock System Service Library Optional Dependencies • DMA System Service Library (used when operating in DMA mode) • Interrupt System Service Library (used when task is running in Interrupt mode) Library Interface a) System Initialization Functions Name Description DRV_IPF_Deinitialize Deinitializes the specified instance of the SPI Flash driver module. Implementation: Dynamic DRV_IPF_Initialize Initializes the IPF SPI Flash Driver instance for the specified driver index. Implementation: Dynamic DRV_IPF_Status Gets the current status of the SPI Flash Driver module. Implementation: Dynamic DRV_IPF_Tasks Maintains the driver's read, erase, and write state machine and implements its ISR. Implementation: Dynamic b) Client Setup Functions Name Description DRV_IPF_ClientStatus Gets current client-specific status of the SPI Flash driver. Implementation: Dynamic DRV_IPF_Close Closes an opened-instance of the SPI Flash driver. Implementation: Dynamic DRV_IPF_Open Opens the specified SPI Flash driver instance and returns a handle to it. Implementation: Dynamic c) Other Functions Name Description DRV_IPF_BlockErase Erase the specified number of blocks in Flash memory. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 852 DRV_IPF_BlockEventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. Implementation: Dynamic DRV_IPF_BlockRead Reads blocks of data starting from the specified address in Flash memory. Implementation: Dynamic DRV_IPF_BlockWrite Write blocks of data starting from a specified address in Flash memory. Implementation: Dynamic DRV_IPF_GeometryGet Returns the geometry of the device. Implementation: Dynamic DRV_IPF_HoldAssert Asserts the Hold pin for flash. Implementation: Dynamic DRV_IPF_HoldDeAssert Deasserts the Hold pin for flash. Implementation: Dynamic DRV_IPF_MediaIsAttached Returns the status of the media. Implementation: Dynamic DRV_IPF_ProtectMemoryVolatile Protects the memory block to which the given memory address belongs Implementation: Dynamic DRV_IPF_ReadBlockProtectionStatus Reads the content of Block Protection Register which belongs to In-Package flash. Implementation: Dynamic DRV_IPF_UnProtectMemoryVolatile Un-protects the memory block to which the given memory address belongs Implementation: Dynamic DRV_IPF_WPAssert Asserts the WP pin for flash. Implementation: Dynamic DRV_IPF_WPDeAssert Deasserts the WP pin for flash. Implementation: Dynamic d) Data Types and Constants Name Description DRV_IPF_BLOCK_COMMAND_HANDLE Handle identifying block commands of the driver. DRV_IPF_BLOCK_EVENT Identifies the possible events that can result from a request. DRV_IPF_BLOCK_OPERATION Lists the different operations that IPF driver can do. DRV_IPF_CLIENT_STATUS Defines the client status. Implementation: Dynamic DRV_IPF_COMMAND_STATUS Specifies the status of the command for the read, write and erase operations. DRV_IPF_EVENT_HANDLER Pointer to a IPF SPI Flash Driver Event handler function. Implementation: Dynamic DRV_IPF_INIT Contains all the data necessary to initialize the SPI Flash device. Implementation: Dynamic DRV_IPF_PROT_MODE Lists the different memory protection modes. _DRV_IPF_H This is macro _DRV_IPF_H. DRV_IPF_BLOCK_COMMAND_HANDLE_INVALID This value defines the SPI Flash Driver Block Command Invalid handle. DRV_IPF_INDEX_0 SPI Flash driver index definitions _DRV_IPF_CONFIG_TEMPLATE_H This is macro _DRV_IPF_CONFIG_TEMPLATE_H. DRV_IPF_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to the hardware instance. DRV_IPF_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_IPF_MODE Determines whether the driver is implemented as static or dynamic Description This section describes the API functions of the SPI PIC32WK IPF Flash Driver library. Refer to each section for a detailed description. a) System Initialization Functions DRV_IPF_Deinitialize Function Deinitializes the specified instance of the SPI Flash driver module. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 853 Implementation: Dynamic File drv_ipf.h C void DRV_IPF_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the SPI Flash Driver module, disabling its operation (and any hardware) and invalidates all of the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. Preconditions Function DRV_IPF_Initialize should have been called before calling this function. Example // This code snippet shows an example of deinitializing the driver. SYS_MODULE_OBJ object; // Returned from DRV_IPF_Initialize SYS_STATUS status; DRV_IPF_Deinitialize(object); status = DRV_IPF_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from the DRV_IPF_Initialize Function void DRV_IPF_Deinitialize( SYS_MODULE_OBJ object ) DRV_IPF_Initialize Function Initializes the IPF SPI Flash Driver instance for the specified driver index. Implementation: Dynamic File drv_ipf.h C SYS_MODULE_OBJ DRV_IPF_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. Description This function initializes the SPI Flash driver instance for the specified driver index, making it ready for clients to open and use it. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 854 Remarks This function must be called before any other SPI Flash function is called. This function should only be called once during system initialization unless DRV_IPF_Deinitialize is called to deinitialize the driver instance. Build configuration options may be used to statically override options in the "init" structure and will take precedence over initialization data passed using this function. Preconditions None. Example // This code snippet shows an example of initializing the IPF SPI // Flash Driver. SPI driver index 0 is used for the purpose. Pin numbers 1, 2 // and 3 of port channel B are configured for hold pin, write protection pin // and chip select pin respectively. Maximum buffer queue size is set 5. DRV_IPF_INIT IPFInitData; SYS_MODULE_OBJ objectHandle; IPFInitData.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; IPFInitData.spiDriverModuleIndex = DRV_SPI_INDEX_0; IPFInitData.holdPortChannel = PORT_CHANNEL_B; IPFInitData.holdBitPosition = PORTS_BIT_POS_1; IPFInitData.writeProtectPortChannel = PORT_CHANNEL_B; IPFInitData.writeProtectBitPosition = PORTS_BIT_POS_2; IPFInitData.chipSelectPortChannel = PORT_CHANNEL_F; IPFInitData.chipSelectBitPosition = PORTS_BIT_POS_2; IPFInitData.queueSize = 5; objectHandle = DRV_IPF_Initialize(DRV_IPF_INDEX_0, (SYS_MODULE_INIT*)IPFInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized init Pointer to a data structure containing data necessary to initialize the driver. Function SYS_MODULE_OBJ DRV_IPF_Initialize ( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); DRV_IPF_Status Function Gets the current status of the SPI Flash Driver module. Implementation: Dynamic File drv_ipf.h C SYS_STATUS DRV_IPF_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is ready and accept requests for new operations SYS_STATUS_UNINITIALIZED - Indicates that the driver is not initialized Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 855 Description This function provides the current status of the SPI Flash Driver module. Remarks A driver can only be opened when its status is SYS_STATUS_READY. Preconditions Function DRV_IPF_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_IPF_Initialize SYS_STATUS IPFStatus; IPFStatus = DRV_IPF_Status(object); else if (SYS_STATUS_ERROR >= IPFStatus) { // Handle error } Parameters Parameters Description object Driver object handle, returned from the DRV_IPF_Initialize Function SYS_STATUS DRV_IPF_Status( SYS_MODULE_OBJ object ) DRV_IPF_Tasks Function Maintains the driver's read, erase, and write state machine and implements its ISR. Implementation: Dynamic File drv_ipf.h C void DRV_IPF_Tasks(SYS_MODULE_OBJ object); Returns None. Description This function is used to maintain the driver's internal state machine and should be called from the system's Tasks function. Remarks This function is normally not called directly by an application. It is called by the system's Tasks function (SYS_Tasks). Preconditions The DRV_IPF_Initialize function must have been called for the specified SPI Flash driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_IPF_Initialize while (true) { DRV_IPF_Tasks (object); // Do other tasks } Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 856 Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_IPF_Initialize) Function void DRV_IPF_Tasks ( SYS_MODULE_OBJ object ); b) Client Setup Functions DRV_IPF_ClientStatus Function Gets current client-specific status of the SPI Flash driver. Implementation: Dynamic File drv_ipf.h C DRV_IPF_CLIENT_STATUS DRV_IPF_ClientStatus(const DRV_HANDLE handle); Returns A DRV_IPF_CLIENT_STATUS value describing the current status of the driver. Description This function gets the client-specific status of the SPI Flash driver associated with the given handle. Remarks This function will not block for hardware access and will immediately return the current status. Preconditions The DRV_IPF_Initialize function must have been called. DRV_IPF_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_IPF_Open DRV_IPF_CLIENT_STATUS clientStatus; clientStatus = DRV_IPF_ClientStatus(handle); if(DRV_IPF_CLIENT_STATUS_READY == clientStatus) { // do the tasks } Parameters Parameters Description handle A valid open instance handle, returned from the driver's open Function DRV_IPF_CLIENT_STATUS DRV_IPF_ClientStatus(DRV_HANDLE handle); DRV_IPF_Close Function Closes an opened-instance of the SPI Flash driver. Implementation: Dynamic File drv_ipf.h Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 857 C void DRV_IPF_Close(const DRV_HANDLE handle); Returns None. Description This function closes an opened-instance of the SPI Flash driver, invalidating the handle. Remarks After calling this function, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_IPF_Open before the caller may use the driver again. Usually, there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_IPF_Initialize function must have been called for the specified SPI Flash driver instance. DRV_IPF_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_IPF_Open DRV_IPF_Close(handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function void DRV_IPF_Close( DRV_Handle handle ); DRV_IPF_Open Function Opens the specified SPI Flash driver instance and returns a handle to it. Implementation: Dynamic File drv_ipf.h C DRV_HANDLE DRV_IPF_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent); Returns If successful, the function returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Errors can occur under the following circumstances: • if the number of client objects allocated via DRV_IPF_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the driver hardware instance being opened is not initialized or is invalid • if the client is trying to open the driver exclusively, but has already been opened in a non exclusive mode by another client. • if the driver status is not ready. The driver status becomes ready inside "DRV_IPF_Tasks" function. To make the SST Driver status ready and hence successfully "Open" the driver, "Task" routine need to be called periodically. Description This function opens the specified SPI Flash driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Remarks The driver will always work in Non-Blocking mode even if IO-intent is selected as blocking. The handle returned is valid until the DRV_IPF_Close function is called. This function will NEVER block waiting for hardware. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 858 Preconditions Function DRV_IPF_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_IPF_Open(DRV_IPF_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } Parameters Parameters Description drvIndex Identifier for the object instance to be opened ioIntent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver Function DRV_HANDLE DRV_IPF_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT ioIntent ); c) Other Functions DRV_IPF_BlockErase Function Erase the specified number of blocks in Flash memory. Implementation: Dynamic File drv_ipf.h C void DRV_IPF_BlockErase(const DRV_HANDLE handle, DRV_IPF_BLOCK_COMMAND_HANDLE * commandHandle, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It Will be DRV_BUFFER_HANDLE_INVALID if the request was not queued. Description This function schedules a non-blocking erase operation in flash memory. The function returns with a valid erase handle in the commandHandle argument if the erase request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. The function returns DRV_IPF_BLOCK_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if the client opened the driver for read only • if nBlock is 0 • if the queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_IPF_EVENT_ERASE_COMPLETE event if the erase operation was successful or DRV_IPF_EVENT_ERASE_ERROR event if the erase operation was not successful. Remarks Write Protection will be disabled for the complete flash memory region in the beginning by default. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 859 Preconditions The DRV_IPF_Initialize function must have been called for the specified SPI Flash driver instance. DRV_IPF_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_IPF_Open call. Example // Destination address should be block aligned. uint32_t blockStart; uint32_t nBlock; DRV_IPF_BLOCK_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // myIPFHandle is the handle returned // by the DRV_IPF_Open function. // Client registers an event handler with driver DRV_IPF_BlockEventHandlerSet(myIPFHandle, APP_IPFEventHandler, (uintptr_t)&myAppObj); DRV_IPF_BlockErase( myIPFHandle, commandHandle, blockStart, nBlock ); if(DRV_IPF_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when // the buffer queue is processed. void APP_IPFEventHandler(DRV_IPF_BLOCK_EVENT event, DRV_IPF_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_IPF_EVENT_ERASE_COMPLETE: // This means the data was transferred. break; case DRV_IPF_EVENT_ERASE_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle blockStart Start block address in IPF memory from where the erase should begin. LSBs (A0-A11) of block start address will be ignored to align it with Erase block size boundary. nBlock Total number of blocks to be erased. Each Erase block is of size 4 KByte. Function void DRV_IPF_BlockErase ( Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 860 const DRV_HANDLE handle, DRV_IPF_BLOCK_COMMAND_HANDLE * commandHandle, uint32_t blockStart, uint32_t nBlock ); DRV_IPF_BlockEventHandlerSet Function Allows a client to identify an event handling function for the driver to call back when queued operation has completed. Implementation: Dynamic File drv_ipf.h C void DRV_IPF_BlockEventHandlerSet(const DRV_HANDLE handle, const DRV_IPF_EVENT_HANDLER eventHandler, const uintptr_t context); Returns None. Description This function allows a client to identify an event handling function for the driver to call back when queued operation has completed. When a client calls any read, write or erase function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the queued operation has completed. The event handler should be set before the client performs any read/write/erase operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued operation has completed, it does not need to register a callback. Preconditions The DRV_IPF_Initialize function must have been called for the specified SPI FLash driver instance. DRV_IPF_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; uint8_t myBuffer[MY_BUFFER_SIZE]; uint32_t blockStart, nBlock; DRV_IPF_BLOCK_COMMAND_HANDLE commandHandle; // myIPFHandle is the handle returned // by the DRV_IPF_Open function. // Client registers an event handler with driver. This is done once. DRV_IPF_BlockEventHandlerSet( myIPFHandle, APP_IPFEventHandler, (uintptr_t)&myAppObj ); DRV_IPF_BlockRead( myIPFHandle, commandHandle, &myBuffer, blockStart, nBlock ); if(DRV_IPF_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event Processing Technique. Event is received when operation is done. void APP_IPFEventHandler(DRV_IPF_BLOCK_EVENT event, DRV_IPF_BLOCK_COMMAND_HANDLE handle, uintptr_t context) { Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 861 // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) context; switch(event) { case DRV_IPF_EVENT_BLOCK_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_IPF_EVENT_BLOCK_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function eventHandler Pointer to the event handler function implemented by the user context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_IPF_BlockEventHandlerSet ( const DRV_HANDLE handle, const DRV_IPF_EVENT_HANDLER eventHandler, const uintptr_t context ); DRV_IPF_BlockRead Function Reads blocks of data starting from the specified address in Flash memory. Implementation: Dynamic File drv_ipf.h C void DRV_IPF_BlockRead(const DRV_HANDLE handle, DRV_IPF_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t * targetBuffer, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It will be DRV_BUFFER_HANDLE_INVALID if the request was not successful. Description This function schedules a non-blocking read operation for reading blocks of data from flash memory. The function returns with a valid handle in the commandHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_IPF_BLOCK_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer could not be allocated to the request • if the target buffer pointer is NULL • if the client opened the driver for write only • if the buffer size is 0 Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 862 • if the read queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_IPF_EVENT_BLOCK_COMMAND_COMPLETE event if the buffer was processed successfully of DRV_IPF_EVENT_BLOCK_COMMAND_ERROR event if the buffer was not processed successfully. Remarks The maximum read speed is 33 MHz. Preconditions The DRV_IPF_Initialize function must have been called for the specified SPI Flash driver instance. DRV_IPF_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_IPF_Open call. Example uint8_t myBuffer[MY_BUFFER_SIZE]; // address should be block aligned. uint32_t blockStart = IPF_BASE_ADDRESS_TO_READ_FROM; uint32_t nBlock = 2; DRV_IPF_BLOCK_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // myIPFHandle is the handle returned // by the DRV_IPF_Open function. // Client registers an event handler with driver DRV_IPF_BlockEventHandlerSet(myIPFHandle, APP_IPFEventHandler, (uintptr_t)&myAppObj); DRV_IPF_BlockRead( myIPFHandle, commandHandle, &myBuffer, blockStart, nBlock ); if(DRV_IPF_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when the buffer is processed. void APP_IPFEventHandler(DRV_IPF_BLOCK_EVENT event, DRV_IPF_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_IPF_EVENT_BLOCK_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_IPF_EVENT_BLOCK_COMMAND_ERROR: // Error handling here. break; default: break; } } Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 863 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle *targetBuffer Buffer into which the data read from the SPI Flash instance will be placed blockStart Start block address in IPF memory from where the read should begin. It can be any address of the flash. nBlock Total number of blocks to be read. Each Read block is of 1 byte. Function void DRV_IPF_BlockRead ( const DRV_HANDLE handle, DRV_IPF_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t *targetBuffer, uint32_t blockStart, uint32_t nBlock ); DRV_IPF_BlockWrite Function Write blocks of data starting from a specified address in Flash memory. Implementation: Dynamic File drv_ipf.h C void DRV_IPF_BlockWrite(DRV_HANDLE handle, DRV_IPF_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t * sourceBuffer, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It will be DRV_BUFFER_HANDLE_INVALID if the request was not successful. Description This function schedules a non-blocking write operation for writing blocks of data into flash memory. The function returns with a valid buffer handle in the commandHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_IPF_BLOCK_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the client opened the driver for read only • if the buffer size is 0 • if the write queue size is full or queue depth is insufficient • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_IPF_EVENT_BLOCK_COMMAND_COMPLETE event if the buffer was processed successfully or DRV_IPF_EVENT_BLOCK_COMMAND_ERROR event if the buffer was not processed successfully. Remarks In the case of multi bytes write operation, byte by byte writing will happen instead of Address auto Increment writing. Write Protection will be disabled for the complete flash memory region in the beginning by default. Preconditions The DRV_IPF_Initialize function must have been called for the specified SPI Flash driver instance. DRV_IPF_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_IPF_Open call. The flash address location which has to be written, must be erased before using the API DRV_IPF_BlockErase(). Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 864 Example uint8_t myBuffer[MY_BUFFER_SIZE]; // address should be block aligned. uint32_t blockStart = IPF_BASE_ADDRESS_TO_WRITE_TO; uint32_t nBlock = 2; DRV_IPF_BLOCK_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // myIPFHandle is the handle returned // by the DRV_IPF_Open function. // Client registers an event handler with driver DRV_IPF_BlockEventHandlerSet(myIPFHandle, APP_IPFEventHandler, (uintptr_t)&myAppObj); DRV_IPF_BlockWrite( myIPFHandle, commandHandle, &myBuffer, blockStart, nBlock ); if(DRV_IPF_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_IPFEventHandler(DRV_IPF_BLOCK_EVENT event, DRV_IPF_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_IPF_EVENT_BLOCK_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_IPF_EVENT_BLOCK_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle -Pointer to an argument that will contain the return buffer handle sourceBuffer The source buffer containing data to be programmed into SPI Flash blockStart Start block address of IPF Flash where the write should begin. It can be any address of the flash. nBlock Total number of blocks to be written. Each write block is of 1 byte. Function void DRV_IPF_BlockWrite ( DRV_HANDLE handle, DRV_IPF_BLOCK_COMMAND_HANDLE * commandHandle, Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 865 uint8_t *sourceBuffer, uint32_t blockStart, uint32_t nBlock ); DRV_IPF_GeometryGet Function Returns the geometry of the device. Implementation: Dynamic File drv_ipf.h C SYS_FS_MEDIA_GEOMETRY * DRV_IPF_GeometryGet(DRV_HANDLE handle); Returns SYS_FS_MEDIA_GEOMETRY - Structure which holds the media geometry information. Description This API gives the following geometrical details of the IPF Flash: • Media Property • Number of Read/Write/Erase regions in the flash device • Number of Blocks and their size in each region of the device Remarks This function is typically used by File System Media Manager. Preconditions None. Example SYS_FS_MEDIA_GEOMETRY * sstFlashGeometry; uint32_t readBlockSize, writeBlockSize, eraseBlockSize; uint32_t nReadBlocks, nReadRegions, totalFlashSize; sstFlashGeometry = DRV_IPF_GeometryGet(sstOpenHandle1); // read block size should be 1 byte readBlockSize = sstFlashGeometry->geometryTable->blockSize; nReadBlocks = sstFlashGeometry->geometryTable->numBlocks; nReadRegions = sstFlashGeometry->numReadRegions; // write block size should be 1 byte writeBlockSize = (sstFlashGeometry->geometryTable +1)->blockSize; // erase block size should be 4k byte eraseBlockSize = (sstFlashGeometry->geometryTable +2)->blockSize; // total flash size should be 256k byte totalFlashSize = readBlockSize * nReadBlocks * nReadRegions; Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function SYS_FS_MEDIA_GEOMETRY DRV_IPF_GeometryGet( DRV_HANDLE handle ); DRV_IPF_HoldAssert Function Asserts the Hold pin for flash. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 866 File drv_ipf.h C void DRV_IPF_HoldAssert(); Returns None. Description This API is used to assert the Hold pin of the in-package flash. Remarks The Hold GPIO is fixed in case of PIC32WK devices. Preconditions None. Example DRV_IPF_HoldAssert(); Function void DRV_IPF_HoldAssert(); DRV_IPF_HoldDeAssert Function Deasserts the Hold pin for flash. Implementation: Dynamic File drv_ipf.h C void DRV_IPF_HoldDeAssert(); Returns None. Description This API is used to deassert the Hold pin of the in-package flash. Remarks The Hold GPIO is fixed in case of PIC32WK devices. Preconditions None. Example DRV_IPF_HoldDeAssert(); Function void DRV_IPF_HoldDeAssert(); DRV_IPF_MediaIsAttached Function Returns the status of the media. Implementation: Dynamic File drv_ipf.h Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 867 C bool DRV_IPF_MediaIsAttached(DRV_HANDLE handle); Returns • True - Media is attached • False - Media is not attached Description This API tells if the media is attached or not. Remarks This function is typically used by File System Media Manager. Preconditions None. Example if (DRV_IPF_MediaIsAttached(handle)) { // Do Something } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function bool DRV_IPF_MediaIsAttached( DRV_HANDLE handle); DRV_IPF_ProtectMemoryVolatile Function Protects the memory block to which the given memory address belongs Implementation: Dynamic File drv_ipf.h C void DRV_IPF_ProtectMemoryVolatile(DRV_HANDLE clientHandle, DRV_IPF_BLOCK_COMMAND_HANDLE * commandHandle, uintptr_t memAddress, DRV_IPF_PROT_MODE protMode); Returns None. Description This API is used to protect the memory block to which a given memory address belongs. Both read and write protection mode is supported. The memory will be protected until the next power cycle. Remarks Only the selected blocks can be read protected, which is as per the in-package flash specification. Preconditions In-package flash driver open function must be called and a valid client handle must be available. Example uintptr_t memAddr = IPF_ADDRESS_PROTECT; DRV_IPF_PROT_MODE protMode = DRV_IPF_WRITE_PROTECT; DRV_IPF_BLOCK_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // myIPFHandle is the handle returned // by the DRV_IPF_Open function. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 868 // Client registers an event handler with driver DRV_IPF_BlockEventHandlerSet(myIPFHandle, APP_IPFEventHandler, (uintptr_t)&myAppObj); DRV_IPF_ProtectMemoryVolatile( myIPFHandle, commandHandle, memAddr, protMode ); if(DRV_IPF_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_IPFEventHandler(DRV_IPF_BLOCK_EVENT event, DRV_IPF_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_IPF_EVENT_BLOCK_COMMAND_COMPLETE: // This means the memory protection is complete. break; case DRV_IPF_EVENT_BLOCK_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description clientHandle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle memAddress Memory address which belongs to the memory block which needs to be protected protMode Read or write protect mode. If a block needs to be protected for both read and write, then both enum values can be ORed and passed to the function. Function void DRV_IPF_ProtectMemoryVolatile ( DRV_HANDLE clientHandle, DRV_IPF_BLOCK_COMMAND_HANDLE * commandHandle, uintptr_t memAddress, DRV_IPF_PROT_MODE protMode ); DRV_IPF_ReadBlockProtectionStatus Function Reads the content of Block Protection Register which belongs to In-Package flash. Implementation: Dynamic File drv_ipf.h Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 869 C void DRV_IPF_ReadBlockProtectionStatus(DRV_HANDLE clientHandle, DRV_IPF_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t * buffer); Returns None. Description This API is read the current contents of the block protection register in in-package flash and fills the buffer passed by the client. Remarks The block protection word is 6-bytes wide. Preconditions In-package flash driver open function must be called and a valid client handle must be available. Example uint8_t buf[6] = {0,}; DRV_IPF_BLOCK_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // myIPFHandle is the handle returned // by the DRV_IPF_Open function. // Client registers an event handler with driver DRV_IPF_BlockEventHandlerSet(myIPFHandle, APP_IPFEventHandler, (uintptr_t)&myAppObj); DRV_IPF_ReadBlockProtectionStatus( myIPFHandle, commandHandle, buf ); if(DRV_IPF_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_IPFEventHandler(DRV_IPF_BLOCK_EVENT event, DRV_IPF_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_IPF_EVENT_BLOCK_COMMAND_COMPLETE: // This means the BPR read is complete. break; case DRV_IPF_EVENT_BLOCK_COMMAND_ERROR: // Error handling here. break; default: break; } } Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 870 Parameters Parameters Description clientHandle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle buffer pointer to a buffer to which the block protection status has to be updated Function void DRV_IPF_ReadBlockProtectionStatus ( DRV_HANDLE clientHandle, DRV_IPF_BLOCK_COMMAND_HANDLE * commandHandle, uint8_t * buffer ); DRV_IPF_UnProtectMemoryVolatile Function Un-protects the memory block to which the given memory address belongs Implementation: Dynamic File drv_ipf.h C void DRV_IPF_UnProtectMemoryVolatile(DRV_HANDLE clientHandle, DRV_IPF_BLOCK_COMMAND_HANDLE * commandHandle, uintptr_t memAddress, DRV_IPF_PROT_MODE protMode); Returns None. Description This API is used to un-protect the memory block to which a given memory address belongs. Both read and write protection mode is supported. The memory will be protected until the next power cycle. Remarks If the memory block a client is trying to unprotect, is protected by some other client, then memory unprotection will not executed. The function will return without unprotecting. Preconditions In-package flash driver open function must be called and a valid client handle must be available. Example uintptr_t memAddr = IPF_ADDRESS_UNPROTECT; DRV_IPF_PROT_MODE protMode = DRV_IPF_WRITE_PROTECT; DRV_IPF_BLOCK_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // myIPFHandle is the handle returned // by the DRV_IPF_Open function. // Client registers an event handler with driver DRV_IPF_BlockEventHandlerSet(myIPFHandle, APP_IPFEventHandler, (uintptr_t)&myAppObj); DRV_IPF_UnProtectMemoryVolatile( myIPFHandle, commandHandle, memAddr, protMode ); if(DRV_IPF_BLOCK_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 871 // Event is received when // the buffer is processed. void APP_IPFEventHandler(DRV_IPF_BLOCK_EVENT event, DRV_IPF_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_IPF_EVENT_BLOCK_COMMAND_COMPLETE: // This means the memory unprotection is complete. break; case DRV_IPF_EVENT_BLOCK_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description clientHandle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle memAddress Memory address which belongs to the memory block which needs to be un-protected protMode Read or write protect mode. If a block needs to be un-protected for both read and write, then both enum values can be ORed and passed to the function. Function void DRV_IPF_UnProtectMemoryVolatile ( DRV_HANDLE clientHandle, DRV_IPF_BLOCK_COMMAND_HANDLE * commandHandle, uintptr_t memAddress, DRV_IPF_PROT_MODE protMode ); DRV_IPF_WPAssert Function Asserts the WP pin for flash. Implementation: Dynamic File drv_ipf.h C void DRV_IPF_WPAssert(); Returns None. Description This API is used to assert the Write Protect (WP) pin of the in-package flash. Remarks The Write Protection GPIO is fixed in case of PIC32WK devices. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 872 Preconditions None. Example DRV_IPF_WPAssert(); Function void DRV_IPF_WPAssert(); DRV_IPF_WPDeAssert Function Deasserts the WP pin for flash. Implementation: Dynamic File drv_ipf.h C void DRV_IPF_WPDeAssert(); Returns None. Description This API is used to deassert the Write Protect (WP) pin of the in-package flash. Remarks The Write Protection GPIO is fixed in case of PIC32WK devices. Preconditions None. Example DRV_IPF_WPDeAssert(); Function void DRV_IPF_WPAssert(); d) Data Types and Constants DRV_IPF_BLOCK_COMMAND_HANDLE Type Handle identifying block commands of the driver. File drv_ipf.h C typedef SYS_FS_MEDIA_BLOCK_COMMAND_HANDLE DRV_IPF_BLOCK_COMMAND_HANDLE; Description SPI Flash Driver Block Command Handle A block command handle is returned by a call to the Read, Write, or Erase functions. This handle allows the application to track the completion of the operation. The handle is returned back to the client by the "event handler callback" function registered with the driver. The handle assigned to a client request expires when the client has been notified of the completion of the operation (after event handler function that notifies the client returns) or after the buffer has been retired by the driver if no event handler callback was set. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 873 DRV_IPF_BLOCK_EVENT Enumeration Identifies the possible events that can result from a request. File drv_ipf.h C typedef enum { DRV_IPF_EVENT_BLOCK_COMMAND_COMPLETE, DRV_IPF_EVENT_BLOCK_COMMAND_ERROR } DRV_IPF_BLOCK_EVENT; Members Members Description DRV_IPF_EVENT_BLOCK_COMMAND_COMPLETE Block operation has been completed successfully. Read/Write/Erase Complete DRV_IPF_EVENT_BLOCK_COMMAND_ERROR There was an error during the block operation Read/Write/Erase Error Description IPF SPI Flash Driver Events This enumeration identifies the possible events that can result from a Read, Write, or Erase request caused by the client. Remarks One of these values is passed in the "event" parameter of the event handling callback function that client registered with the driver by calling the DRV_IPF_BlockEventHandlerSet function when a block request is completed. DRV_IPF_BLOCK_OPERATION Enumeration Lists the different operations that IPF driver can do. File drv_ipf.h C typedef enum { DRV_IPF_BLOCK_READ, DRV_IPF_BLOCK_WRITE, DRV_IPF_BLOCK_ERASE, DRV_IPF_HW_BLOCK_PROT, DRV_IPF_HW_BLOCK_UNPROT, DRV_IPF_READ_HW_BLOCK_PROT } DRV_IPF_BLOCK_OPERATION; Members Members Description DRV_IPF_BLOCK_READ Block Read DRV_IPF_BLOCK_WRITE Block Write DRV_IPF_BLOCK_ERASE Block Erase DRV_IPF_HW_BLOCK_PROT Hardware Block Protection DRV_IPF_HW_BLOCK_UNPROT Hardware Block Un-Protection DRV_IPF_READ_HW_BLOCK_PROT Read HW Block Protection Status Description IPF Driver Operations This enumeration lists the different operations that IPF driver can do. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 874 DRV_IPF_CLIENT_STATUS Enumeration Defines the client status. Implementation: Dynamic File drv_ipf.h C typedef enum { DRV_IPF_CLIENT_STATUS_READY = DRV_CLIENT_STATUS_READY+0, DRV_IPF_CLIENT_STATUS_BUSY = DRV_CLIENT_STATUS_BUSY, DRV_IPF_CLIENT_STATUS_CLOSED = DRV_CLIENT_STATUS_CLOSED, DRV_IPF_CLIENT_STATUS_ERROR = DRV_CLIENT_STATUS_ERROR } DRV_IPF_CLIENT_STATUS; Members Members Description DRV_IPF_CLIENT_STATUS_READY = DRV_CLIENT_STATUS_READY+0 Up and running, ready to start new operations DRV_IPF_CLIENT_STATUS_BUSY = DRV_CLIENT_STATUS_BUSY Operation in progress, unable to start a new one DRV_IPF_CLIENT_STATUS_CLOSED = DRV_CLIENT_STATUS_CLOSED Client is closed DRV_IPF_CLIENT_STATUS_ERROR = DRV_CLIENT_STATUS_ERROR Client Error Description SPI Flash Client Status Defines the various client status codes. Remarks None. DRV_IPF_COMMAND_STATUS Enumeration Specifies the status of the command for the read, write and erase operations. File drv_ipf.h C typedef enum { DRV_IPF_COMMAND_COMPLETED = SYS_FS_MEDIA_COMMAND_COMPLETED, DRV_IPF_COMMAND_QUEUED = SYS_FS_MEDIA_COMMAND_QUEUED, DRV_IPF_COMMAND_IN_PROGRESS = SYS_FS_MEDIA_COMMAND_IN_PROGRESS, DRV_IPF_COMMAND_ERROR_UNKNOWN = SYS_FS_MEDIA_COMMAND_UNKNOWN } DRV_IPF_COMMAND_STATUS; Members Members Description DRV_IPF_COMMAND_COMPLETED = SYS_FS_MEDIA_COMMAND_COMPLETED Done OK and ready DRV_IPF_COMMAND_QUEUED = SYS_FS_MEDIA_COMMAND_QUEUED Scheduled but not started DRV_IPF_COMMAND_IN_PROGRESS = SYS_FS_MEDIA_COMMAND_IN_PROGRESS Currently being in transfer DRV_IPF_COMMAND_ERROR_UNKNOWN = SYS_FS_MEDIA_COMMAND_UNKNOWN Unknown Command Description IPF Driver Command Status Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 875 IPF Driver command Status This type specifies the status of the command for the read, write and erase operations. Remarks None. DRV_IPF_EVENT_HANDLER Type Pointer to a IPF SPI Flash Driver Event handler function. Implementation: Dynamic File drv_ipf.h C typedef void (* DRV_IPF_EVENT_HANDLER)(DRV_IPF_BLOCK_EVENT event, DRV_IPF_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t context); Returns None. Description IPF SPI Flash Driver Event Handler Function Pointer This data type defines the required function signature for the IPF SPI Flash driver event handling callback function. A client must register a pointer to an event handling function whose function signature (parameter and return value types) match the types specified by this function pointer in order to receive event calls back from the driver. The parameters and return values and return value are described here and a partial example implementation is provided. Remarks If the event is DRV_IPF_EVENT_BLOCK_COMMAND_COMPLETE, it means that the data was transferred successfully. If the event is DRV_IPF_EVENT_BLOCK_COMMAND_ERROR, it means that the data was not transferred successfully. The context parameter contains the a handle to the client context, provided at the time the event handling function was registered using the DRV_IPF_BlockEventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the read/write/erase request. The event handler function executes in the driver peripheral's interrupt context when the driver is configured for interrupt mode operation. It is recommended of the application to not perform process intensive or blocking operations with in this function. The Read, Write, and Erase functions can be called in the event handler to add a buffer to the driver queue. These functions can only be called to add buffers to the driver whose event handler is running. Example void APP_MyBufferEventHandler ( DRV_IPF_BLOCK_EVENT event, DRV_IPF_BLOCK_COMMAND_HANDLE commandHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_IPF_EVENT_BLOCK_COMMAND_COMPLETE: // Handle the completed buffer. break; case DRV_IPF_EVENT_BLOCK_COMMAND_ERROR: default: // Handle error. break; } } Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 876 Parameters Parameters Description event Identifies the type of event commandHandle Handle returned from the Read/Write/Erase requests context Value identifying the context of the application that registered the event handling function DRV_IPF_INIT Structure Contains all the data necessary to initialize the SPI Flash device. Implementation: Dynamic File drv_ipf.h C typedef struct { SYS_MODULE_INIT moduleInit; SYS_MODULE_INDEX spiDriverModuleIndex; PORTS_CHANNEL holdPortChannel; PORTS_BIT_POS holdBitPosition; PORTS_CHANNEL writeProtectPortChannel; PORTS_BIT_POS writeProtectBitPosition; PORTS_CHANNEL chipSelectPortChannel; PORTS_BIT_POS chipSelectBitPosition; uint32_t queueSize; } DRV_IPF_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization SYS_MODULE_INDEX spiDriverModuleIndex; Identifies the SPI driver to be used PORTS_CHANNEL holdPortChannel; HOLD pin port channel PORTS_BIT_POS holdBitPosition; HOLD pin port position PORTS_CHANNEL writeProtectPortChannel; Write protect pin port channel PORTS_BIT_POS writeProtectBitPosition; Write Protect Bit pin position PORTS_CHANNEL chipSelectPortChannel; Chip select pin port channel PORTS_BIT_POS chipSelectBitPosition; Chip Select Bit pin position uint32_t queueSize; This is the buffer queue size. This is the maximum number of requests that this instance of the driver will queue. For a static build of the driver, this is overridden by the DRV_IPF_QUEUE_SIZE macro in system_config.h Description SST SPI Flash Driver Initialization Data This structure contains all of the data necessary to initialize the SPI Flash device. Remarks A pointer to a structure of this format containing the desired initialization data must be passed into the DRV_IPF_Initialize function. DRV_IPF_PROT_MODE Enumeration Lists the different memory protection modes. File drv_ipf.h C typedef enum { DRV_IPF_WRITE_PROTECT = 1, DRV_IPF_READ_PROTECT } DRV_IPF_PROT_MODE; Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 877 Members Members Description DRV_IPF_WRITE_PROTECT = 1 Write Protect DRV_IPF_READ_PROTECT Read Protect Description IPF Driver memory protection modes This enumeration lists the different memory protection modes. Remarks None. _DRV_IPF_H Macro File drv_ipf.h C #define _DRV_IPF_H Description This is macro _DRV_IPF_H. DRV_IPF_BLOCK_COMMAND_HANDLE_INVALID Macro This value defines the SPI Flash Driver Block Command Invalid handle. File drv_ipf.h C #define DRV_IPF_BLOCK_COMMAND_HANDLE_INVALID Description SPI Flash Driver Block Event Invalid Handle This value defines the SPI Flash Driver Block Command Invalid handle. It is returned by read/write/erase routines when the request could not be taken. Remarks None. DRV_IPF_INDEX_0 Macro SPI Flash driver index definitions File drv_ipf.h C #define DRV_IPF_INDEX_0 0 Description Driver SPI Flash Module Index reference These constants provide IPF SPI Flash driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_IPF_Initialize and DRV_IPF_Open routines to identify the driver instance in use. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 878 _DRV_IPF_CONFIG_TEMPLATE_H Macro File drv_ipf_config_template.h C #define _DRV_IPF_CONFIG_TEMPLATE_H Description This is macro _DRV_IPF_CONFIG_TEMPLATE_H. DRV_IPF_CLIENTS_NUMBER Macro Sets up the maximum number of clients that can be connected to the hardware instance. File drv_ipf_config_template.h C #define DRV_IPF_CLIENTS_NUMBER 4 Description IPF Client Count Configuration Sets up the maximum number of clients that can be connected to the hardware instance. So if IPF will be accessed by 2 clients then this number should be 2. It is recommended that this be set exactly equal to the number of expected clients. Client support consumes RAM memory space. Remarks None. DRV_IPF_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported File drv_ipf_config_template.h C #define DRV_IPF_INSTANCES_NUMBER 1 Description IPF driver objects configuration Sets up the maximum number of hardware instances that can be supported. It is recommended that this number be set exactly equal to the number of IPF modules that are needed by the application. Hardware Instance support consumes RAM memory space. Remarks As PIC32WK has only 1 instance of IPF, this macro is always set to 1. DRV_IPF_MODE Macro Determines whether the driver is implemented as static or dynamic File drv_ipf_config_template.h C #define DRV_IPF_MODE DYNAMIC Description IPF mode Determines whether the driver is implemented as static or dynamic. Static drivers control the peripheral directly with peripheral library routines. Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 879 Remarks None. Files Files Name Description drv_ipf.h SPI Flash Driver Interface Definition drv_ipf_config_template.h IPF Driver Configuration Template. Description This section lists the source and header files used by the SPI PIC32WK IPF Flash Driver Library. drv_ipf.h SPI Flash Driver Interface Definition Enumerations Name Description DRV_IPF_BLOCK_EVENT Identifies the possible events that can result from a request. DRV_IPF_BLOCK_OPERATION Lists the different operations that IPF driver can do. DRV_IPF_CLIENT_STATUS Defines the client status. Implementation: Dynamic DRV_IPF_COMMAND_STATUS Specifies the status of the command for the read, write and erase operations. DRV_IPF_PROT_MODE Lists the different memory protection modes. Functions Name Description DRV_IPF_BlockErase Erase the specified number of blocks in Flash memory. Implementation: Dynamic DRV_IPF_BlockEventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. Implementation: Dynamic DRV_IPF_BlockRead Reads blocks of data starting from the specified address in Flash memory. Implementation: Dynamic DRV_IPF_BlockWrite Write blocks of data starting from a specified address in Flash memory. Implementation: Dynamic DRV_IPF_ClientStatus Gets current client-specific status of the SPI Flash driver. Implementation: Dynamic DRV_IPF_Close Closes an opened-instance of the SPI Flash driver. Implementation: Dynamic DRV_IPF_Deinitialize Deinitializes the specified instance of the SPI Flash driver module. Implementation: Dynamic DRV_IPF_GeometryGet Returns the geometry of the device. Implementation: Dynamic DRV_IPF_HoldAssert Asserts the Hold pin for flash. Implementation: Dynamic DRV_IPF_HoldDeAssert Deasserts the Hold pin for flash. Implementation: Dynamic DRV_IPF_Initialize Initializes the IPF SPI Flash Driver instance for the specified driver index. Implementation: Dynamic DRV_IPF_MediaIsAttached Returns the status of the media. Implementation: Dynamic DRV_IPF_Open Opens the specified SPI Flash driver instance and returns a handle to it. Implementation: Dynamic DRV_IPF_ProtectMemoryVolatile Protects the memory block to which the given memory address belongs Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 880 DRV_IPF_ReadBlockProtectionStatus Reads the content of Block Protection Register which belongs to In-Package flash. Implementation: Dynamic DRV_IPF_Status Gets the current status of the SPI Flash Driver module. Implementation: Dynamic DRV_IPF_Tasks Maintains the driver's read, erase, and write state machine and implements its ISR. Implementation: Dynamic DRV_IPF_UnProtectMemoryVolatile Un-protects the memory block to which the given memory address belongs Implementation: Dynamic DRV_IPF_WPAssert Asserts the WP pin for flash. Implementation: Dynamic DRV_IPF_WPDeAssert Deasserts the WP pin for flash. Implementation: Dynamic Macros Name Description _DRV_IPF_H This is macro _DRV_IPF_H. DRV_IPF_BLOCK_COMMAND_HANDLE_INVALID This value defines the SPI Flash Driver Block Command Invalid handle. DRV_IPF_INDEX_0 SPI Flash driver index definitions Structures Name Description DRV_IPF_INIT Contains all the data necessary to initialize the SPI Flash device. Implementation: Dynamic Types Name Description DRV_IPF_BLOCK_COMMAND_HANDLE Handle identifying block commands of the driver. DRV_IPF_EVENT_HANDLER Pointer to a IPF SPI Flash Driver Event handler function. Implementation: Dynamic Description SPI Flash Driver Interface Definition The SPI Flash device driver provides a simple interface to manage the SPI Flash modules which are external to Microchip Controllers. This file defines the interface definition for the SPI Flash Driver. File Name drv_IPF.h Company Microchip Technology Inc. drv_ipf_config_template.h IPF Driver Configuration Template. Macros Name Description _DRV_IPF_CONFIG_TEMPLATE_H This is macro _DRV_IPF_CONFIG_TEMPLATE_H. DRV_IPF_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to the hardware instance. DRV_IPF_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported DRV_IPF_MODE Determines whether the driver is implemented as static or dynamic Description IPF Driver Configuration Template These file provides the list of all the configurations that can be used with the driver. This file should not be included in the driver. File Name drv_ipf_config_template.h Volume V: MPLAB Harmony Framework Driver Libraries Help SPI PIC32WK IPF Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 881 Company Microchip Technology Inc. SQI Driver Library Introduction This library provides an interface to manage the Serial Quad Interface (SQI) module on the Microchip family of microcontrollers in different modes of operation. Description The MPLAB Harmony Serial Quad Interface (SQI) Driver provides a high-level interface to the SQI peripherals on Microchip's PIC32 microcontrollers. The SQI Driver includes the following features: • Provides application ready routines to read and write data to an SQI peripheral • Supports Single, Dual, and Quad Lane modes • Supports Single Data Rate (SDR) • Supports Interrupt mode operation only • Supports multi-client operation • Provides data transfer events • Supports non-blocking mode operation only • Features thread-safe functions for use in RTOS applications • Uses the SQI module’s internal DMA Controller for transfers Using the Library This topic describes the basic architecture of the SQI Driver Library and provides information and examples on its use. Description Interface Header File: drv_sqi.h The interface to the SQI Driver Library is defined in the drv_sqi.h header file. Any C language source (.c) file that uses the SQI Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the Driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the SQI Driver Library 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 SQI Driver Library supports up to two Chip Select lines. The following diagram shows the high SQI Driver and the SQI Flash sub-system SQI Abstraction Model Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 882 Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. 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 System Interaction Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks and status functions. Client Setup Functions Provides open, close, status and other setup functions. Data Transfer Functions Provides data transfer functions available in the configuration. How the Library Works The library provides interfaces to support: • System Functionality • Client Functionality Note: Not all modes are available on all devices, please refer to the specific device data sheet to determine the modes that are supported for your device. System Functions Provides information on the system functions provided in the SQI Driver Library. Description SQI Driver Initialization The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization, each instance of the SQI would be initialized with the following configuration settings (either passed dynamically at run time using DRV_SQI_INIT or by using initialization overrides) that are supported by the specific SQI Controller hardware: Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 883 • SQI Peripheral ID - Identifies the SQI Peripheral ID to be used • Interrupt Source - The interrupt source associated with the SQI Controller • Enabled Devices - Number of devices to enable • Device Configuration - This configuration is per enabled device. A maximum of two devices are supported. The following configurations are allowed per device: • Clock Divider Value - Clock divider value to be used • SPI Mode of Operation - SPI mode of operation to be used for this device • LSB First - Send or receive least significant bit of a byte first The DRV_SQI_Initialize function configures and initializes the SQI controller using the configuration information provided. It returns an object handle of the type SYS_MODULE_OBJ. This object handle would be used by other system interfaces such as DRV_SQI_Status, DRV_SQI_Tasks and DRV_SQI_Deinitialize. Example: /* SQI Driver Initialization Data */ const DRV_SQI_INIT drvSqiInit = { .sqiId = SQI_ID_0, .interruptSource = INT_SOURCE_SQI1, .enabledDevices = DRV_SQI_ENABLE_DEVICE_1, .clockDivider = DRV_SQI_CLK_DIV_1, .devCfg[0].spiMode = DRV_SQI_SPI_MODE_0, .devCfg[0].lsbFirst = false, }; /* Initialize the SQI Driver */ sysObj.drvSqi = DRV_SQI_Initialize(DRV_SQI_INDEX_0, (SYS_MODULE_INIT *)&drvSqiInit); SQI Driver Task Routine The SQI driver data transfers are interrupt driven. The data transfer request from the client results in the SQI driver kick starting the transfer if there is no transfer in progress otherwise the request is added to the driver queue. The SQI interrupt handler is responsible for invoking the DRV_SQI_Tasks, which maintains the driver state machine. The task routine checks if the current request is complete and if there is another data transfer request queued, then it kick starts the processing of the request. SQI Driver Status DRV_SQI_Status returns the current status of the SQI driver module and is called by the Harmony System. The application may not find the need to call this function directly. Example: SYS_MODULE_OBJ object; // Returned from DRV_SQI_Initialize SYS_STATUS sqiStatus; sqiStatus = DRV_SQI_Status(object); if (SYS_STATUS_ERROR >= sqiStatus) { // Handle error } Client Core Functions Provides information on the client core functions provided in the SQI Driver Library Description Opening the Driver For the application to start using an instance of the module, it must call the DRV_SQI_Open function repeatedly until a valid handle is returned by the driver. This provides the configuration required to open the SQI instance for operation. For the various options available for I/O INTENT please refer to "Data Types and Constants" in the Library Interface section. Example: sqiHandle = DRV_SQI_Open (0, DRV_IO_INTENT_READWRITE); if (sqiHandle != DRV_HANDLE_INVALID) { /* Do further processing. */ } else { Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 884 /* Call until the function returns a valid handle. */ } Closing the Driver Closes an opened-instance of the SQI driver Example: DRV_HANDLE handle; // Returned from DRV_SQI_Open DRV_SQI_Close(handle); Client Data Transfer Functions Provides information on the client data transfer functions provided in the SQI Driver Library. Description Client data transfer functionality provides API interfaces for the data transfer operation. The following diagram illustrates the data transfer model. Applications need to perform the following steps to transfer data using the SQI Driver: 1. The system should have completed necessary initialization and the DRV_SQI_Tasks should be running in an interrupt environment. 2. Open_the driver using DRV_SQI_Open with the necessary intent. The application should wait call the DRV_SQI_Open until the function returns a valid open handle. 3. Register callback function using the DRV_SQI_EventHandlerSet. 4. Add a transfer request using the buffer using the DRV_SQI_TransferData function. The reads or writes of blocks of data generally involves sending down the read or a write command, the address on the device from/to which data is to be read/written. The client also has to specify the source or destination buffer and the number of bytes to be read or written. The client builds an array of transfer elements containing this information and passes the array and the number of elements of the array as part of this transfer request. 5. Check for the current transfer status using DRV_SQI_CommandStatus until the transfer progress is DRV_SQI_COMMAND_COMPLETED, or wait for the callback to be called. 6. When the client has no more data to be transferred, the client can close the driver using DRV_SQI_Close. Example: Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 885 #define READ_BUF_SIZE 512 uint8_t readBuffer[READ_BUF_SIZE] __attribute__((coherent, aligned(16))); uint8_t command [5] __attribute__((coherent, aligned(16)) = {0x0B, 0x00, 0x00, 0x00, 0x0FF}; uint8_t numElements = 0; DRV_SQI_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; DRV_SQI_TRANSFER_ELEMENT xferData[2]; // mySQIHandle is the handle returned by the DRV_SQI_Open function. // Setup the transfer elements. xferData[0].data = &command[0]; xferData[0].length = sizeof(command); xferData[0].flag = (DRV_SQI_FLAG_MODE_SINGLE_LANE); xferData[1].data = readBuffer; xferData[1].length = READ_BUF_SIZE; xferData[1].flag = (DRV_SQI_FLAG_MODE_QUAD_LANE | DRV_SQI_FLAG_DIR_READ | DRV_SQI_FLAG_DEASSERT_CS); DRV_SQI_TransferData(mySQIHandle, &commandHandle, 0, xferData, 2); if(DRV_SQI_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } else { // Transfer operation queued successfully. Wait for the // completion event. } // Transfer completion can be tracked either by polling on the commandHandle or waiting // for the event using the event callback function. status = DRV_SQI_CommandStatus(mySQIHandle, commandHandle); if(status == DRV_SQI_COMMAND_COMPLETED) { // Operation Done } // Event handler. void APP_SQIEventHandler ( DRV_SQI_EVENT event, DRV_SQI_COMMAND_HANDLE handle, uintptr_t context ) { // The context handle was set to an application specific // object. It is now retrievable easily in the event // handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) context; switch(event) { case DRV_SQI_EVENT_COMMAND_COMPLETE: // This means the operation was completed // successfully. break; case DRV_SQI_EVENT_COMMAND_ERROR: // Operation failed. Handle the error. break; default: break; } } Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 886 Configuring the Library Macros Name Description DRV_SQI_BUFFER_OBJECT_NUMBER Selects the maximum number of buffer objects DRV_SQI_CLIENTS_NUMBER Selects the maximum number of clients DRV_SQI_DMA_BUFFER_DESCRIPTORS_NUMBER Selects the maximum number of DMA Buffer descriptors to be used by the driver. DRV_SQI_INSTANCES_NUMBER Selects the maximum number of Driver instances that can be supported by the dynamic driver. DRV_SQI_INTERRUPT_MODE Macro specifies operation of the driver to be in the interrupt mode or polled mode Description The configuration of the SQI driver is based on the file system_config.h. This header file contains the configuration selection for the SQI driver. Based on the selections made, the SQI driver may support the selected features. These configuration settings will apply to all instances of the SQI driver. This header can be placed anywhere, 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. DRV_SQI_BUFFER_OBJECT_NUMBER Macro Selects the maximum number of buffer objects File drv_sqi_config_template.h C #define DRV_SQI_BUFFER_OBJECT_NUMBER 5 Description SQI Driver maximum number of buffer objects This definition selects the maximum number of buffer objects. This indirectly also specifies the queue depth. The SQI Driver can queue up DRV_SQI_BUFFER_OBJECT_NUMBER of read/write/erase requests before return a DRV_SQI_BUFFER_HANDLE_INVALID due to the queue being full. Buffer objects are shared by all instances of the driver. Increasing this number increases the RAM requirement of the driver. Remarks This macro is mandatory when building the driver for dynamic operation. DRV_SQI_CLIENTS_NUMBER Macro Selects the maximum number of clients File drv_sqi_config_template.h C #define DRV_SQI_CLIENTS_NUMBER 1 Description SQI maximum number of clients This definition selects the maximum number of clients that the SQI driver can supported at run time. This constant defines the total number of SQI driver clients that will be available to all instances of the SQI driver. Remarks This macro is mandatory when building the driver for dynamic operation. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 887 DRV_SQI_DMA_BUFFER_DESCRIPTORS_NUMBER Macro Selects the maximum number of DMA Buffer descriptors to be used by the driver. File drv_sqi_config_template.h C #define DRV_SQI_DMA_BUFFER_DESCRIPTORS_NUMBER 4 Description SQI Driver maximum number DMA Buffer Descriptors This definition selects the maximum number of DMA buffer descriptor objects. The SQI Driver can queue up to DRV_SQI_DMA_BUFFER_DESCRIPTORS_NUMBER of transactions to be processed by the hardware. DMA buffer desired are shared by all instances of the driver. Increasing this number increases the RAM requirement of the driver. Remarks This macro is mandatory when building the driver for dynamic operation. DRV_SQI_INSTANCES_NUMBER Macro Selects the maximum number of Driver instances that can be supported by the dynamic driver. File drv_sqi_config_template.h C #define DRV_SQI_INSTANCES_NUMBER 1 Description SQI Driver instance configuration This definition selects the maximum number of Driver instances that can be supported by the dynamic driver. In case of this driver, multiple instances of the driver could use the same hardware instance. Remarks This macro is mandatory when building the driver for dynamic operation. DRV_SQI_INTERRUPT_MODE Macro Macro specifies operation of the driver to be in the interrupt mode or polled mode File drv_sqi_config_template.h C #define DRV_SQI_INTERRUPT_MODE true Description SQI interrupt and polled mode operation control This macro specifies operation of the driver to be in the interrupt mode or polled mode • true - Select if interrupt mode of SQI operation is desired • false - Select if polling mode of SQI operation is desired Not defining this option to true or false will result in build error. Remarks This macro is mandatory when building the driver for dynamic operation. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 888 Building the Library This section lists the files that are available in the SQI Driver Library. Description This section list the files that are available in the \src folder of the SQI 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. 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 /framework/driver/sqi. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_sqi.h Header file that exports the driver API. 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 /src/dynamic/drv_sqi.c This file contains the source code for the dynamic implementation of the SQI driver. 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 N/A No optional files are available for this library Module Dependencies The SQI Driver Library depends on the following modules: • Clock System Service Library Optional Dependencies • Interrupt System Service Library (used when task is running in Interrupt mode) Library Interface a) System Interaction Functions Name Description DRV_SQI_Initialize Initializes the SQI instance for the specified driver index DRV_SQI_Deinitialize Deinitializes the specified instance of the SQI driver module DRV_SQI_Status Gets the current status of the SQI driver module. DRV_SQI_Tasks Maintains the driver's task state machine. b) Client Setup Functions Name Description DRV_SQI_Open Opens the specified SQI driver instance and returns a handle to it. DRV_SQI_Close Closes an opened-instance of the SQI driver DRV_SQI_CommandStatus Gets the current status of the transfer request. DRV_SQI_EventHandlerSet Allows a client to register an event handling function, which the driver can invoke when the queued transfer request has completed. c) Data Transfer Functions Name Description DRV_SQI_TransferData Queue a data transfer operation on the specified SQI device. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 889 DRV_SQI_TransferFrames Queue a transfer request operation on the SQI device. d) Data Types and Constants Name Description DRV_SQI_COMMAND_HANDLE Handle to identify the transfer request queued at the SQI driver. DRV_SQI_COMMAND_STATUS Specifies the status of the transfer request. DRV_SQI_EVENT Identifies the possible events that can result from a transfer request. DRV_SQI_EVENT_HANDLER Pointer to a SQI Driver Event handler function DRV_SQI_SPI_OPERATION_MODE Enumeration of the SPI mode of operation supported by the SQI Controller. DRV_SQI_TRANSFER_FLAGS Enumeration of the configuration options associated with a single transfer element. DRV_SQI_TransferElement Defines the data transfer element of the SQI driver. DRV_SQI_COMMAND_HANDLE_INVALID Identifies an invalid command handle. DRV_SQI_INDEX_0 SQI driver index definitions. DRV_SQI_FLAG_32_BIT_ADDR_ENABLE This is macro DRV_SQI_FLAG_32_BIT_ADDR_ENABLE. DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_MASK This is macro DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_MASK. DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_POS Enables 32-bit addressing instead of 24-bit addressing. DRV_SQI_FLAG_ADDR_ENABLE This is macro DRV_SQI_FLAG_ADDR_ENABLE. DRV_SQI_FLAG_ADDR_ENABLE_MASK This is macro DRV_SQI_FLAG_ADDR_ENABLE_MASK. DRV_SQI_FLAG_ADDR_ENABLE_POS Address Enable Macro. DRV_SQI_FLAG_CRM_ENABLE This is macro DRV_SQI_FLAG_CRM_ENABLE. DRV_SQI_FLAG_CRM_ENABLE_MASK This is macro DRV_SQI_FLAG_CRM_ENABLE_MASK. DRV_SQI_FLAG_CRM_ENABLE_POS Continuous Read Mode Enable Macro. DRV_SQI_FLAG_DATA_DIRECTION_MASK This is macro DRV_SQI_FLAG_DATA_DIRECTION_MASK. DRV_SQI_FLAG_DATA_DIRECTION_POS Macros to select the direction of the transfers. DRV_SQI_FLAG_DATA_DIRECTION_READ This is macro DRV_SQI_FLAG_DATA_DIRECTION_READ. DRV_SQI_FLAG_DATA_DIRECTION_WRITE This is macro DRV_SQI_FLAG_DATA_DIRECTION_WRITE. DRV_SQI_FLAG_DATA_ENABLE This is macro DRV_SQI_FLAG_DATA_ENABLE. DRV_SQI_FLAG_DATA_ENABLE_MASK This is macro DRV_SQI_FLAG_DATA_ENABLE_MASK. DRV_SQI_FLAG_DATA_ENABLE_POS Data Enable Macro. DRV_SQI_FLAG_DATA_TARGET_MASK This is macro DRV_SQI_FLAG_DATA_TARGET_MASK. DRV_SQI_FLAG_DATA_TARGET_MEMORY This is macro DRV_SQI_FLAG_DATA_TARGET_MEMORY. DRV_SQI_FLAG_DATA_TARGET_POS Macros to select the source and destination of a transfer. DRV_SQI_FLAG_DATA_TARGET_REGISTER This is macro DRV_SQI_FLAG_DATA_TARGET_REGISTER. DRV_SQI_FLAG_DDR_ENABLE This is macro DRV_SQI_FLAG_DDR_ENABLE. DRV_SQI_FLAG_DDR_ENABLE_MASK This is macro DRV_SQI_FLAG_DDR_ENABLE_MASK. DRV_SQI_FLAG_DDR_ENABLE_POS DDR Enable Macro. DRV_SQI_FLAG_INSTR_ENABLE This is macro DRV_SQI_FLAG_INSTR_ENABLE. DRV_SQI_FLAG_INSTR_ENABLE_MASK This is macro DRV_SQI_FLAG_INSTR_ENABLE_MASK. DRV_SQI_FLAG_INSTR_ENABLE_POS Macros listing the bitmap values for the flags member of the DRV_SQI_TransferFrame structure. Instruction Enable Macro. DRV_SQI_FLAG_OPT_ENABLE This is macro DRV_SQI_FLAG_OPT_ENABLE. DRV_SQI_FLAG_OPT_ENABLE_MASK This is macro DRV_SQI_FLAG_OPT_ENABLE_MASK. DRV_SQI_FLAG_OPT_ENABLE_POS Option Enable Macro. DRV_SQI_FLAG_OPT_LENGTH This is macro DRV_SQI_FLAG_OPT_LENGTH. DRV_SQI_FLAG_OPT_LENGTH_1BIT This is macro DRV_SQI_FLAG_OPT_LENGTH_1BIT. DRV_SQI_FLAG_OPT_LENGTH_2BIT This is macro DRV_SQI_FLAG_OPT_LENGTH_2BIT. DRV_SQI_FLAG_OPT_LENGTH_4BIT This is macro DRV_SQI_FLAG_OPT_LENGTH_4BIT. DRV_SQI_FLAG_OPT_LENGTH_8BIT This is macro DRV_SQI_FLAG_OPT_LENGTH_8BIT. DRV_SQI_FLAG_OPT_LENGTH_MASK This is macro DRV_SQI_FLAG_OPT_LENGTH_MASK. DRV_SQI_FLAG_OPT_LENGTH_POS Macros to enable and specify the option length. DRV_SQI_FLAG_SQI_CS_NUMBER This is macro DRV_SQI_FLAG_SQI_CS_NUMBER. DRV_SQI_FLAG_SQI_CS_NUMBER_0 This is macro DRV_SQI_FLAG_SQI_CS_NUMBER_0. DRV_SQI_FLAG_SQI_CS_NUMBER_1 This is macro DRV_SQI_FLAG_SQI_CS_NUMBER_1. DRV_SQI_FLAG_SQI_CS_NUMBER_2 This is macro DRV_SQI_FLAG_SQI_CS_NUMBER_2. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 890 DRV_SQI_FLAG_SQI_CS_NUMBER_3 This is macro DRV_SQI_FLAG_SQI_CS_NUMBER_3. DRV_SQI_FLAG_SQI_CS_NUMBER_MASK This is macro DRV_SQI_FLAG_SQI_CS_NUMBER_MASK. DRV_SQI_FLAG_SQI_CS_NUMBER_POS Macros to select the SQI CS Line Number to be used for the current transfer • frame. DRV_SQI_LANE_CONFIG Defines the SQI lane configuration options. DRV_SQI_TransferFrame Defines the transfer frame of the SQI driver. Description This section describes the API functions of the SQI Driver Library. Refer to each section for a detailed description. a) System Interaction Functions DRV_SQI_Initialize Function Initializes the SQI instance for the specified driver index File drv_sqi.h C SYS_MODULE_OBJ DRV_SQI_Initialize(const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT *const init); Returns Returns a valid handle to a driver instance object on success. Otherwise returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the SQI driver instance for the specified driver index, making it ready for clients to open and use it. Remarks This routine must be called before any other SQI routines are called. This routine should only be called once during system initialization unless DRV_SQI_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. If the operation requires time to allow the hardware to initialize, it will be reported by the DRV_SQI_Status operation. The system must use DRV_SQI_Status to find out when the driver is in the ready state. Preconditions None. Example // This code snippet shows an example of initializing the SQI Driver. SYS_MODULE_OBJ objectHandle; TODO:Replace with appropriate init snippet. // SQI Driver Initialization Data const DRV_SQI_INIT drvSqiInit = { .sqiId = SQI_ID_0, .interruptSource = INT_SOURCE_SQI1, .enabledDevices = DRV_SQI_ENABLE_BOTH_DEVICES, .clockDivider = DRV_SQI_CLK_DIV_1, .devCfg[0].spiMode = DRV_SQI_SPI_MODE_0, .devCfg[0].lsbFirst = true, .devCfg[1].spiMode = DRV_SQI_SPI_MODE_3, .devCfg[1].lsbFirst = false, }; objectHandle = DRV_SQI_Initialize(DRV_SQI_INDEX_0, (SYS_MODULE_INIT*)&drvSqiInit); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 891 Parameters Parameters Description index Identifier for the instance to be initialized. init Pointer to a data structure containing any data necessary to initialize the driver. Function SYS_MODULE_OBJ DRV_SQI_Initialize ( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); DRV_SQI_Deinitialize Function Deinitializes the specified instance of the SQI driver module File drv_sqi.h C void DRV_SQI_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the SQI driver module, disabling its operation (and any hardware). Invalidates all the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. Preconditions Function DRV_SQI_Initialize should have been called before calling this function. Parameter: object - Driver object handle, returned from the DRV_SQI_Initialize routine Example // This code snippet shows an example of deinitializing the driver. SYS_MODULE_OBJ object; // Returned from DRV_SQI_Initialize SYS_STATUS status; DRV_SQI_Deinitialize(object); status = DRV_SQI_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later to know if the driver is deinitialized. } Function void DRV_SQI_Deinitialize ( SYS_MODULE_OBJ object ); DRV_SQI_Status Function Gets the current status of the SQI driver module. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 892 File drv_sqi.h C SYS_STATUS DRV_SQI_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is ready and can accept transfer requests. SYS_STATUS_UNINITIALIZED - Indicates the driver is not initialized. Description This routine provides the current status of the SQI driver module. Remarks This routine will NEVER block waiting for hardware. Preconditions Function DRV_SQI_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_SQI_Initialize SYS_STATUS sqiStatus; sqiStatus = DRV_SQI_Status(object); else if (SYS_STATUS_ERROR >= sqiStatus) { // Handle error } Parameters Parameters Description object Driver object handle, returned from the DRV_SQI_Initialize routine Function SYS_STATUS DRV_SQI_Status ( SYS_MODULE_OBJ object ); DRV_SQI_Tasks Function Maintains the driver's task state machine. File drv_sqi.h C void DRV_SQI_Tasks(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal task state machine. Remarks This routine may either be called by the system's task routine(SYS_Tasks) or the from the interrupt service routine of the peripheral. Preconditions The DRV_SQI_Initialize routine must have been called for the specified SQI driver instance. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 893 Example SYS_MODULE_OBJ object; // Returned from DRV_SQI_Initialize while (true) { DRV_SQI_Tasks (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_SQI_Initialize) Function void DRV_SQI_Tasks ( SYS_MODULE_OBJ object ); b) Client Setup Functions DRV_SQI_Open Function Opens the specified SQI driver instance and returns a handle to it. File drv_sqi.h C DRV_HANDLE DRV_SQI_Open(const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, DRV_HANDLE_INVALID is returned. Errors can occur under the following circumstances: • if the number of client objects allocated via DRV_SQI_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the client is trying to open the driver exclusively, but has already been opened in a non exclusive mode by another client. • if the driver hardware instance being opened is not initialized or is invalid Description This routine opens the specified SQI driver instance and provides a handle identifying the SQI driver instance. This handle must be provided to all other client-level operations to identify the caller and the instance of the driver. Remarks The handle returned is valid until the DRV_SQI_Close routine is called. This routine will NEVER block waiting for hardware. If the driver has has already been opened, it cannot be opened exclusively. Preconditions Function DRV_SQI_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_SQI_Open(DRV_SQI_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 894 Parameters Parameters Description index Identifier for the object instance to be opened. intent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver. Function DRV_HANDLE DRV_SQI_Open ( const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent ); DRV_SQI_Close Function Closes an opened-instance of the SQI driver File drv_sqi.h C void DRV_SQI_Close(const DRV_HANDLE handle); Returns None Description This routine closes an opened-instance of the SQI driver, invalidating the handle. Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_SQI_Open before the caller may use the driver again. Usually there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_SQI_Initialize routine must have been called for the specified SQI driver instance. DRV_SQI_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SQI_Open DRV_SQI_Close(handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_SQI_Close ( const DRV_HANDLE handle ); DRV_SQI_CommandStatus Function Gets the current status of the transfer request. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 895 File drv_sqi.h C DRV_SQI_COMMAND_STATUS DRV_SQI_CommandStatus(const DRV_HANDLE handle, const DRV_SQI_COMMAND_HANDLE commandHandle); Returns A DRV_SQI_COMMAND_STATUS value describing the current status of the transfer request. Returns DRV_SQI_COMMAND_ERROR_UNKNOWN if the client handle or the handle is not valid. Description This routine gets the current status of the tranfer request. The application must use this routine where the status of a scheduled transfer request needs to polled on. The function may return DRV_SQI_COMMAND_COMPLETED in a case where the handle has expired. A handle expires when the internal buffer object is re-assigned to another transfer request. It is recommended that this function be called regularly in order to track the status of the transfer request correctly. The application can alternatively register an event handler to receive the transfer completion events. Remarks This routine will not block for hardware access and will immediately return the current status of the transfer request. Preconditions The DRV_SQI_Initialize() routine must have been called. The DRV_SQI_Open() must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SQI_Open DRV_SQI_COMMAND_HANDLE commandHandle; DRV_SQI_COMMAND_STATUS status; status = DRV_SQI_CommandStatus(handle, commandHandle); if(status == DRV_SQI_COMMAND_COMPLETED) { // Operation Done } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function DRV_SQI_COMMAND_STATUS DRV_SQI_CommandStatus ( const DRV_HANDLE handle, const DRV_SQI_COMMAND_HANDLE commandHandle ); DRV_SQI_EventHandlerSet Function Allows a client to register an event handling function, which the driver can invoke when the queued transfer request has completed. File drv_sqi.h C void DRV_SQI_EventHandlerSet(const DRV_HANDLE handle, const void * eventHandler, const uintptr_t context); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 896 Description This function allows a client to identify an event handling function for the driver to call back when queued operation has completed. When a client queues a transfer request with the driver, it is provided with a handle identifying the transfer request that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the queued operation has completed. The event handler should be set before the client performs any transfer operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued operation has completed, it does not need to register a callback. Preconditions The DRV_SQI_Initialize() routine must have been called for the specified SQI driver instance. The DRV_SQI_Open() routine must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; DRV_SQI_TransferFrame xferFrame; DRV_SQI_COMMAND_HANDLE commandHandle; // drvSQIHandle is the handle returned by the DRV_SQI_Open function. // Client registers an event handler with driver. This is done once. DRV_SQI_EventHandlerSet(drvSQIHandle, APP_SQIEventHandler, (uintptr_t)&myAppObj); DRV_SQI_Read(drvSQIHandle, &commandHandle, &xferFrame, 1); if(DRV_SQI_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event handler. void APP_SQIEventHandler ( DRV_SQI_EVENT event, DRV_SQI_COMMAND_HANDLE handle, uintptr_t context ) { // The context handle was set to an application specific object. It is // now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) context; switch(event) { case DRV_SQI_EVENT_COMMAND_COMPLETE: // This means the operation was completed successfully. break; case DRV_SQI_EVENT_COMMAND_ERROR: // Operation failed. Handle the error. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function eventHandler Pointer to the event handler function implemented by the user Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 897 context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_SQI_EventHandlerSet ( const DRV_HANDLE handle, const void *eventHandler, const uintptr_t context ); c) Data Transfer Functions DRV_SQI_TransferData Function Queue a data transfer operation on the specified SQI device. File drv_sqi.h C void DRV_SQI_TransferData(DRV_HANDLE handle, DRV_SQI_COMMAND_HANDLE * commandHandle, uint8_t sqiDevice, DRV_SQI_TransferElement * xferData, uint8_t numElements); Returns The handle to the command request is returned in the commandHandle argument. It will be DRV_SQI_COMMAND_HANDLE_INVALID if the request was not successful. Description This routine queues a data transfer operation on the specified SQI device. The reads or writes of blocks of data generally involves sending down the read or a write command, the address on the device from/to which data is to be read/written. The client also has to specify the source or destination buffer and the number of bytes to be read or written. The client builds an array of transfer elements containing these information and passes the array and the number of elements of the array as part of this transfer operation. If an event handler is registered with the driver the event handler would be invoked with the status of the operation once the operation has been completed. The function returns DRV_SQI_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if the driver handle is invalid • if the transfer element is NULL or number of transfer elements is zero • if a buffer object could not be allocated to the request Remarks None. Preconditions The DRV_SQI_Initialize routine must have been called for the specified SQI driver instance. DRV_SQI_Open must have been called with DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE as the ioIntent to obtain a valid opened device handle. Example #define READ_BUF_SIZE 512 uint8_t readBuffer[READ_BUF_SIZE] __attribute__((coherent, aligned(16))); uint8_t command [5] __attribute__((coherent, aligned(16)) = {0x0B, 0x00, 0x00, 0x00, 0x0FF}; uint8_t numElements = 0; DRV_SQI_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; DRV_SQI_TransferElement xferData[2]; // mySQIHandle is the handle returned by the DRV_SQI_Open function. // Setup the transfer elements. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 898 xferData[0].data = &command[0]; xferData[0].length = sizeof(command); xferData[0].flag = (DRV_SQI_FLAG_MODE_SINGLE_LANE); xferData[1].data = readBuffer; xferData[1].length = READ_BUF_SIZE; xferData[1].flag = (DRV_SQI_FLAG_MODE_QUAD_LANE | DRV_SQI_FLAG_DIR_READ | DRV_SQI_FLAG_DEASSERT_CS); DRV_SQI_TransferData(mySQIHandle, &commandHandle, 0, xferData, 2); if(DRV_SQI_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } else { // Transfer operation queued successfully. Wait for the completion event. } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle sqiDevice The SQI device index on which the operation is to be performed. xferData Pointer to the transfer elements array. numElements Number of elements in the transfer elements array. Function void DRV_SQI_TransferData ( DRV_HANDLE handle, DRV_SQI_COMMAND_HANDLE *commandHandle, uint8_t sqiDevice, DRV_SQI_TransferElement *xferData, uint8_t numElements ); DRV_SQI_TransferFrames Function Queue a transfer request operation on the SQI device. File drv_sqi.h C void DRV_SQI_TransferFrames(DRV_HANDLE handle, DRV_SQI_COMMAND_HANDLE * commandHandle, DRV_SQI_TransferFrame * frame, uint8_t numFrames); Returns The handle to the transfer request is returned in the commandHandle argument. It will be DRV_SQI_COMMAND_HANDLE_INVALID if the request was not successful. Description This routine queues a transfer request operation on the SQI device. In order to perform any operation on the sqi flash device, a one byte instruction specifying the operation to be performed needs to be sent out. This is followed by optional address from/to which data is to be read/written, option, dummy and data bytes. If an event handler is registered with the driver the event handler would be invoked with the status of the operation once the operation has been completed. The function returns DRV_SQI_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if the driver handle is invalid • if the transfer element is NULL or number of transfer elements is zero • if a buffer object could not be allocated to the request Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 899 Remarks None. Preconditions The DRV_SQI_Initialize routine must have been called for the specified SQI driver instance. DRV_SQI_Open must have been called with DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE as the ioIntent to obtain a valid opened device handle. Example #define READ_BUF_SIZE 512 uint8_t readBuffer[READ_BUF_SIZE]; uint8_t numElements = 0; DRV_SQI_COMMAND_HANDLE cmdHandle; DRV_SQI_TransferFrame xferFrame; DRV_SQI_TransferFrame *frame = &xferFrame; frame->instruction = 0x6B; frame->address = 0x00; frame->data = readBuffer; frame->length = READ_BUF_SIZE; frame->laneCfg = DRV_SQI_LANE_QUAD_DATA; frame->numDummyBytes = 8; frame->flags = (DRV_SQI_FLAG_INSTR_ENABLE_MASK | DRV_SQI_FLAG_DATA_ENABLE_MASK | DRV_SQI_FLAG_ADDR_ENABLE_MASK | DRV_SQI_FLAG_DATA_TARGET_MEMORY | DRV_SQI_FLAG_DATA_DIRECTION_READ); DRV_SQI_TransferFrames (sqiHandle, &cmdHandle, frame, 1); if (cmdHandle == DRV_SQI_COMMAND_HANDLE_INVALID) { // handle the failure. } else { // continue with the rest of the operation. } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the handle to the track the status of the transfer request. frame Pointer to the transfer frame array. numFrames Number of elements in the transfer frame array. Function void DRV_SQI_TransferFrames ( DRV_HANDLE handle, DRV_SQI_COMMAND_HANDLE *commandHandle, DRV_SQI_TransferFrame *frame, uint8_t numFrames ); d) Data Types and Constants DRV_SQI_COMMAND_HANDLE Type Handle to identify the transfer request queued at the SQI driver. File drv_sqi.h Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 900 C typedef uintptr_t DRV_SQI_COMMAND_HANDLE; Description SQI Driver Command Handle A command handle is returned by a call to the DRV_SQI_TransferFrames () function. This handle allows the application to track the completion of the request. This command handle is also returned to the client along with the event that has occurred with respect to the request. This allows the application to connect the event to a specific transfer request in case where multiple requests are queued. The command handle associated with the transfer request expires when the client has been notified of the completion of the request (after event handler function that notifies the client returns) or after the request has been retired by the driver if no event handler callback was set. Remarks None. DRV_SQI_COMMAND_STATUS Enumeration Specifies the status of the transfer request. File drv_sqi.h C typedef enum { DRV_SQI_COMMAND_COMPLETED, DRV_SQI_COMMAND_QUEUED, DRV_SQI_COMMAND_IN_PROGRESS, DRV_SQI_COMMAND_ERROR_UNKNOWN } DRV_SQI_COMMAND_STATUS; Members Members Description DRV_SQI_COMMAND_COMPLETED Command completed. DRV_SQI_COMMAND_QUEUED Command is pending. DRV_SQI_COMMAND_IN_PROGRESS Command is being processed DRV_SQI_COMMAND_ERROR_UNKNOWN There was an error while processing the command. Description SQI Driver Command Status This enumeration identifies the possible status values associated with a transfer request. The client can retrieve the status by calling the DRV_SQI_CommandStatus () function and passing the command handle associated with the request. Remarks None. DRV_SQI_EVENT Enumeration Identifies the possible events that can result from a transfer request. File drv_sqi.h C typedef enum { DRV_SQI_EVENT_COMMAND_COMPLETE = 0, DRV_SQI_EVENT_COMMAND_ERROR } DRV_SQI_EVENT; Members Members Description DRV_SQI_EVENT_COMMAND_COMPLETE = 0 Operation has been completed successfully. DRV_SQI_EVENT_COMMAND_ERROR There was an error during the operation Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 901 Description SQI Driver Events This enumeration identifies the possible events that can result from a transfer request issued by the client. Remarks One of these values is passed in the "event" parameter of the event handling callback function that client registered with the driver by calling the DRV_SQI_EventHandlerSet function when a request is completed. DRV_SQI_EVENT_HANDLER Type Pointer to a SQI Driver Event handler function File drv_sqi.h C typedef void (* DRV_SQI_EVENT_HANDLER)(DRV_SQI_EVENT event, DRV_SQI_COMMAND_HANDLE commandHandle, void *context); Returns None. Description SQI Driver Event Handler Function Pointer data type. This data type defines the required function signature for the SQI driver event handling callback function. A client must register a pointer to a event handling function the signature(parameter and return value types) of which should match the types specified by this function pointer in order to receive transfer request related event call backs from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks If the event is DRV_SQI_EVENT_COMMAND_COMPLETE, that the operation associated with the transfer request was completed successfully. If the event is DRV_SQI_EVENT_COMMAND_ERROR, there was an error while executing the transfer request. The context parameter contains context details provided by the client as part of registering the event handler function. This context value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) of the client that made the request. Example void MyAppCommandEventHandler ( DRV_SQI_EVENT event, DRV_SQI_COMMAND_HANDLE commandHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT)context; switch(event) { case DRV_SQI_EVENT_COMMAND_COMPLETE: // Handle the completed transfer request. break; case DRV_SQI_EVENT_COMMAND_ERROR: default: // Handle the failed transfer request. break; } } Parameters Parameters Description event Identifies the type of event commandHandle Handle identifying the transfer request to which this event relates Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 902 context Value identifying the context of the application that registered the event handling function. DRV_SQI_SPI_OPERATION_MODE Enumeration Enumeration of the SPI mode of operation supported by the SQI Controller. File drv_sqi.h C typedef enum { DRV_SQI_SPI_MODE_0 = 0, DRV_SQI_SPI_MODE_3 = 3 } DRV_SQI_SPI_OPERATION_MODE; Members Members Description DRV_SQI_SPI_MODE_0 = 0 CPOL = 0 and CPHA = 0. SCK Idle state = LOW DRV_SQI_SPI_MODE_3 = 3 CPOL = 1 and CPHA = 1. SCK Idle state = HIGH Description SQI SPI Mode of operation This enumeration lists the SPI mode of operation supported by the SQI controller. In MODE 0 of operation: CPOL = 0 and CPHA = 0. SCK Idle state = LOW In MODE 3 of operation: CPOL = 1 and CPHA = 1. SCK Idle state = HIGH In both MODE 0 and MODE 3 of operation the: SQI Data Input is sampled on the rising edge of the SQI Clock SQI Data is Output on the falling edge of the SQI Clock Remarks None DRV_SQI_TRANSFER_FLAGS Enumeration Enumeration of the configuration options associated with a single transfer element. File drv_sqi.h C typedef enum { DRV_SQI_FLAG_MODE_SINGLE_LANE = 0x00, DRV_SQI_FLAG_MODE_DUAL_LANE = 0x01, DRV_SQI_FLAG_MODE_QUAD_LANE = 0x02, DRV_SQI_FLAG_DDR_MODE = 0x04, DRV_SQI_FLAG_DEASSERT_CS = 0x08, DRV_SQI_FLAG_DIR_READ = 0x80 } DRV_SQI_TRANSFER_FLAGS; Members Members Description DRV_SQI_FLAG_MODE_SINGLE_LANE = 0x00 Bits 0-1: Indicates the Lane configuration to be used. DRV_SQI_FLAG_DDR_MODE = 0x04 Bit 2: This bit indicates if DDR or SDR mode of operation is to be used. DRV_SQI_FLAG_DEASSERT_CS = 0x08 Bit 3: This bit indicates if CS is to be de-asserted at the end of this • transaction. DRV_SQI_FLAG_DIR_READ = 0x80 Bit 7: This bit indicates if the operation is a read or a write. Description Flags associated with the SQI Driver Transfer element. This enumeration lists the various configuration options associated with a single transfer element(Refer to the data structure DRV_SQI_TransferElement). The client can specify one or more of these as configuration parameters of a single transfer element. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 903 Remarks None DRV_SQI_TransferElement Structure Defines the data transfer element of the SQI driver. File drv_sqi.h C typedef struct { uint8_t * data; uint32_t length; uint8_t flag; } DRV_SQI_TransferElement; Members Members Description uint8_t * data; Pointer to the source or destination buffer uint32_t length; Length of the buffer in bytes. uint8_t flag; This is a bitmap used to indicate the configuration options to be used • for this transfer element. One or more values of the enumeration • DRV_SQI_TRANSFER_FLAGS can be passed as part of this flag. Description SQI Driver data transfer element. This data type defines the composition of a single transfer element. A single element will consist of the pointer to the source of destination buffer, length of the data to be transferred or received and the various configuration options to be used for the element. The configuration options also indicate if data is transferred to/from the device. A client builds an array of such transfer elements and passes the array and the number of elements of the array as part of the read or write operation. Remarks None. DRV_SQI_COMMAND_HANDLE_INVALID Macro Identifies an invalid command handle. File drv_sqi.h C #define DRV_SQI_COMMAND_HANDLE_INVALID ((DRV_SQI_COMMAND_HANDLE)(-1)) Description SQI Driver Invalid Command Handle This is the definition of an invalid command handle. An invalid command handle is returned by DRV_SQI_TransferFrames() function if the transfer request was not queued. Remarks None. DRV_SQI_INDEX_0 Macro SQI driver index definitions. File drv_sqi.h Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 904 C #define DRV_SQI_INDEX_0 0 Description SQI Driver Module Index Numbers This constant provides the SQI driver index definition. Remarks This constant should be used in place of hard-coded numeric literal. This value should be passed into the DRV_SQI_Initialize and DRV_SQI_Open functions to identify the driver instance in use. DRV_SQI_FLAG_32_BIT_ADDR_ENABLE Macro File drv_sqi.h C #define DRV_SQI_FLAG_32_BIT_ADDR_ENABLE(value) (DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_MASK & ((value) << DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_POS)) Description This is macro DRV_SQI_FLAG_32_BIT_ADDR_ENABLE. DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_MASK Macro File drv_sqi.h C #define DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_MASK (0x1U << DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_POS) Description This is macro DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_MASK. DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_POS Macro File drv_sqi.h C #define DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_POS (6) Description Enables 32-bit addressing instead of 24-bit addressing. DRV_SQI_FLAG_ADDR_ENABLE Macro File drv_sqi.h C #define DRV_SQI_FLAG_ADDR_ENABLE(value) (DRV_SQI_FLAG_ADDR_ENABLE_MASK & ((value) << DRV_SQI_FLAG_ADDR_ENABLE_POS)) Description This is macro DRV_SQI_FLAG_ADDR_ENABLE. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 905 DRV_SQI_FLAG_ADDR_ENABLE_MASK Macro File drv_sqi.h C #define DRV_SQI_FLAG_ADDR_ENABLE_MASK (0x1U << DRV_SQI_FLAG_ADDR_ENABLE_POS) Description This is macro DRV_SQI_FLAG_ADDR_ENABLE_MASK. DRV_SQI_FLAG_ADDR_ENABLE_POS Macro File drv_sqi.h C #define DRV_SQI_FLAG_ADDR_ENABLE_POS (1) Description Address Enable Macro. DRV_SQI_FLAG_CRM_ENABLE Macro File drv_sqi.h C #define DRV_SQI_FLAG_CRM_ENABLE(value) (DRV_SQI_FLAG_CRM_ENABLE_MASK & ((value) << DRV_SQI_FLAG_CRM_ENABLE_POS)) Description This is macro DRV_SQI_FLAG_CRM_ENABLE. DRV_SQI_FLAG_CRM_ENABLE_MASK Macro File drv_sqi.h C #define DRV_SQI_FLAG_CRM_ENABLE_MASK (0x1U << DRV_SQI_FLAG_CRM_ENABLE_POS) Description This is macro DRV_SQI_FLAG_CRM_ENABLE_MASK. DRV_SQI_FLAG_CRM_ENABLE_POS Macro File drv_sqi.h C #define DRV_SQI_FLAG_CRM_ENABLE_POS (5) Description Continuous Read Mode Enable Macro. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 906 DRV_SQI_FLAG_DATA_DIRECTION_MASK Macro File drv_sqi.h C #define DRV_SQI_FLAG_DATA_DIRECTION_MASK (0x1U << DRV_SQI_FLAG_DATA_DIRECTION_POS) Description This is macro DRV_SQI_FLAG_DATA_DIRECTION_MASK. DRV_SQI_FLAG_DATA_DIRECTION_POS Macro File drv_sqi.h C #define DRV_SQI_FLAG_DATA_DIRECTION_POS (11) Description Macros to select the direction of the transfers. DRV_SQI_FLAG_DATA_DIRECTION_READ Macro File drv_sqi.h C #define DRV_SQI_FLAG_DATA_DIRECTION_READ (DRV_SQI_FLAG_DATA_DIRECTION_MASK & ((0x1U) << DRV_SQI_FLAG_DATA_DIRECTION_POS)) Description This is macro DRV_SQI_FLAG_DATA_DIRECTION_READ. DRV_SQI_FLAG_DATA_DIRECTION_WRITE Macro File drv_sqi.h C #define DRV_SQI_FLAG_DATA_DIRECTION_WRITE (DRV_SQI_FLAG_DATA_DIRECTION_MASK & ((0x0U) << DRV_SQI_FLAG_DATA_DIRECTION_POS)) Description This is macro DRV_SQI_FLAG_DATA_DIRECTION_WRITE. DRV_SQI_FLAG_DATA_ENABLE Macro File drv_sqi.h C #define DRV_SQI_FLAG_DATA_ENABLE(value) (DRV_SQI_FLAG_DATA_ENABLE_MASK & ((value) << DRV_SQI_FLAG_DATA_ENABLE_POS)) Description This is macro DRV_SQI_FLAG_DATA_ENABLE. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 907 DRV_SQI_FLAG_DATA_ENABLE_MASK Macro File drv_sqi.h C #define DRV_SQI_FLAG_DATA_ENABLE_MASK (0x1U << DRV_SQI_FLAG_DATA_ENABLE_POS) Description This is macro DRV_SQI_FLAG_DATA_ENABLE_MASK. DRV_SQI_FLAG_DATA_ENABLE_POS Macro File drv_sqi.h C #define DRV_SQI_FLAG_DATA_ENABLE_POS (3) Description Data Enable Macro. DRV_SQI_FLAG_DATA_TARGET_MASK Macro File drv_sqi.h C #define DRV_SQI_FLAG_DATA_TARGET_MASK (0x1U << DRV_SQI_FLAG_DATA_TARGET_POS) Description This is macro DRV_SQI_FLAG_DATA_TARGET_MASK. DRV_SQI_FLAG_DATA_TARGET_MEMORY Macro File drv_sqi.h C #define DRV_SQI_FLAG_DATA_TARGET_MEMORY (DRV_SQI_FLAG_DATA_TARGET_MASK & ((0x1U) << DRV_SQI_FLAG_DATA_TARGET_POS)) Description This is macro DRV_SQI_FLAG_DATA_TARGET_MEMORY. DRV_SQI_FLAG_DATA_TARGET_POS Macro File drv_sqi.h C #define DRV_SQI_FLAG_DATA_TARGET_POS (10) Description Macros to select the source and destination of a transfer. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 908 DRV_SQI_FLAG_DATA_TARGET_REGISTER Macro File drv_sqi.h C #define DRV_SQI_FLAG_DATA_TARGET_REGISTER (DRV_SQI_FLAG_DATA_TARGET_MASK & ((0x0U) << DRV_SQI_FLAG_DATA_TARGET_POS)) Description This is macro DRV_SQI_FLAG_DATA_TARGET_REGISTER. DRV_SQI_FLAG_DDR_ENABLE Macro File drv_sqi.h C #define DRV_SQI_FLAG_DDR_ENABLE(value) (DRV_SQI_FLAG_DDR_ENABLE_MASK & ((value) << DRV_SQI_FLAG_DDR_ENABLE_POS)) Description This is macro DRV_SQI_FLAG_DDR_ENABLE. DRV_SQI_FLAG_DDR_ENABLE_MASK Macro File drv_sqi.h C #define DRV_SQI_FLAG_DDR_ENABLE_MASK (0x1U << DRV_SQI_FLAG_DDR_ENABLE_POS) Description This is macro DRV_SQI_FLAG_DDR_ENABLE_MASK. DRV_SQI_FLAG_DDR_ENABLE_POS Macro File drv_sqi.h C #define DRV_SQI_FLAG_DDR_ENABLE_POS (4) Description DDR Enable Macro. DRV_SQI_FLAG_INSTR_ENABLE Macro File drv_sqi.h C #define DRV_SQI_FLAG_INSTR_ENABLE(value) (DRV_SQI_FLAG_INSTR_ENABLE_MASK & ((value) << DRV_SQI_FLAG_INSTR_ENABLE_POS)) Description This is macro DRV_SQI_FLAG_INSTR_ENABLE. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 909 DRV_SQI_FLAG_INSTR_ENABLE_MASK Macro File drv_sqi.h C #define DRV_SQI_FLAG_INSTR_ENABLE_MASK (0x1U << DRV_SQI_FLAG_INSTR_ENABLE_POS) Description This is macro DRV_SQI_FLAG_INSTR_ENABLE_MASK. DRV_SQI_FLAG_INSTR_ENABLE_POS Macro File drv_sqi.h C #define DRV_SQI_FLAG_INSTR_ENABLE_POS (0) Description Macros listing the bitmap values for the flags member of the DRV_SQI_TransferFrame structure. Instruction Enable Macro. DRV_SQI_FLAG_OPT_ENABLE Macro File drv_sqi.h C #define DRV_SQI_FLAG_OPT_ENABLE(value) (DRV_SQI_FLAG_OPT_ENABLE_MASK & ((value) << DRV_SQI_FLAG_OPT_ENABLE_POS)) Description This is macro DRV_SQI_FLAG_OPT_ENABLE. DRV_SQI_FLAG_OPT_ENABLE_MASK Macro File drv_sqi.h C #define DRV_SQI_FLAG_OPT_ENABLE_MASK (0x1U << DRV_SQI_FLAG_OPT_ENABLE_POS) Description This is macro DRV_SQI_FLAG_OPT_ENABLE_MASK. DRV_SQI_FLAG_OPT_ENABLE_POS Macro File drv_sqi.h C #define DRV_SQI_FLAG_OPT_ENABLE_POS (2) Description Option Enable Macro. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 910 DRV_SQI_FLAG_OPT_LENGTH Macro File drv_sqi.h C #define DRV_SQI_FLAG_OPT_LENGTH(value) (DRV_SQI_FLAG_OPT_LENGTH_MASK & ((value) << DRV_SQI_FLAG_OPT_LENGTH_POS)) Description This is macro DRV_SQI_FLAG_OPT_LENGTH. DRV_SQI_FLAG_OPT_LENGTH_1BIT Macro File drv_sqi.h C #define DRV_SQI_FLAG_OPT_LENGTH_1BIT (0x0U) Description This is macro DRV_SQI_FLAG_OPT_LENGTH_1BIT. DRV_SQI_FLAG_OPT_LENGTH_2BIT Macro File drv_sqi.h C #define DRV_SQI_FLAG_OPT_LENGTH_2BIT (0x1U) Description This is macro DRV_SQI_FLAG_OPT_LENGTH_2BIT. DRV_SQI_FLAG_OPT_LENGTH_4BIT Macro File drv_sqi.h C #define DRV_SQI_FLAG_OPT_LENGTH_4BIT (0x2U) Description This is macro DRV_SQI_FLAG_OPT_LENGTH_4BIT. DRV_SQI_FLAG_OPT_LENGTH_8BIT Macro File drv_sqi.h C #define DRV_SQI_FLAG_OPT_LENGTH_8BIT (0x3U) Description This is macro DRV_SQI_FLAG_OPT_LENGTH_8BIT. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 911 DRV_SQI_FLAG_OPT_LENGTH_MASK Macro File drv_sqi.h C #define DRV_SQI_FLAG_OPT_LENGTH_MASK (0x3U << DRV_SQI_FLAG_OPT_LENGTH_POS) Description This is macro DRV_SQI_FLAG_OPT_LENGTH_MASK. DRV_SQI_FLAG_OPT_LENGTH_POS Macro File drv_sqi.h C #define DRV_SQI_FLAG_OPT_LENGTH_POS (8) Description Macros to enable and specify the option length. DRV_SQI_FLAG_SQI_CS_NUMBER Macro File drv_sqi.h C #define DRV_SQI_FLAG_SQI_CS_NUMBER(value) (DRV_SQI_FLAG_SQI_CS_NUMBER_MASK & ((value) << DRV_SQI_FLAG_SQI_CS_NUMBER_POS)) Description This is macro DRV_SQI_FLAG_SQI_CS_NUMBER. DRV_SQI_FLAG_SQI_CS_NUMBER_0 Macro File drv_sqi.h C #define DRV_SQI_FLAG_SQI_CS_NUMBER_0 (0x0U) Description This is macro DRV_SQI_FLAG_SQI_CS_NUMBER_0. DRV_SQI_FLAG_SQI_CS_NUMBER_1 Macro File drv_sqi.h C #define DRV_SQI_FLAG_SQI_CS_NUMBER_1 (0x1U) Description This is macro DRV_SQI_FLAG_SQI_CS_NUMBER_1. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 912 DRV_SQI_FLAG_SQI_CS_NUMBER_2 Macro File drv_sqi.h C #define DRV_SQI_FLAG_SQI_CS_NUMBER_2 (0x2U) Description This is macro DRV_SQI_FLAG_SQI_CS_NUMBER_2. DRV_SQI_FLAG_SQI_CS_NUMBER_3 Macro File drv_sqi.h C #define DRV_SQI_FLAG_SQI_CS_NUMBER_3 (0x3U) Description This is macro DRV_SQI_FLAG_SQI_CS_NUMBER_3. DRV_SQI_FLAG_SQI_CS_NUMBER_MASK Macro File drv_sqi.h C #define DRV_SQI_FLAG_SQI_CS_NUMBER_MASK (0x3U << DRV_SQI_FLAG_SQI_CS_NUMBER_POS) Description This is macro DRV_SQI_FLAG_SQI_CS_NUMBER_MASK. DRV_SQI_FLAG_SQI_CS_NUMBER_POS Macro File drv_sqi.h C #define DRV_SQI_FLAG_SQI_CS_NUMBER_POS (16) Description Macros to select the SQI CS Line Number to be used for the current transfer • frame. DRV_SQI_LANE_CONFIG Enumeration Defines the SQI lane configuration options. File drv_sqi.h C typedef enum { DRV_SQI_LANE_SINGLE = 0, DRV_SQI_LANE_DUAL_DATA, DRV_SQI_LANE_QUAD_DATA, DRV_SQI_LANE_DUAL_ADDR_DATA, DRV_SQI_LANE_QUAD_ADDR_DATA, Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 913 DRV_SQI_LANE_DUAL_ALL, DRV_SQI_LANE_QUAD_ALL } DRV_SQI_LANE_CONFIG; Members Members Description DRV_SQI_LANE_SINGLE = 0 Instruction opcode, Address and Data are all sent in single lane DRV_SQI_LANE_DUAL_DATA Instruction opcode and Address are sent in single lane, while data is • sent using dual lane. DRV_SQI_LANE_QUAD_DATA Instruction opcode and Address are sent in single lane, while data is • sent using quad lane. DRV_SQI_LANE_DUAL_ADDR_DATA Instruction opcode is sent in single lane, Address and Data are sent • using dual lane. DRV_SQI_LANE_QUAD_ADDR_DATA Instruction opcode is sent in single lane, Address and Data are sent • using quad lane. DRV_SQI_LANE_DUAL_ALL Instruction opcode, Address and Data are sent using dual lanes. DRV_SQI_LANE_QUAD_ALL Instruction opcode, Address and Data are sent using quad lanes. Description SQI lane configuration options. This enumeration lists the various lane configuration options provided by the driver. Remarks None. DRV_SQI_TransferFrame Structure Defines the transfer frame of the SQI driver. File drv_sqi.h C typedef struct { uint8_t instruction; uint32_t address; uint8_t * data; uint32_t length; DRV_SQI_LANE_CONFIG laneCfg; uint8_t option; uint8_t numDummyBytes; uint32_t flags; } DRV_SQI_TransferFrame; Members Members Description uint8_t instruction; 8-bit instruction opcode. uint32_t address; 24/32-bit address. uint8_t * data; Pointer to the source or destination buffer uint32_t length; Length of the buffer in bytes. DRV_SQI_LANE_CONFIG laneCfg; Lane Configuration. uint8_t option; Option code associated with the current command. uint8_t numDummyBytes; Optional number of dummy bytes associated with the current command. uint32_t flags; This is bit-map field providing various configuration options for the • current frame. Description SQI Driver transfer frame. This data type defines the composition of a single transfer frame. In order to perform any operation on the SQI flash device, a one byte instruction specifying the operation to be performed needs to be sent out. This is followed by optional address from/to which data is to be read/written, option, dummy and data bytes. The configuration options also indicate if data is transferred to/from the device. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 914 Remarks None. Files Files Name Description drv_sqi.h SQI Driver Interface Definition drv_sqi_config_template.h SQI driver configuration definitions. Description This section lists the source and header files used by the SQI Driver Library. drv_sqi.h SQI Driver Interface Definition Enumerations Name Description DRV_SQI_COMMAND_STATUS Specifies the status of the transfer request. DRV_SQI_EVENT Identifies the possible events that can result from a transfer request. DRV_SQI_LANE_CONFIG Defines the SQI lane configuration options. DRV_SQI_SPI_OPERATION_MODE Enumeration of the SPI mode of operation supported by the SQI Controller. DRV_SQI_TRANSFER_FLAGS Enumeration of the configuration options associated with a single transfer element. Functions Name Description DRV_SQI_Close Closes an opened-instance of the SQI driver DRV_SQI_CommandStatus Gets the current status of the transfer request. DRV_SQI_Deinitialize Deinitializes the specified instance of the SQI driver module DRV_SQI_EventHandlerSet Allows a client to register an event handling function, which the driver can invoke when the queued transfer request has completed. DRV_SQI_Initialize Initializes the SQI instance for the specified driver index DRV_SQI_Open Opens the specified SQI driver instance and returns a handle to it. DRV_SQI_Status Gets the current status of the SQI driver module. DRV_SQI_Tasks Maintains the driver's task state machine. DRV_SQI_TransferData Queue a data transfer operation on the specified SQI device. DRV_SQI_TransferFrames Queue a transfer request operation on the SQI device. Macros Name Description DRV_SQI_COMMAND_HANDLE_INVALID Identifies an invalid command handle. DRV_SQI_FLAG_32_BIT_ADDR_ENABLE This is macro DRV_SQI_FLAG_32_BIT_ADDR_ENABLE. DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_MASK This is macro DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_MASK. DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_POS Enables 32-bit addressing instead of 24-bit addressing. DRV_SQI_FLAG_ADDR_ENABLE This is macro DRV_SQI_FLAG_ADDR_ENABLE. DRV_SQI_FLAG_ADDR_ENABLE_MASK This is macro DRV_SQI_FLAG_ADDR_ENABLE_MASK. DRV_SQI_FLAG_ADDR_ENABLE_POS Address Enable Macro. DRV_SQI_FLAG_CRM_ENABLE This is macro DRV_SQI_FLAG_CRM_ENABLE. DRV_SQI_FLAG_CRM_ENABLE_MASK This is macro DRV_SQI_FLAG_CRM_ENABLE_MASK. DRV_SQI_FLAG_CRM_ENABLE_POS Continuous Read Mode Enable Macro. DRV_SQI_FLAG_DATA_DIRECTION_MASK This is macro DRV_SQI_FLAG_DATA_DIRECTION_MASK. DRV_SQI_FLAG_DATA_DIRECTION_POS Macros to select the direction of the transfers. DRV_SQI_FLAG_DATA_DIRECTION_READ This is macro DRV_SQI_FLAG_DATA_DIRECTION_READ. DRV_SQI_FLAG_DATA_DIRECTION_WRITE This is macro DRV_SQI_FLAG_DATA_DIRECTION_WRITE. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 915 DRV_SQI_FLAG_DATA_ENABLE This is macro DRV_SQI_FLAG_DATA_ENABLE. DRV_SQI_FLAG_DATA_ENABLE_MASK This is macro DRV_SQI_FLAG_DATA_ENABLE_MASK. DRV_SQI_FLAG_DATA_ENABLE_POS Data Enable Macro. DRV_SQI_FLAG_DATA_TARGET_MASK This is macro DRV_SQI_FLAG_DATA_TARGET_MASK. DRV_SQI_FLAG_DATA_TARGET_MEMORY This is macro DRV_SQI_FLAG_DATA_TARGET_MEMORY. DRV_SQI_FLAG_DATA_TARGET_POS Macros to select the source and destination of a transfer. DRV_SQI_FLAG_DATA_TARGET_REGISTER This is macro DRV_SQI_FLAG_DATA_TARGET_REGISTER. DRV_SQI_FLAG_DDR_ENABLE This is macro DRV_SQI_FLAG_DDR_ENABLE. DRV_SQI_FLAG_DDR_ENABLE_MASK This is macro DRV_SQI_FLAG_DDR_ENABLE_MASK. DRV_SQI_FLAG_DDR_ENABLE_POS DDR Enable Macro. DRV_SQI_FLAG_INSTR_ENABLE This is macro DRV_SQI_FLAG_INSTR_ENABLE. DRV_SQI_FLAG_INSTR_ENABLE_MASK This is macro DRV_SQI_FLAG_INSTR_ENABLE_MASK. DRV_SQI_FLAG_INSTR_ENABLE_POS Macros listing the bitmap values for the flags member of the DRV_SQI_TransferFrame structure. Instruction Enable Macro. DRV_SQI_FLAG_OPT_ENABLE This is macro DRV_SQI_FLAG_OPT_ENABLE. DRV_SQI_FLAG_OPT_ENABLE_MASK This is macro DRV_SQI_FLAG_OPT_ENABLE_MASK. DRV_SQI_FLAG_OPT_ENABLE_POS Option Enable Macro. DRV_SQI_FLAG_OPT_LENGTH This is macro DRV_SQI_FLAG_OPT_LENGTH. DRV_SQI_FLAG_OPT_LENGTH_1BIT This is macro DRV_SQI_FLAG_OPT_LENGTH_1BIT. DRV_SQI_FLAG_OPT_LENGTH_2BIT This is macro DRV_SQI_FLAG_OPT_LENGTH_2BIT. DRV_SQI_FLAG_OPT_LENGTH_4BIT This is macro DRV_SQI_FLAG_OPT_LENGTH_4BIT. DRV_SQI_FLAG_OPT_LENGTH_8BIT This is macro DRV_SQI_FLAG_OPT_LENGTH_8BIT. DRV_SQI_FLAG_OPT_LENGTH_MASK This is macro DRV_SQI_FLAG_OPT_LENGTH_MASK. DRV_SQI_FLAG_OPT_LENGTH_POS Macros to enable and specify the option length. DRV_SQI_FLAG_SQI_CS_NUMBER This is macro DRV_SQI_FLAG_SQI_CS_NUMBER. DRV_SQI_FLAG_SQI_CS_NUMBER_0 This is macro DRV_SQI_FLAG_SQI_CS_NUMBER_0. DRV_SQI_FLAG_SQI_CS_NUMBER_1 This is macro DRV_SQI_FLAG_SQI_CS_NUMBER_1. DRV_SQI_FLAG_SQI_CS_NUMBER_2 This is macro DRV_SQI_FLAG_SQI_CS_NUMBER_2. DRV_SQI_FLAG_SQI_CS_NUMBER_3 This is macro DRV_SQI_FLAG_SQI_CS_NUMBER_3. DRV_SQI_FLAG_SQI_CS_NUMBER_MASK This is macro DRV_SQI_FLAG_SQI_CS_NUMBER_MASK. DRV_SQI_FLAG_SQI_CS_NUMBER_POS Macros to select the SQI CS Line Number to be used for the current transfer • frame. DRV_SQI_INDEX_0 SQI driver index definitions. Structures Name Description DRV_SQI_TransferElement Defines the data transfer element of the SQI driver. DRV_SQI_TransferFrame Defines the transfer frame of the SQI driver. Types Name Description DRV_SQI_COMMAND_HANDLE Handle to identify the transfer request queued at the SQI driver. DRV_SQI_EVENT_HANDLER Pointer to a SQI Driver Event handler function Description SQI Driver Interface Definition The SQI driver provides data structures and interfaces to manage the SQI controller. This file contains the data structures and interface definitions of the SQI driver. File Name drv_sqi.h Company Microchip Technology Inc. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 916 drv_sqi_config_template.h SQI driver configuration definitions. Macros Name Description DRV_SQI_BUFFER_OBJECT_NUMBER Selects the maximum number of buffer objects DRV_SQI_CLIENTS_NUMBER Selects the maximum number of clients DRV_SQI_DMA_BUFFER_DESCRIPTORS_NUMBER Selects the maximum number of DMA Buffer descriptors to be used by the driver. DRV_SQI_INSTANCES_NUMBER Selects the maximum number of Driver instances that can be supported by the dynamic driver. DRV_SQI_INTERRUPT_MODE Macro specifies operation of the driver to be in the interrupt mode or polled mode Description SQI Driver Configuration Template Header file. This template file describes all the mandatory and optional configuration macros that are needed for building the SQI driver. Do not include this file in source code. File Name drv_sqi_config_template.h Company Microchip Technology Inc. SQI Flash Driver Library This section describes the Serial Quad Interface (SQI) Flash Driver Library. Introduction This library provides an interface to manage the SST26VF family of SQI Flash devices in different modes of operation. Description The MPLAB Harmony SST26 SQI Flash Driver provides a high-level interface to manage the SST26VF family of Flash devices over the SQI interface. The driver includes the following features: • Provides application ready routines to perform block operations on the SQI Flash devices • Supports Single, Dual, and Quad Lane modes • Supports multi-client operation • Provides data transfer events • Supports non-blocking mode of operation only • Thread-safe functions for use in RTOS applications The SST26 Flash Driver uses the SQI module to establish the communication between SST26 Flash devices and Microchip microcontrollers. The following diagram shows the pin connections that are required to make the driver operational: Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 917 The SST26 Flash driver supports multi-client operation. This feature allows multiple application clients to access the same Flash device. Multiple instances of the driver can be used when multiple Flash devices are required to be part of the system. Using the Library This topic describes the basic architecture of the SQI Flash Driver Library and provides information and examples on its use. Description Interface Header Files: drv_sst26.h The interface to the SQI Flash Driver Library is defined in the header file. Any C language source (.c) file that uses the SQI Flash Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the SQI Flash Driver Library with a convenient C language interface. This topic describes how that abstraction is modeled in software. Description The SST26 SQI Flash needs a specific set of commands to be given on its SQI interface along with the required address and data to do different operations. This driver abstracts these requirements and provide simple APIs that can be used to perform Erase, Write, and Read operations. The SQI Driver is used for this purpose. The following layered diagram depicts the communication between different modules. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 918 Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the SQI Flash Driver module. Library Interface Section Description System Functions These functions are accessed by the MPLAB Harmony System module and allow the driver to be initialized, deinitialized, and maintained. Core Client Functions These functions allow the application client to open and close the driver. Block Operation Functions These functions enable the Flash module to be erased, written, and read (to/from). Media Interface Functions These functions provide media status and the Flash geometry. How the Library Works This topic provides information on how the SQI Flash Driver Library works. Description System Functions SST26 Driver Initialization The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization each instance of the SST26 Flash driver would be initialized with the following configuration settings passed dynamically at run time using DRV_SST26_INIT, that are supported by the specific SST26 Flash driver: • sqiDevice: The SQI controller supports a maximum of two slave devices. This identifies the SQI device index on which the flash device is located. The DRV_SST26_Initialize function configures and initializes the SST26 Flash driver using the configuration information provided. It returns an object handle of the type SYS_MODULE_OBJ. This object handle would be used by other system interfaces such as DRV_SST26_Status, DRV_SST26_Tasks and DRV_SST26_Deinitialize. Example: /*** SST26 FLASH Driver Initialization Data ***/ const DRV_SST26_INIT drvSst26InitData0 = { .sqiDevice = 1, }; Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 919 /* Initialize the SST26 Driver */ sysObj.drvSst26Obj0 = DRV_SST26_Initialize(DRV_SST26_INDEX_0, (SYS_MODULE_INIT *)&drvSst26InitData0); SST26 Flash Driver Task Routine The SST26 Driver task routine DRV_SST26_Tasks, will be called from the system task routine, SYS_Tasks. The driver task routine is responsible maintaining the driver state machine. The block operation requests from the application or from other modules are added to the driver queue. The task routine processes these queued requests by invoking the SQI driver routines for handling the transfer to the flash media. SST26 Flash Driver Status DRV_SST26_Status returns the current status of the SST26 Flash driver and is called by MPLAB Harmony. The application may not find the need to call this function directly. Example: SYS_MODULE_OBJ object; // Returned from DRV_SST26_Initialize SYS_STATUS sst26Status; sst26Status = DRV_SST26_Status(object); if (SYS_STATUS_ERROR >= sst26Status) { // Handle error } Client Core Functions Opening the Driver For the application to start using an instance of the module, it must call the DRV_SST26_Open function repeatedly until a valid handle is returned by the driver. The application client uses this driver handle to access the driver functions. For the various options available for I/O INTENT please refer to Data Types and Constants in the Library Interface section. Example: handle = DRV_SST26_Open(DRV_SST26_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { /* Call until the function returns a valid handle. */ } else { /* Do further processing. */ } Closing the Driver DRV_SST26_Close closes an opened-instance of the SST26 Flash driver, which also invalidates the driver handle. The application must open the driver again to obtain a valid handle. Example: DRV_HANDLE handle; // Returned from DRV_SST26_Open DRV_SST26_Close(handle); Client Block Operation Functions The driver provides client interfaces to perform operations in terms of blocks. A block is a unit that represents the minimum amount of data that can be erased, written, or read. The block sizes may differ for Erase, Write, and Read operations. The DRV_SST26_GeometryGet function can be used to read out the geometry of the flash device. The geometry indicates the number of read, write and erase regions, blocks per region and the size of each block. The DRV_SST26_Erase, DRV_SST26_Write, and DRV_SST26_Read functions are used to erase, write, and read the data to/from SST26 Flash devices. In addition to these functions, the driver also provides the DRV_SST26_EraseWrite function that combines the step of erasing a sector and then writing a page. The application can use this function if it wants to avoid having to explicitly delete a sector in order to update the pages contained in the sector. These functions are non-blocking in nature and queue the operation request into the driver queue. All of the requests in the queue are executed by the DRV_SST26_Tasks function one-by-one. A command handle associated with the operation request is returned to the application client when the operation request is queued at the driver. This handle allows the application client to track the request as it progresses through the queue. The handle expires when the request processing is complete. The driver provides events (DRV_SST26_EVENT) that indicate the completion of the requests. The following steps can be used for a simple Block Data Operation: Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 920 1. The system should have completed necessary initialization of the SQI Driver and the SST26 Flash Driver, and the DRV_SST26_Tasks function should be running in a polled environment. 2. Open the driver using DRV_SST26_Open with the necessary intent. 3. Set an event handler callback using the function DRV_SST26_EventHandlerSet. 4. Request for block operations using the functions, DRV_SST26_Erase, DRV_SST26_Write, DRV_SST26_Read and DRV_SST26_EraseWrite with the appropriate parameters. 5. Wait for event handler callback to occur and check the status of the block operation using the callback function parameter of type DRV_SST26_ EVENT. 6. After performing the required block operations, the client can close the driver using the function , DRV_SST25VF020B_Close . Example: // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; uint8_t myBuffer[MY_BUFFER_SIZE]; uint32_t blockStart, nBlock; DRV_SST26_COMMAND_HANDLE commandHandle; // drvSST26Handle is the handle returned by the DRV_SST26_Open // function. Client registers an event handler with driver. This is done once. DRV_SST26_EventHandlerSet(drvSST26Handle, APP_SST26EventHandler, (uintptr_t)&myAppObj); DRV_SST26_Read(drvSST26Handle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_SST26_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event Processing Technique. Event is received when operation is done. void APP_SST26EventHandler ( DRV_SST26_EVENT event, DRV_SST26_COMMAND_HANDLE commandHandle, uintptr_t contextHandle ) { // The context handle was set to an application specific // object. It is now retrievable easily in the event // handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) context; switch(event) { case DRV_SST26_EVENT_COMMAND_COMPLETE: // Operation completed successfully. break; case DRV_SST26_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Media Interface Functions Reading the Device Geometry The application can call the DRV_SST26_GeometryGet function to obtain the geometry of the flash device. The geometry indicates the number of read, write and erase regions, number of blocks per region and the size of each block. Example: SYS_FS_MEDIA_GEOMETRY * sst26FlashGeometry; uint32_t readBlockSize, writeBlockSize, eraseBlockSize; uint32_t nReadBlocks, nReadRegions, totalFlashSize; Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 921 sst26FlashGeometry = DRV_SST26_GeometryGet(sst26OpenHandle1); readBlockSize = sst26FlashGeometry->geometryTable->blockSize; nReadBlocks = sst26FlashGeometry->geometryTable->numBlocks; nReadRegions = sst26FlashGeometry->numReadRegions; writeBlockSize = (sst26FlashGeometry->geometryTable +1)->blockSize; eraseBlockSize = (sst26FlashGeometry->geometryTable +2)->blockSize; //The below expression provides the flash memory size. totalFlashSize = readBlockSize * nReadBlocks * nReadRegions; Configuring the Library Macros Name Description DRV_SST26_BUFFER_OBJECT_NUMBER Selects the maximum number of buffer objects DRV_SST26_CLIENTS_NUMBER Selects the maximum number of clients DRV_SST26_INSTANCES_NUMBER Selects the maximum number of Driver instances that can be supported by the dynamic driver. DRV_SST26_SYS_FS_REGISTER Register to use with the File system Description The SQI Flash Driver requires the specification of compile-time configuration macros. These macros define resource usage, feature availability, and dynamic behavior of the driver. These configuration macros should be defined in the system_config.h file. This header can be placed anywhere, 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. DRV_SST26_BUFFER_OBJECT_NUMBER Macro Selects the maximum number of buffer objects File drv_sst26_config_template.h C #define DRV_SST26_BUFFER_OBJECT_NUMBER 5 Description SST26 Driver maximum number of buffer objects This definition selects the maximum number of buffer objects. This indirectly also specifies the queue depth. The SST26 Driver can queue up DRV_SST26_BUFFER_OBJECT_NUMBER of read/write/erase requests before return a DRV_SST26_BUFFER_HANDLE_INVALID due to the queue being full. Buffer objects are shared by all instances of the driver. Increasing this number increases the RAM requirement of the driver. Remarks This macro is mandatory when building the driver for dynamic operation. DRV_SST26_CLIENTS_NUMBER Macro Selects the maximum number of clients File drv_sst26_config_template.h C #define DRV_SST26_CLIENTS_NUMBER 1 Description SST26 maximum number of clients This definition selects the maximum number of clients that the SST26 driver can supported at run time. This constant defines the total number of SST26 driver clients that will be available to all instances of the SST26 driver. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 922 Remarks This macro is mandatory when building the driver for dynamic operation. DRV_SST26_INSTANCES_NUMBER Macro Selects the maximum number of Driver instances that can be supported by the dynamic driver. File drv_sst26_config_template.h C #define DRV_SST26_INSTANCES_NUMBER 1 Description SST26 Driver instance configuration This definition selects the maximum number of Driver instances that can be supported by the dynamic driver. In case of this driver, multiple instances of the driver could use the same hardware instance. Remarks This macro is mandatory when building the driver for dynamic operation. DRV_SST26_SYS_FS_REGISTER Macro Register to use with the File system File drv_sst26_config_template.h C #define DRV_SST26_SYS_FS_REGISTER Description SST26 Driver Register with File System Specifying this macro enables the SST26 driver to register its services with the SYS FS. Remarks This macro is optional and should be specified only if the SST26 driver is to be used with the File System. Building the Library This section lists the files that are available in the SQI Flash Driver Library. Description This section list the files that are available in the /src folder of the SQI Flash 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. 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 /framework/driver/sqi_flash. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description sst26/drv_sst26.h Header file that exports the SST26VF driver API. 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. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 923 Source File Name Description sst26/src/dynamic/drv_sst26.c Basic SQI Flash Driver SST26VF implementation file. 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 N/A No optional files are available for this library Module Dependencies The SQI Flash Driver Library depends on the following modules: • SQI Driver Library • Ports System Service Library Library Interface a) System Functions Name Description DRV_SST26_Initialize Initializes the SST26 instance for the specified driver index DRV_SST26_Deinitialize Deinitializes the specified instance of the SST26 driver module DRV_SST26_Status Gets the current status of the SST26 driver module. DRV_SST26_Tasks Maintains the SST26 driver's internal state machine. b) Core Client Functions Name Description DRV_SST26_Open Opens the specified SST26 driver instance and returns a handle to it DRV_SST26_Close Closes an opened-instance of the SST26 driver c) Block Operation Functions Name Description DRV_SST26_Erase Erase the specified number of flash blocks from the specified block start address. DRV_SST26_EraseWrite Erase and Write blocks of data starting from a specified block start address. DRV_SST26_Read Reads blocks of data from the specified block start address. DRV_SST26_Write Writes blocks of data starting at the specified block start address. DRV_SST26_CommandStatus Gets the current status of the command. DRV_SST26_EventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. d) Media Interface Functions Name Description DRV_SST26_AddressGet Returns the SST26 media start address DRV_SST26_GeometryGet Returns the geometry of the device. DRV_SST26_IsAttached Returns the physical attach status of the SST26. DRV_SST26_IsWriteProtected Returns the write protect status of the SST26. e) Data Types and Constants Name Description DRV_SST26_COMMAND_HANDLE Handle identifying commands queued in the driver. DRV_SST26_COMMAND_STATUS SST26 Driver command Status DRV_SST26_EVENT Identifies the possible events that can result from a request. DRV_SST26_EVENT_HANDLER Pointer to a SST26 Driver Event handler function DRV_SST26_INIT Defines the data required to initialize or reinitialize the SST26 driver DRV_SST26_COMMAND_HANDLE_INVALID This value defines the SST26 Driver's Invalid Command Handle. DRV_SST26_INDEX_0 SST26 driver index definitions DRV_SST26_INDEX_1 This is macro DRV_SST26_INDEX_1. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 924 Description This section describes the API functions of the SQI Flash Driver Library. Refer to each section for a detailed description. a) System Functions DRV_SST26_Initialize Function Initializes the SST26 instance for the specified driver index File drv_sst26.h C SYS_MODULE_OBJ DRV_SST26_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise it returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the SST26 driver instance for the specified driver index, making it ready for clients to open and use it. Remarks This routine must be called before any other SST26 routine is called. This routine should only be called once during system initialization unless DRV_SST26_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. If the operation requires time to allow the hardware to initialize, it will be reported by the DRV_SST26_Status operation. The system must use DRV_SST26_Status to find out when the driver is in the ready state. Preconditions None. Example // This code snippet shows an example of initializing the SST26 Driver. SYS_MODULE_OBJ objectHandle; const DRV_SST26_INIT drvSst26InitData0 = { .sqiDevice = 1, }; //usage of DRV_SST26_INDEX_0 indicates usage of Flash-related APIs objectHandle = DRV_SST26_Initialize(DRV_SST26_INDEX_0, (SYS_MODULE_INIT*)&drvSst26InitData0); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized init Pointer to a data structure containing any data necessary to initialize the driver. Function SYS_MODULE_OBJ DRV_SST26_Initialize ( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 925 DRV_SST26_Deinitialize Function Deinitializes the specified instance of the SST26 driver module File drv_sst26.h C void DRV_SST26_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the SST26 driver module, disabling its operation (and any hardware). Invalidates all the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. Preconditions Function DRV_SST26_Initialize should have been called before calling this function. Parameter: object - Driver object handle, returned from the DRV_SST26_Initialize routine Example // This code snippet shows an example of deinitializing the driver. SYS_MODULE_OBJ object; // Returned from DRV_SST26_Initialize SYS_STATUS status; DRV_SST26_Deinitialize(object); status = DRV_SST26_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know when the driver is // deinitialized. } Function void DRV_SST26_Deinitialize ( SYS_MODULE_OBJ object ); DRV_SST26_Status Function Gets the current status of the SST26 driver module. File drv_sst26.h C SYS_STATUS DRV_SST26_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is ready and accept requests for new operations. SYS_STATUS_UNINITIALIZED - Indicates the driver is not initialized. Description This routine provides the current status of the SST26 driver module. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 926 Remarks This routine will NEVER block waiting for hardware. Preconditions Function DRV_SST26_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_SST26_Initialize SYS_STATUS SST26Status; SST26Status = DRV_SST26_Status(object); else if (SYS_STATUS_ERROR >= SST26Status) { // Handle error } Parameters Parameters Description object Driver object handle, returned from the DRV_SST26_Initialize routine Function SYS_STATUS DRV_SST26_Status ( SYS_MODULE_OBJ object ); DRV_SST26_Tasks Function Maintains the SST26 driver's internal state machine. File drv_sst26.h C void DRV_SST26_Tasks(SYS_MODULE_OBJ object); Returns None. Description This routine maintains the driver's internal state machine. Part of the driver initialization is done in this routine. This routine is responsible for processing the read, write, erase or erasewrite requests queued for the SST26 driver. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks). This routine may execute in an ISR context and will never block or access any resources that may cause it to block. Preconditions The DRV_SST26_Initialize routine must have been called for the specified SST26 driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_SST26_Initialize while (true) { DRV_SST26_Tasks (object); // Do other tasks } Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 927 Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_SST26_Initialize) Function void DRV_SST26_Tasks ( SYS_MODULE_OBJ object ); b) Core Client Functions DRV_SST26_Open Function Opens the specified SST26 driver instance and returns a handle to it File drv_sst26.h C DRV_HANDLE DRV_SST26_Open(const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, DRV_HANDLE_INVALID is returned. Errors can occur under the following circumstances: • if the number of client objects allocated via DRV_SST26_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the client is trying to open the driver exclusively, but has already been opened in a non exclusive mode by another client. • if the driver hardware instance being opened is not initialized or is invalid Description This routine opens the specified SST26 driver instance and provides a handle. This handle must be provided to all other client-level operations to identify the caller and the instance of the driver. Remarks The handle returned is valid until the DRV_SST26_Close routine is called. This routine will NEVER block waiting for hardware. If the driver has has already been opened, it cannot be opened exclusively. Preconditions Function DRV_SST26_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_SST26_Open(DRV_SST26_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } Parameters Parameters Description index Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver Function DRV_HANDLE DRV_SST26_Open Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 928 ( const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent ); DRV_SST26_Close Function Closes an opened-instance of the SST26 driver File drv_sst26.h C void DRV_SST26_Close(const DRV_HANDLE handle); Returns None Description This routine closes an opened-instance of the SST26 driver, invalidating the handle. Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_SST26_Open before the caller may use the driver again. Usually there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_SST26_Initialize routine must have been called for the specified SST26 driver instance. DRV_SST26_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SST26_Open DRV_SST26_Close(handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_SST26_Close ( const DRV_HANDLE handle ); c) Block Operation Functions DRV_SST26_Erase Function Erase the specified number of flash blocks from the specified block start address. File drv_sst26.h C void DRV_SST26_Erase(const DRV_HANDLE handle, DRV_SST26_COMMAND_HANDLE * commandHandle, uint32_t blockStart, uint32_t nBlock); Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 929 Returns The command handle is returned in the commandHandle argument. It Will be DRV_SST26_COMMAND_HANDLE_INVALID if the request was not queued. Description This function schedules a non-blocking erase operation of flash memory. The function returns with a valid erase handle in the commandHandle argument if the erase request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. The function returns DRV_SST26_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer object could not be allocated to the request • if the client opened the driver for read only • if the number of blocks to be erased is either zero or more than the number of blocks actually available • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_SST26_EVENT_COMMAND_COMPLETE event if the erase operation was successful or DRV_SST26_EVENT_COMMAND_ERROR event if the erase operation was not successful. Remarks None. Preconditions The DRV_SST26_Initialize() routine must have been called for the specified SST26 driver instance. The DRV_SST26_Open() routine must have been called with DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE to obtain a valid opened device handle. Example // Use DRV_SST26_GeometryGet () to find the read region geometry. // Find the erase block start address from where the number of blocks // should be erased. uint32_t blockStart = 0; uint32_t nBlock = 4; DRV_SST26_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySST26Handle is the handle returned by the DRV_SST26_Open function. // Client registers an event handler with driver DRV_SST26_EventHandlerSet(mySST26Handle, APP_SST26EventHandler, (uintptr_t)&myAppObj); DRV_SST26_Erase( mySST26Handle, &commandHandle, blockStart, nBlock ); if(DRV_SST26_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when the buffer queue is processed. void APP_SST26EventHandler ( DRV_SST26_EVENT event, DRV_SST26_COMMAND_HANDLE commandHandle, uintptr_t contextHandle ) { // contextHandle points to myAppObj. switch(event) { case DRV_SST26_EVENT_COMMAND_COMPLETE: // Erase operation completled successfully. break; case DRV_SST26_EVENT_COMMAND_ERROR: // Error handling here. break; Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 930 default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle blockStart Erase block start address from where the blocks should be erased. nBlock Total number of blocks to be erased. Function void DRV_SST26_Erase ( const DRV_HANDLE handle, DRV_SST26_COMMAND_HANDLE * commandHandle, uint32_t blockStart, uint32_t nBlock ); DRV_SST26_EraseWrite Function Erase and Write blocks of data starting from a specified block start address. File drv_sst26.h C void DRV_SST26_EraseWrite(const DRV_HANDLE handle, DRV_SST26_COMMAND_HANDLE * commandHandle, void * sourceBuffer, uint32_t writeBlockStart, uint32_t nWriteBlock); Returns The command handle is returned in the commandHandle argument. It Will be DRV_SST26_COMMAND_HANDLE_INVALID if the request was not queued. Description This function combines the step of erasing a sector and then writing the page. The application can use this function if it wants to avoid having to explicitly delete a sector in order to update the pages contained in the sector. This function schedules a non-blocking operation to erase and write blocks of data into flash memory. The function returns with a valid command handle in the commandHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_SST26_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the client opened the driver for read only • if the number of blocks to be written is either zero or more than the number of blocks actually available • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_SST26_EVENT_COMMAND_COMPLETE event if the buffer was processed successfully or DRV_SST26_EVENT_COMMAND_ERROR event if the buffer was not processed successfully. Remarks None. Preconditions The DRV_SST26_Initialize() routine must have been called for the specified SST26 driver instance. The DRV_SST26_Open() must have been called with DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE as a parameter to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 931 Example uint8_t myBuffer[MY_BUFFER_SIZE]; // Use DRV_SST26_GeometryGet () to find the write region geometry. // Find the block address to which data is to be written. uint32_t blockStart = SST26_BLOCK_ADDRESS_TO_WRITE_TO; uint32_t nBlock = 2; DRV_SST26_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySST26Handle is the handle returned by the DRV_SST26_Open function. // Client registers an event handler with driver DRV_SST26_EventHandlerSet(mySST26Handle, APP_SST26EventHandler, (uintptr_t)&myAppObj); DRV_SST26_EraseWrite(mySST26Handle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_SST26_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when the buffer is processed. void APP_SST26EventHandler ( DRV_SST26_EVENT event, DRV_SST26_COMMAND_HANDLE commandHandle, uintptr_t contextHandle ) { // contextHandle points to myAppObj. switch(event) { case DRV_SST26_EVENT_COMMAND_COMPLETE: // Operation completled successfully. break; case DRV_SST26_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return command handle. If NULL, then command handle is not returned. sourceBuffer The source buffer containing data to be programmed into SST26 Flash writeBlockStart Write block start address where the write should begin. nWriteBlock Total number of blocks to be written. Function void DRV_SST26_EraseWrite ( const DRV_HANDLE handle, DRV_SST26_COMMAND_HANDLE * commandHandle, void * sourceBuffer, uint32_t writeBlockStart, uint32_t nWriteBlock Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 932 ); DRV_SST26_Read Function Reads blocks of data from the specified block start address. File drv_sst26.h C void DRV_SST26_Read(const DRV_HANDLE handle, DRV_SST26_COMMAND_HANDLE * commandHandle, void * targetBuffer, uint32_t blockStart, uint32_t nBlock); Returns The command handle is returned in the commandHandle argument. It will be DRV_SST26_COMMAND_HANDLE_INVALID if the request was not successful. Description This function schedules a non-blocking read operation for reading blocks of data from the flash memory. The function returns with a valid command handle in the commandHandle argument if the request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_SST26_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer object could not be allocated to the request • if the target buffer pointer is NULL • if the client opened the driver for write only • if the number of blocks to be read is either zero or more than the number of blocks actually available • if the driver handle is invalid Remarks None. Preconditions The DRV_SST26_Initialize routine must have been called for the specified SST26 driver instance. DRV_SST26_Open must have been called with DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE as the ioIntent to obtain a valid opened device handle. Example uint8_t myBuffer[MY_BUFFER_SIZE]; // Use DRV_SST26_GeometryGet () to find the read region geometry. // Find the block address from which to read data. uint32_t blockStart = SST26_BLOCK_ADDRESS_TO_READ_FROM; uint32_t nBlock = 2; DRV_SST26_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySST26Handle is the handle returned by the DRV_SST26_Open function. // Client registers an event handler with driver DRV_SST26_EventHandlerSet(mySST26Handle, APP_SST26EventHandler, (uintptr_t)&myAppObj); DRV_SST26_Read(mySST26Handle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_SST26_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } else { // Read queued successfully. } // Event is received when the command request is processed. void APP_SST26EventHandler ( Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 933 DRV_SST26_EVENT event, DRV_SST26_COMMAND_HANDLE commandHandle, uintptr_t contextHandle ) { // contextHandle points to myAppObj. switch(event) { case DRV_SST26_EVENT_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_SST26_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the command handle targetBuffer Buffer into which the data read from the SST26 Flash memory will be placed blockStart Read block start address from where the data should be read. nBlock Total number of blocks to be read. Function void DRV_SST26_Read ( const DRV_HANDLE handle, DRV_SST26_COMMAND_HANDLE * commandHandle, void * targetBuffer, uint32_t blockStart, uint32_t nBlock ); DRV_SST26_Write Function Writes blocks of data starting at the specified block start address. File drv_sst26.h C void DRV_SST26_Write(const DRV_HANDLE handle, DRV_SST26_COMMAND_HANDLE * commandHandle, void * sourceBuffer, uint32_t blockStart, uint32_t nBlock); Returns The command handle is returned in the commandHandle argument. It will be DRV_SST26_COMMAND_HANDLE_INVALID if the request was not successful. Description This function schedules a non-blocking write operation for writing blocks of data into flash memory. The function returns with a valid command handle in the commandHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_SST26_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if a buffer object could not be allocated to the request • if the source buffer pointer is NULL • if the client opened the driver for read only Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 934 • if the number of blocks to be written is either zero or more than the number of blocks actually available • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_SST26_EVENT_COMMAND_COMPLETE event if the buffer was processed successfully or DRV_SST26_EVENT_COMMAND_ERROR event if the buffer was not processed successfully. Remarks None. Preconditions The DRV_SST26_Initialize() routine must have been called for the specified SST26 driver instance. DRV_SST26_Open() routine must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified as a parameter to this routine. The flash address location which has to be written, must have be erased before using the DRV_SST26_Erase() routine. Example uint8_t myBuffer[MY_BUFFER_SIZE]; // Use DRV_SST26_GeometryGet () to find the write region geometry. // Find the block address to which data is to be written. uint32_t blockStart = SST26_BLOCK_ADDRESS_TO_WRITE_TO; uint32_t nBlock = 2; DRV_SST26_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySST26Handle is the handle returned by the DRV_SST26_Open function. // Client registers an event handler with driver DRV_SST26_EventHandlerSet(mySST26Handle, APP_SST26EventHandler, (uintptr_t)&myAppObj); DRV_SST26_Write(mySST26Handle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_SST26_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event is received when the buffer is processed. void APP_SST26EventHandler ( DRV_SST26_EVENT event, DRV_SST26_COMMAND_HANDLE commandHandle, uintptr_t contextHandle ) { // contextHandle points to myAppObj. switch(event) { case DRV_SST26_EVENT_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_SST26_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle sourceBuffer The source buffer containing data to be programmed into SST26 Flash Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 935 blockStart Write block start address from where the data should be written to. nBlock Total number of blocks to be written. Function void DRV_SST26_Write ( const DRV_HANDLE handle, DRV_SST26_COMMAND_HANDLE * commandHandle, void * sourceBuffer, uint32_t blockStart, uint32_t nBlock ); DRV_SST26_CommandStatus Function Gets the current status of the command. File drv_sst26.h C DRV_SST26_COMMAND_STATUS DRV_SST26_CommandStatus(const DRV_HANDLE handle, const DRV_SST26_COMMAND_HANDLE commandHandle); Returns A DRV_SST26_COMMAND_STATUS value describing the current status of the command. Returns DRV_SST26_COMMAND_HANDLE_INVALID if the client handle or the command handle is not valid. Description This routine gets the current status of the command. The application must use this routine where the status of a scheduled command needs to be polled on. The function may return DRV_SST26_COMMAND_COMPLETED in a case where the command handle has expired. A command handle expires when the internal buffer object is re-assigned to another request. It is recommended that this function be called regularly in order to track the command status correctly. The application can alternatively register an event handler to receive the command completion events. Remarks This routine will not block for hardware access and will immediately return the current status. Preconditions The DRV_SST26_Initialize() routine must have been called. The DRV_SST26_Open() must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SST26_Open DRV_SST26_COMMAND_HANDLE commandHandle; DRV_SST26_COMMAND_STATUS status; status = DRV_SST26_CommandStatus(handle, commandHandle); if(status == DRV_SST26_COMMAND_COMPLETED) { // Operation Done } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function DRV_SST26_COMMAND_STATUS DRV_SST26_CommandStatus ( const DRV_HANDLE handle, Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 936 const DRV_SST26_COMMAND_HANDLE commandHandle ); DRV_SST26_EventHandlerSet Function Allows a client to identify an event handling function for the driver to call back when queued operation has completed. File drv_sst26.h C void DRV_SST26_EventHandlerSet(const DRV_HANDLE handle, const void * eventHandler, const uintptr_t context); Returns None. Description This function allows a client to identify an event handling function for the driver to call back when queued operation has completed. When a client calls a read, write, erase or a erasewrite function, it is provided with a handle identifying the command that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the queued operation has completed. The event handler should be set before the client performs any operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued operation has completed, it does not need to register a callback. Preconditions The DRV_SST26_Initialize() routine must have been called for the specified SST26 driver instance. The DRV_SST26_Open() routine must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; uint8_t myBuffer[MY_BUFFER_SIZE]; uint32_t blockStart, nBlock; DRV_SST26_COMMAND_HANDLE commandHandle; // drvSST26Handle is the handle returned by the DRV_SST26_Open function. // Client registers an event handler with driver. This is done once. DRV_SST26_EventHandlerSet(drvSST26Handle, APP_SST26EventHandler, (uintptr_t)&myAppObj); DRV_SST26_Read(drvSST26Handle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_SST26_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event Processing Technique. Event is received when operation is done. void APP_SST26EventHandler ( DRV_SST26_EVENT event, DRV_SST26_COMMAND_HANDLE commandHandle, uintptr_t contextHandle ) { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) context; switch(event) { Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 937 case DRV_SST26_EVENT_COMMAND_COMPLETE: // Operation completled successfully. break; case DRV_SST26_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function eventHandler Pointer to the event handler function implemented by the user context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_SST26_EventHandlerSet ( const DRV_HANDLE handle, const void * eventHandler, const uintptr_t context ); d) Media Interface Functions DRV_SST26_AddressGet Function Returns the SST26 media start address File drv_sst26.h C uintptr_t DRV_SST26_AddressGet(const DRV_HANDLE handle); Returns Start address of the SST26 Media if the handle is valid otherwise NULL. Description This function returns the SST26 Media start address. Remarks None. Preconditions The DRV_SST26_Initialize() routine must have been called for the specified SST26 driver instance. The DRV_SST26_Open() routine must have been called to obtain a valid opened device handle. Example uintptr_t startAddress; startAddress = DRV_SST26_AddressGet(drvSST26Handle); Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 938 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function uintptr_t DRV_SST26_AddressGet ( const DRV_HANDLE handle ); DRV_SST26_GeometryGet Function Returns the geometry of the device. File drv_sst26.h C SYS_FS_MEDIA_GEOMETRY * DRV_SST26_GeometryGet(const DRV_HANDLE handle); Returns SYS_FS_MEDIA_GEOMETRY - Pointer to structure which holds the media geometry information. Description This API gives the following geometrical details of the SST26 Flash: • Media Property • Number of Read/Write/Erase regions in the flash device • Number of Blocks and their size in each region of the device Remarks None. Preconditions The DRV_SST26_Initialize() routine must have been called for the specified SST26 driver instance. The DRV_SST26_Open() routine must have been called to obtain a valid opened device handle. Example SYS_FS_MEDIA_GEOMETRY * sst26FlashGeometry; uint32_t readBlockSize, writeBlockSize, eraseBlockSize; uint32_t nReadBlocks, nReadRegions, totalFlashSize; sst26FlashGeometry = DRV_SST26_GeometryGet(sst26OpenHandle1); readBlockSize = sst26FlashGeometry->geometryTable->blockSize; nReadBlocks = sst26FlashGeometry->geometryTable->numBlocks; nReadRegions = sst26FlashGeometry->numReadRegions; writeBlockSize = (sst26FlashGeometry->geometryTable +1)->blockSize; eraseBlockSize = (sst26FlashGeometry->geometryTable +2)->blockSize; totalFlashSize = readBlockSize * nReadBlocks * nReadRegions; Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function SYS_FS_MEDIA_GEOMETRY * DRV_SST26_GeometryGet ( const DRV_HANDLE handle Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 939 ); DRV_SST26_IsAttached Function Returns the physical attach status of the SST26. File drv_sst26.h C bool DRV_SST26_IsAttached(const DRV_HANDLE handle); Returns Returns false if the handle is invalid otherwise returns true. Description This function returns the physical attach status of the SST26. Remarks None. Preconditions The DRV_SST26_Initialize() routine must have been called for the specified SST26 driver instance. The DRV_SST26_Open() routine must have been called to obtain a valid opened device handle. Example bool isSST26Attached; isSST26Attached = DRV_SST26_isAttached(drvSST26Handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function bool DRV_SST26_IsAttached ( const DRV_HANDLE handle ); DRV_SST26_IsWriteProtected Function Returns the write protect status of the SST26. File drv_sst26.h C bool DRV_SST26_IsWriteProtected(const DRV_HANDLE handle); Returns True - If the flash is write protected. False - If the flash is not write protected. Description This function returns the write protect status of the SST26. Remarks None. Preconditions The DRV_SST26_Initialize() routine must have been called for the specified SST26 driver instance. The DRV_SST26_Open() routine must have been called to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 940 Example bool isWriteProtected; isWriteProtected = DRV_SST26_IsWriteProtected(drvSST26Handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function bool DRV_SST26_IsWriteProtected ( const DRV_HANDLE handle ); e) Data Types and Constants DRV_SST26_COMMAND_HANDLE Type Handle identifying commands queued in the driver. File drv_sst26.h C typedef SYS_FS_MEDIA_BLOCK_COMMAND_HANDLE DRV_SST26_COMMAND_HANDLE; Description SST26 Driver command handle. A command handle is returned by a call to the Read, Write, Erase or EraseWrite functions. This handle allows the application to track the completion of the operation. This command handle is also returned to the client along with the event that has occurred with respect to the command. This allows the application to connect the event to a specific command in case where multiple commands are queued. The command handle associated with the command request expires when the client has been notified of the completion of the command (after event handler function that notifies the client returns) or after the command has been retired by the driver if no event handler callback was set. Remarks None. DRV_SST26_COMMAND_STATUS Enumeration SST26 Driver command Status File drv_sst26.h C typedef enum { DRV_SST26_COMMAND_COMPLETED = SYS_FS_MEDIA_COMMAND_COMPLETED, DRV_SST26_COMMAND_QUEUED = SYS_FS_MEDIA_COMMAND_QUEUED, DRV_SST26_COMMAND_IN_PROGRESS = SYS_FS_MEDIA_COMMAND_IN_PROGRESS, DRV_SST26_COMMAND_ERROR_UNKNOWN = SYS_FS_MEDIA_COMMAND_UNKNOWN } DRV_SST26_COMMAND_STATUS; Members Members Description DRV_SST26_COMMAND_COMPLETED = SYS_FS_MEDIA_COMMAND_COMPLETED Done OK and ready DRV_SST26_COMMAND_QUEUED = SYS_FS_MEDIA_COMMAND_QUEUED Scheduled but not started DRV_SST26_COMMAND_IN_PROGRESS = SYS_FS_MEDIA_COMMAND_IN_PROGRESS Currently being in transfer Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 941 DRV_SST26_COMMAND_ERROR_UNKNOWN = SYS_FS_MEDIA_COMMAND_UNKNOWN Unknown Command Description SST26 Driver Command Status Specifies the status of the command for the read, write, erase and erasewrite operations. Remarks None. DRV_SST26_EVENT Enumeration Identifies the possible events that can result from a request. File drv_sst26.h C typedef enum { DRV_SST26_EVENT_COMMAND_COMPLETE = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_COMPLETE, DRV_SST26_EVENT_COMMAND_ERROR = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_ERROR } DRV_SST26_EVENT; Members Members Description DRV_SST26_EVENT_COMMAND_COMPLETE = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_COMPLETE Operation has been completed successfully. DRV_SST26_EVENT_COMMAND_ERROR = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_ERROR There was an error during the operation Description SST26 Driver Events This enumeration identifies the possible events that can result from a read, write, erase or erasewrite request caused by the client. Remarks One of these values is passed in the "event" parameter of the event handling callback function that client registered with the driver by calling the DRV_SST26_EventHandlerSet function when a request is completed. DRV_SST26_EVENT_HANDLER Type Pointer to a SST26 Driver Event handler function File drv_sst26.h C typedef SYS_FS_MEDIA_EVENT_HANDLER DRV_SST26_EVENT_HANDLER; Returns None. Description SST26 Driver Event Handler Function Pointer This data type defines the required function signature for the SST26 event handling callback function. A client must register a pointer to an event handling function whose function signature (parameter and return value types) match the types specified by this function pointer in order to receive event calls back from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks If the event is DRV_SST26_EVENT_COMMAND_COMPLETE, it means that the requested operation was completed successfully. If the event is DRV_SST26_EVENT_COMMAND_ERROR, it means that the scheduled operation was not completed successfully. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 942 The context parameter contains the handle to the client context, provided at the time the event handling function was registered using the DRV_SST26_EventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the read/write/erase request. The event handler function executes in the driver peripheral's interrupt context when the driver is configured for interrupt mode operation. It is recommended of the application to not perform process intensive or blocking operations within this function. Example void APP_MySst26EventHandler ( DRV_SST26_EVENT event, DRV_SST26_COMMAND_HANDLE commandHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_SST26_EVENT_COMMAND_COMPLETE: // Handle the completed buffer. break; case DRV_SST26_EVENT_COMMAND_ERROR: default: // Handle error. break; } } Parameters Parameters Description event Identifies the type of event commandHandle Handle returned from the Read/Write/Erase/EraseWrite requests context Value identifying the context of the application that registered the event handling function DRV_SST26_INIT Structure Defines the data required to initialize or reinitialize the SST26 driver File drv_sst26.h C typedef struct { uint8_t sqiDevice; } DRV_SST26_INIT; Members Members Description uint8_t sqiDevice; SQI Device Index. Description SST26 Driver Initialization Data This data type defines the data required to initialize or reinitialize the SST26 driver. Remarks Not all initialization features are available for all devices. Please refer to the specific device data sheet to determine availability. DRV_SST26_COMMAND_HANDLE_INVALID Macro This value defines the SST26 Driver's Invalid Command Handle. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 943 File drv_sst26.h C #define DRV_SST26_COMMAND_HANDLE_INVALID SYS_FS_MEDIA_BLOCK_COMMAND_HANDLE_INVALID Description SST26 Driver Invalid Command Handle. This value defines the SST26 Driver's Invalid Command Handle. This value is returned by read/write/erase/erasewrite routines when the command request was not accepted. Remarks None. DRV_SST26_INDEX_0 Macro SST26 driver index definitions File drv_sst26.h C #define DRV_SST26_INDEX_0 0 Description Driver SST26 Module Index reference These constants provide SST26 driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_SST26_Initialize and DRV_SST26_Open routines to identify the driver instance in use. DRV_SST26_INDEX_1 Macro File drv_sst26.h C #define DRV_SST26_INDEX_1 1 Description This is macro DRV_SST26_INDEX_1. Files Files Name Description drv_sst26.h SST26 Driver Interface Definition drv_sst26_config_template.h SST26 driver configuration definitions. Description This section lists the source and header files used by the SQI Flash Driver Library. drv_sst26.h SST26 Driver Interface Definition Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 944 Enumerations Name Description DRV_SST26_COMMAND_STATUS SST26 Driver command Status DRV_SST26_EVENT Identifies the possible events that can result from a request. Functions Name Description DRV_SST26_AddressGet Returns the SST26 media start address DRV_SST26_Close Closes an opened-instance of the SST26 driver DRV_SST26_CommandStatus Gets the current status of the command. DRV_SST26_Deinitialize Deinitializes the specified instance of the SST26 driver module DRV_SST26_Erase Erase the specified number of flash blocks from the specified block start address. DRV_SST26_EraseWrite Erase and Write blocks of data starting from a specified block start address. DRV_SST26_EventHandlerSet Allows a client to identify an event handling function for the driver to call back when queued operation has completed. DRV_SST26_GeometryGet Returns the geometry of the device. DRV_SST26_Initialize Initializes the SST26 instance for the specified driver index DRV_SST26_IsAttached Returns the physical attach status of the SST26. DRV_SST26_IsWriteProtected Returns the write protect status of the SST26. DRV_SST26_Open Opens the specified SST26 driver instance and returns a handle to it DRV_SST26_Read Reads blocks of data from the specified block start address. DRV_SST26_Status Gets the current status of the SST26 driver module. DRV_SST26_Tasks Maintains the SST26 driver's internal state machine. DRV_SST26_Write Writes blocks of data starting at the specified block start address. Macros Name Description DRV_SST26_COMMAND_HANDLE_INVALID This value defines the SST26 Driver's Invalid Command Handle. DRV_SST26_INDEX_0 SST26 driver index definitions DRV_SST26_INDEX_1 This is macro DRV_SST26_INDEX_1. Structures Name Description DRV_SST26_INIT Defines the data required to initialize or reinitialize the SST26 driver Types Name Description DRV_SST26_COMMAND_HANDLE Handle identifying commands queued in the driver. DRV_SST26_EVENT_HANDLER Pointer to a SST26 Driver Event handler function Description SST26 Driver Interface Definition The SST26 driver provides a simple interface to manage the SST26VF series of SQI Flash Memory connected to Microchip microcontrollers. This file defines the interface definition for the SST26 driver. File Name drv_sst26.h Company Microchip Technology Inc. drv_sst26_config_template.h SST26 driver configuration definitions. Volume V: MPLAB Harmony Framework Driver Libraries Help SQI Flash Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 945 Macros Name Description DRV_SST26_BUFFER_OBJECT_NUMBER Selects the maximum number of buffer objects DRV_SST26_CLIENTS_NUMBER Selects the maximum number of clients DRV_SST26_INSTANCES_NUMBER Selects the maximum number of Driver instances that can be supported by the dynamic driver. DRV_SST26_SYS_FS_REGISTER Register to use with the File system Description SST26 Driver Configuration Template Header file. This template file describes all the mandatory and optional configuration macros that are needed for building the SST26 driver. Do not include this file in source code. File Name drv_sst26_config_template.h Company Microchip Technology Inc. SRAM Driver Library This section describes the Static Random Access (SRAM) driver library. Introduction The SRAM Media Driver library provides a high-level interface to manage the onboard SRAM as a media Description The SRAM Media driver features the following: • Provides application ready routines to perform block operations on the SRAM media • Supports multi-client operation • Provides data transfer events • Supports blocking mode of operation only Using the Library This topic describes the basic architecture of the SRAM Media Driver Library and provides information and examples about how to use it. Description Interface Header Files: drv_sram.h Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Topics Name Description Abstraction Model This library provides a low-level abstraction of the SRAM media with a convenient C language interface. This topic describes how that abstraction is modeled in software. Library Overview This library provides information about how the driver operates in a system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the SRAM Media driver module. How the Library Works This section describes how the SRAM Media Driver Library operates Abstraction Model This library provides a low-level abstraction of the SRAM media with a convenient C language interface. This section describes how that abstraction is modeled in software. Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 946 Description The SRAM Media driver facilitates the block access to the SRAM media by providing APIs that can be used to perform read/write operations. The end applications can either access the media directly through the driver or through MPLAB Harmony. The following diagram shows the communication between different modules. SRAM Media Driver Abstraction Model Library Overview Refer to the Driver Library Overview section for information about how the SRAM driver operates within a system. Description The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the SRAM module. Library Interface Section Description System Functions Provides system module interfaces, device initialization, de-initialization and status functions. Data Types and Constants Provides data types and macros. How the Library Works The library provides interfaces to support: • System Functionality • Client Functionality • Media Functionality System Initialization/Status Functions The SRAM driver provides the following system functions: • SRAM driver initialization • SRAM driver status. Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 947 Description SRAM driver initialization The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. During system initialization each instance of the SRAM Media driver would be initialized with the following configuration settings passed dynamically at run time using DRV_SRAM_INIT: • registerWithFs: This controls the registration of the driver with the Harmony File System. • mediaStartAddress: This indicates the start address of the SRAM media on which driver is to operate. • sramMediaGeometry: This provides the SRAM media geometry information that the driver will use while performing the read/write operations on the media. The DRV_SRAM_Initialize function configures and initializes the SRAM Media driver by using the configuration information provided. The function returns an object handle of the type SYS_MODULE_OBJ. This object handle is used by other system interfaces such as DRV_SRAM_Status and DRV_SRAM_Deinitialize. Example: /*** SRAM Driver Initialization Data ***/ SYS_FS_MEDIA_REGION_GEOMETRY sramMedia0GeometryTable[3] = { { .blockSize = 1, .numBlocks = (32 * (1024/1)), }, { .blockSize = 1, .numBlocks = (32 * (1024/1)), }, { .blockSize = 1, .numBlocks = (32 * (1024/1)), } }; const SYS_FS_MEDIA_GEOMETRY sramMedia0Geometry = { .mediaProperty = SYS_FS_MEDIA_WRITE_IS_BLOCKING | SYS_FS_MEDIA_READ_IS_BLOCKING, .numReadRegions = 1, .numWriteRegions = 1, .numEraseRegions = 1, .geometryTable = (SYS_FS_MEDIA_REGION_GEOMETRY *)&sramMedia0GeometryTable }; extern uint8_t SRAM_MEDIA_0_DATA[]; const DRV_SRAM_INIT drvSram0Init = { .registerWithFs = true, .mediaStartAddress = (uint8_t *)SRAM_MEDIA_0_DATA, .sramMediaGeometry = (SYS_FS_MEDIA_GEOMETRY *)&sramMedia0Geometry }; /* Initialize the SRAM Driver Instance 0 */ sysObj.drvSramObj0 = DRV_SRAM_Initialize(DRV_SRAM_INDEX_0, (SYS_MODULE_INIT *)&drvSram0Init); SRAM driver status DRV_SRAM_Status() returns the current status of the SRAM Media driver and is called by the Harmony System. The application may not find the need to call this function directly. Example: SYS_MODULE_OBJ object; // Returned from DRV_SRAM_Initialize Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 948 SYS_STATUS sramStatus; sramStatus = DRV_SRAM_Status(object); if (SYS_STATUS_ERROR >= sramStatus) { // Handle error } Client Core Functions The SRAM driver provides the following client core functions: • Opening the driver • Closing the driver Description Opening the driver For the application to start using an instance of the module, it must call the function DRV_SRAM_Open and obtain a valid driver handle. The application client uses this driver handle to access the driver functions. For the various options available for I/O INTENT, please refer to Data Types and Constants in the Library Interface section. Example: handle = DRV_SRAM_Open(DRV_SRAM_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { /* Call until the function returns a valid handle. */ } else { /* Do further processing. */ } Closing the driver This function closes an opened-instance of the SRAM Media driver. This invalidates the driver handle. The application must open the driver again to obtain a valid handle. Example: DRV_HANDLE handle; // Returned from DRV_SRAM_Open DRV_SRAM_Close(handle); Client Block Operation Functions The SRAM driver provides client interfaces to perform operations in terms of blocks. Description A block is a unit that represents the minimum amount of data that can be written or read. The block sizes may differ for write and read operations. The DRV_SRAM_GeometryGet function can be used to read out the geometry of the SRAM Media. The geometry indicates the number of read, write, and erase regions; blocks per region; and the size of each block. The DRV_SRAM_Write and DRV_SRAM_Read functions are used to write and read the data to/from SRAM media. These functions block operations until the requested amount of data is transferred. If an event handler has been registered to receive the driver events, then the event handler will be invoked from within these functions. The driver provides events (DRV_SRAM_EVENT) that indicate the completion of the requests. The following steps can be performed for a simple block data transfer operation: 1. Make sure the system has completed the necessary initialization of the SRAM driver. 2. Open the driver using DRV_SRAM_Open with the necessary intent. 3. Register an event handler callback by using the function DRV_SRAM_EventHandlerSet. 4. Request for block operation by using the functions DRV_SRAM_Write and DRV_SRAM_Read with the appropriate parameters. 5. Wait for the event handler callback to occur and check the status of the block operation by using the callback function parameter of type DRV_SRAM_ EVENT. 6. After performing the required block operations, the client can close the driver by using the function DRV_SRAM_Close. Example: uint8_t myBuffer[MY_BUFFER_SIZE]; uint32_t blockStart = 0; uint32_t nBlock = 2; Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 949 DRV_SRAM_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySRAMHandle is the handle returned by the DRV_SRAM_Open // function. DRV_SRAM_EventHandlerSet( mySRAMHandle, APP_SRAMEventHandler, (uintptr_t)&myAppObj); DRV_SRAM_Read( mySRAMHandle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_SRAM_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } else { // Read operation completed successfully. } // Event is invoked from within the DRV_SRAM_Read function when // the read operation processing is complete. void APP_SRAMEventHandler ( DRV_SRAM_EVENT event, DRV_SRAM_COMMAND_HANDLE commandHandle, uintptr_t contextHandle ) { // contextHandle points to myAppObj. switch(event) { case DRV_SRAM_EVENT_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_SRAM_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Media Interface Functions The SRAM driver provides the following media interface function: • Reading the device geometry Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 950 Description The application can call the DRV_SRAM_GeometryGet function to obtain the geometry of the media device. Reading the device geometry The geometry indicates the number of read, write, and erase regions; the number of blocks per region; and the size of each block. Example: SYS_FS_MEDIA_GEOMETRY * sramGeometry; uint32_t readBlockSize, writeBlockSize, eraseBlockSize; uint32_t nReadBlocks, nReadRegions, totalSize; sramGeometry = DRV_SRAM_GeometryGet(sramOpenHandle1); readBlockSize = sramGeometry->geometryTable->blockSize; nReadBlocks = sramGeometry->geometryTable->numBlocks; nReadRegions = sramGeometry->numReadRegions; writeBlockSize = (sramGeometry->geometryTable +1)->blockSize; eraseBlockSize = (sramGeometry->geometryTable +2)->blockSize; totalSize = readBlockSize * nReadBlocks * nReadRegions; Configuring the Library This section contains related configuration macros. Description The configuration of the SRAM driver is based on the file system_config.h. This header file contains the configuration selection for the SRAM driver. Based on the selections made, the SRAM driver may support the selected features. These configuration settings apply to all instances of the SRAM driver. 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 in the SRAM library. 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 /framework/driver/sram/. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_sram.h This is the SRAM library's interface header file. 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 /src/dynamic/drv_sram.c This file contains the source code for the dynamic implementation of the SRAM driver. /config/drv_sram_config_template.h This file contains configuration macros for the SRAM driver. Optional File(s) This table lists and describes the source and header files that may optionally be included if required for the desired implementation. Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 951 Source File Name Description N/A No optional files are available for this library. Library Interface This section describes the Application Programming Interface (API) functions of the SRAM driver library. Refer to each section for a detailed description. a) System Functions Name Description DRV_SRAM_AddressGet Returns the SRAM media start address DRV_SRAM_Close Closes an opened-instance of the SRAM driver DRV_SRAM_CommandStatus Gets the current status of the command. DRV_SRAM_Deinitialize Deinitializes the specified instance of the SRAM driver module DRV_SRAM_EventHandlerSet Allows a client to identify an event handling function for the driver to call back when an operation has completed. DRV_SRAM_GeometryGet Returns the geometry of the device. DRV_SRAM_Initialize Initializes the SRAM instance for the specified driver index. DRV_SRAM_IsAttached Returns the physical attach status of the SRAM. DRV_SRAM_IsWriteProtected Returns the write protect status of the SRAM. DRV_SRAM_Open Opens the specified SRAM driver instance and returns a handle to it DRV_SRAM_Read Reads blocks of data from the specified block start address. DRV_SRAM_Status Gets the current status of the SRAM driver module. DRV_SRAM_Write Writes blocks of data starting from the specified block start address of the SRAM media. c) Data Types and Constants Name Description DRV_SRAM_COMMAND_HANDLE Handle identifying commands queued in the driver. DRV_SRAM_COMMAND_STATUS Specifies the status of the command for the read and write operations. DRV_SRAM_EVENT Identifies the possible events that can result from a request. DRV_SRAM_EVENT_HANDLER Pointer to a SRAM Driver Event handler function DRV_SRAM_INIT Defines the data required to initialize the SRAM driver _DRV_SRAM_H This is macro _DRV_SRAM_H. DRV_SRAM_COMMAND_HANDLE_INVALID This value defines the SRAM Driver's Invalid Command Handle. DRV_SRAM_INDEX_0 SRAM driver index definitions DRV_SRAM_INDEX_1 This is macro DRV_SRAM_INDEX_1. a) System Functions DRV_SRAM_AddressGet Function Returns the SRAM media start address File drv_sram.h C uintptr_t DRV_SRAM_AddressGet(const DRV_HANDLE handle); Returns Start address of the SRAM Media if the handle is valid otherwise NULL. Description This function returns the SRAM Media start address. Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 952 Remarks None. Preconditions The DRV_SRAM_Initialize() routine must have been called for the specified SRAM driver instance. The DRV_SRAM_Open() routine must have been called to obtain a valid opened device handle. Example uintptr_t startAddress; startAddress = DRV_SRAM_AddressGet(drvSRAMHandle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open Function uintptr_t DRV_SRAM_AddressGet ( const DRV_HANDLE handle ); DRV_SRAM_Close Function Closes an opened-instance of the SRAM driver File drv_sram.h C void DRV_SRAM_Close(const DRV_HANDLE handle); Returns None Description This routine closes an opened-instance of the SRAM driver, invalidating the handle. Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_SRAM_Open before the caller may use the driver again. Usually there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_SRAM_Initialize routine must have been called for the specified SRAM driver instance. DRV_SRAM_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SRAM_Open DRV_SRAM_Close(handle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_SRAM_Close ( const DRV_HANDLE handle ); Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 953 DRV_SRAM_CommandStatus Function Gets the current status of the command. File drv_sram.h C DRV_SRAM_COMMAND_STATUS DRV_SRAM_CommandStatus(const DRV_HANDLE handle, const DRV_SRAM_COMMAND_HANDLE commandHandle); Returns A DRV_SRAM_COMMAND_STATUS value describing the current status of the command. Returns DRV_SRAM_COMMAND_COMPLETED if the client handle or the command handle is not valid. Description This routine gets the current status of the command. The application must use this routine where the status of a scheduled command needs to be polled on. The function may return DRV_SRAM_COMMAND_COMPLETED in a case where the command handle has expired. A command handle expires when the internal buffer object is re-assigned to another read or write request. It is recommended that this function be called regularly in order to track the command status correctly. The application can alternatively register an event handler to receive read or write operation completion events. Remarks This routine will not block for hardware access and will immediately return the current status. Preconditions The DRV_SRAM_Initialize() routine must have been called. The DRV_SRAM_Open() must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_SRAM_Open DRV_SRAM_COMMAND_HANDLE commandHandle; DRV_SRAM_COMMAND_STATUS status; status = DRV_SRAM_CommandStatus(handle, commandHandle); if(status == DRV_SRAM_COMMAND_COMPLETED) { // Operation Done } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function DRV_SRAM_COMMAND_STATUS DRV_SRAM_CommandStatus ( const DRV_HANDLE handle, const DRV_SRAM_COMMAND_HANDLE commandHandle ); DRV_SRAM_Deinitialize Function Deinitializes the specified instance of the SRAM driver module File drv_sram.h C void DRV_SRAM_Deinitialize(SYS_MODULE_OBJ object); Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 954 Returns None. Description Deinitializes the specified instance of the SRAM driver module, disabling its operation. Invalidates all the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. Preconditions Function DRV_SRAM_Initialize should have been called before calling this function. Parameter: object - Driver object handle, returned from the DRV_SRAM_Initialize routine Example // This code snippet shows an example of deinitializing the driver. SYS_MODULE_OBJ object; // Returned from DRV_SRAM_Initialize SYS_STATUS status; DRV_SRAM_Deinitialize(object); status = DRV_SRAM_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know when the driver is // deinitialized. } Function void DRV_SRAM_Deinitialize ( SYS_MODULE_OBJ object ); DRV_SRAM_EventHandlerSet Function Allows a client to identify an event handling function for the driver to call back when an operation has completed. File drv_sram.h C void DRV_SRAM_EventHandlerSet(const DRV_HANDLE handle, const void * eventHandler, const uintptr_t context); Returns None. Description This function allows a client to identify an event handling function for the driver to call back when an operation has completed. When a client calls a read or a write function, it is provided with a handle identifying the read/write request. The driver will pass this handle back to the client by calling "eventHandler" function when the operation has completed. The event handler should be set before the client performs any read or write operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued operation has completed, it does not need to register a callback. Preconditions The DRV_SRAM_Initialize() routine must have been called for the specified SRAM driver instance. The DRV_SRAM_Open() routine must have been called to obtain a valid opened device handle. Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 955 Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; uint8_t myBuffer[MY_BUFFER_SIZE]; uint32_t blockStart, nBlock; DRV_SRAM_COMMAND_HANDLE commandHandle; // drvSRAMHandle is the handle returned by the DRV_SRAM_Open function. // Client registers an event handler with driver. This is done once. DRV_SRAM_EventHandlerSet(drvSRAMHandle, APP_SRAMEventHandler, (uintptr_t)&myAppObj); DRV_SRAM_Read(drvSRAMHandle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_SRAM_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } // Event Processing Technique. Event is received when operation is done. void APP_SRAMEventHandler ( DRV_SRAM_EVENT event, DRV_SRAM_COMMAND_HANDLE handle, uintptr_t context ) { // The context handle was set to an application specific object. It is // now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) context; switch(event) { case DRV_SRAM_EVENT_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_SRAM_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function eventHandler Pointer to the event handler function implemented by the user context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_SRAM_EventHandlerSet ( const DRV_HANDLE handle, const void * eventHandler, const uintptr_t context ); Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 956 DRV_SRAM_GeometryGet Function Returns the geometry of the device. File drv_sram.h C SYS_FS_MEDIA_GEOMETRY * DRV_SRAM_GeometryGet(const DRV_HANDLE handle); Returns SYS_FS_MEDIA_GEOMETRY - Pointer to structure which holds the media geometry information. Description This API gives the following geometrical details of the SRAM memory: • Media Property • Number of Read/Write/Erase regions • Number of Blocks and their size in each region of the device Remarks None. Preconditions The DRV_SRAM_Initialize() routine must have been called for the specified SRAM driver instance. The DRV_SRAM_Open() routine must have been called to obtain a valid opened device handle. Example SYS_FS_MEDIA_GEOMETRY * sramGeometry; uint32_t readBlockSize, writeBlockSize, eraseBlockSize; uint32_t nReadBlocks, nReadRegions, totalSize; sramGeometry = DRV_SRAM_GeometryGet(sramOpenHandle1); readBlockSize = sramGeometry->geometryTable->blockSize; nReadBlocks = sramGeometry->geometryTable->numBlocks; nReadRegions = sramGeometry->numReadRegions; writeBlockSize = (sramGeometry->geometryTable +1)->blockSize; eraseBlockSize = (sramGeometry->geometryTable +2)->blockSize; totalSize = readBlockSize * nReadBlocks * nReadRegions; Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function SYS_FS_MEDIA_GEOMETRY * DRV_SRAM_GeometryGet ( const DRV_HANDLE handle ); DRV_SRAM_Initialize Function Initializes the SRAM instance for the specified driver index. File drv_sram.h C SYS_MODULE_OBJ DRV_SRAM_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 957 Returns If successful, returns a valid handle to a driver instance object. Otherwise it returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the SRAM driver instance for the specified driver index, making it ready for clients to open and use it. Remarks This routine must be called before any other SRAM routine is called. This routine should only be called once during system initialization unless DRV_SRAM_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. The system must use DRV_SRAM_Status to find out when the driver is in the ready state. Preconditions None. Example // This code snippet shows an example of initializing the SRAM Driver. SYS_MODULE_OBJ objectHandle; SYS_FS_MEDIA_REGION_GEOMETRY gSramGeometryTable[3] = { { // Read Region Geometry .blockSize = 512, .numBlocks = (DRV_SRAM_MEDIA_SIZE * (1024/512)), }, { // Write Region Geometry .blockSize = 512, .numBlocks = ((DRV_SRAM_MEDIA_SIZE * (1024/512)) }, { // Erase Region Geometry .blockSize = 512, .numBlocks = ((DRV_SRAM_MEDIA_SIZE * (1024/512)) } }; const SYS_FS_MEDIA_GEOMETRY gSramGeometry = { .mediaProperty = SYS_FS_MEDIA_WRITE_IS_BLOCKING, // Number of read, write and erase entries in the table .numReadRegions = 1, .numWriteRegions = 1, .numEraseRegions = 1, .geometryTable = &gSramGeometryTable }; // SRAM Driver Initialization Data const DRV_SRAM_INIT drvSramInit = { .mediaStartAddress = DRV_SRAM_MEDIA_START_ADDRESS, .sramMediaGeometry = &gSramGeometry }; objectHandle = DRV_SRAM_Initialize(DRV_SRAM_INDEX_0, (SYS_MODULE_INIT*)&drvSRAMInit); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized. Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 958 init Pointer to a data structure containing any data necessary to initialize the driver. Function SYS_MODULE_OBJ DRV_SRAM_Initialize ( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ); DRV_SRAM_IsAttached Function Returns the physical attach status of the SRAM. File drv_sram.h C bool DRV_SRAM_IsAttached(const DRV_HANDLE handle); Returns Returns false if the handle is invalid otherwise returns true. Description This function returns the physical attach status of the SRAM. Remarks None. Preconditions The DRV_SRAM_Initialize() routine must have been called for the specified SRAM driver instance. The DRV_SRAM_Open() routine must have been called to obtain a valid opened device handle. Example // The SRAM media is always attached and so the below always returns true. bool isSRAMAttached; isSRAMAttached = DRV_SRAM_isAttached(drvSRAMHandle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open Function bool DRV_SRAM_IsAttached ( const DRV_HANDLE handle ); DRV_SRAM_IsWriteProtected Function Returns the write protect status of the SRAM. File drv_sram.h C bool DRV_SRAM_IsWriteProtected(const DRV_HANDLE handle); Returns Always returns false. Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 959 Description This function returns the physical attach status of the SRAM. This function always returns false. Remarks None. Preconditions The DRV_SRAM_Initialize() routine must have been called for the specified SRAM driver instance. The DRV_SRAM_Open() routine must have been called to obtain a valid opened device handle. Example // The SRAM media is treated as always writeable. bool isWriteProtected; isWriteProtected = DRV_SRAM_IsWriteProtected(drvSRAMHandle); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function Function bool DRV_SRAM_IsWriteProtected ( const DRV_HANDLE handle ); DRV_SRAM_Open Function Opens the specified SRAM driver instance and returns a handle to it File drv_sram.h C DRV_HANDLE DRV_SRAM_Open(const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, DRV_HANDLE_INVALID is returned. Errors can occur under the following circumstances: • if the number of client objects allocated via DRV_SRAM_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the client is trying to open the driver exclusively, but has already been opened in a non exclusive mode by another client. • if the driver hardware instance being opened is invalid Description This routine opens the specified SRAM driver instance and provides a handle. This handle must be provided to all other client-level operations to identify the caller and the instance of the driver. Remarks The handle returned is valid until the DRV_SRAM_Close routine is called. This routine will NEVER block waiting for hardware. If the driver has has already been opened, it cannot be opened exclusively. Preconditions DRV_SRAM_Initialize must have been called before calling this function. Example DRV_HANDLE handle; Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 960 handle = DRV_SRAM_Open(DRV_SRAM_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver } Parameters Parameters Description index Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver Function DRV_HANDLE DRV_SRAM_Open ( const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent ); DRV_SRAM_Read Function Reads blocks of data from the specified block start address. File drv_sram.h C void DRV_SRAM_Read(const DRV_HANDLE handle, DRV_SRAM_COMMAND_HANDLE * commandHandle, void * targetBuffer, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It will be DRV_SRAM_COMMAND_HANDLE_INVALID if the request was not successful. Description This routine reads blocks of data from the specified block start address. This operation is blocking and returns with the required data in the target buffer. If a event handler has been registered to receive the driver events then the event handler will be called from within this function. The function returns DRV_SRAM_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if the driver handle is invalid • if the driver state is not ready • if the target buffer pointer is NULL • if the number of blocks to be read is zero or more than the actual number of blocks available • if the client opened the driver in write only mode Remarks None. Preconditions The DRV_SRAM_Initialize routine must have been called for the specified SRAM driver instance. DRV_SRAM_Open must have been called with DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE as the ioIntent to obtain a valid opened device handle. Example uint8_t myBuffer[MY_BUFFER_SIZE]; uint32_t blockStart = 0; uint32_t nBlock = 2; DRV_SRAM_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySRAMHandle is the handle returned by the DRV_SRAM_Open function. Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 961 DRV_SRAM_EventHandlerSet(mySRAMHandle, APP_SRAMEventHandler, (uintptr_t)&myAppObj); DRV_SRAM_Read(mySRAMHandle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_SRAM_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } else { // Read operation completed successfully. } // Event is invoked from within the DRV_SRAM_Read function when the read // operation processing is complete. void APP_SRAMEventHandler ( DRV_SRAM_EVENT event, DRV_SRAM_COMMAND_HANDLE commandHandle, uintptr_t contextHandle ) { // contextHandle points to myAppObj. switch(event) { case DRV_SRAM_EVENT_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_SRAM_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle targetBuffer Buffer into which the data read from the SRAM memory will be placed blockStart SRAM media's start block address from where the read should begin. nBlock Total number of blocks to be read. Function void DRV_SRAM_Read ( const DRV_HANDLE handle, DRV_SRAM_COMMAND_HANDLE * commandHandle, void * targetBuffer, uint32_t blockStart, uint32_t nBlock ); DRV_SRAM_Status Function Gets the current status of the SRAM driver module. File drv_sram.h Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 962 C SYS_STATUS DRV_SRAM_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is ready and accept requests for new operations. SYS_STATUS_UNINITIALIZED - Indicates the driver is not initialized. Description This routine provides the current status of the SRAM driver module. Remarks None. Preconditions Function DRV_SRAM_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_SRAM_Initialize SYS_STATUS SRAMStatus; SRAMStatus = DRV_SRAM_Status(object); if (SRAMStatus == SYS_STATUS_READY) { // Driver is ready to process read/write operations. } else { // Driver is not ready. } Parameters Parameters Description object Driver object handle, returned from the DRV_SRAM_Initialize routine Function SYS_STATUS DRV_SRAM_Status ( SYS_MODULE_OBJ object ); DRV_SRAM_Write Function Writes blocks of data starting from the specified block start address of the SRAM media. File drv_sram.h C void DRV_SRAM_Write(const DRV_HANDLE handle, DRV_SRAM_COMMAND_HANDLE * commandHandle, void * sourceBuffer, uint32_t blockStart, uint32_t nBlock); Returns The buffer handle is returned in the commandHandle argument. It will be DRV_SRAM_COMMAND_HANDLE_INVALID if the request was not successful. Description This routine writes blocks of data starting at the specified block start address. This operation is blocking and returns after having written the data. If a event handler has been registered to receive the driver events then the event handler will be called from within this function. The function returns DRV_SRAM_COMMAND_HANDLE_INVALID in the commandHandle argument under the following circumstances: • if the driver handle is invalid Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 963 • if the driver state is not ready • if the source buffer pointer is NULL • if the number of blocks to be written is zero or more than the actual number of blocks available • if the client opened the driver in read only mode Remarks None Preconditions The DRV_SRAM_Initialize() routine must have been called for the specified SRAM driver instance. DRV_SRAM_Open() routine must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified as a parameter to this routine. Example uint8_t myBuffer[MY_BUFFER_SIZE]; uint32_t blockStart = 2; uint32_t nBlock = 2; DRV_SRAM_COMMAND_HANDLE commandHandle; MY_APP_OBJ myAppObj; // mySRAMHandle is the handle returned by the DRV_SRAM_Open function. // Client registers an event handler with driver DRV_SRAM_EventHandlerSet(mySRAMHandle, APP_SRAMEventHandler, (uintptr_t)&myAppObj); DRV_SRAM_Write(mySRAMHandle, &commandHandle, &myBuffer, blockStart, nBlock); if(DRV_SRAM_COMMAND_HANDLE_INVALID == commandHandle) { // Error handling here } else { // Write completed successfully. } // Event is received from within the DRV_SRAM_Write function when the // buffer is processed. void APP_SRAMEventHandler ( DRV_SRAM_EVENT event, DRV_SRAM_COMMAND_HANDLE commandHandle, uintptr_t contextHandle ) { // contextHandle points to myAppObj. switch(event) { case DRV_SRAM_EVENT_COMMAND_COMPLETE: // This means the data was transferred. break; case DRV_SRAM_EVENT_COMMAND_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open function commandHandle Pointer to an argument that will contain the return buffer handle Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 964 sourceBuffer The source buffer containing data to be programmed into SRAM memory blockStart Start block address of SRAM media from where the write should begin. nBlock Total number of blocks to be written. Function void DRV_SRAM_Write ( const DRV_HANDLE handle, DRV_SRAM_COMMAND_HANDLE * commandHandle, void * sourceBuffer, uint32_t blockStart, uint32_t nBlock ); c) Data Types and Constants DRV_SRAM_COMMAND_HANDLE Type Handle identifying commands queued in the driver. File drv_sram.h C typedef SYS_FS_MEDIA_BLOCK_COMMAND_HANDLE DRV_SRAM_COMMAND_HANDLE; Description SRAM Driver command handle. A command handle is returned by a call to the Read or Write functions. This handle allows the application to track the completion of the operation. This command handle is also returned to the client along with the event that has occurred with respect to the command. This allows the application to connect the event to a specific command in case where multiple commands are queued. The command handle associated with the command request expires when the client has been notified of the completion of the command (after event handler function that notifies the client returns) or after the command has been retired by the driver if no event handler callback was set. Remarks None. DRV_SRAM_COMMAND_STATUS Enumeration Specifies the status of the command for the read and write operations. File drv_sram.h C typedef enum { DRV_SRAM_COMMAND_COMPLETED = SYS_FS_MEDIA_COMMAND_COMPLETED, DRV_SRAM_COMMAND_QUEUED = SYS_FS_MEDIA_COMMAND_QUEUED, DRV_SRAM_COMMAND_IN_PROGRESS = SYS_FS_MEDIA_COMMAND_IN_PROGRESS, DRV_SRAM_COMMAND_ERROR_UNKNOWN = SYS_FS_MEDIA_COMMAND_UNKNOWN } DRV_SRAM_COMMAND_STATUS; Members Members Description DRV_SRAM_COMMAND_COMPLETED = SYS_FS_MEDIA_COMMAND_COMPLETED Done OK and ready DRV_SRAM_COMMAND_QUEUED = SYS_FS_MEDIA_COMMAND_QUEUED Scheduled but not started DRV_SRAM_COMMAND_IN_PROGRESS = SYS_FS_MEDIA_COMMAND_IN_PROGRESS Currently being in transfer Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 965 DRV_SRAM_COMMAND_ERROR_UNKNOWN = SYS_FS_MEDIA_COMMAND_UNKNOWN Unknown Command Description SRAM Driver Command Status SRAM Driver command Status This type specifies the status of the command for the read and write operations. Remarks None. DRV_SRAM_EVENT Enumeration Identifies the possible events that can result from a request. File drv_sram.h C typedef enum { DRV_SRAM_EVENT_COMMAND_COMPLETE = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_COMPLETE, DRV_SRAM_EVENT_COMMAND_ERROR = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_ERROR } DRV_SRAM_EVENT; Members Members Description DRV_SRAM_EVENT_COMMAND_COMPLETE = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_COMPLETE Operation has been completed successfully. DRV_SRAM_EVENT_COMMAND_ERROR = SYS_FS_MEDIA_EVENT_BLOCK_COMMAND_ERROR There was an error during the operation Description SRAM Driver Events This enumeration identifies the possible events that can result from a read or a write request caused by the client. Remarks One of these values is passed in the "event" parameter of the event handling callback function that client registered with the driver by calling the DRV_SRAM_EventHandlerSet function when a request is completed. DRV_SRAM_EVENT_HANDLER Type Pointer to a SRAM Driver Event handler function File drv_sram.h C typedef SYS_FS_MEDIA_EVENT_HANDLER DRV_SRAM_EVENT_HANDLER; Returns None. Description SRAM Driver Event Handler Function Pointer This data type defines the required function signature for the SRAM event handling callback function. A client must register a pointer to an event handling function whose function signature (parameter and return value types) match the types specified by this function pointer in order to receive event callbacks from the driver. The parameters and return values are described here and a partial example implementation is provided. Remarks If the event is DRV_SRAM_EVENT_COMMAND_COMPLETE, it means that the read or write operation was completed successfully. Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 966 If the event is DRV_SRAM_EVENT_COMMAND_ERROR, it means that the scheduled operation was not completed successfully. The context parameter contains the handle to the client context, provided at the time the event handling function was registered using the DRV_SRAM_EventHandlerSet function. This context handle value is passed back to the client as the "context" parameter. It can be any value necessary to identify the client context or instance (such as a pointer to the client's data) instance of the client that made the read/write request. The event handler function executes in the driver's context. It is recommended of the application to not perform process intensive or blocking operations within this function. Example void APP_MySramEventHandler ( DRV_SRAM_EVENT event, DRV_SRAM_COMMAND_HANDLE commandHandle, uintptr_t context ) { MY_APP_DATA_STRUCT pAppData = (MY_APP_DATA_STRUCT) context; switch(event) { case DRV_SRAM_EVENT_COMMAND_COMPLETE: // Handle the completed buffer. break; case DRV_SRAM_EVENT_COMMAND_ERROR: default: // Handle error. break; } } Parameters Parameters Description event Identifies the type of event commandHandle Handle returned from the Read/Write requests context Value identifying the context of the application that registered the event handling function DRV_SRAM_INIT Structure Defines the data required to initialize the SRAM driver File drv_sram.h C typedef struct { bool registerWithFs; uint8_t* mediaStartAddress; const SYS_FS_MEDIA_GEOMETRY * sramMediaGeometry; } DRV_SRAM_INIT; Members Members Description bool registerWithFs; Flag to indicate if the driver is to be registered with the file system. uint8_t* mediaStartAddress; SRAM Media start address. The driver treats this address as block 0 • address for read and write operations. const SYS_FS_MEDIA_GEOMETRY * sramMediaGeometry; SRAM Media geometry object. Description SRAM Driver Initialization Data This data type defines the data required to initialize the SRAM driver. Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 967 Remarks None. _DRV_SRAM_H Macro File drv_sram.h C #define _DRV_SRAM_H Description This is macro _DRV_SRAM_H. DRV_SRAM_COMMAND_HANDLE_INVALID Macro This value defines the SRAM Driver's Invalid Command Handle. File drv_sram.h C #define DRV_SRAM_COMMAND_HANDLE_INVALID SYS_FS_MEDIA_BLOCK_COMMAND_HANDLE_INVALID Description SRAM Driver Invalid Command Handle. This value defines the SRAM Driver Invalid Command Handle. This value is returned by read/write routines when the command request is not accepted. Remarks None. DRV_SRAM_INDEX_0 Macro SRAM driver index definitions File drv_sram.h C #define DRV_SRAM_INDEX_0 0 Description Driver SRAM Module Index reference These constants provide SRAM driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_SRAM_Initialize and DRV_SRAM_Open routines to identify the driver instance in use. DRV_SRAM_INDEX_1 Macro File drv_sram.h C #define DRV_SRAM_INDEX_1 1 Description This is macro DRV_SRAM_INDEX_1. Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 968 Files Files Name Description drv_sram.h SRAM Driver Interface Definition Description This section will list only the library's interface header file(s). drv_sram.h SRAM Driver Interface Definition Enumerations Name Description DRV_SRAM_COMMAND_STATUS Specifies the status of the command for the read and write operations. DRV_SRAM_EVENT Identifies the possible events that can result from a request. Functions Name Description DRV_SRAM_AddressGet Returns the SRAM media start address DRV_SRAM_Close Closes an opened-instance of the SRAM driver DRV_SRAM_CommandStatus Gets the current status of the command. DRV_SRAM_Deinitialize Deinitializes the specified instance of the SRAM driver module DRV_SRAM_EventHandlerSet Allows a client to identify an event handling function for the driver to call back when an operation has completed. DRV_SRAM_GeometryGet Returns the geometry of the device. DRV_SRAM_Initialize Initializes the SRAM instance for the specified driver index. DRV_SRAM_IsAttached Returns the physical attach status of the SRAM. DRV_SRAM_IsWriteProtected Returns the write protect status of the SRAM. DRV_SRAM_Open Opens the specified SRAM driver instance and returns a handle to it DRV_SRAM_Read Reads blocks of data from the specified block start address. DRV_SRAM_Status Gets the current status of the SRAM driver module. DRV_SRAM_Write Writes blocks of data starting from the specified block start address of the SRAM media. Macros Name Description _DRV_SRAM_H This is macro _DRV_SRAM_H. DRV_SRAM_COMMAND_HANDLE_INVALID This value defines the SRAM Driver's Invalid Command Handle. DRV_SRAM_INDEX_0 SRAM driver index definitions DRV_SRAM_INDEX_1 This is macro DRV_SRAM_INDEX_1. Structures Name Description DRV_SRAM_INIT Defines the data required to initialize the SRAM driver Types Name Description DRV_SRAM_COMMAND_HANDLE Handle identifying commands queued in the driver. DRV_SRAM_EVENT_HANDLER Pointer to a SRAM Driver Event handler function Description SRAM Driver Interface Definition The SRAM driver provides a simple interface to manage the SRAM Memory on Microchip microcontrollers. This file defines the interface definition for the SRAM driver. Volume V: MPLAB Harmony Framework Driver Libraries Help SRAM Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 969 File Name drv_sram.h Company Microchip Technology Inc. Timer Driver Library This section describes the Timer Driver Library. Introduction This library provides an interface to manage the Timer module on the Microchip family of microcontrollers during different modes of operation. Description 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 and accurate hardware delays. Note: Not all features are available on all devices. Please refer to the specific device data sheet to determine availability. Using the Library This topic describes the basic architecture of the Timer Driver Library and provides information and examples on its use. Description Interface Header File: drv_tmr.h The interface to the Timer Driver Library is defined in the drv_tmr.h header file. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model The Timer Driver abstracts the hardware by providing the capability to register callback functions to the application. Description Abstraction Model The abstraction model of the Timer Driver is explained in the following diagram: The core functionality of the Timer allows access to both the counter and the period values. Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the Timer Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 970 Library Interface Section Description Configuration Provides macros for configuring the system. It is required that the system configures the driver to build correctly by choosing appropriate configuration options as listed in this section. These macros enable different features or modes of the timer peripheral. System Interaction Functions Provides interfaces to system_layer to initialize, deinitialize and reinitialize the module. This section also describes functions to query the status of the module. Core Functions Provides interfaces for core functionality of the driver. Alarm Functions Provides interfaces to handle alarm features, if alarm functionality is enabled. Period Functions Provides interfaces to control the periodicity of the timers. Counter Control Functions Provides interfaces to update the counter values. Miscellaneous Functions Provides interfaces to get the version information, timer tick and operating frequencies. How the Library Works The library provides interfaces to support: • System Interaction • Sync Mode Setup • Period Modification • Counter Modification • Client Core Functionality • Client Alarm Functionality (optional function, enabled using configuration options) • Other Optional Functionality (enabled using configuration options) Note: Any code segment pertaining to the driver interfaces will work for both the static or dynamic configurations. It is not necessary to modify the code to move from one configuration to the other (i.e., from static or dynamic or static-multi). System Interaction This section describes Timer initialization and reinitialization. Description Initialization and Reinitialization The system performs the initialization of the device driver with settings that affect only the instance of the device that is being initialized. The DRV_TMR_Initialize function returns an object handle of the type SYS_MODULE_OBJ. After this, the object handle returned by the Initialize interface would be used by the other system interfaces such as DRV_TMR_Deinitialize and DRV_TMR_Status, DRV_TMR_Tasks. Example: Timer Initialization DRV_TMR_INIT init; SYS_MODULE_OBJ object; SYS_STATUS tmrStatus; // populate the TMR init configuration structure init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.tmrId = TMR_ID_2; init.clockSource = TMR_CLOCK_SOURCE_PERIPHERAL_CLOCK; init.prescale = TMR_PRESCALE_VALUE_256; init.interruptSource = INT_SOURCE_TIMER_2; init.mode = DRV_TMR_OPERATION_MODE_16_BIT; init.asyncWriteEnable = false; object = DRV_TMR_Initialize (DRV_TMR_INDEX_0, (SYS_MODULE_INIT *)&init); if (object == SYS_MODULE_OBJ_INVALID) { // Handle error } Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 971 Deinitialization Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This routine may block if the driver is running in an OS environment that supports blocking operations and the driver requires system resources access. However, the routine will never block for hardware Timer access. Status Timer status is available to query the module state after initialization and reinitialization. Tasks Routine The interface DRV_TMR_Tasks needs to be called by the system task service in a polled environment and in an interrupt-based system. Example: Polling int main( void ) { SYS_MODULE_OBJ object; object = DRV_TMR_Initialize( DRV_TMR_INDEX_0, (SYS_MODULE_INIT *) &initConf ); if( SYS_STATUS_READY != DRV_TMR_Status( object ) ) return 0; while (1) { DRV_TMR_Tasks (object); } } Example: Interrupt int main( void ) { SYS_MODULE_OBJ object; object = DRV_TMR_Initialize( DRV_TMR_INDEX_0, (SYS_MODULE_INIT *) &initConf ); if( SYS_STATUS_READY != DRV_TMR_Status( object ) ) return 0; while (1); } /* Sample interrupt routine not specific to any device family */ void ISR T1Interrupt(void) { //Call the Timer Tasks routine DRV_TMR_Tasks(object); } Client Interaction This section describes general client operation. Description General Client Operation For the application to begin using an instance of the Timer module, it must call the DRV_TMR_Open function. This provides the configuration required to open the Timer instance for operation. The Timer Driver supports only the 'DRV_IO_INTENT_EXCLUSIVE' IO_INTENT. Example: DRV_HANDLE handle; // Configure the instance DRV_TMR_INDEX_1 with the configuration handle = DRV_TMR_Open(DRV_TMR_INDEX_1, DRV_IO_INTENT_EXCLUSIVE); if( handle == DRV_HANDLE_INVALID ) { // Client cannot open the instance. } The function DRV_TMR_Close closes an already opened instance of the Timer Driver, invalidating the handle. DRV_TMR_Open must have been Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 972 called to obtain a valid opened device handle. Example: DRV_HANDLE handle; // Configure the instance DRV_TMR_INDEX_1 with the configuration handle = DRV_TMR_Open(DRV_TMR_INDEX_1, DRV_IO_INTENT_EXCLUSIVE); /*...*/ DRV_TMR_Close( handle ); The client has the option to check the status through the interface DRV_TMR_ClientStatus. Example: DRV_HANDLE handle; // Configure the instance DRV_TMR_INDEX_1 with the configuration handle = DRV_TMR_Open(DRV_TMR_INDEX_1, DRV_IO_INTENT_EXCLUSIVE); if ( DRV_TMR_CLIENT_STATUS_READY != DRV_TMR_ClientStatus( handle ) ) return 0; Modification This section describes Period modification for the different types of Timers (i.e., 16-/32-bit). Description These set of functions help modify the Timer periodicity at the client level. Period Modification Periodicity of Timer (16/32-bit) can be modified using DRV_TMR_AlarmPeriodSet and the current period can be obtained using DRV_TMR_AlarmPeriodGet. Example: DRV_HANDLE handle; /* Open the client */ handle = DRV_TMR_Open( DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); /* ... */ /* Update the new period */ DRV_TMR_AlarmPeriodSet( handle, 0xC350); Counter Modification This section describes counter modification for the different types of Timers (i.e., 8-/16-/32-bit). Description These set of functions help modify the initial value of the Timer counters to help adjust any errors in the periodicity. Counter Modification The Timer initial value can be modified using DRV_TMR_CounterValueSet and the current counter value can be obtained using DRV_TMR_CounterValueGet. Example: DRV_HANDLE handle; /* Open the client */ handle = DRV_TMR_Open( DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); /* ... */ /* Update the counter value */ /* Following code updates the initial value from 0x0000 to 0x0010 to cover up any error in the previously set periodicity */ DRV_TMR_CounterValueSet( handle, 0x0010); Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 973 Core Functionality This section describes core functionality of the Timer Driver. Description Core functionality provides an extremely basic interface for the driver operation. Applications using the Timer core functionality need to perform the following: 1. The system should have completed the necessary initialization and DRV_TMR_Tasks should be called in a polled/interrupt environment. 2. Open_the driver using DRV_TMR_Open. The Timer Driver only supports exclusive access. 3. The Timer can be updated using DRV_TMR_AlarmPeriodSet. The previously set value can be retrieved using DRV_TMR_AlarmPeriodGet. 4. Start the driver using DRV_TMR_Start. 5. Poll for the elapsed alarm status using DRV_TMR_AlarmHasElapsed. 6. The client will be able to stop the started Timer instance using DRV_TMR_Stop at any time and will be able to close it using DRV_TMR_Close when it is no longer required. Example: /* Open the client */ handle = DRV_TMR_Open( DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); DRV_TMR_Start (handle); unsigned int alarmCount = 0; while (1) { if (true == DRV_TMR_AlarmHasElapsed (handle)) { alarmCount++; // Do something } } Notes: 1. The user needs to stop the Timer before any updates on the counter or period and restart it later. 2. The Timer alarm count gets reset after any call to DRV_TMR_AlarmHasElapsed. 3. The Timer alarm status remains unchanged if the user stops the timer and restarts later. Alarm Functionality This section describes the Timer Driver alarm functionality. Description The Timer Driver provides alarm functionality. Applications using the Timer alarm functionality, need to perform the following: 1. The system should have completed the necessary initialization and DRV_TMR_Tasks should be running in either a polled environment or in an interrupt environment. 2. Open_the driver using DRV_TMR_Open. The Timer Driver supports exclusive access only. 3. Configure the alarm using DRV_TMR_AlarmRegister. 4. Start the driver using DRV_TMR_Start. 5. If a callback is supplied, the Timer Driver will call the callback function when the alarm expires. 6. The client will be able to stop the started Timer module instance using DRV_TMR_Stop at any time and will be able to close it using DRV_TMR_Close when it is no longer required. 7. The client can deregister the callback by using DRV_TMR_AlarmDeregister. Example: DRV_HANDLE handle; /* Open the client */ handle = DRV_TMR_Open (DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); /* Configure the timer alarm feature */ uint32_t myFreq = 1000; // 1KHz uint32_t clkFreq = DRV_TMR_CounterFrequencyGet(tmrHandle); // timer running frequency // calculate the divider needed uint32_t divider = clkFreq / myFreq; // Start the alarm if(!DRV_TMR_AlarmRegister ( tmrHandle, divider, true, 0, CallBackFreq )) Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 974 { // divider value could not be obtain; // handle the error // return; } DRV_TMR_Start (handle); // The driver tasks function calls the client registered callback after the alarm expires. void CallBackFreq (uintptr_t context, uint32_t alarmCount) { // Do something specific on an alarm event trigger } Optional Interfaces This section describes additional/optional client interfaces. Description Additional/Optional client interfaces include the following: Get Operating Frequency The function DRV_TMR_CounterFrequencyGet provides the client with the information on the Timer operating frequency. Example: DRV_HANDLE handle; uint32_t freq; /* Open the client */ handle = DRV_TMR_Open (DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); freq = DRV_TMR_OperatingFrequencyGet (handle); Example Usage of the Timer Driver This section describes typical usage of the Timer Driver for various Timer modules in polling/interrupt advanced/core modes. Description The user can pass NULL to the driver initialize interface. However, the respective configuration parameters need to be configured in the correct manner. Example: //Polled mode under 32-bit count mode for a PIC32 device using the alarm feature SYS_MODULE_OBJ object; // main DRV_TMR_INIT init; DRV_HANDLE handle; init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.tmrId = TMR_ID_2; init.clockSource = TMR_CLKSOURCE_INTERNAL; init.prescale = TMR_PRESCALE_TX_VALUE_256; init.interruptSource = INT_SOURCE_TIMER_3; init.mode = DRV_TMR_OPERATION_MODE_16_BIT;init.asyncWriteEnable = false; object = DRV_TMR_Initialize (DRV_TMR_INDEX_0, (SYS_MODULE_INIT *)&init); if ( SYS_STATUS_READY != DRV_TMR_Status(object)) return 0; handle = DRV_TMR_Open (DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if ( DRV_TMR_CLIENT_STATUS_READY != DRV_TMR_ClientStatus(handle)) return 0; if(!DRV_TMR_AlarmRegister ( tmrHandle, divider, true, 0, AlarmCallback )) { // divider value could not be obtain; Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 975 // handle the error } DRV_TMR_Start (handle); while (1) { DRV_TMR_Tasks (object); } DRV_TMR_Stop (handle); DRV_TMR_Close (handle); if ( DRV_TMR_CLIENT_STATUS_INVALID != DRV_TMR_ClientStatus(handle)) return 0; DRV_TMR_Deinitialize (object); // end main void AlarmCallback (uintptr_t context, uint32_t alarmCount) { // Do something specific on an alarm event trigger } Configuring the Library Macros Name Description DRV_TMR_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported by the dynamic driver. DRV_TMR_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_TMR_CLOCK_PRESCALER Sets the default timer driver clock prescaler. DRV_TMR_MODE Sets the default timer driver clock operating mode. DRV_TMR_MODULE_ID Sets the default timer module ID to be used by the timer driver. DRV_TMR_MODULE_INIT Sets the default module init value for the timer driver. DRV_TMR_INTERRUPT_SOURCE Sets the default timer driver clock interrupt source DRV_TMR_ASYNC_WRITE_ENABLE Controls Asynchronous Write mode of the Timer. DRV_TMR_CLOCK_SOURCE Sets the default timer driver clock source. DRV_TMR_CLIENTS_NUMBER Sets up the maximum number of clients that can be supported by an instance of the dynamic driver. Description The configuration of the Timer Driver Library is based on the file system_config.h. This header file contains the configuration selection for the Timer Driver Library build. Based on the selections made here and the system setup, the Timer Driver may support the selected features. These configuration settings will apply to all instances of the driver. This header can be placed anywhere in the application-specific folders and the path of this header needs to be presented to the include search for a successful build. Refer to the Applications Help section for more details. DRV_TMR_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported by the dynamic driver. File drv_tmr_config_template.h C #define DRV_TMR_INSTANCES_NUMBER 5 Description Hardware instances support This definition sets up the maximum number of hardware instances that can be supported by the dynamic driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 976 Remarks None DRV_TMR_INTERRUPT_MODE Macro Controls operation of the driver in the interrupt or polled mode. File drv_tmr_config_template.h C #define DRV_TMR_INTERRUPT_MODE true Description TMR Interrupt And Polled Mode Operation Control This macro controls the operation of the driver in the interrupt mode of operation. The possible values of this macro are: • true - Select if interrupt mode of timer operation is desired • false - Select if polling mode of timer operation is desired Not defining this option to true or false will result in a build error. Remarks None. DRV_TMR_CLOCK_PRESCALER Macro Sets the default timer driver clock prescaler. File drv_tmr_config_template.h C #define DRV_TMR_CLOCK_PRESCALER (TMR_PRESCALE_VALUE_256) Description Default timer driver clock prescaler This macro sets the default timer driver clock prescaler. Remarks This value can be overridden by a run time initialization value. DRV_TMR_MODE Macro Sets the default timer driver clock operating mode. File drv_tmr_config_template.h C #define DRV_TMR_MODE (DRV_TMR_OPERATION_MODE_16_BIT) Description Default timer driver clock operating mode This macro sets the default timer driver clock operating mode. Remarks This value can be overridden by a run time initialization value. Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 977 DRV_TMR_MODULE_ID Macro Sets the default timer module ID to be used by the timer driver. File drv_tmr_config_template.h C #define DRV_TMR_MODULE_ID (TMR_ID_2) Description Default timer driver index This macro sets the default timer module ID to be used by the timer driver. Remarks This value can be overridden by a run time initialization value. DRV_TMR_MODULE_INIT Macro Sets the default module init value for the timer driver. File drv_tmr_config_template.h C #define DRV_TMR_MODULE_INIT (SYS_MODULE_POWER_RUN_FULL) Description Default module init object configuration This macro sets the default module init value for the timer driver. Remarks This value can be overridden by a run time initialization value. DRV_TMR_INTERRUPT_SOURCE Macro Sets the default timer driver clock interrupt source File drv_tmr_config_template.h C #define DRV_TMR_INTERRUPT_SOURCE (INT_SOURCE_TIMER_2) Description Default timer driver clock interrupt source This macro sets the default timer driver clock interrupt source Remarks This value can be overridden by a run time initialization value. DRV_TMR_ASYNC_WRITE_ENABLE Macro Controls Asynchronous Write mode of the Timer. File drv_tmr_config_template.h C #define DRV_TMR_ASYNC_WRITE_ENABLE false Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 978 Description TMR Asynchronous write mode configuration This macro controls the Asynchronous Write mode of the Timer. This macro accepts the following values: • true - Configures the Timer to enable asynchronous write control • false - Configures the Timer to disable asynchronous write control • DRV_CONFIG_NOT_SUPPORTED - When the feature is not supported on the instance. Remarks This feature is not available in all modules/devices. Refer to the specific device data sheet for more information. DRV_TMR_CLOCK_SOURCE Macro Sets the default timer driver clock source. File drv_tmr_config_template.h C #define DRV_TMR_CLOCK_SOURCE (DRV_TMR_CLKSOURCE_INTERNAL) Description Default timer driver clock source This macro sets the default timer driver clock source. Remarks This value can be overridden by a run time initialization value. DRV_TMR_CLIENTS_NUMBER Macro Sets up the maximum number of clients that can be supported by an instance of the dynamic driver. File drv_tmr_config_template.h C #define DRV_TMR_CLIENTS_NUMBER 1 Description Client instances support This definition sets up the maximum number of clients that can be supported by an instance of the dynamic driver. Remarks Currently each client is required to get exclusive access to the timer module. Therfore the DRV_TMR_CLIENTS_NUMBER should always be set to 1. Building the Library This section lists the files that are available in the Timer Driver Library. Description This section list the files that are available in the \src folder of the Timer 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. 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 /framework/driver/tmr. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 979 Source File Name Description /drv_tmr.h Header file that exports the driver API. 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 /src/dynamic/drv_tmr_dynamic.c Basic Timer driver implementation file. 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 N/A No optional files are available for this library Module Dependencies The Timer Driver Library depends on the following modules: • Clock System Service Library • Interrupt System Service Library • Interrupt Peripheral Library • Device Control System Service Library Library Interface a) System Interaction Functions Name Description DRV_TMR_Deinitialize Deinitializes the specified instance of the Timer driver. Implementation: Dynamic DRV_TMR_Initialize Initializes the Timer driver. Implementation: Static/Dynamic DRV_TMR_Status Provides the current status of the Timer driver. Implementation: Dynamic DRV_TMR_Tasks Maintains the driver's state machine. Implementation: Dynamic DRV_TMR_ClockSet Sets the timers clock by selecting the source and prescaler. Implementation: Dynamic DRV_TMR_GateModeSet Enables the Gate mode. Implementation: Dynamic b) Core Functions Name Description DRV_TMR_ClientStatus Gets the status of the client operation. Implementation: Dynamic DRV_TMR_Close Closes an opened instance of the Timer driver. Implementation: Dynamic DRV_TMR_Open Opens the specified Timer driver instance and returns a handle to it. Implementation: Dynamic DRV_TMR_Start Starts the Timer counting. Implementation: Static/Dynamic DRV_TMR_Stop Stops the Timer from counting. Implementation: Static/Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 980 c) Alarm Functions Name Description DRV_TMR_AlarmHasElapsed Provides the status of Timer's period elapse. Implementation: Dynamic DRV_TMR_AlarmDisable Disables an alarm signal. Implementation: Dynamic DRV_TMR_AlarmEnable Re-enables an alarm signal. Implementation: Dynamic DRV_TMR_AlarmDeregister Removes a previously set alarm. Implementation: Dynamic DRV_TMR_AlarmPeriodGet Provides the Timer's period. Implementation: Dynamic DRV_TMR_AlarmPeriodSet Updates the Timer's period. Implementation: Dynamic DRV_TMR_AlarmRegister Sets up an alarm. Implementation: Dynamic d) Counter Control Functions Name Description DRV_TMR_CounterFrequencyGet Provides the Timer input frequency. Implementation: Dynamic DRV_TMR_CounterClear Clears the Timer's counter register. Implementation: Static/Dynamic DRV_TMR_CounterValueGet Reads the Timer's counter register. Implementation: Static/Dynamic DRV_TMR_CounterValueSet Updates the Timer's counter register. Implementation: Static/Dynamic e) Miscellaneous Functions Name Description DRV_TMR_GateModeClear Enables the Gate mode. Implementation: Dynamic DRV_TMR_PrescalerGet This function gets the currently selected prescaler. Implementation: Dynamic DRV_TMR_OperationModeGet This function gets the currently selected operation mode. Implementation: Dynamic DRV_TMR_DividerRangeGet Returns the Timer divider values. Implementation: Dynamic f) Data Types and Constants Name Description DRV_TMR_CALLBACK Pointer to a Timer driver callback function data type. DRV_TMR_INIT Defines the Timer driver initialization data. DRV_TMR_CLIENT_STATUS Identifies the client-specific status of the Timer driver DRV_TMR_DIVIDER_RANGE This data structure specifies the divider values that can be obtained by the timer module. DRV_TMR_OPERATION_MODE Lists the operation modes available for timer driver. DRV_TMR_INDEX_COUNT Number of valid Timer driver indices. DRV_TMR_INDEX_0 Timer driver index definitions DRV_TMR_INDEX_1 This is macro DRV_TMR_INDEX_1. DRV_TMR_INDEX_2 This is macro DRV_TMR_INDEX_2. DRV_TMR_INDEX_3 This is macro DRV_TMR_INDEX_3. DRV_TMR_INDEX_4 This is macro DRV_TMR_INDEX_4. DRV_TMR_INDEX_5 This is macro DRV_TMR_INDEX_5. DRV_TMR_INDEX_6 This is macro DRV_TMR_INDEX_6. DRV_TMR_INDEX_7 This is macro DRV_TMR_INDEX_7. DRV_TMR_INDEX_8 This is macro DRV_TMR_INDEX_8. Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 981 DRV_TMR_INDEX_9 This is macro DRV_TMR_INDEX_9. DRV_TMR_INDEX_10 This is macro DRV_TMR_INDEX_10. DRV_TMR_INDEX_11 This is macro DRV_TMR_INDEX_11. Description This section describes the functions of the Timer Driver Library. Refer to each section for a detailed description. a) System Interaction Functions DRV_TMR_Deinitialize Function Deinitializes the specified instance of the Timer driver. Implementation: Dynamic File drv_tmr.h C void DRV_TMR_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the Timer driver, disabling its operation (and any hardware). All internal data is invalidated. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_TMR_Status operation. The system has to use DRV_TMR_Status to find out when the module is in the ready state. Preconditions The DRV_TMR_Initialize function must have been called before calling this function and a valid SYS_MODULE_OBJ must have been returned. Example SYS_MODULE_OBJ tmrObject; // Returned from DRV_TMR_Initialize SYS_STATUS tmrStatus; DRV_TMR_Deinitialize ( tmrObject ); tmrStatus = DRV_TMR_Status ( tmrObject ); if ( SYS_MODULE_UNINITIALIZED == tmrStatus ) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from DRV_TMR_Initialize Function void DRV_TMR_Deinitialize ( SYS_MODULE_OBJ object ) DRV_TMR_Initialize Function Initializes the Timer driver. Implementation: Static/Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 982 File drv_tmr.h C SYS_MODULE_OBJ DRV_TMR_Initialize(const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver object. Otherwise, it returns SYS_MODULE_OBJ_INVALID. The returned object must be passed as argument to DRV_TMR_Deinitialize, DRV_TMR_Tasks and DRV_TMR_Status functions. Description This function initializes the Timer driver, making it ready for clients to open and use it. Remarks This function must be called before any other Timer driver function is called. This function should only be called once during system initialization unless DRV_TMR_Deinitialize is called to deinitialize the driver instance. This function will NEVER block for hardware access. The system must use DRV_TMR_Status to find out when the driver is in the ready state. Build configuration options may be used to statically override options in the "init" structure and will take precedence over initialization data passed using this function. Preconditions None. Example DRV_TMR_INIT init; SYS_MODULE_OBJ objectHandle; // Populate the timer initialization structure init.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; init.tmrId = TMR_ID_2; init.clockSource = DRV_TMR_CLKSOURCE_INTERNAL; init.prescale = TMR_PRESCALE_VALUE_256; init.interruptSource = INT_SOURCE_TIMER_2; init.mode = DRV_TMR_OPERATION_MODE_16_BIT; init.asyncWriteEnable = false; // Do something objectHandle = DRV_TMR_Initialize ( DRV_TMR_INDEX_0, (SYS_MODULE_INIT*)&init ); if ( SYS_MODULE_OBJ_INVALID == objectHandle ) { // Handle error } Parameters Parameters Description drvIndex Index for the driver instance to be initialized init Pointer to a data structure containing any data necessary to initialize the driver. Function SYS_MODULE_OBJ DRV_TMR_Initialize ( const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init ) DRV_TMR_Status Function Provides the current status of the Timer driver. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 983 File drv_tmr.h C SYS_STATUS DRV_TMR_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is initialized and ready for operation Description This function provides the current status of the Timer driver. Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_STATUS_ERROR - Indicates that the driver is in an error state Any value less than SYS_STATUS_ERROR is also an error state. SYS_MODULE_UNINITIALIZED - Indicates that the driver has been deinitialized This value is less than SYS_STATUS_ERROR. The this operation can be used to determine when any of the driver's module level operations has completed. Once the status operation returns SYS_STATUS_READY, the driver is ready for operation. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This function will NEVER block waiting for hardware. Preconditions The DRV_TMR_Initialize function must have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_TMR_Initialize SYS_STATUS tmrStatus; tmrStatus = DRV_TMR_Status ( object ); else if ( SYS_STATUS_ERROR >= tmrStatus ) { // Handle error } Parameters Parameters Description object Driver object handle, returned from DRV_TMR_Initialize Function SYS_STATUS DRV_TMR_Status ( SYS_MODULE_OBJ object ) DRV_TMR_Tasks Function Maintains the driver's state machine. Implementation: Dynamic File drv_tmr.h C void DRV_TMR_Tasks(SYS_MODULE_OBJ object); Returns None Description This function is used to maintain the driver's internal state machine and processes the timer events.. Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 984 Remarks This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) Preconditions The DRV_TMR_Initialize function must have been called for the specified Timer driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_TMR_Initialize while (true) { DRV_TMR_Tasks ( object ); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_TMR_Initialize) Function void DRV_TMR_Tasks ( SYS_MODULE_OBJ object ) DRV_TMR_ClockSet Function Sets the timers clock by selecting the source and prescaler. Implementation: Dynamic File drv_tmr.h C bool DRV_TMR_ClockSet(DRV_HANDLE handle, DRV_TMR_CLK_SOURCES clockSource, TMR_PRESCALE preScale); Returns • true - if the operation is successful • false - either the handle is invalid or the clockSource and/or prescaler are not supported Description This function sets the timer clock by selecting the source and prescaler. The clock sources are device specific, refer device datasheet for supported clock sources. If unsupported clock source is passed then the behaviour of this function is unpredictable. Remarks None. Preconditions The DRV_TMR_Initialize function must have been called. Must have selected 32-Bit timer mode if mode selection is applicable. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE tmrHandle; // Returned from DRV_TMR_Open DRV_TMR_ClockSet ( tmrHandle, DRV_TMR_CLKSOURCE_INTERNAL, TMR_PRESCALE_VALUE_256 ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine clockSource Clock source of the timer preScale Timer's Prescaler divisor Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 985 Function bool DRV_TMR_ClockSet ( DRV_HANDLE handle, DRV_TMR_CLK_SOURCES clockSource, TMR_PRESCALE preScale ) DRV_TMR_GateModeSet Function Enables the Gate mode. Implementation: Dynamic File drv_tmr.h C bool DRV_TMR_GateModeSet(DRV_HANDLE handle); Returns • true - if the operation is successful • false - either the handle is invalid or the gate mode is not supported Description This function enables the Gated mode of Timer. User can measure the duration of an external signal in this mode. Once the Gate mode is enabled, Timer will start on the raising edge of the external signal. It will keep counting until the next falling edge. Remarks None. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE tmrHandle; // Returned from DRV_TMR_Open DRV_TMR_GateModeSet ( tmrHandle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function bool DRV_TMR_GateModeSet ( DRV_HANDLE handle ) b) Core Functions DRV_TMR_ClientStatus Function Gets the status of the client operation. Implementation: Dynamic File drv_tmr.h C DRV_TMR_CLIENT_STATUS DRV_TMR_ClientStatus(DRV_HANDLE handle); Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 986 Returns None Description This function gets the status of the recently completed client level operation. Remarks None. Preconditions The DRV_TMR_Initialize function must have been called for the specified Timer driver instance. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE tmrHandle; // Returned from DRV_TMR_Open DRV_TMR_CLIENT_STATUS tmrDrvStatus; tmrDrvStatus = DRV_TMR_ClientStatus ( tmrHandle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function DRV_TMR_CLIENT_STATUS DRV_TMR_ClientStatus ( DRV_HANDLE handle ) DRV_TMR_Close Function Closes an opened instance of the Timer driver. Implementation: Dynamic File drv_tmr.h C void DRV_TMR_Close(DRV_HANDLE handle); Returns None Description This function closes an opened instance of the Timer driver, invalidating the handle. Remarks After calling this function, the handle passed in "handle" must not be used with any of the remaining driver functions. A new handle must be obtained by calling DRV_TMR_Open before the caller may use the driver again. Usually there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_TMR_Initialize function must have been called for the specified Timer driver instance. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open DRV_TMR_Close ( handle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 987 Function void DRV_TMR_Close ( DRV_HANDLE handle ) DRV_TMR_Open Function Opens the specified Timer driver instance and returns a handle to it. Implementation: Dynamic File drv_tmr.h C DRV_HANDLE DRV_TMR_Open(const SYS_MODULE_INDEX index, const DRV_IO_INTENT intent); Returns If successful, the function returns a valid open instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Description This function opens the specified Timer driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Timer driver does not support multiple clients. If two tasks want to use the timer, one should wait until the other one gets closed. Remarks The handle returned is valid until the DRV_TMR_Close function is called. This function will NEVER block waiting for hardware. If the requested intent flags are not supported, the function will return DRV_HANDLE_INVALID. The Timer driver does not support DRV_IO_INTENT_SHARED. Only exclusive access is supported for now. Preconditions The DRV_TMR_Initialize function must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_TMR_Open ( DRV_TMR_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); if ( DRV_HANDLE_INVALID == handle ) { // Unable to open the driver } Parameters Parameters Description index Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT ORed together to indicate the intended use of the driver Function DRV_HANDLE DRV_TMR_Open ( const SYS_MODULE_INDEX index, const DRV_IO_INTENT intent ) DRV_TMR_Start Function Starts the Timer counting. Implementation: Static/Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 988 File drv_tmr.h C bool DRV_TMR_Start(DRV_HANDLE handle); Returns • true - if the operation succeeded • false - the supplied handle is invalid or the client doesn't have the needed parameters to run (alarm callback and period ) Description This function starts the Timer counting. Remarks None. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Timer parameters must have been set by a call to DRV_TMR_AlarmRegister. Example DRV_HANDLE tmrHandle; // Returned from DRV_TMR_Open DRV_TMR_AlarmRegister(tmrHandle, 0x100, true, 0, myTmrCallback); DRV_TMR_Start ( tmrHandle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function bool DRV_TMR_Start ( DRV_HANDLE handle ) DRV_TMR_Stop Function Stops the Timer from counting. Implementation: Static/Dynamic File drv_tmr.h C void DRV_TMR_Stop(DRV_HANDLE handle); Returns None. Description This function stops the running Timer from counting. Remarks None. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 989 DRV_TMR_Stop ( handle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_TMR_Stop ( DRV_HANDLE handle ) c) Alarm Functions DRV_TMR_AlarmHasElapsed Function Provides the status of Timer's period elapse. Implementation: Dynamic File drv_tmr.h C uint32_t DRV_TMR_AlarmHasElapsed(DRV_HANDLE handle); Returns Number of times timer has elapsed since the last call. Description This function returns the number of times Timer's period has elapsed since last call to this API has made. On calling this API, the internally maintained counter will be cleared and count will be started again from next elapse. Remarks None. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE tmrHandle; // Returned from DRV_TMR_Open bool elapseStatus; SYS_MODULE_OBJ tmrObject // Returned by DRV_TMR_Initialize unsigned int appInternalTime = 0; Sys_Tasks() { //Timer task will be called from ISR APP_TimeUpdate_Task(); //Other Tasks } void APP_TimeUpdate_Task ( void ) { //We will not miss a count even though we are late appInternalTime += DRV_TMR_AlarmHasElapsed ( tmrHandle ); } Parameters Parameters Description handle A valid handle, returned from the DRV_TMR_Open Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 990 Function unsigned int DRV_TMR_AlarmHasElapsed ( DRV_HANDLE handle ) DRV_TMR_AlarmDisable Function Disables an alarm signal. Implementation: Dynamic File drv_tmr.h C bool DRV_TMR_AlarmDisable(DRV_HANDLE handle); Returns The current status of the alarm: • true if the alarm was currently enabled • false if the alarm was currently disabled Description This function allows the client to disable an alarm generation. Use DRV_TMR_AlarmEnable to re-enable. Remarks When the driver operates in interrupts this call resolves to a device interrupt disable. Do NOT disable the timer except for very short periods of time. If the time that the interrupt is disabled is longer than a wrap around period and the interrupt is missed, the hardware has no means of recovering and the resulting timing will be inaccurate. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. A client alarm must be active. Example Parameters Parameters Description handle A valid handle, returned from DRV_TMR_Open Function bool DRV_TMR_AlarmDisable ( DRV_HANDLE handle); DRV_TMR_AlarmEnable Function Re-enables an alarm signal. Implementation: Dynamic File drv_tmr.h C void DRV_TMR_AlarmEnable(DRV_HANDLE handle, bool enable); Returns None Description This function allows the client to re-enable an alarm after it has been disabled by a DRV_TMR_AlarmDisable call. Remarks When the driver operates in interrupts this call resolves to a device interrupt re-enable. Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 991 Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example Parameters Parameters Description handle A valid handle, returned from DRV_TMR_Open enable boolean to enable the current callback Function void DRV_TMR_AlarmEnable ( DRV_HANDLE handle, bool enable ); DRV_TMR_AlarmDeregister Function Removes a previously set alarm. Implementation: Dynamic File drv_tmr.h C void DRV_TMR_AlarmDeregister(DRV_HANDLE handle); Returns None. Description This function removes a previously set alarm. Remarks None. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. DRV_TMR_AlarmRegister function must have been called before. Example // Example of a key debounce check static unsigned int lastReadKey, readKey, keyCount, globalKeyState; DRV_HANDLE tmrHandle; // Returned from DRV_TMR_Open void keyPressDetect () { // Calculate the count to be passed on from the clock input DRV_TMR_AlarmRegister ( tmrHandle, 0xFF00, true, DebounceCheck ); } void DebounceCheck ( uintptr_t context ) { readKey = AppReadKey(); if ( readKey != lastReadKey ) { lastReadKey = readKey; keyCount = 0; } else { if ( keyCount > 20 ) { Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 992 globalKeyState = readKey; DRV_TMR_AlarmDeregister ( tmrHandle ); } keyCount++; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_TMR_AlarmDeregister ( DRV_HANDLE handle ) DRV_TMR_AlarmPeriodGet Function Provides the Timer's period. Implementation: Dynamic File drv_tmr.h C uint32_t DRV_TMR_AlarmPeriodGet(DRV_HANDLE handle); Returns Timer period value: • a 16 bit value if the timer is configured in 16 bit mode • a 32 bit value if the timer is configured in 32 bit mode Description This function gets the Timer's period. Remarks None. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE tmrHandle; // Returned from DRV_TMR_Open uint32_t period; period = DRV_TMR_AlarmPeriodGet ( tmrHandle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function uint32_t DRV_TMR_AlarmPeriodGet ( DRV_HANDLE handle ) DRV_TMR_AlarmPeriodSet Function Updates the Timer's period. Implementation: Dynamic File drv_tmr.h Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 993 C void DRV_TMR_AlarmPeriodSet(DRV_HANDLE handle, uint32_t value); Returns None. Description This function updates the Timer's period. Remarks • The period value will be truncated to a 16 bit value if the timer is configured in 16 bit mode. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_TMR_Open DRV_TMR_AlarmPeriodSet ( handle, 0x1000 ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine value Period value • a 16 bit value if the timer is configured in 16 bit mode • a 32 bit value if the timer is configured in 32 bit mode Function void DRV_TMR_AlarmPeriodSet ( DRV_HANDLE handle, uint32_t value ) DRV_TMR_AlarmRegister Function Sets up an alarm. Implementation: Dynamic File drv_tmr.h C bool DRV_TMR_AlarmRegister(DRV_HANDLE handle, uint32_t divider, bool isPeriodic, uintptr_t context, DRV_TMR_CALLBACK callBack); Returns • true - if the call succeeded • false - the obtained divider could not be obtained or the passed handle was invalid Description This function sets up an alarm, allowing the client to receive a callback from the driver when the timer counter reaches zero. Alarms can be one-shot or periodic. A periodic alarm will reload the timer and generate alarm until stopped. The alarm frequency is: DRV_TMR_CounterFrequencyGet() / divider; Remarks The divider value will be truncated to a 16 bit value if the timer is configured in 16 bit mode. The timer should be started using DRV_TMR_Start API to get a callback. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. divider value has to be within the timer divider range (see DRV_TMR_DividerSpecGet). Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 994 Example //Do the initialization with 'mode' set to DRV_TMR_OPERATION_MODE_16_BIT void setupTask () { DRV_HANDLE tmrHandle; // Returned from DRV_TMR_Open uint32_t myFreq = 1000; // 1KHz uint32_t clkFreq = DRV_TMR_CounterFrequencyGet(tmrHandle); // timer running frequency // calculate the divider needed uint32_t divider = clkFreq / myFreq; // Start the alarm if(!DRV_TMR_AlarmRegister ( tmrHandle, divider, true, 0, CallBackFreq )) { // divider value could not be obtain; // handle the error // } } Parameters Parameters Description handle A valid handle, returned from DRV_TMR_Open divider The value to divide the timer clock source to obtain the required alarm frequency. • a 16 bit value if the timer is configured in 16 bit mode • a 32 bit value if the timer is configured in 32 bit mode isPeriodic Flag indicating whether the alarm should be one-shot or periodic. context A reference, call back function will be called with the same reference. callBack A call back function which will be called on time out. Function bool DRV_TMR_AlarmRegister ( DRV_HANDLE handle, uint32_t divider, bool isPeriodic, uintptr_t context, DRV_TMR_CALLBACK callBack ) d) Counter Control Functions DRV_TMR_CounterFrequencyGet Function Provides the Timer input frequency. Implementation: Dynamic File drv_tmr.h C uint32_t DRV_TMR_CounterFrequencyGet(DRV_HANDLE handle); Returns 32-bit value corresponding to the running frequency. If Timer clock source is external, then this function returns 0. Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 995 Description This function provides the Timer input frequency. Input frequency is the clock to the Timer register and it is considering the prescaler divisor. Remarks On most processors, the Timer's base frequency is the same as the peripheral bus clock. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE tmrHandle; // Returned from DRV_TMR_Open uint32_t clkFreqHz; clkFreqHz = DRV_TMR_CounterFrequencyGet ( tmrHandle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function uint32_t DRV_TMR_CounterFrequencyGet ( DRV_HANDLE handle ) DRV_TMR_CounterClear Function Clears the Timer's counter register. Implementation: Static/Dynamic File drv_tmr.h C void DRV_TMR_CounterClear(DRV_HANDLE handle); Returns None. Description This function clears the Timer's value in the counter register. Remarks None. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_TMR_CounterClear ( DRV_HANDLE handle ) DRV_TMR_CounterValueGet Function Reads the Timer's counter register. Implementation: Static/Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 996 File drv_tmr.h C uint32_t DRV_TMR_CounterValueGet(DRV_HANDLE handle); Returns Timer current period: • a 16 bit value if the timer is configured in 16 bit mode • a 32 bit value if the timer is configured in 32 bit mode Description This function returns the Timer's value in the counter register. Remarks None. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example //Example to use timer for precision time measurement //without configuring an alarm (interrupt based) char appState = 0; DRV_HANDLE tmrHandle; // Returned from DRV_TMR_Open switch ( appState ) { case 0: //Calculate and set the counter period DRV_TMR_CounterValueSet ( tmrHandle, ( 0xFFFF - 0x1000 ) ); //counter starts DRV_TMR_Start ( tmrHandle ); //Trigger an application operation app_trigger_operation(); //Check for time-out in the next state appState++; case 1: //Overflows and stops at 0 if no alarm is set if ( DRV_TMR_CounterValueGet ( tmrHandle ) == 0 ) { //Time-out return false; } else if ( app_operation_isComplete( ) ) { //Operation is complete before time-out return true; } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function uint32_t DRV_TMR_CounterValueGet ( DRV_HANDLE handle ) Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 997 DRV_TMR_CounterValueSet Function Updates the Timer's counter register. Implementation: Static/Dynamic File drv_tmr.h C void DRV_TMR_CounterValueSet(DRV_HANDLE handle, uint32_t counterPeriod); Returns None. Description This function updates the Timer's value in the counter register. Remarks None. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine counterPeriod counter period value • a 16 bit value if the timer is configured in 16 bit mode • a 32 bit value if the timer is configured in 32 bit mode Function void DRV_TMR_CounterValueSet ( DRV_HANDLE handle, uint32_t counterPeriod ) e) Miscellaneous Functions DRV_TMR_GateModeClear Function Enables the Gate mode. Implementation: Dynamic File drv_tmr.h C bool DRV_TMR_GateModeClear(DRV_HANDLE handle); Returns • true - if the operation is successful • false - either the handle is invalid or the gate mode is not supported Description This function enables the Gated mode of Timer. User can measure the duration of an external signal in this mode. Once the Gate mode is enabled, Timer will start on the raising edge of the external signal. It will keep counting until the next falling edge. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 998 Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE tmrHandle; // Returned from DRV_TMR_Open DRV_TMR_GateModeClear ( tmrHandle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function bool DRV_TMR_GateModeClear ( DRV_HANDLE handle ) DRV_TMR_PrescalerGet Function This function gets the currently selected prescaler. Implementation: Dynamic File drv_tmr.h C TMR_PRESCALE DRV_TMR_PrescalerGet(DRV_HANDLE handle); Returns Timer prescaler. Description This function gets the currently selected prescaler. Remarks None. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE tmrHandle; // Returned from DRV_TMR_Open TMR_PRESCALE preScale; preScale = DRV_TMR_PrescalerGet ( tmrHandle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function TMR_PRESCALE DRV_TMR_PrescalerGet ( DRV_HANDLE handle ) DRV_TMR_OperationModeGet Function This function gets the currently selected operation mode. Implementation: Dynamic File drv_tmr.h Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 999 C DRV_TMR_OPERATION_MODE DRV_TMR_OperationModeGet(DRV_HANDLE handle); Returns A DRV_TMR_OPERATION_MODE value showing how the timer is currently configured. DRV_TMR_OPERATION_MODE_NONE is returned for an invalid client handle. Description This function gets the currently selected 16/32 bit operation mode. Remarks None. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE tmrHandle; // Returned from DRV_TMR_Open DRV_TMR_OPERATION_MODE operMode; operMode = DRV_TMR_OperationModeGet ( tmrHandle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function DRV_TMR_OPERATION_MODE DRV_TMR_OperationModeGet(DRV_HANDLE handle) DRV_TMR_DividerRangeGet Function Returns the Timer divider values. Implementation: Dynamic File drv_tmr.h C DRV_TMR_OPERATION_MODE DRV_TMR_DividerRangeGet(DRV_HANDLE handle, DRV_TMR_DIVIDER_RANGE* pDivRange); Returns • A DRV_TMR_OPERATION_MODE value showing how the timer is currently configured. The pDivRange is updated with the supported range values. • DRV_TMR_OPERATION_MODE_NONE for invalid client handle Description This function provides the Timer operating mode and divider range. Remarks None. Preconditions The DRV_TMR_Initialize function must have been called. DRV_TMR_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE tmrHandle; // Returned from DRV_TMR_Open DRV_TMR_OPERATION_MODE timerMode; DRV_TMR_DIVIDER_RANGE timerRange; Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1000 DRV_TMR_DividerRangeGet(handle, &timerRange); uint32_t clkFreqHz = DRV_TMR_CounterFrequencyGet ( tmrHandle ); uint32_t maxFreqHz = clkFreqHz / timerRange.dividerMin; uint32_t minFreqHz = clkFreqHz / timerRange.dividerMax; Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine pDivRange Address to store the timer divider range. Function DRV_TMR_OPERATION_MODE DRV_TMR_DividerRangeGet ( DRV_HANDLE handle, DRV_TMR_DIVIDER_RANGE* pDivRange ) f) Data Types and Constants DRV_TMR_CALLBACK Type Pointer to a Timer driver callback function data type. File drv_tmr.h C typedef void (* DRV_TMR_CALLBACK)(uintptr_t context, uint32_t alarmCount); Description Timer Driver Callback Function Pointer This data type defines a pointer to a Timer driver callback function. Remarks Useful only when timer alarm callback support is enabled by defining the DRV_TMR_ALARM_ENABLE configuration option. DRV_TMR_INIT Structure Defines the Timer driver initialization data. File drv_tmr.h C typedef struct { SYS_MODULE_INIT moduleInit; TMR_MODULE_ID tmrId; DRV_TMR_CLK_SOURCES clockSource; TMR_PRESCALE prescale; INT_SOURCE interruptSource; DRV_TMR_OPERATION_MODE mode; bool asyncWriteEnable; } DRV_TMR_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization. TMR_MODULE_ID tmrId; Identifies timer hardware module (PLIB-level) ID DRV_TMR_CLK_SOURCES clockSource; Clock Source select. Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1001 TMR_PRESCALE prescale; Prescaler Selection from the processor enumeration INT_SOURCE interruptSource; Interrupt Source for TMR module. If 'DRV_TMR_OPERATION_MODE_32_BIT' flag is selected the interrupt will be generated by the 2nd timer of the pair, the odd numbered one. DRV_TMR_OPERATION_MODE mode; Select 16/32 bit operation mode. 32 bit mode will combine two 16 bit timer modules to form a 32 bit one. This is usually only necessary for very long delays. bool asyncWriteEnable; Asynchronous write enable configuration. If true the asynchronous write is enabled. For timers that do not support this feature the value is ignored Description Timer Driver Initialize Data This data type defines data required to initialize the Timer driver. Remarks Not all initialization features are available on all devices. DRV_TMR_CLIENT_STATUS Enumeration Identifies the client-specific status of the Timer driver File drv_tmr.h C typedef enum { DRV_TMR_CLIENT_STATUS_INVALID, DRV_TMR_CLIENT_STATUS_BUSY, DRV_TMR_CLIENT_STATUS_READY, DRV_TMR_CLIENT_STATUS_RUNNING } DRV_TMR_CLIENT_STATUS; Members Members Description DRV_TMR_CLIENT_STATUS_INVALID Driver is invalid (or unopened) state DRV_TMR_CLIENT_STATUS_BUSY An operation is currently in progress DRV_TMR_CLIENT_STATUS_READY Ready, no operations running DRV_TMR_CLIENT_STATUS_RUNNING Timer started and running, processing transactions Description Timer Driver Client Status This enumeration identifies the client-specific status of the Timer driver. Remarks None. DRV_TMR_DIVIDER_RANGE Structure This data structure specifies the divider values that can be obtained by the timer module. File drv_tmr.h C typedef struct { uint32_t dividerMin; uint32_t dividerMax; uint32_t dividerStep; } DRV_TMR_DIVIDER_RANGE; Members Members Description uint32_t dividerMin; The minimum divider value that the timer module can obtain uint32_t dividerMax; The maximum divider value that the timer module can obtain Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1002 uint32_t dividerStep; The divider step value, between 2 divider values Should be 1 for most timers Description Timer Driver divider operating specification This data structure specifies the divider values that can be obtained by the timer hardware. Remarks None. DRV_TMR_OPERATION_MODE Enumeration Lists the operation modes available for timer driver. File drv_tmr.h C typedef enum { DRV_TMR_OPERATION_MODE_NONE, DRV_TMR_OPERATION_MODE_16_BIT, DRV_TMR_OPERATION_MODE_32_BIT } DRV_TMR_OPERATION_MODE; Members Members Description DRV_TMR_OPERATION_MODE_NONE The timer module operating mode none/invalid DRV_TMR_OPERATION_MODE_16_BIT The timer module operates in 16 bit mode DRV_TMR_OPERATION_MODE_32_BIT The timer module operates in 32 bit mode This will combine two 16 bit timer modules Description Timer Driver Operation mode This enumeration lists all the available operation modes that are valid for the timer hardware. Remarks Not all modes are available on all devices. DRV_TMR_INDEX_COUNT Macro Number of valid Timer driver indices. File drv_tmr.h C #define DRV_TMR_INDEX_COUNT TMR_NUMBER_OF_MODULES Description Timer Driver Module Index Count This constant identifies Timer driver index definitions. Remarks This constant should be used in place of hard-coded numeric literals. This value is device-specific. DRV_TMR_INDEX_0 Macro Timer driver index definitions File drv_tmr.h Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1003 C #define DRV_TMR_INDEX_0 0 Description Timer Driver Module Index Numbers These constants provide Timer driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_TMR_Initialize and DRV_TMR_Open functions to identify the driver instance in use. DRV_TMR_INDEX_1 Macro File drv_tmr.h C #define DRV_TMR_INDEX_1 1 Description This is macro DRV_TMR_INDEX_1. DRV_TMR_INDEX_2 Macro File drv_tmr.h C #define DRV_TMR_INDEX_2 2 Description This is macro DRV_TMR_INDEX_2. DRV_TMR_INDEX_3 Macro File drv_tmr.h C #define DRV_TMR_INDEX_3 3 Description This is macro DRV_TMR_INDEX_3. DRV_TMR_INDEX_4 Macro File drv_tmr.h C #define DRV_TMR_INDEX_4 4 Description This is macro DRV_TMR_INDEX_4. Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1004 DRV_TMR_INDEX_5 Macro File drv_tmr.h C #define DRV_TMR_INDEX_5 5 Description This is macro DRV_TMR_INDEX_5. DRV_TMR_INDEX_6 Macro File drv_tmr.h C #define DRV_TMR_INDEX_6 6 Description This is macro DRV_TMR_INDEX_6. DRV_TMR_INDEX_7 Macro File drv_tmr.h C #define DRV_TMR_INDEX_7 7 Description This is macro DRV_TMR_INDEX_7. DRV_TMR_INDEX_8 Macro File drv_tmr.h C #define DRV_TMR_INDEX_8 8 Description This is macro DRV_TMR_INDEX_8. DRV_TMR_INDEX_9 Macro File drv_tmr.h C #define DRV_TMR_INDEX_9 9 Description This is macro DRV_TMR_INDEX_9. Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1005 DRV_TMR_INDEX_10 Macro File drv_tmr.h C #define DRV_TMR_INDEX_10 10 Description This is macro DRV_TMR_INDEX_10. DRV_TMR_INDEX_11 Macro File drv_tmr.h C #define DRV_TMR_INDEX_11 11 Description This is macro DRV_TMR_INDEX_11. Files Files Name Description drv_tmr.h Timer device driver interface header file. drv_tmr_config_template.h Timer driver configuration definitions for the template version. Description This section lists the source and header files used by the Timer Driver Library. drv_tmr.h Timer device driver interface header file. Enumerations Name Description DRV_TMR_CLIENT_STATUS Identifies the client-specific status of the Timer driver DRV_TMR_OPERATION_MODE Lists the operation modes available for timer driver. Functions Name Description DRV_TMR_AlarmDeregister Removes a previously set alarm. Implementation: Dynamic DRV_TMR_AlarmDisable Disables an alarm signal. Implementation: Dynamic DRV_TMR_AlarmEnable Re-enables an alarm signal. Implementation: Dynamic DRV_TMR_AlarmHasElapsed Provides the status of Timer's period elapse. Implementation: Dynamic DRV_TMR_AlarmPeriodGet Provides the Timer's period. Implementation: Dynamic DRV_TMR_AlarmPeriodSet Updates the Timer's period. Implementation: Dynamic DRV_TMR_AlarmRegister Sets up an alarm. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1006 DRV_TMR_ClientStatus Gets the status of the client operation. Implementation: Dynamic DRV_TMR_ClockSet Sets the timers clock by selecting the source and prescaler. Implementation: Dynamic DRV_TMR_Close Closes an opened instance of the Timer driver. Implementation: Dynamic DRV_TMR_CounterClear Clears the Timer's counter register. Implementation: Static/Dynamic DRV_TMR_CounterFrequencyGet Provides the Timer input frequency. Implementation: Dynamic DRV_TMR_CounterValueGet Reads the Timer's counter register. Implementation: Static/Dynamic DRV_TMR_CounterValueSet Updates the Timer's counter register. Implementation: Static/Dynamic DRV_TMR_Deinitialize Deinitializes the specified instance of the Timer driver. Implementation: Dynamic DRV_TMR_DividerRangeGet Returns the Timer divider values. Implementation: Dynamic DRV_TMR_GateModeClear Enables the Gate mode. Implementation: Dynamic DRV_TMR_GateModeSet Enables the Gate mode. Implementation: Dynamic DRV_TMR_Initialize Initializes the Timer driver. Implementation: Static/Dynamic DRV_TMR_Open Opens the specified Timer driver instance and returns a handle to it. Implementation: Dynamic DRV_TMR_OperationModeGet This function gets the currently selected operation mode. Implementation: Dynamic DRV_TMR_PrescalerGet This function gets the currently selected prescaler. Implementation: Dynamic DRV_TMR_Start Starts the Timer counting. Implementation: Static/Dynamic DRV_TMR_Status Provides the current status of the Timer driver. Implementation: Dynamic DRV_TMR_Stop Stops the Timer from counting. Implementation: Static/Dynamic DRV_TMR_Tasks Maintains the driver's state machine. Implementation: Dynamic Macros Name Description DRV_TMR_INDEX_0 Timer driver index definitions DRV_TMR_INDEX_1 This is macro DRV_TMR_INDEX_1. DRV_TMR_INDEX_10 This is macro DRV_TMR_INDEX_10. DRV_TMR_INDEX_11 This is macro DRV_TMR_INDEX_11. DRV_TMR_INDEX_2 This is macro DRV_TMR_INDEX_2. DRV_TMR_INDEX_3 This is macro DRV_TMR_INDEX_3. DRV_TMR_INDEX_4 This is macro DRV_TMR_INDEX_4. DRV_TMR_INDEX_5 This is macro DRV_TMR_INDEX_5. DRV_TMR_INDEX_6 This is macro DRV_TMR_INDEX_6. DRV_TMR_INDEX_7 This is macro DRV_TMR_INDEX_7. DRV_TMR_INDEX_8 This is macro DRV_TMR_INDEX_8. DRV_TMR_INDEX_9 This is macro DRV_TMR_INDEX_9. DRV_TMR_INDEX_COUNT Number of valid Timer driver indices. Volume V: MPLAB Harmony Framework Driver Libraries Help Timer Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1007 Structures Name Description DRV_TMR_DIVIDER_RANGE This data structure specifies the divider values that can be obtained by the timer module. DRV_TMR_INIT Defines the Timer driver initialization data. Types Name Description DRV_TMR_CALLBACK Pointer to a Timer driver callback function data type. Description Timer Device Driver Interface Definition This header file contains the function prototypes and definitions of the data types and constants that make up the interface to the Timer device driver. File Name drv_tmr.h Company Microchip Technology Inc. drv_tmr_config_template.h Timer driver configuration definitions for the template version. Macros Name Description DRV_TMR_ASYNC_WRITE_ENABLE Controls Asynchronous Write mode of the Timer. DRV_TMR_CLIENTS_NUMBER Sets up the maximum number of clients that can be supported by an instance of the dynamic driver. DRV_TMR_CLOCK_PRESCALER Sets the default timer driver clock prescaler. DRV_TMR_CLOCK_SOURCE Sets the default timer driver clock source. DRV_TMR_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported by the dynamic driver. DRV_TMR_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_TMR_INTERRUPT_SOURCE Sets the default timer driver clock interrupt source DRV_TMR_MODE Sets the default timer driver clock operating mode. DRV_TMR_MODULE_ID Sets the default timer module ID to be used by the timer driver. DRV_TMR_MODULE_INIT Sets the default module init value for the timer driver. Description Timer Driver Configuration Definitions for the Template Version These definitions set up the driver for the default mode of operation of the driver. File Name drv_tmr_config_template.h Company Microchip Technology Inc. Touch Driver Libraries Help This section describes the Touch Driver Libraries. Generic Touch Driver API This library help section outlines the generic Touch Driver API to be followed by anyone who wants to use a custom created touch driver to go with the MPLAB Harmony framework for their applications. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1008 Description This generic driver would still be used with the Touch System Service as described by the API. It provides the data structures and functions required for the touch driver to interface with the graphics library as well as the Touch System Services. The APIs provide routines to read the touch input data from the touch screen. The driver is based on the device notifying the availability of touch input data through external interrupt. Currently, the API and the system services only supports non-gestural single-fingered touch input. Library Interface Functions Name Description DRV_TOUCH_Close Closes an opened instance of an TOUCH module driver. DRV_TOUCH_Deinitialize Deinitializes the index instance of the TOUCH module. DRV_TOUCH_Initialize Initializes hardware and data for the index instance of the TOUCH module. DRV_TOUCH_Open Opens the specified instance of the Touch driver for use and provides an "open-instance" handle. DRV_TOUCH_Read Notifies the driver that there is current touch data to read DRV_TOUCH_Reinitialize DRV_TOUCH_Status Provides the current status of the index instance of the TOUCH module. DRV_TOUCH_Tasks Maintains the driver's state machine and implements its task queue processing. Implementation: Dynamic Data Types and Constants Name Description DRV_TOUCH_INIT Defines the data required to initialize or reinitialize the TOUCH driver DRV_TOUCH_PEN_STATE Identifies the current state of the pen. DRV_TOUCH_POSITION_STATUS Identifies the current status of the current touch point. DRV_TOUCH_SAMPLE_POINTS This is type DRV_TOUCH_SAMPLE_POINTS. DRV_TOUCH_INDEX_0 Touch driver index definitions. DRV_TOUCH_INDEX_1 This is macro DRV_TOUCH_INDEX_1. DRV_TOUCH_INDEX_COUNT Number of valid TOUCH driver indices. Description Functions DRV_TOUCH_Close Function Closes an opened instance of an TOUCH module driver. File drv_touch.h C void DRV_TOUCH_Close(DRV_HANDLE handle); Returns None. Description This function closes an opened instance of an TOUCH module driver, making the specified handle invalid. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1009 Preconditions The DRV_TOUCH_Initialize routine must have been called for the specified TOUCH device instance and the DRV_TOUCH_Status must have returned SYS_STATUS_READY. DRV_TOUCH_Open must have been called to obtain a valid opened device handle. Example myTouchHandle = DRV_TOUCH_Open(DRV_TOUCH_ID_1, DRV_IO_INTENT_NONBLOCKING|DRV_IO_INTENT_READWRITE); DRV_TOUCH_Close(myTouchHandle); Parameters Parameters Description drvHandle A valid open-instance handle, returned from the driver's open routine Function void DRV_TOUCH_Close ( const DRV_HANDLE drvHandle ) DRV_TOUCH_Deinitialize Function Deinitializes the index instance of the TOUCH module. File drv_touch.h C void DRV_TOUCH_Deinitialize(const SYS_MODULE_INDEX index); Returns None. Description This function deinitializes the index instance of the TOUCH module, disabling its operation (and any hardware for driver modules). It deinitializes only the specified module instance. It also resets all the internal data structures and fields for the specified instance to the default settings. Preconditions The DRV_TOUCH_Initialize function should have been called before calling this function. Example SYS_STATUS touchstatus; DRV_TOUCH_Deinitialize(DRV_TOUCH_ID_1); touchstatus = DRV_TOUCH_Status(DRV_TOUCH_ID_1); Parameters Parameters Description index Index, identifying the instance of the TOUCH module to be deinitialized Function void DRV_TOUCH_Deinitialize ( const SYS_MODULE_ID index ) DRV_TOUCH_Initialize Function Initializes hardware and data for the index instance of the TOUCH module. File drv_touch.h C SYS_MODULE_OBJ DRV_TOUCH_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1010 Returns None Description This function initializes hardware for the index instance of the TOUCH module, using the hardware initialization given data. It also initializes any internal driver data structures making the driver ready to be opened. Preconditions None. Example DRV_TOUCH_INIT_DATA touchInitData; SYS_STATUS touchStatus; // Populate the touchInitData structure touchInitData.moduleInit.powerState = SYS_MODULE_POWER_RUN_FULL; touchInitData.moduleInit.moduleCode = (DRV_TOUCH_INIT_DATA_MASTER | DRV_TOUCH_INIT_DATA_SLAVE); DRV_TOUCH_Initialize(DRV_TOUCH_ID_1, (SYS_MODULE_INIT*)&touchInitData); touchStatus = DRV_TOUCH_Status(DRV_TOUCH_ID_1); Parameters Parameters Description index Index, identifying the instance of the TOUCH module to be initialized data Pointer to the data structure containing any data necessary to initialize the hardware. This pointer may be null if no data is required and the default initialization is to be used. Function void DRV_TOUCH_Initialize ( const TOUCH_MODULE_ID index, const SYS_MODULE_INIT *const data ) DRV_TOUCH_Open Function Opens the specified instance of the Touch driver for use and provides an "open-instance" handle. File drv_touch.h C DRV_HANDLE DRV_TOUCH_Open(const SYS_MODULE_INDEX index, const DRV_IO_INTENT intent); Returns If successful, the routine returns a valid open-instance handle (a value identifying both the caller and the module instance). If an error occurs, the returned value is DRV_HANDLE_INVALID. Description This function opens the specified instance of the Touch module for use and provides a handle that is required to use the remaining driver routines. This function opens a specified instance of the Touch module driver for use by any client module and provides an "open-instance" handle that must be provided to any of the other Touch driver operations to identify the caller and the instance of the Touch driver/hardware module. Preconditions The DRV_TOUCH_Initialize routine must have been called for the specified TOUCH device instance and the DRV_TOUCH_Status must have returned SYS_STATUS_READY. Example DRV_HANDLE touchHandle; DRV_TOUCH_CLIENT_STATUS touchClientStatus; touchHandle = DRV_TOUCH_Open(DRV_TOUCH_ID_1, DRV_IO_INTENT_NONBLOCKING|DRV_IO_INTENT_READWRITE); if (DRV_HANDLE_INVALID == touchHandle) { // Handle open error } Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1011 touchClientStatus = DRV_TOUCH_ClientStatus(touchHandle); // Close the device when it is no longer needed. DRV_TOUCH_Close(touchHandle); Parameters Parameters Description index Index, identifying the instance of the TOUCH module to be opened. intent Flags parameter identifying the intended usage and behavior of the driver. Multiple flags may be ORed together to specify the intended usage of the device. See the DRV_IO_INTENT definition. Function DRV_HANDLE DRV_TOUCH_Open ( const SYS_MODULE_INDEX index, const DRV_IO_INTENT intent ) DRV_TOUCH_Read Function Notifies the driver that there is current touch data to read File drv_touch.h C size_t DRV_TOUCH_Read(DRV_HANDLE drvHandle, void * buffer, size_t size); Description Notifies the driver that there is current touch data to read Example Function size_t DRV_TOUCH_Read ( DRV_HANDLE drvHandle, void *buffer, size_t size ) DRV_TOUCH_Reinitialize Function File drv_touch.h C void DRV_TOUCH_Reinitialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT *const data); Returns None. Preconditions The DRV_TOUCH_Initialize function should have been called before calling this function. Example SYS_MODULE_INIT touchInit; SYS_STATUS touchStatus; DRV_TOUCH_Reinitialize(DRV_TOUCH_ID_1, &touchStatus); Parameters Parameters Description index Index, identifying the instance of the TOUCH module to be reinitialized data Pointer to the data structure containing any data necessary to reinitialize the hardware. This pointer may be null if no data is required and default configuration is to be used. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1012 Function void DRV_TOUCH_Reinitialize( const SYS_MODULE_ID index, const SYS_MODULE_INIT *const data ) DRV_TOUCH_Status Function Provides the current status of the index instance of the TOUCH module. File drv_touch.h C SYS_STATUS DRV_TOUCH_Status(const SYS_MODULE_INDEX index); Description This function provides the current status of the index instance of the TOUCH module. Preconditions The DRV_TOUCH_Initialize function should have been called before calling this function. Function SYS_STATUS DRV_TOUCH_Status ( const TOUCH_MODULE_ID index ) DRV_TOUCH_Tasks Function Maintains the driver's state machine and implements its task queue processing. Implementation: Dynamic File drv_touch.h C void DRV_TOUCH_Tasks(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal state machine and implement its command queue processing. It is always called from SYS_Tasks() function. This routine decodes the touch input data available. Remarks This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) Preconditions The DRV_TOUCH_Initialize routine must have been called for the specified MTCH6301 driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_TOUCH_MTCH6301_Initialize void SYS_Tasks( void ) { DRV_TOUCH_Tasks ( object ); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_TOUCH_Initialize) Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1013 Function void DRV_TOUCH_Tasks ( SYS_MODULE_OBJ object ); Data Types and Constants DRV_TOUCH_INIT Structure Defines the data required to initialize or reinitialize the TOUCH driver File drv_touch.h C typedef struct { SYS_MODULE_INIT moduleInit; int touchId; SYS_MODULE_OBJ (* drvInitialize)(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); DRV_HANDLE (* drvOpen)(const SYS_MODULE_INDEX index, const DRV_IO_INTENT intent); void (* drvCalibrationSet)(DRV_TOUCH_SAMPLE_POINTS * samplePoints); short (* drvTouchGetX)(uint8_t touchNumber); short (* drvTouchGetY)(uint8_t touchNumber); DRV_TOUCH_POSITION_STATUS (* drvTouchStatus)(const SYS_MODULE_INDEX index); void (* drvTouchDataRead)(const SYS_MODULE_INDEX index); DRV_TOUCH_PEN_STATE (* drvTouchPenGet)(uint8_t touchNumber); INT_SOURCE interruptSource; uint16_t orientation; uint16_t horizontalResolution; uint16_t verticalResolution; uint16_t (* pReadFunc)(uint32_t); void (* pWriteFunc)(uint16_t, uint32_t); void (* pSectorErase)(uint32_t); int32_t minTouchDetectDelta; } DRV_TOUCH_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization int touchId; ID uint16_t orientation; Orientation of the display (given in degrees of 0,90,180,270) uint16_t horizontalResolution; Horizontal Resolution of the displayed orientation in Pixels uint16_t (* pReadFunc)(uint32_t); typedef for read function pointer void (* pWriteFunc)(uint16_t, uint32_t); typedef for write function pointer Description TOUCH Driver Initialization Data This data type defines the data required to initialize or reinitialize the TOUCH driver. If the driver is built statically, the members of this data structure are statically over-ridden by static override definitions in the system_config.h file. Remarks None. DRV_TOUCH_PEN_STATE Type Identifies the current state of the pen. File drv_touch.h C typedef enum DRV_TOUCH_PEN_STATE@2 DRV_TOUCH_PEN_STATE; Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1014 Description TOUCH Controller Driver Pen State Identifies the current state of the pen reported from a touch event. Remarks This enumeration is the return type for the TouchGetPen routine. DRV_TOUCH_POSITION_STATUS Type Identifies the current status of the current touch point. File drv_touch.h C typedef enum DRV_TOUCH_POSITION_STATUS@2 DRV_TOUCH_POSITION_STATUS; Description TOUCH Controller Driver Touch status Identifies the current status of the current touch point. Remarks This enumeration is the return type for the status routine for the current touch point DRV_TOUCH_SAMPLE_POINTS Type File drv_touch.h C typedef struct DRV_TOUCH_SAMPLE_POINTS@2 DRV_TOUCH_SAMPLE_POINTS; Description This is type DRV_TOUCH_SAMPLE_POINTS. DRV_TOUCH_INDEX_0 Macro Touch driver index definitions. File drv_touch.h C #define DRV_TOUCH_INDEX_0 0 Description Touch Driver Module Index Numbers These constants provide the Touch driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_TOUCH_Initialize and DRV_TOUCH_Open functions to identify the driver instance in use. DRV_TOUCH_INDEX_1 Macro File drv_touch.h Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1015 C #define DRV_TOUCH_INDEX_1 1 Description This is macro DRV_TOUCH_INDEX_1. DRV_TOUCH_INDEX_COUNT Macro Number of valid TOUCH driver indices. File drv_touch.h C #define DRV_TOUCH_INDEX_COUNT 1 Description TOUCH Driver Module Index Count This constant identifies the number of valid TOUCH driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific header files defined as part of the peripheral libraries. Files Files Name Description drv_touch.h Touch device driver interface file. Description drv_touch.h Touch device driver interface file. Functions Name Description DRV_TOUCH_Close Closes an opened instance of an TOUCH module driver. DRV_TOUCH_Deinitialize Deinitializes the index instance of the TOUCH module. DRV_TOUCH_Initialize Initializes hardware and data for the index instance of the TOUCH module. DRV_TOUCH_Open Opens the specified instance of the Touch driver for use and provides an "open-instance" handle. DRV_TOUCH_Read Notifies the driver that there is current touch data to read DRV_TOUCH_Reinitialize DRV_TOUCH_Status Provides the current status of the index instance of the TOUCH module. DRV_TOUCH_Tasks Maintains the driver's state machine and implements its task queue processing. Implementation: Dynamic Macros Name Description DRV_TOUCH_INDEX_0 Touch driver index definitions. DRV_TOUCH_INDEX_1 This is macro DRV_TOUCH_INDEX_1. DRV_TOUCH_INDEX_COUNT Number of valid TOUCH driver indices. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1016 Structures Name Description DRV_TOUCH_INIT Defines the data required to initialize or reinitialize the TOUCH driver Types Name Description DRV_TOUCH_PEN_STATE Identifies the current state of the pen. DRV_TOUCH_POSITION_STATUS Identifies the current status of the current touch point. DRV_TOUCH_SAMPLE_POINTS This is type DRV_TOUCH_SAMPLE_POINTS. Description Touch Driver Interface The Touch driver provides a abstraction to all touch drivers. File Name drv_touch.h Company Microchip Technology Inc. 10-bit ADC Touch Driver Library This topic describes the 10-bit ADC Touch Driver Library. Introduction This library provides an interface to manage the 10-bit ADC Touch Driver module on the Microchip family of microcontrollers in different modes of operation. Description The MPLAB Harmony 10-bit ADC Touch Driver provides a high-level interface to the 10-bit ADC touch device. This driver provides application routines to read non-gestural single-point touch input data from the touch screen. The 10-bit ADC touch device can notify the availability of touch input data through external interrupt. The 10-bit ADC Touch Driver allows the application to map a controller pin as an external interrupt pin. Using the Library This topic describes the basic architecture of the 10-bit ADC Touch Driver Library and provides information and examples on its use. Description Interface Header File: drv_adc10bit.h The interface to the 10-bit ADC Touch Driver library is defined in the drv_adc10bit.h header file. Any C language source (.c) file that uses the ADC 10-bit Touch Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the 10-bit ADC Touch Driver module. Library Interface Section Description System Functions Provides system module interfaces, device initialization, deinitialization, open, close, task, and status functions. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1017 Configuring the Library Macros Name Description DRV_ADC10BIT_CALIBRATION_DELAY Defines the calibration delay. DRV_ADC10BIT_CALIBRATION_INSET Defines the calibration inset. DRV_ADC10BIT_CLIENTS_NUMBER Selects the maximum number of clients. DRV_ADC10BIT_INDEX ADC10BIT static index selection. DRV_ADC10BIT_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported. DRV_ADC10BIT_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_ADC10BIT_SAMPLE_POINTS Defines the sample points. DRV_ADC10BIT_TOUCH_DIAMETER Defines the touch diameter. Description The configuration of the 10-bit ADC Touch Driver is based on the file system_config.h. This header file contains the configuration selection for the ADC 10-bit Touch Driver. Based on the selections made, the driver may support the selected features. These configuration settings will apply to all instances of the 10-bit ADC Touch Driver. This header can be placed anywhere, 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. DRV_ADC10BIT_CALIBRATION_DELAY Macro Defines the calibration delay. File drv_adc10bit_config_template.h C #define DRV_ADC10BIT_CALIBRATION_DELAY 300 Description ADC10BIT Calibration Delay This macro enables the delay between calibration touch points. Remarks None. DRV_ADC10BIT_CALIBRATION_INSET Macro Defines the calibration inset. File drv_adc10bit_config_template.h C #define DRV_ADC10BIT_CALIBRATION_INSET 25 Description ADC10BIT Calibration Inset This macro defines the calibration inset. Remarks None. DRV_ADC10BIT_CLIENTS_NUMBER Macro Selects the maximum number of clients. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1018 File drv_adc10bit_config_template.h C #define DRV_ADC10BIT_CLIENTS_NUMBER 1 Description ADC10BIT client number This macro selects the maximum number of clients. This definition selected the maximum number of clients that the ADC10BIT driver can support at run-time. Remarks None. DRV_ADC10BIT_INDEX Macro ADC10BIT static index selection. File drv_adc10bit_config_template.h C #define DRV_ADC10BIT_INDEX DRV_ADC10BIT_INDEX_0 Description ADC10BIT Static Index Selection This macro specifies the static index selection for the driver object reference. Remarks This index is required to make a reference to the driver object. DRV_ADC10BIT_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported. File drv_adc10bit_config_template.h C #define DRV_ADC10BIT_INSTANCES_NUMBER 1 Description ADC10BIT hardware instance configuration This macro sets up the maximum number of hardware instances that can be supported. Remarks None. DRV_ADC10BIT_INTERRUPT_MODE Macro Controls operation of the driver in the interrupt or polled mode. File drv_adc10bit_config_template.h C #define DRV_ADC10BIT_INTERRUPT_MODE false Description ADC10BIT Interrupt And Polled Mode Operation Control Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1019 This macro controls the operation of the driver in the interrupt mode of operation. The possible values of this macro are: • true - Select if interrupt mode of ADC10BIT operation is desired • false - Select if polling mode of ADC10BIT operation is desired Not defining this option to true or false will result in a build error. Remarks None. DRV_ADC10BIT_SAMPLE_POINTS Macro Defines the sample points. File drv_adc10bit_config_template.h C #define DRV_ADC10BIT_SAMPLE_POINTS 4 Description ADC10BIT Sample Points This macro defines the sample points. Remarks None. DRV_ADC10BIT_TOUCH_DIAMETER Macro Defines the touch diameter. File drv_adc10bit_config_template.h C #define DRV_ADC10BIT_TOUCH_DIAMETER 10 Description ADC10BIT Touch Diameter This macro defines the touch diameter. Remarks None. Building the Library This section lists the files that are available in the 10-bit ADC Touch Driver Library. Description This section list the files that are available in the \src folder of the 10-bit ADC Touch 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. 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 /framework/driver/touch/adc10bit. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_adc10bit.h Header file that exports the driver API. 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. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1020 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 /src/drv_adc10bit.c Basic 10-bit ADC Touch Driver implementation file. 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 N/A No optional files are available for this library. Module Dependencies The 10-bit ADC Touch Driver Library depends on the following modules: • Interrupt System Service Library • Ports System Service Library • Touch System Service Library • I2C Driver Library Library Interface a) System Functions Name Description DRV_TOUCH_ADC10BIT_CalibrationSet Loads calibration parameters from Non-volatile Memory. DRV_TOUCH_ADC10BIT_Close Closes an opened instance of the 10-bit ADC Driver. DRV_TOUCH_ADC10BIT_Deinitialize Deinitializes the specified instance of the ADC10BIT driver module. DRV_TOUCH_ADC10BIT_Initialize Initializes the 10-bit ADC Driver instance for the specified driver index DRV_TOUCH_ADC10BIT_Open Opens the specified ADC10BIT driver instance and returns a handle to it. DRV_TOUCH_ADC10BIT_Status Provides the current status of the ADC10BIT driver module. DRV_TOUCH_ADC10BIT_Tasks Maintains the driver's state machine and implements its ISR. DRV_TOUCH_ADC10BIT_TouchGetRawX Returns raw x coordinate status when the touch screen is pressed. DRV_TOUCH_ADC10BIT_TouchGetRawY Returns raw y coordinate status when the touch screen is pressed. DRV_TOUCH_ADC10BIT_TouchGetX Returns x coordinate status when the touch screen is pressed. DRV_TOUCH_ADC10BIT_TouchStoreCalibration Stores calibration parameters into Non-volatile Memory. DRV_TOUCH_ADC10BIT_PositionDetect None. DRV_TOUCH_ADC10BIT_TouchGetY Returns y coordinate status when the touch screen is pressed. DRV_TOUCH_ADC10BIT_TouchDataRead Notifies the driver that the current touch data has been read DRV_TOUCH_ADC10BIT_TouchStatus Returns the status of the current touch input. b) Data Types and Constants Name Description _DRV_TOUCH_ADC10BIT_CLIENT_DATA Defines the data that can be changed per client. _DRV_TOUCH_ADC10BIT_INIT Defines the data required to initialize or reinitialize the 10-bit ADC Driver. DRV_ADC10BIT_MODULE_ID This is type DRV_ADC10BIT_MODULE_ID. DRV_TOUCH_ADC10BIT_CLIENT_DATA Defines the data that can be changed per client. DRV_TOUCH_ADC10BIT_HANDLE Driver handle. DRV_TOUCH_ADC10BIT_INIT Defines the data required to initialize or reinitialize the 10-bit ADC Driver. DRV_TOUCH_ADC10BIT_HANDLE_INVALID Definition of an invalid handle. DRV_TOUCH_ADC10BIT_INDEX_0 ADC10BIT driver index definitions. DRV_TOUCH_ADC10BIT_INDEX_1 This is macro DRV_TOUCH_ADC10BIT_INDEX_1. DRV_TOUCH_ADC10BIT_INDEX_COUNT Number of valid ADC10BIT driver indices. Description This section describes the API functions of the 10-bit ADC Touch Driver library. Refer to each section for a detailed description. a) System Functions Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1021 DRV_TOUCH_ADC10BIT_CalibrationSet Function Loads calibration parameters from Non-volatile Memory. File drv_adc10bit.h C void DRV_TOUCH_ADC10BIT_CalibrationSet(DRV_TOUCH_SAMPLE_POINTS * samplePoints); Returns None. Description This function loads calibration parameters from Non-volatile Memory. Preconditions The NVM initialization function must be called before calling this function. Function void DRV_TOUCH_ADC10BIT_TouchLoadCalibration(void) DRV_TOUCH_ADC10BIT_Close Function Closes an opened instance of the 10-bit ADC Driver. File drv_adc10bit.h C void DRV_TOUCH_ADC10BIT_Close(DRV_HANDLE handle); Returns None Description This function closes an opened instance of the 10-bit ADC Driver, invalidating the handle. Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_TOUCH_ADC10BIT_Open before the caller may use the driver again. This function is thread safe in a RTOS application. Usually there is no need for the driver client to verify that the Close operation has completed. Preconditions DRV_TOUCH_ADC10BIT_Initialize must have been called for the specified ADC10BIT driver instance. DRV_TOUCH_ADC10BIT_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_TOUCH_ADC10BIT_Open DRV_TOUCH_ADC10BIT_Close ( handle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_TOUCH_ADC10BIT_Close ( DRV_HANDLE handle ) Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1022 DRV_TOUCH_ADC10BIT_Deinitialize Function Deinitializes the specified instance of the ADC10BIT driver module. File drv_adc10bit.h C void DRV_TOUCH_ADC10BIT_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description This function deinitializes the specified instance of the 10-bit ADC Driver module, disabling its operation (and any hardware) and invalidates all of the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_TOUCH_ADC10BIT_Status operation. The system has to use DRV_TOUCH_ADC10BIT_Status to determine when the module is in the ready state. Preconditions DRV_TOUCH_ADC10BIT_Initialize must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Example SYS_MODULE_OBJ object; // Returned from DRV_TOUCH_ADC10BIT_Initialize SYS_STATUS status; DRV_TOUCH_ADC10BIT_Deinitialize ( object ); status = DRV_TOUCH_ADC10BIT_Status( object ); if( SYS_MODULE_UNINITIALIZED == status ) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from DRV_TOUCH_ADC10BIT_Initialize Function void DRV_TOUCH_ADC10BIT_Deinitialize ( SYS_MODULE_OBJ object ) DRV_TOUCH_ADC10BIT_Initialize Function Initializes the 10-bit ADC Driver instance for the specified driver index File drv_adc10bit.h C SYS_MODULE_OBJ DRV_TOUCH_ADC10BIT_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, returns SYS_MODULE_OBJ_INVALID. Description This function initializes the 10-bit ADC Driver instance for the specified driver index, making it ready for clients to open and use it. The initialization Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1023 data is specified by the 'init' parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. The driver instance index is independent of the 10-bit ADC Driver module ID. For example, driver instance 0 can be assigned to ADC10BIT2. If the driver is built statically, then some of the initialization parameters are overridden by configuration macros. Refer to the description of the DRV_TOUCH_ADC10BIT_INIT data structure for more details on which members on this data structure are overridden. Remarks This routine must be called before any other ADC10BIT routine is called. This routine should only be called once during system initialization unless DRV_TOUCH_ADC10BIT_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. Preconditions None. Example DRV_TOUCH_ADC10BIT_INIT init; SYS_MODULE_OBJ objectHandle; // Populate the ADC10BIT initialization structure init.spiId = ADC10BIT_ID_1; objectHandle = DRV_TOUCH_ADC10BIT_Initialize(DRV_TOUCH_ADC10BIT_INDEX_1, (SYS_MODULE_INIT*)usartInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized. Please note this is not the 10-bit ADC Driver ID. The hardware 10-bit ADC Driver ID is set in the initialization structure. This is the index of the driver index to use. init Pointer to a data structure containing any data necessary to initialize the driver. If this pointer is NULL, the driver uses the static initialization override macros for each member of the initialization data structure. Function SYS_MODULE_OBJ DRV_TOUCH_ADC10BIT_Initialize( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ) DRV_TOUCH_ADC10BIT_Open Function Opens the specified ADC10BIT driver instance and returns a handle to it. File drv_adc10bit.h C DRV_HANDLE DRV_TOUCH_ADC10BIT_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. An error can occur when the following is true: • if the number of client objects allocated via DRV_TOUCH_ADC10BIT_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the driver hardware instance being opened is not initialized or is invalid Description This function opens the specified USART driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. The DRV_IO_INTENT_BLOCKING and DRV_IO_INTENT_NONBLOCKING ioIntent options additionally affect the behavior of the DRV_USART_Read() and DRV_USART_Write() functions. If the ioIntent is DRV_IO_INTENT_NONBLOCKING, then these function will not block even if the required amount of data could not be processed. If the ioIntent is DRV_IO_INTENT_BLOCKING, these functions will block until the required amount of data is processed. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1024 If ioIntent is DRV_IO_INTENT_READ, the client will only be read from the driver. If ioIntent is DRV_IO_INTENT_WRITE, the client will only be able to write to the driver. If the ioIntent in DRV_IO_INTENT_READWRITE, the client will be able to do both, read and write. Specifying a DRV_IO_INTENT_EXCLUSIVE will cause the driver to provide exclusive access to this client. The driver cannot be opened by any other client. Remarks The handle returned is valid until the DRV_TOUCH_ADC10BIT_Close routine is called. This routine will NEVER block waiting for hardware. If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. It should not be called in an ISR. Preconditions DRV_TOUCH_ADC10BIT_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_TOUCH_ADC10BIT_Open( DRV_TOUCH_ADC10BIT_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); if( DRV_HANDLE_INVALID == handle ) { // Unable to open the driver } Parameters Parameters Description drvIndex Index of the driver initialized with DRV_TOUCH_ADC10BIT_Initialize. Please note this is not the SPI id. intent Zero or more of the values from the enumeration DRV_IO_INTENT ORed together to indicate the intended use of the driver Function DRV_HANDLE DRV_TOUCH_ADC10BIT_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ) DRV_TOUCH_ADC10BIT_Status Function Provides the current status of the ADC10BIT driver module. File drv_adc10bit.h C SYS_STATUS DRV_TOUCH_ADC10BIT_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system level operation and cannot start another Description This function provides the current status of the ADC10BIT driver module. Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_MODULE_UNINITIALIZED - Indicates that the driver has been deinitialized This value is less than SYS_STATUS_ERROR. This function can be used to determine when any of the driver's module level operations has completed. If the status operation returns SYS_STATUS_BUSY, the previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This function will NEVER block waiting for hardware. If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1025 Preconditions DRV_TOUCH_ADC10BIT_Initialize must have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_TOUCH_ADC10BIT_Initialize SYS_STATUS status; status = DRV_TOUCH_ADC10BIT_Status( object ); if( SYS_STATUS_READY != status ) { // Handle error } Parameters Parameters Description object Driver object handle, returned from DRV_TOUCH_ADC10BIT_Initialize Function SYS_STATUS DRV_TOUCH_ADC10BIT_Status ( SYS_MODULE_OBJ object ) DRV_TOUCH_ADC10BIT_Tasks Function Maintains the driver's state machine and implements its ISR. File drv_adc10bit.h C void DRV_TOUCH_ADC10BIT_Tasks(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal state machine and implement its transmit ISR for interrupt-driven implementations. In polling mode, this function should be called from the SYS_Tasks function. In Interrupt mode, this function should be called in the transmit interrupt service routine of the USART that is associated with this USART driver hardware instance. Remarks This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the appropriate raw ISR. This function may execute in an ISR context and will never block or access any resources that may cause it to block. Preconditions DRV_TOUCH_ADC10BIT_Initialize must have been called for the specified 10-bit ADC Driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_TOUCH_ADC10BIT_Initialize while( true ) { DRV_TOUCH_ADC10BIT_Tasks ( object ); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_TOUCH_ADC10BIT_Initialize) Function void DRV_TOUCH_ADC10BIT_Tasks ( SYS_MODULE_OBJ object ); Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1026 DRV_TOUCH_ADC10BIT_TouchGetRawX Function Returns raw x coordinate status when the touch screen is pressed. File drv_adc10bit.h C short DRV_TOUCH_ADC10BIT_TouchGetRawX(); Returns • raw x coordinate - Indicates the touch screen was pressed • -1 - Indicates the touch screen was not pressed Description This function returns the raw x coordinate status when the touch screen is pressed. Remarks None. Preconditions None. Function short DRV_TOUCH_ADC10BIT_TouchGetRawX() DRV_TOUCH_ADC10BIT_TouchGetRawY Function Returns raw y coordinate status when the touch screen is pressed. File drv_adc10bit.h C short DRV_TOUCH_ADC10BIT_TouchGetRawY(); Returns • raw y coordinate - Indicates the touch screen was pressed • -1 - Indicates the touch screen was not pressed Description This function returns the raw y coordinate status when the touch screen is pressed. Remarks None. Preconditions None. Function short DRV_TOUCH_ADC10BIT_TouchGetRawY() DRV_TOUCH_ADC10BIT_TouchGetX Function Returns x coordinate status when the touch screen is pressed. File drv_adc10bit.h Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1027 C short DRV_TOUCH_ADC10BIT_TouchGetX(uint8_t touchNumber); Returns • x coordinate - Indicates the touch screen was pressed • -1 - Indicates the touch screen was not pressed Description This function returns the x coordinate status when the touch screen is pressed. Remarks None. Preconditions None. Parameters Parameters Description touchNumber touch input index. Function short DRV_TOUCH_ADC10BIT_TouchGetX( uint8_t touchNumber ) DRV_TOUCH_ADC10BIT_TouchStoreCalibration Function Stores calibration parameters into Non-volatile Memory. File drv_adc10bit.h C void DRV_TOUCH_ADC10BIT_TouchStoreCalibration(); Returns None. Description This function stores calibration parameters into Non-volatile Memory. Remarks This API is deprecated and its funcationality is handled via SYSTEM_INITIALIZATION Preconditions The NVM initialization function must be called before calling this function. Function void DRV_TOUCH_ADC10BIT_TouchStoreCalibration(void) DRV_TOUCH_ADC10BIT_PositionDetect Function None. File drv_adc10bit.h C short DRV_TOUCH_ADC10BIT_PositionDetect(); Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1028 Returns None. Description None. Preconditions None. Function void DRV_TOUCH_ADC10BIT_TouchLoadCalibration(void) DRV_TOUCH_ADC10BIT_TouchGetY Function Returns y coordinate status when the touch screen is pressed. File drv_adc10bit.h C short DRV_TOUCH_ADC10BIT_TouchGetY(uint8_t touchNumber); Returns • y coordinate - Indicates the touch screen was pressed • -1 - Indicates the touch screen was not pressed Description This function returns the y coordinate status when the touch screen is pressed. Remarks None. Preconditions None. Parameters Parameters Description handle driver client handle. touchNumber touch input index. Function short DRV_TOUCH_ADC10BIT_TouchGetY( DRV_HANDLE handle, uint8_t touchNumber ) DRV_TOUCH_ADC10BIT_TouchDataRead Function Notifies the driver that the current touch data has been read File drv_adc10bit.h C void DRV_TOUCH_ADC10BIT_TouchDataRead(const SYS_MODULE_INDEX index); Returns None. Description Notifies the driver that the current touch data has been read Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1029 Function void DRV_TOUCH_ADC10BIT_TouchDataRead( const SYS_MODULE_INDEX index ) DRV_TOUCH_ADC10BIT_TouchStatus Function Returns the status of the current touch input. File drv_adc10bit.h C DRV_TOUCH_POSITION_STATUS DRV_TOUCH_ADC10BIT_TouchStatus(const SYS_MODULE_INDEX index); Returns It returns the status of the current touch input. Description It returns the status of the current touch input. Function DRV_TOUCH_POSITION_SINGLE DRV_TOUCH_ADC10BIT_TouchStatus( const SYS_MODULE_INDEX index ) b) Data Types and Constants DRV_ADC10BIT_MODULE_ID Enumeration File drv_adc10bit.h C typedef enum { ADC10BIT_ID_1 = 0, ADC10BIT_NUMBER_OF_MODULES } DRV_ADC10BIT_MODULE_ID; Description This is type DRV_ADC10BIT_MODULE_ID. DRV_TOUCH_ADC10BIT_CLIENT_DATA Structure Defines the data that can be changed per client. File drv_adc10bit.h C typedef struct _DRV_TOUCH_ADC10BIT_CLIENT_DATA { } DRV_TOUCH_ADC10BIT_CLIENT_DATA; Description Macro: ADC10BIT Driver Client Specific Configuration This data type defines the data can be configured per client. This data can be per client, and overrides the configuration data contained inside of DRV_TOUCH_ADC10BIT_INIT. Remarks None. DRV_TOUCH_ADC10BIT_HANDLE Type Driver handle. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1030 File drv_adc10bit.h C typedef uintptr_t DRV_TOUCH_ADC10BIT_HANDLE; Description Macro: ADC10BIT Driver Handle Touch screen controller interfacing with the 10-bit Analog-to-Digital (ADC) converter device. Remarks None DRV_TOUCH_ADC10BIT_INIT Structure Defines the data required to initialize or reinitialize the 10-bit ADC Driver. File drv_adc10bit.h C typedef struct _DRV_TOUCH_ADC10BIT_INIT { SYS_MODULE_INIT moduleInit; DRV_ADC10BIT_MODULE_ID adc10bitId; } DRV_TOUCH_ADC10BIT_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System module initialization DRV_ADC10BIT_MODULE_ID adc10bitId; Identifies peripheral (PLIB-level) ID Description Macro: ADC10BIT Driver Initialization Data This data type defines the data required to initialize or reinitialize the 10-bit ADC Driver. If the driver is built statically, the members of this data structure are statically over-ridden by static override definitions in the system_config.h file. Remarks None. DRV_TOUCH_ADC10BIT_HANDLE_INVALID Macro Definition of an invalid handle. File drv_adc10bit.h C #define DRV_TOUCH_ADC10BIT_HANDLE_INVALID ((DRV_TOUCH_ADC10BIT_HANDLE)(-1)) Description Macro: ADC10BIT Driver Invalid Handle This is the definition of an invalid handle. An invalid handle is returned by DRV_ADC10BIT_RawRead and DRV_ADC10BIT_RawRead functions if the request was not successful. Remarks None. DRV_TOUCH_ADC10BIT_INDEX_0 Macro ADC10BIT driver index definitions. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1031 File drv_adc10bit.h C #define DRV_TOUCH_ADC10BIT_INDEX_0 0 Description Macro: ADC10BIT Driver Module Index Numbers These constants provide the 10-bit ADC Driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_ADC10BIT_Initialize and DRV_ADC10BIT_Open functions to identify the driver instance in use. DRV_TOUCH_ADC10BIT_INDEX_1 Macro File drv_adc10bit.h C #define DRV_TOUCH_ADC10BIT_INDEX_1 1 Description This is macro DRV_TOUCH_ADC10BIT_INDEX_1. DRV_TOUCH_ADC10BIT_INDEX_COUNT Macro Number of valid ADC10BIT driver indices. File drv_adc10bit.h C #define DRV_TOUCH_ADC10BIT_INDEX_COUNT 2 Description Macro: ADC10BIT Driver Module Index Count This constant identifies the number of valid 10-bit ADC Driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific header files defined as part of the peripheral libraries. Files Files Name Description drv_adc10bit.h 10-bit ADC Touch Driver interface definitions drv_adc10bit_config_template.h 10-bit ADC Touch Driver configuration template. Description This section lists the source and header files used by the 10-bit ADC Touch Driver Library. drv_adc10bit.h 10-bit ADC Touch Driver interface definitions Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1032 Enumerations Name Description DRV_ADC10BIT_MODULE_ID This is type DRV_ADC10BIT_MODULE_ID. Functions Name Description DRV_TOUCH_ADC10BIT_CalibrationSet Loads calibration parameters from Non-volatile Memory. DRV_TOUCH_ADC10BIT_Close Closes an opened instance of the 10-bit ADC Driver. DRV_TOUCH_ADC10BIT_Deinitialize Deinitializes the specified instance of the ADC10BIT driver module. DRV_TOUCH_ADC10BIT_Initialize Initializes the 10-bit ADC Driver instance for the specified driver index DRV_TOUCH_ADC10BIT_Open Opens the specified ADC10BIT driver instance and returns a handle to it. DRV_TOUCH_ADC10BIT_PositionDetect None. DRV_TOUCH_ADC10BIT_Status Provides the current status of the ADC10BIT driver module. DRV_TOUCH_ADC10BIT_Tasks Maintains the driver's state machine and implements its ISR. DRV_TOUCH_ADC10BIT_TouchDataRead Notifies the driver that the current touch data has been read DRV_TOUCH_ADC10BIT_TouchGetRawX Returns raw x coordinate status when the touch screen is pressed. DRV_TOUCH_ADC10BIT_TouchGetRawY Returns raw y coordinate status when the touch screen is pressed. DRV_TOUCH_ADC10BIT_TouchGetX Returns x coordinate status when the touch screen is pressed. DRV_TOUCH_ADC10BIT_TouchGetY Returns y coordinate status when the touch screen is pressed. DRV_TOUCH_ADC10BIT_TouchStatus Returns the status of the current touch input. DRV_TOUCH_ADC10BIT_TouchStoreCalibration Stores calibration parameters into Non-volatile Memory. Macros Name Description DRV_TOUCH_ADC10BIT_HANDLE_INVALID Definition of an invalid handle. DRV_TOUCH_ADC10BIT_INDEX_0 ADC10BIT driver index definitions. DRV_TOUCH_ADC10BIT_INDEX_1 This is macro DRV_TOUCH_ADC10BIT_INDEX_1. DRV_TOUCH_ADC10BIT_INDEX_COUNT Number of valid ADC10BIT driver indices. Structures Name Description _DRV_TOUCH_ADC10BIT_CLIENT_DATA Defines the data that can be changed per client. _DRV_TOUCH_ADC10BIT_INIT Defines the data required to initialize or reinitialize the 10-bit ADC Driver. DRV_TOUCH_ADC10BIT_CLIENT_DATA Defines the data that can be changed per client. DRV_TOUCH_ADC10BIT_INIT Defines the data required to initialize or reinitialize the 10-bit ADC Driver. Types Name Description DRV_TOUCH_ADC10BIT_HANDLE Driver handle. Description 10-bit ADC Touch Driver Interface Definition This is a resistive touch screen driver that is using the Microchip Graphics Library. The calibration values are automatically checked (by reading a specific memory location on the non-volatile memory) when initializing the module if the function pointers to the read and write callback functions are initialized. If the read value is invalid calibration will automatically be executed. Otherwise, the calibration values will be loaded and used. The driver assumes that the application side provides the read and write routines to a non-volatile memory. If the callback functions are not initialized, the calibration routine will always be called at start-up to initialize the global calibration values. This driver assumes that the Graphics Library is initialized and will be using the default font of the library. File Name drv_adc10bit.h Company Microchip Technology Inc. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1033 drv_adc10bit_config_template.h 10-bit ADC Touch Driver configuration template. Macros Name Description DRV_ADC10BIT_CALIBRATION_DELAY Defines the calibration delay. DRV_ADC10BIT_CALIBRATION_INSET Defines the calibration inset. DRV_ADC10BIT_CLIENTS_NUMBER Selects the maximum number of clients. DRV_ADC10BIT_INDEX ADC10BIT static index selection. DRV_ADC10BIT_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported. DRV_ADC10BIT_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_ADC10BIT_SAMPLE_POINTS Defines the sample points. DRV_ADC10BIT_TOUCH_DIAMETER Defines the touch diameter. Description 10-bit ADC Touch Driver Configuration Template This header file contains the build-time configuration selections for the 10-bit ADC Touch Driver. This is the template file which give all possible configurations that can be made. This file should not be included in any project. File Name drv_adc10bit_config_template.h Company Microchip Technology Inc. ADC Touch Driver Library This topic describes the ADC Touch Driver Library. Introduction This library provides an interface to manage the ADC Touch Driver module on the Microchip family of microcontrollers in different modes of operation. Description The MPLAB Harmony ADC Touch Driver provides a high-level interface to the ADC touch device. This driver provides application routines to read the touch input data from the touch screen. . The ADC touch device can notify the availability of touch input data through external interrupt. The ADC Touch Driver allows the application to map a controller pin as an external interrupt pin. Using the Library This topic describes the basic architecture of the ADC Touch Driver Library and provides information and examples on its use. Description Interface Header File: drv_touch_adc.h The interface to the ADC Touch Driver library is defined in the drv_touch_adc.h header file. Any C language source (.c) file that uses the ADC Touch Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the ADC Touch Driver Library 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 ADC Touch Driver has routines to perform the following operations. The driver initialization routines allow the application to initialize the driver. The driver must be initialized before it can be used by application. Once driver is initialized the driver open routine allows retrieving the client handle. Once the touch input is available a touch input read request is sent and input data is retrieved in a buffer. The buffer data is then decoded Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1034 to get the x and y coordinate of the touch screen in the form of the number of pixels. ADC Touch Driver Abstraction Model Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the ADC Touch Driver module. Library Interface Section Description System Functions Provides system module interfaces, device initialization, deinitialization, open, close, task, and status functions. How the Library Works The library provides interfaces to support system functions, which provide system module interfaces, device initialization, deinitialization, open, close, task, and status functions. During steady state operation, the DRV_TOUCH_ADC_Tasks is called continuously in System_Tasks to save the current touch position, or -1 if no touch was detected. At any time, DRV_TOUCH_ADC_TouchGetX and DRV_TOUCH_ADC_TouchGetY are called to retrieve the last touch position. Touch positions are not queued. Touch samples are configurable, the default is 300. The return integer can have the value between 0-screenWidth and 0-screenHeight. Initializing the Driver Before the ADC Touch Driver can be opened, it must be configured and initialized. The driver build time configuration is defined by the configuration macros. Refer to the Building the Library section for the location of and more information on the various configuration macros and how these macros should be designed. The driver initialization is configured through the DRV_TOUCH_INIT data structure that is passed to the DRV_TOUCH_ADC_Initialize function. The initialization parameters include the interrupt source, interrupt pin remap configuration and touch screen resolution. The following code shows an example of initializing the ADC Touch Touch Driver. /* The following code shows an example of designing the * DRV_TOUCH_INIT data structure. It also shows how an example * usage of the DRV_TOUCH_ADC_Initialize function. */ Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1035 DRV_TOUCH_INIT drvTouchInitData; SYS_MODULE_OBJ objectHandle; /* Touch Module Id*/ drvTouchInitData.touchId = DRV_TOUCH_INDEX_0; /* I2C Bus driver open */ drvTouchInitData.drvOpen = DRV_I2C_Open; /* Interrupt Source for Touch */ drvTouchInitData.interruptSource = INT_SOURCE_EXTERNAL_1; /* Interrupt Pin function mapping */ drvTouchInitData.interruptPort.inputFunction = INPUT_FUNC_INT1; /* Pin to be mapped as interrupt pin */ drvTouchInitData.interruptPort.inputPin = INPUT_PIN_RPE8; /* Analog pin number */ drvTouchInitData.interruptPort.analogPin = PORTS_ANALOG_PIN_25; /* Pin Mode of analog pin */ drvTouchInitData.interruptPort.pinMode = PORTS_PIN_MODE_DIGITAL; /* Interrupt pin port */ drvTouchInitData.interruptPort.channel = PORT_CHANNEL_E; /* Interrupt pin port maskl */ drvTouchInitData.interruptPort.dataMask = 0x8; /* Touch screen orientation */ drvTouchInitData.orientation = DISP_ORIENTATION; /* Touch screen horizontal resolution */ drvTouchInitData.horizontalResolution = DISP_HOR_RESOLUTION; /* Touch screen vertical resolution */ drvTouchInitData.verticalResolution = DISP_VER_RESOLUTION; /* Driver initialization */ objectHandle = DRV_TOUCH_ADC_Initialize(DRV_TOUCH_INDEX_0, (SYS_MODULE_INIT*)drvTouchInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Opening the Driver To use the ADC Touch Driver, the application must open the driver. This is done by calling the DRV_TOUCH_ADC_Open function. If successful, the DRV_TOUCH_ADC_Open function will return a handle to the driver. This handle records the association between the client and the driver instance that was opened. The DRV_TOUCH_ADC_Open function may return DRV_HANDLE_INVALID in the situation where the driver is not ready to be opened. When this occurs, the application can try opening the driver again. Note that the open function may return an invalid handle in other (error) cases as well. The following code shows an example of the driver being opened. DRV_HANDLE handle; handle = DRV_TOUCH_ADC_Open( DRV_TOUCH_ADC_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); if( DRV_HANDLE_INVALID == handle ) { // Unable } Tasks Routine To use the ADC Touch Driver, the application must open the driver. This is done by calling the DRV_TOUCH_ADC_Open function. If successful, the DRV_TOUCH_ADC_Open function will return a handle to the driver. This handle records the association between the client and the driver instance that was opened. The DRV_TOUCH_ADC_Open function may return DRV_HANDLE_INVALID in the situation where the driver is not ready to be opened. When this occurs, the application can try opening the driver again. Note that the open function may return an invalid handle in Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1036 other (error) cases as well. The following code shows an example of the driver being opened. DRV_HANDLE handle; handle = DRV_TOUCH_ADC_Open( DRV_TOUCH_ADC_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); if( DRV_HANDLE_INVALID == handle ) { // Unable } Configuring the Library The configuration of the ADC Touch Driver is based on the file system_config.h. This header file contains the configuration selection for the ADC 10-bit Touch Driver. Based on the selections made, the driver may support the selected features. These configuration settings will apply to all instances of the ADC Touch Driver. This header can be placed anywhere, 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 in the ADC Touch Driver Library. Description This section list the files that are available in the \src folder of the ADC Touch 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. 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 /framework/driver/touch/touch_adc. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_touch_adc.h Header file that exports the driver API. 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 /src/drv_touch_adc.c Basic ADC Touch Driver implementation file. 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 N/A No optional files are available for this library. Module Dependencies The ADC Touch Driver Library depends on the following modules: • Interrupt System Service Library • Ports System Service Library • Touch System Service Library • I2C Driver Library Library Interface This section describes the API functions of the ADC Touch Driver library. Refer to each section for a detailed description. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1037 a) System Functions b) Data Types and Constants Files This section lists the source and header files used by the ADC Touch Driver Library. AR1021 Touch Driver Library This topic describes the AR1021 Touch Driver Library. Introduction This library provides a low-level abstraction of the AR1021 Touch Driver 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 AR1021 Touch Driver Library, in conjunction with the Microchip AR1021 Resistive Touch Screen Controller module, allows an application to: • Calibrate touch points • Receive touch points The following application services are provided by the AR1021 Touch Driver Library: • Configuring the AR1021 controller (TouchThreshold, PenUpDelay, PenStateReportDelaylist, SensitivityFilter, etc.) • Saving touch points to EEPROM The operational services are not typically accessible to the application as this portion of the code resides within the Touch System Service Library software layer and is used by the Graphics Library stack services to receive touch point data. Using the Library This topic describes the basic architecture of the AR1021 Touch Driver Library and provides information and examples on its use. Description Interface Header File: drv_ar1021.h The interface to the AR1021 Touch Driver library is defined in the drv_ar1021.h header file. Any C language source (.c) file that uses the AR1021 Touch Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the AR1021 Touch Driver Library 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 AR1021 Touch Driver Library provides the following functionality: • AR1021 library initialization • AR1021 controller configuration • AR1021 controller connectivity • AR1021 polling for pen-down and pen-up touch point events The abstraction model shown in the following diagram depicts how the AR1021 Touch Driver is positioned in the MPLAB Harmony framework. The AR1021 Touch Driver Library uses the SPI Driver for control and touch data transfers to the AR1021 module. AR1021 Touch Driver Abstraction Model Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1038 Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the AR1021 Touch Driver module. Library Interface Section Description System Functions Provides system module interfaces, device initialization, deinitialization, task, and status functions. Client Functions Provides functions to open, close, and calibrate the AR1021 Touch Driver. How the Library Works The library provides interfaces to support: • System functions, which provide system module interfaces, device initialization, deinitialization, task, touch, and status functions • Client functions, which open, close, and calibrate the AR1021 Touch Driver Initializing the Driver Before the AR1021 Touch Driver can be opened, it must be configured and initialized. The driver build time configuration is defined by the configuration macros. Refer to the Building the Library section for the location of and more information on the various configuration macros and how these macros should be designed. The driver initialization is configured through the DRV_TOUCH_INIT data structure that is passed to the DRV_TOUCH_AR1021_Initialize function. The initialization parameters include the interrupt source, interrupt pin remap configuration and touch screen resolution. The following code shows an example of initializing the AR1021 Touch Driver. Example: /* The following code shows an example of designing the * DRV_TOUCH_INIT data structure. It also shows how an example * usage of the DRV_TOUCH_AR1021_Initialize function. */ DRV_TOUCH_INIT drvTouchInitData; SYS_MODULE_OBJ objectHandle; /* Driver initialization */ objectHandle = DRV_TOUCH_AR1021_Initialize(DRV_TOUCH_INDEX_0, Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1039 (SYS_MODULE_INIT*)drvTouchInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Opening the Driver To use the AR1021 Touch Driver, the application must open the driver. This is done by calling the DRV_TOUCH_AR1021_Open function. If successful, the DRV_TOUCH_AR1021_Open function will return a handle to the driver. This handle records the association between the client and the driver instance that was opened. The DRV_TOUCH_AR1021_Open function may return DRV_HANDLE_INVALID in the situation where the driver is not ready to be opened. When this occurs, the application can try opening the driver again. Note that the open function may return an invalid handle in other (error) cases as well. The following code shows an example of the driver being opened. DRV_HANDLE handle; handle = DRV_TOUCH_AR1021_Open( DRV_TOUCH_AR1021_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); if( DRV_HANDLE_INVALID == handle ) { // Unable to open the driver } Tasks Routine This routine processes the AR1021 Touch Driver commands from the command queue. If the state of the command is initialize or done it returns. If the read request registration is successful the state of command is to decode input. The tasks routine decodes the input and updates the global variables storing the touch input data in form of x and y coordinates. The AR1021 Touch Driver task routine is to be called from SYS_Tasks. The following code shows an example: SYS_MODULE_OBJ object; // Returned from DRV_TOUCH_AR1021_Initialize void SYS_Tasks( void ) { DRV_TOUCH_AR1021_Tasks ( object ); // Do other tasks } Configuring the Library Macros Name Description DRV_AR1021_CALIBRATION_DELAY Define the calibration delay. DRV_AR1021_CALIBRATION_INSET Define the calibration inset. DRV_AR1021_CLIENTS_NUMBER Selects the maximum number of clients. DRV_AR1021_INDEX AR1021 static index selection. DRV_AR1021_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported. DRV_AR1021_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_AR1021_SAMPLE_POINTS Define the sample points. DRV_AR1021_TOUCH_DIAMETER Define the touch diameter. Description The configuration of the AR1021 Touch Driver is accomplished through AR1021 Touch Driver selections in the MPLAB Harmony Configurator (MHC). Based on the selections made, a specific AR1021 Touch Driver is established automatically to execute all system configuration, initialization, and steady-state touch acquisitions. Refer to Volume III: MPLAB Harmony Configurator (MHC) for more details on system configuration. Refer to the Applications Help section for additional information. DRV_AR1021_CALIBRATION_DELAY Macro Define the calibration delay. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1040 File drv_ar1021_config_template.h C #define DRV_AR1021_CALIBRATION_DELAY 300 Description AR1021 Calibration Delay This macro enables the delay between calibration touch points. Remarks None. DRV_AR1021_CALIBRATION_INSET Macro Define the calibration inset. File drv_ar1021_config_template.h C #define DRV_AR1021_CALIBRATION_INSET 25 Description AR1021 Calibration Inset This macro define the calibration inset. Remarks None. DRV_AR1021_CLIENTS_NUMBER Macro Selects the maximum number of clients. File drv_ar1021_config_template.h C #define DRV_AR1021_CLIENTS_NUMBER 1 Description AR1021 Maximum Number of Clients This definition selected the maximum number of clients that the AR1021 driver can support at run time. Remarks None. DRV_AR1021_INDEX Macro AR1021 static index selection. File drv_ar1021_config_template.h C #define DRV_AR1021_INDEX DRV_AR1021_INDEX_0 Description AR1021 Static Index Selection AR1021 static index selection for the driver object reference. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1041 Remarks This index is required to make a reference to the driver object. DRV_AR1021_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported. File drv_ar1021_config_template.h C #define DRV_AR1021_INSTANCES_NUMBER 1 Description AR1021 hardware instance configuration This macro sets up the maximum number of hardware instances that can be supported. Remarks None. DRV_AR1021_INTERRUPT_MODE Macro Controls operation of the driver in the interrupt or polled mode. File drv_ar1021_config_template.h C #define DRV_AR1021_INTERRUPT_MODE false Description AR1021 Interrupt And Polled Mode Operation Control This macro controls the operation of the driver in the interrupt mode of operation. The possible values of this macro are: • true - Select if interrupt mode of AR1021 operation is desired • false - Select if polling mode of AR1021 operation is desired Not defining this option to true or false will result in a build error. Remarks None. DRV_AR1021_SAMPLE_POINTS Macro Define the sample points. File drv_ar1021_config_template.h C #define DRV_AR1021_SAMPLE_POINTS 4 Description AR1021 Sample Points AR1021 sample points Remarks None. DRV_AR1021_TOUCH_DIAMETER Macro Define the touch diameter. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1042 File drv_ar1021_config_template.h C #define DRV_AR1021_TOUCH_DIAMETER 10 Description AR1021 Touch Diameter This macro defines the touch diameter Remarks None. Building the Library This section lists the files that are available in the AR1021 Touch Driver Library. Description This section list the files that are available in the \src folder of the AR1021 Touch 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. 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 /framework/driver/touch/ar1021. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_ar1021.h Header file that exports the driver API. 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 /drv_ar1021.c Basic AR1021 Touch Driver implementation file. 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 N/A No optional files are available for this library. Module Dependencies The AR1021 Touch Driver Library depends on the following modules: • Interrupt System Service Library • Ports System Service Library • Touch System Service Library • I2C Driver Library Library Interface a) System Functions Name Description DRV_TOUCH_AR1021_Deinitialize De-initializes the specified instance of the AR1021 driver module. DRV_TOUCH_AR1021_FactoryDefaultSet Set AR1021 controller to factory default configuration settings. DRV_TOUCH_AR1021_Initialize Initializes the AR1021 instance for the specified driver index Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1043 DRV_TOUCH_AR1021_RegisterConfigWrite Write a value to the given AR1021 configuration register. DRV_TOUCH_AR1021_Status Provides the current status of the AR1021 driver module. DRV_TOUCH_AR1021_Tasks Maintains the driver's state machine and implements its task queue processing. Implementation: Dynamic DRV_TOUCH_AR1021_TouchDataRead Notifies the driver that the current touch data has been read DRV_TOUCH_AR1021_TouchGetX Returns the x coordinate of touch input. Implementation: Dynamic DRV_TOUCH_AR1021_TouchGetY Returns the y coordinate of touch input. Implementation: Dynamic DRV_TOUCH_AR1021_TouchPenGet Returns the PEN state of the touch event. DRV_TOUCH_AR1021_TouchStatus Returns the status of the current touch input. b) Client Functions Name Description DRV_TOUCH_AR1021_Calibrate Calibrate the touch screen DRV_TOUCH_AR1021_CalibrationSet Set calibration with pre-defined points.. DRV_TOUCH_AR1021_Close Closes an opened instance of the AR1021 driver DRV_TOUCH_AR1021_Open Opens the specified AR1021 driver instance and returns a handle to it. Implementation: Dynamic c) Data Types and Constants Name Description DRV_TOUCH_AR1021_CALIBRATION_PROMPT_CALLBACK Defines the callback functions required to inform the user of touch and release targets. DRV_TOUCH_AR1021_HANDLE Touch screen controller AR1021 driver handle. DRV_TOUCH_AR1021_MODULE_ID This is type DRV_TOUCH_AR1021_MODULE_ID. DRV_TOUCH_AR1021_TASK_STATE Enumeration defining AR1021 touch controller driver task state. DRV_TOUCH_AR1021_HANDLE_INVALID Definition of an invalid handle. DRV_TOUCH_AR1021_INDEX_0 AR1021 driver index definitions. DRV_TOUCH_AR1021_INDEX_COUNT Number of valid AR1021 driver indices. Description This section describes the API functions of the AR1021 Touch Driver Library. a) System Functions DRV_TOUCH_AR1021_Deinitialize Function De-initializes the specified instance of the AR1021 driver module. File drv_ar1021.h C void DRV_TOUCH_AR1021_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description De-initializes the specified instance of the AR1021 driver module, disabling its operation (and any hardware) and invalidates all of the internal data. Remarks Once the Initialize operation has been called, the De-initialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_TOUCH_AR1021_Status operation. The system has to use DRV_TOUCH_AR1021_Status to find out when the module is in the ready state. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1044 Preconditions Function DRV_TOUCH_AR1021_Initialize must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Example SYS_MODULE_OBJ object; // Returned from DRV_TOUCH_AR1021_Initialize SYS_STATUS status; DRV_TOUCH_AR1021_Deinitialize ( object ); status = DRV_TOUCH_AR1021_Status( object ); if( SYS_MODULE_UNINITIALIZED == status ) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from DRV_TOUCH_AR1021_Initialize Function void DRV_TOUCH_AR1021_Deinitialize ( SYS_MODULE_OBJ object ) DRV_TOUCH_AR1021_FactoryDefaultSet Function Set AR1021 controller to factory default configuration settings. File drv_ar1021.h C void DRV_TOUCH_AR1021_FactoryDefaultSet(); Returns None Description This function returns the AR1021 to operate on factory default configuration settings. Remarks A power cycle is required to run on the default settings. Preconditions The DRV_TOUCH_AR1021_Open routine must have been called for the specified AR1021 driver instance. Example DRV_TOUCH_AR1021_FactoryDefaultSet ( void ); Function void DRV_TOUCH_AR1021_FactoryDefaultSet(void) DRV_TOUCH_AR1021_Initialize Function Initializes the AR1021 instance for the specified driver index File drv_ar1021.h C SYS_MODULE_OBJ DRV_TOUCH_AR1021_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1045 Returns If successful, returns a valid handle to a driver instance object. Otherwise, returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the AR1021 driver instance for the specified driver index, making it ready for clients to open and use it. The initialization data is specified by the 'init' parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. The driver instance index is independent of the AR1021 module ID. For example, driver instance 0 can be assigned to AR10212. If the driver is built statically, then some of the initialization parameters are overridden by configuration macros. Refer to the description of the DRV_TOUCH_AR1021_INIT data structure for more details on which members on this data structure are overridden. Remarks This routine must be called before any other AR1021 routine is called. This routine should only be called once during system initialization unless DRV_TOUCH_AR1021_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. Preconditions None. Example DRV_TOUCH_INIT drvAr1021InitData; SYS_MODULE_OBJ objectHandle; objectHandle = DRV_TOUCH_AR1021_Initialize(DRV_TOUCH_AR1021_INDEX_1, (SYS_MODULE_INIT*)drvAr1021InitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized. Please note this is not the AR1021 id. The hardware AR1021 id is set in the initialization structure. This is the index of the driver index to use. init Pointer to a data structure containing any data necessary to initialize the driver. If this pointer is NULL, the driver uses the static initialization override macros for each member of the initialization data structure. Function SYS_MODULE_OBJ DRV_TOUCH_AR1021_Initialize( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ) DRV_TOUCH_AR1021_RegisterConfigWrite Function Write a value to the given AR1021 configuration register. File drv_ar1021.h C void DRV_TOUCH_AR1021_RegisterConfigWrite(uint16_t regOffset, uint8_t Value); Returns None Description This function set a value to the given AR1021 configuration register. Remarks none Preconditions The DRV_TOUCH_AR1021_Open routine must have been called for the specified AR1021 driver instance. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1046 Example DRV_TOUCH_AR1021_RegisterConfigWrite(uint16_t regOffset, uint8_t Value); Function void DRV_TOUCH_AR1021_RegisterConfigWrite(uint16_t regOffset, uint8_t Value) DRV_TOUCH_AR1021_Status Function Provides the current status of the AR1021 driver module. File drv_ar1021.h C SYS_STATUS DRV_TOUCH_AR1021_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system level operation and cannot start another Description This function provides the current status of the AR1021 driver module. Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_MODULE_UNINITIALIZED - Indicates that the driver has been deinitialized This value is less than SYS_STATUS_ERROR. This function can be used to determine when any of the driver's module level operations has completed. If the status operation returns SYS_STATUS_BUSY, the previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This function will NEVER block waiting for hardware. If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Preconditions The DRV_TOUCH_AR1021_Initialize function must have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_TOUCH_AR1021_Initialize SYS_STATUS status; status = DRV_TOUCH_AR1021_Status( object ); if( SYS_STATUS_READY != status ) { // Handle error } Parameters Parameters Description object Driver object handle, returned from DRV_TOUCH_AR1021_Initialize Function SYS_STATUS DRV_TOUCH_AR1021_Status ( SYS_MODULE_OBJ object ) DRV_TOUCH_AR1021_Tasks Function Maintains the driver's state machine and implements its task queue processing. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1047 File drv_ar1021.h C void DRV_TOUCH_AR1021_Tasks(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal state machine and implement its command queue processing. It is always called from SYS_Tasks() function. Remarks This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) Preconditions The DRV_TOUCH_AR1021_Initialize routine must have been called for the specified AR1021 driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_TOUCH_AR1021_Initialize while( true ) { DRV_TOUCH_AR1021_Tasks ( object ); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_TOUCH_AR1021_Initialize) Function void DRV_TOUCH_AR1021_Tasks ( SYS_MODULE_OBJ object ); DRV_TOUCH_AR1021_TouchDataRead Function Notifies the driver that the current touch data has been read File drv_ar1021.h C void DRV_TOUCH_AR1021_TouchDataRead(const SYS_MODULE_INDEX index); Returns None. Description Notifies the driver that the current touch data has been read Function void DRV_TOUCH_AR1021_TouchDataRead( const SYS_MODULE_INDEX index ) DRV_TOUCH_AR1021_TouchGetX Function Returns the x coordinate of touch input. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1048 File drv_ar1021.h C short DRV_TOUCH_AR1021_TouchGetX(uint8_t touchNumber); Returns It returns the x coordinate of the touch input in terms of number of pixels. Description It returns the x coordinate in form of number of pixels for a touch input denoted by touchNumber. Parameters Parameters Description touchNumber index to the touch input. Function short DRV_TOUCH_AR1021_TouchGetX( uint8 touchNumber ) DRV_TOUCH_AR1021_TouchGetY Function Returns the y coordinate of touch input. Implementation: Dynamic File drv_ar1021.h C short DRV_TOUCH_AR1021_TouchGetY(uint8_t touchNumber); Returns It returns the y coordinate of the touch input in terms of number of pixels. Description It returns the y coordinate in form of number of pixes for a touch input denoted by touchNumber. Parameters Parameters Description touchNumber index to the touch input. Function short DRV_TOUCH_AR1021_TouchGetY( uint8 touchNumber ) DRV_TOUCH_AR1021_TouchPenGet Function Returns the PEN state of the touch event. File drv_ar1021.h C DRV_TOUCH_PEN_STATE DRV_TOUCH_AR1021_TouchPenGet(uint8_t touchNumber); Returns It returns DRV_TOUCH_PEN_STATE Description It returns the PEN state of the last touch event corresponding to the x and y position. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1049 Parameters Parameters Description touchNumber index to the touch input. Function DRV_TOUCH_PEN_STATE DRV_TOUCH_AR1021_TouchPenGet(uint8_t touchNumber) DRV_TOUCH_AR1021_TouchStatus Function Returns the status of the current touch input. File drv_ar1021.h C DRV_TOUCH_POSITION_STATUS DRV_TOUCH_AR1021_TouchStatus(const SYS_MODULE_INDEX index); Returns It returns the status of the current touch input. Description It returns the status of the current touch input. Function DRV_TOUCH_POSITION_SINGLE DRV_TOUCH_AR1021_TouchStatus( const SYS_MODULE_INDEX index ) b) Client Functions DRV_TOUCH_AR1021_Calibrate Function Calibrate the touch screen File drv_ar1021.h C void DRV_TOUCH_AR1021_Calibrate(const DRV_TOUCH_AR1021_CALIBRATION_PROMPT_CALLBACK * prompt); Returns None Description This function display calibration points on the display to enable calibration. Remarks None Preconditions The DRV_TOUCH_AR1021_Initialize routine must have been called for the specified AR1021 driver instance. Example DRV_TOUCH_AR1021_Calibrate ( handle ); Function void DRV_TOUCH_AR1021_Calibrate ( ( const DRV_TOUCH_AR1021_CALIBRATION_PROMPT_CALLBACK * prompt ) ) DRV_TOUCH_AR1021_CalibrationSet Function Set calibration with pre-defined points.. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1050 File drv_ar1021.h C void DRV_TOUCH_AR1021_CalibrationSet(DRV_TOUCH_SAMPLE_POINTS * samplePoints); Returns None Description This function allows for the setting of pre-loaded calibration points. Remarks None Preconditions The DRV_TOUCH_AR1021_Open routine must have been called for the specified AR1021 driver instance. Example DRV_TOUCH_AR1021_CalibrationSet ( void ); Function void DRV_TOUCH_AR1021_CalibrationSet(void) DRV_TOUCH_AR1021_Close Function Closes an opened instance of the AR1021 driver File drv_ar1021.h C void DRV_TOUCH_AR1021_Close(DRV_HANDLE handle); Returns None Description This function closes an opened instance of the AR1021 driver, invalidating the handle. Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_TOUCH_AR1021_Open before the caller may use the driver again. This function is thread safe in a RTOS application. Usually there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_TOUCH_AR1021_Initialize routine must have been called for the specified AR1021 driver instance. DRV_TOUCH_AR1021_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_TOUCH_AR1021_Open DRV_TOUCH_AR1021_Close ( handle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_TOUCH_AR1021_Close ( DRV_HANDLE handle ) Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1051 DRV_TOUCH_AR1021_Open Function Opens the specified AR1021 driver instance and returns a handle to it. Implementation: Dynamic File drv_ar1021.h C DRV_HANDLE DRV_TOUCH_AR1021_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. An error can occur when the following is true: • if the number of client objects allocated via DRV_TOUCH_AR1021_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the driver hardware instance being opened is not initialized or is invalid Description This routine opens the specified AR1021 driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. The current version of driver does not support the DRV_IO_INTENT feature. The driver is by default non-blocking. The driver can perform both read and write to the AR1021 device. The driver supports single client only. Remarks The handle returned is valid until the DRV_TOUCH_AR1021_Close routine is called. This routine will NEVER block waiting for hardware. If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. It should not be called in an ISR. Preconditions The DRV_TOUCH_AR1021_Initialize function must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_TOUCH_AR1021_Open( DRV_TOUCH_AR1021_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); if( DRV_HANDLE_INVALID == handle ) { // Unable to open the driver } Parameters Parameters Description drvIndex Index of the driver initialized with DRV_TOUCH_AR1021_Initialize(). intent Zero or more of the values from the enumeration DRV_IO_INTENT ORed together to indicate the intended use of the driver. The current version of driver does not support the selective IO intent feature. Function DRV_HANDLE DRV_TOUCH_AR1021_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ) c) Data Types and Constants DRV_TOUCH_AR1021_CALIBRATION_PROMPT_CALLBACK Structure Defines the callback functions required to inform the user of touch and release targets. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1052 File drv_ar1021.h C typedef struct { void (* firstPromptCallback)(void); void (* secondPromptCallback)(void); void (* thirdPromptCallback)(void); void (* fourthPromptCallback)(void); void (* completeCallback)(void); } DRV_TOUCH_AR1021_CALIBRATION_PROMPT_CALLBACK; Members Members Description void (* firstPromptCallback)(void); first calibration target void (* secondPromptCallback)(void); second calibration target void (* thirdPromptCallback)(void); third calibration target void (* fourthPromptCallback)(void); fourth calibration target void (* completeCallback)(void); complete calibration Description TOUCH Driver Calibration Initialization Data This data type defines the callback function pointers required to inform of touch and release targets. The driver will invoke each callback in sequential order. The host code can display graphic and/or textual content to direct the user when a where on the LCD display to touch and release. Remarks None. DRV_TOUCH_AR1021_HANDLE Type Touch screen controller AR1021 driver handle. File drv_ar1021.h C typedef uintptr_t DRV_TOUCH_AR1021_HANDLE; Description AR1021 Driver Handle Touch controller AR1021 driver handle is a handle for the driver client object. Each driver with successful open call will return a new handle to the client object. Remarks None. DRV_TOUCH_AR1021_MODULE_ID Enumeration File drv_ar1021.h C typedef enum { AR1021_ID_1 = 0, AR1021_NUMBER_OF_MODULES } DRV_TOUCH_AR1021_MODULE_ID; Description This is type DRV_TOUCH_AR1021_MODULE_ID. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1053 DRV_TOUCH_AR1021_TASK_STATE Enumeration Enumeration defining AR1021 touch controller driver task state. File drv_ar1021.h C typedef enum { DRV_TOUCH_AR1021_TASK_STATE_INIT = 0, DRV_TOUCH_AR1021_TASK_STATE_DONE } DRV_TOUCH_AR1021_TASK_STATE; Members Members Description DRV_TOUCH_AR1021_TASK_STATE_INIT = 0 Task initialize state DRV_TOUCH_AR1021_TASK_STATE_DONE Task complete state Description AR1021 Touch Controller Driver Task State This enumeration defines the AR1021 touch controller driver task state. The task state helps to synchronize the operations of initialization the the task, adding the read input task to the task queue once the touch controller notifies the available touch input and a decoding the touch input received. Remarks None. DRV_TOUCH_AR1021_HANDLE_INVALID Macro Definition of an invalid handle. File drv_ar1021.h C #define DRV_TOUCH_AR1021_HANDLE_INVALID ((DRV_TOUCH_AR1021_HANDLE)(-1)) Description AR1021 Driver Invalid Handle This is the definition of an invalid handle. An invalid handle is is returned by DRV_TOUCH_AR1021_Open() and DRV_AR1021_Close() functions if the request was not successful. Remarks None. DRV_TOUCH_AR1021_INDEX_0 Macro AR1021 driver index definitions. File drv_ar1021.h C #define DRV_TOUCH_AR1021_INDEX_0 0 Description AR1021 Driver Module Index Numbers These constants provide the AR1021 driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_AR1021_Initialize and Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1054 DRV_AR1021_Open functions to identify the driver instance in use. DRV_TOUCH_AR1021_INDEX_COUNT Macro Number of valid AR1021 driver indices. File drv_ar1021.h C #define DRV_TOUCH_AR1021_INDEX_COUNT 1 Description AR1021 Driver Module Index Count This constant identifies the number of valid AR1021 driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific header files defined as part of the peripheral libraries. Files Files Name Description drv_ar1021.h Touch controller AR1021 driver implementation. Description This section lists the source and header files used by the AR1021 Touch Driver Library. drv_ar1021.h Touch controller AR1021 driver implementation. Enumerations Name Description DRV_TOUCH_AR1021_MODULE_ID This is type DRV_TOUCH_AR1021_MODULE_ID. DRV_TOUCH_AR1021_TASK_STATE Enumeration defining AR1021 touch controller driver task state. Functions Name Description DRV_TOUCH_AR1021_Calibrate Calibrate the touch screen DRV_TOUCH_AR1021_CalibrationSet Set calibration with pre-defined points.. DRV_TOUCH_AR1021_Close Closes an opened instance of the AR1021 driver DRV_TOUCH_AR1021_Deinitialize De-initializes the specified instance of the AR1021 driver module. DRV_TOUCH_AR1021_FactoryDefaultSet Set AR1021 controller to factory default configuration settings. DRV_TOUCH_AR1021_Initialize Initializes the AR1021 instance for the specified driver index DRV_TOUCH_AR1021_Open Opens the specified AR1021 driver instance and returns a handle to it. Implementation: Dynamic DRV_TOUCH_AR1021_RegisterConfigWrite Write a value to the given AR1021 configuration register. DRV_TOUCH_AR1021_Status Provides the current status of the AR1021 driver module. DRV_TOUCH_AR1021_Tasks Maintains the driver's state machine and implements its task queue processing. Implementation: Dynamic DRV_TOUCH_AR1021_TouchDataRead Notifies the driver that the current touch data has been read DRV_TOUCH_AR1021_TouchGetX Returns the x coordinate of touch input. Implementation: Dynamic DRV_TOUCH_AR1021_TouchGetY Returns the y coordinate of touch input. Implementation: Dynamic DRV_TOUCH_AR1021_TouchPenGet Returns the PEN state of the touch event. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1055 DRV_TOUCH_AR1021_TouchStatus Returns the status of the current touch input. Macros Name Description DRV_TOUCH_AR1021_HANDLE_INVALID Definition of an invalid handle. DRV_TOUCH_AR1021_INDEX_0 AR1021 driver index definitions. DRV_TOUCH_AR1021_INDEX_COUNT Number of valid AR1021 driver indices. Structures Name Description DRV_TOUCH_AR1021_CALIBRATION_PROMPT_CALLBACK Defines the callback functions required to inform the user of touch and release targets. Types Name Description DRV_TOUCH_AR1021_HANDLE Touch screen controller AR1021 driver handle. Description Touch controller AR1021 driver file This file consist of touch controller AR1021 driver interfaces. It implements the driver interfaces which read the touch input data from AR1021 through SPI bus. File Name drv_ar1021.c MTCH6301 Touch Driver Library This topic describes the MTCH6301 Touch Driver Library. Introduction This library provides an interface to manage the MTCH6301 Touch Driver module on the Microchip family of microcontrollers in different modes of operation. Description The MPLAB Harmony MTCH6301 Touch Driver provides a high-level interface to the MTCH6301 touch controller device. This driver provides application routines to read the touch input data from the touch screen. The MTCH6301 device can notify the availability of touch input data through external interrupt. The MTCH6301 driver allows the application to map a controller pin as an external interrupt pin. Currently, the MTCH6301 Touch Driver only supports non-gestural single-fingered touch input. Using the Library This topic describes the basic architecture of the MTCH6301 Touch Driver Library and provides information and examples on its use. Description Interface Header File: drv_mtch6301.h The interface to the MTCH6301 Touch Driver library is defined in the drv_mtch6301.h header file. Any C language source (.c) file that uses the MTCH6301 Touch Driver library should include this header. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the MTCH6301 Touch Driver Library 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 MTCH6301 Touch Driver has routines to perform the following operations: • Sending read request • Reading the touch input data Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1056 • Access to the touch input data The driver initialization routines allow the application to initialize the driver. The driver must be initialized before it can be used by application. Once the driver is initialized the driver open routine allows to retrieve the client handle. Once the touch input is available a touch input read request is sent and input data is retrieved in a buffer. The buffer data is then decoded to get the x and y coordinate of the touch screen in the form of the number of pixels. MTCH6301 Driver Abstraction Model Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the MTCH6301 Touch Driver. Library Interface Section Description System Functions Provides system module interfaces, device initialization, deinitialization, open, close, task, and status functions. How the Library Works The library provides interfaces to support: • System functions, which provide system module interfaces, device initialization, deinitialization, open, close, task, and status functions. • Read Request function, which provides Touch input data read request function • Read Touch Input function, which provides functions retrieving updated Touch input in the form x and y coordinates. Initializing the Driver Before the MTCH6301 Touch Driver can be opened, it must be configured and initialized. The driver build time configuration is defined by the configuration macros. Refer to the Building the Library section for the location of and more information on the various configuration macros and how these macros should be designed. The driver initialization is configured through the DRV_TOUCH_INIT data structure that is passed to the DRV_TOUCH_MTCH6301_Initialize function. The initialization parameters include the interrupt source, interrupt pin remap configuration and touch screen resolution. The following code shows an example of initializing the MTCH6301 Touch Driver. Example: /* The following code shows an example of designing the * DRV_TOUCH_INIT data structure. It also shows how an example * usage of the DRV_TOUCH_MTCH6301_Initialize function. */ Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1057 DRV_TOUCH_INIT drvTouchInitData; SYS_MODULE_OBJ objectHandle; /* Touch Module Id*/ drvTouchInitData.touchId = DRV_TOUCH_INDEX_0; /* I2C Bus driver open */ drvTouchInitData.drvOpen = DRV_I2C_Open; /* Interrupt Source for Touch */ drvTouchInitData.interruptSource = INT_SOURCE_EXTERNAL_1; /* Interrupt Pin function mapping */ drvTouchInitData.interruptPort.inputFunction = INPUT_FUNC_INT1; /* Pin to be mapped as interrupt pin */ drvTouchInitData.interruptPort.inputPin = INPUT_PIN_RPE8; /* Analog pin number */ drvTouchInitData.interruptPort.analogPin = PORTS_ANALOG_PIN_25; /* Pin Mode of analog pin */ drvTouchInitData.interruptPort.pinMode = PORTS_PIN_MODE_DIGITAL; /* Interrupt pin port */ drvTouchInitData.interruptPort.channel = PORT_CHANNEL_E; /* Interrupt pin port maskl */ drvTouchInitData.interruptPort.dataMask = 0x8; /* Touch screen orientation */ drvTouchInitData.orientation = DISP_ORIENTATION; /* Touch screen horizontal resolution */ drvTouchInitData.horizontalResolution = DISP_HOR_RESOLUTION; /* Touch screen vertical resolution */ drvTouchInitData.verticalResolution = DISP_VER_RESOLUTION; /* Driver initialization */ objectHandle = DRV_TOUCH_MTCH6301_Initialize(DRV_TOUCH_INDEX_0, (SYS_MODULE_INIT*)drvTouchInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Opening the Driver To use the MTCH6301 Touch Driver, the application must open the driver. This is done by calling the DRV_TOUCH_MTCH6301_Open function. If successful, the DRV_TOUCH_MTCH6301_Open function will return a handle to the driver. This handle records the association between the client and the driver instance that was opened. The DRV_TOUCH_MTCH6301_Open function may return DRV_HANDLE_INVALID in the situation where the driver is not ready to be opened. When this occurs, the application can try opening the driver again. Note that the open function may return an invalid handle in other (error) cases as well. The following code shows an example of the driver being opened. DRV_HANDLE handle; handle = DRV_TOUCH_MTCH6301_Open( DRV_TOUCH_MTCH6301_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); if( DRV_HANDLE_INVALID == handle ) { // Unable to open the driver } Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1058 Touch Input Read Request To read the touch input from the MTCH6301 touch controller device, a read request must be registered. This is done by calling the DRV_TOUCH_MTCH6301_ReadRequest. If successful it registers a buffer read request to the I2C command queue. It also adds a input decode command to the MTCH6301 command queue once the I2C returns with touch input data. It can return error if the driver instance object is invalid or the MTCH6301 command queue is full. The read request is to be called from the MTCH6301 ISR. This ISR is triggered once the touch input is available. The following code shows an example of a MTCH6301 read request registration: SYS_MODULE_OBJ object; // Returned from DRV_TOUCH_MTCH6301_Initialize void __ISR(_EXTERNAL_INT_VECTOR, ipl5) _IntHandlerDrvMtch6301(void) { DRV_TOUCH_MTCH6301_ReadRequest ( object ); // Do other tasks } Tasks Routine This routine processes the MTCH6301 commands from the command queue. If the state of the command is initialize or done it returns. If the read request registration is successful the state of command is to decode input. The tasks routine decodes the input and updates the global variables storing the touch input data in form of x and y coordinates. The MTCH6301 Touch Driver task routine is to be called from SYS_Tasks. The following code shows an example: SYS_MODULE_OBJ object; // Returned from DRV_TOUCH_MTCH6301_Initialize void SYS_Tasks( void ) { DRV_TOUCH_MTCH6301_Tasks ( object ); // Do other tasks } Configuring the Library Macros Name Description DRV_MTCH6301_CALIBRATION_DELAY Defines the calibration delay. DRV_MTCH6301_CALIBRATION_INSET Defines the calibration inset. DRV_MTCH6301_CLIENTS_NUMBER Selects the maximum number of clients. DRV_MTCH6301_INDEX MTCH6301 static index selection. DRV_MTCH6301_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported. DRV_MTCH6301_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_MTCH6301_SAMPLE_POINTS Define the sample points. DRV_MTCH6301_TOUCH_DIAMETER Defines the touch diameter. Description The configuration of the MTCH6301 Touch Driver is based on the file system_config.h. This header file contains the configuration selection for the MTCH6301 Touch Driver. Based on the selections made, the driver may support the selected features. These configuration settings will apply to all instances of the MTCH6301 Touch Driver. This header can be placed anywhere, 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. DRV_MTCH6301_CALIBRATION_DELAY Macro Defines the calibration delay. File drv_mtch6301_config_template.h C #define DRV_MTCH6301_CALIBRATION_DELAY 300 Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1059 Description MTCH6301 Calibration Delay This macro enables the delay between calibration touch points. Remarks None. DRV_MTCH6301_CALIBRATION_INSET Macro Defines the calibration inset. File drv_mtch6301_config_template.h C #define DRV_MTCH6301_CALIBRATION_INSET 25 Description MTCH6301 Calibration Inset This macro defines the calibration inset. Remarks None. DRV_MTCH6301_CLIENTS_NUMBER Macro Selects the maximum number of clients. File drv_mtch6301_config_template.h C #define DRV_MTCH6301_CLIENTS_NUMBER 1 Description MTCH6301 maximum number of clients This macro selects the maximum number of clients. This definition selected the maximum number of clients that the MTCH6301 driver can support at run time. Remarks None. DRV_MTCH6301_INDEX Macro MTCH6301 static index selection. File drv_mtch6301_config_template.h C #define DRV_MTCH6301_INDEX DRV_MTCH6301_INDEX_0 Description MTCH6301 Static Index Selection This macro specifies the static index selection for the driver object reference. Remarks This index is required to make a reference to the driver object. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1060 DRV_MTCH6301_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported. File drv_mtch6301_config_template.h C #define DRV_MTCH6301_INSTANCES_NUMBER 1 Description MTCH6301 hardware instance configuration This macro sets up the maximum number of hardware instances that can be supported. Remarks None. DRV_MTCH6301_INTERRUPT_MODE Macro Controls operation of the driver in the interrupt or polled mode. File drv_mtch6301_config_template.h C #define DRV_MTCH6301_INTERRUPT_MODE false Description MTCH6301 Interrupt And Polled Mode Operation Control This macro controls the operation of the driver in the interrupt mode of operation. The possible values of this macro are: • true - Select if interrupt mode of MTCH6301 operation is desired • false - Select if polling mode of MTCH6301 operation is desired Not defining this option to true or false will result in a build error. Remarks None. DRV_MTCH6301_SAMPLE_POINTS Macro Define the sample points. File drv_mtch6301_config_template.h C #define DRV_MTCH6301_SAMPLE_POINTS 4 Description MTCH6301 Sample Points MTCH6301 sample points Remarks None. DRV_MTCH6301_TOUCH_DIAMETER Macro Defines the touch diameter. File drv_mtch6301_config_template.h Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1061 C #define DRV_MTCH6301_TOUCH_DIAMETER 10 Description MTCH6301 Touch Diameter This macro defines the touch diameter Remarks None. Building the Library This section lists the files that are available in the MTCH6301 Touch Driver Library. Description This section list the files that are available in the \src folder of the MTCH6301 Touch 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. 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 /framework/driver/touch/mtch6301. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_mtch6301.h Header file that exports the driver API. 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 /src/drv_mtch6301.c Basic MTCH6301 Touch Driver implementation file. 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 N/A No optional files are available for this library. Module Dependencies The MTCH6301 Touch Driver Library depends on the following modules: • Interrupt System Service Library • Ports System Service Library • Touch System Service Library • I2C Driver Library Library Interface a) System Functions Name Description DRV_TOUCH_MTCH6301_Close Closes an opened instance of the MTCH6301 driver. Implementation: Dynamic DRV_TOUCH_MTCH6301_Deinitialize Deinitializes the specified instance of the MTCH6301 driver module. Implementation: Dynamic DRV_TOUCH_MTCH6301_Initialize Initializes the MTCH6301 instance for the specified driver index. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1062 DRV_TOUCH_MTCH6301_Open Opens the specified MTCH6301 driver instance and returns a handle to it. Implementation: Dynamic DRV_TOUCH_MTCH6301_Status Provides the current status of the MTCH6301 driver module. Implementation: Dynamic DRV_TOUCH_MTCH6301_Tasks Maintains the driver's state machine and implements its task queue processing. Implementation: Dynamic DRV_TOUCH_MTCH6301_ReadRequest Sends a read request to I2C bus driver and adds the read task to queue. Implementation: Dynamic DRV_TOUCH_MTCH6301_TouchGetX Returns the x coordinate of touch input. Implementation: Dynamic DRV_TOUCH_MTCH6301_TouchGetY Returns the y coordinate of touch input. Implementation: Dynamic DRV_TOUCH_MTCH6301_TouchDataRead Notifies the driver that the current touch data has been read DRV_TOUCH_MTCH6301_TouchStatus Returns the status of the current touch input. b) Data Types and Constants Name Description _DRV_MTCH6301_CLIENT_OBJECT MTCH6301 Driver client object maintaining client data. DRV_TOUCH_MTCH6301_HANDLE Touch screen controller MTCH6301 driver handle. DRV_TOUCH_MTCH6301_MODULE_ID Number of valid MTCH6301 driver indices. DRV_TOUCH_MTCH6301_HANDLE_INVALID Definition of an invalid handle. DRV_TOUCH_MTCH6301_I2C_READ_FRAME_SIZE I2C Frame size for reading MTCH6301 touch input. DRV_TOUCH_MTCH6301_CLIENT_OBJECT MTCH6301 Driver client object maintaining client data. DRV_TOUCH_MTCH6301_INDEX_0 MTCH6301 driver index definitions. DRV_TOUCH_MTCH6301_INDEX_1 This is macro DRV_TOUCH_MTCH6301_INDEX_1. DRV_TOUCH_MTCH6301_INDEX_COUNT Number of valid Touch controller MTCH6301 driver indices. DRV_TOUCH_MTCH6301_OBJECT Defines the data structure maintaining MTCH6301 driver instance object. DRV_TOUCH_MTCH6301_TASK_QUEUE Defines the MTCH6301 Touch Controller driver task data structure. DRV_TOUCH_MTCH6301_TASK_STATE Enumeration defining MTCH6301 touch controller driver task state. DRV_TOUCH_MTCH6301_I2C_MASTER_READ_ID MTCH6301 input read, I2C address from where master reads touch input data. DRV_TOUCH_MTCH6301_I2C_MASTER_WRITE_ID MTCH6301 command register write, I2C address where master sends the commands. Description This section describes the API functions of the MTCH6301 Touch Driver library. Refer to each section for a detailed description. a) System Functions DRV_TOUCH_MTCH6301_Close Function Closes an opened instance of the MTCH6301 driver. Implementation: Dynamic File drv_mtch6301.h C void DRV_TOUCH_MTCH6301_Close(DRV_HANDLE handle); Returns None Description This function closes an opened instance of the MTCH6301 driver, invalidating the handle. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1063 Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_TOUCH_MTCH6301_Open before the caller may use the driver again. This function is thread safe in a RTOS application. Usually, there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_TOUCH_MTCH6301_Initialize routine must have been called for the specified MTCH6301 driver instance. DRV_TOUCH_MTCH6301_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_TOUCH_MTCH6301_Open DRV_TOUCH_MTCH6301_Close ( handle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_TOUCH_MTCH6301_Close ( DRV_HANDLE handle ) DRV_TOUCH_MTCH6301_Deinitialize Function Deinitializes the specified instance of the MTCH6301 driver module. Implementation: Dynamic File drv_mtch6301.h C void DRV_TOUCH_MTCH6301_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the MTCH6301 driver module, disabling its operation (and any hardware) and invalidates all of the internal data. Remarks Once the Initialize operation has been called, the De-initialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_TOUCH_MTCH6301_Status operation. The system has to use DRV_TOUCH_MTCH6301_Status to determine when the module is in the ready state. Preconditions Function DRV_TOUCH_MTCH6301_Initialize must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Parameter: object - Driver object handle, returned from DRV_TOUCH_MTCH6301_Initialize Example SYS_MODULE_OBJ object; //Returned from DRV_TOUCH_MTCH6301_Initialize SYS_STATUS status; DRV_TOUCH_MTCH6301_Deinitialize ( object ); status = DRV_TOUCH_MTCH6301_Status( object ); if( SYS_MODULE_UNINITIALIZED == status ) { // Check again later if you need to know // when the driver is deinitialized. } Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1064 Function void DRV_TOUCH_MTCH6301_Deinitialize ( SYS_MODULE_OBJ object ) DRV_TOUCH_MTCH6301_Initialize Function Initializes the MTCH6301 instance for the specified driver index. Implementation: Dynamic File drv_mtch6301.h C SYS_MODULE_OBJ DRV_TOUCH_MTCH6301_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the MTCH6301 driver instance for the specified driver index, making it ready for clients to open and use it. The initialization data is specified by the 'init' parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. The driver instance index is independent of the MTCH6301 module ID. For example, driver instance 0 can be assigned to MTCH63012. If the driver is built statically, then some of the initialization parameters are overridden by configuration macros. Refer to the description of the DRV_TOUCH_MTCH6301_INIT data structure for more details on which members on this data structure are overridden. Remarks This routine must be called before any other MTCH6301 routine is called. This routine should only be called once during system initialization unless DRV_TOUCH_MTCH6301_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. Preconditions None. Example DRV_TOUCH_MTCH6301_INIT init; SYS_MODULE_OBJ objectHandle; // Populate the MTCH6301 initialization structure // Touch Module Id init.touchId = DRV_TOUCH_INDEX_0; // I2C Bus driver open init.drvOpen = DRV_I2C_Open; // Interrupt Source for Touch init.interruptSource = INT_SOURCE_EXTERNAL_1; // Interrupt Pin function mapping init.interruptPort.inputFunction = INPUT_FUNC_INT1; // Pin to be mapped as interrupt pin init.interruptPort.inputPin = INPUT_PIN_RPE8; // Analog pin number init.interruptPort.analogPin = PORTS_ANALOG_PIN_25; // Pin Mode of analog pin init.interruptPort.pinMode = PORTS_PIN_MODE_DIGITAL; // Interrupt pin port init.interruptPort.channel = PORT_CHANNEL_E; // Interrupt pin port maskl init.interruptPort.dataMask = 0x8; Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1065 // Touch screen orientation init.orientation = DISP_ORIENTATION; // Touch screen horizontal resolution init.horizontalResolution = DISP_HOR_RESOLUTION; // Touch screen vertical resolution init.verticalResolution = DISP_VER_RESOLUTION; objectHandle = DRV_TOUCH_MTCH6301_Initialize(DRV_TOUCH_INDEX_0, (SYS_MODULE_INIT*)init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized. Please note this is not the MTCH6301 ID. The hardware MTCH6301 ID is set in the initialization structure. This is the index of the driver index to use. init Pointer to a data structure containing any data necessary to initialize the driver. If this pointer is NULL, the driver uses the static initialization override macros for each member of the initialization data structure. Function SYS_MODULE_OBJ DRV_TOUCH_MTCH6301_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ) DRV_TOUCH_MTCH6301_Open Function Opens the specified MTCH6301 driver instance and returns a handle to it. Implementation: Dynamic File drv_mtch6301.h C DRV_HANDLE DRV_TOUCH_MTCH6301_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. An error can occur when the following is true: • if the number of client objects allocated via DRV_TOUCH_MTCH6301_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the driver hardware instance being opened is not initialized or is invalid Description This routine opens the specified MTCH6301 driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. The current version of driver does not support the DRV_IO_INTENT feature. The driver is by default non-blocking. The driver can perform both read and write to the MTCH6301 device. The driver supports single client only. Remarks The handle returned is valid until the DRV_TOUCH_MTCH6301_Close routine is called. This routine will NEVER block waiting for hardware. If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. It should not be called in an ISR. Preconditions The DRV_TOUCH_MTCH6301_Initialize function must have been called before calling this function. Example DRV_HANDLE handle; Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1066 handle = DRV_TOUCH_MTCH6301_Open( DRV_TOUCH_MTCH6301_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); if( DRV_HANDLE_INVALID == handle ) { // Unable to open the driver } Parameters Parameters Description drvIndex Index of the driver initialized with DRV_TOUCH_MTCH6301_Initialize(). intent Zero or more of the values from the enumeration DRV_IO_INTENT ORed together to indicate the intended use of the driver. The current version of driver does not support the selective IO intent feature. Function DRV_HANDLE DRV_TOUCH_MTCH6301_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ) DRV_TOUCH_MTCH6301_Status Function Provides the current status of the MTCH6301 driver module. Implementation: Dynamic File drv_mtch6301.h C SYS_STATUS DRV_TOUCH_MTCH6301_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system-level operation and cannot start another Description This function provides the current status of the MTCH6301 driver module. Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_MODULE_UNINITIALIZED - Indicates that the driver has been deinitialized This value is less than SYS_STATUS_ERROR. This function can be used to determine when any of the driver's module level operations has completed. If the status operation returns SYS_STATUS_BUSY, the previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This function will NEVER block waiting for hardware. If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Preconditions The DRV_TOUCH_MTCH6301_Initialize function must have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_TOUCH_MTCH6301_Initialize SYS_STATUS status; status = DRV_TOUCH_MTCH6301_Status( object ); if( SYS_STATUS_READY != status ) { // Handle error } Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1067 Parameters Parameters Description object Driver object handle, returned from DRV_TOUCH_MTCH6301_Initialize Function SYS_STATUS DRV_TOUCH_MTCH6301_Status ( SYS_MODULE_OBJ object ) DRV_TOUCH_MTCH6301_Tasks Function Maintains the driver's state machine and implements its task queue processing. Implementation: Dynamic File drv_mtch6301.h C void DRV_TOUCH_MTCH6301_Tasks(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal state machine and implement its command queue processing. It is always called from SYS_Tasks() function. This routine decodes the touch input data available in drvI2CReadFrameData. Remarks This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) Preconditions The DRV_TOUCH_MTCH6301_Initialize routine must have been called for the specified MTCH6301 driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_TOUCH_MTCH6301_Initialize void SYS_Tasks( void ) { DRV_TOUCH_MTCH6301_Tasks ( object ); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_TOUCH_MTCH6301_Initialize) Function void DRV_TOUCH_MTCH6301_Tasks ( SYS_MODULE_OBJ object ); DRV_TOUCH_MTCH6301_ReadRequest Function Sends a read request to I2C bus driver and adds the read task to queue. Implementation: Dynamic File drv_mtch6301.h C void DRV_TOUCH_MTCH6301_ReadRequest(SYS_MODULE_OBJ object); Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1068 Returns None. Description This routine is used to send a touch input read request to the I2C bus driver and adding the input read decode task to the queue. It is always called from MTCH6301 interrupt ISR routine. Remarks This function is normally not called directly by an application. It is called by the MTCH6301 ISR routine. Preconditions The DRV_TOUCH_MTCH6301_Initialize routine must have been called for the specified MTCH6301 driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_TOUCH_MTCH6301_Initialize void __ISR(_EXTERNAL_INT_VECTOR, ipl5) _IntHandlerDrvMtch6301(void) { DRV_TOUCH_MTCH6301_ReadRequest ( object ); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_TOUCH_MTCH6301_Initialize) Function void DRV_TOUCH_MTCH6301_ReadRequest( SYS_MODULE_OBJ object ) DRV_TOUCH_MTCH6301_TouchGetX Function Returns the x coordinate of touch input. Implementation: Dynamic File drv_mtch6301.h C short DRV_TOUCH_MTCH6301_TouchGetX(uint8_t touchNumber); Returns It returns the x coordinate of the touch input in terms of number of pixels. Description It returns the x coordinate in form of number of pixes for a touch input denoted by touchNumber. Parameters Parameters Description touchNumber index to the touch input. Function short DRV_TOUCH_MTCH6301_TouchGetX( uint8 touchNumber ) DRV_TOUCH_MTCH6301_TouchGetY Function Returns the y coordinate of touch input. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1069 File drv_mtch6301.h C short DRV_TOUCH_MTCH6301_TouchGetY(uint8_t touchNumber); Returns It returns the y coordinate of the touch input in terms of number of pixels. Description It returns the y coordinate in form of number of pixes for a touch input denoted by touchNumber. Parameters Parameters Description touchNumber index to the touch input. Function short DRV_TOUCH_MTCH6301_TouchGetY( uint8 touchNumber ) DRV_TOUCH_MTCH6301_TouchDataRead Function Notifies the driver that the current touch data has been read File drv_mtch6301.h C void DRV_TOUCH_MTCH6301_TouchDataRead(const SYS_MODULE_INDEX index); Returns None. Description Notifies the driver that the current touch data has been read Function void DRV_TOUCH_MTCH6301_TouchDataRead( const SYS_MODULE_INDEX index ) DRV_TOUCH_MTCH6301_TouchStatus Function Returns the status of the current touch input. File drv_mtch6301.h C DRV_TOUCH_POSITION_STATUS DRV_TOUCH_MTCH6301_TouchStatus(const SYS_MODULE_INDEX index); Returns It returns the status of the current touch input. Description It returns the status of the current touch input. Function DRV_TOUCH_POSITION_SINGLE DRV_TOUCH_MTCH6301_TouchStatus( const SYS_MODULE_INDEX index ) b) Data Types and Constants Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1070 DRV_TOUCH_MTCH6301_HANDLE Type Touch screen controller MTCH6301 driver handle. File drv_mtch6301.h C typedef uintptr_t DRV_TOUCH_MTCH6301_HANDLE; Description MTCH6301 Driver Handle Touch controller MTCH6301 driver handle is a handle for the driver client object. Each driver with succesful open call will return a new handle to the client object. Remarks None. DRV_TOUCH_MTCH6301_MODULE_ID Enumeration Number of valid MTCH6301 driver indices. File drv_mtch6301.h C typedef enum { MTCH6301_ID_1 = 0, MTCH6301_NUMBER_OF_MODULES } DRV_TOUCH_MTCH6301_MODULE_ID; Description MTCH6301 Driver Module Index Count This constant identifies the number of valid MTCH6301 driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific header files defined as part of the peripheral libraries. DRV_TOUCH_MTCH6301_HANDLE_INVALID Macro Definition of an invalid handle. File drv_mtch6301.h C #define DRV_TOUCH_MTCH6301_HANDLE_INVALID ((DRV_TOUCH_MTCH6301_HANDLE)(-1)) Description MTCH6301 Driver Invalid Handle This is the definition of an invalid handle. An invalid handle is is returned by DRV_TOUCH_MTCH6301_Open() and DRV_MTCH6301_Close() functions if the request was not successful. Remarks None. DRV_TOUCH_MTCH6301_I2C_READ_FRAME_SIZE Macro I2C Frame size for reading MTCH6301 touch input. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1071 File drv_mtch6301.h C #define DRV_TOUCH_MTCH6301_I2C_READ_FRAME_SIZE 7 Description MTCH6301 Driver Module I2C Frame Size This constant identifies the size of I2C frame required to read from MTCH6301 touch controller. MTCH6301 notifies the availability of input data through interrupt pin. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific data sheets. DRV_TOUCH_MTCH6301_CLIENT_OBJECT Structure MTCH6301 Driver client object maintaining client data. File drv_mtch6301.h C typedef struct _DRV_MTCH6301_CLIENT_OBJECT { DRV_TOUCH_MTCH6301_OBJECT* driverObject; DRV_IO_INTENT intent; struct DRV_TOUCH_MTCH6301_CLIENT_OBJECT* pNext; } DRV_TOUCH_MTCH6301_CLIENT_OBJECT; Members Members Description DRV_TOUCH_MTCH6301_OBJECT* driverObject; Driver Object associated with the client DRV_IO_INTENT intent; The intent with which the client was opened struct DRV_TOUCH_MTCH6301_CLIENT_OBJECT* pNext; Next driver client object Description MTCH6301 Driver client object This defines the object required for the maintenance of the software clients instance. This object exists once per client instance. Remarks None. DRV_TOUCH_MTCH6301_INDEX_0 Macro MTCH6301 driver index definitions. File drv_mtch6301.h C #define DRV_TOUCH_MTCH6301_INDEX_0 0 Description MTCH6301 Driver Module Index Numbers These constants provide the MTCH6301 driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_MTCH6301_Initialize and DRV_MTCH6301_Open functions to identify the driver instance in use. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1072 DRV_TOUCH_MTCH6301_INDEX_1 Macro File drv_mtch6301.h C #define DRV_TOUCH_MTCH6301_INDEX_1 1 Description This is macro DRV_TOUCH_MTCH6301_INDEX_1. DRV_TOUCH_MTCH6301_INDEX_COUNT Macro Number of valid Touch controller MTCH6301 driver indices. File drv_mtch6301.h C #define DRV_TOUCH_MTCH6301_INDEX_COUNT 2 Description MTCH6301 Driver Module Index Count This constant identifies the number of valid Touch Controller MTCH6301 driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific header files defined as part of the peripheral libraries. DRV_TOUCH_MTCH6301_OBJECT Structure Defines the data structure maintaining MTCH6301 driver instance object. File drv_mtch6301.h C typedef struct { SYS_STATUS status; int touchId; SYS_MODULE_INDEX drvIndex; bool inUse; bool isExclusive; uint8_t numClients; INT_SOURCE interruptSource; uint16_t orientation; uint16_t horizontalResolution; uint16_t verticalResolution; DRV_HANDLE (* drvOpen)(const SYS_MODULE_INDEX index, const DRV_IO_INTENT intent); int32_t readRequest; DRV_TOUCH_MTCH6301_TASK_QUEUE* taskQueue; DRV_HANDLE drvI2CHandle; DRV_TOUCH_POSITION_STATUS touchStatus; } DRV_TOUCH_MTCH6301_OBJECT; Members Members Description SYS_STATUS status; The status of the driver int touchId; The peripheral Id associated with the object SYS_MODULE_INDEX drvIndex; Save the index of the driver. Important to know this as we are using reference based accessing bool inUse; Flag to indicate instance in use bool isExclusive; Flag to indicate module used in exclusive access mode Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1073 uint8_t numClients; Number of clients possible with the hardware instance INT_SOURCE interruptSource; Touch input interrupt source uint16_t orientation; Orientation of the display (given in degrees of 0,90,180,270) uint16_t horizontalResolution; Horizontal Resolution of the displayed orientation in Pixels uint16_t verticalResolution; Vertical Resolution of the displayed orientaion in Pixels DRV_HANDLE (* drvOpen)(const SYS_MODULE_INDEX index, const DRV_IO_INTENT intent); Callback for I2C Driver Open call int32_t readRequest; Touch Input read request counter DRV_TOUCH_MTCH6301_TASK_QUEUE* taskQueue; Head of the task queue DRV_HANDLE drvI2CHandle; I2C bus driver handle DRV_TOUCH_POSITION_STATUS touchStatus; Touch status Description MTCH6301 Driver Instance Object. This data structure maintains the MTCH6301 driver instance object. The object exists once per hardware instance. Remarks None. DRV_TOUCH_MTCH6301_TASK_QUEUE Structure Defines the MTCH6301 Touch Controller driver task data structure. File drv_mtch6301.h C typedef struct { bool inUse; DRV_TOUCH_MTCH6301_TASK_STATE taskState; DRV_I2C_BUFFER_HANDLE drvI2CReadBufferHandle; uint8_t drvI2CReadFrameData[DRV_TOUCH_MTCH6301_I2C_READ_FRAME_SIZE]; } DRV_TOUCH_MTCH6301_TASK_QUEUE; Members Members Description bool inUse; Flag denoting the allocation of task DRV_TOUCH_MTCH6301_TASK_STATE taskState; Enum maintaining the task state DRV_I2C_BUFFER_HANDLE drvI2CReadBufferHandle; I2C Buffer handle uint8_t drvI2CReadFrameData[DRV_TOUCH_MTCH6301_I2C_READ_FRAME_SIZE]; Response to Read Touch Input Command • Response = { MTCH6301 Read Address, • Input Data Size, • Touch Id, Pen status, • Touch X coordinate (0 to 6), • Touch X coordinate (7 to 11), • Touch Y coordinate (0 to 6), • Touch Y coordinate (7 to 11) } Description MTCH6301 Touch Controller driver task data structure. This data type defines the data structure maintaing task context in the task queue. The inUse flag denotes the task context allocation for a task. The enum variable taskState maintains the current task state. The I2C buffer handle drvI2CReadBufferHandle maintains the I2C driver buffer handle returned by the I2C driver read request. The byte array variable drvI2CReadFrameData maintains the I2C frame data sent by MTCH6301 after a successful read request. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1074 DRV_TOUCH_MTCH6301_TASK_STATE Enumeration Enumeration defining MTCH6301 touch controller driver task state. File drv_mtch6301.h C typedef enum { DRV_TOUCH_MTCH6301_TASK_STATE_INIT = 0, DRV_TOUCH_MTCH6301_TASK_STATE_READ_INPUT, DRV_TOUCH_MTCH6301_TASK_STATE_DECODE_INPUT, DRV_TOUCH_MTCH6301_TASK_STATE_DONE } DRV_TOUCH_MTCH6301_TASK_STATE; Members Members Description DRV_TOUCH_MTCH6301_TASK_STATE_INIT = 0 Task initialize state DRV_TOUCH_MTCH6301_TASK_STATE_READ_INPUT Task read touch input request state DRV_TOUCH_MTCH6301_TASK_STATE_DECODE_INPUT Task touch input decode state DRV_TOUCH_MTCH6301_TASK_STATE_DONE Task complete state Description MTCH6301 Touch Controller Driver Task State This enumeration defines the MTCH6301 touch controller driver task state. The task state helps to synchronize the operations of initialization the the task, adding the read input task to the task queue once the touch controller notifies the available touch input and a decoding the touch input received. Remarks None. DRV_TOUCH_MTCH6301_I2C_MASTER_READ_ID Macro MTCH6301 input read, I2C address from where master reads touch input data. File drv_mtch6301.h C #define DRV_TOUCH_MTCH6301_I2C_MASTER_READ_ID 0x4B Description MTCH6301 Driver Module Master Input Read I2C address This constant defines the MTCH6301 touch input read I2C address. This address is used as I2C address to read Touch input from MTCH6301 Touch controller. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific data sheets. DRV_TOUCH_MTCH6301_I2C_MASTER_WRITE_ID Macro MTCH6301 command register write, I2C address where master sends the commands. File drv_mtch6301.h C #define DRV_TOUCH_MTCH6301_I2C_MASTER_WRITE_ID 0x4A Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1075 Description MTCH6301 Driver Module Master Command Write I2C Address This constant defines the MTCH6301 command register I2C write address. This address is used as I2C address to write commands into MTCH6301 Touch controller register. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific data sheets. Files Files Name Description drv_mtch6301.h Touch controller MTCH6301 Driver interface header file. drv_mtch6301_config_template.h MTCH6301 Touch Driver configuration template. Description This section lists the source and header files used by the MTCH6301 Touch Driver Library. drv_mtch6301.h Touch controller MTCH6301 Driver interface header file. Enumerations Name Description DRV_TOUCH_MTCH6301_MODULE_ID Number of valid MTCH6301 driver indices. DRV_TOUCH_MTCH6301_TASK_STATE Enumeration defining MTCH6301 touch controller driver task state. Functions Name Description DRV_TOUCH_MTCH6301_Close Closes an opened instance of the MTCH6301 driver. Implementation: Dynamic DRV_TOUCH_MTCH6301_Deinitialize Deinitializes the specified instance of the MTCH6301 driver module. Implementation: Dynamic DRV_TOUCH_MTCH6301_Initialize Initializes the MTCH6301 instance for the specified driver index. Implementation: Dynamic DRV_TOUCH_MTCH6301_Open Opens the specified MTCH6301 driver instance and returns a handle to it. Implementation: Dynamic DRV_TOUCH_MTCH6301_ReadRequest Sends a read request to I2C bus driver and adds the read task to queue. Implementation: Dynamic DRV_TOUCH_MTCH6301_Status Provides the current status of the MTCH6301 driver module. Implementation: Dynamic DRV_TOUCH_MTCH6301_Tasks Maintains the driver's state machine and implements its task queue processing. Implementation: Dynamic DRV_TOUCH_MTCH6301_TouchDataRead Notifies the driver that the current touch data has been read DRV_TOUCH_MTCH6301_TouchGetX Returns the x coordinate of touch input. Implementation: Dynamic DRV_TOUCH_MTCH6301_TouchGetY Returns the y coordinate of touch input. Implementation: Dynamic DRV_TOUCH_MTCH6301_TouchStatus Returns the status of the current touch input. Macros Name Description DRV_TOUCH_MTCH6301_HANDLE_INVALID Definition of an invalid handle. DRV_TOUCH_MTCH6301_I2C_MASTER_READ_ID MTCH6301 input read, I2C address from where master reads touch input data. DRV_TOUCH_MTCH6301_I2C_MASTER_WRITE_ID MTCH6301 command register write, I2C address where master sends the commands. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1076 DRV_TOUCH_MTCH6301_I2C_READ_FRAME_SIZE I2C Frame size for reading MTCH6301 touch input. DRV_TOUCH_MTCH6301_INDEX_0 MTCH6301 driver index definitions. DRV_TOUCH_MTCH6301_INDEX_1 This is macro DRV_TOUCH_MTCH6301_INDEX_1. DRV_TOUCH_MTCH6301_INDEX_COUNT Number of valid Touch controller MTCH6301 driver indices. Structures Name Description _DRV_MTCH6301_CLIENT_OBJECT MTCH6301 Driver client object maintaining client data. DRV_TOUCH_MTCH6301_CLIENT_OBJECT MTCH6301 Driver client object maintaining client data. DRV_TOUCH_MTCH6301_OBJECT Defines the data structure maintaining MTCH6301 driver instance object. DRV_TOUCH_MTCH6301_TASK_QUEUE Defines the MTCH6301 Touch Controller driver task data structure. Types Name Description DRV_TOUCH_MTCH6301_HANDLE Touch screen controller MTCH6301 driver handle. Description Touch Controller MTCH6301 Driver Interface File This header file describes the macros, data structure and prototypes of the touch controller MTCH6301 driver interface. File Name drv_mtch6301.c drv_mtch6301_config_template.h MTCH6301 Touch Driver configuration template. Macros Name Description DRV_MTCH6301_CALIBRATION_DELAY Defines the calibration delay. DRV_MTCH6301_CALIBRATION_INSET Defines the calibration inset. DRV_MTCH6301_CLIENTS_NUMBER Selects the maximum number of clients. DRV_MTCH6301_INDEX MTCH6301 static index selection. DRV_MTCH6301_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported. DRV_MTCH6301_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_MTCH6301_SAMPLE_POINTS Define the sample points. DRV_MTCH6301_TOUCH_DIAMETER Defines the touch diameter. Description MTCH6301 Touch Driver Configuration Template This header file contains the build-time configuration selections for the MTCH6301 Touch Driver. This is the template file which give all possible configurations that can be made. This file should not be included in any project. File Name drv_mtch6301_config_template.h Company Microchip Technology Inc. MTCH6303 Touch Driver Library This topic describes the MTCH6303 Touch Driver Library. Introduction This library provides an interface to manage the MTCH6303 Touch Driver module on the Microchip family of microcontrollers in different modes of operation. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1077 Description The MPLAB Harmony MTCH6303 Touch Driver provides a high-level interface to the MTCH6303 touch controller device. This driver provides application routines to read the touch input data from the touch screen. The MTCH6303 device can notify the availability of touch input data through external interrupt. The MTCH6303 driver allows the application to map a controller pin as an external interrupt pin. Currently, the MTCH6303 Touch Driver only supports non-gestural single-finger touch screen input. Using the Library This topic describes the basic architecture of the MTCH6303 Touch Driver Library and provides information and examples on its use. Description Interface Header File: drv_mtch6303_static.h The interface to the MTCH6303 Touch Driver Library is defined in the drv_mtch6303_static.h header file. This file is generated by the MPLAB Harmony Configurator (MHC) during application code generation. It is included in system_definitions.h by MHC during application code generation. Any configuration macros required for MTCH6303 Driver are included in system_config.h by MHC during code generation. Any C language source (.c) file that uses the MTCH6303 Touch Driver Library should include system_config.h and system_definitions.h, respectively. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the MTCH6303 Touch Driver Library 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 MTCH6303 Touch Driver has routines to perform the following operations: • MTCH6303 register read and write • MTCh6303 message read and write • MTCH6303 touch input read • Mapping of the touch input to screen resolution The driver Initialization routine allows the application to initialize the driver. The driver must be initialized before it can be used by the application. Once the driver is initialized, the driver Open function allows retrieval of the client handle. If the client handle is valid, an event handler routine needs to be registered by the application. The MTCH6303 Touch Driver triggers an interrupt once touch input is available to be read from the MTCH6303 registers. A touch input Read function is called from the interrupt handler to initiate the touch input read task. An Event Handler function is called once the touch input read task is completed. A valid touch input will be available only after the event handler routine is triggered. The touch input must be read inside of the event handler function. The touch input data is a raw value and needs to be mapped to the target screen resolution. At zero degree orientation, touch input is mapped on the x axis from zero at the left and the maximum value at the right. At zero degree orientation, touch input is mapped on the y axis from zero at the top and the maximum value at the bottom. MTCH6303 Driver Abstraction Model Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1078 Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the MTCH6303 Touch Driver. Library Interface Section Description System Functions Provides system module interfaces, device initialization, deinitialization, reinitialization, tasks, and status functions. Client Setup Functions Provides open, close, status, and other setup function. Read and Write Functions Provides functions to read and write to the MTCH6303 registers, messages, and touch data. Miscellaneous Functions Provides miscellaneous functions. How the Library Works The library provides interfaces to support: • System functions, which provide system module interfaces, device initialization, deinitialization, task, and status functions • Client setup functions, which provide client interfaces such as open, close and event handler registration • Read and write functions, initiate the touch input or register or message read and write tasks • Miscellaneous functions such as touch input map function are provided to process the raw touch input data Configuring the Library The configuration of the MTCH6303 Touch Driver is based on the file system_config.h. This header file contains the configuration selection for the MTCH6303 Touch Driver. Based on the selections made, the driver may support the selected features. These configuration settings will apply to all instances of the MTCH6303 Touch Driver. This header can be placed anywhere, 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 in the MTCH6303 Touch Driver Library. Description This section list the files that are available in the /src folder of the MTCH6303 Touch 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. 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 /framework/driver/touch/mtch6303. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_mtch6303_static.h Header file that exports the driver API. 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 /src/drv_mtch6303_static.c Basic MTCH6303 Touch Driver implementation file. /src/drv_mtch6303_buffer_queue_i2c_static.c MTCH6303 I2C buffer queue implementation file. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1079 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 /drv_mtch6303_buffer_queue_touch_static.c MTCH6303 message buffer queue implementation file. Module Dependencies The MTCH6303 Touch Driver Library depends on the following modules: • Interrupt System Service Library • Ports System Service Library • I2C Driver Library Library Interface a) System Functions Name Description DRV_MTCH6303_Deinitialize Deinitializes the instance of the MTCH6303 driver module. DRV_MTCH6303_Initialize Initializes the MTCH6303 static single instance. DRV_MTCH6303_Status Gets the current status of the MTCH6303 driver module. DRV_MTCH6303_Tasks Maintains the driver's register read/write state machine and implements its ISR. b) Client Setup Functions Name Description DRV_MTCH6303_Close Closes an opened-instance of the MTCH6303 driver. DRV_MTCH6303_ErrorGet This function returns the error associated with the last client request. DRV_MTCH6303_Open Opens the MTCH6303 driver instance and returns a handle to it. c) Read and Write Functions Name Description DRV_MTCH6303_AddRegisterRead Schedules a non-blocking register read request to read I2C accessible MTCH6303 registers. DRV_MTCH6303_AddRegisterWrite Schedule a non-blocking driver register write operation to write I2C accessible MTCH6303 registers. DRV_MTCH6303_TOUCH_AddMessageCommandWrite Schedule a non-blocking driver command message write operation to write command message to MTCH6303 registers. DRV_MTCH6303_TOUCH_AddMessageReportRead Schedules a non-blocking report message read request to read the report message from MTCH6303 device. DRV_MTCH6303_TOUCH_AddTouchInputRead Schedules a non-blocking read buffer request to read touch input from MTCH6303. DRV_MTCH6303_TOUCH_BufferEventHandlerSet Allows a client to identify a buffer event handling function for the driver to call back when queued message transfers have finished. DRV_MTCH6303_TOUCH_Tasks Maintains the driver's message state machine and implements its ISR. DRV_MTCH6303_TouchInputMap Maps the raw touch input to display resolution. DRV_MTCH6303_TouchInputRead Schedules a non-blocking read buffer request to read touch input from MTCH6303. DRV_MTCH6303_BufferEventHandlerSet Allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. d) Data Types and Constants Name Description DRV_MTCH6303_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_MTCH6303_TOUCH_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_MTCH6303_TOUCH_NUM_INPUTS Definition of number of touch input packets can be identified by MTCH6303. DRV_MTCH6303_BUFFER_EVENT Lists the different conditions that happens during a buffer transfer. DRV_MTCH6303_BUFFER_EVENT_HANDLER Points to a callback after completion of an register read -write or message stream read - write. DRV_MTCH6303_BUFFER_HANDLE Handle identifying a read or write buffer passed to the driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1080 DRV_MTCH6303_CLIENT_STATUS Defines the client-specific status of the MTCH6303 driver. DRV_MTCH6303_ERROR Defines the possible errors that can occur during driver operation. DRV_MTCH6303_TOUCH_BUFFER_EVENT Lists the different conditions that happens during a touch message buffer transfer. DRV_MTCH6303_TOUCH_BUFFER_EVENT_HANDLER Points to a callback after completion of an message report read or message command write. DRV_MTCH6303_TOUCH_BUFFER_HANDLE Handle identifying a read or write touch message buffer passed to the driver. DRV_MTCH6303_TOUCH_DATA Defines MTCH6303 I2C Touch Data DRV_MTCH6303_TOUCH_INPUT Defines MTCH6303 Touch Input Packet DRV_MTCH6303_TOUCH_MESSAGE Defines MTCH6303 Touch Message. DRV_MTCH6303_TOUCH_MESSAGE_HEADER Defines Touch Message Header. DRV_MTCH6303_TOUCH_NIBBLE_0 Defines the I2C Nibble 0 of MTCH6303 Touch input packet. DRV_MTCH6303_TOUCH_STATUS Defines the I2C touch status register bits DRV_TOUCH_MTCH6303_MSG_ID List of report or command message identification. DRV_TOUCH_MTCH6303_I2C_REGISTER_MAP List of MTCH6303 I2C Accessible Register Identification. Description This section describes the API functions of the MTCH6303 Touch Driver library. Refer to each section for a detailed description. a) System Functions DRV_MTCH6303_Deinitialize Function Deinitializes the instance of the MTCH6303 driver module. File drv_mtch6303.h C void DRV_MTCH6303_Deinitialize(); Returns None. Description Deinitializes the instance of the MTCH6303 driver module, disabling its operation. Invalidates all the internal data. Remarks once the initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. this routine will NEVER block waiting for hardware. Preconditions Function DRV_MTCH6303_Initialize should have been called before calling this function. Example SYS_STATUS status; DRV_MTCH6303_Deinitialize(); status = DRV_MTCH6303_Status(); if(SYS_MODULE_DEINITIALIZED != status) { //check again later if you need to know //when the driver is deinitialized } Function void DRV_MTCH6303_Deinitialize( void ) Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1081 DRV_MTCH6303_Initialize Function Initializes the MTCH6303 static single instance. File drv_mtch6303.h C SYS_MODULE_OBJ DRV_MTCH6303_Initialize(); Returns If successful, returns a valid handle to a driver instance object. Otherwise, returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the MTCH6303 static driver instance. It makes the instance ready for a client to open and use it. The instance parameters are initialized by values set by MPLAB Harmony Configurator. Preconditions None. Example // The following code snippet shows an example MTCH6303 driver initialization. SYS_MODULE_OBJ objectHandle; objectHandle = DRV_MTCH6303_Initialize(); if( SYS_MODULE_OBJ_INVALID == objectHandle ) { // Handle error } Remarks: This routine must be called before any other MTCH6303 routine is called. This routine should only be called once during system initialization unless DRV_MTCH6303_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. Function SYS_MODULE_OBJ DRV_MTCH6303_Initialize ( void ) DRV_MTCH6303_Status Function Gets the current status of the MTCH6303 driver module. File drv_mtch6303.h C SYS_STATUS DRV_MTCH6303_Status(); Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system level operation and cannot start another. SYS_STATUS_DEINITIALIZED - Indicates that the driver has been deinitialized. Description This routine provides the current status of the MTCH6303 driver module. Remarks A driver can opened only when its status is SYS_STATUS_READY. Preconditions Function DRV_MTCH6303_Initialize should have been called before calling this function. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1082 Example SYS_STATUS mtch6303Status; mtch6303Status = DRV_MTCH6303_Status(); if(SYS_STATUS_READY == mtch6303Status) { // This means the driver can be opened using the // DRV_MTCH6303_Open() function. } Function SYS_STATUS DRV_MTCH6303_Status( void ) DRV_MTCH6303_Tasks Function Maintains the driver's register read/write state machine and implements its ISR. File drv_mtch6303.h C void DRV_MTCH6303_Tasks(); Returns None. Description This routine is used to maintain the driver's register read/write state machine and implement its ISR for interrupt-driven implementations. In interrupt mode, this function is called in I2C Driver event Handler routine. The I2C Driver event Handler routine is registered by MTCH6303 event Handler register routine. Remarks This routine may execute in an ISR context and will never block or access any resources that may cause it to block. Preconditions Function DRV_MTCH6303_Initialize should have been called before calling this function. It also needs registration of the MTCH6303 Driver event handler routine. Function void DRV_MTCH6303_Tasks( void ) b) Client Setup Functions DRV_MTCH6303_Close Function Closes an opened-instance of the MTCH6303 driver. File drv_mtch6303.h C DRV_MTCH6303_CLIENT_STATUS DRV_MTCH6303_Close(); Returns DRV_MTCH6303_CLIENT_STATUS_ERROR - if driver fails to remove buffer objects from queue. DRV_MTCHC6303_CLIENT_STATUS_CLOSED - client is successfully closed Description This routine closes an opened-instance of the MTCH6303 driver. Any buffers in the driver queue that were submitted by this client will be removed. DRV_MTCH6303_Open must be called to before using the driver again. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1083 Remarks The driver will abort any ongoing operations when this routine is called. Preconditions The DRV_MTCH6303_Initialize routine must have been called. DRV_MTCH6303_Open must have been called. Example DRV_MTH6303_CLIENT_STATUS mtch6303Status; mtch6303Status = DRV_MTCH6303_Close() if( DRV_MTCH6303_CLIENT_STATUS_ERROR == mtch6303Status ) { //retry closing the driver client } Function DRV_MTCH6303_CLIENT_STATUS DRV_MTCH6303_Close ( void ) DRV_MTCH6303_ErrorGet Function This function returns the error associated with the last client request. File drv_mtch6303.h C DRV_MTCH6303_ERROR DRV_MTCH6303_ErrorGet(); Returns DRV_MTCH6303_ERROR_NONE - no error Description This function returns the error associated with the last client request. Remarks This routine always return DRV_MTCH6303_ERROR_NONE the client error is currently not updated by any of the MTCH6303 operations API's. Preconditions The DRV_MTCH6303_Initialize routine must have been called. DRV_MTCH6303_Open must have been called to open a device client. Function DRV_MTCH6303_ERROR DRV_MTCH6303_ErrorGet ( void ) DRV_MTCH6303_Open Function Opens the MTCH6303 driver instance and returns a handle to it. File drv_mtch6303.h C DRV_HANDLE DRV_MTCH6303_Open(); Returns If successful, the routine returns a valid open-instance handle. If an error occurs, the return value is DRV_HANDLE_INVALID. Error can occur • if the driver is not ready to be opened, typically when the initialize routine has not completed execution. • if the bus driver fails to open • if the client is trying to open the driver but driver has been opened exclusively by another client. Description This routine opens the specified MTCH6303 driver instance and provides a handle. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1084 Remarks The handle returned is valid until the DRV_MTCH6303_Close routine is called. This routine will NEVER block waiting for hardware.If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. Preconditions Function DRV_MTCH6303_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_MTCH6303_Open( ); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver // May be the driver is not initialized or the initialization // is not complete. } Function DRV_HANDLE DRV_MTCH6303_Open { void } c) Read and Write Functions DRV_MTCH6303_AddRegisterRead Function Schedules a non-blocking register read request to read I2C accessible MTCH6303 registers. File drv_mtch6303.h C void DRV_MTCH6303_AddRegisterRead(DRV_MTCH6303_BUFFER_HANDLE * bufferHandle, uint8_t source, size_t nBytes, uint8_t * destination); Returns None. Description This function schedules a non-blocking register read request to read I2C accessible MTCH6303 registers. The function returns with a valid buffer handle in the bufferHandle argument if the register read request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. The function returns DRV_MTCH6303_BUFFER_HANDLE_INVALID in the bufferHandle argument: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0 • if the read queue size is full or queue depth is insufficient. • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_MTCH6303_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully or DRV_MTCH6303_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. The register data is collected into destination and can be read once a buffer event complete is reported. A event handler is called on buffer event complete where the register data must be read from destination. Preconditions The DRV_MTCH6303_Initialize routine must have been called and the DRV_MTCH6303_Status must have returned SYS_STATUS_READY. DRV_MTCH6303_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; uint8_t registerData[NUM_REGISTERS]; DRV_MTCH6303_BUFFER_HANDLE bufferHandle; // Client registers an event handler with driver Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1085 DRV_MTCH6303_BufferEventHandlerSet( APP_MTCH6303BufferEventHandler, (uintptr_t)&myAppObj); DRV_MTCH6303_AddRegisterRead( &bufferHandle, DRV_MTCH6303_REG_TOUCH_STATUS, NUM_REGISTERS, ®isterData ); if(DRV_MTCH6303_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_MTCH6303BufferEventHandler( DRV_MTCH6303_BUFFER_EVENT event, DRV_MTCH6303_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle ) { // contextHandle points to myAppObj. switch(event) { case DRV_MTCH6303_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_MTCH6303_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Remarks: None. Parameters Parameters Description bufferHandle Handle to the buffer scheduled. source Register index. nBytes Number of registers to be read, starting from source. destination buffer collecting register data. Function void DRV_MTCH6303_AddRegisterRead( DRV_MTCH6303_BUFFER_HANDLE * bufferHandle, uint8_t source, size_t nBytes, uint8_t * destination ) DRV_MTCH6303_AddRegisterWrite Function Schedule a non-blocking driver register write operation to write I2C accessible MTCH6303 registers. File drv_mtch6303.h C void DRV_MTCH6303_AddRegisterWrite(DRV_MTCH6303_BUFFER_HANDLE * bufferHandle, uint8_t destination, size_t nBytes, uint8_t * source); Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1086 Returns None. Description This function schedules a non-blocking register write request to write I2C accessible MTCH6303 registers. The function returns with a valid buffer handle in the bufferHandle argument if the register write request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_MTCH6303_BUFFER_HANDLE_INVALID in the bufferHandle argument: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0 • if the write queue size is full or queue depth is insufficient. • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_MTCH6303_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully or DRV_MTCH6303_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. A event handler is called on buffer event complete where the application data is written to the I2C accessible MTCH6303 Register. Remarks None. Preconditions The DRV_MTCH6303_Initialize routine must have been called and the DRV_MTCH6303_Status must have returned SYS_STATUS_READY. DRV_MTCH6303_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; uint8_t registerData[NUM_REGISTERS]; DRV_MTCH6303_BUFFER_HANDLE bufferHandle; // Client registers an event handler with driver DRV_MTCH6303_BufferEventHandlerSet( APP_MTCH6303BufferEventHandler, (uintptr_t)&myAppObj); DRV_MTCH6303_AddRegisterWrite( &bufferHandle, DRV_MTCH6303_REG_TOUCH_STATUS, NUM_REGISTERS, ®isterData ); if(DRV_MTCH6303_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_MTCH6303BufferEventHandler( DRV_MTCH6303_BUFFER_EVENT event, DRV_MTCH6303_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle ) { // contextHandle points to myAppObj. switch(event) { case DRV_MTCH6303_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_MTCH6303_BUFFER_EVENT_ERROR: // Error handling here. break; Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1087 default: break; } } Parameters Parameters Description bufferHandle Pointer to an argument that will contain the return buffer handle. destination Index to the start of destination register list. nBytes number of registers. source pointer to the data to be written to the register. Function void DRV_MTCH6303_AddRegisterWrite( DRV_MTCH6303_BUFFER_HANDLE * bufferHandle, uint8_t destination, size_t nBytes, uint8_t * source ) DRV_MTCH6303_TOUCH_AddMessageCommandWrite Function Schedule a non-blocking driver command message write operation to write command message to MTCH6303 registers. File drv_mtch6303.h C void DRV_MTCH6303_TOUCH_AddMessageCommandWrite(DRV_MTCH6303_TOUCH_BUFFER_HANDLE * bufferHandle, DRV_MTCH6303_TOUCH_MESSAGE * messageCmd, size_t messageSize); Returns None. Description This function schedules a non-blocking command message write request to write command message to MTCH6303. The function returns with a valid buffer handle in the bufferHandle argument if the register command message write request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. While the request is in the queue, the application message buffer is owned by the driver and should not be modified. The function returns DRV_MTCH6303_TOUCH_BUFFER_HANDLE_INVALID in the bufferHandle argument: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0 • if the message write queue size is full or queue depth is insufficient. • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_MTCH6303_TOUCH_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully or DRV_MTCH6303_TOUCH_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. A event handler is called on buffer event complete where the application command message is written to MTCH6303. Remarks None. Preconditions The DRV_MTCH6303_Initialize routine must have been called and the DRV_MTCH6303_Status must have returned SYS_STATUS_READY. DRV_MTCH6303_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; DRV_MTCH6303_TOUCH_MESSAGE messageCommand; DRV_MTCH6303_TOUCH_BUFFER_HANDLE bufferHandle; // Client registers an event handler with driver Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1088 DRV_MTCH6303_TOUCH_BufferEventHandlerSet( APP_MTCH6303BufferEventHandler, (uintptr_t)&myAppObj); DRV_MTCH6303_TOUCH_AddMessageCommandWrite( &bufferHandle, &messageCommand, MY_MESSAGE_SIZE ); if(DRV_MTCH6303_TOUCH_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_MTCH6303BufferEventHandler( DRV_MTCH6303_TOUCH_BUFFER_EVENT event, DRV_MTCH6303_TOUCH_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle ) { // contextHandle points to myAppObj. switch(event) { case DRV_MTCH6303_TOUCH_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_MTCH6303_TOUCH_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description bufferHandle Pointer to an argument that will contain the return buffer handle. messageCmd command message to write to MTCH6303. messageSize command message size. It includes message header and payload size. Function void DRV_MTCH6303_TOUCH_AddMessageCommandWrite ( DRV_MTCH6303_TOUCH_BUFFER_HANDLE * bufferHandle, DRV_MTCH6303_TOUCH_MESSAGE * messageCmd, size_t messageSize ) DRV_MTCH6303_TOUCH_AddMessageReportRead Function Schedules a non-blocking report message read request to read the report message from MTCH6303 device. File drv_mtch6303.h C void DRV_MTCH6303_TOUCH_AddMessageReportRead(DRV_MTCH6303_TOUCH_BUFFER_HANDLE * bufferHandle, DRV_MTCH6303_TOUCH_MESSAGE * messageRep, size_t messageSize); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1089 Description This function schedules a non-blocking report message read request to read the report message from MTCH6303 device. The function returns with a valid buffer handle in the bufferHandle argument if the register read request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. The function returns DRV_MTCH6303_TOUCH_BUFFER_HANDLE_INVALID in the bufferHandle argument: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0 • if the read queue size is full or queue depth is insufficient. • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_MTCH6303_TOUCH_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully or DRV_MTCH6303_TOUCH_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. The register data is collected into destination and can be read once a buffer event complete is reported. A event handler is called on buffer event complete where the register data must be read from destination. Remarks None. Preconditions The DRV_MTCH6303_Initialize routine must have been called and the DRV_MTCH6303_Status must have returned SYS_STATUS_READY. DRV_MTCH6303_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; DRV_MTCH6303_TOUCH_MESSAGE messageReport; DRV_MTCH6303_TOUCH_BUFFER_HANDLE bufferHandle; // Client registers an event handler with driver DRV_MTCH6303_TOUCH_BufferEventHandlerSet( APP_MTCH6303BufferEventHandler, (uintptr_t)&myAppObj); DRV_MTCH6303_TOUCH_AddMessageReportRead( &bufferHandle, &messageReport, MY_MESSAGE_SIZE ); if(DRV_MTCH6303_TOUCH_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_MTCH6303BufferEventHandler( DRV_MTCH6303_TOUCH_BUFFER_EVENT event, DRV_MTCH6303_TOUCH_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle ) { // contextHandle points to myAppObj. switch(event) { case DRV_MTCH6303_TOUCH_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_MTCH6303_TOUCH_BUFFER_EVENT_ERROR: // Error handling here. break; default: Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1090 break; } } Parameters Parameters Description bufferHandle Handle to the buffer scheduled. messageRep report message buffer. messageSize report message size. It includes message header and payload size. Function void DRV_MTCH6303_TOUCH_AddMessageReportRead ( DRV_MTCH6303_TOUCH_BUFFER_HANDLE * bufferHandle, DRV_MTCH6303_TOUCH_MESSAGE * messageRep, size_t messageSize ) DRV_MTCH6303_TOUCH_AddTouchInputRead Function Schedules a non-blocking read buffer request to read touch input from MTCH6303. File drv_mtch6303.h C void DRV_MTCH6303_TOUCH_AddTouchInputRead(DRV_MTCH6303_TOUCH_BUFFER_HANDLE * bufferHandle, DRV_MTCH6303_TOUCH_DATA * touchData); Returns None. Description This function schedules a non-blocking read buffer request to read touch input from MTCH6303. The function returns with a valid buffer handle in the bufferHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. The function returns DRV_MTCH6303_TOUCH_BUFFER_HANDLE_INVALID in the bufferHandle argument: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0 • if the read queue size is full or queue depth is insufficient. • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_MTCH6303_TOUCH_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully or DRV_MTCH6303_TOUCH_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. The touch data is collected into touchData and can be read once a buffer event complete is reported. A event handler is called on buffer event complete where the touch data must be read from touchData. Remarks None. Preconditions The DRV_MTCH6303_Initialize routine must have been called and the DRV_MTCH6303_Status must have returned SYS_STATUS_READY. DRV_MTCH6303_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; DRV_MTCH6303_TOUCH_DATA touchData; DRV_MTCH6303_BUFFER_HANDLE bufferHandle; // Client registers an event handler with driver DRV_MTCH6303_TOUCH_BufferEventHandlerSet( APP_MTCH6303BufferEventHandler, (uintptr_t)&myAppObj); Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1091 DRV_MTCH6303_TOUCH_AddTouchInputRead( &bufferHandle, &touchData ); if(DRV_MTCH6303_TOUCH_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_MTCH6303BufferEventHandler( DRV_MTCH6303_TOUCH_BUFFER_EVENT event, DRV_MTCH6303_TOUCH_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle ) { // contextHandle points to myAppObj. switch(event) { case DRV_MTCH6303_TOUCH_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_MTCH6303_TOUCH_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description bufferHandle Handle to the buffer scheduled. touchData Buffer collecting touch data. Function void DRV_MTCH6303_TOUCH_AddTouchInputRead ( DRV_MTCH6303_TOUCH_BUFFER_HANDLE * bufferHandle, DRV_MTCH6303_TOUCH_DATA * touchData ) DRV_MTCH6303_TOUCH_BufferEventHandlerSet Function Allows a client to identify a buffer event handling function for the driver to call back when queued message transfers have finished. File drv_mtch6303.h C void DRV_MTCH6303_TOUCH_BufferEventHandlerSet(const DRV_MTCH6303_TOUCH_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t context); Returns None. Description This function allows a client to identify a message event handling function for the driver to call back when queued message transfers have finished. When a client calls either the DRV_MTCH6303_TOUCH_AddTouchInputRead, DRV_MTCH6303_TOUCH_AddMessageReportRead or DRV_MTCH6303_TOUCH_AddMessageCommandWrite function, it is provided with a handle identifying the message that was added to the driver's message queue. The driver will pass this handle back to the client by calling "eventHandler" function when the message transfer has completed. The event handler should be set before the client performs any "message add" operations that could generate events. The event handler once set, Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1092 persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks None. Preconditions The DRV_MTCH6303_Initialize routine must have been called and the DRV_MTCH6303_Status must have returned SYS_STATUS_READY. Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; DRV_MTCH6303_TOUCH_MESSAGE messageReport; DRV_MTCH6303_TOUCH_BUFFER_HANDLE bufferHandle; // myMTCH6303Handle is the handle returned // by the DRV_MTCH6303_Open function. // Client registers an event handler with driver. This is done once DRV_MTCH6303_TOUCH_BufferEventHandlerSet( APP_MTCH6303BufferEventHandler, (uintptr_t)&myAppObj ); DRV_MTCH6303_TOUCH_AddMessageReportRead( &bufferHandle, &messageReport ); if(DRV_MTCH6303_TOUCH_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_MTCH6303BufferEventHandler( DRV_MTCH6303_TOUCH_BUFFER_EVENT event, DRV_MTCH6303_TOUCH_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle ) { // contextHandle points to myAppObj. switch(event) { case DRV_MTCH6303_TOUCH_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_MTCH6303_TOUCH_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description eventHandler Pointer to the event handler function. context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_MTCH6303_TOUCH_BufferEventHandlerSet ( Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1093 const DRV_MTCH6303_TOUCH_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t context ) DRV_MTCH6303_TOUCH_Tasks Function Maintains the driver's message state machine and implements its ISR. File drv_mtch6303.h C void DRV_MTCH6303_TOUCH_Tasks(); Returns None. Description This routine is used to maintain the driver's message state machine and implement its ISR for interrupt-driven implementations. In interrupt mode, this function is called in I2C Driver event Handler routine. The I2C Driver event Handler routine is registered by MTCH6303 Touch event Handler register routine. Remarks This routine may execute in an ISR context and will never block or access any resources that may cause it to block. Preconditions Function DRV_MTCH6303_Initialize should have been called before calling this function. It also needs registration of the MTCH6303 Driver Touch event handler routine. Function void DRV_MTCH6303_TOUCH_Tasks( void ) DRV_MTCH6303_TouchInputMap Function Maps the raw touch input to display resolution. File drv_mtch6303.h C inline uint16_t DRV_MTCH6303_TouchInputMap(uint16_t touchValue, uint16_t dispResolution); Returns This function returns the raw touch input mapped to display resolution in form of number of pixels. Description This function maps the raw touch input to display resolution. Raw touch input touchValue is obtained from the individual x or y value of DRV_MTCH6303_TOUCH_DATA. Raw touch value varies from 0 to 0x7FFF. The displayResolution is either horizontal or vertical resolution of the display in pixels. The function returns the raw touch input mapped to display resolution in form of number of pixels. Remarks None. Preconditions None. Example // Display with resolution 800 x 480 #define DISP_HOR_RESOUTION 800 #define DISP_VER_RESOLUTION 480 DRV_MTCH6303_TOUCH_DATA touchData; uint16_t rawTouchX; Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1094 uint16_t rawTouchY; uint16_t touchX; uint16_t touchY; // map 0th touch packet to display resolution rawTouchX = touchData.touch[0].x; rawTouchY = touchData.touch[0].y; // map raw touch input in x direction to display horizontal resolution touchX = DRV_MTCH6303_TouchInputMap( rawTouchX, DISP_HOR_RESOLUTION ); // map raw touch input in y direction to display vertical resolution touchY = DRV_MTCH6303_TouchInputMap( rawTouchY, DISP_VER_RESOLUTION ); // use touchX and touchY as input to graphics objects. Parameters Parameters Description touchValue raw touch input either in x or y direction (0 - 0x7FFF). dispResolution display resolution specifying either width or height of the display in pixels. Function uint16_t DRV_MTCH6303_TouchInputMap( uint16_t touchValue, uint16_t dispResolution ) DRV_MTCH6303_TouchInputRead Function Schedules a non-blocking read buffer request to read touch input from MTCH6303. File drv_mtch6303.h C void DRV_MTCH6303_TouchInputRead(DRV_MTCH6303_BUFFER_HANDLE * bufferHandle, DRV_MTCH6303_TOUCH_DATA * touchData); Returns None. Description This function schedules a non-blocking read buffer request to read touch input from MTCH6303. The function returns with a valid buffer handle in the bufferHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance queue and returns immediately. The function returns DRV_MTCH6303_BUFFER_HANDLE_INVALID in the bufferHandle argument: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0 • if the read queue size is full or queue depth is insufficient. • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_MTCH6303_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully or DRV_MTCH6303_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. The touch data is collected into touchData and can be read once a buffer event complete is reported. A event handler is called on buffer event complete where the touch data must be read from touchData. Remarks None. Preconditions The DRV_MTCH6303_Initialize routine must have been called and the DRV_MTCH6303_Status must have returned SYS_STATUS_READY. DRV_MTCH6303_Open must have been called to obtain a valid opened device handle. Example MY_APP_OBJ myAppObj; DRV_MTCH6303_TOUCH_DATA touchData; DRV_MTCH6303_BUFFER_HANDLE bufferHandle; Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1095 // Client registers an event handler with driver DRV_MTCH6303_BufferEventHandlerSet( APP_MTCH6303BufferEventHandler, (uintptr_t)&myAppObj); DRV_MTCH6303_TouchInputRead( &bufferHandle, &touchData ); if(DRV_MTCH6303_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_MTCH6303BufferEventHandler( DRV_MTCH6303_BUFFER_EVENT event, DRV_MTCH6303_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle ) { // contextHandle points to myAppObj. switch(event) { case DRV_MTCH6303_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_MTCH6303_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description bufferHandle Handle to the buffer scheduled. touchData Buffer collecting touch data. Function void DRV_MTCH6303_TouchInputRead( DRV_MTCH6303_BUFFER_HANDLE * bufferHandle, DRV_MTCH6303_TOUCH_DATA * touchData ) DRV_MTCH6303_BufferEventHandlerSet Function Allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. File drv_mtch6303.h C void DRV_MTCH6303_BufferEventHandlerSet(const DRV_MTCH6303_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t context); Returns None. Description This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. When a client calls either the DRV_MTCH6303_TouchInputRead, DRV_MTCH6303_AddRegisterRead or DRV_MTCH6303_AddRegisterWrite function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1096 calling "eventHandler" function when the buffer transfer has completed. The event handler should be set before the client performs any "buffer add" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks None. Preconditions The DRV_MTCH6303_Initialize routine must have been called and the DRV_MTCH6303_Status must have returned SYS_STATUS_READY. Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; // myMTCH6303Handle is the handle returned // by the DRV_MTCH6303_Open function. // Client registers an event handler with driver. This is done once DRV_MTCH6303_BufferEventHandlerSet( APP_MTCH6303BufferEventHandle, (uintptr_t)&myAppObj ); DRV_MTCH6303_AddRegisterRead( &bufferHandle DRV_MTCH6303_REG_TOUCH_STATUS, MY_BUFFER_SIZE, &mybuffer); if(DRV_MTCH6303_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event Processing Technique. Event is received when // the buffer is processed. void APP_MTCH6303BufferEventHandle( DRV_MTCH6303_BUFFER_EVENT event, DRV_MTCH6303_BUFFER_HANDLE handle, uintptr_t context) { // contextHandle points to myAppObj. switch(event) { case DRV_MTCH6303_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_MTCH6303_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description eventHandler Pointer to the event handler function. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1097 context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_MTCH6303_BufferEventHandlerSet ( const DRV_MTCH6303_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t context ) d) Data Types and Constants DRV_MTCH6303_BUFFER_HANDLE_INVALID Macro Definition of an invalid buffer handle. File drv_mtch6303.h C #define DRV_MTCH6303_BUFFER_HANDLE_INVALID Description MTCH6303 Driver Invalid Buffer Handle This is the definition of an invalid buffer handle. An invalid buffer handle is returned by DRV_MTCH6303_AddRegisterRead, DRV_MTCH6303_AddRegisterWrite or DRV_MTCH6303_TouchInputRead functions if the request was not successful. Remarks None DRV_MTCH6303_TOUCH_BUFFER_HANDLE_INVALID Macro Definition of an invalid buffer handle. File drv_mtch6303.h C #define DRV_MTCH6303_TOUCH_BUFFER_HANDLE_INVALID Description MTCH6303 Driver Invalid Buffer Handle This is the definition of an invalid buffer handle. An invalid buffer handle is returned by DRV_MTCH6303_TOUCH_AddMessageReportRead, DRV_MTCH6303_TOUCH_AddMessageCommandWrite or DRV_MTCH6303_TOUCH_AddTouchInputRead functions if the request was not successful. Remarks None DRV_MTCH6303_TOUCH_NUM_INPUTS Macro Definition of number of touch input packets can be identified by MTCH6303. File drv_mtch6303.h C #define DRV_MTCH6303_TOUCH_NUM_INPUTS 0xA Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1098 Description MTCH6303 Number of touch input packets MTCH6303 supports multi-touch and can identify upto 10 different touch input packets. Remarks None. DRV_MTCH6303_BUFFER_EVENT Enumeration Lists the different conditions that happens during a buffer transfer. File drv_mtch6303.h C typedef enum { DRV_MTCH6303_BUFFER_EVENT_COMPLETE, DRV_MTCH6303_BUFFER_EVENT_ERROR, DRV_MTCH6303_BUFFER_EVENT_ABORT } DRV_MTCH6303_BUFFER_EVENT; Members Members Description DRV_MTCH6303_BUFFER_EVENT_COMPLETE Event buffer transfer complete DRV_MTCH6303_BUFFER_EVENT_ERROR Event buffer transfer error DRV_MTCH6303_BUFFER_EVENT_ABORT Event buffer transfer abort Description MTCH6303 Buffer Events This enumeration identifies the different conditions that can happen during a buffer transaction. Callbacks can be made with the appropriate buffer condition passed as a parameter to execute the desired action. The values act like flags and multiple flags can be set. Remarks None. DRV_MTCH6303_BUFFER_EVENT_HANDLER Type Points to a callback after completion of an register read -write or message stream read - write. File drv_mtch6303.h C typedef void (* DRV_MTCH6303_BUFFER_EVENT_HANDLER)(DRV_MTCH6303_BUFFER_EVENT event, DRV_MTCH6303_BUFFER_HANDLE bufferHandle, uintptr_t context); Description MTCH6303 Buffer Event Callback This type identifies the MTCH6303 Buffer Event. It allows the client driver to register a callback using DRV_MTCH6303_BUFFER_EVENT_HANDLER. By using this mechanism, the driver client will be notified at the completion of the corresponding transfer. Remarks A transfer can be composed of various transfer segments. Once a transfer is completed the driver will call the client registered transfer callback. The callback could be called from ISR context and should be kept as short as possible. It is meant for signaling and it should not be blocking. Parameters Parameters Description DRV_MTCH6303_BUFFER_EVENT Status of MTCH6303 transfer Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1099 bufferHandle Handle that identifies the particular Buffer Object context pointer to the object to be processed. Function void ( *DRV_MTCH6303_BUFFER_EVENT_HANDLER ) ( DRV_MTCH6303_BUFFER_EVENT event, DRV_MTCH6303_BUFFER_HANDLE bufferHandle, uintptr_t context ) DRV_MTCH6303_BUFFER_HANDLE Type Handle identifying a read or write buffer passed to the driver. File drv_mtch6303.h C typedef uintptr_t DRV_MTCH6303_BUFFER_HANDLE; Description MTCH6303 Driver Buffer Handle A buffer handle value is returned by a call to the DRV_MTCH6303_AddRegisterRead, DRV_MTCH6303_AddRegisterWrite or DRV_MTCH6303_TouchInputRead functions. This handle is associated with the buffer passed into the function and it allows the application to track the completion of the data from (or into) that buffer. The buffer handle value returned from these functions is returned back to the client by the "event handler callback" function registered with the driver. The buffer handle assigned to a client request expires when the client has been notified of the completion of the buffer transfer (after event handler function that notifies the client returns) or after the buffer has been retired by the driver if no event handler callback was set. Remarks None DRV_MTCH6303_CLIENT_STATUS Enumeration Defines the client-specific status of the MTCH6303 driver. File drv_mtch6303.h C typedef enum { DRV_MTCH6303_CLIENT_STATUS_ERROR = DRV_CLIENT_STATUS_ERROR, DRV_MTCH6303_CLIENT_STATUS_CLOSED = DRV_CLIENT_STATUS_CLOSED, DRV_MTCH6303_CLIENT_STATUS_BUSY = DRV_CLIENT_STATUS_BUSY, DRV_MTCH6303_CLIENT_STATUS_READY = DRV_CLIENT_STATUS_READY } DRV_MTCH6303_CLIENT_STATUS; Members Members Description DRV_MTCH6303_CLIENT_STATUS_ERROR = DRV_CLIENT_STATUS_ERROR An error has occurred. DRV_MTCH6303_CLIENT_STATUS_CLOSED = DRV_CLIENT_STATUS_CLOSED The driver is closed, no operations for this client are ongoing, and/or the given handle is invalid. DRV_MTCH6303_CLIENT_STATUS_BUSY = DRV_CLIENT_STATUS_BUSY The driver is currently busy and cannot start additional operations. DRV_MTCH6303_CLIENT_STATUS_READY = DRV_CLIENT_STATUS_READY The module is running and ready for additional operations Description MTCH6303 Client-Specific Driver Status This enumeration defines the client-specific status codes of the MTCH6303 driver. Remarks Returned by the DRV_MTCH6303_ClientStatus function. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1100 DRV_MTCH6303_ERROR Enumeration Defines the possible errors that can occur during driver operation. File drv_mtch6303.h C typedef enum { } DRV_MTCH6303_ERROR; Description MTCH6303 Driver Errors. This data type defines the possible errors that can occur when occur during MTCH6303 driver operation. These values are returned by DRV_MTCH6303_ErrorGet function. Remarks None DRV_MTCH6303_TOUCH_BUFFER_EVENT Enumeration Lists the different conditions that happens during a touch message buffer transfer. File drv_mtch6303.h C typedef enum { DRV_MTCH6303_TOUCH_BUFFER_EVENT_COMPLETE, DRV_MTCH6303_TOUCH_BUFFER_EVENT_ERROR, DRV_MTCH6303_TOUCH_BUFFER_EVENT_ABORT } DRV_MTCH6303_TOUCH_BUFFER_EVENT; Members Members Description DRV_MTCH6303_TOUCH_BUFFER_EVENT_COMPLETE Event touch message buffer transfer complete DRV_MTCH6303_TOUCH_BUFFER_EVENT_ERROR Event touch message buffer transfer error DRV_MTCH6303_TOUCH_BUFFER_EVENT_ABORT Event touch message buffer transfer abort Description MTCH6303 Touch Message Buffer Events This enumeration identifies the different conditions that can happen during a touch message buffer transaction. Callbacks can be made with the appropriate touch message buffer condition passed as a parameter to execute the desired action. The values act like flags and multiple flags can be set. Remarks None. DRV_MTCH6303_TOUCH_BUFFER_EVENT_HANDLER Type Points to a callback after completion of an message report read or message command write. File drv_mtch6303.h C typedef void (* DRV_MTCH6303_TOUCH_BUFFER_EVENT_HANDLER)(DRV_MTCH6303_TOUCH_BUFFER_EVENT event, DRV_MTCH6303_TOUCH_BUFFER_HANDLE bufferHandle, uintptr_t context); Description MTCH6303 Touch Buffer Event Callback Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1101 This type identifies the MTCH6303 Touch Buffer Event. It allows the client driver to register a callback using DRV_MTCH6303_TOUCH_BUFFER_EVENT_HANDLER. By using this mechanism, the driver client will be notified at the completion of the corresponding transfer. Remarks A transfer can be composed of various transfer segments. Once a transfer is completed the driver will call the client registered transfer callback. The callback could be called from ISR context and should be kept as short as possible. It is meant for signaling and it should not be blocking. Parameters Parameters Description DRV_MTCH6303_TOUCH_BUFFER_EVENT Status of MTCH6303 touch message transfer bufferHandle Handle that identifies the particular Buffer Object context pointer to the object to be processed. Function void ( *DRV_MTCH6303_TOUCH_BUFFER_EVENT_HANDLER ) ( DRV_MTCH6303_TOUCH_BUFFER_EVENT event, DRV_MTCH6303_TOUCH_BUFFER_HANDLE bufferHandle, uintptr_t context ) DRV_MTCH6303_TOUCH_BUFFER_HANDLE Type Handle identifying a read or write touch message buffer passed to the driver. File drv_mtch6303.h C typedef uintptr_t DRV_MTCH6303_TOUCH_BUFFER_HANDLE; Description MTCH6303 Driver Touch Message Queue Buffer Handle A touch message buffer handle value is returned by a call to the DRV_MTCH6303_TOUCH_AddMessageReportRead, DRV_MTCH6303_TOUCH_AddMessageCommandWrite or DRV_MTCH6303_TOUCH_AddTouchInputRead. This handle is associated with the buffer passed into the function and it allows the application to track the completion of the data from (or into) that buffer. The buffer handle value returned from these functions is returned back to the client by the "event handler callback" function registered with the driver. The buffer handle assigned to a client request expires when the client has been notified of the completion of the buffer transfer (after event handler function that notifies the client returns) or after the buffer has been retired by the driver if no event handler callback was set. Remarks None. DRV_MTCH6303_TOUCH_DATA Structure Defines MTCH6303 I2C Touch Data File drv_mtch6303.h C typedef struct { uint8_t i2cReadAddr; DRV_MTCH6303_TOUCH_STATUS status; DRV_MTCH6303_TOUCH_INPUT touch[ DRV_MTCH6303_TOUCH_NUM_INPUTS ]; } DRV_MTCH6303_TOUCH_DATA; Members Members Description uint8_t i2cReadAddr; Dummy I2C Read Address required for bitbang driver DRV_MTCH6303_TOUCH_STATUS status; MTCH6303 Touch Status DRV_MTCH6303_TOUCH_INPUT touch[ DRV_MTCH6303_TOUCH_NUM_INPUTS ]; MTCH6303 Touch Input array of size DRV_MTCH6303_TOUCH_NUM_INPUTS Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1102 Description MTCH6303 I2C Touch Data This structure defines MTCH6303 I2C Touch Data. The structure DRV_MTCH6303_TOUCH_DATA is passed to API's DRV_MTCH6303_AddRegisterRead or DRV_MTCH6303_TOUCH_AddTouchInputRead. The API's will update the structure with touch input. Remarks It is packed to form structure of size 62 bytes. The structure member i2cReadAddr is only applicable if the I2C driver is of type bitbang. Otherwise the variable required to be commented out. DRV_MTCH6303_TOUCH_INPUT Structure Defines MTCH6303 Touch Input Packet File drv_mtch6303.h C typedef struct { DRV_MTCH6303_TOUCH_NIBBLE_0 nibble_0; uint8_t touchId; uint16_t x; uint16_t y; } DRV_MTCH6303_TOUCH_INPUT; Members Members Description DRV_MTCH6303_TOUCH_NIBBLE_0 nibble_0; MTCH6303 I2C Touch Input Packet Nibble 0 uint8_t touchId; MTCH6303 I2C Touch Input Packet ID (0 - 16) uint16_t x; MTCH6303 I2C Touch Input Packet position x (0 - 0x7FFF) uint16_t y; MTCH6303 I2C Touch Input Packet position y (0 - 0x7FFF) Description MTCH6303 Touch Input Packet. This structure defines the MTCH6303 Touch Input Packet. Remarks It is part of DRV_MTCH6303_TOUCH_DATA structure. It is packed to form structure of size 6 bytes. DRV_MTCH6303_TOUCH_MESSAGE Structure Defines MTCH6303 Touch Message. File drv_mtch6303.h C typedef struct { DRV_MTCH6303_TOUCH_MESSAGE_HEADER header; uint8_t payload[0x3E]; } DRV_MTCH6303_TOUCH_MESSAGE; Members Members Description DRV_MTCH6303_TOUCH_MESSAGE_HEADER header; MTCH6303 Touch Message Header uint8_t payload[0x3E]; MTCH6303 Touch Message payload. First byte of payload is of type DRV_TOUCH_MTCH6303_MSG_ID in case of first fragment of message. Otherwise the first byte acts as a normal payload. Description MTCH6303 Touch Message This structure defines MTCH6303 Touch Message. The variable pointer of type DRV_MTCH6303_TOUCH_MESSAGE is passed to the API's Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1103 DRV_MTCH6303_TOUCH_AddMessageReportRead or DRV_MTCH6303_TOUCH_AddMessageCommandWrite. Remarks It is packed to form structure of size 63 bytes. DRV_MTCH6303_TOUCH_MESSAGE_HEADER Structure Defines Touch Message Header. File drv_mtch6303.h C typedef struct { uint32_t msgFragSize : 6; uint32_t continued : 1; uint32_t moreMessages : 1; } DRV_MTCH6303_TOUCH_MESSAGE_HEADER; Members Members Description uint32_t msgFragSize : 6; MTCH6303 Message Fragment Size. If Message Fragment size is 0x3F the Fragment is incomplete and uses up ALL of the parent transport layer packet. uint32_t continued : 1; MTCH6303 Message continued from last fragment if set to 1. uint32_t moreMessages : 1; MTCH6303 more messages to follow in this block if set to 1. Description MTCH6303 Touch Message Header This structure defines Touch Message Header. Remarks It is part of structure DRV_MTCH6303_TOUCH_MESSAGE. It is packed to form structure of size 1 byte. DRV_MTCH6303_TOUCH_NIBBLE_0 Structure Defines the I2C Nibble 0 of MTCH6303 Touch input packet. File drv_mtch6303.h C typedef struct { uint32_t touchState : 1; uint32_t inRange : 1; uint32_t reserved : 6; } DRV_MTCH6303_TOUCH_NIBBLE_0; Members Members Description uint32_t touchState : 1; Touch packet available uint32_t inRange : 1; Touch packet in range uint32_t reserved : 6; Reserved bits Description MTCH6303 I2C Touch Input Packet Nibble 0 This structure defines the I2C Nibble 0 of MTCH6303 Touch input packet. Remarks It is part of DRV_MTCH6303_TOUCH_INPUT structure. It is packed to form structure of size 1 byte. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1104 DRV_MTCH6303_TOUCH_STATUS Structure Defines the I2C touch status register bits File drv_mtch6303.h C typedef struct { uint32_t nTouch : 4; uint32_t streamReady : 1; uint32_t gestureReady : 1; uint32_t gestICData : 1; uint32_t reserved : 1; } DRV_MTCH6303_TOUCH_STATUS; Members Members Description uint32_t nTouch : 4; Number of available touch packets uint32_t streamReady : 1; stream data ready uint32_t gestureReady : 1; gesture data ready uint32_t gestICData : 1; GestIC data ready uint32_t reserved : 1; reserved bit Description MTCH6303 I2C touch status This structure defines the I2C touch status register bits. Remarks It is part of DRV_MTCH6303_TOUCH_DATA structure. It is packed to form structure of size 1 byte. DRV_TOUCH_MTCH6303_MSG_ID Enumeration List of report or command message identification. File drv_mtch6303.h C typedef enum { DRV_TOUCH_MTCH6303_MSG_CMD_QUERY_VERSION } DRV_TOUCH_MTCH6303_MSG_ID; Members Members Description DRV_TOUCH_MTCH6303_MSG_CMD_QUERY_VERSION Message sends firmware version query command. Bytes 124:127 = Rev[2].Minor.Major Description MTCH6303 Touch message Identification. This enumeration identifies the different report or command messages supported by MTCH6303. This identifier identifies the type of the message. The identifier is passed in the message DRV_MTCH6303_TOUCH_MESSAGE as first byte of the payload. It is applicable only for first fragment of message. If message involves multiple fragments, the payload of message fragments other than first fragment should start with normal payload byte. The touch message is read or send to MTCH6303 by using DRV_MTCH6303_TOUCH_AddMessageReportRead or DRV_MTCH6303_TOUCH_AddMessageCommandWrite. Remarks To be passed as first byte of message payload. Applicable only for first fragment of message. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1105 DRV_TOUCH_MTCH6303_I2C_REGISTER_MAP Enumeration List of MTCH6303 I2C Accessible Register Identification. File drv_mtch6303.h C typedef enum { } DRV_TOUCH_MTCH6303_I2C_REGISTER_MAP; Description MTCH6303 I2C Accessible Register Identification. This enumeration identifies the different I2C accessible MTCH6303 Registers. The identifier is passed as source to the register read routine or as destination to the register write routine. The MTCH6303 driver routine to read the I2C accessible MTCH6303 registers is DRV_MTCH6303_AddRegisterRead. The MTCH6303 driver routine to write the I2C accessible MTCH6303 registers is DRV_MTCH6303_AddRegisterWrite. Remarks To read or write multiple registers, identifier of only first register is sufficient as source or destination respectively. Files Files Name Description drv_mtch6303.h MTCH6303 driver interface declarations for the static single instance driver. Description This section lists the source and header files used by the MTCH6303 Touch Driver Library. drv_mtch6303.h MTCH6303 driver interface declarations for the static single instance driver. Enumerations Name Description DRV_MTCH6303_BUFFER_EVENT Lists the different conditions that happens during a buffer transfer. DRV_MTCH6303_CLIENT_STATUS Defines the client-specific status of the MTCH6303 driver. DRV_MTCH6303_ERROR Defines the possible errors that can occur during driver operation. DRV_MTCH6303_TOUCH_BUFFER_EVENT Lists the different conditions that happens during a touch message buffer transfer. DRV_TOUCH_MTCH6303_I2C_REGISTER_MAP List of MTCH6303 I2C Accessible Register Identification. DRV_TOUCH_MTCH6303_MSG_ID List of report or command message identification. Functions Name Description DRV_MTCH6303_AddRegisterRead Schedules a non-blocking register read request to read I2C accessible MTCH6303 registers. DRV_MTCH6303_AddRegisterWrite Schedule a non-blocking driver register write operation to write I2C accessible MTCH6303 registers. DRV_MTCH6303_BufferEventHandlerSet Allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. DRV_MTCH6303_Close Closes an opened-instance of the MTCH6303 driver. DRV_MTCH6303_Deinitialize Deinitializes the instance of the MTCH6303 driver module. DRV_MTCH6303_ErrorGet This function returns the error associated with the last client request. DRV_MTCH6303_Initialize Initializes the MTCH6303 static single instance. DRV_MTCH6303_Open Opens the MTCH6303 driver instance and returns a handle to it. DRV_MTCH6303_Status Gets the current status of the MTCH6303 driver module. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1106 DRV_MTCH6303_Tasks Maintains the driver's register read/write state machine and implements its ISR. DRV_MTCH6303_TOUCH_AddMessageCommandWrite Schedule a non-blocking driver command message write operation to write command message to MTCH6303 registers. DRV_MTCH6303_TOUCH_AddMessageReportRead Schedules a non-blocking report message read request to read the report message from MTCH6303 device. DRV_MTCH6303_TOUCH_AddTouchInputRead Schedules a non-blocking read buffer request to read touch input from MTCH6303. DRV_MTCH6303_TOUCH_BufferEventHandlerSet Allows a client to identify a buffer event handling function for the driver to call back when queued message transfers have finished. DRV_MTCH6303_TOUCH_Tasks Maintains the driver's message state machine and implements its ISR. DRV_MTCH6303_TouchInputMap Maps the raw touch input to display resolution. DRV_MTCH6303_TouchInputRead Schedules a non-blocking read buffer request to read touch input from MTCH6303. Macros Name Description DRV_MTCH6303_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_MTCH6303_TOUCH_BUFFER_HANDLE_INVALID Definition of an invalid buffer handle. DRV_MTCH6303_TOUCH_NUM_INPUTS Definition of number of touch input packets can be identified by MTCH6303. Structures Name Description DRV_MTCH6303_TOUCH_DATA Defines MTCH6303 I2C Touch Data DRV_MTCH6303_TOUCH_INPUT Defines MTCH6303 Touch Input Packet DRV_MTCH6303_TOUCH_MESSAGE Defines MTCH6303 Touch Message. DRV_MTCH6303_TOUCH_MESSAGE_HEADER Defines Touch Message Header. DRV_MTCH6303_TOUCH_NIBBLE_0 Defines the I2C Nibble 0 of MTCH6303 Touch input packet. DRV_MTCH6303_TOUCH_STATUS Defines the I2C touch status register bits Types Name Description DRV_MTCH6303_BUFFER_EVENT_HANDLER Points to a callback after completion of an register read -write or message stream read - write. DRV_MTCH6303_BUFFER_HANDLE Handle identifying a read or write buffer passed to the driver. DRV_MTCH6303_TOUCH_BUFFER_EVENT_HANDLER Points to a callback after completion of an message report read or message command write. DRV_MTCH6303_TOUCH_BUFFER_HANDLE Handle identifying a read or write touch message buffer passed to the driver. Description MTCH6303 Driver Interface Declarations for Static Single Instance Driver The MTCH6303 device driver provides a simple interface to manage the MTCH6303 module. This file defines the interface Declarations for the MTCH6303 driver. Remarks Static single instance driver interface eliminates the need for an object ID or object handle. Static single-open interfaces also eliminate the need for the open handle. File Name drv_mtch6303_static.h Company Microchip Technology Inc. mXT336T Touch Driver Library This topic describes the mXT336T Touch Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1107 Introduction This library provides an interface to manage the mXT336T Touch Driver module on the Microchip family of microcontrollers in different modes of operation. Description The MPLAB Harmony mXT336T Touch Driver provides a high-level interface to the mXT336T touch controller device. This driver provides application routines to read the touch input data from the touch screen. The mXT336T device can notify the availability of touch input data through external interrupt. The mXT336T driver allows the application to map a controller pin as an external interrupt pin. Currently, the mXT336T Touch Driver only supports non-gestural single-fingered touch input. Using the Library This topic describes the basic architecture of the mXT336T Touch Driver Library and provides information and examples on its use. Description Interface Header Files: drv_mxt336t.h, drv_mxt.h The interface to the mXT336T Touch Driver library is defined in the drv_mxt336t.h and drv_mxt.h header files. Any C language source (.c) file that uses the mXT336T Touch Driver library should include this header. The mXT336T Touch Driver is based on the Object Protocol for the Atmel® maXTouch® mXT336T Touchscreen Controller. The functioning of the driver is divided into two file sets: • drv_mxt.h has the system touch interface (API’s, Initialization and tasks) • drv_mxt336t.h has the device specific interface for getting the device ready for communication and receiving commands. The device specific interface is based on the Object Protocol previously mentioned. The aria_quickstart demonstration interfaces with the mXT336T Touch Driver Library. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the mXT336T Touch Driver Library 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 mXT336T Touch Driver has routines to perform the following operations: • Sending read request • Reading the touch input data • Access to the touch input data The driver initialization routines allow the application to initialize the driver. The driver must be initialized before it can be used by application. Once the driver is initialized the driver open routine allows retrieving the client handle. Once the touch input is available a touch input read request is sent and input data is retrieved in a buffer. The buffer data is then decoded to get the x and y coordinate of the touch screen in the form of the number of pixels. mXT336T Driver Abstraction Model Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1108 Library Overview This section contains information about how the Touch Driver operates in a system. Description The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the mXT336T Touch Driver. Library Interface Section Description Device-specific Functions Provides mXT336T-specific system module interfaces, device initialization, deinitialization, open, close, task, and status functions. Generic Functions Provides generic system module interfaces, device initialization, deinitialization, open, close, task, and status functions. How the Library Works This section describes the workings of the Touch Driver Library. Description The library provides interfaces to support: • System functions, which provide system module interfaces, device initialization, deinitialization, open, close, task, and status functions. • Read Request function, which provides Touch input data read request function • Read Touch Input function, which provides functions retrieving updated Touch input in the form x and y coordinates. Initializing the Driver Before the mXT336T Touch Driver can be opened, it must be configured and initialized. The driver build time configuration is defined by the configuration macros. Refer to the Building the Library section for the location of and more information on the various configuration macros and how these macros should be designed. The driver initialization is configured through the DRV_TOUCH_INIT data structure that is passed to the DRV_MXT336T_Initialize and the DRV_MXT_Initialize functions. The initialization parameters include the interrupt source, interrupt pin remap configuration and touch screen resolution. The following code shows an example of initializing the mXT336T Touch Driver. Example: /* The following code shows an example of designing the * DRV_TOUCH_INIT data structure. It also shows how an example * usage of the DRV_TOUCH_MXT336T_Initialize function. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1109 */ DRV_TOUCH_INIT drvTouchInitData; DRV_MXT_INIT drvMxtInitData; SYS_MODULE_OBJ objectHandle; const DRV_MXT336T_INIT drvTouchInitData = { .moduleInit = {0}, .touchId = DRV_TOUCH_INDEX_0, .drvInitialize = NULL, .drvOpen = DRV_I2C_Open, .orientation = 0, .horizontalResolution = 480, .verticalResolution = 272, .interruptSource = INT_SOURCE_EXTERNAL_1, .interruptChannel = PORT_CHANNEL_E, .interruptPin = PORTS_BIT_POS_8, .resetChannel = PORT_CHANNEL_A, .resetPin = PORTS_BIT_POS_2, }; const DRV_MXT_INIT drvMxtInitData = { .moduleInit = {0}, .mxtId = DRV_MXT_INDEX_0, .drvInitialize = NULL, .orientation = 0, .horizontalResolution = 480, .verticalResolution = 272, }; /* Driver initialization */ sysObj.drvMXT336T = DRV_MXT336T_Initialize(DRV_MXT336T_INDEX_0, (SYS_MODULE_INIT *)&drvTouchInitData); sysObj.drvMxt0 = DRV_MXT_Initialize(DRV_MXT_INDEX_0, (SYS_MODULE_INIT *)&drvMxtInitData); Opening the Driver To use the mXT336T Touch Driver, the application must open the driver. This is done by calling the DRV_MXT_Open function. If successful, the DRV_MXT_Open function will return a handle to the driver. This handle records the association between the client and the driver instance that was opened. The DRV_MXT_Open function may return DRV_HANDLE_INVALID in the situation where the driver is not ready to be opened. When this occurs, the application can try opening the driver again. Note that the open function may return an invalid handle in other (error) cases as well. The following code shows an example of the driver being opened. The open function in the driver is called from the system initialization routine by assigning a function pointer from sys_init object. const DRV_TOUCH_INIT sysTouchInit0 = { .drvInitialize = DRV_MXT_Initialize, .drvOpen = DRV_MXT_Open, . . }; SYS_TOUCH_HANDLE SYS_TOUCH_Open ( const SYS_MODULE_INDEX moduleIndex ) { SYS_TOUCH_CLIENT_OBJ *clientObj; SYS_TOUCH_OBJ *dObj; . . . /* open touch driver */ dObj->driverInitData->drvOpen(moduleIndex, DRV_IO_INTENT_READWRITE); Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1110 } Touch Input Read Request To read the touch input from the mXT336T touch controller device, a read request must be registered. This is done by calling DRV_MXT336T_ReadRequest. If successful, it registers a buffer read request to the I2C command queue. It also adds an input decode command to the mXT336T command queue once the I2C returns with touch input data. It can return error if the driver instance object is invalid or the mXT336T command queue is full. The read request is to be called from the mXT336T ISR. This ISR is triggered once the touch input is available. The following code shows an example of a mXT336T read request registration: SYS_MODULE_OBJ object; // Returned from DRV_TOUCH_MXT336T_Initialize void ISR(_EXTERNAL_INT_VECTOR, ipl5) _IntHandlerDrvMxt336t(void) { DRV__MXT336T_ReadRequest ( object ); // Do other tasks Tasks Routine This routine processes the mXT336T commands from the command queue. If the state of the command is initialize or done it returns. If the read request registration is successful the state of command is to decode input. The tasks routine decodes the input and updates the global variables storing the touch input data in form of x and y coordinates. The mXT336T Touch Driver task routine is to be called from SYS_Tasks. The following code shows an example: SYS_MODULE_OBJ drvMXT336T; SYS_MODULE_OBJ drvMxt0;; // Returned from DRV_TOUCH_MXT336T_Initialize void SYS_Tasks( void ) { DRV_MXT336T_Tasks(sysObj.drvMXT336T); DRV_MXT_Tasks(sysObj.drvMxt0); // Do other tasks } Configuring the Library Macros Name Description DRV_MXT336T_CALIBRATION_DELAY Defines the calibration delay. DRV_MXT336T_CALIBRATION_INSET Defines the calibration inset. DRV_MXT336T_CLIENTS_NUMBER Selects the maximum number of clients. DRV_MXT336T_INDEX MXT336T static index selection. DRV_MXT336T_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported. DRV_MXT336T_INTERRUPT_MODE Controls operation of the driver in the interrupt or polled mode. DRV_MXT336T_SAMPLE_POINTS Define the sample points. DRV_MXT336T_TOUCH_DIAMETER Defines the touch diameter. Description The configuration of the mXT336T Touch Driver is based on the file system_config.h. This header file contains the configuration selection for the mXT336T Touch Driver. Based on the selections made, the driver may support the selected features. These configuration settings will apply to all instances of the mXT336T Touch Driver. This header can be placed anywhere, 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. DRV_MXT336T_CALIBRATION_DELAY Macro Defines the calibration delay. File drv_mxt336t_config_template.h Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1111 C #define DRV_MXT336T_CALIBRATION_DELAY 300 Description MXT336T Calibration Delay This macro enables the delay between calibration touch points. Remarks None. DRV_MXT336T_CALIBRATION_INSET Macro Defines the calibration inset. File drv_mxt336t_config_template.h C #define DRV_MXT336T_CALIBRATION_INSET 25 Description MXT336T Calibration Inset This macro defines the calibration inset. Remarks None. DRV_MXT336T_CLIENTS_NUMBER Macro Selects the maximum number of clients. File drv_mxt336t_config_template.h C #define DRV_MXT336T_CLIENTS_NUMBER 5 Description MXT336T maximum number of clients This macro selects the maximum number of clients. This definition selected the maximum number of clients that the MXT336T driver can support at run time. Remarks None. DRV_MXT336T_INDEX Macro MXT336T static index selection. File drv_mxt336t_config_template.h C #define DRV_MXT336T_INDEX DRV_MXT336T_INDEX_0 Description MXT336T Static Index Selection This macro specifies the static index selection for the driver object reference. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1112 Remarks This index is required to make a reference to the driver object. DRV_MXT336T_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported. File drv_mxt336t_config_template.h C #define DRV_MXT336T_INSTANCES_NUMBER 1 Description MXT336T hardware instance configuration This macro sets up the maximum number of hardware instances that can be supported. Remarks None. DRV_MXT336T_INTERRUPT_MODE Macro Controls operation of the driver in the interrupt or polled mode. File drv_mxt336t_config_template.h C #define DRV_MXT336T_INTERRUPT_MODE false Description MXT336T Interrupt And Polled Mode Operation Control This macro controls the operation of the driver in the interrupt mode of operation. The possible values of this macro are: • true - Select if interrupt mode of MXT336T operation is desired • false - Select if polling mode of MXT336T operation is desired Not defining this option to true or false will result in a build error. Remarks None. DRV_MXT336T_SAMPLE_POINTS Macro Define the sample points. File drv_mxt336t_config_template.h C #define DRV_MXT336T_SAMPLE_POINTS 4 Description MXT336T Sample Points MXT336T sample points Remarks None. DRV_MXT336T_TOUCH_DIAMETER Macro Defines the touch diameter. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1113 File drv_mxt336t_config_template.h C #define DRV_MXT336T_TOUCH_DIAMETER 10 Description MXT336T Touch Diameter This macro defines the touch diameter Remarks None. Configuring the MHC The following figure details the settings required to configure the MHC for the mXT336T Touch Driver. Building the Library This section lists the files that are available in the mXT336T Touch Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1114 Description This section list the files that are available in the \src folder of the mXT336T Touch 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. 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 /framework/driver/touch/mxt336t. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_mxt336t.h Header file that exports the device-specific driver API. /drv_mxt.h Header file for generic driver API. 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 src/drv_mxt336t.c Basic mXT336T Touch Driver implementation file. src/drv_mxt.c Generic maXTouch touch driver implementation file. 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 N/A No optional files are available for this library. Module Dependencies The mXT336T Touch Driver Library depends on the following modules: • Interrupt System Service Library • Ports System Service Library • Touch System Service Library • I2C Driver Library Library Interface a) Device-specific Functions Name Description DRV_MXT336T_Close Closes an opened instance of the MXT336T driver. Implementation: Dynamic DRV_MXT336T_ReadRequest Sends a read request to I2C bus driver and adds the read task to queue. Implementation: Dynamic DRV_MXT336T_Open Opens the specified MXT336T driver instance and returns a handle to it. Implementation: Dynamic DRV_MXT336T_CloseObject Closes an opened instance of the MXT336T client object DRV_MXT336T_OpenObject Opens the specified MXT336T object driver instance and returns a handle to it. Implementation: Dynamic DRV_MXT336T_DEVICE_ClientObjectEventHandlerSet Sets the event handler for a MXT336T client object DRV_MXT336T_Deinitialize Deinitializes the specified instance of the MXT336T driver module. Implementation: Dynamic DRV_MXT336T_Initialize Initializes the MXT336T instance for the specified driver index DRV_MXT336T_Status Provides the current status of the MXT336T driver module. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1115 DRV_MXT336T_Tasks Maintains the driver's state machine and implements its task queue processing. Implementation: Dynamic b) Generic Functions Name Description DRV_MXT_Close Closes an opened instance of the MXT driver. Implementation: Dynamic DRV_MXT_MaxtouchEventCallback DRV_MXT_Deinitialize Deinitializes the specified instance of the MXT driver module. Implementation: Dynamic DRV_MXT_Open Opens the specified MXT driver instance and returns a handle to it. Implementation: Dynamic DRV_MXT_TouchDataRead Notifies the driver that the current touch data has been read DRV_MXT_Initialize Initializes the MXT instance for the specified driver index. Implementation: Dynamic DRV_MXT_ReadRequest Sends a read request to I2C bus driver and adds the read task to queue. Implementation: Dynamic DRV_MXT_TouchGetX Returns the x coordinate of touch input. Implementation: Dynamic DRV_MXT_TouchGetY Returns the y coordinate of touch input. Implementation: Dynamic DRV_MXT_Status Provides the current status of the MXT driver module. Implementation: Dynamic DRV_MXT_Tasks Maintains the driver's state machine and implements its task queue processing. Implementation: Dynamic DRV_MXT_TouchStatus Returns the status of the current touch input. c) Data Types and Constants Name Description _DRV_MXT_CLIENT_OBJECT MXT Driver client object maintaining client data. DRV_MXT_CLIENT_OBJECT MXT Driver client object maintaining client data. DRV_MXT_HANDLE Touch screen controller MXT driver handle. DRV_MXT_INIT Defines the data required to initialize or reinitialize the MXT driver DRV_MXT_MODULE_ID Number of valid MXT driver indices. DRV_MXT_OBJECT Defines the data structure maintaining MXT driver instance object. DRV_MXT_TASK_QUEUE Defines the MXT Touch Controller driver task data structure. DRV_MXT_TASK_STATE Enumeration defining MXT touch controller driver task state. DRV_MXT336T_CLIENT_CALLBACK Pointer to a MXT336T client callback function data type. DRV_MXT336T_HANDLE Touch screen controller MXT336T driver handle. DRV_MXT336T_INIT Defines the data required to initialize or reinitialize the MXT336T driver DRV_MXT336T_OBJECT_CLIENT_EVENT_DATA This structure maintains the information associated with each msg received or event that occurs DRV_MXT336T_OBJECT_TYPE The enum lists the different objects supported by the maxtouch device. DRV_MXT_HANDLE_INVALID Definition of an invalid handle. _DRV_MXT336T_H This is macro _DRV_MXT336T_H. DRV_MXT_I2C_MASTER_READ_ID MXT input read, I2C address from where master reads touch input data. DRV_MXT_I2C_MASTER_WRITE_ID MXT command register write, I2C address where master sends the commands. DRV_MXT_I2C_READ_FRAME_SIZE I2C Frame size for reading MXT touch input. DRV_MXT_INDEX_0 MXT driver index definitions. DRV_MXT_INDEX_1 This is macro DRV_MXT_INDEX_1. DRV_MXT_INDEX_COUNT Number of valid Touch controller MXT driver indices. DRV_MXT336T_HANDLE_INVALID Definition of an invalid handle. DRV_MXT336T_I2C_FRAME_SIZE I2C Frame size for reading MXT336T touch input. DRV_MXT336T_I2C_MASTER_READ_ID MXT336T input read, I2C address from where master reads touch input data. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1116 DRV_MXT336T_I2C_MASTER_WRITE_ID MXT336T command register write, I2C address where master sends the commands. DRV_MXT336T_I2C_READ_ID_FRAME_SIZE This is macro DRV_MXT336T_I2C_READ_ID_FRAME_SIZE. DRV_MXT336T_INDEX_0 MXT336T driver index definitions. DRV_MXT336T_INDEX_1 This is macro DRV_MXT336T_INDEX_1. DRV_MXT336T_INDEX_COUNT Number of valid Touch controller MXT336T driver indices. t100_event Types of touch events reported by the Maxtouch Multi touch object t100_type Types of touch types reported by the Maxtouch Multi touch object DRV_MXT336T_T100_XRANGE MXT336T Driver Object Register Adresses for the registers being read in the driver DRV_MXT336T_T100_YRANGE This is macro DRV_MXT336T_T100_YRANGE. Description This section describes the functions of the mXT336T Touch Driver Library. Refer to each section for a detailed description. a) Device-specific Functions DRV_MXT336T_Close Function Closes an opened instance of the MXT336T driver. Implementation: Dynamic File drv_mxt336t.h C void DRV_MXT336T_Close(DRV_HANDLE handle); Returns None Description This function closes an opened instance of the MXT336T driver, invalidating the handle. Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_MXT336T_Open before the caller may use the driver again. This function is thread safe in a RTOS application. Usually, there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_MXT336T_Initialize routine must have been called for the specified MXT336T driver instance. DRV_MXT336T_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_MXT336T_Open DRV_MXT336T_Close ( handle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_MXT336T_Close ( DRV_HANDLE handle ) DRV_MXT336T_ReadRequest Function Sends a read request to I2C bus driver and adds the read task to queue. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1117 Implementation: Dynamic File drv_mxt336t.h C void DRV_MXT336T_ReadRequest(SYS_MODULE_OBJ object); Returns None. Description This routine is used to send a touch input read request to the I2C bus driver and adding the input read decode task to the queue. It is always called from MXT336T interrupt ISR routine. Remarks This function is normally not called directly by an application. It is called by the MXT336T ISR routine. Preconditions The DRV_MXT336T_Initialize routine must have been called for the specified MXT336T driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_MXT336T_Initialize void __ISR(_EXTERNAL_INT_VECTOR, ipl5) _IntHandlerDrvMXT(void) { DRV_MXT336T_ReadRequest ( object ); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_MXT336T_Initialize) Function void DRV_MXT336T_ReadRequest( SYS_MODULE_OBJ object ) DRV_MXT336T_Open Function Opens the specified MXT336T driver instance and returns a handle to it. Implementation: Dynamic File drv_mxt336t.h C DRV_HANDLE DRV_MXT336T_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. An error can occur when the following is true: • if the number of client objects allocated via DRV_MXT336T_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the driver hardware instance being opened is not initialized or is invalid Description This routine opens the specified MXT336T driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. The current version of driver does not support the DRV_IO_INTENT feature. The driver is by default non-blocking. The driver can perform both read and write to the MXT336T device. The driver supports single client only. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1118 Remarks The handle returned is valid until the DRV_MXT336T_Close routine is called. This routine will NEVER block waiting for hardware. If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. It should not be called in an ISR. Preconditions The DRV_MXT336T_Initialize function must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_MXT336T_Open( DRV_MXT336T_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); if( DRV_HANDLE_INVALID == handle ) { // Unable to open the driver } Parameters Parameters Description drvIndex Index of the driver initialized with DRV_MXT336T_Initialize(). intent Zero or more of the values from the enumeration DRV_IO_INTENT ORed together to indicate the intended use of the driver. The current version of driver does not support the selective IO intent feature. Function DRV_HANDLE DRV_MXT336T_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ) DRV_MXT336T_CloseObject Function Closes an opened instance of the MXT336T client object File drv_mxt336t.h C void DRV_MXT336T_CloseObject(DRV_HANDLE handle); Returns None Description This function closes an opened instance of the MXT336T client object, invalidating the handle. Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_MXT336T_OpenObject before the caller may use the driver again. This function is thread safe in a RTOS application. Usually, there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_MXT336T_Initialize routine must have been called for the specified MXT336T driver instance. DRV_MXT336T_OpenObject must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_MXT336T_Open DRV_MXT336T_CloseObject ( handle ); Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1119 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_MXT336T_CloseObject ( DRV_HANDLE handle ) DRV_MXT336T_OpenObject Function Opens the specified MXT336T object driver instance and returns a handle to it. Implementation: Dynamic File drv_mxt336t.h C DRV_HANDLE DRV_MXT336T_OpenObject(const DRV_HANDLE deviceHandle, const uint8_t objType, const uint8_t objInstance); Returns If successful, the routine returns a valid object-instance handle ( Description This routine opens the specified MXT336T object driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. Preconditions The DRV_MXT336T_Initialize function must have been called before calling this function. The driver must have been opened. Example DRV_HANDLE handle; handle = DRV_MXT336T_OpenObject(drvHandle, GEN_PROCESSOR_T5, 1); Parameters Parameters Description deviceHandle Handle of the MXT336T device objType Object type being requested objInstance Instance of the object of this type Function DRV_HANDLE DRV_MXT336T_OpenObject ( const DRV_HANDLE deviceHandle, const uint8_t objType, const uint8_t objInstance ) DRV_MXT336T_DEVICE_ClientObjectEventHandlerSet Function Sets the event handler for a MXT336T client object File drv_mxt336t.h C bool DRV_MXT336T_DEVICE_ClientObjectEventHandlerSet(const DRV_HANDLE clientHandle, const DRV_MXT336T_CLIENT_CALLBACK callback, uintptr_t context); Returns bool - true if the handler was successfully set • false if the handler could not be set Description This function sets the event handler used to handle report messages from a MXT336T object. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1120 Preconditions The DRV_MXT336T_OpenObject routine must have been called for the specified MXT336T driver instance. DRV_MXT336T_OpenObject must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_MXT336T_OpenObject DRV_MXT336T_DEVICE_ClientObjectEventHandlerSet(handle, objectCallback, NULL); Parameters Parameters Description clientHandle A valid open-instance handle, returned from the driver's openobject routine callback A callback function to handle report messages context The context for the call Function bool DRV_MXT336T_DEVICE_ClientObjectEventHandlerSet(const DRV_HANDLE clientHandle, const DRV_MXT336T_CLIENT_CALLBACK callback, uintptr_t context) DRV_MXT336T_Deinitialize Function Deinitializes the specified instance of the MXT336T driver module. Implementation: Dynamic File drv_mxt336t.h C void DRV_MXT336T_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the MXT336T driver module, disabling its operation (and any hardware) and invalidates all of the internal data. Remarks Once the Initialize operation has been called, the De-initialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_MXT336T_Status operation. The system has to use DRV_MXT336T_Status to determine when the module is in the ready state. Preconditions Function DRV_MXT336T_Initialize must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Parameter: object - Driver object handle, returned from DRV_MXT336T_Initialize Example SYS_MODULE_OBJ object; //Returned from DRV_MXT336T_Initialize SYS_STATUS status; DRV_MXT336T_Deinitialize ( object ); status = DRV_MXT336T_Status( object ); if( SYS_MODULE_UNINITIALIZED == status ) { // Check again later if you need to know // when the driver is deinitialized. } Function void DRV_MXT336T_Deinitialize ( SYS_MODULE_OBJ object ) Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1121 DRV_MXT336T_Initialize Function Initializes the MXT336T instance for the specified driver index File drv_mxt336t.h C SYS_MODULE_OBJ DRV_MXT336T_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the MXT336T driver instance for the specified driver index, making it ready for clients to open and use it. The initialization data is specified by the 'init' parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. The driver instance index is independent of the MXT336T module ID. For example, driver instance 0 can be assigned to MXT336T2. If the driver is built statically, then some of the initialization parameters are overridden by configuration macros. Refer to the description of the DRV_MXT336T_INIT data structure for more details on which members on this data structure are overridden. Remarks This routine must be called before any other MXT336T routine is called. This routine should only be called once during system initialization unless DRV_MXT336T_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. Preconditions None. Example DRV_MXT336T_INIT init; SYS_MODULE_OBJ objectHandle; // Populate the MXT336T initialization structure // Touch Module Id init.moduleInit = {0}, init.touchId = DRV_TOUCH_INDEX_0, init.drvInitialize = NULL, init.drvOpen = DRV_I2C_Open, init.interruptSource = INT_SOURCE_EXTERNAL_1, init.interruptChannel = PORT_CHANNEL_D, init.interruptPin = PORTS_BIT_POS_1, init.resetChannel = PORT_CHANNEL_A, init.resetPin = PORTS_BIT_POS_14, objectHandle = DRV_MXT336T_Initialize(DRV_TOUCH_INDEX_0, (SYS_MODULE_INIT*)init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized. Please note this is not the MXT336T ID. The hardware MXT336T ID is set in the initialization structure. This is the index of the driver index to use. init Pointer to a data structure containing any data necessary to initialize the driver. If this pointer is NULL, the driver uses the static initialization override macros for each member of the initialization data structure. Function SYS_MODULE_OBJ DRV_MXT336T_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ) Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1122 DRV_MXT336T_Status Function Provides the current status of the MXT336T driver module. Implementation: Dynamic File drv_mxt336t.h C SYS_STATUS DRV_MXT336T_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system-level operation and cannot start another Description This function provides the current status of the MXT336T driver module. Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_MODULE_UNINITIALIZED - Indicates that the driver has been deinitialized This value is less than SYS_STATUS_ERROR. This function can be used to determine when any of the driver's module level operations has completed. If the status operation returns SYS_STATUS_BUSY, the previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This function will NEVER block waiting for hardware. If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Preconditions The DRV_MXT336T_Initialize function must have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_MXT336T_Initialize SYS_STATUS status; status = DRV_MXT336T_Status( object ); if( SYS_STATUS_READY != status ) { // Handle error } Parameters Parameters Description object Driver object handle, returned from DRV_MXT336T_Initialize Function SYS_STATUS DRV_MXT336T_Status ( SYS_MODULE_OBJ object ) DRV_MXT336T_Tasks Function Maintains the driver's state machine and implements its task queue processing. Implementation: Dynamic File drv_mxt336t.h C void DRV_MXT336T_Tasks(SYS_MODULE_OBJ object); Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1123 Returns None. Description This routine is used to maintain the driver's internal state machine and implement its command queue processing. It is always called from SYS_Tasks() function. This routine decodes the touch input data available in drvI2CReadFrameData. Remarks This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) Preconditions The DRV_MXT336T_Initialize routine must have been called for the specified MXT336T driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_MXT336T_Initialize void SYS_Tasks( void ) { DRV_MXT336T_Tasks ( object ); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_MXT336T_Initialize) Function void DRV_MXT336T_Tasks ( SYS_MODULE_OBJ object ); b) Generic Functions DRV_MXT_Close Function Closes an opened instance of the MXT driver. Implementation: Dynamic File drv_mxt.h C void DRV_MXT_Close(DRV_HANDLE handle); Returns None Description This function closes an opened instance of the MXT driver, invalidating the handle. Remarks After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines. A new handle must be obtained by calling DRV_MXT_Open before the caller may use the driver again. This function is thread safe in a RTOS application. Usually, there is no need for the driver client to verify that the Close operation has completed. Preconditions The DRV_MXT_Initialize routine must have been called for the specified MXT driver instance. DRV_MXT_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_MXT_Open Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1124 DRV_MXT_Close ( handle ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_MXT_Close ( DRV_HANDLE handle ) DRV_MXT_MaxtouchEventCallback Function File drv_mxt.h C void DRV_MXT_MaxtouchEventCallback(DRV_HANDLE clientObject, DRV_MXT336T_OBJECT_CLIENT_EVENT_DATA * updateObject, uintptr_t context); Remarks See prototype in app.h. Function void DRV_MXT_MaxtouchEventCallback ( DRV_HANDLE clientObject, DRV_MAXTOUCH_OBJECT_CLIENT_EVENT_DATA *updateObject, uintptr_t context); DRV_MXT_Deinitialize Function Deinitializes the specified instance of the MXT driver module. Implementation: Dynamic File drv_mxt.h C void DRV_MXT_Deinitialize(SYS_MODULE_OBJ object); Returns None. Description Deinitializes the specified instance of the MXT driver module, disabling its operation (and any hardware) and invalidates all of the internal data. Remarks Once the Initialize operation has been called, the De-initialize operation must be called before the Initialize operation can be called again. This function will NEVER block waiting for hardware. If the operation requires time to allow the hardware to complete, this will be reported by the DRV_MXT_Status operation. The system has to use DRV_MXT_Status to determine when the module is in the ready state. Preconditions Function DRV_MXT_Initialize must have been called before calling this routine and a valid SYS_MODULE_OBJ must have been returned. Parameter: object - Driver object handle, returned from DRV_MXT_Initialize Example SYS_MODULE_OBJ object; //Returned from DRV_MXT_Initialize SYS_STATUS status; DRV_MXT_Deinitialize ( object ); status = DRV_MXT_Status( object ); if( SYS_MODULE_UNINITIALIZED == status ) { // Check again later if you need to know Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1125 // when the driver is deinitialized. } Function void DRV_MXT_Deinitialize ( SYS_MODULE_OBJ object ) DRV_MXT_Open Function Opens the specified MXT driver instance and returns a handle to it. Implementation: Dynamic File drv_mxt.h C DRV_HANDLE DRV_MXT_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. An error can occur when the following is true: • if the number of client objects allocated via DRV_MXT_CLIENTS_NUMBER is insufficient • if the client is trying to open the driver but driver has been opened exclusively by another client • if the driver hardware instance being opened is not initialized or is invalid Description This routine opens the specified MXT driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. The current version of driver does not support the DRV_IO_INTENT feature. The driver is by default non-blocking. The driver can perform both read and write to the MXT device. The driver supports single client only. Remarks The handle returned is valid until the DRV_MXT_Close routine is called. This routine will NEVER block waiting for hardware. If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. It should not be called in an ISR. Preconditions The DRV_MXT_Initialize function must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_MXT_Open( DRV_MXT_INDEX_0, DRV_IO_INTENT_EXCLUSIVE ); if( DRV_HANDLE_INVALID == handle ) { // Unable to open the driver } Parameters Parameters Description drvIndex Index of the driver initialized with DRV_MXT_Initialize(). intent Zero or more of the values from the enumeration DRV_IO_INTENT ORed together to indicate the intended use of the driver. The current version of driver does not support the selective IO intent feature. Function DRV_HANDLE DRV_MXT_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ) Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1126 DRV_MXT_TouchDataRead Function Notifies the driver that the current touch data has been read File drv_mxt.h C void DRV_MXT_TouchDataRead(const SYS_MODULE_INDEX index); Returns None. Description Notifies the driver that the current touch data has been read Function void DRV_MXT_TouchDataRead( const SYS_MODULE_INDEX index ) DRV_MXT_Initialize Function Initializes the MXT instance for the specified driver index. Implementation: Dynamic File drv_mxt.h C SYS_MODULE_OBJ DRV_MXT_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the MXT driver instance for the specified driver index, making it ready for clients to open and use it. The initialization data is specified by the 'init' parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. The driver instance index is independent of the MXT module ID. For example, driver instance 0 can be assigned to MXT2. If the driver is built statically, then some of the initialization parameters are overridden by configuration macros. Refer to the description of the DRV_MXT_INIT data structure for more details on which members on this data structure are overridden. Remarks This routine must be called before any other MXT routine is called. This routine should only be called once during system initialization unless DRV_MXT_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. Preconditions None. Example DRV_MXT_INIT init; SYS_MODULE_OBJ objectHandle; // Populate the MXT initialization structure // Touch Module Id init.touchId = DRV_TOUCH_INDEX_0; // I2C Bus driver open init.drvOpen = DRV_I2C_Open; // Interrupt Source for Touch init.interruptSource = INT_SOURCE_EXTERNAL_1; // Interrupt Pin function mapping Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1127 init.interruptPort.inputFunction = INPUT_FUNC_INT1; // Pin to be mapped as interrupt pin init.interruptPort.inputPin = INPUT_PIN_RPE8; // Analog pin number init.interruptPort.analogPin = PORTS_ANALOG_PIN_25; // Pin Mode of analog pin init.interruptPort.pinMode = PORTS_PIN_MODE_DIGITAL; // Interrupt pin port init.interruptPort.channel = PORT_CHANNEL_E; // Interrupt pin port maskl init.interruptPort.dataMask = 0x8; // Touch screen orientation init.orientation = DISP_ORIENTATION; // Touch screen horizontal resolution init.horizontalResolution = DISP_HOR_RESOLUTION; // Touch screen vertical resolution init.verticalResolution = DISP_VER_RESOLUTION; objectHandle = DRV_MXT_Initialize(DRV_TOUCH_INDEX_0, (SYS_MODULE_INIT*)init); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized. Please note this is not the MXT ID. The hardware MXT ID is set in the initialization structure. This is the index of the driver index to use. init Pointer to a data structure containing any data necessary to initialize the driver. If this pointer is NULL, the driver uses the static initialization override macros for each member of the initialization data structure. Function SYS_MODULE_OBJ DRV_MXT_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ) DRV_MXT_ReadRequest Function Sends a read request to I2C bus driver and adds the read task to queue. Implementation: Dynamic File drv_mxt.h C void DRV_MXT_ReadRequest(SYS_MODULE_OBJ object); Returns None. Description This routine is used to send a touch input read request to the I2C bus driver and adding the input read decode task to the queue. It is always called from MXT interrupt ISR routine. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1128 Remarks This function is normally not called directly by an application. It is called by the MXT ISR routine. Preconditions The DRV_MXT_Initialize routine must have been called for the specified MXT driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_MXT_Initialize void __ISR(_EXTERNAL_INT_VECTOR, ipl5) _IntHandlerDrvMXT(void) { DRV_MXT_ReadRequest ( object ); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_MXT_Initialize) Function void DRV_MXT_ReadRequest( SYS_MODULE_OBJ object ) DRV_MXT_TouchGetX Function Returns the x coordinate of touch input. Implementation: Dynamic File drv_mxt.h C short DRV_MXT_TouchGetX(uint8_t touchNumber); Returns It returns the x coordinate of the touch input in terms of number of pixels. Description It returns the x coordinate in form of number of pixes for a touch input denoted by touchNumber. Parameters Parameters Description touchNumber index to the touch input. Function short DRV_MXT_TouchGetX( uint8 touchNumber ) DRV_MXT_TouchGetY Function Returns the y coordinate of touch input. Implementation: Dynamic File drv_mxt.h C short DRV_MXT_TouchGetY(uint8_t touchNumber); Returns It returns the y coordinate of the touch input in terms of number of pixels. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1129 Description It returns the y coordinate in form of number of pixes for a touch input denoted by touchNumber. Parameters Parameters Description touchNumber index to the touch input. Function short DRV_MXT_TouchGetY( uint8 touchNumber ) DRV_MXT_Status Function Provides the current status of the MXT driver module. Implementation: Dynamic File drv_mxt.h C SYS_STATUS DRV_MXT_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system-level operation and cannot start another Description This function provides the current status of the MXT driver module. Remarks Any value greater than SYS_STATUS_READY is also a normal running state in which the driver is ready to accept new operations. SYS_MODULE_UNINITIALIZED - Indicates that the driver has been deinitialized This value is less than SYS_STATUS_ERROR. This function can be used to determine when any of the driver's module level operations has completed. If the status operation returns SYS_STATUS_BUSY, the previous operation has not yet completed. Once the status operation returns SYS_STATUS_READY, any previous operations have completed. The value of SYS_STATUS_ERROR is negative (-1). Any value less than that is also an error state. This function will NEVER block waiting for hardware. If the Status operation returns an error value, the error may be cleared by calling the reinitialize operation. If that fails, the deinitialize operation will need to be called, followed by the initialize operation to return to normal operations. Preconditions The DRV_MXT_Initialize function must have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_MXT_Initialize SYS_STATUS status; status = DRV_MXT_Status( object ); if( SYS_STATUS_READY != status ) { // Handle error } Parameters Parameters Description object Driver object handle, returned from DRV_MXT_Initialize Function SYS_STATUS DRV_MXT_Status ( SYS_MODULE_OBJ object ) Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1130 DRV_MXT_Tasks Function Maintains the driver's state machine and implements its task queue processing. Implementation: Dynamic File drv_mxt.h C void DRV_MXT_Tasks(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal state machine and implement its command queue processing. It is always called from SYS_Tasks() function. This routine decodes the touch input data available in drvI2CReadFrameData. Remarks This function is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) Preconditions The DRV_MXT_Initialize routine must have been called for the specified MXT driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_MXT_Initialize void SYS_Tasks( void ) { DRV_MXT_Tasks ( object ); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_MXT_Initialize) Function void DRV_MXT_Tasks ( SYS_MODULE_OBJ object ); DRV_MXT_TouchStatus Function Returns the status of the current touch input. File drv_mxt.h C DRV_TOUCH_POSITION_STATUS DRV_MXT_TouchStatus(const SYS_MODULE_INDEX index); Returns It returns the status of the current touch input. Description It returns the status of the current touch input. Function DRV_TOUCH_POSITION_SINGLE DRV_MXT_TouchStatus( const SYS_MODULE_INDEX index ) c) Data Types and Constants Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1131 DRV_MXT_CLIENT_OBJECT Structure MXT Driver client object maintaining client data. File drv_mxt.h C typedef struct _DRV_MXT_CLIENT_OBJECT { DRV_MXT_OBJECT* driverObject; DRV_IO_INTENT intent; } DRV_MXT_CLIENT_OBJECT; Members Members Description DRV_MXT_OBJECT* driverObject; Driver Object associated with the client DRV_IO_INTENT intent; The intent with which the client was opened Description Structure DRV_MXT_CLIENT_OBJECT This defines the object required for the maintenance of the software clients instance. This object exists once per client instance. Remarks None. DRV_MXT_HANDLE Type Touch screen controller MXT driver handle. File drv_mxt.h C typedef uintptr_t DRV_MXT_HANDLE; Description MXT Driver Handle Touch controller MXT driver handle is a handle for the driver client object. Each driver with succesful open call will return a new handle to the client object. Remarks None. DRV_MXT_INIT Structure Defines the data required to initialize or reinitialize the MXT driver File drv_mxt.h C typedef struct { SYS_MODULE_INIT moduleInit; int mxtId; SYS_MODULE_OBJ (* drvInitialize)(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); SYS_MODULE_INDEX maxtouchID; uint16_t orientation; uint16_t horizontalResolution; uint16_t verticalResolution; } DRV_MXT_INIT; Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1132 Members Members Description SYS_MODULE_INIT moduleInit; System module initialization int mxtId; ID SYS_MODULE_OBJ (* drvInitialize)(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); initialize function for module (normally called statically SYS_MODULE_INDEX maxtouchID; index for the maxtouch driver instance used by this driver uint16_t orientation; Orientation of the display (given in degrees of 0,90,180,270) uint16_t horizontalResolution; Horizontal Resolution of the displayed orientation in Pixels Description Structure DRV_MXT_INIT This data type defines the data required to initialize or reinitialize the MXT driver. If the driver is built statically, the members of this data structure are statically over-ridden by static override definitions in the system_config.h file. Remarks None. DRV_MXT_MODULE_ID Enumeration Number of valid MXT driver indices. File drv_mxt.h C typedef enum { MXT_ID_1 = 0, MXT_NUMBER_OF_MODULES } DRV_MXT_MODULE_ID; Description Enumeration: DRV_MXT_MODULE_ID This constant identifies the number of valid MXT driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific header files defined as part of the peripheral libraries. DRV_MXT_OBJECT Structure Defines the data structure maintaining MXT driver instance object. File drv_mxt.h C typedef struct { SYS_STATUS status; int mxtId; SYS_MODULE_INDEX drvIndex; bool inUse; bool isExclusive; uint8_t numClients; uint16_t orientation; uint16_t horizontalResolution; uint16_t verticalResolution; int32_t readRequest; SYS_MODULE_INDEX maxtouchID; DRV_HANDLE hMaxtouch; DRV_HANDLE hMaxtouchGestureClient; DRV_TOUCH_POSITION_STATUS touchStatus; Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1133 bool maxtouchDataAvailable; uint8_t maxtouchData[32]; uint16_t xRange; uint16_t yRange; } DRV_MXT_OBJECT; Members Members Description SYS_STATUS status; The status of the driver int mxtId; The peripheral Id associated with the object SYS_MODULE_INDEX drvIndex; Save the index of the driver. Important to know this as we are using reference based accessing bool inUse; Flag to indicate instance in use bool isExclusive; Flag to indicate module used in exclusive access mode uint8_t numClients; Number of clients possible with the hardware instance uint16_t orientation; Orientation of the display (given in degrees of 0,90,180,270) uint16_t horizontalResolution; Horizontal Resolution of the displayed orientation in Pixels uint16_t verticalResolution; Vertical Resolution of the displayed orientaion in Pixels int32_t readRequest; Touch Input read request counter SYS_MODULE_INDEX maxtouchID; index of the maxtouch driver being used DRV_HANDLE hMaxtouch; handle for the maxtouch driver being used DRV_HANDLE hMaxtouchGestureClient; handle for the maxtouch driver object we are listening to DRV_TOUCH_POSITION_STATUS touchStatus; Touch status bool maxtouchDataAvailable; flag to indicate new maxtouch data is available uint8_t maxtouchData[32]; data from the maxtouch device Description Structure DRV_MXT_OBJECT This data structure maintains the MXT driver instance object. The object exists once per hardware instance. Remarks None. DRV_MXT_TASK_QUEUE Structure Defines the MXT Touch Controller driver task data structure. File drv_mxt.h C typedef struct { bool inUse; DRV_MXT_TASK_STATE taskState; DRV_I2C_BUFFER_HANDLE drvI2CReadBufferHandle; uint8_t drvI2CReadFrameData[DRV_MXT_I2C_READ_FRAME_SIZE]; } DRV_MXT_TASK_QUEUE; Members Members Description bool inUse; Flag denoting the allocation of task DRV_MXT_TASK_STATE taskState; Enum maintaining the task state DRV_I2C_BUFFER_HANDLE drvI2CReadBufferHandle; I2C Buffer handle Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1134 uint8_t drvI2CReadFrameData[DRV_MXT_I2C_READ_FRAME_SIZE]; Response to Read Touch Input Command • Response = { MXT Read Address, • Input Data Size, • Touch Id, Pen status, • Touch X coordinate (0 to 6), • Touch X coordinate (7 to 11), • Touch Y coordinate (0 to 6), • Touch Y coordinate (7 to 11) } Description Structure DRV_MXT_TASK_QUEUE This data type defines the data structure maintaing task context in the task queue. The inUse flag denotes the task context allocation for a task. The enum variable taskState maintains the current task state. The I2C buffer handle drvI2CReadBufferHandle maintains the I2C driver buffer handle returned by the I2C driver read request. The byte array variable drvI2CReadFrameData maintains the I2C frame data sent by MXT after a successful read request. Remarks None. DRV_MXT_TASK_STATE Enumeration Enumeration defining MXT touch controller driver task state. File drv_mxt.h C typedef enum { DRV_MXT_TASK_STATE_INIT = 0, DRV_MXT_TASK_STATE_READ_INPUT, DRV_MXT_TASK_STATE_DECODE_INPUT, DRV_MXT_TASK_STATE_DONE } DRV_MXT_TASK_STATE; Members Members Description DRV_MXT_TASK_STATE_INIT = 0 Task initialize state DRV_MXT_TASK_STATE_READ_INPUT Task read touch input request state DRV_MXT_TASK_STATE_DECODE_INPUT Task touch input decode state DRV_MXT_TASK_STATE_DONE Task complete state Description Enumeration DRV_MXT_TASK_STATE This enumeration defines the MXT touch controller driver task state. The task state helps to synchronize the operations of initialization the the task, adding the read input task to the task queue once the touch controller notifies the available touch input and a decoding the touch input received. Remarks None. DRV_MXT336T_CLIENT_CALLBACK Type Pointer to a MXT336T client callback function data type. File drv_mxt336t.h C typedef void (* DRV_MXT336T_CLIENT_CALLBACK)(DRV_HANDLE clientObject, DRV_MXT336T_OBJECT_CLIENT_EVENT_DATA *updateObject, uintptr_t context); Description MXT336T Driver Callback Function Pointer Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1135 This data type defines a pointer to a MXT336T client callback function. DRV_MXT336T_HANDLE Type Touch screen controller MXT336T driver handle. File drv_mxt336t.h C typedef uintptr_t DRV_MXT336T_HANDLE; Description MXT336T Driver Handle Touch controller MXT336T driver handle is a handle for the driver client object. Each driver with successful open call will return a new handle to the client object. Remarks None. DRV_MXT336T_INIT Type Defines the data required to initialize or reinitialize the MXT336T driver File drv_mxt336t.h C typedef struct DRV_MXT336T_INIT@2 DRV_MXT336T_INIT; Description Structure DRV_MXT336T_INIT This data type defines the data required to initialize or reinitialize the MXT336T driver. If the driver is built statically, the members of this data structure are statically over-ridden by static override definitions in the system_config.h file. Remarks None. DRV_MXT336T_OBJECT_CLIENT_EVENT_DATA Structure This structure maintains the information associated with each msg received or event that occurs File drv_mxt336t.h C typedef struct { uint8_t reportID; uint8_t dataSize; uint8_t * pData; uint16_t xRange; uint16_t yRange; } DRV_MXT336T_OBJECT_CLIENT_EVENT_DATA; Members Members Description uint8_t reportID; report ID within the object uint8_t dataSize; max size of data uint8_t * pData; data associated with the report Description Structure DRV_MXT336T_OBJECT_CLIENT_EVENT_DATA Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1136 This structure maintains the information associated with each msg received or event that occurs. Each msg gets a reportID that identifies the object reporting the change in status. For touch messages the xRange and yRange for the touch device gets reported and the data pointer contains the status msg information which has the touch type, touch event and touch coordinates. Remarks None. DRV_MXT336T_OBJECT_TYPE Enumeration The enum lists the different objects supported by the maxtouch device. File drv_mxt336t.h C typedef enum { DRV_MXT336T_OBJECT_RESERVED_T0 = 0, DRV_MXT336T_OBJECT_RESERVED_T1 = 1, DRV_MXT336T_OBJECT_DEBUG_DELTAS_T2 = 2, DRV_MXT336T_OBJECT_DEBUG_REFERENCES_T3 = 3, DRV_MXT336T_OBJECT_DEBUG_SIGNALS_T4 = 4, DRV_MXT336T_OBJECT_GEN_MESSAGEPROCESSOR_T5 = 5, DRV_MXT336T_OBJECT_GEN_COMMANDPROCESSOR_T6 = 6, DRV_MXT336T_OBJECT_GEN_POWERCONFIG_T7 = 7, DRV_MXT336T_OBJECT_GEN_ACQUISITIONCONFIG_T8 = 8, DRV_MXT336T_OBJECT_TOUCH_MULTITOUCHSCREEN_T9 = 9, DRV_MXT336T_OBJECT_TOUCH_SINGLETOUCHSCREEN_T10 = 10, DRV_MXT336T_OBJECT_TOUCH_XSLIDER_T11 = 11, DRV_MXT336T_OBJECT_TOUCH_YSLIDER_T12 = 12, DRV_MXT336T_OBJECT_TOUCH_XWHEEL_T13 = 13, DRV_MXT336T_OBJECT_TOUCH_YWHEEL_T14 = 14, DRV_MXT336T_OBJECT_TOUCH_KEYARRAY_T15 = 15, DRV_MXT336T_OBJECT_PROCG_SIGNALFILTER_T16 = 16, DRV_MXT336T_OBJECT_PROCI_LINEARIZATIONTABLE_T17 = 17, DRV_MXT336T_OBJECT_SPT_COMMSCONFIG_T18 = 18, DRV_MXT336T_OBJECT_SPT_GPIOPWM_T19 = 19, DRV_MXT336T_OBJECT_PROCI_GRIPFACESUPPRESSION_T20 = 20, DRV_MXT336T_OBJECT_RESERVED_T21 = 21, DRV_MXT336T_OBJECT_PROCG_NOISESUPPRESSION_T22 = 22, DRV_MXT336T_OBJECT_TOUCH_PROXIMITY_T23 = 23, DRV_MXT336T_OBJECT_PROCI_ONETOUCHGESTUREPROCESSOR_T24 = 24, DRV_MXT336T_OBJECT_SPT_SELFTEST_T25 = 25, DRV_MXT336T_OBJECT_DEBUG_CTERANGE_T26 = 26, DRV_MXT336T_OBJECT_PROCI_TWOTOUCHGESTUREPROCESSOR_T27 = 27, DRV_MXT336T_OBJECT_SPT_CTECONFIG_T28 = 28, DRV_MXT336T_OBJECT_SPT_GPI_T29 = 29, DRV_MXT336T_OBJECT_SPT_GATE_T30 = 30, DRV_MXT336T_OBJECT_TOUCH_KEYSET_T31 = 31, DRV_MXT336T_OBJECT_TOUCH_XSLIDERSET_T32 = 32, DRV_MXT336T_OBJECT_RESERVED_T33 = 33, DRV_MXT336T_OBJECT_GEN_MESSAGEBLOCK_T34 = 34, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T35 = 35, DRV_MXT336T_OBJECT_RESERVED_T36 = 36, DRV_MXT336T_OBJECT_DEBUG_DIAGNOSTIC_T37 = 37, DRV_MXT336T_OBJECT_SPT_USERDATA_T38 = 38, DRV_MXT336T_OBJECT_SPARE_T39 = 39, DRV_MXT336T_OBJECT_PROCI_GRIPSUPPRESSION_T40 = 40, DRV_MXT336T_OBJECT_PROCI_PALMSUPPRESSION_T41 = 41, DRV_MXT336T_OBJECT_PROCI_TOUCHSUPPRESSION_T42 = 42, DRV_MXT336T_OBJECT_SPT_DIGITIZER_T43 = 43, DRV_MXT336T_OBJECT_SPT_MESSAGECOUNT_T44 = 44, DRV_MXT336T_OBJECT_PROCI_VIRTUALKEY_T45 = 45, DRV_MXT336T_OBJECT_SPT_CTECONFIG_T46 = 46, DRV_MXT336T_OBJECT_PROCI_STYLUS_T47 = 47, DRV_MXT336T_OBJECT_PROCG_NOISESUPPRESSION_T48 = 48, DRV_MXT336T_OBJECT_GEN_DUALPULSE_T49 = 49, DRV_MXT336T_OBJECT_SPARE_T50 = 50, DRV_MXT336T_OBJECT_SPT_SONY_CUSTOM_T51 = 51, DRV_MXT336T_OBJECT_TOUCH_PROXKEY_T52 = 52, DRV_MXT336T_OBJECT_GEN_DATASOURCE_T53 = 53, DRV_MXT336T_OBJECT_PROCG_NOISESUPPRESSION_T54 = 54, DRV_MXT336T_OBJECT_PROCI_ADAPTIVETHRESHOLD_T55 = 55, Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1137 DRV_MXT336T_OBJECT_PROCI_SHIELDLESS_T56 = 56, DRV_MXT336T_OBJECT_PROCI_EXTRATOUCHSCREENDATA_T57 = 57, DRV_MXT336T_OBJECT_SPT_EXTRANOISESUPCTRLS_T58 = 58, DRV_MXT336T_OBJECT_SPT_FASTDRIFT_T59 = 59, DRV_MXT336T_OBJECT_SPT_TIMER_T61 = 61, DRV_MXT336T_OBJECT_PROCG_NOISESUPPRESSION_T62 = 62, DRV_MXT336T_OBJECT_PROCI_ACTIVESTYLUS_T63 = 63, DRV_MXT336T_OBJECT_SPT_REFERENCERELOAD_T64 = 64, DRV_MXT336T_OBJECT_PROCI_LENSBENDING_T65 = 65, DRV_MXT336T_OBJECT_SPT_GOLDENREFERENCES_T66 = 66, DRV_MXT336T_OBJECT_PROCI_CUSTOMGESTUREPROCESSOR_T67 = 67, DRV_MXT336T_OBJECT_SERIAL_DATA_COMMAND_T68 = 68, DRV_MXT336T_OBJECT_PROCI_PALMGESTUREPROCESSOR_T69 = 69, DRV_MXT336T_OBJECT_SPT_DYNAMICCONFIGURATIONCONTROLLER_T70 = 70, DRV_MXT336T_OBJECT_SPT_DYNAMICCONFIGURATIONCONTAINER_T71 = 71, DRV_MXT336T_OBJECT_PROCG_NOISESUPPRESSION_T72 = 72, DRV_MXT336T_OBJECT_PROCI_ZONEINDICATION_T73 = 73, DRV_MXT336T_OBJECT_PROCG_SIMPLEGESTUREPROCESSOR_T74 = 74, DRV_MXT336T_OBJECT_MOTION_SENSING_OBJECT_T75 = 75, DRV_MXT336T_OBJECT_PROCI_MOTION_GESTURES_T76 = 76, DRV_MXT336T_OBJECT_SPT_CTESCANCONFIG_T77 = 77, DRV_MXT336T_OBJECT_PROCI_GLOVEDETECTION_T78 = 78, DRV_MXT336T_OBJECT_SPT_TOUCHEVENTTRIGGER_T79 = 79, DRV_MXT336T_OBJECT_PROCI_RETRANSMISSIONCOMPENSATION_T80 = 80, DRV_MXT336T_OBJECT_PROCI_UNLOCKGESTURE_T81 = 81, DRV_MXT336T_OBJECT_SPT_NOISESUPEXTENSION_T82 = 82, DRV_MXT336T_OBJECT_ENVIRO_LIGHTSENSING_T83 = 83, DRV_MXT336T_OBJECT_PROCI_GESTUREPROCESSOR_T84 = 84, DRV_MXT336T_OBJECT_PEN_ACTIVESTYLUSPOWER_T85 = 85, DRV_MXT336T_OBJECT_PROCG_NOISESUPACTIVESTYLUS_T86 = 86, DRV_MXT336T_OBJECT_PEN_ACTIVESTYLUSDATA_T87 = 87, DRV_MXT336T_OBJECT_PEN_ACTIVESTYLUSRECEIVE_T88 = 88, DRV_MXT336T_OBJECT_PEN_ACTIVESTYLUSTRANSMIT_T89 = 89, DRV_MXT336T_OBJECT_PEN_ACTIVESTYLUSWINDOW_T90 = 90, DRV_MXT336T_OBJECT_DEBUG_CUSTOMDATACONFIG_T91 = 91, DRV_MXT336T_OBJECT_PROCI_SYMBOLGESTUREPROCESSOR_T92 = 92, DRV_MXT336T_OBJECT_PROCI_TOUCHSEQUENCELOGGER_T93 = 93, DRV_MXT336T_OBJECT_SPT_PTCCONFIG_T95 = 95, DRV_MXT336T_OBJECT_SPT_PTCTUNINGPARAMS_T96 = 96, DRV_MXT336T_OBJECT_TOUCH_PTCKEYS_T97 = 97, DRV_MXT336T_OBJECT_PROCG_PTCNOISESUPPRESSION_T98 = 98, DRV_MXT336T_OBJECT_PROCI_KEYGESTUREPROCESSOR_T99 = 99, DRV_MXT336T_OBJECT_TOUCH_MULTITOUCHSCREEN_T100 = 100, DRV_MXT336T_OBJECT_SPT_TOUCHSCREENHOVER_T101 = 101, DRV_MXT336T_OBJECT_SPT_SELFCAPHOVERCTECONFIG_T102 = 102, DRV_MXT336T_OBJECT_PROCI_SCHNOISESUPPRESSION_T103 = 103, DRV_MXT336T_OBJECT_SPT_AUXTOUCHCONFIG_T104 = 104, DRV_MXT336T_OBJECT_SPT_DRIVENPLATEHOVERCONFIG_T105 = 105, DRV_MXT336T_OBJECT_SPT_ACTIVESTYLUSMMBCONFIG_T106 = 106, DRV_MXT336T_OBJECT_PROCI_ACTIVESTYLUS_T107 = 107, DRV_MXT336T_OBJECT_PROCG_NOISESUPSELFCAP_T108 = 108, DRV_MXT336T_OBJECT_SPT_SELFCAPGLOBALCONFIG_T109 = 109, DRV_MXT336T_OBJECT_SPT_SELFCAPTUNINGPARAMS_T110 = 110, DRV_MXT336T_OBJECT_SPT_SELFCAPCONFIG_T111 = 111, DRV_MXT336T_OBJECT_PROCI_SELFCAPGRIPSUPPRESSION_T112 = 112, DRV_MXT336T_OBJECT_SPT_PROXMEASURECONFIG_T113 = 113, DRV_MXT336T_OBJECT_SPT_ACTIVESTYLUSMEASCONFIG_T114 = 114, DRV_MXT336T_OBJECT_PROCI_SYMBOLGESTURE_T115 = 115, DRV_MXT336T_OBJECT_SPT_SYMBOLGESTURECONFIG_T116 = 116, DRV_MXT336T_OBJECT_GEN_INFOBLOCK16BIT_T254 = 254, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T220 = 220, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T221 = 221, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T222 = 222, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T223 = 223, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T224 = 224, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T225 = 225, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T226 = 226, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T227 = 227, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T228 = 228, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T229 = 229, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T230 = 230, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T231 = 231, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T232 = 232, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T233 = 233, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T234 = 234, Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1138 DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T235 = 235, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T236 = 236, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T237 = 237, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T238 = 238, DRV_MXT336T_OBJECT_SPT_PROTOTYPE_T239 = 239, DRV_MXT336T_OBJECT_RESERVED_T255 = 255 } DRV_MXT336T_OBJECT_TYPE; Description Enumeration DRV_MXT336T_OBJECT_TYPE The MAxtouch devices follow a Object protocol for their driver implementation. This makes it possible to implement a generic driver for many maxtouch devices. The device communicates the different properties or status like touch messages etc with the driver through an Object table. The different types of objects associated with the maxtouch device are listed in the enum below. Remarks None. DRV_MXT_HANDLE_INVALID Macro Definition of an invalid handle. File drv_mxt.h C #define DRV_MXT_HANDLE_INVALID ((DRV_MXT_HANDLE)(-1)) Description MXT Driver Invalid Handle This is the definition of an invalid handle. An invalid handle is is returned by DRV_MXT_Open() and DRV_MXT_Close() functions if the request was not successful. Remarks None. _DRV_MXT336T_H Macro File drv_mxt336t.h C #define _DRV_MXT336T_H Description This is macro _DRV_MXT336T_H. DRV_MXT_I2C_MASTER_READ_ID Macro MXT input read, I2C address from where master reads touch input data. File drv_mxt.h C #define DRV_MXT_I2C_MASTER_READ_ID 0x4B Description MXT Driver Module Master Input Read I2C address This constant defines the MXT touch input read I2C address. This address is used as I2C address to read Touch input from MXT Touch controller. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific data sheets. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1139 DRV_MXT_I2C_MASTER_WRITE_ID Macro MXT command register write, I2C address where master sends the commands. File drv_mxt.h C #define DRV_MXT_I2C_MASTER_WRITE_ID 0x4A Description MXT Driver Module Master Command Write I2C Address This constant defines the MXT command register I2C write address. This address is used as I2C address to write commands into MXT Touch controller register. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific data sheets. DRV_MXT_I2C_READ_FRAME_SIZE Macro I2C Frame size for reading MXT touch input. File drv_mxt.h C #define DRV_MXT_I2C_READ_FRAME_SIZE 7 Description MXT Driver Module I2C Frame Size This constant identifies the size of I2C frame required to read from MXT touch controller. MXT notifies the availability of input data through interrupt pin. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific data sheets. DRV_MXT_INDEX_0 Macro MXT driver index definitions. File drv_mxt.h C #define DRV_MXT_INDEX_0 0 Description MXT Driver Module Index Numbers These constants provide the MXT driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_MXT_Initialize and DRV_MXT_Open functions to identify the driver instance in use. DRV_MXT_INDEX_1 Macro File drv_mxt.h Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1140 C #define DRV_MXT_INDEX_1 1 Description This is macro DRV_MXT_INDEX_1. DRV_MXT_INDEX_COUNT Macro Number of valid Touch controller MXT driver indices. File drv_mxt.h C #define DRV_MXT_INDEX_COUNT 2 Description MXT Driver Module Index Count This constant identifies the number of valid Touch Controller MXT driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific header files defined as part of the peripheral libraries. DRV_MXT336T_HANDLE_INVALID Macro Definition of an invalid handle. File drv_mxt336t.h C #define DRV_MXT336T_HANDLE_INVALID ((DRV_MXT336T_HANDLE)(-1)) Description MXT336T Driver Invalid Handle This is the definition of an invalid handle. An invalid handle is is returned by DRV_MXT336T_Open() and DRV_MXT336T_Close() functions if the request was not successful. Remarks None. DRV_MXT336T_I2C_FRAME_SIZE Macro I2C Frame size for reading MXT336T touch input. File drv_mxt336t.h C #define DRV_MXT336T_I2C_FRAME_SIZE 32 Description MXT336T Driver Module I2C Frame Size This constant identifies the size of I2C frame required to read from MXT336T touch controller. MXT336T notifies the availability of input data through interrupt pin. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific data sheets. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1141 DRV_MXT336T_I2C_MASTER_READ_ID Macro MXT336T input read, I2C address from where master reads touch input data. File drv_mxt336t.h C #define DRV_MXT336T_I2C_MASTER_READ_ID 0x95 Description MXT336T Driver Module Master Input Read I2C address This constant defines the MXT336T touch input read I2C address. This address is used as I2C address to read Touch input from MXT336T Touch controller. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific data sheets. DRV_MXT336T_I2C_MASTER_WRITE_ID Macro MXT336T command register write, I2C address where master sends the commands. File drv_mxt336t.h C #define DRV_MXT336T_I2C_MASTER_WRITE_ID 0x94 Description MXT336T Driver Module Master Command Write I2C Address This constant defines the MXT336T command register I2C write address. This address is used as I2C address to write commands into MXT336T Touch controller register. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific data sheets. DRV_MXT336T_I2C_READ_ID_FRAME_SIZE Macro File drv_mxt336t.h C #define DRV_MXT336T_I2C_READ_ID_FRAME_SIZE 8 Description This is macro DRV_MXT336T_I2C_READ_ID_FRAME_SIZE. DRV_MXT336T_INDEX_0 Macro MXT336T driver index definitions. File drv_mxt336t.h C #define DRV_MXT336T_INDEX_0 0 Description MXT336T Driver Module Index Numbers Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1142 These constants provide the MXT336T driver index definitions. Remarks These constants should be used in place of hard-coded numeric literals. These values should be passed into the DRV_MXT336T_Initialize and DRV_MXT336T_Open functions to identify the driver instance in use. DRV_MXT336T_INDEX_1 Macro File drv_mxt336t.h C #define DRV_MXT336T_INDEX_1 1 Description This is macro DRV_MXT336T_INDEX_1. DRV_MXT336T_INDEX_COUNT Macro Number of valid Touch controller MXT336T driver indices. File drv_mxt336t.h C #define DRV_MXT336T_INDEX_COUNT 2 Description MXT336T Driver Module Index Count This constant identifies the number of valid Touch Controller MXT336T driver indices. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific header files defined as part of the peripheral libraries. t100_event Enumeration Types of touch events reported by the Maxtouch Multi touch object File drv_mxt.h C enum t100_event { MXT_T100_EVENT_NO_EVENT = 0, MXT_T100_EVENT_MOVE = 1, MXT_T100_EVENT_UNSUP = 2, MXT_T100_EVENT_SUP = 3, MXT_T100_EVENT_DOWN = 4, MXT_T100_EVENT_UP = 5, MXT_T100_EVENT_UNSUPSUP = 6, MXT_T100_EVENT_UNSUPUP = 7, MXT_T100_EVENT_DOWNSUP = 8, MXT_T100_EVENT_DOWNUP = 9 }; Description Enumeration: t100_event The maxtouch multi touch object DRV_MXT336T_OBJECT_TOUCH_MULTITOUCHSCREEN_T100 return a number of different types of touch events. Each touch event has a return type associated with it. These are listed in this enum. These events are returned in the touch status message associated with the multi touch object. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1143 t100_type Enumeration Types of touch types reported by the Maxtouch Multi touch object File drv_mxt.h C enum t100_type { MXT_T100_TYPE_FINGER = 1, MXT_T100_TYPE_PASSIVE_STYLUS = 2, MXT_T100_TYPE_ACTIVE_STYLUS = 3, MXT_T100_TYPE_HOVERING_FINGER = 4, MXT_T100_TYPE_GLOVE = 5, MXT_T100_TYPE_LARGE_TOUCH = 6 }; Description Enumeration: t100_type The maxtouch multi touch object DRV_MXT336T_OBJECT_TOUCH_MULTITOUCHSCREEN_T100 return a number of different types of touch types. These are listed in this enum. The touch type is returned in the touch status message associated with the multi touch object. Remarks None. DRV_MXT336T_T100_XRANGE Macro MXT336T Driver Object Register Adresses for the registers being read in the driver File drv_mxt336t.h C #define DRV_MXT336T_T100_XRANGE 13 Description MXT336T Driver Object Register Adresses for the registers being read in the driver MXT336T Objects have different registers that contain certain values regarding display resoltuion etc. These register addresses are used to read the values from object tables. Remarks This constant should be used in place of hard-coded numeric literals. This value is derived from device-specific protocol guides. DRV_MXT336T_T100_YRANGE Macro File drv_mxt336t.h C #define DRV_MXT336T_T100_YRANGE 24 Description This is macro DRV_MXT336T_T100_YRANGE. Files Files Name Description drv_mxt.h Touch controller MXT Driver interface header file. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1144 drv_mxt336t.h Touch controller MXT336T Driver interface header file. Description drv_mxt.h Touch controller MXT Driver interface header file. Enumerations Name Description t100_event Types of touch events reported by the Maxtouch Multi touch object t100_type Types of touch types reported by the Maxtouch Multi touch object DRV_MXT_MODULE_ID Number of valid MXT driver indices. DRV_MXT_TASK_STATE Enumeration defining MXT touch controller driver task state. Functions Name Description DRV_MXT_Close Closes an opened instance of the MXT driver. Implementation: Dynamic DRV_MXT_Deinitialize Deinitializes the specified instance of the MXT driver module. Implementation: Dynamic DRV_MXT_Initialize Initializes the MXT instance for the specified driver index. Implementation: Dynamic DRV_MXT_MaxtouchEventCallback DRV_MXT_Open Opens the specified MXT driver instance and returns a handle to it. Implementation: Dynamic DRV_MXT_ReadRequest Sends a read request to I2C bus driver and adds the read task to queue. Implementation: Dynamic DRV_MXT_Status Provides the current status of the MXT driver module. Implementation: Dynamic DRV_MXT_Tasks Maintains the driver's state machine and implements its task queue processing. Implementation: Dynamic DRV_MXT_TouchDataRead Notifies the driver that the current touch data has been read DRV_MXT_TouchGetX Returns the x coordinate of touch input. Implementation: Dynamic DRV_MXT_TouchGetY Returns the y coordinate of touch input. Implementation: Dynamic DRV_MXT_TouchStatus Returns the status of the current touch input. Macros Name Description DRV_MXT_HANDLE_INVALID Definition of an invalid handle. DRV_MXT_I2C_MASTER_READ_ID MXT input read, I2C address from where master reads touch input data. DRV_MXT_I2C_MASTER_WRITE_ID MXT command register write, I2C address where master sends the commands. DRV_MXT_I2C_READ_FRAME_SIZE I2C Frame size for reading MXT touch input. DRV_MXT_INDEX_0 MXT driver index definitions. DRV_MXT_INDEX_1 This is macro DRV_MXT_INDEX_1. DRV_MXT_INDEX_COUNT Number of valid Touch controller MXT driver indices. Structures Name Description _DRV_MXT_CLIENT_OBJECT MXT Driver client object maintaining client data. DRV_MXT_CLIENT_OBJECT MXT Driver client object maintaining client data. DRV_MXT_INIT Defines the data required to initialize or reinitialize the MXT driver DRV_MXT_OBJECT Defines the data structure maintaining MXT driver instance object. DRV_MXT_TASK_QUEUE Defines the MXT Touch Controller driver task data structure. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1145 Types Name Description DRV_MXT_HANDLE Touch screen controller MXT driver handle. Description Touch Controller MXT Driver Interface File This header file describes the macros, data structure and prototypes of the touch controller MXT driver interface. File Name drv_MXT.c drv_mxt336t.h Touch controller MXT336T Driver interface header file. Enumerations Name Description DRV_MXT336T_OBJECT_TYPE The enum lists the different objects supported by the maxtouch device. Functions Name Description DRV_MXT336T_Close Closes an opened instance of the MXT336T driver. Implementation: Dynamic DRV_MXT336T_CloseObject Closes an opened instance of the MXT336T client object DRV_MXT336T_Deinitialize Deinitializes the specified instance of the MXT336T driver module. Implementation: Dynamic DRV_MXT336T_DEVICE_ClientObjectEventHandlerSet Sets the event handler for a MXT336T client object DRV_MXT336T_Initialize Initializes the MXT336T instance for the specified driver index DRV_MXT336T_Open Opens the specified MXT336T driver instance and returns a handle to it. Implementation: Dynamic DRV_MXT336T_OpenObject Opens the specified MXT336T object driver instance and returns a handle to it. Implementation: Dynamic DRV_MXT336T_ReadRequest Sends a read request to I2C bus driver and adds the read task to queue. Implementation: Dynamic DRV_MXT336T_Status Provides the current status of the MXT336T driver module. Implementation: Dynamic DRV_MXT336T_Tasks Maintains the driver's state machine and implements its task queue processing. Implementation: Dynamic Macros Name Description _DRV_MXT336T_H This is macro _DRV_MXT336T_H. DRV_MXT336T_HANDLE_INVALID Definition of an invalid handle. DRV_MXT336T_I2C_FRAME_SIZE I2C Frame size for reading MXT336T touch input. DRV_MXT336T_I2C_MASTER_READ_ID MXT336T input read, I2C address from where master reads touch input data. DRV_MXT336T_I2C_MASTER_WRITE_ID MXT336T command register write, I2C address where master sends the commands. DRV_MXT336T_I2C_READ_ID_FRAME_SIZE This is macro DRV_MXT336T_I2C_READ_ID_FRAME_SIZE. DRV_MXT336T_INDEX_0 MXT336T driver index definitions. DRV_MXT336T_INDEX_1 This is macro DRV_MXT336T_INDEX_1. DRV_MXT336T_INDEX_COUNT Number of valid Touch controller MXT336T driver indices. DRV_MXT336T_T100_XRANGE MXT336T Driver Object Register Adresses for the registers being read in the driver DRV_MXT336T_T100_YRANGE This is macro DRV_MXT336T_T100_YRANGE. Volume V: MPLAB Harmony Framework Driver Libraries Help Touch Driver Libraries Help © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1146 Structures Name Description DRV_MXT336T_OBJECT_CLIENT_EVENT_DATA This structure maintains the information associated with each msg received or event that occurs Types Name Description DRV_MXT336T_CLIENT_CALLBACK Pointer to a MXT336T client callback function data type. DRV_MXT336T_HANDLE Touch screen controller MXT336T driver handle. DRV_MXT336T_INIT Defines the data required to initialize or reinitialize the MXT336T driver Description Touch Controller MXT336T Driver Interface File This header file describes the macros, data structure and prototypes of the touch controller MXT336T driver interface. File Name drv_MXT336T.c USB Driver Libraries Common Interface Provides information on the USB Driver interface that is common to all PIC32 devices. Description The USB Driver Common Interface definition specifies the functions and their behavior that a USB Driver must implement so that the driver can be used by the MPLAB Harmony USB Host and Device Stack. Note: The MPLAB Harmony USB Driver for PIC32MX and PIC32MZ devices implements the USB Driver Common Interface. The USB Driver Common Interface contains functions that are grouped as follows: • Driver System Functions - These functions are called by MPLAB Harmony to initialize and maintain the operational state of the USB Driver. The system functions can vary between different PIC32 device USB Drivers. As such, the USB Driver Common Interface does not require these functions to be of the same type. These functions are not called by the USB Host or Device Stack and therefore are allowed to (and can) vary across different PIC32 device USB Drivers. A description of these functions, along with a description of how to initialize the USB Driver for Host, Device or Dual Role operation, is provided in the specific PIC32 device USB Driver help section (see PIC32MX USB Driver and PIC32MZ USB Driver). • Driver General Client Functions -These functions are called by the USB Host or Device Stack to gain access to the driver • Driver Host Mode Client Functions - These functions are called exclusively by the USB Host Stack to operate and access the USB as a Host • Driver Device Mode Client Functions - These functions are called exclusively by the USB Device Stack to operate and access the USB as a Device The USB Driver Common Interface is defined in the \framework\driver\usb\drv_usb.h file. This file contains the data types and structures that define the interface. Specifically, the DRV_USB_HOST_INTERFACE structure, contained in this file, is the common interface for USB Driver Host mode functions. It is a structure of function pointers, pointing to functions that define the Driver Host mode Client functions. The following code example shows this structure and the function pointer it contains. // ***************************************************************************** /* USB Driver Client Functions Interface (For Host mode) Summary: Group of function pointers to the USB Driver Host mode Client Functions. Description: This structure is a group of function pointers pointing to the USB Driver Host mode Client routines. The USB Driver should export this group of functions so that the Host layer can access the driver functionality. Remarks: None. */ Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1147 typedef struct { /* This is a pointer to the driver Open function. This function may be * called twice in a Dual Role application, once by the Host Stack and then * by the Device Stack */ DRV_HANDLE (*open)(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); /* This is pointer to the driver Close function */ void (*close)(DRV_HANDLE handle); /* This is a pointer to the event call back set function */ void (*eventHandlerSet)(DRV_HANDLE handle, uintptr_t hReferenceData, DRV_USB_EVENT_CALLBACK eventHandler); /* This is a pointer to the Host IRP submit function */ USB_ERROR (*hostIRPSubmit)(DRV_USB_HOST_PIPE_HANDLE pipeHandle, USB_HOST_IRP * irp); /* This is a pointer to the Host IRP Cancel all function */ void (*hostIRPCancel)(USB_HOST_IRP * irp); /* This is pointer to the Host event disable function */ bool (*hostEventsDisable)(DRV_HANDLE handle); /* This is a pointer to the Host event enable function */ void (*hostEventsEnable)(DRV_HANDLE handle, bool eventContext); /* This is a pointer to the Host pipe setup function */ DRV_USB_HOST_PIPE_HANDLE (*hostPipeSetup) ( DRV_HANDLE client, uint8_t deviceAddress, USB_ENDPOINT endpointAndDirection, uint8_t hubAddress, uint8_t hubPort, USB_TRANSFER_TYPE pipeType, uint8_t bInterval, uint16_t wMaxPacketSize, USB_SPEED speed ); /* This is a pointer to the Host Pipe Close function */ void (*hostPipeClose)(DRV_USB_HOST_PIPE_HANDLE pipeHandle); /* This is a pointer to the Host Root Hub functions */ DRV_USB_ROOT_HUB_INTERFACE rootHubInterface; } DRV_USB_HOST_INTERFACE; The DRV_USB_DEVICE_INTERFACE structure, contained in this file, is the common interface for USB Driver Device mode functions. It is a structure of function pointers, pointer to functions that define the Driver Device mode Client functions. The following code example shows this structure and the function pointer it contains. // ***************************************************************************** /* USB Driver Client Functions Interface (For Device Mode) Summary: Group of function pointers to the USB Driver Device Mode Client Functions. Description: This structure is a group of function pointers pointing to the USB Driver Device Mode Client routines. The USB Driver should export this group of functions so that the Device Layer can access the driver functionality. Remarks: None. */ typedef struct { /* This is a pointer to the driver Open function */ DRV_HANDLE (*open)(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1148 /* This is pointer to the driver Close function */ void (*close)(DRV_HANDLE handle); /* This is a pointer to the event call back set function */ void (*eventHandlerSet)(DRV_HANDLE handle, uintptr_t hReferenceData, DRV_USB_EVENT_CALLBACK eventHandler); /* This is a pointer to the device address set function */ void (*deviceAddressSet)(DRV_HANDLE handle, uint8_t address); /* This is a pointer to the device current speed get function */ USB_SPEED (*deviceCurrentSpeedGet)(DRV_HANDLE handle); /* This is a pointer to the SOF Number get function */ uint16_t (*deviceSOFNumberGet)(DRV_HANDLE handle); /* This is a pointer to the device attach function */ void (*deviceAttach)(DRV_HANDLE handle); /* This is a pointer to the device detach function */ void (*deviceDetach)(DRV_HANDLE handle); /* This is a pointer to the device endpoint enable function */ USB_ERROR (*deviceEndpointEnable)(DRV_HANDLE handle, USB_ENDPOINT endpoint, USB_TRANSFER_TYPE transferType, uint16_t endpointSize); /* This is a pointer to the device endpoint disable function */ USB_ERROR (*deviceEndpointDisable)(DRV_HANDLE handle, USB_ENDPOINT endpoint); /* This is a pointer to the device endpoint stall function */ USB_ERROR (*deviceEndpointStall)(DRV_HANDLE handle, USB_ENDPOINT endpoint); /* This is a pointer to the device endpoint stall clear function */ USB_ERROR (*deviceEndpointStallClear)(DRV_HANDLE handle, USB_ENDPOINT endpoint); /* This is pointer to the device endpoint enable status query function */ bool (*deviceEndpointIsEnabled)(DRV_HANDLE handle, USB_ENDPOINT endpoint); /* This is pointer to the device endpoint stall status query function */ bool (*deviceEndpointIsStalled)(DRV_HANDLE handle, USB_ENDPOINT endpoint); /* This is a pointer to the device IRP submit function */ USB_ERROR (*deviceIRPSubmit)(DRV_HANDLE handle, USB_ENDPOINT endpoint, USB_DEVICE_IRP * irp); /* This is a pointer to the device IRP Cancel all function */ USB_ERROR (*deviceIRPCancelAll)(DRV_HANDLE handle, USB_ENDPOINT endpoint); /* This is a pointer to the device remote wakeup start function */ void (*deviceRemoteWakeupStart)(DRV_HANDLE handle); /* This is a pointer to the device remote wakeup stop function */ void (*deviceRemoteWakeupStop)(DRV_HANDLE handle); /* This is a pointer to the device Test mode enter function */ USB_ERROR (*deviceTestModeEnter)(DRV_HANDLE handle, USB_TEST_MODE_SELECTORS testMode); } DRV_USB_DEVICE_INTERFACE; Both of these structures also contain pointers to General Client functions. The specific PIC32 device USB Driver allocates and initializes such a structure. The following code example shows how the PIC32MX USB Host mode Driver allocates and initializes the DRV_USB_HOST_INTERFACE structure. This code is contained in the \framework\driver\usb\usbhs\src\dynamic\drv_usbfs_host.c file. /********************************************************** * This structure is a set of pointer to the USBFS driver * functions. It is provided to the Host layer as the * interface to the driver. * *******************************************************/ Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1149 DRV_USB_HOST_INTERFACE gDrvUSBFSHostInterface = { .open = DRV_USBFS_Open, .close = DRV_USBFS_Close, .eventHandlerSet = DRV_USBFS_ClientEventCallBackSet, .hostIRPSubmit = DRV_USBFS_HOST_IRPSubmit, .hostIRPCancel = DRV_USBFS_HOST_IRPCancel, .hostPipeSetup = DRV_USBFS_HOST_PipeSetup, .hostPipeClose = DRV_USBFS_HOST_PipeClose, .hostEventsDisable = DRV_USBFS_HOST_EventsDisable, .hostEventsEnable = DRV_USBFS_HOST_EventsEnable, .rootHubInterface.rootHubPortInterface.hubPortReset = DRV_USBFS_HOST_ROOT_HUB_PortReset, .rootHubInterface.rootHubPortInterface.hubPortSpeedGet = DRV_USBFS_HOST_ROOT_HUB_PortSpeedGet, .rootHubInterface.rootHubPortInterface.hubPortResetIsComplete = DRV_USBFS_HOST_ROOT_HUB_PortResetIsComplete, .rootHubInterface.rootHubPortInterface.hubPortSuspend = DRV_USBFS_HOST_ROOT_HUB_PortSuspend, .rootHubInterface.rootHubPortInterface.hubPortResume = DRV_USBFS_HOST_ROOT_HUB_PortResume, .rootHubInterface.rootHubMaxCurrentGet = DRV_USBFS_HOST_ROOT_HUB_MaximumCurrentGet, .rootHubInterface.rootHubPortNumbersGet = DRV_USBFS_HOST_ROOT_HUB_PortNumbersGet, .rootHubInterface.rootHubSpeedGet = DRV_USBFS_HOST_ROOT_HUB_BusSpeedGet, .rootHubInterface.rootHubInitialize = DRV_USBFS_HOST_ROOT_HUB_Initialize, .rootHubInterface.rootHubOperationEnable = DRV_USBFS_HOST_ROOT_HUB_OperationEnable, .rootHubInterface.rootHubOperationIsEnabled = DRV_USBFS_HOST_ROOT_HUB_OperationIsEnabled, }; Similarly, the PIC32MX USB Device mode Driver allocates and initializes the DRV_USB_DEVICE_INTERFACE structure. This can be reviewed in the \framework\driver\usb\usbhs\src\dynamic\drv_usbfs_device.c file. /***************************************************** * This structure is a pointer to a set of USB Driver * Device mode functions. This set is exported to the * Device Layer when the Device Layer must use the * PIC32MX USB Controller. ******************************************************/ DRV_USB_DEVICE_INTERFACE gDrvUSBFSDeviceInterface = { .open = DRV_USBFS_Open, .close = DRV_USBFS_Close, .eventHandlerSet = DRV_USBFS_ClientEventCallBackSet, .deviceAddressSet = DRV_USBFS_DEVICE_AddressSet, .deviceCurrentSpeedGet = DRV_USBFS_DEVICE_CurrentSpeedGet, .deviceSOFNumberGet = DRV_USBFS_DEVICE_SOFNumberGet, .deviceAttach = DRV_USBFS_DEVICE_Attach, .deviceDetach = DRV_USBFS_DEVICE_Detach, .deviceEndpointEnable = DRV_USBFS_DEVICE_EndpointEnable, .deviceEndpointDisable = DRV_USBFS_DEVICE_EndpointDisable, .deviceEndpointStall = DRV_USBFS_DEVICE_EndpointStall, .deviceEndpointStallClear = DRV_USBFS_DEVICE_EndpointStallClear, .deviceEndpointIsEnabled = DRV_USBFS_DEVICE_EndpointIsEnabled, .deviceEndpointIsStalled = DRV_USBFS_DEVICE_EndpointIsStalled, .deviceIRPSubmit = DRV_USBFS_DEVICE_IRPSubmit, .deviceIRPCancelAll = DRV_USBFS_DEVICE_IRPCancelAll, .deviceRemoteWakeupStop = DRV_USBFS_DEVICE_RemoteWakeupStop, .deviceRemoteWakeupStart = DRV_USBFS_DEVICE_RemoteWakeupStart, .deviceTestModeEnter = NULL }; A pointer to the DRV_USB_HOST_INTERFACE structure is passed to the USB Host Stack as part of USB Host Stack initialization. The following code example shows how this is done. /******************************************************************************** * This is a table of the USB Host mode drivers that this application will * support. Also contained in the driver index. In this example, the * application will want to use instance 0 of the PIC32MX USB Full-Speed driver. * *****************************************************************************/ const USB_HOST_HCD hcdTable = { .drvIndex = DRV_USBFS_INDEX_0, Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1150 .hcdInterface = DRV_USBFS_HOST_INTERFACE }; /* Here the pointer to the USB Driver Common Interface is provided to the USB * Host Layer via the hostControllerDrivers member of the Host Layer * Initialization data structure. */ const USB_HOST_INIT usbHostInitData = { .nTPLEntries = 1 , .tplList = (USB_HOST_TPL_ENTRY *)USBTPList, .hostControllerDrivers = (USB_HOST_HCD *)&hcdTable }; A pointer to the DRV_USB_DEVICE_INTERFACE structure is passed to the USB Device Stack as part of the USB Device Stack initialization. The Host Stack and Device Stack then access the driver functions through the function pointers contained in these structures. The Driver General Client, Host mode and Device mode Client functions are described in this section. Any references to a USB Driver Client in the following sections, implies the client is a USB Host Stack and/or the USB Device Stack. Driver General Client Functions Provides information on the General Client functions for the USB Driver. Description The DRV_USB_HOST_INTERFACE and the DRV_USB_DEVICE_INTERFACE structures contain pointers to the USB Driver’s General Client functions. These functions are not specific to the operation mode (Host, Device, or Dual Role) of the driver. A USB Driver must implement these functions and ensure that the Host or Device Stack can access these functions through the driver’s common interface structures. The common interface contains three general client functions: • Driver Open Function • Driver Close Function • Driver Event Handler Set Function Driver Open Function The open member of the DRV_USB_HOST_INTERFACE and the DRV_USB_DEVICE_INTERFACE structures should point to the USB Driver Open function. The signature of the Open function is as follows: DRV_HANDLE (*open)(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); The USB Driver Open function must match this signature. The Driver Client uses the USB Driver index (drvIndex) to specify the instance of the USB module that Host Stack or the Device Stack should open. The USB Driver should ignore the intent parameter. The function should return a driver handle. If the driver is not ready to be opened, it should return an invalid handle (DRV_HANDLE_INVALID). In such a case, the client will continue trying to open the driver by calling the Open function again. The driver may also fail to open for an invalid index parameter or if USB module is in an error condition. When supporting Dual Role operation, both the Host Stack and Device Stack will call the Driver Open function in one application. The USB Driver must support multiple calls to the Open function in the same application. The Open function should be thread-safe. Driver Close Function The close member of the DRV_USB_HOST_INTERFACE and the DRV_USB_DEVICE_INTERFACE structures should point to the USB Driver Close function. The signature of the Close function is as follows: void (*close)(DRV_HANDLE handle); The USB Driver Close function must match this signature. The Driver Client passes the handle obtained from the Driver Open function as a parameter to the close. The USB Host Stack or USB Device Stack will close the driver only when the stack is deinitialized (which is typically a rare case). The USB Driver should deallocate any client-related resources in the Close function. If the specified driver handle is not valid, the Close function should not have any side effects. The USB Driver expects the Close function to be called from the context of the thread in which the driver was opened; therefore, this function is not expected to be thread-safe. Driver Event Handler Set Function The eventHandlerSet member of the DRV_USB_HOST_INTERFACE and the DRV_USB_DEVICE_INTERFACE structures should point to the USB Driver Event Handler Set function. The signature of the Event Handler Set function is as follows: void (*eventHandlerSet)(DRV_HANDLE handle, uintptr_t hReferenceData, DRV_USB_EVENT_CALLBACK eventHandler); The USB Driver Event Handler Set function must match this signature. The signature of the Client Event Handling function should match DRV_USB_EVENT_CALLBACK. The USB Driver calls this function when it must communicate USB events to the client. The client can set the eventHandler parameter to NULL if it does not want to receive USB Driver events. The client will receive Host mode events if the USB Driver is operating in Host mode. It will receive Device mode events if the USB Driver is operating in Device mode. The DRV_USB_EVENT type enumeration contains all the possible events that the USB Driver would generate. The following code example shows the enumeration. // ***************************************************************************** /* USB Driver Events Enumeration Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1151 Summary: Identifies the different events that the USB Driver provides. Description: Identifies the different events that the USB Driver provides. The USB Driver should be able to provide these events. Remarks: None. */ typedef enum { /* Bus error occurred and was reported. This event can be generated in both * Host and Device mode. */ DRV_USB_EVENT_ERROR = 1, /* Host has issued a device Reset. This event occurs only in Device mode */ DRV_USB_EVENT_RESET_DETECT, /* Resume detected while USB in suspend mode. This event can be generated in * both Host and Device mode. In Host mode, the events occurs when a remote * wakeup capable device has generated resume signaling. In Device mode, * this event will occur when the Host has issued resume signaling. */ DRV_USB_EVENT_RESUME_DETECT, /* This event is generated in Device mode only. It occurs when the Host * suspends the bus and the bus goes idle. */ DRV_USB_EVENT_IDLE_DETECT, /* This event is generated in Host mode and Device mode. In Host mode, this * event occurs when the device has stalled the Host. In Device mode, this * event occurs when the Host has accessed a stalled endpoint thus * triggering the device to send a STALL to the Host. */ DRV_USB_EVENT_STALL, /* This event is generated in Host mode and Device mode. In Device mode, * this event occurs when a SOF has been generated by the Host. In Host * mode, this event occurs when controller is about to generate an SOF. * */ DRV_USB_EVENT_SOF_DETECT, /* This event is generated in Device mode when the VBUS voltage is above * VBUS session valid. */ DRV_USB_EVENT_DEVICE_SESSION_VALID, /* This event is generated in Device mode when the VBUS voltage falls * below VBUS session valid. */ DRV_USB_EVENT_DEVICE_SESSION_INVALID, } DRV_USB_EVENT; This completes the discussion on the Driver General Client Functions. Driver Host Mode Client Functions Provides information on the Host mode Client functions for the USB Driver. Description The DRV_USB_HOST_INTERFACE structure contains pointers to the USB Driver’s Host mode Client functions. These functions are only applicable when the USB module is operating as a USB Host. Along with the function pointers to the driver’s Host mode specific functions, the DRV_USB_HOST_INTERFACE structure also contains another structure of function pointers of the type DRV_USB_ROOT_HUB_INTERFACE. This structure contains function pointers to the USB Driver’s Root Hub functions. A USB Driver must implement these functions and ensure that the Host Stack can access these functions through the driver’s DRV_USB_HOST_INTERFACE structure. The Driver Host mode Client functions in the DRV_USB_HOST_INTERFACE structure are: • Driver Host Pipe Setup Function • Driver Host Pipe Close Function Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1152 • Driver Host Events Disable Function • Driver Host Events Enable Function • Driver Host IRP Submit Function • Driver Host IRP Cancel Function Driver Host Pipe Setup Function The hostPipeSetup member of the DRV_USB_HOST_INTERFACE structure should point to the USB Driver Host Pipe Setup function. The signature of the Host Pipe Setup function is as follows: DRV_USB_HOST_PIPE_HANDLE (*hostPipeSetup) ( DRV_HANDLE client, uint8_t deviceAddress, USB_ENDPOINT endpointAndDirection, uint8_t hubAddress, uint8_t hubPort, USB_TRANSFER_TYPE pipeType, uint8_t bInterval, uint16_t wMaxPacketSize, USB_SPEED speed); The USB Driver Host mode Pipe Setup function must match this signature. The USB Host Stack calls this function to create a communication pipe to the attached device. The function parameters define the property of this communication pipe. The driverHandle parameter is the handle to the driver obtained through the driver Open function. The deviceAddress and the endpointAddress parameters specify the address of the USB device and the endpoint on this device to which this pipe must connect. If the device is connected to the Host though a hub, hubAddress and hubPort must specify the address of the hub and port to which the device is connected. The USB Driver will use these parameters to schedule split transactions if the target device is a Low-Speed or Full-Speed device and is connected to the Host through a high-speed hub. If the device is connected directly to the Host, these parameters should be set to zero ('0'). The pipeType parameter specifies the type of USB transfers that this pipe would support. The bInterval parameter is interpreted as per the USB 2.0 Specification based on the transfer type and the speed of the pipe. The wMaxPacketSize parameter defines the maximum size of a transaction that the driver should use while transporting a transfer on the pipe. The Host layer will use the information obtained from the USB device descriptors of the attached device to decide the wMaxPacketSize parameter. The Driver Host Pipe Setup function should be thread-safe, but does not have to be event safe. The Host layer (or the Host Client Drivers) will not, and should not attempt to create a pipe in an interrupt, and therefore, an event context. The function should return DRV_USB_PIPE_HANDLE_INVALID if the driver could not open the pipe. The driver may not be able to open a pipe due to incorrect function parameters or due to lack of resources. Driver Host Pipe Close Function The hostPipeClose member of the DRV_USB_HOST_INTERFACE structure should point to the USB Driver Host Pipe Close function. The signature of the Host Pipe Close function is as follows: void (*hostPipeClose)(DRV_USB_HOST_PIPE_HANDLE pipeHandle); The USB Driver Host mode Pipe Close function must match this signature. The USB Host Stack calls this function to close communication pipes. The pipeHandle parameter is the pipe handle obtained from the Pipe Setup function. The Host Client Driver typically closes pipes when a device detach was detected. The Client Driver may also close pipes when a device configuration needs to change or when the Client Driver is being unloaded by the Host. The Pipe Close function has no side effect if the pipe handle is invalid. Closing the pipe will abort all I/O Request Packets (IRP) that are scheduled on the pipe. Any transaction in progress will complete. The IRP callback functions for each IRP scheduled in the pipe will be called with a USB_HOST_IRP_STATUS_ABORTED status. The USB Driver Pipe Close function must be thread-safe and event-safe. The latter requirement allows the Pipe Close function to be called in the context of the device detach Interrupt Service Routine. Driver Host Event Disable Function The hostEventsDisable member of the DRV_USB_HOST_INTERFACE structure should point to the USB Driver Host mode Driver Events Disable function. The signature of the Events Disable function is as follows: bool (*hostEventsDisable)(DRV_HANDLE handle); The USB Driver Host mode Driver Events Disable function must match this signature. The Host Stack will call this function when it wants to execute a section of code that should not be interrupted by the USB Driver. Calling this function should disable USB Driver event generation. The handle parameter is set to the driver handle obtained via the driver Open function. The function will return the present state of the event generation, whether it is enabled or disabled. The Host Stack will pass this value to the USB Driver Host mode Driver Events Enable function when it needs to enable the driver events. Driver Host Events Enable Function The hostEventsEnable member of the DRV_USB_HOST_INTERFACE structure should point to the USB Driver Host mode Driver Events Enable function. The signature of the events enable function is as follows: void (*hostEventsEnable)(DRV_HANDLE handle, bool eventContext); The USB Driver Host mode Driver Events Enable function must match this signature. The USB Host Stack calls this function to re-enable the USB Driver Host mode Events (if they were enabled) after it called the USB Driver Host mode Events Disable function to disable driver events. The handle parameter is set to the driver handle obtained via the driver Open function. The eventContext parameter is set to the value returned by the Host mode Driver Events Disable function. The USB Driver will use the eventContext parameter to restore the event generation status (enabled or disabled) to what it was when the USB Driver Host mode Driver Events Disable function was called. Driver Host IRP Submit Function The hostIRPSubmit member of the DRV_USB_HOST_INTERFACE structure should point to the USB Driver Host IRP Submit function. The Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1153 signature of the IRP Submit function is as follows: USB_ERROR (*hostIRPSubmit)(DRV_USB_HOST_PIPE_HANDLE pipeHandle, USB_HOST_IRP * irp); The USB Driver Host IRP Submit function must match this signature. The Host Stack calls this function to submit an IRP to the USB Driver. The USB Driver provides this mechanism to transfer data between the Host Stack and the attached device. The pipeHandle parameter should be set to the pipe handle obtained by the Pipe Setup function. The pipe handle specifies the pipe, and therefore, the target device, endpoint, speed and transfer type, on which the I/O must be processed. The irp parameter should point to the IRP data structure. The IRP data structure will transport an entire transfer over the pipe. The USB Driver will split up the transfer into transactions based on the parameters specified at the time of pipe creation. This process does not require Host Stack intervention. The function will return USB_ERROR_HOST_PIPE_INVALID if the pipe handle is not valid. It will return USB_ERROR_OSAL_FUNCTION if an error occurred while performing a RTOS-related operation. It will return USB_ERROR_NONE if the IRP was submitted successfully. The USB Driver will queue the IRP if there is already an IRP being processed on the pipe. The completion of the IRP processing is indicated by the USB Driver calling the IRP Callback function specified within the IRP. The Host IRP Submit function must be thread-safe and IRP callback-safe. The Host Stack may resubmit the IRP within the IRP Callback function. The IRP Callback function itself executes within an interrupt context. The completion status of the IRP will be available in the status member of the IRP when the IRP callback function is invoked. Driver Host IRP Cancel Function The hostIRPCancel member of the DRV_USB_HOST_INTERFACE structure should point to the USB Driver Host IRP Cancel function. The signature of the IRP Cancel function is as follows void (*hostIRPCancel)(USB_HOST_IRP * irp); The USB Driver Host IRP Cancel function must match this signature. The Host Stack and Host Client Drivers will call this function to cancel an IRP that was submitted. The IRP will be aborted successfully if it is not in progress. If the IRP processing has begun, the on-going transaction will complete and pending transactions in the transfer will be aborted. In either case, the IRP Callback function will be called with the IRP status as USB_HOST_IRP_STATUS_ABORTED. Driver Host USB Root Hub Port Interface Provides information on the Root Hub Port interface of the USB Host Driver. Description The rootHubPortInterface member of the DRV_USB_ROOT_HUB_INTERFACE structure should point to the USB Driver Root Hub Port functions. The data type of this member is USB_HUB_INTERFACE. This data type is a structure containing function pointers pointing to the port control functions of the root hub. The USB Driver must assign the function pointers in this structure to the root hub port control functions. These same functions are also exported by a Hub Driver to the USB Host Stack, which allow the Host Stack to control a device regardless of whether it is connected to a root hub or an external hub. The port functions are valid only when a device is attached to the port. The behavior of these functions on a port to which no device is connected is not defined. Descriptions of the port control functions are provided, which include: • Driver Host Hub Port Reset Function • Driver Host Hub Port Reset Completion Status Function • Driver Host Hub Port Suspend Function • Driver Host Hub Port Resume Function • Driver Host Hub Port Speed Get Function Driver Host Hub Port Reset Function The hubPortReset member of the USB_HUB_INTERFACE structure should point to the USB Driver Root Hub Port Reset function. The signature of this function is as follows: USB_ERROR (*hubPortReset)(uintptr_t hubAddress, uint8_t port); The USB Driver Root Hub Port Reset function must follow this signature. This function starts reset signaling on the port. If the device is connected to the root hub, the USB Host Stack will set the hubAddress parameter to the driver handle obtained through the driver Open function. The USB Host Stack uses the parent identifier provided by the root hub driver when the USB_HOST_DeviceEnumerate function was called to query the driver handle that is linked to this root hub. If the device is connected to an external hub, the hubAddress parameter is directly set to the parent identifier. For the PIC32MX and PIC32MZ USB Drivers, the port parameter is ignored. For an external hub, this must be set to the port to which the device is connected. The function returns USB_ERROR_NONE if the function was successful. If the reset signaling is already in progress on the port, calling this function has no effect. The USB Driver will itself time duration of the reset signal. This does not require USB Host Stack intervention. The USB Host Stack will call the port reset completion status function to check if the reset signaling has completed. Calling this function on a port which exists on an external hub will cause the hub driver to issue a control transfer to start the port reset procedure. Driver Host Hub Port Reset Completion Status Function The hubPortResetIsComplete member of the USB_HUB_INTERFACE structure should point to the USB Driver Root Hub Port Reset Completion Status function. The signature of this function is as follows: bool (*hubPortResetIsComplete)(uintptr_t hubAddress, uint8_t port); The USB Driver Root Hub Port Reset Completion Status function must follow this signature. The USB Host Stack calls this function to check if the port reset sequence that was started on a port has completed. The function returns true if the reset signaling has completed. If the device is connected to the root hub, the USB Host Stack will set the hubAddress parameter to the driver handle obtained through the driver Open function. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1154 If the device is connected to an external hub, the hubAddress parameter is directly set to the parent identifier. For the PIC32MX and PIC32MZ USB Drivers, the port parameter is ignored. For an external hub, this parameter must be set to the port to which the device is connected. Driver Host Hub Port Suspend Function The hubPortSuspend member of the USB_HUB_INTERFACE structure should point to the USB Driver Root Hub Port Suspend function. The signature of this function is as follows: USB_ERROR(*hubPortSuspend)(uintptr_t hubAddress, uint8_t port); The USB Driver Root Hub Port Suspend function must follow this signature. The USB Host Stack calls this function to suspend the port. If the device is connected to the root hub, the USB Host Stack will set the hubAddress parameter to the driver handle obtained through the driver Open function. If the device is connected to an external hub, the hubAddress parameter is directly set to the parent identifier. For the PIC32MX and PIC32MZ USB Drivers, the port parameter is ignored. For an external hub, this parameter must be set to the port to which the device is connected. The function returns USB_ERROR_NONE if the request was successful. Calling this function on a suspended port will not have any effect. Driver Host Hub Port Resume Function The hubPortResume member of the USB_HUB_INTERFACE structure should point to the USB Driver Root Hub Port Resume function. The signature of this function is as follows: USB_ERROR(*hubPortResume)(uintptr_t hubAddress, uint8_t port); The USB Driver Root Hub Port Resume function must follow this signature. The USB Host Stack calls this function to resume a suspended port. If the device is connected to the root hub, the USB Host Stack will set the hubAddress parameter to the driver handle obtained through the driver Open function. If the device is connected to an external hub, the hubAddress parameter is directly set to the parent identifier. For the PIC32MX and PIC32MZ USB Drivers, the port parameter is ignored. For an external hub, this parameter must be set to the port to which the device is connected. The function returns USB_ERROR_NONE if the request was successful. Calling this function on a port that is not suspended will not have any effect. Driver Host Hub Port Speed Get Function The hubPortSpeedGet member of the USB_HUB_INTERFACE structure should point to the USB Driver Root Hub Port Speed Get function. The signature of this function is as follows: USB_SPEED(*hubPortSpeedGet)(uintptr_t hubAddress, uint8_t port); The USB Driver Root Hub Port Speed Get function must follow this signature. The USB Host Stack calls this function to obtain the USB speed of the device that is attached to the port. The Host Stack calls this function only after it has completed reset of the port. If the device is connected to the root hub, the USB Host Stack will set the hubAddress parameter to the driver handle obtained through the driver Open function. If the device is connected to an external hub, the hubAddress parameter is directly set to the parent identifier. For the PIC32MX and PIC32MZ USB Drivers, the port parameter is ignored. For an external hub, this parameter must be set to the port to which the device is connected. The function returns USB_SPEED_ERROR if the request was not successful. It will return the functional USB speed otherwise. This concludes the section describing the USB Driver Host mode Client Functions. The USB Driver Device Mode Client Functions are discussed in the next section. Driver Host Root Hub Interface Provides information on the Root Hub interface for the USB Host Driver. Description The USB Driver Common Interface requires the USB Driver to be operating in Host mode to provide root hub control functions. If the USB peripheral does not contain root hub features in hardware, these features must be emulated in software by the driver. The USB peripheral on PIC32MX and PIC32MZ devices does not contain root hub features; therefore, the USB Driver for these peripherals emulates the root hub functionality in software. The rootHubInterface member of the DRV_USB_HOST_INTERFACE structure is a structure of type DRV_USB_ROOT_HUB_INTERFACE. The members of this structure are function pointers to the root hub control functions of the USB Driver. Along with other Host mode functions, the USB Driver while operating in Host mode must also ensure that the rootHubInterface member of DRV_USB_HOST_INTERFACE is set up correctly so that the USB Host Stack can access the root hub functions. Descriptions of the function pointer types in the DRV_USB_ROOT_HUB_INTERFACE include: • Driver Host Root Hub Speed Get Function • Driver Host Root Hub Port Numbers Get Function • Driver Host Root Hub Maximum Current Get Function • Driver Host Root Hub Operation Enable Function • Driver Host Root Hub Operation Enable Status Function • Driver Host Root Hub Initialize Function Driver Host Root Hub Speed Get Function The rootHubSpeedGet member of the DRV_USB_ROOT_HUB_INTERFACE structure should point to the USB Driver Root Hub Speed Get Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1155 function. The signature of this function is as follows: USB_SPEED (*rootHubSpeedGet)(DRV_HANDLE handle); The USB Driver Root Hub Speed Get function must match this signature. The USB Host Stack calls this function to identify the speed at which the root hub is operating. The handle parameter is the handle obtained by calling the USB Driver Open function. The operation speed is configured by the USB Driver initialization and depends on the capability of the USB peripheral. For example, the USB peripheral on PIC32MZ devices supports both Hi-Speed and Full-Speed Host mode operation. It can be configured through initialization to only operate at Full-Speed. The Root Hub Speed Get function must return the USB speed at which the USB peripheral is operating. This should not be confused with the speed of the attached device. Driver Host Root Hub Port Numbers Get Function The rootHubPortNumbersGet member of the DRV_USB_ROOT_HUB_INTERFACE structure should point to the USB Driver Root Hub Port Numbers Get function. The signature of this function is as follows: USB_SPEED (*rootHubSpeedGet)(DRV_HANDLE handle); The USB Driver Root Hub Speed Get function must match this signature. This function should return the number of ports that the root hub contains. On the USB peripheral for both PIC32MZ and PIC32MX devices, this value is always '1'. Driver Host Root Hub Maximum Current Get Function The rootHubMaxCurrentGet member of the DRV_USB_ROOT_HUB_INTERFACE structure should point to the USB Driver Root Hub Maximum Current Get function. The signature of this function is as follows: uint32_t (*rootHubMaxCurrentGet)(DRV_HANDLE handle); The USB Driver Root Hub Maximum Current Get function must match this signature. This function returns the maximum VBUS current that the root hub can provide. The USB Host Stack calls this function to know the maximum current that the root hub VBUS power supply can provide. This value is then used to determine if the Host can support the current requirements of the attached device. The handle parameter is the driver handle obtained by calling the driver Open function. The PIC32MX and the PIC32MZ USB peripherals cannot supply VBUS. The root hub driver only switches the VBUS supply. The current rating of the VBUS is specified through the USB Driver initialization. The root hub maximum current get function implementation in these drivers returns this value to the Host Stack. Driver Host Root Hub Operation Enable Function The rootHubOperationEnable member of the DRV_USB_ROOT_HUB_INTERFACE structure should point to the USB Driver Root Hub Operation Enable function. The signature of this function is as follows" void (*rootHubOperationEnable)(DRV_HANDLE handle, bool enable); The USB Driver Root Hub Operation Enable function must match this signature. The USB Host Stack calls this function when it ready to receive device attach events from the root hub. Calling this function will cause the USB Driver root hub functionality to enable detection of device attach and detach. The USB Driver will then raise events to the USB Host Stack. The handle parameter is the driver handle obtained by calling the driver Open function. Setting the enable parameter to true enables the root hub operation. Setting the enable parameter to false disables the root hub operation. Driver Host Root Hub Operation Enable Status Function The rootHubOperationIsEnabled member of the DRV_USB_ROOT_HUB_INTERFACE structure should point to the USB Driver Root Hub Operation Enable Status function. The signature of this function is as follows: bool (*rootHubOperationIsEnabled)(DRV_HANDLE handle); The USB Driver Root Hub Operation Enable Status function must match this signature. This USB Host Stack calls this function after calling the operation enable function to check if this has completed. The function returns true if the operation enable function has completed. The USB Host Stack will call this function periodically until it returns true. Driver Host Root Hub Initialize Function The rootHubInitialize member of the DRV_USB_ROOT_HUB_INTERFACE structure should point to the USB Driver Root Hub Initialize function. The signature of this function is as follows: void (*rootHubInitialize)(DRV_HANDLE handle, USB_HOST_DEVICE_OBJ_HANDLE usbHostDeviceInfo); The USB Driver Root Hub Initialize function must match this signature. The USB Host Stack calls this function to assign a device identifier (usbHostDeviceInfo) to the root hub. This function is called before the Host Stack enables the root hub operation. The USB Driver root hub should use this identifier as the parent identifier when it calls the USB_HOST_DeviceEnumerate function to enumerate the attached device. At the time of enumeration, the USB Host Stack will use this parent identifier to identify the parent hub (whether root hub or external hub) of the attached device. The USB Driver root hub should retain the usbHostDeviceInfo parameter for the life time of its operation. Driver Device Mode Client Functions Provides information on the USB Driver Device mode Client functions. Description The DRV_USB_DEVICE_INTERFACE structure contains pointers to the USB Driver’s Device mode Client Functions. These functions are only applicable when the USB module is operating as a USB Device. A USB Driver must implement these functions and ensure that the Device Stack Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1156 can access these functions through the driver’s DRV_USB_DEVICE_INTERFACE structure. Descriptions of the Driver Device Mode Client functions in the DRV_USB_DEVICE_INTERFACE structure include: • Driver Device Address Set Function • Driver Device Current Speed Get Function • Driver Device SOF Number Get Function • Driver Device Attach Function • Driver Device Detach Function • Driver Device Endpoint Enable Function • Driver Device Endpoint Disable Function • Driver Device Endpoint Stall Function • Driver Device Endpoint Stall Clear Function • Driver Device Endpoint Enable Status Function • Driver Device Endpoint Stall Status Function • Driver Device IRP Submit Function • Driver Device IRP Cancel All Function • Driver Device IRP Cancel Function • Driver Device Remote Wakeup Start Function • Driver Device Remote Wakeup Stop Function • Driver Device Test Mode Enter Function The PIC32MZ and the PIC32MX USB peripheral drivers implement the Device mode functions and export these functions to the Device Stack though their respective DRV_USB_DEVICE_INTERFACE structure. Driver Device Address Set Function The deviceAddressSet member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Device Address Set function. The signature of this function is as follows: void (*deviceAddressSet)(DRV_HANDLE handle, uint8_t address); The USB Driver Device Address Set Function should match this signature. The USB Device Stack will call this function to set the Device USB Address. The function will be called in an interrupt context and hence the function implementation must be interrupt-safe. The handle parameter is the driver handle obtained from calling the driver Open function. The address parameter is the address provided by the USB Host through the Set Device Address Standard request. Driver Device Current Speed Get Function The deviceCurrentSpeedGet member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Current Speed Get function. The signature of this function is as follows: USB_SPEED (*deviceCurrentSpeedGet)(DRV_HANDLE handle); The USB Driver Device Current Speed Get function should match this signature. The USB Device Stack will call this function to obtain the speed at which the device has connected to the USB. It will call this function after reset signaling has completed. The handle parameter is driver handle obtained from calling the driver Open function. This function is called in an interrupt context and should be interrupt-safe. Driver Device SOF Number Get Function The deviceSOFNumberGet member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Start-Of-Frame Number Get function. The signature of this function is as follows: uint16_t (*deviceSOFNumberGet)(DRV_HANDLE handle); The USB Driver SOF Number Get function should match this signature. The USB Device Stack will call this function to obtain the current SOF number. The USB peripheral uses a 16 bit counter to count the number of SOFs that have occurred since USB reset. This value is returned along with the Device Stack Start of Frame event. This function is called from an interrupt context and should be interrupt-safe. The handle parameter is the driver handle obtained from calling the driver Open function. Driver Device Attach Function The deviceAttach member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Attach function. The signature of this function is as follows: uint16_t(*deviceAttach)(DRV_HANDLE handle); The USB Driver Attach function should match this signature. The USB Device Stack will call this function when the Device application calls the USB Device Stack Device Attach function. The USB Driver will enable the required signaling resistors for indicate attach to the Host. The application could call this function in response to a VBUS power available event. This function must be interrupt-safe. The handle parameter is the driver handle obtained from calling the driver Open function. Driver Device Detach Function The deviceDetach member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Detach function. The signature of this function is as follows: uint16_t(*deviceDetach)(DRV_HANDLE handle); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1157 The USB Driver Detach function should match this signature. The USB Device Stack will call this function when the Device application calls the USB Device Stack Device Detach function. The USB Driver will disable the required signaling resistors to indicate detach to the Host. The application could call this function in response to a VBUS power not available event. This function should be interrupt-safe. The handle parameter is driver handle obtained from calling the driver Open function. Driver Device Endpoint Enable Function The deviceEndpointEnable member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Endpoint Enable function. The signature of this function is as follows: USB_ERROR (*deviceEndpointEnable)(DRV_HANDLE handle, USB_ENDPOINT endpoint, USB_TRANSFER_TYPE transferType, uint16_t endpointSize); The USB Driver Endpoint Enable function should match this signature. The USB Device Stack Function Driver will call this function when it is initialized by the USB Device Layer. The Device Layer, on receiving the Set Configuration request from the Host, identifies the function drivers that are required by the configuration and initializes them. The function drivers will call the endpoint enable function to enable the endpoints required for their operation. Enabling the endpoint will cause it reply to transaction requests from the Host and accept transfer requests from the device application. The handle parameter is the driver handle obtained from calling the driver Open function. The endpoint parameter is the USB endpoint (which indicates the direction along with endpoint number) that should be enabled. The transferType is the type of the USB transfer that this endpoint will handle. The endpointSize is the size of the maximum transaction that the endpoint will handle. This should match the endpoint size communicated to the Host via the device endpoint descriptors. The function will return USB_ERRROR_NONE if the endpoint was configured successfully. The function will return USB_ERROR_DEVICE_ENDPOINT_INVALID if the specified endpoint is not provisioned in the system configuration. It will return USB_ERROR_PARAMETER_INVALID if the driver handle is not valid. The endpoint enable function will be called in an interrupt context and should be interrupt-safe. It is not expected to be thread safe. For standard function drivers, the endpoint enable function will be called in the context of the USB Device Layer Client. For vendor USB devices, the vendor application must call the endpoint enable function in response to and within the context of the device configured event. Again this event itself will execute in the context of the Device Layer. Driver Device Endpoint Disable Function The deviceEndpointDisable member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Endpoint Disable function. The signature of this function is as follows: USB_ERROR (*deviceEndpointDisable)(DRV_HANDLE handle, USB_ENDPOINT endpoint); The USB Driver Endpoint Disable function should match this signature. The USB Device Stack Function Driver will call this function when it is deinitialized by the USB Device Layer. The Device Layer will deinitialize function drivers when it receives a USB reset event from the driver or on receiving the Set Configuration request from the Host with configuration parameter 0. Disabling the endpoint will cause it NAK transaction request from the Host and not accept transfer requests from the device application. The handle parameter is the driver handle obtained from calling the driver Open function. The endpoint parameter is the USB endpoint (which indicates the direction along with endpoint number) that should be disabled. The function will return USB_ERRROR_NONE if the function executed successfully. The function will return USB_ERROR_DEVICE_ENDPOINT_INVALID if the specified endpoint is not provisioned in the system configuration. It will return USB_ERROR_PARAMETER_INVALID if the driver handle is not valid. The endpoint disable function will be called in an interrupt context and should be interrupt-safe. It is not expected to be thread safe. For standard function drivers, the endpoint disable function will be called in the context of the USB Device Layer Client. For vendor USB devices, the vendor application must call the endpoint enable function in response to and within the context of the device reset event. Again this event itself will execute in the context of the Device Layer. Disabling the endpoint will not cancel any transfers that have been queued against the endpoint. The function drivers will call the IRP Cancel All function to cancel any pending transfers. Driver Device Endpoint Stall Function The deviceEndpointStall member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Endpoint Stall function. The signature of this function is as follows: USB_ERROR (*deviceEndpointStall)(DRV_HANDLE handle, USB_ENDPOINT endpoint); The USB Driver Endpoint Stall function should match this signature. The USB Device Stack Function Driver will call this function to stall an endpoint. The Device Layer itself will stall endpoint 0 for several reasons including non-support of the Host request or failure while executing the request. A function driver will also stall an endpoint for protocol specific reasons. The driver will stall both, receive and transmit directions when stalling Endpoint 0. The driver will stall the specified direction while stalling a non-zero endpoint. This function must be thread safe and interrupt safe. Stalling the endpoint will abort all the transfers queued on the endpoint with the completion status set to USB_DEVICE_IRP_STATUS_ABORTED_ENDPOINT_HALT. The handle parameter is the driver handle obtained from calling the driver Open function. The endpoint parameter is the USB endpoint (which indicates the direction along with endpoint number) that should be stalled. The function will return USB_ERRROR_NONE if the function executed successfully. The function will return USB_ERROR_DEVICE_ENDPOINT_INVALID if the specified endpoint is not provisioned in the system configuration. It will return USB_ERROR_PARAMETER_INVALID if the driver handle is not valid. Driver Device Endpoint Stall Clear Function The deviceEndpointStallClear member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Endpoint Stall Clear function. The signature of this function is as follows: Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1158 USB_ERROR (*deviceEndpointStallClear)(DRV_HANDLE handle, USB_ENDPOINT endpoint); The USB Driver Endpoint Stall Clear function should match this signature. The USB Device Stack Function Driver will call this function to clear the stall on a non-zero endpoint. The Device Layer will call this function to clear the stall condition on Endpoint 0. Clearing the stall on a non-zero endpoint will clear all transfers scheduled on the endpoint and transfer completion status will be set to USB_DEVICE_IRP_STATUS_TERMINATED_BY_HOST. When the stall is cleared, the data toggle for non-zero endpoint will be set to DATA0. The data toggle on Endpoint 0 OUT endpoint will be set to DATA1. The USB Driver will clear the Stall condition on an endpoint even if it was not stalled. This function must be thread safe and interrupt safe. Stalling the endpoint will flush all the transfers queued on the endpoint. The handle parameter is the driver handle obtained from calling the driver Open function. The endpoint parameter is the USB endpoint (which indicates the direction along with endpoint number) whose stall condition must be cleared. The function will return USB_ERRROR_NONE if the function executed successfully. The function will return USB_ERROR_DEVICE_ENDPOINT_INVALID if the specified endpoint is not provisioned in the system configuration. It will return USB_ERROR_PARAMETER_INVALID if the driver handle is not valid. Driver Device Endpoint Enable Status Function The deviceEndpointIsEnabled member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Endpoint Enable Status function. The signature of this function is as follows: bool (*deviceEndpointIsEnabled)(DRV_HANDLE handle, USB_ENDPOINT endpoint); The USB Driver Endpoint Enable Status function should match this signature. The USB Device Stack function will call this function to check if an endpoint has been enabled. The function returns true if the endpoint is enabled. The endpoint is enabled through the USB Driver Endpoint Enable function. The handle parameter is the driver handle obtained from calling the driver Open function. The endpoint parameter is the USB endpoint (which indicates the direction along with endpoint number) whose enable status needs to be queried. Driver Device Endpoint Stall Status Function The deviceEndpointIsStalled member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Endpoint Stall Status function. The signature of this function is as follows: bool (*deviceEndpointIsStalled)(DRV_HANDLE handle, USB_ENDPOINT endpoint); The USB Driver Endpoint Stall Status function should match this signature. The USB Device Stack function will call this function to check if an endpoint has been stalled. The function returns true if the endpoint is stalled. The endpoint is stalled through the USB Driver Endpoint Stall function. The handle parameter is the driver handle obtained from calling the driver Open function. The endpoint parameter is the USB endpoint (which indicates the direction along with endpoint number) whose stall status needs to be queried. Driver Device IRP Submit Function The deviceIRPSubmit member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Device IRP Submit function. The signature of the IRP submit function is as follows: USB_ERROR (*deviceIRPSubmit)(DRV_HANDLE handle, USB_ENDPOINT endpoint, USB_DEVICE_IRP * irp); The USB Driver Device IRP Submit function must match this signature. The Device Stack (USB Device calls this function to submit an IRP to the USB Driver. The USB Driver provides this mechanism to transfer data between the device and the Host. The handle parameter is the driver handle obtained from calling the driver Open function. The endpoint parameter should set to endpoint through which transfer must be processed. The irp parameter should point to the Device IRP data structure. The IRP data structure will transport an entire transfer over the endpoint. The USB Driver will split up the transfer into transactions based on the endpoint size specified at the time of enabling the endpoint. This process does not require Device Stack intervention. The function will return USB_ERRROR_NONE if the function executed successfully. The function will return USB_ERROR_DEVICE_ENDPOINT_INVALID if the specified endpoint is not provisioned in the system configuration. It will return USB_ERROR_PARAMETER_INVALID if the driver handle is not valid. It will return USB_ERROR_DEVICE_IRP_IN_USE if an in progress IRP is resubmitted. It will return USB_ERROR_ENDPOINT_NOT_CONFIGURED if the IRP is submitted to an endpoint that is not enabled. The USB Driver will queue the IRP if there is already an IRP being processed on the endpoint. The completion of the IRP processing is indicated by the USB Driver calling the IRP callback function specified within the IRP. The Device IRP Submit function must be thread safe and IRP callback safe. The Device Stack may resubmit the IRP within the IRP callback function. The IRP callback function itself executes within an interrupt context. The completion status of the IRP will be available in the status member of the IRP when the IRP callback function is invoked. Driver Device IRP Cancel All Function The deviceIRPCancelAll member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Device IRP Cancel All function. The signature of this is as follows: USB_ERROR (*deviceIRPCancelAll)(DRV_HANDLE handle, USB_ENDPOINT endpoint); The USB Driver Device IRP Cancel All function must match this signature. The USB Device Stack will call this function before disabling the endpoint. Calling this function will call all IRPs that are queued on the endpoint to be canceled. The callback of each IRP will be invoked and the IRP completion status will be set to USB_DEVICE_IRP_STATUS_ABORTED. If an IRP is in progress, an ongoing transaction will be allowed to complete and pending transactions will be canceled. The handle parameter is the driver handle obtained from calling the driver Open function. The endpoint parameter is the USB endpoint (which indicates the direction along with endpoint number) whose queued IRPs must be canceled. The function is thread safe and interrupt safe and will return USB_ERRROR_NONE if it executed successfully. The function will return USB_ERROR_DEVICE_ENDPOINT_INVALID if the specified endpoint is not provisioned in the system configuration. It will return USB_ERROR_PARAMETER_INVALID if the driver handle is not valid. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1159 Driver Device IRP Cancel Function The deviceIRPCancel member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Device IRP Cancel function. The signature of this is as follows: USB_ERROR (*deviceIRPCancel)(DRV_HANDLE handle, USB_DEVICE_IRP * IRP); The USB Driver Device IRP Cancel function must match this signature. This function is called by the USB Device Stack function driver to cancel a scheduled IRP. If the IRP is in the queue but it’s processing has not started, the IRP will removed from the queue and the IRP callback function will be called from within the cancel function. The callback will be invoked with the IRP completion status set to USB_DEVICE_IRP_STATUS_ABORTED. If an IRP is in progress, an ongoing transaction will be allowed to complete and pending transactions will be canceled. The handle parameter is the driver handle obtained from calling the driver Open function. The irp parameter is the IRP to be canceled. The function is thread safe and will return USB_ERRROR_NONE if it executed successfully. It will return USB_ERROR_PARAMETER_INVALID if the driver handle is not valid or if the IRP has status indicates that this IRP is not queued or not in progress. The application should not release the data memory associated with IRP unless the callback has been received. Driver Device Remote Wakeup Start Function The deviceRemoteWakeupStart member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Device Remote Wakeup Start function. The signature of this function is as follows: void (*deviceRemoteWakeupStart)(DRV_HANDLE handle); The USB Driver Device Remote Wakeup Start function must match this signature. The USB Device Stack will call the function when the device application wants to start remote wakeup signaling. This would happen if the device supports remote wake-up capability and this has been enabled by the Host. The handle parameter is the driver handle obtained from calling the driver Open function. Driver Device Remote Wakeup Stop Function The deviceRemoteWakeupStop member of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Device Remote Wakeup Stop function. The signature of this function is as follows: void (*deviceRemoteWakeupStop)(DRV_HANDLE handle); The USB Driver Device Remote Wakeup Stop function must match this signature. The USB Device Stack will call the function when the device application wants to stop remote wakeup signaling. The application would call after calling the remote wakeup start function. The handle parameter is the driver handle obtained from calling the driver Open function. Driver Device Test Mode Enter Function The deviceTestModeEnter parameter of the DRV_USB_DEVICE_INTERFACE structure should point to the USB Driver Device Test Mode Enter function. The signature of this function is as follows: USB_ERROR (*deviceTestModeEnter)(DRV_HANDLE handle, USB_TEST_MODE_SELECTORS testMode); The USB Driver Device Test Mode Enter function should match this signature. The USB Device Stack calls this driver function to place the driver into test mode. This is required when the USB Host (operating at Hi-Speed) send the Set Feature request with the feature selector test set to test mode. This request also specifies which of the test mode signals, the driver should enable. The handle parameter is the driver handle obtained from calling the driver Open function. The testMode parameter should be set to one of the test modes as defined in table 9-7 of the USB 2.0 specification. The test mode enter function is only supported by the PIC32MZ USB Driver as the USB peripheral on this controller supports Hi-Speed operation. The function will return USB_ERRROR_NONE if it executed successfully. It will return USB_ERROR_PARAMETER_INVALID if the driver handle is not valid. This concludes the discussion on the DRV_USB_DEVICE_INTERFACE structure. The following sections describe using the USB Common Driver. Opening the Driver Provides information and examples for opening the driver. Description The USB Host Stack and the USB Device Stack must obtain a handle to the USB Driver to access the functionality of the driver. This handle is obtained through the USB Driver Open function. The DRV_USB_DEVICE_INTERFACE structure and DRV_USB_DEVICE_HOST_INTERFACE structure provide access to the USB Driver Open function through the open member of these structures. Calling the Open function may not return a valid driver handle the first time the function is called. In fact, the USB Driver will return an invalid driver handle until the driver is ready to be opened. The Host and the Device Stack call the Open function repetitively in a state machine, until the function returns a valid handle. The USB Host Stack can open the USB Driver but can call its Host mode functions only if the USB Driver was initialized for Host mode or Dual Role operation. The USB Host Stack accesses the driver functions through the DRV_USB_HOST_INTERFACE pointer that was provided to the Host Layer through the Host Stack initialization. The USB Device Stack can open the USB Driver but can call its Device mode functions only if the USB Driver was initialized for Device mode or Dual Role operation. The USB Device Stack accesses the driver functions through the DRV_USB_HOST_INTERFACE pointer that was provided to the Host Layer through the Host Stack initialization The following code example shows how the USB Host Layer opens the USB Driver. /* This code example shows how the Host Layer open the HCD via the hcdInterface. * The driver handle is stored in hcdHandle member of the busObj data structure. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1160 * The busObj data structure Host Layer local data structure. The Host Layer * opens the HCD when the bus is enabled. This operation takes place in the * USB_HOST_BUS_STATE_ENABLING state. */ /* Note the Host Layer calls the Open function by accessing the open member of * the hcdInterface which is of the type DRV_USB_HOST_INTERFACE. Also note how * the function is called repetitively until the Open function returns a valid * handle. */ case USB_HOST_BUS_STATE_ENABLING: /* The bus is being enabled. Try opening the HCD */ busObj->hcdHandle = busObj->hcdInterface->open(busObj->hcdIndex, DRV_IO_INTENT_EXCLUSIVE | DRV_IO_INTENT_NONBLOCKING | DRV_IO_INTENT_READWRITE ); /* Validate the Open function status */ if (DRV_HANDLE_INVALID == busObj->hcdHandle ) { /* The driver may not open the first time. This is okay. We * should try opening it again. The state of bus is not * changed. */ } The following code example shows how the USB Device Layer opens the USB Driver. /* This code example shows how the USB Device Layer calls the USBCD open * function to open the USBCD. The Device Layer accesses the USBCD Open function * through the driverInterface member of the usbDeviceInstanceState object. The * driverInterface member is a DRV_USB_DEVICE_INTERFACE type. The * usbDeviceInstanceState is a USB Device Layer local object. */ /* The Device Layer attempts to open the USBCD when it is initializing. Note how * the Device Layer advances to the next state only when the USBCD returns a * valid handle. */ switch(usbDeviceThisInstance->taskState) { case USB_DEVICE_TASK_STATE_OPENING_USBCD: /* Try to open the driver handle. This could fail if the driver is * not ready to be opened. */ usbDeviceThisInstance->usbCDHandle = usbDeviceThisInstance->driverInterface->open( usbDeviceThisInstance->driverIndex, DRV_IO_INTENT_EXCLUSIVE|DRV_IO_INTENT_NONBLOCKING|DRV_IO_INTENT_READWRITE); /* Check if the driver was opened */ if(usbDeviceThisInstance->usbCDHandle != DRV_HANDLE_INVALID) { /* Yes the driver could be opened. */ /* Advance the state to the next state */ usbDeviceThisInstance->taskState = USB_DEVICE_TASK_STATE_RUNNING; /* Update the USB Device Layer state to indicate that it can be * opened */ usbDeviceThisInstance->usbDeviceInstanceState = SYS_STATUS_READY; } break; USB Driver Host Mode Operation Provides information on Host mode operation. Description The USB Driver operates or can operate in the Host mode when it is initialized for Host mode or Dual Role operation. When operating in Host mode, the USB Driver is also referred to as the Host Controller Driver (HCD). In Dual Role mode, the USB Driver will switch to Host mode when the USB Driver Host Root Hub Operation Enable function is called. The USB Driver Client must perform these steps to operate the USB Driver in Host mode. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1161 1. Open the USB Driver to obtain the driver handle. 2. Set the event handler. 3. Call the Root Hub Control function to obtain the speed of the root hub, the number of ports that the root hub supports, and the maximum current that the root hub VBUS can supply. 4. Calls the Root Hub Initialize function with an identifier parameter. This identifier parameter allows the Host Stack to uniquely identify the root hub when where there are multiple root hubs. 5. The Driver Client will then enable the root hub operation and will wait until the root hub operation is enabled. 6. The Driver Client can now call the USB Driver Host mode functions. The following sections explain Steps 2 through 6 in more detail. Handling Host Mode Driver Events Currently, the HCD does not provide any events to the client. The client can optionally register an event handler through the eventHandlerSet function pointer in the DRV_USB_HOST_INTERFACE structure. Future releases of the USB Driver may contain features that provide events to the Driver Client. Please refer to the following Root Hub Operation section for details on how the driver indicates device attach and detach to the client. Root Hub Operation A key feature of the HCD is the Root Hub Driver. The Root Hub Driver emulates hub operation in USB Driver software and provides a hub like interface to the USB Host Layer. The USB Host Layer treats the root hub like an external hub. This simplifies the implementation of USB Host Layer while supporting multiple devices through a hub. In that, the USB Host layer does not have to treat a device connected directly to the USB peripheral differently than a device connected to an external hub. The following code example shows how the USB Host Layer calls the root hub function to obtain information about the root hub. /* This code example shows how the USB Host Layer calls the root hub functions to * obtain information about the root. The USB Host Layer first opens the HCD and * then accesses the root hub functions through the rootHubInterface member of * hcdInterface. rootHubInterface is of the type DRV_USB_ROOT_HUB_INTERFACE and * the hcdInterface is of the type of DRV_USB_HOST_INTERFACE. */ /* The code example shows how the Host Layer gets to know the root hub operation * speed, number of root hub ports and the maximum amount of current that the * root can supply. These function can be called only after HCD was opened and a * valid driver handle obtained. */ case USB_HOST_BUS_STATE_ENABLING: /* The bus is being enabled. Try opening the HCD */ busObj->hcdHandle = busObj->hcdInterface->open(busObj->hcdIndex, DRV_IO_INTENT_EXCLUSIVE | DRV_IO_INTENT_NONBLOCKING | DRV_IO_INTENT_READWRITE ); /* Validate the Open function status */ if (DRV_HANDLE_INVALID == busObj->hcdHandle ) { /* The driver may not open the first time. This is okay. We * should try opening it again. The state of bus is not * changed. */ } else { /* Update the bus root hub information with the * details of the controller. Get the bus speed, number of * ports, the maximum current that the HCD can supply, * pointer to the root hub port functions. */ SYS_DEBUG_PRINT(SYS_ERROR_INFO, "\r\nUSB Host Layer: Bus %d Root Hub Driver Opened.",hcCount); busObj->rootHubInfo.speed = busObj->hcdInterface->rootHubInterface.rootHubSpeedGet(busObj->hcdHandle); busObj->rootHubInfo.ports = busObj->hcdInterface->rootHubInterface.rootHubPortNumbersGet(busObj->hcdHandle); busObj->rootHubInfo.power = busObj->hcdInterface->rootHubInterface.rootHubMaxCurrentGet(busObj->hcdHandle); busObj->rootHubInfo.rootHubPortInterface = busObj->hcdInterface->rootHubInterface.rootHubPortInterface; Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1162 The USB Host Layer must initialize and enable the operation of the root hub. While initializing the Root Hub Driver, the Host layer will assign a unique identifier to the root hub. The root hub will return this value as the parent identifier while calling the USB_HOST_DeviceEnumerate function. The USB Host Layer must then enable the operation of the root hub driver. This will cause the root hub driver to detect device attach and detach. The following code example shows how the USB Host Layer initializes and enables the root hub driver /* The following code example show how the USB Host Layer initializes the root * hub and then enables the root hub operation. The * rootHubDevice->deviceIdentifier is a unique identifier that allows the USB * Host layer to identify this root hub. It is returned by the root hub driver * in the USB_HOST_DeviceEnumerate() function as the parent identifier when the * device is connected to the root hub. */ /* The hcdHandle is the driver handle. The hcdInterface pointer is of the type * DRV_USB_HOST_INTERFACE and points to the HCD interface. */ busObj->hcdInterface->rootHubInterface.rootHubInitialize( busObj->hcdHandle , rootHubDevice->deviceIdentifier ); busObj->hcdInterface->rootHubInterface.rootHubOperationEnable( busObj->hcdHandle , true ); When a device is attached, the Root Hub Driver will implement the required settling attach settling delay and will then call the USB Host Layer’s USB_HOST_DeviceEnumerate function to enumerate the device. While calling this function, the root hub driver will provide the identifier that was provided to it in its initialize function. The USB_HOST_DeviceEnumerate function will return an identifier which uniquely identifies the attached device. The root hub driver uses this value to identify the device to the Host when the USB_HOST_DeviceDenumerate function is called on device detach. The following code example shows how the Root Hub driver calls the USB_HOST_DeviceEnumerate and the USB_HOST_DeviceDenumerate functions. /* The following code shows how the root hub driver calls the * USB_HOST_DeviceEnumerate() function in the device attach interrupt. As seen * here, the root hub returns the identifier that the USB Host Layer assigned to * it the rootHubInitialize function call. The pUSBDrvObj->usbHostDeviceInfo * variable contains this identifier. */ if(PLIB_USB_InterruptFlagGet(usbID, USB_INT_ATTACH)) { /* We can treat this as a valid attach. We then clear the * detach flag and enable the detach interrupt. We enable * the Transaction interrupt */ PLIB_USB_InterruptFlagClear(usbID, USB_INT_HOST_DETACH); PLIB_USB_InterruptEnable(usbID, USB_INT_HOST_DETACH); PLIB_USB_InterruptEnable(usbID, USB_INT_TOKEN_DONE); /* Ask the Host layer to enumerate this device. While calling * this function, the UHD of the parent device which is the * root hub in this case. * */ pUSBDrvObj->attachedDeviceObjHandle = USB_HOST_DeviceEnumerate (pUSBDrvObj->usbHostDeviceInfo, 0); } /* The following code example shows how the root hub driver calls the * USB_HOST_DeviceDenumerate() function in the device detach interrupt. Note how * the attachedDeviceObjHandle that was assigned at the time of device * enumeration is returned to the Host Layer to let the Host know which device * is being detached. */ if((usbInterrupts & USB_INT_HOST_DETACH) && (enabledUSBInterrupts & USB_INT_HOST_DETACH)) { /* Perform other detach related handling */ /* Ask the Host Layer to de-enumerate this device. */ USB_HOST_DeviceDenumerate (pUSBDrvObj->attachedDeviceObjHandle); /* Disable the LS Direct Connect. It may have been enabled if the last attach was for a Low-Speed device. */ PLIB_USB_EP0LSDirectConnectDisable(pUSBDrvObj->usbID); /* Continue to perform detach handling */ } Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1163 Root Hub Port Operation The HCD Root Hub Driver exposes a set of port related functions that allow the USB Host Layer to control the port. The most commonly used functions are the function to reset the port and get the port speed. In this case, this is the speed of the attached device. The following code example shows how the USB Host Layer calls the hubPortReset, hubPortResetIsComplete and hubPortSpeedGet port functions. /* The following code shows an example of how the Host Layer called the * hubPortReset function to reset the port to which the device is connected. * The code proceeds with the port reset if no device on the bus is in an * enumeration state. It will then call the hubPortReset function of the parent * hub of the device. The parent hub, hubInterface member of deviceObj points to * this driver, can be the root hub or an external hub */ if(!busObj->deviceIsEnumerating) { /* Remember which device is enumerating */ busObj->enumeratingDeviceIdentifier = deviceObj->deviceIdentifier; /* Grab the flag */ busObj->deviceIsEnumerating = true; /* Reset the device */ deviceObj->hubInterface->hubPortReset( deviceObj->hubHandle, deviceObj->devicePort ); } /* The following code example shows how the Host checks if the port reset * operation has completed. If the reset operation has completed, the speed of * the attached device can be obtained. The reset settling delay can then be * started. */ case USB_HOST_DEVICE_STATE_WAITING_FOR_RESET_COMPLETE: /* Check if the reset has completed */ if(deviceObj->hubInterface->hubPortResetIsComplete ( deviceObj->hubHandle ,deviceObj->devicePort )) { /* The reset has completed. We can also obtain the speed of the * device. We give a reset recovery delay to the device */ deviceObj->speed = deviceObj->hubInterface->hubPortSpeedGet (deviceObj->hubHandle, deviceObj->devicePort); deviceObj->deviceState = USB_HOST_DEVICE_STATE_START_RESET_SETTLING_DELAY; } Opening and Closing a Pipe The HCD client can open a pipe to the device after resetting the device. The USB Host Layer calls the hostPipeSetup function in the DRV_USB_HOST_INTERFACE structure to open a pipe. The USB Host Layer must open a pipe to communicate to a specific endpoint on a target device. While opening the pipe, the USB Host Layer must specify parameters which specify the address of the target device, the type of the transfer that the pipe must support and the speed of the pipe. If the device is connected to a hub, the address of the hub must be specified. The HCD Pipe Setup function is not interrupt-safe. It should not be called in any event handler that executes in an interrupt context. The Pipe Setup function returns a valid pipe handle if the pipe was opened successfully. Pipe creation may fail if the target device was disconnected or if there are insufficient resources to open the pipe. The pipe handle is then used along with the hostIRPSubmit function to transfer data between the Host and the device. The following code shows example usage of a Pipe Open function. /* The following code example shows how the Host Layer uses the hostPipeSetup * function to open a control pipe to the attached device. Most of the * parameters that are passed to this function become known when the device is * attached. The pipe handle is checked for validity after the hostPipeSetup * function call. */ if(busObj->timerExpired) { busObj->busOperationsTimerHandle = SYS_TMR_HANDLE_INVALID; /* Settling delay has completed. Now we can open default address * pipe and and get the configuration descriptor */ SYS_DEBUG_PRINT(SYS_ERROR_INFO, "\r\nUSB Host Layer: Bus %d Device Reset Complete.", busIndex); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1164 deviceObj->controlPipeHandle = deviceObj->hcdInterface->hostPipeSetup( deviceObj->hcdHandle, USB_HOST_DEFAULT_ADDRESS , 0 /* Endpoint */, deviceObj->hubAddress /* Address of the hub */, deviceObj->devicePort /* Address of the port */, USB_TRANSFER_TYPE_CONTROL, /* Type of pipe to open */ 0 /* bInterval */, 8 /* Endpoint Size */, deviceObj->speed ); if(DRV_USB_HOST_PIPE_HANDLE_INVALID == deviceObj->controlPipeHandle) { /* We need a pipe else we cannot proceed */ SYS_DEBUG_PRINT(SYS_ERROR_DEBUG, "\r\nUSB Host Layer: Bus %d Could not open control pipe. Device not supported.", busIndex); } } An open pipe consumes computational and memory resources and must therefore must be closed if it will not be used. This is especially true of pipes to a device that is detached. The Host Layer calls the hostPipeClose function in the DRV_USB_HOST_INTERFACE structure to close the pipe. The pipe to be closed is specified by the pipe handle. The Pipe Close function can be called from an event handler. It is interrupt safe. Closing a pipe will cancel all pending transfers on that pipe. The IRP callback for such canceled transfers will be called with the status USB_HOST_IRP_STATUS_ABORTED. The following code example shows an example of closing the pipe. /* The following code example shows an example of how the Host Layer calls the * hostPipeClose function to close an open pipe. Pipe should be closed if it * will not used. An open pipe consumes memory resources. In this example, the * Host Layer closes the pipe if it was not able successfully submit an IRP to * this pipe. */ /* Submit the IRP */ if(USB_ERROR_NONE != deviceObj->hcdInterface->hostIRPSubmit ( deviceObj->controlPipeHandle, & (deviceObj->controlTransferObj.controlIRP))) { /* We need to be able to send the IRP. We move the device to * an error state. Close the pipe and send an event to the * application. The assigned address will be released when * the device in unplugged. */ SYS_DEBUG_PRINT(SYS_ERROR_DEBUG, "\r\nUSB Host Layer: Bus %d Set Address IRP failed. Device not supported.", busIndex); /* Move the device to error state */ deviceObj->deviceState = USB_HOST_DEVICE_STATE_ERROR; /* Close the pipe as we are about mark this device as unsupported. */ deviceObj->hcdInterface->hostPipeClose(deviceObj->controlPipeHandle); } Transferring Data to an Attached Device The USB Host Layer, the HCD client, needs to transfer data to the attached device to understand the device capabilities and to operate the device. The HCD uses a concept of Input Output Request Packet (IRP) to transfer data to and from the attached device. IRPs are transported over pipes which are setup by calling the USB Driver Pipe Setup function. A Host IRP is a USB_HOST_IRP type data structure. The IRP is created by the Host layer and submitted to the HCD for processing through the hostIRPSubmit function. At the time of submitting the IRP, the pipe over which the IRP must be transported is specified. The data request in the IRP is transported using the attributes of pipe. When an IRP is submitted to the HCD, it is owned by the HCD and cannot be modified by the Host Layer until the HCD issues an IRP callback. The HCD will issue the IRP callback when it has completed or terminated processing of the IRP. An IRP does not have its own transfer type. It inherits the properties of the pipe to which it is submitted. Hence an IRP becomes a control transfer IRP it was submitted to a control transfer pipe. A pipe allows multiple IRPs to be queued. This allows the Host Layer to submit IRPs to a pipe even while an IRP is being processed on the pipe. The HCD will process an IRP in the order that it was received. The following code example shows the USB_HOST_IRP data structure. /* The following code example shows the USB_HOST_IRP structure. The Host Layer * uses this structure to place data transfer requests on a pipe. */ typedef struct _USB_HOST_IRP { /* Points to the 8 byte setup command packet in case this is a IRP is * scheduled on a CONTROL pipe. Should be NULL otherwise */ void * setup; /* Pointer to data buffer */ void * data; Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1165 /* Size of the data buffer */ unsigned int size; /* Status of the IRP */ USB_HOST_IRP_STATUS status; /* Request specific flags */ USB_HOST_IRP_FLAG flags; /* User data */ uintptr_t userData; /* Pointer to function to be called when IRP is terminated. Can be NULL, in * which case the function will not be called. */ void (*callback)(struct _USB_HOST_IRP * irp); /**************************************** * These members of the IRP should not be * modified by client ****************************************/ uintptr_t privateData[7]; } USB_HOST_IRP; The setup member of the USB_HOST_IRP structure must point to the 8 byte setup packet for control transfers. The driver will send this 8 byte data in the Setup phase of the control transfer. It can be NULL for non-control transfers. This member is only considered if the IRP is submitted to a control transfer pipe. It is ignored for non-control transfer pipes. The structure of the setup command should match that specified in the USB 2.0 specification. The data member of the USB_HOST_IRP structure points to a data buffer. This data buffer will contain the data that needs to be sent to the device for data stage of a OUT transfer, or it will contain the data that was received from the device during an IN transfer. Any hardware specific cache coherency and address alignment requirements must be considered while allocating this data buffer. The Driver Client should not modify or examine the contents of the IRP after the IRP has been submitted and is being processed. It can be examined after the driver has released the IRP. The size member of the USB_HOST_IRP structure contains the size of the transfer. for Bulk transfers, the size of the transfer can exceed the size of the transaction (which is equal to size of the endpoint reported by the device). The HCD in such a case will split up the transfer into transactions. This process does not require external intervention. For control transfers, the size of the transfer is specified in the setup packet (pointed to by the setup member of the USB_HOST_IRP structure). The driver will itself process the Setup, Data (if required) and Handshake stages of control transfer. This process again does not require external intervention. For interrupt and isochronous transfers, the size of transfer specified in the IRP cannot exceed the size of the transaction. If size is specified as 0, then the driver will send a zero length packet. The size parameter of the IRP is updated by the driver when IRP processing is completed. This will contain the size of the completed transfer. The status member of the IRP provides the completion status of the IRP and should be checked only when the IRP processing has completed. This is indicated by the driver calling the IRP callback function. The IRP status is a USB_HOST_IRP_STATUS type. The following code example shows the different possible values of the status member and an example of submit a control transfer IRP. /* The following code shows an example of how the Host Layer populates * the IRP object and then submits it. IRP_Callback function is called when an * IRP has completed processing. The status of the IRP at completion can be * checked in the status flag. The size field of the irp will contain the amount * of data transferred. */ void IRP_Callback(USB_HOST_IRP * irp) { /* irp is pointing to the IRP for which the callback has occurred. In most * cases this function will execute in an interrupt context. The application * should not perform any hardware access or interrupt unsafe operations in * this function. */ switch(irp->status) { case USB_HOST_IRP_STATUS_ERROR_UNKNOWN: /* IRP was terminated due to an unknown error */ break; case USB_HOST_IRP_STATUS_ABORTED: /* IRP was terminated by the application */ break; case USB_HOST_IRP_STATUS_ERROR_BUS: /* IRP was terminated due to a bus error */ Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1166 break; case USB_HOST_IRP_STATUS_ERROR_DATA: /* IRP was terminated due to data error */ break; case USB_HOST_IRP_STATUS_ERROR_NAK_TIMEOUT: /* IRP was terminated because of a NAK timeout */ break; case USB_HOST_IRP_STATUS_ERROR_STALL: /* IRP was terminated because of a device sent a STALL */ break; case USB_HOST_IRP_STATUS_COMPLETED: /* IRP has been completed */ break; case USB_HOST_IRP_STATUS_COMPLETED_SHORT: /* IRP has been completed but the amount of data processed was less * than requested. */ break; default: break; } } /* In the following code example the a control transfer IRP is submitted to a * control pipe. The setup parameter of the IRP points to the Setup command of * the control transfer. The direction of the data stage is specified by the * Setup packet. */ USB_HOST_IRP irp; USB_ERROR result; USB_HOST_PIPE_HANDLE controlPipe; USB_SETUP_PACKET setup; uint8_t controlTransferData[32]; irp.setup = setup; irp.data = controlTransferData; irp.size = 32; irp.flags = USB_HOST_IRP_FLAG_NONE ; irp.userData = &someApplicationObject; irp.callback = IRP_Callback; result = DRV_USBFS_HOST_IRPSubmit(controlPipeHandle, &irp); switch(result) { case USB_ERROR_NONE: /* The IRP was submitted successfully */ break; case USB_ERROR_HOST_PIPE_INVALID: /* The specified pipe handle is not valid */ break; case USB_ERROR_OSAL_FUNCTION: /* An error occurred while trying to grab mutex */ break; default: break; } The flags member of the USB_HOST_IRP structure specifies flags which affect the behavior of the IRP. The USB_HOST_IRP_FLAG enumeration specifies the available option. The USB_HOST_IRP_FLAG_SEND_ZLP causes the driver to add a Zero Length Packet (ZLP) to the data stage of the transfer when the transfer size is an exact multiple of the endpoint size. The USB_HOST_IRP_WAIT_FOR_ZLP flag will cause the driver to wait for a ZLP from the device in a case where the size of data received thus far in the transfer is an exact multiple of the endpoint Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1167 size. The callback member of the USB_HOST_IRP structure points to a function which the driver calls when the IRP processing is completed. The Driver Client must implement this function and assign the pointer to this function to the callback member of the IRP. Every IRP can have its own callback function or one common callback function could be used. The callback function will execute in an interrupt context. The Driver Client should not execute interrupt unsafe, blocking, or computationally intensive operations in the callback function. The client can call hostIRPSubmit function in the IRP callback function to submit another IRP or resubmit the same IRP. The client can check the status and size of the IRP in the callback function. The userData member of the USB_HOST_IRP structure can be used by the client to associate a client specific context with the Host. This context can then be used by the client, in the IRP callback function to identify the context in which the IRP was submitted. This member is particularly useful if the client wants to implement one callback function for all IRPs. The privateData member of the IRP is used by the driver and should not be accessed or manipulated by the Driver Client. The following code examples show usage of IRPs to transfer data between the Host and the attached device and along with the different flags. /* The following code shows an example of submitting an IRP to send data * to a device. In this example we will request the driver to send a ZLP after * sending the last transaction. The driver will send the ZLP only if the size * of the transfer is a multiple of the endpoint size. This is not a control * transfer IRP. So the setup field of the IRP will be ignored. */ USB_HOST_IRP irp; USB_ERROR result; USB_HOST_PIPE_HANDLE bulkOUTPipeHandle; uint8_t data[128]; irp.data = data; irp.size = 128; irp.flags = USB_HOST_IRP_FLAG_SEND_ZLP ; irp.userData = &someApplicationObject; irp.callback = IRP_Callback; result = DRV_USBFS_HOST_IPRSubmit( bulkOUTPipeHandle, &irp ); /* The following code shows an example of submitting an IRP to receive * data to a device. In this example we will request the driver to wait for a * ZLP after receiving the last transaction. The driver will wait for the ZLP * only if the size of the transfer is a multiple of the endpoint size. This is * not a control transfer IRP. So the setup field of the IRP will be ignored. * */ USB_HOST_IRP irp; USB_ERROR result; USB_HOST_PIPE_HANDLE bulkINPipeHandle; uint8_t data[128]; irp.data = data; irp.size = 128; irp.flags = USB_HOST_IRP_FLAG_WAIT_FOR_ZLP ; irp.userData = &someApplicationObject; irp.callback = IRP_Callback; result = DRV_USBFS_HOST_IPRSubmit( bulkINPipeHandle, &irp ); USB Driver Device Mode Operation Provides information on Device mode operation. Description The USB Driver operates can operate in the Device mode when it is initialized for Device mode or Dual Role operation. When operating in Device mode, the USB Driver is also referred to as the USB Controller Driver (USBCD). In Dual-Role mode, the USB Driver will switch to USBCD mode when the USB Driver Device Attach function is called. The USB Driver Client must perform these steps to operate the USB Driver in Device mode. 1. Open the USB Driver to obtain the driver handle. 2. Set the event handler. 3. Wait for the application to attach the device to the bus. 4. Enable Endpoint 0 and respond to USB Host Enumeration requests. 5. Allow the application and function drivers to enable other endpoints and communicate with the Host. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1168 The following sections discuss these operations in more detail. General Device Mode Operations Provides information on general Device mode operations. Description This section describes the USBCD operations such as setting event handlers and attaching and detaching the device. Handling Device Mode Driver Events The Device Layer will call the USBCD eventHandlerSet function to register the Device mode event handling function. The USBCD generates various events that indicate different states of the USB. These events are defined by the DRV_USB_EVENT enumeration. The following code example shows how the Device Layer registers the driver event handling function. /* This code example shows the implementation of the USB_DEVICE_Attach and the * USB_DEVICE_Detach function. These functions are actually macro that map * directly deviceAttach and the deviceDetach function of the driverInterface * member of the deviceClient Object (which is the macro parameter) */ #define USB_DEVICE_Attach( x ) ((USB_DEVICE_OBJ *)x)->driverInterface->deviceAttach ( ((USB_DEVICE_OBJ *)(x))->usbCDHandle) #define USB_DEVICE_Detach( x ) ((USB_DEVICE_OBJ *)x)->driverInterface->deviceDetach ( ((USB_DEVICE_OBJ *)x)->usbCDHandle) If the driver is operating in interrupt mode, the client event handling function will execute in an interrupt context. The client should not call interrupt unsafe, computationally intensive or blocking functions in the event handler. The following code shows a small example of the Device Layer USBCD Event Handler: /* This code example shows a partial implementation of the USB Device Layer * event handler. Note how the code type casts the referenceHandle parameter to * a USB_DEVICE_OBJ type. This referenceHandle is the same value that the Device * Layer passed when the event handler was set. This now easily allows one * implementation of the event handling code to be used by multiple Device * Layer instances. */ void _USB_DEVICE_EventHandler ( uintptr_t referenceHandle, DRV_USB_EVENT eventType, void * eventData ) { USB_DEVICE_OBJ* usbDeviceThisInstance; USB_DEVICE_MASTER_DESCRIPTOR * ptrMasterDescTable; USB_DEVICE_EVENT_DATA_SOF SOFFrameNumber; usbDeviceThisInstance = (USB_DEVICE_OBJ *)referenceHandle; /* Handle events, only if this instance is in initialized state */ if( usbDeviceThisInstance->usbDeviceInstanceState <= SYS_STATUS_UNINITIALIZED ) { /* The device should anyway not be attached when the Device Layer is * not initialized. If we receive driver event when the Device Layer is * not initialized, there is nothing we can do but ignore them. */ return; } switch(eventType) { case DRV_USB_EVENT_RESET_DETECT: /* Clear the suspended state */ usbDeviceThisInstance->usbDeviceStatusStruct.isSuspended = false; /* Cancel any IRP already submitted in the RX direction. */ DRV_USB_DEVICE_IRPCancelAll( usbDeviceThisInstance->usbCDHandle, controlEndpointRx ); /* Code not shown for the sake of brevity. */ Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1169 } } In the previous code example, the Device Layer (the Driver Client) sets the hReferenceData parameter, of the Event Handler Set function, to point to a local object. This pointer is returned to the Device Layer, in the event handler when an event occurs. For multiple instances of USB drivers in one application, this allows the Device Layer to easily associate a Device Layer specific context to the driver instance, thus simplifying implementation of the event handler. Attaching and Detaching the Device The USB Device Layer calls the USBCD deviceAttach and deviceDetach functions to attach and detach the device on the USB. The USB Device Layer should be ready to handle events which would occur when the device is attached on the bus. Hence the USB Device Layer should register the USBCD event handler before the attach function is called. The deviceAttach and deviceDetach functions can be called in an interrupt context. These functions are respectively called when the USB Device application detects a valid VBUS voltage and when the VBUS voltage is not valid. Setting the Device Address The USB Device Layer will call the USBCD deviceAddressSet function to set the USB address of the device. The Device Layer will do this when it receives the Set Address control request from the Host. The USBCD will reset the device address to '0' when it has received reset signaling from the root hub. The following code example shows how the USB Device Layer calls this function. /* The following code example shows how the USB Device Layer calls the * DRV_USB_DEVICE_AddressSet function to set the address. The * DRV_USB_DEVICE_AddressSet function is actually a macro that calls the * deviceAddressSet function of the driverInterface of usbDeviceThisInstance * object. The usbDeviceThisInstance is Device Layer object. * * As seen in this code, the Device Layer calls the address set function when * the it a pending set address control request from the Host has completed. */ void _USB_DEVICE_Ep0TransmitCompleteCallback(USB_DEVICE_IRP * handle) { USB_DEVICE_IRP * irpHandle = (USB_DEVICE_IRP *)handle; USB_DEVICE_OBJ * usbDeviceThisInstance; USB_DEVICE_CONTROL_TRANSFER_STRUCT * controlTransfer; usbDeviceThisInstance = (USB_DEVICE_OBJ *)irpHandle->userData; controlTransfer = &(usbDeviceThisInstance->controlTransfer); if(irpHandle->status == USB_DEVICE_IRP_STATUS_ABORTED) { return; } if(usbDeviceThisInstance->usbDeviceStatusStruct.setAddressPending) { DRV_USB_DEVICE_AddressSet(usbDeviceThisInstance->usbCDHandle, usbDeviceThisInstance->deviceAddress); usbDeviceThisInstance->usbDeviceStatusStruct.setAddressPending = false; } /* Code not shown for the sake of brevity */ } Device Current Speed and SOF Number The USB Device Layer will call the USBCD deviceCurrentSpeedGet function to know the speed at which the device is attached to the USB. This allows the Device Layer to select the correct endpoint settings at the time of processing the Set Configuration request issued by the Host. The USB Device Layer will call the deviceSOFNumberGet function to return the SOF number at the time of the SOF event. Device Remote Wake-up The USB Device Layer will call the USBCD deviceRemoteWakeupStop and deviceRemoteWakeupStart functions to stop and start remote signaling. The Device layer application will call the USB Device Layer Stop and Start Remote Wakeup Signaling functions to remotely let the root hub know that the device is ready to be woken up. The timing of the remote signaling is controlled by the Device Layer. The client should call the remote wakeup function only when the device is suspended by the Host. Device Endpoint Operations Provides information on Device Endpoint operations. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1170 Description The UBSCD Endpoint functions allow the Driver Client to enable, disable, stall and clear the stall condition on an endpoint. The client submits requests to transmit and receive data from the USB Host on an endpoint. Endpoint Enable and Disable functions The USBCD client must enable an endpoint it must use the endpoint for communicating with the USB Host. The client will call the USBCD deviceEndpointEnable function to enable the endpoint. While calling this function, the client must specify the endpoint address, the transfer type to be processed on this endpoint and the maximum size of a transaction on this endpoint. This function is thread-safe when called in an RTOS application. The USBCD allows an endpoint to be accessed by one thread only. The USB Device Layer and the device function drivers will enable the endpoint when the Host sets the device configuration. The USBCD deviceEndpointIsEnabled function is available to check if an endpoint is enabled. The following code example shows how the USB Device Layer enables the device endpoint. /* The following code example shows the USB Device Layer enables Endpoint 0 to * prepare for the enumeration process after it has received reset signaling * from the Host. The Device Layer calls the deviceEndpointEnable function to * to enable the endpoint. The driverInterface member of the * usbDeviceThisInstance structure points to the USB Device Mode Driver Common * Interface. */ void _USB_DEVICE_EventHandler ( uintptr_t referenceHandle, DRV_USB_EVENT eventType, void * eventData ) { /* Code not shown due to space constraints */ switch(eventType) { case DRV_USB_EVENT_RESET_DETECT: /* Clear the suspended state */ usbDeviceThisInstance->usbDeviceStatusStruct.isSuspended = false; /* Cancel any IRP already submitted in the RX direction. */ DRV_USB_DEVICE_IRPCancelAll( usbDeviceThisInstance->usbCDHandle, controlEndpointRx ); /* Cancel any IRP already submitted in the TX direction. */ DRV_USB_DEVICE_IRPCancelAll( usbDeviceThisInstance->usbCDHandle, controlEndpointTx ); /* Deinitialize all function drivers.*/ _USB_DEVICE_DeInitializeAllFunctionDrivers ( usbDeviceThisInstance ); /* Disable all endpoints except for EP0.*/ DRV_USB_DEVICE_EndpointDisableAll(usbDeviceThisInstance->usbCDHandle); /* Enable EP0 endpoint in RX direction */ (void)usbDeviceThisInstance->driverInterface->deviceEndpointEnable (usbDeviceThisInstance->usbCDHandle, controlEndpointTx, USB_TRANSFER_TYPE_CONTROL, USB_DEVICE_EP0_BUFFER_SIZE); /* Code not shown due to space constraints */ break; } } The USB Device Layer and the Function drivers will disable an endpoint when the Host sets a zero-device configuration or when the Host resets the device. The USBCD deviceEndpointDisable function disables an endpoint. When an endpoint is disabled, it does not accept requests for Host communication. Disabling an endpoint does not cancel any communication requests that that have been submitted on the endpoint. These requests must be canceled explicitly. Device Endpoint Stall and Stall Clear The USBCD client can call the deviceEndpointStall and deviceEndpointStallClear functions to stall and cleat the stall on an endpoint respectively. The USB Device Layer and function driver may stall endpoint to indicate error or to indicate a protocol state. The endpoint stall condition may be Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1171 cleared in response to a USB Host Clear Feature request. Stalling or clearing the stall on an endpoint will cause all communication requests on the endpoint to be canceled. The function calls are thread safe and interrupt safe. The deviceEndpointIsStalled function is also available to check if an endpoint is in a stalled state. The following code example shows how the USB Device Layer calls these functions to stall and clear the stall on an endpoint. /* The following code example shows how the USB Device Layer calls the driver * endpoint stall function (deviceEndpointStall) to stall an endpoint when the a * Host send a Set Feature request with feature selector set to endpoint halt. * The endpoint to be halted is identified in the setup packet and is identified * in this code example as usbEndpoint. Also shown is how the stall clear * (deviceEndpointStallClear) and stall status check (deviceEndpointIsStalled) * functions are called. */ /* The driverInterface member of the usbDeviceThisInstance structure is a * pointer to the USB Driver Common Interface. */ void _USB_DEVICE_ProcessStandardEndpointRequest ( USB_DEVICE_OBJ * usbDeviceThisInstance, uint8_t interfaceNumber, USB_SETUP_PACKET * setupPkt ) { USB_ENDPOINT usbEndpoint; usbEndpoint = setupPkt->bEPID; if( setupPkt->bRequest == USB_REQUEST_GET_STATUS ) { usbDeviceThisInstance->getStatusResponse.status = 0x00; usbDeviceThisInstance->getStatusResponse.endPointHalt = usbDeviceThisInstance->driverInterface->deviceEndpointIsStalled (usbDeviceThisInstance->usbCDHandle, usbEndpoint ); USB_DEVICE_ControlSend( (USB_DEVICE_HANDLE)usbDeviceThisInstance, (uint8_t *)&usbDeviceThisInstance->getStatusResponse, 2 ); } else if( setupPkt->bRequest == USB_REQUEST_CLEAR_FEATURE ) { if( setupPkt->wValue == USB_FEATURE_SELECTOR_ENDPOINT_HALT ) { usbDeviceThisInstance->driverInterface->deviceEndpointStallClear (usbDeviceThisInstance->usbCDHandle, usbEndpoint ); USB_DEVICE_ControlStatus((USB_DEVICE_HANDLE)usbDeviceThisInstance, USB_DEVICE_CONTROL_STATUS_OK ); } } else if (setupPkt->bRequest == USB_REQUEST_SET_FEATURE ) { if( setupPkt->wValue == USB_FEATURE_SELECTOR_ENDPOINT_HALT ) { usbEndpoint = setupPkt->bEPID; usbDeviceThisInstance->driverInterface->deviceEndpointStall (usbDeviceThisInstance->usbCDHandle, usbEndpoint ); USB_DEVICE_ControlStatus((USB_DEVICE_HANDLE)usbDeviceThisInstance, USB_DEVICE_CONTROL_STATUS_OK ); } } /* Additional code is not shown due to space constraints */ } Transferring Data to the Host Provides information on transferring data to the Host. Description The USB Device Layer, the USBCD client, needs to transfer data to the Host in response to enumeration requests for general operation on the device. The USB uses a concept of Input Output Request Packet (IRP) to transfer data to and from the Host. IRPs are transported over endpoints which are enabled by calling the USBCD Endpoint Enable function. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1172 A Device IRP is a USB_DEVICE_IRP type data structure. The IRP is created by the Device Layer and submitted to the USBCD for processing through the deviceIRPSubmit function. At the time of submitting the IRP, the endpoint over which the IRP must be transported is specified. The data request in the IRP is transported using the attributes of the endpoint. When an IRP is submitted to the USBCD, it is owned by the USBCD and cannot be modified by the Device Layer until the USBCD issues an IRP callback. The USBCD will issue the IRP callback when it has completed or terminated processing of the IRP. An IRP does not have its own transfer type. It inherits the properties of the endpoint to which it is submitted. Hence an IRP becomes a control transfer IRP it was submitted to a control endpoint. An endpoint allows multiple IRPs to be queued. This allows the Device Layer to submit IRPs to an endpoint even while an IRP is being processed on the endpoint. The USBCD will process an IRP in the order that it was received. The following code example shows the USB_DEVICE_IRP data structure: /* This code example shows the USB_DEVICE_IPR structure. The Device Layer * uses such a structure to transfer data through the driver. A structure of * this type is allocated by the Device Layer and the other function drivers and * passed to the deviceIRPSubmit function. */ typedef struct _USB_DEVICE_IRP { /* Pointer to the data buffer */ void * data; /* Size of the data buffer */ unsigned int size; /* Status of the IRP */ USB_DEVICE_IRP_STATUS status; /* IRP Callback. If this is NULL, then there is no callback generated */ void (*callback)(struct _USB_DEVICE_IRP * irp); /* Request specific flags */ USB_DEVICE_IRP_FLAG flags; /* User data */ uintptr_t userData; /*********************************** * The following members should not * be modified by the client ***********************************/ uint32_t privateData[3]; } USB_DEVICE_IRP; The data member of the USB_DEVICE_IRP structure points to a data buffer. This data buffer will contain the data that needs to be sent to the Host for the data stage of an IN transfer. For an OUT transfer, it will contain the data that was received from the Host. Any hardware specific cache coherency and address alignment requirements must be considered while allocating this data buffer. The Driver Client should not modify or examine the contents of the IRP after the IRP has been submitted and is being processed. It can be examined after the driver has released the IRP. The size member of the USB_DEVICE_IRP structure specifies the size of the data buffer. The transfer will end when the device has sent or received size number of bytes. While sending data to the Host, the IRP size can exceed the size of the transaction (which is equal to the size of the endpoint). The USBCD in such a case will split up the transfer into transactions. This process does not require external intervention. The driver uses receive and transmit IRPs to process control transfers. When the driver receives a Setup packet, the IRP completion status would be USB_DEVICE_IRP_STATUS. The Driver Client should then use additional receive and transmit IRPs to complete the control transfer. For interrupt and isochronous transfers, the size of transfer specified in the IRP cannot exceed the size of the transaction. If size is specified as 0, then the driver will send or expect a zero length packet. The size parameter of the IRP is updated by the driver when IRP processing is completed. This will contain the size of the completed transfer. The status member of the IRP provides the completion status of the IRP and should be checked only when the IRP processing has completed. This is indicated by the driver calling the IRP callback function. The IRP status is a USB_DEVICE_IRP_STATUS type. The following code example shows the different possible values of the status member and example usage of IRPs to transfer data between the device and the Host. /* The followoing code shows example usage of the device IRP. The submit status * of the IRP is available when IRP submit function returns. The completion * status of the IRP is available when the IRP has terminated and the IRP * callback function is invoked. The IRP callback * function shown in this example shows the possible complete status of the IRP. * The end application may or may not handle all the cases. Multiple IRPs can be * queued on an endpoint. */ void IRP_Callback(USB_DEVICE_IRP * irp) { Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1173 /* irp is pointing to the IRP for which the callback has occurred. In most * cases this function will execute in an interrupt context. The application * should not perform any hardware access or interrupt unsafe operations in * this function. */ switch(irp->status) { case USB_DEVICE_IRP_STATUS_TERMINATED_BY_HOST: /* The IRP was aborted because the Host cleared the stall on the * endpoint */ break; case USB_DEVICE_IRP_STATUS_ABORTED_ENDPOINT_HALT: /* IRP was aborted because the endpoint halted */ break; case USB_DEVICE_IRP_STATUS_ABORTED: /* USB Device IRP was aborted by the function driver */ break; case USB_DEVICE_IRP_STATUS_ERROR: /* An error occurred on the bus when the IRP was being processed */ break; case USB_DEVICE_IRP_STATUS_COMPLETED: /* The IRP was completed */ break; case USB_DEVICE_IRP_STATUS_COMPLETED_SHORT: /* The IRP was completed but the amount of data received was less * than the requested size */ break; default: break; } } /* In the following example, the IRP is submitted to Endpoint 0x84. This is * interpreted as an IN direction endpoint (MSB of 0x84 is 1) and Endpoint 4. * The data contained in source will be sent to the USB Host. Assuming * the endpoint size is 64, the 130 bytes of data in this case will be sent to * the Host in three transaction of 64, 64 and 2 bytes. A transaction completes * when the Host polls (sends an IN token) the device. The callback function * will then called indicating the completion status of the IRP. The application * should not modify the privateData field of the IRP. If the IRP was submitted * successfully, the buffer will be owned by the driver until the IRP callback * function has been called. Because the size of the transfer is not a multiple * of the endpoint size, the IRP flag must be set * USB_DEVICE_IRP_FLAG_DATA_COMPLETE. This directs the driver to not perform any * explicit signaling to the Host to indicate end of transfer. The last packet * in this case is a short packet and this signals the end of the transfer. */ USB_DEVICE_IRP irp; USB_ERROR result; uint8_t source[130]; irp.data = source; irp.size = 130; irp.called = IRP_Callback; flags = USB_DEVICE_IRP_FLAG_DATA_COMPLETE; userData = &someApplicationObject; result = DRV_USBFS_DEVICE_IRPSubmit(driverHandle, 0x84, &irp); switch(result) { Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1174 case USB_ERROR_PARAMETER_INVALID: /* This can happen if the driverHandle is invalid */ break; case USB_ERROR_DEVICE_IRP_IN_USE: /* This can happen if the IRP is being resubmitted while it is still in * process (it was submitted before but processing has not completed */ break; case USB_ERROR_DEVICE_ENDPOINT_INVALID; /* The endpoint to which this IRP is being submitted is not provisioned * in the system. This is controller by DRV_USBFS_ENDPOINTS_NUMBER * configuration parameter. */ break; case USB_ERROR_ENDPOINT_NOT_CONFIGURED: /* The endpoint to which this IRP is being submitted is not enabled. It * must be enabled by calling the DRV_USBFS_DEVICE_EndpointEnable() * function. */ break; case USB_ERROR_PARAMETER_INVALID: /* The USB_DEVICE_IRP_FLAG_DATA_PENDING flag was specified but the * transfer size is not a multiple of the endpoint size. If the IRP was * submitted to a receive endpoint, this error can occur if the size is * not a multiple of the endpoint size. */ break; case USB_ERROR_OSAL_FUNCTION: /* An error occurred while trying to grab a mutex. This is applicable * when the driver is running with a RTOS. */ break; case USB_ERROR_NONE: /* The IRP was submitted successfully. */ break; default: break; } /* The following code example shows how an IRP is submitted to an OUT endpoint. * In this case data will be pointing to a buffer where the received data will * be stored. Note that the size of the IRP should be a multiple of the endpoint * size. The flags parameter is ignored in the data receive case. The IRP * terminates when the specified size of bytes has been received (the Host sends * OUT packets) or when a short packet has been received. */ USB_DEVICE_IRP irp; USB_ERROR result; uint8_t destination[128]; irp.data = destination; irp.size = 128; irp.called = IRP_Callback; userData = &someApplicationObject; result = DRV_USBFS_DEVICE_IRPSubmit(driverHandle, 0x04, &irp); For IRPs submitted to an Interrupt or Isochronous endpoints, the driver will always send either the less than or equal to the maximum endpoint packet size worth of bytes in a transaction. The application could either submit an IRP per Interrupt/Isochronous polling interval or it could submit one IRP for multiple polling intervals. The flags member of the USB_DEVICE_IRP structure specifies flags which affect the behavior of the IRP. The USB_DEVICE_IRP_FLAG enumeration specifies the available option. The USB_DEVICE_IRP_FLAG_DATA_COMPLETE causes the driver to add a Zero Length Packet (ZLP) to the data stage of the IN transfer when the transfer size is an exact multiple of the endpoint size. If the transfer size is not a multiple of the endpoint size, no ZLP will be sent. The USB_DEVICE_IRP_FLAG_PENDING flag will cause the driver to not send a ZLP in a case where the size of the IN transfer is an exact multiple of the endpoint size. The following code example demonstrates this. /* In the following code example, the IRP is submitted to an IN endpoint whose size * is 64. The transfer size is 128, which is an exact multiple of the endpoint Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1175 * size. The flag is set to USB_DEVICE_IRP_FLAG_DATA_COMPLETE. The driver * will send two transactions of 64 bytes each and will then automatically send a * Zero Length Packet (ZLP), thus completing the transfer. The IRP callback will * be invoked when the ZLP transaction has completed. */ USB_DEVICE_IRP irp; USB_ERROR result; uint8_t source[128]; irp.data = source; irp.size = 128; irp.called = IRP_Callback; flags = USB_DEVICE_IRP_FLAG_DATA_COMPLETE; userData = &someApplicationObject; result = DRV_USBFS_DEVICE_IRPSubmit(driverHandle, 0x84, &irp); /* In the following code example, the IRP is submitted to an IN endpoint whose size * is 64. The transfer size is 128, which is an exact multiple of the endpoint * size. The flag is set to to USB_DEVICE_IRP_FLAG_DATA_PENDING. The driver will * send two transactions of 64 bytes each but will not send a ZLP. The USB Host * can then consider that there is more data pending in the transfer. The IRP * callback will be invoked when the two transactions have completed. */ USB_DEVICE_IRP irp; USB_ERROR result; uint8_t source[128]; irp.data = source; irp.size = 128; irp.called = IRP_Callback; flags = USB_DEVICE_IRP_FLAG_DATA_COMPLETE; userData = &someApplicationObject; result = DRV_USBFS_DEVICE_IRPSubmit(driverHandle, 0x84, &irp); The callback member of the USB_DEVICE_IRP structure points to a function which the driver calls when the IRP processing is completed. The Driver Client must implement this function and assign the pointer to this function to the callback member of the IRP. Every IRP can have its own callback function or one common callback function could be used. The callback function will execute in an interrupt context. The Driver Client should not execute interrupt unsafe, blocking or computationally intensive operations in the callback function. The client can call deviceIRPSubmit function in the IRP callback function to submit another IRP or resubmit the same IRP. The client can check the status and size of the IRP in the callback function. The userData member of the USB_DEVICE_IRP structure can be used by the client to associate a client specific context with the Host. This context can then be used by the client, in the IRP callback function to identify the context in which the IRP was submitted. This member is particularly useful if the client wants to implement one callback function for all IRPs. The privateData member of the IRP is used by the driver and should not be accessed or manipulated by the Driver Client. PIC32MX USB Driver Provides information on the USB Driver specific to PIC32MX devices. Description The PIC32MX USB Driver in MPLAB Harmony provides API functions that allow the MPLAB Harmony USB Host and Device Stack to access the USB while operating on a PIC32MX microcontroller. The driver implements the USB Driver Common Interface required by the USB Host and Device Stack. It abstracts the USB module operational details from the Host and Device Stack and provides the stacks with a modular access mechanism to the USB. The PIC32MX USB Driver features the following: • USB 2.0 Full Speed operation in Peripheral mode • USB 2.0 Full Speed and Low Speed USB Peripheral Support in Host mode • Designed for Dual Role Operation • Capable of operating multiple USB modules • Features non-blocking function and is interoperable with other MPLAB Harmony modules • Features thread safe functions when operating within an RTOS • Capable of operating in Polled and Interrupt modes • Implements the USB Driver Common Interface required by the MPLAB Harmony USB Host and Device Stack • Completely configurable through MPLAB Harmony Configurator (MHC) tool • Implements feature separation (Host and Device mode functions are implemented across different files) Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1176 Note: This help section only discusses features that are unique to the PIC32MX USB Driver and are not a part of the USB Driver Common Interface. The driver functions that implement the USB Driver Common Interface are described in the Common Interface Help section. While the PIC32MX USB module supports USB "On-The-Go" (OTG), this release of the PIC32MX Driver does not implement USB OTG protocol support. This help section only provides relevant information about the operation of the USB. The reader is encouraged to refer to the USB 2.0 Specification available at www.usb.org for a detailed explanation of USB protocol. Using the Library This topic describes the basic architecture of the PIC32MX USB Driver Library and provides information and examples on its use. Description Interface Header File: drv_usbfs.h The interface to the PIC32MX USB Driver library is defined in the drv_usbfs.h header file. Please refer to the What is MPLAB Harmony? section for how the Driver interacts with the framework. Library Overview Provides an overview of the library. Description The PIC32MX USB Driver will typically be used by a USB Host and/or Device Stack. The USB Host and Device Stack operate as driver client applications. The driver is initialized as part of the MPLAB Harmony System Initialization. The driver initialization data structure specifies the operation mode (Host, Device, or Dual Role) of the driver. The driver features task routines to be called in the MPLAB Harmony application tasks function (SYS_Tasks function) and the USB Module Interrupt Service Routine (ISR). The Host and the Device Stack can open the driver only when initialization has completed. It will continue to return an invalid driver handle while the initialization is in progress. Once opened, the Device Mode function can be called if the driver is operating in Device mode. The Host Mode function can be called if the driver is operating in Host mode. In Dual Role operation mode, the driver supports Host and Device operation in the same application. Even then, the driver will either operate as a USB Host or Device. OTG operation is not supported. The PIC32MX USB Driver features RTOS thread-safe functions. This allows the driver client application to safely call driver functions across different RTOS threads. Not all of the driver functions are interrupt-safe. In addition to the USB Driver, which implements the USB Driver Common Interface, the PIC32MX USB Driver implements functions which are required for its operation in the MPLAB Harmony framework. The following table lists the different categories of functions in the PIC32MX USB Driver. Library Interface Section Description System Function These functions are accessed by the MPLAB Harmony System module. They allow the driver to be initialized, deinitialized and maintained. These functions are implemented in the drv_usbfs.c source file. Client Core Functions These functions allow the USB Host and Device Stack to open, close and perform other general driver operations. These functions are a part of the USB Driver Common Interface and are implemented in drv_usbfs.c source file. Device Mode Operation Functions These functions allow the USB Device Stack to perform USB Device mode specific driver operations. These functions are a part of the USB Driver Common Interface and are implemented in drv_usbfs_device.c source file Host Mode Operation Functions These functions allow the USB Host Stack to perform USB Host mode specific driver operations. These functions are a part of the USB Driver Common Interface and are implemented in drv_usbfs_host.c source file. Root Hub Functions These functions allow the USB Host Stack to access the driver Root hub operation. These functions are a part of the USB Driver Common Interface and are implemented in drv_usbfs_host.c source file. Abstraction Model Provides information on the abstraction model for the library. Description The PIC32MX USB Driver implements the abstraction model defined by the USB Driver Common interface. This interface abstracts USB module specific details and provides a module independent interface to the driver client applications. While operating in Device mode, the driver expects the client application (the USB Device Stack) to enable endpoints and then submit I/O request Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1177 packet (IRP) requests to the enabled endpoints. Multiple IRPs can be queued on an endpoint. The driver calls the IRP callback function when the IRP is processed. The driver allows the client application to also attach and detach the device on the bus. It generates events which indicate USB states. While operating in Host mode, the driver expects the client application (the USB Host Stack) to open pipes to endpoints on the connected device. The client application can then submit IRPs to the pipes. Multiple IRPs can be queued on a pipe. The driver calls the IRP callback function when the IRP is processed. The driver will call application defined functions to enumerate and denumerate a device. These functions are called when the driver detect device attach and detach respectively. The driver also exports root hub functions to the client application. This allows the client application to treat the driver as a single port hub Please refer to the PIC32 USB Driver Common Interface help section for more details on the driver abstraction model. How the Library Works Provides information on how the library works. Description This section only explains aspects of driver operation which are unique to the PIC32MX USB Driver. Major driver operations are described in the PIC32 USB Driver Common Interface help section. Driver Initialization Note: While generating a MPLAB Harmony USB project with MHC, the initialization code for the driver is generated automatically based on selections made in the USB Host stack or Device Stack Configuration trees. The PIC32MX USB Driver must be initialized so that a client application can open. The client application will not be able to open the driver if the initialization is in progress or has failed. The driver is initialized by calling the DRV_USBFS_Initialize function. This function is called from the SYS_Initialize function in the MPLAB Harmony application project and accepts two input parameters. The index parameter defines the instance of the USB Driver to be initialized. This becomes significant when the PIC32MX microcontroller has more than one USB module. The init parameter is a driver specific data structure of the type DRV_USBFS_INIT. This structure is shown in the following code example. /* This code snippet show the PIC32MX USB Driver Initialization data structure. * A structure of this type must be provided to the DRV_USBFS_Initialize() * function. */ typedef struct { /* System Module Initialization */ SYS_MODULE_INIT moduleInit; /* Identifies the USB peripheral to be used. This should be the USB PLIB module instance identifier. */ uint8_t usbID; /* This should be set to true if the USB module must stop operation in IDLE mode */ bool stopInIdle; /* This should be set to true if the USB module must suspend when the CPU enters sleep mode. */ bool suspendInSleep; /* Specify the interrupt source for the USB module. This should be Interrupt PLIB Interrupt source identifier for the USB module instance specified in usbID. */ INT_SOURCE interruptSource; /* Specify the operational speed of the USB module. This should always be set to USB_SPEED_FULL. The use of this parameter is deprecated. */ USB_SPEED operationSpeed; /* Specify the operation mode of the USB module. This defines if the USB * module will support Device, Host or Dual Role operation */ DRV_USBFS_OPMODES operationMode; /* A pointer to the endpoint descriptor table. This should be aligned at 512 byte address boundary. The size of the table is equal to the DRV_USBFS_ENDPOINT_TABLE_ENTRY_SIZE times the number of endpoints needed in the application. */ void * endpointTable; Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1178 /* Root hub available current in mA. This specifies the amount of current that root hub can provide to the attached device. This should be specified in mA. This is required when the driver is required to operate in host mode. */ uint32_t rootHubAvailableCurrent; /* When operating in Host mode, the application can specify a Root Hub port enable function. This parameter should point to Root Hub port enable function. If this parameter is NULL, it implies that the Port is always enabled. */ DRV_USBFS_ROOT_HUB_PORT_POWER_ENABLE portPowerEnable; /* When operating in Host mode, the application can specify a Root Port Indication. This parameter should point to the Root Port Indication function. If this parameter is NULL, it implies that Root Port Indication is not supported. */ DRV_USBFS_ROOT_HUB_PORT_INDICATION portIndication; /* When operating is Host mode, the application can specify a Root Port Overcurrent detection. This parameter should point to the Root Port Indication function. If this parameter is NULL, it implies that Overcurrent detection is not supported. */ DRV_USBFS_ROOT_HUB_PORT_OVER_CURRENT_DETECT portOverCurrentDetect; } DRV_USBFS_INIT; The operationMode parameter defines by the driver operation mode. parameter in the initialization data structure. This can be set DRV_USBFS_OPMODE_DEVICE, DRV_USBFS_OPMODE_HOST or DRV_USBFS_OPMODE_DUAL_ROLE for device, host and dual role operation respectively. The endpointTable parameter must point to a byte array. The size of the array depends on the maximum number of device endpoints that application needs. A direction of an endpoint counts as one endpoint. Each endpoint requires 32 bytes. Therefore, if the USB Device requires 3 endpoints (Endpoint 0 + Endpoint 1 IN + Endpoint 2 OUT), the size of the array will 96 bytes (32 * 3). The byte array start address must be located on a 512 byte boundary. When operating in host mode, the driver will use only one endpoint and size of the endpoint table array should be set to 32. The rootHubAvailableCurrent parameter should be set to the maximum current that VBUS power supply can provide on the bus. The driver does not use this information directly. It provides this data to the client application while operating in host mode. The portPowerEnable parameter must point to a Port Power Enable function. The driver, while operating in host mode, will call this function to enable the VBUS switch. This function should activate the VBUS switch if the driver calls this function with the enable parameter set to true. It should deactivate the switch if the driver calls this function with the enable parameter set to false. This parameter should be set to NULL if such a switch (of the switch control) is not available in the application. The portIndication parameter must point to a Port Indication function. The driver, while operating in host mode, will call this function to indicate the current state of the port. The driver will call this function with LED color status as defined in the Chapter 11 of the USB 2.0 Specification. This parameter should be set to NULL if such a LED indication is not available in the application. The portOverCurrentDetect parameter must point to a Port Overcurrent Detect function. The driver, while operating in Host mode, will call this function periodically to check if the attached device is overdrawing current. If the function should return true if such a condition exists. This parameter should be set to NULL if such detection is not available in the application. The following code example shows initialization of the driver for device mode operation. /* This code shows an example of DRV_USBFS_INIT data structure for * device mode operation. Here the driver is initialized to work with USB1 USB * module. Note how the endPointTable is defined. It should be aligned on a 512 * byte boundary. */ DRV_USBFS_INIT init; SYS_MODULE_OBJ usbDriverObj; uint8_t __attribute__((aligned(512))) endPointTable[DRV_USBFS_ENDPOINTS_NUMBER * 32]; const DRV_USBFS_INIT drvUSBInit = { /* Assign the endpoint table */ .endpointTable = endPointTable, /* Interrupt Source for USB module */ .interruptSource = INT_SOURCE_USB_1, /* System module initialization. */ .moduleInit = {SYS_MODULE_POWER_RUN_FULL}, Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1179 /* Configure the driver for device mode operation. */ .operationMode = DRV_USBFS_OPMODE_DEVICE, /* Configure the driver to operate at full speed. */ .operationSpeed = USB_SPEED_FULL, /* Stop in idle */ .stopInIdle = false, /* Suspend in sleep */ .suspendInSleep = false, /* Identifies peripheral (PLIB-level) ID */ .usbID = USB_ID_1 }; void SYS_Initialize(void) { /* Initialize the USB Driver. Note how the init parameter is typecasted to * SYS_MODULE_INIT type. The SYS_MODULE_OBJ returned by this function call * is passed to the driver tasks routine. DRV_USBFS_INDEX_0 is helper * constant defined in drv_usbfs.h */ usbDriverObj = DRV_USBFS_Initialize(DRV_USBFS_INDEX_0, (SYS_MODULE_INIT *)(drvUSBInit)); } void SYS_Tasks(void) { /* The polled state of the USB driver is updated by calling the * DRV_USBFS_Tasks function in the SYS_Tasks() function. The * DRV_USBFS_Tasks() takes the driver module object returned by the * DRV_USBFS_Initialize funciton as a parameter. */ DRV_USBFS_Tasks(usbDriverObj); } void __ISR(_USB_1_VECTOR, ipl4AUTO) _IntHandlerUSBInstance0(void) { /* The DRV_USBFS_Tasks_ISR function update the interrupt state of the USB * Driver. If the driver is configured for polling mode, this function need * not be invoked or included in the project. */ DRV_USBFS_Tasks_ISR(sysObj.drvUSBObject); } The following code example shows initialization of the driver for host mode operation. /* This code shows an example of the USBFS driver can be configured for * host mode operation. For host mode operation, only one endpoint is needed and * hence the size of the endpoint table is 32 bytes (for one endpoint). In this * example, the BSP_USBVBUSSwitchOverCurrentDetect function checks for over * current condition and the BSP_USBVBUSPowerEnable function enables the VBUS * power. The port indication function is not implemented and hence the * portIndication member of the initialization data structure is set to NULL. */ /* The implementation of the port over current detect, indication and the VBUS * power supply functions is discussed later in this help section. */ uint8_t __attribute__((aligned(512))) endpointTable[32]; DRV_USBFS_INIT drvUSBFSInit = { /* Pointer to the endpoint table */ .endpointTable = endpointTable, /* Interrupt Source for the USB module */ .interruptSource = INT_SOURCE_USB_1, /* This should always be set to SYS_MODULE_POWER_RUN_FULL. */ .moduleInit = {SYS_MODULE_POWER_RUN_FULL}, Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1180 /* Configure for host mode operation. */ .operationMode = DRV_USBFS_OPMODE_HOST, /* The driver should run at full speed. */ .operationSpeed = USB_SPEED_FULL, /* Port indication function is not implemented. */ .portIndication = NULL, /* This is the over current detect function. */ .portOverCurrentDetect = BSP_USBVBUSSwitchOverCurrentDetect, /* This is the VBUS Power enable function */ .portPowerEnable = BSP_USBVBUSPowerEnable, /* Here we state that the VBUS power supply can provide at most 500 mA of * current */ .rootHubAvailableCurrent = 500, /* Module will operate in IDLE. */ .stopInIdle = false, /* Module will not suspend automatically in sleep */ .suspendInSleep = false, /* USB Module ID is 1 */ .usbID = USB_ID_1 }; void SYS_Initialize(void) { /* Initialize the USB Driver. Note how the init parameter is typecasted to * SYS_MODULE_INIT type. The SYS_MODULE_OBJ returned by this function call * is passed to the driver tasks routine. DRV_USBFS_INDEX_0 is helper * constant defined in drv_usbfs.h */ usbDriverObj = DRV_USBFS_Initialize(DRV_USBFS_INDEX_0, (SYS_MODULE_INIT *)(drvUSBInit)); } void SYS_Tasks(void) { /* The polled state of the USB driver is updated by calling the * DRV_USBFS_Tasks function in the SYS_Tasks() function. The * DRV_USBFS_Tasks() takes the driver module object returned by the * DRV_USBFS_Initialize funciton as a parameter. */ DRV_USBFS_Tasks(usbDriverObj); } void __ISR(_USB_1_VECTOR, ipl4AUTO) _IntHandlerUSBInstance0(void) { /* The DRV_USBFS_Tasks_ISR function update the interrupt state of the USB * Driver. If the driver is configured for polling mode, this function need * not be invoked or included in the project. */ DRV_USBFS_Tasks_ISR(sysObj.drvUSBObject); } The PIC32MX USB Driver requires definition of configuration constants to be available in the system_config.h file of the MPLAB Harmony Application Project Configuration. Refer to the Configuring the Library section for details. Multi-client Operation The PIC32MX USB Driver supports multi-client operation. In that, it can be opened by two application clients. This is required where Dual Operation is desired. The following should be noted when using multi-client operation: • The driver should be initialized for Dual Role Operation mode. • The DRV_USBFS_Open function can be called at the most twice in the application. The driver supports a maximum of two clients. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1181 • A client can access either the host or device functionality of the driver. It cannot do both. • It is possible for the two clients to operate in two different threads while operating with an RTOS. Note: The typical the application clients for PIC32MX USB Driver would be the MPLAB Harmony USB Host and Device Stack. The complexity of operating the driver in Dual Role mode is handled by the stack operation. The MHC will configure the driver for Dual Role operation when such operation is selected in USB Stack configuration tree. USB Driver Common Interface The PIC32MX USB Driver exports its implementation of the USB Driver Common Interface to the Host and Device Layer via the DRV_USBFS_HOST_INTERFACE and DRV_USBFS_DEVICE_INTERFACE structures. The DRV_USBFS_HOST_INTERFACE structure is defined in the drv_usbfs_host.c file. The following code example shows this structure. /********************************************************** * This structure is a set of pointer to the USBFS driver * functions. It is provided to the host and device layer * as the interface to the driver. * *******************************************************/ DRV_USB_HOST_INTERFACE gDrvUSBFSHostInterface = { .open = DRV_USBFS_Open, .close = DRV_USBFS_Close, .eventHandlerSet = DRV_USBFS_ClientEventCallBackSet, .hostIRPSubmit = DRV_USBFS_HOST_IRPSubmit, .hostIRPCancel = DRV_USBFS_HOST_IRPCancel, .hostPipeSetup = DRV_USBFS_HOST_PipeSetup, .hostPipeClose = DRV_USBFS_HOST_PipeClose, .hostEventsDisable = DRV_USBFS_HOST_EventsDisable, .hostEventsEnable = DRV_USBFS_HOST_EventsEnable, .rootHubInterface.rootHubPortInterface.hubPortReset = DRV_USBFS_HOST_ROOT_HUB_PortReset, .rootHubInterface.rootHubPortInterface.hubPortSpeedGet = DRV_USBFS_HOST_ROOT_HUB_PortSpeedGet, .rootHubInterface.rootHubPortInterface.hubPortResetIsComplete = DRV_USBFS_HOST_ROOT_HUB_PortResetIsComplete, .rootHubInterface.rootHubPortInterface.hubPortSuspend = DRV_USBFS_HOST_ROOT_HUB_PortSuspend, .rootHubInterface.rootHubPortInterface.hubPortResume = DRV_USBFS_HOST_ROOT_HUB_PortResume, .rootHubInterface.rootHubMaxCurrentGet = DRV_USBFS_HOST_ROOT_HUB_MaximumCurrentGet, .rootHubInterface.rootHubPortNumbersGet = DRV_USBFS_HOST_ROOT_HUB_PortNumbersGet, .rootHubInterface.rootHubSpeedGet = DRV_USBFS_HOST_ROOT_HUB_BusSpeedGet, .rootHubInterface.rootHubInitialize = DRV_USBFS_HOST_ROOT_HUB_Initialize, .rootHubInterface.rootHubOperationEnable = DRV_USBFS_HOST_ROOT_HUB_OperationEnable, .rootHubInterface.rootHubOperationIsEnabled = DRV_USBFS_HOST_ROOT_HUB_OperationIsEnabled, }; The DRV_USBFS_DEVICE_INTERFACE structure is defined in the drv_usbfs_device.c file. The following code example shows this structure. The MPLAB Harmony USB Host and Device stack perform driver independent access through the function pointers contained in these structures. /***************************************************** * This structure is a pointer to a set of USB Driver * Device mode functions. This set is exported to the * device layer when the device layer must use the * PIC32MX USB Controller. ******************************************************/ DRV_USB_DEVICE_INTERFACE gDrvUSBFSDeviceInterface = { .open = DRV_USBFS_Open, .close = DRV_USBFS_Close, .eventHandlerSet = DRV_USBFS_ClientEventCallBackSet, .deviceAddressSet = DRV_USBFS_DEVICE_AddressSet, .deviceCurrentSpeedGet = DRV_USBFS_DEVICE_CurrentSpeedGet, .deviceSOFNumberGet = DRV_USBFS_DEVICE_SOFNumberGet, .deviceAttach = DRV_USBFS_DEVICE_Attach, .deviceDetach = DRV_USBFS_DEVICE_Detach, .deviceEndpointEnable = DRV_USBFS_DEVICE_EndpointEnable, .deviceEndpointDisable = DRV_USBFS_DEVICE_EndpointDisable, .deviceEndpointStall = DRV_USBFS_DEVICE_EndpointStall, .deviceEndpointStallClear = DRV_USBFS_DEVICE_EndpointStallClear, .deviceEndpointIsEnabled = DRV_USBFS_DEVICE_EndpointIsEnabled, .deviceEndpointIsStalled = DRV_USBFS_DEVICE_EndpointIsStalled, .deviceIRPSubmit = DRV_USBFS_DEVICE_IRPSubmit, Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1182 .deviceIRPCancel = DRV_USBFS_DEVICE_IRPCancel, .deviceIRPCancelAll = DRV_USBFS_DEVICE_IRPCancelAll, .deviceRemoteWakeupStop = DRV_USBFS_DEVICE_RemoteWakeupStop, .deviceRemoteWakeupStart = DRV_USBFS_DEVICE_RemoteWakeupStart, .deviceTestModeEnter = NULL }; Operation with RTOS The PIC32MX USB Driver is designed to operate with a RTOS. The driver implementation uses the MPLAB Harmony Operating System Abstraction Layer (OSAL). This allows the driver to function with entire range of RTOSes supported in MPLAB Harmony. The following points must be considered while using the driver with an RTOS. • The driver can be opened from different threads • In Device mode, an enabled endpoint should only be accessed from one thread. For example, if an application requires two endpoints, Endpoint 2 and Endpoint 3, the application could contain two threads, one accessing Endpoint 2 and another accessing Endpoint 3. The thread accessing Endpoint 2 cannot access Endpoint 3. • While operating in Host mode, endpoint pipes can be opened from different threads. A pipe handle to an open pipe cannot be shared across threads. Host Mode Attach Detach Operation When the PIC32MX USB Driver operating in Host mode detects a device attach or detach, it implements debouncing before signaling attach detach signal to the USB Host Stack. When the device is attached, the driver waits for DRV_USBFS_HOST_ATTACH_DEBOUNCE_DURATION milliseconds to allow for the mechanical chatter, which occurs when the device is inserted into the host receptacle, to settle. If the device is still attached after the DRV_USBFS_HOST_ATTACH_DEBOUNCE_DURATION expires, the driver calls the USB_HOST_DeviceEnumerate function to let the host stack enumerate the device. It also starts checking for Device Detach. When the device is detached, the driver waits for DRV_USBFS_POST_DETACH_DELAY milliseconds to allow for the detach operation to settle. If the device is indeed detached after the DRV_USBFS_POST_DETACH_DELAY delay expires, the driver calls USB_HOST_DeviceDenumerate function to let the USB Host stack denumerate the device. It then starts checking for device attach. Root Hub Operation The PIC32MX USB Driver implements a Root Hub Driver Interface. This allows the driver to emulate a hub. The USB Host Stack enumerates the Root Hub as a device. The Host Stack then does not differentiate between an external hub and the root hub. While emulating a hub, the PIC32MX USB Driver Root Hub appears as a single port hub. As a part of the root hub interface, the PIC32MX USB Driver requires the application to supply functions for hub features that it does not implement. These features are: • Port Overcurrent Detect • VBUS Switch Control • Port Indication A pointer to these functions (if implemented) must be supplied through the driver initialization data (of the type DRV_USBFS_INIT) structure at the time of driver initialization. The application has the option of not implementing these functions. In such a case, the function pointers for the unimplemented function, in the initialization data structure should be set to NULL. The root hub driver must also be able to communicate the maximum current capability of its port to the USB Host Layer. The PIC32MX USB Controller does not contain built-in (hardware implemented) functionality for controlling the root hub port current. To facilitate this request, the driver will report the current capability that was specified in the rootHubAvailableCurrent parameter of the driver initialization data structure. The application must set this parameter to report the current supply capability of the VBUS power supply. The USB Host Layer uses this value to manage the bus current budget. If a connected device reports a configuration that requires more current than what the VBUS power supply can provide, the host will not set the configuration. Port Overcurrent Detect The Root Hub operation in PIC32MX USB Driver will periodically call a Port Overcurrent Detect function to detect if an overcurrent condition is active on the port. The application must supply this function if port overcurrent detection is needed. The PIC32MX USB Controller does not contain built-in (hardware implemented) functionality for checking overcurrent condition. The overcurrent condition on the port can occur in a case where the attached device has malfunctioned or when the USB VBUS line has short circuited to ground. The signature of the function and an example implementation is shown in the following code example. The function must return (and must continue to return) true if an overcurrent condition exists on the port. /* This code shows an example implementation of the * portOverCurrentDetect function. The PIC32MX USB Driver will call this * function periodically to check if an over current condition exists on the * port. In this example, we assume that the over current detect pin from an * external circuit in the system, is connected to port RD0 and the pin logic * is active high. The function must return true if an over current condition is * present on this pin */ Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1183 bool BSP_USBVBUSSwitchOverCurrentDetect(uint8_t port) { if(PLIB_PORTS_PinGet(PORTS_ID_0, PORT_CHANNEL_D, 0) == 1) { return(true); } else { return(false); } } VBUS Switch Control The PIC32MX USB Driver Root Hub operation will attempt to control the VBUS power supply to the port. Because the PIC32MX USB Controller does not contain built-in (hardware implemented) functionality for checking controlling VBUS, such a control function must be supplied by the application. The root hub operation will access this function when the PIC32MX USB Driver will call the portPowerEnable function as a part of the Bus Enable sequence. The following code shows an example of how this function can be implemented. /* This code shows an example implementation of the VBUS Power Enable * function. The PIC32MX USB Driver will call this function as a part of bus * enable function. In this example, it is assumed that system contains an * external VBUS power switch and this is control by port RB5. */ void BSP_USBVBUSPowerEnable(uint8_t port, bool enable) { if(enable) { PLIB_PORTS_PinSet(PORTS_ID_0, PORT_CHANNEL_B, PORTS_BIT_POS_5); } else { PLIB_PORTS_PinClear(PORTS_ID_0, PORT_CHANNEL_B, PORTS_BIT_POS_5); } } Port Indication function The Root Hub Operation in the PIC32MX USB Driver allows display of Port LED status. If the application requires this indication, it must implement a function which the Root Hub operation would call when a change in the Root Hub port has occurred. The port indication operation is specified in Section 11.5.3 of the USB 2.0 Specification. /* This code shows an example implementation of the port indication * function. The PIC32MX USB Driver calls this function when it wants to indicate * port status. It is assumed that three function to switch off, blink and * switch on an LED are available. It is further assumed that these function * accept the color of the LED to operated on. */ void BSP_RootHubPortIndication ( uint8_t port, USB_HUB_PORT_INDICATOR_COLOR color, USB_HUB_PORT_INDICATOR_STATE state ) { /* The color parameter indicates the color of the LED to be affected. The * color will be either USB_HUB_PORT_INDICATOR_COLOR_GREEN or * USB_HUB_PORT_INDICATOR_COLOR_AMBER. */ switch (state) { case USB_HUB_PORT_INDICATOR_STATE_OFF: BSP_SwitchLEDOff(color); break; case USB_HUB_PORT_INDICATOR_STATE_BLINKING: BSP_LEDBlink(color); break; case USB_HUB_PORT_INDICATOR_STATE_ON: BSP_SwitchLEDOn(color); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1184 break; default: break; } } Configuring the Library Provides information on the configuring the library. Macros Name Description DRV_USBFS_DEVICE_SUPPORT Determines if the USB Device Functionality should be enabled. DRV_USBFS_ENDPOINTS_NUMBER Configures the number of endpoints to be provisioned in the driver. DRV_USBFS_HOST_ATTACH_DEBOUNCE_DURATION Configures the time duration (in milliseconds) that the driver will wait to re-confirm a device attach. DRV_USBFS_HOST_NAK_LIMIT Configures the NAK Limit for Host Mode Control Transfers. DRV_USBFS_HOST_PIPES_NUMBER Configures the maximum number of pipes that are can be opened when the driver is operating in Host mode. DRV_USBFS_HOST_RESET_DURATION Configures the time duration (in milliseconds) of the Reset Signal. DRV_USBFS_HOST_SUPPORT Determines if the USB Host Functionality should be enabled. DRV_USBFS_INSTANCES_NUMBER Specifies the number of driver instances to be enabled in the application. DRV_USBFS_INTERRUPT_MODE Configures the driver for interrupt or polling mode operation. Description The PIC32MX USB Driver requires the specification of compile-time configuration macros. These macros define resource usage, feature availability, and dynamic behavior of the driver. These configuration macros should be defined in the system_config.h file. This header can be placed anywhere, 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. DRV_USBFS_DEVICE_SUPPORT Macro Determines if the USB Device Functionality should be enabled. File drv_usbfs_config_template.h C #define DRV_USBFS_DEVICE_SUPPORT true Description USB Full Speed Driver Device Mode Support. This constant should be set to true if USB device support is required in the application. It should be set to false if device support is not required. Remarks This constant should always be defined. DRV_USBFS_ENDPOINTS_NUMBER Macro Configures the number of endpoints to be provisioned in the driver. File drv_usbfs_config_template.h C #define DRV_USBFS_ENDPOINTS_NUMBER 3 Description USB Full Speed Driver Endpoint Numbers. This constant configures the number of endpoints that the driver needs to manage. When DRV_USBFS_DEVICE_SUPPORT is enabled, this Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1185 constant should be set to the total number of endpoints to be enabled in the device. When enabled, a endpoint can be used for communication. Using any direction of an endpoint will require that entire endpoint to be enabled. Consider the case of a composite USB Device that containing a CDC and MSD function. The CDC function will require 1 Bulk endpoint (OUT and IN directions) and 1 Interrupt endpoint (IN direction). The MSD function will require 1 Bulk endpoint (IN and OUT directions). This design can be implemented by using 4 endpoints. Endpoint 0 is used for the mandatory control interface. Endpoint 1 is used for CDC Bulk interface. Endpoint 2 is used for CDC interrupt interface and endpoint 3 is used for MSD Bulk Interface. The constant should then be set to 4. For Host mode operation, this constant should be set to 1. Setting this to greater than 1 will result in unused data memory allocation. Remarks This constant should always be defined. DRV_USBFS_HOST_ATTACH_DEBOUNCE_DURATION Macro Configures the time duration (in milliseconds) that the driver will wait to re-confirm a device attach. File drv_usbfs_config_template.h C #define DRV_USBFS_HOST_ATTACH_DEBOUNCE_DURATION 500 Description USB Full Speed Driver Host Mode Attach Debounce Duration. This constant configures the time duration (in milliseconds) that driver will wait to re-confirm a device attach. When the driver first detects device attach, it start, it will start a timer for the duration specified by the constant. When the timer expires, the driver will check if the device is still attached. If so, the driver will then signal attach to the host stack. The duration allows for device attach to become electro-mechanically stable. Remarks This constant should always be defined when DRV_USBFS_HOST_SUPPORT is set to true. DRV_USBFS_HOST_NAK_LIMIT Macro Configures the NAK Limit for Host Mode Control Transfers. File drv_usbfs_config_template.h C #define DRV_USBFS_HOST_NAK_LIMIT 2000 Description USB Full Speed Driver Host Mode Control Transfers NAK Limit. This constant configures the number of NAKs that the driver can accept from the device in the data stage of a control transfer before aborting the control transfer with a USB_HOST_IRP_STATUS_ERROR_NAK_TIMEOUT. Setting this constant to 0 will disable NAK limit checking. This constant should be adjusted to enable USB host compatibility with USB Devices which require more time to process control transfers. Remarks This constant should always be defined when DRV_USBFS_HOST_SUPPORT is set to true. DRV_USBFS_HOST_PIPES_NUMBER Macro Configures the maximum number of pipes that are can be opened when the driver is operating in Host mode. File drv_usbfs_config_template.h C #define DRV_USBFS_HOST_PIPES_NUMBER 10 Description USB Full Speed Driver Host Mode Pipes Number. This constant configures the maximum number of pipes that can be opened when the driver is operating in Host mode. Calling the Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1186 DRV_USBFS_HOST_PipeSetup function will cause a pipe to be opened. Calling this function when DRV_USBFS_HOST_PIPES_NUMBER number of pipes have already been opened will cause the function to return an Invalid Pipe Handle. This constant should be configured to account for the maximum number of devices and the device types to be supported by the host application. For example if the USB Host application must support 2 USB Mass Storage devices and 1 CDC device, it must set this constant 9 ( 4 bulk pipes for 2 Mass Storage devices + 2 bulk pipes and 1 interrupt pipe for 1 CDC device and 2 control pipes for 2 devices). Allocating pipes consumes data memory. Remarks This constant should always be defined when DRV_USBFS_HOST_SUPPORT is set to true. DRV_USBFS_HOST_RESET_DURATION Macro Configures the time duration (in milliseconds) of the Reset Signal. File drv_usbfs_config_template.h C #define DRV_USBFS_HOST_RESET_DURATION 100 Description USB Full Speed Driver Host Mode Reset Duration. This constant configures the duration of the reset signal. The driver generates reset signal when the USB Host stack requests for root hub port reset. The driver will generate the reset signal for the duration specified by this constant and will then stop generating the reset signal. Remarks This constant should always be defined when DRV_USBFS_HOST_SUPPORT is set to true. DRV_USBFS_HOST_SUPPORT Macro Determines if the USB Host Functionality should be enabled. File drv_usbfs_config_template.h C #define DRV_USBFS_HOST_SUPPORT false Description USB Full Speed Driver Host Mode Support. This constant should be set to true if USB Host mode support is required in the application. It should be set to false if host support is not required. Remarks This constant should always be defined. DRV_USBFS_INSTANCES_NUMBER Macro Specifies the number of driver instances to be enabled in the application. File drv_usbfs_config_template.h C #define DRV_USBFS_INSTANCES_NUMBER 1 Description USB Full Speed Driver Instances Number. This constant defines the number of driver instances to be enabled in the application. This will be typically be the number of USB controllers to be used in the application. On PIC32MX microcontrollers that have one USB controller, this value will always be 1. On PIC32MX microcontrollers which have 2 USB controllers, this value could 1 or 2, depending on whether 1 or 2 USB segments are required. To conserve data memory, this constant should be set to exactly the number of USB controller that are required in the system. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1187 Remarks This constant should always be defined. DRV_USBFS_INTERRUPT_MODE Macro Configures the driver for interrupt or polling mode operation. File drv_usbfs_config_template.h C #define DRV_USBFS_INTERRUPT_MODE true Description USB Full Speed Driver Interrupt Mode. This constant configures the driver for interrupt or polling operation. If this flag is set to true, the driver will operate in interrupt mode. If the flag is set to false, the driver will operate in polled mode. In polled, the driver interrupt state machine gets updated in the SYS_Tasks(). If the driver is configured interrupt mode, the driver interrupt state machine gets updated in the driver interrupt service routine. It is always recommended for the driver to operate in interrupt mode. Remarks This constant should always be defined. Building the Library This section lists the files that are available in the PIC32MX USB Driver Library. Description This section list the files that are available in the \src folder of the PIC32MX USB 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. 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 /framework/driver/usb/usbfs. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_usbfs.h This file should be included by any .c file which accesses the PIC32MX USB Driver API. This one file contains the prototypes for all driver API. 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 /src/dynamic/drv_usbfs.c This file should always be included in the project when using the PIC3MX USB Driver. 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 /src/dynamic/drv_usbfs_device.c This file should be included in the project if Device mode operation is required. /src/dynamic/drv_usbfs_host.c This file should be included in the project if Host mode operation is required. Module Dependencies The PIC32MX USB Driver Library depends on the following modules: • Interrupt System Service Library Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1188 Library Interface a) System Functions Name Description DRV_USBFS_Status Provides the current status of the USB Driver module. DRV_USBFS_Tasks Maintains the driver's state machine when the driver is configured for Polled mode. DRV_USBFS_Tasks_ISR Maintains the driver's Interrupt state machine and implements its ISR. b) Client Core Functions Name Description DRV_USBFS_ClientEventCallBackSet This function sets up the event callback function that is invoked by the USB controller driver to notify the client of USB bus events. DRV_USBFS_Close Closes an opened-instance of the USB Driver. DRV_USBFS_Initialize Initializes the USB Driver. DRV_USBFS_Open Opens the specified USB Driver instance and returns a handle to it. c) Device Mode Operation Functions Name Description DRV_USBFS_DEVICE_AddressSet This function will set the USB module address that is obtained from the Host. DRV_USBFS_DEVICE_Attach This function will enable the attach signaling resistors on the D+ and D- lines thus letting the USB Host know that a device has been attached on the bus. DRV_USBFS_DEVICE_CurrentSpeedGet This function returns the USB speed at which the device is operating. DRV_USBFS_DEVICE_Detach This function will disable the attach signaling resistors on the D+ and D- lines thus letting the USB Host know that the device has detached from the bus. DRV_USBFS_DEVICE_EndpointDisable This function disables an endpoint. DRV_USBFS_DEVICE_EndpointDisableAll This function disables all provisioned endpoints. DRV_USBFS_DEVICE_EndpointEnable This function enables an endpoint for the specified direction and endpoint size. DRV_USBFS_DEVICE_EndpointIsEnabled This function returns the enable/disable status of the specified endpoint and direction. DRV_USBFS_DEVICE_EndpointIsStalled This function returns the stall status of the specified endpoint and direction. DRV_USBFS_DEVICE_EndpointStall This function stalls an endpoint in the specified direction. DRV_USBFS_DEVICE_EndpointStallClear This function clears the stall on an endpoint in the specified direction. DRV_USBFS_DEVICE_IRPCancel This function cancels the specific IRP that are queued and in progress at the specified endpoint. DRV_USBFS_DEVICE_IRPCancelAll This function cancels all IRPs that are queued and in progress at the specified endpoint. DRV_USBFS_DEVICE_IRPSubmit This function submits an I/O Request Packet (IRP) for processing to the Hi-Speed USB Driver. DRV_USBFS_DEVICE_RemoteWakeupStart This function causes the device to start Remote Wakeup Signalling on the bus. DRV_USBFS_DEVICE_RemoteWakeupStop This function causes the device to stop the Remote Wakeup Signalling on the bus. DRV_USBFS_DEVICE_SOFNumberGet This function will return the USB SOF packet number. d) Host Mode Operation Functions Name Description DRV_USBFS_HOST_EventsDisable Disables Host mode events. DRV_USBFS_HOST_EventsEnable Restores the events to the specified the original value. DRV_USBFS_HOST_IRPCancel Cancels the specified IRP. DRV_USBFS_HOST_IRPSubmit Submits an IRP on a pipe. DRV_USBFS_HOST_PipeClose Closes an open pipe. DRV_USBFS_HOST_PipeSetup Open a pipe with the specified attributes. e) Root Hub Functions Name Description DRV_USBFS_HOST_ROOT_HUB_BusSpeedGet This function returns the operating speed of the bus to which this root hub is connected. DRV_USBFS_HOST_ROOT_HUB_Initialize This function initializes the root hub driver. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1189 DRV_USBFS_HOST_ROOT_HUB_MaximumCurrentGet Returns the maximum amount of current that this root hub can provide on the bus. DRV_USBFS_HOST_ROOT_HUB_OperationEnable This function enables or disables root hub operation. DRV_USBFS_HOST_ROOT_HUB_OperationIsEnabled Returns the operation enabled status of the root hub. DRV_USBFS_HOST_ROOT_HUB_PortNumbersGet Returns the number of ports this root hub contains. DRV_USBFS_HOST_ROOT_HUB_PortReset Resets the specified root hub port. DRV_USBFS_HOST_ROOT_HUB_PortResetIsComplete Returns true if the root hub has completed the port reset operation. DRV_USBFS_HOST_ROOT_HUB_PortResume Resumes the specified root hub port. DRV_USBFS_HOST_ROOT_HUB_PortSpeedGet Returns the speed of at which the port is operating. DRV_USBFS_HOST_ROOT_HUB_PortSuspend Suspends the specified root hub port. f) Data Types and Constants Name Description DRV_USBFS_EVENT Identifies the different events that the USB Driver provides. DRV_USBFS_EVENT_CALLBACK Type of the USB Driver event callback function. DRV_USBFS_HOST_PIPE_HANDLE Defines the USB Driver Host Pipe Handle type. DRV_USBFS_INIT This type definition defines the Driver Initialization Data Structure. DRV_USBFS_OPMODES Identifies the operating modes supported by the USB Driver. DRV_USBFS_ROOT_HUB_PORT_INDICATION USB Root hub Application Hooks (Port Indication). DRV_USBFS_ROOT_HUB_PORT_OVER_CURRENT_DETECT USB Root hub Application Hooks (Port Overcurrent detection). DRV_USBFS_ROOT_HUB_PORT_POWER_ENABLE USB Root hub Application Hooks (Port Power Enable/ Disable). DRV_USBFS_DEVICE_INTERFACE USB Driver Device Mode Interface Functions. DRV_USBFS_ENDPOINT_TABLE_ENTRY_SIZE USB Driver Endpoint Table Entry Size in bytes. DRV_USBFS_HOST_INTERFACE USB Driver Host Mode Interface Functions. DRV_USBFS_HOST_PIPE_HANDLE_INVALID Value of an Invalid Host Pipe Handle. DRV_USBFS_INDEX_0 USB Driver Module Index 0 Definition. DRV_USBFS_INDEX_1 USB Driver Module Index 1 Definition. Description This section describes the functions of the PIC32MX USB Driver Library. Refer to each section for a detailed description. a) System Functions DRV_USBFS_Status Function Provides the current status of the USB Driver module. File drv_usbfs.h C SYS_STATUS DRV_USBFS_Status(SYS_MODULE_OBJ object); Returns • SYS_STATUS_READY - Indicates that the driver is ready. • SYS_STATUS_UNINITIALIZED - Indicates that the driver has never been initialized. Description This function provides the current status of the USB Driver module. Remarks None. Preconditions The DRV_USBFS_Initialize function must have been called before calling this function. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1190 Example SYS_MODULE_OBJ object; // Returned from DRV_USBFS_Initialize SYS_STATUS status; DRV_USBFS_INIT moduleInit; uint8_t __attribute__((aligned(512))) endpointTable[DRV_USBFS_ENDPOINT_TABLE_ENTRY_SIZE * 2]; usbInitData.usbID = USB_ID_1; usbInitData.opMode = DRV_USBFS_OPMODE_DEVICE; usbInitData.stopInIdle = false; usbInitData.suspendInSleep = false; usbInitData.operationSpeed = USB_SPEED_FULL; usbInitData.interruptSource = INT_SOURCE_USB; usbInitData.sysModuleInit.powerState = SYS_MODULE_POWER_RUN_FULL ; // This is how this data structure is passed to the initialize // function. DRV_USBFS_Initialize(DRV_USBFS_INDEX_0, (SYS_MODULE_INIT *) &usbInitData); // The status of the driver can be checked. status = DRV_USBFS_Status(object); if(SYS_STATUS_READY == status) { // Driver is ready to be opened. } Parameters Parameters Description object Driver object handle, returned from the DRV_USBFS_Initialize function. Function SYS_STATUS DRV_USBFS_Status ( SYS_MODULE_OBJ object ) DRV_USBFS_Tasks Function Maintains the driver's state machine when the driver is configured for Polled mode. File drv_usbfs.h C void DRV_USBFS_Tasks(SYS_MODULE_OBJ object); Returns None. Description Maintains the driver's Polled state machine. This function should be called from the SYS_Tasks function. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks). This function will never block. Preconditions The DRV_USBFS_Initialize function must have been called for the specified USB Driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_USBFS_Initialize while (true) { DRV_USBFS_Tasks(object); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1191 // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_USBFS_Initialize function). Function void DRV_USBFS_Tasks( SYS_MODULE_OBJ object ) DRV_USBFS_Tasks_ISR Function Maintains the driver's Interrupt state machine and implements its ISR. File drv_usbfs.h C void DRV_USBFS_Tasks_ISR(SYS_MODULE_OBJ object); Returns None. Description This function is used to maintain the driver's internal Interrupt state machine and implement its ISR for interrupt-driven implementations. Remarks This routine should be called from the USB interrupt service routine. In case of multiple USB modules, it should be ensured that the correct USB driver system module object is passed to this routine. Preconditions The DRV_USBFS_Initialize function must have been called for the specified USB Driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_USBFS_Initialize while (true) { DRV_USBFS_Tasks_ISR (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_USBFS_Initialize). Function void DRV_USBFS_Tasks_ISR( SYS_MODULE_OBJ object ) b) Client Core Functions DRV_USBFS_ClientEventCallBackSet Function This function sets up the event callback function that is invoked by the USB controller driver to notify the client of USB bus events. File drv_usbfs.h C void DRV_USBFS_ClientEventCallBackSet(DRV_HANDLE handle, uintptr_t hReferenceData, DRV_USB_EVENT_CALLBACK Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1192 myEventCallBack); Returns None. Description This function sets up the event callback function that is invoked by the USB controller driver to notify the client of USB bus events. The callback is disabled by either not calling this function after the DRV_USBFS_Open function has been called or by setting the myEventCallBack argument as NULL. When the callback function is called, the hReferenceData argument is returned. Remarks Typical usage of the USB Driver requires a client to register a callback. Preconditions None. Example // Set the client event callback for the Device Layer. The // USBDeviceLayerEventHandler function is the event handler. When this // event handler is invoked by the driver, the driver returns back the // second argument specified in the following function (which in this case // is the Device Layer data structure). This allows the application // firmware to identify, as an example, the Device Layer object associated // with this callback. DRV_USBFS_ClientEventCallBackSet(myUSBDevice.usbDriverHandle, (uintptr_t)&myUSBDevice, USBDeviceLayerEventHandler); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). hReferenceData Object (could be a pointer) that is returned with the callback. myEventCallBack Callback function for all USB events. Function void DRV_USBFS_ClientEventCallBackSet ( DRV_HANDLE handle, uintptr_t hReferenceData, DRV_USBFS_EVENT_CALLBACK myEventCallBack ); DRV_USBFS_Close Function Closes an opened-instance of the USB Driver. File drv_usbfs.h C void DRV_USBFS_Close(DRV_HANDLE handle); Returns None. Description This function closes an opened-instance of the USB Driver, invalidating the handle. Remarks After calling this function, the handle passed in handle parameter must not be used with any of the other driver functions. A new handle must be obtained by calling DRV_USBFS_Open function before the caller may use the driver again. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1193 Preconditions The DRV_USBFS_Initialize function must have been called for the specified USB Driver instance. DRV_USBFS_Open function must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_USBFS_Open DRV_USBFS_Close(handle); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). Function void DRV_USBFS_Close( DRV_HANDLE handle ) DRV_USBFS_Initialize Function Initializes the USB Driver. File drv_usbfs.h C SYS_MODULE_OBJ DRV_USBFS_Initialize(const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init); Returns • SYS_MODULE_OBJ_INVALID - The driver initialization failed. • A valid System Module Object - The driver initialization was able to start. It may have not completed and requires the DRV_USBFS_Tasks function to be called periodically. This value will never be the same as SYS_MODULE_OBJ_INVALID. Description This function initializes the USB Driver, making it ready for clients to open. The driver initialization does not complete when this function returns. The DRV_USBFS_Tasks function must called periodically to complete the driver initialization. The DRV_USBHS_Open function will fail if the driver was not initialized or if initialization has not completed. Remarks This routine must be called before any other USB driver routine is called. This routine should only be called once during system initialization unless DRV_USBFS_Deinitialize is called to deinitialize the driver instance. Preconditions None. Example // The following code shows an example initialization of the // driver. The USB module to be used is USB1. The module should not // automatically suspend when the microcontroller enters Sleep mode. The // module should continue operation when the CPU enters Idle mode. The // power state is set to run at full clock speeds. Device Mode operation // should be at FULL speed. The size of the endpoint table is set for 2 // endpoints. DRV_USBFS_INIT moduleInit; uint8_t __attribute__((aligned(512))) endpointTable[DRV_USBFS_ENDPOINT_TABLE_ENTRY_SIZE * 2]; usbInitData.usbID = USB_ID_1; usbInitData.opMode = DRV_USBFS_OPMODE_DEVICE; usbInitData.stopInIdle = false; usbInitData.suspendInSleep = false; usbInitData.operationSpeed = USB_SPEED_FULL; usbInitData.interruptSource = INT_SOURCE_USB; usbInitData.sysModuleInit.powerState = SYS_MODULE_POWER_RUN_FULL ; Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1194 // This is how this data structure is passed to the initialize // function. DRV_USBFS_Initialize(DRV_USBFS_INDEX_0, (SYS_MODULE_INIT *) &usbInitData); Parameters Parameters Description drvIndex Ordinal number of driver instance to be initialized. This should be set to DRV_USBFS_INDEX_0 if driver instance 0 needs to be initialized. init Pointer to a data structure containing data necessary to initialize the driver. This should be a DRV_USBFS_INIT structure reference typecast to SYS_MODULE_INIT reference. Function SYS_MODULE_OBJ DRV_USBHS_Initialize ( const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init ) DRV_USBFS_Open Function Opens the specified USB Driver instance and returns a handle to it. File drv_usbfs.h C DRV_HANDLE DRV_USBFS_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); Returns • DRV_HANDLE_INVALID - The driver could not be opened successfully.This can happen if the driver initialization was not complete or if an internal error has occurred. • A Valid Driver Handle - This is an arbitrary value and is returned if the function was successful. This value will never be the same as DRV_HANDLE_INVALID. Description This function opens the specified USB Driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The intent flag should always be DRV_IO_INTENT_EXCLUSIVE|DRV_IO_INTENT_READWRITE|DRV_IO_INTENT_NON_BLOCKING. Any other setting of the intent flag will return a invalid driver handle. A driver instance can only support one client. Trying to open a driver that has an existing client will result in an unsuccessful function call. Remarks The handle returned is valid until the DRV_USBFS_Close function is called. The function will typically return DRV_HANDLE_INVALID if the driver was not initialized. In such a case the client should try to open the driver again. Preconditions Function DRV_USBFS_Initialize must have been called before calling this function. Example DRV_HANDLE handle; // This code assumes that the driver has been initialized. handle = DRV_USBFS_Open(DRV_USBFS_INDEX_0, DRV_IO_INTENT_EXCLUSIVE| DRV_IO_INTENT_READWRITE| DRV_IO_INTENT_NON_BLOCKING); if(DRV_HANDLE_INVALID == handle) { // The application should try opening the driver again. } Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1195 Parameters Parameters Description drvIndex Identifies the driver instance to be opened. As an example, this value can be set to DRV_USBFS_INDEX_0 if instance 0 of the driver has to be opened. intent Should always be (DRV_IO_INTENT_EXCLUSIVE|DRV_IO_INTENT_READWRITE| DRV_IO_INTENT_NON_BLOCKING). Function DRV_HANDLE DRV_USBFS_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ) c) Device Mode Operation Functions DRV_USBFS_DEVICE_AddressSet Function This function will set the USB module address that is obtained from the Host. File drv_usbfs.h C void DRV_USBFS_DEVICE_AddressSet(DRV_HANDLE handle, uint8_t address); Returns None. Description This function will set the USB module address that is obtained from the Host in a setup transaction. The address is obtained from the SET_ADDRESS command issued by the Host. The primary (first) client of the driver uses this function to set the module's USB address after decoding the setup transaction from the Host. Remarks None. Preconditions None. Example // This function should be called by the first client of the driver, // which is typically the Device Layer. The address to set is obtained // from the Host during enumeration. DRV_USBFS_DEVICE_AddressSet(deviceLayer, 4); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). address The address of this module on the USB bus. Function void DRV_USBFS_DEVICE_AddressSet( DRV_HANDLE handle, uint8_t address); DRV_USBFS_DEVICE_Attach Function This function will enable the attach signaling resistors on the D+ and D- lines thus letting the USB Host know that a device has been attached on Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1196 the bus. File drv_usbfs.h C void DRV_USBFS_DEVICE_Attach(DRV_HANDLE handle); Returns None. Description This function enables the pull-up resistors on the D+ or D- lines thus letting the USB Host know that a device has been attached on the bus . This function should be called when the driver client is ready to receive communication from the Host (typically after all initialization is complete). The USB 2.0 specification requires VBUS to be detected before the data line pull-ups are enabled. The application must ensure the same. Remarks None. Preconditions The Client handle should be valid. Example // Open the device driver and attach the device to the USB. handle = DRV_USBFS_Open(DRV_USBFS_INDEX_0, DRV_IO_INTENT_EXCLUSIVE| DRV_IO_INTENT_READWRITE| DRV_IO_INTENT_NON_BLOCKING); // Register a callback DRV_USBFS_ClientEventCallBackSet(handle, (uintptr_t)&myDeviceLayer, MyDeviceLayerEventCallback); // The device can be attached when VBUS Session Valid event occurs void MyDeviceLayerEventCallback(uintptr_t handle, DRV_USBFS_EVENT event, void * hReferenceData) { switch(event) { case DRV_USBFS_EVENT_DEVICE_SESSION_VALID: // A valid VBUS was detected. DRV_USBFS_DEVICE_Attach(handle); break; case DRV_USBFS_EVENT_DEVICE_SESSION_INVALID: // VBUS is not valid anymore. The device can be disconnected. DRV_USBFS_DEVICE_Detach(handle); break; default: break; } } } Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). Function void DRV_USBFS_DEVICE_Attach( DRV_HANDLE handle); DRV_USBFS_DEVICE_CurrentSpeedGet Function This function returns the USB speed at which the device is operating. File drv_usbfs.h Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1197 C USB_SPEED DRV_USBFS_DEVICE_CurrentSpeedGet(DRV_HANDLE handle); Returns • USB_SPEED_ERROR - The device speed is not valid. • USB_SPEED_FULL - The device is operating at Full speed. Description This function returns the USB speed at which the device is operating. Remarks None. Preconditions Only valid after the device is attached to the Host and Host has completed reset signaling. Example // Get the current speed. USB_SPEED deviceSpeed; deviceSpeed = DRV_USBFS_DEVICE_CurrentSpeedGet(deviceLayer); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). Function USB_SPEED DRV_USBFS_DEVICE_CurrentSpeedGet( DRV_HANDLE handle); DRV_USBFS_DEVICE_Detach Function This function will disable the attach signaling resistors on the D+ and D- lines thus letting the USB Host know that the device has detached from the bus. File drv_usbfs.h C void DRV_USBFS_DEVICE_Detach(DRV_HANDLE handle); Returns None. Description This function disables the pull-up resistors on the D+ or D- lines. This function should be called when the application wants to disconnect the device from the bus (typically to implement a soft detach or switch to Host mode operation). A self-powered device should be detached from the bus when the VBUS is not valid. Remarks None. Preconditions The Client handle should be valid. Example // Open the device driver and attach the device to the USB. handle = DRV_USBFS_Open(DRV_USBFS_INDEX_0, DRV_IO_INTENT_EXCLUSIVE| DRV_IO_INTENT_READWRITE| DRV_IO_INTENT_NON_BLOCKING); // Register a callback DRV_USBFS_ClientEventCallBackSet(handle, (uintptr_t)&myDeviceLayer, MyDeviceLayerEventCallback); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1198 // The device can be detached when VBUS Session Invalid event occurs void MyDeviceLayerEventCallback(uintptr_t handle, DRV_USBFS_EVENT event, void * hReferenceData) { switch(event) { case DRV_USBFS_EVENT_DEVICE_SESSION_VALID: // A valid VBUS was detected. DRV_USBFS_DEVICE_Attach(handle); break; case DRV_USBFS_EVENT_DEVICE_SESSION_INVALID: // VBUS is not valid anymore. The device can be disconnected. DRV_USBFS_DEVICE_Detach(handle); break; default: break; } } } Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). Function void DRV_USBFS_DEVICE_Detach( DRV_HANDLE handle); DRV_USBFS_DEVICE_EndpointDisable Function This function disables an endpoint. File drv_usbfs.h C USB_ERROR DRV_USBFS_DEVICE_EndpointDisable(DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection); Returns • USB_ERROR_NONE - The endpoint was successfully enabled. • USB_ERROR_DEVICE_ENDPOINT_INVALID - The endpoint that is being accessed is not a valid endpoint (endpoint was not provisioned through the DRV_USBFS_ENDPOINTS_NUMBER configuration constant) defined for this driver instance. Description This function disables an endpoint. If the endpoint type is a control endpoint type, both directions are disabled. For non-control endpoints, the function disables the specified direction only. The direction to be disabled is specified by the Most Significant Bit (MSB) of the endpointAndDirection parameter. Remarks None. Preconditions The Client handle should be valid. Example // This code shows an example of how to disable // a control endpoint. Note that the direction parameter is ignored. // For a control endpoint, both the directions are disabled. USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 0); DRV_USBFS_DEVICE_EndpointDisable(handle, ep ); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1199 // This code shows an example of how to disable a BULK IN // endpoint USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); DRV_USBFS_DEVICE_EndpointDisable(handle, ep ); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). endpointAndDirection Specifies the endpoint and direction. Function USB_ERROR DRV_USBFS_DEVICE_EndpointDisable ( DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection ) DRV_USBFS_DEVICE_EndpointDisableAll Function This function disables all provisioned endpoints. File drv_usbfs.h C USB_ERROR DRV_USBFS_DEVICE_EndpointDisableAll(DRV_HANDLE handle); Returns • USB_ERROR_NONE - The function exited successfully. • USB_ERROR_PARAMETER_INVALID - The driver handle is invalid. Description This function disables all provisioned endpoints in both directions. Remarks This function is typically called by the USB Device Layer to disable all endpoints upon detecting a bus reset. Preconditions The Client handle should be valid. Example // This code shows an example of how to disable all endpoints. DRV_USBFS_DEVICE_EndpointDisableAll(handle); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). Function USB_ERROR DRV_USBFS_DEVICE_EndpointDisableAll( DRV_HANDLE handle) Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1200 DRV_USBFS_DEVICE_EndpointEnable Function This function enables an endpoint for the specified direction and endpoint size. File drv_usbfs.h C USB_ERROR DRV_USBFS_DEVICE_EndpointEnable(DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection, USB_TRANSFER_TYPE transferType, uint16_t endpointSize); Returns • USB_ERROR_NONE - The endpoint was successfully enabled. • USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is not a valid endpoint defined for this driver instance. The value of DRV_USBFS_ENDPOINTS_NUMBER configuration constant should be adjusted. • USB_ERROR_PARAMETER_INVALID - The driver handle is invalid. Description This function enables an endpoint for the specified direction and endpoint size. The function will enable the endpoint for communication in one direction at a time. It must be called twice if the endpoint is required to communicate in both the directions, with the exception of control endpoints. If the endpoint type is a control endpoint, the endpoint is always bidirectional and the function needs to be called only once. The size of the endpoint must match the wMaxPacketSize reported in the endpoint descriptor for this endpoint. A transfer that is scheduled over this endpoint will be scheduled in wMaxPacketSize transactions. The function does not check if the endpoint is already in use. It is the client's responsibility to make sure that a endpoint is not accidentally reused. Remarks None. Preconditions The Client handle should be valid. Example // This code shows an example of how to enable Endpoint // 0 for control transfers. Note that for a control endpoint, the // direction parameter is ignored. A control endpoint is always // bidirectional. Endpoint size is 64 bytes. uint8_t ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 0); DRV_USBFS_DEVICE_EndpointEnable(handle, ep, USB_TRANSFER_TYPE_CONTROL, 64); // This code shows an example of how to set up a endpoint // for BULK IN transfer. For an IN transfer, data moves from device // to Host. In this example, Endpoint 1 is enabled. The maximum // packet size is 64. uint8_t ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); DRV_USBFS_DEVICE_EndpointEnable(handle, ep, USB_TRANSFER_TYPE_BULK, 64); // If Endpoint 1 must also be set up for BULK OUT, the // DRV_USBFS_DEVICE_EndpointEnable function must be called again, as shown // here. ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_HOST_TO_DEVICE, 1); DRV_USBFS_DEVICE_EndpointEnable(handle, ep, USB_TRANSFER_TYPE_BULK, 64); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1201 Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). endpointAndDirection Specifies the endpoint and direction. transferType Should be USB_TRANSFER_TYPE_CONTROL for control endpoint, USB_TRANSFER_TYPE_BULK for bulk endpoint, USB_TRANSFER_TYPE_INTERRUPT for interrupt endpoint and USB_TRANSFER_TYPE_ISOCHRONOUS for isochronous endpoint. endpointSize Maximum size (in bytes) of the endpoint as reported in the endpoint descriptor. Function USB_ERROR DRV_USBFS_DEVICE_EndpointEnable ( DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection, USB_TRANSFER_TYPE transferType, uint16_t endpointSize ); DRV_USBFS_DEVICE_EndpointIsEnabled Function This function returns the enable/disable status of the specified endpoint and direction. File drv_usbfs.h C bool DRV_USBFS_DEVICE_EndpointIsEnabled(DRV_HANDLE client, USB_ENDPOINT endpointAndDirection); Returns • true - The endpoint is enabled. • false - The endpoint is disabled. Description This function returns the enable/disable status of the specified endpoint and direction. Remarks None. Preconditions The Client handle should be valid. Example // This code shows an example of how the // DRV_USBFS_DEVICE_EndpointIsEnabled function can be used to obtain the // status of Endpoint 1 and IN direction. USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); if(DRV_USBFS_ENDPOINT_STATE_DISABLED == DRV_USBFS_DEVICE_EndpointIsEnabled(handle, ep)) { // Endpoint is disabled. Enable endpoint. DRV_USBFS_DEVICE_EndpointEnable(handle, ep, USB_ENDPOINT_TYPE_BULK, 64); } Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1202 Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). endpointAndDirection Specifies the endpoint and direction. Function bool DRV_USBFS_DEVICE_EndpointIsEnabled ( DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection ) DRV_USBFS_DEVICE_EndpointIsStalled Function This function returns the stall status of the specified endpoint and direction. File drv_usbfs.h C bool DRV_USBFS_DEVICE_EndpointIsStalled(DRV_HANDLE client, USB_ENDPOINT endpoint); Returns • true - The endpoint is stalled. • false - The endpoint is not stalled. Description This function returns the stall status of the specified endpoint and direction. Remarks None. Preconditions The Client handle should be valid. Example // This code shows an example of how the // DRV_USBFS_DEVICE_EndpointIsStalled function can be used to obtain the // stall status of Endpoint 1 and IN direction. USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); if(true == DRV_USBFS_DEVICE_EndpointIsStalled (handle, ep)) { // Endpoint stall is enabled. Clear the stall. DRV_USBFS_DEVICE_EndpointStallClear(handle, ep); } Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). endpointAndDirection Specifies the endpoint and direction. Function bool DRV_USBFS_DEVICE_EndpointIsStalled ( Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1203 DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection ) DRV_USBFS_DEVICE_EndpointStall Function This function stalls an endpoint in the specified direction. File drv_usbfs.h C USB_ERROR DRV_USBFS_DEVICE_EndpointStall(DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection); Returns • USB_ERROR_NONE - The endpoint was successfully enabled. • USB_ERROR_PARAMETER_INVALID - The driver handle is not valid. • USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is out of the valid endpoint defined for this driver instance. • USB_ERROR_OSAL_FUNCTION - An error with an OSAL function called in this function. Description This function stalls an endpoint in the specified direction. Remarks None. Preconditions The Client handle should be valid. Example // This code shows an example of how to stall an endpoint. In // this example, Endpoint 1 IN direction is stalled. USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); DRV_USBFS_DEVICE_EndpointStall(handle, ep); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). endpointAndDirection Specifies the endpoint and direction. Function USB_ERROR DRV_USBFS_DEVICE_EndpointStall ( DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection ) DRV_USBFS_DEVICE_EndpointStallClear Function This function clears the stall on an endpoint in the specified direction. File drv_usbfs.h Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1204 C USB_ERROR DRV_USBFS_DEVICE_EndpointStallClear(DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection); Returns • USB_ERROR_NONE - The endpoint was successfully enabled. • USB_ERROR_PARAMETER_INVALID - The driver handle is not valid. • USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is out of the valid endpoint defined for this driver instance. Description This function clears the stall on an endpoint in the specified direction. Remarks None. Preconditions The Client handle should be valid. Example // This code shows an example of how to clear a stall. In this // example, the stall condition on Endpoint 1 IN direction is cleared. USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); DRV_USBFS_DEVICE_EndpointStallClear(handle, ep); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). endpointAndDirection Specifies the endpoint and direction. Function USB_ERROR DRV_USBFS_DEVICE_EndpointStallClear ( DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection ) DRV_USBFS_DEVICE_IRPCancel Function This function cancels the specific IRP that are queued and in progress at the specified endpoint. File drv_usbfs.h C USB_ERROR DRV_USBFS_DEVICE_IRPCancel(DRV_HANDLE client, USB_DEVICE_IRP * irp); Returns • USB_ERROR_NONE - The IRP have been canceled successfully. • USB_ERROR_PARAMETER_INVALID - Invalid parameter or the IRP already has been aborted or completed • USB_ERROR_OSAL_FUNCTION - An OSAL function called in this function did not execute successfully. Description This function attempts to cancel the processing of a queued IRP. An IRP that was in the queue but yet to be processed will be cancelled successfully and the IRP callback function will be called from this function with the USB_DEVICE_IRP_STATUS_ABORTED status. The application can release the data buffer memory used by the IRP when this callback occurs. If the IRP was in progress (a transaction in on the bus) when the cancel function was called, the IRP will be canceled only when an ongoing or the next transaction has completed. The IRP callback Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1205 function will then be called in an interrupt context. The application should not release the related data buffer unless the IRP callback has occurred. Remarks The size returned after the ABORT callback will be always 0 regardless of the amount of data that has been sent or received. The client should not assume any data transaction has happened for an canceled IRP. If the last transaction of the IRP was in progress, the IRP cancel does not have any effect. The first transaction of any ongoing IRP cannot be canceled. Preconditions The Client handle should be valid. Example // This code shows an example of how to cancel IRP. In this example the IRP // has been scheduled from a device to the Host. USB_ENDPOINT ep; USB_DEVICE_IRP irp; ep.direction = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); irp.data = myDataBufferToSend; irp.size = 130; irp.flags = USB_DEVICE_IRP_FLAG_DATA_COMPLETE; irp.callback = MyIRPCompletionCallback; irp.referenceData = (uintptr_t)&myDeviceLayerObj; if (DRV_USBFS_DEVICE_IRPSubmit(handle, ep, &irp) != USB_ERROR_NONE) { // This means there was an error. } else { // Check the status of the IRP. if(irp.status != USB_DEVICE_IRP_STATUS_COMPLETED) { // Cancel the submitted IRP. if (DRV_USBFS_DEVICE_IRPCancel(handle, &irp) != USB_ERROR_NONE) { // The IRP Cancel request submission was successful. // IRP cancel status will be notified through the callback // function. } else { // The IRP may have been completed before IRP cancel operation. // could start. No callback notification will be generated. } } else { // The IRP processing must have been completed before IRP cancel was // submitted. } } void MyIRPCallback(USB_DEVICE_IRP * irp) { // Check if the IRP callback is for a Cancel request if(irp->status == USB_DEVICE_IRP_STATUS_ABORTED) { // IRP cancel completed } } Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). irp Pointer to the IRP to cancel. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1206 Function USB_ERROR DRV_USBFS_DEVICE_IRPCancel ( DRV_HANDLE client, USB_DEVICE_IRP * irp ) DRV_USBFS_DEVICE_IRPCancelAll Function This function cancels all IRPs that are queued and in progress at the specified endpoint. File drv_usbfs.h C USB_ERROR DRV_USBFS_DEVICE_IRPCancelAll(DRV_HANDLE client, USB_ENDPOINT endpointAndDirection); Returns • USB_ERROR_NONE - The endpoint was successfully enabled. • USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is out of the valid endpoint defined for this driver instance. • USB_ERROR_PARAMETER_INVALID - The driver handle is not valid. • USB_ERROR_OSAL_FUNCTION - An OSAL function called in this function did not execute successfully. Description This function cancels all IRPs that are queued and in progress at the specified endpoint. Remarks None. Preconditions The Client handle should be valid. Example // This code shows an example of how to cancel all IRPs. void MyIRPCallback(USB_DEVICE_IRP * irp) { // Check if this is setup command if(irp->status == USB_DEVICE_IRP_STATUS_SETUP) { if(IsSetupCommandSupported(irp->data) == false) { // This means that this setup command is not // supported. Stall the some related endpoint and cancel all // queue IRPs. DRV_USBFS_DEVICE_EndpointStall(handle, ep); DRV_USBFS_DEVICE_IRPCancelAll(handle, ep); } } } Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). endpointAndDirection Specifies the endpoint and direction. Function USB_ERROR DRV_USBFS_DEVICE_IRPCancelAll Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1207 ( DRV_HANDLE client, USB_ENDPOINT endpointAndDirection ); DRV_USBFS_DEVICE_IRPSubmit Function This function submits an I/O Request Packet (IRP) for processing to the Hi-Speed USB Driver. File drv_usbfs.h C USB_ERROR DRV_USBFS_DEVICE_IRPSubmit(DRV_HANDLE client, USB_ENDPOINT endpointAndDirection, USB_DEVICE_IRP * irp); Returns • USB_ERROR_NONE - if the IRP was submitted successful. • USB_ERROR_IRP_SIZE_INVALID - if the size parameter of the IRP is not correct. • USB_ERROR_PARAMETER_INVALID - If the client handle is not valid. • USB_ERROR_ENDPOINT_NOT_CONFIGURED - If the endpoint is not enabled. • USB_ERROR_DEVICE_ENDPOINT_INVALID - The specified endpoint is not valid. • USB_ERROR_OSAL_FUNCTION - An OSAL call in the function did not complete successfully. Description This function submits an I/O Request Packet (IRP) for processing to the USB Driver. The IRP allows a client to send and receive data from the USB Host. The data will be sent or received through the specified endpoint. The direction of the data transfer is indicated by the direction flag in the endpointAndDirection parameter. Submitting an IRP arms the endpoint to either send data to or receive data from the Host. If an IRP is already being processed on the endpoint, the subsequent IRP submit operation will be queued. The contents of the IRP (including the application buffers) should not be changed until the IRP has been processed. Particular attention should be paid to the size parameter of IRP. The following should be noted: • The size parameter while sending data to the Host can be less than, greater than, equal to, or be an exact multiple of the maximum packet size for the endpoint. The maximum packet size for the endpoint determines the number of transactions required to process the IRP. • If the size parameter, while sending data to the Host is less than the maximum packet size, the transfer will complete in one transaction. • If the size parameter, while sending data to the Host is greater than the maximum packet size, the IRP will be processed in multiple transactions. • If the size parameter, while sending data to the Host is equal to or an exact multiple of the maximum packet size, the client can optionally ask the driver to send a Zero Length Packet(ZLP) by specifying the USB_DEVICE_IRP_FLAG_DATA_COMPLETE flag as the flag parameter. • The size parameter, while receiving data from the Host must be an exact multiple of the maximum packet size of the endpoint. If this is not the case, the driver will return a USB_ERROR_IRP_SIZE_INVALID result. If while processing the IRP, the driver receives less than maximum packet size or a ZLP from the Host, the driver considers the IRP as processed. The size parameter at this point contains the actual amount of data received from the Host. The IRP status is returned as USB_DEVICE_IRP_STATUS_COMPLETED_SHORT. • If a ZLP needs to be sent to Host, the IRP size should be specified as 0 and the flag parameter should be set as USB_DEVICE_IRP_FLAG_DATA_COMPLETE. • If the IRP size is an exact multiple of the endpoint size, the client can request the driver to not send a ZLP by setting the flag parameter to USB_DEVICE_IRP_FLAG_DATA_PENDING. This flag indicates that there is more data pending in this transfer. • Specifying a size less than the endpoint size along with the USB_DEVICE_IRP_FLAG_DATA_PENDING flag will cause the driver to return a USB_ERROR_IRP_SIZE_INVALID. • If the size is greater than but not a multiple of the endpoint size, and the flag is specified as USB_DEVICE_IRP_FLAG_DATA_PENDING, the driver will send multiple of endpoint size number of bytes. For example, if the IRP size is 130 and the endpoint size if 64, the number of bytes sent will 128. Remarks This function can be called from the ISR of the USB module to associated with the client. Preconditions The Client handle should be valid. Example // The following code shows an example of how to schedule a IRP to send data // from a device to the Host. Assume that the max packet size is 64 and Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1208 // and this data needs to sent over Endpoint 1. In this example, the // transfer is processed as three transactions of 64, 64 and 2 bytes. USB_ENDPOINT ep; USB_DEVICE_IRP irp; ep.direction = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); irp.data = myDataBufferToSend; irp.size = 130; irp.flags = USB_DEVICE_IRP_FLAG_DATA_COMPLETE; irp.callback = MyIRPCompletionCallback; irp.referenceData = (uintptr_t)&myDeviceLayerObj; if (DRV_USBFS_DEVICE_IRPSubmit(handle, ep, &irp) != USB_ERROR_NONE) { // This means there was an error. } else { // The status of the IRP can be checked. while(irp.status != USB_DEVICE_IRP_STATUS_COMPLETED) { // Wait or run a task function. } } // The following code shows how the client can request // the driver to send a ZLP when the size is an exact multiple of // endpoint size. irp.data = myDataBufferToSend; irp.size = 128; irp.flags = USB_DEVICE_IRP_FLAG_DATA_COMPLETE; irp.callback = MyIRPCompletionCallback; irp.referenceData = (uintptr_t)&myDeviceLayerObj; // Note that while receiving data from the Host, the size should be an // exact multiple of the maximum packet size of the endpoint. In the // following example, the DRV_USBFS_DEVICE_IRPSubmit function will return a // USB_DEVICE_IRP_SIZE_INVALID value. ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_HOST_TO_DEVICE, 1); irp.data = myDataBufferToSend; irp.size = 60; // THIS SIZE IS NOT CORRECT irp.flags = USB_DEVICE_IRP_FLAG_DATA_COMPLETE; irp.callback = MyIRPCompletionCallback; irp.referenceData = (uintptr_t)&myDeviceLayerObj; Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). endpointAndDirection Specifies the endpoint and direction. irp Pointer to the IRP to be added to the queue for processing. Function USB_ERROR DRV_USBFS_DEVICE_IRPSubmit ( DRV_HANDLE client, USB_ENDPOINT endpointAndDirection, USB_DEVICE_IRP * irp ); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1209 DRV_USBFS_DEVICE_RemoteWakeupStart Function This function causes the device to start Remote Wakeup Signalling on the bus. File drv_usbfs.h C void DRV_USBFS_DEVICE_RemoteWakeupStart(DRV_HANDLE handle); Returns None. Description This function causes the device to start Remote Wakeup Signalling on the bus. This function should be called when the device, presently placed in suspend mode by the Host, wants to be wakeup. Note that the device can do this only when the Host has enabled the device's Remote Wakeup capability. Remarks None. Preconditions The handle should be valid. Example DRV_HANDLE handle; // If the Host has enabled the Remote Wakeup capability, and if the device // is in suspend mode, then start Remote Wakeup signaling. if(deviceIsSuspended && deviceRemoteWakeupEnabled) { DRV_USBFS_DEVICE_RemoteWakeupStart(handle); } Parameters Parameters Description handle Handle to the driver (returned from DRV_USBFS_Open function). Function void DRV_USBFS_DEVICE_RemoteWakeupStart( DRV_HANDLE handle); DRV_USBFS_DEVICE_RemoteWakeupStop Function This function causes the device to stop the Remote Wakeup Signalling on the bus. File drv_usbfs.h C void DRV_USBFS_DEVICE_RemoteWakeupStop(DRV_HANDLE handle); Returns None. Description This function causes the device to stop Remote Wakeup Signalling on the bus. This function should be called after the DRV_USBFS_DEVICE_RemoteWakeupStart function was called to start the Remote Wakeup signaling on the bus. Remarks This function should be 1 to 15 milliseconds after the DRV_USBFS_DEVICE_RemoteWakeupStart function was called. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1210 Preconditions The handle should be valid. The DRV_USBFS_DEVICE_RemoteWakeupStart function was called to start the Remote Wakeup signaling on the bus. Example DRV_HANDLE handle; // If the Host has enabled the Remote Wakeup capability, and if the device // is in suspend mode, then start Remote Wakeup signaling. Wait for 10 // milliseconds and then stop the Remote Wakeup signaling if(deviceIsSuspended && deviceRemoteWakeupEnabled) { DRV_USBFS_DEVICE_RemoteWakeupStart(handle); DelayMilliSeconds(10); DRV_USBFS_DEVICE_RemoteWakeupStop(handle); } Parameters Parameters Description handle Handle to the driver (returned from DRV_USBFS_Open function). Function void DRV_USBFS_DEVICE_RemoteWakeupStop( DRV_HANDLE handle); DRV_USBFS_DEVICE_SOFNumberGet Function This function will return the USB SOF packet number. File drv_usbfs.h C uint16_t DRV_USBFS_DEVICE_SOFNumberGet(DRV_HANDLE handle); Returns The SOF packet number. Description This function will return the USB SOF packet number.. Remarks None. Preconditions This function will return a valid value only when the device is attached to the bus. The SOF packet count will not increment if the bus is suspended. Example // This code shows how the DRV_USBFS_DEVICE_SOFNumberGet function is called // to read the current SOF number. DRV_HANDLE handle; uint16_t sofNumber; sofNumber = DRV_USBFS_DEVICE_SOFNumberGet(handle); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1211 Function uint16_t DRV_USBFS_DEVICE_SOFNumberGet( DRV_HANDLE handle); d) Host Mode Operation Functions DRV_USBFS_HOST_EventsDisable Function Disables Host mode events. File drv_usbfs.h C bool DRV_USBFS_HOST_EventsDisable(DRV_HANDLE handle); Returns • true - Driver event generation was enabled when this function was called. • false - Driver event generation was not enabled when this function was called. Description This function disables the Host mode events. This function is called by the Host Layer when it wants to execute code atomically. Remarks None. Preconditions The handle should be valid. Example // This code shows how the DRV_USBFS_HOST_EventsDisable and // DRV_USBFS_HOST_EventsEnable function can be called to disable and enable // events. DRV_HANDLE driverHandle; bool eventsWereEnabled; // Disable the driver events. eventsWereEnabled = DRV_USBFS_HOST_EventsDisable(driverHandle); // Code in this region will not be interrupted by driver events. // Enable the driver events. DRV_USBFS_HOST_EventsEnable(driverHandle, eventsWereEnabled); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBFS_Open function). Function bool DRV_USBFS_HOST_EventsDisable ( DRV_HANDLE handle ); DRV_USBFS_HOST_EventsEnable Function Restores the events to the specified the original value. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1212 File drv_usbfs.h C void DRV_USBFS_HOST_EventsEnable(DRV_HANDLE handle, bool eventContext); Returns None. Description This function will restore the enable disable state of the events. The eventRestoreContext parameter should be equal to the value returned by the DRV_USBFS_HOST_EventsDisable function. Remarks None. Preconditions The handle should be valid. Example // This code shows how the DRV_USBFS_HOST_EventsDisable and // DRV_USBFS_HOST_EventsEnable function can be called to disable and enable // events. DRV_HANDLE driverHandle; bool eventsWereEnabled; // Disable the driver events. eventsWereEnabled = DRV_USBFS_HOST_EventsDisable(driverHandle); // Code in this region will not be interrupted by driver events. // Enable the driver events. DRV_USBFS_HOST_EventsEnable(driverHandle, eventsWereEnabled); Parameters Parameters Description handle Handle to the driver (returned from DRV_USBFS_Open function). eventRestoreContext Value returned by the DRV_USBFS_HOST_EventsDisable function. Function void DRV_USBFS_HOST_EventsEnable ( DRV_HANDLE handle bool eventRestoreContext ); DRV_USBFS_HOST_IRPCancel Function Cancels the specified IRP. File drv_usbfs.h C void DRV_USBFS_HOST_IRPCancel(USB_HOST_IRP * inputIRP); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1213 Description This function attempts to cancel the specified IRP. If the IRP is queued and its processing has not started, it will be cancelled successfully. If the IRP in progress, the ongoing transaction will be allowed to complete. Remarks None. Preconditions None. Example // This code shows how a submitted IRP can be cancelled. USB_HOST_IRP irp; USB_ERROR result; USB_HOST_PIPE_HANDLE controlPipe; USB_SETUP_PACKET setup; uint8_t controlTransferData[32]; irp.setup = setup; irp.data = controlTransferData; irp.size = 32; irp.flags = USB_HOST_IRP_FLAG_NONE ; irp.userData = &someApplicationObject; irp.callback = IRP_Callback; DRV_USBFS_HOST_IRPSubmit(controlPipeHandle, &irp); // Additional application logic may come here. This logic may decide to // cancel the submitted IRP. DRV_USBFS_HOST_IRPCancel(&irp); Parameters Parameters Description inputIRP Pointer to the IRP to cancel. Function void DRV_USBFS_HOST_IRPCancel(USB_HOST_IRP * inputIRP); DRV_USBFS_HOST_IRPSubmit Function Submits an IRP on a pipe. File drv_usbfs.h C USB_ERROR DRV_USBFS_HOST_IRPSubmit(DRV_USBFS_HOST_PIPE_HANDLE hPipe, USB_HOST_IRP * pinputIRP); Returns • USB_ERROR_NONE - The IRP was submitted successfully. • USB_ERROR_PARAMETER_INVALID - The pipe handle is not valid. • USB_ERROR_OSAL_FUNCTION - An error occurred in an OSAL function called in this function. Description This function submits an IRP on the specified pipe. The IRP will be added to the queue and will be processed in turn. The data will be transferred on the bus based on the USB bus scheduling rules. When the IRP has been processed, the callback function specified in the IRP will be called. The IRP status will be updated to reflect the completion status of the IRP. Remarks An IRP can also be submitted in an IRP callback function. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1214 Preconditions The pipe handle should be valid. Example // The following code shows an example of how the host layer populates // the IRP object and then submits it. IRP_Callback function is called when an // IRP has completed processing. The status of the IRP at completion can be // checked in the status flag. The size field of the irp will contain the amount // of data transferred. void IRP_Callback(USB_HOST_IRP * irp) { // irp is pointing to the IRP for which the callback has occurred. In most // cases this function will execute in an interrupt context. The application // should not perform any hardware access or interrupt un-safe operations in // this function. switch(irp->status) { case USB_HOST_IRP_STATUS_ERROR_UNKNOWN: // IRP was terminated due to an unknown error break; case USB_HOST_IRP_STATUS_ABORTED: // IRP was terminated by the application break; case USB_HOST_IRP_STATUS_ERROR_BUS: // IRP was terminated due to a bus error break; case USB_HOST_IRP_STATUS_ERROR_DATA: // IRP was terminated due to data error break; case USB_HOST_IRP_STATUS_ERROR_NAK_TIMEOUT: // IRP was terminated because of a NAK timeout break; case USB_HOST_IRP_STATUS_ERROR_STALL: // IRP was terminated because of a device sent a STALL break; case USB_HOST_IRP_STATUS_COMPLETED: // IRP has been completed break; case USB_HOST_IRP_STATUS_COMPLETED_SHORT: // IRP has been completed but the amount of data processed was less // than requested. break; default: break; } } // In the following code snippet the a control transfer IRP is submitted to a // control pipe. The setup parameter of the IRP points to the Setup command of // the control transfer. The direction of the data stage is specified by the // Setup packet. USB_HOST_IRP irp; USB_ERROR result; USB_HOST_PIPE_HANDLE controlPipe; USB_SETUP_PACKET setup; uint8_t controlTransferData[32]; Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1215 irp.setup = setup; irp.data = controlTransferData; irp.size = 32; irp.flags = USB_HOST_IRP_FLAG_NONE ; irp.userData = &someApplicationObject; irp.callback = IRP_Callback; result = DRV_USBFS_HOST_IRPSubmit(controlPipeHandle, &irp); Parameters Parameters Description hPipe Handle to the pipe to which the IRP has to be submitted. pInputIRP Pointer to the IRP. Function USB_ERROR DRV_USBFS_HOST_IRPSubmit ( DRV_USBFS_HOST_PIPE_HANDLE hPipe, USB_HOST_IRP * pInputIRP ); DRV_USBFS_HOST_PipeClose Function Closes an open pipe. File drv_usbfs.h C void DRV_USBFS_HOST_PipeClose(DRV_USBFS_HOST_PIPE_HANDLE pipeHandle); Returns None. Description This function closes an open pipe. Any IRPs scheduled on the pipe will be aborted and IRP callback functions will be called with the status as DRV_USB_HOST_IRP_STATE_ABORTED. The pipe handle will become invalid and the pipe will not accept IRPs. Remarks None. Preconditions The pipe handle should be valid. Example // This code shows how an open Host pipe can be closed. DRV_HANDLE driverHandle; DRV_USBFS_HOST_PIPE_HANDLE pipeHandle; // Close the pipe. DRV_USBFS_HOST_PipeClose(pipeHandle); Parameters Parameters Description pipeHandle Handle to the pipe to close. Function void DRV_USBFS_HOST_PipeClose ( Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1216 DRV_USBFS_HOST_PIPE_HANDLE pipeHandle ); DRV_USBFS_HOST_PipeSetup Function Open a pipe with the specified attributes. File drv_usbfs.h C DRV_USBFS_HOST_PIPE_HANDLE DRV_USBFS_HOST_PipeSetup(DRV_HANDLE client, uint8_t deviceAddress, USB_ENDPOINT endpointAndDirection, uint8_t hubAddress, uint8_t hubPort, USB_TRANSFER_TYPE pipeType, uint8_t bInterval, uint16_t wMaxPacketSize, USB_SPEED speed); Returns • DRV_USB_HOST_PIPE_HANDLE_INVALID - The pipe could not be created. • A valid Pipe Handle - The pipe was created successfully. This is an arbitrary value and will never be the same as DRV_USB_HOST_PIPE_HANDLE_INVALID. Description This function opens a communication pipe between the Host and the device endpoint. The transfer type and other attributes are specified through the function parameters. The driver does not check for available bus bandwidth, which should be done by the application (the USB Host Layer in this case) Remarks None. Preconditions The driver handle should be valid. Example // This code shows how the DRV_USBFS_HOST_PipeSetup function is called for // create a communication pipe. In this example, Bulk pipe is created // between the Host and a device. The Device address is 2 and the target // endpoint on this device is 4 . The direction of the data transfer over // this pipe is from the Host to the device. The device is connected to Port // 1 of a Hub, whose USB address is 3. The maximum size of a transaction // on this pipe is 64 bytes. This is a Bulk Pipe and hence the bInterval // field is set to 0. The target device is operating at Full Speed. DRV_HANDLE driverHandle; DRV_USBFS_HOST_PIPE_HANDLE pipeHandle; pipeHandle = DRV_USBFS_HOST_PipeSetup(driverHandle, 0x02, 0x14, 0x03, 0x01, USB_TRANSFER_TYPE_BULK, 0, 64, USB_SPEED_FULL); if(pipeHandle != DRV_USBFS_HOST_PIPE_HANDLE_INVALID) { // The pipe was created successfully. } Parameters Parameters Description client Handle to the driver (returned from DRV_USBFS_Open function). deviceAddress USB Address of the device to connect to. endpoint Endpoint on the device to connect to. hubAddress Address of the hub to which this device is connected. If not connected to a hub, this value should be set to 0. hubPort Port number of the hub to which this device is connected. pipeType Transfer type of the pipe to open. bInterval Polling interval for periodic transfers. This should be specified as defined by the USB 2.0 Specification. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1217 wMaxPacketSize This should be set to the endpoint size reported by the device in its configuration descriptors. This defines the maximum size of the transaction in a transfer on this pipe. speed The speed of the pipe. This should match the speed at which the device connected to the Host. Function DRV_USBFS_HOST_PIPE_HANDLE DRV_USBFS_HOST_PipeSetup ( DRV_HANDLE client, uint8_t deviceAddress, USB_ENDPOINT endpointAndDirection, uint8_t hubAddress, uint8_t hubPort, USB_TRANSFER_TYPE pipeType, uint8_t bInterval, uint16_t wMaxPacketSize, USB_SPEED speed ); e) Root Hub Functions DRV_USBFS_HOST_ROOT_HUB_BusSpeedGet Function This function returns the operating speed of the bus to which this root hub is connected. File drv_usbfs.h C USB_SPEED DRV_USBFS_HOST_ROOT_HUB_BusSpeedGet(DRV_HANDLE handle); Returns • USB_SPEED_FULL - The Root hub is connected to a bus that is operating at Full Speed. Description This function returns the operating speed of the bus to which this root hub is connected. Remarks None. Preconditions None. Example // This code shows how the DRV_USBFS_HOST_ROOT_HUB_BusSpeedGet function is // called to know the operating speed of the bus to which this Root hub is // connected. DRV_HANDLE driverHandle; USB_SPEED speed; speed = DRV_USBFS_HOST_ROOT_HUB_BusSpeedGet(driverHandle); Parameters Parameters Description handle Handle to the driver (returned from DRV_USBFS_Open function). Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1218 Function USB_SPEED DRV_USBFS_HOST_ROOT_HUB_BusSpeedGet( DRV_HANDLE handle); DRV_USBFS_HOST_ROOT_HUB_Initialize Function This function initializes the root hub driver. File drv_usbfs.h C void DRV_USBFS_HOST_ROOT_HUB_Initialize(DRV_HANDLE handle, USB_HOST_DEVICE_OBJ_HANDLE usbHostDeviceInfo); Returns None. Description This function initializes the root hub driver. It is called by the Host Layer at the time of processing the root hub devices. The Host Layer assigns a USB_HOST_DEVICE_INFO reference to this root hub driver. This identifies the relationship between the root hub and the Host Layer. Remarks None. Preconditions None. Example // This code shows how the USB Host Layer calls the // DRV_USBFS_HOST_ROOT_HUB_Initialize function. The usbHostDeviceInfo // parameter is an arbitrary identifier assigned by the USB Host Layer. Its // interpretation is opaque to the Root hub Driver. DRV_HANDLE drvHandle; USB_HOST_DEVICE_OBJ_HANDLE usbHostDeviceInfo = 0x10003000; DRV_USBFS_HOST_ROOT_HUB_Initialize(drvHandle, usbHostDeviceInfo); Parameters Parameters Description handle Handle to the driver. usbHostDeviceInfo Reference provided by the Host. Function void DRV_USBFS_HOST_ROOT_HUB_Initialize ( DRV_HANDLE handle, USB_HOST_DEVICE_OBJ_HANDLE usbHostDeviceInfo, ) DRV_USBFS_HOST_ROOT_HUB_MaximumCurrentGet Function Returns the maximum amount of current that this root hub can provide on the bus. File drv_usbfs.h C uint32_t DRV_USBFS_HOST_ROOT_HUB_MaximumCurrentGet(DRV_HANDLE handle); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1219 Returns Returns the maximum current (in milliamperes) that the root hub can supply. Description This function returns the maximum amount of current that this root hub can provide on the bus. Remarks None. Preconditions None. Example // This code shows how the DRV_USBFS_HOST_ROOT_HUB_MaximumCurrentGet // function is called to obtain the maximum VBUS current that the Root hub // can supply. DRV_HANDLE driverHandle; uint32_t currentMilliAmperes; currentMilliAmperes = DRV_USBFS_HOST_ROOT_HUB_MaximumCurrentGet(driverHandle); Parameters Parameters Description handle Handle to the driver (returned from DRV_USBFS_Open function). Function uint32_t DRV_USBFS_HOST_ROOT_HUB_MaximumCurrentGet( DRV_HANDLE); DRV_USBFS_HOST_ROOT_HUB_OperationEnable Function This function enables or disables root hub operation. File drv_usbfs.h C void DRV_USBFS_HOST_ROOT_HUB_OperationEnable(DRV_HANDLE handle, bool enable); Returns None. Description This function enables or disables root hub operation. When enabled, the root hub will detect devices attached to the port and will request the Host Layer to enumerate the device. This function is called by the Host Layer when it is ready to receive enumeration requests from the Host. If the operation is disabled, the root hub will not detect attached devices. Remarks None. Preconditions None. Example // This code shows how the DRV_USBFS_HOST_ROOT_HUB_OperationEnable and the // DRV_USBFS_HOST_ROOT_HUB_OperationIsEnabled functions are called to enable // the Root hub operation. DRV_HANDLE driverHandle; // Enable Root hub operation. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1220 DRV_USBFS_HOST_ROOT_HUB_OperationEnable(driverHandle); // Wait till the Root hub operation is enabled. if(DRV_USBFS_HOST_ROOT_HUB_OperationIsEnabled(driverHandle) == false) { // The operation has not completed. Call the // DRV_USBFS_HOST_ROOT_HUB_OperationIsEnabled function again to check if // the operation has completed. Note that the DRV_USBFS_Tasks function // must be allowed to run at periodic intervals to allow the enable // operation to completed. } Parameters Parameters Description handle Handle to the driver (returned from DRV_USBFS_Open function). enable If this is set to true, root hub operation is enabled. If this is set to false, root hub operation is disabled. Function void DRV_USBFS_HOST_ROOT_HUB_OperationEnable ( DRV_HANDLE handle, bool enable ); DRV_USBFS_HOST_ROOT_HUB_OperationIsEnabled Function Returns the operation enabled status of the root hub. File drv_usbfs.h C bool DRV_USBFS_HOST_ROOT_HUB_OperationIsEnabled(DRV_HANDLE handle); Returns • true - Root hub operation is enabled. • false - Root hub operation is not enabled. Description This function returns true if the DRV_USBFS_HOST_ROOT_HUB_OperationEnable function has completed enabling the Host. Remarks None. Preconditions None. Example // This code shows how the DRV_USBFS_HOST_ROOT_HUB_OperationEnable and the // DRV_USBFS_HOST_ROOT_HUB_OperationIsEnabled functions are called to enable // the Root hub operation. DRV_HANDLE driverHandle; // Enable Root hub operation. DRV_USBFS_HOST_ROOT_HUB_OperationEnable(driverHandle); // Wait till the Root hub operation is enabled. if(DRV_USBFS_HOST_ROOT_HUB_OperationIsEnabled(driverHandle) == false) { // The operation has not completed. Call the // DRV_USBFS_HOST_ROOT_HUB_OperationIsEnabled function again to check if // the operation has completed. Note that the DRV_USBFS_Tasks function Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1221 // must be allowed to run at periodic intervals to allow the enable // operation to completed. } Parameters Parameters Description handle Handle to the driver (returned from DRV_USBFS_Open function). Function bool DRV_USBFS_HOST_ROOT_HUB_OperationIsEnabled( DRV_HANDLE handle); DRV_USBFS_HOST_ROOT_HUB_PortNumbersGet Function Returns the number of ports this root hub contains. File drv_usbfs.h C uint8_t DRV_USBFS_HOST_ROOT_HUB_PortNumbersGet(DRV_HANDLE handle); Returns This function will always return 1. Description This function returns the number of ports that this root hub contains. Remarks None. Preconditions None. Example // This code shows how DRV_USBFS_HOST_ROOT_HUB_PortNumbersGet function can // be called to obtain the number of Root hub ports. DRV_HANDLE driverHandle; uint8_t nPorts; nPorts = DRV_USBFS_HOST_ROOT_HUB_PortNumbersGet(driverHandle); Parameters Parameters Description handle Handle to the driver (returned from DRV_USBFS_Open function). Function uint8_t DRV_USBFS_HOST_ROOT_HUB_PortNumbersGet( DRV_HANDLE handle); DRV_USBFS_HOST_ROOT_HUB_PortReset Function Resets the specified root hub port. File drv_usbfs.h C USB_ERROR DRV_USBFS_HOST_ROOT_HUB_PortReset(DRV_HANDLE handle, uint8_t port); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1222 Description This function resets the root hub port. The reset duration is defined by DRV_USBFS_ROOT_HUB_RESET_DURATION. The status of the reset signaling can be checked using the DRV_USBFS_ROOT_HUB_PortResetIsComplete function. Remarks The root hub on the PIC32MZ USB controller contains only one port - port 0. Preconditions None. Example // This code shows how the DRV_USB_HOST_ROOT_HUB_PortReset and the // DRV_USBFS_ROOT_HUB_PortResetIsComplete functions are called to complete a // port reset sequence. DRV_HANDLE driverHandle; // Reset Port 0. DRV_USB_HOST_ROOT_HUB_PortReset(driverHandle, 0); // Check if the Reset operation has completed. if(DRV_USBFS_ROOT_HUB_PortResetIsComplete(driverHandle, 0) == false) { // This means that the Port Reset operation has not completed yet. The // DRV_USBFS_ROOT_HUB_PortResetIsComplete function should be called // again after some time to check the status. } Parameters Parameters Description handle Handle to the driver (returned from DRV_USBFS_Open function). port Port to reset. Function void DRV_USBFS_ROOT_HUB_PortReset( DRV_HANDLE handle, uint8_t port ); DRV_USBFS_HOST_ROOT_HUB_PortResetIsComplete Function Returns true if the root hub has completed the port reset operation. File drv_usbfs.h C bool DRV_USBFS_HOST_ROOT_HUB_PortResetIsComplete(DRV_HANDLE handle, uint8_t port); Returns • true - The reset signaling has completed. • false - The reset signaling has not completed. Description This function returns true if the port reset operation has completed. It should be called after the DRV_USB_HOST_ROOT_HUB_PortReset function to check if the reset operation has completed. Remarks The root hub on this particular hardware only contains one port - port 0. Preconditions None. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1223 Example // This code shows how the DRV_USB_HOST_ROOT_HUB_PortReset and the // DRV_USBFS_ROOT_HUB_PortResetIsComplete functions are called to complete a // port reset sequence. DRV_HANDLE driverHandle; // Reset Port 0. DRV_USB_HOST_ROOT_HUB_PortReset(driverHandle, 0); // Check if the Reset operation has completed. if(DRV_USBFS_ROOT_HUB_PortResetIsComplete(driverHandle, 0) == false) { // This means that the Port Reset operation has not completed yet. The // DRV_USBFS_ROOT_HUB_PortResetIsComplete function should be called // again after some time to check the status. } Parameters Parameters Description handle Handle to the driver (returned from DRV_USBFS_Open function). port Port to check Function bool DRV_USBFS_ROOT_HUB_PortResetIsComplete ( DRV_HANDLE handle, uint8_t port ); DRV_USBFS_HOST_ROOT_HUB_PortResume Function Resumes the specified root hub port. File drv_usbfs.h C USB_ERROR DRV_USBFS_HOST_ROOT_HUB_PortResume(DRV_HANDLE handle, uint8_t port); Returns • USB_ERROR_NONE - The function executed successfully. • USB_ERROR_PARAMETER_INVALID - The driver handle is not valid or the port number does not exist. Description This function resumes the root hub. The resume duration is defined by DRV_USBFS_ROOT_HUB_RESUME_DURATION. The status of the resume signaling can be checked using the DRV_USBFS_ROOT_HUB_PortResumeIsComplete function. Remarks The root hub on this particular hardware only contains one port - port 0. Preconditions None. Example // This code shows how the DRV_USBFS_HOST_ROOT_HUB_PortResume function is // called to resume the specified port. DRV_HANDLE driverHandle; // Resume Port 0. DRV_USBFS_HOST_ROOT_HUB_PortResume(driverHandle, 0); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1224 Parameters Parameters Description handle Handle to the driver (returned from DRV_USBFS_Open function). port Port to resume. Function USB_ERROR DRV_USBFS_HOST_ROOT_HUB_PortResume ( DRV_HANDLE handle, uint8_t port ); DRV_USBFS_HOST_ROOT_HUB_PortSpeedGet Function Returns the speed of at which the port is operating. File drv_usbfs.h C USB_SPEED DRV_USBFS_HOST_ROOT_HUB_PortSpeedGet(DRV_HANDLE handle, uint8_t port); Returns • USB_SPEED_ERROR - This value is returned if the driver handle is not or if the speed information is not available or if the specified port is not valid. • USB_SPEED_FULL - A Full Speed device has been connected to the port. • USB_SPEED_LOW - A Low Speed device has been connected to the port. Description This function returns the speed at which the port is operating. Remarks The root hub on this particular hardware only contains one port - port 0. Preconditions None. Example // This code shows how the DRV_USBFS_HOST_ROOT_HUB_PortSpeedGet function is // called to know the operating speed of the port. This also indicates the // operating speed of the device connected to this port. DRV_HANDLE driverHandle; USB_SPEED speed; speed = DRV_USBFS_HOST_ROOT_HUB_PortSpeedGet(driverHandle, 0); Parameters Parameters Description handle Handle to the driver (returned from DRV_USBFS_Open function). port Port number of the port to be analyzed.. Function USB_SPEED DRV_USBFS_HOST_ROOT_HUB_PortSpeedGet ( DRV_HANDLE handle, uint8_t port ); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1225 DRV_USBFS_HOST_ROOT_HUB_PortSuspend Function Suspends the specified root hub port. File drv_usbfs.h C USB_ERROR DRV_USBFS_HOST_ROOT_HUB_PortSuspend(DRV_HANDLE handle, uint8_t port); Returns • USB_ERROR_NONE - The function executed successfully. • USB_ERROR_PARAMETER_INVALID - The driver handle is not valid or the port number does not exist. Description This function suspends the root hub port. Remarks The root hub on this particular hardware only contains one port - port 0. Preconditions None. Example // This code shows how the DRV_USBFS_HOST_ROOT_HUB_PortSuspend function is // called to suspend the specified port. DRV_HANDLE driverHandle; // Suspend Port 0. DRV_USBFS_HOST_ROOT_HUB_PortSuspend(driverHandle, 0); Parameters Parameters Description handle Handle to the driver (returned from DRV_USBFS_Open function). port Port to suspend. Function USB_ERROR DRV_USBFS_ROOT_HUB_PortSuspend( DRV_HANDLE handle, uint8_t port); f) Data Types and Constants DRV_USBFS_EVENT Enumeration Identifies the different events that the USB Driver provides. File drv_usbfs.h C typedef enum { DRV_USBFS_EVENT_ERROR = DRV_USB_EVENT_ERROR, DRV_USBFS_EVENT_RESET_DETECT = DRV_USB_EVENT_RESET_DETECT, DRV_USBFS_EVENT_RESUME_DETECT = DRV_USB_EVENT_RESUME_DETECT, DRV_USBFS_EVENT_IDLE_DETECT = DRV_USB_EVENT_IDLE_DETECT, DRV_USBFS_EVENT_STALL = DRV_USB_EVENT_STALL, DRV_USBFS_EVENT_SOF_DETECT = DRV_USB_EVENT_SOF_DETECT, DRV_USBFS_EVENT_DEVICE_SESSION_VALID = DRV_USB_EVENT_DEVICE_SESSION_VALID, DRV_USBFS_EVENT_DEVICE_SESSION_INVALID = DRV_USB_EVENT_DEVICE_SESSION_INVALID } DRV_USBFS_EVENT; Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1226 Members Members Description DRV_USBFS_EVENT_ERROR = DRV_USB_EVENT_ERROR Bus error occurred and was reported DRV_USBFS_EVENT_RESET_DETECT = DRV_USB_EVENT_RESET_DETECT Host has issued a device reset DRV_USBFS_EVENT_RESUME_DETECT = DRV_USB_EVENT_RESUME_DETECT Resume detected while USB in suspend mode DRV_USBFS_EVENT_IDLE_DETECT = DRV_USB_EVENT_IDLE_DETECT Idle detected DRV_USBFS_EVENT_STALL = DRV_USB_EVENT_STALL Stall handshake has occurred DRV_USBFS_EVENT_SOF_DETECT = DRV_USB_EVENT_SOF_DETECT Either Device received SOF or SOF threshold was reached in the Host mode operation DRV_USBFS_EVENT_DEVICE_SESSION_VALID = DRV_USB_EVENT_DEVICE_SESSION_VALID Session valid DRV_USBFS_EVENT_DEVICE_SESSION_INVALID = DRV_USB_EVENT_DEVICE_SESSION_INVALID Session Invalid Description USB Driver Events Enumeration. This enumeration identifies the different events that are generated by the USB Driver. Remarks None. DRV_USBFS_EVENT_CALLBACK Type Type of the USB Driver event callback function. File drv_usbfs.h C typedef void (* DRV_USBFS_EVENT_CALLBACK)(uintptr_t hClient, DRV_USBFS_EVENT eventType, void * eventData); Returns None. Description Type of the USB Driver Event Callback Function. Define the type of the USB Driver event callback function. The client should register an event callback function of this type when it intends to receive events from the USB Driver. The event callback function is registered using the DRV_USBFS_ClientEventCallBackSet function. Remarks None. Parameters Parameters Description hClient Handle to the driver client that registered this callback function. eventType This parameter identifies the event that caused the callback function to be called. eventData Pointer to a data structure that is related to this event. This value will be NULL if the event has no related data. DRV_USBFS_HOST_PIPE_HANDLE Type Defines the USB Driver Host Pipe Handle type. File drv_usbfs.h Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1227 C typedef uintptr_t DRV_USBFS_HOST_PIPE_HANDLE; Description USB Driver Host Pipe Handle. This type definition defines the type of the USB Driver Host Pipe Handle. Remarks None. DRV_USBFS_INIT Structure This type definition defines the Driver Initialization Data Structure. File drv_usbfs.h C typedef struct { SYS_MODULE_INIT moduleInit; USB_MODULE_ID usbID; bool stopInIdle; bool suspendInSleep; INT_SOURCE interruptSource; USB_SPEED operationSpeed; DRV_USBFS_OPMODES operationMode; void * endpointTable; uint32_t rootHubAvailableCurrent; DRV_USBFS_ROOT_HUB_PORT_POWER_ENABLE portPowerEnable; DRV_USBFS_ROOT_HUB_PORT_INDICATION portIndication; DRV_USBFS_ROOT_HUB_PORT_OVER_CURRENT_DETECT portOverCurrentDetect; } DRV_USBFS_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System Module Initialization USB_MODULE_ID usbID; Identifies the USB peripheral to be used. This should be the USB PLIB module instance identifier. bool stopInIdle; This should be set to true if the USB module must stop operation in IDLE mode bool suspendInSleep; This should be set to true if the USB module must suspend when the CPU enters sleep mode. INT_SOURCE interruptSource; Specify the interrupt source for the USB module. This should be the interrupt source identifier for the USB module instance specified in usbID. USB_SPEED operationSpeed; Specify the operational speed of the USB module. This should always be set to USB_SPEED_FULL. DRV_USBFS_OPMODES operationMode; Specify the operation mode of the USB module. This specifies if the USB module should operate as a Device, Host, or both (Dual Role operation). void * endpointTable; A pointer to the endpoint descriptor table. This should be aligned at 512 byte address boundary. The size of the table is equal to DRV_USBFS_ENDPOINT_TABLE_ENTRY_SIZE times the number of endpoints needed in the application. uint32_t rootHubAvailableCurrent; Root hub available current in milliamperes. This specifies the amount of current that root hub can provide to the attached device. This should be specified in mA. This is required when the driver is required to operate in host mode. DRV_USBFS_ROOT_HUB_PORT_POWER_ENABLE portPowerEnable; When operating in Host mode, the application can specify a Root Hub port enable function. This parameter should point to Root Hub port enable function. If this parameter is NULL, it implies that the Port is always enabled. DRV_USBFS_ROOT_HUB_PORT_INDICATION portIndication; When operating in Host mode, the application can specify a Root Port Indication. This parameter should point to the Root Port Indication function. If this parameter is NULL, it implies that Root Port Indication is not supported. DRV_USBFS_ROOT_HUB_PORT_OVER_CURRENT_DETECT portOverCurrentDetect; When operating is Host mode, the application can specify a Root Port Overcurrent detection. This parameter should point to the Root Port Indication function. If this parameter is NULL, it implies that Overcurrent detection is not supported. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1228 Description USB Device Driver Initialization Data. This structure contains all the data necessary to initialize the USB Driver. A pointer to a structure of this type, containing the desired initialization data, must be passed into the DRV_USBFS_Initialize function. Remarks None. DRV_USBFS_OPMODES Enumeration Identifies the operating modes supported by the USB Driver. File drv_usbfs.h C typedef enum { DRV_USBFS_OPMODE_DUAL_ROLE = DRV_USB_OPMODE_DUAL_ROLE, DRV_USBFS_OPMODE_DEVICE = DRV_USB_OPMODE_DEVICE, DRV_USBFS_OPMODE_HOST = DRV_USB_OPMODE_HOST, DRV_USBFS_OPMODE_OTG = DRV_USB_OPMODE_OTG } DRV_USBFS_OPMODES; Members Members Description DRV_USBFS_OPMODE_DUAL_ROLE = DRV_USB_OPMODE_DUAL_ROLE The driver should be able to switch between host and device mode DRV_USBFS_OPMODE_DEVICE = DRV_USB_OPMODE_DEVICE The driver should support device mode operation only DRV_USBFS_OPMODE_HOST = DRV_USB_OPMODE_HOST The driver should support host mode operation only DRV_USBFS_OPMODE_OTG = DRV_USB_OPMODE_OTG The driver should support the OTG protocol Description USB Operating Modes Enumeration. This enumeration identifies the operating modes supported by the USB Driver. Remarks None. DRV_USBFS_ROOT_HUB_PORT_INDICATION Type USB Root hub Application Hooks (Port Indication). File drv_usbfs.h C typedef void (* DRV_USBFS_ROOT_HUB_PORT_INDICATION)(uint8_t port, USB_HUB_PORT_INDICATOR_COLOR color, USB_HUB_PORT_INDICATOR_STATE state); Description USB Root hub Application Hooks (Port Indication). A function of the type defined here should be provided to the driver root to implement Port Indication. The root hub driver calls this function when it needs to update the state of the port indication LEDs. The application can choose to implement the Amber and Green colors as one LED or two different LEDs. The root hub driver specifies the color and the indicator attribute (on, off or blinking) when it calls this function. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1229 DRV_USBFS_ROOT_HUB_PORT_OVER_CURRENT_DETECT Type USB Root hub Application Hooks (Port Overcurrent detection). File drv_usbfs.h C typedef bool (* DRV_USBFS_ROOT_HUB_PORT_OVER_CURRENT_DETECT)(uint8_t port); Description USB Root hub Application Hooks (Port Overcurrent detection). A function of the type defined here should be provided to the driver root hub to check for port over current condition. This function will be called periodically by the root hub driver to check the Overcurrent status of the port. It should continue to return true while the Overcurrent condition exists on the port. It should return false when the Overcurrent condition does not exist. Remarks None. DRV_USBFS_ROOT_HUB_PORT_POWER_ENABLE Type USB Root hub Application Hooks (Port Power Enable/ Disable). File drv_usbfs.h C typedef void (* DRV_USBFS_ROOT_HUB_PORT_POWER_ENABLE)(uint8_t port, bool control); Description USB Root hub Application Hooks (Port Power Enable/ Disable). A function of the type defined here should be provided to the driver root to control port power. The root hub driver will call this function when it needs to enable port power. If the application circuit contains a VBUS switch, the switch should be accessed and controlled by this function. If the enable parameter is true, the switch should be enabled and VBUS should be available on the port. If the enable parameter is false, the switch should be disabled and VBUS should not be available on the port. Remarks None. DRV_USBFS_DEVICE_INTERFACE Macro USB Driver Device Mode Interface Functions. File drv_usbfs.h C #define DRV_USBFS_DEVICE_INTERFACE Description USB Driver Device Mode Interface Functions. The Device Driver interface in the Device Layer Initialization data structure should be set to this value so that Device Layer can access the USB Driver Device Mode functions. Remarks None. DRV_USBFS_ENDPOINT_TABLE_ENTRY_SIZE Macro USB Driver Endpoint Table Entry Size in bytes. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1230 File drv_usbfs.h C #define DRV_USBFS_ENDPOINT_TABLE_ENTRY_SIZE 32 Description USB Driver Endpoint Table Entry Size in bytes. This constant defines the size (in bytes) of an entry in the endpoint table. Remarks None. DRV_USBFS_HOST_INTERFACE Macro USB Driver Host Mode Interface Functions. File drv_usbfs.h C #define DRV_USBFS_HOST_INTERFACE Description USB Driver Host Mode Interface Functions. The Host Controller Driver interface in the Host Layer Initialization data structure should be set to this value so that Host Layer can access the USB Driver Host Mode functions. Remarks None. DRV_USBFS_HOST_PIPE_HANDLE_INVALID Macro Value of an Invalid Host Pipe Handle. File drv_usbfs.h C #define DRV_USBFS_HOST_PIPE_HANDLE_INVALID ((DRV_USBFS_HOST_PIPE_HANDLE)(-1)) Description USB Driver Invalid Host Pipe Handle. This constant defines the value of an Invalid Host Pipe Handle. Remarks None. DRV_USBFS_INDEX_0 Macro USB Driver Module Index 0 Definition. File drv_usbfs.h C #define DRV_USBFS_INDEX_0 0 Description USB Driver Module Index 0 Definition. This constant defines the value of USB Driver Index 0. The SYS_MODULE_INDEX parameter of the DRV_USBFS_Initialize and Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1231 DRV_USBFS_Open functions should be set to this value to identify instance 0 of the driver. Remarks These constants should be used in place of hard-coded numeric literals and should be passed into the DRV_USBFS_Initialize and DRV_USBFS_Open functions to identify the driver instance in use. These are not indicative of the number of modules that are actually supported by the microcontroller. DRV_USBFS_INDEX_1 Macro USB Driver Module Index 1 Definition. File drv_usbfs.h C #define DRV_USBFS_INDEX_1 1 Description USB Driver Module Index 1 Definition. This constant defines the value of USB Driver Index 1. The SYS_MODULE_INDEX parameter of the DRV_USBFS_Initialize and DRV_USBFS_Open functions should be set to this value to identify instance 1 of the driver. Remarks These constants should be used in place of hard-coded numeric literals and should be passed into the DRV_USBFS_Initialize and DRV_USBFS_Open functions to identify the driver instance in use. These are not indicative of the number of modules that are actually supported by the microcontroller. Files Files Name Description drv_usbfs.h PIC32MX USB Module Driver Interface File. drv_usbfs_config_template.h USB Full Speed (USBFS) Driver Configuration Template. Description drv_usbfs.h PIC32MX USB Module Driver Interface File. Enumerations Name Description DRV_USBFS_EVENT Identifies the different events that the USB Driver provides. DRV_USBFS_OPMODES Identifies the operating modes supported by the USB Driver. Functions Name Description DRV_USBFS_ClientEventCallBackSet This function sets up the event callback function that is invoked by the USB controller driver to notify the client of USB bus events. DRV_USBFS_Close Closes an opened-instance of the USB Driver. DRV_USBFS_DEVICE_AddressSet This function will set the USB module address that is obtained from the Host. DRV_USBFS_DEVICE_Attach This function will enable the attach signaling resistors on the D+ and Dlines thus letting the USB Host know that a device has been attached on the bus. DRV_USBFS_DEVICE_CurrentSpeedGet This function returns the USB speed at which the device is operating. DRV_USBFS_DEVICE_Detach This function will disable the attach signaling resistors on the D+ and Dlines thus letting the USB Host know that the device has detached from the bus. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1232 DRV_USBFS_DEVICE_EndpointDisable This function disables an endpoint. DRV_USBFS_DEVICE_EndpointDisableAll This function disables all provisioned endpoints. DRV_USBFS_DEVICE_EndpointEnable This function enables an endpoint for the specified direction and endpoint size. DRV_USBFS_DEVICE_EndpointIsEnabled This function returns the enable/disable status of the specified endpoint and direction. DRV_USBFS_DEVICE_EndpointIsStalled This function returns the stall status of the specified endpoint and direction. DRV_USBFS_DEVICE_EndpointStall This function stalls an endpoint in the specified direction. DRV_USBFS_DEVICE_EndpointStallClear This function clears the stall on an endpoint in the specified direction. DRV_USBFS_DEVICE_IRPCancel This function cancels the specific IRP that are queued and in progress at the specified endpoint. DRV_USBFS_DEVICE_IRPCancelAll This function cancels all IRPs that are queued and in progress at the specified endpoint. DRV_USBFS_DEVICE_IRPSubmit This function submits an I/O Request Packet (IRP) for processing to the Hi-Speed USB Driver. DRV_USBFS_DEVICE_RemoteWakeupStart This function causes the device to start Remote Wakeup Signalling on the bus. DRV_USBFS_DEVICE_RemoteWakeupStop This function causes the device to stop the Remote Wakeup Signalling on the bus. DRV_USBFS_DEVICE_SOFNumberGet This function will return the USB SOF packet number. DRV_USBFS_HOST_EventsDisable Disables Host mode events. DRV_USBFS_HOST_EventsEnable Restores the events to the specified the original value. DRV_USBFS_HOST_IRPCancel Cancels the specified IRP. DRV_USBFS_HOST_IRPSubmit Submits an IRP on a pipe. DRV_USBFS_HOST_PipeClose Closes an open pipe. DRV_USBFS_HOST_PipeSetup Open a pipe with the specified attributes. DRV_USBFS_HOST_ROOT_HUB_BusSpeedGet This function returns the operating speed of the bus to which this root hub is connected. DRV_USBFS_HOST_ROOT_HUB_Initialize This function initializes the root hub driver. DRV_USBFS_HOST_ROOT_HUB_MaximumCurrentGet Returns the maximum amount of current that this root hub can provide on the bus. DRV_USBFS_HOST_ROOT_HUB_OperationEnable This function enables or disables root hub operation. DRV_USBFS_HOST_ROOT_HUB_OperationIsEnabled Returns the operation enabled status of the root hub. DRV_USBFS_HOST_ROOT_HUB_PortNumbersGet Returns the number of ports this root hub contains. DRV_USBFS_HOST_ROOT_HUB_PortReset Resets the specified root hub port. DRV_USBFS_HOST_ROOT_HUB_PortResetIsComplete Returns true if the root hub has completed the port reset operation. DRV_USBFS_HOST_ROOT_HUB_PortResume Resumes the specified root hub port. DRV_USBFS_HOST_ROOT_HUB_PortSpeedGet Returns the speed of at which the port is operating. DRV_USBFS_HOST_ROOT_HUB_PortSuspend Suspends the specified root hub port. DRV_USBFS_Initialize Initializes the USB Driver. DRV_USBFS_Open Opens the specified USB Driver instance and returns a handle to it. DRV_USBFS_Status Provides the current status of the USB Driver module. DRV_USBFS_Tasks Maintains the driver's state machine when the driver is configured for Polled mode. DRV_USBFS_Tasks_ISR Maintains the driver's Interrupt state machine and implements its ISR. Macros Name Description DRV_USBFS_DEVICE_INTERFACE USB Driver Device Mode Interface Functions. DRV_USBFS_ENDPOINT_TABLE_ENTRY_SIZE USB Driver Endpoint Table Entry Size in bytes. DRV_USBFS_HOST_INTERFACE USB Driver Host Mode Interface Functions. DRV_USBFS_HOST_PIPE_HANDLE_INVALID Value of an Invalid Host Pipe Handle. DRV_USBFS_INDEX_0 USB Driver Module Index 0 Definition. DRV_USBFS_INDEX_1 USB Driver Module Index 1 Definition. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1233 Structures Name Description DRV_USBFS_INIT This type definition defines the Driver Initialization Data Structure. Types Name Description DRV_USBFS_EVENT_CALLBACK Type of the USB Driver event callback function. DRV_USBFS_HOST_PIPE_HANDLE Defines the USB Driver Host Pipe Handle type. DRV_USBFS_ROOT_HUB_PORT_INDICATION USB Root hub Application Hooks (Port Indication). DRV_USBFS_ROOT_HUB_PORT_OVER_CURRENT_DETECT USB Root hub Application Hooks (Port Overcurrent detection). DRV_USBFS_ROOT_HUB_PORT_POWER_ENABLE USB Root hub Application Hooks (Port Power Enable/ Disable). Description PIC32MX USB Module Driver Interface Header File. The PIC32MX Full speed USB Module driver provides a simple interface to manage the "USB" peripheral on PIC32MX microcontrollers. This file defines the interface definitions and prototypes for the USB driver. The driver interface meets the requirements of the MPLAB Harmony USB Host and Device Layer. File Name drv_usbfs.h Company Microchip Technology Inc. drv_usbfs_config_template.h USB Full Speed (USBFS) Driver Configuration Template. Macros Name Description DRV_USBFS_DEVICE_SUPPORT Determines if the USB Device Functionality should be enabled. DRV_USBFS_ENDPOINTS_NUMBER Configures the number of endpoints to be provisioned in the driver. DRV_USBFS_HOST_ATTACH_DEBOUNCE_DURATION Configures the time duration (in milliseconds) that the driver will wait to re-confirm a device attach. DRV_USBFS_HOST_NAK_LIMIT Configures the NAK Limit for Host Mode Control Transfers. DRV_USBFS_HOST_PIPES_NUMBER Configures the maximum number of pipes that are can be opened when the driver is operating in Host mode. DRV_USBFS_HOST_RESET_DURATION Configures the time duration (in milliseconds) of the Reset Signal. DRV_USBFS_HOST_SUPPORT Determines if the USB Host Functionality should be enabled. DRV_USBFS_INSTANCES_NUMBER Specifies the number of driver instances to be enabled in the application. DRV_USBFS_INTERRUPT_MODE Configures the driver for interrupt or polling mode operation. Description USB Full Speed Driver Configuration Template. This file lists all the configurations constants that affect the operation of the USBFS Driver. File Name drv_usbfs_config_template.h Company Microchip Technology Inc. PIC32MZ USB Driver Provides information on the USB Driver specific to PIC32MZ devices. Description The PIC32MZ USB Driver in MPLAB Harmony provides API functions that allow the MPLAB Harmony USB Host and Device Stack to access the Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1234 USB while operating on a PIC32MZ microcontroller. The driver implements the USB Driver Common Interface required by the USB Host and Device Stack. It abstracts the USB module operational details from the Host and Device Stack and provides the stacks with a modular access mechanism to the USB. The PIC32MZ USB Driver features the following: • USB 2.0 High Speed and Full Speed operation in Peripheral mode • USB 2.0 High Speed, Full Speed and Low Speed USB Peripheral Support in Host mode • Designed for Dual Role Operation • Capable of operating multiple USB modules • Features non-blocking function and is interoperable with other MPLAB Harmony modules • Features thread safe functions when operating within an RTOS • Capable of operating in Polled and Interrupt modes • Implements the USB Driver Common Interface required by the MPLAB Harmony USB Host and Device Stack • Completely configurable through the MPLAB Harmony Configurator (MHC) • Implements feature separation (Host and Device mode functions are implemented across different files) • Designed to use the module’s built-in DMA controller and transfer scheduler Note: This help section only discusses features that are unique to the PIC32MZ USB Driver and are not a part of the USB Driver Common Interface. The driver functions that implement the USB Driver Common Interface are described in the Common Interface Help section. While the PIC32MZ USB module supports USB "On-The-Go" (OTG), the PIC32MZ Driver does not currently implement USB OTG protocol support. This help section only provides relevant information about the operation of the USB. The reader is encouraged to refer to the USB 2.0 Specification available at www.usb.org for a detailed explanation of USB protocol. Using the Library This topic describes the basic architecture of the USB PIC32MZ Driver Library and provides information and examples on its use. Description Interface Header File: drv_usbhs.h The interface to the PIC32MZ USB Driver library is defined in the drv_usbhs.h header file. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Library Overview Provides an overview of the library. Description The PIC32MZ USB Driver will typically be used by a USB Host and/or Device Stack. The USB Host and Device Stack operate as driver client applications. The driver is initialized as part of the MPLAB Harmony System Initialization. The driver initialization data structure specifies the operation mode (Host, Device, or Dual Role) of the driver. The driver features task routines to be called in the MPLAB Harmony application tasks function (SYS_Tasks function) and the USB Module Interrupt Service Routine (ISR). The Host and the Device Stack can open the driver only when initialization has completed. It will continue to return an invalid driver handle while the initialization is in progress. Once opened, the Device Mode function can be called if the driver is operating in Device mode. The Host Mode function can be called if the driver is operating in Host mode. In Dual Role operation mode, the driver supports Host and Device operation in the same application. Even then, the driver will either operate as a USB Host or Device. OTG operation is not supported. The PIC32MZ USB Driver features RTOS thread-safe functions. This allows the driver client application to safely call driver functions across different RTOS threads. Not all of the driver functions are interrupt-safe. In addition to the USB Driver, which implements the USB Driver Common Interface, the PIC32MZ USB Driver implements functions which are required for its operation in the MPLAB Harmony framework. The following table lists the different categories of functions in the PIC32MZ USB Driver. Library Interface Section Description System Function These functions are accessed by the MPLAB Harmony System module. They allow the driver to be initialized, deinitialized and maintained. These functions are implemented in the drv_usbhs.c source file. Client Core Functions These functions allow the USB Host and Device Stack to open, close and perform other general driver operations. These functions are a part of the USB Driver Common Interface and are implemented in drv_usbhs.c source file. Device Mode Operation Functions These functions allow the USB Device Stack to perform USB Device mode specific driver operations. These functions are a part of the USB Driver Common Interface and are implemented in drv_usbhs_device.c source file Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1235 Host Mode Operation Functions These functions allow the USB Host Stack to perform USB Host mode specific driver operations. These functions are a part of the USB Driver Common Interface and are implemented in drv_usbhs_host.c source file. Root Hub Functions These functions allow the USB Host Stack to access the driver Root hub operation. These functions are a part of the USB Driver Common Interface and are implemented in drv_usbhs_host.c source file. Abstraction Model Provides information on the abstraction model for the library. Description The PIC32MZ USB Driver implements the abstraction model defined by the USB Driver Common interface. This interface abstracts USB module specific details and provides a module independent interface to the driver client applications. While operating in Device mode, the driver expects the client application (the USB Device Stack) to enable endpoints and then submit I/O request packet (IRP) requests to the enabled endpoints. Multiple IRPs can be queued on an endpoint. The driver calls the IRP callback function when the IRP is processed. The driver allows the client application to also attach and detach the device on the bus. It generates events which indicate USB states. While operating in Host mode, the driver expects the client application (the USB Host Stack) to open pipes to endpoints on the connected device. The client application can then submit IRPs to the pipes. Multiple IRPs can be queued on a pipe. The driver calls the IRP callback function when the IRP is processed. The driver will call application defined functions to enumerate and denumerate a device. These functions are called when the driver detect device attach and detach respectively. The driver also exports root hub functions to the client application. This allows the client application to treat the driver as a single port hub Please refer to the PIC32 USB Driver Common Interface help section for more details on the driver abstraction model. How the Library Works Provides information on how the library works. Description This section only explains aspects of driver operation which are unique to the PIC32MZ USB Driver. Major driver operations are described in the PIC32 USB Driver Common Interface help section. Driver Initialization Note: While generating a MPLAB Harmony USB project with MHC, the initialization code for the driver is generated automatically based on selections made in the USB Host stack or Device Stack Configuration trees. The PIC32MZ USB Driver must be initialized so that a client application can open. The client application will not be able to open the driver if the initialization is in progress or has failed. The driver is initialized by calling the DRV_USBHS_Initialize function. This function is called from the SYS_Initialize function in the MPLAB Harmony application project and accepts two input parameters. The index parameter defines the instance of the USB Driver to be initialized. This becomes significant when the PIC32MZ microcontroller has more than one USB module. The init parameter is a driver-specific data structure of the type DRV_USBHS_INIT. This structure is shown in the following code example. /* This code show the PIC32MZ USB Driver Initialization data structure. * A structure of this type must be provided to the DRV_USBHS_Initialize * function. */ typedef struct { /* System Module Initialization */ SYS_MODULE_INIT moduleInit; /* Identifies the USB peripheral to be used. This should be the USB PLIB module instance identifier. */ uint8_t usbID; /* This should be set to true if the USB module must stop operation in Idle mode */ bool stopInIdle; /* This should be set to true if the USB module must suspend when the CPU enters Sleep mode. */ bool suspendInSleep; /* Specify the interrupt source for the USB module. This should be Interrupt Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1236 PLIB Interrupt source identifier for the USB module instance specified in usbID. */ INT_SOURCE interruptSource; /* Specify the interrupt source for the USB module specific DMA controller. * This should be the PLIB Interrupt source identified for the USB * module instance specified in usbID. */ INT_SOURCE interruptSourceUSBDma; /* Specify the operational speed of the USB module. This should always be set to USB_SPEED_FULL. */ USB_SPEED operationSpeed; /* Specify the operation mode of the USB module. This defines if the USB * module will support Device, Host or Dual Role operation */ DRV_USBHS_OPMODES operationMode; /* A pointer to the endpoint descriptor table. This should be aligned at 512 byte address boundary. The size of the table is equal to the DRV_USBHS_ENDPOINT_TABLE_ENTRY_SIZE times the number of endpoints needed in the application. */ void * endpointTable; /* Root hub available current in mA. This specifies the amount of current that root hub can provide to the attached device. This should be specified in mA. This is required when the driver is required to operate in host mode. */ uint32_t rootHubAvailableCurrent; /* When operating in Host mode, the application can specify a Root Hub port enable function. This parameter should point to Root Hub port enable function. If this parameter is NULL, it implies that the Port is always enabled. */ DRV_USBHS_ROOT_HUB_PORT_POWER_ENABLE portPowerEnable; /* When operating in Host mode, the application can specify a Root Port Indication. This parameter should point to the Root Port Indication function. If this parameter is NULL, it implies that Root Port Indication is not supported. */ DRV_USBHS_ROOT_HUB_PORT_INDICATION portIndication; /* When operating is Host mode, the application can specify a Root Port Overcurrent detection. This parameter should point to the Root Port Indication function. If this parameter is NULL, it implies that Overcurrent detection is not supported. */ DRV_USBHS_ROOT_HUB_PORT_OVER_CURRENT_DETECT portOverCurrentDetect; } DRV_USBHS_INIT; The operationMode parameter defines the driver operation mode. This can be set to DRV_USBFS_OPMODE_DEVICE, DRV_USBFS_OPMODE_HOST, or DRV_USBFS_OPMODE_DUAL_ROLE for Device, Host and Dual Role operation, respectively. The rootHubAvailableCurrent parameter should be set to the maximum current that the VBUS power supply can provide on the bus. The driver does not use this information directly. It provides this data to the client application while operating in Host mode. The portPowerEnable parameter must point to a Port Power Enable function. The driver, while operating in Host mode, will call this function to enable the VBUS switch. This function should activate the VBUS switch if the driver calls this function with the enable parameter set to true. It should deactivate the switch if the driver calls this function with the enable parameter set to false. This parameter should be set to NULL if such a switch (of the switch control) is not available in the application. The portIndication parameter must point to a Port Indication function. The driver, while operating in Host mode, will call this function to indicate the current state of the port. The driver will call this function with LED color status as defined in Chapter 11 of the USB 2.0 Specification. This parameter should be set to NULL if such a LED indication is not available in the application. The portOverCurrentDetect parameter must point to a Port Overcurrent Detect function. The driver, while operating in Host mode, will call this function periodically to check if the attached device is overdrawing current. If the function should return true if such a condition exists. This parameter should be set to NULL if such detection is not available in the application. The following code example shows initialization of the driver for Device mode operation. /* This code shows an example of DRV_USBHS_INIT data structure for * Device mode operation. Here the driver is initialized to work with USB0 USB * module. */ Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1237 DRV_USBHS_INIT init; SYS_MODULE_OBJ usbDriverObj; const DRV_USBHS_INIT drvUSBInit = { /* Interrupt Source for USB module */ .interruptSource = INT_SOURCE_USB_1, /* DMA Interrupt Source for USB module */ .interruptSourceUSBDma = INT_SOURCE_USB_1_DMA, /* System module initialization */ .moduleInit = {SYS_MODULE_POWER_RUN_FULL}, /* Module operate in device mode */ .operationMode = DRV_USBHS_OPMODE_DEVICE, /* Module operated at high speed */ .operationSpeed = USB_SPEED_HIGH, /* Stop in idle */ .stopInIdle = false, /* Suspend in sleep */ .suspendInSleep = false, /* Identifies peripheral (PLIB-level) ID */ .usbID = USBHS_ID_0 }; void SYS_Initialize(void) { /* Initialize the USB Driver. Note how the init parameter is typecast to * SYS_MODULE_INIT type. The SYS_MODULE_OBJ returned by this function call * is passed to the driver tasks routine. DRV_USBHS_INDEX_0 is helper * constant defined in drv_usbfs.h */ usbDriverObj = DRV_USBHS_Initialize(DRV_USBHS_INDEX_0, (SYS_MODULE_INIT *)(drvUSBInit)); } void SYS_Tasks(void) { /* The polled state of the USB driver is updated by calling the * DRV_USBHS_Tasks function in the SYS_Tasks() function. The * DRV_USBHS_Tasks() takes the driver module object returned by the * DRV_USBHS_Initialize funciton as a parameter. */ DRV_USBHS_Tasks(usbDriverObj); } void __ISR(_USB_VECTOR, ipl4AUTO) _IntHandlerUSBInstance0(void) { /* The DRV_USBHS_Tasks_ISR function update the interrupt state of the USB * Driver. If the driver is configured for Polling mode, this function need * not be invoked or included in the project. */ DRV_USBHS_Tasks_ISR(usbDriverObj); } void __ISR ( _USB_DMA_VECTOR,ipl4AUTO) _IntHandlerUSBInstance0_USBDMA ( void ) { DRV_USBHS_Tasks_ISR_USBDMA(usbDriverObj); } The following code example shows initialization of the driver for Host mode operation. /* This code shows an example of how the Hi-Speed USB (USBHS) driver can be configured * for Host mode operation. In this example, the * BSP_USBVBUSSwitchOverCurrentDetect function checks for over current condition * and the BSP_USBVBUSPowerEnable function enables the VBUS power. The port Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1238 * indication function is not implemented and hence the portIndication member of * the initialization data structure is set to NULL. */ /* The implementation of the port over current detect, indication and the VBUS * power supply functions is discussed later in this help section. */ DRV_USBHS_INIT drvUSBHSInit = { /* This should always be set to SYS_MODULE_POWER_RUN_FULL. */ .moduleInit = {SYS_MODULE_POWER_RUN_FULL}, /* Interrupt Source for the USB module */ .interruptSource = INT_SOURCE_USB_1, /* Interrupt Source for the USB DMA module */ .interruptSourceUSBDma = INT_SOURCE_USB_1_DMA, /* Configure for host mode operation. */ .operationMode = DRV_USBHS_OPMODE_HOST, /* The driver should run at high speed. */ .operationSpeed = USB_SPEED_HIGH, /* Port indication function is not implemented and is not available */ .portIndication = NULL, /* This is the VBUS Power enable function */ .portPowerEnable = BSP_USBVBUSPowerEnable, /* This is the over current detect function. */ .portOverCurrentDetect = BSP_USBVBUSSwitchOverCurrentDetect, /* Here we state that the VBUS power supply can provide at most 500 mA of * current */ .rootHubAvailableCurrent = 500, /* Moudule will operate in IDLE. */ .stopInIdle = false, /* Module will not suspend automatically in sleep */ .suspendInSleep = false, /* USB Module ID is 1 */ .usbID = USBHS_ID_0 }; void SYS_Initialize(void) { /* Initialize the USB Driver. Note how the init parameter is typecast to * SYS_MODULE_INIT type. The SYS_MODULE_OBJ returned by this function call * is passed to the driver tasks routine. DRV_USBHS_INDEX_0 is helper * constant defined in drv_usbfs.h */ usbDriverObj = DRV_USBHS_Initialize(DRV_USBHS_INDEX_0, (SYS_MODULE_INIT *)(drvUSBInit)); } void SYS_Tasks(void) { /* The polled state of the USB driver is updated by calling the * DRV_USBHS_Tasks function in the SYS_Tasks() function. The * DRV_USBHS_Tasks takes the driver module object returned by the * DRV_USBHS_Initialize funciton as a parameter. */ DRV_USBHS_Tasks(usbDriverObj); } void __ISR( _USB_VECTOR , IPL4AUTO)_IntHandler_USB_stub ( void ) { Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1239 /* The DRV_USBHS_Tasks_ISR function updates the interrupt state of the USB * Driver. If the driver is configured for polling mode, this function need * not be invoked or included in the project. */ DRV_USBHS_Tasks_ISR(usbDriverObj); } void __ISR ( _USB_DMA_VECTOR, IPL4AUTO) _IntHandlerUSBInstance0_USBDMA ( void ) { /* The DRV_USBHS_Tasks_ISR_USBDMA function update the DMA transfer state of * the USB Driver. */ DRV_USBHS_Tasks_ISR_USBDMA(usbDriverObj); } The PIC32MX USB Driver requires definition of configuration constants to be available in the system_config.h file of the MPLAB Harmony Application Project Configuration. Refer to the Configuring the Library section for details. Multi-client Operation The PIC32MZ USB Driver supports multi-client operation. In that, it can be opened by two application clients. This is required where Dual Operation is desired. The following should be noted when using multi-client operation: • The driver should be initialized for Dual Role Operation mode. • The DRV_USBHS_Open function can be called at the most twice in the application. The driver supports a maximum of two clients. • A client can access either the host or device functionality of the driver. It cannot do both. • It is possible for the two clients to operate in two different threads while operating with an RTOS. Note: The typical the application clients for PIC32MZ USB Driver would be the MPLAB Harmony USB Host and Device Stack. The complexity of operating the driver in Dual Role mode is handled by the stack operation. The MHC will configure the driver for Dual Role operation when such operation is selected in USB Stack configuration tree. USB Driver Common Interface The PIC32MZ USB Driver exports its implementation of the USB Driver Common Interface to the Host and Device Layer via the DRV_USBHS_HOST_INTERFACE and DRV_USBHS_DEVICE_INTERFACE structures. The DRV_USBHS_HOST_INTERFACE structure is defined in the drv_usbhs_host.c file. The following code example shows this structure. /********************************************************** * This structure is a set of pointer to the USBHS driver * functions. It is provided to the host and device layer * as the interface to the driver. * *******************************************************/ DRV_USB_HOST_INTERFACE gDrvUSBHSHostInterface = { .open = DRV_USBHS_Open, .close = DRV_USBHS_Close, .eventHandlerSet = DRV_USBHS_ClientEventCallBackSet, .hostIRPSubmit = DRV_USBHS_HOST_IRPSubmit, .hostIRPCancel = DRV_USBHS_HOST_IRPCancel, .hostPipeSetup = DRV_USBHS_HOST_PipeSetup, .hostPipeClose = DRV_USBHS_HOST_PipeClose, .hostEventsDisable = DRV_USBHS_HOST_EventsDisable, .hostEventsEnable = DRV_USBHS_HOST_EventsEnable, .rootHubInterface.rootHubPortInterface.hubPortReset = DRV_USBHS_HOST_ROOT_HUB_PortReset, .rootHubInterface.rootHubPortInterface.hubPortSpeedGet = DRV_USBHS_HOST_ROOT_HUB_PortSpeedGet, .rootHubInterface.rootHubPortInterface.hubPortResetIsComplete = DRV_USBHS_HOST_ROOT_HUB_PortResetIsComplete, .rootHubInterface.rootHubPortInterface.hubPortSuspend = DRV_USBHS_HOST_ROOT_HUB_PortSuspend, .rootHubInterface.rootHubPortInterface.hubPortResume = DRV_USBHS_HOST_ROOT_HUB_PortResume, .rootHubInterface.rootHubMaxCurrentGet = DRV_USBHS_HOST_ROOT_HUB_MaximumCurrentGet, .rootHubInterface.rootHubPortNumbersGet = DRV_USBHS_HOST_ROOT_HUB_PortNumbersGet, .rootHubInterface.rootHubSpeedGet = DRV_USBHS_HOST_ROOT_HUB_BusSpeedGet, .rootHubInterface.rootHubInitialize = DRV_USBHS_HOST_ROOT_HUB_Initialize, .rootHubInterface.rootHubOperationEnable = DRV_USBHS_HOST_ROOT_HUB_OperationEnable, .rootHubInterface.rootHubOperationIsEnabled = DRV_USBHS_HOST_ROOT_HUB_OperationIsEnabled, }; The DRV_USBFS_DEVICE_INTERFACE structure is defined in the drv_usbhs_device.c file. The following code example shows this structure. The MPLAB Harmony USB Host and Device stack perform driver independent access through the function pointers contained in these structures. /***************************************************** Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1240 * This structure is a pointer to a set of USB Driver * Device mode functions. This set is exported to the * device layer when the device layer must use the * PIC32MZ USB Controller. ******************************************************/ DRV_USB_DEVICE_INTERFACE gDrvUSBHSDeviceInterface = { .open = DRV_USBHS_Open, .close = DRV_USBHS_Close, .eventHandlerSet = DRV_USBHS_ClientEventCallBackSet, .deviceAddressSet = DRV_USBHS_DEVICE_AddressSet, .deviceCurrentSpeedGet = DRV_USBHS_DEVICE_CurrentSpeedGet, .deviceSOFNumberGet = DRV_USBHS_DEVICE_SOFNumberGet, .deviceAttach = DRV_USBHS_DEVICE_Attach, .deviceDetach = DRV_USBHS_DEVICE_Detach, .deviceEndpointEnable = DRV_USBHS_DEVICE_EndpointEnable, .deviceEndpointDisable = DRV_USBHS_DEVICE_EndpointDisable, .deviceEndpointStall = DRV_USBHS_DEVICE_EndpointStall, .deviceEndpointStallClear = DRV_USBHS_DEVICE_EndpointStallClear, .deviceEndpointIsEnabled = DRV_USBHS_DEVICE_EndpointIsEnabled, .deviceEndpointIsStalled = DRV_USBHS_DEVICE_EndpointIsStalled, .deviceIRPSubmit = DRV_USBHS_DEVICE_IRPSubmit, .deviceIRPCancelAll = DRV_USBHS_DEVICE_IRPCancelAll, .deviceRemoteWakeupStop = DRV_USBHS_DEVICE_RemoteWakeupStop, .deviceRemoteWakeupStart = DRV_USBHS_DEVICE_RemoteWakeupStart, .deviceTestModeEnter = DRV_USBHS_DEVICE_TestModeEnter }; Operation with RTOS The PIC32MZ USB Driver is designed to operate with a RTOS. The driver implementation uses the MPLAB Harmony Operating System Abstraction Layer (OSAL). This allows the driver to function with entire range of RTOSes supported in MPLAB Harmony. The following points must be considered while using the driver with an RTOS. • The driver can be opened from different threads • In Device mode, an enabled endpoint should only be accessed from one thread. For example, if an application requires two endpoints, Endpoint 2 and Endpoint 3, the application could contain two threads, one accessing Endpoint 2 and another accessing Endpoint 3. The thread accessing Endpoint 2 cannot access Endpoint 3. • While operating in Host mode, endpoint pipes can be opened from different threads. A pipe handle to an open pipe cannot be shared across threads. USB DMA Operation The PIC32MZ USB module features a built-in DMA controller. This controller works independently of the PIC32MZ DMA controller. The PIC32MZ USB Driver uses USB DMA controller to expedite transfer of memory from the USB module FIFO to user application memory. The following should be noted for the USB DMA controller: • If the PIC32MZ USB Driver could not allocate a DMA channel (all channels are busy), it will use the CPU instructions to unload the endpoint FIFOs • The USB module and the USB DMA controller interrupt priorities should be the same • The application buffer start address should always be aligned on a 16-byte boundary and should be placed in coherent memory. Refer to the description of the DRV_USBHS_HOST_IRPSubmit and DRV_USBHS_DEVICE_IRPSubmit functions for details on how the user application buffer should be allocated. Root Hub Operation The PIC32MZ USB Driver implements a Root Hub Driver Interface. This allows the driver to emulate a hub. The USB Host Stack enumerates the Root Hub as a device. The Host Stack then does not differentiate between an external hub and the root hub. While emulating a hub, the PIC32MZ USB Driver Root Hub appears as a single port hub. As a part of the Root Hub interface, the PIC32MZ USB Driver requires the application to supply functions for hub features that it does not implement. These features are: • Port Overcurrent Detect • VBUS Switch Control • Port Indication A pointer to these functions (if implemented) must be supplied through the driver initialization data (of the type DRV_USBHS_INIT) structure at the time of driver initialization. The application has the option of not implementing these functions. In such a case, the function pointers for the unimplemented function, in the initialization data structure should be set to NULL. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1241 The root hub driver must also be able to communicate the maximum current capability of its port to the USB Host Layer. The PIC32MZ USB Controller does not contain built-in (hardware implemented) functionality for controlling the root hub port current. To facilitate this request, the driver will report the current capability that was specified in the rootHubAvailableCurrent parameter of the driver initialization data structure. The application must set this parameter to report the current supply capability of the VBUS power supply. The USB Host Layer uses this value to manage the bus current budget. If a connected device reports a configuration that requires more current than what the VBUS power supply can provide, the host will not set the configuration. Port Overcurrent Detect The Root Hub operation in PIC32MZ USB Driver will periodically call a Port Overcurrent Detect function to detect if an overcurrent condition is active on the port. The application must supply this function if port overcurrent detection is needed. The PIC32MZ USB Controller does not contain built-in (hardware implemented) functionality for checking overcurrent condition. The overcurrent condition on the port can occur in a case where the attached device has malfunctioned or when the USB VBUS line has short circuited to ground. The signature of the function and an example implementation is shown in the following code example. The function must return (and must continue to return) true if an overcurrent condition exists on the port. /* This code shows an example implementation of the * portOverCurrentDetect function. The PIC32MZ USB Driver will call this * function periodically to check if an over current condition exists on the * port. In this example, we assume that the over current detect pin from an * external circuit in the system, is connected to port RD0 and the pin logic * is active high. The function must return true if an over current condition is * present on this pin */ bool BSP_USBVBUSSwitchOverCurrentDetect(uint8_t port) { if(PLIB_PORTS_PinGet(PORTS_ID_0, PORT_CHANNEL_D, 0) == 1) { return(true); } else { return(false); } } VBUS Switch Control The PIC32MZ USB Driver Root Hub operation will attempt to control the VBUS power supply to the port. Because the PIC32MZ USB Controller does not contain built-in (hardware implemented) functionality for checking controlling VBUS, such a control function must be supplied by the application. The root hub operation will access this function when the PIC32MX USB Driver will call the portPowerEnable function as a part of the Bus Enable sequence. The following code shows an example of how this function can be implemented. /* This code shows an example implementation of the VBUS Power Enable * function. The PIC32MZ USB Driver will call this function as a part of bus * enable function. In this example, it is assumed that system contains an * external VBUS power switch and this is control by port RB5. */ void BSP_USBVBUSPowerEnable(uint8_t port, bool enable) { if(enable) { PLIB_PORTS_PinSet(PORTS_ID_0, PORT_CHANNEL_B, PORTS_BIT_POS_5); } else { PLIB_PORTS_PinClear(PORTS_ID_0, PORT_CHANNEL_B, PORTS_BIT_POS_5); } } Port Indication Function The Root Hub Operation in the PIC32MZ USB Driver allows display of Port LED status. If the application requires this indication, it must implement a function which the Root Hub operation would call when a change in the Root Hub port has occurred. The port indication operation is specified in Section 11.5.3 of the USB 2.0 Specification. /* This code shows an example implementation of the port indication * function. The PIC32MZ USB Driver call this function when it wants to indicate * port status. It is assumed that three function to switch off, blink and * switch on an LED are available. It is further assumed that these function Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1242 * accept the color of the LED to operated on. */ void BSP_RootHubPortIndication ( uint8_t port, USB_HUB_PORT_INDICATOR_COLOR color, USB_HUB_PORT_INDICATOR_STATE state ) { /* The color parameter indicates the color of the LED to be affected. The * color will be either USB_HUB_PORT_INDICATOR_COLOR_GREEN or * USB_HUB_PORT_INDICATOR_COLOR_AMBER. */ switch (state) { case USB_HUB_PORT_INDICATOR_STATE_OFF: BSP_SwitchLEDOff(color); break; case USB_HUB_PORT_INDICATOR_STATE_BLINKING: BSP_LEDBlink(color); break; case USB_HUB_PORT_INDICATOR_STATE_ON: BSP_SwitchLEDOn(color); break; default: break; } } Configuring the Library Provides information on the configuring the library. Macros Name Description DRV_USBHS_DEVICE_SUPPORT Determines if the USB Device Functionality should be enabled. DRV_USBHS_ENDPOINTS_NUMBER Configures the number of endpoints to be provisioned in the driver. DRV_USBHS_HOST_ATTACH_DEBOUNCE_DURATION Configures the time duration (in milliseconds) that the driver will wait to reconfirm a device attach. DRV_USBHS_HOST_NAK_LIMIT Configures the NAK Limit for Host Mode Control Transfers. DRV_USBHS_HOST_PIPES_NUMBER Configures the maximum number of pipes that are can be opened when the driver is operating in Host mode. DRV_USBHS_HOST_RESET_DURATION Configures the time duration (in milliseconds) of the Reset Signal. DRV_USBHS_HOST_SUPPORT Determines if the USB Host Functionality should be enabled. DRV_USBHS_INSTANCES_NUMBER Specifies the number of driver instances to be enabled in the application. DRV_USBHS_INTERRUPT_MODE Configures the driver for interrupt or polling mode operation. Description The PIC32MZ USB Driver requires the specification of compile-time configuration macros. These macros define resource usage, feature availability, and dynamic behavior of the driver. These configuration macros should be defined in the system_config.h file. This header can be placed anywhere, 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. DRV_USBHS_DEVICE_SUPPORT Macro Determines if the USB Device Functionality should be enabled. File drv_usbhs_config_template.h C #define DRV_USBHS_DEVICE_SUPPORT true Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1243 Description Hi-Speed USB Driver Device Mode Support. This constant should be set to true if USB device support is required in the application. It should be set to false if device support is not required. Remarks This constant should always be defined. DRV_USBHS_ENDPOINTS_NUMBER Macro Configures the number of endpoints to be provisioned in the driver. File drv_usbhs_config_template.h C #define DRV_USBHS_ENDPOINTS_NUMBER 3 Description Hi-Speed USB Driver Endpoint Numbers. This constant configures the number of endpoints that the driver needs to manage. When DRV_USBHS_DEVICE_SUPPORT is enabled, this constant should be set to the total number of endpoints to be enabled in the device. When enabled, an endpoint can be used for communication. Using any direction of an endpoint will require that the entire endpoint to be enabled. Consider the case of a composite USB Device that contains a CDC and MSD function. The CDC function will require one Bulk endpoint (OUT and IN directions) and one Interrupt endpoint (IN direction). The MSD function will require one Bulk endpoint (IN and OUT directions). This design can be implemented by using four endpoints. Endpoint 0 is used for the mandatory control interface. Endpoint 1 is used for CDC Bulk interface. Endpoint 2 is used for CDC Interrupt interface and Endpoint 3 is used for MSD Bulk Interface. The constant should then be set to 4. For Host mode operation, this constant should be set to 1. Setting this value to greater than 1 will result in unused data memory allocation. Remarks This constant should always be defined. DRV_USBHS_HOST_ATTACH_DEBOUNCE_DURATION Macro Configures the time duration (in milliseconds) that the driver will wait to reconfirm a device attach. File drv_usbhs_config_template.h C #define DRV_USBHS_HOST_ATTACH_DEBOUNCE_DURATION 500 Description Hi-Speed USB Driver Host Mode Attach Debounce Duration. This constant configures the time duration (in milliseconds) that the driver will wait to reconfirm a device attach. When the driver first detects a device attach, it will start a timer for the duration specified by the constant. When the timer expires, the driver will check if the device is still attached. If so, the driver will then signal an attach event to the host stack. The duration allows for the device attach to become electro-mechanically stable. Remarks This constant should always be defined when DRV_USBHS_HOST_SUPPORT is set to true. DRV_USBHS_HOST_NAK_LIMIT Macro Configures the NAK Limit for Host Mode Control Transfers. File drv_usbhs_config_template.h C #define DRV_USBHS_HOST_NAK_LIMIT 2000 Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1244 Description Hi-Speed USB Driver Host Mode Control Transfers NAK Limit. This constant configures the number of NAKs that the driver can accept from the device in the data stage of a control transfer before aborting the control transfer with a USB_HOST_IRP_STATUS_ERROR_NAK_TIMEOUT. Setting this constant to 0 will disable NAK limit checking. This constant should be adjusted to enable USB host compatibility with USB Devices that require more time to process control transfers. Remarks This constant should always be defined when DRV_USBHS_HOST_SUPPORT is set to true. DRV_USBHS_HOST_PIPES_NUMBER Macro Configures the maximum number of pipes that are can be opened when the driver is operating in Host mode. File drv_usbhs_config_template.h C #define DRV_USBHS_HOST_PIPES_NUMBER 10 Description Hi-Speed USB Driver Host Mode Pipes Number. This constant configures the maximum number of pipes that can be opened when the driver is operating in Host mode. Calling the DRV_USBHS_HOST_PipeSetup function will cause a pipe to be opened. Calling this function when DRV_USBHS_HOST_PIPES_NUMBER number of pipes have already been opened will cause the function to return an Invalid Pipe Handle. This constant should be configured to account for the maximum number of devices and the device types to be supported by the host application. For example, if the USB Host application must support two USB Mass Storage devices and one CDC device. A CDC device requires four pipes and a Mass Storage Device requires three pipes. This constant should therefore be set to a value of 9 ( four bulk pipes for two Mass Storage devices + two bulk pipes and one Interrupt pipe for one CDC device and two control pipes for two devices). Allocating pipes consumes data memory. While enabling support for multiple devices, through a Hub, the application should consider the worst case requirement while configuring this constant. For example, a case where devices with the most number of pipe requirements are connected to the hub. At the same time, setting this constant to more than what is required will consume data memory. Remarks This constant should always be defined when DRV_USBHS_HOST_SUPPORT is set to true. DRV_USBHS_HOST_RESET_DURATION Macro Configures the time duration (in milliseconds) of the Reset Signal. File drv_usbhs_config_template.h C #define DRV_USBHS_HOST_RESET_DURATION 100 Description Hi-Speed USB Driver Host Mode Reset Duration. This constant configures the duration of the reset signal. The driver generates a reset signal when the USB Host stack requests for a root hub port reset. The driver will generate the reset signal for the duration specified by this constant and will then stop generating the reset signal. Remarks This constant should always be defined when DRV_USBHS_HOST_SUPPORT is set to true. DRV_USBHS_HOST_SUPPORT Macro Determines if the USB Host Functionality should be enabled. File drv_usbhs_config_template.h Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1245 C #define DRV_USBHS_HOST_SUPPORT false Description Hi-Speed USB Driver Host Mode Support. This constant should be set to true if USB Host mode support is required in the application. It should be set to false if host support is not required. Remarks This constant should always be defined. DRV_USBHS_INSTANCES_NUMBER Macro Specifies the number of driver instances to be enabled in the application. File drv_usbhs_config_template.h C #define DRV_USBHS_INSTANCES_NUMBER 1 Description Hi-Speed USB Driver Instances Number. This constant defines the number of driver instances to be enabled in the application. This will be typically be the number of USB controllers to be used in the application. On PIC32MZ microcontrollers that have one USB controller, this value will always be 1. On PIC32MZ microcontrollers that have two USB controllers, this value could be one or two, depending on whether one or two USB segments are required. To conserve data memory, this constant should be set to exactly the number of USB controllers that are required in the system. Remarks This constant should always be defined. DRV_USBHS_INTERRUPT_MODE Macro Configures the driver for interrupt or polling mode operation. File drv_usbhs_config_template.h C #define DRV_USBHS_INTERRUPT_MODE true Description Hi-Speed USB Driver Interrupt Mode. This constant configures the driver for interrupt or polling operation. If this flag is set to true, the driver will operate in Interrupt mode. If the flag is set to false, the driver will operate in Polled mode. In Polled mode, the driver interrupt state machine gets updated in the SYS_Tasks function. If the driver is configured for Interrupt mode, the driver Interrupt state machine gets updated in the driver Interrupt Service Routine(ISR). It is always recommended for the driver to operate in Interrupt mode. Remarks This constant should always be defined. Building the Library This section lists the files that are available in the PIC32MZ USB Driver Library. Description This section list the files that are available in the \src folder of the PIC32MZ USB 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. 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 /framework/driver/usb/usbhs. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1246 Source File Name Description /drv_usbhs.h This file should be included by any .c file which accesses the PIC32MZ USB Driver API. This one file contains the prototypes for all driver API. 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 /src/dynamic/drv_usbhs.c This file should always be included in the project when using the PIC3MZ USB Driver. 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 /src/dynamic/drv_usbhs_device.c This file should be included in the project if Device mode operation is required. /src/dynamic/drv_usbhs_host.c This file should be included in the project if Host mode operation is required. Module Dependencies The PIC32MZ USB Driver Library depends on the following modules: • Interrupt System Service Library Library Interface a) System Functions Name Description DRV_USBHS_Initialize Initializes the Hi-Speed USB Driver. DRV_USBHS_Status Provides the current status of the Hi-Speed USB Driver module. DRV_USBHS_Tasks Maintains the driver's state machine when the driver is configured for Polled mode. DRV_USBHS_Tasks_ISR Maintains the driver's Interrupt state machine and implements its ISR. DRV_USBHS_Tasks_ISR_USBDMA Maintains the driver's DMA Transfer state machine and implements its ISR. b) Client Core Functions Name Description DRV_USBHS_ClientEventCallBackSet This function sets up the event callback function that is invoked by the USB controller driver to notify the client of USB bus events. DRV_USBHS_Close Closes an opened-instance of the Hi-Speed USB Driver. DRV_USBHS_Open Opens the specified Hi-Speed USB Driver instance and returns a handle to it. c) Device Mode Operation Functions Name Description DRV_USBHS_DEVICE_AddressSet This function will set the USB module address that is obtained from the Host. DRV_USBHS_DEVICE_Attach This function will enable the attach signaling resistors on the D+ and D- lines thus letting the USB Host know that a device has been attached on the bus. DRV_USBHS_DEVICE_CurrentSpeedGet This function will return the USB speed at which the device is operating. DRV_USBHS_DEVICE_Detach This function will disable the attach signaling resistors on the D+ and D- lines thus letting the USB Host know that the device has detached from the bus. DRV_USBHS_DEVICE_EndpointDisable This function disables an endpoint. DRV_USBHS_DEVICE_EndpointDisableAll This function disables all provisioned endpoints. DRV_USBHS_DEVICE_EndpointEnable This function enables an endpoint for the specified direction and endpoint size. DRV_USBHS_DEVICE_EndpointIsEnabled This function returns the enable/disable status of the specified endpoint and direction. DRV_USBHS_DEVICE_EndpointIsStalled This function returns the stall status of the specified endpoint and direction. DRV_USBHS_DEVICE_EndpointStall This function stalls an endpoint in the specified direction. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1247 DRV_USBHS_DEVICE_EndpointStallClear This function clears the stall on an endpoint in the specified direction. DRV_USBHS_DEVICE_IRPCancel This function cancels the specific IRP that are queued and in progress at the specified endpoint. DRV_USBHS_DEVICE_IRPCancelAll This function cancels all IRPs that are queued and in progress at the specified endpoint. DRV_USBHS_DEVICE_IRPSubmit This function submits an I/O Request Packet (IRP) for processing to the Hi-Speed USB Driver. DRV_USBHS_DEVICE_RemoteWakeupStart This function causes the device to start Remote Wakeup Signalling on the bus. DRV_USBHS_DEVICE_RemoteWakeupStop This function causes the device to stop the Remote Wakeup Signalling on the bus. DRV_USBHS_DEVICE_SOFNumberGet This function will return the USB SOF packet number. DRV_USBHS_DEVICE_TestModeEnter This function enables the specified USB 2.0 Test Mode. DRV_USBHS_DEVICE_TestModeExit This function disables the specified USB 2.0 Test Mode. d) Host Mode Operation Functions Name Description DRV_USBHS_HOST_EventsDisable Disables Host mode events. DRV_USBHS_HOST_EventsEnable Restores the events to the specified the original value. DRV_USBHS_HOST_IRPCancel Cancels the specified IRP. DRV_USBHS_HOST_IRPSubmit Submits an IRP on a pipe. DRV_USBHS_HOST_PipeClose Closes an open pipe. DRV_USBHS_HOST_PipeSetup Open a pipe with the specified attributes. e) Root Hub Functions Name Description DRV_USBHS_HOST_ROOT_HUB_BusSpeedGet This function returns the operating speed of the bus to which this root hub is connected. DRV_USBHS_HOST_ROOT_HUB_Initialize This function initializes the root hub driver. DRV_USBHS_HOST_ROOT_HUB_MaximumCurrentGet Returns the maximum amount of current that this root hub can provide on the bus. DRV_USBHS_HOST_ROOT_HUB_OperationEnable This function enables or disables root hub operation. DRV_USBHS_HOST_ROOT_HUB_OperationIsEnabled Returns the operation enabled status of the root hub. DRV_USBHS_HOST_ROOT_HUB_PortNumbersGet Returns the number of ports this root hub contains. DRV_USBHS_HOST_ROOT_HUB_PortReset Resets the specified root hub port. DRV_USBHS_HOST_ROOT_HUB_PortResetIsComplete Returns true if the root hub has completed the port reset operation. DRV_USBHS_HOST_ROOT_HUB_PortResume Resumes the specified root hub port. DRV_USBHS_HOST_ROOT_HUB_PortSpeedGet Returns the speed of at which the port is operating. DRV_USBHS_HOST_ROOT_HUB_PortSuspend Suspends the specified root hub port. f) Data Types and Constants Name Description DRV_USBHS_EVENT Identifies the different events that the Hi-Speed USB Driver provides. DRV_USBHS_EVENT_CALLBACK Type of the Hi-Speed USB Driver event callback function. DRV_USBHS_HOST_PIPE_HANDLE Defines the Hi-Speed USB Driver Host Pipe Handle type. DRV_USBHS_INIT This type definition defines the Driver Initialization Data Structure. DRV_USBHS_OPMODES Identifies the operating modes supported by the Hi-Speed USB Driver. DRV_USBHS_ROOT_HUB_PORT_INDICATION USB Root hub Application Hooks (Port Indication). DRV_USBHS_ROOT_HUB_PORT_OVER_CURRENT_DETECT USB Root hub Application Hooks (Port Overcurrent detection). DRV_USBHS_ROOT_HUB_PORT_POWER_ENABLE USB Root hub Application Hooks (Port Power Enable/ Disable). DRV_USBHS_DEVICE_INTERFACE Hi-Speed USB Driver Device Mode Interface Functions. DRV_USBHS_HOST_INTERFACE Hi-Speed USB Driver Host Mode Interface Functions. DRV_USBHS_HOST_PIPE_HANDLE_INVALID Value of an Invalid Host Pipe Handle. DRV_USBHS_INDEX_0 Hi-Speed USB Driver Module Index 0 Definition. Description This section describes the functions of the PIC32MZ USB Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1248 Refer to each section for a detailed description. a) System Functions DRV_USBHS_Initialize Function Initializes the Hi-Speed USB Driver. File drv_usbhs.h C SYS_MODULE_OBJ DRV_USBHS_Initialize(const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init); Returns • SYS_MODULE_OBJ_INVALID - The driver initialization failed. • A valid System Module Object - The driver initialization was able to start. It may have not completed and requires the DRV_USBHS_Tasks function to be called periodically. This value will never be the same as SYS_MODULE_OBJ_INVALID. Description This function initializes the Hi-Speed USB Driver, making it ready for clients to open. The driver initialization does not complete when this function returns. The DRV_USBHS_Tasks function must called periodically to complete the driver initialization. The DRV_USBHS_Open function will fail if the driver was not initialized or if initialization has not completed. Remarks This function must be called before any other Hi-Speed USB Driver function is called. This function should only be called once during system initialization unless DRV_USBHS_Deinitialize is called to deinitialize the driver instance. Preconditions None. Example // The following code shows an example initialization of the // driver. The USB module to be used is USB1. The module should not // automatically suspend when the microcontroller enters Sleep mode. The // module should continue operation when the module enters Idle mode. The // power state is set to run at full clock speeds. Device Mode operation // should be at FULL speed. The size of the endpoint table is set for two // endpoints. DRV_USBHS_INIT moduleInit; usbInitData.usbID = USBHS_ID_0; usbInitData.opMode = DRV_USBHS_OPMODE_DEVICE; usbInitData.stopInIdle = false; usbInitData.suspendInSleep = false; usbInitData.operationSpeed = USB_SPEED_FULL; usbInitData.interruptSource = INT_SOURCE_USB; usbInitData.sysModuleInit.powerState = SYS_MODULE_POWER_RUN_FULL ; // This is how this data structure is passed to the initialize // function. DRV_USBHS_Initialize(DRV_USBHS_INDEX_0, (SYS_MODULE_INIT *) &usbInitData); Parameters Parameters Description drvIndex Ordinal number of driver instance to be initialized. This should be set to DRV_USBHS_INDEX_0 if driver instance 0 needs to be initialized. init Pointer to a data structure containing data necessary to initialize the driver. This should be a DRV_USBHS_INIT structure reference typecast to SYS_MODULE_INIT reference. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1249 Function SYS_MODULE_OBJ DRV_USBHS_Initialize ( const SYS_MODULE_INDEX drvIndex, const SYS_MODULE_INIT * const init ) DRV_USBHS_Status Function Provides the current status of the Hi-Speed USB Driver module. File drv_usbhs.h C SYS_STATUS DRV_USBHS_Status(SYS_MODULE_OBJ object); Returns • SYS_STATUS_READY - Indicates that the driver is ready. • SYS_STATUS_UNINITIALIZED - Indicates that the driver has never been initialized. Description This function provides the current status of the Hi-Speed USB Driver module. Remarks None. Preconditions The DRV_USBHS_Initialize function must have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_USBHS_Initialize SYS_STATUS status; DRV_USBHS_INIT moduleInit; usbInitData.usbID = USBHS_ID_0; usbInitData.opMode = DRV_USBHS_OPMODE_DEVICE; usbInitData.stopInIdle = false; usbInitData.suspendInSleep = false; usbInitData.operationSpeed = USB_SPEED_FULL; usbInitData.interruptSource = INT_SOURCE_USB; usbInitData.sysModuleInit.powerState = SYS_MODULE_POWER_RUN_FULL ; // This is how this data structure is passed to the initialize // function. DRV_USBHS_Initialize(DRV_USBHS_INDEX_0, (SYS_MODULE_INIT *) &usbInitData); // The status of the driver can be checked. status = DRV_USBHS_Status(object); if(SYS_STATUS_READY == status) { // Driver is ready to be opened. } Parameters Parameters Description object Driver object handle, returned from the DRV_USBHS_Initialize function. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1250 Function SYS_STATUS DRV_USBHS_Status ( SYS_MODULE_OBJ object ) DRV_USBHS_Tasks Function Maintains the driver's state machine when the driver is configured for Polled mode. File drv_usbhs.h C void DRV_USBHS_Tasks(SYS_MODULE_OBJ object); Returns None. Description Maintains the driver's Polled state machine. This function should be called from the SYS_Tasks function. Remarks This function is normally not called directly by an application. It is called by the system's Tasks function (SYS_Tasks). This function will never block. Preconditions The DRV_USBHS_Initialize function must have been called for the specified Hi-Speed USB Driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_USBHS_Initialize while (true) { DRV_USBHS_Tasks(object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_USBHS_Initialize function). Function void DRV_USBHS_Tasks( SYS_MODULE_OBJ object ) DRV_USBHS_Tasks_ISR Function Maintains the driver's Interrupt state machine and implements its ISR. File drv_usbhs.h C void DRV_USBHS_Tasks_ISR(SYS_MODULE_OBJ object); Returns None. Description This function is used to maintain the driver's internal Interrupt state machine and implement its ISR for interrupt-driven implementations. Remarks This function should be called from the USB ISR. For multiple USB modules, it should be ensured that the correct Hi-Speed USB Driver system module object is passed to this function. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1251 Preconditions The DRV_USBHS_Initialize function must have been called for the specified Hi-Speed USB Driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_USBHS_Initialize while (true) { DRV_USBHS_Tasks_ISR (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_USBHS_Initialize). Function void DRV_USBHS_Tasks_ISR( SYS_MODULE_OBJ object ) DRV_USBHS_Tasks_ISR_USBDMA Function Maintains the driver's DMA Transfer state machine and implements its ISR. File drv_usbhs.h C void DRV_USBHS_Tasks_ISR_USBDMA(SYS_MODULE_OBJ object); Returns None. Description This function is used to maintain the driver's internal DMA Transfer state machine and implement its ISR for interrupt-driven implementations. Remarks This function should be called from the USB DMA ISR. For multiple USB modules, it should be ensured that the correct Hi-Speed USB Driver system module object is passed to this function. Preconditions The DRV_USBHS_Initialize function must have been called for the specified Hi-Speed USB Driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_USBHS_Initialize while (true) { DRV_USBHS_Tasks_ISR_USBDMA (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_USBHS_Initialize). Function void DRV_USBHS_Tasks_ISR_USBDMA( SYS_MODULE_OBJ object ) b) Client Core Functions Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1252 DRV_USBHS_ClientEventCallBackSet Function This function sets up the event callback function that is invoked by the USB controller driver to notify the client of USB bus events. File drv_usbhs.h C void DRV_USBHS_ClientEventCallBackSet(DRV_HANDLE handle, uintptr_t hReferenceData, DRV_USB_EVENT_CALLBACK myEventCallBack); Returns None. Description This function sets up the event callback function that is invoked by the USB controller driver to notify the client of USB bus events. The callback is disabled by either not calling this function after the DRV_USBHS_Open function has been called or by setting the myEventCallBack argument as NULL. When the callback function is called, the hReferenceData argument is returned. Remarks Typical usage of the Hi-Speed USB Driver requires a client to register a callback. Preconditions None. Example // Set the client event callback for the Device Layer. The // USBDeviceLayerEventHandler function is the event handler. When this // event handler is invoked by the driver, the driver returns back the // second argument specified in the following function (which in this case // is the Device Layer data structure). This allows the application // firmware to identify, as an example, the Device Layer object associated // with this callback. DRV_USBHS_ClientEventCallBackSet(myUSBDevice.usbDriverHandle, (uintptr_t)&myUSBDevice, USBDeviceLayerEventHandler); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). hReferenceData Object (could be a pointer) that is returned with the callback. myEventCallBack Callback function for all USB events. Function void DRV_USBHS_ClientEventCallBackSet ( DRV_HANDLE handle, uintptr_t hReferenceData, DRV_USBHS_EVENT_CALLBACK myEventCallBack ); DRV_USBHS_Close Function Closes an opened-instance of the Hi-Speed USB Driver. File drv_usbhs.h C void DRV_USBHS_Close(DRV_HANDLE handle); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1253 Returns None. Description This function closes an opened-instance of the Hi-Speed USB Driver, invalidating the handle. Remarks After calling this function, the handle passed in handle parameter must not be used with any of the other driver functions. A new handle must be obtained by calling DRV_USBHS_Open function before the caller may use the driver again. Preconditions The DRV_USBHS_Initialize function must have been called for the specified Hi-Speed USB Driver instance. DRV_USBHS_Open function must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_USBHS_Open DRV_USBHS_Close(handle); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). Function void DRV_USBHS_Close( DRV_HANDLE handle ) DRV_USBHS_Open Function Opens the specified Hi-Speed USB Driver instance and returns a handle to it. File drv_usbhs.h C DRV_HANDLE DRV_USBHS_Open(const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent); Returns • DRV_HANDLE_INVALID - The driver could not be opened successfully.This can happen if the driver initialization was not complete or if an internal error has occurred. • A Valid Driver Handle - This is an arbitrary value and is returned if the function was successful. This value will never be the same as DRV_HANDLE_INVALID. Description This function opens the specified Hi-Speed USB Driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The intent flag should always be DRV_IO_INTENT_EXCLUSIVE|DRV_IO_INTENT_READWRITE|DRV_IO_INTENT_NON_BLOCKING. Any other setting of the intent flag will return a invalid driver handle. A driver instance can only support one client. Trying to open a driver that has an existing client will result in an unsuccessful function call. Remarks The handle returned is valid until the DRV_USBHS_Close function is called. The function will typically return DRV_HANDLE_INVALID if the driver was not initialized. In such a case the client should try to open the driver again. Preconditions Function DRV_USBHS_Initialize must have been called before calling this function. Example DRV_HANDLE handle; // This code assumes that the driver has been initialized. handle = DRV_USBHS_Open(DRV_USBHS_INDEX_0, DRV_IO_INTENT_EXCLUSIVE| DRV_IO_INTENT_READWRITE| DRV_IO_INTENT_NON_BLOCKING); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1254 if(DRV_HANDLE_INVALID == handle) { // The application should try opening the driver again. } Parameters Parameters Description drvIndex Identifies the driver instance to be opened. As an example, this value can be set to DRV_USBHS_INDEX_0 if instance 0 of the driver has to be opened. intent Should always be (DRV_IO_INTENT_EXCLUSIVE|DRV_IO_INTENT_READWRITE| DRV_IO_INTENT_NON_BLOCKING). Function DRV_HANDLE DRV_USBHS_Open ( const SYS_MODULE_INDEX drvIndex, const DRV_IO_INTENT intent ) c) Device Mode Operation Functions DRV_USBHS_DEVICE_AddressSet Function This function will set the USB module address that is obtained from the Host. File drv_usbhs.h C void DRV_USBHS_DEVICE_AddressSet(DRV_HANDLE handle, uint8_t address); Returns None. Description This function will set the USB module address that is obtained from the Host in a setup transaction. The address is obtained from the SET_ADDRESS command issued by the Host. The primary (first) client of the driver uses this function to set the module's USB address after decoding the setup transaction from the Host. Remarks None. Preconditions None. Example // This function should be called by the first client of the driver, // which is typically the Device Layer. The address to set is obtained // from the Host during enumeration. DRV_USBHS_DEVICE_AddressSet(deviceLayer, 4); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). address The address of this module on the USB bus. Function void DRV_USBHS_DEVICE_AddressSet( DRV_HANDLE handle, uint8_t address); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1255 DRV_USBHS_DEVICE_Attach Function This function will enable the attach signaling resistors on the D+ and D- lines thus letting the USB Host know that a device has been attached on the bus. File drv_usbhs.h C void DRV_USBHS_DEVICE_Attach(DRV_HANDLE handle); Returns None. Description This function enables the pull-up resistors on the D+ or D- lines thus letting the USB Host know that a device has been attached on the bus . This function should be called when the driver client is ready to receive communication from the Host (typically after all initialization is complete). The USB 2.0 specification requires VBUS to be detected before the data line pull-ups are enabled. The application must ensure the same. Remarks None. Preconditions The Client handle should be valid. Example // Open the device driver and attach the device to the USB. handle = DRV_USBHS_Open(DRV_USBHS_INDEX_0, DRV_IO_INTENT_EXCLUSIVE| DRV_IO_INTENT_READWRITE| DRV_IO_INTENT_NON_BLOCKING); // Register a callback DRV_USBHS_ClientEventCallBackSet(handle, (uintptr_t)&myDeviceLayer, MyDeviceLayerEventCallback); // The device can be attached when VBUS Session Valid event occurs void MyDeviceLayerEventCallback(uintptr_t handle, DRV_USBHS_EVENT event, void * hReferenceData) { switch(event) { case DRV_USBHS_EVENT_DEVICE_SESSION_VALID: // A valid VBUS was detected. DRV_USBHS_DEVICE_Attach(handle); break; case DRV_USBHS_EVENT_DEVICE_SESSION_INVALID: // VBUS is not valid anymore. The device can be disconnected. DRV_USBHS_DEVICE_Detach(handle); break; default: break; } } } Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). Function void DRV_USBHS_DEVICE_Attach( DRV_HANDLE handle); DRV_USBHS_DEVICE_CurrentSpeedGet Function This function will return the USB speed at which the device is operating. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1256 File drv_usbhs.h C USB_SPEED DRV_USBHS_DEVICE_CurrentSpeedGet(DRV_HANDLE handle); Returns Returns a member of the USB_SPEED type. Description This function will return the USB speed at which the device is operating. Remarks None. Preconditions Only valid after the device is attached to the Host and Host has completed reset signaling. Example // Get the current speed. USB_SPEED deviceSpeed; deviceSpeed = DRV_USBHS_DEVICE_CurrentSpeedGet(deviceLayer); if(deviceLayer == USB_SPEED_HIGH) { // Possibly adjust buffers for higher throughput. } Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). Function USB_SPEED DRV_USBHS_DEVICE_CurrentSpeedGet( DRV_HANDLE handle); DRV_USBHS_DEVICE_Detach Function This function will disable the attach signaling resistors on the D+ and D- lines thus letting the USB Host know that the device has detached from the bus. File drv_usbhs.h C void DRV_USBHS_DEVICE_Detach(DRV_HANDLE handle); Returns None. Description This function disables the pull-up resistors on the D+ or D- lines. This function should be called when the application wants to disconnect the device from the bus (typically to implement a soft detach or switch to Host mode operation). A self-powered device should be detached from the bus when the VBUS is not valid. Remarks None. Preconditions The Client handle should be valid. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1257 Example // Open the device driver and attach the device to the USB. handle = DRV_USBHS_Open(DRV_USBHS_INDEX_0, DRV_IO_INTENT_EXCLUSIVE| DRV_IO_INTENT_READWRITE| DRV_IO_INTENT_NON_BLOCKING); // Register a callback DRV_USBHS_ClientEventCallBackSet(handle, (uintptr_t)&myDeviceLayer, MyDeviceLayerEventCallback); // The device can be detached when VBUS Session Invalid event occurs void MyDeviceLayerEventCallback(uintptr_t handle, DRV_USBHS_EVENT event, void * hReferenceData) { switch(event) { case DRV_USBHS_EVENT_DEVICE_SESSION_VALID: // A valid VBUS was detected. DRV_USBHS_DEVICE_Attach(handle); break; case DRV_USBHS_EVENT_DEVICE_SESSION_INVALID: // VBUS is not valid anymore. The device can be disconnected. DRV_USBHS_DEVICE_Detach(handle); break; default: break; } } } Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). Function void DRV_USBHS_DEVICE_Detach( DRV_HANDLE handle); DRV_USBHS_DEVICE_EndpointDisable Function This function disables an endpoint. File drv_usbhs.h C USB_ERROR DRV_USBHS_DEVICE_EndpointDisable(DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection); Returns • USB_ERROR_NONE - The endpoint was successfully enabled. • USB_ERROR_DEVICE_ENDPOINT_INVALID - The endpoint that is being accessed is not a valid endpoint (endpoint was not provisioned through the DRV_USBHS_ENDPOINTS_NUMBER configuration constant) defined for this driver instance. Description This function disables an endpoint. If the endpoint type is a control endpoint type, both directions are disabled. For non-control endpoints, the function disables the specified direction only. The direction to be disabled is specified by the Most Significant Bit (MSB) of the endpointAndDirection parameter. Remarks None. Preconditions The Client handle should be valid. Example // This code shows an example of how to disable Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1258 // a control endpoint. Note that the direction parameter is ignored. // For a control endpoint, both the directions are disabled. USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 0); DRV_USBHS_DEVICE_EndpointDisable(handle, ep ); // This code shows an example of how to disable a BULK IN // endpoint USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); DRV_USBHS_DEVICE_EndpointDisable(handle, ep ); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). endpointAndDirection Specifies the endpoint and direction. Function USB_ERROR DRV_USBHS_DEVICE_EndpointDisable ( DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection ) DRV_USBHS_DEVICE_EndpointDisableAll Function This function disables all provisioned endpoints. File drv_usbhs.h C USB_ERROR DRV_USBHS_DEVICE_EndpointDisableAll(DRV_HANDLE handle); Returns • USB_ERROR_NONE - The function exited successfully. • USB_ERROR_PARAMETER_INVALID - The driver handle is invalid. Description This function disables all provisioned endpoints in both directions. Remarks This function is typically called by the USB Device Layer to disable all endpoints upon detecting a bus reset. Preconditions The Client handle should be valid. Example // This code shows an example of how to disable all endpoints. DRV_USBHS_DEVICE_EndpointDisableAll(handle); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1259 Function USB_ERROR DRV_USBHS_DEVICE_EndpointDisableAll( DRV_HANDLE handle) DRV_USBHS_DEVICE_EndpointEnable Function This function enables an endpoint for the specified direction and endpoint size. File drv_usbhs.h C USB_ERROR DRV_USBHS_DEVICE_EndpointEnable(DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection, USB_TRANSFER_TYPE transferType, uint16_t endpointSize); Returns • USB_ERROR_NONE - The endpoint was successfully enabled. • USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is not a valid endpoint defined for this driver instance. The value of DRV_USBHS_ENDPOINTS_NUMBER configuration constant should be adjusted. • USB_ERROR_PARAMETER_INVALID - The driver handle is invalid. Description This function enables an endpoint for the specified direction and endpoint size. The function will enable the endpoint for communication in one direction at a time. It must be called twice if the endpoint is required to communicate in both the directions, with the exception of control endpoints. If the endpoint type is a control endpoint, the endpoint is always bidirectional and the function needs to be called only once. The size of the endpoint must match the wMaxPacketSize reported in the endpoint descriptor for this endpoint. A transfer that is scheduled over this endpoint will be scheduled in wMaxPacketSize transactions. The function does not check if the endpoint is already in use. It is the client's responsibility to make sure that a endpoint is not accidentally reused. Remarks None. Preconditions The Client handle should be valid. Example // This code shows an example of how to enable Endpoint // 0 for control transfers. Note that for a control endpoint, the // direction parameter is ignored. A control endpoint is always // bidirectional. Endpoint size is 64 bytes. uint8_t ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 0); DRV_USBHS_DEVICE_EndpointEnable(handle, ep, USB_TRANSFER_TYPE_CONTROL, 64); // This code shows an example of how to set up a endpoint // for BULK IN transfer. For an IN transfer, data moves from device // to Host. In this example, Endpoint 1 is enabled. The maximum // packet size is 64. uint8_t ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); DRV_USBHS_DEVICE_EndpointEnable(handle, ep, USB_TRANSFER_TYPE_BULK, 64); // If Endpoint 1 must also be set up for BULK OUT, the // DRV_USBHS_DEVICE_EndpointEnable function must be called again, as shown // here. ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_HOST_TO_DEVICE, 1); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1260 DRV_USBHS_DEVICE_EndpointEnable(handle, ep, USB_TRANSFER_TYPE_BULK, 64); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). endpointAndDirection Specifies the endpoint and direction. transferType Should be USB_TRANSFER_TYPE_CONTROL for control endpoint, USB_TRANSFER_TYPE_BULK for bulk endpoint, USB_TRANSFER_TYPE_INTERRUPT for interrupt endpoint and USB_TRANSFER_TYPE_ISOCHRONOUS for isochronous endpoint. endpointSize Maximum size (in bytes) of the endpoint as reported in the endpoint descriptor. Function USB_ERROR DRV_USBHS_DEVICE_EndpointEnable ( DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection, USB_TRANSFER_TYPE transferType, uint16_t endpointSize ); DRV_USBHS_DEVICE_EndpointIsEnabled Function This function returns the enable/disable status of the specified endpoint and direction. File drv_usbhs.h C bool DRV_USBHS_DEVICE_EndpointIsEnabled(DRV_HANDLE client, USB_ENDPOINT endpointAndDirection); Returns • true - The endpoint is enabled. • false - The endpoint is disabled. Description This function returns the enable/disable status of the specified endpoint and direction. Remarks None. Preconditions The Client handle should be valid. Example // This code shows an example of how the // DRV_USBHS_DEVICE_EndpointIsEnabled function can be used to obtain the // status of Endpoint 1 and IN direction. USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); if(DRV_USBHS_ENDPOINT_STATE_DISABLED == DRV_USBHS_DEVICE_EndpointIsEnabled(handle, ep)) { // Endpoint is disabled. Enable endpoint. DRV_USBHS_DEVICE_EndpointEnable(handle, ep, USB_ENDPOINT_TYPE_BULK, 64); } Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1261 Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). endpointAndDirection Specifies the endpoint and direction. Function bool DRV_USBHS_DEVICE_EndpointIsEnabled ( DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection ) DRV_USBHS_DEVICE_EndpointIsStalled Function This function returns the stall status of the specified endpoint and direction. File drv_usbhs.h C bool DRV_USBHS_DEVICE_EndpointIsStalled(DRV_HANDLE client, USB_ENDPOINT endpoint); Returns • true - The endpoint is stalled. • false - The endpoint is not stalled. Description This function returns the stall status of the specified endpoint and direction. Remarks None. Preconditions The Client handle should be valid. Example // This code shows an example of how the // DRV_USBHS_DEVICE_EndpointIsStalled function can be used to obtain the // stall status of Endpoint 1 and IN direction. USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); if(true == DRV_USBHS_DEVICE_EndpointIsStalled (handle, ep)) { // Endpoint stall is enabled. Clear the stall. DRV_USBHS_DEVICE_EndpointStallClear(handle, ep); } Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). endpointAndDirection Specifies the endpoint and direction. Function bool DRV_USBHS_DEVICE_EndpointIsStalled ( Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1262 DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection ) DRV_USBHS_DEVICE_EndpointStall Function This function stalls an endpoint in the specified direction. File drv_usbhs.h C USB_ERROR DRV_USBHS_DEVICE_EndpointStall(DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection); Returns • USB_ERROR_NONE - The endpoint was successfully enabled. • USB_ERROR_PARAMETER_INVALID - The driver handle is not valid. • USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is out of the valid endpoint defined for this driver instance. • USB_ERROR_OSAL_FUNCTION - An error with an OSAL function called in this function. Description This function stalls an endpoint in the specified direction. Remarks None. Preconditions The Client handle should be valid. Example // This code shows an example of how to stall an endpoint. In // this example, Endpoint 1 IN direction is stalled. USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); DRV_USBHS_DEVICE_EndpointStall(handle, ep); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). endpointAndDirection Specifies the endpoint and direction. Function USB_ERROR DRV_USBHS_DEVICE_EndpointStall ( DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection ) DRV_USBHS_DEVICE_EndpointStallClear Function This function clears the stall on an endpoint in the specified direction. File drv_usbhs.h Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1263 C USB_ERROR DRV_USBHS_DEVICE_EndpointStallClear(DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection); Returns • USB_ERROR_NONE - The endpoint was successfully enabled. • USB_ERROR_PARAMETER_INVALID - The driver handle is not valid. • USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is out of the valid endpoint defined for this driver instance. Description This function clears the stall on an endpoint in the specified direction. Remarks None. Preconditions The Client handle should be valid. Example // This code shows an example of how to clear a stall. In this // example, the stall condition on Endpoint 1 IN direction is cleared. USB_ENDPOINT ep; ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); DRV_USBHS_DEVICE_EndpointStallClear(handle, ep); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). endpointAndDirection Specifies the endpoint and direction. Function USB_ERROR DRV_USBHS_DEVICE_EndpointStallClear ( DRV_HANDLE handle, USB_ENDPOINT endpointAndDirection ) DRV_USBHS_DEVICE_IRPCancel Function This function cancels the specific IRP that are queued and in progress at the specified endpoint. File drv_usbhs.h C USB_ERROR DRV_USBHS_DEVICE_IRPCancel(DRV_HANDLE client, USB_DEVICE_IRP * irp); Returns • USB_ERROR_NONE - The IRP have been canceled successfully. • USB_ERROR_PARAMETER_INVALID - Invalid parameter or the IRP already has been aborted or completed • USB_ERROR_OSAL_FUNCTION - An OSAL function called in this function did not execute successfully. Description This function attempts to cancel the processing of a queued IRP. An IRP that was in the queue but yet to be processed will be cancelled successfully and the IRP callback function will be called from this function with the USB_DEVICE_IRP_STATUS_ABORTED status. The application can release the data buffer memory used by the IRP when this callback occurs. If the IRP was in progress (a transaction in on the bus) when the cancel function was called, the IRP will be canceled only when an ongoing or the next transaction has completed. The IRP callback Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1264 function will then be called in an interrupt context. The application should not release the related data buffer unless the IRP callback has occurred. Remarks The size returned after the ABORT callback will be always 0 regardless of the amount of data that has been sent or received. The client should not assume any data transaction has happened for an canceled IRP. If the last transaction of the IRP was in progress, the IRP cancel does not have any effect. The first transaction of any ongoing IRP cannot be canceled. Preconditions The Client handle should be valid. Example // This code shows an example of how to cancel IRP. In this example the IRP // has been scheduled from a device to the Host. USB_ENDPOINT ep; USB_DEVICE_IRP irp; ep.direction = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); irp.data = myDataBufferToSend; irp.size = 130; irp.flags = USB_DEVICE_IRP_FLAG_DATA_COMPLETE; irp.callback = MyIRPCompletionCallback; irp.referenceData = (uintptr_t)&myDeviceLayerObj; if (DRV_USBHS_DEVICE_IRPSubmit(handle, ep, &irp) != USB_ERROR_NONE) { // This means there was an error. } else { // Check the status of the IRP. if(irp.status != USB_DEVICE_IRP_STATUS_COMPLETED) { // Cancel the submitted IRP. if (DRV_USBHS_DEVICE_IRPCancel(handle, &irp) != USB_ERROR_NONE) { // The IRP Cancel request submission was successful. // IRP cancel status will be notified through the callback // function. } else { // The IRP may have been completed before IRP cancel operation. // could start. No callback notification will be generated. } } else { // The IRP processing must have been completed before IRP cancel was // submitted. } } void MyIRPCallback(USB_DEVICE_IRP * irp) { // Check if the IRP callback is for a Cancel request if(irp->status == USB_DEVICE_IRP_STATUS_ABORTED) { // IRP cancel completed } } Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). irp Pointer to the IRP to cancel. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1265 Function USB_ERROR DRV_USBHS_DEVICE_IRPCancel ( DRV_HANDLE client, USB_DEVICE_IRP * irp ) DRV_USBHS_DEVICE_IRPCancelAll Function This function cancels all IRPs that are queued and in progress at the specified endpoint. File drv_usbhs.h C USB_ERROR DRV_USBHS_DEVICE_IRPCancelAll(DRV_HANDLE client, USB_ENDPOINT endpointAndDirection); Returns • USB_ERROR_NONE - The endpoint was successfully enabled. • USB_ERROR_DEVICE_ENDPOINT_INVALID - If the endpoint that is being accessed is out of the valid endpoint defined for this driver instance. • USB_ERROR_PARAMETER_INVALID - The driver handle is not valid. • USB_ERROR_OSAL_FUNCTION - An OSAL function called in this function did not execute successfully. Description This function cancels all IRPs that are queued and in progress at the specified endpoint. Remarks None. Preconditions The Client handle should be valid. Example // This code shows an example of how to cancel all IRPs. void MyIRPCallback(USB_DEVICE_IRP * irp) { // Check if this is setup command if(irp->status == USB_DEVICE_IRP_STATUS_SETUP) { if(IsSetupCommandSupported(irp->data) == false) { // This means that this setup command is not // supported. Stall the some related endpoint and cancel all // queue IRPs. DRV_USBHS_DEVICE_EndpointStall(handle, ep); DRV_USBHS_DEVICE_IRPCancelAll(handle, ep); } } } Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). endpointAndDirection Specifies the endpoint and direction. Function USB_ERROR DRV_USBHS_DEVICE_IRPCancelAll Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1266 ( DRV_HANDLE client, USB_ENDPOINT endpointAndDirection ); DRV_USBHS_DEVICE_IRPSubmit Function This function submits an I/O Request Packet (IRP) for processing to the Hi-Speed USB Driver. File drv_usbhs.h C USB_ERROR DRV_USBHS_DEVICE_IRPSubmit(DRV_HANDLE client, USB_ENDPOINT endpointAndDirection, USB_DEVICE_IRP * irp); Returns • USB_ERROR_NONE - if the IRP was submitted successful. • USB_ERROR_IRP_SIZE_INVALID - if the size parameter of the IRP is not correct. • USB_ERROR_PARAMETER_INVALID - If the client handle is not valid. • USB_ERROR_ENDPOINT_NOT_CONFIGURED - If the endpoint is not enabled. • USB_ERROR_DEVICE_ENDPOINT_INVALID - The specified endpoint is not valid. • USB_ERROR_OSAL_FUNCTION - An OSAL call in the function did not complete successfully. Description This function submits an I/O Request Packet (IRP) for processing to the USB Driver. The IRP allows a client to send and receive data from the USB Host. The data will be sent or received through the specified endpoint. The direction of the data transfer is indicated by the direction flag in the endpointAndDirection parameter. Submitting an IRP arms the endpoint to either send data to or receive data from the Host. If an IRP is already being processed on the endpoint, the subsequent IRP submit operation will be queued. The contents of the IRP (including the application buffers) should not be changed until the IRP has been processed. Particular attention should be paid to the size parameter of IRP. The following should be noted: • The size parameter while sending data to the Host can be less than, greater than, equal to, or be an exact multiple of the maximum packet size for the endpoint. The maximum packet size for the endpoint determines the number of transactions required to process the IRP. • If the size parameter, while sending data to the Host is less than the maximum packet size, the transfer will complete in one transaction. • If the size parameter, while sending data to the Host is greater than the maximum packet size, the IRP will be processed in multiple transactions. • If the size parameter, while sending data to the Host is equal to or an exact multiple of the maximum packet size, the client can optionally ask the driver to send a Zero Length Packet(ZLP) by specifying the USB_DEVICE_IRP_FLAG_DATA_COMPLETE flag as the flag parameter. • The size parameter, while receiving data from the Host must be an exact multiple of the maximum packet size of the endpoint. If this is not the case, the driver will return a USB_ERROR_IRP_SIZE_INVALID result. If while processing the IRP, the driver receives less than maximum packet size or a ZLP from the Host, the driver considers the IRP as processed. The size parameter at this point contains the actual amount of data received from the Host. The IRP status is returned as USB_DEVICE_IRP_STATUS_COMPLETED_SHORT. • If a ZLP needs to be sent to Host, the IRP size should be specified as 0 and the flag parameter should be set as USB_DEVICE_IRP_FLAG_DATA_COMPLETE. • If the IRP size is an exact multiple of the endpoint size, the client can request the driver to not send a ZLP by setting the flag parameter to USB_DEVICE_IRP_FLAG_DATA_PENDING. This flag indicates that there is more data pending in this transfer. • Specifying a size less than the endpoint size along with the USB_DEVICE_IRP_FLAG_DATA_PENDING flag will cause the driver to return a USB_ERROR_IRP_SIZE_INVALID. • If the size is greater than but not a multiple of the endpoint size, and the flag is specified as USB_DEVICE_IRP_FLAG_DATA_PENDING, the driver will send multiple of endpoint size number of bytes. For example, if the IRP size is 130 and the endpoint size if 64, the number of bytes sent will 128. Remarks This function can be called from the ISR of the USB module to associated with the client. Preconditions The Client handle should be valid. Example // The following code shows an example of how to schedule a IRP to send data // from a device to the Host. Assume that the max packet size is 64 and Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1267 // and this data needs to sent over Endpoint 1. In this example, the // transfer is processed as three transactions of 64, 64 and 2 bytes. USB_ENDPOINT ep; USB_DEVICE_IRP irp; ep.direction = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_DEVICE_TO_HOST, 1); irp.data = myDataBufferToSend; irp.size = 130; irp.flags = USB_DEVICE_IRP_FLAG_DATA_COMPLETE; irp.callback = MyIRPCompletionCallback; irp.referenceData = (uintptr_t)&myDeviceLayerObj; if (DRV_USBHS_DEVICE_IRPSubmit(handle, ep, &irp) != USB_ERROR_NONE) { // This means there was an error. } else { // The status of the IRP can be checked. while(irp.status != USB_DEVICE_IRP_STATUS_COMPLETED) { // Wait or run a task function. } } // The following code shows how the client can request // the driver to send a ZLP when the size is an exact multiple of // endpoint size. irp.data = myDataBufferToSend; irp.size = 128; irp.flags = USB_DEVICE_IRP_FLAG_DATA_COMPLETE; irp.callback = MyIRPCompletionCallback; irp.referenceData = (uintptr_t)&myDeviceLayerObj; // Note that while receiving data from the Host, the size should be an // exact multiple of the maximum packet size of the endpoint. In the // following example, the DRV_USBHS_DEVICE_IRPSubmit function will return a // USB_DEVICE_IRP_SIZE_INVALID value. ep = USB_ENDPOINT_AND_DIRECTION(USB_DATA_DIRECTION_HOST_TO_DEVICE, 1); irp.data = myDataBufferToSend; irp.size = 60; // THIS SIZE IS NOT CORRECT irp.flags = USB_DEVICE_IRP_FLAG_DATA_COMPLETE; irp.callback = MyIRPCompletionCallback; irp.referenceData = (uintptr_t)&myDeviceLayerObj; Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). endpointAndDirection Specifies the endpoint and direction. irp Pointer to the IRP to be added to the queue for processing. Function USB_ERROR DRV_USBHS_DEVICE_IRPSubmit ( DRV_HANDLE client, USB_ENDPOINT endpointAndDirection, USB_DEVICE_IRP * irp ); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1268 DRV_USBHS_DEVICE_RemoteWakeupStart Function This function causes the device to start Remote Wakeup Signalling on the bus. File drv_usbhs.h C void DRV_USBHS_DEVICE_RemoteWakeupStart(DRV_HANDLE handle); Returns None. Description This function causes the device to start Remote Wakeup Signalling on the bus. This function should be called when the device, presently placed in suspend mode by the Host, wants to be wakeup. Note that the device can do this only when the Host has enabled the device's Remote Wakeup capability. Remarks None. Preconditions The handle should be valid. Example DRV_HANDLE handle; // If the Host has enabled the Remote Wakeup capability, and if the device // is in suspend mode, then start Remote Wakeup signaling. if(deviceIsSuspended && deviceRemoteWakeupEnabled) { DRV_USBHS_DEVICE_RemoteWakeupStart(handle); } Parameters Parameters Description handle Handle to the driver (returned from DRV_USBHS_Open function). Function void DRV_USBHS_DEVICE_RemoteWakeupStart( DRV_HANDLE handle); DRV_USBHS_DEVICE_RemoteWakeupStop Function This function causes the device to stop the Remote Wakeup Signalling on the bus. File drv_usbhs.h C void DRV_USBHS_DEVICE_RemoteWakeupStop(DRV_HANDLE handle); Returns None. Description This function causes the device to stop Remote Wakeup Signalling on the bus. This function should be called after the DRV_USBHS_DEVICE_RemoteWakeupStart function was called to start the Remote Wakeup signaling on the bus. Remarks This function should be 1 to 15 milliseconds after the DRV_USBHS_DEVICE_RemoteWakeupStart function was called. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1269 Preconditions The handle should be valid. The DRV_USBHS_DEVICE_RemoteWakeupStart function was called to start the Remote Wakeup signaling on the bus. Example DRV_HANDLE handle; // If the Host has enabled the Remote Wakeup capability, and if the device // is in suspend mode, then start Remote Wakeup signaling. Wait for 10 // milliseconds and then stop the Remote Wakeup signaling if(deviceIsSuspended && deviceRemoteWakeupEnabled) { DRV_USBHS_DEVICE_RemoteWakeupStart(handle); DelayMilliSeconds(10); DRV_USBHS_DEVICE_RemoteWakeupStop(handle); } Parameters Parameters Description handle Handle to the driver (returned from DRV_USBHS_Open function). Function void DRV_USBHS_DEVICE_RemoteWakeupStop( DRV_HANDLE handle); DRV_USBHS_DEVICE_SOFNumberGet Function This function will return the USB SOF packet number. File drv_usbhs.h C uint16_t DRV_USBHS_DEVICE_SOFNumberGet(DRV_HANDLE handle); Returns The SOF packet number. Description This function will return the USB SOF packet number.. Remarks None. Preconditions This function will return a valid value only when the device is attached to the bus. The SOF packet count will not increment if the bus is suspended. Example // This code shows how the DRV_USBHS_DEVICE_SOFNumberGet function is called // to read the current SOF number. DRV_HANDLE handle; uint16_t sofNumber; sofNumber = DRV_USBHS_DEVICE_SOFNumberGet(handle); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1270 Function uint16_t DRV_USBHS_DEVICE_SOFNumberGet( DRV_HANDLE handle); DRV_USBHS_DEVICE_TestModeEnter Function This function enables the specified USB 2.0 Test Mode. File drv_usbhs.h C USB_ERROR DRV_USBHS_DEVICE_TestModeEnter(DRV_HANDLE handle, USB_TEST_MODE_SELECTORS testMode); Returns • USB_ERROR_NONE - The function executed successfully. • USB_ERROR_PARAMETER_INVALID - The handle or the value of testMode parameter is not valid. Description This function causes the device to enter the specified USB 2.0 defined test mode. It is called in response to Set Feature command from the host. The wValue field of this command specifies the Test Mode to enter. The USB module will perform the action identified by the testMode parameter. Remarks This function should be called only when the USB device has attached to the Host at High speed and only in response to the Set Feature command from the Host. Preconditions The handle should be valid. Example DRV_HANDLE handle; // This code shows how the DRV_USBHS_DEVICE_TestModeEnter function is // called to make the USB device enter the Test_J test mode. DRV_USBHS_DEVICE_TestModeEnter(handle, USB_TEST_MODE_SELECTOR_TEST_J); Parameters Parameters Description handle Handle to the driver (returned from DRV_USBHS_Open function). testMode This parameter identifies the USB 2.0 specification test mode (see table 9-7 of the USB 2.0 specification). Function USB_ERROR DRV_USBHS_DEVICE_TestModeEnter ( DRV_HANDLE handle, USB_TEST_MODE_SELECTORS testMode ); DRV_USBHS_DEVICE_TestModeExit Function This function disables the specified USB 2.0 Test Mode. File drv_usbhs.h C USB_ERROR DRV_USBHS_DEVICE_TestModeExit(DRV_HANDLE handle, USB_TEST_MODE_SELECTORS testMode); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1271 Returns • USB_ERROR_NONE - The function executed successfully. • USB_ERROR_PARAMETER_INVALID - The handle or the value of testMode parameter is not valid. Description This function causes the device to stop the specified USB 2.0 defined test mode. This function can be called after calling the DRV_USBHS_DEVICE_TestModeEnter function to stop the test mode execution. Remarks None. Preconditions The handle should be valid. Example DRV_HANDLE handle; // This code shows how the DRV_USBHS_DEVICE_TestModeEnter function is // called to make the USB device enter the Test_J test mode. DRV_USBHS_DEVICE_TestModeEnter(handle, USB_TEST_MODE_SELECTOR_TEST_J); // Now the DRV_USBHS_DEVICE_TestModeExit function is called to stop the // Test_J test mode. DRV_USBHS_DEVICE_TestModeExit(handle, USB_TEST_MODE_SELECTOR_TEST_J); Parameters Parameters Description handle Handle to the driver (returned from DRV_USBHS_Open function). testMode This parameter identifies the USB 2.0 specification test mode (see table 9-7 of the USB 2.0 specification). Function USB_ERROR DRV_USBHS_DEVICE_TestModeExit ( DRV_HANDLE handle, USB_TEST_MODE_SELECTORS testMode ); d) Host Mode Operation Functions DRV_USBHS_HOST_EventsDisable Function Disables Host mode events. File drv_usbhs.h C bool DRV_USBHS_HOST_EventsDisable(DRV_HANDLE handle); Returns • true - Driver event generation was enabled when this function was called. • false - Driver event generation was not enabled when this function was called. Description This function disables the Host mode events. This function is called by the Host Layer when it wants to execute code atomically. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1272 Remarks None. Preconditions The handle should be valid. Example // This code shows how the DRV_USBHS_HOST_EventsDisable and // DRV_USBHS_HOST_EventsEnable function can be called to disable and enable // events. DRV_HANDLE driverHandle; bool eventsWereEnabled; // Disable the driver events. eventsWereEnabled = DRV_USBHS_HOST_EventsDisable(driverHandle); // Code in this region will not be interrupted by driver events. // Enable the driver events. DRV_USBHS_HOST_EventsEnable(driverHandle, eventsWereEnabled); Parameters Parameters Description handle Client's driver handle (returned from DRV_USBHS_Open function). Function bool DRV_USBHS_HOST_EventsDisable ( DRV_HANDLE handle ); DRV_USBHS_HOST_EventsEnable Function Restores the events to the specified the original value. File drv_usbhs.h C void DRV_USBHS_HOST_EventsEnable(DRV_HANDLE handle, bool eventContext); Returns None. Description This function will restore the enable disable state of the events. The eventRestoreContext parameter should be equal to the value returned by the DRV_USBHS_HOST_EventsDisable function. Remarks None. Preconditions The handle should be valid. Example // This code shows how the DRV_USBHS_HOST_EventsDisable and // DRV_USBHS_HOST_EventsEnable function can be called to disable and enable // events. DRV_HANDLE driverHandle; Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1273 bool eventsWereEnabled; // Disable the driver events. eventsWereEnabled = DRV_USBHS_HOST_EventsDisable(driverHandle); // Code in this region will not be interrupted by driver events. // Enable the driver events. DRV_USBHS_HOST_EventsEnable(driverHandle, eventsWereEnabled); Parameters Parameters Description handle Handle to the driver (returned from DRV_USBHS_Open function). eventRestoreContext Value returned by the DRV_USBHS_HOST_EventsDisable function. Function void DRV_USBHS_HOST_EventsEnable ( DRV_HANDLE handle bool eventRestoreContext ); DRV_USBHS_HOST_IRPCancel Function Cancels the specified IRP. File drv_usbhs.h C void DRV_USBHS_HOST_IRPCancel(USB_HOST_IRP * inputIRP); Returns None. Description This function attempts to cancel the specified IRP. If the IRP is queued and its processing has not started, it will be cancelled successfully. If the IRP in progress, the ongoing transaction will be allowed to complete. Remarks None. Preconditions None. Example // This code shows how a submitted IRP can be cancelled. USB_HOST_IRP irp; USB_ERROR result; USB_HOST_PIPE_HANDLE controlPipe; USB_SETUP_PACKET setup; uint8_t controlTransferData[32]; irp.setup = setup; irp.data = controlTransferData; irp.size = 32; irp.flags = USB_HOST_IRP_FLAG_NONE ; irp.userData = &someApplicationObject; irp.callback = IRP_Callback; DRV_USBHS_HOST_IRPSubmit(controlPipeHandle, &irp); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1274 // Additional application logic may come here. This logic may decide to // cancel the submitted IRP. DRV_USBHS_HOST_IRPCancel(&irp); Parameters Parameters Description inputIRP Pointer to the IRP to cancel. Function void DRV_USBHS_HOST_IRPCancel(USB_HOST_IRP * inputIRP); DRV_USBHS_HOST_IRPSubmit Function Submits an IRP on a pipe. File drv_usbhs.h C USB_ERROR DRV_USBHS_HOST_IRPSubmit(DRV_USBHS_HOST_PIPE_HANDLE hPipe, USB_HOST_IRP * pinputIRP); Returns • USB_ERROR_NONE - The IRP was submitted successfully. • USB_ERROR_PARAMETER_INVALID - The pipe handle is not valid. • USB_ERROR_OSAL_FUNCTION - An error occurred in an OSAL function called in this function. Description This function submits an IRP on the specified pipe. The IRP will be added to the queue and will be processed in turn. The data will be transferred on the bus based on the USB bus scheduling rules. When the IRP has been processed, the callback function specified in the IRP will be called. The IRP status will be updated to reflect the completion status of the IRP. Remarks An IRP can also be submitted in an IRP callback function. Preconditions The pipe handle should be valid. Example // The following code shows an example of how the host layer populates // the IRP object and then submits it. IRP_Callback function is called when an // IRP has completed processing. The status of the IRP at completion can be // checked in the status flag. The size field of the irp will contain the amount // of data transferred. void IRP_Callback(USB_HOST_IRP * irp) { // irp is pointing to the IRP for which the callback has occurred. In most // cases this function will execute in an interrupt context. The application // should not perform any hardware access or interrupt un-safe operations in // this function. switch(irp->status) { case USB_HOST_IRP_STATUS_ERROR_UNKNOWN: // IRP was terminated due to an unknown error break; case USB_HOST_IRP_STATUS_ABORTED: // IRP was terminated by the application break; case USB_HOST_IRP_STATUS_ERROR_BUS: // IRP was terminated due to a bus error Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1275 break; case USB_HOST_IRP_STATUS_ERROR_DATA: // IRP was terminated due to data error break; case USB_HOST_IRP_STATUS_ERROR_NAK_TIMEOUT: // IRP was terminated because of a NAK timeout break; case USB_HOST_IRP_STATUS_ERROR_STALL: // IRP was terminated because of a device sent a STALL break; case USB_HOST_IRP_STATUS_COMPLETED: // IRP has been completed break; case USB_HOST_IRP_STATUS_COMPLETED_SHORT: // IRP has been completed but the amount of data processed was less // than requested. break; default: break; } } // In the following code snippet the a control transfer IRP is submitted to a // control pipe. The setup parameter of the IRP points to the Setup command of // the control transfer. The direction of the data stage is specified by the // Setup packet. USB_HOST_IRP irp; USB_ERROR result; USB_HOST_PIPE_HANDLE controlPipe; USB_SETUP_PACKET setup; uint8_t controlTransferData[32]; irp.setup = setup; irp.data = controlTransferData; irp.size = 32; irp.flags = USB_HOST_IRP_FLAG_NONE ; irp.userData = &someApplicationObject; irp.callback = IRP_Callback; result = DRV_USBHS_HOST_IRPSubmit(controlPipeHandle, &irp); Parameters Parameters Description hPipe Handle to the pipe to which the IRP has to be submitted. pInputIRP Pointer to the IRP. Function USB_ERROR DRV_USBHS_HOST_IRPSubmit ( DRV_USBHS_HOST_PIPE_HANDLE hPipe, USB_HOST_IRP * pInputIRP ); DRV_USBHS_HOST_PipeClose Function Closes an open pipe. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1276 File drv_usbhs.h C void DRV_USBHS_HOST_PipeClose(DRV_USBHS_HOST_PIPE_HANDLE pipeHandle); Returns None. Description This function closes an open pipe. Any IRPs scheduled on the pipe will be aborted and IRP callback functions will be called with the status as DRV_USB_HOST_IRP_STATE_ABORTED. The pipe handle will become invalid and the pipe and will not accept IRPs. Remarks None. Preconditions The pipe handle should be valid. Example // This code shows how an open Host pipe can be closed. DRV_HANDLE driverHandle; DRV_USBHS_HOST_PIPE_HANDLE pipeHandle; // Close the pipe. DRV_USBHS_HOST_PipeClose(pipeHandle); Parameters Parameters Description pipeHandle Handle to the pipe to close. Function void DRV_USBHS_HOST_PipeClose ( DRV_USBHS_HOST_PIPE_HANDLE pipeHandle ); DRV_USBHS_HOST_PipeSetup Function Open a pipe with the specified attributes. File drv_usbhs.h C DRV_USBHS_HOST_PIPE_HANDLE DRV_USBHS_HOST_PipeSetup(DRV_HANDLE client, uint8_t deviceAddress, USB_ENDPOINT endpointAndDirection, uint8_t hubAddress, uint8_t hubPort, USB_TRANSFER_TYPE pipeType, uint8_t bInterval, uint16_t wMaxPacketSize, USB_SPEED speed); Returns • DRV_USB_HOST_PIPE_HANDLE_INVALID - The pipe could not be created. • A valid Pipe Handle - The pipe was created successfully. This is an arbitrary value and will never be the same as DRV_USB_HOST_PIPE_HANDLE_INVALID. Description This function opens a communication pipe between the Host and the device endpoint. The transfer type and other attributes are specified through the function parameters. The driver does not check for available bus bandwidth, which should be done by the application (the USB Host Layer in this case) Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1277 Remarks None. Preconditions The driver handle should be valid. Example // This code shows how the DRV_USBHS_HOST_PipeSetup function is called for // create a communication pipe. In this example, Bulk pipe is created // between the Host and a device. The Device address is 2 and the target // endpoint on this device is 4 . The direction of the data transfer over // this pipe is from the Host to the device. The device is connected to Port // 1 of a Hub, whose USB address is 3. The maximum size of a transaction // on this pipe is 64 bytes. This is a Bulk Pipe and hence the bInterval // field is set to 0. The target device is operating at Full Speed. DRV_HANDLE driverHandle; DRV_USBHS_HOST_PIPE_HANDLE pipeHandle; pipeHandle = DRV_USBHS_HOST_PipeSetup(driverHandle, 0x02, 0x14, 0x03, 0x01, USB_TRANSFER_TYPE_BULK, 0, 64, USB_SPEED_FULL); if(pipeHandle != DRV_USBHS_HOST_PIPE_HANDLE_INVALID) { // The pipe was created successfully. } Parameters Parameters Description client Handle to the driver (returned from DRV_USBHS_Open function). deviceAddress USB Address of the device to connect to. endpoint Endpoint on the device to connect to. hubAddress Address of the hub to which this device is connected. If not connected to a hub, this value should be set to 0. hubPort Port number of the hub to which this device is connected. pipeType Transfer type of the pipe to open. bInterval Polling interval for periodic transfers. This should be specified as defined by the USB 2.0 Specification. wMaxPacketSize This should be set to the endpoint size reported by the device in its configuration descriptors. This defines the maximum size of the transaction in a transfer on this pipe. speed The speed of the pipe. This should match the speed at which the device connected to the Host. Function DRV_USBHS_HOST_PIPE_HANDLE DRV_USBHS_HOST_PipeSetup ( DRV_HANDLE client, uint8_t deviceAddress, USB_ENDPOINT endpointAndDirection, uint8_t hubAddress, uint8_t hubPort, USB_TRANSFER_TYPE pipeType, uint8_t bInterval, uint16_t wMaxPacketSize, USB_SPEED speed ); e) Root Hub Functions Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1278 DRV_USBHS_HOST_ROOT_HUB_BusSpeedGet Function This function returns the operating speed of the bus to which this root hub is connected. File drv_usbhs.h C USB_SPEED DRV_USBHS_HOST_ROOT_HUB_BusSpeedGet(DRV_HANDLE handle); Returns • USB_SPEED_HIGH - The Root hub is connected to a bus that is operating at High Speed. • USB_SPEED_FULL - The Root hub is connected to a bus that is operating at Full Speed. Description This function returns the operating speed of the bus to which this root hub is connected. Remarks None. Preconditions None. Example // This code shows how the DRV_USBHS_HOST_ROOT_HUB_BusSpeedGet function is // called to know the operating speed of the bus to which this Root hub is // connected. DRV_HANDLE driverHandle; USB_SPEED speed; speed = DRV_USBHS_HOST_ROOT_HUB_BusSpeedGet(driverHandle); Parameters Parameters Description handle Handle to the driver (returned from DRV_USBHS_Open function). Function USB_SPEED DRV_USBHS_HOST_ROOT_HUB_BusSpeedGet( DRV_HANDLE handle); DRV_USBHS_HOST_ROOT_HUB_Initialize Function This function initializes the root hub driver. File drv_usbhs.h C void DRV_USBHS_HOST_ROOT_HUB_Initialize(DRV_HANDLE handle, USB_HOST_DEVICE_OBJ_HANDLE usbHostDeviceInfo); Returns None. Description This function initializes the root hub driver. It is called by the Host Layer at the time of processing the root hub devices. The Host Layer assigns a USB_HOST_DEVICE_INFO reference to this root hub driver. This identifies the relationship between the root hub and the Host Layer. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1279 Preconditions None. Example // This code shows how the USB Host Layer calls the // DRV_USBHS_HOST_ROOT_HUB_Initialize function. The usbHostDeviceInfo // parameter is an arbitrary identifier assigned by the USB Host Layer. Its // interpretation is opaque to the Root hub Driver. DRV_HANDLE drvHandle; USB_HOST_DEVICE_OBJ_HANDLE usbHostDeviceInfo = 0x10003000; DRV_USBHS_HOST_ROOT_HUB_Initialize(drvHandle, usbHostDeviceInfo); Parameters Parameters Description handle Handle to the driver. usbHostDeviceInfo Reference provided by the Host. Function void DRV_USBHS_HOST_ROOT_HUB_Initialize ( DRV_HANDLE handle, USB_HOST_DEVICE_OBJ_HANDLE usbHostDeviceInfo, ) DRV_USBHS_HOST_ROOT_HUB_MaximumCurrentGet Function Returns the maximum amount of current that this root hub can provide on the bus. File drv_usbhs.h C uint32_t DRV_USBHS_HOST_ROOT_HUB_MaximumCurrentGet(DRV_HANDLE handle); Returns Returns the maximum current (in milliamperes) that the root hub can supply. Description This function returns the maximum amount of current that this root hub can provide on the bus. Remarks None. Preconditions None. Example // This code shows how the DRV_USBHS_HOST_ROOT_HUB_MaximumCurrentGet // function is called to obtain the maximum VBUS current that the Root hub // can supply. DRV_HANDLE driverHandle; uint32_t currentMilliAmperes; currentMilliAmperes = DRV_USBHS_HOST_ROOT_HUB_MaximumCurrentGet(driverHandle); Parameters Parameters Description handle Handle to the driver (returned from DRV_USBHS_Open function). Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1280 Function uint32_t DRV_USBHS_HOST_ROOT_HUB_MaximumCurrentGet( DRV_HANDLE); DRV_USBHS_HOST_ROOT_HUB_OperationEnable Function This function enables or disables root hub operation. File drv_usbhs.h C void DRV_USBHS_HOST_ROOT_HUB_OperationEnable(DRV_HANDLE handle, bool enable); Returns None. Description This function enables or disables root hub operation. When enabled, the root hub will detect devices attached to the port and will request the Host Layer to enumerate the device. This function is called by the Host Layer when it is ready to receive enumeration requests from the Host. If the operation is disabled, the root hub will not detect attached devices. Remarks None. Preconditions None. Example // This code shows how the DRV_USBHS_HOST_ROOT_HUB_OperationEnable and the // DRV_USBHS_HOST_ROOT_HUB_OperationIsEnabled functions are called to enable // the Root hub operation. DRV_HANDLE driverHandle; // Enable Root hub operation. DRV_USBHS_HOST_ROOT_HUB_OperationEnable(driverHandle); // Wait till the Root hub operation is enabled. if(DRV_USBHS_HOST_ROOT_HUB_OperationIsEnabled(driverHandle) == false) { // The operation has not completed. Call the // DRV_USBHS_HOST_ROOT_HUB_OperationIsEnabled function again to check if // the operation has completed. Note that the DRV_USBHS_Tasks function // must be allowed to run at periodic intervals to allow the enable // operation to completed. } Parameters Parameters Description handle Handle to the driver (returned from DRV_USBHS_Open function). enable If this is set to true, root hub operation is enabled. If this is set to false, root hub operation is disabled. Function void DRV_USBHS_HOST_ROOT_HUB_OperationEnable ( DRV_HANDLE handle, bool enable ); Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1281 DRV_USBHS_HOST_ROOT_HUB_OperationIsEnabled Function Returns the operation enabled status of the root hub. File drv_usbhs.h C bool DRV_USBHS_HOST_ROOT_HUB_OperationIsEnabled(DRV_HANDLE handle); Returns • true - Root hub operation is enabled. • false - Root hub operation is not enabled. Description This function returns true if the DRV_USBHS_HOST_ROOT_HUB_OperationEnable function has completed enabling the Host. Remarks None. Preconditions None. Example // This code shows how the DRV_USBHS_HOST_ROOT_HUB_OperationEnable and the // DRV_USBHS_HOST_ROOT_HUB_OperationIsEnabled functions are called to enable // the Root hub operation. DRV_HANDLE driverHandle; // Enable Root hub operation. DRV_USBHS_HOST_ROOT_HUB_OperationEnable(driverHandle); // Wait till the Root hub operation is enabled. if(DRV_USBHS_HOST_ROOT_HUB_OperationIsEnabled(driverHandle) == false) { // The operation has not completed. Call the // DRV_USBHS_HOST_ROOT_HUB_OperationIsEnabled function again to check if // the operation has completed. Note that the DRV_USBHS_Tasks function // must be allowed to run at periodic intervals to allow the enable // operation to completed. } Parameters Parameters Description handle Handle to the driver (returned from DRV_USBHS_Open function). Function bool DRV_USBHS_HOST_ROOT_HUB_OperationIsEnabled( DRV_HANDLE handle); DRV_USBHS_HOST_ROOT_HUB_PortNumbersGet Function Returns the number of ports this root hub contains. File drv_usbhs.h C uint8_t DRV_USBHS_HOST_ROOT_HUB_PortNumbersGet(DRV_HANDLE handle); Returns This function will always return 1. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1282 Description This function returns the number of ports that this root hub contains. Remarks None. Preconditions None. Example // This code shows how DRV_USBHS_HOST_ROOT_HUB_PortNumbersGet function can // be called to obtain the number of Root hub ports. DRV_HANDLE driverHandle; uint8_t nPorts; nPorts = DRV_USBHS_HOST_ROOT_HUB_PortNumbersGet(driverHandle); Parameters Parameters Description handle Handle to the driver (returned from DRV_USBHS_Open function). Function uint8_t DRV_USBHS_HOST_ROOT_HUB_PortNumbersGet( DRV_HANDLE handle); DRV_USBHS_HOST_ROOT_HUB_PortReset Function Resets the specified root hub port. File drv_usbhs.h C USB_ERROR DRV_USBHS_HOST_ROOT_HUB_PortReset(DRV_HANDLE handle, uint8_t port); Returns None. Description This function resets the root hub port. The reset duration is defined by DRV_USBHS_ROOT_HUB_RESET_DURATION. The status of the reset signaling can be checked using the DRV_USBHS_ROOT_HUB_PortResetIsComplete function. Remarks The root hub on the PIC32MZ USB controller contains only one port - port 0. Preconditions None. Example // This code shows how the DRV_USB_HOST_ROOT_HUB_PortReset and the // DRV_USBHS_ROOT_HUB_PortResetIsComplete functions are called to complete a // port reset sequence. DRV_HANDLE driverHandle; // Reset Port 0. DRV_USB_HOST_ROOT_HUB_PortReset(driverHandle, 0); // Check if the Reset operation has completed. if(DRV_USBHS_ROOT_HUB_PortResetIsComplete(driverHandle, 0) == false) { // This means that the Port Reset operation has not completed yet. The // DRV_USBHS_ROOT_HUB_PortResetIsComplete function should be called Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1283 // again after some time to check the status. } Parameters Parameters Description handle Handle to the driver (returned from DRV_USBHS_Open function). port Port to reset. Function void DRV_USBHS_ROOT_HUB_PortReset( DRV_HANDLE handle, uint8_t port ); DRV_USBHS_HOST_ROOT_HUB_PortResetIsComplete Function Returns true if the root hub has completed the port reset operation. File drv_usbhs.h C bool DRV_USBHS_HOST_ROOT_HUB_PortResetIsComplete(DRV_HANDLE handle, uint8_t port); Returns • true - The reset signaling has completed. • false - The reset signaling has not completed. Description This function returns true if the port reset operation has completed. It should be called after the DRV_USB_HOST_ROOT_HUB_PortReset function to check if the reset operation has completed. Remarks The root hub on this particular hardware only contains one port - port 0. Preconditions None. Example // This code shows how the DRV_USB_HOST_ROOT_HUB_PortReset and the // DRV_USBHS_ROOT_HUB_PortResetIsComplete functions are called to complete a // port reset sequence. DRV_HANDLE driverHandle; // Reset Port 0. DRV_USB_HOST_ROOT_HUB_PortReset(driverHandle, 0); // Check if the Reset operation has completed. if(DRV_USBHS_ROOT_HUB_PortResetIsComplete(driverHandle, 0) == false) { // This means that the Port Reset operation has not completed yet. The // DRV_USBHS_ROOT_HUB_PortResetIsComplete function should be called // again after some time to check the status. } Parameters Parameters Description handle Handle to the driver (returned from DRV_USBHS_Open function). port Port to check Function bool DRV_USBHS_ROOT_HUB_PortResetIsComplete ( DRV_HANDLE handle, Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1284 uint8_t port ); DRV_USBHS_HOST_ROOT_HUB_PortResume Function Resumes the specified root hub port. File drv_usbhs.h C USB_ERROR DRV_USBHS_HOST_ROOT_HUB_PortResume(DRV_HANDLE handle, uint8_t port); Returns • USB_ERROR_NONE - The function executed successfully. • USB_ERROR_PARAMETER_INVALID - The driver handle is not valid or the port number does not exist. Description This function resumes the root hub. The resume duration is defined by DRV_USBHS_ROOT_HUB_RESUME_DURATION. The status of the resume signaling can be checked using the DRV_USBHS_ROOT_HUB_PortResumeIsComplete function. Remarks The root hub on this particular hardware only contains one port - port 0. Preconditions None. Example // This code shows how the DRV_USBHS_HOST_ROOT_HUB_PortResume function is // called to resume the specified port. DRV_HANDLE driverHandle; // Resume Port 0. DRV_USBHS_HOST_ROOT_HUB_PortResume(driverHandle, 0); Parameters Parameters Description handle Handle to the driver (returned from DRV_USBHS_Open function). port Port to resume. Function USB_ERROR DRV_USBHS_HOST_ROOT_HUB_PortResume ( DRV_HANDLE handle, uint8_t port ); DRV_USBHS_HOST_ROOT_HUB_PortSpeedGet Function Returns the speed of at which the port is operating. File drv_usbhs.h C USB_SPEED DRV_USBHS_HOST_ROOT_HUB_PortSpeedGet(DRV_HANDLE handle, uint8_t port); Returns • USB_SPEED_ERROR - This value is returned if the driver handle is not or if the speed information is not available or if the specified port is not valid. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1285 • USB_SPEED_HIGH - A High Speed device has been connected to the port. • USB_SPEED_FULL - A Full Speed device has been connected to the port. • USB_SPEED_LOW - A Low Speed device has been connected to the port. Description This function returns the speed at which the port is operating. Remarks The root hub on this particular hardware only contains one port - port 0. Preconditions None. Example // This code shows how the DRV_USBHS_HOST_ROOT_HUB_PortSpeedGet function is // called to know the operating speed of the port. This also indicates the // operating speed of the device connected to this port. DRV_HANDLE driverHandle; USB_SPEED speed; speed = DRV_USBHS_HOST_ROOT_HUB_PortSpeedGet(driverHandle, 0); Parameters Parameters Description handle Handle to the driver (returned from DRV_USBHS_Open function). port Port number of the port to be analyzed.. Function USB_SPEED DRV_USBHS_HOST_ROOT_HUB_PortSpeedGet ( DRV_HANDLE handle, uint8_t port ); DRV_USBHS_HOST_ROOT_HUB_PortSuspend Function Suspends the specified root hub port. File drv_usbhs.h C USB_ERROR DRV_USBHS_HOST_ROOT_HUB_PortSuspend(DRV_HANDLE handle, uint8_t port); Returns • USB_ERROR_NONE - The function executed successfully. • USB_ERROR_PARAMETER_INVALID - The driver handle is not valid or the port number does not exist. Description This function suspends the root hub port. Remarks The root hub on this particular hardware only contains one port - port 0. Preconditions None. Example // This code shows how the DRV_USBHS_HOST_ROOT_HUB_PortSuspend function is // called to suspend the specified port. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1286 DRV_HANDLE driverHandle; // Suspend Port 0. DRV_USBHS_HOST_ROOT_HUB_PortSuspend(driverHandle, 0); Parameters Parameters Description handle Handle to the driver (returned from DRV_USBHS_Open function). port Port to suspend. Function USB_ERROR DRV_USBHS_ROOT_HUB_PortSuspend( DRV_HANDLE handle, uint8_t port); f) Data Types and Constants DRV_USBHS_EVENT Enumeration Identifies the different events that the Hi-Speed USB Driver provides. File drv_usbhs.h C typedef enum { DRV_USBHS_EVENT_ERROR = DRV_USB_EVENT_ERROR, DRV_USBHS_EVENT_RESET_DETECT = DRV_USB_EVENT_RESET_DETECT, DRV_USBHS_EVENT_RESUME_DETECT = DRV_USB_EVENT_RESUME_DETECT, DRV_USBHS_EVENT_IDLE_DETECT = DRV_USB_EVENT_IDLE_DETECT, DRV_USBHS_EVENT_STALL = DRV_USB_EVENT_STALL, DRV_USBHS_EVENT_SOF_DETECT = DRV_USB_EVENT_SOF_DETECT, DRV_USBHS_EVENT_DEVICE_SESSION_VALID = DRV_USB_EVENT_DEVICE_SESSION_VALID, DRV_USBHS_EVENT_DEVICE_SESSION_INVALID = DRV_USB_EVENT_DEVICE_SESSION_INVALID } DRV_USBHS_EVENT; Members Members Description DRV_USBHS_EVENT_ERROR = DRV_USB_EVENT_ERROR Bus error occurred and was reported DRV_USBHS_EVENT_RESET_DETECT = DRV_USB_EVENT_RESET_DETECT Host has issued a device reset DRV_USBHS_EVENT_RESUME_DETECT = DRV_USB_EVENT_RESUME_DETECT Resume detected while USB in suspend mode DRV_USBHS_EVENT_IDLE_DETECT = DRV_USB_EVENT_IDLE_DETECT Idle detected DRV_USBHS_EVENT_STALL = DRV_USB_EVENT_STALL Stall handshake has occurred DRV_USBHS_EVENT_SOF_DETECT = DRV_USB_EVENT_SOF_DETECT Device received SOF operation DRV_USBHS_EVENT_DEVICE_SESSION_VALID = DRV_USB_EVENT_DEVICE_SESSION_VALID VBUS voltage had Session valid DRV_USBHS_EVENT_DEVICE_SESSION_INVALID = DRV_USB_EVENT_DEVICE_SESSION_INVALID Session Invalid Description Hi-Speed USB Driver Events Enumeration. This enumeration identifies the different events that are generated by the Hi-Speed USB Driver. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1287 DRV_USBHS_EVENT_CALLBACK Type Type of the Hi-Speed USB Driver event callback function. File drv_usbhs.h C typedef void (* DRV_USBHS_EVENT_CALLBACK)(uintptr_t hClient, DRV_USBHS_EVENT eventType, void * eventData); Returns None. Description Type of the Hi-Speed USB Driver Event Callback Function. Define the type of the Hi-Speed USB Driver event callback function. The client should register an event callback function of this type when it intends to receive events from the Hi-Speed USB Driver. The event callback function is registered using the DRV_USBHS_ClientEventCallBackSet function. Remarks None. Parameters Parameters Description hClient Handle to the driver client that registered this callback function. eventType This parameter identifies the event that caused the callback function to be called. eventData Pointer to a data structure that is related to this event. This value will be NULL if the event has no related data. DRV_USBHS_HOST_PIPE_HANDLE Type Defines the Hi-Speed USB Driver Host Pipe Handle type. File drv_usbhs.h C typedef uintptr_t DRV_USBHS_HOST_PIPE_HANDLE; Description Hi-Speed USB Driver Host Pipe Handle. This type definition defines the type of the Hi-Speed USB Driver Host Pipe Handle. Remarks None. DRV_USBHS_INIT Structure This type definition defines the Driver Initialization Data Structure. File drv_usbhs.h C typedef struct { SYS_MODULE_INIT moduleInit; USBHS_MODULE_ID usbID; bool stopInIdle; bool suspendInSleep; INT_SOURCE interruptSource; INT_SOURCE interruptSourceUSBDma; USB_SPEED operationSpeed; Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1288 DRV_USBHS_OPMODES operationMode; void * endpointTable; uint32_t rootHubAvailableCurrent; DRV_USBHS_ROOT_HUB_PORT_POWER_ENABLE portPowerEnable; DRV_USBHS_ROOT_HUB_PORT_INDICATION portIndication; DRV_USBHS_ROOT_HUB_PORT_OVER_CURRENT_DETECT portOverCurrentDetect; } DRV_USBHS_INIT; Members Members Description SYS_MODULE_INIT moduleInit; System Module Initialization USBHS_MODULE_ID usbID; Identifies the USB peripheral to be used. This should be the USB PLIB module instance identifier. bool stopInIdle; This should be set to true if the USB module must stop operation in Idle mode bool suspendInSleep; This should be set to true if the USB module must suspend when the CPU enters Sleep mode. INT_SOURCE interruptSource; Specify the interrupt source for the USB module. This should be the interrupt source for the USB module instance specified in usbID. INT_SOURCE interruptSourceUSBDma; Specify the interrupt source for the USB module specific DMA controller. This should be the USB DMA interrupt source for the USB Module instance specified in usbID. USB_SPEED operationSpeed; Specify the operational speed of the USB module. This should always be set to USB_SPEED_FULL. DRV_USBHS_OPMODES operationMode; Specify the operation mode of the USB module. This specifies if the USB module should operate as a Device, Host, or both (Dual Role operation). void * endpointTable; A pointer to the endpoint descriptor table. This should be aligned at 512 byte address boundary. The size of the table is equal to the DRV_USBHS_ENDPOINT_TABLE_ENTRY_SIZE times the number of endpoints needed in the application. uint32_t rootHubAvailableCurrent; Root hub available current in milliamperes. This specifies the amount of current that root hub can provide to the attached device. This should be specified in mA. This is required when the driver is required to operate in Host mode. DRV_USBHS_ROOT_HUB_PORT_POWER_ENABLE portPowerEnable; When operating in Host mode, the application can specify a Root hub port enable function. This parameter should point to Root hub port enable function. If this parameter is NULL, it implies that the port is always enabled. DRV_USBHS_ROOT_HUB_PORT_INDICATION portIndication; When operating in Host mode, the application can specify a Root Port Indication. This parameter should point to the Root Port Indication function. If this parameter is NULL, it implies that Root Port Indication is not supported. DRV_USBHS_ROOT_HUB_PORT_OVER_CURRENT_DETECT portOverCurrentDetect; When operating is Host mode, the application can specify a Root Port Overcurrent detection. This parameter should point to the Root Port Indication function. If this parameter is NULL, it implies that Overcurrent detection is not supported. Description USB Device Driver Initialization Data. This structure contains all the data necessary to initialize the Hi-Speed USB Driver. A pointer to a structure of this type, containing the desired initialization data, must be passed into the DRV_USBHS_Initialize function. Remarks None. DRV_USBHS_OPMODES Enumeration Identifies the operating modes supported by the Hi-Speed USB Driver. File drv_usbhs.h C typedef enum { DRV_USBHS_OPMODE_DUAL_ROLE = DRV_USB_OPMODE_DUAL_ROLE, DRV_USBHS_OPMODE_DEVICE = DRV_USB_OPMODE_DEVICE, DRV_USBHS_OPMODE_HOST = DRV_USB_OPMODE_HOST, DRV_USBHS_OPMODE_OTG = DRV_USB_OPMODE_OTG } DRV_USBHS_OPMODES; Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1289 Members Members Description DRV_USBHS_OPMODE_DUAL_ROLE = DRV_USB_OPMODE_DUAL_ROLE The driver should be able to switch between Host and Device mode DRV_USBHS_OPMODE_DEVICE = DRV_USB_OPMODE_DEVICE The driver should support Device mode operation only DRV_USBHS_OPMODE_HOST = DRV_USB_OPMODE_HOST The driver should support Host mode operation only DRV_USBHS_OPMODE_OTG = DRV_USB_OPMODE_OTG The driver should support the OTG protocol Description USB Operating Modes Enumeration. This enumeration identifies the operating modes supported by the Hi-Speed USB Driver. Remarks None. DRV_USBHS_ROOT_HUB_PORT_INDICATION Type USB Root hub Application Hooks (Port Indication). File drv_usbhs.h C typedef void (* DRV_USBHS_ROOT_HUB_PORT_INDICATION)(uint8_t port, USB_HUB_PORT_INDICATOR_COLOR color, USB_HUB_PORT_INDICATOR_STATE state); Description USB Root hub Application Hooks (Port Indication). A function of the type defined here should be provided to the driver root to implement Port Indication. The root hub driver calls this function when it needs to update the state of the port indication LEDs. The application can choose to implement the Amber and Green colors as one LED or two different LEDs. The root hub driver specifies the color and the indicator attribute (on, off or blinking) when it calls this function. Remarks None. DRV_USBHS_ROOT_HUB_PORT_OVER_CURRENT_DETECT Type USB Root hub Application Hooks (Port Overcurrent detection). File drv_usbhs.h C typedef bool (* DRV_USBHS_ROOT_HUB_PORT_OVER_CURRENT_DETECT)(uint8_t port); Description USB Root hub Application Hooks (Port Overcurrent detection). A function of the type defined here should be provided to the driver root hub to check for port over current condition. This function will be called periodically by the root hub driver to check the Overcurrent status of the port. It should continue to return true while the Overcurrent condition exists on the port. It should return false when the Overcurrent condition does not exist. Remarks None. DRV_USBHS_ROOT_HUB_PORT_POWER_ENABLE Type USB Root hub Application Hooks (Port Power Enable/ Disable). Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1290 File drv_usbhs.h C typedef void (* DRV_USBHS_ROOT_HUB_PORT_POWER_ENABLE)(uint8_t port, bool control); Description USB Root hub Application Hooks (Port Power Enable/ Disable). A function of the type defined here should be provided to the driver root to control port power. The root hub driver will call this function when it needs to enable port power. If the application circuit contains a VBUS switch, the switch should be accessed and controlled by this function. If the enable parameter is true, the switch should be enabled and VBUS should be available on the port. If the enable parameter is false, the switch should be disabled and VBUS should not be available on the port. Remarks None. DRV_USBHS_DEVICE_INTERFACE Macro Hi-Speed USB Driver Device Mode Interface Functions. File drv_usbhs.h C #define DRV_USBHS_DEVICE_INTERFACE Description Hi-Speed USB Driver Device Mode Interface Functions. The Device Controller Driver Interface member of the Device Stack Initialization data structure should be set to this value so that the Device Stack can access the Hi-Speed USB Driver Device Mode functions. Remarks None. DRV_USBHS_HOST_INTERFACE Macro Hi-Speed USB Driver Host Mode Interface Functions. File drv_usbhs.h C #define DRV_USBHS_HOST_INTERFACE Description Hi-Speed USB Driver Host Mode Interface Functions. The Host Controller Driver Interface member of the Host Layer Initialization data structure should be set to this value so that the Host Layer can access the Hi-Speed USB Driver Host Mode functions. Remarks None. DRV_USBHS_HOST_PIPE_HANDLE_INVALID Macro Value of an Invalid Host Pipe Handle. File drv_usbhs.h C #define DRV_USBHS_HOST_PIPE_HANDLE_INVALID Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1291 Description Hi-Speed USB Driver Invalid Host Pipe Handle. This constant defines the value of an Invalid Host Pipe Handle. Remarks None. DRV_USBHS_INDEX_0 Macro Hi-Speed USB Driver Module Index 0 Definition. File drv_usbhs.h C #define DRV_USBHS_INDEX_0 0 Description Hi-Speed USB Driver Module Index 0 Definition. This constant defines the value of Hi-Speed USB Driver Index 0. The SYS_MODULE_INDEX parameter of the DRV_USBHS_Initialize and DRV_USBHS_Open functions should be set to this value to identify instance 0 of the driver. Remarks These constants should be used in place of hard-coded numeric literals and should be passed into the DRV_USBHS_Initialize and DRV_USBHS_Open functions to identify the driver instance in use. These are not indicative of the number of modules that are actually supported by the microcontroller. Files Files Name Description drv_usbhs.h PIC32MZ USB Module Driver Interface File drv_usbhs_config_template.h Hi-Speed USB (USBHS) Driver Configuration Template. Description drv_usbhs.h PIC32MZ USB Module Driver Interface File Enumerations Name Description DRV_USBHS_EVENT Identifies the different events that the Hi-Speed USB Driver provides. DRV_USBHS_OPMODES Identifies the operating modes supported by the Hi-Speed USB Driver. Functions Name Description DRV_USBHS_ClientEventCallBackSet This function sets up the event callback function that is invoked by the USB controller driver to notify the client of USB bus events. DRV_USBHS_Close Closes an opened-instance of the Hi-Speed USB Driver. DRV_USBHS_DEVICE_AddressSet This function will set the USB module address that is obtained from the Host. DRV_USBHS_DEVICE_Attach This function will enable the attach signaling resistors on the D+ and Dlines thus letting the USB Host know that a device has been attached on the bus. DRV_USBHS_DEVICE_CurrentSpeedGet This function will return the USB speed at which the device is operating. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1292 DRV_USBHS_DEVICE_Detach This function will disable the attach signaling resistors on the D+ and Dlines thus letting the USB Host know that the device has detached from the bus. DRV_USBHS_DEVICE_EndpointDisable This function disables an endpoint. DRV_USBHS_DEVICE_EndpointDisableAll This function disables all provisioned endpoints. DRV_USBHS_DEVICE_EndpointEnable This function enables an endpoint for the specified direction and endpoint size. DRV_USBHS_DEVICE_EndpointIsEnabled This function returns the enable/disable status of the specified endpoint and direction. DRV_USBHS_DEVICE_EndpointIsStalled This function returns the stall status of the specified endpoint and direction. DRV_USBHS_DEVICE_EndpointStall This function stalls an endpoint in the specified direction. DRV_USBHS_DEVICE_EndpointStallClear This function clears the stall on an endpoint in the specified direction. DRV_USBHS_DEVICE_IRPCancel This function cancels the specific IRP that are queued and in progress at the specified endpoint. DRV_USBHS_DEVICE_IRPCancelAll This function cancels all IRPs that are queued and in progress at the specified endpoint. DRV_USBHS_DEVICE_IRPSubmit This function submits an I/O Request Packet (IRP) for processing to the Hi-Speed USB Driver. DRV_USBHS_DEVICE_RemoteWakeupStart This function causes the device to start Remote Wakeup Signalling on the bus. DRV_USBHS_DEVICE_RemoteWakeupStop This function causes the device to stop the Remote Wakeup Signalling on the bus. DRV_USBHS_DEVICE_SOFNumberGet This function will return the USB SOF packet number. DRV_USBHS_DEVICE_TestModeEnter This function enables the specified USB 2.0 Test Mode. DRV_USBHS_DEVICE_TestModeExit This function disables the specified USB 2.0 Test Mode. DRV_USBHS_HOST_EventsDisable Disables Host mode events. DRV_USBHS_HOST_EventsEnable Restores the events to the specified the original value. DRV_USBHS_HOST_IRPCancel Cancels the specified IRP. DRV_USBHS_HOST_IRPSubmit Submits an IRP on a pipe. DRV_USBHS_HOST_PipeClose Closes an open pipe. DRV_USBHS_HOST_PipeSetup Open a pipe with the specified attributes. DRV_USBHS_HOST_ROOT_HUB_BusSpeedGet This function returns the operating speed of the bus to which this root hub is connected. DRV_USBHS_HOST_ROOT_HUB_Initialize This function initializes the root hub driver. DRV_USBHS_HOST_ROOT_HUB_MaximumCurrentGet Returns the maximum amount of current that this root hub can provide on the bus. DRV_USBHS_HOST_ROOT_HUB_OperationEnable This function enables or disables root hub operation. DRV_USBHS_HOST_ROOT_HUB_OperationIsEnabled Returns the operation enabled status of the root hub. DRV_USBHS_HOST_ROOT_HUB_PortNumbersGet Returns the number of ports this root hub contains. DRV_USBHS_HOST_ROOT_HUB_PortReset Resets the specified root hub port. DRV_USBHS_HOST_ROOT_HUB_PortResetIsComplete Returns true if the root hub has completed the port reset operation. DRV_USBHS_HOST_ROOT_HUB_PortResume Resumes the specified root hub port. DRV_USBHS_HOST_ROOT_HUB_PortSpeedGet Returns the speed of at which the port is operating. DRV_USBHS_HOST_ROOT_HUB_PortSuspend Suspends the specified root hub port. DRV_USBHS_Initialize Initializes the Hi-Speed USB Driver. DRV_USBHS_Open Opens the specified Hi-Speed USB Driver instance and returns a handle to it. DRV_USBHS_Status Provides the current status of the Hi-Speed USB Driver module. DRV_USBHS_Tasks Maintains the driver's state machine when the driver is configured for Polled mode. DRV_USBHS_Tasks_ISR Maintains the driver's Interrupt state machine and implements its ISR. DRV_USBHS_Tasks_ISR_USBDMA Maintains the driver's DMA Transfer state machine and implements its ISR. Macros Name Description DRV_USBHS_DEVICE_INTERFACE Hi-Speed USB Driver Device Mode Interface Functions. DRV_USBHS_HOST_INTERFACE Hi-Speed USB Driver Host Mode Interface Functions. Volume V: MPLAB Harmony Framework Driver Libraries Help USB Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1293 DRV_USBHS_HOST_PIPE_HANDLE_INVALID Value of an Invalid Host Pipe Handle. DRV_USBHS_INDEX_0 Hi-Speed USB Driver Module Index 0 Definition. Structures Name Description DRV_USBHS_INIT This type definition defines the Driver Initialization Data Structure. Types Name Description DRV_USBHS_EVENT_CALLBACK Type of the Hi-Speed USB Driver event callback function. DRV_USBHS_HOST_PIPE_HANDLE Defines the Hi-Speed USB Driver Host Pipe Handle type. DRV_USBHS_ROOT_HUB_PORT_INDICATION USB Root hub Application Hooks (Port Indication). DRV_USBHS_ROOT_HUB_PORT_OVER_CURRENT_DETECT USB Root hub Application Hooks (Port Overcurrent detection). DRV_USBHS_ROOT_HUB_PORT_POWER_ENABLE USB Root hub Application Hooks (Port Power Enable/ Disable). Description PIC32MZ USB Module Driver Interface Header File The PIC32MZ Hi-Speed USB Module driver provides a simple interface to manage the "USB" peripheral on the PIC32MZ microcontroller. This file defines the interface definitions and prototypes for the Hi-Speed USB Driver. The driver interface meets the requirements of the MPLAB Harmony USB Host and Device Layer. File Name drv_usbhs.h Company Microchip Technology Inc. drv_usbhs_config_template.h Hi-Speed USB (USBHS) Driver Configuration Template. Macros Name Description DRV_USBHS_DEVICE_SUPPORT Determines if the USB Device Functionality should be enabled. DRV_USBHS_ENDPOINTS_NUMBER Configures the number of endpoints to be provisioned in the driver. DRV_USBHS_HOST_ATTACH_DEBOUNCE_DURATION Configures the time duration (in milliseconds) that the driver will wait to reconfirm a device attach. DRV_USBHS_HOST_NAK_LIMIT Configures the NAK Limit for Host Mode Control Transfers. DRV_USBHS_HOST_PIPES_NUMBER Configures the maximum number of pipes that are can be opened when the driver is operating in Host mode. DRV_USBHS_HOST_RESET_DURATION Configures the time duration (in milliseconds) of the Reset Signal. DRV_USBHS_HOST_SUPPORT Determines if the USB Host Functionality should be enabled. DRV_USBHS_INSTANCES_NUMBER Specifies the number of driver instances to be enabled in the application. DRV_USBHS_INTERRUPT_MODE Configures the driver for interrupt or polling mode operation. Description Hi-Speed USB Driver Configuration Template This file lists all the configurations constants that affect the operation of the USBHS Driver. File Name drv_usbhs_config_template.h Company Microchip Technology Inc. USART Driver Library This section describes the USART Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1294 Introduction This section introduces the MPLAB Harmony USART Driver. Description The MPLAB Harmony USART Driver (also referred to as the USART Driver) provides a high-level interface to the USART and UART peripherals on Microchip's PIC32 microcontrollers. This driver provides application ready routines to read and write data to the UART using common data transfer models, which eliminates the need for the application to implement this code. The USART driver features the following: • Provides byte transfer, read/write, and buffer queue data transfer models • Supports Interrupt and Polled modes of operation • Supports point-to-point data communication • Supports multi-client and multi-instance operation • Provides data transfer events • Supports blocking and non-blocking operation with the read/write data transfer model • Features thread-safe functions for use in RTOS applications • Supports DMA transfers • Supports high baud rate setting • Major features are implemented in separate source code files and can be included only if needed. This helps optimize overall application code size. Using the Library This topic describes the basic architecture of the USART Driver Library and provides information and examples on its use. Description Interface Header File: drv_usart.h The interface to the USART library is defined in the drv_usart.h header file. Please refer to the What is MPLAB Harmony? section for how the driver interacts with the framework. Abstraction Model This section describes how the USART Driver abstracts the USART peripheral features. Description The USART driver features routines to perform the following functions: • Driver initialization • Transfer data • Manage communication properties of the module The Driver initialization routines allow the system to initialize the driver. The driver must be initialized before it can be opened by a client. The data transfer routines allow the application to receive and transmit data through the USART. The driver also provides routines to change the communication properties such as USART baud or line control settings. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1295 As seen in the previous figure, the USART driver clients transfer data through the USART Driver Data Transfer model. The driver abstracts out the hardware details of the UART module FIFO mechanism and shift registers, and provides a low overhead data transfer mechanism to the application. The USART driver provides three different data transfer models for transferring data. • The Byte Transfer Model • The File I/O Type Read/Write Transfer Model • Buffer Queue Transfer Model Byte Transfer Model: The byte transfer model allows the application to transfer data through USART driver one byte at a time. With this model, the driver reads one byte from the receive FIFO or writes one byte to the transmit FIFO. The application must check if data has been received before reading the data. Similarly, it must check if the transmit FIFO is not full before writing to the FIFO. The byte transfer model places the responsibility of maintaining the USART peripheral on the Application. The driver cannot support other data transfer models if support for this data transfer model is enabled. The byte transfer model is only recommended for simple data transfer applications. To use the byte transfer model, the drv_usart_byte_model.c file must be included in the project and the DRV_USART_BYTE_MODEL_SUPPORT configuration macro should be set to true. File I/O Type Read/Write Transfer Model: This data transfer model is similar to file read and write API model in a UNIX operating system application. The application calls the USART driver read and write routines to transfer data through the USART. Unlike the byte transfer model, the read/write data model can process a block of data. Depending on the mode (blocking or non-blocking) in which the client opened the driver, the driver will either block until all of the data is transferred or will immediately return with the number of bytes transferred. The application does not have to check the FIFO status while using this mode. The application can instead use the return status (number of bytes transferred) to maintain its logic and complete the data transfer. The read/write model can be used with the non-DMA buffer queue model. It cannot be used with the byte transfer model and the DMA-enabled buffer queue model in the same application. To use the file I/O type read/write data transfer model, the drv_usart_read_write.c file must be included in the project and the DRV_USART_READ_WRITE_MODEL_SUPPORT configuration macro should be set to true. See File I/O Type Read/Write Data Transfer Modef for additional information. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1296 Buffer Queue Transfer Model: The buffer queue data transfer model allows clients to queue data transfers for processing. This data transfer model is always non-blocking. The USART driver returns a buffer handle for a queued request. The clients can track the completion of a buffer through events and API. If the USART driver is busy processing a data transfer, other data transfer requests are queued. This allows the clients to optimize their application logic and increase throughput. To optimize memory usage, the USART driver implements a shared buffer object pool concept to add a data transfer request to the queue. The following figure shows a conceptual representation of the buffer queue model. Buffer Queue Transfer Model As shown in the previous figure, each USART driver hardware instance has a read and write queue. The system designer must configure the sizes of these read and write queues. The USART driver additionally employs a global pool of buffer queue objects. This pool is common to all USART Driver hardware instances and its size is defined by the DRV_USART_QUEUE_DEPTH_COMBINED configuration macro. When a client places a request to add a data transfer, the driver performs the following actions: • It checks if a buffer object is free in the global pool. If not, the driver rejects the request. • It then checks if the hardware instance specific queue is full. If not, the buffer object from the global pool is added to the hardware instance specific queue. If the queue is full, the driver rejects the request. The buffer queue model can be used along with the file I/O type read/write data transfer model. To use the Buffer Queue Data Transfer model, the drv_usart_buffer_queue.c file must be included in the project and DRV_USART_BUFFER_QUEUE_SUPPORT configuration macro should be set to true. The USART Driver DMA feature is only available while using the Buffer Queue Model. If enabled, the USART Driver uses the DMA module channels to transfer data directly from application memory to USART transmit or receive registers. This reduces CPU resource consumption and improves system performance. To use the buffer queue model with DMA, the drv_usart_buffer_queue_dma.c file should be included in the project instead of drv_usart_buffer_queue.c. See Buffer Queue Transfer Model for additional information. Communication Management The USART Driver API contains functions to control the USART Driver communication properties. These functions allow the client to change the parity, stop bits, number of data bits and the communication baud rate. A change in the communication setting affects all ongoing communication and all driver clients. Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1297 The library interface routines are divided into various sub-sections, which address one of the blocks or the overall operation of the USART Driver Library. Library Interface Section Description System Routines These routines are accessed by the MPLAB Harmony system module. They allow the driver to be initialized, deinitialized and maintained. Core Client Routines These routines allow the application client to open and close the driver. Communication Management Client Routines These routines allow the client to change the properties of the communication channel (such as baud, parity, etc.). Buffer Queue Read/Write Client Routines These routines allow the client to use the buffer queue data transfer model. File I/O Type Read/Write Routines These routines allow the client to use the file I/O type read/write routines. Byte Transfer Routines These routines allow the client to use the byte data transfer model. The USART driver must be first initialized. One or more application clients can then open the USART Driver in Blocking or non-Blocking mode. The Open function returns a handle which allows the client to access the driver client functionality. The Driver tasks routines should be invoked regularly from the SYS_Tasks routine in case of Polled mode operation or from USART Driver Interrupt Service Routine (ISR), in case of Interrupt mode. The driver implementation is split across multiple files to optimize the application project code size. The application project must include the drv_usart.c file if the USART driver is needed in the application. If DMA-enabled data transfers are required, the drv_usart_dma.c file should be included into the project instead of the drv_usart.c file. These files implement the system and core Client routines. Other driver files can be included based on the required driver features. The USART Driver API, unless otherwise specified, should not be called from an interrupt context. That is, they should not be called from an ISR or from event handlers that are executing within an ISR context. How the Library Works This section describes how to use the USART Driver. Description Prior to using the USART Driver, the application must decide on which USART data transfer models are required. The application project should then include the USART Driver files, required to support the data transfer model into the application project. Additionally, the application design must consider the need for USART Driver to be opened in blocking or non blocking modes. This will also affect the application flow. Initializing the USART Driver Describes how to initialize the USART Driver. Description The USART Driver must be configured and initialized for clients to be able to open the driver. The driver build time configuration is defined by the configuration macros. Refer to the Building the Library section for the location of and more information on the various configuration macros and how these macros should be designed. The driver initialization is configured through the DRV_USART_INIT data structure that is passed to the DRV_USART_Initialize function. The initialization parameters include the USART baud, the USART Peripheral, USART interrupts and read queue and write queue sizes (which are applicable only when buffer queue data transfer is used). The following code shows an example of initializing the USART driver for 300 bps and uses USART2. If the driver is configured for Interrupt mode of operation, the priority of the USART interrupts needs to be specified. /* The following code shows an example of designing the * DRV_USART_INIT data structure. It also shows how an example * usage of the DRV_USART_Initialize() function and how Interrupt * System Service routines are used to set USART Interrupt * priority. */ DRV_USART_INIT usartInit; SYS_MODULE_OBJ usartModule1; /* Set the baud to 300 */ usartInit.baud = 300; /* Auto Baud detection or Stop Idle is not needed */ usartInit.flags = DRV_USART_INIT_FLAG_NONE; /* Handshaking is not needed */ usartInit.handshake = DRV_USART_HANDSHAKE_NONE; Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1298 /* USART Error Interrupt source for this USART * driver instance. Note that INT_SOURCE_USART_2_ERROR * value is defined by the Interrupt System Service and * is the error interrupt for USART 2*/ usartInit.interruptError = INT_SOURCE_USART_2_ERROR; /* USART Receive Interrupt source for this USART * driver instance. Note that INT_SOURCE_USART_2_RECEIVE * value is defined by the Interrupt System Service and * is the error interrupt for USART 2 */ usartInit.interruptReceive = INT_SOURCE_USART_2_RECEIVE; /* USART Transmit Interrupt source for this USART * driver instance. Note that INT_SOURCE_USART_2_TRANSMIT * value is defined by the Interrupt System Service and * is the error interrupt for USART 2 */ usartInit.interruptTransmit = INT_SOURCE_USART_2_TRANSMIT; /* Line control mode */ usartInit.lineControl = DRV_USART_LINE_CONTROL_8NONE1; /* Operation mode is normal. Loopback or addressed is not * needed */ usartInit.mode = DRV_USART_OPERATION_MODE_NORMAL; /* Peripheral Bus clock frequency at which the USART is * operating */ usartInit.brgClock = 80000000; /* System module power setting. Typically set to * SYS_MODULE_POWER_RUN_FULL */ usartInit.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; /* Receive buffer queue size. In this case a maximum of 2 * receive buffers can be queued. Only applicable if the * Buffer Queue Data Transfer Model is included in the * application. */ usartInit.queueSizeReceive = 2; /* Transmit buffer queue size. In this case a maximum of 3 * transmit buffers can be queued. Only applicable if the * Buffer Queue Data Transfer Model is included in the * application. */ usartInit.queueSizeTransmit = 3; /* The USART peripheral instance index associated with this * driver instance. Note that this value is defined by the * USART Peripheral Library */ usartInit.usartID = USART_ID_2; /* Initialize USART Driver Instance 0 */ usartModule1 = DRV_USART_Initialize(DRV_USART_0, (SYS_MODULE_INIT*)&usartInit); /* The result of the driver initialization can be checked */ if(SYS_MODULE_OBJ_INVALID == usartModule1) { /* There was an error in initialization. */ } /* If the USART driver is configured for interrupt mode of * operation, the interrupt priorities should be configured. * Here the Interrupt System Service is used to set the * priority to level 4 */ /* Initialize the interrupt system service */ SYS_INT_Initialize(); /* Set the USART 2 module interrupt priority to 4*/ SYS_INT_VectorPrioritySet(INT_VECTOR_UART2, INT_PRIORITY_LEVEL4); Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1299 /* Set the USART 2 module interrupt sub-priority to 0*/ SYS_INT_VectorSubprioritySet(INT_VECTOR_UART2, INT_SUBPRIORITY_LEVEL0); /* Enable global interrupt */ SYS_INT_Enable(); The USART Driver can be configured to transfer data through the DMA. In such a case, the DMA channels to be used for USART transmit and receive need to be specified. The USART Driver depends on the DMA System Service to access the DMA module. The DMA channels to be used for transmit and receive transfers should be specified in the DRV_USART_INIT data structure. The following code shows an example of using the USART Driver initialization to use DMA for transferring data. The code also shows example initialization of the DMA System Service. /* The following code shows an example of designing the * DRV_USART_INIT data structure. It also shows how an example * usage of the DRV_USART_Initialize() function and how Interrupt * System Service routines are used to set USART Interrupt * priority. */ DRV_USART_INIT usartInit; SYS_DMA_INIT dmaInit; SYS_MODULE_OBJ usartModule1; SYS_MODULE_OBJ dmaModule; /* Set the baud to 300 */ usartInit.baud = 300; /* Auto Baud detection or Stop Idle is not needed */ usartInit.flags = DRV_USART_INIT_FLAG_NONE; /* Handshaking is not needed */ usartInit.handshake = DRV_USART_HANDSHAKE_NONE; /* USART Error Interrupt source for this USART * driver instance. Note that INT_SOURCE_USART_2_ERROR * value is defined by the Interrupt System Service and * is the error interrupt for USART2*/ usartInit.interruptError = INT_SOURCE_USART_2_ERROR; /* USART Receive Interrupt source for this USART * driver instance. Note that INT_SOURCE_USART_2_RECEIVE * value is defined by the Interrupt System Service and * is the receive interrupt for USART2 */ usartInit.interruptReceive = INT_SOURCE_USART_2_RECEIVE; /* USART Transmit Interrupt source for this USART * driver instance. Note that INT_SOURCE_USART_2_TRANSMIT * value is defined by the Interrupt System Service and * is the transmit interrupt for USART2 */ usartInit.interruptTransmit = INT_SOURCE_USART_2_TRANSMIT; /* Line control mode */ usartInit.lineControl = DRV_USART_LINE_CONTROL_8NONE1; /* Operation mode is normal. Loopback or addressed is not * needed */ usartInit.mode = DRV_USART_OPERATION_MODE_NORMAL; /* Peripheral Bus clock frequency at which the USART is * operating */ usartInit.brgClock = 80000000; /* System module power setting. Typically set to * SYS_MODULE_POWER_RUN_FULL */ usartInit.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; /* Receive buffer queue size. In this case a maximum of 2 * receive buffers can be queued. Only applicable if the * Buffer Queue Data Transfer Model is included in the * application. */ Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1300 usartInit.queueSizeReceive = 2; /* Transmit buffer queue size. In this case a maximum of 3 * transmit buffers can be queued. Only applicable if the * Buffer Queue Data Transfer Model is included in the * application. */ usartInit.queueSizeTransmit = 3; /* The USART peripheral instance index associated with this * driver instance. Note that this value is defined by the * USART Peripheral Library */ usartInit.usartID = USART_ID_2; /* Use DMA channel 1 for transmit. If transmit via DMA is * not required, set this to DMA_CHANNEL_NONE. These values * are defined by the DMA System Service. */ usartInit.dmaChannelTransmit = DMA_CHANNEL_1; /* Use DMA channel 2 for receive. If receive via DMA is * not required, set this to DMA_CHANNEL_NONE. These values * are defined by the DMA System Service. */ usartInit.dmaChannelReceive = DMA_CHANNEL_2; /* Set the interrupt source for the Transmit DMA channel. * This parameter is ignored if the dmaChannelTransmit * parameter is set to DMA_CHANNEL_NONE. */ usartInit.dmaInterruptTransmit = INT_SOURCE_DMA_1; /* Set the interrupt source for the Receive DMA channel. * This parameter is ignored if the dmaChannelReceive * parameter is set to DMA_CHANNEL_NONE. */ usartInit.dmaInterruptReceive = INT_SOURCE_DMA_2; /********* End of DRV_USART_INIT Initialization *************/ /* If the USART driver is configured for interrupt mode of * operation, the interrupt priorities should be configured. * Here the Interrupt System Service is used to set the * priority to level 4 */ /* Initialize the interrupt system service */ SYS_INT_Initialize(); /* Set the USART 2 module interrupt priority to 4*/ SYS_INT_VectorPrioritySet(INT_VECTOR_UART2, INT_PRIORITY_LEVEL4); /* Set the USART 2 module interrupt sub-priority to 0*/ SYS_INT_VectorSubprioritySet(INT_VECTOR_UART2, INT_SUBPRIORITY_LEVEL0); /* Set the DMA 1 channel interrupt priority to 4*/ SYS_INT_VectorPrioritySet(INT_VECTOR_DMA1, INT_PRIORITY_LEVEL4); /* Set the DMA 1 channel interrupt sub-priority to 0*/ SYS_INT_VectorSubprioritySet(INT_VECTOR_DMA1, INT_SUBPRIORITY_LEVEL0); /* Set the DMA 2 channel interrupt priority to 4*/ SYS_INT_VectorPrioritySet(INT_VECTOR_DMA2, INT_PRIORITY_LEVEL4); /* Set the DMA 2 channel interrupt sub-priority to 0*/ SYS_INT_VectorSubprioritySet(INT_VECTOR_DMA2, INT_SUBPRIORITY_LEVEL0); /* Enable global interrupt */ SYS_INT_Enable(); /* This is the DMA System Service Initialization */ dmaInit.sidl = SYS_DMA_SIDL_DISABLE; dmaModule = SYS_DMA_Initialize((SYS_MODULE_INIT*)&dmaInit); Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1301 /* The result of the DMA System Service initialization can be checked */ if(SYS_MODULE_OBJ_INVALID == dmaModule) { /* DMA System Service initialization was not successful */ } /* Initialize USART Driver Instance 0 */ usartModule1 = DRV_USART_Initialize(DRV_USART_0, (SYS_MODULE_INIT*)&usartInit); /* The result of the driver initialization can be checked */ if(SYS_MODULE_OBJ_INVALID == usartModule1) { /* There was an error in initialization. */ } Opening the USART Driver Describes how to open the USART Driver. Description To use the USART driver, the application must open the driver. This is done by calling the DRV_USART_Open function. Calling this function with DRV_IO_INTENT_NONBLOCKING will cause the driver to be opened in non blocking mode. The DRV_USART_Read and DRV_USART_Write functions when called by this client will be non blocking. . Calling this function with DRV_IO_INTENT_BLOCKING will cause the driver to be opened in blocking mode. The DRV_USART_Read and DRV_USART_Write functions when called by this client will be blocking. If successful, the DRV_USART_Open function will return a valid handle to the driver. This handle records the association between the client and the driver instance that was opened. The DRV_USART_Open function may return DRV_HANDLE_INVALID in the situation where the driver is not ready to be opened. When this occurs, the application can try opening the driver again. Note that the open function may return an invalid handle in other (error) cases as well. The following code shows an example of the driver being opened in different modes. DRV_HANDLE usartHandle1, usartHandle2; /* Client 1 opens the USART driver in non blocking mode */ usartHandle1 = DRV_USART_Open(DRV_USART_0, DRV_IO_INTENT_READWRITE|DRV_IO_INTENT_NONBLOCKING); /* Check if the handle is valid */ if(DRV_HANDLE_INVALID == usartHandle1) { /* The driver was not opened successfully. The client * can try opening it again */ } /* Client 2 opens the USART driver in blocking mode */ usartHandle2 = DRV_USART_Open(DRV_USART_0, DRV_IO_INTENT_READWRITE|DRV_IO_INTENT_BLOCKING); /* Check if the handle is valid */ if(DRV_HANDLE_INVALID == usartHandle2) { /* The driver was not opened successfully. The client * can try opening it again */ } /* The client can also open the USART driver in read only mode * (DRV_IO_INTENT_READ), write only mode (DRV_IO_INTENT_WRITE) * and exclusive mode (DRV_IO_INTENT_EXCLUSIVE). If the driver * has been opened exclusively by a client, it cannot be opened * again by another client */ Byte Transfer Model Describes the USART Driver byte transfer model. Description To use the byte transfer model, the DRV_USART_BYTE_MODEL_SUPPORT configuration macro should be true. The drv_usart_byte_model.c function should be included in the application project. The application cannot support the read/write and buffer queue data transfer model when the byte model is enabled. The following code shows an example of how the DRV_USART_WriteByte function and the DRV_USART_ReadByte function are used. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1302 /* Client uses the a byte model API to write a byte*/ if(!DRV_USART_TransmitBufferIsFull(usartHandle1)) { byte = '1'; DRV_USART_WriteByte(usartHandle1,byte); } /* Client waits until data is available and then reads * byte */ while(DRV_USART_ReceiverBufferIsEmpty(usartHandle1)); byte = DRV_USART_ReadByte(usartHandle1); File I/O Type Read/Write Data Transfer Model This topic describes the file I/O type read/write data transfer model. Description To use the file I/O type read/write data transfer model, the DRV_USART_READ_WRITE_MODEL_SUPPORT configuration macro should be 'true'. The file drv_usart_read_write.c file should be included in the application project. The driver can support the non-DMA buffer queue data transfer model along with the file I/O type read/write data transfer model. The byte transfer model and DMA buffer queue model cannot be enabled if the file I/O type read/write data transfer model is enabled. The DRV_USART_Read and DRV_USART_Write function represent the file I/O type read/write data transfer model. The functional behavior of these API is affected by the mode in which the client opened the driver. If the client opened the driver in blocking mode these API will block. In blocking mode, the DRV_USART_Read and DRV_USART_Write functions will not return until the requested number of bytes have been read or written. When operating in a RTOS application, the application thread that has opened driver in blocking mode, will enter a blocked state when it calls DRV_USART_Write or DRV_USART_Read function. This will allow the RTOS scheduler to schedule other threads which are ready to run. If the client opened the driver in non-blocking mode these API will not block. In non-blocking mode, the DRV_USART_Read and DRV_USART_Write functions will return immediately with the amount of data that could be read or written. Note: Do not open the driver in Blocking mode when the driver is configured for polling operation (DRV_USART_INTERRUPT_MODE is false) in a bare-metal (non-RTOS) application. This will cause the system to enter an infinite loop condition when the DRV_USART_Read or DRV_USART_Write function is called. The following code shows an example of file I/O type read/write data transfer model usage when the driver is opened in Blocking mode. /* This code shows the functionality of the DRV_USART_Write and * DRV_USART_Read function when the driver is opened in blocking mode */ DRV_HANDLE usartHandle1; uint8_t myData[10]; size_t bytesProcessed; /* The driver is opened in blocking mode */ usartHandle1 = DRV_USART_Open(DRV_USART_0, DRV_IO_INTENT_READWRITE|DRV_IO_INTENT_BLOCKING); /* Check if the driver was opened successfully */ if(DRV_HANDLE_INVALID == usartHandle1) { /* The driver could not be opened successfully */ } /* Transmit 10 bytes from the myData array. Function will not return until 10 bytes * have been accepted by the driver. This is because the client opened the driver * in blocking mode. */ bytesProcessed = DRV_USART_Write(usartHandle1, myData, 10); /* Read 10 bytes from the myData array. Function will not return until all 10 bytes * have been received by the driver. This is because the client opened the driver * in blocking mode. */ bytesProcessed = DRV_USART_Read(usartHandle1, myData, 10); In non-Blocking mode, the driver uses the internal USART hardware FIFO as storage. The DRV_USART_Read function checks if bytes are available in USART receive hardware FIFO. If bytes are available, these are read and the number of bytes read is returned. The DRV_USART_Write function checks if USART transmit hardware FIFO has empty location. If locations are empty, the bytes to be transmitted are queued up in the FIFO and the number of queued bytes is returned. In either case, the number of bytes read or written may be less than the number requested by the client. The client can, in such a case, call the DRV_USART_Read and/or the DRV_USART_Write functions again to process the pending bytes. The following code shows how this can be done. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1303 /* This code shows the functionality of the DRV_USART_Write and * DRV_USART_Read functions when the driver is opened in non-blocking mode */ DRV_HANDLE usartHandle1; uint8_t myData[10]; size_t bytesProcessed; /* The driver is opened in non-blocking mode */ usartHandle1 = DRV_USART_Open(DRV_USART_0, DRV_IO_INTENT_READWRITE|DRV_IO_INTENT_NONBLOCKING); /* Check if the driver was opened successfully */ if(DRV_HANDLE_INVALID == usartHandle1) { /* The driver could not be opened successfully */ } /* The following code call the DRV_USART_Write function * multiple times to write 10 bytes completely. Note how the * function return value is used to update the location of * user source data. */ bytesProcessed = 0; do { /* Write data to the USART and use the return value to * update the source data pointer and pending bytes number. */ bytesProcessed += DRV_USART_Write(usartHandle1, myData + bytesProcessed, (10 - bytesProcessed)); } while(bytesProcessed < 10); /* The following code calls the DRV_USART_Read function multiple times to read * 10 bytes completely. Note how the function return value is used to update the * location of user destination array. */ bytesProcessed = 0; do { /* Read data from the USART and use the return value to update the * destination pointer and pending bytes number. */ bytesProcessed += DRV_USART_Read(usartHandle1, myData + bytesProcessed, (10 - bytesProcessed)); }while (bytesProcessed < 10); Buffer Queue Transfer Model This topic describes the buffer queue data transfer model. Description To use the buffer queue data transfer model, the DRV_USART_BUFFER_QUEUE_SUPPORT configuration macro should be true. The file, drv_usart_buffer_queue.c, should be included in the application project. If the DMA-enabled buffer queue model is required, the drv_usart_buffer_queue_dma.c file (and not the drv_usart_buffer_queue.c ) should be included in the application project. The DMA and non-DMA buffer queue model API is the same. The driver can support the non-DMA buffer queue data transfer model along with the file I/O type read/write data transfer model. The byte transfer model cannot be enabled if the buffer queue data transfer model is enabled. The DRV_USART_BufferAddRead and DRV_USART_BufferAddWrite functions represent the buffer queue data transfer model. These functions are always non-blocking. The Buffer Queue Data Transfer Model employs queuing of read and write request. Each driver instance contains a read and write queue. The size of the read queue is determined by the queueSizeRead member of the DRV_USART_INIT data structure. The size of the write queue is determined by the queueSizeWrite member of the DRV_USART_INIT data structure. The driver provides driver events (DRV_USART_BUFFER_EVENT) that indicates termination of the buffer requests. When the driver is configured for Interrupt mode operation (that is defined and registered by the driver client), the buffer event handler executes in an interrupt context. Calling computationally intensive or hardware polling routines within the event handlers is not recommended. Calling interrupt unsafe functions in the event handler when the driver is configured for Interrupt mode could result in unpredictable system behavior. When the driver adds request to the queue, it returns a buffer handle. This unique handle allows the client to track the request as it progresses through the queue. The buffer handle is returned with the buffer event and expires when the event associated with the buffer has been generated and the event handler returns. The following code shows an example of using the buffer queue data transfer model. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1304 /* This code shows an example of using the * Buffer Queue Data Transfer Model. */ DRV_HANDLE usartHandle1; uint8_t myData1[10], myData2[10]; uint8_t myData3[10], myData4[10]; size_t bytesProcessed; DRV_USART_BUFFER_HANDLE bufferHandle1, bufferHandle2; DRV_USART_BUFFER_HANDLE bufferHandle3, bufferHandle4; /* The driver is opened in non blocking mode */ usartHandle1 = DRV_USART_Open(DRV_USART_0, DRV_IO_INTENT_READWRITE|DRV_IO_INTENT_NONBLOCKING); /* Check if the driver was opened successfully */ if(DRV_HANDLE_INVALID == usartHandle1) { /* The driver could not be opened successfully */ } /* Register a Buffer Event Handler with USART driver. * This event handler function will be called whenever * there is a buffer event. An application defined * context can also be specified. This is returned when * the event handler is called. * */ DRV_USART_BufferEventHandlerSet(usartHandle1, APP_USARTBufferEventHandler, NULL); /* Queue up two buffers for transmit */ DRV_USART_BufferAddWrite(usartHandle1, &bufferHandle1, myData1, 10); DRV_USART_BufferAddWrite(usartHandle1, &bufferHandle2, myData2, 10); /* Queue up two buffers for receive */ DRV_USART_BufferAddRead(usartHandle1, &bufferHandle3, myData3, 10); DRV_USART_BufferAddRead(usartHandle1, &bufferHandle4, myData4, 10); /* This is application USART Driver Buffer Event Handler */ void APP_USARTBufferEventHandler(DRV_USART_BUFFER_EVENT event, DRV_USART_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { switch(event) { case DRV_USART_BUFFER_EVENT_COMPLETE: /* This means the data was transferred */ break; case DRV_USART_BUFFER_EVENT_ERROR: /* Error handling here. */ break; default: break; } } Driver Tasks Routine This topic describes the Driver "Task" routines. Description The USART driver contains three task routines, DRV_USART_TasksTransmit, DRV_USART_TasksReceive and DRV_USART_TasksError. These task routines implement the USART Driver state machines for transmit, receive and error related operations. If the driver is configured for polling operation, the required task routine should be called in SYS_Tasks routine of the system. If the driver is configured for interrupt mode of operation, the task routine should be called from the ISR. The following code shows an example of both. /* The following code shows an example of * USART2 Interrupt Service Routine. This function * will be called when a USART2 interrupt occurs Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1305 * and the driver is configured for interrupt mode * operation */ void __ISR ( _UART_2_VECTOR,ipl4 ) _InterruptHandler_USART ( void ) { /* usartModule1 is the System Module Object * that was returned by the DRV_USART_Initialize * function. */ DRV_USART_TasksTransmit(usartModule1); DRV_USART_TasksReceive(usartModule1); DRV_USART_TasksError(usartModule1); } /* In case of Polled mode, the tasks routines are * invoked from the SYS_Tasks() routine. */ void SYS_Tasks(void) { DRV_USART_TasksTransmit(usartModule1); DRV_USART_TasksReceive(usartModule1); DRV_USART_TasksError(usartModule1); } /* The SYS_Tasks routine is invoked from the main * application while(1) loop. */ while(1) { SYS_Tasks(); } Using the USART Driver with DMA This topic provides information on using the USART Driver with DMA. Description To use the USART Driver with DMA, the following should be noted: • Include drv_usart_dma.c in the project. Do not include drv_usart.c. • Include drv_usart_buffer_queue_dma.c in the project. Do not include drv_usart_buffer_queue.c. • Initialize the driver to use DMA. Refer to Initializing the USART Driver for details. • Refer to the DMA System Service section for details on initializing and using the DMA system service in Polling or Interrupt mode • The DRV_USART_INTERRUPT_MODE configuration macro should be set to 'true' • Do not directly invoke the DRV_USART_TasksTransmit and DRV_USART_TasksReceive functions Configuring the Library Macros Name Description DRV_USART_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_USART_INDEX USART Static Index selection. DRV_USART_INTERRUPT_MODE Macro controls interrupt based operation of the driver. DRV_USART_INTERRUPT_SOURCE_ERROR Defines the error interrupt source for the static driver. DRV_USART_PERIPHERAL_ID Configures the USART PLIB Module ID. DRV_USART_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported. DRV_USART_BUFFER_QUEUE_SUPPORT Specifies if the Buffer Queue support should be enabled. DRV_USART_BYTE_MODEL_SUPPORT Specifies if the Byte Model support should be enabled. DRV_USART_INTERRUPT_SOURCE_RECEIVE Defines the Receive interrupt source for the static driver. DRV_USART_INTERRUPT_SOURCE_RECEIVE_DMA Defines the Receive DMA Channel interrupt source for the static driver. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1306 DRV_USART_INTERRUPT_SOURCE_TRANSMIT Defines the Transmit interrupt source for the static driver. DRV_USART_INTERRUPT_SOURCE_TRANSMIT_DMA Defines the Transmit DMA Channel interrupt source for the static driver. DRV_USART_QUEUE_DEPTH_COMBINED Defines the number of entries of all queues in all instances of the driver. DRV_USART_READ_WRITE_MODEL_SUPPORT Specifies if Read/Write Model support should be enabled. DRV_USART_RECEIVE_DMA Defines the USART Driver Receive DMA Channel for the static driver. DRV_USART_TRANSMIT_DMA Defines the USART Driver Transmit DMA Channel in case of static driver. DRV_USART_BAUD_RATE_IDXn Specifies the USART Baud at which the USART driver is initialized. DRV_USART_BYTE_MODEL_BLOCKING Enables or Disables DRV_USART_ByteWrite function blocking behavior. DRV_USART_BYTE_MODEL_CALLBACK Enables or Disables Callback Feature of the Byte Transfer Model. DRV_USART_RCV_QUEUE_SIZE_IDXn Sets the USART Driver Receive Queue Size while using the Buffer Queue Data Transfer Model. DRV_USART_XMIT_QUEUE_SIZE_IDXn Sets the USART Driver Transmit Queue Size while using the Buffer Queue Data Transfer Model. Description The USART Driver requires the specification of compile-time configuration macros. These macros define resource usage, feature availability, and dynamic behavior of the driver. These configuration macros should be defined in the system_config.h file. This header can be placed anywhere in the application specific folders and the path of this header needs to be presented to the include search for a successful build. Refer to the Applications Help section for more details. Note: Initialization overrides are not supported in this version. /* In this configuration example, the USART driver * must manage only on USART peripheral instance. * This macro can be greater than one if more * USART peripherals are needed. Not defining this * macro will cause the driver to be built in * static mode */ #define DRV_USART_INSTANCES_NUMBER 1 /* There will be 3 different client that use the * one instance of the USART peripheral. Note that * this macro configures the total (combined) number of clients * across all instance of the USART driver. Not defining * this macro will cause the driver to be configured * for single client operation */ #define DRV_USART_CLIENTS_NUMBER 3 /* USART Driver should be built for interrupt mode. * Set this to false for Polled mode operation */ #define DRV_USART_INTERRUPT_MODE true /* Combined buffer queue depth is 5. Refer to the * description of the Buffer Queue data transfer model * and the DRV_USART_QUEUE_DEPTH_COMBINED macro * for more details on how this is configured. */ #define DRV_USART_QUEUE_DEPTH_COMBINED 5 /* Set this macro to true is Buffer Queue data * transfer model is to be enabled. */ #define DRV_USART_BUFFER_QUEUE_SUPPORT true /* Set this macro to true if Byte by Byte data * transfer model is to be enabled. */ #define DRV_USART_BYTE_MODEL_SUPPORT false /* Set this macro to true File IO type Read Write * data transfer model is to be enabled */ #define DRV_USART_READ_WRITE_MODEL_SUPPORT false Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1307 DRV_USART_CLIENTS_NUMBER Macro Sets up the maximum number of clients that can be connected to any hardware instance. File drv_usart_config_template.h C #define DRV_USART_CLIENTS_NUMBER 4 Description USART Client Count Configuration This macro sets up the maximum number of clients that can be connected to any hardware instance. This value represents the total number of clients to be supported across all hardware instances. Therefore, if USART1 will be accessed by two clients and USART2 will accessed by three clients, this number should be 5. It is recommended that this value be set exactly equal to the number of expected clients, as client support consumes RAM memory space. If this macro is not defined and the DRV_USART_INSTANCES_NUMBER macro is not defined, the driver will be built for static - single client operation. If this macro is defined and the DRV_USART_INSTANCES_NUMBER macro is not defined, the driver will be built for static - multi client operation. Remarks None. DRV_USART_INDEX Macro USART Static Index selection. File drv_usart_config_template.h C #define DRV_USART_INDEX DRV_USART_INDEX_2 Description Index - Used for static drivers USART Static Index selection for the driver object reference. This macro defines the driver index for static and static multi-client builds. For example, if this macro is set to DRV_USART_INDEX_2, the static driver APIs would be DRV_USART2_Initialize, DRV_USART2_Open, etc. When building static drivers, this macro should be different for each static build of the USART driver that needs to be included in the project. Remarks This index is required to make a reference to the driver object DRV_USART_INTERRUPT_MODE Macro Macro controls interrupt based operation of the driver. File drv_usart_config_template.h C #define DRV_USART_INTERRUPT_MODE true Description USART Interrupt Mode Operation Control This macro controls the interrupt based operation of the driver. The possible values are: • true - Enables the interrupt mode • false - Enables the polling mode If the macro value is true, the Interrupt Service Routine (ISR) for the interrupt should be defined in the system. The DRV_USART_Tasks routine should be called in the ISR. While using the USART driver with DMA, this flag should always be true. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1308 DRV_USART_INTERRUPT_SOURCE_ERROR Macro Defines the error interrupt source for the static driver. File drv_usart_config_template.h C #define DRV_USART_INTERRUPT_SOURCE_ERROR INT_SOURCE_USART_2_ERROR Description Error Interrupt Source This macro defines the Error interrupt source for the static driver. The interrupt source defined by this macro will override the errorInterruptSource member of the DRV_USB_INIT initialization data structure in the driver initialization routine. This value should be set to the USART module error interrupt enumeration in the Interrupt PLIB for the microcontroller. Remarks None. DRV_USART_PERIPHERAL_ID Macro Configures the USART PLIB Module ID. File drv_usart_config_template.h C #define DRV_USART_PERIPHERAL_ID USART_ID_2 Description USART Peripheral Library Module ID This macro configures the PLIB ID if the driver is built statically. This value will override the usartID member of the DRV_USART_INIT initialization data structure. In that when the driver is built statically, the usartID member of the DRV_USART_INIT data structure will be ignored by the driver initialization routine and this macro will be considered. This should be set to the PLIB ID of USART module (USART_ID_1, USART_ID_2, and so on). Remarks None. DRV_USART_INSTANCES_NUMBER Macro Sets up the maximum number of hardware instances that can be supported. File drv_usart_config_template.h C #define DRV_USART_INSTANCES_NUMBER 2 Description USART driver objects configuration This macro sets up the maximum number of hardware instances that can be supported. It is recommended that this number be set exactly equal to the number of USART modules that are needed by the application, as hardware Instance support consumes RAM memory space. If this macro is not defined, the driver will be built statically. Remarks None DRV_USART_BUFFER_QUEUE_SUPPORT Macro Specifies if the Buffer Queue support should be enabled. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1309 File drv_usart_config_template.h C #define DRV_USART_BUFFER_QUEUE_SUPPORT true Description USART Driver Buffer Queue Support This macro defines whether or not Buffer Queue support should be enabled. Setting this macro to true will enable buffer queue support and all buffer related driver function. The driver should be built along with the drv_usart_buffer_queue.c file, which contains the functional implementation for buffer queues. If buffer queue operation is enabled, the DRV_USART_BYTE_MODEL_SUPPORT function should not be true. If this macro is set to false, the behavior of the USART Driver Buffer Queue API is not defined. While using the USART driver with DMA, the driver supports Buffer Queue Data transfer model regardless of the value of this configuration macro. Remarks None. DRV_USART_BYTE_MODEL_SUPPORT Macro Specifies if the Byte Model support should be enabled. File drv_usart_config_template.h C #define DRV_USART_BYTE_MODEL_SUPPORT false Description USART Driver Byte Model Support This macro defines whether or Byte Model support should be enabled. Setting this macro to true will enable byte model support and all byte operation related driver functions. The driver should be built along with the drv_usart_byte_model.c file, which contains the functional implementation for byte model operation. If byte model operation is enabled, the driver will not support buffer queue and read write models. The behavior of the byte mode API when this macro is set to false is not defined. Remarks None. DRV_USART_INTERRUPT_SOURCE_RECEIVE Macro Defines the Receive interrupt source for the static driver. File drv_usart_config_template.h C #define DRV_USART_INTERRUPT_SOURCE_RECEIVE INT_SOURCE_USART_2_RECEIVE Description Receive Interrupt Source This macro defines the Receive interrupt source for the static driver. The interrupt source defined by this macro will override the rxInterruptSource member of the DRV_USB_INIT initialization data structure in the driver initialization routine. This value should be set to the USART module receive interrupt enumeration in the Interrupt PLIB for the microcontroller. Remarks None. DRV_USART_INTERRUPT_SOURCE_RECEIVE_DMA Macro Defines the Receive DMA Channel interrupt source for the static driver. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1310 File drv_usart_config_template.h C #define DRV_USART_INTERRUPT_SOURCE_RECEIVE_DMA Description Receive DMA Channel Interrupt Source This macro defines the Receive DMA Channel interrupt source for the static driver. The interrupt source defined by this macro will override the dmaInterruptReceive member of the DRV_USB_INIT initialization data structure in the driver initialization routine. This value should be set to the DMA channel interrupt enumeration in the Interrupt PLIB for the microcontroller. Remarks None. DRV_USART_INTERRUPT_SOURCE_TRANSMIT Macro Defines the Transmit interrupt source for the static driver. File drv_usart_config_template.h C #define DRV_USART_INTERRUPT_SOURCE_TRANSMIT INT_SOURCE_USART_2_TRANSMIT Description Transmit Interrupt Source This macro defines the TX interrupt source for the static driver. The interrupt source defined by this macro will override the txInterruptSource member of the DRV_USB_INIT initialization data structure in the driver initialization routine. This value should be set to the USART module transmit interrupt enumeration in the Interrupt PLIB for the microcontroller. Remarks None. DRV_USART_INTERRUPT_SOURCE_TRANSMIT_DMA Macro Defines the Transmit DMA Channel interrupt source for the static driver. File drv_usart_config_template.h C #define DRV_USART_INTERRUPT_SOURCE_TRANSMIT_DMA Description Transmit DMA Channel Interrupt Source This macro defines the TX DMA Channel interrupt source for the static driver. The interrupt source defined by this macro will override the dmaInterruptTransmit member of the DRV_USB_INIT initialization data structure in the driver initialization routine. This value should be set to the DMA channel interrupt enumeration in the Interrupt PLIB for the microcontroller. Remarks None. DRV_USART_QUEUE_DEPTH_COMBINED Macro Defines the number of entries of all queues in all instances of the driver. File drv_usart_config_template.h Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1311 C #define DRV_USART_QUEUE_DEPTH_COMBINED 16 Description USART Driver Instance combined queue depth. This macro defines the number of entries of all queues in all instances of the driver. Each hardware instance supports a buffer queue for transmit and receive operations. The size of queue is specified either in driver initialization (for dynamic build) or by macros (for static build). The hardware instance transmit buffer queue will queue transmit buffers submitted by the DRV_USART_BufferAddWrite function. The hardware instance receive buffer queue will queue receive buffers submitted by the DRV_USART_BufferAddRead function. A buffer queue will contain buffer queue entries, with each related to a BufferAdd request. This configuration macro defines the total number of buffer entries that will be available for use between all USART driver hardware instances. The buffer queue entries are allocated to individual hardware instances as requested by hardware instances. Once the request is processed, the buffer queue entry is free for use by other hardware instances. The total number of buffer entries in the system determines the ability of the driver to service non blocking read and write requests. If a free buffer entry is not available, the driver will not add the request and will return an invalid buffer handle. The greater the number of buffer entries, the greater the ability of the driver to service and add requests to its queue. A hardware instance additionally can queue up as many buffer entries as specified by its transmit and receive buffer queue size. For example, consider the case of static single client driver application where full duplex non blocking operation is desired without queuing, the minimum transmit queue depth and minimum receive queue depth should be 1. Therefore, the total number of buffer entries should be 2. As another example, consider the case of a dynamic driver (i.e., two instances) where instance 1 will queue up to three write requests and up to two read requests, and instance 2 will queue up to two write requests and up to six read requests, the value of this macro should be: 13 (2 + 3 + 2 + 6). Remarks None. DRV_USART_READ_WRITE_MODEL_SUPPORT Macro Specifies if Read/Write Model support should be enabled. File drv_usart_config_template.h C #define DRV_USART_READ_WRITE_MODEL_SUPPORT true Description USART Driver Read Write Model Support This macro defines whether or not Read Write Model support should be enabled. Setting this macro to true will enable read write model support and all read/write related driver functions. The driver should be built along with the drv_usart_read_write.c file, which contains the functional implementation for byte model operation. If read/write model operation is enabled, the DRV_USART_BYTE_MODEL_SUPPORT macro should not be true. The behavior of the Read Write Model API when this macro is set to false is not defined. Remarks None. DRV_USART_RECEIVE_DMA Macro Defines the USART Driver Receive DMA Channel for the static driver. File drv_usart_config_template.h C #define DRV_USART_RECEIVE_DMA Description USART Driver Receive DMA Channel This macro defines the USART Receive DMA Channel for the static driver. The DMA channel defined by this macro will override the dmaReceive member of the DRV_USB_INIT initialization data structure in the driver initialization routine. This value should be set to the DMA channel in the Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1312 DMA PLIB for the microcontroller. Remarks None. DRV_USART_TRANSMIT_DMA Macro Defines the USART Driver Transmit DMA Channel in case of static driver. File drv_usart_config_template.h C #define DRV_USART_TRANSMIT_DMA Description USART Driver Transmit DMA Channel This macro defines the USART Transmit DMA Channel for the static driver. The DMA channel defined by this macro will override the dmaTransmit member of the DRV_USB_INIT initialization data structure in the driver initialization routine. This value should be set to the DMA channel in the DMA PLIB for the microcontroller. Remarks None. DRV_USART_BAUD_RATE_IDXn Macro Specifies the USART Baud at which the USART driver is initialized. File drv_usart_config_template.h C #define DRV_USART_BAUD_RATE_IDXn Description USART Driver Baud Selection. This configuration constant specifies the baud rate at which the USART Driver is initialized. This is the baud rate at which the USART module will operate when the driver initialization has completed. The driver client can call the DRV_USART_BaudSet function after opening the driver to change the USART baud rate after initialization has completed. Remarks This constant is automatically generated by MHC and its value is set to the value specified in USART Driver Baud Selection field. DRV_USART_BYTE_MODEL_BLOCKING Macro Enables or Disables DRV_USART_ByteWrite function blocking behavior. File drv_usart_config_template.h C #define DRV_USART_BYTE_MODEL_BLOCKING Description USART Driver Byte Write Blocking Behavior This USART Driver MHC option controls the blocking behavior of the DRV_USART_ByteWrite function and is only applicable when the USART Driver Byte Transfer model is selected. Selecting this option will cause the DRV_USART_ByteWrite function to block until the byte has been written to the USART Transmit FIFO. Blocking behavior is enabled by default (to enable backward compatibility with previous versions of the driver). This option can be used for simple applications where interoperability with other MPLAB Harmony modules is not a design concern. If the application uses several other MPLAB Harmony modules (Middleware, File System, etc.), it is recommended to disable this option and use the non-blocking DRV_USART_ByteWrite function. This requires the application to call the DRV_USART_TransmitBufferIsFull function to check if the byte can be written to the USART, as shown in the following code example. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1313 if(!DRV_USART_TransmitBufferIsFull(usartHandle1)) { byte = '1'; DRV_USART_WriteByte(usartHandle1,byte); } Using the non-blocking implementation results in improved application interoperability with other MPLAB Harmony modules. Remarks The DRV_USART_BYTE_MODEL_BLOCKING constant is specified for documentation purposes only. It does not affect the configuration of the driver. DRV_USART_BYTE_MODEL_CALLBACK Macro Enables or Disables Callback Feature of the Byte Transfer Model. File drv_usart_config_template.h C #define DRV_USART_BYTE_MODEL_CALLBACK Description USART Driver Byte Model Callback Feature. This USART Driver MHC option controls the Callback feature of the Byte Transfer model. Selecting this option allows an application to register Byte Transfer Event Callback functions with the driver. These callback functions are invoked on the occurrence of Byte Transfer events. Callback functions can be registered to Byte Transmit, Byte Receive, and USART Error events, as shown in the following code example. // This code shows how a callback function is // registered for the Byte Receive event. DRV_USART_ByteReceiveCallbackSet(DRV_USART_INDEX_0, APP_USARTReceiveEventHandler); // Event Processing Technique. Event is received when // a byte is received. void APP_USARTReceiveEventHandler(const SYS_MODULE_INDEX index) { // Byte has been Received. Handle the event. // Read byte using DRV_USART_ReadByte. } When operating in Interrupt mode, the callback functions are invoked in an interrupt context. If this option is not selected, the application must use the DRV_USART_TransmitBufferIsFull, DRV_USART_ReceiverBufferIsEmpty, and DRV_USART_ErrorGet functions to check the status of Byte transmit or receive. Remarks The DRV_USART_BYTE_MODEL_CALLBACK constant is specified for documentation purposes only. It does not affect the configuration of the driver. DRV_USART_RCV_QUEUE_SIZE_IDXn Macro Sets the USART Driver Receive Queue Size while using the Buffer Queue Data Transfer Model. File drv_usart_config_template.h C #define DRV_USART_RCV_QUEUE_SIZE_IDXn Description USART Driver Receive Queue Size Selection. This constant sets the USART Driver Receive queue size when using the Buffer Queue Data Transfer Model. It affects the queuing capacity of the DRV_USART_BufferAddRead function for the selected driver instance. For example, if this option is set to 5 for USART Driver 0, USART Driver 0 can then queue up to a maximum of five driver client receive buffer requests from any driver clients. Therefore, if USART Driver 0 has two clients and if client 1 has queued up three buffers for receive, client 2 can only queue up to two buffers. If the client attempts to queue up more buffers, DRV_USART_BufferAddRead will not accept the request and will generate an invalid buffer handle (DRV_USART_BUFFER_HANDLE_INVALID). Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1314 Remarks This constant is automatically generated by MHC and its value is set to the value specified in USART Driver Receive Queue Size field. DRV_USART_XMIT_QUEUE_SIZE_IDXn Macro Sets the USART Driver Transmit Queue Size while using the Buffer Queue Data Transfer Model. File drv_usart_config_template.h C #define DRV_USART_XMIT_QUEUE_SIZE_IDXn Description USART Driver Transmit Queue Size Selection. This constant sets the USART Driver Transmit queue size when using the Buffer Queue Data Transfer Model. It affects the queuing capacity of the DRV_USART_BufferAddWrite function, for the selected driver instance. For example, if this option is set to 5 for USART Driver 0, USART Driver 0 can then queue up to a maximum of five driver client transmit buffer requests from any driver clients. Therefore if USART Driver 0 has two clients and if client 1 has queued up three buffers for transmit, client 2 can only queue up to two buffers. If the client attempts to queue up more buffers, DRV_USART_BufferAddWrite will not accept the request and will generate an invalid buffer handle (DRV_USART_BUFFER_HANDLE_INVALID). Remarks This constant is automatically generated by MHC and its value is set to the value specified in USART Driver Transmit Queue Size field. Building the Library This section lists the files that are available in the USART Driver Library. Description This section list the files that are available in the \src folder of the USART 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. 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 /framework/driver/usart. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description /drv_usart.h This file should be included by any .c file which accesses the USART Driver API. This one file contains the prototypes for all driver API. 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 /src/dynamic/drv_usart.c This file should always be included in the project when using the USART Driver. /src/dynamic/drv_usart_dma.c This file should always be included in the project when using the USART driver with DMA. 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 /src/dynamic/drv_usart_byte_model.c This file should be included in the project if the USART Driver Byte Model API is required. /src/dynamic/drv_usart_buffer_queue.c This file should be included in the project if the USART Driver Buffer Queue Model API (without DMA) is required. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1315 /src/dynamic/drv_usart_read_write.c This file should be included in the project if the USART Driver Read Write Model API is required. /src/dynamic/drv_usart_buffer_queue_dma.c This file should be included in the project if the USART Driver Buffer Queue Model API with DMA is required. Module Dependencies The USART Driver Library depends on the following modules: • Interrupt System Service Library • DMA System Service Library (if USART Driver is configured to use DMA) Library Interface a) System Functions Name Description DRV_USART_Initialize Initializes the USART instance for the specified driver index. Implementation: Static/Dynamic DRV_USART_Deinitialize Deinitializes the specified instance of the USART driver module. Implementation: Static/Dynamic DRV_USART_Status Gets the current status of the USART driver module. Implementation: Static/Dynamic DRV_USART_TasksReceive Maintains the driver's receive state machine and implements its ISR. Implementation: Static/Dynamic DRV_USART_TasksTransmit Maintains the driver's transmit state machine and implements its ISR. Implementation: Static/Dynamic DRV_USART_TasksError Maintains the driver's error state machine and implements its ISR. Implementation: Static/Dynamic b) Core Client Functions Name Description DRV_USART_Open Opens the specified USART driver instance and returns a handle to it. Implementation: Static/Dynamic DRV_USART_Close Closes an opened-instance of the USART driver. Implementation: Static/Dynamic DRV_USART_ClientStatus Gets the current client-specific status the USART driver. Implementation: Static/Dynamic DRV_USART_ErrorGet This function returns the error(if any) associated with the last client request. Implementation: Static/Dynamic c) Communication Management Client Functions Name Description DRV_USART_BaudSet This function changes the USART module baud to the specified value. Implementation: Static/Dynamic DRV_USART_LineControlSet This function changes the USART module line control to the specified value. Implementation: Static/Dynamic d) Buffer Queue Read/Write Client Functions Name Description DRV_USART_BufferAddRead Schedule a non-blocking driver read operation. Implementation: Static/Dynamic DRV_USART_BufferAddWrite Schedule a non-blocking driver write operation. Implementation: Static/Dynamic DRV_USART_BufferEventHandlerSet Allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. Implementation: Static/Dynamic DRV_USART_BufferProcessedSizeGet This API will be deprecated and not recommended to use. Use DRV_USART_BufferCompletedBytesGet to get the number of bytes processed for the specified buffer. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1316 DRV_USART_AddressedBufferAddWrite Schedule a non-blocking addressed driver write operation. Implementation: Dynamic DRV_USART_BufferCompletedBytesGet Returns the number of bytes that have been processed for the specified buffer. Implementation: Static/Dynamic DRV_USART_BufferRemove Removes a requested buffer from the queue. Implementation: Static/Dynamic e) File I/O Type Read/Write Functions Name Description DRV_USART_Read Reads data from the USART. Implementation: Static/Dynamic DRV_USART_Write Writes data to the USART. Implementation: Static/Dynamic f) Byte Transfer Functions Name Description DRV_USART_ReadByte Reads a byte of data from the USART. Implementation: Static/Dynamic DRV_USART_WriteByte Writes a byte of data to the USART. Implementation: Static/Dynamic DRV_USART_TransmitBufferSizeGet Returns the size of the transmit buffer. Implementation: Static/Dynamic DRV_USART_ReceiverBufferSizeGet Returns the size of the receive buffer. Implementation: Static/Dynamic DRV_USART_TransferStatus Returns the transmitter and receiver transfer status. Implementation: Static/Dynamic DRV_USART_TransmitBufferIsFull Provides the status of the driver's transmit buffer. Implementation: Static/Dynamic DRV_USART_ReceiverBufferIsEmpty Provides the status of the driver's receive buffer. Implementation: Static/Dynamic DRV_USART_ByteErrorCallbackSet Registers callback to handle for byte error events. DRV_USART_ByteReceiveCallbackSet Registers receive callback function for byte receive event. DRV_USART_ByteTransmitCallbackSet Registers a callback function for byte transmit event. Description This section describes the functions of the USART Driver Library. Refer to each section for a detailed description. a) System Functions DRV_USART_Initialize Function Initializes the USART instance for the specified driver index. Implementation: Static/Dynamic File drv_usart.h C SYS_MODULE_OBJ DRV_USART_Initialize(const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init); Returns If successful, returns a valid handle to a driver instance object. Otherwise, returns SYS_MODULE_OBJ_INVALID. Description This routine initializes the USART driver instance for the specified driver index, making it ready for clients to open and use it. The initialization data is specified by the init parameter. The initialization may fail if the number of driver objects allocated are insufficient or if the specified driver instance is already initialized. The driver instance index is independent of the USART module ID. For example, driver instance 0 can be assigned to Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1317 USART2. If the driver is built statically, then some of the initialization parameters are overridden by configuration macros. Refer to the description of the DRV_USART_INIT data structure for more details on which members on this data structure are overridden. Remarks This routine must be called before any other USART routine is called. This routine should only be called once during system initialization unless DRV_USART_Deinitialize is called to deinitialize the driver instance. This routine will NEVER block for hardware access. Preconditions None. Example // The following code snippet shows an example USART driver initialization. // The driver is initialized for normal mode and a baud of 300. The // receive queue size is set to 2 and transmit queue size is set to 3. DRV_USART_INIT usartInit; SYS_MODULE_OBJ objectHandle; usartInit.baud = 300; usartInit.mode = DRV_USART_OPERATION_MODE_NORMAL; usartInit.flags = DRV_USART_INIT_FLAG_NONE; usartInit.usartID = USART_ID_2; usartInit.brgClock = 80000000; usartInit.handshake = DRV_USART_HANDSHAKE_NONE; usartInit.lineControl = DRV_USART_LINE_CONTROL_8NONE1; usartInit.interruptError = INT_SOURCE_USART_2_ERROR; usartInit.interruptReceive = INT_SOURCE_USART_2_RECEIVE; usartInit.queueSizeReceive = 2; usartInit.queueSizeTransmit = 3; usartInit.interruptTransmit = INT_SOURCE_USART_2_TRANSMIT; usartInit.moduleInit.value = SYS_MODULE_POWER_RUN_FULL; objectHandle = DRV_USART_Initialize(DRV_USART_INDEX_1, (SYS_MODULE_INIT*)&usartInitData); if (SYS_MODULE_OBJ_INVALID == objectHandle) { // Handle error } Parameters Parameters Description index Identifier for the instance to be initialized init Pointer to a data structure containing any data necessary to initialize the driver. Function SYS_MODULE_OBJ DRV_USART_Initialize ( const SYS_MODULE_INDEX index, const SYS_MODULE_INIT * const init ) DRV_USART_Deinitialize Function Deinitializes the specified instance of the USART driver module. Implementation: Static/Dynamic File drv_usart.h C void DRV_USART_Deinitialize(SYS_MODULE_OBJ object); Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1318 Returns None. Description Deinitializes the specified instance of the USART driver module, disabling its operation (and any hardware). Invalidates all the internal data. Remarks Once the Initialize operation has been called, the Deinitialize operation must be called before the Initialize operation can be called again. This routine will NEVER block waiting for hardware. Preconditions Function DRV_USART_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_USART_Initialize SYS_STATUS status; DRV_USART_Deinitialize(object); status = DRV_USART_Status(object); if (SYS_MODULE_DEINITIALIZED != status) { // Check again later if you need to know // when the driver is deinitialized. } Parameters Parameters Description object Driver object handle, returned from the DRV_USART_Initialize routine Function void DRV_USART_Deinitialize( SYS_MODULE_OBJ object ) DRV_USART_Status Function Gets the current status of the USART driver module. Implementation: Static/Dynamic File drv_usart.h C SYS_STATUS DRV_USART_Status(SYS_MODULE_OBJ object); Returns SYS_STATUS_READY - Indicates that the driver is busy with a previous system level operation and cannot start another SYS_STATUS_DEINITIALIZED - Indicates that the driver has been deinitialized Description This routine provides the current status of the USART driver module. Remarks A driver can opened only when its status is SYS_STATUS_READY. Preconditions Function DRV_USART_Initialize should have been called before calling this function. Example SYS_MODULE_OBJ object; // Returned from DRV_USART_Initialize SYS_STATUS usartStatus; usartStatus = DRV_USART _Status(object); Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1319 if (SYS_STATUS_READY == usartStatus) { // This means the driver can be opened using the // DRV_USART_Open() function. } Parameters Parameters Description object Driver object handle, returned from the DRV_USART_Initialize routine Function SYS_STATUS DRV_USART_Status( SYS_MODULE_OBJ object ) DRV_USART_TasksReceive Function Maintains the driver's receive state machine and implements its ISR. Implementation: Static/Dynamic File drv_usart.h C void DRV_USART_TasksReceive(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal receive state machine and implement its receive ISR for interrupt-driven implementations. In polling mode, this function should be called from the SYS_Tasks function. In interrupt mode, this function should be called in the receive interrupt service routine of the USART that is associated with this USART driver hardware instance. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the appropriate raw ISR. This routine may execute in an ISR context and will never block or access any resources that may cause it to block. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_USART_Initialize while (true) { DRV_USART_TasksReceive (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_USART_Initialize) Function void DRV_USART_TasksReceive (SYS_MODULE_OBJ object ); DRV_USART_TasksTransmit Function Maintains the driver's transmit state machine and implements its ISR. Implementation: Static/Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1320 File drv_usart.h C void DRV_USART_TasksTransmit(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal transmit state machine and implement its transmit ISR for interrupt-driven implementations. In polling mode, this function should be called from the SYS_Tasks function. In interrupt mode, this function should be called in the transmit interrupt service routine of the USART that is associated with this USART driver hardware instance. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the appropriate raw ISR. This routine may execute in an ISR context and will never block or access any resources that may cause it to block. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_USART_Initialize while (true) { DRV_USART_TasksTransmit (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_USART_Initialize) Function void DRV_USART_TasksTransmit (SYS_MODULE_OBJ object ); DRV_USART_TasksError Function Maintains the driver's error state machine and implements its ISR. Implementation: Static/Dynamic File drv_usart.h C void DRV_USART_TasksError(SYS_MODULE_OBJ object); Returns None. Description This routine is used to maintain the driver's internal error state machine and implement its error ISR for interrupt-driven implementations. In polling mode, this function should be called from the SYS_Tasks function. In interrupt mode, this function should be called in the error interrupt service routine of the USART that is associated with this USART driver hardware instance. Remarks This routine is normally not called directly by an application. It is called by the system's Tasks routine (SYS_Tasks) or by the appropriate raw ISR. This routine may execute in an ISR context and will never block or access any resources that may cause it to block. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1321 Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. Example SYS_MODULE_OBJ object; // Returned from DRV_USART_Initialize while (true) { DRV_USART_TasksError (object); // Do other tasks } Parameters Parameters Description object Object handle for the specified driver instance (returned from DRV_USART_Initialize) Function void DRV_USART_TasksError (SYS_MODULE_OBJ object ); b) Core Client Functions DRV_USART_Open Function Opens the specified USART driver instance and returns a handle to it. Implementation: Static/Dynamic File drv_usart.h C DRV_HANDLE DRV_USART_Open(const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent); Returns If successful, the routine returns a valid open-instance handle (a number identifying both the caller and the module instance). If an error occurs, the return value is DRV_HANDLE_INVALID. Error can occur • if the number of client objects allocated via DRV_USART_CLIENTS_NUMBER is insufficient. • if the client is trying to open the driver but driver has been opened exclusively by another client. • if the driver hardware instance being opened is not initialized or is invalid. • if the client is trying to open the driver exclusively, but has already been opened in a non exclusive mode by another client. • if the driver is not ready to be opened, typically when the initialize routine has not completed execution. Description This routine opens the specified USART driver instance and provides a handle that must be provided to all other client-level operations to identify the caller and the instance of the driver. The ioIntent parameter defines how the client interacts with this driver instance. The DRV_IO_INTENT_BLOCKING and DRV_IO_INTENT_NONBLOCKING ioIntent options additionally affect the behavior of the DRV_USART_Read and DRV_USART_Write functions. If the ioIntent is DRV_IO_INTENT_NONBLOCKING, then these function will not block even if the required amount of data could not be processed. If the ioIntent is DRV_IO_INTENT_BLOCKING, these functions will block until the required amount of data is processed. If the driver is configured for polling and bare-metal operation, it will not support DRV_IO_INTENT_BLOCKING. The driver will operation will always be non-blocking. If ioIntent is DRV_IO_INTENT_READ, the client will only be able to read from the driver. If ioIntent is DRV_IO_INTENT_WRITE, the client will only be able to write to the driver. If the ioIntent is DRV_IO_INTENT_READWRITE, the client will be able to do both, read and write. Specifying a DRV_IO_INTENT_EXCLUSIVE will cause the driver to provide exclusive access to this client. The driver cannot be opened by any other client. Remarks The handle returned is valid until the DRV_USART_Close routine is called. This routine will NEVER block waiting for hardware.If the requested intent flags are not supported, the routine will return DRV_HANDLE_INVALID. This function is thread safe in a RTOS application. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1322 Preconditions Function DRV_USART_Initialize must have been called before calling this function. Example DRV_HANDLE handle; handle = DRV_USART_Open(DRV_USART_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); if (DRV_HANDLE_INVALID == handle) { // Unable to open the driver // May be the driver is not initialized or the initialization // is not complete. } Parameters Parameters Description index Identifier for the object instance to be opened intent Zero or more of the values from the enumeration DRV_IO_INTENT "ORed" together to indicate the intended use of the driver. See function description for details. Function DRV_HANDLE DRV_USART_Open ( const SYS_MODULE_INDEX index, const DRV_IO_INTENT ioIntent ) DRV_USART_Close Function Closes an opened-instance of the USART driver. Implementation: Static/Dynamic File drv_usart.h C void DRV_USART_Close(const DRV_HANDLE handle); Returns None. Description This routine closes an opened-instance of the USART driver, invalidating the handle. Any buffers in the driver queue that were submitted by this client will be removed. After calling this routine, the handle passed in "handle" must not be used with any of the remaining driver routines (with one possible exception described in the "Remarks" section). A new handle must be obtained by calling DRV_USART_Open before the caller may use the driver again Remarks Usually there is no need for the client to verify that the Close operation has completed. The driver will abort any ongoing operations when this routine is called. However, if it requires additional time to do so in a non-blocking environment, it will still return from the Close operation but the handle is now a zombie handle. The client can only call the DRV_USART_ClientStatus on a zombie handle to track the completion of the Close operation. The DRV_USART_ClientStatus routine will return DRV_CLIENT_STATUS_CLOSED when the close operation has completed. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_USART_Open DRV_USART_Close(handle); Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1323 // After this point, the handle cannot be used with any other function // except the DRV_USART_ClientStatus function, which can be used to query // the success status of the DRV_USART_Close function. while(DRV_USART_CLIENT_STATUS_CLOSED != DRV_USART_ClientStatus(handle)); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function void DRV_USART_Close( DRV_Handle handle ) DRV_USART_ClientStatus Function Gets the current client-specific status the USART driver. Implementation: Static/Dynamic File drv_usart.h C DRV_USART_CLIENT_STATUS DRV_USART_ClientStatus(DRV_HANDLE handle); Returns A DRV_USART_CLIENT_STATUS value describing the current status of the driver. Description This function gets the client-specific status of the USART driver associated with the given handle. This function can be used to check the status of client after the DRV_USART_Close() function has been called. Remarks This function will not block for hardware access and will immediately return the current status. This function is thread safe when called in a RTOS application. Preconditions The DRV_USART_Initialize function must have been called. DRV_USART_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE handle; // Returned from DRV_USART_Open DRV_USART_CLIENT_STATUS status; status = DRV_USART_ClientStatus(handle); if( DRV_USART_CLIENT_STATUS_CLOSED != status ) { // The client had not closed. } Parameters Parameters Description handle Handle returned from the driver's open function. Function DRV_USART_CLIENT_STATUS DRV_USART_ClientStatus( DRV_HANDLE handle ) DRV_USART_ErrorGet Function This function returns the error(if any) associated with the last client request. Implementation: Static/Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1324 File drv_usart.h C DRV_USART_ERROR DRV_USART_ErrorGet(const DRV_HANDLE client); Returns A DRV_USART_ERROR type indicating last known error status. Description This function returns the error(if any) associated with the last client request. DRV_USART_Read and DRV_USART_Write will update the client error status when these functions return DRV_USART_TRANSFER_ERROR. If the driver send a DRV_USART_BUFFER_EVENT_ERROR to the client, the client can call this function to know the error cause. The error status will be updated on every operation and should be read frequently (ideally immediately after the driver operation has completed) to know the relevant error status. Remarks It is the client's responsibility to make sure that the error status is obtained frequently. The driver will update the client error status regardless of whether this has been examined by the client. This function is thread safe when used in a RTOS application. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_USART_BUFFER_HANDLE bufferHandle; // myUSARTHandle is the handle returned // by the DRV_USART_Open function. // Client registers an event handler with driver. This is done once. DRV_USART_BufferEventHandlerSet( myUSARTHandle, APP_USARTBufferEventHandle, (uintptr_t)&myAppObj ); bufferHandle = DRV_USART_BufferAddRead( myUSARThandle, myBuffer, MY_BUFFER_SIZE ); if(DRV_USART_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event Processing Technique. Event is received when // the buffer is processed. void APP_USARTBufferEventHandler( DRV_USART_BUFFER_EVENT event, DRV_USART_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle ) { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) contextHandle; size_t processedBytes; switch(event) { case DRV_USART_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_USART_BUFFER_EVENT_ERROR: Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1325 // Error handling here. // We can find out how many bytes were processed in this // buffer before the error occurred. We can also find // the error cause. processedBytes = DRV_USART_BufferCompletedBytesGet(bufferHandle); if(DRV_USART_ERROR_RECEIVE_OVERRUN == DRV_USART_ErrorGet(myUSARTHandle)) { // There was an receive over flow error. // Do error handling here. } break; default: break; } } Parameters Parameters Description bufferhandle Handle of the buffer of which the processed number of bytes to be obtained. Function DRV_USART_ERROR DRV_USART_ErrorGet( DRV_HANDLE client); c) Communication Management Client Functions DRV_USART_BaudSet Function This function changes the USART module baud to the specified value. Implementation: Static/Dynamic File drv_usart.h C DRV_USART_BAUD_SET_RESULT DRV_USART_BaudSet(const DRV_HANDLE client, uint32_t baud); Returns None. Description This function changes the USART module baud to the specified value. Any queued buffer requests will be processed at the updated baud. The USART driver operates at the baud specified in DRV_USART_Initialize function unless the DRV_USART_BaudSet function is called to change the baud. Remarks The implementation of this function, in this release of the driver, changes the baud immediately. This may interrupt on-going data transfer. It is recommended that the driver be opened exclusively if this function is to be called. This function is thread safe when used in a RTOS application. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. Example // myUSARTHandle is the handle returned // by the DRV_USART_Open function. DRV_USART_BaudSet(myUSARTHandle, 9600); Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1326 Parameters Parameters Description handle client handle returned by DRV_USART_Open function. baud desired baud. Function void DRV_USART_BaudSet( DRV_HANDLE client, uint32_t baud); DRV_USART_LineControlSet Function This function changes the USART module line control to the specified value. Implementation: Static/Dynamic File drv_usart.h C DRV_USART_LINE_CONTROL_SET_RESULT DRV_USART_LineControlSet(const DRV_HANDLE client, const DRV_USART_LINE_CONTROL lineControl); Returns DRV_USART_LINE_CONTROL_SET_SUCCESS if the function was successful. Returns DRV_HANDLE_INVALID if the client handle is not valid. Description This function changes the USART module line control parameters to the specified value. Any queued buffer requests will be processed at the updated line control parameters. The USART driver operates at the line control parameters specified in DRV_USART_Initialize function unless the DRV_USART_LineControlSet function is called to change the line control parameters. Remarks The implementation of this function, in this release of the driver, changes the line control immediately. This may interrupt on-going data transfer. It is recommended that the driver be opened exclusively if this function is to be called. This function is thread safe when called in a RTOS application. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. Example // myUSARTHandle is the handle returned // by the DRV_USART_Open function. DRV_USART_LineControlSet(myUSARTHandle, DRV_USART_LINE_CONTROL_8NONE1); Parameters Parameters Description handle client handle returned by DRV_USART_Open function. lineControl line control parameters. Function void DRV_USART_LineControlSet ( DRV_HANDLE client, DRV_USART_LINE_CONTROL lineControl ); d) Buffer Queue Read/Write Client Functions Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1327 DRV_USART_BufferAddRead Function Schedule a non-blocking driver read operation. Implementation: Static/Dynamic File drv_usart.h C void DRV_USART_BufferAddRead(const DRV_HANDLE handle, DRV_USART_BUFFER_HANDLE * const bufferHandle, void * buffer, const size_t size); Returns The buffer handle is returned in the bufferHandle argument. This is DRV_USART_BUFFER_HANDLE_INVALID if the request was not successful. Description This function schedules a non-blocking read operation. The function returns with a valid buffer handle in the bufferHandle argument if the read request was scheduled successfully. The function adds the request to the hardware instance receive queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. The function returns DRV_USART_BUFFER_HANDLE_INVALID in the bufferHandle argument: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the buffer size is 0 • if the read queue size is full or queue depth is insufficient. • if the driver handle is invalid If the requesting client registered an event callback with the driver, the driver will issue a DRV_USART_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully of DRV_USART_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the USART Driver Buffer Event Handler that is registered by the client. It should not be called in the event handler associated with another USART driver instance. It should not be called directly in an ISR. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART device instance and the DRV_USART_Status must have returned SYS_STATUS_READY. DRV_USART_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_USART_Open call. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_USART_BUFFER_HANDLE bufferHandle; // myUSARTHandle is the handle returned // by the DRV_USART_Open function. // Client registers an event handler with driver DRV_USART_BufferEventHandlerSet(myUSARTHandle, APP_USARTBufferEventHandler, (uintptr_t)&myAppObj); DRV_USART_BufferAddRead(myUSARThandle, &bufferHandle, myBuffer, MY_BUFFER_SIZE); if(DRV_USART_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_USARTBufferEventHandler(DRV_USART_BUFFER_EVENT event, Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1328 DRV_USART_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_USART_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_USART_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle Handle of the communication channel as returned by the DRV_USART_Open function. buffer Buffer where the received data will be stored. size Buffer size in bytes. Function void DRV_USART_BufferAddRead ( const DRV_HANDLE handle, DRV_USART_BUFFER_HANDLE * bufferHandle, void * buffer, const size_t size ) DRV_USART_BufferAddWrite Function Schedule a non-blocking driver write operation. Implementation: Static/Dynamic File drv_usart.h C void DRV_USART_BufferAddWrite(const DRV_HANDLE handle, DRV_USART_BUFFER_HANDLE * bufferHandle, void * buffer, const size_t size); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_USART_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking write operation. The function returns with a valid buffer handle in the bufferHandle argument if the write request was scheduled successfully. The function adds the request to the hardware instance transmit queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. On returning, the bufferHandle parameter may be DRV_USART_BUFFER_HANDLE_INVALID for the following reasons: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the client opened the driver for read-only • if the buffer size is 0 Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1329 • if the transmit queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_USART_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully or a DRV_USART_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the USART Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another USART driver instance. It should not otherwise be called directly in an ISR. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART device instance and the DRV_USART_Status must have returned SYS_STATUS_READY. DRV_USART_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_USART_Open call. Example MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_USART_BUFFER_HANDLE bufferHandle; // myUSARTHandle is the handle returned // by the DRV_USART_Open function. // Client registers an event handler with driver DRV_USART_BufferEventHandlerSet(myUSARTHandle, APP_USARTBufferEventHandler, (uintptr_t)&myAppObj); DRV_USART_BufferAddWrite(myUSARThandle, &bufferHandle, myBuffer, MY_BUFFER_SIZE); if(DRV_USART_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_USARTBufferEventHandler(DRV_USART_BUFFER_EVENT event, DRV_USART_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_USART_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_USART_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle Handle of the communication channel as return by the DRV_USART_Open function. bufferHandle Pointer to an argument that will contain the return buffer handle. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1330 buffer Data to be transmitted. size Buffer size in bytes. Function void DRV_USART_BufferAddWrite ( const DRV_HANDLE handle, DRV_USART_BUFFER_HANDLE * bufferHandle, void * buffer, size_t size ); DRV_USART_BufferEventHandlerSet Function Allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. Implementation: Static/Dynamic File drv_usart.h C void DRV_USART_BufferEventHandlerSet(const DRV_HANDLE handle, const DRV_USART_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t context); Returns None. Description This function allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. When a client calls either the DRV_USART_BufferAddRead or DRV_USART_BufferAddWrite function, it is provided with a handle identifying the buffer that was added to the driver's buffer queue. The driver will pass this handle back to the client by calling "eventHandler" function when the buffer transfer has completed. The event handler should be set before the client performs any "buffer add" operations that could generate events. The event handler once set, persists until the client closes the driver or sets another event handler (which could be a "NULL" pointer to indicate no callback). Remarks If the client does not want to be notified when the queued buffer transfer has completed, it does not need to register a callback. This function is thread safe when called in a RTOS application. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_USART_BUFFER_HANDLE bufferHandle; // myUSARTHandle is the handle returned // by the DRV_USART_Open function. // Client registers an event handler with driver. This is done once DRV_USART_BufferEventHandlerSet( myUSARTHandle, APP_USARTBufferEventHandle, (uintptr_t)&myAppObj ); DRV_USART_BufferAddRead(myUSARThandle, &bufferHandle myBuffer, MY_BUFFER_SIZE); if(DRV_USART_BUFFER_HANDLE_INVALID == bufferHandle) { Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1331 // Error handling here } // Event Processing Technique. Event is received when // the buffer is processed. void APP_USARTBufferEventHandler(DRV_USART_BUFFER_EVENT event, DRV_USART_BUFFER_HANDLE handle, uintptr_t context) { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) context; switch(event) { case DRV_USART_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_USART_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine eventHandler Pointer to the event handler function. context The value of parameter will be passed back to the client unchanged, when the eventHandler function is called. It can be used to identify any client specific data object that identifies the instance of the client module (for example, it may be a pointer to the client module's state structure). Function void DRV_USART_BufferEventHandlerSet ( const DRV_HANDLE handle, const DRV_USART_BUFFER_EVENT_HANDLER eventHandler, const uintptr_t context ) DRV_USART_BufferProcessedSizeGet Function This API will be deprecated and not recommended to use. Use DRV_USART_BufferCompletedBytesGet to get the number of bytes processed for the specified buffer. File drv_usart.h C size_t DRV_USART_BufferProcessedSizeGet(DRV_USART_BUFFER_HANDLE bufferHandle); Returns None. Description None. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1332 Remarks None. Preconditions None. Example None. Function size_t DRV_USART_BufferProcessedSizeGet ( DRV_USART_BUFFER_HANDLE bufferHandle ); DRV_USART_AddressedBufferAddWrite Function Schedule a non-blocking addressed driver write operation. Implementation: Dynamic File drv_usart.h C void DRV_USART_AddressedBufferAddWrite(const DRV_HANDLE hClient, DRV_USART_BUFFER_HANDLE * bufferHandle, uint8_t address, void * source, size_t nWords); Returns The bufferHandle parameter will contain the return buffer handle. This will be DRV_USART_BUFFER_HANDLE_INVALID if the function was not successful. Description This function schedules a non-blocking addressed write operation. The function returns with a valid buffer handle in the bufferHandle argument if the addressed write request was scheduled successfully. The function adds the request to the hardware instance transmit queue and returns immediately. While the request is in the queue, the application buffer is owned by the driver and should not be modified. On returning, the bufferHandle parameter may be DRV_USART_BUFFER_HANDLE_INVALID for the following reasons: • if a buffer could not be allocated to the request • if the input buffer pointer is NULL • if the client opened the driver for read-only • if the buffer size is 0 • if the transmit queue is full or the queue depth is insufficient If the requesting client registered an event callback with the driver, the driver will issue a DRV_USART_BUFFER_EVENT_COMPLETE event if the buffer was processed successfully or a DRV_USART_BUFFER_EVENT_ERROR event if the buffer was not processed successfully. Remarks This function is thread safe in a RTOS application. It can be called from within the USART Driver Buffer Event Handler that is registered by this client. It should not be called in the event handler associated with another USART driver instance. It should not otherwise be called directly in an ISR. The source buffer should be a 16-bit word aligned buffer. The 9th bit of the higher byte 16-bit buffer is used to indicate data/address. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART device instance and the DRV_USART_Status must have returned SYS_STATUS_READY. DRV_USART_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_USART_Open call. The operation mode of the driver must be DRV_USART_OPERATION_MODE_ADDRESSED. Example MY_APP_OBJ myAppObj; uint16_t mybuffer[MY_BUFFER_SIZE]; DRV_USART_BUFFER_HANDLE bufferHandle; Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1333 uint8_t clientAddress; // myUSARTHandle is the handle returned // by the DRV_USART_Open function. // Client registers an event handler with driver clientAddress = 0x60; DRV_USART_BufferEventHandlerSet(myUSARTHandle, APP_USARTBufferEventHandler, (uintptr_t)&myAppObj); DRV_USART_AddressedBufferAddWrite(myUSARThandle, &bufferHandle, clientAddress myBuffer, MY_BUFFER_SIZE); if(DRV_USART_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event is received when // the buffer is processed. void APP_USARTBufferEventHandler(DRV_USART_BUFFER_EVENT event, DRV_USART_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle) { // contextHandle points to myAppObj. switch(event) { case DRV_USART_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_USART_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } Parameters Parameters Description hClient Handle of the communication channel as return by the DRV_USART_Open function. bufferHandle Pointer to an argument that will contain the return buffer handle. address Address of the receiver client source Data to be transmitted. size Buffer size in 16-bit words. Function void DRV_USART_AddressedBufferAddWrite ( const DRV_HANDLE hClient, DRV_USART_BUFFER_HANDLE * bufferHandle, uint8_t address, void * source, size_t nWords ); Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1334 DRV_USART_BufferCompletedBytesGet Function Returns the number of bytes that have been processed for the specified buffer. Implementation: Static/Dynamic File drv_usart.h C size_t DRV_USART_BufferCompletedBytesGet(DRV_USART_BUFFER_HANDLE bufferHandle); Returns Returns the number of bytes that have been processed for this buffer. Returns DRV_USART_BUFFER_HANDLE_INVALID for an invalid or an expired buffer handle. Description This function returns number of bytes that have been processed for the specified buffer. The client can use this function, in a case where the buffer has terminated due to an error, to obtain the number of bytes that have been processed. Or in any other use case. This function can be used for non-DMA buffer transfers only. It cannot be used when the USART driver is configured to use DMA. Remarks This function is thread safe when used in a RTOS application. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. Either the DRV_USART_BufferAddRead or DRV_USART_BufferAddWrite function must have been called and a valid buffer handle returned. Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_USART_BUFFER_HANDLE bufferHandle; // myUSARTHandle is the handle returned // by the DRV_USART_Open function. // Client registers an event handler with driver. This is done once DRV_USART_BufferEventHandlerSet( myUSARTHandle, APP_USARTBufferEventHandle, (uintptr_t)&myAppObj ); bufferHandle = DRV_USART_BufferAddRead( myUSARThandle, myBuffer, MY_BUFFER_SIZE ); if(DRV_USART_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event Processing Technique. Event is received when // the buffer is processed. void APP_USARTBufferEventHandler( DRV_USART_BUFFER_EVENT event, DRV_USART_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle ) { // The context handle was set to an application specific // object. It is now retrievable easily in the event handler. MY_APP_OBJ myAppObj = (MY_APP_OBJ *) contextHandle; size_t processedBytes; switch(event) { Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1335 case DRV_USART_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_USART_BUFFER_EVENT_ERROR: // Error handling here. // We can find out how many bytes were processed in this // buffer before the error occurred. processedBytes = DRV_USART_BufferCompletedBytesGet(bufferHandle); break; default: break; } } Parameters Parameters Description bufferhandle Handle for the buffer of which the processed number of bytes to be obtained. Function size_t DRV_USART_BufferCompletedBytesGet ( DRV_USART_BUFFER_HANDLE bufferHandle ); DRV_USART_BufferRemove Function Removes a requested buffer from the queue. Implementation: Static/Dynamic File drv_usart.h C DRV_USART_BUFFER_RESULT DRV_USART_BufferRemove(DRV_USART_BUFFER_HANDLE bufferHandle); Returns DRV_USART_BUFFER_RESULT_HANDLE_INVALID - Buffer handle is invalid. DRV_USART_BUFFER_RESULT_HANDLE_EXPIRED - Buffer handle is expired. DRV_USART_BUFFER_RESULT_REMOVED_SUCCESFULLY - Buffer is removed from the queue successfully. DRV_USART_BUFFER_RESULT_REMOVAL_FAILED - Failed to remove buffer from the queue because of mutex timeout in RTOS environment. Description This function removes a specified buffer from the queue. The client can use this function to delete 1. An unwated stalled buffer. 2. Queued buffers on timeout. or in any other use case. Remarks This function is thread safe when used in a RTOS application. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. Either the DRV_USART_BufferAddRead or DRV_USART_BufferAddWrite function must have been called and a valid buffer handle returned. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1336 Example // myAppObj is an application specific object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; DRV_USART_BUFFER_HANDLE bufferHandle; // myUSARTHandle is the handle returned // by the DRV_USART_Open function. // Client registers an event handler with driver. This is done once DRV_USART_BufferEventHandlerSet( myUSARTHandle, APP_USARTBufferEventHandle, (uintptr_t)&myAppObj ); bufferHandle = DRV_USART_BufferAddRead( myUSARThandle, myBuffer, MY_BUFFER_SIZE ); if(DRV_USART_BUFFER_HANDLE_INVALID == bufferHandle) { // Error handling here } // Event Processing Technique. Event is received when // the buffer is processed. void APP_USARTBufferEventHandler( DRV_USART_BUFFER_EVENT event, DRV_USART_BUFFER_HANDLE bufferHandle, uintptr_t contextHandle ) { switch(event) { case DRV_USART_BUFFER_EVENT_COMPLETE: // This means the data was transferred. break; case DRV_USART_BUFFER_EVENT_ERROR: // Error handling here. break; default: break; } } // Timeout function, where remove queued buffer if it still exists. void APP_TimeOut(void) { DRV_USART_BUFFER_RESULT bufferResult; bufferResult = DRV_USART_BufferRemove(bufferHandle); if(DRV_USART_BUFFER_RESULT_REMOVED_SUCCESFULLY == bufferResult) { //Buffer removed succesfully from the queue } else { //Either buffer is invalid or expired. //Or not able to acquire mutex in RTOS mode. } } Parameters Parameters Description bufferhandle Handle of the buffer to delete. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1337 Function DRV_USART_BUFFER_RESULT DRV_USART_BufferRemove( DRV_USART_BUFFER_HANDLE bufferHandle ) e) File I/O Type Read/Write Functions DRV_USART_Read Function Reads data from the USART. Implementation: Static/Dynamic File drv_usart.h C size_t DRV_USART_Read(const DRV_HANDLE handle, void * buffer, const size_t numbytes); Returns Number of bytes actually copied into the caller's buffer. Returns DRV_USART_READ_ERROR in case of an error. Description This routine reads data from the USART. This function is blocking if the driver was opened by the client for blocking operation. This function will not block if the driver was opened by the client for non blocking operation. If the ioIntent parameter at the time of opening the driver was DRV_IO_INTENT_BLOCKING, this function will only return when (or will block until) numbytes of bytes have been received or if an error occurred. If there are buffers queued for receiving data, these buffers will be serviced first. The function will not return until the requested number of bytes have been read. If the ioIntent parameter at the time of opening the driver was DRV_IO_INTENT_NON_BLOCKING, this function will return with the number of bytes that were actually read. The function will not wait until numBytes of bytes have been read. If there are buffer queued for reading data, then the function will not block and will return immediately with 0 bytes read. Remarks This function is thread safe in a RTOS application. If the driver is configured for polled operation, this it will not support blocking operation in a bare metal (non-RTOS) application. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_READ or DRV_IO_INTENT_READWRITE must have been specified in the DRV_USART_Open call. Example DRV_HANDLE myUSARTHandle; // Returned from DRV_USART_Open char myBuffer[MY_BUFFER_SIZE]; unsigned int count; unsigned int total; total = 0; do { count = DRV_USART_Read(myUSARTHandle, &myBuffer[total], MY_BUFFER_SIZE - total); if(count == DRV_USART_READ_ERROR) { // There was an error. The DRV_USART_ErrorGet() function // can be called to find the exact error. } total += count; // Do something else... } while( total < MY_BUFFER_SIZE ); Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1338 Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine buffer Buffer into which the data read from the USART instance will be placed. numbytes Total number of bytes that need to be read from the module instance (must be equal to or less than the size of the buffer) Function size_t DRV_USART_Read ( const DRV_HANDLE handle, void * buffer, const size_t numbytes ) DRV_USART_Write Function Writes data to the USART. Implementation: Static/Dynamic File drv_usart.h C size_t DRV_USART_Write(const DRV_HANDLE handle, void * buffer, const size_t numbytes); Returns Number of bytes actually written to the driver. Return DRV_USART_WRITE_ERROR in case of an error. Description This routine writes data to the USART. This function is blocking if the driver was opened by the client for blocking operation. This function will not block if the driver was opened by the client for non blocking operation. If the ioIntent parameter at the time of opening the driver was DRV_IO_INTENT_BLOCKING, this function will only return when (or will block until) numbytes of bytes have been transmitted or if an error occurred. If there are buffers queued for writing, the function will wait until all the preceding buffers are completed. Ongoing buffer transmit operations will not be affected. If the ioIntent parameter at the time of opening the driver was DRV_IO_INTENT_NON_BLOCKING, this function will return with the number of bytes that were actually accepted for transmission. The function will not wait until numBytes of bytes have been transmitted. If there a buffers queued for transmit, the function will not wait and will return immediately with 0 bytes. Remarks This function is thread safe in a RTOS application. This function is thread safe in a RTOS application. If the driver is configured for polled operation, this it will not support blocking operation in a bare metal (non-RTOS) application. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. DRV_IO_INTENT_WRITE or DRV_IO_INTENT_READWRITE must have been specified in the DRV_USART_Open call. Example DRV_HANDLE myUSARTHandle; // Returned from DRV_USART_Open char myBuffer[MY_BUFFER_SIZE]; int count; unsigned int total; total = 0; do { count = DRV_USART_Write(myUSARTHandle, &myBuffer[total], MY_BUFFER_SIZE - total); total += count; Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1339 // Do something else... } while( total < MY_BUFFER_SIZE ); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine buffer Buffer containing the data to written. numbytes size of the buffer Function size_t DRV_USART_Write ( const DRV_HANDLE handle, void * buffer, const size_t numbytes ) f) Byte Transfer Functions DRV_USART_ReadByte Function Reads a byte of data from the USART. Implementation: Static/Dynamic File drv_usart.h C uint8_t DRV_USART_ReadByte(const DRV_HANDLE handle); Returns A data byte received by the driver. Description This routine reads a byte of data from the USART. Remarks This function is thread safe when called in a RTOS application. Note that DRV_USART_WriteByte and DRV_USART_ReadByte function cannot co-exist with DRV_USART_BufferAddRead, DRV_USART_BufferAddWrite, DRV_USART_Read and DRV_USART_Write functions in a application. Calling the DRV_USART_ReadByte and DRV_USART_WriteByte functions will disrupt the processing of any queued buffers. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. The transfer status should be checked to see if the receiver is not empty before calling this function. Example DRV_HANDLE myUSARTHandle; // Returned from DRV_USART_Open char myBuffer[MY_BUFFER_SIZE]; unsigned int numBytes; numBytes = 0; do { if( DRV_USART_TRANSFER_STATUS_RECEIVER_DATA_PRESENT & DRV_USART_TransferStatus(myUSARTHandle) ) { myBuffer[numBytes++] = DRV_USART_ReadByte(myUSARTHandle); } // Do something else... Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1340 } while( numBytes < MY_BUFFER_SIZE); Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function uint8_t DRV_USART_ReadByte( const DRV_HANDLE handle ) DRV_USART_WriteByte Function Writes a byte of data to the USART. Implementation: Static/Dynamic File drv_usart.h C void DRV_USART_WriteByte(const DRV_HANDLE handle, const uint8_t byte); Returns None. Description This routine writes a byte of data to the USART. Remarks This function is thread safe when called in a RTOS application. Note that DRV_USART_WriteByte and DRV_USART_ReadByte function cannot co-exist with DRV_USART_BufferAddRead, DRV_USART_BufferAddWrite, DRV_USART_Read and DRV_USART_Write functions in a application. Calling the DRV_USART_ReadByte and DRV_USART_WriteByte function will disrupt the processing of any queued buffers. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. The transfer status should be checked to see if transmitter is not full before calling this function. Example DRV_HANDLE myUSARTHandle; // Returned from DRV_USART_Open char myBuffer[MY_BUFFER_SIZE]; unsigned int numBytes; // Preinitialize myBuffer with MY_BUFFER_SIZE bytes of valid data. numBytes = 0; while( numBytes < MY_BUFFER_SIZE ); { if( !(DRV_USART_TRANSFER_STATUS_TRANSMIT_FULL & DRV_USART_TransferStatus(myUSARTHandle)) ) { DRV_USART_WriteByte(myUSARTHandle, myBuffer[numBytes++]); } // Do something else... } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine byte Data byte to write to the USART Function void DRV_USART_WriteByte( const DRV_HANDLE handle, const uint8_t byte) Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1341 DRV_USART_TransmitBufferSizeGet Function Returns the size of the transmit buffer. Implementation: Static/Dynamic File drv_usart.h C unsigned int DRV_USART_TransmitBufferSizeGet(const DRV_HANDLE handle); Returns Size of the driver's transmit buffer, in bytes. Description This routine returns the size of the transmit buffer and can be used by the application to determine the number of bytes to write with the DRV_USART_WriteByte function. Remarks Does not account for client queued buffers. This function is thread safe when used in a RTOS application. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE myUSARTHandle; // Returned from DRV_USART_Open const uint8_t writeBuffer[5]; unsigned int size, numBytes = 0; unsigned int writeBufferLen = sizeof(writeBuffer); size = DRV_USART_TransmitBufferSizeGet (myUSARTHandle); // Do something based on the transmitter buffer size Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function unsigned int DRV_USART_TransmitBufferSizeGet ( const DRV_HANDLE handle ) DRV_USART_ReceiverBufferSizeGet Function Returns the size of the receive buffer. Implementation: Static/Dynamic File drv_usart.h C unsigned int DRV_USART_ReceiverBufferSizeGet(const DRV_HANDLE handle); Returns Size of the driver's receive buffer, in bytes. Description This routine returns the size of the receive buffer. Remarks Does not account for client queued buffers. This function is thread safe when called in a RTOS application. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1342 Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE myUSARTHandle; // Returned from DRV_USART_Open const uint8_t readBuffer[5]; unsigned int size, numBytes = 0; unsigned int readbufferLen = sizeof(readBuffer); size = DRV_USART_ReceiverBufferSizeGet(myUSARTHandle); // Do something based on the receiver buffer size Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function unsigned int DRV_USART_ReceiverBufferSizeGet( const DRV_HANDLE handle ) DRV_USART_TransferStatus Function Returns the transmitter and receiver transfer status. Implementation: Static/Dynamic File drv_usart.h C DRV_USART_TRANSFER_STATUS DRV_USART_TransferStatus(const DRV_HANDLE handle); Returns A DRV_USART_TRANSFER_STATUS value describing the current status of the transfer. Description This returns the transmitter and receiver transfer status. Remarks The returned status may contain a value with more than one of the bits specified in the DRV_USART_TRANSFER_STATUS enumeration set. The caller should perform an "AND" with the bit of interest and verify if the result is non-zero (as shown in the example) to verify the desired status bit. This function is thread safe when called in a RTOS application. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE myUSARTHandle; // Returned from DRV_USART_Open if (DRV_USART_TRANSFER_STATUS_RECEIVER_DATA_PRESENT & DRV_USART_TransferStatus(myUSARTHandle)) { // Data has been received that can be read } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function DRV_USART_TRANSFER_STATUS DRV_USART_TransferStatus( const DRV_HANDLE handle ) Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1343 DRV_USART_TransmitBufferIsFull Function Provides the status of the driver's transmit buffer. Implementation: Static/Dynamic File drv_usart.h C bool DRV_USART_TransmitBufferIsFull(const DRV_HANDLE handle); Returns true - if the transmit buffer is full false - if the transmit buffer is not full Description This routine identifies if the driver's transmit buffer is full or not. This function can be used in conjunction with the DRV_USART_Write and DRV_USART_WriteByte functions. Remarks Does not account for client queued buffers. This function is thread safe when called in a RTOS application. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE myUSARTHandle; // Returned from DRV_USART_Open unsigned int numBytes; int bytesToWrite; const uint8_t writeBuffer[35] = "1234567890ABCDEFGHIJKLMNOPn" ; int writebufferLen = strlen((char *)writeBuffer); numBytes = 0; while( numBytes < writebufferLen ) { if (DRV_USART_TransmitBufferisFull()) { // Do something else until there is some room in the driver's Transmit buffer. } else { DRV_USART_WriteByte(myUSARTHandle, writeBuffer[numBytes++]); } } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function bool DRV_USART_TransmitBufferIsFull( const DRV_HANDLE handle ) DRV_USART_ReceiverBufferIsEmpty Function Provides the status of the driver's receive buffer. Implementation: Static/Dynamic File drv_usart.h Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1344 C bool DRV_USART_ReceiverBufferIsEmpty(const DRV_HANDLE handle); Returns true - if the driver's receive buffer is empty false - if the driver's receive buffer is not empty Description This routine indicates if the driver's receiver buffer is empty. This function can be used in conjunction with the DRV_USART_Read and DRV_USART_ReadByte functions. Remarks Does not account for client queued buffers. This function is safe thread safe when used in a RTOS application. Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. DRV_USART_Open must have been called to obtain a valid opened device handle. Example DRV_HANDLE myUSARTHandle; // Returned from DRV_USART_Open char myBuffer[MY_BUFFER_SIZE]; unsigned int numBytes; numBytes = 0; while( numBytes < MY_BUFFER_SIZE ); { if ( !DRV_USART_ReceiverBufferIsEmpty(myUSARTHandle) ) { if( numBytes < MY_BUFFER_SIZE ) { myBuffer[numBytes++] = DRV_USART_ReadByte (myUSARTHandle); } else { break; } } // Do something else while more data is received. } Parameters Parameters Description handle A valid open-instance handle, returned from the driver's open routine Function bool DRV_USART_ReceiverBufferIsEmpty( const DRV_HANDLE handle ) DRV_USART_ByteErrorCallbackSet Function Registers callback to handle for byte error events. File drv_usart.h C void DRV_USART_ByteErrorCallbackSet(const SYS_MODULE_INDEX index, const DRV_USART_BYTE_EVENT_HANDLER eventHandler); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1345 Description This function allows a callback function to be registered with the driver to handle the error events occurring in the transmit/receive path during byte transfers. The callback function should be registered as part of the initialization. The callback functionality is available only in the interrupt mode of operation. The driver clears the interrupt after invoking the callback function. Remarks None Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; // myUSARTHandle is the handle returned by the DRV_USART_Open function. myUSARTHandle = DRV_USART_Open(DRV_USART_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); (uintptr_t)&myAppObj ); // Register an event handler with driver. This is done once DRV_USART_ByteErrorCallbackSet (DRV_USART_INDEX_0, APP_USARTErrorEventHandler); // Event Processing Technique. void APP_USARTErrorEventHandler(const SYS_MODULE_INDEX index) { // Error has occurred. Handle the event. } Parameters Parameters Description index Identifier for the object instance to be opened eventHandler Pointer to the event handler function. Function void DRV_USART_ByteErrorCallbackSet ( const SYS_MODULE_INDEX index, const DRV_USART_BYTE_EVENT_HANDLER eventHandler ) DRV_USART_ByteReceiveCallbackSet Function Registers receive callback function for byte receive event. File drv_usart.h C void DRV_USART_ByteReceiveCallbackSet(const SYS_MODULE_INDEX index, const DRV_USART_BYTE_EVENT_HANDLER eventHandler); Returns None. Description This function allows a receive callback function to be registered with the driver. The callback function is invoked when a byte has been received. The received byte can then be read using DRV_USART_ReadByte() function. The callback function should be registered with the driver as part of the initialization. The callback functionality is available only in the interrupt mode of operation. The driver clears the interrupt after invoking the callback function. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1346 Remarks None Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; // myUSARTHandle is the handle returned by the DRV_USART_Open function. myUSARTHandle = DRV_USART_Open(DRV_USART_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); (uintptr_t)&myAppObj ); // Register an event handler with driver. This is done once DRV_USART_ByteReceiveCallbackSet(DRV_USART_INDEX_0, APP_USARTReceiveEventHandler); // Event Processing Technique. Event is received when // a byte is received. void APP_USARTReceiveEventHandler(const SYS_MODULE_INDEX index) { // Byte has been Received. Handle the event. // Read byte using DRV_USART_ReadByte () // DRV_USART_ReceiverBufferIsEmpty() function can be used to // check if the receiver buffer is empty. } Parameters Parameters Description index Identifier for the object instance to be opened eventHandler Pointer to the event handler function. Function void DRV_USART_ByteReceiveCallbackSet ( const SYS_MODULE_INDEX index, const DRV_USART_BYTE_EVENT_HANDLER eventHandler ) DRV_USART_ByteTransmitCallbackSet Function Registers a callback function for byte transmit event. File drv_usart.h C void DRV_USART_ByteTransmitCallbackSet(const SYS_MODULE_INDEX index, const DRV_USART_BYTE_EVENT_HANDLER eventHandler); Returns None. Description This function allows a transmit callback function to be registered with the driver. The callback function is invoked when a byte has been transmitted using DRV_USART_WriteByte () function. The callback function should be registered with the driver prior to any writes to the driver. The callback functionality is available only in the interrupt mode of operation. The driver clears the interrupt after invoking the callback function. Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1347 Remarks None Preconditions The DRV_USART_Initialize routine must have been called for the specified USART driver instance. Example // myAppObj is an application specific state data object. MY_APP_OBJ myAppObj; uint8_t mybuffer[MY_BUFFER_SIZE]; // myUSARTHandle is the handle returned by the DRV_USART_Open function. myUSARTHandle = DRV_USART_Open(DRV_USART_INDEX_0, DRV_IO_INTENT_EXCLUSIVE); (uintptr_t)&myAppObj ); // Register an event handler with driver. This is done once DRV_USART_ByteTransmitCallbackSet (DRV_USART_INDEX_0, APP_USARTTransmitEventHandler); DRV_USART_WriteByte (myUSARThandle, myBuffer[0]); // Event Processing Technique. Event is received when // the byte is transmitted. void APP_USARTTransmitEventHandler (const SYS_MODULE_INDEX index) { // Byte has been transmitted. Handle the event. } Parameters Parameters Description index Identifier for the object instance to be opened eventHandler Pointer to the event handler function. Function void DRV_USART_ByteTransmitCallbackSet ( const SYS_MODULE_INDEX index, const DRV_USART_BYTE_EVENT_HANDLER eventHandler ) Files Files Name Description drv_usart.h USART Driver Interface Header File drv_usart_config_template.h USART Driver Configuration Template. Description This section lists the source and header files used by the USART Driver Library. drv_usart.h USART Driver Interface Header File Functions Name Description DRV_USART_AddressedBufferAddWrite Schedule a non-blocking addressed driver write operation. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1348 DRV_USART_BaudSet This function changes the USART module baud to the specified value. Implementation: Static/Dynamic DRV_USART_BufferAddRead Schedule a non-blocking driver read operation. Implementation: Static/Dynamic DRV_USART_BufferAddWrite Schedule a non-blocking driver write operation. Implementation: Static/Dynamic DRV_USART_BufferCompletedBytesGet Returns the number of bytes that have been processed for the specified buffer. Implementation: Static/Dynamic DRV_USART_BufferEventHandlerSet Allows a client to identify a buffer event handling function for the driver to call back when queued buffer transfers have finished. Implementation: Static/Dynamic DRV_USART_BufferProcessedSizeGet This API will be deprecated and not recommended to use. Use DRV_USART_BufferCompletedBytesGet to get the number of bytes processed for the specified buffer. DRV_USART_BufferRemove Removes a requested buffer from the queue. Implementation: Static/Dynamic DRV_USART_ByteErrorCallbackSet Registers callback to handle for byte error events. DRV_USART_ByteReceiveCallbackSet Registers receive callback function for byte receive event. DRV_USART_ByteTransmitCallbackSet Registers a callback function for byte transmit event. DRV_USART_ClientStatus Gets the current client-specific status the USART driver. Implementation: Static/Dynamic DRV_USART_Close Closes an opened-instance of the USART driver. Implementation: Static/Dynamic DRV_USART_Deinitialize Deinitializes the specified instance of the USART driver module. Implementation: Static/Dynamic DRV_USART_ErrorGet This function returns the error(if any) associated with the last client request. Implementation: Static/Dynamic DRV_USART_Initialize Initializes the USART instance for the specified driver index. Implementation: Static/Dynamic DRV_USART_LineControlSet This function changes the USART module line control to the specified value. Implementation: Static/Dynamic DRV_USART_Open Opens the specified USART driver instance and returns a handle to it. Implementation: Static/Dynamic DRV_USART_Read Reads data from the USART. Implementation: Static/Dynamic DRV_USART_ReadByte Reads a byte of data from the USART. Implementation: Static/Dynamic DRV_USART_ReceiverBufferIsEmpty Provides the status of the driver's receive buffer. Implementation: Static/Dynamic DRV_USART_ReceiverBufferSizeGet Returns the size of the receive buffer. Implementation: Static/Dynamic DRV_USART_Status Gets the current status of the USART driver module. Implementation: Static/Dynamic DRV_USART_TasksError Maintains the driver's error state machine and implements its ISR. Implementation: Static/Dynamic DRV_USART_TasksReceive Maintains the driver's receive state machine and implements its ISR. Implementation: Static/Dynamic DRV_USART_TasksTransmit Maintains the driver's transmit state machine and implements its ISR. Implementation: Static/Dynamic DRV_USART_TransferStatus Returns the transmitter and receiver transfer status. Implementation: Static/Dynamic DRV_USART_TransmitBufferIsFull Provides the status of the driver's transmit buffer. Implementation: Static/Dynamic DRV_USART_TransmitBufferSizeGet Returns the size of the transmit buffer. Implementation: Static/Dynamic DRV_USART_Write Writes data to the USART. Implementation: Static/Dynamic DRV_USART_WriteByte Writes a byte of data to the USART. Implementation: Static/Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help USART Driver Library © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1349 Description USART Driver Interface Header File The USART device driver provides a simple interface to manage the USART or UART modules on Microchip microcontrollers. This file provides the interface definition for the USART driver. File Name drv_usart.h Company Microchip Technology Inc. drv_usart_config_template.h USART Driver Configuration Template. Macros Name Description DRV_USART_BAUD_RATE_IDXn Specifies the USART Baud at which the USART driver is initialized. DRV_USART_BUFFER_QUEUE_SUPPORT Specifies if the Buffer Queue support should be enabled. DRV_USART_BYTE_MODEL_BLOCKING Enables or Disables DRV_USART_ByteWrite function blocking behavior. DRV_USART_BYTE_MODEL_CALLBACK Enables or Disables Callback Feature of the Byte Transfer Model. DRV_USART_BYTE_MODEL_SUPPORT Specifies if the Byte Model support should be enabled. DRV_USART_CLIENTS_NUMBER Sets up the maximum number of clients that can be connected to any hardware instance. DRV_USART_INDEX USART Static Index selection. DRV_USART_INSTANCES_NUMBER Sets up the maximum number of hardware instances that can be supported. DRV_USART_INTERRUPT_MODE Macro controls interrupt based operation of the driver. DRV_USART_INTERRUPT_SOURCE_ERROR Defines the error interrupt source for the static driver. DRV_USART_INTERRUPT_SOURCE_RECEIVE Defines the Receive interrupt source for the static driver. DRV_USART_INTERRUPT_SOURCE_RECEIVE_DMA Defines the Receive DMA Channel interrupt source for the static driver. DRV_USART_INTERRUPT_SOURCE_TRANSMIT Defines the Transmit interrupt source for the static driver. DRV_USART_INTERRUPT_SOURCE_TRANSMIT_DMA Defines the Transmit DMA Channel interrupt source for the static driver. DRV_USART_PERIPHERAL_ID Configures the USART PLIB Module ID. DRV_USART_QUEUE_DEPTH_COMBINED Defines the number of entries of all queues in all instances of the driver. DRV_USART_RCV_QUEUE_SIZE_IDXn Sets the USART Driver Receive Queue Size while using the Buffer Queue Data Transfer Model. DRV_USART_READ_WRITE_MODEL_SUPPORT Specifies if Read/Write Model support should be enabled. DRV_USART_RECEIVE_DMA Defines the USART Driver Receive DMA Channel for the static driver. DRV_USART_TRANSMIT_DMA Defines the USART Driver Transmit DMA Channel in case of static driver. DRV_USART_XMIT_QUEUE_SIZE_IDXn Sets the USART Driver Transmit Queue Size while using the Buffer Queue Data Transfer Model. Description USART Driver Configuration Template These file provides the list of all the configurations that can be used with the driver. This file should not be included in the driver. File Name drv_usart_config_template.h Company Microchip Technology Inc. Wi-Fi Driver Libraries This section describes the Wi-Fi Driver Libraries available in MPLAB Harmony. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1350 Description MRF24WN0MA Wi-Fi PICtail/PICtail Plus Daughter Board: Part number - AC164153 http://www.microchip.com/Developmenttools/ProductDetails.aspx?PartNO=AC164153 The following table lists the library files available for the Wi-Fi Drivers. Wi-Fi Library File Matrix Wi-Fi Device PIC32MX795F512L PIC32MZ2048ECH144 PIC32MZ2048EFM144 MRF24WN wdrvext_mx.a wdrvext_mz_ec.a wdrvext_mz_ef.a MRF24WN Wi-Fi Driver Library This topic describes the MRF24WN Wi-Fi Driver Library. Description The following table lists the library files available for the MRF24WN Wi-Fi Driver. Introduction This library provides a low-level abstraction of the MRF24WN Wi-Fi Driver 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 MRF24WN Wi-Fi Driver Library, in conjunction with the MRF24WN module, allows an application to: • Join an existing 802.11 Wi-Fi Infrastructure network • Create a 802.11 Wi-Fi Ad Hoc or Soft AP network The following application services are provided by the Wi-Fi library: • Configuring Wi-Fi connection (SSID, security mode, channel list, etc.) • Join an existing Wi-Fi Infrastructure network • Create a Wi-Fi Ad Hoc or Soft AP network • Scan for Wi-Fi Access Point (AP) or Soft AP • Getting Wi-Fi network status • Wi-Fi power control • Wi-Fi console commands The MAC_layer services are not directly accessible to the application; this portion of the code resides under the TCP/IP Stack MAC module software layers and is used by stack services to transmit and receive data over a Wi-Fi network. The following diagram shows the interaction of the primary software blocks in a Wi-Fi application. Wi-Fi Software Block Diagram The following table provides information that includes network mode and security mode support by MRF24WN Wi-Fi Driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1351 Using the Library This topic describes the basic architecture of the MRF24WN Wi-Fi Driver Library and provides information and examples on its use. Description Interface Header Files: wdrv_mrf24wn_common.h and wdrv_mrf24wn_api.h The interface to the MRF24WN Wi-Fi Driver Library is defined in the wdrv_mrf24wn_common.h and wdrv_mrf24wn_api.h header files. Please refer to the Understanding MPLAB Harmony section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the MRF24WN Wi-Fi module with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The MRF24WN Wi-Fi Library provides the following functionality: • Wi-Fi library initialization • Wi-Fi network configuration • Wi-Fi network connection • Scanning for existing Wi-Fi networks • Wi-Fi event processing • Wi-Fi status • Wi-FI console commands Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The Library Interface functions are divided into various sub-sections, which address one of the blocks or the overall operation of the Wi-Fi module. Library Interface Section Description Wi-Fi Initialization Functions This section provides functions that initialize the Wi-Fi library and allow its API to be used. Wi-Fi Status Functions This section provides functions that retrieve the Wi-Fi connection status. Wi-Fi External Functions This section provides public functions accessible to TCP/IP applications. Other Functions This section provides additional miscellaneous functions for configuring the Wi-Fi connection. How the Library Works This section describes how the MRF24WN Wi-Fi Driver Library operates. Description Before the driver is ready for use, its should be configured (compile time configuration). There are few run-time configuration items that are done during initialization of the driver instance, and a few that are client-specific and are done using dedicated functions. To use the MRF24WN Wi-Fi Driver, initialization and client functions should be invoked in a specific sequence to ensure correct operation. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1352 System Initialization This section describes initialization and reinitialization features. Description Wi-Fi initialization configures the MRF24WN module and then directs it to join (or create) a Wi-Fi network. The MRF24WN module defaults to open security and scans all channels in the domain. Therefore, to initialize and_connect_with the minimum function call overhead in an open security network, the following functions can be used: WDRV_EXT_CmdSSIDSet("MySsidName",strlen("MySsidName"); WDRV_EXT_CmdConnect(); // start the connection process Alternatively, the following functions could be used to achieve the same effect: WDRV_EXT_CmdNetModeBSSSet(); WDRV_EXT_CmdSecNoneSet(); WDRV_EXT_CmdSSIDSet("MySsidName",strlen("MySsidName"); WDRV_EXT_CmdConnect(); Client Functionality This section describes core operation. Description From the client perspective, once Wi-Fi initialization is complete and the connection process has started, the client responds to Wi-Fi events. The client is notified of events by the callback function WDRV_ProcessEvent. The parameters into that function are event and eventInfo, where event is the event code and eventInfo is additional information about the event. Wi-Fi Connection Events /*No Wi-Fi connection exists*/ WDRV_CSTATE_NOT_CONNECTED = 1, /*Wi-Fi connection in progress*/ WDRV_CSTATE_CONNECTION_IN_PROGRESS = 2, /*Wi-Fi connected in infrastructure mode*/ WDRV_CSTATE_CONNECTED_INFRASTRUCTURE = 3, /*Wi-Fi connected in adHoc mode*/ WDRV_CSTATE_CONNECTED_ADHOC = 4, /*Wi-Fi in process of reconnecting*/ WDRV_CSTATE_RECONNECTION_IN_PROGRESS = 5, /*Wi-Fi connection temporarily lost*/ WDRV_CSTATE_CONNECTION_TEMPORARY_LOST = 6, /*Wi-Fi connection permanently lost*/ WDRV_CSTATE_CONNECTION_PERMANENTLY_LOST = 7 Scan Events WDRV_SOFTAP_EVENT_CONNECTED = 0, WDRV_SOFTAP_EVENT_DISCONNECTED = 1 Key Events WDRV_SOFTAP_EVENT_LINK_LOST = 0, WDRV_SOFTAP_EVENT_RECEIVED_DEAUTH = 1 Disconnect Events WDRV_DISCONNECT_REASON_NO_NETWORK_AVAIL = 0x01, WDRV_DISCONNECT_REASON_LOST_LINK = 0x02, WDRV_DISCONNECT_REASON_DISCONNECT_CMD = 0x03, Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1353 WDRV_DISCONNECT_REASON_BSS_DISCONNECTED = 0x04, WDRV_DISCONNECT_REASON_AUTH_FAILED = 0x05, WDRV_DISCONNECT_REASON_ASSOC_FAILED = 0x06, WDRV_DISCONNECT_REASON_NO_RESOURCES_AVAIL = 0x07, WDRV_DISCONNECT_REASON_CONNECTION_DENIED = 0x08, WDRV_DISCONNECT_REASON_INVALID_PROFILE = 0x0A, WDRV_DISCONNECT_REASON_PROFILE_MISMATCH = 0x0C, WDRV_DISCONNECT_REASON_CONNECTION_EVICTED = 0x0d Configuring the Library The configuration of the MRF24WN Wi-Fi Driver is based on the file system_config.h. This header file contains the configuration selection for the Wi-Fi Driver. Based on the selections made, the MRF24WN Wi-Fi Driver may support the selected features. These configuration settings will apply to all instances of the MRF24WN Wi-Fi Driver. 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. Sample Functionality The following code provides an example of Wi-Fi Driver configuration. /*** Wi-Fi Driver Configuration ***/ #define WIFI_USE_RTOS #define WDRV_EXT_INIT_TASK_STACK_SIZE 512u #define WDRV_EXT_INIT_TASK_PRIO 6u #define WDRV_EXT_MAIN_TASK_STACK_SIZE 2048u #define WDRV_EXT_MAIN_TASK_PRIO 7u #define WDRV_ASSERT(condition, msg) WDRV_Assert(condition, msg, __FILE__, __LINE__) #define DRV_WIFI_SPI_INDEX 0 #define DRV_WIFI_SPI_INSTANCE sysObj.spiObjectIdx0 #define DRV_WIFI_NVM_SPACE_ENABLE #define DRV_WIFI_NVM_SPACE_ADDR (48*1024) #define MRF_INT_SOURCE INT_SOURCE_EXTERNAL_1 #define MRF_INT_VECTOR INT_VECTOR_INT1 // IO mapping for general control pins, including CS, RESET and HIBERNATE // MRF24W in SPI 1 slot #define WF_CS_PORT_CHANNEL PORT_CHANNEL_E #define WF_CS_BIT_POS 9 #define WF_RESET_PORT_CHANNEL PORT_CHANNEL_F #define WF_RESET_BIT_POS 0 #define WF_HIBERNATE_PORT_CHANNEL PORT_CHANNEL_F #define WF_HIBERNATE_BIT_POS 1 #define WF_INT_PRIORITY 3 #define WF_INT_SUBPRIORITY 1 #define WF_INT_PORT_CHANNEL PORT_CHANNEL_E #define WF_INT_BIT_POS 8 #define WDRV_DEFAULT_NETWORK_TYPE WDRV_NETWORK_TYPE_INFRASTRUCTURE #define WDRV_DEFAULT_SSID_NAME "MicrochipDemoApp" #define WDRV_DEFAULT_WIFI_SECURITY_MODE WDRV_SECURITY_OPEN #define WDRV_DEFAULT_WEP_KEYS_40 "5AFB6C8E77" // default WEP40 key #define WDRV_DEFAULT_WEP_KEYS_104 "90E96780C739409DA50034FCAA" // default WEP104 key #define WDRV_DEFAULT_PSK_PHRASE "Microchip 802.11 Secret PSK Password" // default WPA-PSK or WPA2-PSK passphrase #define WDRV_DEFAULT_WPS_PIN "12390212" // default WPS PIN Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1354 #define WDRV_DEFAULT_CHANNEL 6 #define WDRV_DEFAULT_POWER_SAVE WDRV_FUNC_DISABLED Building the Library This section lists the files that are available in the MRF24WN Wi-Fi Driver Library. 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 /framework/driver/wifi/mrf24wn. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description wdrv_mrf24wn_common.h Contains all data types, define constants for the MRF24WN Wi-Fi Driver. wdrv_mrf24wn_api.h Contains function prototypes for interfacing to the MRF24WN Wi-Fi Driver. 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 wdrv_mrf24wn_cli.c Provides access to MRF24WN Wi-Fi Driver controller. wdrv_mrf24wn_config_data.c Stores and retrieves MRF24WN Wi-Fi Driver configuration information in Non-volatile Memory (NVM). wdrv_mrf24wn_connmgr.c Provides access to MRF24WN Wi-Fi Driver controller for connection manager. wdrv_mrf24wn_events.c Provides access to MRF24WN Wi-Fi Driver controller for MAC events. wdrv_mrf24wn_iwpriv.c Provides functions to configure optional (private) parameters of the MRF24WN Wi-Fi Driver. wdrv_mrf24wn_main.c Module for Microchip TCP/IP Stack PIC32 implementation for multiple Wi-Fi MAC support. wdrv_mrf24wn_misc.c Miscellaneous support functions and data types for the MRF24WN Wi-Fi Driver. wdrv_mrf24wn_osal.c RTOS wrapper functions for the MRF24WN Wi-Fi Driver. wdrv_mrf24wn_scan_helper.c Provides helper functions to access scan results. 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 N/A The MRF24WN Wi-Fi Driver controller has no optional files. Module Dependencies The MRF24WN Wi-Fi Driver Library depends on the following modules: • SPI Driver Library • NVM Driver Library • UART Driver Library • USB Driver Library • Operating System Abstraction Layer (OSAL) Library Help • Clock System Service Library • System Service Library Introduction • Console System Service Library • File System Service Library • Interrupt System Service Library • Timer System Service Library • Debug System Service Library • Ports System Service Library Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1355 • FreeRTOS Library Help • Crypto Library • Peripheral Libraries Console Commands This section describes the console commands available for the MRF24WN Wi-Fi Driver. Description Both the Web Server and the EasyConfig demonstrations support the followings commands, which enable control over the Wi-Fi settings. Command: deleteconf Parameters Description None. Wi-Fi console command to erase saved Wi-Fi configuration in memory. Command: iwconfig Parameters Description [ ssid ] name: Specifies the name of the SSID (1-32 ASCII characters). [ mode ] idle: Disconnected from the current configuration. managed: Connects in infrastructure mode to the currently set SSID. [ power ] enable: Enables all Power-Saving features (PS_POLL). Will wake up to check for all types of traffic (unicast, multicast, and broadcast). disable: Disables any Power-Saving features. Will always be in an active power state. [ security ] mode: open/wep40/wep104/wpa/wpa2/pin/pbc. For example: iwconfig security open iwconfig security wep40 iwconfig security wep104 iwconfig security wpa iwconfig security wpa2 iwconfig security pin iwconfig security pbc [ scan ] Starts a Wi-Fi scan. [ scanget ] scan_index: Retrieves the scan result after the scan completes (1 - n). Command: mac Parameters Description None. Wi-Fi console command to retrieve the MAC address of the MRF24WN module. Command: readconf Parameters Description None. Wi-Fi console command to read saved Wi-Fi configuration in memory. Command: saveconf Parameters Description None. Wi-Fi console command to save Wi-Fi configuration to memory. Library Interface a) Wi-Fi Initialization Functions Name Description WDRV_SPI_In Receives data from the module through the SPI bus. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1356 WDRV_SPI_Out Sends data out to the module through the SPI bus. Implementation: Dynamic WDRV_GPIO_Init Initializes the GPIO objects for the Wi-Fi driver. Implementation: Dynamic WDRV_GPIO_PowerOff Powers off the MRF24WN module. Implementation: Dynamic WDRV_GPIO_PowerOn Powers on the MRF24WN module. Implementation: Dynamic WDRV_IsPowerOff Checks if MRF24WN is turned off. Implementation: Dynamic WDRV_MRF24WN_ISR Wi-Fi driver (MRF24WN-specific) interrupt service routine. Implementation: Dynamic b) Wi-Fi Status Functions Name Description WDRV_EXT_CmdConnectContextChannelGet Gets the AP channel Implementation: Dynamic WDRV_EXT_CmdPowerSaveGet Retrieves current power save status. Implementation: Dynamic WDRV_EXT_ScanResultGet Reads the selected scan results back from the MRF24WN module. Implementation: Dynamic c) External Functions Name Description WDRV_EXT_CmdNetModeIBSSSet Sets the Wi-Fi network type to Adhoc. Implementation: Dynamic WDRV_EXT_CmdSecWPA2Set Sets Wi-Fi security to WPA2. Implementation: Dynamic WDRV_EXT_Initialize Initializes the MRF24WN Wi-Fi driver. Implementation: Dynamic WDRV_EXT_Initialize Initializes the WINC1500 Wi-Fi driver. Implementation: Dynamic WDRV_EXT_PrivConfig Configures g_wdrvext_priv parameter. Implementation: Dynamic e) Private Configuration Functions Name Description iwpriv_config_write Writes to the Wi-Fi context configuration which is currently used by Wi-Fi driver. Implementation: Dynamic iwpriv_connstatus_get Gets the Wi-Fi connection status. Implementation: Dynamic iwpriv_devinfo_get Gets the device information. Implementation: Dynamic iwpriv_initialconn_set Sets the initial connection status of Wi-Fi driver. Implementation: Dynamic iwpriv_initstatus_get Gets the initialization status of Wi-Fi driver. Implementation: Dynamic iwpriv_is_servermode Checks if the passed Wi-Fi context configuration is operating in server mode. Implementation: Dynamic iwpriv_leftclient_get Gets the left client's information. Implementation: Dynamic iwpriv_mcastfilter_set Adds a MAC address to the multi-cast filter. Implementation: Dynamic iwpriv_nettype_get Gets the current network type. Implementation: Dynamic iwpriv_nettype_set Sets the current network type. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1357 iwpriv_numberofscanresults_get Gets the number of scan results. Implementation: Dynamic iwpriv_powersave_config Enables or disables Power Save mode in Wi-Fi driver. Implementation: Dynamic iwpriv_prescan_start Starts prescan. Implementation: Dynamic iwpriv_scan_start Starts scan. Implementation: Dynamic iwpriv_scanstatus_get Gets the prescan status. Implementation: Dynamic iwpriv_ssid_get Gets the current SSID. Implementation: Dynamic iwpriv_ssid_set Sets the current SSID. Implementation: Dynamic iwpriv_execute This is function iwpriv_execute. iwpriv_get This is function iwpriv_get. iwpriv_prescan_isfinished Checks if the prescan is complete. Implementation: Dynamic iwpriv_prescan_option_get To see if prescan will run before next connection. Implementation: Dynamic iwpriv_prescan_option_set To run prescan or not. Implementation: Dynamic iwpriv_set This is function iwpriv_set. iwpriv_adhocctx_set Sets the Ad hoc network context information. Implementation: Dynamic iwpriv_config_read Reads the Wi-Fi context configuration. Implementation: Dynamic f) Data Types and Constants Name Description IWPRIV_CONN_STATUS This is type IWPRIV_CONN_STATUS. IWPRIV_STATUS This is type IWPRIV_STATUS. IWPRIV_CMD This is type IWPRIV_CMD. IWPRIV_EXECUTE_PARAM This is type IWPRIV_EXECUTE_PARAM. IWPRIV_GET_PARAM This is type IWPRIV_GET_PARAM. IWPRIV_PARAM_CLIENTINFO This is type IWPRIV_PARAM_CLIENTINFO. IWPRIV_PARAM_CONTEXT This is type IWPRIV_PARAM_CONTEXT. IWPRIV_PARAM_DEVICEINFO This is type IWPRIV_PARAM_DEVICEINFO. IWPRIV_SCAN_STATUS This is type IWPRIV_SCAN_STATUS. IWPRIV_SET_PARAM This is type IWPRIV_SET_PARAM. IWPRIV_PARAM_CONFIG This is type IWPRIV_PARAM_CONFIG. IWPRIV_PARAM_CONNECT This is type IWPRIV_PARAM_CONNECT. IWPRIV_PARAM_DRIVERSTATUS This is type IWPRIV_PARAM_DRIVERSTATUS. IWPRIV_PARAM_FWUPGRADE This is type IWPRIV_PARAM_FWUPGRADE. IWPRIV_PARAM_MULTICASTFILTER This is type IWPRIV_PARAM_MULTICASTFILTER. IWPRIV_PARAM_NETWORKTYPE This is type IWPRIV_PARAM_NETWORKTYPE. IWPRIV_PARAM_OPERATIONMODE This is type IWPRIV_PARAM_OPERATIONMODE. IWPRIV_PARAM_POWERSAVE This is type IWPRIV_PARAM_POWERSAVE. IWPRIV_PARAM_SCAN This is type IWPRIV_PARAM_SCAN. IWPRIV_PARAM_SSID This is type IWPRIV_PARAM_SSID. Description This section describes the Application Programming Interface (API) functions of the MRF24WN Wi-Fi Driver. Refer to each section for a detailed description. a) Wi-Fi Initialization Functions Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1358 WDRV_SPI_In Function Receives data from the module through the SPI bus. Implementation: Dynamic File wdrv_mrf24wn_api.h C void WDRV_SPI_In(uint8_t *const OutBuf, uint16_t OutSize, uint8_t *const InBuf, uint16_t InSize); Returns None. Description This function receives data from the module through the SPI bus. Remarks None. Preconditions The TCP/IP stack should be initialized. Parameters Parameters Description bufOut buffer pointer of output command OutSize the command size InBuf buffer pointer of input data InSize the input data size Function void WDRV_SPI_In(uint8_t const *const OutBuf, uint16_t OutSize, uint8_t *const InBuf, uint16_t InSize) WDRV_SPI_Out Function Sends data out to the module through the SPI bus. Implementation: Dynamic File wdrv_mrf24wn_api.h C void WDRV_SPI_Out(uint8_t *const bufOut, uint16_t OutSize); Returns None. Description This function sends data out to the module through the SPI bus. Remarks None. Preconditions The TCP/IP stack should be initialized. Parameters Parameters Description bufOut buffer pointer of output data Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1359 OutSize the data size Function void WDRV_SPI_Out(uint8_t const *const bufOut, uint16_t OutSize) WDRV_GPIO_Init Function Initializes the GPIO objects for the Wi-Fi driver. Implementation: Dynamic File wdrv_mrf24wn_api.h C void WDRV_GPIO_Init(); Returns None. Description This function initializes the GPIO objects for the Wi-Fi driver. Remarks None. Preconditions The TCP/IP stack should be initialized. Function void WDRV_GPIO_Init(void) WDRV_GPIO_PowerOff Function Powers off the MRF24WN module. Implementation: Dynamic File wdrv_mrf24wn_api.h C void WDRV_GPIO_PowerOff(); Returns None. Description This function powers off the MRF24WN module. Remarks None. Preconditions The TCP/IP stack should be initialized. Function void WDRV_GPIO_PowerOff(void) WDRV_GPIO_PowerOn Function Powers on the MRF24WN module. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1360 File wdrv_mrf24wn_api.h C void WDRV_GPIO_PowerOn(); Returns None. Description This function powers on the MRF24WN module. Remarks None. Preconditions The TCP/IP stack should be initialized. Function void WDRV_GPIO_PowerOn(void) WDRV_IsPowerOff Function Checks if MRF24WN is turned off. Implementation: Dynamic File wdrv_mrf24wn_api.h C bool WDRV_IsPowerOff(); Returns • 0 - Indicates that MRF24WN is turned off • Non-zero value - Indicates that MRF24WN is on Description This function checks if MRF24WN is turned off. Remarks None. Function bool WDRV_IsPowerOff(void) WDRV_MRF24WN_ISR Function Wi-Fi driver (MRF24WN-specific) interrupt service routine. Implementation: Dynamic File wdrv_mrf24wn_api.h C void WDRV_MRF24WN_ISR(); Returns None. Description This function is the Wi-Fi driver (MRF24WN-specific) interrupt service routine. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1361 Remarks None. Preconditions Wi-Fi initialization must be complete. Function void WDRV_MRF24WN_ISR(void) b) Wi-Fi Status Functions WDRV_EXT_CmdConnectContextChannelGet Function Gets the AP channel Implementation: Dynamic File wdrv_mrf24wn_api.h C uint32_t WDRV_EXT_CmdConnectContextChannelGet(uint16_t * bssChannel); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description This function gets the current AP channel. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description bssChannel pointer where the current AP channel will be written Function uint32_t WDRV_EXT_CmdConnectContextChannelGet(uint16_t *bssChannel) WDRV_EXT_CmdPowerSaveGet Function Retrieves current power save status. Implementation: Dynamic File wdrv_mrf24wn_api.h C uint32_t WDRV_EXT_CmdPowerSaveGet(bool * enabled); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description This function retrieves the current power save status. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1362 Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description enabled pointer where the current power save status will be written Function uint32_t WDRV_EXT_CmdPowerSaveGet(bool *enabled) WDRV_EXT_ScanResultGet Function Reads the selected scan results back from the MRF24WN module. Implementation: Dynamic File wdrv_mrf24wn_api.h C void WDRV_EXT_ScanResultGet(uint16_t idx, WDRV_SCAN_RESULT * p_scanResult); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description After a scan has completed this function is used to read one scan result at a time from the MRF24WN module. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description listIndex index (0 based list) of the scan entry to retrieve p_scanResult pointer to where scan result is written Function void WDRV_EXT_ScanResultGet(uint8_t listIndex, WDRV_SCAN_RESULT *p_scanResult) c) External Functions WDRV_EXT_CmdNetModeIBSSSet Function Sets the Wi-Fi network type to Adhoc. Implementation: Dynamic File wdrv_mrf24wn_api.h C uint32_t WDRV_EXT_CmdNetModeIBSSSet(); Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1363 Returns • 0 - Indicates success • Non-zero value - Indicates failure Description This function sets the Wi-Fi network type to Adhoc. Remarks None. Preconditions Wi-Fi initialization must be complete. Function uint32_t WDRV_EXT_CmdNetModeIBSSSet(void) WDRV_EXT_CmdSecWPA2Set Function Sets Wi-Fi security to WPA2. Implementation: Dynamic File wdrv_mrf24wn_api.h C uint32_t WDRV_EXT_CmdSecWPA2Set(uint8_t * key, uint16_t len); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description This function sets the Wi-Fi security to WPA2. One can only connect to an AP that is running the same WPA2 mode. Remarks None. Preconditions Wi-Fi initialization must be complete and in an unconnected state. Parameters Parameters Description key pointer to the WPA2 key buffer len WPA2 key length Function uint32_t WDRV_EXT_CmdSecWPA2Set(uint8_t *key, uint16_t len) WDRV_EXT_Initialize Function Initializes the MRF24WN Wi-Fi driver. Implementation: Dynamic File wdrv_mrf24wn_api.h C int32_t WDRV_EXT_Initialize(const WDRV_CALLBACKS *const CB); Returns • 0 - Indicates success Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1364 • non-zero value - Indicates failure Description This function initializes the MRF24WN Wi-Fi driver, making it ready for clients to use. Remarks None. Preconditions None. Parameters Parameters Description CB pointer to callback functions Function int32_t WDRV_EXT_Initialize(const WDRV_CALLBACKS *const CB) WDRV_EXT_Initialize Function Initializes the WINC1500 Wi-Fi driver. Implementation: Dynamic File wdrv_winc1500_api.h C void WDRV_EXT_Initialize(const WDRV_HOOKS *const ehooks, bool initWait); Returns None. Description This function initializes the WINC1500 Wi-Fi driver, making it ready for clients to use. Remarks None. Preconditions None. Parameters Parameters Description ehooks pointer to WDRV layer hooks initWait true will put WDRV in wait during initialization Function void WDRV_EXT_Initialize(const WDRV_HOOKS *const ehooks, bool initWait) WDRV_EXT_PrivConfig Function Configures g_wdrvext_priv parameter. Implementation: Dynamic File wdrv_mrf24wn_api.h C void WDRV_EXT_PrivConfig(uint32_t * config); Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1365 Returns None. Description This function configures g_wdrvext_priv parameter. Remarks None. Preconditions None. Parameters Parameters Description config pointer to the parameter array Function void WDRV_EXT_PrivConfig(uint32_t *config) d) GPIO Functions e) Private Configuration Functions iwpriv_config_write Function Writes to the Wi-Fi context configuration which is currently used by Wi-Fi driver. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C void iwpriv_config_write(void * wifi_cfg); Returns None. Description This function reads from a passed pointer, copies everything from it, and writes to the Wi-Fi context configuration, which is currently used by the Wi-Fi driver. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description wifi_cfg pointer to where the context configuration is stored Function void iwpriv_config_write(void *wifi_cfg) iwpriv_connstatus_get Function Gets the Wi-Fi connection status. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1366 File wdrv_mrf24wn_iwpriv.h C IWPRIV_CONN_STATUS iwpriv_connstatus_get(); Returns Status of current Wi-Fi connection. See the definition for the IWPRIV_CONN_STATUS structure. Description This function gets the Wi-Fi connection status. Remarks IWPRIV_CONNECTION_FAILED does not necessarily mean that the module fails to connect to the network. It stands on the application's perspective, and actually can be customized. For example, in the Web Server demonstrations's use case, WDRV_CSTATE_CONNECTION_PERMANENTLY_LOST is treated as a fail case and will trigger the application to restart. Preconditions Wi-Fi initialization must be complete. Function IWPRIV_CONN_STATUS iwpriv_connstatus_get(void) iwpriv_devinfo_get Function Gets the device information. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C void iwpriv_devinfo_get(void * info); Returns None. Description This function returns the device information. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description info pointer to where the device information is written Function void iwpriv_devinfo_get(void *info) iwpriv_initialconn_set Function Sets the initial connection status of Wi-Fi driver. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1367 C void iwpriv_initialconn_set(bool connect); Returns None. Description This function sets the initial connection status of Wi-Fi driver. After Wi-Fi initialization, it decides whether or not to start the Wi-Fi connection. Remarks This function is mainly used to implement prescan. It has to be called before Wi-Fi driver's initialization is finished to be effective. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description connect boolean value which indicates whether or not to start an initial connect Function void iwpriv_initialconn_set(bool connect) iwpriv_initstatus_get Function Gets the initialization status of Wi-Fi driver. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C uint8_t iwpriv_initstatus_get(); Returns Current initialization status of the Wi-Fi driver (IWPRIV_READY or IWPRIV_IN_PROGRESS). Description This function returns the initialization status of the Wi-Fi driver. Remarks None. Preconditions None. Function uint8_t iwpriv_initstatus_get(void) iwpriv_is_servermode Function Checks if the passed Wi-Fi context configuration is operating in server mode. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C bool iwpriv_is_servermode(); Returns • true - Wi-Fi context configuration is operating in server mode Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1368 • false - Wi-Fi context configuration is not operating in server mode Description This function checks if the passed Wi-Fi context configuration is operating in server mode, which includes Ad hoc mode and SoftAP mode. Remarks None. Preconditions Wi-Fi initialization must be complete. Function bool iwpriv_is_servermode(void) iwpriv_leftclient_get Function Gets the left client's information. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C void iwpriv_leftclient_get(bool * updated, TCPIP_MAC_ADDR * addr); Returns None. Description This function returns the left client's information when the Wi-Fi module works in server mode and has the DHCP Server enabled. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description updated if the left client's information needs to be updated addr MAC address of the left client Function void iwpriv_leftclient_get(bool *updated, TCPIP_MAC_ADDR *addr) iwpriv_mcastfilter_set Function Adds a MAC address to the multi-cast filter. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C IWPRIV_STATUS iwpriv_mcastfilter_set(uint8_t * addr); Returns Status of the set operation, IWPRIV_READY or IWPRIV_ERROR. See definition for the IWPRIV_STATUS structure. Description This function adds a MAC address to the multi-cast filter. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1369 Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description addr pointer to where the MAC address is stored Function IWPRIV_STATUS iwpriv_mcastfilter_set(uint8_t *addr) iwpriv_nettype_get Function Gets the current network type. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C void iwpriv_nettype_get(uint8_t * netType); Returns None. Description This function returns the current network type. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description netType pointer to where the network type is written Function void iwpriv_nettype_get(uint8_t *netType) iwpriv_nettype_set Function Sets the current network type. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C void iwpriv_nettype_set(uint8_t netType); Returns None. Description This function sets the current network type. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1370 Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description netType the network type to set Function void iwpriv_nettype_set(uint8_t netType) iwpriv_numberofscanresults_get Function Gets the number of scan results. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C uint16_t iwpriv_numberofscanresults_get(); Returns Number of scan results. Description This function gets the number of scan results. Remarks None. Preconditions Wi-Fi initialization must be complete. Function uint16_t iwpriv_numberofscanresults_get(void) iwpriv_powersave_config Function Enables or disables Power Save mode in Wi-Fi driver. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C void iwpriv_powersave_config(bool enabled); Returns None. Description This function enables or disables Power Save mode in Wi-Fi driver, which depends on the passed boolean value. Remarks None. Preconditions Wi-Fi initialization must be complete. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1371 Parameters Parameters Description enabled boolean value which indicates to enable or disable Power Save mode in Wi-Fi driver Function void iwpriv_powersave_config(bool enabled) iwpriv_prescan_start Function Starts prescan. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C void iwpriv_prescan_start(); Returns None. Description This function directs the Wi-Fi driver to start a prescan. Remarks None. Preconditions Wi-Fi initialization must be complete. Function void iwpriv_prescan_start(void) iwpriv_scan_start Function Starts scan. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C void iwpriv_scan_start(); Returns None. Description The function starts a Wi-Fi scan. Remarks None. Preconditions Wi-Fi initialization must be complete. Function void iwpriv_scan_start(void) Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1372 iwpriv_scanstatus_get Function Gets the prescan status. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C IWPRIV_SCAN_STATUS iwpriv_scanstatus_get(); Returns Prescan status: IWPRIV_SCAN_IDLE, IWPRIV_SCAN_IN_PROGRESS, IWPRIV_SCAN_NO_AP_FOUND or IWPRIV_SCAN_SUCCESSFUL. See the definition for the IWPRIV_SCAN_STATUS structure. Description This function gets the prescan status. Remarks None. Preconditions Wi-Fi initialization must be complete. Function IWPRIV_SCAN_STATUS iwpriv_scanstatus_get(void) iwpriv_ssid_get Function Gets the current SSID. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C void iwpriv_ssid_get(uint8_t * ssid, uint8_t * ssidLen); Returns None. Description This function returns the current SSID. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description ssid pointer to where the SSID is written ssidLen pointer to where the SSID length is written Function void iwpriv_ssid_get(uint8_t *ssid, uint8_t *ssidLen) Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1373 iwpriv_ssid_set Function Sets the current SSID. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C void iwpriv_ssid_set(uint8_t * ssid, uint8_t ssidLen); Returns None. Description This function sets the current SSID. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description ssid pointer to where the SSID is stored ssidLen pointer to where the SSID length is stored Function void iwpriv_ssid_set(uint8_t *ssid, uint8_t ssidLen) iwpriv_execute Function File wdrv_mrf24wn_iwpriv.h C void iwpriv_execute(IWPRIV_CMD cmd, IWPRIV_EXECUTE_PARAM * params); Description This is function iwpriv_execute. iwpriv_get Function File wdrv_mrf24wn_iwpriv.h C void iwpriv_get(IWPRIV_CMD cmd, IWPRIV_GET_PARAM * params); Description This is function iwpriv_get. iwpriv_prescan_isfinished Function Checks if the prescan is complete. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1374 File wdrv_mrf24wn_iwpriv.h C bool iwpriv_prescan_isfinished(); Returns None. Description This function checks if the prescan is complete. Remarks None. Preconditions Wi-Fi initialization must be complete. Function bool iwpriv_prescan_isfinished(void) iwpriv_prescan_option_get Function To see if prescan will run before next connection. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C bool iwpriv_prescan_option_get(); Returns None. Description This function checks whether or not the prescan will run before next connection. Remarks None. Preconditions Wi-Fi initialization must be complete. Function bool iwpriv_prescan_option_get(void) iwpriv_prescan_option_set Function To run prescan or not. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C void iwpriv_prescan_option_set(bool scan); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1375 Description This function controls whether or not to run prescan. Remarks Prescan means the scan runs before the module is connected. It needs to use multiple functions in this file. Please refer to the Easy Configuration demonstration to see the correct usage of prescan. After the the module is connected, MRF24WN module can also do regular scans. But it cannot perform a scan when the connection is in progress. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description scan true: run prescan before next connection false do not run prescan before next connection Function void iwpriv_prescan_option_set(bool scan) iwpriv_set Function File wdrv_mrf24wn_iwpriv.h C void iwpriv_set(IWPRIV_CMD cmd, IWPRIV_SET_PARAM * params); Description This is function iwpriv_set. iwpriv_adhocctx_set Function Sets the Ad hoc network context information. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C void iwpriv_adhocctx_set(void * p_cxt); Returns None. Description This function sets the current Ad hoc network context information by reading from a passed pointer. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description p_cxt pointer to where the Ad hoc network context is stored Function void iwpriv_adhocctx_set(void *p_cxt) Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1376 iwpriv_config_read Function Reads the Wi-Fi context configuration. Implementation: Dynamic File wdrv_mrf24wn_iwpriv.h C void iwpriv_config_read(void * wifi_cfg); Returns None. Description This function reads the current Wi-Fi context configuration, copies and stores the whole structure to the pointer passed to the function. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description wifi_cfg pointer to where the context configuration is written Function void iwpriv_config_read(void *wifi_cfg) f) Data Types and Constants IWPRIV_CONN_STATUS Enumeration File wdrv_mrf24wn_iwpriv.h C typedef enum { IWPRIV_CONNECTION_FAILED = -1, IWPRIV_CONNECTION_SUCCESSFUL, IWPRIV_CONNECTION_IDLE, IWPRIV_CONNECTION_IN_PROGRESS, IWPRIV_CONNECTION_REESTABLISHED } IWPRIV_CONN_STATUS; Description This is type IWPRIV_CONN_STATUS. IWPRIV_STATUS Enumeration File wdrv_mrf24wn_iwpriv.h C typedef enum { IWPRIV_ERROR = -1, IWPRIV_READY, IWPRIV_IN_PROGRESS } IWPRIV_STATUS; Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1377 Description This is type IWPRIV_STATUS. IWPRIV_CMD Enumeration File wdrv_mrf24wn_iwpriv.h C typedef enum { PRESCAN_OPTION_GET, PRESCAN_OPTION_SET, PRESCAN_START, PRESCAN_ISFINISHED_GET, SCAN_START, SCANSTATUS_GET, SCANRESULT_GET, SCANRESULTS_COUNT_GET, CONFIG_GET, CONFIG_SET, SSID_GET, SSID_SET, NETWORKTYPE_GET, NETWORKTYPE_SET, CONNSTATUS_GET, CLIENTINFO_GET, DEVICEINFO_GET, DRVSTATUS_GET, FWUPGRADEREQUEST_GET, OPERATIONMODE_GET, INITCONN_OPTION_SET, ADHOCCTX_SET, MULTICASTFILTER_SET, POWERSAVE_SET } IWPRIV_CMD; Description This is type IWPRIV_CMD. IWPRIV_EXECUTE_PARAM Union File wdrv_mrf24wn_iwpriv.h C typedef union { } IWPRIV_EXECUTE_PARAM; Description This is type IWPRIV_EXECUTE_PARAM. IWPRIV_GET_PARAM Union File wdrv_mrf24wn_iwpriv.h C typedef union { IWPRIV_PARAM_SCAN scan; IWPRIV_PARAM_CONFIG cfg; IWPRIV_PARAM_SSID ssid; IWPRIV_PARAM_NETWORKTYPE netType; IWPRIV_PARAM_CONNECT conn; IWPRIV_PARAM_CLIENTINFO clientInfo; IWPRIV_PARAM_DEVICEINFO devInfo; Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1378 IWPRIV_PARAM_DRIVERSTATUS driverStatus; IWPRIV_PARAM_FWUPGRADE fwUpgrade; IWPRIV_PARAM_OPERATIONMODE opMode; } IWPRIV_GET_PARAM; Description This is type IWPRIV_GET_PARAM. IWPRIV_PARAM_CLIENTINFO Structure File wdrv_mrf24wn_iwpriv.h C typedef struct { uint8_t * addr; bool updated; } IWPRIV_PARAM_CLIENTINFO; Members Members Description uint8_t * addr; it usually points to a MAC address, which is an array of 6 uint8_t elements Description This is type IWPRIV_PARAM_CLIENTINFO. IWPRIV_PARAM_CONTEXT Structure File wdrv_mrf24wn_iwpriv.h C typedef struct { void * context; } IWPRIV_PARAM_CONTEXT; Description This is type IWPRIV_PARAM_CONTEXT. IWPRIV_PARAM_DEVICEINFO Structure File wdrv_mrf24wn_iwpriv.h C typedef struct { void * info; } IWPRIV_PARAM_DEVICEINFO; Description This is type IWPRIV_PARAM_DEVICEINFO. IWPRIV_SCAN_STATUS Enumeration File wdrv_mrf24wn_iwpriv.h C typedef enum { IWPRIV_SCAN_SUCCESSFUL, IWPRIV_SCAN_IDLE, IWPRIV_SCAN_IN_PROGRESS, Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1379 IWPRIV_SCAN_NO_AP_FOUND } IWPRIV_SCAN_STATUS; Description This is type IWPRIV_SCAN_STATUS. IWPRIV_SET_PARAM Union File wdrv_mrf24wn_iwpriv.h C typedef union { IWPRIV_PARAM_SCAN scan; IWPRIV_PARAM_CONFIG cfg; IWPRIV_PARAM_SSID ssid; IWPRIV_PARAM_NETWORKTYPE netType; IWPRIV_PARAM_CONNECT conn; IWPRIV_PARAM_CONTEXT ctx; IWPRIV_PARAM_MULTICASTFILTER multicast; IWPRIV_PARAM_POWERSAVE powerSave; } IWPRIV_SET_PARAM; Description This is type IWPRIV_SET_PARAM. IWPRIV_PARAM_CONFIG Structure File wdrv_mrf24wn_iwpriv.h C typedef struct { void * config; } IWPRIV_PARAM_CONFIG; Description This is type IWPRIV_PARAM_CONFIG. IWPRIV_PARAM_CONNECT Structure File wdrv_mrf24wn_iwpriv.h C typedef struct { bool initConnAllowed; IWPRIV_CONN_STATUS status; } IWPRIV_PARAM_CONNECT; Description This is type IWPRIV_PARAM_CONNECT. IWPRIV_PARAM_DRIVERSTATUS Structure File wdrv_mrf24wn_iwpriv.h C typedef struct { bool isOpen; } IWPRIV_PARAM_DRIVERSTATUS; Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1380 Description This is type IWPRIV_PARAM_DRIVERSTATUS. IWPRIV_PARAM_FWUPGRADE Structure File wdrv_mrf24wn_iwpriv.h C typedef struct { bool requested; } IWPRIV_PARAM_FWUPGRADE; Description This is type IWPRIV_PARAM_FWUPGRADE. IWPRIV_PARAM_MULTICASTFILTER Structure File wdrv_mrf24wn_iwpriv.h C typedef struct { uint8_t * addr; IWPRIV_STATUS status; } IWPRIV_PARAM_MULTICASTFILTER; Members Members Description uint8_t * addr; it usually points to a MAC address, which is an array of 6 uint8_t elements Description This is type IWPRIV_PARAM_MULTICASTFILTER. IWPRIV_PARAM_NETWORKTYPE Structure File wdrv_mrf24wn_iwpriv.h C typedef struct { uint8_t type; } IWPRIV_PARAM_NETWORKTYPE; Description This is type IWPRIV_PARAM_NETWORKTYPE. IWPRIV_PARAM_OPERATIONMODE Structure File wdrv_mrf24wn_iwpriv.h C typedef struct { bool isServer; } IWPRIV_PARAM_OPERATIONMODE; Description This is type IWPRIV_PARAM_OPERATIONMODE. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1381 IWPRIV_PARAM_POWERSAVE Structure File wdrv_mrf24wn_iwpriv.h C typedef struct { bool enabled; } IWPRIV_PARAM_POWERSAVE; Description This is type IWPRIV_PARAM_POWERSAVE. IWPRIV_PARAM_SCAN Structure File wdrv_mrf24wn_iwpriv.h C typedef struct { bool prescanAllowed; bool prescanFinished; IWPRIV_SCAN_STATUS scanStatus; uint16_t numberOfResults; uint16_t index; WDRV_SCAN_RESULT * result; } IWPRIV_PARAM_SCAN; Description This is type IWPRIV_PARAM_SCAN. IWPRIV_PARAM_SSID Structure File wdrv_mrf24wn_iwpriv.h C typedef struct { uint8_t * ssid; uint8_t ssidLen; } IWPRIV_PARAM_SSID; Description This is type IWPRIV_PARAM_SSID. Files Files Name Description wdrv_mrf24wn_api.h MRF24WN Interface Functions wdrv_mrf24wn_iwpriv.h Configure optional (private) parameters of MRF24WN driver. Description This section lists the source and header files used by the MRF24WN Wi-Fi Driver Library. wdrv_mrf24wn_api.h MRF24WN Interface Functions Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1382 Functions Name Description WDRV_EXT_CmdConnectContextChannelGet Gets the AP channel Implementation: Dynamic WDRV_EXT_CmdNetModeIBSSSet Sets the Wi-Fi network type to Adhoc. Implementation: Dynamic WDRV_EXT_CmdPowerSaveGet Retrieves current power save status. Implementation: Dynamic WDRV_EXT_CmdSecWPA2Set Sets Wi-Fi security to WPA2. Implementation: Dynamic WDRV_EXT_Initialize Initializes the MRF24WN Wi-Fi driver. Implementation: Dynamic WDRV_EXT_PrivConfig Configures g_wdrvext_priv parameter. Implementation: Dynamic WDRV_EXT_ScanResultGet Reads the selected scan results back from the MRF24WN module. Implementation: Dynamic WDRV_GPIO_DeInit Deinitializes the GPIO objects for the Wi-Fi driver. Implementation: Dynamic WDRV_GPIO_Init Initializes the GPIO objects for the Wi-Fi driver. Implementation: Dynamic WDRV_GPIO_PowerOff Powers off the MRF24WN module. Implementation: Dynamic WDRV_GPIO_PowerOn Powers on the MRF24WN module. Implementation: Dynamic WDRV_INTR_Deinit Deinitializes interrupts for Wi-Fi driver. Implementation: Dynamic WDRV_INTR_Init Initializes interrupts for the Wi-Fi driver. Implementation: Dynamic WDRV_INTR_SourceDisable Disables interrupts from the module. Implementation: Dynamic WDRV_INTR_SourceEnable Enables interrupts from the module. Implementation: Dynamic WDRV_IsPowerOff Checks if MRF24WN is turned off. Implementation: Dynamic WDRV_MRF24WN_ISR Wi-Fi driver (MRF24WN-specific) interrupt service routine. Implementation: Dynamic WDRV_SPI_Deinit Deinitializes the SPI object for the Wi-Fi driver. Implementation: Dynamic WDRV_SPI_In Receives data from the module through the SPI bus. Implementation: Dynamic WDRV_SPI_Init Initializes the SPI object for the Wi-Fi driver. Implementation: Dynamic WDRV_SPI_Out Sends data out to the module through the SPI bus. Implementation: Dynamic Description MRF24WN Interface Functions File Name wdrv_mrf24wn_api.h Company Microchip Technology Inc. wdrv_mrf24wn_iwpriv.h Configure optional (private) parameters of MRF24WN driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1383 Enumerations Name Description IWPRIV_CMD This is type IWPRIV_CMD. IWPRIV_CONN_STATUS This is type IWPRIV_CONN_STATUS. IWPRIV_SCAN_STATUS This is type IWPRIV_SCAN_STATUS. IWPRIV_STATUS This is type IWPRIV_STATUS. Functions Name Description iwpriv_adhocctx_set Sets the Ad hoc network context information. Implementation: Dynamic iwpriv_config_read Reads the Wi-Fi context configuration. Implementation: Dynamic iwpriv_config_write Writes to the Wi-Fi context configuration which is currently used by Wi-Fi driver. Implementation: Dynamic iwpriv_connstatus_get Gets the Wi-Fi connection status. Implementation: Dynamic iwpriv_devinfo_get Gets the device information. Implementation: Dynamic iwpriv_execute This is function iwpriv_execute. iwpriv_get This is function iwpriv_get. iwpriv_initialconn_set Sets the initial connection status of Wi-Fi driver. Implementation: Dynamic iwpriv_initstatus_get Gets the initialization status of Wi-Fi driver. Implementation: Dynamic iwpriv_is_servermode Checks if the passed Wi-Fi context configuration is operating in server mode. Implementation: Dynamic iwpriv_leftclient_get Gets the left client's information. Implementation: Dynamic iwpriv_mcastfilter_set Adds a MAC address to the multi-cast filter. Implementation: Dynamic iwpriv_nettype_get Gets the current network type. Implementation: Dynamic iwpriv_nettype_set Sets the current network type. Implementation: Dynamic iwpriv_numberofscanresults_get Gets the number of scan results. Implementation: Dynamic iwpriv_powersave_config Enables or disables Power Save mode in Wi-Fi driver. Implementation: Dynamic iwpriv_prescan_isfinished Checks if the prescan is complete. Implementation: Dynamic iwpriv_prescan_option_get To see if prescan will run before next connection. Implementation: Dynamic iwpriv_prescan_option_set To run prescan or not. Implementation: Dynamic iwpriv_prescan_start Starts prescan. Implementation: Dynamic iwpriv_scan_start Starts scan. Implementation: Dynamic iwpriv_scanstatus_get Gets the prescan status. Implementation: Dynamic iwpriv_set This is function iwpriv_set. iwpriv_ssid_get Gets the current SSID. Implementation: Dynamic iwpriv_ssid_set Sets the current SSID. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1384 Structures Name Description IWPRIV_PARAM_CLIENTINFO This is type IWPRIV_PARAM_CLIENTINFO. IWPRIV_PARAM_CONFIG This is type IWPRIV_PARAM_CONFIG. IWPRIV_PARAM_CONNECT This is type IWPRIV_PARAM_CONNECT. IWPRIV_PARAM_CONTEXT This is type IWPRIV_PARAM_CONTEXT. IWPRIV_PARAM_DEVICEINFO This is type IWPRIV_PARAM_DEVICEINFO. IWPRIV_PARAM_DRIVERSTATUS This is type IWPRIV_PARAM_DRIVERSTATUS. IWPRIV_PARAM_FWUPGRADE This is type IWPRIV_PARAM_FWUPGRADE. IWPRIV_PARAM_MULTICASTFILTER This is type IWPRIV_PARAM_MULTICASTFILTER. IWPRIV_PARAM_NETWORKTYPE This is type IWPRIV_PARAM_NETWORKTYPE. IWPRIV_PARAM_OPERATIONMODE This is type IWPRIV_PARAM_OPERATIONMODE. IWPRIV_PARAM_POWERSAVE This is type IWPRIV_PARAM_POWERSAVE. IWPRIV_PARAM_SCAN This is type IWPRIV_PARAM_SCAN. IWPRIV_PARAM_SSID This is type IWPRIV_PARAM_SSID. Unions Name Description IWPRIV_EXECUTE_PARAM This is type IWPRIV_EXECUTE_PARAM. IWPRIV_GET_PARAM This is type IWPRIV_GET_PARAM. IWPRIV_SET_PARAM This is type IWPRIV_SET_PARAM. Description MRF24WN Private Configuration Support Functions in this module support the connection process for the MRF24WN. File Name wdrv_mrf24wn_iwpriv.h Company Microchip Technology Inc. WILC1000 Wi-Fi Driver Ethernet Mode Library This topic describes the WILC1000 Wi-Fi Driver Library. Introduction This library provides a low-level abstraction of the WILC1000 Wi-Fi Driver 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. Note: The WILC1000 Wi-Fi Driver is compatible with the WILC1000 PICtail/PICtail Plus Daughter Board with WILC1000 firmware version 4.2.3 and later in "Ethernet mode". Description The Wi-Fi software library, in conjunction with the WILC1000 module, allows an application to: • Join an existing 802.11 Wi-Fi network • Create a 802.11 Wi-Fi network The following application services are provided by the Wi-Fi library: • Configure a Wi-Fi connection (SSID, security mode, and so on) • Join an existing network or create a "Soft-AP" Wi-Fi network • Scan for other Wi-Fi devices in the area • Receive Wi-Fi network status • Wi-Fi power control The MAC_layer services are not directly accessible to the application. This portion of the code resides under the TCP/IP Stack MAC module software layers and is used by stack services to transmit and receive data over a Wi-Fi network. The following diagram shows the interaction of the Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1385 primary software blocks in a Wi-Fi application. Wi-Fi Software Block Diagram The following table provides information that includes network mode and security mode support by the WILC1000 Wi-Fi Driver. Using the Library This topic describes the basic architecture of the WILC1000 Wi-Fi Driver Library and provides information and examples on its use. Description Interface Header Files: wdrv_wilc1000_api.h and wdrv_wilc1000_stub.h The interface to the WILC1000 Wi-Fi Driver Library is defined in the wdrv_wilc1000_api.h and wdrv_wilc1000_stub.h header files. Please refer to the Understanding MPLAB Harmony section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the WILC1000 Wi-Fi module with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The WILC1000 Wi-Fi Library provides the following functionality: • Wi-Fi library initialization • Wi-Fi network configuration • Wi-Fi network connection • Scanning for existing Wi-Fi networks Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1386 • Wi-Fi event processing • Wi-Fi status • Wi-FI console commands Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. TheLibrary Interface functions are divided into various sub-sections, which address one of the blocks or the overall operation of the Wi-Fi module. Library Interface Section Description Wi-Fi Initialization Functions This section provides functions that initialize the Wi-Fi library and allow its API to be used. Wi-Fi Status Functions This section provides functions that retrieve the Wi-Fi connection status. Wi-Fi External Functions This section provides public functions accessible to TCP/IP applications. Other Functions This section provides additional miscellaneous functions for configuring the Wi-Fi connection. Data Types and Constants This section provides data types and macros. How the Library Works This section describes how the WILC1000 Wi-Fi Driver Library operates. Description Before the driver is ready for use, it should be configured (compile time configuration). There are a few run-time configuration items that are done during initialization of the driver instance, and a few that are client-specific and are done using dedicated functions. To use the WILC1000 Wi-Fi Driver, initialization and client functions should be invoked in a specific sequence to ensure correct operation. Configuring the Library This section describes how to configure the WILC1000 Wi-Fi driver. Description The configuration of the WILC1000 Wi-Fi Driver is based on the file system_config.h. This header file contains the configuration selection for the Wi-Fi Driver. Based on the selections made, the WILC1000 Wi-Fi Driver may support the selected features. These configuration settings will apply to all instances of the WILC1000 Wi-Fi Driver. 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. Sample Functionality The following code provides an example of Wi-Fi Driver configuration. (refer to system.config.h) /*** SPI Driver Configuration ***/ #define DRV_SPI_NUMBER_OF_MODULES 4 /*** Driver Compilation and static configuration options. ***/ /*** Select SPI compilation units.***/ #define DRV_SPI_POLLED 0 #define DRV_SPI_ISR 1 #define DRV_SPI_MASTER 1 #define DRV_SPI_SLAVE 0 #define DRV_SPI_RM 1 #define DRV_SPI_EBM 0 #define DRV_SPI_8BIT 1 #define DRV_SPI_16BIT 0 #define DRV_SPI_32BIT 0 #define DRV_SPI_DMA 1 /*** SPI Driver Static Allocation Options ***/ #define DRV_SPI_INSTANCES_NUMBER 1 #define DRV_SPI_CLIENTS_NUMBER 1 #define DRV_SPI_ELEMENTS_PER_QUEUE 10 /*** SPI Driver DMA Options ***/ Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1387 #define DRV_SPI_DMA_TXFER_SIZE 512 #define DRV_SPI_DMA_DUMMY_BUFFER_SIZE 512 /* SPI Driver Instance 0 Configuration */ #define DRV_SPI_SPI_ID_IDX0 SPI_ID_1 #define DRV_SPI_TASK_MODE_IDX0 DRV_SPI_TASK_MODE_ISR #define DRV_SPI_SPI_MODE_IDX0 DRV_SPI_MODE_MASTER #define DRV_SPI_ALLOW_IDLE_RUN_IDX0 false #define DRV_SPI_SPI_PROTOCOL_TYPE_IDX0 DRV_SPI_PROTOCOL_TYPE_STANDARD #define DRV_SPI_COMM_WIDTH_IDX0 SPI_COMMUNICATION_WIDTH_8BITS #define DRV_SPI_SPI_CLOCK_IDX0 CLK_BUS_PERIPHERAL_2 #define DRV_SPI_BAUD_RATE_IDX0 2000000 #define DRV_SPI_BUFFER_TYPE_IDX0 DRV_SPI_BUFFER_TYPE_STANDARD #define DRV_SPI_CLOCK_MODE_IDX0 DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_FALL #define DRV_SPI_INPUT_PHASE_IDX0 SPI_INPUT_SAMPLING_PHASE_AT_END #define DRV_SPI_TRANSMIT_DUMMY_BYTE_VALUE_IDX0 0x00 #define DRV_SPI_TX_INT_SOURCE_IDX0 INT_SOURCE_SPI_1_TRANSMIT #define DRV_SPI_RX_INT_SOURCE_IDX0 INT_SOURCE_SPI_1_RECEIVE #define DRV_SPI_ERROR_INT_SOURCE_IDX0 INT_SOURCE_SPI_1_ERROR #define DRV_SPI_INT_VECTOR_IDX0 INT_VECTOR_SPI1 #define DRV_SPI_INT_PRIORITY_IDX0 INT_PRIORITY_LEVEL1 #define DRV_SPI_INT_SUB_PRIORITY_IDX0 INT_SUBPRIORITY_LEVEL0 #define DRV_SPI_QUEUE_SIZE_IDX0 10 #define DRV_SPI_RESERVED_JOB_IDX0 1 #define DRV_SPI_TX_DMA_CHANNEL_IDX0 DMA_CHANNEL_1 #define DRV_SPI_TX_DMA_THRESHOLD_IDX0 16 #define DRV_SPI_RX_DMA_CHANNEL_IDX0 DMA_CHANNEL_0 #define DRV_SPI_RX_DMA_THRESHOLD_IDX0 16 /*** Timer Driver Configuration ***/ #define DRV_TMR_INTERRUPT_MODE true #define DRV_TMR_INSTANCES_NUMBER 1 #define DRV_TMR_CLIENTS_NUMBER 1 /*** Timer Driver 0 Configuration ***/ #define DRV_TMR_PERIPHERAL_ID_IDX0 TMR_ID_2 #define DRV_TMR_INTERRUPT_SOURCE_IDX0 INT_SOURCE_TIMER_2 #define DRV_TMR_INTERRUPT_VECTOR_IDX0 INT_VECTOR_T2 #define DRV_TMR_ISR_VECTOR_IDX0 _TIMER_2_VECTOR #define DRV_TMR_INTERRUPT_PRIORITY_IDX0 INT_PRIORITY_LEVEL4 #define DRV_TMR_INTERRUPT_SUB_PRIORITY_IDX0 INT_SUBPRIORITY_LEVEL0 #define DRV_TMR_CLOCK_SOURCE_IDX0 DRV_TMR_CLKSOURCE_INTERNAL #define DRV_TMR_PRESCALE_IDX0 TMR_PRESCALE_VALUE_256 #define DRV_TMR_OPERATION_MODE_IDX0 DRV_TMR_OPERATION_MODE_16_BIT #define DRV_TMR_ASYNC_WRITE_ENABLE_IDX0 false #define DRV_TMR_POWER_STATE_IDX0 SYS_MODULE_POWER_RUN_FULL /*** Wi-Fi Driver Configuration ***/ #define WILC1000_INT_SOURCE INT_SOURCE_CHANGE_NOTICE #define WILC1000_INT_VECTOR INT_VECTOR_CN #define WDRV_SPI_INDEX 0 #define WDRV_SPI_INSTANCE sysObj.spiObjectIdx0 #define WDRV_USE_SPI_DMA #define WDRV_NVM_SPACE_ENABLE #define WDRV_NVM_SPACE_ADDR (48 * 1024) #define WDRV_BOARD_TYPE WDRV_BD_TYPE_MX_ESK #define WDRV_EXT_RTOS_TASK_SIZE 2048u #define WDRV_EXT_RTOS_TASK_PRIORITY 2u // I/O mappings for general control pins, including CHIP_EN, IRQN, RESET_N and SPI_SSN. #define WDRV_CHIP_EN_PORT_CHANNEL PORT_CHANNEL_F #define WDRV_CHIP_EN_BIT_POS 1 Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1388 #define WDRV_IRQN_PORT_CHANNEL PORT_CHANNEL_G #define WDRV_IRQN_BIT_POS 7 #define WDRV_RESET_N_PORT_CHANNEL PORT_CHANNEL_F #define WDRV_RESET_N_BIT_POS 0 #define WDRV_SPI_SSN_PORT_CHANNEL PORT_CHANNEL_B #define WDRV_SPI_SSN_BIT_POS 2 #define WILC1000_ON_PIC32MX_ESK // On PIC32MX ESK, when CN9 (Pin G7) is used as external interrupt, // it is sometimes better to use another GPIO (Pin E0) to read CN9's value. // In this case, a jumper wire is needed to connect Pin E0 and Pin G7. //#define WDRV_VERIFY_IRQN_BY_ANOTHER_GPIO #if defined(WDRV_VERIFY_IRQN_BY_ANOTHER_GPIO) // Use Pin E0. Please also make sure that Pin E0 and Pin G7 are connected (by a jumper wire). #define WDRV_IRQN_PORT_CHANNEL_READ PORT_CHANNEL_E #define WDRV_IRQN_BIT_POS_READ 0 #else // Still directly read Pin G7's value. #define WDRV_IRQN_PORT_CHANNEL_READ PORT_CHANNEL_G #define WDRV_IRQN_BIT_POS_READ 7 #endif #define WDRV_DEFAULT_NETWORK_TYPE WDRV_NETWORK_TYPE_INFRASTRUCTURE #define WDRV_DEFAULT_CHANNEL 6 #define WDRV_DEFAULT_SSID "MicrochipDemoApp" #define WDRV_DEFAULT_SECURITY_MODE WDRV_SECURITY_OPEN #define WDRV_DEFAULT_WEP_KEYS_40 "5AFB6C8E77" // default WEP40 key #define WDRV_DEFAULT_WEP_KEYS_104 "90E96780C739409DA50034FCAA" // default WEP104 key #define WDRV_DEFAULT_PSK_PHRASE "Microchip 802.11 Secret PSK Password" // default WPA-PSK Building the Library This section lists the files that are available in the WILC1000 Wi-Fi Driver Library. 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 /framework/driver/wifi/wilc1000. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description wdrv_wilc1000_stub.h Contains Stub function prototypes for interfacing to the WILC1000 Wi-Fi Driver. wdrv_wilc1000_api.h Contains API function prototypes for interfacing to the WILC1000 Wi-Fi Driver. 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 wdrv_wilc1000_console.c Console module for the WILC1000 wireless driver. wdrv_wilc1000_fw_update.c WILC1000 firmware update support. wdrv_wilc1000_eint.c External interrupt handler for the WILC1000 wireless driver. wdrv_wilc1000_timer.c Timer functions for the WILC1000 wireless driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1389 wdrv_wilc1000_gpio.c WILC1000 GPIO support for SPI communication. wdrv_wilc1000_spi.c WILC1000 support for SPI communication. wdrv_wilc1000_cli.c WILC1000 driver CLI implementation. wdrv_wilc1000_config_data.c Stores and retrieves Wi-Fi configuration to/from non-volatile memory (NVM). wdrv_wilc1000_connmgr.c WILC1000 driver connection manager. wdrv_wilc1000_events.c WILC1000 driver MAC events. wdrv_wilc1000_iwpriv.c WILC1000 driver connection process functions. wdrv_wilc1000_main.c WILC1000 driver Microchip TCP/IP Stack PIC32 MAC support. wdrv_wilc1000_osal.c WILC1000 driver OS abstraction layer. wdrv_wilc1000_scan_helper.c WILC1000 driver scan helper functions. wdrext_wilc1000.c WILC1000 driver extended functions. wilc1000_task.c WILC1000 driver task handler. 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 N/A The WILC1000 Wi-Fi Driver controller has no optional files. Module Dependencies The WILC1000 Wi-Fi Driver Library depends on the following modules: • SPI Driver Library • NVM Driver Library • UART Driver Library • USB Driver Library • Operating System Abstraction Layer (OSAL) Library Help • Clock System Service Library • System Service Library Introduction • Console System Service Library • File System Service Library • Interrupt System Service Library • Timer System Service Library • Debug System Service Library • Ports System Service Library • FreeRTOS Library Help • Crypto Library • Peripheral Libraries • Networking Presentation Layer Help • TCP/IP Stack Library Help • Command Processor System Service Library • DMA System Service Library • Random Number Generator System Service Library • Common System Service Library • TCP/IP Ethernet MAC Driver Library Console Commands This section describes the console commands available for the WILC1000 Wi-Fi Driver. Description Both the Web Server and the EasyConfig demonstrations support the followings commands, which enable control over the Wi-Fi settings. Command: deleteconf Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1390 Parameters Description None. Wi-Fi console command to erase saved Wi-Fi configuration in memory. Command: iwconfig Parameters Description [ ssid ] name: Specifies the name of the SSID (1-32 ASCII characters). [ mode ] idle: Disconnected from the current configuration. managed: Connects in infrastructure mode to the currently set SSID. [ power ] enable: Enables all Power-Saving features (PS_POLL). Will wake up to check for all types of traffic (unicast, multicast, and broadcast). disable: Disables any Power-Saving features. Will always be in an active power state. [ security ] mode: open/wep40/wep104/wpa/wpa2/pin/pbc. For example: iwconfig security open iwconfig security wep40 iwconfig security wep104 iwconfig security wpa iwconfig security wpa2 iwconfig security pin iwconfig security pbc [ scan ] Starts a Wi-Fi scan. [ scanget ] scan_index: Retrieves the scan result after the scan completes (1 - n). Command: mac Parameters Description None. Wi-Fi console command to retrieve the MAC address of the MRF24WN module. Command: ota Parameters Description [ http://ip-address/ ] [ filename.bin ] Upgrade the WILC1000 firmware over-the-air. For example: http://192.168.0.4/winc1500_ota.bin Command: readconf Parameters Description None. Wi-Fi console command to read saved Wi-Fi configuration in memory. Command: saveconf Parameters Description None. Wi-Fi console command to save Wi-Fi configuration to memory. Library Interface This section describes the Application Programming Interface (API) functions of the WILC1000 Wi-Fi Driver. Refer to each section for a detailed description. a) Wi-Fi Initialization Functions b) Wi-Fi Status Functions Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1391 c) Wi-Fi External Functions d) Other Functions e) Data Types and Constants Files Files Name Description wdrv_wilc1000_api.h WILC1000 wireless driver APIs. wdrv_wilc1000_stub.h WILC1000 wireless driver stub APIs. Description This section lists the source and header files used by the MRF24WN Wi-Fi Driver Library. wdrv_wilc1000_api.h WILC1000 wireless driver APIs. Functions Name Description WDRV_EXT_CmdScanOptionSet Sets scan options. Implementation: Dynamic WDRV_EXT_CmdSSIDSet Sets the SSID. Implementation: Dynamic WDRV_EXT_Initialize Initializes the WILC1000 Wi-Fi driver. Implementation: Dynamic WDRV_EXT_ScanDoneSet Indicates when a scan has completed. Implementation: Dynamic WDRV_EXT_ScanIsInProgress Check whether host scan is now in progress or not. Implementation: Dynamic Description WILC1000 wireless driver APIs. File Name wdrv_wilc1000_api.h Company Microchip Technology Inc. wdrv_wilc1000_stub.h WILC1000 wireless driver stub APIs. Description WILC1000 wireless driver stub APIs. File Name wdrv_wilc1000_stub.h Company Microchip Technology Inc. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1392 WINC1500 Wi-Fi Driver Ethernet Mode Library This topic describes the WINC1500 Wi-Fi Driver Library. Introduction This library provides a low-level abstraction of the WINC1500 Wi-Fi Driver 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. Note: The WINC1500 Wi-Fi Driver is compatible with the WINC1500 PICtail/PICtail Plus Daughter board with WINC1500 firmware version 19.5.2 and later in "Ethernet mode". The driver will also work with WINC1500 firmware version 19.4.4 with limited backward compatibility. Description The Wi-Fi software library, in conjunction with the WINC1500 module, allows an application to: • Join an existing 802.11 Wi-Fi network • Create a 802.11 Wi-Fi network The following application services are provided by the Wi-Fi library: • Configure a Wi-Fi connection (SSID, security mode, and so on) • Join an existing network or create a "Soft-AP" Wi-Fi network • Scan for other Wi-Fi devices in the area • Receive Wi-Fi network status • Wi-Fi power control The MAC_layer services are not directly accessible to the application. This portion of the code resides under the TCP/IP Stack MAC module software layers and is used by stack services to transmit and receive data over a Wi-Fi network. The following diagram shows the interaction of the primary software blocks in a Wi-Fi application. Wi-Fi Software Block Diagram The following table provides information that includes network mode and security mode support by the WINC1500 Wi-Fi Driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1393 Using the Library This topic describes the basic architecture of the WINC1500 Wi-Fi Driver Library and provides information and examples on its use. Description Interface Header Files: wdrv_winc1500_api.h and wdrv_winc1500_stub.h The interface to the WINC1500 Wi-Fi Driver Library is defined in the wdrv_winc1500_api.h and wdrv_winc1500_stub.h header files. Please refer to the Understanding MPLAB Harmony section for how the driver interacts with the framework. Abstraction Model This library provides a low-level abstraction of the WINC1500 Wi-Fi module with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The WINC1500 Wi-Fi Library provides the following functionality: • Wi-Fi library initialization • Wi-Fi network configuration • Wi-Fi network connection • Scanning for existing Wi-Fi networks • Wi-Fi event processing • Wi-Fi status • Wi-FI console commands Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. TheLibrary Interface functions are divided into various sub-sections, which address one of the blocks or the overall operation of the Wi-Fi module. Library Interface Section Description Wi-Fi Initialization Functions This section provides functions that initialize the Wi-Fi library and allow its API to be used. Wi-Fi Status Functions This section provides functions that retrieve the Wi-Fi connection status. Wi-Fi External Functions This section provides public functions accessible to TCP/IP applications. Other Functions This section provides additional miscellaneous functions for configuring the Wi-Fi connection. Data Types and Constants This section provides data types and macros. How the Library Works This section describes how the WINC1500 Wi-Fi Driver Library operates. Description Before the driver is ready for use, it should be configured (compile time configuration). There are a few run-time configuration items that are done during initialization of the driver instance, and a few that are client-specific and are done using dedicated functions. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1394 To use the WINC1500 Wi-Fi Driver, initialization and client functions should be invoked in a specific sequence to ensure correct operation. Configuring the Library This section describes how to configure the WINC1500 Wi-Fi driver. Description The configuration of the WINC1500 Wi-Fi Driver is based on the file system_config.h. This header file contains the configuration selection for the Wi-Fi Driver. Based on the selections made, the WINC1500 Wi-Fi Driver may support the selected features. These configuration settings will apply to all instances of the WINC1500 Wi-Fi Driver. 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. Sample Functionality The following code provides an example of Wi-Fi Driver configuration. (refer to system.config.h) /*** SPI Driver Configuration ***/ #define DRV_SPI_NUMBER_OF_MODULES 4 /*** Driver Compilation and static configuration options. ***/ /*** Select SPI compilation units.***/ #define DRV_SPI_POLLED 0 #define DRV_SPI_ISR 1 #define DRV_SPI_MASTER 1 #define DRV_SPI_SLAVE 0 #define DRV_SPI_RM 1 #define DRV_SPI_EBM 0 #define DRV_SPI_8BIT 1 #define DRV_SPI_16BIT 0 #define DRV_SPI_32BIT 0 #define DRV_SPI_DMA 1 /*** SPI Driver Static Allocation Options ***/ #define DRV_SPI_INSTANCES_NUMBER 1 #define DRV_SPI_CLIENTS_NUMBER 1 #define DRV_SPI_ELEMENTS_PER_QUEUE 10 /*** SPI Driver DMA Options ***/ #define DRV_SPI_DMA_TXFER_SIZE 512 #define DRV_SPI_DMA_DUMMY_BUFFER_SIZE 512 /* SPI Driver Instance 0 Configuration */ #define DRV_SPI_SPI_ID_IDX0 SPI_ID_1 #define DRV_SPI_TASK_MODE_IDX0 DRV_SPI_TASK_MODE_ISR #define DRV_SPI_SPI_MODE_IDX0 DRV_SPI_MODE_MASTER #define DRV_SPI_ALLOW_IDLE_RUN_IDX0 false #define DRV_SPI_SPI_PROTOCOL_TYPE_IDX0 DRV_SPI_PROTOCOL_TYPE_STANDARD #define DRV_SPI_COMM_WIDTH_IDX0 SPI_COMMUNICATION_WIDTH_8BITS #define DRV_SPI_SPI_CLOCK_IDX0 CLK_BUS_PERIPHERAL_2 #define DRV_SPI_BAUD_RATE_IDX0 2000000 #define DRV_SPI_BUFFER_TYPE_IDX0 DRV_SPI_BUFFER_TYPE_STANDARD #define DRV_SPI_CLOCK_MODE_IDX0 DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_FALL #define DRV_SPI_INPUT_PHASE_IDX0 SPI_INPUT_SAMPLING_PHASE_AT_END #define DRV_SPI_TRANSMIT_DUMMY_BYTE_VALUE_IDX0 0x00 #define DRV_SPI_TX_INT_SOURCE_IDX0 INT_SOURCE_SPI_1_TRANSMIT #define DRV_SPI_RX_INT_SOURCE_IDX0 INT_SOURCE_SPI_1_RECEIVE #define DRV_SPI_ERROR_INT_SOURCE_IDX0 INT_SOURCE_SPI_1_ERROR #define DRV_SPI_INT_VECTOR_IDX0 INT_VECTOR_SPI1 #define DRV_SPI_INT_PRIORITY_IDX0 INT_PRIORITY_LEVEL1 #define DRV_SPI_INT_SUB_PRIORITY_IDX0 INT_SUBPRIORITY_LEVEL0 #define DRV_SPI_QUEUE_SIZE_IDX0 10 #define DRV_SPI_RESERVED_JOB_IDX0 1 #define DRV_SPI_TX_DMA_CHANNEL_IDX0 DMA_CHANNEL_1 #define DRV_SPI_TX_DMA_THRESHOLD_IDX0 16 #define DRV_SPI_RX_DMA_CHANNEL_IDX0 DMA_CHANNEL_0 #define DRV_SPI_RX_DMA_THRESHOLD_IDX0 16 Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1395 /*** Timer Driver Configuration ***/ #define DRV_TMR_INTERRUPT_MODE true #define DRV_TMR_INSTANCES_NUMBER 1 #define DRV_TMR_CLIENTS_NUMBER 1 /*** Timer Driver 0 Configuration ***/ #define DRV_TMR_PERIPHERAL_ID_IDX0 TMR_ID_2 #define DRV_TMR_INTERRUPT_SOURCE_IDX0 INT_SOURCE_TIMER_2 #define DRV_TMR_INTERRUPT_VECTOR_IDX0 INT_VECTOR_T2 #define DRV_TMR_ISR_VECTOR_IDX0 _TIMER_2_VECTOR #define DRV_TMR_INTERRUPT_PRIORITY_IDX0 INT_PRIORITY_LEVEL4 #define DRV_TMR_INTERRUPT_SUB_PRIORITY_IDX0 INT_SUBPRIORITY_LEVEL0 #define DRV_TMR_CLOCK_SOURCE_IDX0 DRV_TMR_CLKSOURCE_INTERNAL #define DRV_TMR_PRESCALE_IDX0 TMR_PRESCALE_VALUE_256 #define DRV_TMR_OPERATION_MODE_IDX0 DRV_TMR_OPERATION_MODE_16_BIT #define DRV_TMR_ASYNC_WRITE_ENABLE_IDX0 false #define DRV_TMR_POWER_STATE_IDX0 SYS_MODULE_POWER_RUN_FULL /*** Wi-Fi Driver Configuration ***/ #define WINC1500_INT_SOURCE INT_SOURCE_CHANGE_NOTICE #define WINC1500_INT_VECTOR INT_VECTOR_CN #define WDRV_SPI_INDEX 0 #define WDRV_SPI_INSTANCE sysObj.spiObjectIdx0 #define WDRV_USE_SPI_DMA #define WDRV_NVM_SPACE_ENABLE #define WDRV_NVM_SPACE_ADDR (48 * 1024) #define WDRV_BOARD_TYPE WDRV_BD_TYPE_MX_ESK #define WDRV_EXT_RTOS_TASK_SIZE 2048u #define WDRV_EXT_RTOS_TASK_PRIORITY 2u // I/O mappings for general control pins, including CHIP_EN, IRQN, RESET_N and SPI_SSN. #define WDRV_CHIP_EN_PORT_CHANNEL PORT_CHANNEL_F #define WDRV_CHIP_EN_BIT_POS 1 #define WDRV_IRQN_PORT_CHANNEL PORT_CHANNEL_G #define WDRV_IRQN_BIT_POS 7 #define WDRV_RESET_N_PORT_CHANNEL PORT_CHANNEL_F #define WDRV_RESET_N_BIT_POS 0 #define WDRV_SPI_SSN_PORT_CHANNEL PORT_CHANNEL_B #define WDRV_SPI_SSN_BIT_POS 2 #define WINC1500_ON_PIC32MX_ESK // On PIC32MX ESK, when CN9 (Pin G7) is used as external interrupt, // it is sometimes better to use another GPIO (Pin E0) to read CN9's value. // In this case, a jumper wire is needed to connect Pin E0 and Pin G7. //#define WDRV_VERIFY_IRQN_BY_ANOTHER_GPIO #if defined(WDRV_VERIFY_IRQN_BY_ANOTHER_GPIO) // Use Pin E0. Please also make sure that Pin E0 and Pin G7 are connected (by a jumper wire). #define WDRV_IRQN_PORT_CHANNEL_READ PORT_CHANNEL_E #define WDRV_IRQN_BIT_POS_READ 0 #else // Still directly read Pin G7's value. #define WDRV_IRQN_PORT_CHANNEL_READ PORT_CHANNEL_G #define WDRV_IRQN_BIT_POS_READ 7 #endif #define WDRV_DEFAULT_NETWORK_TYPE WDRV_NETWORK_TYPE_INFRASTRUCTURE #define WDRV_DEFAULT_CHANNEL 6 #define WDRV_DEFAULT_SSID "MicrochipDemoApp" Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1396 #define WDRV_DEFAULT_SECURITY_MODE WDRV_SECURITY_OPEN #define WDRV_DEFAULT_WEP_KEYS_40 "5AFB6C8E77" // default WEP40 key #define WDRV_DEFAULT_WEP_KEYS_104 "90E96780C739409DA50034FCAA" // default WEP104 key #define WDRV_DEFAULT_PSK_PHRASE "Microchip 802.11 Secret PSK Password" // default WPA-PSK Building the Library This section lists the files that are available in the WINC1500 Wi-Fi Driver Library. 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 /framework/driver/wifi/winc1500. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description wdrv_winc1500_stub.h Contains Stub function prototypes for interfacing to the WINC1500 Wi-Fi Driver. wdrv_winc1500_api.h Contains API function prototypes for interfacing to the WINC1500 Wi-Fi Driver. 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 wdrv_winc1500_console.c Console module for the WINC1500 wireless driver. wdrv_winc1500_fw_update.c WINC1500 firmware update support. wdrv_winc1500_eint.c External interrupt handler for the WINC1500 wireless driver. wdrv_winc1500_timer.c Timer functions for the WINC1500 wireless driver. wdrv_winc1500_gpio.c WINC1500 GPIO support for SPI communication. wdrv_winc1500_spi.c WINC1500 support for SPI communication. wdrv_winc1500_cli.c WINC1500 driver CLI implementation. wdrv_winc1500_config_data.c Stores and retrieves Wi-Fi configuration to/from non-volatile memory (NVM). wdrv_winc1500_connmgr.c WINC1500 driver connection manager. wdrv_winc1500_events.c WINC1500 driver MAC events. wdrv_winc1500_iwpriv.c WINC1500 driver connection process functions. wdrv_winc1500_main.c WINC1500 driver Microchip TCP/IP Stack PIC32 MAC support. wdrv_winc1500_osal.c WINC1500 driver OS abstraction layer. wdrv_winc1500_scan_helper.c WINC1500 driver scan helper functions. wdrext_winc1500.c WINC1500 driver extended functions. winc1500_task.c WINC1500 driver task handler. 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 N/A The WINC1500 Wi-Fi Driver controller has no optional files. Module Dependencies The WINC1500 Wi-Fi Driver Library depends on the following modules: • SPI Driver Library • NVM Driver Library Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1397 • UART Driver Library • USB Driver Library • Operating System Abstraction Layer (OSAL) Library Help • Clock System Service Library • System Service Library Introduction • Console System Service Library • File System Service Library • Interrupt System Service Library • Timer System Service Library • Debug System Service Library • Ports System Service Library • FreeRTOS Library Help • Crypto Library • Peripheral Libraries • Networking Presentation Layer Help • TCP/IP Stack Library Help • Command Processor System Service Library • DMA System Service Library • Random Number Generator System Service Library • Common System Service Library • TCP/IP Ethernet MAC Driver Library Console Commands This section describes the console commands available for the WINC1500 Wi-Fi Driver. Description Both the Web Server and the EasyConfig demonstrations support the followings commands, which enable control over the Wi-Fi settings. Command: deleteconf Parameters Description None. Wi-Fi console command to erase saved Wi-Fi configuration in memory. Command: iwconfig Parameters Description [ ssid ] name: Specifies the name of the SSID (1-32 ASCII characters). [ mode ] idle: Disconnected from the current configuration. managed: Connects in infrastructure mode to the currently set SSID. [ power ] enable: Enables all Power-Saving features (PS_POLL). Will wake up to check for all types of traffic (unicast, multicast, and broadcast). disable: Disables any Power-Saving features. Will always be in an active power state. [ security ] mode: open/wep40/wep104/wpa/wpa2/pin/pbc. For example: iwconfig security open iwconfig security wep40 iwconfig security wep104 iwconfig security wpa iwconfig security wpa2 iwconfig security pin iwconfig security pbc [ scan ] Starts a Wi-Fi scan. [ scanget ] scan_index: Retrieves the scan result after the scan completes (1 - n). Command: mac Parameters Description None. Wi-Fi console command to retrieve the MAC address of the MRF24WN module. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1398 Command: ota Parameters Description [ http://ip-address/ ] [ filename.bin ] Upgrade the WINC1500 firmware over-the-air. For example: http://192.168.0.4/winc1500_ota.bin Command: readconf Parameters Description None. Wi-Fi console command to read saved Wi-Fi configuration in memory. Command: saveconf Parameters Description None. Wi-Fi console command to save Wi-Fi configuration to memory. Library Interface a) Wi-Fi Initialization Functions Name Description WDRV_CLI_Init Initializes the console CLI interface. Implementation: Dynamic WDRV_INTR_Deinit Deinitializes interrupts for Wi-Fi driver. Implementation: Dynamic WDRV_INTR_Init Initializes interrupts for the Wi-Fi driver. Implementation: Dynamic WDRV_SPI_Deinit Deinitializes the SPI object for the Wi-Fi driver. Implementation: Dynamic WDRV_SPI_Init Initializes the SPI object for the Wi-Fi driver. Implementation: Dynamic WDRV_GPIO_DeInit Deinitializes the GPIO objects for the Wi-Fi driver. Implementation: Dynamic WDRV_EXT_Deinitialize Deinitializes the WINC1500 Wi-Fi driver. Implementation: Dynamic WDRV_WINC1500_ISR Wi-Fi driver (WINC1500-specific) interrupt service routine. Implementation: Dynamic b) Wi-Fi Status Functions Name Description WDRV_EXT_CmdFWVersionGet Retrieves FW version information. Implementation: Dynamic WDRV_EXT_ScanResultGet Reads the selected scan results back from the WINC1500 module. Implementation: Dynamic WDRV_EXT_CmdMacAddressGet Retrieves the WINC1500 MAC address. Implementation: Dynamic WDRV_EXT_CmdScanGet Reads the number of scan results from the WINC1500 module. Implementation: Dynamic WDRV_EXT_CmdSSIDGet Gets the SSID. Implementation: Dynamic c) Wi-Fi External Functions Name Description WDRV_EXT_CmdPowerSavePut Puts the module in power save mode. Implementation: Dynamic WDRV_EXT_HWInterruptHandler Wi-Fi driver (WINC1500-specific) interrupt service routine. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1399 WDRV_EXT_CmdScanOptionSet Sets scan options. Implementation: Dynamic WDRV_EXT_ModuleUpDown Enables or disables WINC1500 module. Implementation: Dynamic WDRV_EXT_MulticastFilterSet Sets a multicast address filter. Implementation: Dynamic WDRV_EXT_CmdConnect Directs the WINC1500 to connect to a Wi-Fi network. Implementation: Dynamic WDRV_EXT_CmdDisconnect Directs the WINC1500 to disconnect from a Wi-Fi network. Implementation: Dynamic WDRV_EXT_CmdNetModeAPSet Sets the Wi-Fi network type to SoftAP. Implementation: Dynamic WDRV_EXT_CmdNetModeBSSSet Sets the Wi-Fi network type to Infrastructure. Implementation: Dynamic WDRV_EXT_CmdScanStart Directs the WINC1500 module to start a scan. Implementation: Dynamic WDRV_EXT_CmdSecNoneSet Sets Wi-Fi security to open (no security). Implementation: Dynamic WDRV_EXT_CmdSecWEPSet Sets Wi-Fi security to use WEP. Implementation: Dynamic WDRV_EXT_CmdSecWPASet Sets Wi-Fi security to use WPA/WPA2. Implementation: Dynamic WDRV_EXT_DataSend Sends data packets to WINC1500 module. Implementation: Dynamic WDRV_EXT_ScanDoneSet Indicates when a scan has completed. Implementation: Dynamic WDRV_EXT_CmdChannelSet Sets the channel on which to operate. Implementation: Dynamic WDRV_EXT_CmdSSIDSet Sets the SSID. Implementation: Dynamic WDRV_EXT_CmdFWUpdate Directs the module to start firmware download and upgrade. Implementation: Dynamic WDRV_EXT_CmdSecWpsSet Sets Wi-Fi security to use WPS. Implementation: Dynamic WDRV_EXT_CmdTxPowerSet Sets the Tx Power at 3 levels, high, medium and low. Implementation: Dynamic WDRV_EXT_CmdConnectContextBssidGet Gets the BSSID Implementation: Dynamic WDRV_EXT_CmdScanOptionsSet Sets scan options. Implementation: Dynamic WDRV_EXT_CmdSSIDSet Sets the SSID. Implementation: Dynamic WDRV_EXT_ScanIsInProgress Check whether host scan is now in progress or not. Implementation: Dynamic d) Other Functions Name Description WDRV_INTR_SourceDisable Disables interrupts from the module. Implementation: Dynamic WDRV_INTR_SourceEnable Enables interrupts from the module. Implementation: Dynamic WDRV_EXT_Initialize Initializes the WILC1000 Wi-Fi driver. Implementation: Dynamic WDRV_EXT_RssiRead Requests RSSI for the connected AP. Implementation: Dynamic WDRV_EXT_WPSResultsRead Reads the WPS process results back from the WINC1500 module and updates the configuration data. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1400 WDRV_STUB_Assert Dumps out an error message on serial console and resets itself when the driver asserts. Implementation: Dynamic WDRV_STUB_GPIO_ChipDisable Disables the WINC1500 chip. Implementation: Dynamic WDRV_STUB_GPIO_ChipEnable Enables the WINC1500 chip. Implementation: Dynamic WDRV_STUB_GPIO_DeInitialize Deinitializes the GPIO object for the Wi-Fi driver. Implementation: Dynamic WDRV_STUB_GPIO_Initialize Initializes the GPIO object for the Wi-Fi driver. Implementation: Dynamic WDRV_STUB_GPIO_ModuleReset Resets the WINC1500 module. Implementation: Dynamic WDRV_STUB_GPIO_ModuleUnreset Unresets the WINC1500 module. Implementation: Dynamic WDRV_STUB_HardDelay Waits spinning for the delay milliseconds. Implementation: Dynamic WDRV_STUB_INTR_Deinit Deinitializes interrupts for Wi-Fi driver. Implementation: Dynamic WDRV_STUB_INTR_Init Initializes interrupts for the Wi-Fi driver. Implementation: Dynamic WDRV_STUB_INTR_SourceDisable Disables interrupts from the module. Implementation: Dynamic WDRV_STUB_INTR_SourceEnable Enables interrupts from the module. Implementation: Dynamic WDRV_STUB_SPI_Deinitialize Deinitializes the SPI object for the Wi-Fi driver. Implementation: Dynamic WDRV_STUB_SPI_In Receives data from the module through the SPI bus. Implementation: Dynamic WDRV_STUB_SPI_Initialize Initializes the SPI object for the Wi-Fi driver. Implementation: Dynamic WDRV_STUB_SPI_Out Sends data out to the module through the SPI bus. Implementation: Dynamic e) Data Types and Constants Name Description _WDRV_WINC1500_API_H This is macro _WDRV_WINC1500_API_H. WDRV_STUB_Print This is macro WDRV_STUB_Print. Description This section describes the Application Programming Interface (API) functions of the WINC1500 Wi-Fi Driver. Refer to each section for a detailed description. a) Wi-Fi Initialization Functions WDRV_CLI_Init Function Initializes the console CLI interface. Implementation: Dynamic File wdrv_winc1500_api.h C bool WDRV_CLI_Init(); Returns • 0 - Indicates success • Non-zero value - Indicates failure Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1401 Description This function initializes the console CLI interface. Remarks None. Preconditions The TCP/IP stack should be initialized. Function bool WDRV_CLI_Init(void) WDRV_INTR_Deinit Function Deinitializes interrupts for Wi-Fi driver. Implementation: Dynamic File wdrv_mrf24wn_api.h C void WDRV_INTR_Deinit(); Returns None. Description This function deinitializes interrupts for the Wi-Fi driver. Remarks None. Preconditions The TCP/IP stack should be initialized. Function void WDRV_INTR_Deinit(void) WDRV_INTR_Init Function Initializes interrupts for the Wi-Fi driver. Implementation: Dynamic File wdrv_mrf24wn_api.h C void WDRV_INTR_Init(); Returns None. Description This function initializes interrupts for the Wi-Fi driver. Remarks None. Preconditions The TCP/IP stack should be initialized. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1402 Function void WDRV_INTR_Init(void) WDRV_SPI_Deinit Function Deinitializes the SPI object for the Wi-Fi driver. Implementation: Dynamic File wdrv_mrf24wn_api.h C void WDRV_SPI_Deinit(); Returns None. Description This function deinitializes the SPI object for the Wi-Fi driver. Remarks None. Preconditions The TCP/IP stack should be initialized. Function void WDRV_SPI_Deinit(void) WDRV_SPI_Init Function Initializes the SPI object for the Wi-Fi driver. Implementation: Dynamic File wdrv_mrf24wn_api.h C void WDRV_SPI_Init(); Returns None. Description This function initializes the SPI object for the Wi-Fi driver. Remarks None. Preconditions The TCP/IP stack should be initialized. Function void WDRV_SPI_Init(void) WDRV_GPIO_DeInit Function Deinitializes the GPIO objects for the Wi-Fi driver. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1403 File wdrv_mrf24wn_api.h C void WDRV_GPIO_DeInit(); Returns None. Description This function deinitializes the GPIO objects for the Wi-Fi driver. Remarks None. Preconditions The TCP/IP stack should be initialized. Function void WDRV_GPIO_DeInit(void) WDRV_EXT_Deinitialize Function Deinitializes the WINC1500 Wi-Fi driver. Implementation: Dynamic File wdrv_winc1500_api.h C void WDRV_EXT_Deinitialize(); Returns None. Description This function deinitializes the WINC1500 driver. Remarks None Preconditions None. Function void WDRV_EXT_Deinitialize(void) WDRV_WINC1500_ISR Function Wi-Fi driver (WINC1500-specific) interrupt service routine. Implementation: Dynamic File wdrv_winc1500_api.h C void WDRV_WINC1500_ISR(); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1404 Description This function is the Wi-Fi driver (WINC1500-specific) interrupt service routine. Remarks None. Preconditions Wi-Fi initialization must be complete. Function void WDRV_WINC1500_ISR(void) b) Wi-Fi Status Functions WDRV_EXT_CmdFWVersionGet Function Retrieves FW version information. Implementation: Dynamic File wdrv_winc1500_api.h C uint32_t WDRV_EXT_CmdFWVersionGet(uint32_t * major, uint32_t * minor, uint32_t * patch); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description This function retrieves the module FW version information. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description major pointer where the major number will be written minor pointer where the minor number will be written patch pointer where the patch number will be written Function uint32_t WDRV_EXT_CmdFWVersionGet(uint32_t *major, uint32_t *minor, uint32_t *patch); WDRV_EXT_ScanResultGet Function Reads the selected scan results back from the WINC1500 module. Implementation: Dynamic File wdrv_winc1500_api.h C void WDRV_EXT_ScanResultGet(uint8_t listIndex, WDRV_SCAN_RESULT * p_scanResult); Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1405 Returns • 0 - Indicates success • Non-zero value - Indicates failure Description After a scan has completed this function is used to read one scan result at a time from the WINC1500 module. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description listIndex index (0 based list) of the scan entry to retrieve p_scanResult pointer to where scan result is written Function void WDRV_EXT_ScanResultGet(uint8_t listIndex, WDRV_SCAN_RESULT *p_scanResult) WDRV_EXT_CmdMacAddressGet Function Retrieves the WINC1500 MAC address. Implementation: Dynamic File wdrv_winc1500_api.h C uint32_t WDRV_EXT_CmdMacAddressGet(uint8_t * MacAddr); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description This function retrieves the WINC1500 MAC address. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description MacAddr Pointer where MAC address will be written (must point to a 6 bytes buffer) Function uint32_t WDRV_EXT_CmdMacAddressGet(uint8_t *MacAddr) WDRV_EXT_CmdScanGet Function Reads the number of scan results from the WINC1500 module. Implementation: Dynamic File wdrv_winc1500_api.h Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1406 C void WDRV_EXT_CmdScanGet(uint16_t * numOfResults); Returns None. Description This function reads the number of scan results from the WINC1500 module. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description numOfResults pointer where the number of scan results will be written Function void WDRV_EXT_CmdScanGet(uint16_t *numOfResults) WDRV_EXT_CmdSSIDGet Function Gets the SSID. Implementation: Dynamic File wdrv_winc1500_api.h C void WDRV_EXT_CmdSSIDGet(uint8_t * ssid, uint8_t * length); Returns None. Description This function returns the SSID and SSID Length. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description ssid pointer to buffer where SSID will be written length number of bytes in SSID Function void WDRV_EXT_CmdSSIDGet(uint8_t *ssid, uint8_t *length) c) Wi-Fi External Functions WDRV_EXT_CmdPowerSavePut Function Puts the module in power save mode. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1407 File wdrv_winc1500_api.h C uint32_t WDRV_EXT_CmdPowerSavePut(bool enable, uint8_t mode, uint16_t listenInterval); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description The function places the module in power save mode. Remarks This works only with Infrastructure mode. Do not call this in other modes. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description enable true will put the module in power save mode. mode 0 : manual mode - not synchronized to AP beacon ; 1. deep automatic mode - ieee802.11 power save mode. listenInterval STA wakes up per this beacon interval. Function uint32_t WDRV_EXT_CmdPowerSavePut(bool enable, uint8_t mode, uint16_t listenInterval) WDRV_EXT_HWInterruptHandler Function Wi-Fi driver (WINC1500-specific) interrupt service routine. Implementation: Dynamic File wdrv_winc1500_api.h C void WDRV_EXT_HWInterruptHandler(); Returns None. Description This function is the Wi-Fi driver (WINC1500-specific) interrupt service routine. Remarks None. Preconditions Wi-Fi initialization must be complete. Function void WDRV_EXT_HWInterruptHandler(void) WDRV_EXT_CmdScanOptionSet Function Sets scan options. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1408 File wdrv_wilc1000_api.h C uint32_t WDRV_EXT_CmdScanOptionSet(uint8_t numOfSlots, uint8_t slotTime, uint8_t probesPerSlot, uint8_t rssiThreshold); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description The function sets scan options. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description numOfSlots The min number of slots is 2 for every channel, every slot the module will send Probe Request on air, and wait/listen for PROBE RESP/BEACONS for the slotTime. slotTime The time that the module will wait on every channel listening to the frames on air. probesPerSlot Number of probe requests to be sent per channel scan slot. rssiThreshold The RSSI threshold of the AP which will be connected to directly. Function uint32_t WDRV_EXT_CmdScanOptionSet(uint8_t numOfSlots, uint8_t slotTime, uint8_t probesPerSlot, uint8_t rssiThreshold); WDRV_EXT_ModuleUpDown Function Enables or disables WINC1500 module. Implementation: Dynamic File wdrv_winc1500_api.h C void WDRV_EXT_ModuleUpDown(uint32_t up); Returns None. Description This function enables or disables WINC1500 module. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description up 1: enable; 0: disable. Function void WDRV_EXT_ModuleUpDown(uint32_t up) Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1409 WDRV_EXT_MulticastFilterSet Function Sets a multicast address filter. Implementation: Dynamic File wdrv_winc1500_api.h C uint32_t WDRV_EXT_MulticastFilterSet(uint8_t * addr); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description This function allows the application to configure up to 8 Multicast address filters on the WINC1500 module. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description addr the pointer of the multicast mac address. Function uint32_t WDRV_EXT_MulticastFilterSet(uint8_t *addr) WDRV_EXT_CmdConnect Function Directs the WINC1500 to connect to a Wi-Fi network. Implementation: Dynamic File wdrv_winc1500_api.h C uint32_t WDRV_EXT_CmdConnect(); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description This function causes the WINC1500 to connect to a Wi-Fi network. Upon connection, or a failure to connect, an event will be generated. Remarks None. Preconditions Wi-Fi initialization must be complete and relevant connection parameters must have been set. Function uint32_t WDRV_EXT_CmdConnect(void) Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1410 WDRV_EXT_CmdDisconnect Function Directs the WINC1500 to disconnect from a Wi-Fi network. Implementation: Dynamic File wdrv_winc1500_api.h C uint32_t WDRV_EXT_CmdDisconnect(); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description This function causes the WINC1500 to disconnect from a Wi-Fi network. Remarks None. Preconditions Wi-Fi initialization must be complete and a connection must be in progress. Function uint32_t WDRV_EXT_CmdDisconnect(void) WDRV_EXT_CmdNetModeAPSet Function Sets the Wi-Fi network type to SoftAP. Implementation: Dynamic File wdrv_winc1500_api.h C void WDRV_EXT_CmdNetModeAPSet(); Returns None. Description This function sets the Wi-Fi network type to SoftAP. Remarks None. Preconditions Wi-Fi initialization must be complete. Function void WDRV_EXT_CmdNetModeAPSet(void) WDRV_EXT_CmdNetModeBSSSet Function Sets the Wi-Fi network type to Infrastructure. Implementation: Dynamic File wdrv_winc1500_api.h Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1411 C void WDRV_EXT_CmdNetModeBSSSet(); Returns None. Description This function sets the Wi-Fi network type to Infrastructure. Remarks None. Preconditions Wi-Fi initialization must be complete. Function void WDRV_EXT_CmdNetModeBSSSet(void) WDRV_EXT_CmdScanStart Function Directs the WINC1500 module to start a scan. Implementation: Dynamic File wdrv_winc1500_api.h C uint32_t WDRV_EXT_CmdScanStart(); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description This function directs the WINC1500 module to start a scan. Remarks None. Preconditions Wi-Fi initialization must be complete. Function uint32_t WDRV_EXT_CmdScanStart(void) WDRV_EXT_CmdSecNoneSet Function Sets Wi-Fi security to open (no security). Implementation: Dynamic File wdrv_winc1500_api.h C void WDRV_EXT_CmdSecNoneSet(); Returns None. Description This function sets the Wi-Fi security to open. One can only connect to an AP that is running in open mode. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1412 Remarks None. Preconditions Wi-Fi initialization must be complete and in an unconnected state. Function void WDRV_EXT_CmdSecNoneSet(void) WDRV_EXT_CmdSecWEPSet Function Sets Wi-Fi security to use WEP. Implementation: Dynamic File wdrv_winc1500_api.h C void WDRV_EXT_CmdSecWEPSet(uint8_t * key, uint16_t len); Returns None. Description This function sets the Wi-Fi security to WEP. One can only connect to an AP that is running the same WEP mode. Remarks None. Preconditions Wi-Fi initialization must be complete and in an unconnected state. Parameters Parameters Description key pointer to the WEP key buffer len WEP key length Function void WDRV_EXT_CmdSecWEPSet(uint8_t *key, uint16_t len) WDRV_EXT_CmdSecWPASet Function Sets Wi-Fi security to use WPA/WPA2. Implementation: Dynamic File wdrv_winc1500_api.h C void WDRV_EXT_CmdSecWPASet(uint8_t * key, uint16_t len); Returns None. Description This function sets the Wi-Fi security to WPA/WPA2. One can only connect to an AP that is running the same WPA/WPA2 mode. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1413 Preconditions Wi-Fi initialization must be complete and in an unconnected state. Parameters Parameters Description key pointer to the WPA key buffer len WPA key length Function void WDRV_EXT_CmdSecWPASet(uint8_t *key, uint16_t len) WDRV_EXT_DataSend Function Sends data packets to WINC1500 module. Implementation: Dynamic File wdrv_winc1500_api.h C uint32_t WDRV_EXT_DataSend(uint16_t segSize, uint8_t * p_segData); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description This function sends data packets to the WINC1500 module. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description seqSize data size p_seqData pointer to the data buffer Function uint32_t WDRV_EXT_DataSend(uint16_t segSize, uint8_t *p_segData) WDRV_EXT_ScanDoneSet Function Indicates when a scan has completed. Implementation: Dynamic File wdrv_wilc1000_api.h C void WDRV_EXT_ScanDoneSet(); Returns None. Description This function indicates when a scan has completed. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1414 Remarks None. Preconditions Wi-Fi initialization must be complete. Function void WDRV_EXT_ScanDoneSet(void) WDRV_EXT_CmdChannelSet Function Sets the channel on which to operate. Implementation: Dynamic File wdrv_winc1500_api.h C void WDRV_EXT_CmdChannelSet(uint16_t channel); Returns None. Description This function sets the channel on which to operate. Remarks This works only with SoftAP mode. Do not call this in other modes. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description channel target channel Function void WDRV_EXT_CmdChannelSet(uint16_t channel) WDRV_EXT_CmdSSIDSet Function Sets the SSID. Implementation: Dynamic File wdrv_wilc1000_api.h C void WDRV_EXT_CmdSSIDSet(uint8_t * ssid, uint16_t len); Returns None. Description This function sets the SSID and SSID length. Remarks Do not include a string terminator in the SSID length. SSIDs are case-sensitive. SSID length must be less than or equal to 32. Preconditions Wi-Fi initialization must be complete. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1415 Parameters Parameters Description ssid pointer to SSID buffer len number of bytes in SSID Function void WDRV_EXT_CmdSSIDSet(uint8_t *ssid, uint16_t len) WDRV_EXT_CmdFWUpdate Function Directs the module to start firmware download and upgrade. Implementation: Dynamic File wdrv_winc1500_api.h C void WDRV_EXT_CmdFWUpdate(); Returns None. Description This function directs the module to start the firmware download and upgrade. Remarks None. Preconditions Wi-Fi initialization must be complete. Function void WDRV_EXT_CmdFWUpdate(void) WDRV_EXT_CmdSecWpsSet Function Sets Wi-Fi security to use WPS. Implementation: Dynamic File wdrv_winc1500_api.h C uint32_t WDRV_EXT_CmdSecWpsSet(bool pinMode, uint8_t * key, uint16_t keyLen); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description This function sets the Wi-Fi security to WPS. One can only connect to an AP that supports WPS. Remarks None Preconditions Wi-Fi initialization must be complete and in an unconnected state. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1416 Parameters Parameters Description pinMode 0: PBC mode; 1: PIN mode key pointer of the PIN buffer keyLen PIN length Function int32_t WDRV_EXT_CmdSecWpsSet(bool pinMode, uint8_t *key, uint16_t keyLen) WDRV_EXT_CmdTxPowerSet Function Sets the Tx Power at 3 levels, high, medium and low. Implementation: Dynamic File wdrv_winc1500_api.h C uint32_t WDRV_EXT_CmdTxPowerSet(uint32_t level); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description The function sets the module's Tx power. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description level 1 : high - 18 dBm PA gain , 2 : medium - 12 dBm PA gain, 3 : low - 6 dBm PA gain. Function uint32_t WDRV_EXT_CmdTxPowerSet(uint32_t level) WDRV_EXT_CmdConnectContextBssidGet Function Gets the BSSID Implementation: Dynamic File wdrv_winc1500_api.h C uint32_t WDRV_EXT_CmdConnectContextBssidGet(uint8_t * bssId); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description This function gets the current AP's BSSID. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1417 Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description bssId pointer where the current AP's BSSID will be written Function uint32_t WDRV_EXT_CmdConnectContextBssidGet(uint8_t *bssId) WDRV_EXT_CmdScanOptionsSet Function Sets scan options. Implementation: Dynamic File wdrv_winc1500_api.h C uint32_t WDRV_EXT_CmdScanOptionsSet(uint8_t numOfSlots, uint8_t slotTime, uint8_t probesPerSlot, uint8_t rssiThreshold); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description The function sets scan options. Remarks None. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description numOfSlots The min number of slots is 2 for every channel, every slot the module will send Probe Request on air, and wait/listen for PROBE RESP/BEACONS for the slotTime. slotTime The time that the module will wait on every channel listening to the frames on air. probesPerSlot Number of probe requests to be sent per channel scan slot. rssiThreshold The RSSI threshold of the AP which will be connected to directly. Function uint32_t WDRV_EXT_CmdScanOptionsSet(uint8_t numOfSlots, uint8_t slotTime, uint8_t probesPerSlot, uint8_t rssiThreshold); WDRV_EXT_CmdSSIDSet Function Sets the SSID. Implementation: Dynamic File wdrv_winc1500_api.h C void WDRV_EXT_CmdSSIDSet(uint8_t * ssid, uint8_t len); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1418 Description This function sets the SSID and SSID length. Remarks SSIDs are case-sensitive. SSID length must be less than or equal to 32. Preconditions Wi-Fi initialization must be complete. Parameters Parameters Description ssid pointer to SSID buffer len number of bytes in SSID Function void WDRV_EXT_CmdSSIDSet(uint8_t *ssid, uint16_t len) WDRV_EXT_ScanIsInProgress Function Check whether host scan is now in progress or not. Implementation: Dynamic File wdrv_wilc1000_api.h C bool WDRV_EXT_ScanIsInProgress(); Returns • true - Host scan is in progress • false - Host scan is not in progress Description Check whether host scan is now in progress or not. Remarks None. Preconditions Wi-Fi initialization must be complete. Function void WDRV_EXT_ScanIsInProgress(void) d) Other Functions WDRV_INTR_SourceDisable Function Disables interrupts from the module. Implementation: Dynamic File wdrv_mrf24wn_api.h C void WDRV_INTR_SourceDisable(); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1419 Description This function disables interrupts from the module. Remarks None. Preconditions Wi-Fi initialization must be complete. Function void WDRV_INTR_SourceDisable(void) WDRV_INTR_SourceEnable Function Enables interrupts from the module. Implementation: Dynamic File wdrv_mrf24wn_api.h C void WDRV_INTR_SourceEnable(); Returns None. Description This function enables interrupts from the module. Remarks None. Preconditions Wi-Fi initialization must be complete. Function void WDRV_INTR_SourceEnable(void) WDRV_EXT_Initialize Function Initializes the WILC1000 Wi-Fi driver. Implementation: Dynamic File wdrv_wilc1000_api.h C void WDRV_EXT_Initialize(WDRV_HOOKS const *const ehooks, bool initWait); Returns None. Description This function initializes the WILC1000 Wi-Fi driver, making it ready for clients to use. Remarks None. Preconditions None. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1420 Parameters Parameters Description ehooks pointer to WDRV layer hooks initWait true will put WDRV in wait during initialization Function void WDRV_EXT_Initialize(WDRV_HOOKS const *const ehooks, bool initWait) WDRV_EXT_RssiRead Function Requests RSSI for the connected AP. Implementation: Dynamic File wdrv_winc1500_api.h C uint32_t WDRV_EXT_RssiRead(); Returns • 0 - Indicates success • Non-zero value - Indicates failure Description This function requests RSSI for the connected AP. Remarks None. Preconditions Wi-Fi initialization must be complete. Function void WDRV_EXT_RssiRead(void) WDRV_EXT_WPSResultsRead Function Reads the WPS process results back from the WINC1500 module and updates the configuration data. Implementation: Dynamic File wdrv_winc1500_api.h C void WDRV_EXT_WPSResultsRead(WDRV_CONFIG * config, uint32_t * status); Returns None. Description After the WPS process has completed, this function is used to read the WPS process results from the WINC1500 module and update the configuration data. Remarks None. Preconditions Wi-Fi initialization must be complete. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1421 Parameters Parameters Description config pointer to where configuration data will be updated status pointer to where WPS process status will be written Function void WDRV_EXT_WPSResultsRead(WDRV_CONFIG *config, uint32_t *status) WDRV_STUB_Assert Function Dumps out an error message on serial console and resets itself when the driver asserts. Implementation: Dynamic File wdrv_winc1500_stub.h C void WDRV_STUB_Assert(int condition, const char * msg, const char * file, int line); Returns None. Description Dumps out an error message on serial console and resets itself when the driver asserts. Remarks None. Preconditions The TCP/IP stack should be initialized. Parameters Parameters Description condition asserts if false msg error message file file name line line number where driver asserts. Function WDRV_STUB_Assert(int condition, const char *msg, const char *file, int line) WDRV_STUB_GPIO_ChipDisable Function Disables the WINC1500 chip. Implementation: Dynamic File wdrv_winc1500_stub.h C void WDRV_STUB_GPIO_ChipDisable(); Returns None. Description This function disables the WINC1500 chip. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1422 Preconditions The TCP/IP stack should be initialized. Function void WDRV_STUB_GPIO_ChipDisable(void) WDRV_STUB_GPIO_ChipEnable Function Enables the WINC1500 chip. Implementation: Dynamic File wdrv_winc1500_stub.h C void WDRV_STUB_GPIO_ChipEnable(); Returns None. Description This function enables the WINC1500 chip. Remarks None. Preconditions The TCP/IP stack should be initialized. Function void WDRV_STUB_GPIO_ChipEnable(void) WDRV_STUB_GPIO_DeInitialize Function Deinitializes the GPIO object for the Wi-Fi driver. Implementation: Dynamic File wdrv_winc1500_stub.h C void WDRV_STUB_GPIO_DeInitialize(); Returns None. Description This function deinitializes the GPIO object for the Wi-Fi driver. Remarks None. Preconditions The TCP/IP stack should be initialized. Function void WDRV_STUB_GPIO_DeInitialize(void) WDRV_STUB_GPIO_Initialize Function Initializes the GPIO object for the Wi-Fi driver. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1423 Implementation: Dynamic File wdrv_winc1500_stub.h C void WDRV_STUB_GPIO_Initialize(); Returns None. Description This function initializes the GPIO object for the Wi-Fi driver. Remarks None. Preconditions The TCP/IP stack should be initialized. Function void WDRV_STUB_GPIO_Initialize(void) WDRV_STUB_GPIO_ModuleReset Function Resets the WINC1500 module. Implementation: Dynamic File wdrv_winc1500_stub.h C void WDRV_STUB_GPIO_ModuleReset(); Returns None. Description This function resets the WINC1500 module. Remarks None. Preconditions The TCP/IP stack should be initialized. Function void WDRV_STUB_GPIO_ModuleReset(void) WDRV_STUB_GPIO_ModuleUnreset Function Unresets the WINC1500 module. Implementation: Dynamic File wdrv_winc1500_stub.h C void WDRV_STUB_GPIO_ModuleUnreset(); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1424 Description This function unresets the WINC1500 module. Remarks None. Preconditions The TCP/IP stack should be initialized. Parameters Parameters Description board Microchip development kit type (i.e., PIC32MZ EC Starter Kit, PIC32 Ethernet Starter Kit, etc.) Function void WDRV_STUB_GPIO_ModuleUnreset(void) WDRV_STUB_HardDelay Function Waits spinning for the delay milliseconds. Implementation: Dynamic File wdrv_winc1500_stub.h C void WDRV_STUB_HardDelay(uint16_t delay); Returns None. Description This function has driver wait spinining for the delay milliseconds. Remarks None. Preconditions The TCP/IP stack should be initialized. Parameters Parameters Description board duration to spin. Function WDRV_STUB_HardDelay(uint16_t delay) WDRV_STUB_INTR_Deinit Function Deinitializes interrupts for Wi-Fi driver. Implementation: Dynamic File wdrv_winc1500_stub.h C void WDRV_STUB_INTR_Deinit(); Returns None. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1425 Description This function deinitializes interrupts for the Wi-Fi driver. Remarks None. Preconditions The TCP/IP stack should be initialized. Function void WDRV_STUB_INTR_Deinit(void) WDRV_STUB_INTR_Init Function Initializes interrupts for the Wi-Fi driver. Implementation: Dynamic File wdrv_winc1500_stub.h C void WDRV_STUB_INTR_Init(void (*isr)(void)); Returns None. Description This function initializes interrupts for the Wi-Fi driver. Remarks None. Preconditions The TCP/IP stack should be initialized. Parameters Parameters Description isr function pointer to the interrupt service handler. Function void WDRV_STUB_INTR_Init(void (*isr)(void)) WDRV_STUB_INTR_SourceDisable Function Disables interrupts from the module. Implementation: Dynamic File wdrv_winc1500_stub.h C void WDRV_STUB_INTR_SourceDisable(); Returns None. Description This function disables interrupts from the module. Remarks None. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1426 Preconditions Wi-Fi initialization must be complete. Function void WDRV_STUB_INTR_SourceDisable(void) WDRV_STUB_INTR_SourceEnable Function Enables interrupts from the module. Implementation: Dynamic File wdrv_winc1500_stub.h C void WDRV_STUB_INTR_SourceEnable(); Returns None. Description This function enables interrupts from the module. Remarks None. Preconditions Wi-Fi initialization must be complete. Function void WDRV_STUB_INTR_SourceEnable(void) WDRV_STUB_SPI_Deinitialize Function Deinitializes the SPI object for the Wi-Fi driver. Implementation: Dynamic File wdrv_winc1500_stub.h C void WDRV_STUB_SPI_Deinitialize(); Returns None. Description This function deinitializes the SPI object for the Wi-Fi driver. Remarks None. Preconditions None. Function void WDRV_STUB_SPI_Deinitialize(void) WDRV_STUB_SPI_In Function Receives data from the module through the SPI bus. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1427 Implementation: Dynamic File wdrv_winc1500_stub.h C bool WDRV_STUB_SPI_In(unsigned char *const buf, uint32_t size); Returns None. Description This function receives data from the module through the SPI bus. Remarks None. Preconditions SPI driver should be initialized. Parameters Parameters Description buf buffer pointer of input data size the input data size Function bool WDRV_STUB_SPI_In(unsigned char *const buf, uint32_t size) WDRV_STUB_SPI_Initialize Function Initializes the SPI object for the Wi-Fi driver. Implementation: Dynamic File wdrv_winc1500_stub.h C void WDRV_STUB_SPI_Initialize(); Returns None. Description This function initializes the SPI object for the Wi-Fi driver. Remarks None. Preconditions None. Function void WDRV_STUB_SPI_Initialize(void) WDRV_STUB_SPI_Out Function Sends data out to the module through the SPI bus. Implementation: Dynamic File wdrv_winc1500_stub.h Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1428 C bool WDRV_STUB_SPI_Out(unsigned char *const buf, uint32_t size); Returns True - Indicates success False - Indicates failure Description This function sends data out to the module through the SPI bus. Remarks None. Preconditions SPI driver should be initialized. Parameters Parameters Description buf buffer pointer of output data size the output data size Function bool WDRV_STUB_SPI_Out(unsigned char const *buf, uint32_t size) e) Data Types and Constants _WDRV_WINC1500_API_H Macro File wdrv_winc1500_api.h C #define _WDRV_WINC1500_API_H Description This is macro _WDRV_WINC1500_API_H. WDRV_STUB_Print Macro File wdrv_winc1500_stub.h C #define WDRV_STUB_Print(x) SYS_CONSOLE_PRINT x Description This is macro WDRV_STUB_Print. Files Files Name Description wdrv_winc1500_api.h WINC1500 wireless driver APIs. wdrv_winc1500_stub.h WINC1500 wireless driver stub APIs. Description This section lists the source and header files used by the MRF24WN Wi-Fi Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1429 wdrv_winc1500_api.h WINC1500 wireless driver APIs. Functions Name Description WDRV_CLI_Init Initializes the console CLI interface. Implementation: Dynamic WDRV_EXT_CmdChannelSet Sets the channel on which to operate. Implementation: Dynamic WDRV_EXT_CmdConnect Directs the WINC1500 to connect to a Wi-Fi network. Implementation: Dynamic WDRV_EXT_CmdConnectContextBssidGet Gets the BSSID Implementation: Dynamic WDRV_EXT_CmdDisconnect Directs the WINC1500 to disconnect from a Wi-Fi network. Implementation: Dynamic WDRV_EXT_CmdFWUpdate Directs the module to start firmware download and upgrade. Implementation: Dynamic WDRV_EXT_CmdFWVersionGet Retrieves FW version information. Implementation: Dynamic WDRV_EXT_CmdMacAddressGet Retrieves the WINC1500 MAC address. Implementation: Dynamic WDRV_EXT_CmdNetModeAPSet Sets the Wi-Fi network type to SoftAP. Implementation: Dynamic WDRV_EXT_CmdNetModeBSSSet Sets the Wi-Fi network type to Infrastructure. Implementation: Dynamic WDRV_EXT_CmdPowerSavePut Puts the module in power save mode. Implementation: Dynamic WDRV_EXT_CmdScanGet Reads the number of scan results from the WINC1500 module. Implementation: Dynamic WDRV_EXT_CmdScanOptionsSet Sets scan options. Implementation: Dynamic WDRV_EXT_CmdScanStart Directs the WINC1500 module to start a scan. Implementation: Dynamic WDRV_EXT_CmdSecNoneSet Sets Wi-Fi security to open (no security). Implementation: Dynamic WDRV_EXT_CmdSecWEPSet Sets Wi-Fi security to use WEP. Implementation: Dynamic WDRV_EXT_CmdSecWPASet Sets Wi-Fi security to use WPA/WPA2. Implementation: Dynamic WDRV_EXT_CmdSecWpsSet Sets Wi-Fi security to use WPS. Implementation: Dynamic WDRV_EXT_CmdSSIDGet Gets the SSID. Implementation: Dynamic WDRV_EXT_CmdSSIDSet Sets the SSID. Implementation: Dynamic WDRV_EXT_CmdTxPowerSet Sets the Tx Power at 3 levels, high, medium and low. Implementation: Dynamic WDRV_EXT_DataSend Sends data packets to WINC1500 module. Implementation: Dynamic WDRV_EXT_Deinitialize Deinitializes the WINC1500 Wi-Fi driver. Implementation: Dynamic WDRV_EXT_HWInterruptHandler Wi-Fi driver (WINC1500-specific) interrupt service routine. Implementation: Dynamic WDRV_EXT_Initialize Initializes the WINC1500 Wi-Fi driver. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1430 WDRV_EXT_ModuleUpDown Enables or disables WINC1500 module. Implementation: Dynamic WDRV_EXT_MulticastFilterSet Sets a multicast address filter. Implementation: Dynamic WDRV_EXT_RssiRead Requests RSSI for the connected AP. Implementation: Dynamic WDRV_EXT_ScanResultGet Reads the selected scan results back from the WINC1500 module. Implementation: Dynamic WDRV_EXT_WPSResultsRead Reads the WPS process results back from the WINC1500 module and updates the configuration data. Implementation: Dynamic WDRV_WINC1500_ISR Wi-Fi driver (WINC1500-specific) interrupt service routine. Implementation: Dynamic Macros Name Description _WDRV_WINC1500_API_H This is macro _WDRV_WINC1500_API_H. Description WINC1500 wireless driver APIs. File Name wdrv_winc1500_api.h Company Microchip Technology Inc. wdrv_winc1500_stub.h WINC1500 wireless driver stub APIs. Functions Name Description WDRV_STUB_Assert Dumps out an error message on serial console and resets itself when the driver asserts. Implementation: Dynamic WDRV_STUB_GPIO_ChipDisable Disables the WINC1500 chip. Implementation: Dynamic WDRV_STUB_GPIO_ChipEnable Enables the WINC1500 chip. Implementation: Dynamic WDRV_STUB_GPIO_DeInitialize Deinitializes the GPIO object for the Wi-Fi driver. Implementation: Dynamic WDRV_STUB_GPIO_Initialize Initializes the GPIO object for the Wi-Fi driver. Implementation: Dynamic WDRV_STUB_GPIO_ModuleReset Resets the WINC1500 module. Implementation: Dynamic WDRV_STUB_GPIO_ModuleUnreset Unresets the WINC1500 module. Implementation: Dynamic WDRV_STUB_HardDelay Waits spinning for the delay milliseconds. Implementation: Dynamic WDRV_STUB_INTR_Deinit Deinitializes interrupts for Wi-Fi driver. Implementation: Dynamic WDRV_STUB_INTR_Init Initializes interrupts for the Wi-Fi driver. Implementation: Dynamic WDRV_STUB_INTR_SourceDisable Disables interrupts from the module. Implementation: Dynamic WDRV_STUB_INTR_SourceEnable Enables interrupts from the module. Implementation: Dynamic WDRV_STUB_SPI_Deinitialize Deinitializes the SPI object for the Wi-Fi driver. Implementation: Dynamic Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1431 WDRV_STUB_SPI_In Receives data from the module through the SPI bus. Implementation: Dynamic WDRV_STUB_SPI_Initialize Initializes the SPI object for the Wi-Fi driver. Implementation: Dynamic WDRV_STUB_SPI_Out Sends data out to the module through the SPI bus. Implementation: Dynamic Macros Name Description WDRV_STUB_Print This is macro WDRV_STUB_Print. Description WINC1500 wireless driver stub APIs. File Name wdrv_winc1500_stub.h Company Microchip Technology Inc. WINC1500 Socket Mode Driver Library This section provides documentation for the WINC1500 Socket Mode Driver Library. Introduction This library provides a low-level abstraction of the WINC1500 Socket Mode Driver 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 WINC1500 Socket Mode Driver library is a C library provides the host MCU application with APIs for WLAN and socket operations, off-loading the host MCU TCP/IP networking and transport layer operations to the WINC1500 module firmware. The MPLAB Harmony Integrated Software Framework blocks for the WINC1500 Wi-Fi Application are shown in the following diagram. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1432 The following diagram shows the partitioning of the MPLAB Harmony WINC1500 Socket Mode Driver software on a MCU. Further discussions reference this diagram. In the previous diagram, the WINC1500 module requires only a SPI interface, a timer, 2 GPIOs for CE and INT, and an interrupt line to connect to the host PIC32 MCU, as shown in the following figure. The figure also shows the I2C interface between the ECC508 device and the Host MCU; however, this feature is not available in the current release and will be available in a future release MPLAB Harmony. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1433 Using the Library This topic describes the basic architecture of the WINC1500 Wi-Fi Driver Library and provides information and examples on its use. Description The WINC1500 Socket Mode Driver Library implements the MPLAB Harmony device driver and communicates with the WINC1500 Host Driver Software to access and control the external WINC1500 module which firmware consists of the following key features: • Wi-Fi IEEE 802.11 b/g/n STA, AP, and Wi-Fi Direct® modes • Wi-Fi Protected Setup (WPS) • Support of WEP, WPA/WPA2 personal, and WPA/WPA2 Enterprise security • Embedded network stack protocols • Embedded 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 • 8 MB internal Flash memory with OTA firmware upgrade • Low power consumption with different power saving modes • SPI, I2C, and UART support The WINC1500 Host Driver Software is a C library which provides the host MCU application with necessary APIs to perform necessary WLAN and socket operations. The architecture of the WINC1500 Host Driver Software which runs on the host MCU is shown below, and the components of the host driver are described in the following diagram. WLAN Application Interface 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, etc.) – WPS activation/deactivation • Wi-Fi AP enable/disable • Wi-Fi Direct enable/disable • Wi-Fi power save control API • Wi-Fi monitoring (Sniffer) mode This interface is defined in the file: m2m_wifi.h. Socket API This module provides the socket communication APIs that are mostly compliant with the well-known BSD sockets. To comply with the nature of MCU application environment, there are differences in API prototypes and in usage of some APIs between WINC1500 sockets and BSD sockets. This interface is defined in the file: socket.h. Host Interface (HIF) The Host Interface is responsible for handling the communication between the host driver and the WINC1500 firmware. This includes interrupt handling, DMA and HIF command/response management. The host driver communicates with the firmware in a form of commands and responses formatted by the HIF layer. The interface is defined in the file: m2m_hif.h. 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…etc.). The minimum required BSP functionality is defined in the file: nm_bsp.h. Serial Bus Interface The Serial Bus Interface module abstracts the hardware associated with implementing the bus between the Host and the WINC1500. The serial bus interface abstracts I2C, SPI, or UART 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. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1434 The bus interface APIs are defined in the file: nm_bus_wrapper.h. Using the WINC1500 Socket Mode Driver Library The interface to the WINC1500 Socket Driver Library is defined in these header files: • wdrv_winc1500_api.h • wdrv_winc1500_stub.h Any C language source (.c) file that uses the WINC1500 Socket Mode Driver library should include both wdrv_winc1500_api.h and wdrv_winc1500_stub.h. Abstraction of the WINC1500 Wi-Fi Application The major blocks of software comprise of a WINC1500 Wi-Fi application are listed and described in the following table. Software Block Description Application Software This is the application code. Note that three event handlers (OTA, Socket, and Wi-Fi) are part of this block. The event handlers contain callback functions that the driver calls and the application processes. WINC1500 Socket Mode Driver This is the WINC1500 Socket Mode driver. The driver API and Stub functions provide application software with setup for the SPI interface between the host MCU and the external WINC1500 module, and provide application software with control and socket data services to the external WINC1500 module via the WINC1500 Host Software Driver. WINC1500 Socket Mode Driver Stub Functions The driver Stub functions provide application software with control to the PIC32 MCU hardware blocks (SPI, EXT_INT, Timer, GPIO, I2C) for configuration of Host PIC32 MCU specific hardware and event handling: • SPI Interface • GPIO control • Timer • Interrupt from WINC1500 • Wi-Fi, TPC/IP socket, and OTA event handling WINC1500 Socket Mode Driver API Functions The driver Ext functions provide application software access to the driver’s system interface for initialize and de-initialize of the driver, as well as setting up the driver hardware interrupt handler and the WINC1500 interrupt service routine. Note: Not all API functions are used in the socket mode driver library. Only these four API functions are used: • WDRV_EXT_Initialize • WDRV_EXT_Deinitialize • WDRV_EXT_HWInterruptHandler • WDRV_WINC1500_ISR WINC1500 Host Software Driver APIs The WINC1500 Host Software Driver provides the host MCU application with necessary APIs to perform necessary WLAN and BSD socket operations by offloading these operations to the WINC1500 module firmware. See Section 3 for details of these APIs. Abstraction Model This library provides a low-level abstraction of the WINC1500 Wi-Fi module with a convenient C language interface. This topic describes how that abstraction is modeled in software and introduces the library's interface. Description The WINC1500 Wi-Fi Library provides the following functionality: • Wi-Fi library initialization • Wi-Fi network configuration • Wi-Fi network connection • Scanning for existing Wi-Fi networks • Wi-Fi event processing • Wi-Fi status • Wi-FI console commands Library Overview Refer to the Driver Library Overview section for information on how the driver operates in a system. The Library Interface functions are divided into various sub-sections, which address one of the blocks or the overall operation of the WINC1500 Socket Mode Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1435 Library Interface Section Description System Interaction Functions Provides system module interfaces, device initialization, deinitialization, hard interrupt handler, and interrupt service routine. See wdrv_winc1500_api.h, and wdrv_winc1500_stub.h. Data Transfer Functions Provides data transfer functions available in the configuration. See wdrv_winc1500_api.h. Status Functions Provides status functions. See m2m_wifi.h Miscellaneous Functions Provides miscellaneous driver functions. How the Library Works This section describes how the WINC1500 Socket Mode Driver Library operates. Description The library provides host PIC32 MCU Wi-Fi application with interface support for the external WINC1500 module and offloads Wi-Fi and BSD socket operations to the WINC1500 module firmware. Configuring the SPI Driver This section describes the configuration settings for the WINC1500 Socket Mode Driver Library. Description Configuration The WINC1500 hardware requires a specific configuration of the SPI driver to work correctly. Inside the MHC SPI driver configuration make sure to select: • SPI clock rate of 8000000 or less • Input phrase of SPI_INPUT_SAMPLING_PHASE_AT_END • Clock mode of DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_FALL Recommended Settings • Interrupt Driver mode • Enhanced Buffer mode • DMA mode enabled • DMA Block Transfer Size to 512 • Size of DMA Buffer for dummy data to 512 • Ensure when setting up DMA in interrupt mode that the DMA interrupts are a higher priority than the SPI Driver interrupt Examples /*** SPI Driver Configuration ***/ #define DRV_SPI_NUMBER_OF_MODULES 6 /*** Driver Compilation and static configuration options. ***/ /*** Select SPI compilation units.***/ #define DRV_SPI_POLLED 0 #define DRV_SPI_ISR 1 #define DRV_SPI_MASTER 1 #define DRV_SPI_SLAVE 0 #define DRV_SPI_RM 1 #define DRV_SPI_EBM 0 #define DRV_SPI_8BIT 1 #define DRV_SPI_16BIT 0 #define DRV_SPI_32BIT 0 #define DRV_SPI_DMA 1 /*** SPI Driver Static Allocation Options ***/ #define DRV_SPI_INSTANCES_NUMBER 1 #define DRV_SPI_CLIENTS_NUMBER 1 #define DRV_SPI_ELEMENTS_PER_QUEUE 10 /*** SPI Driver DMA Options ***/ #define DRV_SPI_DMA_TXFER_SIZE 512 #define DRV_SPI_DMA_DUMMY_BUFFER_SIZE 512 /* SPI Driver Instance 0 Configuration */ #define DRV_SPI_SPI_ID_IDX0 SPI_ID_1 Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1436 #define DRV_SPI_TASK_MODE_IDX0 DRV_SPI_TASK_MODE_ISR #define DRV_SPI_SPI_MODE_IDX0 DRV_SPI_MODE_MASTER #define DRV_SPI_ALLOW_IDLE_RUN_IDX0 false #define DRV_SPI_SPI_PROTOCOL_TYPE_IDX0 DRV_SPI_PROTOCOL_TYPE_STANDARD #define DRV_SPI_COMM_WIDTH_IDX0 SPI_COMMUNICATION_WIDTH_8BITS #define DRV_SPI_CLOCK_SOURCE_IDX0 SPI_BAUD_RATE_PBCLK_CLOCK #define DRV_SPI_SPI_CLOCK_IDX0 CLK_BUS_PERIPHERAL_2 #define DRV_SPI_BAUD_RATE_IDX0 8000000 #define DRV_SPI_BUFFER_TYPE_IDX0 DRV_SPI_BUFFER_TYPE_STANDARD #define DRV_SPI_CLOCK_MODE_IDX0 DRV_SPI_CLOCK_MODE_IDLE_LOW_EDGE_FALL #define DRV_SPI_INPUT_PHASE_IDX0 SPI_INPUT_SAMPLING_PHASE_AT_END #define DRV_SPI_TRANSMIT_DUMMY_BYTE_VALUE_IDX0 0x00 #define DRV_SPI_TX_INT_SOURCE_IDX0 INT_SOURCE_SPI_1_TRANSMIT #define DRV_SPI_RX_INT_SOURCE_IDX0 INT_SOURCE_SPI_1_RECEIVE #define DRV_SPI_ERROR_INT_SOURCE_IDX0 INT_SOURCE_SPI_1_ERROR #define DRV_SPI_TX_INT_VECTOR_IDX0 INT_VECTOR_SPI1_TX #define DRV_SPI_RX_INT_VECTOR_IDX0 INT_VECTOR_SPI1_RX #define DRV_DRV_SPI_ERROR_INT_VECTOR_IDX0 INT_VECTOR_SPI1_FAULT #define DRV_SPI_TX_INT_PRIORITY_IDX0 INT_PRIORITY_LEVEL1 #define DRV_SPI_TX_INT_SUB_PRIORITY_IDX0 INT_SUBPRIORITY_LEVEL0 #define DRV_SPI_RX_INT_PRIORITY_IDX0 INT_PRIORITY_LEVEL1 #define DRV_SPI_RX_INT_SUB_PRIORITY_IDX0 INT_SUBPRIORITY_LEVEL0 #define DRV_SPI_ERROR_INT_PRIORITY_IDX0 INT_PRIORITY_LEVEL1 #define DRV_SPI_ERROR_INT_SUB_PRIORITY_IDX0 INT_SUBPRIORITY_LEVEL0 #define DRV_SPI_QUEUE_SIZE_IDX0 10 #define DRV_SPI_RESERVED_JOB_IDX0 1 #define DRV_SPI_TX_DMA_CHANNEL_IDX0 DMA_CHANNEL_1 #define DRV_SPI_TX_DMA_THRESHOLD_IDX0 16 #define DRV_SPI_RX_DMA_CHANNEL_IDX0 DMA_CHANNEL_0 #define DRV_SPI_RX_DMA_THRESHOLD_IDX0 16 WINC1500 Module Firmware Overview Provides an overview of the firmware for the WINC1500 Module. Description 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. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1437 WLAN APIs This WLAN APIs provide 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, etc.) • WPS activation/deactivation • Wi-Fi AP enable/disable • Wi-Fi Direct enable/disable • Wi-Fi power save control API • Wi-Fi monitoring (Sniffer) mode This interface is defined in the file: m2m_wifi.h. Socket API The socket APIs are mostly compliant with the BSD sockets and to comply with the nature of MCU application environment, there are differences in API prototypes and in usage of some APIs between WINC1500 sockets and BSD sockets. This interface is defined in the file: socket.h. IoT Library The IoT library provides a set of networking protocols in WINC1500 firmware. It offloads the host MCU from networking and transport layer protocols. The following sections describe the components of WINC1500 IoT library. • WINC1500 TCP/IP STACK - The WINC TCP/IP is an IPv4.0 stack based on the uIP TCP/IP stack (pronounced micro IP). • DHCP CLIENT/SERVER - A DHCP client is embedded in WINC1500 firmware that can obtain an IP configuration automatically after connecting to a Wi-Fi network. WINC1500 firmware provides an instance of a DHCP server that starts automatically when 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. • DNS RESOLVER – WINC1500 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. • SNTP - The SNTP (Simple Network Time Protocol) module implements an SNTP client used to synchronize the WINC1500 internal clock to the UTC clock. • EAP-TTLS/MSCHAPV2.0 - This module implements the authentication protocol EAP-TTLS/MsChapv2.0 used for establishing a Wi-Fi connection with an AP by with WPA-Enterprise security. • TRANSPORT LAYER SECURITY - For TLS implementation. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1438 • WI-FI PROTECTED SETUP - For WPS protocol implementation. • WI-FI DIRECT - For Wi-Fi Direct protocol implementation. • CRYPTO LIBRARY - The Crypto Library contains a set of cryptographic algorithms used by 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) • 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) Host Interface Driver Wi-Fi Events Provides information on the Host Interface Driver Wi-Fi events. Description There are four categories of events: • Wi-Fi events • Socket events • OTA (Over-The-Air) update events • Error Events Wi-Fi Events Wi-Fi events must be customized to suit the application. The WINC1500 socket driver calls the event callback function to notify the application of Wi-Fi events. The p_eventData parameter points to a ‘C’ union of containing all possible Wi-Fi event data. Not all events have data associated with them – in this case the pointer will be NULL. When an event occurs, the event data should be read as soon as possible before another event occurs which will overwrite data from the previous event. If the event data is to be retrieved outside the event handler function, the utility function m2m_wifi_get_wifi_event_data() returns a pointer to the t_wifiEventData union. Socket Events Socket events are handled, but must be customized to suit the application. The WINC1500 driver calls the socket event callback function to notify the application of socket events. The p_eventData parameter points to a ‘C’ union of containing all possible socket event data. Not all events have data associated with them – in this case the pointer will be NULL. When an event occurs, the event data should be read as soon as possible before another event occurs which will overwrite data from the previous event. If the event data is to be retrieved outside the event handler function, the utility function m2m_wifi_get_socket_event_data() returns a pointer to the t_socketEventData union. OTA Events OTA events are associated with downloading and switching to a new WINC1500 firmware image downloaded via the Wi-Fi network. The WINC1500 driver calls the OTA event callback function to notify the application of OTA events. The p_eventData parameter points to a ‘C’ structure containing the OTA event data. If the event data is to be retrieved outside the event handler function, the utility function m2m_wifi_get_ota_event_data() returns a pointer to the t_otaEventData structure. Error Events The application is notified of error events via the callback. Error codes are defined in: wf_errors.h. Configuring the Library This section describes how to configure the WINC1500 Wi-Fi driver. Description The configuration of the WINC1500 Wi-Fi Driver is based on the file system_config.h. This header file contains the configuration selection for the WINC1500 Socket Mode Driver Library. Based on the selection, the WINC1500 Socket Mode Driver Library may support the selected features. These configuration settings will apply to all instances of the WINC1500 Socket Mode Driver Library. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1439 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 in the WINC1500 Wi-Fi Driver Library. 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 /framework/driver/wifi/winc1500. Interface File(s) This table lists and describes the header files that must be included (i.e., using #include) by any code that uses this library. Source File Name Description wdrv_winc1500_stub.h Contains Stub function prototypes for interfacing to the WINC1500 Wi-Fi Driver. wdrv_winc1500_api.h Contains API function prototypes for interfacing to the WINC1500 Wi-Fi Driver. 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 Folder Name Description /driver/wifi/winc1500/dev/console/wdrv_winc1500_console.c Console module for WINC1500 wireless driver. /driver/wifi/winc1500/dev/gpio/wdrv_winc1500_eint.c External interrupt handler for WINC1500 wireless driver. /driver/wifi/winc1500/dev/gpio/wdrv_winc1500_gpio.c GPIO interface for WINC1500 wireless driver. /driver/wifi/winc1500/dev/spi/wdrv_winc1500_spi.c Support SPI communications to the WINC1500 module. /driver/wifi/winc1500/dev/timer/wdrv_winc1500_timer.c Timer functions for WINC1500 wireless driver. /driver/wifi/winc1500/osal/wdrv_winc1500_osal.c OS abstraction layer for WINC1500 wireless driver. /driver/wifi/winc1500/wireless_driver_extension/common/source/nm_common.c This module contains common APIs implementations. /driver/wifi/winc1500/wireless_driver_extension/driver/source/m2m_hif.c This module contains M2M host interface API implementations. /driver/wifi/winc1500/wireless_driver_extension/driver/source/m2m_ota.c WINC1500 IoT OTA Interface. /driver/wifi/winc1500/wireless_driver_extension/driver/source/m2m_periph.c WINC1500 Peripherals Application Interface. /driver/wifi/winc1500/wireless_driver_extension/driver/source/m2m_wifi.c This module contains M2M Wi-Fi APIs implementation. /driver/wifi/winc1500/wireless_driver_extension/driver/source/nmasic.c This module contains WINC1500 ASIC specific internal APIs. /driver/wifi/winc1500/wireless_driver_extension/driver/source/nmbus.c This module contains WINC1500 bus APIs implementation. /driver/wifi/winc1500/wireless_driver_extension/driver/source/nmdrv.c This module contains WINC1500 M2M driver APIs implementation. /driver/wifi/winc1500/wireless_driver_extension/driver/source/nmspi.c This module contains WINC1500 SPI protocol bus APIs implementation. /driver/wifi/winc1500/wireless_driver_extension/socket/source/socket.c WINC1500 BSD Compatible Socket Interface. /driver/wifi/winc1500/wireless_driver_extension/spi_flash/source/spi_flash.c WINC1500 SPI flash interface. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1440 /driver/wifi/winc1500/wireless_driver_extension/wdrvext_winc1500.c WINC1500 wireless driver extension. /driver/wifi/winc1500/wireless_driver_extension/winc1500_fw_update.c WINC1500 firmware update support. /driver/wifi/winc1500/wireless_driver_extension/winc1500_task.c Entry point of WINC1500 core driver. 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 N/A The WINC1500 Wi-Fi Driver controller has no optional files. Module Dependencies The WINC1500 Socket Mode Driver Library depends on the following modules: • SPI Driver Library • SPI Flash Driver Library • WINC1500 Wi-Fi Driver Ethernet Mode Library • Timer Driver Library • USART Driver Library Library Interface This section describes the Application Programming Interface (API) functions of the WINC1500 Socket Mode Driver. Refer to the WINC1500 Wi-Fi Driver Library > Library Interface section for information on the APIs in that library that are also used by the WINC1500 Socket Mode Driver. Refer to each section for a detailed description. WINC1500 Firmware Update Utility Refer to WINC1500 Firmware Update Guide for detailed information on using the firmware update utility. Volume V: MPLAB Harmony Framework Driver Libraries Help Wi-Fi Driver Libraries © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1441 Index _ _DRV_AK4642_H macro 189 _DRV_AK4953_H macro 232 _DRV_AK7755_H macro 305 _DRV_CAMERA_OVM7690_delayMS function 95 _DRV_CAMERA_OVM7690_DMAEventHandler function 95 _DRV_CAMERA_OVM7690_HardwareSetup function 95 _DRV_COMMON_H macro 18 _DRV_ENC28J60_Configuration structure 424 _DRV_ENCX24J600_Configuration structure 444 _DRV_IPF_CONFIG_TEMPLATE_H macro 879 _DRV_IPF_H macro 878 _DRV_MIIM_CONFIG_H macro 620 _DRV_MTCH6301_CLIENT_OBJECT structure 1072 _DRV_MXT_CLIENT_OBJECT structure 1132 _DRV_MXT336T_H macro 1139 _DRV_PMP_QUEUE_ELEMENT_OBJ structure 706 _DRV_SDCARD_INIT structure 737 _DRV_SRAM_H macro 968 _DRV_TOUCH_ADC10BIT_CLIENT_DATA structure 1030 _DRV_TOUCH_ADC10BIT_INIT structure 1031 _DRV_WM8904_CONFIG_TEMPLATE_H macro 320 _DRV_WM8904_H macro 342 _PLIB_UNSUPPORTED macro 19 _WDRV_WINC1500_API_H macro 1429 1 10-bit ADC Touch Driver Library 1017 A a) System Interaction Functions 362 Abstraction Model 27, 81, 106, 157, 199, 238, 278, 317, 360, 378, 408, 428, 447, 469, 516, 520, 553, 611, 614, 618, 645, 682, 715, 744, 772, 848, 882, 918, 946, 970, 1034, 1038, 1056, 1078, 1108, 1177, 1236, 1295, 1352, 1386, 1394, 1435 ADC Touch Driver Library 1034 AK4384 Codec Driver Library 106 AK4642 Codec Driver Library 157 AK4953 Codec Driver Library 199 AK4954 Codec Driver Library 238 AK7755 Codec Driver Library 278 AR1021 Touch Driver Library 1038 BM64 Bluetooth Driver Library 27 CTR Driver Library 360 Data EEPROM Driver Library 378 Ethernet MAC Driver Library 447, 516 Ethernet PHY Driver Library 469 MIIM Driver Library 618 MRF24WN Wi-Fi Driver Library 1352 MTCH6301 Touch Driver Library 1056 MTCH6303 Touch Driver Library 1078 NVM Driver Library 645 PMP Driver Library 682 SD Card Driver Library 715 SPI Driver Library 744 SPI Flash Driver Library 772 SPI PIC32WK IPF Flash Driver Library 848 SQI Driver Library 882 SQI Flash Driver Library 918 Timer Driver Library 970 USART Driver Library 1295 WILC1000 Wi-Fi Driver Library 1386 WINC1500 Socket Mode Driver Library 1435 WINC1500 Wi-Fi Driver Library 1394 WM8904 Codec Driver Library 317 ADC Driver Library 20 ADC Touch Driver Library 1034 AK4384 Codec Driver Library 105 AK4642 Codec Driver Library 156 AK4953 Codec Driver Library 198 AK4954 Codec Driver Library 237 AK7755 Codec Driver Library 277 Alarm Functionality 974 AR1021 Touch Driver Library 1038 AVRCP Functions 32 B b) Other Functions 365 BLE Functions 32 Block Operations 774, 850 Bluetooth Driver Libraries 25 BM64 Bluetooth Driver Library 25 Buffer Queue Transfer Model 1304 Building the Library 36, 83, 119, 168, 206, 246, 286, 323, 351, 361, 384, 411, 430, 452, 473, 518, 533, 570, 613, 621, 654, 689, 721, 754, 782, 851, 889, 923, 951, 979, 1020, 1037, 1043, 1062, 1079, 1114, 1188, 1246, 1315, 1355, 1389, 1397, 1440 10-bit ADC Touch Driver Library 1020 ADC Touch Driver Library 1037 AK4384 Driver Library 119 AK4642 Driver Library 168 AK4953 Driver Library 206 AK4954 Driver Library 246 AK7755 Driver Library 286 AR1021 Touch Driver Library 1043 BM64 Bluetooth Driver Library 36 CPLD XC2C64A Driver Library 351 CTR Driver Library 361 Data EEPROM Driver Library 384 ENC28J60 Driver Library 411 ENCX24J600 Driver Library 430 Ethernet MAC Driver Library 452, 518 Ethernet PHY Driver Library 473 I2C Driver Library 533 I2S Driver Library 570 MRF24WN Wi-Fi Driver Library 1355, 1389, 1397, 1440 MTCH6301 Touch Driver Library 1062 MTCH6303 Touch Driver Library 1079 NVM Driver Library 654 PMP Driver Library 689 SD Card Driver Library 721 SPI Driver Library 754 SPI Flash Driver Library 782 SPI PIC32WK IPF Flash Driver Library 851 SQI Driver Library 889 SQI Flash Driver Library 923 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1442 Timer Driver Library 979 USART Driver Library 1315 WM8904 Driver Library 323 Byte Transfer Model 1302 C c) Data Types and Constants 371 Camera Driver Libraries 72 CAMERA_MODULE_ID enumeration 79 CAN Driver Library 102 Client Access 109, 159, 201, 240, 280, 319, 523, 555, 746 Client Access Operation 647, 717 Client Block Data Operation 648, 718 Client Block Operation Functions 949 Client Core Functions 884, 949 Client Data Transfer Functions 885 Client Functionality 1353 Client Functions 30 Client Interaction 972 Client Operation 686 Client Operations 109, 160, 201, 240, 280, 319 Client Operations - Buffered 556 Client Operations - Non-buffered 561 Client Transfer 523 Client Transfer - Core 747 Codec Driver Libraries 105 Common Interface 1147 Comparator Driver Library 349 Configuring in MPLAB Harmony Configurator 617 Configuring the Library 33, 82, 115, 165, 203, 243, 283, 320, 351, 361, 382, 410, 430, 449, 471, 518, 528, 565, 613, 619, 650, 688, 719, 749, 775, 851, 887, 922, 951, 976, 1018, 1037, 1040, 1059, 1079, 1111, 1185, 1243, 1306, 1354, 1387, 1395, 1439 10-bit ADC Touch Driver Library 1018 ADC Touch Driver Library 1037 AK4384 Driver Library 115 AK4642 Driver Library 165 AK4953 Driver Library 203 AK4954 Driver Library 243 AK7755 Driver Library 283 AR1021 Touch Driver Library 1040 BM64 Bluetooth Driver Library 33 CPLD XC2C64A Driver Library 351 CTR Driver Library 361 Data EEPROM Driver Library 382 Ethernet MAC Driver Library 449, 518 Ethernet PHY Driver Library 471 MRF24WN Wi-Fi Driver Library 1354, 1387, 1395, 1439 MTCH6301 Touch Driver Library 1059 MTCH6303 Touch Driver Library 1079 NVM Driver Library 619, 650 PMP Driver Library 688 SD Card Driver Library 719 SPI Driver Library 749 SPI Flash Driver Library 775 SPI PIC32WK IPF Flash Driver Library 851 SQI Driver Library 887 SQI Flash Driver Library 922 Timer Driver Library 976 USART Driver Library 1306 WM8904 Driver Library 320 Configuring the MHC 35, 118, 167, 205, 245, 285, 322, 1114 BM64 Bluetooth Driver Library 35 Configuring the SPI Driver 409, 429, 1436 Console Commands 1356, 1390, 1398 Core Functionality 974 Counter Modification 973 CPLD XC2C64A Driver Library 350 CPLD_DEVICE_CONFIGURATION enumeration 358 CPLD_GFX_CONFIGURATION enumeration 358 CPLD_SPI_CONFIGURATION enumeration 359 CPLDGetDeviceConfiguration function 352 CPLDGetGraphicsConfiguration function 353 CPLDGetSPIConfiguration function 353 CPLDInitialize function 354 CPLDSetGraphicsConfiguration function 354 CPLDSetSPIFlashConfiguration function 355 CPLDSetWiFiConfiguration function 356 CPLDSetZigBeeConfiguration function 357 CTR Driver Library 360 D Data EEPROM Driver Library 377 Data Transfer Function 30 DATA_LENGTH enumeration 313 Device Endpoint Operations 1170 Driver Device Mode Client Functions 1156 Driver General Client Functions 1151 Driver Host Mode Client Functions 1152 Driver Host Root Hub Interface 1155 Driver Host USB Root Hub Port Interface 1154 Driver Libraries Help 3 Driver Library Overview 3 Driver Tasks Routine 1305 driver.h 19 driver_common.h 20 DRV_ADC_Deinitialize function 21 DRV_ADC_Initialize function 21 DRV_ADC_SamplesAvailable function 22 DRV_ADC_SamplesRead function 22 DRV_ADC_Start function 23 DRV_ADC_Stop function 23 drv_adc10bit.h 1032 DRV_ADC10BIT_CALIBRATION_DELAY macro 1018 DRV_ADC10BIT_CALIBRATION_INSET macro 1018 DRV_ADC10BIT_CLIENTS_NUMBER macro 1018 drv_adc10bit_config_template.h 1034 DRV_ADC10BIT_INDEX macro 1019 DRV_ADC10BIT_INSTANCES_NUMBER macro 1019 DRV_ADC10BIT_INTERRUPT_MODE macro 1019 DRV_ADC10BIT_MODULE_ID enumeration 1030 DRV_ADC10BIT_SAMPLE_POINTS macro 1020 DRV_ADC10BIT_TOUCH_DIAMETER macro 1020 DRV_ADCx_Close function 24 DRV_ADCx_Open function 24 drv_ak4384.h 154 DRV_AK4384_AUDIO_DATA_FORMAT enumeration 146 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1443 DRV_AK4384_BCLK_BIT_CLK_DIVISOR macro 117 DRV_AK4384_BUFFER_EVENT enumeration 147 DRV_AK4384_BUFFER_EVENT_HANDLER type 147 DRV_AK4384_BUFFER_HANDLE type 148 DRV_AK4384_BUFFER_HANDLE_INVALID macro 152 DRV_AK4384_BufferAddWrite function 138 DRV_AK4384_BufferCombinedQueueSizeGet function 141 DRV_AK4384_BufferEventHandlerSet function 139 DRV_AK4384_BufferProcessedSizeGet function 143 DRV_AK4384_BufferQueueFlush function 142 DRV_AK4384_CHANNEL enumeration 149 DRV_AK4384_ChannelOutputInvertDisable function 127 DRV_AK4384_ChannelOutputInvertEnable function 128 DRV_AK4384_CLIENTS_NUMBER macro 115 DRV_AK4384_Close function 126 DRV_AK4384_COMMAND_EVENT_HANDLER type 149 DRV_AK4384_CommandEventHandlerSet function 144 drv_ak4384_config_template.h 156 DRV_AK4384_CONTROL_CLOCK macro 115 DRV_AK4384_COUNT macro 152 DRV_AK4384_DEEMPHASIS_FILTER enumeration 150 DRV_AK4384_DeEmphasisFilterSet function 128 DRV_AK4384_Deinitialize function 122 DRV_AK4384_INDEX_0 macro 152 DRV_AK4384_INDEX_1 macro 153 DRV_AK4384_INDEX_2 macro 153 DRV_AK4384_INDEX_3 macro 153 DRV_AK4384_INDEX_4 macro 153 DRV_AK4384_INDEX_5 macro 153 DRV_AK4384_INIT structure 150 DRV_AK4384_Initialize function 121 DRV_AK4384_INPUT_REFCLOCK macro 116 DRV_AK4384_INSTANCES_NUMBER macro 116 DRV_AK4384_MCLK_MODE enumeration 151 DRV_AK4384_MCLK_SAMPLE_FREQ_MULTPLIER macro 117 DRV_AK4384_MuteOff function 129 DRV_AK4384_MuteOn function 130 DRV_AK4384_Open function 125 DRV_AK4384_SamplingRateGet function 130 DRV_AK4384_SamplingRateSet function 131 DRV_AK4384_SetAudioCommunicationMode function 125 DRV_AK4384_SlowRollOffFilterDisable function 132 DRV_AK4384_SlowRollOffFilterEnable function 132 DRV_AK4384_Status function 123 DRV_AK4384_Tasks function 124 DRV_AK4384_TIMER_DRIVER_MODULE_INDEX macro 116 DRV_AK4384_TIMER_PERIOD macro 117 DRV_AK4384_VersionGet function 145 DRV_AK4384_VersionStrGet function 146 DRV_AK4384_VolumeGet function 133 DRV_AK4384_VolumeSet function 134 DRV_AK4384_ZERO_DETECT_MODE enumeration 151 DRV_AK4384_ZeroDetectDisable function 134 DRV_AK4384_ZeroDetectEnable function 135 DRV_AK4384_ZeroDetectInvertDisable function 136 DRV_AK4384_ZeroDetectInvertEnable function 136 DRV_AK4384_ZeroDetectModeSet function 137 drv_ak4642.h 196 DRV_AK4642_AUDIO_DATA_FORMAT enumeration 191 DRV_AK4642_BCLK_BIT_CLK_DIVISOR macro 165 DRV_AK4642_BUFFER_EVENT enumeration 192 DRV_AK4642_BUFFER_EVENT_HANDLER type 192 DRV_AK4642_BUFFER_HANDLE type 193 DRV_AK4642_BUFFER_HANDLE_INVALID macro 189 DRV_AK4642_BufferAddRead function 183 DRV_AK4642_BufferAddWrite function 181 DRV_AK4642_BufferAddWriteRead function 184 DRV_AK4642_BufferEventHandlerSet function 185 DRV_AK4642_CHANNEL enumeration 193 DRV_AK4642_CLIENTS_NUMBER macro 166 DRV_AK4642_Close function 174 DRV_AK4642_COMMAND_EVENT_HANDLER type 194 DRV_AK4642_CommandEventHandlerSet function 187 drv_ak4642_config_template.h 198 DRV_AK4642_COUNT macro 190 DRV_AK4642_Deinitialize function 171 DRV_AK4642_INDEX_0 macro 190 DRV_AK4642_INDEX_1 macro 190 DRV_AK4642_INDEX_2 macro 191 DRV_AK4642_INDEX_3 macro 191 DRV_AK4642_INDEX_4 macro 191 DRV_AK4642_INDEX_5 macro 191 DRV_AK4642_INIT structure 195 DRV_AK4642_Initialize function 170 DRV_AK4642_INPUT_REFCLOCK macro 166 DRV_AK4642_INSTANCES_NUMBER macro 166 DRV_AK4642_INT_EXT_MIC enumeration 195 DRV_AK4642_IntExtMicSet function 179 DRV_AK4642_MCLK_SAMPLE_FREQ_MULTPLIER macro 166 DRV_AK4642_MCLK_SOURCE macro 167 DRV_AK4642_MIC enumeration 196 DRV_AK4642_MicSet function 181 DRV_AK4642_MONO_STEREO_MIC enumeration 195 DRV_AK4642_MonoStereoMicSet function 180 DRV_AK4642_MuteOff function 175 DRV_AK4642_MuteOn function 176 DRV_AK4642_Open function 173 DRV_AK4642_SamplingRateGet function 177 DRV_AK4642_SamplingRateSet function 177 DRV_AK4642_SetAudioCommunicationMode function 180 DRV_AK4642_Status function 172 DRV_AK4642_Tasks function 173 DRV_AK4642_VersionGet function 188 DRV_AK4642_VersionStrGet function 189 DRV_AK4642_VolumeGet function 178 DRV_AK4642_VolumeSet function 178 drv_ak4953.h 235 DRV_AK4953_AUDIO_DATA_FORMAT enumeration 228 DRV_AK4953_BCLK_BIT_CLK_DIVISOR macro 203 DRV_AK4953_BUFFER_EVENT enumeration 228 DRV_AK4953_BUFFER_EVENT_HANDLER type 229 DRV_AK4953_BUFFER_HANDLE type 230 DRV_AK4953_BUFFER_HANDLE_INVALID macro 232 DRV_AK4953_BufferAddRead function 225 DRV_AK4953_BufferAddWrite function 220 DRV_AK4953_BufferAddWriteRead function 221 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1444 DRV_AK4953_BufferEventHandlerSet function 214 DRV_AK4953_CHANNEL enumeration 234 DRV_AK4953_CLIENTS_NUMBER macro 203 DRV_AK4953_Close function 211 DRV_AK4953_COMMAND_EVENT_HANDLER type 230 DRV_AK4953_CommandEventHandlerSet function 213 drv_ak4953_config_template.h 237 DRV_AK4953_COUNT macro 232 DRV_AK4953_Deinitialize function 210 DRV_AK4953_DIGITAL_BLOCK_CONTROL enumeration 231 DRV_AK4953_INDEX_0 macro 232 DRV_AK4953_INDEX_1 macro 233 DRV_AK4953_INDEX_2 macro 233 DRV_AK4953_INDEX_3 macro 233 DRV_AK4953_INDEX_4 macro 233 DRV_AK4953_INDEX_5 macro 234 DRV_AK4953_INIT structure 231 DRV_AK4953_Initialize function 209 DRV_AK4953_INPUT_REFCLOCK macro 204 DRV_AK4953_INSTANCES_NUMBER macro 204 DRV_AK4953_INT_EXT_MIC enumeration 234 DRV_AK4953_IntExtMicSet function 226 DRV_AK4953_MCLK_SAMPLE_FREQ_MULTPLIER macro 204 DRV_AK4953_MCLK_SOURCE macro 204 DRV_AK4953_MIC enumeration 235 DRV_AK4953_MicSet function 227 DRV_AK4953_MONO_STEREO_MIC enumeration 234 DRV_AK4953_MonoStereoMicSet function 227 DRV_AK4953_MuteOff function 223 DRV_AK4953_MuteOn function 224 DRV_AK4953_Open function 210 DRV_AK4953_QUEUE_DEPTH_COMBINED macro 205 DRV_AK4953_SamplingRateGet function 217 DRV_AK4953_SamplingRateSet function 215 DRV_AK4953_SetAudioCommunicationMode function 216 DRV_AK4953_Status function 217 DRV_AK4953_Tasks function 212 DRV_AK4953_VersionGet function 218 DRV_AK4953_VersionStrGet function 219 DRV_AK4953_VolumeGet function 219 DRV_AK4953_VolumeSet function 225 drv_ak4954.h 275 DRV_AK4954_AUDIO_DATA_FORMAT enumeration 268 DRV_AK4954_BCLK_BIT_CLK_DIVISOR macro 243 DRV_AK4954_BUFFER_EVENT enumeration 268 DRV_AK4954_BUFFER_EVENT_HANDLER type 269 DRV_AK4954_BUFFER_HANDLE type 270 DRV_AK4954_BUFFER_HANDLE_INVALID macro 273 DRV_AK4954_BufferAddRead function 261 DRV_AK4954_BufferAddWrite function 262 DRV_AK4954_BufferAddWriteRead function 263 DRV_AK4954_BufferEventHandlerSet function 254 DRV_AK4954_CHANNEL enumeration 270 DRV_AK4954_CLIENTS_NUMBER macro 243 DRV_AK4954_Close function 251 DRV_AK4954_COMMAND_EVENT_HANDLER type 270 DRV_AK4954_CommandEventHandlerSet function 253 drv_ak4954_config_template.h 277 DRV_AK4954_COUNT macro 273 DRV_AK4954_Deinitialize function 250 DRV_AK4954_DIGITAL_BLOCK_CONTROL enumeration 271 DRV_AK4954_INDEX_0 macro 274 DRV_AK4954_INDEX_1 macro 274 DRV_AK4954_INDEX_2 macro 274 DRV_AK4954_INDEX_3 macro 274 DRV_AK4954_INDEX_4 macro 275 DRV_AK4954_INDEX_5 macro 275 DRV_AK4954_INIT structure 272 DRV_AK4954_Initialize function 249 DRV_AK4954_INPUT_REFCLOCK macro 244 DRV_AK4954_INSTANCES_NUMBER macro 244 DRV_AK4954_INT_EXT_MIC enumeration 272 DRV_AK4954_IntExtMicSet function 265 DRV_AK4954_MCLK_SAMPLE_FREQ_MULTPLIER macro 244 DRV_AK4954_MCLK_SOURCE macro 244 DRV_AK4954_MIC enumeration 272 DRV_AK4954_MicSet function 265 DRV_AK4954_MONO_STEREO_MIC enumeration 273 DRV_AK4954_MonoStereoMicSet function 266 DRV_AK4954_MuteOff function 266 DRV_AK4954_MuteOn function 267 DRV_AK4954_Open function 250 DRV_AK4954_QUEUE_DEPTH_COMBINED macro 245 DRV_AK4954_SamplingRateGet function 257 DRV_AK4954_SamplingRateSet function 255 DRV_AK4954_SetAudioCommunicationMode function 256 DRV_AK4954_Status function 257 DRV_AK4954_Tasks function 252 DRV_AK4954_VersionGet function 258 DRV_AK4954_VersionStrGet function 259 DRV_AK4954_VolumeGet function 259 DRV_AK4954_VolumeSet function 260 drv_ak7755.h 314 DRV_AK7755_BCLK_BIT_CLK_DIVISOR macro 283 DRV_AK7755_BICK_FS_FORMAT enumeration 307 DRV_AK7755_BUFFER_EVENT enumeration 307 DRV_AK7755_BUFFER_EVENT_HANDLER type 308 DRV_AK7755_BUFFER_HANDLE type 309 DRV_AK7755_BUFFER_HANDLE_INVALID macro 305 DRV_AK7755_BufferAddRead function 300 DRV_AK7755_BufferAddWrite function 301 DRV_AK7755_BufferAddWriteRead function 303 DRV_AK7755_BufferEventHandlerSet function 292 DRV_AK7755_CHANNEL enumeration 309 DRV_AK7755_CLIENTS_NUMBER macro 283 DRV_AK7755_Close function 288 DRV_AK7755_COMMAND_EVENT_HANDLER type 310 DRV_AK7755_CommandEventHandlerSet function 294 drv_ak7755_config_template.h 315 DRV_AK7755_COUNT macro 306 DRV_AK7755_DAC_INPUT_FORMAT enumeration 310 DRV_AK7755_Deinitialize function 289 DRV_AK7755_DSP_DIN1_INPUT_FORMAT enumeration 311 DRV_AK7755_DSP_DOUT1_OUTPUT_FORMAT enumeration 311 DRV_AK7755_DSP_DOUT4_OUTPUT_FORMAT enumeration 311 DRV_AK7755_DSP_PROGRAM enumeration 312 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1445 DRV_AK7755_INDEX_0 macro 306 DRV_AK7755_INDEX_1 macro 306 DRV_AK7755_INDEX_2 macro 306 DRV_AK7755_INDEX_3 macro 307 DRV_AK7755_INDEX_4 macro 307 DRV_AK7755_INDEX_5 macro 307 DRV_AK7755_INIT structure 312 DRV_AK7755_Initialize function 290 DRV_AK7755_INPUT_REFCLOCK macro 284 DRV_AK7755_INSTANCES_NUMBER macro 284 DRV_AK7755_INT_EXT_MIC enumeration 312 DRV_AK7755_IntExtMicSet function 303 DRV_AK7755_LRCK_IF_FORMAT enumeration 313 DRV_AK7755_MCLK_SAMPLE_FREQ_MULTPLIER macro 284 DRV_AK7755_MCLK_SOURCE macro 285 DRV_AK7755_MONO_STEREO_MIC enumeration 313 DRV_AK7755_MonoStereoMicSet function 303 DRV_AK7755_MuteOff function 304 DRV_AK7755_MuteOn function 304 DRV_AK7755_Open function 291 DRV_AK7755_SamplingRateGet function 296 DRV_AK7755_SamplingRateSet function 295 DRV_AK7755_SetAudioCommunicationMode function 296 DRV_AK7755_Status function 297 DRV_AK7755_Tasks function 292 DRV_AK7755_VersionGet function 297 DRV_AK7755_VersionStrGet function 298 DRV_AK7755_VolumeGet function 299 DRV_AK7755_VolumeSet function 299 drv_ar1021.h 1055 DRV_AR1021_CALIBRATION_DELAY macro 1040 DRV_AR1021_CALIBRATION_INSET macro 1041 DRV_AR1021_CLIENTS_NUMBER macro 1041 DRV_AR1021_INDEX macro 1041 DRV_AR1021_INSTANCES_NUMBER macro 1042 DRV_AR1021_INTERRUPT_MODE macro 1042 DRV_AR1021_SAMPLE_POINTS macro 1042 DRV_AR1021_TOUCH_DIAMETER macro 1042 drv_bm64.h 70 DRV_BM64_BLE_EnableAdvertising function 65 DRV_BM64_BLE_QueryStatus function 64 DRV_BM64_BLE_STATUS enumeration 70 DRV_BM64_BUFFER_EVENT macro 66 DRV_BM64_BUFFER_EVENT_COMPLETE macro 66 DRV_BM64_BUFFER_EVENT_HANDLER type 67 DRV_BM64_BUFFER_HANDLE macro 66 DRV_BM64_BUFFER_HANDLE_INVALID macro 66 DRV_BM64_BufferAddRead function 44 DRV_BM64_BufferEventHandlerSet function 41 DRV_BM64_CancelForwardOrRewind function 52 DRV_BM64_ClearBLEData function 61 DRV_BM64_Close function 42 drv_bm64_config_template.h 72 DRV_BM64_DATA32 macro 66 DRV_BM64_DisconnectAllLinks function 49 DRV_BM64_DRVR_STATUS enumeration 67 DRV_BM64_EnterBTPairingMode function 50 DRV_BM64_EVENT enumeration 67 DRV_BM64_EVENT_HANDLER type 68 DRV_BM64_EventHandlerSet function 43 DRV_BM64_FastForward function 53 DRV_BM64_ForgetAllLinks function 50 DRV_BM64_GetBDAddress function 59 DRV_BM64_GetBDName function 60 DRV_BM64_GetLinkStatus function 51 DRV_BM64_GetPlayingStatus function 54 DRV_BM64_GetPowerStatus function 38 DRV_BM64_Initialize function 39 DRV_BM64_LinkLastDevice function 52 DRV_BM64_LINKSTATUS enumeration 68 DRV_BM64_MAXBDNAMESIZE macro 67 DRV_BM64_Open function 43 DRV_BM64_Pause function 55 DRV_BM64_Play function 55 DRV_BM64_PLAYINGSTATUS enumeration 69 DRV_BM64_PlayNextSong function 56 DRV_BM64_PlayPause function 57 DRV_BM64_PlayPreviousSong function 57 DRV_BM64_PROTOCOL enumeration 69 DRV_BM64_ReadByteFromBLE function 62 DRV_BM64_ReadDataFromBLE function 62 DRV_BM64_REQUEST enumeration 69 DRV_BM64_Rewind function 58 DRV_BM64_SAMPLE_FREQUENCY enumeration 70 DRV_BM64_SamplingRateGet function 46 DRV_BM64_SamplingRateSet function 46 DRV_BM64_SendByteOverBLE function 63 DRV_BM64_SendDataOverBLE function 64 DRV_BM64_SetBDName function 61 DRV_BM64_Status function 39 DRV_BM64_Stop function 59 DRV_BM64_TaskReq function 40 DRV_BM64_Tasks function 40 DRV_BM64_volumeDown function 47 DRV_BM64_VolumeGet function 48 DRV_BM64_VolumeSet function 48 DRV_BM64_volumeUp function 48 drv_camera.h 79 DRV_CAMERA_Close function 73 DRV_CAMERA_Deinitialize function 73 DRV_CAMERA_INDEX_0 macro 78 DRV_CAMERA_INDEX_1 macro 78 DRV_CAMERA_INDEX_COUNT macro 78 DRV_CAMERA_INIT structure 77 DRV_CAMERA_Initialize function 74 DRV_CAMERA_INTERRUPT_PORT_REMAP structure 77 DRV_CAMERA_Open function 75 drv_camera_ovm7690.h 101 DRV_CAMERA_OVM7690_CLIENT_OBJ structure 95 DRV_CAMERA_OVM7690_CLIENT_STATUS enumeration 96 DRV_CAMERA_OVM7690_Close function 88 DRV_CAMERA_OVM7690_Deinitialize function 85 DRV_CAMERA_OVM7690_ERROR enumeration 96 DRV_CAMERA_OVM7690_FrameBufferAddressSet function 89 DRV_CAMERA_OVM7690_FrameRectSet function 89 DRV_CAMERA_OVM7690_HsyncEventHandler function 92 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1446 DRV_CAMERA_OVM7690_INDEX_0 macro 99 DRV_CAMERA_OVM7690_INDEX_1 macro 100 DRV_CAMERA_OVM7690_INIT structure 97 DRV_CAMERA_OVM7690_Initialize function 84 DRV_CAMERA_OVM7690_OBJ structure 97 DRV_CAMERA_OVM7690_Open function 87 DRV_CAMERA_OVM7690_RECT structure 98 DRV_CAMERA_OVM7690_REG12_OP_FORMAT enumeration 99 DRV_CAMERA_OVM7690_REG12_SOFT_RESET macro 100 DRV_CAMERA_OVM7690_RegisterSet function 86 DRV_CAMERA_OVM7690_SCCB_READ_ID macro 100 DRV_CAMERA_OVM7690_SCCB_WRITE_ID macro 100 DRV_CAMERA_OVM7690_Start function 91 DRV_CAMERA_OVM7690_Stop function 92 DRV_CAMERA_OVM7690_Tasks function 87 DRV_CAMERA_OVM7690_VsyncEventHandler function 93 DRV_CAMERA_Reinitialize function 76 DRV_CAMERA_Status function 76 DRV_CAMERA_Tasks function 77 DRV_CAN_ChannelMessageReceive function 103 DRV_CAN_ChannelMessageTransmit function 103 DRV_CAN_Close function 104 DRV_CAN_Deinitialize function 104 DRV_CAN_Initialize function 105 DRV_CAN_Open function 105 DRV_CLIENT_STATUS enumeration 15 DRV_CMP_Initialize function 350 DRV_CODEC_WM8904_MODE macro 320 DRV_CONFIG_NOT_SUPPORTED macro 17 drv_ctr.h 376 DRV_CTR_Adjust function 366 DRV_CTR_CALLBACK type 372 DRV_CTR_CLIENT_STATUS enumeration 372 DRV_CTR_ClientStatus function 366 DRV_CTR_Close function 367 DRV_CTR_COUNTER structure 373 DRV_CTR_COUNTER_NUM macro 375 DRV_CTR_Deinitialize function 362 DRV_CTR_Drift function 368 DRV_CTR_EventISR function 368 DRV_CTR_INDEX_0 macro 375 DRV_CTR_INIT structure 373 DRV_CTR_Initialize function 363 DRV_CTR_LATCH structure 374 DRV_CTR_LATCH_FIFO_CNT macro 376 DRV_CTR_LATCH_NUM macro 376 DRV_CTR_Open function 369 DRV_CTR_RegisterCallBack function 370 DRV_CTR_Status function 365 DRV_CTR_TRIGGER structure 374 DRV_CTR_TriggerISR function 371 DRV_DYNAMIC_BUILD macro 528 drv_eeprom.h 406 DRV_EEPROM_AddressGet function 397 DRV_EEPROM_BUFFER_OBJECT_NUMBER macro 383 DRV_EEPROM_BulkErase function 391 DRV_EEPROM_CLIENTS_NUMBER macro 383 DRV_EEPROM_Close function 389 DRV_EEPROM_COMMAND_HANDLE type 403 DRV_EEPROM_COMMAND_HANDLE_INVALID macro 402 DRV_EEPROM_COMMAND_STATUS enumeration 403 DRV_EEPROM_CommandStatus function 397 drv_eeprom_config_template.h 407 DRV_EEPROM_Deinitialize function 387 DRV_EEPROM_Erase function 392 DRV_EEPROM_EVENT enumeration 404 DRV_EEPROM_EVENT_HANDLER type 404 DRV_EEPROM_EventHandlerSet function 398 DRV_EEPROM_GeometryGet function 400 DRV_EEPROM_INDEX_0 macro 402 DRV_EEPROM_INIT structure 405 DRV_EEPROM_Initialize function 386 DRV_EEPROM_INSTANCES_NUMBER macro 383 DRV_EEPROM_IsAttached function 401 DRV_EEPROM_IsWriteProtected function 401 DRV_EEPROM_MEDIA_SIZE macro 384 DRV_EEPROM_Open function 390 DRV_EEPROM_Read function 394 DRV_EEPROM_Status function 388 DRV_EEPROM_SYS_FS_REGISTER macro 384 DRV_EEPROM_Tasks function 388 DRV_EEPROM_Write function 395 drv_enc28j60.h 426 DRV_ENC28J60_CLIENT_INSTANCES macro 410 DRV_ENC28J60_Close function 416 drv_enc28j60_config_template.h 427 DRV_ENC28J60_ConfigGet function 417 DRV_ENC28J60_Configuration structure 424 DRV_ENC28J60_Deinitialize function 413 DRV_ENC28J60_EventAcknowledge function 422 DRV_ENC28J60_EventMaskSet function 423 DRV_ENC28J60_EventPendingGet function 423 DRV_ENC28J60_Initialize function 414 DRV_ENC28J60_INSTANCES_NUMBER macro 410 DRV_ENC28J60_LinkCheck function 417 DRV_ENC28J60_MACObject variable 425 DRV_ENC28J60_MDIX_TYPE enumeration 425 DRV_ENC28J60_Open function 418 DRV_ENC28J60_PacketRx function 421 DRV_ENC28J60_PacketTx function 422 DRV_ENC28J60_ParametersGet function 418 DRV_ENC28J60_PowerMode function 419 DRV_ENC28J60_Process function 414 DRV_ENC28J60_RegisterStatisticsGet function 419 DRV_ENC28J60_Reinitialize function 415 DRV_ENC28J60_RxFilterHashTableEntrySet function 421 DRV_ENC28J60_SetMacCtrlInfo function 415 DRV_ENC28J60_StackInitialize function 415 DRV_ENC28J60_StatisticsGet function 420 DRV_ENC28J60_Status function 420 DRV_ENC28J60_Tasks function 416 drv_encx24j600.h 445 DRV_ENCX24J600_Close function 436 DRV_ENCX24J600_ConfigGet function 436 DRV_ENCX24J600_Configuration structure 444 DRV_ENCX24J600_Deinitialize function 433 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1447 DRV_ENCX24J600_EventAcknowledge function 442 DRV_ENCX24J600_EventMaskSet function 443 DRV_ENCX24J600_EventPendingGet function 443 DRV_ENCX24J600_Initialize function 433 DRV_ENCX24J600_LinkCheck function 437 DRV_ENCX24J600_MDIX_TYPE enumeration 445 DRV_ENCX24J600_Open function 437 DRV_ENCX24J600_PacketRx function 440 DRV_ENCX24J600_PacketTx function 442 DRV_ENCX24J600_ParametersGet function 438 DRV_ENCX24J600_PowerMode function 438 DRV_ENCX24J600_Process function 435 DRV_ENCX24J600_RegisterStatisticsGet function 439 DRV_ENCX24J600_Reinitialize function 434 DRV_ENCX24J600_RxFilterHashTableEntrySet function 441 DRV_ENCX24J600_SetMacCtrlInfo function 435 DRV_ENCX24J600_StackInitialize function 435 DRV_ENCX24J600_StatisticsGet function 439 DRV_ENCX24J600_Status function 440 DRV_ENCX24J600_Tasks function 434 drv_ethmac.h 467 DRV_ETHMAC_CLIENTS_NUMBER macro 450 drv_ethmac_config.h 468 DRV_ETHMAC_INDEX macro 450 DRV_ETHMAC_INDEX_0 macro 466 DRV_ETHMAC_INDEX_1 macro 466 DRV_ETHMAC_INDEX_COUNT macro 467 DRV_ETHMAC_INSTANCES_NUMBER macro 450 DRV_ETHMAC_INTERRUPT_MODE macro 451 DRV_ETHMAC_INTERRUPT_SOURCE macro 451 DRV_ETHMAC_PERIPHERAL_ID macro 451 DRV_ETHMAC_PIC32MACClose function 454 DRV_ETHMAC_PIC32MACConfigGet function 459 DRV_ETHMAC_PIC32MACDeinitialize function 454 DRV_ETHMAC_PIC32MACEventAcknowledge function 463 DRV_ETHMAC_PIC32MACEventMaskSet function 464 DRV_ETHMAC_PIC32MACEventPendingGet function 464 DRV_ETHMAC_PIC32MACInitialize function 455 DRV_ETHMAC_PIC32MACLinkCheck function 455 DRV_ETHMAC_PIC32MACOpen function 456 DRV_ETHMAC_PIC32MACPacketRx function 461 DRV_ETHMAC_PIC32MACPacketTx function 462 DRV_ETHMAC_PIC32MACParametersGet function 456 DRV_ETHMAC_PIC32MACPowerMode function 457 DRV_ETHMAC_PIC32MACProcess function 457 DRV_ETHMAC_PIC32MACRegisterStatisticsGet function 460 DRV_ETHMAC_PIC32MACReinitialize function 460 DRV_ETHMAC_PIC32MACRxFilterHashTableEntrySet function 461 DRV_ETHMAC_PIC32MACStatisticsGet function 458 DRV_ETHMAC_PIC32MACStatus function 458 DRV_ETHMAC_PIC32MACTasks function 466 DRV_ETHMAC_POWER_STATE macro 452 DRV_ETHMAC_Tasks_ISR function 465 drv_ethphy.h 505 DRV_ETHPHY_CLIENT_STATUS enumeration 495 DRV_ETHPHY_ClientOperationAbort function 483 DRV_ETHPHY_ClientOperationResult function 484 DRV_ETHPHY_CLIENTS_NUMBER macro 471 DRV_ETHPHY_ClientStatus function 481 DRV_ETHPHY_Close function 482 drv_ethphy_config.h 507 DRV_ETHPHY_CONFIG_FLAGS enumeration 500 DRV_ETHPHY_Deinitialize function 477 DRV_ETHPHY_HWConfigFlagsGet function 480 DRV_ETHPHY_INDEX macro 472 DRV_ETHPHY_INDEX_0 macro 499 DRV_ETHPHY_INDEX_1 macro 499 DRV_ETHPHY_INDEX_COUNT macro 499 DRV_ETHPHY_INIT structure 496 DRV_ETHPHY_Initialize function 476 DRV_ETHPHY_INSTANCES_NUMBER macro 472 DRV_ETHPHY_INTERFACE_INDEX enumeration 504 DRV_ETHPHY_INTERFACE_TYPE enumeration 505 DRV_ETHPHY_LINK_STATUS enumeration 500 DRV_ETHPHY_LinkStatusGet function 492 DRV_ETHPHY_NEG_DONE_TMO macro 472 DRV_ETHPHY_NEG_INIT_TMO macro 473 DRV_ETHPHY_NEGOTIATION_RESULT structure 496 DRV_ETHPHY_NegotiationIsComplete function 493 DRV_ETHPHY_NegotiationResultGet function 493 DRV_ETHPHY_OBJECT structure 501 DRV_ETHPHY_OBJECT_BASE structure 502 DRV_ETHPHY_OBJECT_BASE_TYPE structure 502 DRV_ETHPHY_Open function 482 DRV_ETHPHY_PERIPHERAL_ID macro 472 DRV_ETHPHY_PhyAddressGet function 494 DRV_ETHPHY_Reinitialize function 478 DRV_ETHPHY_Reset function 483 DRV_ETHPHY_RESET_CLR_TMO macro 473 DRV_ETHPHY_RESET_FUNCTION type 503 DRV_ETHPHY_RestartNegotiation function 495 DRV_ETHPHY_RESULT enumeration 503 DRV_ETHPHY_Setup function 480 DRV_ETHPHY_SETUP structure 497 DRV_ETHPHY_SMIClockSet function 486 DRV_ETHPHY_SMIRead function 487 DRV_ETHPHY_SMIScanDataGet function 487 DRV_ETHPHY_SMIScanStart function 486 DRV_ETHPHY_SMIScanStatusGet function 484 DRV_ETHPHY_SMIScanStop function 485 DRV_ETHPHY_SMIStatus function 488 DRV_ETHPHY_SMIWrite function 488 DRV_ETHPHY_Status function 478 DRV_ETHPHY_Tasks function 479 DRV_ETHPHY_USE_DRV_MIIM macro 504 DRV_ETHPHY_VENDOR_MDIX_CONFIGURE type 497 DRV_ETHPHY_VENDOR_MII_CONFIGURE type 498 DRV_ETHPHY_VENDOR_SMI_CLOCK_GET type 498 DRV_ETHPHY_VENDOR_WOL_CONFIGURE type 501 DRV_ETHPHY_VendorDataGet function 489 DRV_ETHPHY_VendorDataSet function 490 DRV_ETHPHY_VendorSMIReadResultGet function 490 DRV_ETHPHY_VendorSMIReadStart function 491 DRV_ETHPHY_VendorSMIWriteStart function 491 drv_flash.h 514 DRV_FLASH_ErasePage function 509 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1448 DRV_FLASH_GetPageSize function 509 DRV_FLASH_GetRowSize function 510 DRV_FLASH_INDEX_0 macro 513 DRV_FLASH_Initialize function 510 DRV_FLASH_IsBusy function 511 DRV_FLASH_Open function 511 DRV_FLASH_PAGE_SIZE macro 514 DRV_FLASH_ROW_SIZE macro 514 DRV_FLASH_WriteQuadWord function 511 DRV_FLASH_WriteRow function 512 DRV_FLASH_WriteWord function 513 drv_gmac.h 520 DRV_HANDLE type 15 DRV_HANDLE_INVALID macro 17 drv_i2c.h 550 drv_i2c_bb.h 551 DRV_I2C_BB_H macro 550 DRV_I2C_BUFFER_QUEUE_SUPPORT macro 548 DRV_I2C_BufferEventHandlerSet function 539 DRV_I2C_BytesTransferred function 540 DRV_I2C_Close function 537 DRV_I2C_CONFIG_BUILD_TYPE macro 529 DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_BASIC macro 529 DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_BLOCKING macro 529 DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_EXCLUSIVE macro 530 DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_MASTER macro 530 DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_NON_BLOCKING macro 530 DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_READ macro 531 DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_SLAVE macro 531 DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_WRITE macro 531 DRV_I2C_CONFIG_SUPPORT_OPERATION_MODE_WRITE_READ macro 532 drv_i2c_config_template.h 551 DRV_I2C_Deinitialize function 535 DRV_I2C_FORCED_WRITE macro 532 DRV_I2C_INDEX macro 313 DRV_I2C_Initialize function 535 DRV_I2C_INSTANCES_NUMBER macro 549 DRV_I2C_INTERRUPT_MODE macro 549 DRV_I2C_Open function 538 DRV_I2C_QUEUE_DEPTH_COMBINED macro 549 DRV_I2C_QueueFlush function 546 DRV_I2C_Receive function 541 DRV_I2C_SlaveCallbackSet function 547 DRV_I2C_Status function 546 DRV_I2C_Tasks function 537 DRV_I2C_TransferStatusGet function 545 DRV_I2C_Transmit function 542 DRV_I2C_TransmitForced function 544 DRV_I2C_TransmitThenReceive function 543 drv_i2s.h 605 DRV_I2S_AUDIO_PROTOCOL_MODE enumeration 596 DRV_I2S_BaudSet function 590 DRV_I2S_BUFFER_EVENT enumeration 596 DRV_I2S_BUFFER_EVENT_HANDLER type 597 DRV_I2S_BUFFER_HANDLE type 598 DRV_I2S_BUFFER_HANDLE_INVALID macro 601 DRV_I2S_BufferAddRead function 578 DRV_I2S_BufferAddWrite function 579 DRV_I2S_BufferAddWriteRead function 581 DRV_I2S_BufferCombinedQueueSizeGet function 584 DRV_I2S_BufferEventHandlerSet function 583 DRV_I2S_BufferProcessedSizeGet function 588 DRV_I2S_BufferQueueFlush function 585 DRV_I2S_CLIENTS_NUMBER macro 569 DRV_I2S_CLOCK_MODE enumeration 598 DRV_I2S_Close function 576 drv_i2s_config_template.h 607 DRV_I2S_COUNT macro 601 DRV_I2S_DATA16 structure 599 DRV_I2S_DATA24 structure 599 DRV_I2S_DATA32 structure 599 DRV_I2S_Deinitialize function 572 DRV_I2S_ERROR enumeration 600 DRV_I2S_ErrorGet function 591 DRV_I2S_INDEX macro 566 DRV_I2S_INDEX_0 macro 602 DRV_I2S_INDEX_1 macro 602 DRV_I2S_INDEX_2 macro 603 DRV_I2S_INDEX_3 macro 603 DRV_I2S_INDEX_4 macro 603 DRV_I2S_INDEX_5 macro 603 DRV_I2S_Initialize function 573 DRV_I2S_INSTANCES_NUMBER macro 566 DRV_I2S_INTERFACE structure 603 DRV_I2S_INTERRUPT_MODE macro 566 DRV_I2S_INTERRUPT_SOURCE_ERROR macro 566 DRV_I2S_INTERRUPT_SOURCE_RECEIVE macro 567 DRV_I2S_INTERRUPT_SOURCE_TRANSMIT macro 567 DRV_I2S_MODE enumeration 600 DRV_I2S_Open function 577 DRV_I2S_PERIPHERAL_ID macro 567 DRV_I2S_QUEUE_DEPTH_COMBINED macro 569 DRV_I2S_Read function 586 DRV_I2S_READ_ERROR macro 601 DRV_I2S_RECEIVE_DMA_CHAINING_CHANNEL macro 569 DRV_I2S_RECEIVE_DMA_CHANNEL macro 568 DRV_I2S_ReceiveErrorIgnore function 593 DRV_I2S_Status function 574 DRV_I2S_STOP_IN_IDLE macro 568 DRV_I2S_Tasks function 575 DRV_I2S_TasksError function 575 DRV_I2S_TRANSMIT_DMA_CHANNEL macro 568 DRV_I2S_TransmitErrorIgnore function 594 DRV_I2S_Write function 587 DRV_I2S_WRITE_ERROR macro 602 DRV_IC_BufferIsEmpty function 608 DRV_IC_Capture16BitDataRead function 609 DRV_IC_Capture32BitDataRead function 609 DRV_IC_Initialize function 608 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1449 DRV_IC_Start function 610 DRV_IC_Stop function 610 drv_input_mxt336t.h 617 DRV_IO_BUFFER_TYPES enumeration 16 DRV_IO_INTENT enumeration 16 DRV_IO_ISBLOCKING macro 18 DRV_IO_ISEXCLUSIVE macro 18 DRV_IO_ISNONBLOCKING macro 18 drv_ipf.h 880 DRV_IPF_BLOCK_COMMAND_HANDLE type 873 DRV_IPF_BLOCK_COMMAND_HANDLE_INVALID macro 878 DRV_IPF_BLOCK_EVENT enumeration 874 DRV_IPF_BLOCK_OPERATION enumeration 874 DRV_IPF_BlockErase function 859 DRV_IPF_BlockEventHandlerSet function 861 DRV_IPF_BlockRead function 862 DRV_IPF_BlockWrite function 864 DRV_IPF_CLIENT_STATUS enumeration 875 DRV_IPF_CLIENTS_NUMBER macro 879 DRV_IPF_ClientStatus function 857 DRV_IPF_Close function 857 DRV_IPF_COMMAND_STATUS enumeration 875 drv_ipf_config_template.h 881 DRV_IPF_Deinitialize function 853 DRV_IPF_EVENT_HANDLER type 876 DRV_IPF_GeometryGet function 866 DRV_IPF_HoldAssert function 866 DRV_IPF_HoldDeAssert function 867 DRV_IPF_INDEX_0 macro 878 DRV_IPF_INIT structure 877 DRV_IPF_Initialize function 854 DRV_IPF_INSTANCES_NUMBER macro 879 DRV_IPF_MediaIsAttached function 867 DRV_IPF_MODE macro 879 DRV_IPF_Open function 858 DRV_IPF_PROT_MODE enumeration 877 DRV_IPF_ProtectMemoryVolatile function 868 DRV_IPF_ReadBlockProtectionStatus function 869 DRV_IPF_Status function 855 DRV_IPF_Tasks function 856 DRV_IPF_UnProtectMemoryVolatile function 871 DRV_IPF_WPAssert function 872 DRV_IPF_WPDeAssert function 873 drv_mcpwm.h 640 DRV_MCPWM_Disable function 638 DRV_MCPWM_Enable function 639 DRV_MCPWM_Initialize function 639 drv_miim.h 636 DRV_MIIM_CALLBACK_HANDLE type 633 DRV_MIIM_CLIENT_OP_PROTECTION macro 620 DRV_MIIM_CLIENT_STATUS enumeration 633 DRV_MIIM_ClientStatus function 623 DRV_MIIM_Close function 623 DRV_MIIM_COMMANDS macro 620 drv_miim_config.h 637 DRV_MIIM_Deinitialize function 624 DRV_MIIM_DeregisterCallback function 624 DRV_MIIM_INDEX_0 macro 619 DRV_MIIM_INDEX_COUNT macro 619 DRV_MIIM_INIT structure 632 DRV_MIIM_Initialize function 625 DRV_MIIM_INSTANCE_CLIENTS macro 620 DRV_MIIM_INSTANCE_OPERATIONS macro 621 DRV_MIIM_INSTANCES_NUMBER macro 621 DRV_MIIM_OBJECT_BASE structure 632 DRV_MIIM_OBJECT_BASE_Default variable 636 DRV_MIIM_Open function 625 DRV_MIIM_OPERATION_CALLBACK type 634 DRV_MIIM_OPERATION_FLAGS enumeration 634 DRV_MIIM_OPERATION_HANDLE type 634 DRV_MIIM_OperationAbort function 626 DRV_MIIM_OperationResult function 626 DRV_MIIM_Read function 627 DRV_MIIM_RegisterCallback function 627 DRV_MIIM_Reinitialize function 628 DRV_MIIM_Scan function 628 DRV_MIIM_Setup function 629 DRV_MIIM_SETUP structure 635 DRV_MIIM_SETUP_FLAGS enumeration 635 DRV_MIIM_Status function 630 DRV_MIIM_Tasks function 631 DRV_MIIM_Write function 631 DRV_MODE enumeration 375 drv_mtch6301.h 1076 DRV_MTCH6301_CALIBRATION_DELAY macro 1059 DRV_MTCH6301_CALIBRATION_INSET macro 1060 DRV_MTCH6301_CLIENTS_NUMBER macro 1060 drv_mtch6301_config_template.h 1077 DRV_MTCH6301_INDEX macro 1060 DRV_MTCH6301_INSTANCES_NUMBER macro 1061 DRV_MTCH6301_INTERRUPT_MODE macro 1061 DRV_MTCH6301_SAMPLE_POINTS macro 1061 DRV_MTCH6301_TOUCH_DIAMETER macro 1061 drv_mtch6303.h 1106 DRV_MTCH6303_AddRegisterRead function 1085 DRV_MTCH6303_AddRegisterWrite function 1086 DRV_MTCH6303_BUFFER_EVENT enumeration 1099 DRV_MTCH6303_BUFFER_EVENT_HANDLER type 1099 DRV_MTCH6303_BUFFER_HANDLE type 1100 DRV_MTCH6303_BUFFER_HANDLE_INVALID macro 1098 DRV_MTCH6303_BufferEventHandlerSet function 1096 DRV_MTCH6303_CLIENT_STATUS enumeration 1100 DRV_MTCH6303_Close function 1083 DRV_MTCH6303_Deinitialize function 1081 DRV_MTCH6303_ERROR enumeration 1101 DRV_MTCH6303_ErrorGet function 1084 DRV_MTCH6303_Initialize function 1082 DRV_MTCH6303_Open function 1084 DRV_MTCH6303_Status function 1082 DRV_MTCH6303_Tasks function 1083 DRV_MTCH6303_TOUCH_AddMessageCommandWrite function 1088 DRV_MTCH6303_TOUCH_AddMessageReportRead function 1089 DRV_MTCH6303_TOUCH_AddTouchInputRead function 1091 DRV_MTCH6303_TOUCH_BUFFER_EVENT enumeration 1101 DRV_MTCH6303_TOUCH_BUFFER_EVENT_HANDLER type 1101 DRV_MTCH6303_TOUCH_BUFFER_HANDLE type 1102 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1450 DRV_MTCH6303_TOUCH_BUFFER_HANDLE_INVALID macro 1098 DRV_MTCH6303_TOUCH_BufferEventHandlerSet function 1092 DRV_MTCH6303_TOUCH_DATA structure 1102 DRV_MTCH6303_TOUCH_INPUT structure 1103 DRV_MTCH6303_TOUCH_MESSAGE structure 1103 DRV_MTCH6303_TOUCH_MESSAGE_HEADER structure 1104 DRV_MTCH6303_TOUCH_NIBBLE_0 structure 1104 DRV_MTCH6303_TOUCH_NUM_INPUTS macro 1098 DRV_MTCH6303_TOUCH_STATUS structure 1105 DRV_MTCH6303_TOUCH_Tasks function 1094 DRV_MTCH6303_TouchInputMap function 1094 DRV_MTCH6303_TouchInputRead function 1095 drv_mxt.h 1145 DRV_MXT_CLIENT_OBJECT structure 1132 DRV_MXT_Close function 1124 DRV_MXT_Deinitialize function 1125 DRV_MXT_HANDLE type 1132 DRV_MXT_HANDLE_INVALID macro 1139 DRV_MXT_I2C_MASTER_READ_ID macro 1139 DRV_MXT_I2C_MASTER_WRITE_ID macro 1140 DRV_MXT_I2C_READ_FRAME_SIZE macro 1140 DRV_MXT_INDEX_0 macro 1140 DRV_MXT_INDEX_1 macro 1140 DRV_MXT_INDEX_COUNT macro 1141 DRV_MXT_INIT structure 1132 DRV_MXT_Initialize function 1127 DRV_MXT_MaxtouchEventCallback function 1125 DRV_MXT_MODULE_ID enumeration 1133 DRV_MXT_OBJECT structure 1133 DRV_MXT_Open function 1126 DRV_MXT_ReadRequest function 1128 DRV_MXT_Status function 1130 DRV_MXT_TASK_QUEUE structure 1134 DRV_MXT_TASK_STATE enumeration 1135 DRV_MXT_Tasks function 1131 DRV_MXT_TouchDataRead function 1127 DRV_MXT_TouchGetX function 1129 DRV_MXT_TouchGetY function 1129 DRV_MXT_TouchStatus function 1131 drv_mxt336t.h 1146 DRV_MXT336T_CALIBRATION_DELAY macro 1111 DRV_MXT336T_CALIBRATION_INSET macro 1112 DRV_MXT336T_CLIENT_CALLBACK type 1135 DRV_MXT336T_CLIENTS_NUMBER macro 1112 DRV_MXT336T_Close function 1117 DRV_MXT336T_CloseObject function 1119 DRV_MXT336T_Deinitialize function 1121 DRV_MXT336T_DEVICE_ClientObjectEventHandlerSet function 1120 DRV_MXT336T_HANDLE type 1136 DRV_MXT336T_HANDLE_INVALID macro 1141 DRV_MXT336T_I2C_FRAME_SIZE macro 1141 DRV_MXT336T_I2C_MASTER_READ_ID macro 1142 DRV_MXT336T_I2C_MASTER_WRITE_ID macro 1142 DRV_MXT336T_I2C_READ_ID_FRAME_SIZE macro 1142 DRV_MXT336T_INDEX macro 1112 DRV_MXT336T_INDEX_0 macro 1142 DRV_MXT336T_INDEX_1 macro 1143 DRV_MXT336T_INDEX_COUNT macro 1143 DRV_MXT336T_INIT type 1136 DRV_MXT336T_Initialize function 1122 DRV_MXT336T_INSTANCES_NUMBER macro 1113 DRV_MXT336T_INTERRUPT_MODE macro 1113 DRV_MXT336T_OBJECT_CLIENT_EVENT_DATA structure 1136 DRV_MXT336T_OBJECT_TYPE enumeration 1137 DRV_MXT336T_Open function 1118 DRV_MXT336T_OpenObject function 1120 DRV_MXT336T_ReadRequest function 1117 DRV_MXT336T_SAMPLE_POINTS macro 1113 DRV_MXT336T_Status function 1123 DRV_MXT336T_T100_XRANGE macro 1144 DRV_MXT336T_T100_YRANGE macro 1144 DRV_MXT336T_Tasks function 1123 DRV_MXT336T_TOUCH_DIAMETER macro 1113 drv_nvm.h 676 DRV_NVM_AddressGet function 669 DRV_NVM_BUFFER_OBJECT_NUMBER macro 650 DRV_NVM_CLIENTS_NUMBER macro 651 DRV_NVM_Close function 659 DRV_NVM_COMMAND_HANDLE type 675 DRV_NVM_COMMAND_HANDLE_INVALID macro 676 DRV_NVM_COMMAND_STATUS enumeration 675 DRV_NVM_CommandStatus function 669 drv_nvm_config_template.h 678 DRV_NVM_Deinitialize function 657 DRV_NVM_DISABLE_ERROR_CHECK macro 652 DRV_NVM_Erase function 663 DRV_NVM_ERASE_WRITE_ENABLE macro 652 DRV_NVM_EraseWrite function 665 DRV_NVM_EVENT enumeration 673 DRV_NVM_EVENT_HANDLER type 674 DRV_NVM_EventHandlerSet function 666 DRV_NVM_GeometryGet function 670 DRV_NVM_INDEX_0 macro 672 DRV_NVM_INDEX_1 macro 673 DRV_NVM_INIT structure 673 DRV_NVM_Initialize function 655 DRV_NVM_INSTANCES_NUMBER macro 651 DRV_NVM_INTERRUPT_MODE macro 651 DRV_NVM_IsAttached function 671 DRV_NVM_IsWriteProtected function 672 DRV_NVM_MEDIA_SIZE macro 653 DRV_NVM_MEDIA_START_ADDRESS macro 653 DRV_NVM_Open function 658 DRV_NVM_PAGE_SIZE macro 652 DRV_NVM_Read function 660 DRV_NVM_ROW_SIZE macro 651 DRV_NVM_Status function 658 DRV_NVM_SYS_FS_REGISTER macro 653 DRV_NVM_Tasks function 668 DRV_NVM_Write function 661 DRV_OC_Disable function 679 DRV_OC_Enable function 679 DRV_OC_FaultHasOccurred function 680 DRV_OC_Initialize function 680 DRV_OC_Start function 681 DRV_OC_Stop function 681 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1451 drv_ovm7690_config_template.h 102 DRV_OVM7690_INTERRUPT_MODE macro 82 drv_pmp.h 708 DRV_PMP_CHIPX_STROBE_MODE enumeration 702 DRV_PMP_CLIENT_STATUS enumeration 702 DRV_PMP_CLIENTS_NUMBER macro 689 DRV_PMP_ClientStatus function 696 DRV_PMP_Close function 697 drv_pmp_config.h 710 DRV_PMP_Deinitialize function 691 DRV_PMP_ENDIAN_MODE enumeration 703 DRV_PMP_INDEX enumeration 703 DRV_PMP_INDEX_COUNT macro 702 DRV_PMP_INIT structure 703 DRV_PMP_Initialize function 692 DRV_PMP_INSTANCES_NUMBER macro 689 DRV_PMP_MODE_CONFIG structure 704 DRV_PMP_ModeConfig function 698 DRV_PMP_Open function 699 DRV_PMP_POLARITY_OBJECT structure 705 DRV_PMP_PORT_CONTROL enumeration 705 DRV_PMP_PORTS structure 705 DRV_PMP_QUEUE_ELEMENT_OBJ structure 706 DRV_PMP_QUEUE_SIZE macro 689 DRV_PMP_Read function 699 DRV_PMP_Reinitialize function 693 DRV_PMP_Status function 694 DRV_PMP_Tasks function 695 DRV_PMP_TimingSet function 696 DRV_PMP_TRANSFER_STATUS enumeration 706 DRV_PMP_TRANSFER_TYPE enumeration 707 DRV_PMP_TransferStatus function 701 DRV_PMP_WAIT_STATES structure 707 DRV_PMP_Write function 700 DRV_RTCC_AlarmDateGet function 711 DRV_RTCC_AlarmTimeGet function 711 DRV_RTCC_ClockOutput function 712 DRV_RTCC_DateGet function 712 DRV_RTCC_Initialize function 713 DRV_RTCC_Start function 713 DRV_RTCC_Stop function 713 DRV_RTCC_TimeGet function 714 drv_sdcard.h 741 DRV_SDCARD_CLIENTS_NUMBER macro 719 DRV_SDCARD_Close function 727 DRV_SDCARD_COMMAND_HANDLE type 739 DRV_SDCARD_COMMAND_HANDLE_INVALID macro 739 DRV_SDCARD_COMMAND_STATUS enumeration 739 DRV_SDCARD_CommandStatus function 734 drv_sdcard_config_template.h 743 DRV_SDCARD_Deinitialize function 724 DRV_SDCARD_ENABLE_WRITE_PROTECT_CHECK macro 721 DRV_SDCARD_EVENT enumeration 740 DRV_SDCARD_EVENT_HANDLER type 740 DRV_SDCARD_EventHandlerSet function 731 DRV_SDCARD_GeometryGet function 735 DRV_SDCARD_INDEX_0 macro 736 DRV_SDCARD_INDEX_1 macro 738 DRV_SDCARD_INDEX_2 macro 738 DRV_SDCARD_INDEX_3 macro 738 DRV_SDCARD_INDEX_COUNT macro 736 DRV_SDCARD_INDEX_MAX macro 720 DRV_SDCARD_INIT structure 737 DRV_SDCARD_Initialize function 723 DRV_SDCARD_INSTANCES_NUMBER macro 720 DRV_SDCARD_IsAttached function 733 DRV_SDCARD_IsWriteProtected function 734 DRV_SDCARD_Open function 728 DRV_SDCARD_POWER_STATE macro 720 DRV_SDCARD_Read function 729 DRV_SDCARD_Reinitialize function 724 DRV_SDCARD_Status function 725 DRV_SDCARD_SYS_FS_REGISTER macro 721 DRV_SDCARD_Tasks function 726 DRV_SDCARD_Write function 730 drv_spi.h 769 DRV_SPI_16BIT macro 749 DRV_SPI_32BIT macro 749 DRV_SPI_8BIT macro 750 DRV_SPI_BufferAddRead function 762 DRV_SPI_BufferAddRead2 function 765 DRV_SPI_BufferAddWrite function 763 DRV_SPI_BufferAddWrite2 function 766 DRV_SPI_BufferAddWriteRead function 764 DRV_SPI_BufferAddWriteRead2 function 767 DRV_SPI_BufferStatus function 761 DRV_SPI_ClientConfigure function 760 DRV_SPI_CLIENTS_NUMBER macro 753 DRV_SPI_Close function 759 drv_spi_config_template.h 770 DRV_SPI_Deinitialize function 756 DRV_SPI_DMA macro 750 DRV_SPI_DMA_DUMMY_BUFFER_SIZE macro 750 DRV_SPI_DMA_TXFER_SIZE macro 751 DRV_SPI_EBM macro 751 DRV_SPI_ELEMENTS_PER_QUEUE macro 751 DRV_SPI_Initialize function 755 DRV_SPI_INSTANCES_NUMBER macro 753 DRV_SPI_ISR macro 752 DRV_SPI_MASTER macro 752 DRV_SPI_Open function 759 DRV_SPI_POLLED macro 752 DRV_SPI_RM macro 752 DRV_SPI_SLAVE macro 753 DRV_SPI_Status function 757 DRV_SPI_Tasks function 758 DRV_SPIn_ReceiverBufferIsFull function 768 DRV_SPIn_TransmitterBufferIsFull function 768 drv_sqi.h 915 DRV_SQI_BUFFER_OBJECT_NUMBER macro 887 DRV_SQI_CLIENTS_NUMBER macro 887 DRV_SQI_Close function 895 DRV_SQI_COMMAND_HANDLE type 900 DRV_SQI_COMMAND_HANDLE_INVALID macro 904 DRV_SQI_COMMAND_STATUS enumeration 901 DRV_SQI_CommandStatus function 895 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1452 drv_sqi_config_template.h 917 DRV_SQI_Deinitialize function 892 DRV_SQI_DMA_BUFFER_DESCRIPTORS_NUMBER macro 888 DRV_SQI_EVENT enumeration 901 DRV_SQI_EVENT_HANDLER type 902 DRV_SQI_EventHandlerSet function 896 DRV_SQI_FLAG_32_BIT_ADDR_ENABLE macro 905 DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_MASK macro 905 DRV_SQI_FLAG_32_BIT_ADDR_ENABLE_POS macro 905 DRV_SQI_FLAG_ADDR_ENABLE macro 905 DRV_SQI_FLAG_ADDR_ENABLE_MASK macro 906 DRV_SQI_FLAG_ADDR_ENABLE_POS macro 906 DRV_SQI_FLAG_CRM_ENABLE macro 906 DRV_SQI_FLAG_CRM_ENABLE_MASK macro 906 DRV_SQI_FLAG_CRM_ENABLE_POS macro 906 DRV_SQI_FLAG_DATA_DIRECTION_MASK macro 907 DRV_SQI_FLAG_DATA_DIRECTION_POS macro 907 DRV_SQI_FLAG_DATA_DIRECTION_READ macro 907 DRV_SQI_FLAG_DATA_DIRECTION_WRITE macro 907 DRV_SQI_FLAG_DATA_ENABLE macro 907 DRV_SQI_FLAG_DATA_ENABLE_MASK macro 908 DRV_SQI_FLAG_DATA_ENABLE_POS macro 908 DRV_SQI_FLAG_DATA_TARGET_MASK macro 908 DRV_SQI_FLAG_DATA_TARGET_MEMORY macro 908 DRV_SQI_FLAG_DATA_TARGET_POS macro 908 DRV_SQI_FLAG_DATA_TARGET_REGISTER macro 909 DRV_SQI_FLAG_DDR_ENABLE macro 909 DRV_SQI_FLAG_DDR_ENABLE_MASK macro 909 DRV_SQI_FLAG_DDR_ENABLE_POS macro 909 DRV_SQI_FLAG_INSTR_ENABLE macro 909 DRV_SQI_FLAG_INSTR_ENABLE_MASK macro 910 DRV_SQI_FLAG_INSTR_ENABLE_POS macro 910 DRV_SQI_FLAG_OPT_ENABLE macro 910 DRV_SQI_FLAG_OPT_ENABLE_MASK macro 910 DRV_SQI_FLAG_OPT_ENABLE_POS macro 910 DRV_SQI_FLAG_OPT_LENGTH macro 911 DRV_SQI_FLAG_OPT_LENGTH_1BIT macro 911 DRV_SQI_FLAG_OPT_LENGTH_2BIT macro 911 DRV_SQI_FLAG_OPT_LENGTH_4BIT macro 911 DRV_SQI_FLAG_OPT_LENGTH_8BIT macro 911 DRV_SQI_FLAG_OPT_LENGTH_MASK macro 912 DRV_SQI_FLAG_OPT_LENGTH_POS macro 912 DRV_SQI_FLAG_SQI_CS_NUMBER macro 912 DRV_SQI_FLAG_SQI_CS_NUMBER_0 macro 912 DRV_SQI_FLAG_SQI_CS_NUMBER_1 macro 912 DRV_SQI_FLAG_SQI_CS_NUMBER_2 macro 913 DRV_SQI_FLAG_SQI_CS_NUMBER_3 macro 913 DRV_SQI_FLAG_SQI_CS_NUMBER_MASK macro 913 DRV_SQI_FLAG_SQI_CS_NUMBER_POS macro 913 DRV_SQI_INDEX_0 macro 904 DRV_SQI_Initialize function 891 DRV_SQI_INSTANCES_NUMBER macro 888 DRV_SQI_INTERRUPT_MODE macro 888 DRV_SQI_LANE_CONFIG enumeration 913 DRV_SQI_Open function 894 DRV_SQI_SPI_OPERATION_MODE enumeration 903 DRV_SQI_Status function 892 DRV_SQI_Tasks function 893 DRV_SQI_TRANSFER_FLAGS enumeration 903 DRV_SQI_TransferData function 898 DRV_SQI_TransferElement structure 904 DRV_SQI_TransferFrame structure 914 DRV_SQI_TransferFrames function 899 drv_sram.h 969 DRV_SRAM_AddressGet function 952 DRV_SRAM_Close function 953 DRV_SRAM_COMMAND_HANDLE type 965 DRV_SRAM_COMMAND_HANDLE_INVALID macro 968 DRV_SRAM_COMMAND_STATUS enumeration 965 DRV_SRAM_CommandStatus function 954 DRV_SRAM_Deinitialize function 954 DRV_SRAM_EVENT enumeration 966 DRV_SRAM_EVENT_HANDLER type 966 DRV_SRAM_EventHandlerSet function 955 DRV_SRAM_GeometryGet function 957 DRV_SRAM_INDEX_0 macro 968 DRV_SRAM_INDEX_1 macro 968 DRV_SRAM_INIT structure 967 DRV_SRAM_Initialize function 957 DRV_SRAM_IsAttached function 959 DRV_SRAM_IsWriteProtected function 959 DRV_SRAM_Open function 960 DRV_SRAM_Read function 961 DRV_SRAM_Status function 962 DRV_SRAM_Write function 963 drv_sst25vf016b.h 842 DRV_SST25VF016B_BLOCK_COMMAND_HANDLE type 798 DRV_SST25VF016B_BLOCK_COMMAND_HANDLE_INVALID macro 801 DRV_SST25VF016B_BLOCK_EVENT enumeration 798 DRV_SST25VF016B_BlockErase function 790 DRV_SST25VF016B_BlockEventHandlerSet function 791 DRV_SST25VF016B_BlockRead function 793 DRV_SST25VF016B_BlockWrite function 794 DRV_SST25VF016B_CLIENT_STATUS enumeration 798 DRV_SST25VF016B_CLIENTS_NUMBER macro 776 DRV_SST25VF016B_ClientStatus function 789 DRV_SST25VF016B_Close function 787 drv_sst25vf016b_config_template.h 843 DRV_SST25VF016B_Deinitialize function 785 DRV_SST25VF016B_EVENT_HANDLER type 799 DRV_SST25VF016B_GeometryGet function 796 DRV_SST25VF016B_HARDWARE_HOLD_ENABLE macro 777 DRV_SST25VF016B_HARDWARE_WRITE_PROTECTION_ENABLE macro 777 DRV_SST25VF016B_INDEX_0 macro 801 DRV_SST25VF016B_INDEX_1 macro 801 DRV_SST25VF016B_INIT structure 800 DRV_SST25VF016B_Initialize function 784 DRV_SST25VF016B_INSTANCES_NUMBER macro 777 DRV_SST25VF016B_MediaIsAttached function 797 DRV_SST25VF016B_MODE macro 777 DRV_SST25VF016B_Open function 788 DRV_SST25VF016B_QUEUE_DEPTH_COMBINED macro 778 DRV_SST25VF016B_Status function 786 DRV_SST25VF016B_Tasks function 787 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1453 drv_sst25vf020b.h 844 DRV_SST25VF020B_BLOCK_COMMAND_HANDLE type 818 DRV_SST25VF020B_BLOCK_COMMAND_HANDLE_INVALID macro 821 DRV_SST25VF020B_BLOCK_EVENT enumeration 818 DRV_SST25VF020B_BlockErase function 809 DRV_SST25VF020B_BlockEraseWrite function 816 DRV_SST25VF020B_BlockEventHandlerSet function 811 DRV_SST25VF020B_BlockRead function 812 DRV_SST25VF020B_BlockWrite function 814 DRV_SST25VF020B_CLIENT_STATUS enumeration 819 DRV_SST25VF020B_CLIENTS_NUMBER macro 778 DRV_SST25VF020B_ClientStatus function 806 DRV_SST25VF020B_Close function 808 DRV_SST25VF020B_COMMAND_STATUS enumeration 821 DRV_SST25VF020B_CommandStatus function 807 drv_sst25vf020b_config_template.h 845 DRV_SST25VF020B_Deinitialize function 804 DRV_SST25VF020B_EVENT_HANDLER type 819 DRV_SST25VF020B_GeometryGet function 817 DRV_SST25VF020B_HARDWARE_HOLD_ENABLE macro 779 DRV_SST25VF020B_HARDWARE_WRITE_PROTECTION_ENABLE macro 779 DRV_SST25VF020B_INDEX_0 macro 822 DRV_SST25VF020B_INDEX_1 macro 822 DRV_SST25VF020B_INIT structure 820 DRV_SST25VF020B_Initialize function 803 DRV_SST25VF020B_INSTANCES_NUMBER macro 779 DRV_SST25VF020B_MediaIsAttached function 817 DRV_SST25VF020B_MODE macro 779 DRV_SST25VF020B_Open function 808 DRV_SST25VF020B_QUEUE_DEPTH_COMBINED macro 780 DRV_SST25VF020B_Status function 805 DRV_SST25VF020B_Tasks function 805 drv_sst25vf064c.h 845 DRV_SST25VF064C_BLOCK_COMMAND_HANDLE type 837 DRV_SST25VF064C_BLOCK_COMMAND_HANDLE_INVALID macro 841 DRV_SST25VF064C_BLOCK_EVENT enumeration 838 DRV_SST25VF064C_BlockErase function 829 DRV_SST25VF064C_BlockEventHandlerSet function 831 DRV_SST25VF064C_BlockRead function 833 DRV_SST25VF064C_BlockWrite function 834 DRV_SST25VF064C_CLIENT_STATUS enumeration 838 DRV_SST25VF064C_CLIENTS_NUMBER macro 780 DRV_SST25VF064C_ClientStatus function 826 DRV_SST25VF064C_Close function 827 DRV_SST25VF064C_COMMAND_STATUS enumeration 839 DRV_SST25VF064C_CommandStatus function 828 drv_sst25vf064c_config_template.h 846 DRV_SST25VF064C_Deinitialize function 824 DRV_SST25VF064C_EVENT_HANDLER type 839 DRV_SST25VF064C_GeometryGet function 836 DRV_SST25VF064C_HARDWARE_HOLD_ENABLE macro 781 DRV_SST25VF064C_HARDWARE_WRITE_PROTECTION_ENABLE macro 781 DRV_SST25VF064C_INDEX_0 macro 841 DRV_SST25VF064C_INDEX_1 macro 841 DRV_SST25VF064C_INIT structure 840 DRV_SST25VF064C_Initialize function 823 DRV_SST25VF064C_INSTANCES_NUMBER macro 781 DRV_SST25VF064C_MediaIsAttached function 837 DRV_SST25VF064C_MODE macro 781 DRV_SST25VF064C_Open function 829 DRV_SST25VF064C_QUEUE_DEPTH_COMBINED macro 782 DRV_SST25VF064C_Status function 825 DRV_SST25VF064C_Tasks function 826 drv_sst26.h 944 DRV_SST26_AddressGet function 938 DRV_SST26_BUFFER_OBJECT_NUMBER macro 922 DRV_SST26_CLIENTS_NUMBER macro 922 DRV_SST26_Close function 929 DRV_SST26_COMMAND_HANDLE type 941 DRV_SST26_COMMAND_HANDLE_INVALID macro 943 DRV_SST26_COMMAND_STATUS enumeration 941 DRV_SST26_CommandStatus function 936 drv_sst26_config_template.h 945 DRV_SST26_Deinitialize function 926 DRV_SST26_Erase function 929 DRV_SST26_EraseWrite function 931 DRV_SST26_EVENT enumeration 942 DRV_SST26_EVENT_HANDLER type 942 DRV_SST26_EventHandlerSet function 937 DRV_SST26_GeometryGet function 939 DRV_SST26_INDEX_0 macro 944 DRV_SST26_INDEX_1 macro 944 DRV_SST26_INIT structure 943 DRV_SST26_Initialize function 925 DRV_SST26_INSTANCES_NUMBER macro 923 DRV_SST26_IsAttached function 940 DRV_SST26_IsWriteProtected function 940 DRV_SST26_Open function 928 DRV_SST26_Read function 933 DRV_SST26_Status function 926 DRV_SST26_SYS_FS_REGISTER macro 923 DRV_SST26_Tasks function 927 DRV_SST26_Write function 934 DRV_STATIC_BUILD macro 532 drv_tmr.h 1006 DRV_TMR_AlarmDeregister function 992 DRV_TMR_AlarmDisable function 991 DRV_TMR_AlarmEnable function 991 DRV_TMR_AlarmHasElapsed function 990 DRV_TMR_AlarmPeriodGet function 993 DRV_TMR_AlarmPeriodSet function 993 DRV_TMR_AlarmRegister function 994 DRV_TMR_ASYNC_WRITE_ENABLE macro 978 DRV_TMR_CALLBACK type 1001 DRV_TMR_CLIENT_STATUS enumeration 1002 DRV_TMR_CLIENTS_NUMBER macro 979 DRV_TMR_ClientStatus function 986 DRV_TMR_CLOCK_PRESCALER macro 977 DRV_TMR_CLOCK_SOURCE macro 979 DRV_TMR_ClockSet function 985 DRV_TMR_Close function 987 drv_tmr_config_template.h 1008 DRV_TMR_CounterClear function 996 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1454 DRV_TMR_CounterFrequencyGet function 995 DRV_TMR_CounterValueGet function 996 DRV_TMR_CounterValueSet function 998 DRV_TMR_Deinitialize function 982 DRV_TMR_DIVIDER_RANGE structure 1002 DRV_TMR_DividerRangeGet function 1000 DRV_TMR_GateModeClear function 998 DRV_TMR_GateModeSet function 986 DRV_TMR_INDEX_0 macro 1003 DRV_TMR_INDEX_1 macro 1004 DRV_TMR_INDEX_10 macro 1006 DRV_TMR_INDEX_11 macro 1006 DRV_TMR_INDEX_2 macro 1004 DRV_TMR_INDEX_3 macro 1004 DRV_TMR_INDEX_4 macro 1004 DRV_TMR_INDEX_5 macro 1005 DRV_TMR_INDEX_6 macro 1005 DRV_TMR_INDEX_7 macro 1005 DRV_TMR_INDEX_8 macro 1005 DRV_TMR_INDEX_9 macro 1005 DRV_TMR_INDEX_COUNT macro 1003 DRV_TMR_INIT structure 1001 DRV_TMR_Initialize function 982 DRV_TMR_INSTANCES_NUMBER macro 976 DRV_TMR_INTERRUPT_MODE macro 977 DRV_TMR_INTERRUPT_SOURCE macro 978 DRV_TMR_MODE macro 977 DRV_TMR_MODULE_ID macro 978 DRV_TMR_MODULE_INIT macro 978 DRV_TMR_Open function 988 DRV_TMR_OPERATION_MODE enumeration 1003 DRV_TMR_OperationModeGet function 999 DRV_TMR_PrescalerGet function 999 DRV_TMR_Start function 988 DRV_TMR_Status function 983 DRV_TMR_Stop function 989 DRV_TMR_Tasks function 984 drv_touch.h 1016 drv_touch_adc.h 614 DRV_TOUCH_ADC10BIT_CalibrationSet function 1022 DRV_TOUCH_ADC10BIT_CLIENT_DATA structure 1030 DRV_TOUCH_ADC10BIT_Close function 1022 DRV_TOUCH_ADC10BIT_Deinitialize function 1023 DRV_TOUCH_ADC10BIT_HANDLE type 1030 DRV_TOUCH_ADC10BIT_HANDLE_INVALID macro 1031 DRV_TOUCH_ADC10BIT_INDEX_0 macro 1031 DRV_TOUCH_ADC10BIT_INDEX_1 macro 1032 DRV_TOUCH_ADC10BIT_INDEX_COUNT macro 1032 DRV_TOUCH_ADC10BIT_INIT structure 1031 DRV_TOUCH_ADC10BIT_Initialize function 1023 DRV_TOUCH_ADC10BIT_Open function 1024 DRV_TOUCH_ADC10BIT_PositionDetect function 1028 DRV_TOUCH_ADC10BIT_Status function 1025 DRV_TOUCH_ADC10BIT_Tasks function 1026 DRV_TOUCH_ADC10BIT_TouchDataRead function 1029 DRV_TOUCH_ADC10BIT_TouchGetRawX function 1027 DRV_TOUCH_ADC10BIT_TouchGetRawY function 1027 DRV_TOUCH_ADC10BIT_TouchGetX function 1027 DRV_TOUCH_ADC10BIT_TouchGetY function 1029 DRV_TOUCH_ADC10BIT_TouchStatus function 1030 DRV_TOUCH_ADC10BIT_TouchStoreCalibration function 1028 DRV_TOUCH_AR1021_Calibrate function 1050 DRV_TOUCH_AR1021_CALIBRATION_PROMPT_CALLBACK structure 1052 DRV_TOUCH_AR1021_CalibrationSet function 1050 DRV_TOUCH_AR1021_Close function 1051 DRV_TOUCH_AR1021_Deinitialize function 1044 DRV_TOUCH_AR1021_FactoryDefaultSet function 1045 DRV_TOUCH_AR1021_HANDLE type 1053 DRV_TOUCH_AR1021_HANDLE_INVALID macro 1054 DRV_TOUCH_AR1021_INDEX_0 macro 1054 DRV_TOUCH_AR1021_INDEX_COUNT macro 1055 DRV_TOUCH_AR1021_Initialize function 1045 DRV_TOUCH_AR1021_MODULE_ID enumeration 1053 DRV_TOUCH_AR1021_Open function 1052 DRV_TOUCH_AR1021_RegisterConfigWrite function 1046 DRV_TOUCH_AR1021_Status function 1047 DRV_TOUCH_AR1021_TASK_STATE enumeration 1054 DRV_TOUCH_AR1021_Tasks function 1047 DRV_TOUCH_AR1021_TouchDataRead function 1048 DRV_TOUCH_AR1021_TouchGetX function 1048 DRV_TOUCH_AR1021_TouchGetY function 1049 DRV_TOUCH_AR1021_TouchPenGet function 1049 DRV_TOUCH_AR1021_TouchStatus function 1050 DRV_TOUCH_Close function 1009 DRV_TOUCH_Deinitialize function 1010 DRV_TOUCH_INDEX_0 macro 1015 DRV_TOUCH_INDEX_1 macro 1015 DRV_TOUCH_INDEX_COUNT macro 1016 DRV_TOUCH_INIT structure 1014 DRV_TOUCH_Initialize function 1010 DRV_TOUCH_MTCH6301_CLIENT_OBJECT structure 1072 DRV_TOUCH_MTCH6301_Close function 1063 DRV_TOUCH_MTCH6301_Deinitialize function 1064 DRV_TOUCH_MTCH6301_HANDLE type 1071 DRV_TOUCH_MTCH6301_HANDLE_INVALID macro 1071 DRV_TOUCH_MTCH6301_I2C_MASTER_READ_ID macro 1075 DRV_TOUCH_MTCH6301_I2C_MASTER_WRITE_ID macro 1075 DRV_TOUCH_MTCH6301_I2C_READ_FRAME_SIZE macro 1071 DRV_TOUCH_MTCH6301_INDEX_0 macro 1072 DRV_TOUCH_MTCH6301_INDEX_1 macro 1073 DRV_TOUCH_MTCH6301_INDEX_COUNT macro 1073 DRV_TOUCH_MTCH6301_Initialize function 1065 DRV_TOUCH_MTCH6301_MODULE_ID enumeration 1071 DRV_TOUCH_MTCH6301_OBJECT structure 1073 DRV_TOUCH_MTCH6301_Open function 1066 DRV_TOUCH_MTCH6301_ReadRequest function 1068 DRV_TOUCH_MTCH6301_Status function 1067 DRV_TOUCH_MTCH6301_TASK_QUEUE structure 1074 DRV_TOUCH_MTCH6301_TASK_STATE enumeration 1075 DRV_TOUCH_MTCH6301_Tasks function 1068 DRV_TOUCH_MTCH6301_TouchDataRead function 1070 DRV_TOUCH_MTCH6301_TouchGetX function 1069 DRV_TOUCH_MTCH6301_TouchGetY function 1069 DRV_TOUCH_MTCH6301_TouchStatus function 1070 DRV_TOUCH_MTCH6303_I2C_REGISTER_MAP enumeration 1106 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1455 DRV_TOUCH_MTCH6303_MSG_ID enumeration 1105 DRV_TOUCH_Open function 1011 DRV_TOUCH_PEN_STATE type 1014 DRV_TOUCH_POSITION_STATUS type 1015 DRV_TOUCH_Read function 1012 DRV_TOUCH_Reinitialize function 1012 DRV_TOUCH_SAMPLE_POINTS type 1015 DRV_TOUCH_Status function 1013 DRV_TOUCH_Tasks function 1013 drv_usart.h 1348 DRV_USART_AddressedBufferAddWrite function 1333 DRV_USART_BAUD_RATE_IDXn macro 1313 DRV_USART_BaudSet function 1326 DRV_USART_BUFFER_QUEUE_SUPPORT macro 1309 DRV_USART_BufferAddRead function 1328 DRV_USART_BufferAddWrite function 1329 DRV_USART_BufferCompletedBytesGet function 1335 DRV_USART_BufferEventHandlerSet function 1331 DRV_USART_BufferProcessedSizeGet function 1332 DRV_USART_BufferRemove function 1336 DRV_USART_BYTE_MODEL_BLOCKING macro 1313 DRV_USART_BYTE_MODEL_CALLBACK macro 1314 DRV_USART_BYTE_MODEL_SUPPORT macro 1310 DRV_USART_ByteErrorCallbackSet function 1345 DRV_USART_ByteReceiveCallbackSet function 1346 DRV_USART_ByteTransmitCallbackSet function 1347 DRV_USART_CLIENTS_NUMBER macro 1308 DRV_USART_ClientStatus function 1324 DRV_USART_Close function 1323 drv_usart_config_template.h 1350 DRV_USART_Deinitialize function 1318 DRV_USART_ErrorGet function 1324 DRV_USART_INDEX macro 1308 DRV_USART_Initialize function 1317 DRV_USART_INSTANCES_NUMBER macro 1309 DRV_USART_INTERRUPT_MODE macro 1308 DRV_USART_INTERRUPT_SOURCE_ERROR macro 1309 DRV_USART_INTERRUPT_SOURCE_RECEIVE macro 1310 DRV_USART_INTERRUPT_SOURCE_RECEIVE_DMA macro 1310 DRV_USART_INTERRUPT_SOURCE_TRANSMIT macro 1311 DRV_USART_INTERRUPT_SOURCE_TRANSMIT_DMA macro 1311 DRV_USART_LineControlSet function 1327 DRV_USART_Open function 1322 DRV_USART_PERIPHERAL_ID macro 1309 DRV_USART_QUEUE_DEPTH_COMBINED macro 1311 DRV_USART_RCV_QUEUE_SIZE_IDXn macro 1314 DRV_USART_Read function 1338 DRV_USART_READ_WRITE_MODEL_SUPPORT macro 1312 DRV_USART_ReadByte function 1340 DRV_USART_RECEIVE_DMA macro 1312 DRV_USART_ReceiverBufferIsEmpty function 1344 DRV_USART_ReceiverBufferSizeGet function 1342 DRV_USART_Status function 1319 DRV_USART_TasksError function 1321 DRV_USART_TasksReceive function 1320 DRV_USART_TasksTransmit function 1320 DRV_USART_TransferStatus function 1343 DRV_USART_TRANSMIT_DMA macro 1313 DRV_USART_TransmitBufferIsFull function 1344 DRV_USART_TransmitBufferSizeGet function 1342 DRV_USART_Write function 1339 DRV_USART_WriteByte function 1341 DRV_USART_XMIT_QUEUE_SIZE_IDXn macro 1315 drv_usbfs.h 1232 DRV_USBFS_ClientEventCallBackSet function 1192 DRV_USBFS_Close function 1193 drv_usbfs_config_template.h 1234 DRV_USBFS_DEVICE_AddressSet function 1196 DRV_USBFS_DEVICE_Attach function 1196 DRV_USBFS_DEVICE_CurrentSpeedGet function 1197 DRV_USBFS_DEVICE_Detach function 1198 DRV_USBFS_DEVICE_EndpointDisable function 1199 DRV_USBFS_DEVICE_EndpointDisableAll function 1200 DRV_USBFS_DEVICE_EndpointEnable function 1201 DRV_USBFS_DEVICE_EndpointIsEnabled function 1202 DRV_USBFS_DEVICE_EndpointIsStalled function 1203 DRV_USBFS_DEVICE_EndpointStall function 1204 DRV_USBFS_DEVICE_EndpointStallClear function 1204 DRV_USBFS_DEVICE_INTERFACE macro 1230 DRV_USBFS_DEVICE_IRPCancel function 1205 DRV_USBFS_DEVICE_IRPCancelAll function 1207 DRV_USBFS_DEVICE_IRPSubmit function 1208 DRV_USBFS_DEVICE_RemoteWakeupStart function 1210 DRV_USBFS_DEVICE_RemoteWakeupStop function 1210 DRV_USBFS_DEVICE_SOFNumberGet function 1211 DRV_USBFS_DEVICE_SUPPORT macro 1185 DRV_USBFS_ENDPOINT_TABLE_ENTRY_SIZE macro 1230 DRV_USBFS_ENDPOINTS_NUMBER macro 1185 DRV_USBFS_EVENT enumeration 1226 DRV_USBFS_EVENT_CALLBACK type 1227 DRV_USBFS_HOST_ATTACH_DEBOUNCE_DURATION macro 1186 DRV_USBFS_HOST_EventsDisable function 1212 DRV_USBFS_HOST_EventsEnable function 1212 DRV_USBFS_HOST_INTERFACE macro 1231 DRV_USBFS_HOST_IRPCancel function 1213 DRV_USBFS_HOST_IRPSubmit function 1214 DRV_USBFS_HOST_NAK_LIMIT macro 1186 DRV_USBFS_HOST_PIPE_HANDLE type 1227 DRV_USBFS_HOST_PIPE_HANDLE_INVALID macro 1231 DRV_USBFS_HOST_PipeClose function 1216 DRV_USBFS_HOST_PIPES_NUMBER macro 1186 DRV_USBFS_HOST_PipeSetup function 1217 DRV_USBFS_HOST_RESET_DURATION macro 1187 DRV_USBFS_HOST_ROOT_HUB_BusSpeedGet function 1218 DRV_USBFS_HOST_ROOT_HUB_Initialize function 1219 DRV_USBFS_HOST_ROOT_HUB_MaximumCurrentGet function 1219 DRV_USBFS_HOST_ROOT_HUB_OperationEnable function 1220 DRV_USBFS_HOST_ROOT_HUB_OperationIsEnabled function 1221 DRV_USBFS_HOST_ROOT_HUB_PortNumbersGet function 1222 DRV_USBFS_HOST_ROOT_HUB_PortReset function 1222 DRV_USBFS_HOST_ROOT_HUB_PortResetIsComplete function 1223 DRV_USBFS_HOST_ROOT_HUB_PortResume function 1224 DRV_USBFS_HOST_ROOT_HUB_PortSpeedGet function 1225 DRV_USBFS_HOST_ROOT_HUB_PortSuspend function 1226 DRV_USBFS_HOST_SUPPORT macro 1187 DRV_USBFS_INDEX_0 macro 1231 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1456 DRV_USBFS_INDEX_1 macro 1232 DRV_USBFS_INIT structure 1228 DRV_USBFS_Initialize function 1194 DRV_USBFS_INSTANCES_NUMBER macro 1187 DRV_USBFS_INTERRUPT_MODE macro 1188 DRV_USBFS_Open function 1195 DRV_USBFS_OPMODES enumeration 1229 DRV_USBFS_ROOT_HUB_PORT_INDICATION type 1229 DRV_USBFS_ROOT_HUB_PORT_OVER_CURRENT_DETECT type 1230 DRV_USBFS_ROOT_HUB_PORT_POWER_ENABLE type 1230 DRV_USBFS_Status function 1190 DRV_USBFS_Tasks function 1191 DRV_USBFS_Tasks_ISR function 1192 drv_usbhs.h 1292 DRV_USBHS_ClientEventCallBackSet function 1253 DRV_USBHS_Close function 1253 drv_usbhs_config_template.h 1294 DRV_USBHS_DEVICE_AddressSet function 1255 DRV_USBHS_DEVICE_Attach function 1256 DRV_USBHS_DEVICE_CurrentSpeedGet function 1256 DRV_USBHS_DEVICE_Detach function 1257 DRV_USBHS_DEVICE_EndpointDisable function 1258 DRV_USBHS_DEVICE_EndpointDisableAll function 1259 DRV_USBHS_DEVICE_EndpointEnable function 1260 DRV_USBHS_DEVICE_EndpointIsEnabled function 1261 DRV_USBHS_DEVICE_EndpointIsStalled function 1262 DRV_USBHS_DEVICE_EndpointStall function 1263 DRV_USBHS_DEVICE_EndpointStallClear function 1263 DRV_USBHS_DEVICE_INTERFACE macro 1291 DRV_USBHS_DEVICE_IRPCancel function 1264 DRV_USBHS_DEVICE_IRPCancelAll function 1266 DRV_USBHS_DEVICE_IRPSubmit function 1267 DRV_USBHS_DEVICE_RemoteWakeupStart function 1269 DRV_USBHS_DEVICE_RemoteWakeupStop function 1269 DRV_USBHS_DEVICE_SOFNumberGet function 1270 DRV_USBHS_DEVICE_SUPPORT macro 1243 DRV_USBHS_DEVICE_TestModeEnter function 1271 DRV_USBHS_DEVICE_TestModeExit function 1271 DRV_USBHS_ENDPOINTS_NUMBER macro 1244 DRV_USBHS_EVENT enumeration 1287 DRV_USBHS_EVENT_CALLBACK type 1288 DRV_USBHS_HOST_ATTACH_DEBOUNCE_DURATION macro 1244 DRV_USBHS_HOST_EventsDisable function 1272 DRV_USBHS_HOST_EventsEnable function 1273 DRV_USBHS_HOST_INTERFACE macro 1291 DRV_USBHS_HOST_IRPCancel function 1274 DRV_USBHS_HOST_IRPSubmit function 1275 DRV_USBHS_HOST_NAK_LIMIT macro 1244 DRV_USBHS_HOST_PIPE_HANDLE type 1288 DRV_USBHS_HOST_PIPE_HANDLE_INVALID macro 1291 DRV_USBHS_HOST_PipeClose function 1276 DRV_USBHS_HOST_PIPES_NUMBER macro 1245 DRV_USBHS_HOST_PipeSetup function 1277 DRV_USBHS_HOST_RESET_DURATION macro 1245 DRV_USBHS_HOST_ROOT_HUB_BusSpeedGet function 1279 DRV_USBHS_HOST_ROOT_HUB_Initialize function 1279 DRV_USBHS_HOST_ROOT_HUB_MaximumCurrentGet function 1280 DRV_USBHS_HOST_ROOT_HUB_OperationEnable function 1281 DRV_USBHS_HOST_ROOT_HUB_OperationIsEnabled function 1282 DRV_USBHS_HOST_ROOT_HUB_PortNumbersGet function 1282 DRV_USBHS_HOST_ROOT_HUB_PortReset function 1283 DRV_USBHS_HOST_ROOT_HUB_PortResetIsComplete function 1284 DRV_USBHS_HOST_ROOT_HUB_PortResume function 1285 DRV_USBHS_HOST_ROOT_HUB_PortSpeedGet function 1285 DRV_USBHS_HOST_ROOT_HUB_PortSuspend function 1286 DRV_USBHS_HOST_SUPPORT macro 1245 DRV_USBHS_INDEX_0 macro 1292 DRV_USBHS_INIT structure 1288 DRV_USBHS_Initialize function 1249 DRV_USBHS_INSTANCES_NUMBER macro 1246 DRV_USBHS_INTERRUPT_MODE macro 1246 DRV_USBHS_Open function 1254 DRV_USBHS_OPMODES enumeration 1289 DRV_USBHS_ROOT_HUB_PORT_INDICATION type 1290 DRV_USBHS_ROOT_HUB_PORT_OVER_CURRENT_DETECT type 1290 DRV_USBHS_ROOT_HUB_PORT_POWER_ENABLE type 1290 DRV_USBHS_Status function 1250 DRV_USBHS_Tasks function 1251 DRV_USBHS_Tasks_ISR function 1251 DRV_USBHS_Tasks_ISR_USBDMA function 1252 drv_wm8904.h 348 DRV_WM8904_AUDIO_DATA_FORMAT enumeration 321 DRV_WM8904_BAUD_RATE macro 321 DRV_WM8904_BUFFER_EVENT enumeration 344 DRV_WM8904_BUFFER_EVENT_HANDLER type 344 DRV_WM8904_BUFFER_HANDLE type 345 DRV_WM8904_BUFFER_HANDLE_INVALID macro 342 DRV_WM8904_BufferAddRead function 332 DRV_WM8904_BufferAddWrite function 333 DRV_WM8904_BufferAddWriteRead function 334 DRV_WM8904_BufferEventHandlerSet function 329 DRV_WM8904_CHANNEL enumeration 346 DRV_WM8904_CLIENTS_NUMBER macro 321 DRV_WM8904_Close function 329 DRV_WM8904_COMMAND_EVENT_HANDLER type 346 DRV_WM8904_CommandEventHandlerSet function 331 drv_wm8904_config_template.h 348 DRV_WM8904_COUNT macro 342 DRV_WM8904_Deinitialize function 326 DRV_WM8904_ENABLE_MIC_INPUT macro 322 DRV_WM8904_INDEX_0 macro 343 DRV_WM8904_INDEX_1 macro 343 DRV_WM8904_INDEX_2 macro 343 DRV_WM8904_INDEX_3 macro 343 DRV_WM8904_INDEX_4 macro 344 DRV_WM8904_INDEX_5 macro 344 DRV_WM8904_INIT structure 347 DRV_WM8904_Initialize function 325 DRV_WM8904_INSTANCES_NUMBER macro 322 DRV_WM8904_MuteOff function 336 DRV_WM8904_MuteOn function 337 DRV_WM8904_Open function 328 DRV_WM8904_SamplingRateGet function 338 DRV_WM8904_SamplingRateSet function 338 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1457 DRV_WM8904_SetAudioCommunicationMode function 339 DRV_WM8904_Status function 326 DRV_WM8904_Tasks function 327 DRV_WM8904_VersionGet function 341 DRV_WM8904_VersionStrGet function 341 DRV_WM8904_VOLUME macro 322 DRV_WM8904_VolumeGet function 339 DRV_WM8904_VolumeSet function 340 drv_xc2c64a.h 359 E ENC28J60 Driver Library Help 407 ENCx24J600 Driver Library Help 427 Ethernet GMAC Driver Library 515 Ethernet MAC Driver Library 446 Ethernet PHY Driver Library 469 Example Code for Complete Operation 687 Example Usage of the Timer Driver 975 F File I/O Type Read/Write Data Transfer Model 1303 Files 19, 70, 79, 101, 154, 196, 235, 275, 314, 347, 359, 376, 406, 425, 445, 467, 505, 514, 520, 550, 605, 613, 617, 636, 639, 676, 708, 741, 769, 842, 880, 915, 944, 969, 1006, 1016, 1032, 1038, 1055, 1076, 1106, 1144, 1232, 1292, 1348, 1382, 1392, 1429 10-bit ADC Touch Driver Library 1032 ADC Touch Driver Library 1038 AK4384 Codec Driver Library 154 AK4642 Codec Driver Library 196 AK4953 Codec Driver Library 235 AK4954 Codec Driver Library 275 AK7755 Codec Driver Library 314 AR1021 Touch Driver Library 1055 BM64 Bluetooth Driver Library 70 CPLD XC2C64A Driver Library 359 CTR Driver Library 376 EEPROM Driver Library 406 Ethernet MAC Driver Library 467, 520 Ethernet PHY Driver Library 505 MRF24WN Wi-Fi Driver Library 1382, 1392, 1429 MTCH6301 Touch Driver Library 1076 MTCH6303 Touch Driver Library 1106 NVM Driver Library 636, 676 PMP Driver Library 708 SD Card Driver Library 741 SPI Driver Library 769 SPI Flash Driver Library 842 SPI PIC32WK IPF Flash Driver Library 880 SQI Driver Library 915 SQI Flash Driver Library 944 Timer Driver Library 1006 USART Driver Library 1348 WM8904 Codec Driver Library 347 Flash Driver Library 508 G General Device Mode Operations 1169 Generic Touch Driver API 1008 H Host Interface Driver Wi-Fi Events 1439 How the Library Works 28, 81, 107, 158, 200, 239, 279, 318, 361, 379, 409, 429, 521, 554, 612, 615, 646, 683, 716, 745, 773, 849, 883, 919, 947, 971, 1035, 1039, 1057, 1079, 1109, 1178, 1236, 1298, 1352, 1387, 1394, 1436 ADC Touch Driver Library 1035 AK4384 Driver Library 107 AK4642 Driver Library 158 AK4953 Driver Library 200 AK4954 Driver Library 239 AK7755 Driver Library 279 AR1021 Touch Driver Library 1039 BM64 Bluetooth Driver Library 28 CTR Driver Library 361 Data EEPROM Driver Library 379 ENC28J60 Driver 409 ENCx24J600 Driver 429 MRF24WN Wi-Fi Driver Library 1352, 1387, 1394, 1436 MTCH6301 Touch Driver Library 1057 MTCH6303 Touch Driver Library 1079 NVM Driver Library 646 PMP Driver Library 683 SD Card Driver Library 716 SPI Driver Library 745 SPI Flash Driver Library 773 SPI PIC32WK IPF Flash Driver Library 849 SQI Driver Library 883 SQI Flash Driver Library 919 Timer Driver Library 971 USART Driver Library 1298 WM8904 Driver Library 318 I I2C Driver Library Help 520 I2C_STATIC_DRIVER_MODE macro 532 I2S Driver Library Help 552 INCLUDE_BM64_BLE macro 34 INCLUDE_BM64_I2S macro 34 INCLUDE_DEPRECATED_MMI_COMMANDS macro 34 Initializing the Driver 1035, 1039, 1057, 1109 Initializing the USART Driver 1298 Input Capture Driver Library 607 Input System Service mXT336T Touch Driver Library 614 Input System Service Touch ADC Driver Library 611 Input System Service Touch Driver Library 610 Introduction 3, 20, 25, 72, 80, 102, 106, 156, 198, 237, 277, 316, 349, 350, 360, 378, 407, 427, 447, 469, 508, 515, 520, 552, 607, 617, 638, 645, 678, 681, 710, 714, 743, 771, 847, 882, 917, 946, 970, 1017, 1034, 1038, 1056, 1077, 1108, 1295, 1351, 1385, 1393, 1432 AK7755 Codec Driver Library 277 OVM7690 Camera Driver Library 80 iwpriv_adhocctx_set function 1376 IWPRIV_CMD enumeration 1378 iwpriv_config_read function 1377 iwpriv_config_write function 1366 IWPRIV_CONN_STATUS enumeration 1377 iwpriv_connstatus_get function 1366 iwpriv_devinfo_get function 1367 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1458 iwpriv_execute function 1374 IWPRIV_EXECUTE_PARAM union 1378 iwpriv_get function 1374 IWPRIV_GET_PARAM union 1378 iwpriv_initialconn_set function 1367 iwpriv_initstatus_get function 1368 iwpriv_is_servermode function 1368 iwpriv_leftclient_get function 1369 iwpriv_mcastfilter_set function 1369 iwpriv_nettype_get function 1370 iwpriv_nettype_set function 1370 iwpriv_numberofscanresults_get function 1371 IWPRIV_PARAM_CLIENTINFO structure 1379 IWPRIV_PARAM_CONFIG structure 1380 IWPRIV_PARAM_CONNECT structure 1380 IWPRIV_PARAM_CONTEXT structure 1379 IWPRIV_PARAM_DEVICEINFO structure 1379 IWPRIV_PARAM_DRIVERSTATUS structure 1380 IWPRIV_PARAM_FWUPGRADE structure 1381 IWPRIV_PARAM_MULTICASTFILTER structure 1381 IWPRIV_PARAM_NETWORKTYPE structure 1381 IWPRIV_PARAM_OPERATIONMODE structure 1381 IWPRIV_PARAM_POWERSAVE structure 1382 IWPRIV_PARAM_SCAN structure 1382 IWPRIV_PARAM_SSID structure 1382 iwpriv_powersave_config function 1371 iwpriv_prescan_isfinished function 1374 iwpriv_prescan_option_get function 1375 iwpriv_prescan_option_set function 1375 iwpriv_prescan_start function 1372 iwpriv_scan_start function 1372 IWPRIV_SCAN_STATUS enumeration 1379 iwpriv_scanstatus_get function 1373 iwpriv_set function 1376 IWPRIV_SET_PARAM union 1380 iwpriv_ssid_get function 1373 iwpriv_ssid_set function 1374 IWPRIV_STATUS enumeration 1377 L Library Interface 14, 21, 37, 72, 83, 102, 120, 169, 207, 247, 287, 323, 349, 351, 362, 385, 412, 432, 453, 474, 508, 519, 533, 570, 607, 613, 617, 622, 638, 654, 678, 690, 710, 722, 754, 783, 852, 889, 924, 952, 980, 1009, 1021, 1037, 1043, 1062, 1080, 1115, 1189, 1247, 1316, 1356, 1391, 1399, 1441 10-bit ADC Touch Driver Library 1021 ADC Driver Library 21 ADC Touch Driver Library 1037 AK4384 Codec Driver Library 120 AK4642 Codec Driver Library 169 AK4953 Codec Driver Library 207 AK4954 Codec Driver Library 247 AK7755 Codec Driver Library 287 AR1021 Touch Driver Library 1043 BM64 Bluetooth Driver Library 37 Camera Driver Library 83 CAN Driver Library 102 Comparator Driver Library 349 CPLD XC2C64A Driver Library 351 CTR Driver Library 362 Data EEPROM Driver Library 385 Ethernet MAC Driver Library 453, 519 Ethernet PHY Driver Library 474 Flash Driver Library 508 Input Capture Driver Library 607 MCPWM Driver Library 638 MRF24WN Wi-Fi Library 1356, 1391, 1399, 1441 MTCH6301 Touch Driver Library 1062 MTCH6303 Touch Driver Library 1080 NVM Driver Library 622, 654 Output Compare Driver Library 678 PMP Driver Library 690 RTCC Driver Library 710 SD Card Driver Library 722 SPI Driver Library 754 SPI Flash Driver Library 783 SPI PIC32WK IPF Flash Driver Library 852 SQI Driver Library 889 SQI Flash Driver Library 924 Timer Driver Library 980 USART Driver Library 1316 WM8904 Codec Driver Library 323 Library Overview 28, 80, 107, 158, 199, 239, 279, 317, 351, 361, 379, 409, 429, 449, 471, 518, 521, 554, 611, 615, 618, 646, 683, 716, 745, 772, 848, 883, 919, 947, 970, 1017, 1035, 1039, 1057, 1079, 1109, 1177, 1235, 1297, 1352, 1387, 1394, 1435 10-bit ADC Touch Driver Library 1017 ADC Touch Driver Library 1035 AK4384 Driver Library 107 AK4642 Driver Library 158 AK4953 Driver Library 199 AK4954 Driver Library 239 AK7755 Driver Library 279 AR1021 Touch Driver Library 1039 BM64 Bluetooth Driver Library 28 CPLD XC2C64A Driver Library 351 CTR Driver Library 361 Data EEPROM Driver Library 379 Ethernet MAC Driver Library 449, 518 Ethernet PHY Driver Library 471 MRF24WN Wi-Fi Driver Library 1352, 1387, 1394, 1435 MTCH6301 Touch Driver Library 1057 MTCH6303 Touch Driver Library 1079 NVM Driver Library 618, 646 PMP Driver Library 683 SD Card Driver Library 716 SPI Driver Library 745 SPI Flash Driver Library 772 SPI PIC32WK IPF Flash Driver Library 848 SQI Driver Library 883 SQI Flash Driver Library 919 Timer Driver Library 970 USART Driver Library 1297 WM8904 Driver Library 317 M MAX_NONBUFFERED_BYTE_COUNT macro 707 Media Interface Functions 950 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1459 Migrating Applications from v1.03.01 and Earlier Releases of MPLAB Harmony 640 MIIM Driver Library 617 Modification 973 Motor Control PWM (MCPWM) Driver Library 638 MRF24WN Wi-Fi Driver Library 1351 MTCH6301 Touch Driver Library 1056 MTCH6303 Touch Driver Library 1077 MXT_T100_EVENT_DOWN enumeration member 1143 MXT_T100_EVENT_DOWNSUP enumeration member 1143 MXT_T100_EVENT_DOWNUP enumeration member 1143 MXT_T100_EVENT_MOVE enumeration member 1143 MXT_T100_EVENT_NO_EVENT enumeration member 1143 MXT_T100_EVENT_SUP enumeration member 1143 MXT_T100_EVENT_UNSUP enumeration member 1143 MXT_T100_EVENT_UNSUPSUP enumeration member 1143 MXT_T100_EVENT_UNSUPUP enumeration member 1143 MXT_T100_EVENT_UP enumeration member 1143 MXT_T100_TYPE_ACTIVE_STYLUS enumeration member 1144 MXT_T100_TYPE_FINGER enumeration member 1144 MXT_T100_TYPE_GLOVE enumeration member 1144 MXT_T100_TYPE_HOVERING_FINGER enumeration member 1144 MXT_T100_TYPE_LARGE_TOUCH enumeration member 1144 MXT_T100_TYPE_PASSIVE_STYLUS enumeration member 1144 mXT336T Touch Driver Library 1107 N NVM Driver Library 640 NVM System Initialization 647 O Opening a Driver 9 Opening the Driver 773, 849, 1036, 1040, 1058, 1110, 1160 Opening the USART Driver 1302 Optional Interfaces 975 Output Compare Driver Library 678 OVM7690 Camera Driver Library 80 P Parallel Master Port (PMP) Driver Library 681 PIC32MX USB Driver 1176 PIC32MZ USB Driver 1234 PMP_QUEUE_ELEMENT_OBJECT structure 708 R RTCC Driver Library 710 S Sample Functionality 1354, 1387, 1395 Sample Rate 32 SAMPLE_LENGTH enumeration 314 SD Card Driver Initialization 717 SDCARD_DETECTION_LOGIC enumeration 737 SDCARD_MAX_LIMIT macro 738 Secure Digital (SD) Card Driver Library 714 Settings Functions 31 SPI Driver Library 743 SPI Flash Driver Library 771 SPI PIC32WK IPF Flash Driver Library 847 SQI Driver Library 882 SQI Flash Driver Library 917 SRAM Driver Library 946 SST25FV016B API 783 SST25VF020B API 802 SST25VF064C API 822 System Access 108, 159, 200, 239, 279, 318, 522, 554, 745 System Functions 29, 883 System Initialization 683, 1353 System Initialization and Deinitialization 773 System Initialization/Deinitialization 849 System Initialization/Status Functions 947 System Interaction 971 T t100_event enumeration 1143 t100_type enumeration 1144 Tasks Routine 1036, 1040, 1059, 1111 Timer Driver Library 970 Touch Driver Libraries Help 1008 Touch Input Read Request 1059, 1111 Transfer Operation 685 Transferring Data to the Host 1172 U USART Driver Library 1294 USB Driver Device Mode Operation 1168 USB Driver Host Mode Operation 1161 USB Driver Libraries 1147 Using a Driver in an Application 7 Using a Driver's Client Interface 6 Using a Driver's System Interface 4 Using Asynchronous and Callback Functions 11 Using Driver Interface Functions 10 Using the Library 27, 80, 106, 157, 199, 238, 278, 317, 350, 360, 378, 408, 428, 447, 469, 516, 520, 553, 614, 618, 645, 682, 715, 744, 771, 847, 882, 918, 946, 970, 1017, 1034, 1038, 1056, 1078, 1108, 1177, 1235, 1295, 1352, 1386, 1394, 1434 10-bit ADC Touch Driver Library 1017 ADC Touch Driver Library 1034 AK4384 Codec Driver Library 106 AK4642 Codec Driver Library 157 AK4953 Codec Driver Library 199 AK4954 Codec Driver Library 238 AK7755 Codec Driver Library 278 AR1021 Touch Driver Library 1038 BM64 Bluetooth Driver Library 27 CPLD XC2C64A Driver Library 350 CTR Driver Library 360 Data EEPROM Driver Library 378 Ethernet MAC Driver Library 447, 516 Ethernet PHY Driver Library 469 MIIM Driver Library 618 MRF24WN Wi-Fi Driver Library 1352 MTCH6301 Touch Driver Library 1056 MTCH6303 Touch Driver Library 1078 NVM Driver Library 645 PMP Driver Library 682 SD Card Driver Library 715 SPI Driver Library 744 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1460 SPI Flash Driver Library 771 SPI PIC32WK IPF Flash Driver Library 847 SQI Driver Library 882 SQI Flash Driver Library 918 Timer Driver Library 970 USART Driver Library 1295 WILC1000 Wi-Fi Driver Library 1386 WINC1500 Socket Mode Driver Library 1434 WINC1500 Wi-Fi Driver Library 1394 WM8904 Codec Driver Library 317 Using the USART Driver with DMA 1306 V Volume V: MPLAB Harmony Framework Reference 2 W WDRV_CLI_Init function 1401 WDRV_EXT_CmdChannelSet function 1415 WDRV_EXT_CmdConnect function 1410 WDRV_EXT_CmdConnectContextBssidGet function 1417 WDRV_EXT_CmdConnectContextChannelGet function 1362 WDRV_EXT_CmdDisconnect function 1411 WDRV_EXT_CmdFWUpdate function 1416 WDRV_EXT_CmdFWVersionGet function 1405 WDRV_EXT_CmdMacAddressGet function 1406 WDRV_EXT_CmdNetModeAPSet function 1411 WDRV_EXT_CmdNetModeBSSSet function 1411 WDRV_EXT_CmdNetModeIBSSSet function 1363 WDRV_EXT_CmdPowerSaveGet function 1362 WDRV_EXT_CmdPowerSavePut function 1407 WDRV_EXT_CmdScanGet function 1406 WDRV_EXT_CmdScanOptionSet function 1408 WDRV_EXT_CmdScanOptionsSet function 1418 WDRV_EXT_CmdScanStart function 1412 WDRV_EXT_CmdSecNoneSet function 1412 WDRV_EXT_CmdSecWEPSet function 1413 WDRV_EXT_CmdSecWPA2Set function 1364 WDRV_EXT_CmdSecWPASet function 1413 WDRV_EXT_CmdSecWpsSet function 1416 WDRV_EXT_CmdSSIDGet function 1407 WDRV_EXT_CmdSSIDSet function 1415, 1418 WDRV_EXT_CmdTxPowerSet function 1417 WDRV_EXT_DataSend function 1414 WDRV_EXT_Deinitialize function 1404 WDRV_EXT_HWInterruptHandler function 1408 WDRV_EXT_Initialize function 1364, 1365, 1420 WDRV_EXT_ModuleUpDown function 1409 WDRV_EXT_MulticastFilterSet function 1410 WDRV_EXT_PrivConfig function 1365 WDRV_EXT_RssiRead function 1421 WDRV_EXT_ScanDoneSet function 1414 WDRV_EXT_ScanIsInProgress function 1419 WDRV_EXT_ScanResultGet function 1363, 1405 WDRV_EXT_WPSResultsRead function 1421 WDRV_GPIO_DeInit function 1403 WDRV_GPIO_Init function 1360 WDRV_GPIO_PowerOff function 1360 WDRV_GPIO_PowerOn function 1360 WDRV_INTR_Deinit function 1402 WDRV_INTR_Init function 1402 WDRV_INTR_SourceDisable function 1419 WDRV_INTR_SourceEnable function 1420 WDRV_IsPowerOff function 1361 wdrv_mrf24wn_api.h 1382 WDRV_MRF24WN_ISR function 1361 wdrv_mrf24wn_iwpriv.h 1383 WDRV_SPI_Deinit function 1403 WDRV_SPI_In function 1359 WDRV_SPI_Init function 1403 WDRV_SPI_Out function 1359 WDRV_STUB_Assert function 1422 WDRV_STUB_GPIO_ChipDisable function 1422 WDRV_STUB_GPIO_ChipEnable function 1423 WDRV_STUB_GPIO_DeInitialize function 1423 WDRV_STUB_GPIO_Initialize function 1423 WDRV_STUB_GPIO_ModuleReset function 1424 WDRV_STUB_GPIO_ModuleUnreset function 1424 WDRV_STUB_HardDelay function 1425 WDRV_STUB_INTR_Deinit function 1425 WDRV_STUB_INTR_Init function 1426 WDRV_STUB_INTR_SourceDisable function 1426 WDRV_STUB_INTR_SourceEnable function 1427 WDRV_STUB_Print macro 1429 WDRV_STUB_SPI_Deinitialize function 1427 WDRV_STUB_SPI_In function 1427 WDRV_STUB_SPI_Initialize function 1428 WDRV_STUB_SPI_Out function 1428 wdrv_wilc1000_api.h 1392 wdrv_wilc1000_stub.h 1392 wdrv_winc1500_api.h 1430 WDRV_WINC1500_ISR function 1404 wdrv_winc1500_stub.h 1431 Wi-Fi Driver Libraries 1350 WILC1000 Wi-Fi Driver Ethernet Mode Library 1385 WINC1500 Firmware Update Utility 1441 WINC1500 Module Firmware Overview 1437 WINC1500 Socket Mode Driver Library 1432 WINC1500 Wi-Fi Driver Ethernet Mode Library 1393 WM8904 Codec Driver Library 316 Index © 2013-2017 Microchip Technology Inc. MPLAB Harmony v2.06 1461

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: =