User Guide Openecu Developer Platform C-API Release 3.0.3-FS (R2019-3)

User Guide OpenECU Developer Platform C-API Release 3.0.3-FS (r2019-3)

Foreword ...... xi 1. Disclaimer ...... xi 2. Health and Safety information ...... xi 1. Introduction ...... 1 1.1. Included in your OpenECU kit ...... 1 1.1.1. Hardware ...... 2 1.1.2. Software ...... 2 1.2. Licensed Features ...... 2 1.3. OpenECU requirements ...... 3 1.3.1. Hardware requirements ...... 3 1.3.2. Software requirements ...... 3 1.3.3. Assumed knowledge ...... 3 1.4. Co-operational development with Pi ...... 4 1.5. Warnings and safety guidelines ...... 4 1.5.1. Verification of OpenECU by Pi Innovo ...... 5 1.6. Warning ...... 6 1.6.1. Personal safety ...... 6 1.6.2. Disclaimer ...... 6 2. Installation ...... 7 2.1. Introduction ...... 7 2.1.1. Third party tool requirements ...... 7 2.1.2. Third party tool requirements — C-API ...... 7 2.1.3. Third party tool requirements — Simulink-API ...... 8 2.1.4. Third party tool requirements — installation ...... 9 2.1.5. Third party tool requirements — compatibility ...... 10 2.2. Installing OpenECU ...... 11 2.3. License setup ...... 17 2.3.1. Floating license ...... 17 2.3.2. Node-locked license ...... 19 2.4. Removing OpenECU ...... 19 2.5. Integration notes for third party tools ...... 20 2.5.1. Microsoft Windows 10 ...... 20 2.5.2. Microsoft Windows 7 ...... 20 2.5.3. Microsoft Windows XP ...... 21 2.5.4. PiSnoop ...... 21 2.5.5. ATI Vision ...... 21 2.5.6. ETAS INCA calibration tool ...... 22 2.5.7. Vector CANape ...... 22 2.5.8. Wind River (Diab) C Compiler v5.5.1.0 ...... 22 2.5.9. Wind River (Diab) C Compiler v5.8.0.0 ...... 24 2.5.10. Wind River (Diab) C Compiler v5.9.0.0 ...... 25 2.5.11. Wind River (Diab) C Compiler v5.9.4.8 ...... 25 2.5.12. GCC Compiler v4.7.3 ...... 26 2.5.13. Python ...... 27 3. Quick start ...... 28 3.1. Introduction ...... 28 3.2. Installed examples ...... 28 3.3. Exercise — Step 1 ...... 28 3.3.1. Designing the application ...... 30 3.3.2. Create the application ...... 30 3.3.3. Review the application ...... 30 3.3.4. Implement the sensor reading ...... 32 3.3.5. Implement the sensor conversion to temperature ...... 33 3.3.6. Implement the threshold comparison ...... 36 3.3.7. Implement the lamp driver ...... 36

3.3.8. Summary so far ...... 37 3.3.9. Create data dictionary and interface specification files ...... 39 3.3.10. Building the application ...... 41 3.3.11. Program the ECU ...... 42 3.3.12. Play with the application ...... 44 4. Software overview ...... 46 4.1. Introduction ...... 46 4.2. System components ...... 46 4.3. System modes ...... 48 4.4. Boot mode ...... 48 4.5. Reprogramming mode ...... 49 4.6. Application mode ...... 54 4.6.1. Building an application ...... 55 4.6.2. Interface specification ...... 58 4.6.3. Data dictionary and engineering unit files ...... 58 4.6.4. Application and library tasks ...... 58 4.6.5. Library status and error handling ...... 61 4.6.6. Compiler library support ...... 61 4.6.7. Deprecated library features ...... 62 4.6.8. Examples ...... 62 5. Library interface ...... 65 5.1. Introduction ...... 67 5.1.1. Name-spaces, naming conventions and library composition ...... 67 5.1.2. File locations ...... 68 5.1.3. Layout of each feature section ...... 69 5.1.4. Notations ...... 69 5.2. System feature (PSY) ...... 70 5.2.1. Overview ...... 70 5.2.2. System types ...... 70 5.2.3. Error log ...... 70 5.2.4. Interface index ...... 71 5.2.5. Interface detail ...... 75 5.3. System start-up and background processing (PSC) ...... 84 5.3.1. Overview ...... 84 5.3.2. Interface index ...... 87 5.3.3. Interface detail ...... 90 5.4. ECU registry information (PREG) ...... 109 5.4.1. Overview ...... 109 5.4.2. Interface index ...... 110 5.4.3. Interface detail ...... 111 5.5. System timing feature (PTM) ...... 118 5.5.1. Overview ...... 118 5.5.2. Interface index ...... 118 5.5.3. Interface detail ...... 119 5.6. Task scheduling (PKN) ...... 124 5.6.1. Tasking model ...... 125 5.6.2. Interface index ...... 129 5.6.3. Interface detail ...... 130 5.7. Library input and output configuration (PIO) ...... 137 5.7.1. Overview ...... 137 5.8. Feature for specific target configuration (PCFG) ...... 138 5.8.1. Overview ...... 138 5.8.2. M110, M220 and M461 targets ...... 139 5.8.3. M250 target ...... 139 5.8.4. M460 target ...... 139 5.8.5. M670 target ...... 139 5.8.6. Interface index ...... 139 5.8.7. Interface detail ...... 140

5.9. Analogue input/output feature (PAX) ...... 147 5.9.1. Overview ...... 147 5.9.2. Interface index ...... 151 5.9.3. Interface detail ...... 152 5.10. Digital input/output feature (PDX) ...... 160 5.10.1. Overview ...... 160 5.10.2. Interface index ...... 169 5.10.3. Interface detail ...... 171 5.11. Digital data feature (PDD) ...... 197 5.11.1. Overview ...... 197 5.11.2. Interface index ...... 197 5.11.3. Interface detail ...... 198 5.12. Output driver control feature (PSS) ...... 200 5.12.1. Overview ...... 200 5.12.2. M220 target ...... 201 5.12.3. M250 target ...... 201 5.12.4. M460 target ...... 202 5.12.5. M461 target ...... 203 5.12.6. M670 target ...... 203 5.12.7. Interface index ...... 203 5.12.8. Interface detail ...... 204 5.13. Serial peripheral feature (PSP) ...... 205 5.13.1. Overview ...... 205 5.13.2. Input and output processing ...... 205 5.13.3. Interface index ...... 206 5.13.4. Interface detail ...... 206 5.14. CJ125 device driver for UEGO measurement feature (PCJ125) ...... 207 5.14.1. Overview ...... 207 5.14.2. Initialisation ...... 207 5.14.3. Diagnostics ...... 207 5.14.4. Interface index ...... 207 5.14.5. Interface detail ...... 208 5.15. CAN messaging feature (PCX) ...... 210 5.15.1. Overview ...... 210 5.15.2. Initialisation ...... 210 5.15.3. Receiving messages ...... 210 5.15.4. Transmitting messages ...... 211 5.15.5. CAN status ...... 212 5.15.6. CAN buses ...... 212 5.15.7. Build time buffer sizing ...... 212 5.15.8. Library tasks ...... 212 5.15.9. Interface index ...... 212 5.15.10. Interface detail ...... 213 5.16. CAN Calibration Protocol (CCP) messaging feature (PCP) ...... 224 5.16.1. Overview ...... 224 5.16.2. Interface index ...... 229 5.16.3. Interface detail ...... 230 5.17. J1939 (SAE) messaging feature (PJ1939) ...... 235 5.17.1. Overview ...... 235 5.17.2. Node addressing ...... 235 5.17.3. Messaging ...... 236 5.17.4. Message bit and byte numbering ...... 237 5.17.5. PGNs ...... 238 5.17.6. Receive messages ...... 238 5.17.7. Transmit messages ...... 239 5.17.8. Core Diagnostic messages ...... 239 5.17.9. Build time buffer sizing ...... 239 5.17.10. Library tasks ...... 240

5.17.11. Interface index ...... 240 5.17.12. Interface detail ...... 245 5.18. Diagnostic Trouble Code (DTC) feature (PDTC) ...... 280 5.18.1. Overview ...... 280 5.18.2. Diagnostic trouble codes — generic ...... 281 5.18.3. Diagnostic trouble codes — J1939 ...... 281 5.18.4. Storage of data across power cycles ...... 282 5.18.5. Build time buffer sizing ...... 282 5.18.6. Interface index ...... 283 5.18.7. Interface detail ...... 284 5.19. Adaptive non-volatile memory feature (PNV) ...... 293 5.19.1. Overview ...... 293 5.19.2. Storage of data across power cycles ...... 295 5.19.3. Interface index ...... 296 5.19.4. Interface detail ...... 298 5.20. Non-volatile Filesystem feature (PFS) ...... 307 5.20.1. Overview ...... 307 5.20.2. Interface index ...... 308 5.20.3. Interface detail ...... 310 5.21. On-board external flash (PEF) ...... 320 5.21.1. Overview ...... 320 5.21.2. Interface index ...... 321 5.21.3. Interface detail ...... 321 5.22. General utilities feature (PUT) ...... 326 5.22.1. Overview ...... 326 5.22.2. Interface index ...... 328 5.22.3. Interface detail ...... 331 5.23. Angular function feature (PAN) ...... 366 5.23.1. Overview ...... 366 5.23.2. Interface index ...... 379 5.23.3. Interface detail ...... 384 5.24. Waveform properties (PROP) ...... 438 5.24.1. Overview ...... 438 5.24.2. Interface index ...... 438 5.24.3. Interface detail ...... 439 6. Extended Diagnostics Functions ...... 444 6.1. Introduction to Diagnostics ...... 444 6.2. Diagnostic Legislation ...... 445 6.3. Approach ...... 447 6.4. Diagnostic Trouble Codes and Freeze-Frames ...... 448 6.5. Diagnostic Monitors, Tests and Performance Ratios ...... 449 6.6. Worked Example - building a diagnostic system ...... 450 6.6.1. Step 1 — Test Conditions at the Monitor level ...... 450 6.6.2. Step 2 — Individual Flow Tests ...... 451 6.6.3. J1979/ISO 15031 Scan tool request/response ...... 452 6.7. Extended Diagnostic Functions ...... 454 6.7.1. J1939 Extended Diagnostics feature (PJ1939) ...... 454 6.7.2. Diagnostics (ISO-15765 and KWP2000) feature (PDG) ...... 511 6.7.3. Diagnostic Trouble Code Extended (DTC) feature (PDTC) ...... 532 6.7.4. Freeze Frame feature (PFF) ...... 564 6.7.5. Parameter Identifier feature (PPID) ...... 567 6.7.6. In-Use Performance Ratio feature (PPR) ...... 580 7. Support tools ...... 599 7.1. Interface and DDE tool ...... 599 7.1.1. Simple interface file example ...... 599 7.1.2. Running the interface tool ...... 601 7.1.3. Warning and error messages ...... 609 7.1.4. Interface file contents ...... 610

7.1.5. DDE specification ...... 647 7.1.6. Units file ...... 653 7.1.7. Automatic ASAP2 entries ...... 653 7.1.8. OpenECU software versioning ...... 661 7.2. Supporting build scripts ...... 662 7.2.1. Creating a binary image with a supported compiler ...... 663 A. Reference documentation ...... 665 A.1. ECU hardware reference documentation ...... 665 B. OpenECU error and warning codes ...... 666 B.1. Interface tool messages ...... 666 B.1.1. Command line option messages ...... 666 B.1.2. File handling messages ...... 669 B.1.3. Interface file messages ...... 670 B.1.4. DDE processing messages ...... 671 B.1.5. Automatic DDE generation messages ...... 687 B.1.6. Code generation messages ...... 688 B.1.7. ASAP2 generation messages ...... 702 B.1.8. ELF to DDE generation messages ...... 706 B.1.9. Data type checks between ELF and DDE messages ...... 706 C. Supporting tools ...... 707 C.1. Introduction ...... 707 C.2. PiSnoop ...... 707 C.2.1. Example Screenshots ...... 708 C.3. ATI Vision ...... 709 C.3.1. Creating a new project and strategy in ATI Vision ...... 709 C.3.2. Downloading an application with an ATI Vision strategy ...... 716 C.3.3. Configuring two OpenECUs on the same CAN bus with ATI Vision ... 721 C.3.4. Configuring CCP seed/key security with ATI Vision ...... 724 C.4. ETAS INCA ...... 724 C.5. Vector CANape ...... 734 C.5.1. Configuring CCP seed/key security with Vector CANape ...... 741 C.6. FreeCCP ...... 742 C.6.1. Programming an OpenECU ...... 742 C.6.2. Choosing the CAN card device (Kvaser) ...... 742 C.6.3. Choosing the CAN card device (Vector) ...... 742 C.6.4. Choosing the CCP settings ...... 743 C.6.5. Checking that the OpenECU device is active ...... 743 D. Memory configurations ...... 744 E. ASAP2 compliance ...... 746 F. CCP compliance ...... 747 F.1. EXCHANGE_ID message handling ...... 748 G. CCP troubleshooting guide ...... 751 G.1. Anatomy of an ATI Hub ...... 751 G.2. No communication between PC and ATI Hub ...... 752 G.2.1. Symptoms ...... 752 G.2.2. Possible causes ...... 752 G.3. No communication between PC and OpenECU ...... 753 G.3.1. Symptoms ...... 753 G.3.2. Possible causes ...... 753 H. Crank wheel signal decoding ...... 758 H.1. Variable reluctance signal ...... 758 H.2. Hall-effect signal ...... 759 H.3. Tooth edge processing ...... 759 H.4. Crank decoding states ...... 762 I. Change log ...... 769 I.1...... 769 J. Glossary of terms ...... 773 K. Contact information ...... 775

3.1. Quick start loom ...... 29 3.2. Transfer function for temperature sensor ...... 33 4.1. System components ...... 46 4.2. System modes ...... 48 4.3. System modes for M220, M250, M460 and M461 ...... 51 4.4. System modes for M110, M221, M560, M680 and M670 ...... 52 4.5. System initialisation ...... 54 4.6. Building an application (in outline) ...... 56 5.1. Tasking model states ...... 125 5.2. Task pre-emption ...... 126 5.3. Task pre-emption with resource locking ...... 128 5.4. TLE8242-2 Dither ...... 148 5.5. TLE8242-2 constant current control diagram ...... 149 5.6. TLE8242-2 KP and KI equations ...... 150 5.7. Direct and indirect analogue outputs ...... 150 5.8. Quadrature encoder and generated signals ...... 162 5.9. Direction of encoder and generated signals ...... 162 5.10. Pulse count example ...... 163 5.11. SENT frame ...... 163 5.12. Peak-hold injector output ...... 166 5.13. Output of H-Bridge during mode transition ...... 168 5.14. Signal update rates ...... 168 5.15. CAN bit sample point ...... 210 5.16. ASAM MCD-MC1 interaction ...... 225 5.17. CCP messaging ...... 225 5.18. J1939 activation state machine ...... 281 5.19. Map look-up ...... 326 5.20. Map look-up with interpolation ...... 327 5.21. Definition of 0° crank (VR sensor input) ...... 367 5.22. Definition of 0° crank (Hall-effect sensor input) ...... 367 5.23. TDC-firing events relative to 0° crank ...... 368 5.24. Task execution relative to cylinder's TDC-firing event ...... 368 5.25. Analogue inputs sampled relative to angular model iteration ...... 368 5.26. Multiple injection pulses ...... 371 5.27. Injection constraints ...... 372 5.28. Main injection event ...... 373 5.29. Injector pulse duration is composed of dead time and flow time ...... 373 5.30. Clipped injection event ...... 373 5.31. Injection events in 360° mode ...... 374 5.32. Post injection events ...... 374 5.33. Spark event relative to cylinder's TDC-firing angle ...... 375 5.34. Output pulse - Angle-Time Duration (turn-on/turn-off) ...... 376 5.35. Output pulse - Angle-Time Duration (turn-on/no-action) ...... 376 5.36. Output pulse - Angle-Angle Duration (turn-off/toggle) ...... 376 5.37. Output pulse - Angle-Angle Duration (turn-on/turn-off) ...... 376 5.38. Output data updated during an event, end modification allowed ...... 377 5.39. Output data updated during an event, end modification not allowed ...... 378 5.40. Output event with overlap between two events ...... 378 5.41. Output event starting within minimum off time ...... 379 6.1. Functional Levels within a Diagnostics System ...... 445 6.2. Scan tool link via Platform ...... 448 6.3. Routine control usage flowchart ...... 515 6.4. Platform OBD state machine — no transitions between Previously Active and Pending ...... 533

6.5. Platform OBD state machine — transitions between Previously Active and Pending ...... 534 6.6. ISO DTC state machine — no transitions from Inactive to Pending ...... 536 6.7. ISO DTC state machine — transitions from Inactive to Pending ...... 536 7.1. Building the interface code ...... 601 7.2. Finishing a build ...... 662 7.3. Building the binary images ...... 663

2.1. Third party tool compatibility ...... 10 2.2. Install components ...... 13 3.1. FEPS voltages ...... 44 4.1. FEPS voltages ...... 53 4.2. CCP defaults ...... 54 4.3. Library and application tasks ...... 58 5.1. Library composition ...... 67 5.2. Interval notation ...... 70 5.3. Registry entries ...... 110 5.4. DTC initialisation values ...... 282 5.5. Pin actions...... 379 6.1. Diagnostic Service Comparisons ...... 446 6.2. PDG supported services ...... 452 6.3. PDG supported services ...... 512 6.4. DTC initialisation values ...... 537 7.1. CCP privilege levels ...... 620 7.2. UDS DTCFormatIdentifier options ...... 625 7.3. Value ranges for J1939 name statements ...... 630 7.4. Value ranges for J1939 PDUs ...... 630 7.5. Value ranges for J1939 PDUs ...... 636 7.6. Bit information for the lamps to be set per DTC ...... 637 7.7. Bit information per lamp type ...... 638 7.8. Data dictionary columns (prefix-style) ...... 648 7.9. Variable naming convention (prefix-style) ...... 649 7.10. 1-d map lookup naming convention (prefix-style) ...... 650 7.11. 2-d map lookup naming convention (prefix-style) ...... 650 7.12. Data dictionary columns (C-style) ...... 650 7.13. Classes of DDE ...... 652 7.14. Examples of C-style DDE names ...... 652 7.15. Automatic ASAP2 entries for boot build information ...... 654 7.16. Automatic ASAP2 entries for reprogramming build information (M220, M221, M250, M460, M461, M550, M670) ...... 654 7.17. Automatic ASAP2 entries for platform build information ...... 655 7.18. Automatic ASAP2 entries for application build information ...... 656 7.19. Automatic ASAP2 entries for application rate task timing information ...... 656 7.20. Automatic ASAP2 entries for auxiliary task timing information ...... 657 7.21. Automatic ASAP2 entries for CPU loading information ...... 657 7.22. Automatic ASAP2 entries for eTPU loading information ...... 658 7.23. Automatic ASAP2 entries for maximum application rate task timing information ... 658 7.24. Automatic ASAP2 entries for run-time information ...... 658 7.25. Automatic ASAP2 entries for reset information (M110, M220, M250, M460, M461) ...... 659 7.26. Automatic ASAP2 entries for number of instances of period overruns or skips of periodic tasks ...... 659 7.27. Automatic ASAP2 entries for memory use information ...... 659 7.28. Automatic ASAP2 entries for memory error correction events ...... 659 7.29. Automatic ASAP2 entries for floating point conditions ...... 660 7.30. Automatic ASAP2 entries for J1939 related information ...... 661 7.31. Software component versions (for M560-000) ...... 661 D.1. Memory configurations supported ...... 744 D.2. Memory configurations supported ...... 744 D.3. Memory configurations supported ...... 745 F.1. Supported CCP commands ...... 747 F.2. Supported CCP commands (in older versions of ECUs) ...... 748 F.3. Original EXCHANGE_ID message ...... 748

F.4. Modified EXCHANGE_ID message ...... 748 F.5. EXCHANGE_ID selection values ...... 749 F.6. EXCHANGE_ID manufacturing data key values and binary format ...... 749 I.1. Release summary for v3.0.3-r2019-3 ...... 769

Before using OpenECU, it is very important to read and understand the warning and safety information given in Section 1.5, “Warnings and safety guidelines” and in Section 1.6, “Warning”.

Pi, the Pi logo and OpenECU are trademarks of Pi Innovo Ltd. Microsoft, Windows, Excel, Word, Vision, CANape and INCA are all registered trademarks of their respective owners. 1. Disclaimer

Pi Innovo makes no representation or warranties of any kind whatsoever with respect to the contents hereof, and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Pi Innovo shall not be liable for any errors contained herein, or for incidental or consequential damages in connection with the furnishing, performance or use of the software, associated hardware, or this written material.

Pi Innovo reserves the right to revise this publication from time to time, and to make changes in the content hereof without obligation to notify any person of such revision or changes.

A copy of the Pi Innovo Terms and Conditions of Sale is available on request, and includes a declaration of the warranty and limitation of liability which apply to all Pi Innovo products and services. 2. Health and Safety information

Under the terms of European and UK Health and Safety Legislation, Pi Innovo is required to classify any hazardous materials in the products it supplies and to provide relevant safety information to users.

Any hazardous materials in Pi products are clearly marked with appropriate symbols. Product Safety Data Sheets relating to these materials are available on request.

1.1. Included in your OpenECU kit ...... 1 1.1.1. Hardware ...... 2 1.1.2. Software ...... 2 1.2. Licensed Features ...... 2 1.3. OpenECU requirements ...... 3 1.3.1. Hardware requirements ...... 3 1.3.2. Software requirements ...... 3 1.3.3. Assumed knowledge ...... 3 1.4. Co-operational development with Pi ...... 4 1.5. Warnings and safety guidelines ...... 4 1.5.1. Verification of OpenECU by Pi Innovo ...... 5 1.6. Warning ...... 6 1.6.1. Personal safety ...... 6 1.6.2. Disclaimer ...... 6

Thank you for choosing Pi Innovo's OpenECU platform.

Pi Innovo's OpenECU platform offers a new solution to engine and vehicle control system development. Based on Pi's extensive experience of ECU development, and backed by Pi's unrivalled capabilities in project and customer support, OpenECU helps you get quickly to what you need: working, robust control systems.

By using production ECU hardware as an auto-code platform, you gain all the advantages of auto-coding and rapid prototyping, but with hardware that meets full production environmental and packaging requirements (see Section A.1, “ECU hardware reference documentation” for environmental and packaging details).

The OpenECU system consists of:

• a range of production ECU hardware modules for engines with up to 8 cylinders (or more with multiple modules);

• an optional range of tested engine and vehicle control strategies, from individual functional blocks to complete strategy suites;

• a comprehensive range of support and consultancy services, ranging from sensor selection and system design advice through to complete bespoke system development.

Applications of the OpenECU platform include:

• engine control system development;

• chassis control system development;

• after treatment control system development;

• transmission control system development;

• hybrid powertrain control system development;

• vehicle fleet trials.

For support contact information, please see the last page of this manual. 1.1. Included in your OpenECU kit

There are several OpenECU packages available from Pi, which can include the following items.

1.1.1. Hardware

The following items of hardware are available as part of OpenECU:

Electronic Control Unit (ECU) This is the computer that monitors and controls all aspects of the electronic system's behaviour. The built file from your application is programmed into the ECU. There are four different models of ECU currently available — 4 in-line cylinder and V8 cylinder, in both development and fleet models (see Section A.1, “ECU hardware reference documentation” for further details).

Connectors All the connectors and terminals required to connect the ECU, the calibration tool and your PC together.

Tools You will require an appropriate crimping tool for the ECU connectors. Pi Innovo will give you details on request. 1.1.2. Software

The following items of software are available as part of OpenECU:

OpenECU C Application Programming Interface (API) A documented C-API to the OpenECU library which allows control of the ECU from an application. The C-API broadly provides the same functionality as the OpenECU Simulink blockset.

And the following items of software are required but not provided as part of OpenECU.

Calibration Tool This electronic tool is used to program the auto-generated code into the ECU, and to monitor (and, in some cases, alter) the values of certain parameters while the ECU is running. Pi's own PiSnoop product is one option, along with several industry-standard alternatives, and we will be able to recommend a suitable product on request.

Compiler A tool which takes application code and turns it into an executable image that can be run on OpenECU hardware. 1.2. Licensed Features

OpenECU allows for several different options enabling different features. The licensing system retains control of the ability to use these features depending on what the customer has purchased.

The current set of available features is:

• OPENECU

The main feature. Enabled when you purchase any version of OpenECU

• CAPI_BUILD

Allows for building OpenECU applications with the C-API.

• EXT_DIAG

Extended diagnostics features.

• Allows use of the Extended diagnostics blockset in Simulink models.

• Allows use of the Extended diagnostics library functions at run time in OpenECU applications

See Chapter 6, Extended Diagnostics Functions. 1.3. OpenECU requirements

To make the best use of OpenECU, certain hardware, software and knowledge requirements need to be fulfilled, as described below. 1.3.1. Hardware requirements

To run the Pi OpenECU software, you will need an IBM-compatible PC with the specifications listed below.

• CPU: a modern Intel or AMD x86 32-bit or 64-bit processor. • RAM: 2 GiB minimum, but more recommended (larger applications will require more RAM). • Free hard disk space: 2 GiB. • Peripheral hardware: keyboard, mouse, DVD/CD-ROM drive (for installation from CD media), at least 8-bit graphics adapter and display (for at least 256 colours).

Either the physical system or a system simulator, is ultimately required to test and calibrate your ECU and the system model you have created to run on it. A suitable Calibration/ reprogramming communications tool is also required conforming to the ASAP2 standard. 1.3.2. Software requirements

You will need the following software pre-installed on your PC:

• Operating system: Microsoft Windows 10 or Microsoft Windows7 SP1 32-bit or 64-bit.

• Wind River Diab compiler; version 5.5.1.0 (M220, M221, M250, M460 and M461); or version 5.8.0.0 (M220, M221, M250, M460 and M461); or version 5.9.0.0 (M220, M221, M250, M460, M461, and M670); or version 5.9.4.8 (M560 and M580). Only the C language version is required (note, C++ is not yet supported).

• Calibration tool: PiSnoop, ATI Vision™ (version 2.5 through 5.1.2), ETAS INCA (version 5.1.2 through 7.2.7) or Vector CANape (version 8.0 through 16.0).

Note

OpenECU developer software does not support earlier versions of Windows than XP (SP3), Windows Vista, or Windows 8.

See the Chapter 2, Installation for full details of the software required. 1.3.3. Assumed knowledge

This manual describes how to use the C-API to create your own designs, but does not include a tutorial about C or embedded systems.

A working knowledge of design modelling and system dynamics principles in an engineering environment is required to make the best use of OpenECU. Ultimately, it is the quality of your own system designs that will be reflected in the quality of your system control strategy.

Note also that there are serious hardware and personal safety considerations involved in developing automotive control systems. Please make sure that you read and understand the notes given in Section 1.5, “Warnings and safety guidelines” to reduce the chance of any such hazards. 1.4. Co-operational development with Pi

Pi Innovo has over 14 years of experience designing powertrain controllers, working closely with customers to get to the best possible control system solution. Millions of cars and trucks on the road use Pi-designed engine control.

OpenECU comes with a wide range of options for customer and project support, allowing you to draw on over 500 man-years of control system design experience. Whichever option you choose, you can count on real commitment from Pi to provide what you need, and to go the extra mile.

For contact information, refer to Appendix K, Contact information. 1.5. Warnings and safety guidelines

It is very important to read and understand the following warnings and safety guidelines. Inappropriate use of the OpenECU system can lead to loss of data, damage to software and hardware, and possible personal injury if safe vehicle operation is compromised.

The safe operation of OpenECU is the responsibility of the those using it. The level of risk associated with the user's application must be ascertained and appropriate mitigation devices used to reduce the potential risks to an acceptable level. These mitigation devices may include a system 'kill switch', driver training, backup systems and use of the vehicle in safe environments.

A structured approach to testing is recommended, particularly before the product is used in environments where it may be in contact with members of the public (e.g. the public highway). This testing may include HIL, static vehicle system test and/or vehicle test in a test track environment.

Pi Innovo supplies OpenECU on the basis that:

• The responsibility for ensuring that the use of OpenECU is safe lies with the customer.

• The customer will include appropriate mitigation devices as identified by the hazard analysis they perform (such as engine kill switch, back up devices).

• All users must be competent to make appropriate safety judgements.

• The user will read all OpenECU documentation (including this document) to ensure its safe use.

• Use of OpenECU in a safety-related system must conform to the Safety Manual for the specific controller hardware.

• OpenECU software has been developed according to ISO 26262 to support functional safety and can provide a basis for achieving compliance according to ISO 26262 for selected Hardware and Software versions. Talk to us about how this can fit into your functional safety system.

Pi Innovo also strongly recommends that:

• Applications be developed using a process suitable for the application.

• HIL testing be used prior vehicle testing.

• "Off public highway" vehicle testing be performed prior to road testing. 1.5.1. Verification of OpenECU by Pi Innovo

Pi Innovo considers the safety and quality of its products to be of paramount importance. The integrity of the product can be considered by assessing the three 'components' which comprise the system.

Systems, rather than software, have a Safety Integrity Level (SIL). The SIL of the customer's resultant system will have to be assessed and defined by their knowledge of the processes used to develop all the components (including those supplied by Pi) comprising the complete system. 1.5.1.1. Hardware

The hardware is a production unit (see Section A.1, “ECU hardware reference documentation” for module environmental specifications). However different applications will have different requirements for output monitoring. Those outputs that are selected (by the customer) to drive safety related outputs should include output monitor circuits. The use of outputs for critical devices which do not contain a monitor feedback is strongly discouraged. 1.5.1.2. Platform

The platform comprises functionality which allows the high level strategy to operate in the specific hardware target (electronic box). It includes:

• The operating system (RTOS) to schedule tasks, process interrupts and manage the internal stack etc..

• The hardware drivers enabling the inputs to be read, and the outputs driven.

• The calibration tool support, CAN support and module reprogramming.

OpenECU has been developed using a lean SIL0 process enabling its rapid introduction to the market place. This process included internal review, module testing and considerable vehicle testing. It is considered to be a reliable and robust platform on which to build vehicle control applications.

The configuration of the platform is the customer's responsibility. It is entirely possible, through careless configuration, to 'cross wire' inputs or outputs for example. This could, for example, lead to injector 1 firing when you intended injector 2 to fire. The mis-calibration of analogue inputs could lead to undesired behaviour such as steering angle or accelerator pedal position to be mis-calculated.

Documented vehicle prove out tests should mitigate against this leading to severe outcomes. 1.5.1.3. Strategy

The strategy may be developed entirely by the customer, or be a development by the customer of generic libraries supplied by Pi Innovo. In either case the integrity of the resultant strategy model must be the responsibility of the customer.

Pi's generic libraries have been extensively validated via module testing, HIL system testing and vehicle testing but have not undergone unit testing.

1.6. Warning

The supplied libraries have been validated for a specific application and a specific hardware set. The user MUST validate the correct function of the strategies in their application. 1.6.1. Personal safety

The process of testing automotive systems can involve many personal safety hazards — high-speed machinery, extremely flammable and potentially explosive fuels, and the possibility of loss of vehicle control is a combination that can be fatal if sensible precautions are not followed.

As the system designer and tester, it is your responsibility to ensure that your working practices are specifically designed to minimise or eliminate the possibility of personal injury, and to incorporate into your designs such fail-safe functionality as is necessary. This includes the avoidance of certain dynamical situations such as open throttles and other 'positive feedback' scenarios where control of the system may be lost. 1.6.2. Disclaimer

Pi Innovo reserves the right to revise this publication from time to time, and to make changes in the content hereof without obligation to notify any person of such revision or changes.

2.1. Introduction ...... 7 2.1.1. Third party tool requirements ...... 7 2.1.2. Third party tool requirements — C-API ...... 7 2.1.3. Third party tool requirements — Simulink-API ...... 8 2.1.4. Third party tool requirements — installation ...... 9 2.1.5. Third party tool requirements — compatibility ...... 10 2.2. Installing OpenECU ...... 11 2.3. License setup ...... 17 2.3.1. Floating license ...... 17 2.3.2. Node-locked license ...... 19 2.4. Removing OpenECU ...... 19 2.5. Integration notes for third party tools ...... 20 2.5.1. Microsoft Windows 10 ...... 20 2.5.2. Microsoft Windows 7 ...... 20 2.5.3. Microsoft Windows XP ...... 21 2.5.4. PiSnoop ...... 21 2.5.5. ATI Vision ...... 21 2.5.6. ETAS INCA calibration tool ...... 22 2.5.7. Vector CANape ...... 22 2.5.8. Wind River (Diab) C Compiler v5.5.1.0 ...... 22 2.5.9. Wind River (Diab) C Compiler v5.8.0.0 ...... 24 2.5.10. Wind River (Diab) C Compiler v5.9.0.0 ...... 25 2.5.11. Wind River (Diab) C Compiler v5.9.4.8 ...... 25 2.5.12. GCC Compiler v4.7.3 ...... 26 2.5.13. Python ...... 27 2.1. Introduction

This chapter describes the installation process for the OpenECU C-API package and its dependencies. 2.1.1. Third party tool requirements

OpenECU developer software has been tested to work with Windows 10. OpenECU is compatible with Windows 7 SP1 (32-bit and 64-bit) and Windows XP SP3, but support for these operating systems is deprecated. OpenECU is not compatible with Windows Vista or Windows 8. 2.1.2. Third party tool requirements — C-API

For C based development, OpenECU requires (at a minimum) one of the following compiler tools:

• Wind River Diab compiler

• GCC Compiler

Note

GCC is an optional component in the OpenECU installation (installed by default). Additionally, GCC support is currently in a beta stage. As such, there a number of

known limitations for compiling an OpenECU application with GCC. Please see the “Integration notes for third party tools” of the “Release notes” for a list of known issues building with GCC for further details.

To program and calibrate an OpenECU with an application, OpenECU integrates with the following calibration tools. Only one calibration tool is required:

• PiSnoop

• ATI VISION

• ETAS INCA

• Vector CANape 2.1.3. Third party tool requirements — Simulink-API

For Simulink model based development, OpenECU requires (at a minimum) the following MathWorks tools:

• MATLAB (base product)

• Simulink (to develop the models)

• Simulink Coder (to generate C code from the models)

• MATLAB Coder (Simulink Coder depends on this)

In addition, if you need to add state diagrams to the model, then you will also need:

• Stateflow (to develop state flow diagrams inside your model) Simulink Coder generates C code from the state flow diagrams inside your model.

Simulink Coder generates C code which does not lend itself to efficient repeatable testing. When creating a production version of your product, you may need better control of the structure of the C code generated from the model to reduce the cost of testing the C code against any industry standards. Under these circumstances you will also need:

• Embedded Coder (to generate C code from the models)

To compile the generated C code (from either Simulink Coder or Embedded Coder), you will need one of the following compilers:

• Wind River Diab compiler

• GCC compiler (free compiler but with known issues)

To program and calibrate an OpenECU with an application, OpenECU integrates with the following calibration tools. Only one calibration tool is required:

• PiSnoop

• ATI VISION

• ETAS INCA

• Vector CANape

2.1.4. Third party tool requirements — installation

OpenECU works with a number of applications (both required and optional) supplied by other companies. If you intend to use OpenECU with one of the following tools, it is best to install them before OpenECU. The installer will then integrate the OpenECU developer software with these applications.

• MATLAB versions:

32-bit: R2013a, R2013b, R2014a, R2014b, R2015a, R2015b 64-bit: R2013b, R2014a, R2014b, R2015a, R2015b, R2016a, R2016b, R2017a, R2017b, R2018a, R2018b

• ETAS INCA calibration tool (version 7.2)

OpenECU works with a number of other applications, but these need not be installed prior to the OpenECU developer software.

• Simulink Coder, formerly Real-Time Workshop, (optional) versions:

32-bit: R2013a, R2013b, R2014a, R2014b, R2015a, R2015b 64-bit: R2013b, R2014a, R2014b, R2015a, R2015b, R2016a, R2016b, R2017a, R2017b, R2018a, R2018b

• Embedded Coder, formerly Real-Time Workshop Embedded Coder, (optional) versions:

32-bit: R2013a, R2013b, R2014a, R2014b, R2015a, R2015b 64-bit: R2013b, R2014a, R2014b, R2015a, R2015b, R2016a, R2016b, R2017a, R2017b, R2018a, R2018b

• Stateflow versions:

32-bit: R2013a, R2013b, R2014a, R2014b, R2015a, R2015b 64-bit: R2013b, R2014a, R2014b, R2015a, R2015b, R2016a, R2016b, R2017a, R2017b, R2018a, R2018b

• Wind River (Diab) C compiler (versions 5.5.1.0, 5.8.0.0 and 5.9.0.0) for M110, M220, M221, M250, M460 and M461 targets

• Wind River (Diab) C compiler (version 5.9.0.0) for M670 targets

• Wind River (Diab) C compiler (version 5.9.4.8) for M560 and 580 targets

• GCC Compiler (version 4.7.3 free compiler option) for M110, M220, M250, M460, M461 and M670 targets

Note

GCC is an optional component in the OpenECU installation (installed by default)

• PiSnoop (any version)

• ATI Vision calibration tool (version 2.5 through 4.0)

• Vector CANape calibration tool (version 8.0 through 13.0)

The applications above have been listed with a version or release number. These are the versions or releases that OpenECU has been tested against. It may be that OpenECU will

work with other versions of these applications, but it is recommended against and Pi may not provide technical support if these versions or releases are not used. 2.1.5. Third party tool requirements — compatibility

In summary, the following third party tools are compatible with this version of OpenECU:

Table 2.1. Third party tool compatibility

Third party tool Compatible versions Operating systems Microsoft Windows a Win10 (64-bit) Win7 SP1 (32-bit) (deprecated) Win7 SP1 (64-bit) (deprecated) XP SP3 (32-bit) (deprecated) Modelling and code generation tools MathWorks MATLAB R2013a, R2013b, R2014a, R2014b, R2015a, R2015b (32-bit) R2013b, R2014a, R2014b, R2015a, R2015b, R2016a, R2016b, MathWorks Simulink R2017a, R2017b, R2018a, R2018b (64-bit) MathWorks MATLAB Coder MathWorks Simulink Coder b MathWorks Embedded Coder Compiler tools c Wind River Diab C compiler v5.5.1.0, v5.8.0.0, v5.9.0.0 for M110, M220, M221, M250, M460 and M461 targets v5.9.0.0 for M670 target v5.9.4.8 for M560 and M580 target GCC Compiler d v4.7.3 for M110, M220, M250, M460, M461 and M670 targets Reprogramming, data logging and calibration tools e PiSnoop Any version ATI Vision f g v2.5 through v5.1.2 ETAS INCA v7.2.7 Vector CANape v8.0 through v16.0 a OpenECU developer software has been tested to work with Windows 10. OpenECU is compatible with Windows 7 SP1 (32- bit and 64-bit) and Windows XP SP3, but support for these operating systems is deprecated. OpenECU is not compatible with Windows Vista or Windows 8.

OpenECU developer software may not function correctly on encrypted drives. OpenECU developer software must be able to create files on the host file system. If using an encrypted drive, be sure that permission settings will allow OpenECU to create files. Pi Innovo cannot provide support for issues with encrypted drives. b Mathworks Simulink Coder includes functionality of RTW and Stateflow Coder. c All OpenECU targets use Freescale PowerPC microcontrollers. The M110, M220, M221, M250, M460 and M461 use an MPC5534 microcontroller, the M670 uses an MPC5674F microcontroller. The M560 and M580 use an MPC5746C for the primary microcontroller and SPC560P34 for the secondary microcontroller.

See the Technicical Specification for your target for more information. d OpenECU has only been tested using GCC Compiler version 4.7.3 and is in the beta stage. As such, there are a number of known issues to keep in mind when compiling an OpenECU application using GCC. For further details, please see "Integration notes for third party tools" for a list of known issues. e These tools have been tested for reprogramming, data logging, and calibration. Some of them have many other features which have not been tested with OpenECU. f The OpenECU method of configuring ATI Vision uses standardised ASAP2 files. As a result, all future versions of Vision are expected to be backwardly compatible (e.g., version 3.7 and version 4.0 are known to be compatible). g The following Vision toolkits are typically used when working with OpenECU: Data Acquisition Toolkit, Calibration Toolkit, Universal ECU Interface Standard Toolkit, APOLLO Data Analysis Toolkit, CAN Interface Toolkit and HORIZON Scripting/Remote

API Toolkit. In particular, the HORIZON Scripting/Remote API Toolkit is required if OpenECU builds are to generate Vision strategy files (.vst).

Some third party tools have been marked deprecated and support for these tools will be removed in a future release of OpenECU.

Third party tool Replacement MathWorks MATLAB R2013a MATLAB latest version (see Pi Innovo's website [http://www.pi- innovo.com/support-center/compatibility] for a complete list of MathWorks MATLAB R2013b supported versions of MATLAB). MathWorks MATLAB R2014a MathWorks MATLAB R2014b WindRiver Diab 5.5.1.0 WindRiver Diab 5.8.0 and 5.9.0 2.2. Installing OpenECU

The installer program, openecu_platform_3_0_3_FS_r2019-3.exe, installs all the necessary files for the OpenECU platform. This file can be obtained from the Pi Document and Download Center web page [http://www.pi-innovo.com/downloads].

The installation process for the OpenECU developer software is performed by a wizard. To run the wizard, execute the appropriate installer program. The installation can be stopped at any point by selecting the Cancel button.

The installer requires that the user has administrative rights to make changes on the computer. If a user without rights is trying to execute the installer a dialog box will be displayed and the installation stops. Login with an administrator account or contact your network administrator and try again.

If a version of an OpenECU installer is already running, a dialog box will appear saying so. Select OK (which stops the current installer) and change to the other OpenECU installer to continue.

The installation process starts with an introduction. Select Next to continue.

The next windows to appear present the license agreement for using OpenECU developer software and related software. Read the license agreements and if acceptable, select I accept the terms of the License Agreement and then Next. If not acceptable, do not install the software.

The next window to appear provides a number of components that can be installed or patched.

The following table breaks out each of the components: Table 2.2. Install components Component Required Installed Description by default Platform Yes Yes A selection of packages to install, including the C-API and Sim-API components. OpenECU Yes Yes Install the Simulink interface to OpenECU, Sim-API documentation and support packages. Blockset Yes Yes Install the OpenECU blockset.

Component Required Installed Description by default Sim-API (optional) Yes Install the OpenECU blockset, ECU Technical Manuals Specifications and other documentation in (HTML) HTML format. Sim-API (optional) Yes Install the OpenECU blockset, ECU Technical Manuals Specifications and other documentation in PDF (PDF) format. Sim-API (optional) Yes Install some examples of how to use the Examples OpenECU blockset. OpenECU C- Yes Yes Install the OpenECU C-API files and libraries. API C-API Yes Yes Install the C interface to OpenECU, documentation and support packages. C-API (optional) Yes Install the OpenECU C-API User Guide, Manuals ECU Technical Specifications and other (HTML) documentation in HTML format. C-API (optional) Yes Install the OpenECU C-API User Guide, Manuals ECU Technical Specifications and other (PDF) documentation in PDF format. C-API (optional) Yes Install some examples of how to use the Examples OpenECU C interface. Extended (optional) No Install the On-Board Diagnostic (OBD) library. Diagnostics This library is available at extra cost. Features Python Yes Yes Install the Python application. This application is used to provide build support when generating and compiling the model source code. Tools (optional) No Installs additional OpenECU tools. GCC (optional) Yes Installs the GNU Compiler Collection (v4.7.3) and related tools for OpenECU targets. lmadmin (optional) No Installs the installers for the lmadmin license installer server from flexera. FreeCCP (optional) No Installs the FreeCCP programming tool (note that this tool is provided without support or warranty). Integration (optional) Yes Options to have the OpenECU installer integrate OpenECU with third party tools, like MATLAB and INCA. MATLAB (optional) Yes During installation, the OpenECU blockset is Integration integrated into MATLAB's PATH. INCA-ProF (optional) No During installation, INCA-ProF is update to Integration understand how to program an OpenECU. Start Menu (optional) Yes During installation, the Window's Start menu Shortcuts is updated to include shortcuts to installed components.

Adjust the component selection as required (especially if you require the installer to update an installed copy of ETAS INCA) and select the Next button.

The next window asks for a destination path to be specified. By default, the installer presents a path to your local drive.

Warning

If the default path is changed, ensure that only digits, upper and lower case letters and the _ character are used to specify directory names. An installation path that includes any space characters will cause problems later on.

If the INCA-ProF integration component was selected, the next window presented provides a list of installed versions of INCA.

Select which versions of INCA will be used with OpenECU and select the Next button. If no version should be updated select None.

Note

If any version of INCA is selected, then the installer will add OpenECU integration to all versions of INCA. This is simply a consequence of the way INCA works.

If no versions of INCA were found, the next window presents details on how to achieve this by hand (more details given in Section 2.5.6, “ETAS INCA calibration tool”). The instructions should be carried out when INCA-ProF runs.

If the Start Menu Shortcuts component was selected, then the next window presented asks the user to select where in the Start menu the OpenECU items will be added. During install, the installer adds short cuts to the documentation components selected and to the OpenECU uninstall application.

Once installation has completed, the user is provided an option to read the getting started guide, the release notes and to visit the OpenECU web site.

Getting started guide

If you are a first time user of OpenECU, it is strongly recommend following the getting started guide, which covers what tools can be used with OpenECU and how to configure OpenECU and those tools to work together.

Release notes

If you are installing a new version of OpenECU, it is strongly recommended that you read the release notes. Some releases of OpenECU change the functionality of features which may have an impact on existing applications. 2.3. License setup

Machine identification generated by the license tools is required to activate an OpenECU platform license.

This section is a quick setup guide to get OpenECU working with your license. Consult the license administration guide for more information on license management and administration. This document is provided with the installation at "[install path]\doc_user \License-Administration-Guide.pdf". 2.3.1. Floating license

To setup a floating license, the vender daemon will have to be run on the designated license server as well as have a license file on that machine. This section describes setting up the vendor daemon for a floating license. 2.3.1.1. Server

• After installing the platform, copy the files in "[install path]\tools\flexera\i86_n3\" to your designated license server. On that machine, run lmtools.exe.

• Select the "System Settings tab", check "Include Domain", and press the button that says "Save HOSTID Info to a File".

• It is recommended that lmadmin license server manager be used to serve licenses. Run the lmadmin installer to install the software. Once the installation is complete, copy the vender daemon, openecu.exe, into the install directory, "C:\Program Files (x86)\FlexNet Publisher License Server Manager\".

• Start the license server manager. You can then use the web interface to upload the license file and start serving your license.

Note

If a license has not yet been purchased, email the file to Pi Innovo with the purchase order. When the purchase is complete, Pi will send a valid license file. If the purchace has already been completed, reply to the welcome email with this information.

• It is recommended that lmadmin license server manager be used to serve licenses. Run the lmadmin installer and start the license server manager. The web interface can then be used to upload the license file and start serving your license.

Note

Details on installing and using the lmadmin tool are in Chapter 9 of the License Administration Guide, "[install path]\doc_user\License-Administration-Guide.pdf".

Note

lmgrd is also provided with the platform as an alternative to lmadmin; consult Chapter 10 of the License Administration guide for details on its use.

2.3.1.2. Client

• On the user development machine, set the environment variable OPENECU_LICENSE_FILE to @to tell the OpenECU platform to look for a floating license from the license server. 2.3.2. Node-locked license

To setup a node-locked license, a license file must be placed on the development machine.

• After installing the platform, run the file: '[install path]\tools\flexera\i86_n3\lmtools.exe'

• Select the "System Settings tab", check "Include Domain", and Press the button that says "Save HOSTID Info to a File" (see screen shot above)

• Email the file to Pi Innovo with the purchase order. When the purchase is complete, Pi will send you a valid license file. (Or if you have already completed the purchase, reply to the welcome email with this information) If a license has not yet been purchased, email the file to Pi Innovo with the purchase order. When the purchase is complete, Pi will send a valid license file. If the purchace has already been completed, reply to the welcome email with this information.

• Copy the file to the directory "C:\openecu" or update the OPENECU_LICENSE_FILE environment variable with the location of your file. 2.4. Removing OpenECU

Navigate through the Windows All Programs Start Menu shortcuts and find the OpenECU Developer Software directory. Select the version of OpenECU to remove and run the uninstaller.

The uninstaller requires that the user has administrative rights to make changes on the computer. If a user without rights is trying to execute the uninstaller a dialog box will be displayed and the uninstaller stops. Login with an administrator account or contact your network administrator and try again.

If a version of an OpenECU uninstaller is already running, a dialog box will appear saying so. Select OK and change to the other OpenECU uninstaller to continue.

The uninstaller presents the location of the previous install to remove. Select the Uninstall button to continue (this will remove that version of OpenECU) or select the Cancel button to stop the uninstall.

Note

The OpenECU uninstaller does not remove the INCA-ProF configuration files for CCP.

2.5. Integration notes for third party tools 2.5.1. Microsoft Windows 10 2.5.1.1. Integration

The installer integrates the OpenECU package with Windows 10 by modifying the Start menu, by modifying some registry items and by copying files to a local drive. 2.5.1.2. Known defects/issues

The installer integrates the OpenECU package with Windows 7 SP1 by modifying the Start menu, by modifying some registry items and by copying files to a local drive. 2.5.2.2. Known defects/issues

OpenECU developer software may not function correctly on encrypted drives. OpenECU developer software must be able to create files on the host file system. If using an encrypted

drive, be sure that permission settings will allow OpenECU to create files. Pi Innovo cannot provide support for issues with encrypted drives. 2.5.3. Microsoft Windows XP 2.5.3.1. Integration

The installer integrates the OpenECU package with Windows XP SP3 by modifying the Start menu, by modifying some registry items and by copying files to a local drive. 2.5.3.2. Known defects/issues

Unlike some other calibration tools, during installation there is nothing special to be done when integrating PiSnoop and OpenECU. 2.5.4.2. Known defects/issues

None. 2.5.5. ATI Vision 2.5.5.1. Integration

Unlike some other calibration tools, during installation there is nothing special to be done when integrating Vision and OpenECU. 2.5.5.2. Known defects/issues

• Open: integration issues with OpenECU while creating a Vision VST (strategy) file.

There have been integration issues between Vision and OpenECU, when the user requests a build create a Vision VST (strategy) file. If OpenECU cannot create a strategy file, then it may be necessary to register the COM interface for Vision by running the RegisterCOMInterface.bat file included in the install of ATI Vision.

• Open: does not operate correctly with encrypted hard drives.

There have been reports of Vision interacting poorly with encrypted hard drives. At the moment, it is not clear what the problem might be. On one occasion, Pi worked with ATI and a customer and determined a work around that is not understood. The work around was to rename the executable file for Vision to something longer than 11 characters.

• Open: some earlier versions do not support CCP seed/key correctly.

ATI Vision 2006 (v3.2) is the earliest version for which CCP seed/key security has been validated by Pi Innovo. Earlier versions may support CCP seed/key security (see the relevant Vision documentation) but bugs in the CCP implementation on various targets are known to exist. ATI have recommended that earlier versions should not be used, or should be used with caution.

2.5.6. ETAS INCA calibration tool 2.5.6.1. Integration

The installer integrates the OpenECU package with the ETAS INCA tool. However, if for any reason the installer could not find an installed version of INCA, the user can manually integrate the necessary ProF component.

The INCA-ProF tool programs OpenECU over CCP using a set of configuration files. In order to manually integrate these configuration files, the user must run INCA, open an experiment, select manage memory then flash programming.

The user is then presented with a dialog box to browse ProF configurations, or a ProF settings dialog box (in which case the user must select Configure...).

With the browse ProF configurations dialog box, select the "Install..." button and browse to the install location of OpenECU:

[install path]\tools_integration\inca_prof

and select OK. This will have manually installed the INCA-ProF configuration file for OpenECU.

Note

If manually integrating and the ProF files cannot be found in the location above, then re- run the OpenECU installer and select the Integration -> INCA-ProF Integration option and try again.

2.5.6.2. Known defects/issues

None. 2.5.7. Vector CANape 2.5.7.1. Integration

Unlike some other calibration tools, during installation there is nothing special to be done when integrating CANape and OpenECU. 2.5.7.2. Known defects/issues

None. 2.5.8. Wind River (Diab) C Compiler v5.5.1.0 2.5.8.1. Installation

The Wind River (Diab) compiler 5.5.1.0 can be installed by running the file setup.exe from the supplied media — several options will be presented during the compiler install and the following responses should be used:

• On Choose your Activation Type window, select one of the following options:

• Permanent activation if you have been assigned with a license file from Wind River, usually named WRSLicence.lic. The full path should point to the license file.

• Temporary activation if you wish to use the Wind River (Diab) compiler on an evaluation basis, or temporary basis until a permanent license is provided. • A reboot may be required to complete installation of the Wind River (Diab) compiler. • If using one version of the Wind River (Diab) compiler, either setup the OPENECU_DIAB_5_5_1_0 environment variable as described in the next point, or adjust Window's system path to include the absolute path to the compiler's bin directory. • If using more than one version of the Wind River (Diab) compiler (for instance, when you are using two or more versions of OpenECU which require different versions of the Wind River (Diab) compiler), the environment variable OPENECU_DIAB_5_5_1_0 must be set to the absolute path to the compiler's bin directory. This macro must terminate in a “\” and must use the DOS 8.3 short naming convention.

E.g., D:\Progra~1\diab\5_5_1_0\win32\bin\ 2.5.8.2. Known defects

• Closed: incorrect generation of object code for “float <= float” comparisons.

The compiler incorrectly generates object code for “float <= float” comparisons, turning the comparison into “float > float”. This issue has been resolved by removing the - Xieee754-pedantic command line option to the compiler command line option to the build configuration files.

• Open: incorrect generation of object code for long C functions.

The compiler incorrectly generates jump instructions in the object code if the jump destination address differs from the address of the jump instruction by more than 15 bits (signed). No warning or error is generated by the compiler. The result is a model which does not behave as expected when run on target (usually the ECU appears as if it is continually resetting).

Workaround (C-API): Break up large functions into small sub-functions.

• Open: generation of non-existent labels.

The compiler can generate non-existent labels such as ".L1013" when compiling code involving large structures, such as those generated by TargetLink. The code then fails to link because the labels are not defined. This has not yet been seen with Simulink builds but it may possibly be seen in future.

Workaround: if this problem is encountered, a patched version of the compiler is available from Wind River for customers who have compiler support (quote service request 1054126).

• Open: incorrect rounding on conversion from float to integer types.

The compiler rounds values when converting from floating point to integer, e.g. from "float" to "signed long" (in terms of native types, otherwise known as F32 and S32 in the OpenECU environment). For example, 3.6 as a float is rounded to 4 as an integer, but the C standard requires that the fractional part is truncated, so a converted value of 3 would be correct. Similarly -3.6 is rounded to -4 instead of being truncated to -3. This defect is fixed in version 5.8.0.0 of the compiler.

Workaround: if this problem is encountered, a patched version of the compiler is available from Wind River for customers who have compiler support (quote service request 864470). 2.5.8.3. Known issues

• Closed: Can't use Simulink look up blocks

There has been a known issue which restricts the compiler to use Simulink lookup block. When using Simulink lookup blocks, the Diab compiler would stop compilation with this error message:

'[model-name].c', line [line-num]: warning (dcc:1792): trying to assign 'ptr to volatile' to 'ptr'

This has now been fixed, see F-CR 13325 in the release notes.

• Closed: compiling the main model file can take a long time.

Small models compile in a short period of time, but once the code presented to the compiler exceeds a limit, the compiler takes a long time to compile the main model file (model- name.c).

Workaround: the compiler sets aside an amount of memory for the compilation phase and if the size of the model code exceeds the limit, the compilation slows down. This can be avoided by increasing the size of the compiler's buffer using a command line option. Add the pcomp_CompileOptions block to the model, set the mode parameter to Add to options and set the compiler options parameter to -Xparse-size=100000. If the compilation is still slow, increase the option value further. 2.5.9. Wind River (Diab) C Compiler v5.8.0.0 2.5.9.1. Installation

The Wind River (Diab) compiler 5.8.0.0 can be installed by running the file setup.exe from the supplied media — several options will be presented during the compiler install and the following responses should be used:

• Follow the guidance given in Section 2.5.8, “Wind River (Diab) C Compiler v5.5.1.0”. • If using a single version of the Wind River (Diab) compiler, either setup the OPENECU_DIAB_5_8 environment variable as described in the next point, or adjust Window's system path to include the absolute path to the compiler's bin directory. • If using multiple versions of the Wind River (Diab) compiler (for instance, when you are using two or more versions of OpenECU which require different versions of the Wind River (Diab) compiler), the environment variable OPENECU_DIAB_5_8 must be set to the absolute path to the compiler's bin directory. This macro must terminate in a “\” and must use the DOS 8.3 short naming convention.

E.g., D:\Progra~1\diab\5_8_0_0\win32\bin\ 2.5.9.2. Known defects

None identified. 2.5.9.3. Known issues

• Closed: Can't use Simulink look up blocks

There has been a known issue which restricts the compiler to use Simulink lookup block. When using Simulink lookup blocks, the Diab compiler would stop compilation with this error message:

'[model-name].c', line [line-num]: warning (dcc:1792): trying to assign 'ptr to volatile' to 'ptr'

This has now been fixed, see F-CR 13325 in the release notes.

2.5.10. Wind River (Diab) C Compiler v5.9.0.0 2.5.10.1. Installation

The Wind River (Diab) compiler 5.9.0.0 can be installed by running the file setup.exe from the supplied media — several options will be presented during the compiler install and the following responses should be used:

• Follow the guidance given in Section 2.5.8, “Wind River (Diab) C Compiler v5.5.1.0”. • If using a single version of the Wind River (Diab) compiler, either setup the OPENECU_DIAB_5_9 environment variable as described in the next point, or adjust Window's system path to include the absolute path to the compiler's bin directory. • If using multiple versions of the Wind River (Diab) compiler (for instance, when you are using two or more versions of OpenECU which require different versions of the Wind River (Diab) compiler), the environment variable OPENECU_DIAB_5_9 must be set to the absolute path to the compiler's bin directory. This macro must terminate in a “\” and must use the DOS 8.3 short naming convention.

E.g., D:\Progra~1\diab\5_9_0_0\win32\bin\ 2.5.10.2. Known defects

None identified. 2.5.10.3. Known issues

• Closed: Can't use Simulink look up blocks

There has been a known issue which restricts the compiler to use Simulink lookup block. When using Simulink lookup blocks, the Diab compiler would stop compilation with this error message:

'[model-name].c', line [line-num]: warning (dcc:1792): trying to assign 'ptr to volatile' to 'ptr'

This has now been fixed, see F-CR 13325 in the release notes.

• Open: Error message 0169

The Diab 5.9.0.0 compiler generates object files that cause the Diab

ddump command to generate the following error message during an application build.

Error 0169 at offset NNNNNNNN: Unexpected EOF.

The error appears to be benign and can be ignored. Currently, there is no known workaround. 2.5.11. Wind River (Diab) C Compiler v5.9.4.8 2.5.11.1. Installation

The Wind River (Diab) compiler 5.9.4.8 can be installed by running the file setup.exe from the supplied media — several options will be presented during the compiler install and the following responses should be used:

• Follow the guidance given in Section 2.5.8, “Wind River (Diab) C Compiler v5.5.1.0”.

• If using a single version of the Wind River (Diab) compiler, either setup the OPENECU_DIAB_5_9_4_8 environment variable as described in the next point, or adjust Window's system path to include the absolute path to the compiler's bin directory. • If using multiple versions of the Wind River (Diab) compiler (for instance, when you are using two or more versions of OpenECU which require different versions of the Wind River (Diab) compiler), the environment variable OPENECU_DIAB_5_9_4_8 must be set to the absolute path to the compiler's bin directory. This macro must terminate in a “\” and must use the DOS 8.3 short naming convention.

E.g., D:\Progra~1\diab\5_9_4_8\win32\bin\ 2.5.11.2. Known defects

There is a compiler defect in which the optimizer may ignore local variable assignments under certain cases. Compiler patch diab_5_9_4_8_patch_TCDIAB-14743 is available from the Pi Innovo website. 2.5.11.3. Known issues

None identified. 2.5.12. GCC Compiler v4.7.3

GCC, also known as the GNU Compiler Collection, is a free compiler system produced by the GNU Project supporting various programming languages. The Free Software Foundation (FSF) distributes GCC under the GNU Public License (GNU GPL). GCC has been adopted as the standard compiler by most modern Unix-like computer operating system and has also been ported to a wide variety of processor architectures and is available for most embedded platforms.

GCC is used with permission under the GPL Version 3. If GCC is installed with OpenECU, the license file can be found in the [install path]\tools\gcc\ppc\docs directory of the OpenECU install. If desired, a copy of the GCC source code can be found and downloaded from the Pi Innovo website.

Support for GCC is currently in beta and as such, the user may run into issues which can cause an application to fail to build or run correctly on target. Listed below are a set of known issues when building an application using GCC. See Appendix K, Contact information for details on how to get in contact with OpenECU support if support is needed for using GCC.

GCC is not recommended for production programs at this time. 2.5.12.1. Installation

GCC is an optional component in the OpenECU installation and is installed by default. 2.5.12.2. Known defects

None identified. 2.5.12.3. Known issues

• Open: Applications built with the GCC compiler do not support the diagnostics feature at this time. Applications using the diagnostics feature will not compile.

• Information: compiler warnings when using Simulink look up blocks.

When building a model that uses Simulink look up blocks, the compiler will emit diagnostic messages similar to the following. These can be ignored.

[file-line]: warning: passing argument 2 of '[lookup function]' discards 'volatile' qualifier from pointer target type [enabled by default] [file-line]: note: expected 'const real_T *' but argument is of type 'const volatile real_T *'

• Information: GCC only supports non-VLE code. Therefore, the compiled code will be larger. In general, GCC applications will be about 50% bigger than code generated by Diab.

• Information: The GNU linker locates data slightly differently than the Diab linker in the final images. RAM and Flash memory utilization may be different for the same application compiled by different compilers.

• Open: Applications built with GCC in general exhibit higher CPU loading than applications build with Diab. 2.5.13. Python

Python is general purpose, high level interpreted programming language, distributed under the PSF license which allows use in non open-source commercial applications. The license can be found in the [install path]\tools\python\license.txt file. 2.5.13.1. Installation

Python is a required component of the OpenECU installation. 2.5.13.2. Known defects

None identified. 2.5.13.3. Known issues

• Open: When using OpenECU, Python may raise an error about an incorrect DLL. For example, “The procedure entry point for X could not be located in the dynamic link library py[name].dll”. This can occur if another application installed on the same machine as OpenECU has also installed Python (for instance, dSpace ControlDesk).

Workaround: Browse to the Windows system directory. Depending on the version of Windows, this will be one of:

c:\windows\system32; or c:\windows\syswow64

Locate the DLL referred to in the error message. The file will start with the characters “py” and end with “.dll”. Group all Python DLLs and move them to a temporary location, then restart OpenECU.

Temporarily moving DLLs will cause the other application to run incorrectly (and if DLLs unrelated to Python are inadvertantly moved, then the applications that rely on those DLLs may not run correctly). You can resolve this by returning the moved DLLs to their original location, or possibly moving the DLLs to the location of the installed applications.

Note

The OpenECU installation of Python does not write files to the Windows directories, or modify global registry entries relating to Python. As such, the OpenECU installation of Python is entirely local to OpenECU and will not affect other packages.

3.1. Introduction ...... 28 3.2. Installed examples ...... 28 3.3. Exercise — Step 1 ...... 28 3.3.1. Designing the application ...... 30 3.3.2. Create the application ...... 30 3.3.3. Review the application ...... 30 3.3.4. Implement the sensor reading ...... 32 3.3.5. Implement the sensor conversion to temperature ...... 33 3.3.6. Implement the threshold comparison ...... 36 3.3.7. Implement the lamp driver ...... 36 3.3.8. Summary so far ...... 37 3.3.9. Create data dictionary and interface specification files ...... 39 3.3.10. Building the application ...... 41 3.3.11. Program the ECU ...... 42 3.3.12. Play with the application ...... 44 3.1. Introduction

This chapter gives you a quick introduction to creating an OpenECU application written in C, and an introduction to programming an OpenECU device.

The step1 exercise in Section 3.3, “Exercise — Step 1” describes how to incorporate the OpenECU C-API library into your own application designs, and how to test and calibrate your models on the ECU. The exercise requires the following resources:

• a working knowledge of C, coding for embedded systems, and the notion of real-time tasks; • a complete installation of Pi's OpenECU C-API package: see Chapter 2, Installation; • a complete installation of supporting tools (e.g., compiler, calibration tool, etc.: see Chapter 2, Installation and Appendix C, Supporting tools); 3.2. Installed examples

The installation of OpenECU comes with a number of explanatory examples of how to use OpenECU, including a completed step1 example (see Section 3.3, “Exercise — Step 1”) configured for various ECUs. See Section 4.6.8, “Examples” and Section 4.6.8.1, “Building the examples” for further details. 3.3. Exercise — Step 1 Create a temperature limit warning

This exercise describes how to build, program, and test an application that monitors a temperature sensor and activates a warning lamp if a temperature threshold is breached. The application uses a single analogue input to measure the temperature, and a single PWM output to activate a warning lamp connected to the power supply.

The exercise requires the OpenECU to be connected to various devices and components as pictured in Figure 3.1, “Quick start loom”.

Figure 3.1. Quick start loom

FEPS 17-19V, 0V

IGN Power supply VPWR 12V DC GND 0V

Calibration CAN0-L, CAN0-H CAN OpenECU 2 Tool

5V supply Analogue input Pot Resistor Sensor GND LED PWM output

M460 CAN0-L CAN0-H Terminated? M220 M250 M461 M550 M670 M220 A43 A28 No FEPS A27 A27 A2 Y22 Y22 M250 A43 A28 No VPWR A2 A2 A20 Y3 Y3 M460 A37 A36 Yes GND A31 A31 C1 Y2 Y2 M461 A37 A36 Yes IGN A26 A26 A12 Y25 Y25 M550 Y11 Y12 Yes CAN0-L A43 A43 A37 Y11 Y11 M670 Y11 Y12 Yes CAN0-H A28 A28 A36 Y12 Y12 5V supply A25 A25 C8 Y8 Y8 External CAN termination required on Analogue input A19 A19 A28 Y31 Y31 loom if CAN bus not terminated Sensor GND A40 A40 C9 Y9 Y9 PWM output A37 A18 A15 Y29 Y29

By following the instructions below, you will complete the application design, create C code, build the application and test the application running on the ECU.

3.3.1. Designing the application

Before any engineering project reaches the design stage, several detailed planning stages should be carried out to define suitable functional requirements and specifications. Once you have a detailed target for your design, you can then start to create an implementation of the application.

For this example, we'll skip the functional specification stage for brevity. The application will read an analogue input every 100 milliseconds, transform the input into a temperature reading, check for sensor faults, and turn on a lamp if the temperature exceeds a limit. We have designed and partially implemented the application for you — you need only finish the implementation as described below. 3.3.2. Create the application

To create the application, copy the [installation directory]\examples\c_api \step1_quick_start directory to somewhere local on your machine. Avoid placing the copy in a directory which contains a space in the path name. The copy has the following directories:

build The build directory contains a batch file which will compile and link the completed step1 implementation.

We'll see how to build the application in Section 3.3.10, “Building the application”.

interface_specification The interface_specification directory the initial implementation of two files: step1_[target-ecu].capi which describes supporting functionality the OpenECU library will provide to the application (for instance, what CCP settings are required to communicate with the calibration tool); and step1.dde which contains a description of the C variables in the step1 implementation which will be exposed to the calibration tool.

We'll see how to write these files in Section 3.3.9, “Create data dictionary and interface specification files”.

loom_specification The loom_specification directory contains a copy of the diagram given in Figure 3.1, “Quick start loom”.

src The src directory contains the initial implementation of the step1 application. We'll see how to implement the functionality of the temperature limit warning in Section 3.3.3, “Review the application”. 3.3.3. Review the application

Open the src\step1_[target-name].c file in a text editor. The file contains a few variables and functions. The M460 version is shown in summary here (and indeed all subsequent examples reflect the M460, there will be some differences to files targeting other ECUs):

#include "openecu.h"

/*...*/

#include "step1_m460_api.h"

static S16 stp_adc_raw; static F32 stp_adc_eng;

static OE_CAL F32 stpc_adc_limit = 90.0;

void psc_initialise_app(void) { (void) pcx_config(PIO_CAN_A37_A36, PIO_CBAUD_500_KBPS); (void) pcx_config(PIO_CAN_C37_C36, PIO_CBAUD_500_KBPS);

/* Delete this comment and conditionals below when filling out this * example from the User Guide. */ #if (1) #error "There is more to do here, see the User Guide." #endif }

void stp_task_100ms(void) { /* Delete this comment and conditionals below when filling out this * example from the User Guide. */ #if (1) #error "There is more to do here, see the User Guide." #endif }

void psc_background_app(void) { }

The source file starts by including openecu.h, which itself includes numerous other OpenECU header files. These header files provide declarations for the OpenECU library, including macros, variables and functions which give the application access the functionality of the ECU.

The OpenECU library isolates the application from the target hardware and provides the framework for allowing the application to perform work on a periodic (and sometimes on an event) basis. You can read more about the library in Chapter 4, Software overview.

The last include file is generated by the interface tool. The interface tool reads an interface specification (which is described in more detail for this exercise in Section 3.3.9, “Create data dictionary and interface specification files”) and generates source code which is compiled and linked with the application and OpenECU library. The source code provides the source definitions to glue the application and library together.

The C variable stp_adc_raw is used to hold the A/D conversion of the temperature sensor. The use of adc is a reference to the pin on the ECU connector (see the loom specification in Figure 3.1, “Quick start loom” to review how the ECU will be connected to power, to communications, to the temperature sensor and to the warning lamp).

The C variable stp_adc_eng is used to hold the result of converting stp_adc_raw into a temperature. It has units °C.

The C variable stpc_adc_limit is a calibration. A calibration is a C variable which can be modified by a calibration tool, without having to recompile the application. Calibrations are typically editable with a calibration tool (there is an introduction to the more common calibration tools in Appendix C, Supporting tools), and some ECUs support editing calibrations while the application is running (useful for tuning your application).

Calibrations used in OpenECU should have the OE_CAL macro for variables that are meant to be declared as volatile const. This is to ensure that calibrations are put into calibration flash in memory. If this macro is not used for calibrations, you may not be able to access calibrations in your calibration tool.

Calibration parameters which are used as the defaults for adaptive parameters must use the OE_ADAP macro instead of OE_CAL for proper operation. Failure to use OE_ADAP in a parameter used with one of the PNV function may result in unexpected module resets or other undefined behaviour. See the C-API nvm_demo source code in the examples folder of the OpenECU installation directory for more information.

This variable is the calibratable temperature limit, above which the application will turn on the warning lamp. The variable has units of °C.

Note

Notice how the name of this variable and the others make use of a prefix, either stpc or stp. All variables in an OpenECU application which will be read or written by a calibration tool need to adhere to this naming policy (which is covered in detail outside of this exercise in Section 7.1.5.2, “DDE naming rules (prefix_style)”). Other variables, private to the application, do not need to follow the naming policy.

The C function psc_initialise_app() is called by the OpenECU library during initialisation. The function currently calls the library to initialise the CAN buses and we'll later add more code to perform additional initialisation.

You can read about the initialisation sequence in Section 4.6, “Application mode”.

The C function psc_initialise_app() initialises the CAN buses by calling the OpenECU library pcx_config() function. The function takes two parameters: the first specifies the CAN bus to configure; and the second specifies the baud rate for the CAN bus. In both cases, the parameters use macros from the pio.h header file. We'll see how similar macros are used in other situations as the exercise progresses.

The function returns a code indicating success or failure of the operation. For this exercise, we'll ignore the return value (by casting it to void), but in your applications, you'll probably want to check the return code.

These blocks will throw a compiler error at build time. They are to prevent the compiler from building the quick start without reading this user guide. They should be deleted in order to build the project

The C function stp_task_100ms() performs the main functionality of the application. The interface specification instructs the library to call this function every 100 milliseconds (we'll see more about the interface specification for this exercise in Section 3.3.9, “Create data dictionary and interface specification files”. At the moment, the function does nothing — we'll expand on it in just a moment.

The C function psc_background_app() is called by the library when the processor is not running anything else. For the purposes of this exercise, we won't need it to do anything but you read more about the background function in Section 5.3.1.2, “System background processing”.

We need to extend the basic functionality of the application to read an analogue input, process it into a temperature reading, and set the state of a PWM output based on the temperature calibration. 3.3.4. Implement the sensor reading

The input portion of the application means reading an analogue input and converting the result to a temperature. Add the following code to the stp_task_100ms() function.

(void) pax_adc_input (PIO_AIN_A28 , &stp_adc_raw , FALSE );

The OpenECU library provides a function called pax_adc_input() to convert the voltage in of a connector pin to the range [0, 4096], where 0 corresponds to ground, and 4096 corresponds to full scale voltage. The full scale voltage depends on the connector pin chosen — A28 in this case corresponds to 5V full scale. The full scale range for each pin is detailed in the ECU's technical specification (Section A.1, “ECU hardware reference documentation”).

The first parameter to the function specifies the channel to convert. As with the CAN bus configuration example, the referenced hardware element is given as a macro. In this case, the macro specifies that the function must provide the result of reading pin A28.

The second parameter to the function specifies the variable to write the result of reading pin A28. We covered variable stp_adc_raw earlier.

The third and final parameter to the function specifies whether the channel given by the first parameter should be initialised or not. In this case, we need to read pin A28, hence the FALSE value. We'll cover initialisation shortly.

We also need to initialise the library to read pin A28, add the following code to function psc_initialise_app().

(void) pax_adc_input(PIO_AIN_A28, &stp_adc_raw, TRUE);

Initialisation uses the same function and parameters except for the last. The final parameter, set to TRUE this time, tells the function to initialise pin A28 to be processed as an analogue input.

With these changes in place, the application can now initialise the temperature sensor input pin and reads the temperature sensor every 100 milliseconds. We now need to convert the reading into a sensible engineering value. 3.3.5. Implement the sensor conversion to temperature

Temperature sensors, and other sensors in general, can often generate a non-linear response to the physical characteristic under measurement. For the purposes of this exercise, we'll assume the temperature sensor is non-linear, and has a response similar to the following:

Figure 3.2. Transfer function for temperature sensor

The OpenECU library directly supports converting linear and non-linear analogue readings to engineering values with the put_process_analog_input() function. Add the following code immediately below the call to put_adc_in().

put_process_analog_input(stp_adc_raw, 0.1, &stp_adc_eng, &stp_adc_confirmed_raw_min_flt, &stp_adc_confirmed_raw_max_flt, &stp_adc_confirmed_slew_rate_flt, &stp_adc_confirmed_eng_min_flt, &stp_adc_confirmed_eng_max_flt, &stp_adc_transient_flt, &stp_adc_process_analog_input_pai_cal, &stp_adc_process_analog_input_pai_wrk );

The first parameter provides the function with the A/D conversion of the input. It is this value which is converted to engineering units.

The second parameter specifies how long it has been since the last call to put_process_analog_input() for pin A28. As the function is called from stp_task_100ms() which runs every 100 milliseconds, 100 milliseconds is specified.

The third parameter points to a variable which is written with the result of converting stp_adc_raw to engineering units.

The fourth through to the ninth parameters point to variables which are written with the results of fault checking the input and conversion process. For the purposes of this exercise, the code won't act on any of the fault flags, but you will probably want to address any detected faults in your own applications.

The tenth parameter points to a work space which the function uses to record information between calls to put_process_analog_input().

The eleventh parameter points to a group of calibrations which define how the

The function call references numerous variables which have not yet been declared. Add the following code after the declaration of stpc_adc_limit.

static BOOL stp_adc_confirmed_raw_min_flt; static BOOL stp_adc_confirmed_raw_max_flt; static BOOL stp_adc_confirmed_slew_rate_flt; static BOOL stp_adc_confirmed_eng_min_flt; static BOOL stp_adc_confirmed_eng_max_flt; static BOOL stp_adc_transient_flt;

which declares the fault flags passed to put_process_analog_input(). We also need to declare the work space and calibration structures. Add the following code immediately after the fault variables:

static PUT_ANALOGUE_WORKSPACE_T stp_adc_process_analog_input_pai_wrk; static const PUT_ANALOGUE_CAL_DATA_T stp_adc_process_analog_input_pai_cal = { &stpc_adc_min_raw_value, &stpc_adc_max_raw_value, &stp_adc_eng_lookup_axis_size, stpc_adc_eng_lookup_x_axis, stpc_adc_eng_lookup_z_data, &stpc_adc_min_eng_value, &stpc_adc_max_eng_value, &stpc_adc_leaky_bucket_rise_rate, &stpc_adc_leaky_bucket_fall_rate, &stpc_adc_leaky_bucket_flt_clear_level, &stpc_adc_default_output_value, &stpc_adc_max_slew_rate };

The structure is essentially a set of pointers to calibrations. The calibrations can themselves be changed by a calibration tool while the application is running. The calibration detail the different transformations and checks applied to the A/D reading.

These specify the minimum and maximum allowable value for the A/D conversion, which in this exercise is stp_adc_raw. If stp_adc_raw is outside the range given by these calibrations, then put_process_analog_input() will record a fault.

Add the following code before the definition of stp_adc_process_analog_input_pai_cal.

static OE_CAL F32 stpc_adc_min_raw_value = 90; static OE_CAL F32 stpc_adc_max_raw_value = 4000;

For this exercise, the raw A/D limits do not bound the full scale, and it will be possible to see the raw fault flags become set if the temperature sensor is shorted to ground or to 5V.

These specify how the A/D conversion is transformed into an engineering value. The x_axis and z_data match the transfer function for the temperature sensor given in Figure 3.2, “Transfer function for temperature sensor”.

Add the following code before the definition of stp_adc_process_analog_input_pai_cal.

static const S32 stp_adc_eng_lookup_axis_size = 6; static OE_CAL F32 stpc_adc_eng_lookup_x_axis[] = {163, 917, 1671, 2424, 3178, 3932 }; static OE_CAL F32 stpc_adc_eng_lookup_z_data[] = {135, 96, 74, 55, 20, -42 };

What these lines of code say, is that an A/D range of [163, 3932] will be mapped onto an engineering range of [-42, 135]°C, following the curve given in the transfer graph.

These specify the minimum and maximum allowable value for the engineering value. If the engineering value is outside the range given by these calibrations, then put_process_analog_input() will record a fault.

Add the following code before the definition of stp_adc_process_analog_input_pai_cal.

static OE_CAL F32 stpc_adc_min_eng_value = -40; static OE_CAL F32 stpc_adc_max_eng_value = 130;

For this exercise, the engineering limits do not bound the full range of the transfer function declared above (range [-42, 135]°C), and it will be possible to see the engineering fault flags become set if the temperature sensor voltage is close to 0V or 5V.

These specify how a detected fault will be validated. For this exercise, it is not important to understand the fault mechanism (although you can read more about it in Section 5.22.1.6, “Leaky bucket fault detection”).

Add the following code before the definition of stp_adc_process_analog_input_pai_cal.

static OE_CAL F32 stpc_adc_leaky_bucket_rise_rate = 0.5; static OE_CAL F32 stpc_adc_leaky_bucket_fall_rate = 0.25; static OE_CAL F32 stpc_adc_leaky_bucket_flt_clear_level = 0.5;

This specifies the engineering value to use if a fault is validated by the leaky bucket. Its a mechanism where by a default engineering value can be used if the temperature sensor is found to be at fault.

Add the following code before the definition of stp_adc_process_analog_input_pai_cal.

static OE_CAL F32 stpc_adc_default_output_value = 60;

For this exercise, it will be possible to see the engineering value default to 60°C if a raw or engineering fault is present for some time.

This specifies the maximum rate of change of the A/D reading. If the rate of change exceeds the limit, a fault is reported. For the purposes of this exercise, we'll set the maximum to a large value to prevent a slew rate fault being reported.

Add the following code before the definition of stp_adc_process_analog_input_pai_cal.

static OE_CAL F32 stpc_adc_max_slew_rate = 10000000;

We also need to initialise the workspace used for processing the analogue input, add the following code to function psc_initialise_app().

put_process_analog_input_init(&stp_adc_process_analog_input_pai_wrk); 3.3.6. Implement the threshold comparison

To be able to turn the warning lamp on or off, the application must decide whether the processed temperature input has exceeded a limit. We already have the processed temperature value (stp_adc_eng) and a calibratable temperature limit (stpc_adc_limit), comparing the two is simple. Add the following code to the end of function stp_task_100ms().

stp_adc_state = (stp_adc_eng > stpc_adc_limit);

This code introduces a new variable, stp_adc_state. It holds the boolean result of the comparison, 0 if the temperature limit has not been exceeded, 1 if the temperature limit has been exceeded. Add the following code after the definition of stp_adc_eng.

static BOOL stp_adc_state; 3.3.7. Implement the lamp driver

Finally, the application must drive the lamp on or off based on the comparison. Add the following code to the end of function stp_task_100ms().

(void) pdx_pwm_output (PIO_POT_A15, 1000, stp_adc_state, 0, FALSE);

The function returns a code indicating success or failure of the operation. For this exercise, just like the call to pax_adc_input() earlier, we'll ignore the return value (by casting it to void), but in your applications, you'll probably want to check the return code.

The OpenECU library provides a function called pdx_pwm_output() drive a pin at a given frequency and duty cycle, essentially generating pulses. The application only needs to turn the lamp on or off so the PWM function may seem like an odd function to choose. It has been chosen to show that some OpenECU library functions can be used for multiple purposes. In this case, the PWM function can generate a low signal without

pulses if the duty cycle is set to 0, and a high signal without pulses if the duty cycle is set to 1. Duty cycles of 0 and 1 exactly match the comparison value calculated earlier.

Note that the actual state of the output (low versus high) depends on the particular pin used and if the pin is configured for a high-side or low-side control. In this example, M460 pin A15 is a low-side only output, so a duty cycle of 0 will have the output off (high voltage if connected to a load) and a duty cycle of 1 will have the output pulled to ground.

The first parameter to the function specifies the channel to drive. As with the pax_adc_input() function, the referenced hardware element is given as a macro. In this case, the macro specifies that the function must drive pin A15.

The second parameter to the function specifies the rate at which pulses should be generated. For this exercise, we don't need pulses to be generated but simply need a constant low or high signal, so any valid frequency which is at least as quick as the task itself will do.

The third parameter to the function specifies the proportion of the frequency which must be pulsed high. Again, for this exercise, we don't need pulses to be generated but simply need a constant low or high signal. In this case, the PWM function can generate a low signal without pulses if the duty cycle is set to 0, and a high signal without pulses if the duty cycle is set to 1. Duty cycles of 0 and 1 exactly match the comparison value stp_adc_state.

The fourth parameter to the function specifies a phase offset that can be set for a given channel relative to other channels with the same frequency. In this case, just set this to zero.

The fifth and final parameter to the function specifies whether the channel given by the first parameter should be initialised or not. In this case, we'll need to drive A15, hence the FALSE value. We'll cover initialisation shortly.

We also need to initialise the library to drive pin A15, add the following code to the end of function psc_initialise_app().

(void) pdx_pwm_output(PIO_POT_A15, 1000, 0, 0, TRUE);

Most OpenECU hardware implements a switch to control whether an output driver can be turned on or not (although some do not, for instance, the M461). The switch can be used as a secondary system to prevent accidental changes to the output drivers. However, for the purposes of this exercise there is no need for this level of functionality, instead, we simply need to ensure that pin A15 can be driven. Add the following code to the end of function psc_initialise_app() if the ECU target supports the function (see pss_set_safety_switch()). for more).

pss_set_safety_switch(TRUE); 3.3.8. Summary so far

Having followed the instructions you will have a simple application which reads an analogue temperature sensor and turns on a lamp if the temperature exceeds a calibratable limit. Your code should now look something like the following.

#include "openecu.h"

#include "step1_m460_api.h"

static S16 stp_adc_raw; static F32 stp_adc_eng; static BOOL stp_adc_state;

static OE_CAL F32 stpc_adc_limit = 90.0;

static BOOL stp_adc_confirmed_raw_min_flt;

static BOOL stp_adc_confirmed_raw_max_flt; static BOOL stp_adc_confirmed_slew_rate_flt; static BOOL stp_adc_confirmed_eng_min_flt; static BOOL stp_adc_confirmed_eng_max_flt; static BOOL stp_adc_transient_flt;

static OE_CAL F32 stpc_adc_min_raw_value = 90; static OE_CAL F32 stpc_adc_max_raw_value = 4000; static const S32 stp_adc_eng_lookup_axis_size = 6; static OE_CAL F32 stpc_adc_eng_lookup_x_axis[] = { 163, 917, 1671, 2424, 3178, 3932 }; static OE_CAL F32 stpc_adc_eng_lookup_z_data[] = { 135, 96, 74, 55, 20, -42 }; static OE_CAL F32 stpc_adc_min_eng_value = -40; static OE_CAL F32 stpc_adc_max_eng_value = 130; static OE_CAL F32 stpc_adc_leaky_bucket_rise_rate = 0.5; static OE_CAL F32 stpc_adc_leaky_bucket_fall_rate = 0.25; static OE_CAL F32 stpc_adc_leaky_bucket_flt_clear_level = 0.5; static OE_CAL F32 stpc_adc_default_output_value = 60; static OE_CAL F32 stpc_adc_max_slew_rate = 10000000;

void psc_initialise_app(void) { (void) pcx_config(PIO_CAN_A37_A36, PIO_CBAUD_500_KBPS); (void) pcx_config(PIO_CAN_C37_C36, PIO_CBAUD_500_KBPS);

(void) pax_adc_input(PIO_AIN_A28, &stp_adc_raw, TRUE);

put_process_analog_input_init(&stp_adc_process_analog_input_pai_wrk);

(void) pdx_pwm_output(PIO_POT_A15, 1000, 0, 0, TRUE);

pss_set_safety_switch(TRUE); }

void stp_task_100ms(void) { (void) pax_adc_input(PIO_AIN_A28, &stp_adc_raw, FALSE);

stp_adc_state = (stp_adc_eng > stpc_adc_limit);

(void) pdx_pwm_output (PIO_POT_A15, 1000, stp_adc_state, 0, FALSE); }

void psc_background_app(void) { }

Before we build the application and link it with the OpenECU library we need to specify how the library and application will work together. For instance, we need to tell the library that function stp_task_100ms must be called every 100 milliseconds. We do this by writing a data dictionary file and an interface specification file. 3.3.9. Create data dictionary and interface specification files

There are two aspects to linking an application with the OpenECU library:

Data dictionary file Used to explain the C variables that will be accessible by a calibration tool while the application is running on an ECU. For this exercise, we'll define data dictionary elements (DDEs) for most of the global variables in the code, so that, for instance, the processed temperature (stp_adc_eng) can be viewed in real-time.

Interface specification file Used to detail information about the application and how it will use the library. The interface specification file is converted into supporting C code to be built with the application and linked to the OpenECU library. For instance, one of the functions of the interface specification file is to declare the application tasks, which in this exercise, consists of stp_task_100ms called every 100 milliseconds.

Both the data dictionary file (or files) and the interface specification file are read by a tool which generates:

• Additional code files which must be linked with the application and OpenECU library to create a binary image to program an ECU with; and

• An ASAP2 file which can be read by a calibration tool to provide access to the application's C variables while the application runs on an ECU. 3.3.9.1. Review the data dictionary file

When the application was created during Section 3.3.2, “Create the application”, a complete data dictionary file was copied. Edit the file interface_specification\step1.dde in a text editor and you'll find it contains numerous lines including:

Name Units Class Accuracy Min Max Description

stp_adc_raw A/D counts d 1 0 4096 Temp. pin A28 as A/D...

Each line is either a comment line (starting with either “**” or “--”) or a line specifying data as a set of columns, each column separated by a single TAB character.

The column specification line consists of a set of named columns, each separated by a single TAB character. The columns can be re-arranged so long as Name remains the first.

The Name column gives the name of the C variable. In this case, stp_adc_raw refers to the C variable of the same name, the variable is used to store the A/D reading of pin A28.

The Units column gives the units to be applied to the value of stp_adc_raw. The units are displayed by calibration tools, but in general, are otherwise ignored by OpenECU and other tools.

The Class column gives the ASAP2 type used for the C variable. Here, the variable is a displayable, that is, something which is stored in RAM and writable by the application, so the class is set to d (for displayable).

The Min and Max columns give the minimum and maximum range the C variable should contain. The range is loosely used by a few tools, but does not in any way restrict what the code can do. For instance, if the range is [0, 4096] but the code assigns value 10000 to the variable, then the variable will be written with 10000 and if the calibration tool is viewing the variable at the time, it may flag the variable as being out of range.

The other lines in the data dictionary file make up comments and other data definitions for both displayables (readable variables) and calibrations (writable variables declared volatile const).

More detailed information about the structure of the data dictionary file can be found in Section 4.6.3, “Data dictionary and engineering unit files”. 3.3.9.2. Review the interface specification file

When the application was created during Section 3.3.2, “Create the application”, a complete data dictionary file was copied. Edit the file interface_specification \step1_[target-ecu].capi in a text editor. The interface file contains various statements, some of which we'll take a closer look at.

target-ecu { hw-part-number = "01T-068144"; hw-issue-number = 1; hw-option = "000"; }

Specifies that the application will be run on an M460 Developer ECU Issue 1.

application { major-version = 1; minor-version = 0; subminor-version = 0;

os-native { stack-size = 8192;

task { name = stp_task; priority = 1; period = 100; function = stp_task_100ms; } } }

Specifies version, name, description and copyright information which is embedded into the source code and is programmed onto the target ECU with the application. The information can be read out of the target ECU later.

In particular, note that the name statement can take tokens, single words starting and ending with the “%” character. See Section 7.1.4.8, “Compound statement: application” for a complete list of tokens.

Specifies the overall stack size to be allocated to the application and OpenECU library. A simple application like the one presented in this exercise typically uses less than 1KB of stack, the 5KB specified here could be reduced if necessary.

Specifies that one function called stp_task_100ms must be called every 100 milliseconds. That is sufficient for this exercise, but other tasks can be specified. When

more than one task is specified, the relative priority of each dictates the running order of the functions (see Section 5.6.1.2, “Preemptive scheduling” for more details).

ccp-messaging { cro = 1785; dto = 1784; station-address = 0; can-bus = 0; baud = 500;

enabled-during-application-mode = true; }

Specifies the calibration communication protocol (CCP) parameters for communication between the calibration tool and application running on the target ECU. The values presented here are the default set that each target ECU is delivered with reprogrammed. We'll see how to program an ECU in Section 3.3.11, “Program the ECU”.

ddes { include-dde-tabbed "../interface_specification/step1.dde";

generate-library-ddes = true; }

Specifies the data dictionary files which describe the application C variables of interest. 3.3.10. Building the application

The following sections detail how to build the application. Building the application can be done using either the Diab Compiler, or by using GCC. Please follow the steps relevant to your compiler. 3.3.10.1. Build the application using a Diab Compiler

The description that follows assumes the example is being built using the Wind River Diab compiler, v5.5.1.0. If you are using another supported compiler, you will need to select files or settings to match your target and compiler combination.

When the application was created during Section 3.3.2, “Create the application”, a simple batch file was copied. Edit the file build\build_[target-ecu]_diab_5_5_1_0.bat. Change the line:

SET OPENECU_DIAB=

to match the installed location of the compiler. The location must end in a trailing directory slash (the “\” character). For instance, if the compiler was installed at c:\diab \5.5.1.0\win32\bin, then the line should be set to:

SET OPENECU_DIAB=c:\diab\5.5.1.0\win32\bin\

Once edited, the build can be run by executing the batch file. The result of a successful build produces a number of files in the same directory as the build directory.

• step1_[target-ecu]_vision.a2l — the ATI Vision specific ASAP2 file for the build application; • step1_[target-ecu]_image_small.s37 — the image bytes to program into the OpenECU in Motorola S-record format (small representing the minimum amount of code and data bytes to program the OpenECU device) — suitable for the ATI Vision calibration tool.

If the build fails for any reason, go back through the stages of the example and identify any corrections, or look at the installed and completed step1 application to identify any differences. 3.3.10.2. Build the application using the GCC Compiler

The description that follows assumes the example is being built using the GCC Compiler v4.7.3 that comes packaged in your OpenECU installation. Please see Section 2.1.5, “Third party tool requirements — compatibility” for a list of supported targets for GCC. If you are using another supported compiler, you will need to select files or settings to match your target and compiler combination.

When the application was created during Section 3.3.2, “Create the application”, a simple batch file was copied. Use the file build\build_[target-ecu]_gcc_4_7_3.bat.

The build can be run by executing the batch file. The result of a successful build produces a number of files in the same directory as the build directory.

The OpenECU is programmed with any CCP compliant tool. Specific instructions for ATI Vision, Vector CANape and ETAS INCA calibration tools are provided in Appendix C, Supporting tools.

At a minimum, the OpenECU device will need to be powered and be connected to the CCP tool over CAN as shown in the following diagram.

FEPS 17-19V, 0V

IGN Power supply VPWR 12V DC OpenECU GND 0V

Calibration CAN0-L, CAN0-H CAN 2 Tool

M220 M460 CAN0-L CAN0-H Terminated? M221 M250 M461 M550 M670 M220 A43 A28 No FEPS A27 A27 A2 Y22 Y22 M250 A43 A28 No VPWR A2 A2 A20 Y3 Y3 M460 A37 A36 Yes GND A31 A31 C1 Y2 Y2 M461 A37 A36 Yes IGN - A26 A12 Y25 Y25 M550 Y11 Y12 Yes CAN0-L A43 A43 A37 Y11 Y11 M670 Y11 Y12 Yes CAN0-H A28 A28 A36 Y12 Y12 External CAN termination required on loom if CAN bus not terminated

The OpenECU device can be programmed by following these steps:

1. Apply a positive FEPS voltage, as given in the following table and then power cycle the ECU (the FEPS signal may not be detected if applied simultaneously with the ECU power). Upon detecting the FEPS signal the ECU is placed into its reprogramming mode, where it does not run the application and responds only to reprogramming commands.

2. Program the ECU following the instructions in Appendix C, Supporting tools.

3. Once programmed, ground the FEPS pin and power cycle the ECU. This places the ECU in its application mode, where the ECU runs the programmed application.

Table 3.1. FEPS voltages

M220 M460 M461 M560 M580 M110 M221 M250 M670 Result 0V 0V 0V 0V FEPS pin is grounded. On power up, the ECU attempts to run the last programmed application in application mode. If a application has not been programmed, the ECU enters reprogramming mode. — > +36V > +13V > +17V FEPS pin is positive. On power up, the ECU enters reprogramming mode. If a application has previously been programmed, the ECU uses the CCP settings of the application. Otherwise, the ECU uses the default CCP settings. < -16V < -16V < -18V < -16V FEPS pin is negative. On power up, the ECU enters reprogramming mode. The ECU uses the default CCP settings and ignores any CCP settings stored in any programmed application. 3.3.12. Play with the application

Once programmed, ground the FEPS pin, power cycle the ECU, and the application will start. With your calibration tool, you will be able to view the stp_adc_raw and stp_adc_eng variables and see them vary as the voltage applied to pin A28 is varied.

Varying the voltage so stp_adc_eng exceeds the value for stpc_adc_limit (which defaults to 90°C) will cause the output driver for A15 to turn on and light the warning lamp.

Grounding the A28 pin will cause the application to determine there is a fault with the temperature sensor, and reported through the stp_adc_confirmed_raw_min_flt and/ or stp_adc_confirmed_eng_min_flt variables.

There are some automatically added data definitions you can view which provides some information about the application (you can find a complete list in Section 7.1.7, “Automatic ASAP2 entries”).

mpl_run_time A counter which the library increments every second the application is running. During reset, the counter is set to zero.

mpl_cpu_loaded The percentage of the CPU used during the last 50 milliseconds. Provides an indication of how hard the application is working.

mpl_tt_stp_task The time in microseconds the step1 task took to run every 100 milliseconds.

4.1. Introduction ...... 46 4.2. System components ...... 46 4.3. System modes ...... 48 4.4. Boot mode ...... 48 4.5. Reprogramming mode ...... 49 4.6. Application mode ...... 54 4.6.1. Building an application ...... 55 4.6.2. Interface specification ...... 58 4.6.3. Data dictionary and engineering unit files ...... 58 4.6.4. Application and library tasks ...... 58 4.6.5. Library status and error handling ...... 61 4.6.6. Compiler library support ...... 61 4.6.7. Deprecated library features ...... 62 4.6.8. Examples ...... 62 4.1. Introduction 4.2. System components

In Figure 4.1, “System components”, each of the different system components is shown in relation to the others. Components in yellow are supplied by Pi, components in white are supplied by the customer.

Figure 4.1. System components

ECU

Bootloader

Library Reprogrammer Application Sensors / Actuators

Communication busses

Calibration Bus analysis Other bus tool tool(s) devices

An ECU is composed of the bootloader, the reprogrammer, the library and the application code.

Bootloader The bootloader handles the ECU start-up and determines which system mode (Section 4.3, “System modes”) to enter. The bootloader component is programmed into the ECU when the ECU is manufactured.

Reprogrammer The reprogrammer handles requests to reprogram the application code using the CAN calibration protocol (see Section 5.16, “CAN Calibration Protocol (CCP) messaging feature (PCP)”). The reprogrammer component is reprogrammed into the ECU before the ECU is manufactured.

Library The library provides start-up, communication, I/O and non-volatile memory functionality usable by the application code. The library component is linked with the application code before being programmed into the ECU.

Application The application uses the library to access the sensors and actuators, and to access other devices via communication buses.

The ECU comes in two types: fleet units and developer units. The main difference between the fleet unit and the developer unit, is that the developer has the capability to adjust calibrations while the application is running. Calibrations are essentially C variables and support is included for single calibrations through to 1d and 2d table calibrations.

Components external to the ECU include:

Sensors/actuators The application can read sensors and drive actuators through the ECU hardware using the library. The sensors and actuators need to match the electrical specification of the ECU (see Section A.1, “ECU hardware reference documentation” for details on each supported ECU).

Physical communication buses The application can receive and transmit messages on the communication buses using the library. Library support ranges from single messages to complete protocol handling (e.g., CCP or J1939).

Calibration tool A (usually) PC based tool which interacts with the ECU to read and modify variables while the application is running (modification of variables only supported on developer units). Appendix C, Supporting tools provides an overview of the supported calibration tools.

The calibration tool also has the ability to reprogram the application when the ECU is running the reprogrammer.

Bus analysis tool A (usually) PC based tool which can analyse the various messages and protocols on the bus, useful for diagnosis. Some tools also support transmission of messages to simulate other bus devices.

Other bus devices Usually smart sensors or actuators, possible other ECUs, all of which need to communicate between each other to achieve the system behaviour required.

4.3. System modes

In Figure 4.2, “System modes”, each of the major system modes is shown. When the ECU is turned on (or is recovering from a powered reset), the bootloader decides which major mode to enter based on external inputs to the ECU.

Figure 4.2. System modes

Boot mode

Bootloader

Determine which mode to enter.

Library Reprogrammer Application

Reprogramming mode Application mode

Boot mode Boot mode starts after reset, performs some tests and, if successful, determines what mode to enter (see Section 4.4, “Boot mode”).

Reprogramming mode Reprogramming mode is entered if the FEPS pin is asserted before the ECU is powered up, if there is an invalid application image in memory, or for certain targets if the ECU is running the application and allowing reprogramming while a reprogramming request is received (FEPS-less) (see Section 4.5, “Reprogramming mode”).

Entering reprogramming mode causes the ECU to listen to the communication buses for reprogramming instructions. The ECU does not run the application.

Application mode Application mode is entered if the FEPS pin is not asserted and if there is a valid application image in memory (see Section 4.6, “Application mode”).

Entering application mode causes the ECU to run the application. The ECU listens to the communications buses for reprogramming instructions, but the application can inhibit reprogramming from occurring if necessary. 4.4. Boot mode

When the ECU is turned on (or is recovering from a powered reset), the bootloader performs various tests. These include:

• Tests on memory devices, looking for hard faults such as shorts on address lines, or memory locations which cannot hold their contents;

• Tests on the code to run, looking for hard faults in the contents of code and data;

• Tests on the frequency of reset, looking for unexpected resets which occur back to back in a short period of time.

If the tests fail then the bootloader will either reset or attempt to enter reprogramming mode, flashing a code to indicate the cause (see the technical specification for each ECU for details about code flashing). If the tests pass, then the bootloader will determine what mode to enter next (see Section 4.5, “Reprogramming mode” and Section 4.6, “Application mode” for details on how each mode is chosen). 4.5. Reprogramming mode

When the ECU is turned on (or is recovering from a powered reset), the bootloader will enter reprogramming mode if the FEPS pin is asserted, if there is an invalid application image in memory, or for certain targets if the ECU is running the application and allowing reprogramming while a reprogramming request is received (FEPS-less).

In reprogramming mode, the ECU listens to the communications buses for instructions to reprogram. Specifically, the ECU listens for CCP commands using either the application CCP settings (if a valid application image is in memory) or the default CCP settings otherwise.

The OpenECU is programmed with any CCP compliant tool. Specific instructions for ATI Vision, Vector CANape and ETAS INCA calibration tools are provided in Appendix C, Supporting tools. If you have another CCP compliant tool, please refer to the manufacturer's instructions for further details in programming and refer to Appendix F, CCP compliance which details how OpenECU complies with the CCP 2.1 standard.

At a minimum, the OpenECU device will need to be powered and be connected to the CCP tool over CAN 0 or CAN A (whichever the target ECU makes available). In some cases the OpenECU module will need to have the FEPS line connected to a power supply capable of up to 19 volts (depending on target), as shown in the following diagram.

Note

The FEPS voltage must be asserted before the ECU is powered up. Powering the FEPS input and ECU simultaneously (i.e. shorting the FEPS and VPWR inputs) may result in reprogramming mode not being detected.

FEPS 17-19V, 0V

IGN Power supply VPWR 12V DC OpenECU GND 0V

Calibration CAN0-L, CAN0-H CAN 2 Tool

OpenECU operates in three system modes:

Boot mode This is the mode initiated when the ECU is turned on (or recovering from a powered reset). Boot mode choose whether to enter reprogramming mode or application mode.

Reprogramming mode This is the mode required to reprogram the OpenECU with the CCP tool. This mode is entered differently depending on the ECU. All OpenECU modules can be made to enter this mode by asserting the FEPS pin with a positive voltage (above the required threshold) and power cycling the OpenECU device.

Application mode This is the mode required to run the application on OpenECU. Start this mode by grounding the FEPS pin and power cycle the OpenECU device.

How reprogramming and application mode is entered differs slightly between groups of ECUs due to differences in the electronics. For the M220, M250, M460 and M461 targets, the next illustration shows how each mode is entered.

Figure 4.3. System modes for M220, M250, M460 and M461

ECU powers up; or ECU resets / Enter boot mode

Application checksum validates; and FEPS grounded / Enter application mode Boot mode

Application checksum invalid; or FEPS has pos or neg voltage / Enter reprogramming mode

Reprogramming Application mode mode Reprogramming request received; and application allows reprogramming; / Enter reprogramming mode

For the M221, M560, M680 and M670 targets, the next illustration shows how each mode is entered.

Figure 4.4. System modes for M110, M221, M560, M680 and M670

ECU powers up (ignition or wake-on-CAN); or ECU resets / Enter boot mode

Application checksum validates; and FEPS grounded / Enter application mode Boot mode

Application checksum invalid; or FEPS has pos or neg voltage / Enter reprogramming mode

Reprogramming Application CAN messages time out time messages CAN / resets ECU mode mode Reprogramming request received; and application allows reprogramming; / Enter reprogramming mode

There are a number of ways in which an ECU can be reprogrammed:

Reprogramming — ECU not previously programmed Reprogramming the ECU without an application can be done with or without FEPS on the M110, M220, M221, M250, M460, M461, M560, M680 and M670.

Without a programmed application, reprogramming mode will use the default CCP settings as defined in Table 4.2, “CCP defaults”. As explained in the table, these settings will vary depending on the version of firmware that is programmed into the ECU.

Reprogramming without FEPS — ECU previously programmed (M110, M220, M221, M250, M460, M461, M560, M680 and M670 only) Once an M110, M220, M221, M250, M460, M461, M560, M680 or M670 ECU has been programmed with a valid application, that ECU can be reprogrammed without having to apply FEPS.

With a programmed application, reprogramming mode will use the CCP settings defined by the application already programmed. If an application with different CCP settings is programmed then the new CCP settings are used after the ECU is power cycled.

Reprogramming with FEPS — ECU previously programmed (M220, M221, M250, M460, M461, M560, M680 and M670 only) All OpenECU targets can be programmed by first applying FEPS and then cycling power to the ECU to enter reprogramming mode.

Furthermore, if the application is running and the application is not inhibiting programming then, without cycling power, the ECU can be programmed by applying FEPS and starting programming.

Forced reprogramming with negative FEPS (M110, M220, M221, M250, M460, M461, M560, M680 and M670 only) The M220, M221, M250, M460, M461, M560, M680 and M670 ECUs can be made to use the default CCP settings instead of the application settings by applying a negative voltage to FEPS and then cycling power to the ECU. Reprogramming mode will then use the default settings for CCP.

The defined CCP settings are defined in Table 4.2, “CCP defaults”. As explained in the table, these settings will vary depending on the version of firmware that is programmed into the ECU.

Once programmed, an ECU will remain in reprogramming mode until the power is cycled. After the power cycle, the ECU will determine which mode to enter based on the FEPS voltage. To start the application after programming, ensure FEPS is grounded and power cycle the ECU.

The FEPS pin is asserted by applying a voltage to the pin. The required voltage varies between ECUs.

Table 4.1. FEPS voltages

As a shortcut, FEPS may be applied while the model is running and, without power cycling the device, be reprogrammed via a CCP compliant tool. When reprogramming starts, the OpenECU device switches from application mode to reprogramming mode. It may be undesirable to allow this method due to safety reasons, so the pcp_inhibit_reprogramming() function can switch this method off.

If the OpenECU device has never been programmed before, it uses the CCP settings given in Table 4.2, “CCP defaults”. The CCP compliant tool must use the same settings. Once the OpenECU device has been reprogrammed with an application that uses different CCP settings, the CCP compliant tool must be changed to use these settings.

Table 4.2. CCP defaults

CCP setting Default value CRO message identifier 1785 DTO message identifier 1784 Station identifier 0 CAN bus identifier CAN 0 CAN bus baud-rate 250kBps or 500kBps a a The default baud-rate for CCP will depend on which version of firmware was flashed into the ECU. All ECUs (such as M220-000 or M250-000) use 500 kBps default baud rate, except for the M461-000 which uses 250 kBps. Refer to Section 7.1.8, “OpenECU software versioning” for details. 4.6. Application mode

When the ECU is turned on (or is recovering from a powered reset), the bootloader will enter application mode if the FEPS pin is not asserted and if there is a valid application image in memory.

When application mode is entered, the library co-ordinates the sequence of initialisation as shown in Figure 4.5, “System initialisation”.

Figure 4.5. System initialisation

Bootloader

Bootloader determines to enter application mode

2 Library pre Reprogrammer initialisation

3 Application initialisation

4 Library post initialisation

Application run

Perhaps the best way to understand how the different components of the OpenECU library interact with the application, is to look at how an application is built into a binary image for reprogramming, and into a data description file for calibration tools.

1. Bootloader — determine which major system mode to enter. When entering application mode, the bootloader changes program flow to the library pre-initialisation phase.

2. Library pre-initialisation — occurs after the bootloader has decided to enter the application mode. During pre-initialisation, the library configures the ECU's hardware in a largely generic way and initialises the C run-time environment.

Hardware configuration includes decoding the reason for reset (which can be inspected by the application by calling psc_decode_reset()).

Initialising the C run-time environment includes clearing C objects with no initialiser to zero, setting C objects with initialisers, and setting up the system stack. The system stack is explained in more detail in Section 5.6.1.3, “Stack sharing”. The size of used stack can be retrieved during application run by calling psc_get_used_stack_size().

3. Application initialisation — occurs after library pre-initialisation, this is the point in time when the application can initialise itself and declare information to the library for post initialisation.

The library invokes the application defined function psc_initialise_app() during application initialisation. The application can initialise any data structures necessary for the application to perform, as well as configuring some aspects of the library. For instance, during application initialisation, the application must declare CAN messages it will receive and transmit (e.g., see ???) or initialise ECU pins for use (e.g., see pdx_digital_output()).

4. Library post-initialisation — occurs after application initialisation to complete any hardware setup (especially any dependent on information declared during application initialisation) then starts the task scheduler.

Note

Typically, library and application initialisation are complete within a few hundred milliseconds of powering up the ECU. A rough guide to the boot time of the ECU can be retrieved by calling psc_decode_reset().

Once the scheduler has started, the application can perform its processing each time one of the application tasks runs.

5. Application run — occurs after library post-initialisation is complete. During application run, both application and library tasks are scheduled in a fixed-priority scheme (see Section 5.6, “Task scheduling (PKN)” for details about task scheduling). 4.6.1. Building an application

With application source code, interface specification and data dictionary files in place, the application can be built and linked with the OpenECU and compiler libraries to generate a binary image which can be programmed and run on an OpenECU. Figure 4.6, “Building an application (in outline)” shows in outline how a build is achieved.

Figure 4.6. Building an application (in outline)

Inputs from application Inputs from elsewhere

Data Interface Application OpenECU dictionary description source library files file code file

Compiler 1 library files

Linker Interface script source files code

Object files

Intermediate build steps build Intermediate 3

ELF or ELF MAP file file

5 4

Target Target ASAP2 image file file

Final outputs from build process

The build process has a number of inputs:

Data dictionary files The data dictionary files describe the data variables of the application code. Data variables are all C global variables, either RAM or ROM based. For each data variable which must be accessible from the calibration tool, there is a corresponding data dictionary element (DDE) which details attributes of the data variable, like description, type, units, and so on. See Section 4.6.3, “Data dictionary and engineering unit files” and Section 7.1.5, “DDE specification” for more.

Interface description file The OpenECU library has a number of function interfaces and data interfaces. The data interfaces are largely exposed so that the build application can closely control the amount of memory the library uses.

Some of the data interfaces are hard to write and maintain by hand, so there is an interface tool which will read an interface description file and generate the data interface code. See Section 4.6.2, “Interface specification” and Section 7.1, “Interface and DDE tool” for more.

Application source code Source code for the application.

OpenECU library file A compiler specific library file for OpenECU. The library file is linked with the application object files to create a binary image for execution on the target.

There is a library file for each target and compiler supported by OpenECU. It is important to link the correct library to match the compiler and target, otherwise the ECU may not operate correctly (see Section 5.1.2, “File locations”).

Compiler library file The compiler's own support libraries (e.g., implementation of the C standard library or compiler specific extensions). See Section 4.6.6, “Compiler library support” for more.

Linker script files The scripts tell the compiler how to combine the application object files, interface object files and libraries to create the binary image to run on the target ECU. This includes details about the layout of memory and how object file sections are allocated to memory.

The inputs are processed in a number of steps to create intermediate objects:

1. Runs the interface tool to generate information about the target and DDEs used in step 5, and to generate the data and task interface code between the application and library.

2. Runs the compiler for the interface code and application code files. The compiler generates object files used in the link stage.

3. Runs the linker to combine the object files from the application and interface tool, as well as the compiler's library and OpenECU libraries, to generate an ELF file.

4. Runs support tools and scripts to extract a binary image of the application from the ELF file. At this stage, the binary image is modified with check- sums and auxiliary data to support robust operation on the ECU. See Section 7.2, “Supporting build scripts” for details.

5. Runs a support tool to extract information from the ELF file (optional). Then runs the interface tool again to generate an ASAP2 file from the target and DDE information from the interface specification. The ASAP2 file is used during reprogramming and calibration of the ECU.

From those intermediate steps, the final set of objects are created:

Target ASAP2 file An ASAP2 file details the memory areas used by the binary application image as well as how DDEs have been allocated to memory. The ASAP2 file is used by PC based tools to reprogram an ECU or to calibrate an ECU. See Appendix C, Supporting tools for more.

Target image file The target image file contains the binary image of the application code and data. Once an ECU is programmed with the image file, the application can be executed. See Appendix C, Supporting tools for more.

The C-API examples supplied with OpenECU show how each of these stages can be implemented in a simple fashion using batch files (see Section 4.6.8.1, “Building the examples”). These are the minimum steps required to build and can be copied if required. But an application may have additional stages to implement and there is no reason why a more sophisticated system (like make or SCons for example) might not be used. 4.6.2. Interface specification

As described already, the library has both data and function parts to its API. Some of the data components are hard to write and maintain by hand and so there is an interface tool which takes a simple description of the interface between the application and library, and generates the data components as required. This helps simplify the coding required to link the application and library together.

The interface tool and format of the interface specification file is given in detail in Section 7.1, “Interface and DDE tool”.

The interface specification also specifies the data dictionaries used to describe application data variables. 4.6.3. Data dictionary and engineering unit files

The OpenECU library can interact with calibration tools to read and write application data while the application is executing on the target. To support the interface between the calibration tool and the application, a data description file is required so the calibration tool understands how the application memory is laid out.

To support the interaction between the calibration tool and application, the interface tool can read a description of the application data and generate the data description file for the calibration tool. The application data is described in a set of data dictionary files explained in more detail in Section 7.1.5, “DDE specification” and the resulting data description file used by the calibration tool can also be used for reprogramming the ECU. 4.6.4. Application and library tasks

The framework of OpenECU requires application processing to occur in one or more tasks. These tasks are declared in the interface specification file, each declaring an application function to call and a priority to schedule the task relative to others.

In order to support the services provided by the library (e.g., J1939 messaging), the library defines a number of auxiliary tasks. These tasks have a unique priority relative to each other and the application tasks, as shown in Table 4.3, “Library and application tasks”.

Table 4.3. Library and application tasks

Priority Task Trigger Targets Description 18+n Module 10ms M220, Handles protection mechanisms to protection periodic M221, avoid ECU damage. task M250, M460, M461, M560, M680 and M670

Priority Task Trigger Targets Description 17+n TPU task Sporadic M220, Handles the event processing required M221, of the TPU peripheral on some ECUs. M250, M560, M680 and M670 16+n Power 100ms M221, Handles the power hold processing on managementperiodic M560, some ECUs. task M680 and M670 15+n Flash code 100ms M220, Handles the Flash code output pin on task periodic M221, some ECUs. M250, M460, M461, M560, M680 and M670 14+n High-Side 100ms M560, Handles the high side output pin(s) on ASIC task periodic M680 and some ECUs. M670 13+n SPI Sporadic M220, Handles SPI messaging between messaging M221, peripherals on-board the ECU. task M250, M460, M461, M560, M680 and M670 12+n CAN 2ms All Handles CAN messaging. messaging periodic (event) task burst 11+n J1939 5ms All Handles J1939 messaging. messaging periodic task 10+n PFF task 10ms All Handles freeze frame processing. periodic 9+n PFS task 10ms All Handles non-volatile filesystem. periodic 8+n PISO 5ms All Handles ISO-15765 messaging. messaging periodic task 7+n PDG 10ms All Handles ISO-15765 based diagnostics messaging periodic messaging. task 6..6+n Application Periodic All Handles application processing. tasks 5 PDTC task 100ms All Handles diagnostic trouble code processing.

Priority Task Trigger Targets Description 4 CAN 2ms All Handles CAN messaging. messaging periodic task burst 3 SPI task 1000ms M220, Handles SPI messaging utility periodic M221, functions. M250, M460, M461, M560, M680 and M670 2 Watchdog 200ms All Handles the processor watchdog. task periodic 1 CCP task 5ms All Handles the CAN Calibration Protocol periodic messaging to and from the calibration tool.

Tasks can have different triggers. Triggers make the task become ready to run. The highest priority task ready to run is given the CPU.

Sporadic The task becomes ready to run based on an event. The event is generally not periodic, but may be periodic under some conditions.

TDC firing The task becomes ready to run based on the angle of the engine relative to each cylinder. See Section 5.23, “Angular function feature (PAN)” for more about supported engine functionality.

Periodic The task becomes ready to run on a periodic basis.

Periodic (burst) The task becomes ready to run based on an event. Once ready, the task becomes periodic for a number of iterations, before stopping and waiting for another event.

Note

The scheduler deals with both application and library tasks. It is possible for a high priority application task to use the processor for as long as it needs and there is no protection offered by the library to prevent tasks from using up more processor time than they should.

The application tasks are scheduled to relative to the library tasks such that a long running task may cause a lower priority library task to become unduly delayed.

An example of this would be the CCP task which runs every 5ms. It is conceivable that an application task may take longer than 5ms to complete and that is a desirable property of the application. However, when the application task takes longer than 5ms, the CCP task becomes delayed by the application task.

The design of the library tries to mitigate the consequences of delayed library tasks. Delaying the library CCP task may cause a burst of DAQ messages to the calibration tool to become delayed and the calibration tool may complain, but delaying the CCP task will not cause the I/O functionality to become delayed or mis-behave.

However, mitigation is all that the library can achieve if the application uses large amounts of the processor, and, for this reason the design of the application must take this into account by keeping the application tasks short. For instance, by splitting long running tasks up into discrete parts which are scheduled on successive task invocations.

See the API documentation for the scheduler feature for more (Section 5.6, “Task scheduling (PKN)”).

4.6.5. Library status and error handling

As the application performs work, it may call the library to access the hardware or perform a function. Depending on the current state of the ECU or the data passed to the library function, the library may or may not be able to perform as required. The library employs two mechanisms to report status and error information when interacting with the application.

Function return values In this case, the function returns an value which indicates the success or not of the call. The application can read the return value and made decisions based on the status of the function.

System feature In this case, the function calls the system feature (see Section 5.2, “System feature (PSY)”) to record that an error has occurred. The system feature records these errors and makes them available to the application via psy_get_error()).

The error handling mechanisms are not mutually exclusive — a function may return a status value and raise an error in the system log. For each library function, the documentation in the sub-sections of Chapter 5, Library interface detail how a function handles errors.

Note

Error checking within the library is not comprehensive, based largely on a design decision to keep the library small and efficient. It is possible to setup or pass invalid data to the library and the library will not raise an error. This is especially true of pointer based function arguments or of build time data structures.

It is the responsibility of the application to interact with the library API correctly.

4.6.6. Compiler library support

The compiler library implements the C standard library as well as any additional functions and data the compiler may require. The OpenECU library relies on some of the standard C library functions and therefore the C library must be included in a build.

OpenECU does the least necessary to make the compiler library work for the functions OpenECU requires. Any additional setup, for instance, to allow memory allocation to work via malloc() and free(), must be performed by the application.

Note

Most compilers supply their implementation of the C standard library as a set of object files. See the compiler documentation for a list of library names.

4.6.7. Deprecated library features

To allow for change in the library, some API features can become marked as deprecated. API features become deprecated when newer features replace older features, or because a change in API naming makes the API more consistent. For instance, when the library is updated to automatically perform a function that the application was required to perform then that function will become marked as deprecated.

As well as being marked deprecated in the documentation, the library header files mark deprecated functions by wrapping them in pre-processor conditional statements. For instance, the API function pss_set_switch() was deprecated (replaced by function pss_set_safety_switch()) and declared in the library header files as:

#if !defined(CFG_DONT_USE_DEPRECATED) /* Deprecated, see pss_set_safety_switch(). */ extern void pss_set_switch ( BOOL pssf_enable ); #else #define pss_set_switch(pssf_enable) pss_set_switch_is_deprecated_see_user_guide() #endif

By defining the CFG_DONT_USE_DEPRECATED macro in the compile command, the compiler pre-processor will replace deprecated API functions with functions which do not exist in the library resulting in a build which does not link. For instance, using the example above, calling pss_set_switch() results in the Diab linker generating the following error:

dld: warning: Undefined symbol 'pss_set_switch_is_deprecated_see_user_guide' in file '[file-name].o' dld: error: Undefined symbols found - no output written

4.6.8. Examples

As part of the install process, a number of examples which use the library are installed, ready to be built.

[install location]\examples\c_api\angular_demo Demonstrates how to use the angular feature for engine control described in Section 5.23, “Angular function feature (PAN)”, including crank and cam trigger wheel configuration, angle based task triggering, and injection and coil pulse generation.

See the example's read-me.txt file for further details.

[install location]\examples\c_api\can_demo Demonstrates how to use the input and output configuration feature described in Section 5.7, “Library input and output configuration (PIO)” to specify CAN buses and baud rates when calling the library.

Demonstrates how to use the CAN feature described in Section 5.15, “CAN messaging feature (PCX)” to receive and transmit CAN messages, unpack and pack data into messages, and monitor the CAN bus status.

Demonstrates how to use the J1939 feature described in Section 5.17, “J1939 (SAE) messaging feature (PJ1939)” to receive and transmit J1939 messages, unpack and pack data into messages and manipulate diagnostic trouble codes (DTCs).

See the example's read-me.txt file for further details.

[install location]\examples\c_api\hbridge_demo Demonstrates how to drive the hbridge outputs by using the digital input/ output feature described in Section 5.10, “Digital input/output feature (PDX)”.

Demonstrates how to use the input and output configuration feature described in Section 5.7, “Library input and output configuration (PIO)” to specify input and output channels when calling the library.

See the example's read-me.txt file for further details.

[install location]\examples\c_api\io_demo Demonstrates how to use the input and output configuration feature described in Section 5.7, “Library input and output configuration (PIO)” to specify input and output channels when calling the library.

Demonstrates how to use the analogue input/output feature described in Section 5.9, “Analogue input/output feature (PAX)” to read and process analogue inputs.

Demonstrates how to use the digital input/output feature described in Section 5.10, “Digital input/output feature (PDX)” to read and drive various signal types.

Demonstrates how to use the safety switch feature described in Section 5.12, “Output driver control feature (PSS)” to control whether the output drivers are enabled or not.

See the example's read-me.txt file for further details.

[install location]\examples\c_api\nvm_util_demo Demonstrates how to use the non-volatile memory feature described in Section 5.19, “Adaptive non-volatile memory feature (PNV)” to store and recall information from non-volatile memory, such as array updates and adaptive table lookup and interpolations.

See the example's read-me.txt file for further details.

[install location]\examples\c_api\step1_completed Demonstrates a simple application which reads an analogue input and if it is above a calibratable threshold, turns on a digital output. This is the completed application from Chapter 3, Quick start.

[install location]\examples\c_api\step1_quick_start A copy of the step1 completed example, used in Chapter 3, Quick start to familiarise new users with the C-API.

[install location]\examples\c_api\util_demo Demonstrates how to use the utility feature described in Section 5.22, “General utilities feature (PUT)” perform auxiliary functions, such as table lookup with interpolation and digital input debounce.

See the example's read-me.txt file for further details.

Each example has the same directory layout. The directories store different types of files and includes a simple batch file to build the example.

build\* Contains a simple batch file for each supported compiler on a given target. See Section 4.6.8.1, “Building the examples” for further details.

interface_specification\* Contains the interface specification and DDEs for the application. The interface specification is processed by the build batch files as described in Section 4.6.1, “Building an application”.

loom_specification\* Contains a bitmap diagram showing how a target ECU should be connected to power, the calibration tool and any other additional equipment for the example to work.

src\* Contains the source files for the application. The source files processed by the build batch files as described in Section 4.6.1, “Building an application”. 4.6.8.1. Building the examples

Each of the examples comes with a batch file which builds the example for a given compiler and target ECU. The batch files are kept as simple as possible to help understand the sequence of commands which goes into building an application.

To build an example using the GCC compiler, no edits are required in the batch file in order to run.

To build an example using the Diab compiler, locate and edit the appropriate batch file (based on Diab compiler and target ECU required). Check the following environment variable at the start of the batch file points to your compiler version, change the path if necessary, then run the batch file from the command line.

OPENECU_DIAB The path to the Diab compiler tool as stored on the build machine, e.g., [diab install location]\diab\5.5.1.0\win32\bin\. The environment variable must end with a directory slash.

The environment variable can be a path to the Diab compiler or a reference to another environment variable, e.g., %OPENECU_DIAB_5_8%. See section Section 2.5.9, “Wind River (Diab) C Compiler v5.8.0.0” for a description of the OPENECU_DIAB_5_8 environment variable.

For instance, to build the step1 completed example for an M220 ECU using Diab 5.5.1.0, at the command prompt, issue the following commands:

cd [install location]\examples\c_api

cd step1_completed\build

build_m220_diab_5_5_1_0.bat

5.1. Introduction ...... 67 5.1.1. Name-spaces, naming conventions and library composition ...... 67 5.1.2. File locations ...... 68 5.1.3. Layout of each feature section ...... 69 5.1.4. Notations ...... 69 5.2. System feature (PSY) ...... 70 5.2.1. Overview ...... 70 5.2.2. System types ...... 70 5.2.3. Error log ...... 70 5.2.4. Interface index ...... 71 5.2.5. Interface detail ...... 75 5.3. System start-up and background processing (PSC) ...... 84 5.3.1. Overview ...... 84 5.3.2. Interface index ...... 87 5.3.3. Interface detail ...... 90 5.4. ECU registry information (PREG) ...... 109 5.4.1. Overview ...... 109 5.4.2. Interface index ...... 110 5.4.3. Interface detail ...... 111 5.5. System timing feature (PTM) ...... 118 5.5.1. Overview ...... 118 5.5.2. Interface index ...... 118 5.5.3. Interface detail ...... 119 5.6. Task scheduling (PKN) ...... 124 5.6.1. Tasking model ...... 125 5.6.2. Interface index ...... 129 5.6.3. Interface detail ...... 130 5.7. Library input and output configuration (PIO) ...... 137 5.7.1. Overview ...... 137 5.8. Feature for specific target configuration (PCFG) ...... 138 5.8.1. Overview ...... 138 5.8.2. M110, M220 and M461 targets ...... 139 5.8.3. M250 target ...... 139 5.8.4. M460 target ...... 139 5.8.5. M670 target ...... 139 5.8.6. Interface index ...... 139 5.8.7. Interface detail ...... 140 5.9. Analogue input/output feature (PAX) ...... 147 5.9.1. Overview ...... 147 5.9.2. Interface index ...... 151 5.9.3. Interface detail ...... 152 5.10. Digital input/output feature (PDX) ...... 160 5.10.1. Overview ...... 160 5.10.2. Interface index ...... 169 5.10.3. Interface detail ...... 171 5.11. Digital data feature (PDD) ...... 197 5.11.1. Overview ...... 197 5.11.2. Interface index ...... 197 5.11.3. Interface detail ...... 198 5.12. Output driver control feature (PSS) ...... 200 5.12.1. Overview ...... 200 5.12.2. M220 target ...... 201 5.12.3. M250 target ...... 201 5.12.4. M460 target ...... 202 5.12.5. M461 target ...... 203

5.12.6. M670 target ...... 203 5.12.7. Interface index ...... 203 5.12.8. Interface detail ...... 204 5.13. Serial peripheral feature (PSP) ...... 205 5.13.1. Overview ...... 205 5.13.2. Input and output processing ...... 205 5.13.3. Interface index ...... 206 5.13.4. Interface detail ...... 206 5.14. CJ125 device driver for UEGO measurement feature (PCJ125) ...... 207 5.14.1. Overview ...... 207 5.14.2. Initialisation ...... 207 5.14.3. Diagnostics ...... 207 5.14.4. Interface index ...... 207 5.14.5. Interface detail ...... 208 5.15. CAN messaging feature (PCX) ...... 210 5.15.1. Overview ...... 210 5.15.2. Initialisation ...... 210 5.15.3. Receiving messages ...... 210 5.15.4. Transmitting messages ...... 211 5.15.5. CAN status ...... 212 5.15.6. CAN buses ...... 212 5.15.7. Build time buffer sizing ...... 212 5.15.8. Library tasks ...... 212 5.15.9. Interface index ...... 212 5.15.10. Interface detail ...... 213 5.16. CAN Calibration Protocol (CCP) messaging feature (PCP) ...... 224 5.16.1. Overview ...... 224 5.16.2. Interface index ...... 229 5.16.3. Interface detail ...... 230 5.17. J1939 (SAE) messaging feature (PJ1939) ...... 235 5.17.1. Overview ...... 235 5.17.2. Node addressing ...... 235 5.17.3. Messaging ...... 236 5.17.4. Message bit and byte numbering ...... 237 5.17.5. PGNs ...... 238 5.17.6. Receive messages ...... 238 5.17.7. Transmit messages ...... 239 5.17.8. Core Diagnostic messages ...... 239 5.17.9. Build time buffer sizing ...... 239 5.17.10. Library tasks ...... 240 5.17.11. Interface index ...... 240 5.17.12. Interface detail ...... 245 5.18. Diagnostic Trouble Code (DTC) feature (PDTC) ...... 280 5.18.1. Overview ...... 280 5.18.2. Diagnostic trouble codes — generic ...... 281 5.18.3. Diagnostic trouble codes — J1939 ...... 281 5.18.4. Storage of data across power cycles ...... 282 5.18.5. Build time buffer sizing ...... 282 5.18.6. Interface index ...... 283 5.18.7. Interface detail ...... 284 5.19. Adaptive non-volatile memory feature (PNV) ...... 293 5.19.1. Overview ...... 293 5.19.2. Storage of data across power cycles ...... 295 5.19.3. Interface index ...... 296 5.19.4. Interface detail ...... 298 5.20. Non-volatile Filesystem feature (PFS) ...... 307 5.20.1. Overview ...... 307 5.20.2. Interface index ...... 308

5.20.3. Interface detail ...... 310 5.21. On-board external flash (PEF) ...... 320 5.21.1. Overview ...... 320 5.21.2. Interface index ...... 321 5.21.3. Interface detail ...... 321 5.22. General utilities feature (PUT) ...... 326 5.22.1. Overview ...... 326 5.22.2. Interface index ...... 328 5.22.3. Interface detail ...... 331 5.23. Angular function feature (PAN) ...... 366 5.23.1. Overview ...... 366 5.23.2. Interface index ...... 379 5.23.3. Interface detail ...... 384 5.24. Waveform properties (PROP) ...... 438 5.24.1. Overview ...... 438 5.24.2. Interface index ...... 438 5.24.3. Interface detail ...... 439 5.1. Introduction 5.1.1. Name-spaces, naming conventions and library composition

Based on the C language, there are a limited number of global name-spaces for identifiers. To avoid clashes with application identifiers which share the same global name-spaces, the library uses a standard naming convention (covered in detail in Section 7.1.5.2, “DDE naming rules (prefix_style)”).

In short, the library uses a 3, 4 or 5 character prefix for all function and data identifiers. Each prefix identifies an area of functionality that the library covers, e.g., PDX for digital I/O or PJ1939 for J1939 messaging. This prefix scheme is similar to the DDE naming scheme covered in Section 7.1.5.2, “DDE naming rules (prefix_style)”.

The current composition of functionality is broken down into a set of features, each with a unique prefix, as shown in Table 5.1, “Library composition”.

Table 5.1. Library composition

Prefix Description Public PSY System feature — definition of integer types and system error logging. PSC System start-up and background processing — handles hardware and library pre and post initialisation, starting application run and implementing the background processing function. PREG ECU registry information — handles retrieval of data specific to the ECU, such as date of manufacturing or the serial number. PTM System timing — provides access to second, millisecond and microsecond timers. PKN Task scheduling — schedules library and application tasks in a fixed preemptive fashion. PIO Library input and output configuration — provides macros for logical channels for each type of input and output, macros for supported CAN buses and baud rates, and so on.

Prefix Description PCFG ECU specific configuration — provides functions specific to some ECUs for utilising functionality not available on other ECUs. PAX Analogue input and output — provides access to analogue based input and output signals (e.g., analogue inputs and constant current outputs). PDX Digital input and output — provides access to digital based input and output signals (e.g., frequency inputs and stepper motor outputs). PDD Digital data — provides access to digital data based signals PAN Angular input and output — provides access to crank, cam, ignition and injector functionality. PSS Output driver control and diagnostics — provides access to the overall output driver switch. PCX CAN messaging — provides access to receive and transmit CAN messages on a periodic basis, and some utility functions to pack and unpack data in messages. PCP CAN calibration protocol messaging — provides basic access to the underlying CCP implementation for interaction with reprogramming and calibration tools. PJ1939 SAE J1939 messaging — provides access to receive and transmit J1939 messages on a periodic basis, handling the transport protocol and address claim negotiations. PDTC Diagnostic trouble codes — handles a simplistic model of diagnostic trouble codes for J1939 messaging. PPR In-Use Performance Ratio (IUPR) calculation — Tracks IUPR and other related information for Diagnostic Test Entities (DTEs)belonging to Diagnostic Monitor Entities (DMEs) and makes them available to report over ISO and J1939 protocols. PNV Non-volatile and adaptive memory — handles storage of data parameters across power cycles and provides some utility functions for adaptive data and maps. PFS Non-volatile filesystem — handles underlying storage of both library and application-specific data in flash memory on supported targets. PEF External flash — handles access to serial flash fitted to some ECUs. PCJ125 CJ125 lambda sensor ASIC — handles access to this device on some ECUs. PNTK NTK lambda sensor ASIC — handles access to this device on some ECUs. PUT General utilities — provides a set of functions for performing some typical functions on an ECU, e.g., table look-up and interpolation. Private Numerous other features are used by the library internally and are not exposed through the C-API. 5.1.2. File locations

The library is provided as a set of C include files and a library object file to be linked with the final application. There is a library object for each target and each compiler supported for that target. These files are located relative to the install location of OpenECU.

[install location]\targets \[ecu]\[ecu]_[option]\[processor]_lib\include\*.h Location of library include files.

[install location]\targets \[ecu]\[ecu]_[option]\[processor]_lib\*.a Location of library object files, one for each supported compiler.

where: [install location] refers to the install location of OpenECU; [ecu] refers to the target ECU for the application; [option] refers to the specific ECU option for the application; and [processor] refers to the ECU's target processor (some ECUs have more than one processor populated).

For instance, when building for a M250 target ECU using Diab v5.5.1.0, the library header files and library object file are located at:

[install location]\targets\m250\m250_000\mpc5534_lib\include\*.h [install location]\targets\m250\m250_000\mpc5534_lib\platform_diab_5_5_1_0.a

When compiling with GCC specifically, the libary object files will not follow the same naming convention mentioned above. Since GCC does not support non-VLE code, the platform is rebuilt, using Diab v5.9 but using non-VLE compiler options. Therefore the library object files are not named using the GCC compiler, but rather with the Diab Compiler (with no_vle specified). The library header files and library object files are located at:

[install location]\targets\m250\m250_000\mpc5534_lib\include\*.h [install location]\targets\m250\m250_000\mpc5534_lib\platform_no_vle_diab_5_5_1_0.a

5.1.3. Layout of each feature section

Each feature is detailed in a separate section from other features. Each feature section is broken down as follows:

Overview section The overview section explains the feature functionality with enough detail to understand what the feature can achieve and how to interface with it at the function level.

Feature index section The feature index section provides a table of macros, enums, structs, typedefs, variables and functions exposed by the feature, along with a summary of the object's description. Each object is linked to the object's detail given in the feature detail section.

Feature detail section The feature detail section provides a series of sub-sections, one for each of macros, types, variables and functions. Each sub-section describes the object is detail, linking to related objects as necessary.

The C object names (for macros, typedefs, variables and so on) are fully linked, allowing for quick browsing. 5.1.4. Notations 5.1.4.1. Range notation

Some function parameters and variables have a valid numerical range or size of array. If so, the range and size information is given beside the object's description using internal notation.

Table 5.2. Interval notation

Notation Range (x, y) x < value < y [x, y) x <= value < y (x, y] x < value <= y [x, y] x <= value <= y

Some objects are not clipped to a range but folded into a range using modulo arithmetic and where this occurs, the description includes details. 5.1.4.2. Fixed point notation

Some function parameters and variables are represented using fixed point numbers rather than floating point numbers. A fixed point number has a fixed number of digits after the radix point (e.g., after the decimal point '.' in floating point decimal notation) in a given base.

Fixed point numbers are expressed as @ fraction units per LSB in the documentation. For instance, the notation @ 0.5 °C per LSB means the least significant bit of the fixed point number represents 0.5 °C. Hence, the value 1 represents 0.5 °C, value 2 represents 1 °C, value 3 represent 1.5 °C and so on. 5.2. System feature (PSY) 5.2.1. Overview

The system feature (PSY) provides the base set of types for the library and a simple logging mechanism for recording conditions that the library believes to be in error. 5.2.2. System types

The library types (BOOL, S8, U8, S16, U16, S32, U32, U64, F32, F64) are to be used when interfacing with the library. Whether that be parameter types, return types, or member types of structures. Each represents an integer or floating point type of a minimum bit width (but the actual underlying type may implement a larger bit width).

The library also defines the NULL, pointer, as well as the TRUE, and FALSE booleans as macros, if those macros have not already been defined. 5.2.3. Error log

As described in Section 4.6.5, “Library status and error handling”, the library records some errors in a log. The system feature gives access to the log for debugging purposes. The log consists of a fixed size array, where each element stores a reference to the feature which raised the error and a code for the error. Once the log is full, further errors raised by the library are discarded.

The feature reference matches one of the feature macros (e.g., PSY_PAX for the analogue input/output feature). The code for an error matches one of the corresponding feature's Pxxx_ERROR_CODE_T enumeration (e.g., PAX_ERROR_CODE_T).

The application can access elements of the log through the psy_get_error() function. The number of reported errors can be determined by calling psy_get_num_errors().

5.2.4. Interface index

An index of interface objects for this feature.

Type Identifier Include file openecu.h and psy.h Macros PSY_MAX_NUM_STORED_ERRORS

The maximum number of different errors that are simultaneously stored. PSY_PBT

This is the error log identifier for the PBT (boot) feature. PSY_PSY

This is the error log identifier for the PSY (system) feature. PSY_PTPU

This is the error log identifier for the PTPU (TPU or eTPU) feature. PSY_PSC

This is the error log identifier for the PSC (startup and idle) feature. PSY_PAX

This is the error log identifier for the PAX (analogue I/ O) feature. PSY_PCX

This is the error log identifier for the PCX (CAN messaging) feature. PSY_PDX

This is the error log identifier for the PDX (digital I/O) feature. PSY_PUT

This is the error log identifier for the PUT (general utility) feature. PSY_PSP

This is the error log identifier for the PSP (SPI messaging) feature. PSY_PNV

This is the error log identifier for the PNV (adaptive non-volatile) feature. PSY_PRS

Type Identifier This is the error log identifier for the PRS (RS232) feature. PSY_PCP

This is the error log identifier for the PCP (CCP scheduling) feature. PSY_PKN

This is the error log identifier for the PKN (scheduler) feature. PSY_PMIOS

This is the error log identifier for the PMIOS (MIOS or eMIOS) feature. PSY_PFL

This is the error log identifier for the PFL (Flash memory) feature. PSY_PCCP

This is the error log identifier for the PCCP (CCP messaging) feature. PSY_PQADC

This is the error log identifier for the PQADC (QADC or eQADC) feature. PSY_PDTC

This is the error log identifier for the PDTC (diagnostic trouble code) feature. PSY_PJ1939

This is the error log identifier for the PJ1939 (SAE J1939 messaging) feature. PSY_PSPI

This is the error log identifier for the PSPI (SPI messaging) feature. PSY_PDG

This is the error log identifier for the PDG (ISO diagnostics) feature. PSY_PFF

This is the error log identifier for the PFF (freeze frame) feature. PSY_PEM

This is the error log identifier for the PEM (emulutor and memory) feature. PSY_PFS

Type Identifier This is the error log identifier for the PFS (filesystem) feature. PSY_PROP

This is the error log identifier for the waveform properties (PROP) feature. PSY_PDD

This is the error log identifier for the PDD (digital data) feature. PSY_PAN

This is the error log identifier for the PAN (angular) feature. PSY_PPP

This is the error log identifier for the PPP (Tunes) feature. PSY_PPM

This is the error log identifier for the PPM (power management) feature. PSY_PSS

This is the error log identifier for the PSS (system safety) feature. PSY_PFC

This is the error log identifier for the PFC (flash code) feature. PSY_PXS

This is the error log identifier for the PXS (extreme switch) feature. PSY_PDC

This is the error log identifier for the PDC (daughter card) feature. PSY_PISO

This is the error log identifier for the PISO (ISO 15765) feature. PSY_APP

This is the error log identifier for the application. PSY_PCFG

This is the error log identifier for the PCFG feature. PSY_PSMC

This is the error log identifier for the PSMC feature. NULL

Type Identifier Ensure the NULL pointer is defined (if it is not already) FALSE

Ensure FALSE is defined (if it is not already) TRUE

Ensure TRUE is defined (if it is not already) Data types PSY_ERROR_LOG_T

The type for an error log. S8

This typedef declares a signed 8 bit integer. U8

This typedef declares an unsigned 8 bit integer. BOOL

This typedef declares a boolean integer. S16

This typedef declares a signed 16 bit integer. U16

This typedef declares an unsigned 16 bit integer. S32

This typedef declares a signed 32 bit integer. U32

This typedef declares an unsigned 32 bit integer. S64

This typedef declares a signed 64 bit integer. U64

This typedef declares an unsigned 64 bit integer. INT

This typedef declares a signed 32 bit integer. UINT

This typedef declares an unsigned 32 bit integer. F32

This typedef declares a 32 bit floating point. FREAL

This typedef declares a 32 bit floating point. F64

Type Identifier This typedef declares a 64 bit floating point. Functions U8 psy_get_num_errors

Returns the number of errors detected by the platform software. BOOL psy_get_error

Gets the information related to an error. 5.2.5. Interface detail 5.2.5.1. Macros 5.2.5.1.1. PSY_MAX_NUM_STORED_ERRORS

Definition: #define PSY_MAX_NUM_STORED_ERRORS 16

Description:

The maximum number of different errors that are simultaneously stored.

The errors can be accessed by calling psy_get_error(). 5.2.5.1.2. PSY_PBT

Definition: #define PSY_PBT (U8)1

Description:

This is the error log identifier for the PBT (boot) feature. 5.2.5.1.3. PSY_PSY

Definition: #define PSY_PSY (U8)2

Description:

This is the error log identifier for the PSY (system) feature. 5.2.5.1.4. PSY_PTPU

Definition: #define PSY_PTPU (U8)3

Description:

This is the error log identifier for the PTPU (TPU or eTPU) feature. 5.2.5.1.5. PSY_PSC

Definition: #define PSY_PSC (U8)4

Description:

This is the error log identifier for the PSC (startup and idle) feature.

5.2.5.1.6. PSY_PAX

Definition: #define PSY_PAX (U8)5

Description:

This is the error log identifier for the PAX (analogue I/O) feature. 5.2.5.1.7. PSY_PCX

Definition: #define PSY_PCX (U8)6

Description:

This is the error log identifier for the PCX (CAN messaging) feature. 5.2.5.1.8. PSY_PDX

Definition: #define PSY_PDX (U8)8

Description:

This is the error log identifier for the PDX (digital I/O) feature. 5.2.5.1.9. PSY_PUT

Definition: #define PSY_PUT (U8)9

Description:

This is the error log identifier for the PUT (general utility) feature. 5.2.5.1.10. PSY_PSP

Definition: #define PSY_PSP (U8)10

Description:

This is the error log identifier for the PSP (SPI messaging) feature. 5.2.5.1.11. PSY_PNV

Definition: #define PSY_PNV (U8)11

Description:

This is the error log identifier for the PNV (adaptive non-volatile) feature. 5.2.5.1.12. PSY_PRS

Definition: #define PSY_PRS (U8)12

Description:

This is the error log identifier for the PRS (RS232) feature.

5.2.5.1.13. PSY_PCP

Definition: #define PSY_PCP (U8)13

Description:

This is the error log identifier for the PCP (CCP scheduling) feature. 5.2.5.1.14. PSY_PKN

Definition: #define PSY_PKN (U8)14

Description:

This is the error log identifier for the PKN (scheduler) feature. 5.2.5.1.15. PSY_PMIOS

Definition: #define PSY_PMIOS (U8)15

Description:

This is the error log identifier for the PMIOS (MIOS or eMIOS) feature. 5.2.5.1.16. PSY_PFL

Definition: #define PSY_PFL (U8)16

Description:

This is the error log identifier for the PFL (Flash memory) feature. 5.2.5.1.17. PSY_PCCP

Definition: #define PSY_PCCP (U8)17

Description:

This is the error log identifier for the PCCP (CCP messaging) feature. 5.2.5.1.18. PSY_PQADC

Definition: #define PSY_PQADC (U8)18

Description:

This is the error log identifier for the PQADC (QADC or eQADC) feature. 5.2.5.1.19. PSY_PDTC

Definition: #define PSY_PDTC (U8)19

Description:

This is the error log identifier for the PDTC (diagnostic trouble code) feature.

5.2.5.1.20. PSY_PJ1939

Definition: #define PSY_PJ1939 (U8)20

Description:

This is the error log identifier for the PJ1939 (SAE J1939 messaging) feature.

5.2.5.1.21. PSY_PSPI

Definition: #define PSY_PSPI (U8)21

Description:

This is the error log identifier for the PSPI (SPI messaging) feature.

5.2.5.1.22. PSY_PDG

Definition: #define PSY_PDG (U8)22

Description:

This is the error log identifier for the PDG (ISO diagnostics) feature.

5.2.5.1.23. PSY_PFF

Definition: #define PSY_PFF (U8)23

Description:

This is the error log identifier for the PFF (freeze frame) feature.

5.2.5.1.24. PSY_PEM

Definition: #define PSY_PEM (U8)24

Description:

This is the error log identifier for the PEM (emulutor and memory) feature.

5.2.5.1.25. PSY_PFS

Definition: #define PSY_PFS (U8)25

Description:

This is the error log identifier for the PFS (filesystem) feature.

5.2.5.1.26. PSY_PROP

Definition: #define PSY_PROP (U8)26

Description:

This is the error log identifier for the waveform properties (PROP) feature. 5.2.5.1.27. PSY_PDD

Definition: #define PSY_PDD (U8)27

Description:

This is the error log identifier for the PDD (digital data) feature. 5.2.5.1.28. PSY_PAN

Definition: #define PSY_PAN (U8)28

Description:

This is the error log identifier for the PAN (angular) feature. 5.2.5.1.29. PSY_PPP

Definition: #define PSY_PPP (U8)29

Description:

This is the error log identifier for the PPP (Tunes) feature. 5.2.5.1.30. PSY_PPM

Definition: #define PSY_PPM (U8)30

Description:

This is the error log identifier for the PPM (power management) feature. 5.2.5.1.31. PSY_PSS

Definition: #define PSY_PSS (U8)31

Description:

This is the error log identifier for the PSS (system safety) feature. 5.2.5.1.32. PSY_PFC

Definition: #define PSY_PFC (U8)32

Description:

This is the error log identifier for the PFC (flash code) feature. 5.2.5.1.33. PSY_PXS

Definition: #define PSY_PXS (U8)33

Description:

This is the error log identifier for the PXS (extreme switch) feature. 5.2.5.1.34. PSY_PDC

Definition: #define PSY_PDC (U8)34

Description:

This is the error log identifier for the PDC (daughter card) feature. 5.2.5.1.35. PSY_PISO

Definition: #define PSY_PISO (U8)35

Description:

This is the error log identifier for the PISO (ISO 15765) feature. 5.2.5.1.36. PSY_APP

Definition: #define PSY_APP (U8)36

Description:

This is the error log identifier for the application. 5.2.5.1.37. PSY_PCFG

Definition: #define PSY_PCFG (U8)37

Description:

This is the error log identifier for the PCFG feature. 5.2.5.1.38. PSY_PSMC

Definition: #define PSY_PSMC (U8)38

Description:

This is the error log identifier for the PSMC feature. 5.2.5.1.39. NULL

Definition: #define NULL ((void *) 0)

Description:

Ensure the NULL pointer is defined (if it is not already) 5.2.5.1.40. FALSE

Definition: #define FALSE ((BOOL)0)

Description:

Ensure FALSE is defined (if it is not already) 5.2.5.1.41. TRUE

Definition: #define TRUE ((BOOL)1)

Description:

Ensure TRUE is defined (if it is not already) 5.2.5.2. Data types

5.2.5.2.1. PSY_ERROR_LOG_T

Summary: The type for an error log.

Members:

U8 PSY_ERROR_LOG_T::feature_id This is the feature identifier for the declared error (e.g., PSY_PFL).

Range: [0, 255] unitless

U16 PSY_ERROR_LOG_T::error_id This is the identifier for the declared error.

Range: [0, 65535]

Description:

The type for an error log.

This type declares a structure containing information relating to a system error (detected by the platform software). 5.2.5.2.2. S8

Definition: typedef signed char S8

Description: This typedef declares a signed 8 bit integer. 5.2.5.2.3. U8

Definition: typedef unsigned char U8

Description: This typedef declares an unsigned 8 bit integer. 5.2.5.2.4. BOOL

Definition: typedef unsigned char BOOL

Description: This typedef declares a boolean integer.

5.2.5.2.5. S16

Definition: typedef signed short S16

Description: This typedef declares a signed 16 bit integer.

5.2.5.2.6. U16

Definition: typedef unsigned short U16

Description: This typedef declares an unsigned 16 bit integer.

5.2.5.2.7. S32

Definition: typedef signed long S32

Description: This typedef declares a signed 32 bit integer.

5.2.5.2.8. U32

Definition: typedef unsigned long U32

Description: This typedef declares an unsigned 32 bit integer.

5.2.5.2.9. S64

Definition: typedef signed long long S64

Description: This typedef declares a signed 64 bit integer.

5.2.5.2.10. U64

Definition: typedef unsigned long long U64

Description: This typedef declares an unsigned 64 bit integer.

5.2.5.2.11. INT

Definition: typedef int INT

Description: This typedef declares a signed 32 bit integer.

5.2.5.2.12. UINT

Definition: typedef unsigned long UINT

Description: This typedef declares an unsigned 32 bit integer. 5.2.5.2.13. F32

Definition: typedef float F32

Description: This typedef declares a 32 bit floating point. 5.2.5.2.14. FREAL

Definition: typedef float FREAL

Description: This typedef declares a 32 bit floating point. 5.2.5.2.15. F64

Definition: typedef double F64

Description: This typedef declares a 64 bit floating point. 5.2.5.3. Functions 5.2.5.3.1. psy_get_num_errors()

Definition: U8 psy_get_num_errors(void)

Supported targets: All targets

Required license: None (Main library).

Description: Returns the number of errors detected by the platform software.

Note

System errors are stored in RAM and are recovered across a reset if possible.

Return: Number of declared errors. Range: [0, PSY_MAX_NUM_STORED_ERRORS] errors 5.2.5.3.2. psy_get_error()

Definition: BOOL psy_get_error(U8 psyf_error_index, PSY_ERROR_LOG_T *psyf_log)

Supported targets: All targets

Required license: None (Main library).

Description: Gets the information related to an error.

Note

System errors are stored in RAM and are recovered across a reset if possible.

Arg (data in): psyf_error_index The index into the error log to retrieve error information from. Range: [0, PSY_MAX_NUM_STORED_ERRORS - 1] unitless

Arg (data out): psyf_log Pointer to store for error information. Cannot be NULL.

Return: True if the error information could be retrieved, false otherwise. 5.3. System start-up and background processing (PSC) 5.3.1. Overview

5.3.1.1. System initialisation

The feature handles the C run-time environment, library and application initialisation. See Section 4.6, “Application mode” for further details. The application must define the psc_initialise_app() function which is called between pre and post initialisation. 5.3.1.2. System background processing

Once initialisation is complete, application run starts. This involves starting the scheduler, which in turn causes library and application tasks to run; and involves calling the background processing functions. Background processing occurs when no other task is running or is ready to run (i.e., when the CPU would otherwise be idle).

The library will call the applications background processing function (psc_background_app()) when it can. The library makes no guarantees that the application background processing function is called, only that if there is CPU idle time when tasks are not running, then an attempt to call the application background processing will eventually be made.

The platform itself performs various operations in the background including checks on RAM hardware. If a RAM error is detected, an unrecoverable error is raised (resulting in ECU reset) because program execution is otherwise likely to fail in an unpredictable manner.

Similarly non-volatile data is revalidated in the background and treated as if it is no longer available if validation fails. Thus if run-time memory corruption occurs affecting non-volatile data, any subsequent attempt to read that data will be handled in the same way as if the data were not present (default used instead).

Background checking for code or calibration corruption works through the Calibration Verification Number computation on supported targets with the OBD library option. Ensure

that the CVN is recomputed continually if run-time corruption checking is required. If it is detected, an unrecoverable error is raised (resulting in ECU reset). This is in addition to boot- time checksum validation. 5.3.1.3. System reset

A controlled system reset occurs when the ECU is turned on, or when the ECU software invokes a reset. A reset causes the bootloader to determine which major system mode to enter (see Section 4.3, “System modes” for more).

The reason for a reset can be determined during application run by calling psc_decode_reset(), which also provides a rough guide to the duration between reset and the start of application run. 5.3.1.4. System up-time (run-time)

The feature maintains a second timer, called the run-timer or up-timer. The current value of the run-timer is returned by calling psc_get_run_time(). It is cleared to zero during library pre- initialisation and incremented every second during application run. The run timer can be used as an indication of how long the system has been running in application mode without a reset. 5.3.1.5. System loading

The feature maintains an estimate of the CPU utilisation. The current CPU loading is returned by calling psc_get_cpu_loading(). The CPU load is calculated every 50 milliseconds during background processing (or longer if any set of tasks cause the background processing to be delayed). The CPU loading is essentially the time used by running tasks over the 50ms period, expressed as a percentage.

The feature also records the highest estimate of CPU utilisation. The highest recorded CPU loading is returned by calling psc_get_max_cpu_loading().

For some target ECUs, this feature maintains an estimate of the eTPU utilisation (the eTPU is used for simple and complex I/O operations, such as crank wheel decoding). As with the CPU, the eTPU loading is calculated every 50 milliseconds during background processing (or longer if any set of tasks cause the background processing to be delayed). Call psc_get_etpu_loading() or psc_get_max_etpu_loading() to retrieve the latest eTPU loading, and maximum eTPU loading seen since reset. 5.3.1.6. System stack

The system stack is configured during library pre-initialisation. The system stack is shared between background processing, library and application tasks (see Section 5.6.1.3, “Stack sharing” for more detail on how the stack is shared).

During pre-initialisation, the memory area allocated to the system stack is filled with a predetermined set of bit patterns. As the stack becomes used, these bit patterns are over-written, and the library determines the amount of used stack by scanning through the memory area to find the point where the bit patterns have been overwritten. This scanning is performed as background processing, and the last calculated system stack use is returned from calling psc_get_used_stack_size().

Note

On supported ECUs, an overflow of the system stack is trapped by this feature. Rather than allow a stack overflow to overwrite valid system variables, resulting in possibly undefined or unexpected behaviour, this feature traps the error, records the issue and resets the ECU.

5.3.1.7. System watchdog handling

The library provides for a simple system which kicks the ECU watchdog periodically. If the watchdog task is starved of CPU time, the ECU watchdog will eventually trigger causing a reset.

Target ECU Watchdog duration Maximum kick period M110, M220, M221, [~419, ~838] milliseconds a 200 milliseconds M250, M460, M461 M560, M680, M670 [~508, ~1016] milliseconds a 200 milliseconds a The range reflects the configuration of the processor's watchdog, which uses two time out periods before resetting the processor. The library automatically kicks the watchdog at the maximum period for the target ECU. But the application may take control of the watchdog by using the watchdog statement (see Section 7.1.4.9, “Compound statement: os-native”) and calling psc_kick_watchdog() as necessary whilst the application runs. 5.3.1.8. System identification

The feature provides a number of variables which can identify the application. The variables contain version numbers, build dates and part numbers. Part numbers are provided for the bootloader components and the library. These variables are added to the ASAP2 file (Target ASAP2 file) which provides for inspection of the application identification while the ECU is running in application mode using a calibration tool (see Section 7.1.7, “Automatic ASAP2 entries” for more).

The application can retreive the bootloader components and the library version numbers, build dates and part numbers by invoking the following functions: psc_get_boot_version(), psc_get_boot_build_date(), psc_get_boot_part_number(), psc_get_prg_version(), psc_get_prg_build_date(), psc_get_prg_part_number(), psc_get_platform_version() , psc_get_platform_build_date(), psc_get_platform_part_number() . There is also a set of functions that can be used to dynamically retrieve the application version and build date: psc_get_application_version() and psc_get_application_build_date(). 5.3.1.9. Library header

The library contains a 1KB header. The header contains information about the processor initialisation, library entry point and various other data, but also contains a check-sum. The check-sum is tested by the bootloader when choosing the system mode to enter (see Section 4.3, “System modes”). The check-sum is set when the application is built — see the batch files for each example to see how this is achieved (see Section 4.6.8, “Examples”). 5.3.1.10. Memory tests

Each ECU implements an internal memory test during startup to check for hard memory faults. Hard memory faults are memory faults that have become permanent such as a shorted address line, or a memory cell that cannot change state. RAM is tested by performing a destructive walking one's test on the address and data lines and a memory recall test on the memory cells. ROM is tested by calculating a checksum of the contents. If a hard memory fault is detected, then the ECU will reset itself to force safety related outputs to a default state.

Some ECUs also implement a continuous internal memory test during runtime to check for soft memory faults. Soft memory faults are transient memory faults, such as might occur when a memory cell changes state due to stray electron releases. The error correction module hardware is capable of detecting and correcting errors that are limited to a single bit wrong in a 64-bit double word. If more than one bit is wrong in a 64-bit double word, then the hardware can detect the error, but it cannot be corrected. If an uncorrectable soft memory fault is detected, then the ECU will reset itself to force safety related outputs to a default state.

The application can retrieve the status of the continuous internal memory soft error test as well as the address of the last detected correctable error by invoking the following functions:

• psc_int_ram_test_progress() • psc_int_rom_test_progress() • psc_int_ram_test_error_detected() • psc_int_rom_test_error_detected() 5.3.2. Interface index

An index of interface objects for this feature.

Type Identifier Include file openecu.h and psc.h Enumerations PSC_ERROR_CODE_T

Error values for debugging when an error is found by the system start and idle feature (PSC), the feature calls a system error log function with an enumeration from this type. PSC_RC_T

An enumerated type which contains success and failure codes returned by some system start and idle feature (PSC) functions. Variables const U8 psc_watchdog_task_enabled

This determines whether the watchdog task is active or not. const BOOL psc_mem_runtime_checks_enabled

This determines whether run-time background memory checks are active or not. const U16 psc_app_major_ver_num

This is the major version number of the application. const U16 psc_app_minor_ver_num

This is the minor version number of the application. const U16 psc_app_sub_minor_ver_num

This is the subminor version number of the application. const U8 psc_app_name

This is the name of the application. const U8 psc_app_desc

This is a description of the application. const U8 psc_app_copyright

This is a copyright notice for the application.

Type Identifier const PHDR_HEADER_T psc_platform_header

The application data header which contains details of CPU initialisation, CCP settings, application version info, etc. Functions void psc_initialise_app

This function is invoked from the library between pre- initialisation and post-initialisation. void psc_background_app

This function is invoked by the library when no tasks are running. U8 psc_get_cpu_loading

Return the last calculated CPU loading. U8 psc_get_max_cpu_loading

Return the maximum CPU loading recorded since reset. PSC_RC_T psc_decode_reset

Determine the reason for the last reset and the duration from reset to the start of the application code. void psc_store_suicide_note

Store data across a reset. U32 psc_get_suicide_note

Recover data stored across a reset. U32 psc_get_reset_count

Return the reset count. U32 psc_get_unstable_reset_count

Return the reset count. PSC_RC_T psc_get_etpu_loading

Return the last calculated eTPU loading for an eTPU device. PSC_RC_T psc_get_max_etpu_loading

Return the maximum eTPU loading recorded since reset for an eTPU device. PSC_RC_T psc_get_hw_version

Return the hardware version information. PSC_RC_T psc_get_boot_version

Return the boot code version information. PSC_RC_T psc_get_boot_build_date

Type Identifier Return the boot code build date information. PSC_RC_T psc_get_boot_part_number

Return the boot code part number information. PSC_RC_T psc_get_prg_version

Return the reprogramming code version information. PSC_RC_T psc_get_prg_build_date

Return the reprogramming code build date information. PSC_RC_T psc_get_prg_part_number

Return the reprogramming code part number information. PSC_RC_T psc_get_platform_version

Return the platform code version information. PSC_RC_T psc_get_platform_build_date

Return the platform code build date information. PSC_RC_T psc_get_platform_part_number

Return the platform code part number information. PSC_RC_T psc_get_application_version

Return the application version information. PSC_RC_T psc_get_application_build_date

Return the application build date information. PSC_RC_T psc_int_ram_test_progress

Report the current progress of the internal RAM test. PSC_RC_T psc_int_rom_test_progress

Report the current progress of the internal ROM test. PSC_RC_T psc_int_ram_test_error_detected

Report the last recorded recoverable error detected during the internal RAM test. PSC_RC_T psc_int_rom_test_error_detected

Report the last recorded recoverable error detected during the internal ROM test. U32 psc_get_run_time

Get the run time of the ECU (the time the ECU has been powered without reset or loss of power). U32 psc_get_used_stack_size

Report the amount of stack used by the application and library code. void psc_watchdog_task

Type Identifier The watchdog handling task. void psc_kick_watchdog

Kick the watchdog to prevent the watchdog causing a reset. 5.3.3. Interface detail 5.3.3.1. Enumerations

5.3.3.1.1. PSC_ERROR_CODE_T

Summary: Error values for debugging when an error is found by the system start and idle feature (PSC), the feature calls a system error log function with an enumeration from this type.

Enumerations:

PSC_DECODE_RESET_INVALID_ARG Error raised if the decode reset function finds an invalid argument.

PSC_ERR_FORCED_RESET Error raised if the platform library forces a reset of the ECU.

PSC_ERR_VERSION_INVALID_PARAM Error raised if at least one of the version pointer arguments to a version function is invalid.

PSC_ERR_BUILD_DATE_INVALID_PARAM Error raised if at least one of the build date pointer arguments to a version function is invalid.

PSC_ERR_PART_NUMBER_INVALID_PARAM Error raised if at least one of the part number pointer arguments to a part-number function is invalid.

PSC_UNEXPECTED_CVN_CHANGE Error raised if the Calibration Verification Number calculation found an unexpected change in flash memory contents.

PSC_ERR_CELL_RETENTION Error raised if internal RAM failure detected.

PSC_ERR_ADDRESS_BUS Error raised if overspill RAM failure detected.

PSC_ERR_DATA_BUS Error raised if external RAM 1 failure detected.

PSC_ERR_HW_VERSION_UNKNOWN Error raised if hardware version is unknown. 5.3.3.1.2. PSC_RC_T

Summary: An enumerated type which contains success and failure codes returned by some system start and idle feature (PSC) functions.

Enumerations:

PSC_RC_OK Return code if everything progressed as expected.

PSC_RC_BAD_ARGS Return code if at least one of the arguments could not be used. 5.3.3.2. Variables

5.3.3.2.1. psc_watchdog_task_enabled

Definition: const U8 psc_watchdog_task_enabled

Description: This determines whether the watchdog task is active or not.

Set true to enable the watchdog task (which automatically kicks the watchdog on a periodic basis) or set false to disable the watchdog task (and handle watchdog functionality from within the application).

5.3.3.2.2. psc_mem_runtime_checks_enabled

Definition: const BOOL psc_mem_runtime_checks_enabled

Description: This determines whether run-time background memory checks are active or not.

Set true to enable the background tests of RAM, flash and non-volatile memory.

5.3.3.2.3. psc_app_major_ver_num

Definition: const U16 psc_app_major_ver_num

Description: This is the major version number of the application.

The complete version number takes the form major.minor.subminor. The application version number is referenced in the application header (psc_platform_header) and can be extracted from the final build image. Range: [0, 65535] unitless

5.3.3.2.4. psc_app_minor_ver_num

Definition: const U16 psc_app_minor_ver_num

Description: This is the minor version number of the application.

Range: [0, 65535] unitless

5.3.3.2.5. psc_app_sub_minor_ver_num

Definition: const U16 psc_app_sub_minor_ver_num

Description: This is the subminor version number of the application.

5.3.3.2.6. psc_app_name

Definition: const U8 psc_app_name[]

Description: This is the name of the application.

The name is a null-terminated string of ASCII characters. The name is referenced in the application header (psc_platform_header) and can be extracted from the final build image.

5.3.3.2.7. psc_app_desc

Definition: const U8 psc_app_desc[]

Description: This is a description of the application.

The description is a null-terminated string of ASCII characters. The description is referenced in the application header (psc_platform_header) and can be extracted from the final build image.

5.3.3.2.8. psc_app_copyright

Definition: const U8 psc_app_copyright[]

Description: This is a copyright notice for the application.

The copyright notice is a null-terminated string of ASCII characters. The copyright notice is referenced in the application header (psc_platform_header) and can be extracted from the final build image.

5.3.3.2.9. psc_platform_header

Definition: const PHDR_HEADER_T psc_platform_header

Description: The application data header which contains details of CPU initialisation, CCP settings, application version info, etc.

5.3.3.3. Functions 5.3.3.3.1. psc_initialise_app()

Definition: void psc_initialise_app(void)

Supported targets: All targets

Required license: None (Main library).

Description: This function is invoked from the library between pre-initialisation and post-initialisation.

The application must define this function. The application may use the function to initialise itself and configure the library (e.g., by calling pcx_declare_message()).

5.3.3.3.2. psc_background_app()

Definition: void psc_background_app(void)

Supported targets: All targets

Required license: None (Main library).

Description: This function is invoked by the library when no tasks are running.

The application must define this function. The application may use the function to perform any time or event independent processing.

5.3.3.3.3. psc_get_cpu_loading()

Definition: U8 psc_get_cpu_loading(void)

Supported targets: All targets

Required license: None (Main library).

Description: Return the last calculated CPU loading.

Return: The last calculated CPU loading. Range: [0, 100] % 5.3.3.3.4. psc_get_max_cpu_loading()

Definition: U8 psc_get_max_cpu_loading(void)

Supported targets: All targets

Required license: None (Main library).

Description: Return the maximum CPU loading recorded since reset.

Return: The maximum value of any previously calculated CPU loading since reset. Range: [0, 100] %

5.3.3.3.5. psc_decode_reset()

Definition: PSC_RC_T psc_decode_reset(U8 *pscf_power_reset, U8 *pscf_watchdog_reset, U8 *pscf_access_reset, U8 *pscf_fp_reset, U8 *pscf_mem_reset, U8 *pscf_forced_reset, U8 *pscf_other_reset, F32 *pscf_boot_duration)

Supported targets: All targets

Required license: None (Main library).

Description: Determine the reason for the last reset and the duration from reset to the start of the application code.

Arg (data out): pscf_power_reset Pointer to where the boolean result of whether the reset occurred due to a power cycle will be written. Set true if so, false otherwise. Cannot be NULL.

Arg (data out): pscf_watchdog_reset Pointer to where the boolean result of whether the reset occurred due to a watchdog timeout will be written. Set true if so, false otherwise. Cannot be NULL.

Arg (data out): pscf_access_reset Pointer to where the boolean result of whether the reset occurred due to an illegal memory access will be written. Set true if so, false otherwise. Cannot be NULL.

Arg (data out): pscf_fp_reset Pointer to where the boolean result of whether the reset occurred due to a floating point exception will be written. Set true if so, false otherwise. Cannot be NULL.

Arg (data out): pscf_mem_reset Pointer to where the Boolean result of whether the reset occurred due to an unrecoverable corruption of internal memory. Cannot be NULL.

Arg (data out): pscf_forced_reset Pointer to where the boolean result of whether the reset occurred due to a forced reset will be written. Set true if so, false otherwise. Cannot be NULL.

Arg (data out): pscf_other_reset Pointer to where the boolean result of whether an undetermined reset occurred. Set true if the reset could not be determined, false otherwise. Cannot be NULL.

Arg (data out): pscf_boot_duration A pointer to where the boot duration in seconds will be written. The boot duration is a rough estimate of time between the boot code starting to run and the scheduler starting all tasks (including the application tasks). Cannot be NULL.

Return:

• PSC_RC_OK - if successful action

• PSC_RC_BAD_ARGS - if configuration error 5.3.3.3.6. psc_store_suicide_note()

Definition: void psc_store_suicide_note(U32 pscf_note)

Supported targets: All targets

Required license: None (Main library).

Description: Store data across a reset.

The function stores a value that will survive a reset. This can be read back when the ECU restarts using the psc_get_suicide_note function.

Note

Data saved this way will not survive a power-cycle.

This function should not be called. It is intended only for testing purposes, and may be removed in future releases.

Arg (data in): pscf_note The data to save. 5.3.3.3.7. psc_get_suicide_note()

Definition: U32 psc_get_suicide_note(void)

Supported targets: All targets

Required license: None (Main library).

Description: Recover data stored across a reset.

The function returns the last value stored using the psc_store_suicide_note function. The data is reset to 0 during a power- on reset.

Note

This function should not be called. It is intended only for testing purposes, and may be removed in future releases.

Return: The data previously stored using the psc_store_suicide_note function. 5.3.3.3.8. psc_get_reset_count()

Definition: U32 psc_get_reset_count(void)

Supported targets: All targets

Required license: None (Main library).

Description: Return the reset count.

The function returns the free running count of the number of powered resets.

Note

The count is reset to one upon power cycle.

5.3.3.3.9. psc_get_unstable_reset_count()

Definition: U32 psc_get_unstable_reset_count(void)

Supported targets: All targets

Required license: None (Main library).

Description: Return the reset count.

The function returns the limited counter of powered resets that occur within 60 seconds of initialisation. It is cleared once the application been running for at least 60 seconds. If the unstable reset counter reaches 5, then the module will be forced in to reprogramming mode.

Note

The count is reset to one upon power cycle.

5.3.3.3.10. psc_get_etpu_loading()

Definition: PSC_RC_T psc_get_etpu_loading(PIO_ETPU_DEVICE_T pscf_etpu_device, U8 *pscf_etpu_loading)

Supported targets:

Required license: None (Main library).

Description: Return the last calculated eTPU loading for an eTPU device.

Arg (data in): pscf_etpu_device Identifies the eTPU device to report on. Use the macros included by the pio.h file, of the form PIO_ETPU_DEVICE_[NAME].

Arg (data out): pscf_etpu_loading The last calculated eTPU loading for the requested eTPU device. Range: [0, 100] %

Return:

• PSC_RC_OK - if successful

• PSC_RC_BAD_ARGS - if wrong eTPU device 5.3.3.3.11. psc_get_max_etpu_loading()

Definition: PSC_RC_T psc_get_max_etpu_loading(PIO_ETPU_DEVICE_T pscf_etpu_device, U8 *pscf_etpu_loading)

Supported targets:

Required license: None (Main library).

Description: Return the maximum eTPU loading recorded since reset for an eTPU device.

Arg (data in): pscf_etpu_device Identifies the eTPU device to report on. Use the macros included by the pio.h file, of the form PIO_ETPU_DEVICE_[NAME].

Arg (data out): pscf_etpu_loading The maximum value of any previously calculated eTPU loading since reset for the requested eTPU device. Range: [0, 100] %

Return:

• PSC_RC_OK - if successful

• PSC_RC_BAD_ARGS - if wrong eTPU device 5.3.3.3.12. psc_get_hw_version()

Definition: PSC_RC_T psc_get_hw_version(S16 *pscf_hw_ver)

Supported targets:

Required license: None (Main library).

Description: Return the hardware version information.

Return the detected version number for the hardware from the PCB.

Can raise the following errors: PSC_ERR_VERSION_INVALID_PARAM.

Arg (data out): pscf_hw_ver Pointer to a variable the function will write the hardware version to. Cannot be NULL. Range: [-1, 100], -1 if hardware version is unknown

Return:

• PSC_RC_OK - if successful action

• PSC_RC_BAD_ARGS - if configuration error 5.3.3.3.13. psc_get_boot_version()

Definition: PSC_RC_T psc_get_boot_version(U16 *pscf_major_ver, U16 *pscf_minor_ver, U16 *pscf_sub_minor_ver)

Supported targets: All targets

Required license: None (Main library).

Description: Return the boot code version information.

Return the major, minor and sub-minor version numbers for boot code programmed into the ECU.

Can raise the following errors: PSC_ERR_VERSION_INVALID_PARAM.

Arg (data out): pscf_major_ver Pointer to a variable the function will write the major version to. Cannot be NULL.

Arg (data out): pscf_minor_ver Pointer to a variable the function will write the minor version to. Cannot be NULL.

Arg (data out): pscf_sub_minor_ver Pointer to a variable the function will write the sub-minor version to. Cannot be NULL.

Return:

• PSC_RC_OK - if successful action

• PSC_RC_BAD_ARGS - if configuration error

5.3.3.3.14. psc_get_boot_build_date()

Definition: PSC_RC_T psc_get_boot_build_date(U16 *pscf_year, U16 *pscf_month, U16 *pscf_day)

Supported targets: All targets

Required license: None (Main library).

Description: Return the boot code build date information.

Return the year, month and day of the build date for boot code programmed into the ECU.

Can raise the following errors: PSC_ERR_BUILD_DATE_INVALID_PARAM.

Arg (data out): pscf_year Pointer to a variable the function will write the build year to. Cannot be NULL. Range: 0, 65535

Arg (data out): pscf_month Pointer to a variable the function will write the build month to. Cannot be NULL. Range: [1, 12] (representing January through December)

Arg (data out): pscf_day Pointer to a variable the function will write the build day to. Cannot be NULL. Range: [1, 31]

Return:

• PSC_RC_OK - if successful action

• PSC_RC_BAD_ARGS - if configuration error 5.3.3.3.15. psc_get_boot_part_number()

Definition: PSC_RC_T psc_get_boot_part_number(U8 *pscf_group, U8 *pscf_letter, U32 *pscf_id, U16 *pscf_issue)

Supported targets: All targets

Required license: None (Main library).

Description: Return the boot code part number information.

Return the group ID number, group ID letter, part ID number and issue ID number of the boot code programmed into the ECU.

Can raise the following errors: PSC_ERR_PART_NUMBER_INVALID_PARAM.

Arg (data out): pscf_group Pointer to a variable the function will write the group id number to. Cannot be NULL. Range: 0, 99

Arg (data out): pscf_letter Pointer to a variable the function will write the group letter to. Cannot be NULL. Range: 0, 255

Arg (data out): pscf_id Pointer to a variable the function will write the part id number to. Cannot be NULL. Range: 0, 999999

Arg (data out): pscf_issue Pointer to a variable the function will write the part issue number to. Cannot be NULL. Range: [0, 65535]

Return:

• PSC_RC_OK - if successful action

• PSC_RC_BAD_ARGS - if configuration error 5.3.3.3.16. psc_get_prg_version()

Definition: PSC_RC_T psc_get_prg_version(U16 *pscf_major_ver, U16 *pscf_minor_ver, U16 *pscf_sub_minor_ver)

Supported targets: All targets

Required license: None (Main library).

Description: Return the reprogramming code version information.

Return the major, minor and sub-minor version numbers for reprogramming code programmed into the ECU.

Can raise the following errors: PSC_ERR_VERSION_INVALID_PARAM.

Arg (data out): pscf_major_ver Pointer to a variable the function will write the major version to. Cannot be NULL.

Arg (data out): pscf_minor_ver Pointer to a variable the function will write the minor version to. Cannot be NULL.

Arg (data out): pscf_sub_minor_ver Pointer to a variable the function will write the sub-minor version to. Cannot be NULL.

Return:

• PSC_RC_OK - if successful action

• PSC_RC_BAD_ARGS - if configuration error

5.3.3.3.17. psc_get_prg_build_date()

Definition: PSC_RC_T psc_get_prg_build_date(U16 *pscf_year, U16 *pscf_month, U16 *pscf_day)

Supported targets: All targets

Required license: None (Main library).

Description: Return the reprogramming code build date information.

Return the year, month and day of the build date for reprogramming code programmed into the ECU.

Can raise the following errors: PSC_ERR_BUILD_DATE_INVALID_PARAM.

Arg (data out): pscf_year Pointer to a variable the function will write the build year to. Cannot be NULL. Range: 0, 65535

Arg (data out): pscf_month Pointer to a variable the function will write the build month to. Cannot be NULL. Range: [1, 12] (representing January through December)

Arg (data out): pscf_day Pointer to a variable the function will write the build day to. Cannot be NULL. Range: [1, 31]

Return:

• PSC_RC_OK - if successful action

• PSC_RC_BAD_ARGS - if configuration error

5.3.3.3.18. psc_get_prg_part_number()

Definition: PSC_RC_T psc_get_prg_part_number(U8 *pscf_group, U8 *pscf_letter, U32 *pscf_id, U16 *pscf_issue)

Supported targets: All targets

Required license: None (Main library).

Description: Return the reprogramming code part number information.

Return the group ID number, group ID letter, part ID number and issue ID number of the reprogramming code programmed into the ECU.

Can raise the following errors: PSC_ERR_PART_NUMBER_INVALID_PARAM.

Arg (data out): pscf_group Pointer to a variable the function will write the group id number to. Cannot be NULL. Range: 0, 99

Arg (data out): pscf_letter Pointer to a variable the function will write the group letter to. Cannot be NULL. Range: 0, 255

Arg (data out): pscf_id Pointer to a variable the function will write the part id number to. Cannot be NULL. Range: 0, 999999

Arg (data out): pscf_issue Pointer to a variable the function will write the part issue number to. Cannot be NULL. Range: [0, 65535]

Return:

• PSC_RC_OK - if successful action

• PSC_RC_BAD_ARGS - if configuration error 5.3.3.3.19. psc_get_platform_version()

Definition: PSC_RC_T psc_get_platform_version(U16 *pscf_major_ver, U16 *pscf_minor_ver, U16 *pscf_sub_minor_ver)

Supported targets: All targets

Required license: None (Main library).

Description: Return the platform code version information.

Return the major, minor and sub-minor version numbers for platform code programmed into the ECU.

Can raise the following errors: PSC_ERR_VERSION_INVALID_PARAM.

Arg (data out): pscf_major_ver Pointer to a variable the function will write the major version to. Cannot be NULL.

Arg (data out): pscf_minor_ver Pointer to a variable the function will write the minor version to. Cannot be NULL.

Arg (data out): pscf_sub_minor_ver Pointer to a variable the function will write the sub-minor version to. Cannot be NULL.

Return:

• PSC_RC_OK - if successful action

• PSC_RC_BAD_ARGS - if configuration error 5.3.3.3.20. psc_get_platform_build_date()

Definition: PSC_RC_T psc_get_platform_build_date(U16 *pscf_year, U16 *pscf_month, U16 *pscf_day)

Supported targets: All targets

Required license: None (Main library).

Description: Return the platform code build date information.

Return the year, month and day of the build date for platform code programmed into the ECU.

Can raise the following errors: PSC_ERR_BUILD_DATE_INVALID_PARAM.

Arg (data out): pscf_year Pointer to a variable the function will write the build year to. Cannot be NULL. Range: 0, 65535

Arg (data out): pscf_month Pointer to a variable the function will write the build month to. Cannot be NULL. Range: [1, 12] (representing January through December)

Arg (data out): pscf_day Pointer to a variable the function will write the build day to. Cannot be NULL. Range: [1, 31]

Return:

• PSC_RC_OK - if successful action

• PSC_RC_BAD_ARGS - if configuration error 5.3.3.3.21. psc_get_platform_part_number()

Definition: PSC_RC_T psc_get_platform_part_number(U8 *pscf_group, U8 *pscf_letter, U32 *pscf_id, U16 *pscf_issue)

Supported targets: All targets

Required license: None (Main library).

Description: Return the platform code part number information.

Return the group ID number, group ID letter, part ID number and issue ID number of the platform code programmed into the ECU.

Can raise the following errors: PSC_ERR_PART_NUMBER_INVALID_PARAM.

Arg (data out): pscf_group Pointer to a variable the function will write the group id number to. Cannot be NULL. Range: 0, 99

Arg (data out): pscf_letter Pointer to a variable the function will write the group letter to. Cannot be NULL. Range: 0, 255

Arg (data out): pscf_id Pointer to a variable the function will write the part id number to. Cannot be NULL. Range: 0, 999999

Arg (data out): pscf_issue Pointer to a variable the function will write the part issue number to. Cannot be NULL. Range: [0, 65535]

Return:

• PSC_RC_OK - if successful action

• PSC_RC_BAD_ARGS - if configuration error 5.3.3.3.22. psc_get_application_version()

Definition: PSC_RC_T psc_get_application_version(U16 *pscf_major_ver, U16 *pscf_minor_ver, U16 *pscf_sub_minor_ver)

Supported targets: All targets

Required license: None (Main library).

Description: Return the application version information.

Return the major, minor and sub-minor version numbers for application programmed into the ECU.

Can raise the following errors: PSC_ERR_VERSION_INVALID_PARAM.

Arg (data in): pscf_major_ver Pointer to a variable the function will write the major version to. Cannot be NULL.

Arg (data in): pscf_minor_ver Pointer to a variable the function will write the minor version to. Cannot be NULL.

Arg (data in): pscf_sub_minor_ver Pointer to a variable the function will write the sub-minor version to.

Cannot be NULL.

Return:

• PSC_RC_OK - if successful action

• PSC_RC_BAD_ARGS - if configuration error 5.3.3.3.23. psc_get_application_build_date()

Definition: PSC_RC_T psc_get_application_build_date(U16 *pscf_year, U16 *pscf_month, U16 *pscf_day)

Supported targets: All targets

Required license: None (Main library).

Description: Return the application build date information.

Return the year, month and day of the build date for the application programmed into the ECU.

Can raise the following errors: PSC_ERR_BUILD_DATE_INVALID_PARAM.

Arg (data in): pscf_year Pointer to a variable the function will write the build year to. Cannot be NULL. Range: 0, 65535

Arg (data in): pscf_month Pointer to a variable the function will write the build month to. Cannot be NULL. Range: [1, 12] (representing January through December)

Arg (data in): pscf_day Pointer to a variable the function will write the build day to. Cannot be NULL. Range: [1, 31]

Return:

• PSC_RC_OK - if successful action

• PSC_RC_BAD_ARGS - if configuration error 5.3.3.3.24. psc_int_ram_test_progress()

Definition: PSC_RC_T psc_int_ram_test_progress(U32 *pscf_start_address, U32 *pscf_end_address, U32 *pscf_current_address)

Supported targets:

Required license: None (Main library).

Description: Report the current progress of the internal RAM test.

The internal RAM test continuously cycles through the internal RAM and checks for errors. One bit errors that are detected in aligned 64- bit accesses are automatically corrected and are reported through the associated error reporting function. Two bit or greater errors are not recoverable and will immediately trigger a reset. The application may determine the reason for the reset.

Arg (data out): pscf_start_address Pointer to where to write the first address of the internal RAM test. Cannot be NULL.

Arg (data out): pscf_end_address Pointer to where to write the end address of the internal RAM test. Cannot be NULL.

Arg (data out): pscf_current_address Pointer to where to write the current address of the internal RAM test. Cannot be NULL.

Return:

• PSC_RC_OK - if parameters are not NULL.

• PSC_RC_BAD_ARGS - if one or more parameters are NULL. 5.3.3.3.25. psc_int_rom_test_progress()

Definition: PSC_RC_T psc_int_rom_test_progress(U32 *pscf_start_address, U32 *pscf_end_address, U32 *pscf_current_address)

Supported targets:

Required license: None (Main library).

Description: Report the current progress of the internal ROM test.

The internal RAM test continuously cycles through the internal ROM and checks for errors. One bit errors that are detected in aligned 64- bit accesses are automatically corrected and are reported through the associated error reporting function. Two bit or greater errors are not recoverable and will immediately trigger a reset. The application may determine the reason for the reset.

Arg (data out): pscf_start_address Pointer to where to write the first address of the internal ROM test. Cannot be NULL.

Arg (data out): pscf_end_address Pointer to where to write the end address of the internal ROM test. Cannot be NULL.

Arg (data out): pscf_current_address Pointer to where to write the current address of the internal ROM test. Cannot be NULL.

Return:

• PSC_RC_OK - if parameters are not NULL.

• PSC_RC_BAD_ARGS - if one or more parameters are NULL. 5.3.3.3.26. psc_int_ram_test_error_detected()

Definition: PSC_RC_T psc_int_ram_test_error_detected(BOOL *pscf_error_detected, U32 *pscf_error_address)

Supported targets:

Required license: None (Main library).

Description: Report the last recorded recoverable error detected during the internal RAM test.

Arg (data out): pscf_error_detected Pointer to where to write the boolean result of whether a recoverable internal RAM fault has been detected. Set true if so, false otherwise. Cannot be NULL.

Arg (data out): pscf_error_address Pointer to where to write the address of the last recoverable internal RAM fault. Cannot be NULL.

Return:

• PSC_RC_OK - if parameters are not NULL.

• PSC_RC_BAD_ARGS - if one or more parameters are NULL. 5.3.3.3.27. psc_int_rom_test_error_detected()

Definition: PSC_RC_T psc_int_rom_test_error_detected(BOOL *pscf_error_detected, U32 *pscf_error_address)

Supported targets:

Required license: None (Main library).

Description: Report the last recorded recoverable error detected during the internal ROM test.

Arg (data out): pscf_error_detected Pointer to where to write the boolean result of whether a recoverable internal ROM fault has been detected. Set true if so, false otherwise. Cannot be NULL.

Arg (data out): pscf_error_address Pointer to where to write the address of the last recoverable internal ROM fault. Cannot be NULL.

Return:

• PSC_RC_OK - if parameters are not NULL.

• PSC_RC_BAD_ARGS - if one or more parameters are NULL.

5.3.3.3.28. psc_get_run_time()

Definition: U32 psc_get_run_time(void)

Supported targets: All targets

Required license: None (Main library).

Description: Get the run time of the ECU (the time the ECU has been powered without reset or loss of power).

Return: The run time. Range: [0, 4294967295] seconds

5.3.3.3.29. psc_get_used_stack_size()

Definition: U32 psc_get_used_stack_size(void)

Supported targets: All targets

Required license: None (Main library).

Description: Report the amount of stack used by the application and library code.

Return: The size of stack used by the application and library code. Range: [0, 4294967295] bytes

5.3.3.3.30. psc_watchdog_task()

Definition: void psc_watchdog_task(void)

Supported targets: All targets

Required license: None (Main library).

Description: The watchdog handling task.

This is the entry point for the watchdog handling task. The task ensures the watchdog does not timeout and cause a reset (which can be determined by calling psc_decode_reset()).

The watchdog handling task is assigned a low priority relative to other tasks. This includes the application tasks. It is important that application tasks do not run for longer than the watchdog timeout period, otherwise the ECU will reset.

The watchdog task is enabled when psc_watchdog_task_enabled is set true. If set false, the application may control when the watchdog is kicked by calling psc_kick_watchdog() (or not).

Note

The watchdog handling task must be scheduled every 200 milliseconds. The period of the watchdog is hard coded by the library and cannot be modified by the application.

5.3.3.3.31. psc_kick_watchdog()

Definition: void psc_kick_watchdog(void)

Supported targets: All targets

Required license: None (Main library).

Description: Kick the watchdog to prevent the watchdog causing a reset.

Kick the main processor's watchdog to prevent a reset. This function should only be called when the watchdog task is disabled (by setting psc_watchdog_task_enabled false).

Note

The watchdog handling must be scheduled periodically greater than 200 milliseconds. The period of the watchdog is hard coded by the library and cannot be modified by the application. 5.4. ECU registry information (PREG) 5.4.1. Overview

The feature provides access to the ECU's registry. The registry represents data that is specific to the ECU, such as the ECU's date of manufacture or serial number. Read access to the registry is provided through the preg_retrieve_value_from_key() function. Write access is not permitted.

The registry contains various pieces of structured data, represented as a set of key-value pairs. To read the registry, an appropriate key is passed to preg_retrieve_value_from_key(). In turn the function searches the registry for a matching key and if found, extracts the value part of the pair into a buffer provided by the caller.

Table 5.3. Registry entries

Key Enumeration Serial number PREG_KEY_SERIAL_NUM Date of manufacture PREG_KEY_DATE_OF_MANUFACTURE Engineering part number PREG_KEY_ENG_PART_NUM Hardware issue and modification level PREG_KEY_HW_ISSUE_MOD_NUM Factory part number PREG_KEY_FACTORY_PART_NUM Factory part number build type PREG_KEY_FACTORY_BUILD_TYPE

For a description of each key-value pair, see the enumeration and structures referred to in the previous table.

Note

Not all ECUs have registry information programmed. The preg_is_data_available() function will return whether registry information is available or not.

5.4.2. Interface index

An index of interface objects for this feature.

Type Identifier Include file openecu.h and preg.h Enumerations PREG_RC_T

An enumerated type which contains success and failure codes returned by some registry feature (PREG) functions. PREG_KEY_T

An enumerated type which represents each of the keys supported by this feature. Data types PREG_VALUE_SERIAL_NUM_T

A structure which represents the data for the ECU's serial number key, see PREG_KEY_SERIAL_NUM. PREG_VALUE_SERIAL_NUM_LONG_T

A structure which represents the data for the ECU's serial number key, see PREG_KEY_SERIAL_NUM_LONG. PREG_VALUE_DATE_OF_MANUFACTURE_T

A structure which represents the structured data for the ECU's date of manufacture key, see PREG_KEY_DATE_OF_MANUFACTURE. PREG_VALUE_ENG_PART_NUM_T

Type Identifier A structure which represents the structured data for the ECU's engineering part number key, see PREG_KEY_ENG_PART_NUM. PREG_VALUE_HW_ISSUE_MOD_NUM_T

A structure which represents the structured data for the ECU's issue-mod key, see PREG_KEY_HW_ISSUE_MOD_NUM. PREG_VALUE_FACTORY_PART_NUM_T

A structure which represents the structured data for the ECU's factory part number key,. PREG_VALUE_FACTORY_BUILD_TYPE_T

A structure which represents the structured data for the ECU's factory part number build type key, see PREG_KEY_FACTORY_BUILD_TYPE. PREG_VALUE_DEV_HW_T

A structure which represents the structured data for the ECU's developer hardware configuration see PREG_KEY_DEV_HW. Functions BOOL preg_is_data_available

Determine whether the registry is available or not. PREG_RC_T preg_retrieve_value_from_key

Retrieve the value for a registry key. PREG_SEEK_RC_T preg_seek_key

trys to find the key PREG_SEEK_RC_T preg_write_key_data_to_ram

writes the data to the selected key PREG_SEEK_RC_T preg_write_ram_data_to_flash

writes the RAM buffer to the shadow area 5.4.3. Interface detail 5.4.3.1. Enumerations

5.4.3.1.1. PREG_RC_T

Summary: An enumerated type which contains success and failure codes returned by some registry feature (PREG) functions.

Enumerations:

PREG_RC_OK Return code if everything progressed as expected.

PREG_RC_BAD_ARGS Return code if at least one of the arguments could not be used.

PREG_RC_INVALID_KEY Return code if the key argument is not one recognised by the feature.

PREG_RC_NOT_FOUND Return code if the key argument could not be found in the registry when retrieving the key's value.

5.4.3.1.2. PREG_KEY_T

Summary: An enumerated type which represents each of the keys supported by this feature.

Enumerations:

PREG_KEY_SERIAL_NUM The key for the ECU's serial number, see PREG_VALUE_SERIAL_NUM_T for the associated data.

PREG_KEY_DATE_OF_MANUFACTURE The key for the ECU's date of manufacture, see PREG_VALUE_DATE_OF_MANUFACTURE_T for the associated data.

PREG_KEY_ENG_PART_NUM The key for the ECU's engineering part number, see PREG_VALUE_ENG_PART_NUM_T for the associated data.

PREG_KEY_HW_ISSUE_MOD_NUM The key for the ECU's mod and issue number, see PREG_VALUE_HW_ISSUE_MOD_NUM_T for the associated data.

PREG_KEY_FACTORY_PART_NUM The key for the ECU's factory part number, see PREG_VALUE_FACTORY_PART_NUM_T for the associated data.

PREG_KEY_FACTORY_BUILD_TYPE The key for the ECU's factory part number build type, see PREG_VALUE_FACTORY_BUILD_TYPE_T for the associated data.

PREG_KEY_RESERVED_1

PREG_KEY_SERIAL_NUM_LONG The key for the ECU's long serial number, see PREG_VALUE_SERIAL_NUM_LONG_T for the associated data.

PREG_KEY_RESERVED_3

PREG_KEY_RESERVED_4

PREG_KEY_DEV_HW The key for the ECU's ECU's developer hardware configuration, see PREG_VALUE_DEV_HW_T for the associated data.

Description: An enumerated type which represents each of the keys supported by this feature.

A key is a reference associated to some structured data. For instance, the PREG_KEY_SERIAL_NUM key is associated with the ECU's 32-bit serial number. 5.4.3.2. Data types 5.4.3.2.1. PREG_VALUE_SERIAL_NUM_T

Summary: A structure which represents the data for the ECU's serial number key, see PREG_KEY_SERIAL_NUM.

Members:

U32 PREG_VALUE_SERIAL_NUM_T::serial_num The serial number is a 32-bit positive integer.

Description:

A structure which represents the data for the ECU's serial number key, see PREG_KEY_SERIAL_NUM.

The serial number is a 32-bit positive integer. Serial numbers across different families of ECUs do not overlap. 5.4.3.2.2. PREG_VALUE_SERIAL_NUM_LONG_T

Summary: A structure which represents the data for the ECU's serial number key, see PREG_KEY_SERIAL_NUM_LONG.

Members:

U64 PREG_VALUE_SERIAL_NUM_LONG_T::serial_num The serial number is a 48-bit positive integer.

Description:

A structure which represents the data for the ECU's serial number key, see PREG_KEY_SERIAL_NUM_LONG.

The serial number is a 48-bit positive integer. Serial numbers across different families of ECUs do not overlap. 5.4.3.2.3. PREG_VALUE_DATE_OF_MANUFACTURE_T

Summary: A structure which represents the structured data for the ECU's date of manufacture key, see PREG_KEY_DATE_OF_MANUFACTURE.

Members:

U8 PREG_VALUE_DATE_OF_MANUFACTURE_T::shift The team shift at time of manufacture.

Range: [1, 3]

U8 PREG_VALUE_DATE_OF_MANUFACTURE_T::day The day of the month of manufacture.

Range: [1, 31]

U8 PREG_VALUE_DATE_OF_MANUFACTURE_T::month The month of manufacture.

Range: [1, 12]

U16 PREG_VALUE_DATE_OF_MANUFACTURE_T::year The year of manufacture.

Range: [2010, ..]

Description:

A structure which represents the structured data for the ECU's date of manufacture key, see PREG_KEY_DATE_OF_MANUFACTURE.

The date is composed as (shift) dd:mm:yyyy, where the shift identifies the team involved in the manufacturing process. 5.4.3.2.4. PREG_VALUE_ENG_PART_NUM_T

Summary: A structure which represents the structured data for the ECU's engineering part number key, see PREG_KEY_ENG_PART_NUM.

Members:

U8 PREG_VALUE_ENG_PART_NUM_T::prefix The part number prefix.

Range: [0, 99]

U8 PREG_VALUE_ENG_PART_NUM_T::letter The part number letter represented as an ASCII character.

Range: [A, Z]

U32 PREG_VALUE_ENG_PART_NUM_T::eng_part_num The engineering part number.

Range: [0, 999999]

Description:

A structure which represents the structured data for the ECU's engineering part number key, see PREG_KEY_ENG_PART_NUM.

The engineering part number matches the pattern: prefix letter engineering-part-number. For instance, the engineering part number assigned to the M250-000 is '01T068165', where '01' represents the prefix, 'T' represents the letter and '068165' represents the engineering part number. 5.4.3.2.5. PREG_VALUE_HW_ISSUE_MOD_NUM_T

Summary: A structure which represents the structured data for the ECU's issue- mod key, see PREG_KEY_HW_ISSUE_MOD_NUM.

Members:

U8 PREG_VALUE_HW_ISSUE_MOD_NUM_T::issue The PCB issue level.

Range: [0, 255]

U8 PREG_VALUE_HW_ISSUE_MOD_NUM_T::mod The PCB modification level.

Range: [0, 255]

Description:

A structure which represents the structured data for the ECU's issue- mod key, see PREG_KEY_HW_ISSUE_MOD_NUM.

The issue level represents a specific design of PCB. Changes to the issue level may have an effect on the platform library.

The modification level represents what changes were performed to the PCB after manufacturing to correct issue level design mistakes. Changes to the modification level should not have an effect on the platform library. 5.4.3.2.6. PREG_VALUE_FACTORY_PART_NUM_T

Summary: A structure which represents the structured data for the ECU's factory part number key,.

Members:

U16 PREG_VALUE_FACTORY_PART_NUM_T::part_num[2] Each numeric part of the factory part number.

Range: [0, 65535]

U8 PREG_VALUE_FACTORY_PART_NUM_T::letter[2] The identifier which separates each factory part number, represented as ASCII characters.

Range: [A, Z]

Description:

A structure which represents the structured data for the ECU's factory part number key,.

For instance, the factory part number could be '450FT1034', where '450' represents the part_num[0], 'F' represents the letter[0], 'T' represents the letter[1], and '1034' represents the part_num[1]. see PREG_KEY_FACTORY_PART_NUM. 5.4.3.2.7. PREG_VALUE_FACTORY_BUILD_TYPE_T

Summary: A structure which represents the structured data for the ECU's factory part number build type key, see PREG_KEY_FACTORY_BUILD_TYPE.

Members:

U8 PREG_VALUE_FACTORY_BUILD_TYPE_T::build_type[2] The factory part number build type, represented as ASCII characters.

Range: [A, Z] 5.4.3.2.8. PREG_VALUE_DEV_HW_T

Summary: A structure which represents the structured data for the ECU's developer hardware configuration see PREG_KEY_DEV_HW.

Members:

BOOL PREG_VALUE_DEV_HW_T::xetk_present The ETAS XETK memory emulator is present on the ECU Range: [0, 1]. 5.4.3.3. Functions 5.4.3.3.1. preg_is_data_available()

Definition: BOOL preg_is_data_available(void)

Supported targets: All targets

Required license: None (Main library).

Description: Determine whether the registry is available or not.

Note that not all ECUs have registry information available. Early builds of some ECUs have no registry information programmed.

Return: True if registry data available, false otherwise. 5.4.3.3.2. preg_retrieve_value_from_key()

Definition: PREG_RC_T preg_retrieve_value_from_key(PREG_KEY_T pregf_key, void *pregf_value_buffer)

Supported targets: All targets

Required license: None (Main library).

Description: Retrieve the value for a registry key.

Search through the registry for a matching key and if found, write the value data for the key to the supplied buffer.

The function performs a linear search and as such, should be called only when necessary to reduce CPU overhead.

Arg (data in): pregf_key The key to retrieve information about. Must be one of the PREG_KEY_T enumerations.

Arg (data out): pregf_value_buffer A pointer to an object declared of suitable type for the key. The object is written with the data values related to the key if the key is found in the registry. The object for a key can be derived from the key enumeration literal. Keys that match PREG_KEY_* correspond to struct types named PREG_VALUE_*_T. For instance, if pregf_key is set to PREG_KEY_SERIAL_NUM then pregf_value_buffer must point to an object of type PREG_VALUE_SERIAL_NUM_T.

Cannot be NULL.

Return:

• PREG_RC_OK if value retrieved from registry

• another enumeration from PREG_RC_T otherwise. 5.4.3.3.3. preg_seek_key()

Definition: PREG_SEEK_RC_T preg_seek_key(U16 pregf_seek_key_ID, U16 *pregf_key_offset, U8 *pregf_key_data)

Description: trys to find the key

Arg (data in): pregf_seek_key_ID The requested value for the registry ID.

Arg (data in): pregf_key_offset A pointer to and object declareed of suitable type. The object is set to offset if it does not equal NULL. Where the offset is the number of bits between the requested key value and the closest found key.

Arg (data in): pregf_key_data The data of the key if a value PREG_SEEK_RC_OK is returned and the key is found.

Return:

• seek_key_state with PREG_SEEK_RC_OK if the key is found, PREG_SEEK_RC_NOT_FOUND if key is not found, or PREG_SEEK_RC_OUT_OF_SPACE 5.4.3.3.4. preg_write_key_data_to_ram()

Definition: PREG_SEEK_RC_T preg_write_key_data_to_ram(U16 pregf_key_ID, U8 *pregf_key_data)

Description: writes the data to the selected key

Arg (data in): pregf_key_ID The value of the registry ID.

Arg (data out): pregf_key_data A pointer to the value of the data of the registry key.

Return:

• PREG_SEEK_RC_NOT_FOUND if the key could not be found for the key ID specified in preg_key_ID.

• PREG_SEEK_RC_OK if the key was properly found.

• PREG_SEEK_RC_OUT_OF_SPACE if there is no room.

• PREG_SEEK_RC_NO_KEY_SELECTED if the has not been sought. 5.4.3.3.5. preg_write_ram_data_to_flash()

Definition: PREG_SEEK_RC_T preg_write_ram_data_to_flash(void)

Description: writes the RAM buffer to the shadow area

Return:

• PREG_SEEK_RC_OK if the reprogramming was successful.

• PREG_SEEK_RC_NO_KEY_SELECTED if there was an issue with programming. 5.5. System timing feature (PTM) 5.5.1. Overview

The system timing feature provides access to second, millisecond and microsecond timers through the ptm_get_s_time() , ptm_get_ms_time() and ptm_get_us_time() functions. All timers wrap to zero when they increment past their maximum value.

The feature provides access to a timer running at the processor's clock rate (or multiple there of) through the ptm_get_sys_time() function. The return value from this function can be converted to microseconds by dividing it by PTM_SYS_TIME_TO_US.

The feature provides functions to calculate the difference in time between the current time and the return value from a previous call to read a timer (ptm_s_time_diff(), ptm_ms_time_diff(), ptm_us_time_diff() and ptm_sys_time_diff()). The results of calling these functions is undefined if more time has past than the timer can record. 5.5.2. Interface index

An index of interface objects for this feature.

Type Identifier Include file openecu.h and ptm.h Macros PTM_SYS_TIME_TO_US

This is the division factor to convert from system time (returned by calling ptm_get_sys_time()) into microseconds. Functions U32 ptm_get_sys_time

Return a free running 32-bit system timer. U32 ptm_sys_time_diff

Return the difference between the current system timer and a snapshot of that timer from a call to ptm_get_sys_time(). U32 ptm_sys_time_diff_update

Return the difference between the current system timer and a snapshot of that timer from a call to

Type Identifier ptm_get_sys_time() and ptm_sys_time_diff_update(), updating the snapshot for the next call. U32 ptm_get_s_time

Return a free running 32-bit second timer. U32 ptm_s_time_diff

Return the difference between the current second timer and a snapshot of that timer from a call to ptm_get_s_time(). U32 ptm_s_time_diff_update

Return the difference between the current second timer and a snapshot of that timer from a call to ptm_get_s_time() and ptm_s_time_diff_update(), updating the snapshot for the next call. U32 ptm_get_ms_time

Return a free running 32-bit millisecond timer. U32 ptm_ms_time_diff

Return the difference between the current millisecond timer and a snapshot of that timer from a call to ptm_get_ms_time(). U32 ptm_ms_time_diff_update

Return the difference between the current millisecond timer and a snapshot of that timer from a call to ptm_get_ms_time() and ptm_ms_time_diff_update(), updating the snapshot for the next call. U32 ptm_get_us_time

Return a free running 32-bit microsecond timer. U32 ptm_us_time_diff

Return the difference between the current microsecond timer and a snapshot of that timer from a call to ptm_get_us_time(). U32 ptm_us_time_diff_update

Return the difference between the current microsecond timer and a snapshot of that timer from a call to ptm_get_us_time() and ptm_us_time_diff_update(), updating the snapshot for the next call. 5.5.3. Interface detail 5.5.3.1. Macros

5.5.3.1.1. PTM_SYS_TIME_TO_US

Definition: #define PTM_SYS_TIME_TO_US (PTM_INT_SYS_TIME_TO_US)

Description:

This is the division factor to convert from system time (returned by calling ptm_get_sys_time()) into microseconds. 5.5.3.2. Functions

5.5.3.2.1. ptm_get_sys_time()

Definition: U32 ptm_get_sys_time(void)

Supported targets: All targets

Required license: None (Main library).

Description: Return a free running 32-bit system timer.

The system timer is a free running 32-bit timer. The timer increments, and wraps to zero when it overflows rather than saturating. The timer can be converted to microseconds by dividing by PTM_SYS_TIME_TO_US.

Return: The current value of the system timer. Range: [0, 4294967295] ticks

5.5.3.2.2. ptm_sys_time_diff()

Definition: U32 ptm_sys_time_diff(U32 ptmf_time)

Supported targets: All targets

Required license: None (Main library).

Description: Return the difference between the current system timer and a snapshot of that timer from a call to ptm_get_sys_time().

Arg (data in): ptmf_time The result of calling ptm_get_sys_time(). Range: [0, 4294967295] ticks

Return: The difference in time between the current value of the system timer and ptmf_time. Range: [0, 4294967295] ticks

5.5.3.2.3. ptm_sys_time_diff_update()

Definition: U32 ptm_sys_time_diff_update(U32 *ptmf_time)

Supported targets: All targets

Required license: None (Main library).

Description: Return the difference between the current system timer and a snapshot of that timer from a call to ptm_get_sys_time() and ptm_sys_time_diff_update(), updating the snapshot for the next call.

Arg (data in): ptmf_time Pointer to the last snapshot of time (either by calling ptm_get_sys_time() initially, or ptm_sys_time_diff_update() subsequently). Range: [0, 4294967295] ticks

Return: The difference in time between the current value of the system timer and ptmf_time. Range: [0, 4294967295] ticks 5.5.3.2.4. ptm_get_s_time()

Definition: U32 ptm_get_s_time(void)

Supported targets: All targets

Required license: None (Main library).

Description: Return a free running 32-bit second timer.

The second timer is a free running 32-bit timer. The timer increments each second and wraps to zero when it overflows rather than saturating.

Return: The current value of the second timer. Range: [0, 4294967295] seconds 5.5.3.2.5. ptm_s_time_diff()

Definition: U32 ptm_s_time_diff(U32 ptmf_time)

Supported targets: All targets

Required license: None (Main library).

Description: Return the difference between the current second timer and a snapshot of that timer from a call to ptm_get_s_time().

Arg (data in): ptmf_time The result of calling ptm_get_s_time(). Range: [0, 4294967295] seconds

Return: The difference in time between the current value of the second timer and ptmf_time.

Range: [0, 4294967295] seconds 5.5.3.2.6. ptm_s_time_diff_update()

Definition: U32 ptm_s_time_diff_update(U32 *ptmf_time)

Supported targets: All targets

Required license: None (Main library).

Description: Return the difference between the current second timer and a snapshot of that timer from a call to ptm_get_s_time() and ptm_s_time_diff_update(), updating the snapshot for the next call.

Arg (data in): ptmf_time Pointer to the last snapshot of time (either by calling ptm_get_s_time() initially, or ptm_s_time_diff_update() subsequently). Range: [0, 4294967295] seconds

Return: The difference in time between the current value of the second timer and ptmf_time. Range: [0, 4294967295] seconds 5.5.3.2.7. ptm_get_ms_time()

Definition: U32 ptm_get_ms_time(void)

Supported targets: All targets

Required license: None (Main library).

Description: Return a free running 32-bit millisecond timer.

The millisecond timer is a free running 32-bit timer. The timer increments each millisecond and wraps to zero when it overflows rather than saturating.

Return: The current value of the millisecond timer. Range: [0, 4294967295] milliseconds 5.5.3.2.8. ptm_ms_time_diff()

Definition: U32 ptm_ms_time_diff(U32 ptmf_time)

Supported targets: All targets

Required license: None (Main library).

Description: Return the difference between the current millisecond timer and a snapshot of that timer from a call to ptm_get_ms_time().

Arg (data in): ptmf_time The result of calling ptm_get_ms_time(). Range: [0, 4294967295] milliseconds

Return: The difference in time between the current value of the millisecond timer and ptmf_time. Range: [0, 4294967295] milliseconds

5.5.3.2.9. ptm_ms_time_diff_update()

Definition: U32 ptm_ms_time_diff_update(U32 *ptmf_time)

Supported targets: All targets

Required license: None (Main library).

Description: Return the difference between the current millisecond timer and a snapshot of that timer from a call to ptm_get_ms_time() and ptm_ms_time_diff_update(), updating the snapshot for the next call.

Arg (data in): ptmf_time Pointer to the last snapshot of time (either by calling ptm_get_ms_time() initially, or ptm_ms_time_diff_update() subsequently). Range: [0, 4294967295] milliseconds

Return: The difference in time between the current value of the millisecond timer and ptmf_time. Range: [0, 4294967295] milliseconds

5.5.3.2.10. ptm_get_us_time()

Definition: U32 ptm_get_us_time(void)

Supported targets: All targets

Required license: None (Main library).

Description: Return a free running 32-bit microsecond timer.

The microsecond timer is a free running 32-bit timer. The timer increments each microsecond and wraps to zero when it overflows rather than saturating.

Return: The current value of the microsecond timer.

Range: [0, 4294967295] microseconds 5.5.3.2.11. ptm_us_time_diff()

Definition: U32 ptm_us_time_diff(U32 ptmf_time)

Supported targets: All targets

Required license: None (Main library).

Description: Return the difference between the current microsecond timer and a snapshot of that timer from a call to ptm_get_us_time().

Arg (data in): ptmf_time The result of calling ptm_get_us_time(). Range: [0, 4294967295] microseconds

Return: The difference in time between the current value of the microsecond timer and ptmf_time. Range: [0, 4294967295] microseconds 5.5.3.2.12. ptm_us_time_diff_update()

Definition: U32 ptm_us_time_diff_update(U32 *ptmf_time)

Supported targets: All targets

Required license: None (Main library).

Description: Return the difference between the current microsecond timer and a snapshot of that timer from a call to ptm_get_us_time() and ptm_us_time_diff_update(), updating the snapshot for the next call.

Arg (data in): ptmf_time Pointer to the last snapshot of time (either by calling ptm_get_us_time() initially, or ptm_us_time_diff_update() subsequently). Range: [0, 4294967295] microseconds

Return: The difference in time between the current value of the microsecond timer and ptmf_time. Range: [0, 4294967295] microseconds 5.6. Task scheduling (PKN)

The task scheduling feature has the following responsibilities:

• non-nested interrupt dispatching (see Section 5.6.1.1, “Interrupt handling”);

• fixed priority pre-emptive task dispatching (see Section 5.6.1.2, “Preemptive scheduling”);

• task timing (see Section 5.6.1.4, “Task timing”);

• resource locking between tasks (see Section 5.6.1.6, “Resource locking”);

• stack handling (see Section 5.6.1.3, “Stack sharing”).

The scheduling feature allows library and application tasks to be scheduled together. See Section 4.6.4, “Application and library tasks” for a list of the pre-defined library tasks and library resources. 5.6.1. Tasking model

The tasking model used by the feature can be represented as a series of state changes.

Figure 5.1. Tasking model states

Waiting

Ready Running

Terminated

All tasks are implemented as single-shot C functions, so each time a task runs it terminates and does not wait. Tasks start by becoming ready due to the periodicity of the task (handled by the scheduler) or due to another task or interrupt making it ready. When tasks are ready to run, they are executed in order from highest to lowest priority with pre-emption if necessary. 5.6.1.1. Interrupt handling

The scheduler feature handles interrupts in a non-nested manner. As the interrupt routines are kept as short as possible, they have a small timing impact on library and application tasks and do not introduce unnecessary latency between themselves.

The scheduler uses one interrupt source as a regular 1 millisecond tick. From this tick, all tasks with timing properties as scheduled.

Note

Interrupt handling is not exposed at the C interface level.

5.6.1.2. Preemptive scheduling

Each task has a priority relative to other tasks. Tasks with a low priority can (with a few exceptions) be interrupted immediately by tasks with a higher priority when those higher priority tasks become ready to run. This scheduling scheme is called fixed pre-emptive

scheduling and can be analysed for various properties if need be (e.g., will a task complete before a given dead-line all the time regardless of other task activities).

Tasks are single-shot in nature, represented by a single C function. For example, a 10 millisecond task would be handled by a C function as follows:

void application_10ms_task(void) { /* Perform application processing. */ return; }

The task function takes no arguments and returns void. The function is invoked by the scheduler and performs the functionality of the application every 10 milliseconds before returning. On return, the scheduler determines if there are any lower priority tasks ready to run (or to continue to run) and schedules those according to their priority (highest to lowest). When no tasks are running, the scheduler allows the library background function to continue to run (the application can make use of this background function to perform its own processing if necessary).

Before a task returns, if a higher priority task becomes ready to run then the scheduler will pre-empt the task function (effectively stopping it) and start to run the function of the higher priority task, before returning to the original function to continue processing. In this fashion, processing which must occur on a more frequent basis can be assigned to a higher priority task and take precedence over less important processing.

Figure 5.2. Task pre-emption

Scheduler Highest priority

Task 2 High priority tb tc

Task 1 Low priority ta td

Background processing Time

Task becomes read to run.

Task completes and returns to scheduler.

The diagram shows the background processing function, a low and high priority task function, and the scheduler function. Shaded areas show when a function is running. Initially the background processing function is running. At time ta the low priority task becomes ready to run, the scheduler pre-empts the background function and starts the low priority task function. At time tb the high priority task becomes ready to run, the scheduler pre-empts the low priority task function and starts the high priority task function. At time tc the high priority task completes and the scheduler continues the low priority task function. At time td the low priority task completes and the scheduler continues the background processing function.

Shown on the same time-line, its easy to see how the processor is divided into running different task functions.

Background processing ta tb tc td Time

Task becomes ready to run.

Task completes and returns to scheduler.

Scheduler – highest priority

Task 2 – high priority

Task 1 – low priority

Background processing

5.6.1.3. Stack sharing

The stack is setup during library pre-initialisation. By using a single shot function tasking model, context switch RAM usage is keep to a minimum, and all tasks share the same system stack. As a new task is scheduled to run, the context of the previous task or of the background processing function is stored on the stack, then the task function is called. This scheme makes for efficient use of stack on resource limited ECUs.

On some target ECUs, this means stack overflow can be caught immediately as an exception by the processor and handled appropriately. 5.6.1.4. Task timing

As the product is delivered as a library, the final overall task timing cannot be known in advance. To facilitate development, the feature times tasks as they run to record the last execution period and the maximum seen since power on (see pkn_task_start_time[], pkn_task_accum_time[], pkn_task_duration_time[] and pkn_max_task_duration_time[]).

The task duration may include pre-emption time from other tasks, so when the scheduler switches tasks, it adjusts the pre-empted task accordingly so that each task time recorded is the time it would have taken that task to run without pre-emption.

Note

This adjustment does not compensate for pre-emption from interrupts. As interrupts are short, no effort is made to adjust the task time to account for interrupts. Consequently, the task times will increase as the interrupt rates increase;

5.6.1.5. Task context switches

When the scheduler changes between tasks, the scheduler saves the integer and floating point processor context as defined by the application interface for the target ECU's processor. Tasks are free to use the processor's general registers as necessary. 5.6.1.6. Resource locking

The scheduler provides a mechanism for a task to lock a resource, thus preventing other tasks from accessing the same resource. The locking mechanism is implemented using the Immediate Priority Ceiling Protocol (IPCP). The protocol ensures that deadlock cannot occur if certain rules are followed (see Section 5.6.1.7, “Resource locking rules”).

The scheduler keeps track of the currently running task with a ceiling. The ceiling is initially the priority level of the task that runs. Only tasks with priority above the ceiling can pre- empt the currently running task (equal priority tasks and lower priority tasks cannot). Calls to pkn_acquire_resource() and pkn_release_resource() adjust the priority ceiling.

Figure 5.3. Task pre-emption with resource locking

Scheduler Highest priority

Task 2 High priority

Task 1 Low priority ta tb tc td

Background processing Time

Task becomes read to run.

Task completes and returns to scheduler.

In this example, there are two tasks which both access the same resource. The diagram shows the background processing function is running initially. At time ta the low priority task becomes ready to run, the scheduler pre-empts the background function and starts the low priority task function. At time tb the low priority task locks a resource that both the high and low priority task share. At time tc the high priority task becomes ready to run but the scheduler does not start it because a resource shared by the high priority task is locked. At time td the low priority task releases the resource lock and because the high priority task is ready to run, the scheduler pre-empts the low-priority function and starts the high priority task function. The resource which was locked by the low priority function was modified by the low priority task only, the other task which could have modified the resource was prevented form running by the scheduler.

When a task wishes to lock a resource, the scheduler must ensure that only that task runs while accessing the resource. It does so by knowing in advance which tasks will access any resource. When any task requests a lock of the resource, the scheduler raises the ceiling priority to the highest priority of any task accessing that resource. This ensures that the task requesting the resource will not be pre-empted by any task also wishing to use the resource. 5.6.1.7. Resource locking rules

The IPCP only works correctly when certain rules are followed:

• resources must be locked by a task in a nested structure, i.e., acquire r1, acquire r2, do work, release r2, release r1;

• a task must not acquire a resource if it already holds that resource;

• a task must not release a resource without acquiring it first.

If these rules are not followed, then it is possible that the scheduler will not honour correct resource locking.

5.6.2. Interface index

An index of interface objects for this feature.

Type Identifier Include file openecu.h and pkn.h Enumerations PKN_ERROR_CODE_T

Error values for debugging when an error is found in a call to the scheduler feature (PKN), the scheduler calls a system error log function with an enumeration from this type. Data types PKN_TASKSET_T

The type for a group of tasks. PKN_TASK_HANDLE_T

This type specifies a task handle. PKN_PERIODIC_TASK_HANDLE_T

This type specifies a periodic task handle. PKN_RESOURCE_HANDLE_T

This type specifies a resource handle. PKN_ILEVEL_T

This type specifies an atomic word large enough to hold the bit pattern for all interrupt levels. Functions void pkn_acquire_resource

Acquire a resource and raise the priority of this task so that others cannot acquire the same resource. void pkn_release_resource

Release a resource and lower the priority to the calling task's actual priority (or dispatch any ready tasks with higher priority). void pkn_ready_task

Make a task ready to run. U32 pkn_get_task_duration

Return the last measured duration of a task. U32 pkn_get_max_task_duration

Return the maximum duration of a task since the scheduler was initialised. U8 pkn_get_task_overrun_count

Type Identifier Return the number of times the task has overrun. U8 pkn_get_task_skip_count

Return the number of times the task has been skipped. 5.6.3. Interface detail 5.6.3.1. Enumerations 5.6.3.1.1. PKN_ERROR_CODE_T

Summary: Error values for debugging when an error is found in a call to the scheduler feature (PKN), the scheduler calls a system error log function with an enumeration from this type.

Enumerations:

PKN_ERR_KERNEL_STARTED_BELOW_KERNEL_LEVEL Error raised if the scheduler is started under the wrong interrupt conditions (internal error).

PKN_ERR_INVALID_RESOURCE_HANDLE Error raised if the scheduler finds the resource does not exist in the internal resource array.

PKN_ERR_TASK_NOT_DECLARED_AS_ACQUIRING_RESOURCE Error raised if the scheduler finds the calling task was not declared as acquiring the resource.

PKN_ERR_INVALID_TASK_HANDLE Error raised if the scheduler finds the task handle does not exist in the internal task array.

PKN_ERR_INVALID_PERIODIC_TASK_HANDLE Error raised if the scheduler finds the task handle does not exist in the internal periodic task array.

PKN_ERR_PERIODIC_TASK_HAS_NO_PERIOD Error raised if the scheduler detected a periodic task that has a period of zero milliseconds.

PKN_ERR_UNEXPECTED_EXCEPTION Error raised if the scheduler traps an unexpected processor exception.

PKN_ERR_UNEXPECTED_INTERRUPT Error raised if the scheduler traps an unexpected processor interrupt. 5.6.3.2. Data types 5.6.3.2.1. PKN_TASKSET_T

Definition: typedef U32 PKN_TASKSET_T

Description: The type for a group of tasks.

A task is a group of functionality that can be run when the task becomes ready. A task can become ready periodically (e.g., scheduled every x ms) or sporadically (e.g., when a sporadic interrupt is processed).

A task has a fixed priority level and tasks ready to run are executed in a pre-emptive fashion where each task release is single shot (think of nested interrupt levels).

A task set is a set of tasks with a common property, e.g., a set of tasks ready to run, or a set of tasks with priority lower than the currently running task.

A task set is represented as a bit set of task bit patterns. Each task is assigned a single bit position in the representation and can be identified by isolating the bit.

As the tasks have a priority ordering, the order of the bits assigned to tasks take the same ordering.

E.g., the highest priority task takes the MS bit (note: PPC bit numbering):

MSB LSB bit 0 bit 31

1 0 0 0 0 0 0 0 0 0

and the second highest priority task takes the second MS bit:

MSB LSB bit 0 bit 31

0 1 0 0 0 0 0 0 0 0

and so on.

A task set or more than one task is then simply the bitwise OR of each task's bit pattern.

E.g., the task set of the second highest task and fourth highest task is represented as:

MSB LSB bit 0 bit 31

0 1 0 1 0 0 0 0 0 0

The bit pattern representation makes finding the highest priority task of a task set easy to find. On the PPC architecture, the count leading zeros machine instruction cntlzw returns the bit position of the MS set bit or 32 if no set bits exist.

When running a task, pre-emption from another source can cause a higher priority task to become ready. The kernel will pre-empt the running task and start running the higher priority task.

To make it easy to determine if a new higher priority task has been make ready to run, the kernel keeps a record of the priority that the current task is running at. This is called the task's ceiling.

The ceiling is represented as a task set of the currently running task and all lower priority tasks.

E.g., if the fourth highest priority task is running, then the ceiling task set would be:

MSB LSB bit 0 bit 31

0 0 0 1 1 1 1 1 1 1

This representation of the ceiling makes it simple to determine is a higher priority task is ready to run. If the ready taskset is greater is value than the ceiling, then there is at least one task with priority higher than the ceiling.

E.g., consider a running task with the fourth highest priority level when the second highest priority task becomes ready to run.

This type specifies an atomic word large enough to hold a task set for up to 32 tasks. 5.6.3.2.2. PKN_TASK_HANDLE_T

Definition: typedef const PKN_TASK_T* const PKN_TASK_HANDLE_T

Description: This type specifies a task handle.

A handle is presented to the kernel API whenever the user requires some action to occur on the handle's object.

The implementation of handles uses pointers for efficiency. 5.6.3.2.3. PKN_PERIODIC_TASK_HANDLE_T

Definition: typedef const PKN_PERIODIC_TASK_T* const PKN_PERIODIC_TASK_HANDLE_T

Description: This type specifies a periodic task handle.

A handle is presented to the kernel API whenever the user requires some action to occur on the handle's object.

The implementation of handles uses pointers for efficiency. 5.6.3.2.4. PKN_RESOURCE_HANDLE_T

Definition: typedef const PKN_RESOURCE_T* const PKN_RESOURCE_HANDLE_T

Description: This type specifies a resource handle.

A handle is presented to the kernel API whenever the user requires some action to occur on the handle's object.

The implementation of handles uses pointers for efficiency. 5.6.3.2.5. PKN_ILEVEL_T

Definition: typedef U32 PKN_ILEVEL_T

Description: This type specifies an atomic word large enough to hold the bit pattern for all interrupt levels.

The kernel has the concept of a suspended kernel or a running kernel.

When the kernel is suspended, there will be no API calls to the kernel from application code. This is achieved by raising the interrupt level high enough that no preemption of the kernel by an exception that calls the kernel will occur.

When the kernel is running, there will be API calls to the kernel from application code. This is achieved by lowering the interrupt level enough that preemption of tasks and non-critical kernel code can occur. 5.6.3.3. Functions

5.6.3.3.1. pkn_acquire_resource()

Definition: void pkn_acquire_resource(const PKN_RESOURCE_HANDLE_T pknf_r_hd)

Supported targets: All targets

Required license: None (Main library).

Description: Acquire a resource and raise the priority of this task so that others cannot acquire the same resource.

Implements part of the Immediate Priority Ceiling Protocol (IPCP) for resource control. The function locks a resource by raising the priority of the current task to the priority of the highest task that will lock the resource.

Callable by application when tasking given the following constraints:

• resources must be locked by a task in a nested structure, i.e., acquire r1, acquire r2, ...., release r2, release r1, to satisfy the priority ceiling protocol;

• a task must not acquire a resource if it already holds that resource;

• a task must not release a resource without acquiring it first.

If a task finishes without releasing its acquired resources, the scheduler automatically releases any acquired.

Can raise the following errors: PKN_ERR_INVALID_RESOURCE_HANDLE, PKN_ERR_TASK_NOT_DECLARED_AS_ACQUIRING_RESOURCE.

Arg (data in): pknf_r_hd A pointer to a resource. The resource itself specifies which tasks can acquire this resource, the ceiling of those tasks and a pointer to a buffer to store context. Cannot be NULL. 5.6.3.3.2. pkn_release_resource()

Definition: void pkn_release_resource(const PKN_RESOURCE_HANDLE_T pknf_r_hd)

Supported targets: All targets

Required license: None (Main library).

Description: Release a resource and lower the priority to the calling task's actual priority (or dispatch any ready tasks with higher priority).

Implements part of the Immediate Priority Ceiling Protocol (IPCP) for resource control. It unlocks a resource by lowering the priority of the current task to the priority that locked it and if necessary, dispatches any tasks with higher priority that were made ready while the resource was locked.

Can raise the following errors: PKN_ERR_INVALID_RESOURCE_HANDLE, PKN_ERR_TASK_NOT_DECLARED_AS_ACQUIRING_RESOURCE.

Callable in the same context as pkn_acquire_resource().

Definition: void pkn_ready_task(const PKN_TASK_HANDLE_T pknf_t_hd)

Supported targets: All targets

Required license: None (Main library).

Description: Make a task ready to run.

Make a task ready to run when not handling an interrupt. The task will be dispatched if it has higher priority than the calling task. The task will not be dispatched immediately if the priority of the task to make ready is lower than the current, but will be dispatched after all higher priority tasks have completed.

Can raise the following errors: PKN_ERR_INVALID_TASK_HANDLE.

Callable by the application at the tasking level.

Arg (data in): pknf_t_hd A pointer to a task structure. The task specifies the priority it should run at as well as the function to call when the task runs. Cannot be NULL. 5.6.3.3.4. pkn_get_task_duration()

Definition: U32 pkn_get_task_duration(const PKN_TASK_HANDLE_T pknf_t_hd)

Supported targets: All targets

Required license: None (Main library).

Description: Return the last measured duration of a task.

Return the last measured duration of a task in microseconds. The duration may include the duration of the task and the duration of any interrupts that occurred while the task was running, but does not include the duration of any tasks that pre-empted the task while it was running.

Can raise the following errors: PKN_ERR_INVALID_TASK_HANDLE.

Callable by the application at the tasking level.

Arg (data in): pknf_t_hd A pointer to a task structure. The task specifies the priority it should run at as well as the function to call when the task runs. Cannot be NULL.

Return: The last measured duration of a task in microseconds Range: [0, 4294967295] microseconds. 5.6.3.3.5. pkn_get_max_task_duration()

Definition: U32 pkn_get_max_task_duration(const PKN_TASK_HANDLE_T pknf_t_hd)

Supported targets: All targets

Required license: None (Main library).

Description: Return the maximum duration of a task since the scheduler was initialised.

Return the maximum measured duration of a task in microseconds. The duration may include the duration of the task and the duration of any interrupts that occurred while the task was running, but does not include the duration of any tasks that pre-empted the task while it was running.

Can raise the following errors: PKN_ERR_INVALID_TASK_HANDLE.

Callable by the application at the tasking level.

Arg (data in): pknf_t_hd A pointer to a task structure. The task specifies the priority it should run at as well as the function to call when the task runs. Cannot be NULL.

Return: The maximum measured duration of a task in microseconds Range: [0, 4294967295] microseconds. 5.6.3.3.6. pkn_get_task_overrun_count()

Definition: U8 pkn_get_task_overrun_count(const PKN_PERIODIC_TASK_HANDLE_T pknf_pt_hd)

Supported targets: All targets

Required license: None (Main library).

Description: Return the number of times the task has overrun.

When a periodic task comes up to be scheduled and still running, then the overrun count for that task is incremented.

Can raise the following errors: PKN_ERR_INVALID_PERIODIC_TASK_HANDLE.

Callable by the application at the tasking level.

Arg (data in): pknf_pt_hd A pointer to a task structure. The task specifies the priority it should run at as well as the function to call when the task runs. Cannot be NULL.

Return: The number of times the task has overrun. Range: [0, 255] count. 5.6.3.3.7. pkn_get_task_skip_count()

Definition: U8 pkn_get_task_skip_count(const PKN_PERIODIC_TASK_HANDLE_T pknf_pt_hd)

Supported targets: All targets

Required license: None (Main library).

Description: Return the number of times the task has been skipped.

When a task is made ready to run, but is already ready to run and hasn't started the previous invocation, then the skip count for that task is incremented.

Can raise the following errors: PKN_ERR_INVALID_PERIODIC_TASK_HANDLE.

Callable by the application at the tasking level.

Arg (data in): pknf_pt_hd A pointer to a task structure. The task specifies the priority it should run at as well as the function to call when the task runs. Cannot be NULL.

Return: The number of times the task has been skipped. Range: [0, 255] count. 5.7. Library input and output configuration (PIO) 5.7.1. Overview

The PIO feature provides a set of macros to be used when calling some of the C-API functions. The macros vary based on the target the application code is written for. An example would be configuring a CAN bus during application initialisation:

/* Call the library to initialise the CAN buses, ignoring the return value. */ (void) pcx_config(PIO_CAN_A28_A43 , PIO_CBAUD_500_KBPS );

The macro PIO_CAN_A28_A43 (for the M220 target) selects the first CAN bus. The ECU connector pins are included in the macro name (A28_A43) so there is a simple relationship between macro and pin.

The macro PIO_CBAUD_500_KBPS (for the M220 target) selects a baud rate of 500 kBps for the first CAN bus.

The macro names are formed so that they are easily associated with their use.

ECU configuration Take the form PIO_CFG_[ITEM] for parameters which can be used to change the behaviour of the ECU. For instance PIO_CFG_HEGO_FILTER_160HZ selects a 160Hz filter for the HEGO analogue input pins supported by an ECU.

CAN buses and baud rates Take the form PIO_CAN_[PIN-NAMES] for CAN buses, and the form PIO_CBAUD_[BAUD]_KBPS for baud rates.

Analogue inputs Take the form PIO_AIN_[PIN-NAME] for connector pins, the form PIO_AIN_INT_[FUNCTION] for internal inputs, the form PIO_AIN_[PIN- NAME]_MONITOR for internal monitor inputs.

Digital inputs Take the form PIO_DIN_[PIN-NAME] for connector pins, the form PIO_DIN_INT_[FUNCTION] for internal inputs, the form PIO_DIN_[PIN- NAME]_MONITOR for internal monitor inputs.

Frequency inputs Take the form PIO_FIN_[PIN-NAME] for connector pins, the form PIO_FIN_INT_[FUNCTION] for internal inputs, the form PIO_FIN_[PIN- NAME]_MONITOR for internal monitor inputs.

Period inputs Take the form PIO_PIN_[PIN-NAME] for connector pins, the form PIO_PIN_INT_[FUNCTION] for internal inputs, the form PIO_PIN_[PIN- NAME]_MONITOR for internal monitor inputs.

Quadrature inputs Take the form PIO_QDIN_[PIN-NAME] or PIO_QFIN_[PIN-NAME] for connector pins, the form PIO_QDIN_INT_[FUNCTION] or PIO_QFIN_INT_[FUNCTION] for internal inputs, or the form PIO_QDIN_[PIN-NAME]_MONITOR or PIO_QFIN_[PIN- NAME]_MONITOR for internal monitor inputs. Pins using QDIN do not support frequency measurement, pins using QFIN support frequency measurement.

Constant current outputs Take the form PIO_CCOT_[PIN-NAME] for connector pins, the form PIO_CCOT_INT_[FUNCTION] for internal outputs, the form PIO_CCOT_[PIN- NAME]_[FUNCTION] for internal outputs related to connector pins.

Digital outputs Take the form PIO_DOT_[PIN-NAME] for connector pins, the form PIO_DOT_INT_[FUNCTION] for internal outputs, the form PIO_DOT_[PIN- NAME]_[FUNCTION] for internal outputs related to connector pins.

Ignition (angular) outputs Take the form PIO_IGNOT_[PIN-NAME] for connector pins, the form PIO_IGNOT_INT_[FUNCTION] for internal outputs, the form PIO_IGNOT_[PIN- NAME]_[FUNCTION] for internal outputs related to connector pins.

Injection (angular) outputs Take the form PIO_INJOT_[PIN-NAME] for connector pins, the form PIO_INJOT_INT_[FUNCTION] for internal outputs, the form PIO_INJOT_[PIN- NAME]_[FUNCTION] for internal outputs related to connector pins.

PWM outputs Take the form PIO_POT_[PIN-NAME] for connector pins, the form PIO_POT_INT_[FUNCTION] for internal outputs, the form PIO_POT_[PIN- NAME]_[FUNCTION] for internal outputs related to connector pins.

Synchronised PWM outputs Take the form PIO_SPOT_[PIN-NAME] for connector pins, the form PIO_SPOT_INT_[FUNCTION] for internal outputs, the form PIO_SPOT_[PIN- NAME]_[FUNCTION] for internal outputs related to connector pins.

Stepper motor outputs Take the form PIO_SMOT_[PIN-NAME] for connector pins, the form PIO_SMOT_INT_[FUNCTION] for internal outputs, the form PIO_SMOT_[PIN- NAME]_[FUNCTION] for internal outputs related to connector pins.

Note

Not all targets are capable of supporting each of the input and output types listed above. In this case, the PIO header files explicitly state there is no support and do not provide any macros for that I/O type.

Unlike other features, the interface to the PIO feature varies per target. For this reason, there is no interface detail in this user guide, refer instead to the PIO header files. 5.8. Feature for specific target configuration (PCFG) 5.8.1. Overview

This feature provides a way to define ECU specific configuration settings for some ECUs that are not available on all ECUs.

5.8.2. M110, M220 and M461 targets

No target specific configuration is available for this target. 5.8.3. M250 target

The configuration of pins A32, A33 and A34 as injectors or a PWM outputs can be achieved by calling pcfg_setup_m250() during application initialisation. If the pin is configured as a PWM output then the current trip level can also be selected. The library configures pin appropriately during library post-initialisation.

The M250-00Z comes with an IMU attached which contains three gyroscopes and an accelerometer. To configure the sample rates of the gyroscopes and the accelerometer to something other than their default values, call the function pcfg_imu_rate() during application initialisation. 5.8.4. M460 target

The configuration of pin A31 as an injector or a PWM output can be achieved by calling pcfg_setup_m460() during application initialisation. If the pin is configured as a PWM output then the current trip level can also be selected. The library configures pin appropriately during library post-initialisation. 5.8.5. M670 target

Certain frequency inputs can be configured by calling pcfg_setup_pwm_clock_m670() during application initialisation. This function will configure the pin's timebase to control the resolution of the input. 5.8.6. Interface index

An index of interface objects for this feature.

Type Identifier Include file openecu.h and pcfg.h Enumerations PCFG_RC_T

An enumerated type which contains success and failure codes returned by some ECU configuration feature (PCFG) functions. PCFG_ERROR_CODE_T

Error values for debugging when an error is found when executing the PCFG feature, the API calls a function with an enumeration from this type. Functions PCFG_RC_T pcfg_imu_rate

Function to configure the sampling rate of an IMU channel.

Type Identifier PCFG_RC_T pcfg_setup_m250

Set the configuration for channel A32, A33 and A34 (either as injector or PWM output). void pcfg_softswitch_m460

Set the configuration for channel A31 (either as injector or PWM output) (deprecated). PCFG_RC_T pcfg_setup_m460

Set the configuration for channel A31 (either as injector or PWM output). PCFG_RC_T pcfg_setup_pwm_clock_m5xx

Set the clock configuration for frequency input channels. PCFG_RC_T pcfg_set_global_mios_prescaler_m5xx

Set the clock configuration for global MIOS frequency. PCFG_RC_T pcfg_setup_pwm_clock_m670

Set the clock configuration for frequency input channels. 5.8.7. Interface detail 5.8.7.1. Enumerations

5.8.7.1.1. PCFG_RC_T

Summary: An enumerated type which contains success and failure codes returned by some ECU configuration feature (PCFG) functions.

Enumerations:

PCFG_RC_OK Return code if everything progressed as expected.

PCFG_RC_SAMPLE_RATE_TOO_LOW Return code if the desired sample rate is too low.

PCFG_RC_SAMPLE_RATE_TOO_HIGH Return code if the desired sample rate is too high.

PCFG_RC_INVALID_CHAN Return code if an internal error occurred which was the result of a software error.

PCFG_RC_BAD_ARGS_HEGO Return code if at least one of the arguments relating to the HEGO filter selection could not be used.

PCFG_RC_BAD_ARGS_TYPE Return code if at least one of the arguments relating to the pin type selection could not be used (M460).

PCFG_RC_BAD_ARGS_HYST Return code if at least one of the arguments relating to the pin hysteresis selection could not be used.

PCFG_RC_BAD_ARGS_NOM_CT Return code if at least one of the arguments relating to the spark nominal current-trip selection could not be used.

PCFG_RC_BAD_ARGS_MAX_CT Return code if at least one of the arguments relating to the spark maximum current-trip selection could not be used.

PCFG_RC_BAD_ARGS_INJ_CT Return code if at least one of the arguments relating to the current- trip selection or current threshold could not be used (M460, M461).

PCFG_RC_BAD_ARGS_MIOS_CLK Return code if at least one of the arguments relating to the MIOS clock selection could not be used (M670).

5.8.7.1.2. PCFG_ERROR_CODE_T

Summary: Error values for debugging when an error is found when executing the PCFG feature, the API calls a function with an enumeration from this type.

Enumerations:

PCFG_INTERNAL_SW_ERROR Error raised when an internal software bug is detected.

Contact Pi Innovo support if encountered. 5.8.7.2. Functions

5.8.7.2.1. pcfg_imu_rate()

Definition: PCFG_RC_T pcfg_imu_rate(PIO_CFG_SAMPLE_RATE_CHAN_T pcfgf_chan, U16 pcfgf_sample_rate)

Required license: None (Main library).

Description: Function to configure the sampling rate of an IMU channel.

Supported by targets: M250-00Z.

Arg (data in): pcfgf_chan The IMU channel needed to configure the sampling rate. This generally will include an accelerometer and a gyroscope. Use the macros included by pio.h defined in the in the enum PIO_CFG_SAMPLE_RATE_CHAN_T.

Arg (data in): pcfgf_sample_rate The sample rate to be set for the accelerometer or the gyroscope on the M250. Note that the default sample rate on the accelerometer is

40Hz and the default sample rate on the gyroscope is 2048 samples per second. Range (accelerometer): The accelerometer only has four options for the sample rate: 40Hz, 160Hz, 640Hz, 2560Hz Range (gyroscope): [4 256] or 2048 Samples Per Second

Note

This function will choose the closest sample rate value to the desired sample rate value.

Return:

• PCFG_RC_OK - successful action

• PCFG_RC_INVALID_CHAN - channel not supported

• PCFG_RC_SAMPLE_RATE_TOO_HIGH - sample rate is too high

• PCFG_RC_SAMPLE_RATE_TOO_LOW - sample rate is too low 5.8.7.2.2. pcfg_setup_m250()

Definition: PCFG_RC_T pcfg_setup_m250(PIO_CFG_OUTPUT_TYPE_T pcfgf_output_type_a32, PIO_CFG_CURRENT_TRIP_T pcfgf_current_trip_level_a32, PIO_CFG_OUTPUT_TYPE_T pcfgf_output_type_a33, PIO_CFG_CURRENT_TRIP_T pcfgf_current_trip_level_a33, PIO_CFG_OUTPUT_TYPE_T pcfgf_output_type_a34, PIO_CFG_CURRENT_TRIP_T pcfgf_current_trip_level_a34)

Supported targets:

Required license: None (Main library).

Description: Set the configuration for channel A32, A33 and A34 (either as injector or PWM output).

Configure the output type for pin A32, A33 and A34 pins, either injector or PWM. When the output has PWM type, the current trip level of the output can be selected (current trip level is not selectable for injector types).

If this function is not called during initialisation, pins A32, A33 and A34 default to PWM type with a current trip level of 5A.

Warning

The function must be called during application initialisation and never during application run.

Arg (data in): pcfgf_output_type_a32 PIO_CFG_OUTPUT_TYPE_INJ to set A32 channel as an injector output, PIO_CFG_OUTPUT_TYPE_PWM to set A32 channel as a PWM output or digital output.

Arg (data in): pcfgf_current_trip_level_a32 PIO_CFG_CURRENT_TRIP_5A to set current trip level for pin A32 to ~5A; PIO_CFG_CURRENT_TRIP_2A to set current trip level for pin A32 to ~2A. Valid only if pcfgf_output_type_a32 is set to PIO_CFG_OUTPUT_TYPE_PWM.

Arg (data in): pcfgf_output_type_a33 PIO_CFG_OUTPUT_TYPE_INJ to set A33 channel as an injector output, PIO_CFG_OUTPUT_TYPE_PWM to set A33 channel as a PWM output or digital output.

Arg (data in): pcfgf_current_trip_level_a33 PIO_CFG_CURRENT_TRIP_5A to set current trip level for pin A33 to ~5A; PIO_CFG_CURRENT_TRIP_2A to set current trip level for pin A33 to ~2A. Valid only if pcfgf_output_type_a33 is set to PIO_CFG_OUTPUT_TYPE_PWM.

Arg (data in): pcfgf_output_type_a34 PIO_CFG_OUTPUT_TYPE_INJ to set A34 channel as an injector output, PIO_CFG_OUTPUT_TYPE_PWM to set A34 channel as a PWM output or digital output.

Arg (data in): pcfgf_current_trip_level_a34 PIO_CFG_CURRENT_TRIP_5A to set current trip level for pin A34 to ~5A; PIO_CFG_CURRENT_TRIP_2A to set current trip level for pin A34 to ~2A. Valid only if pcfgf_output_type_a34 is set to PIO_CFG_OUTPUT_TYPE_PWM.

Return:

• PCFG_RC_OK - if successful action

• PCFG_RC_BAD_ARGS_TYPE - if configuration error on pin type parameter

• PCFG_RC_BAD_ARGS_INJ_CT - if configuration error on current trip parameter 5.8.7.2.3. pcfg_softswitch_m460()

Definition: void pcfg_softswitch_m460(BOOL pcfgf_softswitch_state)

Supported targets:

Required license: None (Main library).

Description: Set the configuration for channel A31 (either as injector or PWM output) (deprecated).

Similar in functionality to pcfg_setup_m460(). This function became deprecated in version 1.8.0 and will be removed in a future release. The function is currently retained to provide backwards compatibility to previous releases.

Warning

The function must be called during application initialisation and never during application run.

Arg (data in): pcfgf_softswitch_state TRUE to set A31 channel as an injector output, FALSE to set A31 channel as a PWM output with a current trip level of ~5A. 5.8.7.2.4. pcfg_setup_m460()

Definition: PCFG_RC_T pcfg_setup_m460(PIO_CFG_OUTPUT_TYPE_T pcfgf_output_type_a31, PIO_CFG_CURRENT_TRIP_T pcfgf_current_trip_level_a31)

Supported targets:

Required license: None (Main library).

Description: Set the configuration for channel A31 (either as injector or PWM output).

Configure the output type for pin A31, either injector or PWM. When the output has PWM type, the current trip level of the output can be selected (current trip level is not selectable for injector types).

Warning

The function must be called during application initialisation and never during application run.

Arg (data in): pcfgf_output_type_a31 PIO_CFG_OUTPUT_TYPE_INJ to set A31 channel as an injector output, PIO_CFG_OUTPUT_TYPE_PWM to set A31 channel as a PWM output or digital output.

Arg (data in): pcfgf_current_trip_level_a31 PIO_CFG_CURRENT_TRIP_5A to set current trip level for pin A31 to ~5A; PIO_CFG_CURRENT_TRIP_2A to set current trip level for pin A31 to ~2A. Valid only if pcfgf_output_type_a31 is set to PIO_CFG_OUTPUT_TYPE_PWM.

Return:

• PCFG_RC_OK - if successful action

• PCFG_RC_BAD_ARGS_TYPE - if configuration error on pin type parameter

• PCFG_RC_BAD_ARGS_INJ_CT - if configuration error on current trip parameter 5.8.7.2.5. pcfg_setup_pwm_clock_m5xx()

Definition: PCFG_RC_T pcfg_setup_pwm_clock_m5xx(PDX_LCHAN_T pcfgf_mios_chan, PIO_CFG_MIOS_CLOCK_SELECT_T pcfgf_clock_select)

Supported targets:

Required license: None (Main library).

Description: Set the clock configuration for frequency input channels.

For MIOS-controlled digital I/O, multiple clock speeds can be chosen, based on a global time base of 1.6 MHz or 400 kHz:

• Slow clock: 400 kHz/100 kHz timebase.

• Medium Slow Clock: 533 kHz/133 kHz timebase.

• Medium Clock: 800 kHz/200 kHz timebase.

• Fast Clock: 1.6 Mhz/400 kHz timebase.

If this function is not called during initialisation before the channel's corresponding initialisation function is called, then it will by default use the slow clock.

Warning

The function must be called during application initialisation before the initialisation function is called for that channel.

Arg (data in): pcfgf_mios_chan The channel to be configured with a particular clock selection. Only eMIOS-based channels are configurable.

Arg (data in): pcfgf_clock_select PIO_CFG_MIOS_CLOCK_SELECT_SLOW to set channel to use the slow clock PIO_CFG_MIOS_CLOCK_SELECT_MEDSLOW to set channel to use the medium slow clock PIO_CFG_MIOS_CLOCK_SELECT_MED to set channel to use the medium clock PIO_CFG_MIOS_CLOCK_SELECT_FAST to set channel to use the fast clock

Return:

• PCFG_RC_OK - if successful action

• PCFG_RC_INVALID_CHAN - if configuration error on pin selection

• PCFG_RC_BAD_ARGS_MIOS_CLK - if configuration error on clock speed parameter

5.8.7.2.6. pcfg_set_global_mios_prescaler_m5xx()

Definition: PCFG_RC_T pcfg_set_global_mios_prescaler_m5xx(PIO_CFG_MIOS_GLOBAL_SELECT_T pcfgf_global_pre)

Supported targets:

Required license: None (Main library).

Description: Set the clock configuration for global MIOS frequency.

For MIOS-controlled digital I/O, an 80KHz peripheral clock can be divided to provide a MIOS global clock of 1.6 MHz or 400 kHz:

If this function is not called during initialisation before the channel's corresponding initialisation function is called, then it will by default use the slow clock.

Warning

The function must be called during application initialisation before the initialisation function is called for that channel.

Arg (data in): pcfgf_global_pre PIO_CFG_MIOS_GLOBAL_SLOW to set a divider of 200 PIO_CFG_MIOS_GLOBAL_FAST to set a divider of 50

Return:

• PCFG_RC_OK - if successful action

• PCFG_RC_BAD_ARGS_MIOS_CLK - if configuration error on clock speed parameter

5.8.7.2.7. pcfg_setup_pwm_clock_m670()

Definition: PCFG_RC_T pcfg_setup_pwm_clock_m670(PDX_LCHAN_T pcfgf_mios_chan, PIO_CFG_MIOS_CLOCK_SELECT_T pcfgf_clock_select)

Supported targets:

Required license: None (Main library).

Description: Set the clock configuration for frequency input channels.

For MIOS-controlled digital I/O, multiple clock speeds can be chosen:

• Slow clock: 4.125Mhz timebase.

• Medium Clock: 8.25Mhz timebase. For inputs 0.75 Hz to 2500 Hz with a minimum resolution of at least 0.5 Hz

• Fast Clock: 16.5Mhz timebase. For inputs 1.6 kHz to 60 kHz with a minimum resolution of at least 218 Hz.

If this function is not called during initialisation before the channel's corresponding initialisation function is called, then it will by default use the slow clock.

Warning

The function must be called during application initialisation before the initialisation function is called for that channel.

Arg (data in): pcfgf_mios_chan The channel to be configured with a particular clock selection. Only eMIOS-based channels are configurable.

Arg (data in): pcfgf_clock_select PIO_CFG_MIOS_CLOCK_SELECT_SLOW to set channel to use the slow clock PIO_CFG_MIOS_CLOCK_SELECT_MED to set channel to use the medium clock PIO_CFG_MIOS_CLOCK_SELECT_FAST to set channel to use the fast clock

Return:

• PCFG_RC_OK - if successful action

• PCFG_RC_INVALID_CHAN - if configuration error on pin selection

• PCFG_RC_BAD_ARGS_MIOS_CLK - if configuration error on clock speed parameter 5.9. Analogue input/output feature (PAX) 5.9.1. Overview 5.9.1.1. Hardware effects on signals

The functions work at the level of the micro-processor pin but the input and output circuitry of the ECU may change the characteristics of the signal. For instance, the input circuitry may include filtering. See the technical specification in Section A.1, “ECU hardware reference documentation” for a description of how the input and output circuitry works for an ECU. 5.9.1.2. Analogue input

The library supports reading the state of an analogue input as seen at the micro-processor pin (see pax_adc_input()). Across the target ECUs some A/D converters have different resolutions. To avoid ambiguity as code is ported between targets, the result of an A/D conversion is always scaled to the range [-1, 1] @ 1/4096 A/D counts per bit (i.e., as if the A/D conversion was 12-bit in range) with the exception of the values coming off of the IMU on the M250-00Z which may have a wider scaling range. Please see the M250 technical specification for further details regarding the scaling. The application must scale the raw A/D conversion to engineering units, and the utility functions put_cal_map_1d_f32(), put_leaky_bucket_f32(), or put_process_analog_input() can all help.

On all modules, the worst case conversion time for an A/D value is ~500µs. Thus, when the software asks for a A/D conversion, the A/D value may be up to 500µs old.

Most target ECUs provide internal signals for determining the reference voltage used for conversion, and this can be used for ratio-metric inputs. 5.9.1.3. Analogue output

The library supports writing an analog output via a SPI analogue output device. Please see pax_dac_output() for details. The analogue output functionality is currently only supported on the M221.

The analogue output function uses the SPI device to talk from the ECU to a digital potentiometer which sets the analogue output resistance. The output is set by passing a value of 0 to 1 which represents the fraction of the total output resistance range as defined by the circuit. For details on the output resistance, see the technical specification for the target hardware that you are using.

5.9.1.4. Constant current output

The library supports driving constant current output (see pax_cc_output()). Across the target ECUs some constant current output devices have different resolutions. 5.9.1.5. Constant current dither

The library supports a hardware controlled dither for TLE8242-2 outputs (see pax_cc_config_tle8242()). The dither waveform is specified by the number of dither steps and the size of each step. Each output pulse advances the dither waveform by one step. The following diagram demonstrates the relationship between the pulse period, number of dither steps, and the dither step size.

Figure 5.4. TLE8242-2 Dither

Pulse Period

Pulse Output

Dither Step

Dither Waveform ¼ Dither Waveform

Setpoint

Dither Step Size Pulse Start Pulse

Time

5.9.1.6. Constant current PI control

The library supports configurable hardware PI control for TLE8242-2 outputs (see pax_cc_config_tle8242()). Each channel of the TLE8242-2 device includes a separate PI controller with programmable gain values KP and KI. The Infineon TLE7242 KI KP Application note describes a method to determine acceptable KP and KI values. A summary is included here; Please refer the the Infineon application note for additional details.

Acceptable KP and KI values may be determined by modeling the control system with a linear continuous time model.

Figure 5.5. TLE8242-2 constant current control diagram

Parameters required to calculate KP and KI

VBAT Supply voltage of the load.

Rc Resistance of the load.

Lc Inductance of the load measured at the pulse frequency.

Rsense Sense resistance value. This value is determined by the OpenECU hardware. It is 100 mR for all outputs.

Fclk Master clock frequency of the TLE8242-2 device. The frequency is set to 22 MHz by the OpenECU platform.

FPWM Pulse frequency of the output channel.

Procedure to calculate KP and KI

Determine Pulse Frequency Set pulse frequency to the upper limit unless some constraint of the load requires it to be lower.

Determine the damping ratio of the system Start with 0.707. Increase toward 1 to reduce overshoot. Decrease to improve rise time. The damping ratio is denoted by zeta in the supplied equations.

Determine the undamped natural frequency Calculate according to equation 1. Decreasing will result in longer settling time and increased dither amplitude attenuation. Increasing will lead to poor matching of the linear model to the system.

Calculate KP' and KI' Calculate according to equations 2 and 3. If KP' is less than zero, then the pulse frequency is too low.

Calculate KP and KI Calculate according to equations 4 and 5. If KP or KI is greater than 4095, then the undamped natural frequency must be decreased.

Figure 5.6. TLE8242-2 KP and KI equations

5.9.1.7. External devices

There are two types of I/O on OpenECU hardware: direct and indirect I/O.

Figure 5.7. Direct and indirect analogue outputs

Direct output signal Output circuitry

To external actuators Processor Output Output device circuitry Serial Direct communications output signal

Internal to ECU External to ECU

Direct I/O Direct I/O takes place on demand. The application calls the necessary function and the function takes a measurement or sets a driver accordingly.

Indirect I/O Indirect I/O is delayed. The application calls the necessary function but the data to be read or set is actioned some time after the function returns.

Indirect I/O always occurs when there is an device between the processor and the pin. The device communicates to the processor across a serial link and it is this communication which introduces the delay. Serial communication is initiated at the end of any task which accesses the device to perform an I/O operation. This is accomplished by calling psp_spi_trigger()

at the end of each application task. Only I/O channels noted as serial in the technical specification (see Section A.1, “ECU hardware reference documentation”) are affected. 5.9.1.8. Monitors

Each target ECU provides some measure of feedback for a subset of the output pins. For instance, measuring the reference voltage for A/D conversions to determine if the reference voltage generator has failed. A complete list of the monitors can be found in the technical specifications (see Section A.1, “ECU hardware reference documentation”). Each monitor is read by using one of the existing feature functions, e.g., by calling pax_adc_input() to read the analogue voltage of a monitor. 5.9.2. Interface index

An index of interface objects for this feature.

Type Identifier Include file openecu.h and pax.h Enumerations PAX_RC_T

An enumerated type which contains success and failure codes returned by some analogue input feature (PAX) functions. PAX_ERROR_CODE_T

Error values for debugging when an error is found when calling the analogue input feature (PAX), the API calls a function with an enumeration from this type. Data types PAX_LCHAN_T

This declares a type with enough value range to represent all logical channels for all targets. Functions PAX_RC_T pax_adc_input

Function to initialise or read an analogue input channel. PAX_RC_T pax_cc_output

Function to initialise or drive a constant current output channel. PAX_RC_T pax_dac_output

Function to drive an analogue output channel. void pax_set_input_update_rate

Set the rate at which a serial based analogue input channel will be read (deprecated). void pax_set_output_update_rate

Set the rate at which a serial based analogue output channel will be updated (deprecated).

Type Identifier PAX_RC_T pax_cc_config_tle8242

Configures a TLE8242-2 peripheral constant current output channel. PAX_RC_T pax_cc_select_meas_chan_tle8242

Selects a TLE8242-2 peripheral constant current channel for measurement. PAX_RC_T pax_cc_read_meas_chan_tle8242

Reports measurements for a previously selected TLE8242-2 peripheral constant current channel. PAX_RC_T pax_cc_autozero_tle8242

Commands a TLE8242-2 peripheral constant current channel to autozero. 5.9.3. Interface detail 5.9.3.1. Enumerations

5.9.3.1.1. PAX_RC_T

Summary: An enumerated type which contains success and failure codes returned by some analogue input feature (PAX) functions.

Enumerations:

PAX_RC_OK Return code if everything progressed as expected.

PAX_RC_SW_ERROR Return code if an internal error occurred which was the result of a software error.

PAX_RC_HW_ERROR Return code if a hardware error occurred which stopped a channel being sampled or actuated.

PAX_RC_BAD_ARGS Return code if at least one of the arguments could not be used.

PAX_RC_FREQ_ERROR Return code if the requested frequency of current modulation is out of range.

PAX_RC_OFFSET_ERROR Return code if the requested pulse phase offset is out of range.

PAX_RC_DITHER_ERROR Return code if the requested dither is invalid.

PAX_RC_CONTROL_LOOP_ERROR Return code if one or more of the control loop parameters are out of range.

5.9.3.1.2. PAX_ERROR_CODE_T

Summary: Error values for debugging when an error is found when calling the analogue input feature (PAX), the API calls a function with an enumeration from this type.

Enumerations:

PAX_ADC_INPUT_INVALID_ARG Error raised if the analogue input function finds an invalid argument.

PAX_CC_OUTPUT_INVALID_ARG Error raised if the constant current output function finds an invalid argument.

PAX_CHANNEL_INVALID Error raised if the analogue channel 'n' is not supported.

'n' is (error_code - PAX_CHANNEL_INVALID).

PAX_ADC_INPUT_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as an analogue input.

'n' is (error_code - PAX_ADC_INPUT_CHANNEL_UNSUPPORTED).

PAX_CC_OUTPUT_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as an current output.

'n' is (error_code - PAX_CC_OUTPUT_CHANNEL_UNSUPPORTED).

PAX_AOT_OUTPUT_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as an analogue output.

'n' is (error_code - PAX_AOT_OUTPUT_CHANNEL_UNSUPPORTED). 5.9.3.2. Data types

5.9.3.2.1. PAX_LCHAN_T

Definition: typedef U16 PAX_LCHAN_T

Description: This declares a type with enough value range to represent all logical channels for all targets.

See pio.h for a list of relevant channels for a specific target. 5.9.3.3. Functions

5.9.3.3.1. pax_adc_input()

Definition: PAX_RC_T pax_adc_input(PAX_LCHAN_T paxf_lchan, S16 *paxf_adc, BOOL paxf_init)

Supported targets: All targets

Required license: None (Main library).

Description: Function to initialise or read an analogue input channel.

This function initialises or reads an analogue input channel. If the input arguments are valid, the function writes the conversion result that reflects the conversion for the specified channel through paxf_adc. If the input arguments are invalid, the function does not modify the conversion result.

Can raise the following errors: PAX_CHANNEL_INVALID, PAX_ADC_INPUT_CHANNEL_UNSUPPORTED and PAX_ADC_INPUT_INVALID_ARG

Note

Consider hardware effects such as filtering, etc..

Arg (data in): paxf_lchan The channel number of the analogue input channel to be read. Use the macros included by the pio.h file, of the form PIO_AIN_[NAME].

Arg (data out): paxf_adc Pointer to the conversion result for the analogue input channel. Can be NULL during application initialisation. Cannot be NULL during application run. Range: [-1, 1] @ 1/4096 A/D counts per LSB

Note

Note that some of the values supplied by the IMU on the M250-00Z have a different range of representation. The gyroscope value and gyroscope angle provide a 14-bit signed value and a 14-bit unsigned value respectively.

Arg (data in): paxf_init True if the channel is to be initialised, false otherwise.

Return:

• PAX_RC_OK - if normal operation

• PAX_RC_BAD_ARGS - if an internal error has occurred

• PAX_RC_SW_ERROR - if a recoverable error has been raised.

5.9.3.3.2. pax_cc_output()

Definition: PAX_RC_T pax_cc_output(PAX_LCHAN_T paxf_lchan, S16 paxf_cc, BOOL paxf_init)

Supported targets: All targets

Required license: None (Main library).

Description: Function to initialise or drive a constant current output channel.

This function initialises or drives a constant current output channel.

Can raise the following errors: PAX_CHANNEL_INVALID and PAX_CC_OUTPUT_CHANNEL_UNSUPPORTED

Note

Consider hardware effects such as low-side/high-side driven, filtering, etc..

Arg (data in): paxf_lchan The channel number of the constant current output channel to drive. Use the macros included by the pio.h file, of the form PIO_CCOT_[NAME].

Arg (data in): paxf_cc The required current to be driven, given as a unit range. Consider hardware effects such as low-side/high-side driven, etc.. Range: [0, 2] A @ 1 mA per LSB (for M670 targets)

Arg (data in): paxf_init True if the channel is to be initialised, false otherwise.

Return:

• PAX_RC_OK - if normal operation

• PAX_RC_SW_ERROR - if a recoverable error has been raised

• PAX_RC_BAD_ARGS - if pax_lchan argument is incorrect 5.9.3.3.3. pax_dac_output()

Definition: PAX_RC_T pax_dac_output(PAX_LCHAN_T paxf_lchan, S16 paxf_dac_level, BOOL paxf_init)

Supported targets:

Required license: None (Main library).

Description: Function to drive an analogue output channel.

Note

Consider hardware effects such as low-side/high-side driven, filtering, etc.

Arg (data in): paxf_lchan The channel number of the analog output channel to write. Use the macros included by the pio.h file, of the form PIO_AOT_[NAME].

Arg (data in): paxf_dac_level The required analog output level fo 12bit DAC output. Range: [-1, 1] @ 1/4096 A/D counts per LSB

Arg (data in): paxf_init True if the channel is to be initialised, false otherwise.

Return:

• PAX_RC_OK - if normal operation

• PAX_RC_SW_ERROR - if a recoverable error has been raised

• PAX_RC_BAD_ARGS - if pax_lchan argument is incorrect 5.9.3.3.4. pax_set_input_update_rate()

Definition: void pax_set_input_update_rate(PAX_LCHAN_T paxf_lchan)

Supported targets: All targets

Required license: None (Main library).

Description: Set the rate at which a serial based analogue input channel will be read (deprecated).

Became deprecated in version 1.8.0. This function will be removed in a future release. This function is no longer necessary, please remove from use in application code.

Arg (data in): paxf_lchan The channel number of the analogue channel to read. Use the macros included by the pio.h file, of the form PIO_[NAME]. 5.9.3.3.5. pax_set_output_update_rate()

Definition: void pax_set_output_update_rate(PAX_LCHAN_T paxf_lchan)

Supported targets: All targets

Required license: None (Main library).

Description: Set the rate at which a serial based analogue output channel will be updated (deprecated).

Became deprecated in version 1.8.0. This function will be removed in a future release. This function is no longer necessary, please remove from use in application code.

Arg (data in): paxf_lchan The channel number of the analogue channel to drive. Use the macros included by the pio.h file, of the form PIO_[NAME].

5.9.3.3.6. pax_cc_config_tle8242()

Definition: PAX_RC_T pax_cc_config_tle8242(PAX_LCHAN_T paxf_lchan, F32 paxf_freq, F32 paxf_pulse_offset, U16 paxf_kp, U16 paxf_ki, U16 paxf_dither_steps, U16 paxf_dither_step_size)

Supported targets:

Required license: None (Main library).

Description: Configures a TLE8242-2 peripheral constant current output channel.

The current setpoint is established through the common pax_cc_output() interface function. Additional configuration specific to the TLE8242-2 is managed through this function. The setpoint and configuration for a channel must be carried out in the same task to ensure data coherence.

Can raise the following errors: PAX_CHANNEL_INVALID

Arg (data in): paxf_lchan The channel number of the constant current output channel to configure. Use the macros included by the pio.h file, of the form PIO_CCOT_[NAME].

Arg (data in): paxf_freq The desired frequency of the output. If the software cannot match the desired frequency, the frequency will be adjusted to as close a match as is possible. Range: [10.5, 4000] Hz

Arg (data in): paxf_pulse_offset The desired phase offset of the output relative to the TLE8242-2 phase sync signal. If the offset is initialised to a non zero value, then the outputs will hold until the phase sync signal is pulsed. The phase sync signal may be pulsed during runtime to syncronise outputs. If the software cannot match the desired pulse offset, the offset will be adjusted to as close a match as possible within 1/32 increments of the pulse period. Range: [0, 31/32 of pulse period] ms

Arg (data in): paxf_kp The desired proportional coefficient of the PI control loop that determines the duty cycle of the constant current output. The supplied value is passed directly to the TLE8242-2 KP register without scaling applied. Range: [0, 4095] unitless

Arg (data in): paxf_ki The desired integral coefficient of the PI control loop that determines the duty cycle of the constant current output. The supplied value is passed directly to the TLE8242-2 KI register without scaling applied.

Range: [0, 4095] unitless

Arg (data in): paxf_dither_steps The desired number of dither steps (one per PWM period) between the centre current value and the maximum, at which the steps reverse direction, etc. Hence the total dither cycle waveform period is the PWM period x 4 x this parameter (see diagram in the user guide section "Constant current dither"). If the software cannot match the number of dither steps, the number of steps will be adjusted to as close a match as possible. Range: [0, 31] steps per 1/4 dither cycle.

Arg (data in): paxf_dither_step_size The desired dither step size. If the software cannot match the desired dither step size, the step size will be adjusted to as close a match as possible. Range: [0, 500] mA

Return:

• PAX_RC_OK - if normal operation

• PAX_RC_SW_ERROR - if a recoverable error has been raised

• PAX_RC_BAD_ARGS - if pax_lchan argument is incorrect

5.9.3.3.7. pax_cc_select_meas_chan_tle8242()

Definition: PAX_RC_T pax_cc_select_meas_chan_tle8242(PAX_LCHAN_T paxf_lchan)

Supported targets:

Required license: None (Main library).

Description: Selects a TLE8242-2 peripheral constant current channel for measurement.

This interface allow the caller to select the TLE8242-2 output for measurement of minimum, maximum, and average current. TLE8242-2 channels cannot be measured in parallel.

Can raise the following errors: PAX_CHANNEL_INVALID

Arg (data in): paxf_lchan The channel number of the constant current output channel to configure. Use the macros included by the pio.h file, of the form PIO_CCOT_[NAME].

Return:

• PAX_RC_OK - if normal operation

• PAX_RC_SW_ERROR - if a recoverable error has been raised

5.9.3.3.8. pax_cc_read_meas_chan_tle8242()

Definition: PAX_RC_T pax_cc_read_meas_chan_tle8242(BOOL *paxf_valid, F32 *paxf_min_current, F32 *paxf_max_current, F32 *paxf_avg_current)

Supported targets:

Required license: None (Main library).

Description: Reports measurements for a previously selected TLE8242-2 peripheral constant current channel.

This interface fetches the measurements for a TLE8242-2 output. The results are not valid until the current dither cycle has completed. TLE8242-2 channels cannot be measured in parallel.

Arg (data out): paxf_valid Flag indicating that the dither cycle has completed and the results are valid.

Arg (data out): paxf_min_current Minimum current over the last dither cycle for the selected channel. Range: [0, 2000] mA

Arg (data out): paxf_max_current Maximum current over the last dither cycle for the selected channel. Range: [0, 2000] mA

Arg (data out): paxf_avg_current Average current over the last dither cycle for the selected channel. Range: [0, 2000] mA

Return:

• PAX_RC_OK - if normal operation

• PAX_RC_SW_ERROR - if a recoverable error has been raised

• PAX_RC_BAD_ARGS - if any arguments are NULL pointers

5.9.3.3.9. pax_cc_autozero_tle8242()

Definition: PAX_RC_T pax_cc_autozero_tle8242(PAX_LCHAN_T paxf_lchan, BOOL *paxf_autozero_done)

Supported targets:

Required license: None (Main library).

Description: Commands a TLE8242-2 peripheral constant current channel to autozero.

This interface allow the caller to initiate autozero of a TLE8242-2 device channel. The current setpoint must be set to zero before triggering the autozero feature. TLE8242-2 channels cannot be autozeroed in parallel.

Can raise the following errors: PAX_CHANNEL_INVALID

Arg (data in): paxf_lchan The channel number of the constant current output channel to zero. Use the macros included by the pio.h file, of the form PIO_CCOT_[NAME].

Arg (data out): paxf_autozero_done Flag indicating that the autozero has completed. The function must be polled during subsequent task iterations to determine that autozero has completed.

Return:

• PAX_RC_OK - if normal operation

• PAX_RC_SW_ERROR - if a recoverable error has been raised

• PAX_RC_BAD_ARGS - if any arguments are invalid 5.10. Digital input/output feature (PDX) 5.10.1. Overview

The library supports various functions to access I/O pins, a summary of which is given below. 5.10.1.1. Hardware effects on signals

The functions work at the level of the micro-processor pin but the input and output circuitry of the ECU may invert the sense of the signal — see the technical specification for a description of how the input circuitry works for an ECU (Section A.1, “ECU hardware reference documentation”).

The input circuitry may include filtering which can affect the input signal. The filter may introduce a limit of frequency range (the signal may undetectable outside of the filters range) and may also introduce signal phase. For rising and falling edges of the signal, the phase may be different, hence the measured high and low time of a pulse train, for example, may not be as expected without the ECU's input circuitry. Again, see the technical specification for a description of how the input circuitry works for an ECU. 5.10.1.2. Digital input

The library supports reading the state of a digital input as seen at the micro- processor pin (see pdx_digital_input()). The utility functions put_debounce_by_cycles() and put_debounce_by_time() can be used to debounce the signal state. 5.10.1.3. Frequency input

The library supports reading the frequency of a digital input as seen at the micro-processor pin (see pdx_frequency_input()). 5.10.1.4. PWM input

The library supports reading the frequency and duty cycle of a digital input as seen at the micro-processor pin (see pdx_pwm_input()). The function measures the time of each high and low (or low and high) pulse to determine the frequency of the input signal.

First pulse Second pulse time time

Input signal

active low if invert is 0 Cycle time (1/Frequency)

First pulse Second pulse time time

Input signal

active high if invert is 1 Cycle time (1/Frequency)

Note

Whether the block measures a low pulse followed by a high pulse, or a high pulse followed by a low pulse is determined during initialisation of the input channel.

The function measures the durations of the first and second pulses and derives the duty cycle (first pulse time divided by the cycle time). Very small duty cycles (less than 1% or greater than 99%) will not be measured accurately or at all.

The function accumulates the count of complete periods modulo 21777216. The application calculated difference of counts between iterations of the block could be used to diagnose unexpected changes in the signal.

Input signal

Cycle/period count 0 1 2

Start of Start of Start of period period period

The function measures the period duration and determines whether the signal has taken longer than the timeout duration. The function accumulates the count of time out events and indicates if the signal is timed out when the function is called.

Input signal

Time out count 0 1 2

Block iterates Signal Signal Block iterates no timeout yet times out times out time out count is 2 and recorded signal shown as not currently timed out

5.10.1.5. Quadrature input

The library supports the decoding of quadrature signals from a quadrature encoder (see pdx_quad_input()). A quadrature encoder generates a pulse train from two sensors which pick up markings on the encoder disk.

Figure 5.8. Quadrature encoder and generated signals

Primary and secondary sensors detect encoder disk markings.

Primary channel The sensor signals are conditioned by the encoder and sensed by OpenECU. Secondary channel Encorder disk, rotating forwards. Primary and secondary channel edges 90° out of phase. Decoding the phase of the edges determines the rotation of the encoder.

The sensors and markings are arranged so that when the encoder is turning, the sensor signals generate two pulse trains 90° out of phase. If the disk is turning in a forwards direction, the primary channel edges will lead the secondary channel edges. If the disk is turning in a backwards direction then the primary channel edges will lag the secondary channel edges. If there are no signal edges on either channel after a period of time, then the encoder has stopped turning (or is turning slowly enough to be considered stationary).

Figure 5.9. Direction of encoder and generated signals

Primary channel shows leading edges. Primary channel shows lagging edges. Forwards direction Backwards direction

Primary channel

Secondary channel

No pulses on either channel. Stopped.

The quadrature decode functions measure the primary and secondary channels, determine the direction at each pulse and count the pulses. If the encoder is turning forwards then for each edge on the primary and secondary channels, the functions increment the count. If the encoder is turning backwards then for each edge on the primary and secondary channels, the functions decrement the count. When either function is called, the function outputs the count of pulses and resets the count to zero.

For instance, if the encoder turns forwards for nine edges between calls to the function, the pulse count from the functions will be nine. If the encoder turns forwards for six edges and then backwards for two edges between calls of the functions, the pulse count from the functions will be four.

Figure 5.10. Pulse count example

Primary channel shows Primary channel shows Primary channel shows leading edges. leading edges. lagging edges. Forwards direction Forwards direction Backwards direction

Primary channel

Secondary channel

Edge count 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 5 4

Function call Function call Function call Function call reset count to zero reset count to zero reset count to zero reset count to zero

Note

Some encoders provide an index signal and some encoders provide complement signals of the primary and secondary signals, both for the purposes of improving reliability. This function does not decode these signals.

A second function (see pdx_quad_freq_input()) provides the same functionality but also measures the duration of each pulse from the encoder primary and secondary channels and returns the last measured frequency of each channel. 5.10.1.6. SENT input (SAE J2716)

The library supports the decoding of SENT sensors for fast data from individual frames (see pdx_sent_input()) and for slow data from sequential frames (see pdx_sent_serial_input()). A SENT sensor encodes data into frames using variable width pulses:

Figure 5.11. SENT frame

Previous frame Status Data 2 Data 4 Data 6 Pause Pause (optional) 12 ticks 17 ticks 14 ticks 12 ticks (optional) or CRC value 0 value 5 value 2 value 0

Calibration / Data 1 Data 3 Data 5 CRC synchronisation pulse 27 ticks 22 ticks 20 ticks 21 ticks 56 SENT ticks value 15 value 10 value 8 value

Overall SENT frame – 154 to 270 SENT ticks (depending on data values), followed by optional pause pulse between frames

The library synchronises to the calibration pulse and decodes the remaining frame pulses based on the expected calibration pulse width time and the actual pulse width time. Across sequential valid SENT frames, the library will extract any serial data from the status nibble.

The library performs various diagnostics:

• checks the SENT sensor clock variance by allowing no more than ±25% of the expected calibration pulse width

• checks frame to frame variability of the calibration pulse (allowing a change in width no more than 1.5625%)

• checks the expected number of fast data nibbles is received

• checks the frame CRC and slow serial CRC 5.10.1.7. Digital output

The library supports setting the state of a digital output (see pdx_digital_output()). 5.10.1.8. PWM output

The library supports setting the frequency and duty cycle of a PWM output (see pdx_pwm_output()), where duty cycle is defined as the High time divided by the Cycle time for a given channel.

High time

Output channel signal Low time

Cycle time (1/Frequency)

High time

Inverted output channel signal

Low time

Cycle time (1/Frequency)

The utility function put_dutycycle_processing() supports scaling and clipping of the duty cycle, and inversion of the PWM signal.

The channel output can be offset from other PWM channels of the same frequency. The Offset argument is used to delay the start of the PWM cycle, so that the PWM pulse will not occur at the same time as other PWM signals of the same frequency.

Other channel (with same frequency) signal

Channel signal

Offset delay time

5.10.1.9. Synchronised PWM output

The library supports the generation of a synchronised PWM signal using two output pins (see pdx_spwm_output()). The second output pin is synchronised to the first and optionally has a programmable delay. The frequency and duty cycle are independent for each pin and can be changed between calls to the function.

The duty cycle is the High time divided by the Cycle time for a given channel.

High time

Master channel signal Low time

High time

Slave channel signal Low time

Cycle time (1/Frequency)

The slave channel is generated relative to the master channel pulse (in this instance, both the master and slave channels are generated with the same frequency).

Master channel signal

Slave channel signal

Synchronisation Synchronisation point point

The slave pulse can be delayed relative to the master pulse by setting the parameter {Slave delay} to a non-zero value.

Master channel signal

Slave channel signal

Slave delay time

In all cases, only one pulse per cycle is generated by both the master and slave channels. For instance, if the frequency of the slave channel was twice that of the master channel, only one pulse would be generated by the slave channel.

Master channel signal

Slave channel signal

Frequency of slave channel twice that of master channel, but only one slave pulse generated.

The Master channel output (and thus the slave) can be offset from other PWM channels of the same frequency. The Master Offset argument is used to delay the start of the PWM cycle, so that the PWM pulse will not occur at the same time as other PWM signals of the same frequency.

Other channel (with same frequency) signal

Master channel signal

Slave channel signal

5.10.1.10. Peak and hold injector output

The library supports the generation of a signal to control a peak and hold injector (see pdx_phinj_output()). This consists of a stepped current signal generated at the selected injector frequency, in which the current is firstly controlled to the peak current threshold for the duration determined by the peak duty cycle, after which it is controlled to the hold current threshold for the remaining duration of the peak-hold duty cycle (i.e. the duration of the peak- hold duty cycle minus the peak duty cycle), after which the current falls to zero until the beginning of the next cycle.

The injector frequency, peak duty cycle, peak-hold duty cycle and injector clock frequency are all passed as arguments to this function and can be changed between calls.

Figure 5.12. Peak-hold injector output

Peak current

Hold current

Injector current

Peak channel

Peak and hold channel

Injector clock

Cycle time = 1/Injector frequency

The injector frequency is 1 / Cycle time. The peak duty is the Peak current duration divided by the Cycle time. The peak-hold duty is the sum of the Peak current duration and the Hold current duration, divided by the Cycle time. The actual peak-hold duty is constrained to be at least as great as the peak duty.

The channel output can be offset from other injector channels of the same frequency. The Offset parameter is used to delay the start of the injector cycle, so that the injector will not activate at the same time as other injector signals of the same frequency.

Other channel (with same frequency) signal

Channel signal

Offset time

The utility function put_dutycycle_processing() can be used to scale and clip the duty cycle inputs prior to calling this function, but no inversion should be applied. 5.10.1.11. H-Bridge output

The library support setting the mode, frequency and duty-cycle of H-Bridge output (see pdx_hbridge_output()), where channel pins are driven accordingly.

The H-Bridge output function controls a load connected between the two ECU pins in the desired mode. Four modes are provided allowing the H-Bridge output to have no drive (all switches open), brake (high-side switches closed), forward or reverse (one side is connected to high-side while the other is PWM'ed to ground at a programmable frequency and dutycycle).

The duty-cycle used in forward and reverse mode is defined as the proportion of time where the load is driven (low-side switch is grounded).

The block supports 0% and 100% duty cycles.

Warning

To avoid unexpected behavior, H-bridges should be set to NO DRIVE mode before flashing the ECU. This can be done by commanding the actuators to NO DRIVE any time the engine is not turning.

Note

Some of the PWM output channels do not produce an accurate waveform when the duty cycle is either very small (e.g., 0.5%) or very large (e.g., 99.5%). All H-bridge output channels cope with 0% and 100% duty cycles correctly.

For the M250 target specifically, in order to avoid shoot-through and damage to the ECU when the mode switches, a 100us dead-time is inserted in the PWM signal for one task cycle at the beginning of mode-transition. Additionally, this dead-time insertion will only occur if the duty cycle that is commanded has a low time of less than 100us.

For this reason, it will not be possible to command a 100% duty cycle during mode- transition for one task period. See diagram below for further detail.

Figure 5.13. Output of H-Bridge during mode transition

Application task requests mode change Application task requests from No-drive to Forwards same mode, Forwards

100us

A30

A30 is requested to have a high duty cycle, After one task iteration is complete and but it is extended to 100 microsecond off the mode is unchanged, the duty cycle is time (dead time) for one task duration. restored (dead-time removed).

Correspondingly, A1 would have 100% duty cycle, but is forced to 100 microseconds dead time for the same task Iteration.

5.10.1.12. External devices

There are two types of I/O on OpenECU hardware: direct and indirect I/O.

Figure 5.14. Signal update rates

Direct output signal Output circuitry

To external actuators Processor Output Output device circuitry Serial Direct communications output signal

Internal to ECU External to ECU

Direct I/O Direct I/O takes place on demand. The application calls the necessary function and the function takes a measurement or sets a driver accordingly.

Indirect I/O Indirect I/O is delayed. The application calls the necessary function but the data to be read or set is actioned some time after the function returns.

the end of each application task. Only I/O channels noted as in the technical specification (see Section A.1, “ECU hardware reference documentation”) are affected. 5.10.1.13. Monitors

Each target ECU provides some measure of feedback for a subset of the output pins. For instance, measuring the actual state of a digital output to determine whether the output is shorted. A complete list of the monitors can be found in the technical specifications (see Section A.1, “ECU hardware reference documentation”). Each monitor is read by using one of the existing feature functions, e.g., by calling pdx_digital_input() to read the digital state of a monitor. 5.10.2. Interface index

An index of interface objects for this feature.

Type Identifier Include file openecu.h and pdx.h Enumerations PDX_RC_T

An enumerated type which contains success and failure codes returned by some digital input feature (PDX) functions. PDX_ERROR_CODE_T

Error values for debugging when an error is found when calling the digital input feature (PDX), the API calls a function with an enumeration from this type. PDX_SENT_SERIAL_FORMAT_T

This enumeration gives the format of the SENT serial data. Data types PDX_LCHAN_T

This declares a type with enough value range to represent all logical channels for all targets. PDX_LCHAN_MONITOR_T

This declares a type with enough value range to represent the groups of output-and-monitor channels for all targets. PDX_LCHAN_PHINJ_T

This declares a type with enough value range to represent logical peak and hold injector channels for all targets. PDX_LCHAN_HBRIDGE_T

This declares a type with enough value range to represent logical H-Bridge channel groups for all targets.

Type Identifier Functions PDX_RC_T pdx_digital_input

Function to initialise or read a digital input channel. PDX_RC_T pdx_digital_monitor_input

Function to initialise or read the status of a digital output monitor. PDX_RC_T pdx_digital_output

Function to initialise or drive a digital output channel. PDX_RC_T pdx_frequency_input

Function to initialise or read a frequency input channel. PDX_RC_T pdx_hbridge_output

Function to initialise or drive an H-Bridge output channel. PDX_RC_T pdx_phinj_output

Function to initialise or drive a peak and hold injector output channel. PDX_RC_T pdx_pwm_input

Function to initialise or read a PWM input channel. PDX_RC_T pdx_pwm_output

Function to initialise or drive a PWM output channel. PDX_RC_T pdx_quad_freq_input

Function to initialise or read a quadrature and frequency input channel. PDX_RC_T pdx_quad_input

Function to initialise or read a quadrature input channel. PDX_RC_T pdx_sent_input

Function to initialise and read a SENT input channel, fast channel signals. PDX_RC_T pdx_sent_serial_input

Function to read a SENT input channel, slow channel signals. PDX_RC_T pdx_spwm_output

Function to initialise or drive a synchronised PWM output channel.

5.10.3. Interface detail 5.10.3.1. Enumerations

5.10.3.1.1. PDX_RC_T

Summary: An enumerated type which contains success and failure codes returned by some digital input feature (PDX) functions.

Enumerations:

PDX_RC_OK Return code if everything progressed as expected.

PDX_RC_SW_ERROR Return code if an internal error occurred which was the result of a software error.

PDX_RC_HW_ERROR Return code if a hardware error occurred which stopped a channel being sampled or actuated.

PDX_RC_BAD_ARGS Return code if at least one of the arguments could not be used.

PDX_RC_FREQ_TOO_LOW Return code if frequency argument is too low.

PDX_RC_FREQ_TOO_HIGH Return code if frequency argument is too large.

PDX_RC_DUTY_OUT_OF_RANGE Return code if duty cycle argument is out of range, [0, 1].

PDX_RC_SDM_ALLOC_ERROR Return code if could not allocate eTPU SDM for function (internal error).

PDX_RC_INACTIVE Return code if input or output device was unresponsive.

PDX_RC_NOT_CONFIGURED Return code if output not configured.

PDX_RC_INVALID_MODE Return code if mode is not supported.

PDX_RC_PEAK_HOLD_TOO_LOW Return code if peak-hold duty cycle is less than peak duty cycle.

PDX_RC_CLIPPED_TO_RANGE Return code if one or more arguments were clipped to range. 5.10.3.1.2. PDX_ERROR_CODE_T

Summary: Error values for debugging when an error is found when calling the digital input feature (PDX), the API calls a function with an enumeration from this type.

Enumerations:

PDX_DO_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as a digital output.

'n' is (error_code - PDX_DO_CHANNEL_UNSUPPORTED).

PDX_DIG_IN_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as a digital input.

'n' is (error_code - PDX_DIG_IN_CHANNEL_UNSUPPORTED).

PDX_FREQ_IN_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as a frequency input.

'n' is (error_code - PDX_FREQ_IN_CHANNEL_UNSUPPORTED).

PDX_PERIOD_IN_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as a period input.

'n' is (error_code - PDX_PERIOD_IN_CHANNEL_UNSUPPORTED).

PDX_QDEC_FREQ_IN_INVALID_ARG Error raised if the quadrature and frequency input function has an invalid argument.

PDX_QDEC_FREQ_IN_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as a quadrature and frequency input.

'n' is (error_code - PDX_QDEC_FREQ_IN_CHANNEL_UNSUPPORTED).

PDX_TPU_QFI_CHANNEL_DEVICE_ERROR Error raised in quadrature and frequency input, if the primary channel 'n' and the secondary channel are not on the same device.

'n' is (error_code - PDX_TPU_QFI_CHANNEL_DEVICE_ERROR).

PDX_QDEC_IN_INVALID_ARG Error raised if the quadrature input function has an invalid argument.

PDX_QDEC_IN_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as a quadrature input.

'n' is (error_code - PDX_QDEC_IN_CHANNEL_UNSUPPORTED).

PDX_TPU_QI_CHANNEL_DEVICE_ERROR Error raised in quadrature input, if the primary channel 'n' and the secondary channel are not on the same device.

'n' is (error_code - PDX_TPU_QI_CHANNEL_DEVICE_ERROR).

PDX_PWM_OUT_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as a PWM output.

'n' is (error_code - PDX_PWM_OUT_CHANNEL_UNSUPPORTED).

PDX_SYNC_PWM_OUT_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as a synchronised PWM output.

'n' is (error_code - PDX_SYNC_PWM_OUT_CHANNEL_UNSUPPORTED).

PDX_TPU_SPO_CHANNEL_DEVICE_ERROR Error raised in synchronised PWM output, if the primary channel 'n' and the secondary channel are not on the same device.

'n' is (error_code - PDX_TPU_SPO_CHANNEL_DEVICE_ERROR).

PDX_PWM_IN_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as a PWM input.

'n' is (error_code - PDX_PWM_IN_CHANNEL_UNSUPPORTED).

PDX_CHANNEL_INVALID Error raised if the digital channel 'n' is not supported.

'n' is (error_code - PDX_CHANNEL_INVALID).

PDX_TLE4953_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as a TLE-4953 input.

'n' is (error_code - PDX_TLE4953_CHANNEL_UNSUPPORTED).

PDX_HBRIDGE_INVALID_MODE Error raised if the H-bridge mode has an invalid value.

PDX_HBRIDGE_CHANNEL_MISMATCH Error raised if the H-bridge channels are not on the same device.

PDX_HBRIDGE_DECODE_ERROR Error raised if something went wrong when decoding a device and/ or channel necessary for H-bridge operation.

PDX_HBRIDGE_CHANNEL_GROUP_UNSUPPORTED Error raised if channel group 'n' cannot be used as an H-bridge output.

'n' is (error_code - PDX_HBRIDGE_CHANNEL_GROUP_UNSUPPORTED).

PDX_DIG_MONITOR_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as a digital data input.

'n' is (error_code - PDX_DIG_MONITOR_CHANNEL_UNSUPPORTED).

PDX_SENT_IN_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as a SENT input.

'n' is (error_code - PDX_SENT_IN_CHANNEL_UNSUPPORTED). 5.10.3.1.3. PDX_SENT_SERIAL_FORMAT_T

Summary: This enumeration gives the format of the SENT serial data.

Enumerations:

PDX_SENT_SERIAL_SHORT The serial data is short, over 16 consecutive SENT frames.

4-bits message ID and 8-bits data.

PDX_SENT_SERIAL_ENHANCED_1 The serial data is enhanced format 1, over 18 consecutive SENT frames.

8-bits message ID and 12-bits data.

PDX_SENT_SERIAL_ENHANCED_2 The serial data is enhanced format 2, over 18 consecutive SENT frames.

4-bits message ID and 16-bits data. 5.10.3.2. Data types

5.10.3.2.1. PDX_LCHAN_T

Definition: typedef U16 PDX_LCHAN_T

Description: This declares a type with enough value range to represent all logical channels for all targets.

See pio.h for a list of relevant channels for a specific target.

5.10.3.2.2. PDX_LCHAN_MONITOR_T

Definition: typedef U16 PDX_LCHAN_MONITOR_T

Description: This declares a type with enough value range to represent the groups of output-and-monitor channels for all targets.

See pio.h for a list of relevant channels for a specific target.

5.10.3.2.3. PDX_LCHAN_PHINJ_T

Definition: typedef U8 PDX_LCHAN_PHINJ_T

Description: This declares a type with enough value range to represent logical peak and hold injector channels for all targets.

See pio.h for a list of relevant channels for a specific target.

5.10.3.2.4. PDX_LCHAN_HBRIDGE_T

Definition: typedef U16 PDX_LCHAN_HBRIDGE_T

Description: This declares a type with enough value range to represent logical H- Bridge channel groups for all targets.

See pio.h for a list of relevant channels for a specific target.

5.10.3.3. Functions

5.10.3.3.1. pdx_digital_input()

Definition: PDX_RC_T pdx_digital_input(PDX_LCHAN_T pdxf_lchan, U8 *pdxf_state, BOOL pdxf_init)

Supported targets: M560-000 and M560-000

Required license: None (Main library).

Description: Function to initialise or read a digital input channel.

Note

Consider hardware effects such as inversion, etc.. Can raise the following errors: PDX_DIG_IN_CHANNEL_UNSUPPORTED + pdxf_lchan, or PDX_CHANNEL_INVALID + pdxf_lchan

Arg (data in): pdxf_lchan The digital channel to use as a digital input. Use the macros included by the pio.h file, of the form PIO_DIN_[NAME].

Arg (data out): pdxf_state The state of the digital input is written through this pointer. Consider hardware effects such as inversion, etc.. Cannot be NULL. Range: 0 or 1

Arg (data in): pdxf_init True if the channel is to be initialised, false otherwise.

Return:

• PDX_RC_OK - if successful action

• PDX_RC_SW_ERROR - if channel not supported

• PDX_RC_HW_ERROR - if error initialising channel

• PDX_RC_BAD_ARGS - if configuration error

• PDX_RC_SDM_ALLOC_ERROR - if error allocating RAM for SDM

5.10.3.3.2. pdx_digital_monitor_input()

Definition: PDX_RC_T pdx_digital_monitor_input(PDX_LCHAN_T pdxf_lchan, F32 pdxf_rise_time, BOOL *pdxf_valid, U32 *pdxf_rise_fail_count, U32 *pdxf_fall_fail_count, BOOL pdxf_init)

Supported targets:

Required license: None (Main library).

Description: Function to initialise or read the status of a digital output monitor.

Can raise the following errors: PDX_DIG_MONITOR_CHANNEL_UNSUPPORTED + pdxf_lchan, or PDX_CHANNEL_INVALID + pdxf_lchan

Arg (data in): pdxf_lchan The channel to use as a digital output monitor. Use the macros included by the pio.h file, of the form PIO_DMIN_[NAME].

Arg (data in): pdxf_rise_time The time after the output has been commanded high when the state of the monitor input channel is to be tested. The value passed here is clipped to range if necessary. Note that the corresponding fall-time is hard-coded and not accessible to the application via this function. Range: [0, 2000000] us

Arg (data out): pdxf_valid The validity flag for the monitor channel is written through this pointer. Monitors are only supported for certain output functions, and if an unsupported output function is in use on the corresponding output channel then this flag will read FALSE. Currently supported functions are spark and PWM outputs. Cannot be NULL. Range: [0, 16777215]

Arg (data out): pdxf_rise_fail_count The number of times that the output failed to rise within the time specified by the pdxf_rise_time parameter is written through this pointer. Cannot be NULL. Range: [0, 16777215]

Arg (data out): pdxf_fall_fail_count The number of times that the output failed to fall within the allowed time is written through this pointer. Cannot be NULL. Range: [0, 16777215]

Arg (data in): pdxf_init True if the channel is to be initialised, false otherwise.

Return:

• PDX_RC_OK - if successful action

• PDX_RC_SW_ERROR - if channel not supported

• PDX_RC_BAD_ARGS - if configuration error

5.10.3.3.3. pdx_digital_output()

Definition: PDX_RC_T pdx_digital_output(PDX_LCHAN_T pdxf_lchan, U8 pdxf_state, BOOL pdxf_init)

Supported targets: M560-000 and M560-000

Required license: None (Main library).

Description: Function to initialise or drive a digital output channel.

Note

Consider hardware effects such as inversion, low-side/high-side driven, filtering, etc..

If the output pin can be configured for either a low-side or high-side output, the polarity of the output is generally controlled by calling pdx_digital_output() using the channel with a name of the form PIO_DOT_XXX_SELECT_HIGH_SIDE . See the technical reference for the targets for specific information. Can raise the following errors: PDX_CHANNEL_INVALID + pdxf_lchan , or PDX_DO_CHANNEL_UNSUPPORTED + pdxf_lchan

Arg (data in): pdxf_lchan The digital channel to use as a digital output. Use the macros included by the pio.h file, of the form PIO_DOT_[NAME].

Arg (data in): pdxf_state The state to which the digital output should be driven. A state of 0 means the output is inactive, where 1 means active (non-inverted). For low-side outputs, active means pulled to ground; high-side, pulled to supply voltage. The inactive state is high impedence. Consider hardware effects such as inversion, low-side/high-side driven, etc.. Range: 0 or 1

Arg (data in): pdxf_init True if the channel is to be initialised, false otherwise.

Return:

• PDX_RC_OK - successful action

• PDX_RC_SW_ERROR - channel not supported

• PDX_RC_HW_ERROR - if error initialising channel

• PDX_RC_BAD_ARGS - configuration error

• PDX_RC_SDM_ALLOC_ERROR - error allocating ram in SDM

5.10.3.3.4. pdx_frequency_input()

Definition: PDX_RC_T pdx_frequency_input(PDX_LCHAN_T pdxf_lchan, U16 pdxf_config, U8 pdxf_count, F32 *pdxf_freq, U16 pdxf_last_edges, U16 *pdxf_this_edges, U32 pdxf_last_time, U32 *pdxf_this_time, U32 pdxf_timeout, BOOL *pdxf_timed_out, BOOL pdxf_init)

Supported targets: All targets

Required license: None (Main library).

Description: Function to initialise or read a frequency input channel.

This function returns the latest measured frequency of a pulse train input. The function relies on a hardware peripheral to measure the input and present the information on request.

The frequency input is read falling edge to falling edge (unless the pdxf_config parameter specifies otherwise).

Note

Consider hardware effects such as inversion, filtering, etc.. Can raise the following errors: PDX_FREQ_IN_CHANNEL_UNSUPPORTED + pdxf_lchan , or PDX_CHANNEL_INVALID + pdxf_lchan

Arg (data in): pdxf_lchan The digital channel to use as a frequency input. Use the macros included by the pio.h file, of the form PIO_FIN_[NAME].

Arg (data in): pdxf_config A configuration parameter used to initialise certain channels on some ECUs, use PIO_CONFIG_FIN.

Arg (data in): pdxf_count A configuration parameter used to initialise certain channels on some ECUs, use PIO_COUNT_FIN.

Arg (data out): pdxf_freq The measured frequency is written through this pointer. If the input signal has timed out, the last measured input frequency (or zero if none has been measured) is written. The range of the frequency is limited in various ways.

• The range of the frequency that can be measured is limited by the filter circuitry of the input pin.

• The lowest measurable frequency is limited by the filter circuitry and the size of the corresponding processor timer for a channel. Any input frequency below the documented limit, is reported as timed-out.

• The highest measurable frequency is limited by the filter circuitry and the resolution of the corresponding processor timer for a channel. In general, the block reports the frequency of the filtered signal and the input filtering forms an upper limit. However, as the frequency increases, the resolution of measurement decreases. Details of the input pin's filtering and processor timing can be found in an ECU's technical specification. Cannot be NULL. Range: [0.5, ...] Hz

Arg (data in): pdxf_last_edges A count of edges seen by the frequency input function last time this function was called (or zero if this is the first time the function has been called). The counter wraps modulo 65536 and is used to determine whether the signal has timed out or not. Range: [0, 65535] edges

Arg (data out): pdxf_this_edges The count of edges seen by the frequency input function this time is written through this pointer. It is the value to be passed as pdxf_last_edges next time the function is called. Cannot be NULL. Range: [0, 65535] edges

Arg (data in): pdxf_last_time The time of the last call to this frequency input function (or zero if it is the first call). It is used to determine whether the signal has timed out or not. Range: [0, 4294967295] microseconds

Arg (data out): pdxf_this_time The time of this call is written through this pointer. It is the value to be passed as pdxf_last_time next time the function is called. Cannot be NULL. Range: [0, 4294967295] microseconds

Arg (data in): pdxf_timeout The duration of the input signal timeout period. Range: [100, 2000000] microseconds

Arg (data out): pdxf_timed_out Set if the input signal has timed out at the point of calling. If between calls, the input signal timed out and then re-established itself, the time out event is not registered. Cannot be NULL. Range: 0 or 1

Arg (data in): pdxf_init True if the channel is to be initialised, false otherwise.

Return:

• PDX_RC_OK - successful action

• PDX_RC_SW_ERROR - channel not supported

• PDX_RC_HW_ERROR - if error initialising channel

• PDX_RC_BAD_ARGS - configuration error

• PDX_RC_SDM_ALLOC_ERROR - error allocating ram in SDM

5.10.3.3.5. pdx_hbridge_output()

Definition: PDX_RC_T pdx_hbridge_output(PDX_LCHAN_HBRIDGE_T pdxf_lchan_hbridge, PIO_HBRIDGE_MODE_T pdxf_mode, F32 pdxf_freq, F32 pdxf_duty, PIO_HBRIDGE_MODE_T *pdxf_last_mode_ptr, BOOL pdxf_init)

Supported targets: All targets

Required license: None (Main library).

Description: Function to initialise or drive an H-Bridge output channel.

Note

On the M250, for the case when the mode is transitioning, a 100% duty cycle can not be achieved until one task cycle has passed. This can result in the driven duty cycle being different from the requested duty cycle. See the H-Bridge section of the user guide for further detail.

On the M250, there is a dead-time insertion on mode changes. Can raise the following errors: PDX_CHANNEL_INVALID , or PDX_HBRIDGE_INVALID_MODE , or PDX_HBRIDGE_CHANNEL_MISMATCH , or PDX_HBRIDGE_CHANNEL_GROUP_UNSUPPORTED + pdxf_lchan_hbridge

Arg (data in): pdxf_lchan_hbridge The group of channels used to control the H-Bridge. Use the macros included by the pio.h file, of the form PIO_HBOT_[NAME]

Arg (data in): pdxf_mode The H-bridge mode to use. Any of:

• PIO_HBRIDGE_MODE_NO_DRIVE - No Drive

• PIO_HBRIDGE_MODE_BRAKE - Brake

• PIO_HBRIDGE_MODE_FORWARD - Forward drive

• PIO_HBRIDGE_MODE_REVERSE - Reverse drive

Arg (data in): pdxf_duty The desired duty cycle of the PWM output. If the software cannot match the desired duty cycle, the frequency will be adjusted to as close a match as is possible. Some channels cannot achieve very low or very high duty cycles accurately (although 0% and 100% is correctly handled when the H-Bridge is not switching sides - see Note below) and will introduce jitter into the signal. It is up to the caller to ensure this condition does not arise. Range: [0, 1] unitless

Arg (data in,out): pdxf_last_mode_ptr The value of pdxf_mode for this call is written through this pointer. It is the value to be passed as pdxf_mode next time the function is called.

Cannot be NULL.

Arg (data in): pdxf_init True if the channel is to be initialised, false otherwise.

Return:

• PDX_RC_OK - successful action

• PDX_RC_SW_ERROR - channel group not supported or channels not on same device

• PDX_RC_BAD_ARGS - configuration error

• PDX_RC_FREQ_TOO_HIGH - frequency is higher than supported frequency

• PDX_RC_FREQ_TOO_LOW - frequency is lower than supported frequency

• PDX_RC_DUTY_OUT_OF_RANGE - duty cycle is outside [0, 1] range

5.10.3.3.6. pdx_phinj_output()

Definition: PDX_RC_T pdx_phinj_output(PDX_LCHAN_PHINJ_T pdxf_lchan_phinj, F32 pdxf_inj_freq, F32 pdxf_peak_duty, F32 pdxf_pkhold_duty, F32 pdxf_clock_freq, F32 pdxf_offset, BOOL pdxf_init)

Supported targets: None at the moment

Required license: None (Main library).

Description: Function to initialise or drive a peak and hold injector output channel.

Can raise the following errors: PDX_CHANNEL_INVALID + pdxf_master_lchan

Arg (data in): pdxf_lchan_phinj The logical channel associated with the peak and hold injector output. Use the macros included by the pio.h file, of the form PIO_PHINJOT_[NAME]. Note that this selects channels for the peak, peak-hold and injector clock outputs.

Arg (data in): pdxf_inj_freq The desired frequency of the peak and hold injector output. If the software cannot match the desired frequency, the frequency will be adjusted to as close a match as is possible. Range: [0.1, 1000] Hz

Arg (data in): pdxf_peak_duty The desired peak duty cycle of the peak and hold injector output. If the software cannot match the desired duty cycle, the frequency will be adjusted to as close a match as is possible. Some channels cannot achieve very low or very high duty cycles accurately

(although 0% and 100% is correctly handled) and will introduce jitter into the signal. It is up to the caller to ensure this condition does not arise. Range: [0, 1] unitless

Arg (data in): pdxf_pkhold_duty The desired peak-hold duty cycle of the peak and hold injector output. This must not be less than the peak duty cycle: if it is it will be set to match the peak duty cycle. If the software cannot match the desired duty cycle, the frequency will be adjusted to as close a match as is possible. Some channels cannot achieve very low or very high duty cycles accurately (although 0% and 100% is correctly handled) and will introduce jitter into the signal. It is up to the caller to ensure this condition does not arise.

Arg (data in): pdxf_clock_freq The desired frequency of the peak and hold injector clock. If the software cannot match the desired frequency, the frequency will be adjusted to as close a match as is possible. Range: [1, 10000] Hz

Arg (data in): pdxf_offset The desired phase offset of the injector output, relative to other injector output channels that have been configured with the same frequency. Range: [0, 10000] ms

Arg (data in): pdxf_init True if the channel is to be initialised, false otherwise.

Return:

• PDX_RC_OK - if successful action

• PDX_RC_BAD_ARGS - if configuration error

• PDX_RC_PEAK_HOLD_TOO_LOW - if the peak-hold duty is less than the peak duty

5.10.3.3.7. pdx_pwm_input()

Definition: PDX_RC_T pdx_pwm_input(PDX_LCHAN_T pdxf_lchan, U8 pdxf_invert, F32 *pdxf_freq, F32 *pdxf_dc, U32 *pdxf_first_duration, U32 *pdxf_second_duration, U32 *pdxf_period_count, U32 pdxf_timeout, U32 *pdxf_timeout_count, BOOL *pdxf_timed_out, BOOL *pdxf_pin_state, BOOL pdxf_init)

Supported targets: All targets

Required license: None (Main library).

Description: Function to initialise or read a PWM input channel.

This function measures the time of each high and low (or low and high) pulse to determine the frequency and duty cycle of the input signal.

Very small duty cycles (less than 1% or greater than 99%) will not be measured accurately or at all.

The function accumulates the count of complete periods modulo 16777216. The application calculated difference of counts between iterations of the block could be used to diagnose unexpected changes in the signal.

The function relies on a hardware peripheral to measure the signal and present the information on request.

Note

Consider hardware effects such as inversion, filtering, etc.. Can raise the following errors: PDX_PWM_IN_CHANNEL_UNSUPPORTED + pdxf_lchan, or PDX_CHANNEL_INVALID + pdxf_lchan

Arg (data in): pdxf_lchan The digital channel to use as a PWM input. Use the macros included by the pio.h file, of the form PIO_PWIN_[NAME].

Arg (data in): pdxf_invert Set to 0 to start measuring PWM input signal on a rising edge (first pulse is high), set to 1 to start measuring PWM input signal on a falling edge (first pulse is low). Parameter valid only during initialisation. Range: 0 or 1

Arg (data out): pdxf_dc The duty cycle of the last measured period. If a timeout has occurred, this remains as the duty cycle of the last measured period (or zero if a measurement has not yet been taken). Cannot be NULL. Range: [0, 1]

Arg (data out): pdxf_freq The frequency of the last measured period. If a timeout has occurred, this remains as the frequency of the last measured period (or zero if a measurement has not yet been taken). The range of the frequency is limited in various ways.

• The range of the frequency that can be measured is limited by the filter circuitry of the input pin.

frequency increases, the resolution of measurement decreases. Details of the input pin's filtering and processor timing can be found in an ECU's technical specification. Cannot be NULL. Range: 0 Hz and [0.5, ...] Hz (minimum)

Arg (data out): pdxf_first_duration The duration of the first pulse in the last measured period (either high or low). If a timeout has occurred, this remains as the last measured first pulse duration (or zero if a measurement has not yet been taken). Cannot be NULL. Range: [0, 4294967296] microseconds

Arg (data out): pdxf_second_duration The duration of the second pulse in the last measured period (inverse of first pulse). If a timeout has occurred, this remains as the last measured second pulse duration (or zero if a measurement has not yet been taken). Cannot be NULL. Range: [0, 4294967296] microseconds

Arg (data out): pdxf_period_count A count of periods seen by the PWM input function. The counter wraps modulo 16777216. Cannot be NULL. Range: [0, 16777216] periods

Note

pdxf_period_count is not supported on M5xx targets

Arg (data in): pdxf_timeout The duration of the PWM input signal timeout period. Parameter valid only during initialisation. Range: [100, 2000000] microseconds

Arg (data out): pdxf_timeout_count A count of instances where the input signal has timed out. The counter wraps modulo 16777216. Cannot be NULL. Range: [0, 16777216] timeouts

Note

pdxf_timeout_count is not supported on M5xx targets

Arg (data out): pdxf_pin_state Set if the input signal is high, clear if the input signal is low. Cannot be NULL.

Range: 0 or 1

Arg (data in): pdxf_init True if the channel is to be initialised, false otherwise.

Return:

• PDX_RC_OK - successful action

• PDX_RC_SW_ERROR - channel not supported

• PDX_RC_BAD_ARGS - configuration error

• PDX_RC_SDM_ALLOC_ERROR - error allocating ram in SDM

• PDX_RC_INACTIVE - channel inactive

5.10.3.3.8. pdx_pwm_output()

Definition: PDX_RC_T pdx_pwm_output(PDX_LCHAN_T pdxf_lchan, F32 pdxf_freq, F32 pdxf_duty, F32 pdxf_offset, BOOL pdxf_init)

Supported targets: All targets

Required license: None (Main library).

Description: Function to initialise or drive a PWM output channel.

Note

Consider hardware effects such as inversion, low-side/high-side driven, filtering, etc.

On the M250 target, when driving the H-bridge arms independently, the driven signal may have dead-time inserted when changing from low-side to high-side or high-side to low-side for one task period to avoid shoot-through and damage to the ECU. This means that the actual duty cycle may be less than the requested duty cycle for one task cycle, especially at high base frequencies.

If the output pin can be configured for either a low-side or high-side output, the polarity of the output is generally controlled by calling pdx_digital_output() using the channel with a name of the form PIO_DOT_XXX_SELECT_HIGH_SIDE . See the technical reference for the targets for specific information. Can raise the following errors: PDX_PWM_OUT_CHANNEL_UNSUPPORTED + pdxf_lchan , or PDX_CHANNEL_INVALID + pdxf_lchan

Arg (data in): pdxf_lchan The digital channel to use as a PWM output. Use the macros included by the pio.h file, of the form PIO_POT_[NAME].

Arg (data in): pdxf_freq The desired frequency of the output. If the software cannot match the desired frequency, the frequency will be adjusted to as close a match as is possible. If the frequency is outside of the allowed range, then it will be clipped to the allowed range and and either PDX_RC_FREQ_TOO_LOW or PDX_RC_FREQ_TOO_HIGH returned as appropriate. Range: [0.5, 10000] Hz

Arg (data in): pdxf_duty The desired duty cycle of the PWM output. This is the fraction of the period (1 / pdxf_freq) which the output will be active. For low-side outputs this is the period that the output is pulled to ground and for high-side outputs this is the time the output will be pulled to supply voltage. When the output is inactive, the output will be in a high-impedence state. If the software cannot match the desired duty cycle, the frequency will be adjusted to as close a match as is possible. Some channels cannot achieve very low or very high duty cycles accurately (although 0% and 100% is correctly handled) and will introduce jitter into the signal. It is up to the caller to ensure this condition does not arise. Range: [0, 1] unitless

Arg (data in): pdxf_offset The desired phase offset of the PWM output, relative to other PWM output channels that have been configured with the same frequency. This Range: [0, 2000] ms

Arg (data in): pdxf_init True if the channel is to be initialised, false otherwise.

Return:

• PDX_RC_OK - successful action

• PDX_RC_SW_ERROR - channel not supported

• PDX_RC_HW_ERROR - if error initialising channel

• PDX_RC_BAD_ARGS - configuration error

• PDX_RC_SDM_ALLOC_ERROR - error allocating ram in SDM

• PDX_RC_FREQ_TOO_LOW - frequency to slow for target, frequency will be clipped to minimum allowed.

• PDX_RC_FREQ_TOO_HIGH - frequency to quick for target, frequency will be clipped to maximum allowed.

5.10.3.3.9. pdx_quad_freq_input()

Definition: PDX_RC_T pdx_quad_freq_input(PDX_LCHAN_T pdxf_pri_lchan, PDX_LCHAN_T pdxf_sec_lchan, U8 pdxf_count, U32 pdxf_last_edges, S32 *pdxf_delta_edges, U32 *pdxf_this_edges, F32 *pdxf_pchan_freq, F32 *pdxf_schan_freq, U32 pdxf_pchan_last_edges, U32 pdxf_schan_last_edges, U32 *pdxf_pchan_edges,

U32 *pdxf_schan_edges, U32 pdxf_pchan_last_time, U32 pdxf_schan_last_time, U32 *pdxf_pchan_time, U32 *pdxf_schan_time, F32 pdxf_timeout, BOOL *pdxf_pchan_timed_out, BOOL *pdxf_schan_timed_out, BOOL pdxf_init)

Supported targets:

Required license: None (Main library).

Description: Function to initialise or read a quadrature and frequency input channel.

This function returns the latest measured edges seen as a quadrature input and the frequency of each input. The function relies on a hardware peripheral to decode the input and present the information on request.

Note

Consider hardware effects such as inversion, filtering, etc.. Can raise the following errors: PDX_TPU_QFI_CHANNEL_DEVICE_ERROR + pdxf_pri_lchan , or PDX_QDEC_FREQ_IN_CHANNEL_UNSUPPORTED + pdxf_pri_lchan , or PDX_CHANNEL_INVALID + pdxf_pri_lchan

Arg (data in): pdxf_pri_lchan The primary digital channel to use as a quadrature and frequency input. Use the macros included by the pio.h file, of the form PIO_QDIN_[NAME].

Arg (data in): pdxf_sec_lchan The secondary digital channel to use as a quadrature and frequency input. Use the macros included by the pio.h file, of the form PIO_QDIN_[NAME]. Cannot be the same as parameter pdxf_pri_lchan.

Arg (data in): pdxf_count The number of cycles the secondary frequency measurement is averaged over. If set to 1, the measurement is made from the latest cycle. The primary frequency measurement is taken from a single cycle. Range: [1, 255] cycles

Arg (data in): pdxf_last_edges This parameter should be populated with zero on the first call to this function, and subsequently with the value written last time to pdxf_this_edges Range: [-8388608, 8388607] edges (for M250, M460 and M461 targets)

Arg (data out): pdxf_delta_edges The signed difference in edges seen since the last call is written through this pointer. The sign determines the direction of travel of the quadrature input signal. Cannot be NULL. Range: [-8388608, 8388607] edges (for M250, M460 and M461 targets)

Arg (data out): pdxf_this_edges This parameter is populated with a function-internal value which needs to be passed the next time the function is called in the pdxf_last_edges parameter. Cannot be NULL. Range: [N/A]

Arg (data out): pdxf_pchan_freq The measured frequency of the primary input channel is written through this pointer. If the input signal has timed out, the last measured input frequency (or zero if none has been measured) is written. The range of the frequency is limited in various ways.

• The range of the frequency that can be measured is limited by the filter circuitry of the input pin.

Arg (data out): pdxf_schan_freq The measured frequency of the secondary input channel is written through this pointer. If the input signal has timed out, the last measured input frequency (or zero if none has been measured) is written. Cannot be NULL. Range: [0.5, ...] Hz (for M250, M460 and M461 targets)

Arg (data in): pdxf_pchan_last_edges A count of edges seen by the quadrature and frequency input function last time this function was called (or zero if this is the first time the function has been called). The counter is used to determine whether the primary signal has timed out or not. Range: [0, 16777215] edges (for M250, M460 and M461 targets)

Arg (data in): pdxf_schan_last_edges A count of edges seen by the quadrature and frequency input function last time this function was called (or zero if this is the first time the function has been called). The counter is used to determine whether the secondary signal has timed out or not. Range: [0, 16777215] edges (for M250, M460 and M461 targets)

Arg (data out): pdxf_pchan_edges The count of edges seen by the frequency input function this time is written through this pointer. It is the value to be passed as pdxf_pchan_last_edges next time the function is called.

Cannot be NULL. Range: [0, 16777215] edges (for M250, M460 and M461 targets)

Arg (data out): pdxf_schan_edges The count of edges seen by the frequency input function this time is written through this pointer. It is the value to be passed as pdxf_schan_last_edges next time the function is called. Cannot be NULL. Range: [0, 16777215] edges (for M250, M460 and M461 targets)

Arg (data in): pdxf_pchan_last_time The time of the last call to this quadrature and frequency input function (or zero if it is the first call). It is used to determine whether the primary signal has timed out or not. Range: [0, 4294967295] microseconds

Arg (data in): pdxf_schan_last_time The time of the last call to this quadrature and frequency input function (or zero if it is the first call). It is used to determine whether the secondary signal has timed out or not. Range: [0, 4294967295] microseconds

Arg (data out): pdxf_pchan_time The time of this call is written through this pointer. It is the value to be passed as pdxf_pchan_last_time next time the function is called. Cannot be NULL. Range: [0, 4294967295] microseconds

Arg (data out): pdxf_schan_time The time of this call is written through this pointer. It is the value to be passed as pdxf_schan_last_time next time the function is called. Cannot be NULL. Range: [0, 4294967295] microseconds

Arg (data in): pdxf_timeout The duration of the input signal timeout period. Range: [100, 2000000] microseconds (for M250, M460 and M461 targets)

Arg (data out): pdxf_pchan_timed_out Set if the primary input signal has timed out at the point of calling. If between calls, the input signal timed out and then re-established itself, the time out event is not registered. Cannot be NULL. Range: 0 or 1

Arg (data out): pdxf_schan_timed_out Set if the secondary input signal has timed out at the point of calling. If between calls, the input signal timed out and then re-established itself, the time out event is not registered. Cannot be NULL. Range: 0 or 1

Arg (data in): pdxf_init True if the channel is to be initialised, false otherwise.

Return:

• PDX_RC_OK - successful action

• PDX_RC_SW_ERROR - channel not supported

• PDX_RC_HW_ERROR - if error initialising channel

• PDX_RC_BAD_ARGS - configuration error

5.10.3.3.10. pdx_quad_input()

Definition: PDX_RC_T pdx_quad_input(PDX_LCHAN_T pdxf_pri_lchan, PDX_LCHAN_T pdxf_sec_lchan, U32 pdxf_last_edges, S32 *pdxf_delta_edges, U32 *pdxf_this_edges, BOOL pdxf_init)

Supported targets:

Required license: None (Main library).

Description: Function to initialise or read a quadrature input channel.

This function returns the latest measured edges seen as a quadrature input. The function relies on a hardware peripheral to decode the input and present the information on request.

Note

Consider hardware effects such as inversion, filtering, etc.. Can raise the following errors: PDX_TPU_QI_CHANNEL_DEVICE_ERROR + pdxf_pri_lchan , or PDX_QDEC_IN_CHANNEL_UNSUPPORTED + pdxf_pri_lchan , or PDX_CHANNEL_INVALID + pdxf_pri_lchan

Arg (data in): pdxf_pri_lchan The primary digital channel to use as a quadrature input. Use the macros included by the pio.h file, of the form PIO_QDIN_[NAME].

Arg (data in): pdxf_sec_lchan The secondary digital channel to use as a quadrature input. Use the macros included by the pio.h file, of the form PIO_QDIN_[NAME].

Arg (data in): pdxf_last_edges A sum of edges seen by the quadrature input function on the primary and secondary input channels last time this function was called (or zero if this is the first time the function has been called). Range: [-8388608, 8388607] edges

Arg (data out): pdxf_this_edges The count of edges seen this call is written through this pointer. It is the value to be passed as pdxf_last_edges next time the function is called.

Cannot be NULL. Range: [-8388608, 8388607] edges

Arg (data in): pdxf_init True if the channel is to be initialised, false otherwise.

Return:

• PDX_RC_OK - if successful action

• PDX_RC_SW_ERROR - if channel not supported

• PDX_RC_HW_ERROR - if error initialising channel

• PDX_RC_BAD_ARGS - if configuration error

5.10.3.3.11. pdx_sent_input()

Definition: PDX_RC_T pdx_sent_input(PDX_LCHAN_T pdxf_lchan, F32 pdxf_tick_length_us, U8 pdxf_num_nibbles, PIO_PDX_SENT_CRC_T pdxf_crc_version, U8 *pdxf_num_decoded_frames, U8 *pdxf_num_desyncs, BOOL *pdxf_valid, U8 *pdxf_status, U32 *pdxf_data, U32 *pdxf_timestamp, BOOL *pdxf_pin_state, BOOL pdxf_init)

Supported targets:

Required license: None (Main library).

Description: Function to initialise and read a SENT input channel, fast channel signals.

The SENT input function decodes a sensor's transmission pulses based on SAE J2716 Jan 2010, making available the sensor's status and data information. SAE J2716 describes SENT as:

The Single Edge Nibble Transmission encoding scheme (SENT) is intended for use in applications where high resolution sensor data needs to be communicated from a sensor to an Engine Control Unit (ECU). It is intended as a replacement for the lower resolution methods of 10 bit A/D converters and PWM and as a simpler low cost alternative to CAN or LIN. The implementation assumes that the sensor is a smart sensor containing a microprocessor or dedicated logic device (ASIC) to create the signal.

SENT is a unidirectional communications scheme from sensor / transmitting device to controller / receiving device which does not include a coordination signal from the controller / receiving device. The sensor signal is transmitted as a series of pulses with data encoded as falling to falling edge periods.

This SENT input function:

• decodes a stream of SENT pulses into status and fast data nibbles;

• retrieves the last received, decoded and verified status and data nibbles;

• allows for a transmitter clock tick variance of +- 25% for the calibration and synchronisation pulse;

• allows for a transmitter clock tick between [3, 90] microseconds;

• allows for an optional pause pulse between transmissions;

• uses the calibration and sychronisation pulse to ratiometrically adjust the status, data and CRC pulses;

• verifies the frame size (checks the expected number of nibbles, or message edges);

• verifies the frame CRC, either the 2008 or 2010 version;

• verifies that successive calibration pulses differ by less than +- 1.5625%.

See the pdx_sent_serial_input() function for reading short serial or extended serial data.

Can raise the following errors: PDX_SENT_IN_CHANNEL_UNSUPPORTED + pdxf_lchan, or PDX_CHANNEL_INVALID + pdxf_lchan

Arg (data in): pdxf_lchan The digital channel to use as a SENT input. Use the macros included by the pio.h file, of the form PIO_SENTIN_[NAME].

Arg (data in): pdxf_tick_length_us The length of the SENT sensor's transmission clock tick. Range: [3, 90] microseconds Resolution: 0.1 microseconds

Arg (data in): pdxf_num_nibbles The number of data nibbles transmitted by the SENT sensor in each frame. Range: [1, 6] nibbles

Arg (data in): pdxf_crc_version Which CRC algorithm the SENT sensor applies to each SENT frame. Either PIO_PDX_SENT_CRC_2008 or PIO_PDX_SENT_CRC_2010.

Arg (data out): pdxf_num_decoded_frames A counter incremented for each frame that is successfully received, decoded and verified. Cannot be NULL. Range: [0, inf] frames, modulo 256

Arg (data out): pdxf_num_desyncs A counter incremented for each loss of synchronisation with the SENT sensor pulse stream. Loss of synchronisation occurs when the pulse decoder has not seen a valid pulse for more than 125% of a calibration pulse duration (where a calibration pulse is 56 SENT ticks, see pdxf_tick_length_us); or a calibration, status, nibble or CRC pulse is too short; or the frame CRC verification fails.

Cannot be NULL. Range: [0, inf] frames, modulo 256

Arg (data out): pdxf_valid True if at least one SENT frame has been successfully received, decoded and verified, false otherwise. If true, then the pdxf_status and pdxf_data parameters provide the status and data received from the last frame, and the pdxf_timestamp parameter provides the time when the frame was received. Cannot be NULL. Range: 0 or 1

Arg (data out): pdxf_status The status nibble of the last SENT frame that was successfully received, decoded and verified. Set to zero when a SENT frame has not been successfully received. Cannot be NULL.

Arg (data out): pdxf_data The data nibbles of the last SENT frame that was successfully received, decoded and verified. Set to zero when a SENT frame has not been successfully received. The data nibbles are packed into the integer right aligned. Cannot be NULL.

Arg (data out): pdxf_timestamp A timestamp is taken when the the last SENT frame was fully received, decoded and verified. The timestamp increments in counts of 256, wrapping approximately every 4 seconds. The timestamp can be used by the application to determine whether the SENT sensor is transmitting data at the expected period. Cannot be NULL. Range: [0, inf] counts, modulo 4294967296

Arg (data out): pdxf_pin_state 1 if the channel pin voltage is above the detection threshold, 0 otherwise. Can be used by the application for electrical diagnostics. Range: 0 or 1

Arg (data in): pdxf_init True if the channel is to be initialised, false otherwise.

Return:

• PDX_RC_OK - successful action

• PDX_RC_SW_ERROR - channel not supported

• PDX_RC_BAD_ARGS - configuration error

• PDX_RC_SDM_ALLOC_ERROR - error allocating ram in SDM

5.10.3.3.12. pdx_sent_serial_input()

Definition: PDX_RC_T pdx_sent_serial_input(PDX_LCHAN_T pdxf_lchan, U8 *pdxf_num_messages, U8 *pdxf_num_failed_crcs, BOOL *pdxf_valid, PDX_SENT_SERIAL_FORMAT_T *pdxf_serial_format, U8 *pdxf_message_id, U32 *pdxf_data, U32 *pdxf_timestamp)

Supported targets:

Required license: None (Main library).

Description: Function to read a SENT input channel, slow channel signals.

This SENT input function:

• decodes the status nibble from 16 or 18 consecutive SENT transmissions into message identification and data values;

• retrieves the last received, decoded and verified serial data;

• verifies the serial message CRC.

The application must initialise a SENT channel by calling pdx_sent_input() before calling pdx_sent_serial_input().

Can raise the following errors: PDX_SENT_IN_CHANNEL_UNSUPPORTED + pdxf_lchan, or PDX_CHANNEL_INVALID + pdxf_lchan

Arg (data in): pdxf_lchan The digital channel to use as a SENT input. Use the macros included by the pio.h file, of the form PIO_SENTIN_[NAME].

Arg (data out): pdxf_num_messages A counter incremented for each serial message that is successfully received, decoded and verified. Cannot be NULL. Range: [0, inf] messages, modulo 256

Arg (data out): pdxf_num_failed_crcs A counter incremented for each serial message that is received but that fails a CRC verification. Cannot be NULL. Range: [0, inf] messages, modulo 256

Arg (data out): pdxf_valid True if at least one serial message has been successfully received, decoded and verified, false otherwise. If true, then the pdxf_serial_format, pdxf_message_id and pdxf_data parameters provide information about the last successfully received, decoded and verified message, and the pdxf_timestamp parameter provides the time when the message was received. Cannot be NULL. Range: 0 or 1

Arg (data out): pdxf_serial_format The detected serial format of the last successfully received, decoded and verified slow serial message. Set to zero when a serial message has not been received. Cannot be NULL.

Arg (data out): pdxf_message_id The value of the message identifier of the last successfully received, decoded and verified slow serial message. Set to zero when a serial message has not yet been received.

Range: [0, 15] for short serial and enhanced serial format 2 Range: [0, 255] for enhanced serial format 1

Arg (data out): pdxf_data The data nibbles of the last successfully received, decoded and verified slow serial message. Set to zero when a serial message has not yet been received. Cannot be NULL. Range: [0, 255] for short serial Range: [0, 8192] for enhanced serial format 1 Range: [0, 65535] for enhanced serial format 2

Arg (data out): pdxf_timestamp A timestamp is taken when the the last successfully received, decoded and verified slow serial message. The timestamp increments in counts of 256, wrapping approximately every 4 seconds. The timestamp can be used by the application to determine whether the SENT sensor is transmitting data at the expected period. Cannot be NULL. Range: [0, inf] counts, modulo 4294967296

Return:

• PDX_RC_OK - successful action

• PDX_RC_SW_ERROR - channel not supported

• PDX_RC_BAD_ARGS - configuration error 5.10.3.3.13. pdx_spwm_output()

Definition: PDX_RC_T pdx_spwm_output(PDX_LCHAN_T pdxf_master_lchan, PDX_LCHAN_T pdxf_slave_lchan, F32 pdxf_master_freq, F32 pdxf_master_duty, F32 pdxf_master_offset, F32 pdxf_slave_freq, F32 pdxf_slave_duty, U32 pdxf_slave_delay, BOOL pdxf_init)

Supported targets:

Required license: None (Main library).

Description: Function to initialise or drive a synchronised PWM output channel.

Note

Consider hardware effects such as inversion, low-side/high-side driven, filtering, etc.. Can raise the following errors: PDX_TPU_SPO_CHANNEL_DEVICE_ERROR + pdxf_master_lchan , or PDX_SYNC_PWM_OUT_CHANNEL_UNSUPPORTED + pdxf_master_lchan , or PDX_CHANNEL_INVALID + pdxf_master_lchan

Arg (data in): pdxf_master_lchan The master digital channel to use as a synchronised PWM output. Use the macros included by the pio.h file, of the form PIO_SPOT_[NAME].

Arg (data in): pdxf_slave_lchan The slave digital channel to use as a PWM output. Use the macros included by the pio.h file, of the form PIO_SPOT_INT_SLAVE_[NAME].

Arg (data in): pdxf_master_freq The desired frequency of the master channel output. If the software cannot match the desired frequency, the frequency will be adjusted to as close a match as is possible. If the frequency is outside of the allowed range, then it will be clipped to the allowed range and and either PDX_RC_FREQ_TOO_LOW or PDX_RC_FREQ_TOO_HIGH returned as appropriate. Range: [1, 10000] Hz (for the M250, M460 targets)

Arg (data in): pdxf_master_duty The desired duty cycle of the master channel PWM output. If the software cannot match the desired duty cycle, the frequency will be adjusted to as close a match as is possible. Some channels cannot achieve very low or very high duty cycles accurately (although 0% and 100% is correctly handled) and will introduce jitter into the signal. It is up to the caller to ensure this condition does not arise. Range: [0, 1] unitless

Arg (data in): pdxf_master_offset The desired phase offset of the master (and hence slave) channel, relative to other channels that have been configured with the same frequency. Range: [0, 2000] ms (for the M250, M460 targets)

Arg (data in): pdxf_slave_freq The desired frequency of the slave channel output. If the software cannot match the desired frequency, the frequency will be adjusted to as close a match as is possible. If the frequency is outside of the allowed range, then it will be clipped to the allowed range and and either PDX_RC_FREQ_TOO_LOW or PDX_RC_FREQ_TOO_HIGH returned as appropriate. Range: [1, 10000] Hz (for the M250, M460 targets)

Arg (data in): pdxf_slave_duty The desired duty cycle of the slave channel PWM output. If the software cannot match the desired duty cycle, the frequency will be adjusted to as close a match as is possible. Some channels cannot achieve very low or very high duty cycles accurately (although 0% and 100% is correctly handled) and will introduce jitter into the signal. It is up to the caller to ensure this condition does not arise. Range: [0, 1] unitless

Arg (data in): pdxf_slave_delay The desired delay of the slave channel. Range: [0, 1000000] microseconds.

Arg (data in): pdxf_init True if the channel is to be initialised, false otherwise.

Return:

• PDX_RC_OK - if successful action

• PDX_RC_SW_ERROR - if channel not supported

• PDX_RC_HW_ERROR - if error initialising channel

• PDX_RC_BAD_ARGS - if configuration error

• PDX_RC_SDM_ALLOC_ERROR - if error allocating ram in SDM

• PDX_RC_FREQ_TOO_LOW - frequency to slow for target

• PDX_RC_FREQ_TOO_HIGH - frequency to quick for target 5.11. Digital data feature (PDD) 5.11.1. Overview

The library supports functions to access virtual data I/O. 5.11.1.1. Digital data input

The library supports reading the value of arbitrary data inputs which are not well grouped into other interfaces (see pdd_data_input()).

An example might be the fault counters for SPI message queues. SPI message queues are not exposed to the application but the application needs to know when SPI messaging fails so the application can take remedial actions if desired.

Injector circuits can provide timing signals to specify boost recharge times. These values can be read though the pdd_data_input function for the application to process in the desired way. 5.11.1.2. Digital data output

The library supports writing a value to arbitrary data outputs which are not well grouped into other interfaces (see pdd_data_output()).

An example may be a user specified payload to write to an ASIC via a SPI message. SPI message queues are not exposed to the application but the application needs to have the ability to tune specified data parameters to send the appropriate real-time settings to an ASIC.

A real-time clock integrated circuit can receive various values that will be interpreted to start the on-chip countdown timer at different rates and times. These values can be written though the pdd_data_output function for the application to have control over values sent to the supported variables in the platform. 5.11.2. Interface index

An index of interface objects for this feature.

Type Identifier Include file openecu.h and pdd.h Enumerations PDD_RC_T

An enumerated type which contains success and failure codes returned by some digital data feature (PDD) functions.

Type Identifier PDD_ERROR_CODE_T

Error values for debugging when an error is found when calling the digital data feature (PDD), the API calls a function with an enumeration from this type. Data types PDD_LCHAN_T

This declares a type with enough value range to represent all logical channels for all targets. Functions PDD_RC_T pdd_data_input

Function to initialise or read a digital data channel. PDD_RC_T pdd_data_output

Function to initialise or write to a specified digital data output channel. 5.11.3. Interface detail 5.11.3.1. Enumerations

5.11.3.1.1. PDD_RC_T

Summary: An enumerated type which contains success and failure codes returned by some digital data feature (PDD) functions.

Enumerations:

PDD_RC_OK Return code if everything progressed as expected.

PDD_RC_SW_ERROR Return code if an internal error occurred which was the result of a software error.

PDD_RC_HW_ERROR Return code if a hardware error occurred which stopped a channel being sampled or actuated.

PDD_RC_BAD_ARGS Return code if at least one of the arguments could not be used. 5.11.3.1.2. PDD_ERROR_CODE_T

Summary: Error values for debugging when an error is found when calling the digital data feature (PDD), the API calls a function with an enumeration from this type.

Enumerations:

PDD_CHANNEL_INVALID Error raised if the digital channel 'n' is not supported.

'n' is (error_code - PDD_CHANNEL_INVALID).

PDD_DIG_DATA_IN_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as a digital data input.

'n' is (error_code - PDD_DIG_DATA_IN_CHANNEL_UNSUPPORTED).

PDD_DIG_DATA_OUT_CHANNEL_UNSUPPORTED Error raised if the channel 'n' cannot be used as a digital data input.

'n' is (error_code - PDD_DIG_DATA_IN_CHANNEL_UNSUPPORTED). 5.11.3.2. Data types

5.11.3.2.1. PDD_LCHAN_T

Definition: typedef U16 PDD_LCHAN_T

Description: This declares a type with enough value range to represent all logical channels for all targets.

See pio.h for a list of relevant channels for a specific target. 5.11.3.3. Functions

5.11.3.3.1. pdd_data_input()

Definition: PDD_RC_T pdd_data_input(PDD_LCHAN_T pddf_lchan, S32 *pddf_data, BOOL pddf_init)

Supported targets: All targets

Required license: None (Main library).

Description: Function to initialise or read a digital data channel.

Can raise the following errors: PDD_DIG_DATA_IN_CHANNEL_UNSUPPORTED + pddf_lchan, or PDD_CHANNEL_INVALID + pddf_lchan

Arg (data in): pddf_lchan The digital channel to use as a digital data input. Use the macros included by the pio.h file, of the from PIO_DIN_DATA_[NAME].

Arg (data out): pddf_data The value of the digital data is written through this pointer. Cannot be NULL. Range: [-2147483648, 2147483647] (the actual range may vary depending on the value read)

Arg (data in): pddf_init TRUE if the channel is to be initialised, FALSE otherwise.

Return:

• PDD_RC_OK - if successful action

• PDD_RC_SW_ERROR - if channel not supported

• PDD_RC_BAD_ARGS - if configuration error

5.11.3.3.2. pdd_data_output()

Definition: PDD_RC_T pdd_data_output(PDD_LCHAN_T pddf_lchan, S32 pddf_data, BOOL pddf_init)

Supported targets: All targets

Required license: None (Main library).

Description: Function to initialise or write to a specified digital data output channel.

Can raise the following errors: PDD_DIG_DATA_OUT_CHANNEL_UNSUPPORTED + pddf_lchan, or PDD_CHANNEL_INVALID + pddf_lchan

Arg (data in): pddf_lchan The digital channel to use as a digital data output. Use the macros included by the pio.h file, of the from PIO_DDOT_DATA_[NAME].

Arg (data in): pddf_data The value of the digital data. Cannot be NULL. Range: [-2147483648, 2147483647] (the actual range may vary depending on the value write)

Arg (data in): pddf_init TRUE if the channel is to be initialised, FALSE otherwise.

Return:

• PDD_RC_OK - if successful action

• PDD_RC_SW_ERROR - if channel not supported

• PDD_RC_BAD_ARGS - if configuration error 5.12. Output driver control feature (PSS) 5.12.1. Overview

The output driver control feature allows access to the overall output driver switch for each ECU (if an ECU supports such a switch). The overall output driver switch can enable or disable a subset of the ECU outputs in one go. The application could use the switch as a safety device if necessary. See the technical specification for the ECU for a description of how the output driver switch works for that ECU (Section A.1, “ECU hardware reference documentation”).

5.12.2. M220 target

On the M220 ECU there is no output control circuit but the ECU does provide over-current trip protection (as well as other forms of circuit protection). 5.12.2.1. Over-current trip latches

The application can call pss_overcur_trip_reset() during application run to reset the over- current trip latches. The API enforces a minimum duration between resets to allow the ECU time to dissipate heat and to reduce component stress. 5.12.3. M250 target

On the M250 ECU, the output control circuit turns on or off the high side switch from which individual actuators can be attached. The choice of actuators which are directly controlled by the circuit is under the control of the system designer.

VPWR

high side switch control from blockset (pss_OutputControl block) LOAD LOAD

switch control from blockset (e.g., from digital output block)

PWRGND

switch control from blockset (e.g., from digital output block)

PWRGND

Internal to ECU External to ECU

5.12.3.1. Initialisation

The application can call pss_set_safety_switch() to set the output control switch state during application initialisation and application run. During power up, boot, library pre-initialisation and application initialisation, the switch is forced off by the library (thus ensuring the outputs do not glitch during the power up and initialisation sequence of the ECU). During library post- initialisation the switch is set as required by the application. If the application has not set the switch state during application initialisation, then the library will force the switch off.

5.12.3.2. Over-current trip latches

On the M460 ECU, the output control circuit turns on or off the high side switch from which individual actuators can be attached. The choice of actuators which are directly controlled by the circuit is under the control of the system designer.

VPWR

high side weak pull-up control from blockset (pss_OvercurTripReset_DiagnEnable block) high side switch control weak from blockset pull (pss_outputControl block) up LOAD LOAD

weak switch control from software pull (e.g., from digital output) down

PWRGND

weak switch control from software pull (e.g., from PWM output) down

PWRGND

Internal to ECU External to ECU

5.12.4.1. Initialisation

The application can call pss_overcur_trip_reset_and_diagn_enable_state() during application run to enable or disable the high side weak pull-up resistor for diagnostic purposes. See Technical Specification — M460 for details.

If the function is never called to change the state of the high side weak pull-up resistor, the resistor is left disabled after library initialisation. 5.12.4.3. Over-current trip latches

The application can call pss_overcur_trip_reset_and_diagn_enable_state() during application run to reset the over-current trip latches. The API enforces a minimum duration between resets to allow the ECU time to dissipate heat and to reduce component stress. 5.12.5. M461 target

On the M461 ECU there is no output control circuit but the ECU does provide over-current trip protection (as well as other forms of circuit protection). 5.12.5.1. Over-current trip latches

On the M670 ECU there is no output control circuit but the ECU does provide over-current trip protection (as well as other forms of circuit protection). See the M670 technical specification for a complete list of protection and electical monitoring signals. 5.12.6.1. Over-current trip latches

An index of interface objects for this feature.

Type Identifier Include file openecu.h and pss.h Functions void pss_overcur_trip_reset

Request that the over-current trip latches are reset. void pss_overcur_trip_reset_and_diagn_enable_state

Request that the over-current trip latches are reset and to set the high-side switch diagnostic enable. void pss_set_safety_switch

Function to set the safety switch state. void pss_set_switch

Function to set the safety switch state (deprecated).

5.12.8. Interface detail 5.12.8.1. Functions

5.12.8.1.1. pss_overcur_trip_reset()

Definition: void pss_overcur_trip_reset(BOOL pssf_request_trip_reset)

Supported targets:

Required license: None (Main library).

Description: Request that the over-current trip latches are reset.

Note

The OpenECU software limits requests for over-current trip reset to be at least 50ms apart. If a second request is issued within 50ms from the first one, it will be latched and delayed until the 50ms time lag has expired.

Arg (data in): pssf_request_trip_reset Need to cause a transition from false to true to generate an over- current trip reset.

5.12.8.1.2. pss_overcur_trip_reset_and_diagn_enable_state()

Definition: void pss_overcur_trip_reset_and_diagn_enable_state(BOOL pssf_enable_diagn, BOOL pssf_request_trip_reset)

Supported targets:

Required license: None (Main library).

Description: Request that the over-current trip latches are reset and to set the high- side switch diagnostic enable.

Note

Arg (data in): pssf_enable_diagn True if the Diagnostic Enable signal is asserted, false otherwise.

Arg (data in): pssf_request_trip_reset Need to cause a transition from false to true to generate an over- current trip reset.

5.12.8.1.3. pss_set_safety_switch()

Definition: void pss_set_safety_switch(BOOL pssf_enable)

Supported targets:

Required license: None (Main library).

Description: Function to set the safety switch state.

If this function is called during application initialisation, the switch state is remembered, and set during library post initialisation. If this function is called during application run, the switch state is actioned immediately. The platform may force the safety switch to stay open in case the battery voltage is detected to be too low.

Arg (data in): pssf_enable True to enable the safety switch and enable the output drivers, false otherwise.

5.12.8.1.4. pss_set_switch()

Definition: void pss_set_switch(BOOL pssf_enable)

Supported targets:

Required license: None (Main library).

Description: Function to set the safety switch state (deprecated).

Identical in functionality to pss_set_safety_switch(). This function became deprecated in version 1.7.3 and will be removed in a future release. The function is currently retained to provide backwards compatibility to previous releases.

Arg (data in): pssf_enable True to enable the safety switch and enable the output drivers, false otherwise. 5.13. Serial peripheral feature (PSP) 5.13.1. Overview

The serial peripheral feature initiates and completes communication between serial devices within the ECU. The feature is largely within the library with only one function exposed to trigger the periodic functionality required. 5.13.2. Input and output processing

The application must call psp_spi_trigger() at the end of each application task. The call ensures that the library performs appropriate input and output processing for the task at the task's activation rate.

5.13.3. Interface index

An index of interface objects for this feature.

Type Identifier Include file openecu.h and psp.h Enumerations PSP_ERROR_CODE_T

Error values for debugging when an error is found when calling the serial peripheral interface feature (PSP), the API calls a function with an enumeration from this type. Functions void psp_spi_trigger

Force all SPI queues accessed by the current task set to be marked as ready for processing. S16 psp_get_fault_count

Gets the fault count for a SPI device. 5.13.4. Interface detail 5.13.4.1. Enumerations 5.13.4.1.1. PSP_ERROR_CODE_T

Summary: Error values for debugging when an error is found when calling the serial peripheral interface feature (PSP), the API calls a function with an enumeration from this type.

Enumerations:

PSP_QUEUE_OUT_OF_RANGE Error raised if the number of transactions configured for SPI transmission is greater than the maximum allowed.

PSP_TJA1145_UNSUPPORTED_BAUD Error raised if CAN-wake with selective CAN frames is configured for a baud with a data rate not supported by the TJA1145.

PSP_TJA1145_SW_ERROR Error raised if a development error in TJA1145 SW is detected. 5.13.4.2. Functions 5.13.4.2.1. psp_spi_trigger()

Definition: void psp_spi_trigger(void)

Supported targets: All targets

Required license: None (Main library).

Description: Force all SPI queues accessed by the current task set to be marked as ready for processing.

Trigger all SPI queues that are read from or written to in the caller's task. This completes the serial communication cycle for passing information to and from serial peripherals.

5.13.4.2.2. psp_get_fault_count()

Definition: S16 psp_get_fault_count(PIO_SPI_DEVICE_T pspf_device)

Supported targets: All targets

Required license: None (Main library).

Description: Gets the fault count for a SPI device.

Reads values of saturating fault counter for a given SPI device.

Arg (data in): pspf_device device for which to get fault count Range: See pio.h for list of fault- able SPI devices.

Return: fault count Number of faults that have been logged since that application began. Or -1 if the parameter is invalid. Range: [-1, 255] integer count or "invalid". 5.14. CJ125 device driver for UEGO measurement feature (PCJ125) 5.14.1. Overview

The CJ125 control feature allows access to the configuration of supported CJ125 devices. See the technical specification for the ECU for a description of how the CJ125 works for that ECU (Section A.1, “ECU hardware reference documentation”). 5.14.2. Initialisation

The application can call pcj125_control() to set the configuration of a specified CJ125 device. 5.14.3. Diagnostics

The library can use the PDX feature to read various diagnostic details about the CJ125 devices. 5.14.4. Interface index

An index of interface objects for this feature.

Type Identifier Include file openecu.h and pcj125.h Enumerations PCJ125_RC_T

An enumerated type which contains success and failure codes returned by some digital input feature (PCJ125) functions. Data types PCJ125_LCHAN_T

This declares a type with enough value range to represent all logical CJ125 channels for all targets. PCJ125_WORKSPACE_T

This structure acts as scratch area for the CJ125 driver to save the configuration. Functions PCJ125_RC_T pcj125_control

Interface to control behaviour of CJ125 device. 5.14.5. Interface detail 5.14.5.1. Enumerations

5.14.5.1.1. PCJ125_RC_T

Summary: An enumerated type which contains success and failure codes returned by some digital input feature (PCJ125) functions.

Enumerations:

PCJ125_RC_OK Return code if everything progressed as expected.

PCJ125_RC_SW_ERROR Return code if an internal error occurred which was the result of a software error.

PCJ125_RC_HW_ERROR Return code if a hardware error occurred which stopped a channel being sampled or actuated.

PCJ125_RC_BAD_ARGS Return code if at least one of the arguments could not be used. 5.14.5.2. Data types

5.14.5.2.1. PCJ125_LCHAN_T

Definition: typedef U8 PCJ125_LCHAN_T

Description: This declares a type with enough value range to represent all logical CJ125 channels for all targets.

See pio.h for a list of relevant channels for a specific target.

5.14.5.2.2. PCJ125_WORKSPACE_T

Definition: typedef struct PCJ125_WORKSPACE_T_ PCJ125_WORKSPACE_T

Description: This structure acts as scratch area for the CJ125 driver to save the configuration.

One structure should be allocated per CJ125 driven and passed to the corresponding pcj125_control call. 5.14.5.3. Functions

5.14.5.3.1. pcj125_control()

Definition: PCJ125_RC_T pcj125_control(PCJ125_LCHAN_T pcj125f_channel, PIO_CJ125_REF_CURRENT_T pcj125f_ref_current, PIO_CJ125_IP_AMP_T pcj125f_ip_amplification, BOOL pcj125f_calibration_mode, PCJ125_WORKSPACE_T *pcj125f_workspace, BOOL pcj125f_init)

Supported targets:

Required license: None (Main library).

Description: Interface to control behaviour of CJ125 device.

This function is called periodically during an application task to set the internal configuration of the specified CJ125 device. The function should be called in a task with the desired rate at which the device should be reconfigured.

Note

This function should only be called once per task for each CJ125 device controlled. If this assumption is violated, then the function call could be out of sync with the device communication which could cause unpredictable behaviour.

Arg (data in): pcj125f_channel The CJ125 channel to control. Use the macros included by the pio.h file, of the form PIO_CJ125_[NAME].

Arg (data in): pcj125f_ref_current Enumeration of the desired reference current used by the device.

Arg (data in): pcj125f_ip_amplification Enumeration of the desired amplification.

Arg (data in): pcj125f_calibration_mode TRUE to configure the device for calibration mode. FALSE otherwise.

Arg (data in,out): pcj125f_workspace Reference to a memory structure used to store information between function Calls. There should be one such structure allocated and passed to this function for each CJ125 in use.

Arg (data in): pcj125f_init True if the channel is to be initialised, false otherwise.

Return:

• PCJ125_RC_OK - successful action

• PCJ125_RC_HW_ERROR - error communicating on channel

• PCJ125_RC_BAD_ARGS - configuration error 5.15. CAN messaging feature (PCX) 5.15.1. Overview

Reception and transmission of CAN messages, as defined by ISO 11989, is supported by the library. The library provides mechanisms to receive and transmit messages, pack and unpack data for messages, as well as handling error cases. 5.15.2. Initialisation

During application initialisation, the application must configure the CAN buses to be used by calling ??? and declare any receive or transmit messages by calling ???. During library post-initialisation, the library configures the ECU hardware to efficiently receive and transmit these messages.

The call to ??? configures the baud rate for the CAN bus. The range of baud rates selectable is controlled by the library, as is the sample point for each CAN bit (set at 75%).

Figure 5.15. CAN bit sample point

Bit time

Sync Prop Phase1 Phase2

Sample point for CAN bit at 75%

The call to ??? returns a handle which must be used when referencing the same message in any other call to this feature. 5.15.3. Receiving messages

The library buffers received CAN messages for the application, discarding messages which are not of interest (i.e., not declared during initialisation). The application can determine whether a message has been received since last time and extract the contents of the message by calling ???.

Each receive message buffer stores one CAN message. If a CAN message with the same identifier is received more than once between calls from the application, then the message buffer is overwritten with the latest received message. This ensures the latest copy of a CAN message is available to the application, but is not suitable for CAN messages which contain state information (e.g., CAN messages containing protocol information, etc.).

Each receive message buffer stores a low accuracy time taken a short period of time after the message is received. That period of time is variable depending on the load of the processor and will therefore suffer jitter, thus the classification of low accuracy. The timer used for the time stamp is a free running timer, that wraps at its maximum to zero.

The return value from calling ??? gives an indication of CAN message status. It provides an indication of whether a message has been received since the last call, whether more than one message with the same CAN identifier has been received, and whether an error occurred on reception. See ???, ??? and ??? for more.

To help unpack data from the contents of a CAN message, the library provides two functions: pcx_unpack_msg() and pcx_vdb_unpack_msg().

Warning

The PCX feature takes precendece over the PJ1939 feature. If you configure the PCX feature to receive a J1939 frame, the PJ1939 feature will not see the frame, and it will not be processed by the platform. This especially causes problems when receiving J1939 DM14 'Boot Load' commands.

5.15.4. Transmitting messages

The library transmits buffered CAN messages for the application. The application tells the library to transmit a new CAN message by calling ???.

Each transmit message buffer stores one CAN message. If the application requests a transmit of a CAN message before the library has transmitted the last CAN message with the same identifier, then the message buffer is overwritten with the latest transmit message. This ensures the latest version of a CAN message is transmitted by the library, but is not suitable for CAN messages which contain state information (e.g., CAN messages containing protocol information, etc.).

The library buffers multiple transmit messages but as the CAN bus is serial in nature, only one message can be transmitted at a time. The library attempts to transmit the messages in the order they are presented when ??? is called, but the library will not always adhere to this ordering.

To lessen the load experienced by the CAN bus and the ECU, after the library has transmitted one message, it will wait for 2 milliseconds before determining the next message to transmit (except for J1939 and CCP messaging which can occur more quickly than this).

To help pack data into the contents of a CAN message, the library provides two functions: pcx_pack_msg() and pcx_vdb_pack_msg().

The library provides a set of counters which can be used to determine whether a message has been transmitted or not. The ??? function provides a count of the requests for transmission from the application, a count of the number of times the message was queued in software rather than being immediately passed to the CAN controller for immediate transmission, and a count of the number of times the message was successfully transmited on the bus. A difference in the count between the application request for transmission and successful transmission indicates a failure to successfully transmit.

Note

If a message is queued waiting for transmission and the application requests the same message is transmitted (possibly with different message data) then the queued message is overwritten with the most recent requested message.

5.15.5. CAN status

The library provides the function ??? to provide the current state of the CAN bus, one of: error-active, error-passive and bus-off. This function replaces the ??? function, which is now deprecated and retained only for backwards compatibility (deprecated functions may be removed in future versions of the developer software). 5.15.6. CAN buses

The number of CAN buses available to each target ECU varies. It may be than one ECU has two buses, but another ECU has only one. The number available to the application is defined by ???. 5.15.7. Build time buffer sizing

To reduce the memory footprint of the library, the feature requires that the application define and size various arrays that belong to the feature. This puts additional emphasis on keeping the application code and interface specification in sync, but is beneficial to the final system (especially for resource constrained ECUs).

Note

This mechanism exposes some of the internal implementation of the library but the application need only understand the internals, only size the necessary arrays. The application must not otherwise access the arrays.

5.15.8. Library tasks

The library implements a couple of tasks to support CAN messaging. See Section 4.6.4, “Application and library tasks” for details. 5.15.9. Interface index

An index of interface objects for this feature.

Type Identifier Include file openecu.h and pcx.h Functions void pcx_pack_msg

Pack a series of data items into an array of CAN message bytes. void pcx_unpack_msg

Unpack a series of data items from an array of CAN message bytes.

Type Identifier void pcx_vdb_pack_msg

Pack a series of data items into an array of CAN message bytes. void pcx_vdb_unpack_msg

Unpack a series of data items from an array of CAN message bytes. 5.15.10. Interface detail 5.15.10.1. Functions 5.15.10.1.1. pcx_pack_msg()

Definition: void pcx_pack_msg(U8 *pcxf_msg_data, const void *const *pcxf_item_ptr, const U8 *pcxf_field_start, const U8 *pcxf_field_width, const U8 *pcxf_is_signed, const U8 *pcxf_type_code, const U8 pcxf_use_bool_type, const U8 pcxf_num_fields)

Supported targets: All targets

Required license: None (Main library).

Description: Pack a series of data items into an array of CAN message bytes.

Pack a series of data items (of various value types) into an array of CAN message data bytes (e.g., convert a floating point data item to a 3 bit integer, and then pack it into an arbitrary bit position in the array). The array can be passed to pcx_transmit() as CAN data to be transmitted.

The packing sequence works as follows:

• for each element in pcxf_item_ptr

1. read the data value from pcxf_item_ptr based on the type from pcxf_type_code and convert to an integer (clip to maximum of a 32-bit integer if converting from a float)

2. clip the integer to the field width as given by pcxf_field_width taking into account the sign given by pcxf_is_signed

3. write bits to pcxf_msg_data based with most significant byte ordering and the bit position given by pcxf_field_start

Can raise the following errors: PCX_ERR_PACK_MSG_INVALID_PARAM, or PCX_ERR_PACK_MSG_FIELD_PARAM.

Note

An alternative of this function with differing functionality is available as pcx_vdb_pack_msg().

Arg (data out): pcxf_msg_data Pointer to an array of data bytes to be set (the array must be 8 bytes in length, if it is too small, this function will write off the end of the array). Unspecified fields are set to zero. Cannot be NULL.

Arg (data in): pcxf_item_ptr Pointer to array of pointers to data to be packed, the type of the final pointed to data is defined by the array pcxf_type_code. Cannot be NULL.

Arg (data in): pcxf_field_start Pointer to array of field start bit numbers. For each item to pack into pcxf_msg_data, the function determines where to place the data using the corresponding element from this array. 0 corresponds to the least significant bit of data byte 0 of the message and 63 to the most significant bit of data byte 7 of the message, assuming these exist. For items whose bit length entry exceeds 7, the bit length must be one of: 0, 8, 16, 24, 32, 40, 48, 56. For fields with lengths ranging from 1 to 15 bits, the start address defines where the message's least significant bit is stored. For fields with lengths more than or equal to 16 bits, the start address defines where the message's most significant bit is stored. Cannot be NULL.

Example: To pack or unpack the bit sequence:

10 9 8 23 22 21 20 19 18 17 16

MS bit LS bit The start position is specified as 16 and the bit length as 11.

CAN data byte: 0 7 6 5 4 3 2 1 0 1 15 14 13 12 11 10 9 8 2 23 22 21 20 19 18 17 16 3 31 30 29 28 27 26 25 24 4 39 38 37 36 35 34 33 32 5 47 46 45 44 43 42 41 40 6 55 54 53 52 51 50 49 48 7 63 62 61 60 59 58 57 56

Note

If the fields overlap (as given by pcxf_field_start and pcxf_field_width) then the functionality is undefined.

If a field extends beyond the length of the message data contents (as given by pcxf_field_start and pcxf_field_width) then the functionality is undefined.

Arg (data in): pcxf_field_width Pointer to array of field bit widths. For each item to pack into pcxf_msg_data, the function determines how many bits to place into the array using the corresponding element from this array. The following values are allowed: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 24 and 32. Items of 8 bits or fewer may not be defined so as to straddle CAN byte boundaries.

Cannot be NULL.

Arg (data in): pcxf_is_signed Pointer to array of sign flags (flag set true if signed, false otherwise). For each item to pack into pcxf_msg_data, the function determines whether to use the MSB of the packed data as a sign bit or not. If the item is negative but specified in this array as unsigned, the item is clipped to zero. Cannot be NULL.

Arg (data in): pcxf_type_code Pointer to array of data type codes. Each element determines the data type of each element in pcxf_item_ptr. The type of each element is one of: PCX_TYPECODE_F32, PCX_TYPECODE_BOOL, PCX_TYPECODE_S8, PCX_TYPECODE_U8 , PCX_TYPECODE_S16 , PCX_TYPECODE_U16, PCX_TYPECODE_S32 , PCX_TYPECODE_U32. The data storage for a boolean type depends on the pcxf_use_bool_type argument. Cannot be NULL.

Arg (data in): pcxf_use_bool_type True if boolean types are stored as 8-bit integers, false clear if boolean types are stored as 32-bit floating point.

Arg (data in): pcxf_num_fields Number of fields in each of pcxf_item_ptr, pcxf_field_start , pcxf_field_width, pcxf_is_signed, and pcxf_type_code. The function does not check that all arrays have the same length. The results of the function are undefined if the length of each differs from this function argument. Range: [1, 255] fields

5.15.10.1.2. pcx_unpack_msg()

Definition: void pcx_unpack_msg(void *const *pcxf_item_ptr, const U8 *pcxf_msg_data, const U8 *pcxf_field_start, const U8 *pcxf_field_width, const U8 *pcxf_is_signed, const U8 *pcxf_type_code, const U8 pcxf_use_bool_type, const U8 pcxf_num_fields)

Supported targets: All targets

Required license: None (Main library).

Description: Unpack a series of data items from an array of CAN message bytes.

Unpack a series of integer data items from an array of CAN message data bytes (e.g., unpack a 3 bit data value from an arbitrary bit position in the array). The array can be filled by calling pcx_receive().

The unpacking sequence works as follows:

• for each element in pcxf_item_ptr

1. read the data from the buffer pcxf_msg_data, based on the item's field start position pcxf_field_start, and bit width pcxf_field_width, most significant byte first

2. if the item is signed as given by pcxf_is_signed, then perform sign extension

3. convert the value to the appropriate type as given by pcxf_type_code

4. write the converted value to the store given by pcxf_item_ptr

Note

An alternative of this function with differing functionality is available as pcx_vdb_unpack_msg(). Can raise the following errors: PCX_ERR_UNPACK_MSG_INVALID_PARAM, or PCX_ERR_UNPACK_MSG_FIELD_PARAM.

Arg (data in): pcxf_msg_data Pointer to an array of data bytes to be read from (the array must be large enough to bound the unpacking, if it is too small, this function will read off the end of the array). Cannot be NULL.

Arg (data in): pcxf_item_ptr Pointer to array of pointers to data to be unpacked, the type of the final pointed to data is defined by the array pcxf_type_code. Cannot be NULL.

Arg (data in): pcxf_field_start Pointer to array of field start bit numbers. For each item to unpack from pcxf_msg_data, the function determines where to retrieve the data using the corresponding element from this array. 0 corresponds to the least significant bit of data byte 0 of the message and 63 to the most significant bit of data byte 7 of the message, assuming these exist. For items whose bit length entry exceeds 7, the bit length must be one of: 0, 8, 16, 24, 32, 40, 48, 56. For fields with lengths ranging from 1 to 15 bits, the start address defines where the message's least significant bit is stored. For fields with lengths more than or equal to 16 bits, the start address defines where the message's most significant bit is stored. Cannot be NULL.

Example: To pack or unpack the bit sequence:

10 9 8 23 22 21 20 19 18 17 16

MS bit LS bit The start position is specified as 16 and the bit length as 11.

Arg (data in): pcxf_field_width Pointer to array of field bit widths. For each item to unpack from pcxf_msg_data, the function determines how many bits to retrieve from the array using the corresponding element from this array. The following values are allowed: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 24 and 32. Items of 8 bits or fewer may not be defined so as to straddle CAN byte boundaries. Cannot be NULL.

Note

If a field extends beyond the length of the message data contents (as given by pcxf_field_start and pcxf_field_width) then the functionality is undefined.

Arg (data in): pcxf_is_signed Pointer to array of sign flags (flag set true if signed, false otherwise). For each item to unpack from pcxf_msg_data, the function determines whether to use the MSB of the packed data as a sign bit or not. If the item is negative but specified in this array as unsigned, the item is clipped to zero. Cannot be NULL.

Arg (data in): pcxf_use_bool_type True if boolean types are stored as 8-bit integers, false if boolean types are stored as 32-bit floating point.

5.15.10.1.3. pcx_vdb_pack_msg()

Definition: void pcx_vdb_pack_msg(const F32 *const *pcxf_item_ptr, U8 *pcxf_msg_data, const U8 *pcxf_field_start, const U8 *pcxf_field_width, const U8 *pcxf_is_signed, const U8 *pcxf_valtype, const U8 *pcxf_order, const F32 *pcxf_eng_min, const F32 *pcxf_eng_max, const F32 *pcxf_scale, const F32 *pcxf_offset, const U8 pcxf_clip_scaled, const U8 pcxf_use_bool_type, const U8 pcxf_num_fields)

Supported targets: All targets

Required license: None (Main library).

Description: Pack a series of data items into an array of CAN message bytes.

Pack a series of floating point data items into an array of CAN message data bytes (e.g., convert a floating point data item to a 32 bit integer, and then pack it into an arbitrary bit position in the array). The array can be passed to pcx_transmit() as CAN data to be transmitted.

The packing sequence works as follows:

• for each element in pcxf_item_ptr

1. clip to engineering min and max given by pcxf_eng_min and pcxf_eng_max, if pcxf_clip_scaled is true

2. convert to value type given by pcxf_valtype (if converting to integer value type, scale based on pcxf_scale and pcxf_offset)

3. clip to bit width of field in CAN message bytes based on pcxf_field_width

4. write bits to pcxf_msg_data based on the byte order given in pcxf_order and the bit position given by pcxf_field_start

Can raise the following errors: PCX_ERR_PACK_VDB_MSG_INVALID_PARAM.

Note

An alternative of this function with differing functionality is available as pcx_pack_msg().

Arg (data in): pcxf_item_ptr Pointer to array of pointers to data to be packed. Each data item is stored as a 32-bit float. Cannot be NULL.

Arg (data out): pcxf_msg_data Pointer to an array of data bytes to be set (the array must be 8 bytes in length, if it is too small, this function will write off the end of the array). All unwritten fields are set to zero. Cannot be NULL.

Arg (data in): pcxf_field_start Pointer to array of field start bit numbers. For each item to pack into pcxf_msg_data, the function determines where to place the data using the corresponding element from this array. 0 corresponds to the least significant bit of data byte 0 of the message and 63 to the most significant bit of data byte 7 of the message, assuming these exist. Cannot be NULL. The ordering of the bytes (see pcxf_order) determines how the start position is specified. If the ordering is specified as LSB then the start position is the least significant message bit of the least significant message byte.

Example: To pack or unpack the CANdb LSB (Intel) bit sequence:

17 16 15 14 13 12

MS bit LS bit The start position is specified as 12 and the bit length as 6.

If the ordering is specified as MSB then the start position is the most significant message bit of the most significant message byte.

Example: To pack or unpack the CANdb MSB (Motorola) bit sequence:

17 16 31 30 29 28

MS bit LS bit The start position is specified as 17 and the bit length as 6.

Note

If the fields overlap (due to overlapping start and width parameters) then the functionality is undefined.

Note

If the fields overlap (as given by pcxf_field_start and pcxf_field_width) then the functionality is undefined.

If a field extends beyond the length of the message data contents (as given by pcxf_field_start and pcxf_field_width) then the functionality is undefined.

Arg (data in): pcxf_is_signed Unused. Set to NULL.

Arg (data in): pcxf_valtype Pointer to array of data type codes. Each element can be one of: PCX_VAL_INT, and PCX_VAL_FLOAT32. Cannot be NULL.

Arg (data in): pcxf_order Pointer to array of data type byte storage order. Each element can be one of: PCX_MSB_ORDER, and PCX_LSB_ORDER. Cannot be NULL.

Arg (data in): pcxf_use_bool_type Unused. Set to false.

Arg (data in): pcxf_eng_min Pointer to array of engineering minimum values. For each item to pack into pcxf_msg_data, the function clips the item to the corresponding minimum element from this array if pcxf_clip_scaled is true. Cannot be NULL.

Arg (data in): pcxf_eng_max Pointer to array of engineering maximum values. For each item to pack into pcxf_msg_data, the function clips the item to the corresponding maximum element from this array if pcxf_clip_scaled is true. Cannot be NULL.

Arg (data in): pcxf_scale Pointer to array of divisors. For each integer item to pack into pcxf_msg_data, the function subtracts an offset specified by pcxf_offset and scales the item by the corresponding divisor in this array. Cannot be NULL.

Note

If the divisor is zero, then the integer item is set to zero.

Arg (data in): pcxf_offset Pointer to array of adders. For each integer item to pack into pcxf_msg_data, the function subtracts the offset specified by this array and scales the item by the corresponding divisor in pcxf_scale. Cannot be NULL.

Arg (data in): pcxf_clip_scaled True if each data item should be clipped to the minimum and maximum specified by pcxf_eng_min and pcxf_eng_max, otherwise false if no clipping is to be performed.

Note

If the representation of the data item value (from pcxf_item_ptr, after clipping (if clipping is applied)) is larger in bit width than the field to pack into, then the packed value is clipped to the bit width of the field to pack into.

Arg (data in): pcxf_num_fields Number of fields in each of pcxf_item_ptr, pcxf_field_start , pcxf_field_width, pcxf_is_signed , pcxf_valtype , pcxf_order , pcxf_eng_min, pcxf_eng_max, pcxf_scale and pcxf_offset. The function does not check that all arrays have the same length. The results of the function are undefined if the length of each differs from this function argument.

5.15.10.1.4. pcx_vdb_unpack_msg()

Definition: void pcx_vdb_unpack_msg(F32 *const *pcxf_item_ptr, U32 *const *pcxf_item_raw_ptr, const U8 *pcxf_msg_data, const U8 *pcxf_field_start, const U8 *pcxf_field_width, const U8 *pcxf_is_signed, const U8 *pcxf_valtype, const U8 *pcxf_order, const F32 *pcxf_eng_min, const F32 *pcxf_eng_max, const F32 *pcxf_scale, const F32 *pcxf_offset, const U8 pcxf_clip_scaled, const U8 pcxf_use_bool_type, const U8 pcxf_num_fields)

Supported targets: All targets

Required license: None (Main library).

Description: Unpack a series of data items from an array of CAN message bytes.

Unpack a series of data items of various types from an array of CAN message data bytes (e.g., unpack a 32 bit data value from an arbitrary bit position in the array). The array can be filled by calling pcx_receive().

The unpacking sequence works as follows:

• for each element in pcxf_item_ptr

1. read the data from the buffer pcxf_msg_data, based on the item's field start position pcxf_field_start, and bit width pcxf_field_width, where the byte order of the data is given by pcxf_order

2. convert to a floating point value, performing sign extension if necessary as specified by pcxf_is_signed

3. scale the value as given by pcxf_scale and pcxf_offset

4. if clipping is enabled pcxf_clip_scaled, then clip the value based on the engineering minimum and maximum (pcxf_eng_min and pcxf_eng_max)

5. write the resulting value to the store given by pcxf_item_ptr

Can raise the following errors:

PCX_ERR_UNPACK_VDB_MSG_INVALID_PARAM.

Note

An alternative of this function with differing functionality is available as pcx_unpack_msg().

Arg (data in): pcxf_item_ptr Pointer to array of pointers to data to be unpacked. Each data item is stored as a 32-bit float. Cannot be NULL.

Arg (data in): pcxf_item_raw_ptr Pointer to array of pointers to data to be unpacked. Each data item is stored as a 32-bit integer, taken from the CAN message without clipping and scaling. If the pointer is NULL, raw data items are not written.

Arg (data out): pcxf_msg_data Pointer to an array of data bytes to be read (the array must be large enough to bound the unpacking, if it is too small, this function will read off the end of the array). Cannot be NULL.

Arg (data in): pcxf_field_start Pointer to array of field start bit numbers. For each item to unpack from pcxf_item_ptr, the function determines where to read the data using the corresponding element from this array. 0 corresponds to the least significant bit of data byte 0 of the message and 63 to the most significant bit of data byte 7 of the message, assuming these exist. Cannot be NULL. The ordering of the bytes (see pcxf_order) determines how the start position is specified. If the ordering is specified as LSB then the start position is the least significant message bit of the least significant message byte.

Example: To pack or unpack the CANdb LSB (Intel) bit sequence:

17 16 15 14 13 12

MS bit LS bit The start position is specified as 12 and the bit length as 6.

If the ordering is specified as MSB then the start position is the most significant message bit of the least significant message byte.

Example: To pack or unpack the CANdb MSB (Motorola) bit sequence:

17 16 31 30 29 28

MS bit LS bit The start position is specified as 17 and the bit length as 6.

Arg (data in): pcxf_field_width Pointer to array of field bit widths. For each item to unpack from pcxf_msg_data, the function determines how many bits to read into the array using the corresponding element from this array. Cannot be NULL. Element range: [1, 32] bits

Note

If a field extends beyond the length of the message data contents (as given by pcxf_field_start and pcxf_field_width) then the functionality is undefined.

Arg (data in): pcxf_is_signed Pointer to array of sign flags (flag set true if signed, false otherwise). For each item to unpack into pcxf_msg_data, the function determines whether to use the MSB of the packed data as a sign bit or not. Cannot be NULL.

Arg (data in): pcxf_valtype Pointer to array of data type codes. Each element can be one of: PCX_VAL_INT, and PCX_VAL_FLOAT32. Cannot be NULL.

Arg (data in): pcxf_order Pointer to array of data type byte storage order. Each element can be one of: PCX_MSB_ORDER, and PCX_LSB_ORDER. Cannot be NULL.

Arg (data in): pcxf_use_bool_type Unused. Set to false.

Arg (data in): pcxf_eng_min Pointer to array of engineering minimum values. For each item to unpack from pcxf_msg_data, the function clips the item to the corresponding minimum element from this array if pcxf_clip_scaled is true. Cannot be NULL.

Arg (data in): pcxf_eng_max Pointer to array of engineering maximum values. For each item to unpack from pcxf_msg_data, the function clips the item to the corresponding maximum element from this array if pcxf_clip_scaled is true. Cannot be NULL.

Arg (data in): pcxf_scale Pointer to array of multipliers. For each integer item to unpack from pcxf_msg_data, the function scales the item by the corresponding multiplier in this array and adds an offset specified by pcxf_offset. Cannot be NULL.

Arg (data in): pcxf_offset Pointer to array of adders. For each integer item to unpack from pcxf_msg_data, the function scales the item by the corresponding multiplier in pcxf_scale and adds the offset specified by this array. Cannot be NULL.

Arg (data in): pcxf_clip_scaled True if each data item should be clipped to the minimum and maximum specified by pcxf_eng_min and pcxf_eng_max, otherwise false if no clipping is to be performed.

Arg (data in): pcxf_num_fields Number of fields in each of pcxf_item_ptr, pcxf_field_start , pcxf_field_width, pcxf_is_signed , pcxf_valtype , pcxf_order , pcxf_eng_min, pcxf_eng_max, pcxf_scale and pcxf_offset (and for pcxf_item_raw_ptr if it is not NULL). The function does not check that all arrays have the same length. The results of the function are undefined if the length of each differs from this function argument. 5.16. CAN Calibration Protocol (CCP) messaging feature (PCP) 5.16.1. Overview

The CAN Calibration Protocol (CCP — as defined by ASAM MCD-MC1) is a simple CAN based messaging system for communicating between a PC based tool and the ECU. The PC based tool could be used for reprogramming, or calibration, or servicing (see Appendix C, Supporting tools for an introduction to a few of these tools) through the use of an ASAP2 file (see Target ASAP2 file for more).

Figure 5.16. ASAM MCD-MC1 interaction

ASAP2 Tool file

ASAP2 defined by ASAM MCD-2MC gives description of ECU memories and ECU variables. CAN device

ASAM MCD-1MC (ASAP1) defines CCP communication between PC tool and ECU

CAN peripheral

CCP driver

ECU

The messaging used to implement CCP is defined by ASAM MCD-1MC (ASAP1), where ASAM MCD-1a covers the ECU and ASAM MCD-1b covers the PC tool. The implementation of CCP messages by OpenECU is detailed in Appendix F, CCP compliance. 5.16.1.1. Messaging

The CCP implementation uses a small number of CAN identifiers for transporting messages to and from the ECU.

Figure 5.17. CCP messaging

PC based tool

CRO message DTO message DAQ messages from tool from ECU from ECU to ECU to tool to tool

ECU

CRO — Command Return Object The CAN message used by the reprogramming or calibration tool when sending a request to the ECU.

DTO — Data Transmission Object The CAN message used by the ECU when replying to a CRO.

DAQ — Data Acquisition Queue The CAN message used to transmit DAQ information from the ECU to the calibration tool.

Unlike CRO and DTO messages, which are response based, the DAQ messages are sent on a periodic basis (rather than on request from the calibration tool). DAQ messages are sent by the library in bursts.

The OpenECU implementation of CCP uses the same CAN identifier for DAQ messages as DTO messages.

The CAN identifiers to be used are defined by the application during build time.

Note

Certain targets, which are not on general release, support CCP parameters which can themselves be calibrated. Using this feature requires caution as the act of reprogramming them with altered values changes subsequent communications using the very interface just used for reprogramming.

On those targets pcpc_tx_id and pcpc_rx_id set the DTO and CRO CAN IDs used by the ECU respectively; pcpc_bus is the zero-based CAN bus index to use for CCP; pcpc_station_addr is the station address for the ECU; and pcpc_baud is the baud rate selected (in kbit/s) used in reprogramming mode, though this may be set differently by user initialisation of the CAN bus in application mode.

5.16.1.2. CCP during reprogramming mode

During reprogramming mode, CCP is used for reprogramming of the ECU. See Section 3.3.11, “Program the ECU” for details. 5.16.1.3. CCP during application mode

During application mode, CCP is used for a number of purposes:

To initiate reprogramming While in application mode, the ECU can accept or reject reprogramming requests. In some cases, it is convenient to accept reprogramming requests because it removes the need to put the ECU into reprogramming mode through a power reset. In some other cases, it is essential that an accidental reprogramming request does not cause application mode to stop when it is controlling the system (e.g., controlling a motor or set of injectors). For this reason, the application can tell the library when to accept and reject reprogramming requests through the pcp_inhibit_reprogramming() function.

To write application calibration variables If the ECU is a developer unit, then the library will accept requests to change calibration data while the application is running. Developer units have additional RAM which allows the calibration which is usually stored in ROM to be stored in RAM and modified while the application is running.

To read application variables The library's CCP implementation supports DAQ lists. A DAQ list is a list of addresses to read and transmit on a periodic basis. The PC based tool creates the DAQ lists and requests the ECU to transmit them periodically. The library supports 4 DAQ lists with 16 ODTs each (each ODT can have up to 7 addresses for reading). For further information about DAQ lists and ODTs, see the ASAM MCD-MC1 specification.

Extract manufacturer's information using EXCHANGE_ID command The extended EXCHANGE_ID message can be used to extract manufacturer's information. More information on how EXCHANGE_ID is set up on OpenECU see the Section F.1, “EXCHANGE_ID message handling” section.

Whether CCP is enabled during application mode can be controlled by setting the pcp_ccpenabled variable at build time. 5.16.1.4. CCP seed/key security

To prevent third parties recalibrating or reprogramming modules, manufacturers typically enable CCP seed/key security for production modules. This requires a valid seed/key exchange to take place with the calibration tool, where the module generates a seed (usually at random) and the calibration tool must respond with the correct key value corresponding to that seed, calculated by a secret algorithm known to the module and the calibration tool. Brute-force attacks are deterred by applying a significant delay (usually 10s) after each incorrect key before a further attempt may be made.

The pcp_seed_key_config array (and the corresponding array size pcp_num_seed_key_configs) configures CCP seed/key security. Each element of this array specifies whether security is required for a CCP privilege level, and if so, what functions are used to generate the seed and to validate the key returned by the calibration tool. Note that seed generation functions are optional; if omitted, the platform will simply generate 32-bit random seeds for CCP seed/key exchanges for this privilege level.

To ensure that CCP seed/key security is also used during reprogramming mode, the functions used to generate the seed (if required) and validate the key are copied to non-volatile storage by the application. The reprogramming mode software retrieves the functions from non- volatile storage, and copies them to RAM for execution.

CCP privilege levels are defined as: calibration; data acquisition; and programming. From the calibration tool it is necessary to gain access to calibration before carrying out data acquisition; and likewise it is necessary to gain access to calibration before carrying out programming. Note however that data acquisition and programming privilege levels are independent: it is possible to read variables without being able to reprogram the module, and vice versa.

CCP seed/key security is a standard feature of the protocol; however configuring it on different calibration/programming tools requires some knowledge of that tool's operation. Support will currently only be given for CCP seed/key security on PiSnoop (see Section C.2, “PiSnoop”), Vector CANape (see Section C.5, “Vector CANape”), and ATI Vision (see Section C.3, “ATI Vision”) 5.16.1.4.1. Specifying functions for use with CCP seed/key security

5.16.1.4.1.1. Seed generator function

The seed generator function must be of the form:

void seed_generator(const U8 privilege_level, U8 *const seed)

privilege_level specifies the privilege level for which a seed is being requested. Values are fixed by the CCP standard as:

• 0x01 (1): Calibration

• 0x02 (2): Data acquisition

• 0x40 (64): Programming

seed is a four-byte array. This will initially contain values generated by a 32-bit random number algorithm within the OpenECU platform. The seed generator function may choose to leave these values intact, or may choose to set its own values in the seed array.

5.16.1.4.1.2. Key validator function

The key validator function must be of the form:

BOOL key_validator(const U8 privilege_level, const U8 *const seed, const U8 *const key, const U8 key_size)

privilege_level specifies the privilege level for which a seed is being requested (see Section 5.16.1.4.1, “Specifying functions for use with CCP seed/key security” for details).

seed is a four-byte array containing the last seed value passed to the calibration tool.

key is an array of up to six bytes whose length is specified by key_size. This contains the key passed back by the calibration tool.

The CCP 2.1 specification for the CCP_UNLOCK command has a six-byte field for the key, although in practice most implementations only use four bytes. The contents of the remaining bytes are often undefined, so the key validator must take care to match the expected seed- key algorithm.

The function must return TRUE if the key is valid for the seed, or FALSE if it is not.

5.16.1.4.1.3. Implementing seed/key functions

Because the seed generator and key validator functions will be relocated and run during reprogramming mode, it is ESSENTIAL that these functions do NOT access any global or static storage OR call any functions. If this is not the case, relocating and invoking the function in reprogramming mode will have unexpected consequences, because the function will read/ write/execute memory at addresses which are not valid when in reprogramming mode. These consequences may include stuck outputs resulting in physical damage to hardware or electrical damage to the ECU, and/or complete permanent disablement of the ECU.

Diab implementation considerations If the application is built using the Diab compiler, then the file containing these functions should be specified for compilation as normal. It is frequently the case that seed/key functions are supplied only as object or library code for security reasons, in which case the file must have been compiled with PowerPC variable bit length (VLE) instructions.

GCC implementation considerations If the application is built using GCC, then the file containing these functions must also contain section attribute specifiers to place the code in sections that correspond to the names of the security functions. The attribute specifiers must be applied to the function prototypes in the form:

void seed_generator(const U8 privilege_level, U8 *const seed) __attribute__ ((section (".seed_generator")));

It is frequently the case that seed/key functions are supplied only as object or library code for security reasons, in which case the file must have been compiled without PowerPC variable bit length (VLE) instructions.

Note however that linkage of these functions requires special handling. Since compilers/ linkers do not provide information about the sizes of functions, and since relocation of a function requires the function size to be known, extra symbols must be generated to report the end of each of these functions. These must be linked according to specific rules. To implement this, a suitable linker definition file excerpt is generated automatically, and this must be inserted at the correct point in the main linker definition file. See --diab- ldfile=FILE and --gcc-ldfile=FILE for further details about generating the linker excerpt. See --output-linker-file=FILE and --ld-excerpt-file=FILE for details about inserting the excerpt into the main linker definition file. 5.16.1.5. Library tasks

The library implements a single task to support CCP messaging. See Section 4.6.4, “Application and library tasks” for details. Excessive delay of this task by application tasks

can cause CCP messages to miss their timing deadlines and this may be reported by PC based support tools. 5.16.2. Interface index

An index of interface objects for this feature.

Type Identifier Include file openecu.h and pcp.h Macros PCP_PL_CAL

Mask value for CCP calibration privilege level. PCP_PL_DAQ

Mask value for CCP data acquisition privilege level. PCP_PL_PGM

Mask value for CCP reprogramming privilege level. PCP_PL_ALL

Mask value for all CCP privilege levels. Data types PCP_SEED_KEY_CONFIG_T

Structure configuring security for one or more CCP privilege levels. PCP_SEED_GENERATOR_T

Typedef for the callback function used to generate a seed for a CCP seed-key exchange. PCP_KEY_VALIDATOR_T

Typedef for the callback function used to validate a key for a CCP seed-key exchange. Variables const pcp_seed_key_config PCP_SEED_KEY_CONFIG_T CCP seed-key configuration for application. const U8 pcp_num_seed_key_configs

Number of array elements in pcp_seed_key_config. const U8 pcp_ccpenabled

True if CCP messaging is enabled during application run, false otherwise. Functions U32 pcp_get_rx_count

Return the number of CCP CRO messages received since the last reset.

Type Identifier void pcp_inhibit_reprogramming

Enable or disable CCP reprogramming requests while running application mode. void pcp_client_task

The CAN calibration protocol (CCP) messaging task. 5.16.3. Interface detail 5.16.3.1. Macros 5.16.3.1.1. PCP_PL_CAL

Definition: #define PCP_PL_CAL 0x01

Description:

Mask value for CCP calibration privilege level. 5.16.3.1.2. PCP_PL_DAQ

Definition: #define PCP_PL_DAQ 0x02

Description:

Mask value for CCP data acquisition privilege level. 5.16.3.1.3. PCP_PL_PGM

Definition: #define PCP_PL_PGM 0x40

Description:

Mask value for CCP reprogramming privilege level. 5.16.3.1.4. PCP_PL_ALL

Definition: #define PCP_PL_ALL (PCP_PL_CAL | PCP_PL_DAQ | PCP_PL_PGM)

Description:

Mask value for all CCP privilege levels. 5.16.3.2. Data types 5.16.3.2.1. PCP_SEED_KEY_CONFIG_T

Summary: Structure configuring security for one or more CCP privilege levels.

Members:

U8 PCP_SEED_KEY_CONFIG_T::privilege_levels Bitwise mask specifying which privilege levels this applies to.

This mask may be set using the literals PCP_PL_CAL (calibration), PCP_PL_DAQ (data acquisition), PCP_PL_PGM (reprogramming) or PCP_PL_ALL (all three).

BOOL PCP_SEED_KEY_CONFIG_T::security_required If security_required is set FALSE, no seed-key exchange is required for the specified privilege level(s).

They may be invoked by the calibration tool at any time. The callback structure elements are ignored.

If security_required is set TRUE, the callbacks provided are used to unlock the specified privilege levels. Activities for these privilege levels may not be invoked by the CCP master until they have been unlocked.

If security_required is set TRUE but either callback is NULL, it will not be possible to unlock these privilege levels and the calibration tool will be permanently prohibited from invoking activities for these privilege levels.

PCP_SEED_GENERATOR_T PCP_SEED_KEY_CONFIG_T::seed_request_callback Pointer to callback function which is called to request a seed value for the specified privilege level(s) when the calibration tool attempts to unlock the privilege level(s).

Set this value to NULL if security is not required.

U8* PCP_SEED_KEY_CONFIG_T::seed_request_callback_end_addr Address of location immediately after seed_request_callback function.

This allows the platform to calculate the size of the function.

PCP_KEY_VALIDATOR_T PCP_SEED_KEY_CONFIG_T::key_validation_callback Pointer to callback function which is called to validate a key value for the returned by the calibration tool, where the key is generated from the seed returned by the previously-called seed_request_callback function.

Set this value to NULL if security is not required.

U8* PCP_SEED_KEY_CONFIG_T::key_validation_callback_end_addr Address of location immediately after key_validation_callback function.

This allows the platform to calculate the size of the function. 5.16.3.2.2. PCP_SEED_GENERATOR_T

Definition: typedef void(* PCP_SEED_GENERATOR_T)(const U8 pcpf_privilege_level, U8 *const pcpf_seed)

Description: Typedef for the callback function used to generate a seed for a CCP seed-key exchange.

The function is run by a processing task which is scheduled every 5ms. The function must therefore take no more than 5ms to execute,

and preferably should be significantly faster. As usual for embedded programming, excessive stack requirements and the use of dynamic memory allocation should be avoided. There is currently no requirement for this function to be re-entrant.

The platform software may copy the callback function to NV storage so that application security algorithms may also be used by the bootloader when reprogramming. In order for this to be possible, the callback function must be relocatable. The function should therefore make no calls to other functions, or refer to application variables or calibratables, otherwise existing callback functions may be incompatible with new releases of OpenECU. Note that direct access to registers and hardcoded memory locations is still permitted.

Arg (data in): pcpf_privilege_level The privilege level for this request will be one of the bit-mask values PCP_PL_CAL, PCP_PL_DAQ or PCP_PL_PGM , representing a request for calibration, data acquisition or programming privilege levels respectively.

Return: The function must return a 32-bit seed value. Typically this will be generated through a random or pseudo-random process. This seed must be stored for later use by the corresponding key validation function when the calibration tool returns a key. 5.16.3.2.3. PCP_KEY_VALIDATOR_T

Definition: typedef BOOL(* PCP_KEY_VALIDATOR_T)(const U8 pcpf_privilege_level, const U8 *const pcpf_seed, const U8 *const pcpf_key, const U8 pcpf_key_size)

Description: Typedef for the callback function used to validate a key for a CCP seed- key exchange.

The function must generate the expected key from the last seed value returned by the corresponding seed request callback function and compare this to the key calculated by the calibration tool.

The function is run by a processing task which is scheduled every 5ms. The function must therefore take no more than 5ms to execute, and preferably should be significantly faster. As usual for embedded programming, excessive stack requirements and the use of dynamic memory allocation should be avoided. There is currently no requirement for this function to be re-entrant.

Arg (data in): pcpf_privilege_level The privilege level for this request will be one of the bit-mask values PCP_PL_CAL, PCP_PL_DAQ or PCP_PL_PGM , representing a

request for calibration, data acquisition or programming privilege levels respectively.

Arg (data in): pcpf_key The key is an array of bytes returned by the calibration tool, generated from the seed returned by the corresponding seed request callback function.

Arg (data in): pcpf_key_size Size of key array in bytes. The array may be between zero and 6 bytes long. Typically the key will be a 32-bit value (4 bytes), i.e. the same size as the seed, but there is no requirement for this to be the case. The size must be checked by the function to ensure that out- of-bounds array accesses do not take place.

Return: The function must return TRUE if the key is correct, or FALSE if not. 5.16.3.3. Variables

5.16.3.3.1. pcp_seed_key_config

Definition: const PCP_SEED_KEY_CONFIG_T pcp_seed_key_config[]

Description: CCP seed-key configuration for application.

Each array element specifies the CCP seed-key security to be applied to one or more CCP privilege levels.

The code tolerates multiple array entries existing which specify the same CCP privilege level. If this occurs, the code carries out processing only for the first array element with a matching CCP privilege level. Any or all subsequent array entries are ignored.

5.16.3.3.2. pcp_num_seed_key_configs

Definition: const U8 pcp_num_seed_key_configs

Description: Number of array elements in pcp_seed_key_config.

5.16.3.3.3. pcp_ccpenabled

Definition: const U8 pcp_ccpenabled

Description: True if CCP messaging is enabled during application run, false otherwise. 5.16.3.4. Functions

5.16.3.4.1. pcp_get_rx_count()

Definition: U32 pcp_get_rx_count(void)

Supported targets: All targets

Required license: None (Main library).

Description: Return the number of CCP CRO messages received since the last reset.

Return: A count of CCP CRO messages received since the last reset. The counter wraps modulo 4294967295. Range: [0, 4294967295] messages

5.16.3.4.2. pcp_inhibit_reprogramming()

Definition: void pcp_inhibit_reprogramming(U8 pcpf_inhibit)

Supported targets: All targets

Required license: None (Main library).

Description: Enable or disable CCP reprogramming requests while running application mode.

The ECU uses the CAN calibration protocol for reprogramming. Reprogramming requests are always honoured while the ECU is in reprogramming mode. In application mode, reprogramming requests can be enabled or disabled. For instance, the application might enable reprogramming requests only while it is in an idle and safe state.

If uncalled by the application, reprogramming is allowed by default.

Arg (data in): pcpf_inhibit True if reprogramming should be inhibited, false otherwise.

5.16.3.4.3. pcp_client_task()

Definition: void pcp_client_task(void)

Supported targets: All targets

Required license: None (Main library).

Description: The CAN calibration protocol (CCP) messaging task.

This is the entry point for the CCP messaging task. The task handles enabling or disabling messaging based on pcp_ccpenabled. If messaging is enabled, then the task manages CCP CAN messages (reception and transmission) and scheduling of DAQ message processing (transmission).

Note

The CCP messaging task must be scheduled every 5 milliseconds. 5.17. J1939 (SAE) messaging feature (PJ1939) 5.17.1. Overview

J1939 is a SAE communications protocol, based on CAN, largely defined by the following documents:

SAE J1939/21 Defines the data link layer, including how J1939 messages map to the CAN specification, definition of Parameter Groups (PG), and definition of the transport protocol (for sending J1939 messages with more than 8 data bytes).

The library directly supports the transport protocol and has facilities to handle PG messages: on request (from another node on the network); periodically (ECU periodically transmits a PG); and on event (ECU transmits PG when a condition becomes true).

SAE J1939/71 Defines the vehicle application layer, essentially a list of predetermined messages and their contents.

SAE J1939/73 Defines the application layer diagnostics, which includes (amongst other things) support for Diagnostic Trouble Codes (DTC).

The core library supports the following basic diagnostic messages (to deal with Diagnostic Trouble Codes):

DM1 All active Diagnostic Trouble Codes

DM2 All previously active Diagnostic Trouble Codes

SAE J1939/81 Defines the network management protocol, a mechanism for allocating addresses to nodes on the J1939 network dynamically.

For the moment, the library only provides support for fixed address J1939 networks. The library will participate in messaging required to claim an address for the ECU, but the library will not dynamically change address when it loses negotiation, nor will the library track the address of other nodes.

It is assumed throughout this document, that the reader is familiar with the SAE J1939 specifications. 5.17.2. Node addressing

All nodes on a J1939 network have a unique identifier and a preferred network address. This information can be specified by setting the name and node_addr variables.

The name array is populated from the J1939 name fields (see SAE J1939 for further details) as follows:

Element Bit number

0 0 IG2 IG1 IG0 VSI3 VSI2 VSI1 VSI0

1 VS6 VS5 VS4 VS3 VS2 VS1 VS0 1

2 F7 F6 F5 F4 F3 F2 F1 F0

3 FI4 FI3 FI2 FI1 FI0 EI2 EI1 EI0

4 MC10 MC9 MC8 MC7 MC6 MC5 MC4 MC3

5 MC2 MC1 MC0 IN20 IN19 IN18 IN17 IN16

6 IN15 IN14 IN13 IN12 IN11 IN10 IN9 IN8

7 IN7 IN6 IN5 IN4 IN3 IN2 IN1 IN0

Where:

IG Industry Group

VSI Vehicle System Instance

VS Vehicle System

F Function

FI Function Instance

EI ECU Instance

MC Manufacturer code

IN Identity Number

For now, the library does not support dynamic addressing. Applications must use a fixed network address. If that address is claimed, then the ECU will claim the NULL address (254) and only process network messages (see J1939/81).

When the ECU has no network address (has claimed the NULL address), it can only participate in network communications. When the ECU has a network address (has claimed a non-NULL address without conflict), then the ECU can participate in all communications. 5.17.3. Messaging

J1939 supports long messages. Long messages contain more than 8 data bytes (and hence require more than one CAN message to be transmitted) and can be up to 1785 bytes long. Not all J1939 networks will have messages this long, and as RAM memory is precious on most of the target ECUs, the application can specify the largest message to be received through the pj1939_size_j1939_rx_buf variable.

The application can also define the number of receive and transmit long messages through the pj1939_num_rx_tx_bufs variable, allowing some balance in RAM use against application responsiveness.

Similarly, as RAM is precious, the number of receive and transmit messages to be buffered between processing by the J1939 stack is configurable by the application through the pj1939_num_trx and pj1939_num_ttx variables. As the CAN link baud rate will be known, and the time between processing by the application will be known, the worst case number of J1939 CAN messages could be derived by the application at build time, and an automatic number of buffers allocated. 5.17.4. Message bit and byte numbering

The library follows the bit and byte numbering convention laid out by the J1939 specifications.

Data byte Bit number LS MS LS 1 8 7 6 5 4 3 2 1 2 16 15 14 13 12 11 10 9 ...... 1785 14280 14279 14278 14277 14276 14275 14274 14273 MS MS LS

where byte 1 corresponds to the first received data byte in the first CAN message for the PG message. This numbering scheme, matches the J1939 specification but differs from the existing CAN feature (e.g., like ??? which refers to the first byte as byte 0). It is felt that although this may cause some confusion, it is better to present the bit ordering according to J1939.

A field which starts at bit 5 and has 10 bits of width is identified as follows:

Data byte Bit number 1 8 7 6 5 - - - - 2 - - 14 13 12 11 10 9

J1939 message fields are generally packed LSB first, so the bits would be interpreted as:

MS LS Data byte 2 Data byte 1 ------14 13 12 11 10 9 8 7 6 5 s s s s s s x x x x x x x x x x

where x is the corresponding bit taken from the J1939 message data bytes, and s is the sign extension of the data. In this case, bit 14 may be considered the sign bit, if the data in the J1939 message data is signed.

However, if the J1939 message field was packed MSB first, the bits would be interpreted as:

MS LS Data byte 1 Data byte 2 ------6 5 14 13 12 11 10 9 8 7 s s s s s s x x x x x x x x x x

where x is the corresponding bit taken from the J1939 message data bytes, and s is the sign extension of the data. In this case, bit 6 may be considered the sign bit, if the data in the J1939 message data is signed.

5.17.5. PGNs

The library makes use of PGN values. A PGN is a 17 bit wide integer, having either PDU1 or PDU2 format (see SAE J1939/21 for more):

Bits 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0 PDU1 format

DP0 PF7 PF6 PF5 PF4 PF3 PF2 PF1 PF0 DA7 DA6 DA5 DA4 DA3 DA2 DA1 DA0 PDU2 format

DP0 PF7 PF6 PF5 PF4 PF3 PF2 PF1 PF0 PS7 PS6 PS5 PS4 PS3 PS2 PS1 PS0

Where:

DP Data page

PF PDU format — the PGN has PDU1 format when the value of PDU format is less than 240, and has PDU2 format when greater than or equal to 240.

PS PDU specific

DA Destination address

A common action when using the J1939 protocol is responding to requests, and the library provides support for trapping specific PGs and filtering out others by populating the _pgn_table and pj1939_num_pgns variables. The library will automatically generate a NACK if a PG request message is received but does not match one of the PGNs in _pgn_table (unless of course, the request was sent to the global address, in which case, the library does not generate a NACK).

To determine if a PGN has been requested, the library provides the pj1939_was_pgn_requested() function. 5.17.6. Receive messages

The library buffers received J1939 messages for the application, discarding messages which are not of interest. The application can determine whether a message has been received since last time and extract the contents of the message by calling pj1939_pg_receive().

Each receive message buffer stores one J1939 message. If a J1939 message with the same PGN is received more than once between calls from the application, then the message buffer is overwritten with the latest received message. This ensures the latest copy of a J1939 message is available to the application, but is not suitable for J1939 messages which contain state information (e.g., J1939 messages containing protocol information, etc.).

The pj1939_pg_receive() function gives an indication of J1939 message status by writing to various status flags. The function provides an indication of whether a message has been received since the last call, whether more than one message with the same CAN identifier has been received, and whether an error occurred on reception. The function also provides a timestamp of the last valid message received.

To help unpack data from the contents of a J1939 message, the function takes data detailing the fields of the message contents, extracts the fields and writes them to application variables.

Warning

5.17.7. Transmit messages

The library transmits buffered J1939 messages for the application. The application tells the library to transmit a new J1939 message by calling pj1939_pg_transmit().

Each transmit message buffer stores one J1939 message. If the application requests a transmit of a J1939 message before the library has transmitted the last CAN message with the same identifier, then the message buffer is overwritten with the latest transmit message. This ensures the latest version of a J1939 message is transmitted by the library, but is not suitable for J1939 messages which contain state information (e.g., J1939 messages containing protocol information, etc.).

The library buffers multiple J1939 transmit messages but as the CAN bus is serial in nature, only one message can be transmitted at a time. The library attempts to transmit the messages in the order they are presented when pj1939_pg_transmit() is called, but the library will not always adhere to this ordering.

Unlike the CAN feature (PCX) which attempts to lessen the load experienced by the CAN bus and the ECU, after the library has transmitted one J1939 message, it will attempt to transmit the next as soon as possible to make it more likely that all protocol message deadlines will be met. However, this may not be possible depending on the current CAN bus loading and the ECU processor loading.

To help pack data into the contents of a J1939 message, the function takes data detailing the fields of the message contents and values of those fields, and writes them to J1939 message (setting all unspecified bits to one). 5.17.8. Core Diagnostic messages

The core library provides functions to help deal with basic diagnostic messaging, specifically DM1 and DM2 messages through the functions pj1939_dm1_transmit(), pj1939_dm1_receive(), pj1939_dm1_decode_dtc(), pj1939_dm2_transmit(), pj1939_dm2_receive() and pj1939_dm2_decode_dtc()

The J1939/73 specification, section 5.7.1, details the transmission rate of the DM1 message (both on request, and periodic transmission). The examples included in that section, show the frequency of transmission and the need to limit bandwidth. Two parameters are made available to filter out high-frequency activation or deactivation of DTCs, to reduce the frequency of DM1 message transmission.

The library schedules DM1 messages to be sent every second if the conditions are right, but will evaluate when to check DTCs for state changes when pj1939_dm1_receive() is called, thus giving the application some control over how frequently the DTC list is inspected to determine newly active DTCs. 5.17.9. Build time buffer sizing

Note

5.17.10. Library tasks

The library implements a single task to support J1939 messaging. See Section 4.6.4, “Application and library tasks” for details. 5.17.11. Interface index

An index of interface objects for this feature.

Type Identifier Include file openecu.h and pj1939.h Enumerations PJ1939_ERROR_T

Error values for debugging when an error is found in a call to the PCX API, the feature calls a function with an enumeration from this type. Data types J1939_TX_MESSAGE_T

This is the definition of a J1939 transmit message. J1939_RX_MESSAGE_T

This is the definition of a J1939 receive message. CAN_PACKET_T

This is the structure of a single CAN packet. PJ1939_RX_BUF_T

This is the structure for buffering received J1939 messages. PGN_T

This is a typedef for the PGN (parameter group number). Variables const U8 pj1939_enabled

Set true if J1939 functionality is enabled, set false otherwise. const U8 pj1939c_node_addr_0

This sets the desired J1939 node address and can be altered by calibration. U8 node_addr

Type Identifier This is a list of preferred J1939 network addresses (all unique and not the null address (254) or the broadcast address (255)). const U8 pj1939_num_node_addr

This is the number of declared J1939 network addresses in the node_addr[] array. const U8 name

This is the J1939 network name of this unit. const PGN_T _pgn_table

This is an array of receive PGNs the library must filter. const U32 pj1939_num_pgns

This is the number of receive PGNs in _pgn_table[]. const PGN_T pj1939_pgn_requested_table

This is the list of expected PGN requests to filter. const U32 pj1939_num_requested_pgns

This is the number of expected PGN requests in the pj1939_pgn_requested_table[] array. U8 pj1939_pgn_requested_src_addr

This is the buffer of source addresses for each PGN request message. U8 pj1939_pgn_requested_dest_addr

This is the buffer of destination addresses for each PGN request message. U32 pj1939_pgn_requested_timestamp

This is the buffer of timestamps for each PGN request message. U8 pj1939_pgn_requested_bitmap

This is the buffer of priority for each PGN request message. U16 pj1939_rx_buf_data_size

This is the size of the data portion to each J1939 receive buffer. U8 *const pj1939_rx_buf_data

This is an array of pointers to each data buffer for each J1939 receive message. PJ1939_RX_BUF_T *const pj1939_rx_buf

This is an array of pointers to each J1939 receive message. const PCX_LCHAN_T pj1939_can_link

Type Identifier This is the CAN link used for the J1939 network messaging. const U8 pj1939_num_ttx

This is the number of transport transmit buffers that can run in parallel. const U8 pj1939_num_trx

This is the number of transport receive buffers that can run in parallel. const U16 pj1939_size_j1939_rx_buf

This is the maximum data size of any J1939 message (both reception and transmission). const U8 pj1939_num_rx_tx_bufs

This is the number of receive and transmit CAN buffers allocated for J1939 message processing. J1939_TX_MESSAGE_T pj1939_ttx_buf

This is an array of J1939 transmit messages. U8 * pj1939_ttx_error_ptr

This is an array of pointers to counters for delayed transmit errors. U8 pj1939_ttx_buf_data

This is the buffer space allocated for all J1939 transmit messages. U8 pj1939_msg_buffer

This is the buffer space allocated for all J1939 receive messages. J1939_TRANSPORT_TX_INFO tx_state

This is the state of the transmission messages that require transport support (i.e., messages that have a data length greater than 8 bytes). J1939_MESSAGE rx_message

This is the state of the receive messages that require transport support (i.e., messages that have a data length greater than 8 bytes) CAN_PACKET_T in_queue

This is the queue of received messages. CAN_PACKET_T out_queue

This is the queue of transmit messages. const BOOL pj1939_use_common_mf_priority

Type Identifier This is a flag to determine whether to use a common priority for all J1939 multi-frame diagnostic message transmissions. const U8 pj1939_common_multiframe_priority

This is the common priority used for all J1939 multiframe diagnostic message transmissions. const U8 pj1939_dm1_source_addr

This is an array of J1939 node addresses corresponding to the list of addresses which are known to transmit DM1 messages. const U8 pj1939_dm1_source_addr_num

This is the number of declared J1939 DM1 transmitter addresses in the pj1939_dm1_source_addr[] array. U8 *const pj1939_dm1_rx_buf_data

This is the list of pointers to message data buffers for each DM1 message to be received. U32 pj1939_dm1_rx_counters

This is an array of counters for each DM1 message to be received. PJ1939_RX_BUF_T *const pj1939_dm1_rx_buf

This is an array of pointers to message buffers for each DM1 message to be received. const U8 pj1939_dm2_source_addr

This is an array of J1939 node addresses corresponding to the list of addresses which are known to transmit DM2 messages. const U8 pj1939_dm2_source_addr_num

This is the number of declared J1939 DM2 transmitter addresses in the pj1939_dm2_source_addr[] array. U8 *const pj1939_dm2_rx_buf_data

This is the list of pointers to message data buffers for each DM2 message to be received. PJ1939_RX_BUF_T *const pj1939_dm2_rx_buf

This is an array of pointers to message buffers for each DM2 message to be received. U32 pj1939_dm2_rx_counters

This is an array of counters for each DM2 message to be received. U8 pj1939_state

This is an array of states for each DTC.

Type Identifier U8 pj1939_sent

This is an array of sent flags for each DTC. U8 pj1939_transient

This is an array of transient fault states for each DTC. U8 pj1939_transient_sent

This is an array of transient sent flags for each DTC. Functions U8 pj1939_dm1_receive

This function indicates if and when a J1939 DM1 message was received. void pj1939_dm1_decode_dtc

This function decodes part of a received J1939 DM1 message. U8 pj1939_dm2_receive

This function indicates if and when a J1939 DM2 message was received. void pj1939_dm2_decode_dtc

This function decodes part of a received J1939 DM2 message. void pj1939_dm1_transmit

This function attempts to transmit a J1939 DM1 message. void pj1939_dm2_transmit

This function attempts to transmit a J1939 DM2 message. void pj1939_inhibit_reprogramming

Enable or disable J1939 reprogramming 'Boot Load' requests while running application mode. void pj1939_was_pgn_requested

Determine whether a PGN has been requested from this node. void pj1939_pg_receive

Determine if a PGN has been received and extract its contents if required. void pj1939_pg_transmit

Construct a J1939 message and attempt to send it (deprecated). void pj1939_pdu1_transmit

Type Identifier Construct a J1939 message and attempt to send it. void pj1939_pdu2_transmit

Construct a J1939 message and attempt to send it. 5.17.12. Interface detail 5.17.12.1. Enumerations

5.17.12.1.1. PJ1939_ERROR_T

Summary: Error values for debugging when an error is found in a call to the PCX API, the feature calls a function with an enumeration from this type.

Enumerations:

PJ1939_WAS_REQ_PGN_INVALID_ARG Error raised if the PGN requested function finds an invalid function argument.

PJ1939_PG_RECEIVE_INVALID_ARG Error raised if the PG receive function finds an invalid function argument.

PJ1939_PG_TRANSMIT_INVALID_ARG Error raised if the PG transmit function finds an invalid function argument.

PJ1939_DM1_DECODE_INVALID_ARG Error raised if the DM1 decode function finds an invalid function argument.

PJ1939_DM2_DECODE_INVALID_ARG Error raised if the DM2 decode function finds an invalid function argument.

PJ1939_DM1_TRANSMIT_INVALID_ARG Error raised if the DM1 transmit function finds an invalid function argument.

PJ1939_DM2_TRANSMIT_INVALID_ARG Error raised if the DM2 transmit function finds an invalid function argument.

PJ1939_DM4_TRANSMIT_INVALID_ARG Error raised if the DM4 transmit function finds an invalid function argument.

PJ1939_DM5_TRANSMIT_INVALID_ARG Error raised if the DM5 transmit function finds an invalid function argument.

PJ1939_DM6_TRANSMIT_INVALID_ARG Error raised if the DM6 transmit function finds an invalid function argument.

PJ1939_DM7_COMMANDED_TEST_INVALID_ARG Error raised if the DM7 commanded test function finds an invalid function argument.

PJ1939_DM8_TRANSMIT_INVALID_ARG Error raised if the DM8 transmit function finds an invalid function argument.

PJ1939_DM10_TRANSMIT_INVALID_ARG Error raised if the DM10 transmit function finds an invalid function argument.

PJ1939_DM12_TRANSMIT_INVALID_ARG Error raised if the DM12 transmit function finds an invalid function argument.

PJ1939_DM14_DECODE_INVALID_ARG Error raised if the DM14 decode function finds an invalid function argument.

PJ1939_DM15_TRANSMIT_INVALID_ARG Error raised if the DM15 transmit function finds an invalid function argument.

PJ1939_DM16_DECODE_INVALID_ARG Error raised if the DM16 decode function finds an invalid function argument.

PJ1939_DM16_TRANSMIT_INVALID_ARG Error raised if the DM16 transmit function finds an invalid function argument.

PJ1939_DM20_TRANSMIT_INVALID_ARG Error raised if the DM20 transmit function finds an invalid function argument.

PJ1939_DM21_TRANSMIT_INVALID_ARG Error raised if the DM21 transmit function finds an invalid function argument.

PJ1939_DM23_TRANSMIT_INVALID_ARG Error raised if the DM23 transmit function finds an invalid function argument.

PJ1939_DM24_TRANSMIT_INVALID_ARG Error raised if the DM24 transmit function finds an invalid function argument.

PJ1939_DM25_TRANSMIT_INVALID_ARG Error raised if the DM25 transmit function finds an invalid function argument.

PJ1939_DM26_TRANSMIT_INVALID_ARG Error raised if the DM26 transmit function finds an invalid function argument.

PJ1939_DM27_TRANSMIT_INVALID_ARG Error raised if the DM27 transmit function finds an invalid function argument.

PJ1939_DM28_TRANSMIT_INVALID_ARG Error raised if the DM28 transmit function finds an invalid function argument.

PJ1939_DM29_TRANSMIT_INVALID_ARG Error raised if the DM29 transmit function finds an invalid function argument.

PJ1939_DM30_TRANSMIT_INVALID_ARG Error raised if the DM30 transmit function finds an invalid function argument.

PJ1939_DM31_TRANSMIT_INVALID_ARG Error raised if the DM31 transmit function finds an invalid function argument.

PJ1939_DM32_TRANSMIT_INVALID_ARG Error raised if the DM32 transmit function finds an invalid function argument.

PJ1939_DM33_TRANSMIT_INVALID_ARG Error raised if the DM33 transmit function finds an invalid function argument.

PJ1939_DM34_TRANSMIT_INVALID_ARG Error raised if the DM34 transmit function finds an invalid function argument.

PJ1939_DM35_TRANSMIT_INVALID_ARG Error raised if the DM35 transmit function finds an invalid function argument.

PJ1939_DM36_TRANSMIT_INVALID_ARG Error raised if the DM36 transmit function finds an invalid function argument.

PJ1939_DM37_TRANSMIT_INVALID_ARG Error raised if the DM37 transmit function finds an invalid function argument.

PJ1939_DM38_TRANSMIT_INVALID_ARG Error raised if the DM38 transmit function finds an invalid function argument.

PJ1939_DM39_TRANSMIT_INVALID_ARG Error raised if the DM39 transmit function finds an invalid function argument.

PJ1939_DM40_TRANSMIT_INVALID_ARG Error raised if the DM40 transmit function finds an invalid function argument.

PJ1939_DM41_TRANSMIT_INVALID_ARG Error raised if the DM41 transmit function finds an invalid function argument.

PJ1939_DM42_TRANSMIT_INVALID_ARG Error raised if the DM42 transmit function finds an invalid function argument.

PJ1939_DM43_TRANSMIT_INVALID_ARG Error raised if the DM43 transmit function finds an invalid function argument.

PJ1939_DM44_TRANSMIT_INVALID_ARG Error raised if the DM44 transmit function finds an invalid function argument.

PJ1939_DM45_TRANSMIT_INVALID_ARG Error raised if the DM45 transmit function finds an invalid function argument.

PJ1939_DM46_TRANSMIT_INVALID_ARG Error raised if the DM46 transmit function finds an invalid function argument.

PJ1939_DM47_TRANSMIT_INVALID_ARG Error raised if the DM47 transmit function finds an invalid function argument.

PJ1939_DM48_TRANSMIT_INVALID_ARG Error raised if the DM48 transmit function finds an invalid function argument.

PJ1939_DM49_TRANSMIT_INVALID_ARG Error raised if the DM49 transmit function finds an invalid function argument.

PJ1939_DM50_TRANSMIT_INVALID_ARG Error raised if the DM50 transmit function finds an invalid function argument.

PJ1939_DM51_TRANSMIT_INVALID_ARG Error raised if the DM51 transmit function finds an invalid function argument.

PJ1939_DM52_TRANSMIT_INVALID_ARG Error raised if the DM52 transmit function finds an invalid function argument.

PJ1939_PGN_TRANSMIT_INVALID_ARG Error raised if the PGN transmit function finds an invalid function argument.

PJ1939_DM1_RECEIVE_INVALID_ARG Error raised if the DM1 receive function finds an invalid function argument.

PJ1939_DM2_RECEIVE_INVALID_ARG Error raised if the DM2 receive function finds an invalid function argument. 5.17.12.2. Data types

5.17.12.2.1. J1939_TX_MESSAGE_T

Summary: This is the definition of a J1939 transmit message.

Members:

PGN_T J1939_TX_MESSAGE_T::PGN This is the message Parameter Group Number.

U8* J1939_TX_MESSAGE_T::data_ptr This is a pointer to the data bytes contained in the J1939 message.

If the data pointer is NULL, the message should be considered invalid.

U16 J1939_TX_MESSAGE_T::byte_count This is the number of data bytes in the J1939 message.

Range: [0, 1785] bytes

U8 J1939_TX_MESSAGE_T::priority This is the J1939 message priority (0 is the highest priority, 7 the lowest).

Priorities requested outside this range will be clipped to 7. Range: [0, 7]

U8 J1939_TX_MESSAGE_T::dest_addr This is the network address of the intended destination node.

This field is ignored for PDU2 format messages with eight or fewer data bytes since they are always broadcast globally. PDU2 format messages with more than eight bytes of data can be broadcast globally or sent to a specific destination. A destination address (global or specific) is required for all PDU1 formats.

S8 J1939_TX_MESSAGE_T::status This is used to define transport layer error and acknowledgment.

Description:

This is the definition of a J1939 transmit message.

Present in the C-API description only for build time size requirements. The typedef is not to be used by application code.

5.17.12.2.2. J1939_RX_MESSAGE_T

Summary: This is the definition of a J1939 receive message.

Members:

PGN_T J1939_RX_MESSAGE_T::PGN This is the message Parameter Group Number.

U8* J1939_RX_MESSAGE_T::data_ptr This is a pointer to the data bytes contained in the J1939 message.

If the data pointer is NULL, the message should be considered invalid.

U16 J1939_RX_MESSAGE_T::byte_count This is the number of data bytes in the J1939 message.

Range: [0, 1785] bytes

U8 J1939_RX_MESSAGE_T::source_addr This is the network address of the node that transmitted the message.

U8 J1939_RX_MESSAGE_T::dest_addr This is the network address of the node to which the message was sent.

Always set to the global address (255) for PDU2 format messages.

Description:

This is the definition of a J1939 receive message.

Present in the C-API description only for build time size requirements. The typedef is not to be used by application code.

5.17.12.2.3. CAN_PACKET_T

Summary: This is the structure of a single CAN packet.

Members:

U32 CAN_PACKET_T::identifier This is the 29-bit CAN identifier contained in an extended format packet.

The identifier is right justified within the 32-bit field so that the upper three bits are always zero.

U8 CAN_PACKET_T::data[CAN_MAX_BYTE_COUNT] This is the data bytes contained in the CAN packet.

The value of unused data bytes is undefined.

U8 CAN_PACKET_T::byte_count This is the number of valid data bytes in the CAN packet.

Range: [0, 8] bytes

Description:

This is the structure of a single CAN packet.

Present in the C-API description only for build time size requirements. The typedef is not to be used by application code.

5.17.12.2.4. PJ1939_RX_BUF_T

Summary: This is the structure for buffering received J1939 messages.

Members:

U32 PJ1939_RX_BUF_T::timestamp This timestamp records when the J1939 message was received.

Range: [0, 4294967295] microseconds

U8 PJ1939_RX_BUF_T::source_addr This is the source address of a received J1939 message.

Range: [0, 255]

U8 PJ1939_RX_BUF_T::dest_addr This is the destination address of the received J1939 message.

Range: [0, 255]

U16 PJ1939_RX_BUF_T::byte_count This is the number of data bytes in the received J1939 message.

Range: [0, 1785] bytes

U8 PJ1939_RX_BUF_T::flags This is a bitfield of status information.

If bit 0 is set, the message has been received at least once since the bit was last cleared. If bit 1 is set, the message has been received more than once since the bit was last cleared. If bit 2 is set, an error was trapped on the last receive.

Description:

This is the structure for buffering received J1939 messages.

Present in the C-API description only for build time size requirements. The typedef is not to be used by application code.

5.17.12.2.5. PGN_T

Definition: typedef U32 PGN_T

Description: This is a typedef for the PGN (parameter group number).

Present in the C-API description only for build time size requirements. The typedef is not to be used by application code. 5.17.12.3. Variables

5.17.12.3.1. pj1939_enabled

Definition: const U8 pj1939_enabled

Description: Set true if J1939 functionality is enabled, set false otherwise.

5.17.12.3.2. pj1939c_node_addr_0

Definition: volatile const U8 pj1939c_node_addr_0

Description: This sets the desired J1939 node address and can be altered by calibration.

However, it is used only during ECU initialisation, so any calibration change must be programmed into flash to take effect on the next power- up.

Note

The _0 suffix is to allow for the future possibility of multiple nodes being implemented in one ECU. Range: [0, 253]

5.17.12.3.3. node_addr

Definition: U8 node_addr[]

Description: This is a list of preferred J1939 network addresses (all unique and not the null address (254) or the broadcast address (255)).

The first element contains the preferred node address. The last element must contain the global address (255).

Range: [0, 253] or 255

5.17.12.3.4. pj1939_num_node_addr

Definition: const U8 pj1939_num_node_addr

Description: This is the number of declared J1939 network addresses in the node_addr[] array.

Range: [2, 255]

5.17.12.3.5. name

Definition: const U8 name[]

Description: This is the J1939 network name of this unit.

See J1939 specification for details.

5.17.12.3.6. _pgn_table

Definition: const PGN_T _pgn_table[]

Description: This is an array of receive PGNs the library must filter.

Must be declared in ascending order and each element must have a unique value. If the application must respond to DM1, DM2, DM3 or DM11 messages, then the PGNs for these must be added to this array.

5.17.12.3.7. pj1939_num_pgns

Definition: const U32 pj1939_num_pgns

Description: This is the number of receive PGNs in _pgn_table[].

Values outside of the defined range will result in undefined behaviour.

Range: [1, 2147483647]

5.17.12.3.8. pj1939_pgn_requested_table

Definition: const PGN_T pj1939_pgn_requested_table[]

Description: This is the list of expected PGN requests to filter.

Must be declared in ascending order and be unique.

5.17.12.3.9. pj1939_num_requested_pgns

Definition: const U32 pj1939_num_requested_pgns

Description: This is the number of expected PGN requests in the pj1939_pgn_requested_table[] array.

5.17.12.3.10. pj1939_pgn_requested_src_addr

Definition: U8 pj1939_pgn_requested_src_addr[]

Description: This is the buffer of source addresses for each PGN request message.

Indexes are the same as the pj1939_pgn_requested_table[] array.

Present in the C-API description only for build time size requirements. The array must be declared and sized by the application. The size of the array must equal pj1939_num_requested_pgns (or one if there are no requested PGNs). The array is not to be accessed by application code.

5.17.12.3.11. pj1939_pgn_requested_dest_addr

Definition: U8 pj1939_pgn_requested_dest_addr[]

Description: This is the buffer of destination addresses for each PGN request message.

Indexes are the same as the pj1939_pgn_requested_table[] array.

Present in the C-API description only for build time size requirements. The array must be declared and sized by the application. The size of the

array must equal pj1939_num_requested_pgns (or one if there are no requested PGNs). The array is not to be accessed by application code. 5.17.12.3.12. pj1939_pgn_requested_timestamp

Definition: U32 pj1939_pgn_requested_timestamp[]

Description: This is the buffer of timestamps for each PGN request message.

Indexes are the same as the pj1939_pgn_requested_table[] array.

Definition: U8 pj1939_pgn_requested_bitmap[]

Description: This is the buffer of priority for each PGN request message.

Indexes are the same as pj1939_pgn_requested_table[], but applied per bit, rather than per byte.

Present in the C-API description only for build time size requirements. The array must be declared and sized by the application. The size of the array must equal { (pj1939_num_requested_pgns + 7) / 8 } (or one if there are no requested PGNs). The array is not to be accessed by application code. 5.17.12.3.14. pj1939_rx_buf_data_size

Definition: U16 pj1939_rx_buf_data_size[]

Description: This is the size of the data portion to each J1939 receive buffer.

The array must be declared and sized by the application. The size of the array must equal pj1939_num_pgns (or one if there are no received PGNs).

Each element corresponds to the same element in the array _pgn_table[], and is the number of data bytes for the corresponding PGN message.

Range: [0, 1785] bytes 5.17.12.3.15. pj1939_rx_buf_data

Definition: U8* const pj1939_rx_buf_data[]

Description: This is an array of pointers to each data buffer for each J1939 receive message.

The array must be declared and sized by the application. The size of the array must equal pj1939_num_pgns (or one if there are no received PGNs).

Each element corresponds to the same element in the array _pgn_table[], and is a pointer to an area of memory large enough to store the data bytes for the corresponding PGN message. 5.17.12.3.16. pj1939_rx_buf

Definition: PJ1939_RX_BUF_T* const pj1939_rx_buf[]

Description: This is an array of pointers to each J1939 receive message.

The array must be declared and sized by the application. The size of the array must equal pj1939_num_pgns (or one if there are no received PGNs).

Each element corresponds to the same element in the array _pgn_table[], and is a pointer to a variable of type PJ1939_RX_BUF_T. 5.17.12.3.17. pj1939_can_link

Definition: const PCX_LCHAN_T pj1939_can_link

Description: This is the CAN link used for the J1939 network messaging.

Use the macros included by the pio.h file, of the form PIO_CAN_[NAME]. 5.17.12.3.18. pj1939_num_ttx

Definition: const U8 pj1939_num_ttx

Description: This is the number of transport transmit buffers that can run in parallel.

The more transmit buffers there are, the larger the number of destination nodes can be communicated with at the same time. At the same time, the more transmit buffers there are, the larger the amount of RAM required to accommodate the parallel information. Values outside of the defined range will result in undefined behaviour.

Range: [1, 127] buffers. 5.17.12.3.19. pj1939_num_trx

Definition: const U8 pj1939_num_trx

Description: This is the number of transport receive buffers that can run in parallel.

The more receive buffers there are, the larger the number of destination nodes can be communicated with at the same time. At the same time, the more receive buffers there are, the larger the amount of RAM required to accommodate the parallel information.

Range: [1, 255] buffers.

5.17.12.3.20. pj1939_size_j1939_rx_buf

Definition: const U16 pj1939_size_j1939_rx_buf

Description: This is the maximum data size of any J1939 message (both reception and transmission).

Any J1939 message with data larger than this variable is rejected by the library.

Range: [8, 1785] bytes.

5.17.12.3.21. pj1939_num_rx_tx_bufs

Definition: const U8 pj1939_num_rx_tx_bufs

Description: This is the number of receive and transmit CAN buffers allocated for J1939 message processing.

Range: [1, 255]

5.17.12.3.22. pj1939_ttx_buf

Definition: J1939_TX_MESSAGE_T pj1939_ttx_buf[]

Description: This is an array of J1939 transmit messages.

Present in the C-API description only for build time size requirements. The array must be declared and sized by the application. The size of the array must equal pj1939_num_ttx (or one if there are no requested PGNs). The array is not to be accessed by application code.

5.17.12.3.23. pj1939_ttx_error_ptr

Definition: U8* pj1939_ttx_error_ptr[]

Description: This is an array of pointers to counters for delayed transmit errors.

The index is the same as for the pj1939_ttx_buf[] array.

Present in the C-API description only for build time size requirements. The array must be declared and sized by the application. The size of the array must equal pj1939_num_ttx. The array is not to be accessed by application code.

5.17.12.3.24. pj1939_ttx_buf_data

Definition: U8 pj1939_ttx_buf_data[]

Description: This is the buffer space allocated for all J1939 transmit messages.

Present in the C-API description only for build time size requirements. The array must be declared and sized by the application. The size of the array must equal {pj1939_num_ttx * pj1939_size_j1939_rx_buf}. The array is not to be accessed by application code.

5.17.12.3.25. pj1939_msg_buffer

Definition: U8 pj1939_msg_buffer[]

Description: This is the buffer space allocated for all J1939 receive messages.

Present in the C-API description only for build time size requirements. The array must be declared and sized by the application. The size of the array must equal {pj1939_num_trx * pj1939_size_j1939_rx_buf}. The array is not to be accessed by application code.

5.17.12.3.26. tx_state

Definition: J1939_TRANSPORT_TX_INFO tx_state[]

Description: This is the state of the transmission messages that require transport support (i.e., messages that have a data length greater than 8 bytes).

5.17.12.3.27. rx_message

Definition: J1939_MESSAGE rx_message[]

Description: This is the state of the receive messages that require transport support (i.e., messages that have a data length greater than 8 bytes)

Present in the C-API description only for build time size requirements. The array must be declared and sized by the application. The size of the array must equal pj1939_num_trx. The array is not to be accessed by application code.

5.17.12.3.28. in_queue

Definition: CAN_PACKET_T in_queue[]

Description: This is the queue of received messages.

Present in the C-API description only for build time size requirements. The array must be declared and sized by the application. The size of

the array must equal pj1939_num_rx_tx_bufs. The array is not to be accessed by application code.

5.17.12.3.29. out_queue

Definition: CAN_PACKET_T out_queue[]

Description: This is the queue of transmit messages.

Present in the C-API description only for build time size requirements. The array must be declared and sized by the application. The size of the array must equal pj1939_num_rx_tx_bufs. The array is not to be accessed by application code.

5.17.12.3.30. pj1939_use_common_mf_priority

Definition: const BOOL pj1939_use_common_mf_priority

Description: This is a flag to determine whether to use a common priority for all J1939 multi-frame diagnostic message transmissions.

If true then the priority for such messages is taken from pj1939_common_multiframe_priority. If false, the priority is as defined in the argument to the appropriate message transmit function. Note that that function argument always determines priority for single-frame messages.

5.17.12.3.31. pj1939_common_multiframe_priority

Definition: const U8 pj1939_common_multiframe_priority

Description: This is the common priority used for all J1939 multi-frame diagnostic message transmissions.

It is only used when the pj1939_use_common_mf_priority flag is true.

Range: [0, 7]

5.17.12.3.32. pj1939_dm1_source_addr

Definition: const U8 pj1939_dm1_source_addr[]

Description: This is an array of J1939 node addresses corresponding to the list of addresses which are known to transmit DM1 messages.

Addresses must be declared in ascending order with each address being unique. DM1 messages sent from other addresses are ignored by the library.

If the ECU is to process received DM1 messages, then the PGN 65226 must be added to the array _pgn_table[].

Range: [0, 253]

5.17.12.3.33. pj1939_dm1_source_addr_num

Definition: const U8 pj1939_dm1_source_addr_num

Description: This is the number of declared J1939 DM1 transmitter addresses in the pj1939_dm1_source_addr[] array.

Range: [0, 255]

5.17.12.3.34. pj1939_dm1_rx_buf_data

Definition: U8* const pj1939_dm1_rx_buf_data[]

Description: This is the list of pointers to message data buffers for each DM1 message to be received.

Each message buffer pointed to must be an array of bytes of size pj1939_size_j1939_rx_buf. The size of the array must equal pj1939_dm1_source_addr_num.

5.17.12.3.35. pj1939_dm1_rx_counters

Definition: U32 pj1939_dm1_rx_counters[]

Description: This is an array of counters for each DM1 message to be received.

Each counter is incremented by pj1939_dm1_receive when a new message is received. The size of the array must equal to pj1939_dm1_source_addr_num.

5.17.12.3.36. pj1939_dm1_rx_buf

Definition: PJ1939_RX_BUF_T* const pj1939_dm1_rx_buf[]

Description: This is an array of pointers to message buffers for each DM1 message to be received.

Present in the C-API description only for build time size requirements. The array must be declared and sized by the application. The size of the array must equal pj1939_dm1_source_addr_num. The array is not to be accessed by application code.

5.17.12.3.37. pj1939_dm2_source_addr

Definition: const U8 pj1939_dm2_source_addr[]

Description: This is an array of J1939 node addresses corresponding to the list of addresses which are known to transmit DM2 messages.

Addresses must be declared in ascending order with each address being unique. DM2 messages sent from other addresses are ignored by the library.

Range: [0, 253]

5.17.12.3.38. pj1939_dm2_source_addr_num

Definition: const U8 pj1939_dm2_source_addr_num

Description: This is the number of declared J1939 DM2 transmitter addresses in the pj1939_dm2_source_addr[] array.

If the ECU is to process received DM2 messages, then the PGN 65227 must be added to the array _pgn_table[].

Range: [0, 255]

5.17.12.3.39. pj1939_dm2_rx_buf_data

Definition: U8* const pj1939_dm2_rx_buf_data[]

Description: This is the list of pointers to message data buffers for each DM2 message to be received.

Each message buffer pointed to must be an array of bytes of size pj1939_size_j1939_rx_buf. The size of the array must equal pj1939_dm2_source_addr_num.

5.17.12.3.40. pj1939_dm2_rx_buf

Definition: PJ1939_RX_BUF_T* const pj1939_dm2_rx_buf[]

Description: This is an array of pointers to message buffers for each DM2 message to be received.

Present in the C-API description only for build time size requirements. The array must be declared and sized by the application. The size of the array must equal pj1939_dm2_source_addr_num. The array is not to be accessed by application code.

5.17.12.3.41. pj1939_dm2_rx_counters

Definition: U32 pj1939_dm2_rx_counters[]

Description: This is an array of counters for each DM2 message to be received.

Each counter is incremented by pj1939_dm2_receive when a new message is received. The size of the array must equal to pj1939_dm2_source_addr_num.

5.17.12.3.42. pj1939_state

Definition: U8 pj1939_state[]

Description: This is an array of states for each DTC.

The array is sized by total number of DTCs in the system, as reported by pdtc_table_all. It is used by the J1939 feature to maintain information required for DM1 messages.

Note

The array is private to the library and should only be defined by the application. It is exposed as part of the API so it can be sized at build time to minimise the library memory footprint.

5.17.12.3.43. pj1939_sent

Definition: U8 pj1939_sent[]

Description: This is an array of sent flags for each DTC.

The array is sized by total number of DTCs in the system, as reported by pdtc_table_all. It is used by the J1939 feature to maintain information required for DM1 messages.

Note

The array is private to the library and should only be defined by the application. It is exposed as part of the API so it can be sized at build time to minimise the library memory footprint.

5.17.12.3.44. pj1939_transient

Definition: U8 pj1939_transient[]

Description: This is an array of transient fault states for each DTC.

The array is sized by total number of DTCs in the system, as reported by pdtc_table_all. It is used by the J1939 feature to maintain information required for DM35 messages.

Note

The array is private to the library and should only be defined by the application. It is exposed as part of the API so it can be sized at build time to minimise the library memory footprint.

5.17.12.3.45. pj1939_transient_sent

Definition: U8 pj1939_transient_sent[]

Description: This is an array of transient sent flags for each DTC.

The array is sized by total number of DTCs in the system, as reported by pdtc_table_all. It is used by the J1939 feature to maintain information required for DM35 messages.

Note

The array is private to the library and should only be defined by the application. It is exposed as part of the API so it can be sized at build time to minimise the library memory footprint.

5.17.12.4. Functions

5.17.12.4.1. pj1939_dm1_receive()

Definition: U8 pj1939_dm1_receive(U8 pj1939f_dm1_idx, U8 *pj1939f_lamp_malfunction, U8 *pj1939f_lamp_red, U8 *pj1939f_lamp_amber, U8 *pj1939f_lamp_protect, U32 *pj1939f_timestamp)

Supported targets: All targets

Required license: None (Main library).

Description: This function indicates if and when a J1939 DM1 message was received.

Examines a received J1939 DM1 message and decodes lamp information and provides a receive timestamp and counter per power cycle. Can be used in conjunction with pj1939_dm1_decode_dtc to determine when a certain diagnostic trouble code becomes active.

WARNING: The PCX feature takes precedence over the PJ1939 feature. If you configure the PCX feature to receive a J1939 frame, the PJ1939 feature will not see the frame, and it will not be processed by the platform. This especially causes problems when receiving J1939 DM14 'Boot Load' commands.

Can raise the following errors: PJ1939_DM1_RECEIVE_INVALID_ARG.

Arg (data in): pj1939f_dm1_idx Index into pj1939_dm1_rx_buf, pj1939_dm1_rx_buf_data and pj1939_dm1_rx_counters, thus identifying the DM1 message to work with (i.e., a DM1 message from a specific address). Range: [0, pj1939_dm1_source_addr_num - 1]

Arg (data out): pj1939f_lamp_malfunction Pointer to location to write the 'lamp malfunction' status for the source transmitting DM1. Once a valid message has been received, only updated if a new message is received or an error occurs. Cannot be NULL. Range: [0, 3]

One of PIO_DTC_LAMP_SLOW_FLASH, PIO_DTC_LAMP_FAST_FLASH, PIO_DTC_LAMP_ON or PIO_DTC_LAMP_OFF (default if no valid reception).

Arg (data out): pj1939f_lamp_red Pointer to location to write the 'lamp red' status for the source transmitting DM1. Once a valid message has been received, only updated if a new message is received or an error occurs. Cannot be NULL. Range: [0, 3] One of PIO_DTC_LAMP_SLOW_FLASH, PIO_DTC_LAMP_FAST_FLASH, PIO_DTC_LAMP_ON or PIO_DTC_LAMP_OFF (default if no valid reception).

Arg (data out): pj1939f_lamp_amber Pointer to location to write the 'lamp amber' status for the source transmitting DM1. Once a valid message has been received, only updated if a new message is received or an error occurs. Cannot be NULL. Range: [0, 3] One of PIO_DTC_LAMP_SLOW_FLASH, PIO_DTC_LAMP_FAST_FLASH, PIO_DTC_LAMP_ON or PIO_DTC_LAMP_OFF (default if no valid reception).

Arg (data out): pj1939f_lamp_protect Pointer to location to write the 'lamp protect' status for the source transmitting DM1. Once a valid message has been received, only updated if a new message is received or an error occurs. Cannot be NULL. Range: [0, 3] One of PIO_DTC_LAMP_SLOW_FLASH, PIO_DTC_LAMP_FAST_FLASH, PIO_DTC_LAMP_ON or PIO_DTC_LAMP_OFF (default if no valid reception).

Arg (data out): pj1939f_timestamp A pointer to the location to write with the timestamp of the received message. Cannot be NULL. Range: [0, 4294967295] us

Return: One or more flags may be set in the return value to indicate:

• whether a fresh message was received since the last poll (PJ1939_RX_DATA);

• whether more than one message was received since the last poll (PJ1939_RX_OVERRUN);

• whether a receive error occurred for this message (PJ1939_RX_ERROR). 5.17.12.4.2. pj1939_dm1_decode_dtc()

Definition: void pj1939_dm1_decode_dtc(U8 pj1939f_dm1_idx, U32 pj1939f_spn, U8 pj1939f_fmi, U8 pj1939f_cm, U8 *pj1939f_active, U8 *pj1939f_oc)

Supported targets: All targets

Required license: None (Main library).

Description: This function decodes part of a received J1939 DM1 message.

Examine a received J1939 DM1 message for a specific diagnostic trouble code (given by a combination of pj1939f_spn, pj1939f_fmi and pj1939f_cm) and report what is found.

Can be used in conjunction with pj1939_dm1_receive to determine when a certain diagnostic trouble code becomes active.

Can raise the following errors: PJ1939_DM1_DECODE_INVALID_ARG.

Arg (data in): pj1939f_dm1_idx Index into pj1939_dm1_rx_buf and pj1939_dm1_rx_buf_data, thus identifying the DM1 message to work with (i.e., a DM1 message from a specific address). Range: [0, pj1939_dm1_source_addr_num - 1]

Arg (data in): pj1939f_spn The 'suspect parameter number' value to search for. Range: [0, 524287]

Arg (data in): pj1939f_fmi The SPN 'failure mode indicator' value to search for. Range: [0, 31]

Arg (data in): pj1939f_cm The SPN 'conversion method' value to search for. Range: [0, 1]

Arg (data out): pj1939f_active Pointer to location to write the status of the SPN/FMI/CM diagnostic trouble code. Written TRUE if the diagnostic trouble code is reported in the message (i.e. Active, for DM1), or written FALSE otherwise. Cannot be NULL.

Arg (data out): pj1939f_oc Pointer to the location to write the occurrence count of the diagnostic trouble code. Cannot be NULL. Range: [0, 127]

5.17.12.4.3. pj1939_dm2_receive()

Definition: U8 pj1939_dm2_receive(U8 pj1939f_dm2_idx, U8 *pj1939f_lamp_malfunction, U8 *pj1939f_lamp_red, U8 *pj1939f_lamp_amber, U8 *pj1939f_lamp_protect, U32 *pj1939f_timestamp)

Supported targets: All targets

Required license: None (Main library).

Description: This function indicates if and when a J1939 DM2 message was received.

Examines a received J1939 DM2 message and decodes lamp information and provides a receive timestamp and counter per power cycle. Can be used in conjunction with pj1939_dm2_decode_dtc to determine when a certain diagnostic trouble code becomes inactive (or previously active).

Can raise the following errors: PJ1939_DM2_RECEIVE_INVALID_ARG.

Arg (data in): pj1939f_dm2_idx Index into pj1939_dm2_rx_buf, pj1939_dm2_rx_buf_data and pj1939_dm2_rx_counters, thus identifying the DM2 message to work with (i.e., a DM2 message from a specific address). Range: [0, pj1939_dm2_source_addr_num - 1]

Arg (data out): pj1939f_lamp_malfunction Pointer to location to write the 'lamp malfunction' status for the source transmitting DM2. Once a valid message has been received, only updated if a new message is received or an error occurs. Cannot be NULL. Range: [0, 3] One of PIO_DTC_LAMP_SLOW_FLASH, PIO_DTC_LAMP_FAST_FLASH, PIO_DTC_LAMP_ON or PIO_DTC_LAMP_OFF (default if no valid reception).

Arg (data out): pj1939f_lamp_red Pointer to location to write the 'lamp red' status for the source transmitting DM2. Once a valid message has been received, only updated if a new message is received or an error occurs. Cannot be NULL. Range: [0, 3] One of PIO_DTC_LAMP_SLOW_FLASH, PIO_DTC_LAMP_FAST_FLASH, PIO_DTC_LAMP_ON or PIO_DTC_LAMP_OFF (default if no valid reception).

Arg (data out): pj1939f_lamp_amber Pointer to location to write the 'lamp amber' status for the source transmitting DM2. Once a valid message has been received, only updated if a new message is received or an error occurs. Cannot be NULL. Range: [0, 3] One of PIO_DTC_LAMP_SLOW_FLASH, PIO_DTC_LAMP_FAST_FLASH, PIO_DTC_LAMP_ON or PIO_DTC_LAMP_OFF (default if no valid reception).

Arg (data out): pj1939f_lamp_protect Pointer to location to write the 'lamp protect' status for the source transmitting DM2. Once a valid message has been received, only updated if a new message is received or an error occurs. Cannot be NULL. Range: [0, 3]

One of PIO_DTC_LAMP_SLOW_FLASH, PIO_DTC_LAMP_FAST_FLASH, PIO_DTC_LAMP_ON or PIO_DTC_LAMP_OFF (default if no valid reception).

Arg (data out): pj1939f_timestamp A pointer to the location to write with the timestamp of the received message. Cannot be NULL. Range: [0, 4294967295] us

Return: One or more flags may be set in the return value to indicate:

• whether a fresh message was received since the last poll (PJ1939_RX_DATA);

• whether more than one message was received since the last poll (PJ1939_RX_OVERRUN);

• whether a receive error occurred for this message (PJ1939_RX_ERROR). 5.17.12.4.4. pj1939_dm2_decode_dtc()

Definition: void pj1939_dm2_decode_dtc(U8 pj1939f_dm2_idx, U32 pj1939f_spn, U8 pj1939f_fmi, U8 pj1939f_cm, U8 *pj1939f_previously_active, U8 *pj1939f_oc)

Supported targets: All targets

Required license: None (Main library).

Description: This function decodes part of a received J1939 DM2 message.

Examine a received J1939 DM2 message for a specific diagnostic trouble code (given by a combination of pj1939f_spn, pj1939f_fmi and pj1939f_cm) and report what is found.

Can be used in conjunction with pj1939_dm2_receive to determine when a certain diagnostic trouble code becomes inactive (previously active).

Can raise the following errors: PJ1939_DM2_DECODE_INVALID_ARG.

Arg (data in): pj1939f_dm2_idx Index into pj1939_dm2_rx_buf and pj1939_dm2_rx_buf_data, thus identifying the DM2 message to work with (i.e., a DM2 message from a specific address). Range: [0, pj1939_dm2_source_addr_num - 1]

Arg (data in): pj1939f_spn The 'suspect parameter number' value to search for. Range: [0, 524287]

Arg (data in): pj1939f_fmi The SPN 'failure mode indicator' value to search for.

Range: [0, 31]

Arg (data in): pj1939f_cm The SPN 'conversion method' value to search for. Range: [0, 1]

Arg (data out): pj1939f_previously_active Pointer to location to write the status of the SPN/FMI/CM diagnostic trouble code. Written TRUE if the diagnostic trouble code is reported in the message (i.e. Previously Active, for DM2), or written FALSE otherwise. Cannot be NULL.

Arg (data out): pj1939f_oc Pointer to the location to write the occurrence count of the diagnostic trouble code. Cannot be NULL. Range: [0, 127]

5.17.12.4.5. pj1939_dm1_transmit()

Definition: void pj1939_dm1_transmit(const PDTC_TABLE_T *const pj1939f_table, const U8 pj1939f_force_transmission, const U8 pj1939f_priority, U8 *pj1939f_error_flag, U8 *pj1939f_transport_error)

Supported targets: All targets

Required license: None (Main library).

Description: This function attempts to transmit a J1939 DM1 message.

Request that a J1939 DM1 message is constructed from the contents of a diagnostic trouble code table and transmitted (broadcast).

The DM1 message contents are constructed from the diagnostic trouble codes stored in one DTC table. Diagnostic trouble codes which do not have J1939 type are ignored.

The transmission of a DM1 message can involve many CAN packets and to avoid overloading the CAN bus, the J1939 specification provides some guidance for transmission rates. This can be overridden if necessary.

• forced transmission - causes the function to attempt to transmit a DM1 message regardless of the changing state of the DTCs.

• unforced transmission - causes the function to attempt to transmit a DM1 message:

• since the last transmission, a duration of one second has past and either, there is at least one active DTC, or despite no active DTCs a DTC becoming inactive has not been transmitted yet;

• since the last transmission, a DTC changes state for the first time (subsequent state changes do not cause a DM1 message to be transmitted).

Can raise the following errors: PJ1939_DM1_TRANSMIT_INVALID_ARG.

Arg (data in): pj1939f_table A pointer to a diagnostic trouble code table. The contents of the DM1 message are derived from DTCs of J1939 type in this table (DTCs of other types are ignored). Cannot be NULL.

Arg (data in): pj1939f_force_transmission Set true if the DM1 message should be transmitted regardless of DTC state changes, set false if the DM1 message should be transmitted according to the general guidelines laid out in SAE J1939-73.

Arg (data in): pj1939f_priority The priority of the DM1 message to be transmitted. The lower the priority value, the higher the message priority. Note that this value will be overridden for multi-frame transmissions if the capi assignment statement multiframe-priority is defined (but will still be used for single-frame transmissions). Range: [0, 7]

Arg (data out): pj1939f_error_flag A pointer to the location to write with the status of the transmission. Written true if there was no free transmit buffer available to hold the DM1 message for transmission, Written false otherwise. Cannot be NULL.

Arg (data out): pj1939f_transport_error A pointer to the location to write the saturated count of transport errors encountered. Cannot be NULL. Range: [0, 255] errors 5.17.12.4.6. pj1939_dm2_transmit()

Definition: void pj1939_dm2_transmit(const PDTC_TABLE_T *const pj1939f_table, const U8 pj1939f_transmit, const U8 pj1939f_priority, U8 *pj1939f_error_flag, U8 *pj1939f_transport_error)

Supported targets: All targets

Required license: None (Main library).

Description: This function attempts to transmit a J1939 DM2 message.

Request that a J1939 DM2 message is constructed from the contents of a diagnostic trouble code table and transmitted (broadcast).

The DM2 message contents are constructed from the diagnostic trouble codes stored in one DTC table. Diagnostic trouble codes which do not have J1939 type are ignored.

Unlike DM1 messages, DM2 messages are transmitted on request.

Can raise the following errors:

PJ1939_DM2_TRANSMIT_INVALID_ARG.

Arg (data in): pj1939f_table A pointer to a diagnostic trouble code table. The contents of the DM2 message are derived from DTCs of J1939 type in this table (DTCs of other types are ignored). Cannot be NULL.

Arg (data in): pj1939f_transmit Set true if the DM2 message should be transmitted, false otherwise.

Arg (data in): pj1939f_priority The priority of the DM2 message to be transmitted. The lower the priority value, the higher the message priority. Note that this value will be overridden for multi-frame transmissions if the capi assignment statement multiframe-priority is defined (but will still be used for single-frame transmissions). Range: [0, 7]

Arg (data out): pj1939f_error_flag A pointer to the location to write with the status of the transmission. Written true if there was no free transmit buffer available to hold the DM2 message for transmission, Written false otherwise. Cannot be NULL.

Arg (data out): pj1939f_transport_error A pointer to the location to write the saturated count of transport errors encountered. Cannot be NULL. Range: [0, 255] errors

5.17.12.4.7. pj1939_inhibit_reprogramming()

Definition: void pj1939_inhibit_reprogramming(U8 pj1939f_inhibit, PJ1939_INHIBIT_REPR_REASONS_T pj1939f_reason)

Supported targets: All targets

Required license: None (Main library).

Description: Enable or disable J1939 reprogramming 'Boot Load' requests while running application mode.

The ECU uses the J1939 protocol for reprogramming. Reprogramming requests are always honoured while the ECU is in reprogramming mode. In application mode, reprogramming requests can be enabled or disabled. For instance, the application might enable reprogramming requests only while it is in an idle and safe state. The application needs to supply a reason for inhibitting reprogramming. This reason will be passed on to an reprogramming -requesting Service Tools.

Arg (data in): pj1939f_inhibit True if reprogramming should be inhibited, false otherwise.

Arg (data in): pj1939f_reason Gives the reason for inhibiting reprogramming.

5.17.12.4.8. pj1939_was_pgn_requested()

Definition: void pj1939_was_pgn_requested(const U32 pj1939f_pgn_idx, U32 *pj1939f_timestamp, U8 *pj1939f_requested, U8 *pj1939f_source_addr, U8 *pj1939f_dest_addr)

Supported targets: All targets

Required license: None (Main library).

Description: Determine whether a PGN has been requested from this node.

Search through the list of PGN requests which have been made either to this node's address or to the broadcast address. If a request has been made then clear the PGN request from the list and return details relating to the request.

Can raise the following errors: PJ1939_WAS_REQ_PGN_INVALID_ARG.

Note

If a PG request message is received, but the requested PG does not match any requested PGN, then the library shall respond with a NACK to the sender of the PG request message, unless the request for PG was sent to the global address, in which case, the NACK is not transmitted.

Arg (data in): pj1939f_pgn_idx The index into the pj1939_pgn_requested_table [] array, thus identifying the requested PGN to work with. Use the macros included by the header file generated from the interface tool, of the form PJ1939_PGN_TABLE_IDX_[PGN- NUMBER]. Range: [0, pj1939_num_requested_pgns - 1]

Arg (data out): pj1939f_timestamp A pointer to the location to write the timestamp of the received message. Cannot be NULL. Range: [0, 4294967295] us

Arg (data out): pj1939f_requested A pointer to the location to write the result of searching for the PGN. Written true if the PGN has been requested, written false otherwise. The request status is cleared after the search. Cannot be NULL.

Arg (data out): pj1939f_source_addr A pointer to the location to write the source address of the J1939 message requesting the PGN. Cannot be NULL. Range of source address: [0, 253]

Arg (data out): pj1939f_dest_addr A pointer to the location to write the destination address of the J1939 message requesting the PGN. Cannot be NULL. Range of destination address: [0, 253 or 255] 5.17.12.4.9. pj1939_pg_receive()

Definition: void pj1939_pg_receive(const U32 pj1939f_pgn_idx, U32 *pj1939f_timestamp, U8 *pj1939f_error_flag, U8 *pj1939f_rx_trig_flag, U8 *pj1939f_overrun_flag, U8 *pj1939f_source_addr, U8 *pj1939f_dest_addr, const U16 pj1939f_message_len, const U16 pj1939f_num_fields, void *const *pj1939f_item_ptr, const U16 *pj1939f_field_start_pos, const U8 *pj1939f_field_width, const U8 *pj1939f_field_sign, const U8 *pj1939f_field_packing)

Supported targets: All targets

Required license: None (Main library).

Description: Determine if a PGN has been received and extract its contents if required.

If a PGN has been received, then unpack the contents of the received message. If a PGN has not been received, then unpack the contents of the received message as if all message data was zero.

The unpacking sequence works as follows:

• for each element in pj1939f_item_ptr

1. read the data from the PGN receive message buffer given by pj1939f_pgn_idx , based on the item's field start position pj1939f_field_start, and bit width pj1939f_field_width, based on the byte ordering of the item given by pj1939f_field_packing

2. if the item is signed as given by pj1939f_field_sign, then perform sign extension

3. write the converted value to the store given by pj1939f_item_ptr

In addition, the function sets various flags to indicate the state of message reception (received since last call, received more than once since last call, received in error).

WARNING: The PCX feature takes precendece over the PJ1939 feature. If you configure the PCX feature to receive a J1939 frame, the PJ1939 feature will not see the frame, and it will not be processed by the platform. This especially causes problems when receiving J1939 DM14 'Boot Load' commands.

Can raise the following errors: PJ1939_PG_RECEIVE_INVALID_ARG.

Arg (data in): pj1939f_pgn_idx The index into the _pgn_table[] and pj1939_rx_buf[] arrays, thus identifying the received PGN message to work with.

Use the macros included by the header file generated from the interface tool, of the form PJ1939_PGN_TABLE_IDX_[PGN- NUMBER]. Range: [0, pj1939_num_pgns - 1]

Arg (data out): pj1939f_timestamp A pointer to the location to write the timestamp of the received message. Cannot be NULL. Range: [0, 4294967295] us

Arg (data out): pj1939f_error_flag A pointer to the location to write the error status of receiving the J1939 message. Written true if there was an error when receiving the message last time, written false otherwise. An error occurs if the length of the J1939 message data contents does not match pj1939f_message_len, or if this node has lost its address claim, or if this node is currently bus-off. Cannot be NULL.

Arg (data out): pj1939f_rx_trig_flag A pointer to the location to write the status of receiving the J1939 message. Written true if the message was received since the last call, written false otherwise. Cannot be NULL.

Arg (data out): pj1939f_overrun_flag A pointer to the location to write the status of receiving the J1939 message. Written true if the message was received more than once since the last call, written false otherwise. Cannot be NULL.

Arg (data out): pj1939f_source_addr A pointer to the location to write the source address of the received J1939 message. Range of source address: [0, 253] Cannot be NULL.

Arg (data out): pj1939f_dest_addr A pointer to the location to write the destination address of the received J1939 message. Can be NULL (in which case, it is not written). Range of destination address: [0, 253 or 255]

Arg (data in): pj1939f_message_len The expected length of the data contents of the received J1939 message. Range: [0, 1785] bytes

Arg (data in): pj1939f_num_fields Number of fields in each of pj1939f_item_ptr, pj1939f_field_start_pos, pj1939f_field_width , pj1939f_field_sign, and pj1939f_field_packing. The function does not check that all arrays have the same length. The results of the function are undefined if the length of each differs from this function argument. Range: [0, 65535] fields

Arg (data in): pj1939f_item_ptr Pointer to array of pointers to data to be unpacked from the receive buffer. Each item in this array should point to 32-bit signed or unsigned integer.

Cannot be NULL.

Arg (data in): pj1939f_field_start_pos Pointer to array of field start bit numbers. For each item to unpack from the J1939 message, the function determines where to retrieve the data using the corresponding element from this array. 0 corresponds to the least significant bit of data byte 0 of the message, 15 to the most significant bit of data byte 2 of the message, and so on, assuming these exist. Cannot be NULL.

Arg (data in): pj1939f_field_width Pointer to array of field bit widths. For each item to unpack from the J1939 message, the function determines how many bits to retrieve from the array using the corresponding element from this array. Cannot be NULL. Range: [1, 32]

Note

If a field extends beyond the length of the data contents of the received message (given by pj1939f_field_start_pos and pj1939f_field_width) then the functionality is undefined.

Arg (data in): pj1939f_field_sign Pointer to array of sign flags (flag set true if signed, false otherwise). For each item to unpack from the J1939 message, the function determines whether to use the MSB of the packed data as a sign bit or not. Cannot be NULL.

Arg (data in): pj1939f_field_packing Pointer to array of byte ordering flags (flag set true if field's data bytes are ordered most significant byte first, false if field's data bytes are ordered least significant byte first (as is typical for J1939 data)). For each item to unpack from the J1939 message, the function determines whether to unpack MSB or LSB. Cannot be NULL. 5.17.12.4.10. pj1939_pg_transmit()

Definition: void pj1939_pg_transmit(const U32 pj1939f_pgn, U8 pj1939f_priority, U8 *pj1939f_error_flag, U8 *pj1939f_transport_error, const U16 pj1939f_message_len, const U16 pj1939f_num_fields, void *const *pj1939f_item_ptr, const U16 *pj1939f_field_start_pos, const U8 *pj1939f_field_width, const U8 *pj1939f_field_packing)

Supported targets: All targets

Required license: None (Main library).

Description: Construct a J1939 message and attempt to send it (deprecated).

Became deprecated in version 2.2.0. This function will be removed in a future release. This function is no longer necessary, please remove from use in application code.

Pack a set of data fields into a J1939 message and attempt to send it.

When the ECU has no network address (has claimed the NULL address), it can only participate in network communications.

If the node address for the ECU cannot be claimed, or the CAN link for J1939 is bus-off, then the software shall set the output pj1939f_error_flag parameter true and not attempt to buffer the message for transmission.

When the ECU has a network address (has claimed a non- NULL address without conflict), then the ECU can participate in all communications.

The library transmits the buffered message when possible. If the message has a data length greater than 8 bytes, then the message is transmitted using the transport protocol. The protocol includes various timeouts and abort conditions, and these are accumulated by the function and presented to the application on the next call to this function via pj1939f_transport_error.

When the application completes initialisation, the library sets the PG message's transport error count to zero.

If an error occurs while transmitting the message using the transport protocol, then the library increments the message's transport error count (saturating at 255).

The packing sequence works as follows:

• set the data contents of the PGN transmit message buffer given by pj1939f_pgn to all bits set

• for each element in pj1939f_item_ptr

1. read the integer data value from pj1939f_item_ptr

2. clip the integer to the field width as given by pj1939f_field_width

3. write bits to PGN transmit buffer identified by pj1939f_msg_data based with the byte ordering given by pj1939f_field_packing and the bit position given by pj1939f_field_start

Can raise the following errors: PJ1939_PG_TRANSMIT_INVALID_ARG.

Arg (data in): pj1939f_pgn The PGN value of the J1939 transmit message including the PS field. The PS field of the PGN must represent the destination address for PDU1 format. If the PS field is zero, the message will be broadcasted globally (PDU2 format). Range: [0, 131071]

Arg (data in): pj1939f_priority The priority of the J1939 message to transmit. The lower the priority value, the higher the message priority. Range: [0, 7]

occurs if there are no free buffers to store the transmit message, or if the node address for the ECU cannot be claimed, or the CAN link for J1939 is bus-off. Cannot be NULL.

Arg (data out): pj1939f_transport_error A saturated count of the transport transmit errors encountered while transmitting a J1939 message. The transport layer is only involved if the message must be broken into more than one CAN message (i.e., the data content of the message exceeds 8 data bytes). Cannot be NULL. Range: [0, 255] errors

Arg (data in): pj1939f_message_len The length of the data contents of the J1939 transmit message. Range: [0, 1785] bytes

Arg (data in): pj1939f_item_ptr Pointer to array of pointers to data to be packed into the transmit buffer. Cannot be NULL.

Arg (data in): pj1939f_num_fields Number of fields in each of pj1939f_item_ptr, pj1939f_field_start_pos, pj1939f_field_width and pj1939f_field_packing. The function does not check that all arrays have the same length. The results of the function are undefined if the length of each differs from this function argument. Range: [0, 65535] fields

Arg (data in): pj1939f_field_start_pos Pointer to array of field start bit numbers. For each item to unpack from the J1939 message, the function determines where to retrieve the data using the corresponding element from this array. 0 corresponds to the least significant bit of data byte 1 of the message, 15 to the most significant bit of data byte 2 of the message, and so on, assuming these exist. Cannot be NULL.

Note

If a field overlaps (as given by pj1939f_field_start_pos and pj1939f_field_width) then the functionality is undefined.

If a field extends beyond the length of the transmit data contents (as given by pj1939f_field_start_pos and pj1939f_field_width) then the functionality is undefined.

Arg (data in): pj1939f_field_packing Pointer to array of byte ordering flags (flag set true if field's data bytes are ordered most significant byte first, false if field's data bytes

are ordered least significant byte first (as is typical for J1939 data)). For each item to unpack from the J1939 message, the function determines whether to unpack MSB or LSB. Cannot be NULL.

5.17.12.4.11. pj1939_pdu1_transmit()

Definition: void pj1939_pdu1_transmit(const U32 pj1939f_pgn, const U8 pj1939f_dest_addr, U8 pj1939f_priority, U8 *pj1939f_error_flag, U8 *pj1939f_transport_error, const U16 pj1939f_message_len, const U16 pj1939f_num_fields, void *const *pj1939f_item_ptr, const U16 *pj1939f_field_start_pos, const U8 *pj1939f_field_width, const U8 *pj1939f_field_packing)

Supported targets: All targets

Required license: None (Main library).

Description: Construct a J1939 message and attempt to send it.

Pack a set of data fields into a J1939 message and attempt to send it using PDU1 format.

When the ECU has no network address (has claimed the NULL address), it can only participate in network communications.

When the ECU has a network address (has claimed a non- NULL address without conflict), then the ECU can participate in all communications.

When the application completes initialisation, the library sets the PG message's transport error count to zero.

If an error occurs while transmitting the message using the transport protocol, then the library increments the message's transport error count (saturating at 255).

The packing sequence works as follows:

• set the data contents of the PGN transmit message buffer given by pj1939f_pgn to all bits set

• for each element in pj1939f_item_ptr

1. read the integer data value from pj1939f_item_ptr

2. clip the integer to the field width as given by pj1939f_field_width

3. write bits to PGN transmit buffer identified by pj1939f_msg_data based with the byte ordering given by pj1939f_field_packing and the bit position given by pj1939f_field_start

Can raise the following errors: PJ1939_PG_TRANSMIT_INVALID_ARG.

Arg (data in): pj1939f_pgn The PGN value of the J1939 transmit message. Range: [0, 130816]

Arg (data in): pj1939f_dest_addr The destination address for the J1939 transmit message. Range: [0, 255]

Arg (data in): pj1939f_priority The priority of the J1939 message to transmit. The lower the priority value, the higher the message priority. Range: [0, 7]

Arg (data out): pj1939f_error_flag A pointer to the location to write with the error status of transmitting the J1939 message. Written true if there was an error when transmitting the message this time, written false otherwise. An error occurs if there are no free buffers to store the transmit message, or if the node address for the ECU cannot be claimed, or the CAN link for J1939 is bus-off. Cannot be NULL.

Arg (data in): pj1939f_message_len The length of the data contents of the J1939 transmit message. Range: [0, 1785] bytes

Arg (data in): pj1939f_item_ptr Pointer to array of pointers to data to be packed into the transmit buffer. Cannot be NULL.

Arg (data in): pj1939f_field_start_pos Pointer to array of field start bit numbers. For each item to unpack from the J1939 message, the function determines where to

retrieve the data using the corresponding element from this array. 0 corresponds to the least significant bit of data byte 1 of the message, 15 to the most significant bit of data byte 2 of the message, and so on, assuming these exist. Cannot be NULL.

Note

If a field overlaps (as given by pj1939f_field_start_pos and pj1939f_field_width) then the functionality is undefined.

If a field extends beyond the length of the transmit data contents (as given by pj1939f_field_start_pos and pj1939f_field_width) then the functionality is undefined.

5.17.12.4.12. pj1939_pdu2_transmit()

Definition: void pj1939_pdu2_transmit(const U32 pj1939f_pgn, U8 pj1939f_priority, U8 *pj1939f_error_flag, U8 *pj1939f_transport_error, const U16 pj1939f_message_len, const U16 pj1939f_num_fields, void *const *pj1939f_item_ptr, const U16 *pj1939f_field_start_pos, const U8 *pj1939f_field_width, const U8 *pj1939f_field_packing)

Supported targets: All targets

Required license: None (Main library).

Description: Construct a J1939 message and attempt to send it.

Pack a set of data fields into a J1939 message and attempt to broadcast it using PDU2 format.