Added Diagnostics task files to project directory

Author: areiter128

dpsk4-vmc.X/sources/apps/diagnostics/_dox/Library_Usage_Guidelines.md

@@ -0,0 +1,75 @@
+# Library Usage Guidance {#diag-library-usage}
+
+This code library repository must be included in an independent directory within the target project. Changes to any of the files of this repository in the target project environment can be pushed back to this library repository from where these changes can be distributed to one, more or all target projects this library has been used in. The upgrade of library files in a particular target project needs to be performed individually, allowing to individually manage the device driver version used.
+
+### Adding Subtree Repository
+
+#### Step 1 - Adding Subtree Repository to Target Project
+
+##### a) Using Sourcetree Application
+
+Open *Sourcetree* Application
+
+- Open menu *Repository* → *Repository Settings*
+- Click *Add* to open the Add Repository dialog
+
+Inside the Repository dialog
+
+- Enter *Remote Name* `subrepo-diagnostics`
+- Enter clone URL/path https://bitbucket.microchip.com/scm/mcu16asmpsl/subrepo-diagnostics.git
+- Under *Optional extended integration* → *Remote Account* select your user account
+- Click *OK* to close the dialog
+
+##### b) Using Git Bash
+
+Open Git Bash at root of target project repository and use the following command for adding the new subtree remote:
+
+- `$ git remote add subrepo-diagnostics https://bitbucket.microchip.com/scm/mcu16asmpsl/subrepo-diagnostics.git`
+
+#### Step 2) Cloning Subtree Repository
+
+Further using Git Bash, use the `subtree add` command to clone the contents of this code library to the target project
+
+- `$ git subtree add --prefix=<code_library_target> subrepo-diagnostics main --squash`
+
+with `<code_library_target>` = path to sub-folder within the target project directory structure this code library should be cloned to (e.g. my_project.X/sources/apps/diagnostics/svc).
+
+#### 3) Pulling latest version from Library Repository
+
+When a new version of this code library is available, you can pull it by using the `subtree pull` command in the Git Bash:
+
+`$ git subtree pull --prefix=<code_library_target> subtree-diagnostics main --squash`
+
+with `<code_library_target>` = path to sub-folder within the target project directory structure this code library has been cloned to (e.g. my_project.X/sources/apps/diagnostics/svc).
+
+#### 4) Pushing new version back to Library Repository
+
+When changes have been made to files of this code library, the new version can be pushed back to the library repository by using the `subtree push` command in the Git Bash:
+
+`$ git subtree push --prefix=<code_library_target> subtree-diagnostics feature/version-update --squash`
+
+with `<code_library_target>` = path to sub-folder within the target project directory structure this code library has been cloned to (e.g. my_project.X/sources/apps/diagnostics/svc).
+
+<span style="color:red">
+
+    <u><b>Note:</b></u><br>
+    Pushing directly to the library project 'main' or 'develop' branches may be prohibited. 
+    Hence, <i><u><b>changes can only be pushed to feature branches</b></u></i>. A Pull Request is required to review and merge changes to 'develop'. Once changes have been approved and merged int 'develop', they may be merged into branch 'main' and thus released as new version through another pull request. This new version of 'main' can be tagged with a new version number and pulled into target projects.
+
+</span>
+
+<br>&nbsp;
+
+<a href="#diag-lib-startDoc">back</a>
+
+---
+
+<span id="diag-lib-history"><a name="diag-lib-history"></a></span>
+
+#### History
+
+- 03/13/2020 v1.0 (M91406) Initial release
+- 11/02/2020 v2.0 (M91406) Enhanced version with generic trap handler
+- 03/08/2021 v2.1 (M91406) Improved ENABLE bit handling keeping fault check executed but bypassing fault trip and recovery responses
+- 07/16/2021 v2.2 (M91406) Introduced global FaultMonitor object and encapsulated scan through fault objects in fault driver
+- 08/01/2022 v3.0 (M91406) Migrated the code to support multiple, user-defined fault monitor data object instances

dpsk4-vmc.X/sources/apps/diagnostics/_dox/diagnostics_description.md

@@ -0,0 +1,60 @@
+Diagnostics Layer {#diagnostics-description}
+=====================
+
+A Diagnostics Object represents a value of a special function register or global user variable, which will monitored and validated by the Diagnostics Library. The library supports different comparisons for validation, such as:
+
+- Greater Than
+- Less Than
+- Equal
+- Not Equal
+- Within Range
+- Out Of Range
+
+The Diagnostics Layer source values are either compared against a user-defined constant (static threshold), or another variable (dynamic threshold). The Diagnostics Layer further supports two thresholds, one defining the Diagnostics Event Trip Level and second is Diagnostics Event Recovery Level. Depending on the type of comparison selected, the range between both thresholds is either interpreted as hysteresis or range. (see @ref apps-layer-diag-lib "Diagnostics Library" for details)
+
+The fundamental mechanism of detecting diagnostics event conditions and creating trip and recovery responses is based on a simple, adjustable detection filter, which does not influence the monitored value but delays the response of the software. Depending on the type of value monitored, the firmware may need to react sooner or later while the diagnostics event detection sensitivity needs to be adjusted accordingly to prevent the power supply from unintended shut downs.
+
+The delay filter counts successive threshold violations, comparing the most recent counter value against an absolute, user-defined maximum. When one sample of the monitored value does *not* violate the given threshold, the counter is reset and starts incrementing from zero at the next threshold detection. When the monitored value remains violating the given threshold until the counter reaches or exceeds the defined maximum counter value, the power supply shut down event is triggered, turning off PWM outputs and control loops and resetting the state machine, waiting for the diagnostics event condition to disappear.
+
+<p>
+  <center>
+    \image html diagevt_trip.png width=540
+  </center>
+</p>
+<p><center><i>Diagnostics Event Detection</i></center></p>
+
+Recovering from a diagnostics event condition uses the same mechanism, but provides its individual set of parameters. Thus, diagnostics event trip responses can be adjusted to be aggressive while recovery events can be further delayed to prevent the end-product from falling into an undesired, high frequency shut-down/restart cycle.
+
+<p>
+  <center>
+    \image html diagevt_recovery.png width=540
+  </center>
+</p>
+<p><center><i>Diagnostics Event Recovery</i></center></p>
+
+#### The most recent firmware version supports the following diagnostics objects:
+
+- **Under Voltage Lock Out (UVLO)**
+  When the input voltage drops below the specified minimum voltage, the power supply is shut down, waiting for the input voltage to recover. If the power has been cut, the power supply will remain off until all capacitors are discharged and the microcontroller (MCU) shuts down. The PWM inputs of teh FET driver are pulled low until that point. The MCU drops out at voltages below 2.9V, which is below the UVLO level of teh FET driver. Hence, the gate drive signals remain pulled to off-state continuously without the chance to accidentally turn on.
+<br>
+- **Over Voltage Lock Out (UVLO)**
+  When the input voltage exceeds the specified absolute maximum value, the power supply is shut down. waiting for the input voltage to drop back into the specified range. Auxiliary power supply, feedback voltage dividers and the power FETs support input voltages of up to 20V above the specified maximum to allow proper tracking of the input voltage even under diagnostics event conditions.
+<br>
+- **Regulation Error (RegErr)**
+  This diagnostics object continuously monitors the deviation between output voltage and control reference. With a small deviation and a time delay, which allows normal voltage drops and overshoots during load transients, this diagnostics object is the last line of defense. Any diagnostics event condition which cannot be detected by the other diagnostics objects, such as internal short circuits, oscillating feedback loops or failing components, will inevitably result in larger deviations of the output voltage from the given reference and will lead to a protective shut down of the power supply.
+<br>
+
+#### Optional diagnostics objects:
+
+- **Over Current Protection (OCP)** *(optional)*
+  The over current protection requires a very fast response in comparison to voltage monitors. Hence, two successive threshold violations are enough to trip an over current diagnostics event condition, shutting down the power supply. As an over current diagnostics event condition disappears instantly when the power supply has been shut down, the recovery delay needs to be significantly expended to result in a decent diagnostics event response behavior of the end-product.
+<br>
+- **Over Temperature Warning (OTW)** *(optional)*
+  The over temperature warning is commonly triggered when the board or system temperature exceeds a threshold value, which is still within the safe operating area but is higher than under commonly expected conditions. The warning allows state machines to take counter measures (e.g. power derating, partial load drop) if possible helping to reduce power losses. In systems where active counter measures are not an option, communication with the load could prevent fatal system failures. However, any measures taken are highly application dependent and have to be implemented as proprietary user functions.
+<br>
+- **Over Temperature Protection (OTP)** *(optional)*
+  The over temperature protection is triggered when the board or system temperature exceeds a absolute maximum threshold value, at which the system has to be shut down to prevent permanent damage. It is recommended to include a wide hysteresis to allow the board to cool down significantly before initiating a restart attempt to prevent the power converter from ending up in a frequent shut-down/restart cycle.
+<br>
+
+---
+© 2024, Microchip Technology Inc.