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

Microchip- Development-Tools-Quick-Guide-to-Microchip-Development-Tools - Manuel

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

Au format texte :

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