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-Driver Libraries Help MPLAB Harmony Integrated Software Framework-Manuel

Microchip- Driver Libraries Help MPLAB Harmony Integrated Software Framework - Manuel

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

Au format texte :

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