From b838eb7b87d8d3ebfbeadf2588c75de6e1dc7244 Mon Sep 17 00:00:00 2001 From: Piotr Korkus Date: Wed, 4 Feb 2026 08:13:49 +0100 Subject: [PATCH] refactor examples structure - link existing examples in `/examples` - add READMEs --- README.md | 2 +- examples/com-api-example | 1 + examples/ipc_bridge | 1 + .../mw/com/example/com-api-example/README.md | 134 ++++++++++++++++++ .../example/com-api-example/com-api-gen/BUILD | 1 + score/mw/com/example/ipc_bridge/README.md | 127 +++++++++++++++++ 6 files changed, 265 insertions(+), 1 deletion(-) create mode 120000 examples/com-api-example create mode 120000 examples/ipc_bridge create mode 100644 score/mw/com/example/com-api-example/README.md create mode 100644 score/mw/com/example/ipc_bridge/README.md diff --git a/README.md b/README.md index c371e059..df09aee3 100644 --- a/README.md +++ b/README.md @@ -120,7 +120,7 @@ communication/ ### For Users - [User Guide](score/mw/com/README.md) - Getting started with the API - [API Reference](score/mw/com/design/README.md) - Detailed API documentation -- [Examples](score/mw/com/example/) - Code examples and tutorials +- [Examples](examples/) - Code examples and tutorials ### For Developers - [Architecture Guide](score/mw/com/design/README.md) - System architecture overview diff --git a/examples/com-api-example b/examples/com-api-example new file mode 120000 index 00000000..c9145863 --- /dev/null +++ b/examples/com-api-example @@ -0,0 +1 @@ +../score/mw/com/example/com-api-example \ No newline at end of file diff --git a/examples/ipc_bridge b/examples/ipc_bridge new file mode 120000 index 00000000..7e6556e9 --- /dev/null +++ b/examples/ipc_bridge @@ -0,0 +1 @@ +../score/mw/com/example/ipc_bridge \ No newline at end of file diff --git a/score/mw/com/example/com-api-example/README.md b/score/mw/com/example/com-api-example/README.md new file mode 100644 index 00000000..f5c183bd --- /dev/null +++ b/score/mw/com/example/com-api-example/README.md @@ -0,0 +1,134 @@ +# COM-API-EXAMPLE + +## Building + +### Standard Build (Host Platform) + +```bash +bazel build //examples/com-api-example:com-api-example +``` + +### QNX Cross-Compilation + +```bash +bazel build --config=x86_64-qnx //examples/com-api-example:com-api-example +``` + +## Running + +After building, the binary will be in `bazel-bin/examples/com-api-example/com-api-example`. + +### Quick Start + +To see the COM API in action, run the example from the repo root: + +```bash +./bazel-bin/examples/com-api-example/com-api-example +``` + +The application demonstrates a producer-consumer pattern where: + +- A `VehicleOfferedProducer` publishes tire pressure data +- A `VehicleConsumer` subscribes to and receives tire pressure updates +- Five samples are sent with incrementing tire pressure values (5.0, 6.0, 7.0, 8.0, 9.0) +- Each sample is read back and validated + +You should see output showing tire data being sent and received, demonstrating the complete publish-subscribe workflow. + +### Running Tests + +```bash +bazel test //examples/com-api-example:com-api-example-test +``` + +The test suite includes: + +- **Integration test**: Basic producer-consumer workflow with synchronous operations +- **Async test**: Multi-threaded async producer-consumer using Tokio runtime + +## Configuration + +The communication behavior is configured via `examples/com-api-example/etc/config.json`: + +- Service interface definitions (`VehicleInterface`) +- Event definitions for data types (`Tire`) +- Instance-specific configuration +- Shared memory settings and transport configuration + +## Project Structure + +```text +examples/ +├── com-api-example/ +│ ├── basic-consumer-producer.rs # Main example and integration tests +│ ├── BUILD # Bazel build configuration +│ ├── etc/ +│ │ └── config.json # Communication configuration +│ └── com-api-gen/ +│ ├── com_api_gen.rs # Generated Rust bindings +│ ├── vehicle_gen.cpp # Generated C++ implementation +│ └── vehicle_gen.h # Generated C++ headers +``` + +## Code Structure + +The example demonstrates several key patterns: + +### VehicleMonitor Struct + +A composite structure that combines: + +- `VehicleConsumer`: Subscribes to vehicle data +- `VehicleOfferedProducer`: Publishes vehicle data +- `Subscription`: Active subscription to tire data + +### Producer-Consumer Pattern + +```rust +// Create producer +let producer = create_producer(runtime, service_id.clone()); + +// Create consumer +let consumer = create_consumer(runtime, service_id); + +// Create monitor combining both +let monitor = VehicleMonitor::new(consumer, producer).unwrap(); + +// Write data +monitor.write_tire_data(Tire { pressure: 5.0 }).unwrap(); + +// Read data +let tire_data = monitor.read_tire_data().unwrap(); +``` + +### Async Multi-Threading (Test) + +The async test demonstrates: + +- Concurrent producer and consumer tasks using Tokio +- Asynchronous data sending at 2ms intervals +- Asynchronous data processing with buffering +- Proper lifecycle management (offer/unoffer) + +## Troubleshooting + +### Build Warnings + +You may see deprecation warnings during compilation related to the COM API. These are intentional warnings from the S-CORE libraries and do not prevent successful builds. + +### QNX Builds + +QNX cross-compilation requires: + +- QNX SDP installation and license +- Proper credential setup (see `.github/workflows/build_and_test_qnx.yml` for CI example) + +### Configuration Path Issues + +The example expects the configuration file at: + +```text +score/mw/com/example/com-api-example/etc/config.json +``` + +Ensure this path is accessible from your workspace root when running the binary. diff --git a/score/mw/com/example/com-api-example/com-api-gen/BUILD b/score/mw/com/example/com-api-example/com-api-gen/BUILD index dfd08c33..e166cd40 100644 --- a/score/mw/com/example/com-api-example/com-api-gen/BUILD +++ b/score/mw/com/example/com-api-example/com-api-gen/BUILD @@ -20,6 +20,7 @@ rust_library( features = ["link_std_cpp_lib"], visibility = [ "//score/mw/com:__subpackages__", + "//examples:__subpackages__", ], deps = [ ":vehicle_gen_cpp", diff --git a/score/mw/com/example/ipc_bridge/README.md b/score/mw/com/example/ipc_bridge/README.md new file mode 100644 index 00000000..dfdae135 --- /dev/null +++ b/score/mw/com/example/ipc_bridge/README.md @@ -0,0 +1,127 @@ +# IPC_BRIDGE + +## Building + +### Standard Build (Host Platform) + +```bash +bazel build //examples/ipc_bridge:sample_sender_receiver +``` + +### QNX Cross-Compilation + +```bash +bazel build --config=x86_64-qnx //examples/ipc_bridge:sample_sender_receiver +``` + +## Running + +After building the binary will be in `bazel-bin/examples/ipc_bridge/ipc_bridge_cpp`. + +### Quick Start (Two Terminals) + +To see the IPC communication in action, open two terminals in the repo root: + +**Terminal 1 - Start Skeleton (Publisher):** + +```bash +./bazel-bin/examples/ipc_bridge/ipc_bridge_cpp \ + --mode skeleton \ + --cycle-time 1000 \ + --num-cycles 10 \ + --service_instance_manifest examples/ipc_bridge/etc/mw_com_config.json +``` + +**Terminal 2 - Start Proxy (Subscriber):** + +```bash +./bazel-bin/examples/ipc_bridge/ipc_bridge_cpp \ + --mode proxy \ + --cycle-time 500 \ + --num-cycles 20 \ + --service_instance_manifest examples/ipc_bridge/etc/mw_com_config.json +``` + +You should see the proxy discover the skeleton service, subscribe, and receive `MapApiLanesStamped` samples. The proxy validates data integrity and ordering for each received sample. + +### Start Skeleton (Publisher) + +```bash +./bazel-bin/examples/ipc_bridge/ipc_bridge_cpp \ + --mode skeleton \ + --cycle-time 1000 \ + --num-cycles 10 \ + --service_instance_manifest examples/ipc_bridge/etc/mw_com_config.json +``` + +### Start Proxy (Subscriber) + +```bash +./bazel-bin/src/scrample \ + --mode proxy \ + --cycle-time 500 \ + --num-cycles 20 \ + --service_instance_manifest examples/ipc_bridge/etc/mw_com_config.json +``` + +### Command-Line Options + +| Option | Description | Required | +| ------ | ----------- | -------- | +| `--mode, -m` | Operation mode: `skeleton`/`send` or `proxy`/`recv` | Yes | +| `--cycle-time, -t` | Cycle time in milliseconds for sending/polling | Yes | +| `--num-cycles, -n` | Number of cycles to execute (0 = infinite) | Yes | +| `--service_instance_manifest, -s` | Path to communication config JSON | Optional | +| `--disable-hash-check, -d` | Skip sample hash validation in proxy mode | Optional | + +## Configuration + +The communication behavior is configured via `examples/ipc_bridge/etc/mw_com_config.json`: + +- Service type definitions and bindings +- Event definitions with IDs +- Instance-specific configuration (shared memory settings, subscriber limits) +- ASIL level and process ID restrictions + +## Project Structure + +``` text +examples/ +├── ipc_bridge/ +│ ├── main.cpp # Entry point and CLI argument parsing +│ ├── sample_sender_receiver.cpp # Core skeleton/proxy logic +│ ├── datatype.h # Data type definitions +│ ├── assert_handler.cpp # Custom assertion handling +│ └── etc/ +│ ├── mw_com_config.json # Communication configuration +│ └── logging.json # Logging configuration +``` + +## Troubleshooting + +### Runtime Warnings + +When running the application, you may see: + +```text +mw::log initialization error: Error No logging configuration files could be found. +Fallback to console logging. +``` + +This is expected and harmless. The application falls back to console logging when the optional logging configuration isn't found at the expected system location. + +### Build Warnings + +You may see deprecation warnings during compilation related to: + +- `string_view` null-termination checks +- `InstanceSpecifier::Create()` API deprecations + +These are intentional warnings from the S-CORE libraries and do not prevent successful builds. They are addressed in the `.bazelrc` configuration with `-Wno-error=deprecated-declarations`. + +### QNX Builds + +QNX cross-compilation requires: + +- QNX SDP installation and license +- Proper credential setup (see `.github/workflows/build_and_test_qnx.yml` for CI example)