|
Document API IEC60730 Library
|
Overview and documentation of IEC60730 library APIs. More...
Modules | |
| BIST | |
| Built In Self Test - Executed periodically. | |
| CPU Registers Check | |
| Verifies CPU registers are working correctly. | |
| IRQ Check | |
| Verifies interrupt frequency is within bounds. | |
| Invariable Memory Check | |
| Verifies contents of flash memory. | |
| OEM External Communications Example using UART | |
| Verifies communication channel is operating as expected. | |
| POST | |
| Power On Self Test - Executed once during power up. | |
| Program Counter Check | |
| Verifies all tests have completed on time. | |
| Safe State | |
| When incorrect behavior is detected, this state prevents further execution. | |
| System Clock Check | |
| Verifies that system clocks are within expected frequencies. | |
| Variable Memory Check | |
| Verifies RAM is working correctly. | |
| Watchdog Check | |
| Monitors CPU execution. | |
Overview and documentation of IEC60730 library APIs.
The IEC60730 library for EFR32 provides a basic implementation required to Support the requirements found in Table H.1 in the IEC60730 specification. It includes all the Power On Self Test (POST) functions executed when a device is first powered on, as well as Built In Self Test (BIST) functions that are called periodically to ensure correct operation. Certain portions of the requirements require a detailed understanding of The system is under development. Callback functions must be completed by the developer to guarantee meeting the full specification. These include a Safe State function used when validation detects an anomaly, properly implemented communications channels (redundancy, error detection, periodic communications), and Plausibility functions to validate system state (internal variables and inputs/outputs).
Copyright 2024 Silicon Laboratories Inc. www.silabs.com Source code in this repo is covered by one of several different licenses. The default license is the Master Software License Agreement (MSLA) MSLA, which applies unless otherwise noted.
During the unit test build process, some third-party code will be added to this repository and separated into another license. An example can be found in the build/_deps directory, where the Unity library uses the MIT license.
The final certificate and detailed report shall be provided for the specific devices.
Once OEMs have completed integrating their system with the IEC60730 Library, they will need to certify their device with a qualified certification house.
This library supports all EFR32MG devices listed in the Selector Guide.
The IEC60730 library dependencies:
Users could get dependency source files from the GSDK suite (platform). To get the latest version of GSDK, please refer to Gecko SDK.
Details on the validation test setup used internally by Silicon Labs can be found at IEC60730 Test Specification. Test results can be found inside each module.
Currently tested on Windows and Linux platforms.
To use Simplicity Studio to generate and build a demo IEC60730 and OEM Customization, refer to the IEC60730 Safety Library Integration Manual in the Doc folder for more details.
See OEM Customization for details on customizing the project and adding custom code.
Using Doxygen to generate HTML documentation, the documents will be generated in docs/html/EFR32_IEC60730_Libraries
Using MkDocs to support read mark-down files.
MkDocs User Guide:
MkDocs markdown fetaures and syntax reference:
Search for icons and Emojis:
*Step 1:** Install mkdocs
*Step 2:** Install mkdocs-material
*Step 3:** Install mkdocs-material-extensions
mkdocs.yml file in place./site, which will be added to your project. It will starting from the site/index.htmlRecommended version:
Run pre-commit install to install pre-commit into your git hooks. pre-commit will now run on every commit:
Staging files need formatting. For example:
Run pre-commit hooks on a repository to check coding convention.
The C compilers:
Tools specification
iec60730.slce file. For example, you want to use simplicity sdk version: This library consists of two main components. The POST component operates immediately after the power is turned on, validating the system state before entering the main execution loop.
The BIST component is executed periodically within the main execution loop.
Validation for IEC60730 also requires external communications validation. Each OEM application has unique external communication requirements. This library includes an example UART communications library that complies with IEC60730 standards. OEMs must adapt their communications to meet the requirements outlined in IEC60730.
The file oem_iec60730.c contains functions and variables that OEMs should modify to suit their specific systems.
This EFR32 IEC60730 library fulfills the requirements for a Class B device. Table 1 outlines the firmware requirements that must be met by controls, as specified in IEC60730, including new entries from Annex H.
Table 2 details the firmware-specific requirements for software-based controls, derived from Table H.1 in IEC60730.
| Information | Clause | Method [1] | Notes specific to this library [2] |
|---|---|---|---|
| 36 Limits of activating quantity | 11.3.2 H.11.4.15 H.17.14 H.18.1.5 H.27.1.1 H.28 | X | Not Applicable |
| 52 Minimum parameters of any heat dissipator | 14 | X | Not Applicable |
| 53 Type of output waveform if other than sinusoidal | H.25 | X | Not Applicable |
| 54 Details of the leakage current waveform produced after failure of the basic insulation | H.27 | X | Not Applicable |
| 55 Relevant parameters of electronic devices unlikely to fail | H.27 | X | Not Applicable |
| 56 Type of output waveform produced after failure of an electronic device | H.27 | X | Not Applicable |
| 57 The effect on controlled outputs after electronic circuit component failure | H.27 | X | To be provided by OEM |
| 58b The effect on controlled outputs after a failure to operate as a result of tests | H.26.2 H.26.15 | X | Not Applicable |
| 66 Software sequence documentation | H.11.12.2.9 | D | Covered by this documentation |
| 67 Program documentation | H.11.12.2.9 H.11.12.2.12 | D | Covered by this documentation |
| 68 Software fault analysis | H.11.12 H.27.1.1.4 | D | Covered by this documentation |
| 69 Software class(es) and structure | H.11.12.2 H.11.12.3 H.27.1.2.2.1 H.27.1.2.3.1 | D | Covered by this documentation |
| 70 Analytical measure and fault/error control techniques employed | H.11.12.1.2 | D | Covered by this documentation |
| 71 Software fault/error detection times for controls | H.2.17.10 | X | Provided by OEM timer ticks. Example uses 1 second. |
| 72 Control responses in case of detected fault/error | H.11.12.2.7 | X | Must be provided by OEM |
| 73 Controls subjected to a second fault analysis and declared condition as a result of the second fault | H.27.1.2.3 | X | Must be provided by OEM |
| 74. External load and emission control measures to be used for test purposes | H.23.1.1 | X | Not Applicable |
| 91 Fault reaction time | H.2.23.2 H.27.1.2.2.2 H.27.1.2.2.3 H.27.1.2.3.2 H.27.1.2.3.3 H.27.1.2.4.2 H.27.1.2.4.3 | X | Provided by OEM timer ticks. Example uses 1 second. |
| 92 Class or classes of control functions | H.6.18 H.27.1.2.2 H.27.1.2.3 | D | This library is for Class B control functions |
| 93 Maximum number of reset actions within a time period | H.11.12.4.3.6 H.11.12.4.3.4 | X | Not Applicable |
| 94 Number of remote reset actions | H.17.1.4.3 | X | Not Applicable |
| Component | Measure Used | Notes |
|---|---|---|
| 1.1 Registers | Periodic self-test using a Static memory test | Provided by library |
| 1.2 Instruction decoding and execution | None | Not required for Class B |
| 1.3 Program counter / Watchdog | Logical monitoring of the program sequence. Code execution sets flag that is periodically checked. Watchdog timer prevents runaway program execution. | Provided by library, see example for integration sample |
| 1.4 Addressing | None | Not required for Class B |
| 1.5 Data paths Instruction decoding | None | Not required for Class B |
| 2 Interrupt handling and execution | Time-slot monitoring(upper and lower limit) | Provided by library, see example for integration sample |
| 3 Clock | Reciprocal Comparison. Use separate oscillator to monitor SYSCLK - Calculate ratio and determine range based on accuracy | Provided by library, see example for integration sample |
| 4.1 Invariable memory | Periodic 16 bit CRC | Provided by library, see example for integration sample |
| 4.2 Variable memory | Periodic static memory test using March-C & stack guard. | Provided by library, see example for integration sample |
| 4.3 Addressing (variable and invariable memory) | 4.1 and 4.2 provide coverage for this component | |
| 5.1 Internal data path | 4.1 and 4.2 provide coverage for this component | |
| 5.2 Internal addressing | 4.1 and 4.2 provide coverage for this component | |
| 6 External Communication | Provided by OEM, UART example in library | |
| 6.1 External Communications - Data | 16 bit CRC | CRC check provided by library |
| 6.2 External Communications - Addressing | 16 bit CRC including the address | OEM must include in protocol proper address verification - see UART example in library |
| 6.3 External Communications - Timing (UART example) | Scheduled transmission | OEM must include in protocol proper timing measures - see UART example in library |
| 7 Input/output periphery / 7.1 Digital I/O | Plausibility check | Provided by OEM |
| 7.2 Analog I/O / 7.2.1 A/D and D/A converter | Plausibility check | Provided by OEM |
| IEC60730_ADC_PLAUSIBILTY_TEST 7.2.2 Analog multiplexer | Plausibility check | Provided by OEM |
| 8 Monitoring device and comparators | None | Not needed for class B |
| 9 Custom chips | None | Not Applicable |
Test Specifications provide detailed specifications for verification testing.
The IEC60730 library follows Silicon Labs Coding Standard.
Customers with support questions can begin with the Silicon Labs support page. Customers can also post their questions to the Silicon Labs Community Forums for help from other Silicon Labs customers.
If a customer needs help with a complex issue, create a Support Request on the support page. The Silicon Labs MCU Applications Engineering team will assist with duplicating the problem and understanding the root cause.
The IEC60730 library is a complex software project that will require ongoing support and updates in the future. This section outlines how Silicon Labs will assist customers with their implementation and release updates for the IEC60730 library.
Once an issue is confirmed to be a problem with the IEC60730 Library, a JIRA ticket must be filed within the Developer Services Team project (DS), starting with the prefix "IEC60730: ".The team lead will assess each issue and assign a severity level, which can be categorized as follows:
The issue ticket will be assigned to the Developer Services Team manager later. At their discretion, they may convene a meeting with the IEC60730 Change Control Board (comprising the DS team lead) to discuss the open JIRA tickets for the IEC60730 Library. After the meeting, Tickets on JIRA will be created and determine whether the issue ticket will be fixed or not. The status of each ticket JIRA will be updated accordingly, and work will be delegated to the appropriate firmware team members. Work will be conducted in a separate branch from the main branch within the Git Version Control System.
Once the updated firmware is complete, the developer will check it into the Silicon Labs Git version control system and create a Code Review JIRA ticket. A review developer will then examine the code to ensure compliance with the Coding Standard. If feasible, a Git Pull Request will be created between the two revisions of the source code. Any comments from the review developer will be logged in a Git branch of the IEC60730 project. The Git commit ID will be linked to the Code Review JIRA ticket. The developer is responsible for addressing the comments from the code review and providing explanations for any declined changes.
Following these steps, the version of the IEC60730 library will be incremented. For any issues resolved, an automated test will be created to replicate the previous issue and demonstrate that it no longer exists in the new library. The developer must also confirm that the Python code functions correctly when the original tests are executed.
If an issue cannot be validated through automated testing, a special waiver must be obtained from the Change Control Board, with instructions for manual testing included in the documentation for the affected module. A complete automated and manual validation cycle must be completed before the updated library is ready for release. This is done by initiating a Daily Firmware build job in the Jenkins build and test environment, using the Git branch as the source.
Once the Daily Firmware build job and any required manual tests confirm the correct operation of the firmware, the branch will be merged back into the master branch. A Release Build will then be triggered in Jenkins, using the new release version along with the master branch.
The MCU FW Team Manager must sign off on the validation results via JIRA. After the library passes validation, the updated library, along with a change list, will be submitted to the certification house for re-certification. Upon completion of re-certification, an Errata document will be created or updated to include a list of all resolved and unresolved issues, along with any available workarounds.
The new library, along with the Errata document and an updated Readme file containing the new version number, will be uploaded to the Silicon Labs downloads site and made available through Simplicity Studio.
An OEM must be aware of these items when integrating the IEC60730 library into their final product.
OEMs must customize the sl_iec60730_safe_state() function according to their system configuration. Safe State must configure any external signals and communications channels such that the system will not cause damage or unexpected operation. The function may attempt external notification, however it must be done cautiously to prevent further deterioration of the system.
sl_iec60730_post() is normally called after system initialization is complete, but before beginning primary operating mode. It includes a Watchdog test that resets the system to verify Watchdog operation. OEMs must expect initialization code before sl_iec60730_post() to execute twice. Initialization code execution time must be short enough that the watchdog can be refreshed in sl_iec60730_post() before expiration.
sl_iec60730_bist() is executed as part of the main system loop, typically at the end. Systems with long execution times will require manual watchdog refresh, and adjustment of sl_iec60730_test_clock_tick() frequency to ensure sl_iec60730_program_counter_test() passes, or calling sl_iec60730_bist() at multiple locations in the main system loop.
When in safety-critical code where POST and BIST are executing, interrupts should remain globally enabled. If interrupts must be disabled for a critical section of firmware, the critical section should follow best practices and be as short as possible. The time in the critical section must be shorter than the fastest clock timer interrupt (usually 10ms), or sl_iec60730_sys_clock_test_disable() must be used to disable the timer tests.
IEC60730_GPIO_COMPLETE and IEC60730_ANALOG_COMPLETE must be set by OEM validation code.
OEMs can use IEC60730_OEM0_COMPLETE - IEC60730_OEM7_COMPLETE or into sl_iec60730_program_counter_check to verify their own test algorithms are executing at least once per every call to sl_iec60730_program_counter_test(). Unused flags must be set to 1.
User should setup the internal watchdog as user's design expectation.
When in a long latency loop, use sl_iec60730_restart_watchdogs() to prevent a watchdog reset. Minimize the time in the loop as much as possible.
OEMs must update oem_irq_freq_bounds for their system use. Interrupt service routines must include code for incrementing oem_irq_exec_count. For an example, see oem_iec60730.c. OEMs must choose and enumerate the index values for oem_irq_exec_count.
OEMs can modify the default System Clock and Timer Clock configurations in oem_iec60730_timer.c according to their system requirements.
OEMs must modify the sl_iec60730_imc_test_region_t structure to align with their memory usage. iec60730_cur_crc or similar must be modified to store the CRC values. The number of areas to be tested depends on the OEM
During the CRC generation for a block of memory, the CPU is halted and unable to respond to interrupt requests.
For a typical system, the amount of invariable memory checked will determine the fault reaction time.
OEMs must modify the sl_iec60730_vmc_test_region_t structure to align with the RAM they want to check. The number of areas to be tested depends on the OEM.
During the CRC generation for a block of memory, the CPU is halted and unable to respond to interrupt requests.
OEMs must write their safety-related communications protocol according to the IEC60730 requirements. The demo provides an example protocol test for UART 0.
OEMs can implement additional safety checks and call sl_iec60730_safe_state() with custom define SL_IEC60730_OEM_FAIL_1 - SL_IEC60730_OEM_FAIL_4 settings.
The sizes given below are for the example programs demo provided by extension with the SDK.
OEM devices that do not use a communications channel(~400 bytes), or have simple plausilbity functions (~200 bytes), will use less space.
OEMs can use these numbers for planning purposes, but must verify against their implementation.
All tests must complete execution before sl_iec60730_program_counter_test() is called. The example code calls sl_iec60730_program_counter_test() once per second.
The test requiring the most iterations to complete is the Invariable Memory Check and Variable Memory Check . It may require calls to sl_iec60730_bist() to guarantee all the invariable memory areas and variable memory areas are checked before sl_iec60730_program_counter_test() is called. This table assumes the largest invariable memory size for each device, and a check across the whole memory area.
The number of blocks per BIST call SL_IEC60730_INVAR_BLOCKS_PER_BIST is chosen to get the time between BIST calls close to the watchdog timeout.
Number of sl_iec60730_bist() calls/second = Size of memory / (Size of CRC block * number of blocks per BIST call)
Maximum time between BIST calls= 1 / (Number of sl_iec60730_bist calls)
Checking against smaller areas increase the time between BIST calls.
The default Fault Reaction Time for the IEC60730 library is 1 second. Because of the BIST call frequency configuration above, a full invariable memory test can take 1 second to run on the largest memory EFR32 devices. The Program counter check runs once per second by default, and all completion bits must be set. OEMs can modify the Clock according to their needs to increase the Fault Reaction Time.
1.8.17