From c92dbc2fced059d790b503699b08673128aa8c2c Mon Sep 17 00:00:00 2001
From: Roland Reichwein <Roland.Reichwein@bmw.de>
Date: Sat, 17 Jan 2026 14:26:16 +0100
Subject: [PATCH] Document how to implement platform specifics (#1262)

Some interfaces need to be implemented in every project
or platform using the ETL:

* etl_get_high_resolution_clock
* etl_get_system_clock
* etl_get_steady_clock
* etl_putchar

Co-authored-by: John Wellbelove <jwellbelove@users.noreply.github.com>
---
 README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/README.md b/README.md
index e9c9da8a..a4c26bdc 100644
--- a/README.md
+++ b/README.md
@@ -184,6 +184,84 @@ add_executable(foo main.cpp)
 target_link_libraries(foo PRIVATE etl::etl)
 ```
 
+## Profile definition
+
+When using ETL in a project, there is typically an `etl_profile.h` defined to
+adjust ETL to the project needs. ETL will automatically find `etl_profile.h`
+if it is available in the include path(s). If it's not available, ETL will
+work with default values.
+
+### Example
+
+```
+#ifndef __ETL_PROFILE_H__
+#define __ETL_PROFILE_H__
+
+#define ETL_TARGET_DEVICE_GENERIC
+#define ETL_TARGET_OS_NONE
+
+#define ETL_NO_STL
+
+#endif
+```
+
+## Platform specific implementation
+
+Although ETL is generally a self-contained header-only library, some interfaces need to be
+implemented in every project or platform, at least if those interfaces are actually being
+used, due to project specifics:
+
+| ETL header | Platform specific API to be implemented | Needed when using                   |
+|------------|-----------------------------------------|-------------------------------------|
+| `chrono.h` | `etl_get_high_resolution_clock()`       | `etl::high_resolution_clock::now()` |
+|            | `etl_get_system_clock()`                | `etl::system_clock::now()`          |
+|            | `etl_get_steady_clock()`                | `etl::steady_clock::now()`          |
+| `print.h`  | `etl_putchar()`                         | `etl::print()`                      |
+|            |                                         | `etl::println()`                    |
+
+### Example
+
+```
+#include <etl/chrono.h>
+#include <etl/print.h>
+
+extern "C"
+{
+
+etl::chrono::high_resolution_clock::rep etl_get_high_resolution_clock()
+{
+  etl::chrono::high_resolution_clock::rep(static_cast<int64_t>(getSystemTimeNs()));
+}
+
+etl::chrono::system_clock::rep etl_get_system_clock()
+{
+  return etl::chrono::system_clock::rep(static_cast<int64_t>(getSystemTimeNs()));
+}
+
+etl::chrono::system_clock::rep etl_get_steady_clock()
+{
+  return etl::chrono::system_clock::rep(static_cast<int64_t>(getSystemTimeNs()));
+}
+
+void etl_putchar(int c)
+{
+  putByteToStdout(static_cast<uint8_t>(c));
+}
+
+}
+```
+
+The following default values apply if the respective macros are not defined
+(e.g. in `etl_profile.h`):
+
+| Macro                                         | Default                    |
+|-----------------------------------------------|----------------------------|
+| `ETL_CHRONO_SYSTEM_CLOCK_DURATION`            | `etl::chrono::nanoseconds` |
+| `ETL_CHRONO_SYSTEM_CLOCK_IS_STEADY`           | `true`                     |
+| `ETL_CHRONO_HIGH_RESOLUTION_CLOCK_DURATION`   | `etl::chrono::nanoseconds` |
+| `ETL_CHRONO_HIGH_RESOLUTION_CLOCK_IS_STEADY`  | `true`                     |
+| `ETL_CHRONO_STEADY_CLOCK_DURATION`            | `etl::chrono::nanoseconds` |
+
 ## Arduino library
 
 The content of this repo is available as a library in the Arduino IDE (search for the "Embedded Template Library" in the IDE library manager). The Arduino library repository is available at ```https://github.com/ETLCPP/etl-arduino```, see there for more details.