Synergy Software Package User's Manual
Data Operation Circuit Driver

Table of Contents

DOC HAL Module Introduction

The Data Operation Circuit (DOC) HAL module provides a high-level API for DOC applications and uses the DOC peripherals on the Synergy MCU. A user-defined callback can be created to inform the CPU when an event occurs.

DOC HAL Module Features

The DOC HAL module peripheral is used to compare 16-bit data and can detect the following events:

  • A mismatch or match between data values
  • Overflow of an addition operation
  • Underflow of a subtraction operation
DOC_BD.png
DOC HAL Module Block Diagram

DOC Hardware support details

The following hardware features are, or are not, supported by SSP for DOC.

Legend:

Symbol Meaning
✓ Available (Tested)
⌧ Not Available (Not tested/not functional or both)
N/A Not supported by MCU 
MCU
Group 		Module-stop Function Event Link Function through ELC HAL Driver
S124 ✓ ⌧
S128 ✓ ⌧
S1JA ✓ ⌧
S3A1 ✓ ⌧
S3A3 ✓ ⌧
S3A6 ✓ ⌧
S3A7 ✓ ⌧
S5D3 ✓ ⌧
S5D5 ✓ ⌧
S5D9 ✓ ⌧
S7G2 ✓ ⌧

DOC HAL Module APIs Overview

The DOC HAL module defines APIs for opening, closing, checking the status of and writing data to the data operation circuit. The DOC HAL module uses the DOC peripheral on the Synergy MCU. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

DOC HAL Module API Summary

Function Name Example API Call and Description
open g_doc.p_api->open(g_doc.p_ctrl, g_doc.p_cfg)
Initial configuration.
close g_doc.p_api->close(g_doc.p_ctrl)
Allow the driver to be reconfigured. Will reduce power consumption.
statusGet g_doc.p_api->statusGet(g_doc.p_ctrl, &my_Status)
Get the DOC status and stores it in the provided pointer p_status.
statusClear g_doc.p_api->statusClear(g_doc.p_ctrl)
Clear DOPCF status flag.
write g_doc.p_api->write(g_doc.p_ctrl, value)
Write to the DODIR and DODSR registers.
inputRegisterWrite g_doc.p_api->inputRegisterWrite(g_doc.p_ctrl, &doc_values)
Write to the DODIR register.
versionGet g_doc.p_api->versionGet(g_doc.p_ctrl, &version)
Retrieve the API version with the version pointer.
Note
For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name Description
SSP_SUCCESS DOC successfully configured.
SSP_ERR_IN_USE Module already open.
SSP_ERR_ASSERTION One or more pointers point to NULL.
SSP_ERR_INVALID_ARGUMENT ISR is not enabled. Enable the ISR in bsp_irq_cfg.h.
SSP_ERR_HW_LOCKED DOC resource is locked.
SSP_ERR_NOT_OPEN Driver not open.
Note
Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

DOC HAL Module Operational Overview

The DOC HAL module controls the DOC peripheral on a Synergy MCU. It is used to compare 16-bit data and can detect a mismatch between data values, an overflow of an addition value, or an underflow of a subtraction operation. If a callback is available and the associated interrupt is enabled, the callback function will be called in response to a DOC event.

The DOC uses two data registers to perform operations: the DOC Data Input Register (DOCDIR) holds the data to be operated on and the DOC Data Setting Register (DOCDSR) holds the value that is used to operate on the input data. In the addition and subtraction modes, this register stores the results of data operations. (Both these registers are 16-bits wide.)

DOC HAL Module Important Operational Notes and Limitations

DOC HAL Module Operational Notes

The initial setting of comparison data is written to the DOC by calling the doc_api_t::write API. The doc_api_t::write API writes to the DOC DODSR and DODIR registers. The doc_api_t::write API use a variable of type doc_data_t, as illustrated below:

     doc_data_t g_doc_values;

   g_doc_values.dodir = 0x1000;

   g_doc_values.dodsr = 0x1000;

   g_doc.p_api->write(g_doc.p_ctrl, &g_doc_values);

If the data to be compared does not change, there is no need to re-write it each time a comparison is required. The input data value can be written to the DOC by using the doc_api_t::inputRegisterWrite API. The doc_api_t::inputRegisterWrite API writes only to the DOC data-input register.

DOC HAL Module Limitations

Refer to the latest SSP Release Notes for any additional operational limitations for this module.

Including the DOC HAL Module in an Application

This section describes how to include the DOC HAL Module in an application using the SSP configurator.

Note
This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the DOC Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the DOC Driver is g_doc0. This name can be changed in the associated Properties window.)

DOC HAL Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_doc0 Data Operation Circuit Driver on r_doc Threads New Stack> Driver> Monitoring> Data Operation Circuit Driver on r_doc

When the Key Matrix Driver on r_kint is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

DOC_MS.png
DOC HAL Module Stack

Configuring the DOC HAL Module

The DOC HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note
You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the DOC HAL Module on r_doc

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enable or disable the parameter error checking.
Name g_doc0 Module name.
Event Comparison mismatch, Comparison match, Addition overflow, Subtraction underflow

Default: Comparison mismatch 		Specify the event which will trigger the DOC interrupt.
Callback NULL A user callback function can be registered in open. If this callback function is provided, it is called from the interrupt service routine (ISR) when the configured DOC event occurs. 

Warning: Since the callback is called from an ISR, care should be taken not to use blocking calls or lengthy processing. Spending excessive time in an ISR can affect the responsiveness of the system.
DOC Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Disabled 		Use the pull down to set the DOC interrupt priority.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

DOC HAL Module Clock Configuration

The DOC HAL module does not require a specific clock configuration.

DOC HAL Module Pin Configuration

The DOC HAL module does not require and specific pin configurations.

Using the DOC HAL Module in an Application

The typical steps in using the DOC HAL module in an application are:

  1. Initialize the DOC using the doc_api_t::open API.
  2. Set register values in DODIR and DODSR using the doc_api_t::write API.
  3. Steam data to the DOC using the doc_api_t::inputRegisterWrite API.
  4. Read the status of the comparison using the doc_api_t::statusGet API or in the callback if enabled.
  5. Clear status flags using the doc_api_t::statusClear API.
  6. Close the module using the doc_api_t::close API.

These common steps are illustrated in a typical operational flow diagram in the following figure:

DOC_TA.png
Flow Diagram of a Typical DOC HAL Module Application