From 2e01fda194e3f9221270b1cf04ef2f8f7241aebe Mon Sep 17 00:00:00 2001 From: Knox Lively Date: Thu, 1 May 2025 09:41:02 -0600 Subject: [PATCH 1/3] Moved execution environment to top for most APIs, and removed function from the GPIO documentation. --- docs/reference/apis/container-api/gpio.md | 75 +------------------ docs/reference/apis/container-api/index.md | 13 +++- .../inter-container-messaging.md | 13 +++- docs/reference/apis/container-api/sensors.md | 10 ++- docs/reference/apis/container-api/timers.md | 10 ++- docs/reference/apis/index.md | 1 - 6 files changed, 35 insertions(+), 87 deletions(-) diff --git a/docs/reference/apis/container-api/gpio.md b/docs/reference/apis/container-api/gpio.md index 5538741..1ce501f 100644 --- a/docs/reference/apis/container-api/gpio.md +++ b/docs/reference/apis/container-api/gpio.md @@ -79,10 +79,6 @@ A function that will be called when a GPIO pin's state changes. typedef void (*ocre_gpio_callback_t)(int pin, ocre_gpio_pin_state_t state); ``` -### Execution Environment - -All GPIO functions have an internal `wasm_exec_env_t` parameter that is used by the Ocre runtime. This parameter is NOT needed when calling these functions from within a container. Container applications should omit this parameter. - --- ## Methods @@ -231,28 +227,6 @@ int ocre_gpio_unregister_callback(int pin); | `0` | on success | | negative value | on error | -### Get Pin ID - -Calculates a pin ID from port and pin numbers. - -```c -int get_pin_id(int port, int pin); -``` - -**Parameters**: - -| Name | Type | Description | -| ------ | ------ | ----------- | -| `port` | *int* | GPIO port number | -| `pin` | *int* | Pin number within the port | - -**Returns**: - -| Value | Description | -| ------ | ----------- | -| positive value (pin ID) | on success | -| `-1` | on error | - --- ## Error Handling @@ -380,52 +354,6 @@ int main() { } ``` -### Using Port and Pin Mapping - -```c -#include -#include "ocre_gpio.h" - -#define GPIO_PORT_A 0 -#define GPIO_PIN_5 5 - -int main() { - // Initialize GPIO subsystem - if (ocre_gpio_init() != 0) { - printf("Failed to initialize GPIO\n"); - return -1; - } - - // Calculate pin ID from port and pin - int pin_id = get_pin_id(GPIO_PORT_A, GPIO_PIN_5); - if (pin_id < 0) { - printf("Invalid port or pin\n"); - return -1; - } - - // Configure the pin as output - ocre_gpio_config_t config; - config.pin = pin_id; - config.direction = OCRE_GPIO_DIR_OUTPUT; - - if (ocre_gpio_configure(&config) != 0) { - printf("Failed to configure GPIO pin\n"); - return -1; - } - - // Toggle the pin 10 times - for (int i = 0; i < 10; i++) { - ocre_gpio_pin_toggle(pin_id); - printf("Pin toggled\n"); - - // Delay (implementation-specific) - for (volatile int j = 0; j < 500000; j++); - } - - return 0; -} -``` - --- ## Reference @@ -438,5 +366,4 @@ int main() { | [`ocre_gpio_pin_get`](#get-gpio-pin-state) | Gets a GPIO pin state | `pin`: GPIO pin number | `OCRE_GPIO_PIN_SET`/`OCRE_GPIO_PIN_RESET` or negative error code | `ENODEV`, `EINVAL` | | [`ocre_gpio_pin_toggle`](#toggle-gpio-pin) | Toggles a GPIO pin state | `pin`: GPIO pin number | `0` on success, negative on error | `ENODEV`, `EINVAL` | | [`ocre_gpio_register_callback`](#register-gpio-callback) | Registers callback for GPIO changes | `pin`: GPIO pin number
`callback`: Callback function | `0` on success, negative on error | `ENODEV`, `EINVAL` | -| [`ocre_gpio_unregister_callback`](#unregister-gpio-callback) | Removes GPIO callback | `pin`: GPIO pin number | `0` on success, negative on error | `ENODEV`, `EINVAL` | -| [`get_pin_id`](#get-pin-id) | Calculates pin ID from port and pin | `port`: GPIO port number
`pin`: Pin number within port | Pin ID or `-1` on invalid Pin | N/A | +| [`ocre_gpio_unregister_callback`](#unregister-gpio-callback) | Removes GPIO callback | `pin`: GPIO pin number | `0` on success, negative on error | `ENODEV`, `EINVAL` | \ No newline at end of file diff --git a/docs/reference/apis/container-api/index.md b/docs/reference/apis/container-api/index.md index 29bc5b8..4146564 100644 --- a/docs/reference/apis/container-api/index.md +++ b/docs/reference/apis/container-api/index.md @@ -16,14 +16,25 @@ Below are the core APIs available for Ocre containers. Each API includes detaile ### Communication +Communication APIs enable containers to interact with each other and with external systems. + | API | Description| |-----|-------------| | **[Inter-Container Messaging](inter-container-messaging)** | Enable secure communication between containers | -### System Interaction +## Hardware + +Hardware APIs provide direct access to physical devices and sensors attached to the system. | API | Description | |-----|-------------| | **[GPIO](gpio)** | Control digital pins for input/output operations with hardware peripherals and external components | | **[Sensors](sensors)** | Interface with hardware sensors for environmental and motion data | + +### Time Management + +Time management APIs enable precise timing operations for container applications. + +| API | Description | +|-----|-------------| | **[Timers](timers)** | Create and manage timed events with millisecond precision | \ No newline at end of file diff --git a/docs/reference/apis/container-api/inter-container-messaging.md b/docs/reference/apis/container-api/inter-container-messaging.md index f7ee8cf..e9c2063 100644 --- a/docs/reference/apis/container-api/inter-container-messaging.md +++ b/docs/reference/apis/container-api/inter-container-messaging.md @@ -36,6 +36,13 @@ Navigate this comprehensive API reference using the links below. --- + +## Execution Environment + +All messaging functions have an internal `wasm_exec_env_t` parameter that is used by the Ocre runtime. This parameter is NOT needed when calling these functions from within a container. Container applications should omit this parameter. + +--- + ## Types ### Message Structure @@ -72,7 +79,7 @@ void ocre_msg_system_init(void); Publishes a message to the specified topic. ```c -int ocre_publish_message(wasm_exec_env_t exec_env, char *topic, char *content_type, void *payload, int payload_len); +int ocre_publish_message(char *topic, char *content_type, void *payload, int payload_len); ``` Fails if the messaging system is not initialized, if `topic`, `content_type`, or `payload` is `NULL`/empty, if `payload_len` is `0`, or if the message queue is full. @@ -99,7 +106,7 @@ Fails if the messaging system is not initialized, if `topic`, `content_type`, or Subscribes to a topic to receive messages. ```c -int ocre_subscribe_message(wasm_exec_env_t exec_env, char *topic, char *handler_name); +int ocre_subscribe_message(char *topic, char *handler_name); ``` **Parameters**: @@ -218,7 +225,7 @@ int main(void) { // Message handler function (exported for WASM) __attribute__((export_name("temperature_handler"))) -void temperature_handler(wasm_exec_env_t exec_env, ocre_msg_t *msg) { +void temperature_handler(ocre_msg_t *msg) { printf("Received message on topic: %s\n", msg->topic); printf("Content type: %s\n", msg->content_type); printf("Payload: %s\n", (char *)msg->payload); diff --git a/docs/reference/apis/container-api/sensors.md b/docs/reference/apis/container-api/sensors.md index 8919370..28ae03b 100644 --- a/docs/reference/apis/container-api/sensors.md +++ b/docs/reference/apis/container-api/sensors.md @@ -35,6 +35,12 @@ Navigate this comprehensive API reference using the links below. --- +## Execution Environment + +All sensor functions have an internal `wasm_exec_env_t` parameter that is used by the Ocre runtime. This parameter is NOT needed when calling these functions from within a container. Container applications should omit this parameter. + +--- + ## Types ### Sensor Callback Function @@ -127,10 +133,6 @@ typedef enum { } ocre_sensors_status_t; ``` -### Execution Environment - -All sensor functions have an internal `wasm_exec_env_t` parameter that is used by the Ocre runtime. This parameter is NOT needed when calling these functions from within a container. Container applications should omit this parameter. - --- ## Methods diff --git a/docs/reference/apis/container-api/timers.md b/docs/reference/apis/container-api/timers.md index 6a5b3b3..048cf98 100644 --- a/docs/reference/apis/container-api/timers.md +++ b/docs/reference/apis/container-api/timers.md @@ -35,6 +35,12 @@ Navigate this comprehensive API reference using the links below. --- +## Execution Environment + +All timer functions have an internal `wasm_exec_env_t` parameter that is used by the Ocre runtime. This parameter is NOT needed when calling these functions from within a container. Container applications should omit this parameter. + +--- + ## Types ### Timer Callback Function @@ -53,10 +59,6 @@ typedef int ocre_timer_t; Each timer is assigned a unique ID between `1` and `MAX_TIMERS`, which is used to reference the timer in all operations after creation. The timer handle is an opaque identifier that abstracts the underlying timer implementation. -### Execution Environment - -All timer functions have an internal `wasm_exec_env_t` parameter that is used by the Ocre runtime. This parameter is NOT needed when calling these functions from within a container. Container applications should omit this parameter. - --- ## Methods diff --git a/docs/reference/apis/index.md b/docs/reference/apis/index.md index 774bbcb..9557eb5 100644 --- a/docs/reference/apis/index.md +++ b/docs/reference/apis/index.md @@ -19,7 +19,6 @@ Ocre provides *two* primary categories of APIs: 2. **[Container Runtime API:](../apis/runtime-api)** The API for managing the Ocre container runtime environment itself, including container lifecycle operations. The Runtime API is intended for system implementors and integrators looking to incorporate the Ocre runtime into their own solutions. - --- ## Next Steps From 71b190c176b57355e3a0b2485f29d97982d9b22b Mon Sep 17 00:00:00 2001 From: Knox Lively Date: Thu, 1 May 2025 09:43:29 -0600 Subject: [PATCH 2/3] Removed mention of wasm_exec_env_t from the messaging docs --- .../apis/container-api/inter-container-messaging.md | 7 ------- 1 file changed, 7 deletions(-) diff --git a/docs/reference/apis/container-api/inter-container-messaging.md b/docs/reference/apis/container-api/inter-container-messaging.md index e9c2063..e4a2b46 100644 --- a/docs/reference/apis/container-api/inter-container-messaging.md +++ b/docs/reference/apis/container-api/inter-container-messaging.md @@ -88,7 +88,6 @@ Fails if the messaging system is not initialized, if `topic`, `content_type`, or | Name | Type | Description | | ---- | ---- | ----------- | -| `exec_env` | *wasm_exec_env_t* | Currently unused but required for compatibility with WebAssembly runtime | | `topic` | *char* | Topic name to publish the message to | | `content_type` | *char* | Content type of the message (`MIME` type recommended) | | `payload` | *void* | Pointer to the **message payload buffer** | @@ -113,7 +112,6 @@ int ocre_subscribe_message(char *topic, char *handler_name); | Name | Type | Description | | ---- | ---- | ----------- | -| `exec_env` | *wasm_exec_env_t* | WebAssembly execution environment used to locate the callback function in the WebAssembly module. | | `topic` | *char* | Topic name to subscribe to | | `handler_name` | *char* | Name of the callback function to be called when a message is received | @@ -151,11 +149,6 @@ The following example demonstrates how to use the Inter-Container Messaging API - The **[Publisher Container](#publisher-container)** sends JSON-formatted temperature readings to the `sensors/temperature` topic every 500 milliseconds. - The **[Subscriber Container](#subscriber-container)** subscribes to this topic and processes incoming messages. -**Notes**: -- The `wasm_exec_env_t` parameter is required for WebAssembly function signatures but may be unused in some cases (e.g., publishing). In real applications, it is provided by the WASM runtime. -- Use `ocre_sleep` instead of POSIX `sleep`. -- The messaging system automatically handles memory allocation and deallocation for messages passed to callback functions. - --- ### Publisher Container From ea59b7d39227811d7e269d6f42e27228c53103c2 Mon Sep 17 00:00:00 2001 From: Knox Lively Date: Mon, 5 May 2025 10:40:21 -0600 Subject: [PATCH 3/3] Added the RNG sensor and restructured the docs slightly. --- .../general_sensors.md} | 8 +- .../apis/container-api/sensors/index.md | 21 +++ .../apis/container-api/sensors/rng_sensor.md | 144 ++++++++++++++++++ 3 files changed, 169 insertions(+), 4 deletions(-) rename docs/reference/apis/container-api/{sensors.md => sensors/general_sensors.md} (99%) create mode 100644 docs/reference/apis/container-api/sensors/index.md create mode 100644 docs/reference/apis/container-api/sensors/rng_sensor.md diff --git a/docs/reference/apis/container-api/sensors.md b/docs/reference/apis/container-api/sensors/general_sensors.md similarity index 99% rename from docs/reference/apis/container-api/sensors.md rename to docs/reference/apis/container-api/sensors/general_sensors.md index 28ae03b..a2c3c91 100644 --- a/docs/reference/apis/container-api/sensors.md +++ b/docs/reference/apis/container-api/sensors/general_sensors.md @@ -1,10 +1,10 @@ --- -title: Sensors +title: General Sensors layout: default -parent: Container +parent: Sensors --- -# Sensors +# General Sensors {: .no_toc } The Sensors API provides a unified interface for discovering, configuring, and retrieving data from various hardware sensors in Ocre containers. It supports multiple sensor types and channels, allowing applications to interact with environmental, motion, and position sensing capabilities. @@ -467,4 +467,4 @@ int main() { | [`sensor_get_channel`](#get-sensor-channel) | Gets channel data | `sample`: Sensor sample
`channel`: Channel to retrieve | `ocre_sensor_value_t` structure | N/A | | [`ocre_sensors_set_trigger`](#set-sensor-trigger) | Sets sensor trigger | `sensor_handle`: Target sensor
`channel`: Target channel
`trigger_type`: Trigger type
`callback`: Callback function
`subscription_id`: `ID` output | Status code | `SENSOR_API_STATUS_OK`,
`SENSOR_API_STATUS_ERROR` | | [`ocre_sensors_clear_trigger`](#clear-sensor-trigger) | Removes sensor trigger | `sensor_handle`: Target sensor
`channel`: Target channel
`subscription_id`: Subscription to remove | Status code | `SENSOR_API_STATUS_OK`,
`SENSOR_API_STATUS_ERROR` | -| [`ocre_sensors_cleanup`](#clean-up-sensor-environment) | Cleans up resources | None | Status code | `SENSOR_API_STATUS_OK`,
`SENSOR_API_STATUS_ERROR` | +| [`ocre_sensors_cleanup`](#clean-up-sensor-environment) | Cleans up resources | None | Status code | `SENSOR_API_STATUS_OK`,
`SENSOR_API_STATUS_ERROR` | \ No newline at end of file diff --git a/docs/reference/apis/container-api/sensors/index.md b/docs/reference/apis/container-api/sensors/index.md new file mode 100644 index 0000000..4b78a28 --- /dev/null +++ b/docs/reference/apis/container-api/sensors/index.md @@ -0,0 +1,21 @@ +--- +title: Sensors +layout: default +parent: Container +has_toc: false +--- + +# Sensors APIs + +Sensors APIs provide unified interfaces for containers to discover, configure, and retrieve data from various hardware sensors. These APIs enable applications to interact with environmental, motion, position, and other specialized sensing capabilities in a consistent manner. + +--- + +## Available APIs + +Below are the sensor APIs available for Ocre containers, providing access to different types of sensor functionality. + +| API | Description | +|-----|-------------| +| [General Sensors](general_sensors) | Unified interface for working with all sensor types, including discovery, configuration, and data retrieval | +| [RNG Sensor](rng_sensor) | Hardware-backed random number generation capabilities with seamless integration into the sensor framework | \ No newline at end of file diff --git a/docs/reference/apis/container-api/sensors/rng_sensor.md b/docs/reference/apis/container-api/sensors/rng_sensor.md new file mode 100644 index 0000000..a832252 --- /dev/null +++ b/docs/reference/apis/container-api/sensors/rng_sensor.md @@ -0,0 +1,144 @@ +--- +title: RNG Sensor +layout: default +parent: Sensors +--- + +# RNG Sensor +{: .no_toc } + +The RNG sensor is pre-integrated with the Ocre sensor subsystem and built into the standard Ocre runtime. Users can access it through the [general Sensors](general_sensors.md) API without needing any additional header files, initialization steps, or configuration. + +--- + +## Table of Contents +{: .no_toc } + +Navigate this comprehensive API reference using the links below. + +
+ + Click to expand + + {: .text-delta } +1. TOC +{:toc} +
+ +--- + +## Header File + +```c +#include "rng_sensor.h" +``` + +{: .highlight Note} +The RNG sensor header file is for internal use only in the Ocre runtime implementation. Application developers should NOT include this header file in their code. Instead, they should only include the general sensors API header (`ocre_sensors.h`) and access the RNG sensor through the [general Sensors](general_sensors.md) API. + +--- + +## Methods + +For end users, there are no additional methods specific to the RNG sensor beyond those provided by the general Sensors API. The RNG sensor is accessed entirely through the standard sensor interface. + +The internal RNG sensor implementation includes: + +### RNG Sensor Initialization + +```c +int rng_sensor_init(const struct device *dev); +``` + +This function is for internal use only and is automatically called during system initialization. Users do not need to call this function. + +--- + +## Usage with Sensors API + +The RNG sensor provides a random number generation channel that can be accessed through the standard Sensors API. + +**To use the RNG sensor:** + +1. Include only the general sensors header: `#include "ocre_sensors.h"` +2. Initialize the sensor subsystem with `ocre_sensors_init()` +3. Discover available sensors with `ocre_sensors_discover()` +4. Find the RNG sensor by looking for a sensor that supports the channel `SENSOR_CHAN_CUSTOM + 1` (value 2) +5. Get a handle and open the sensor using standard API calls +6. Read random values using `ocre_sensors_read()` with channel value `SENSOR_CHAN_CUSTOM + 1` + +--- + +## Examples + +### Basic RNG Sensor Usage + +```c +#include +#include "ocre_sensors.h" + +int main() { + // Initialize the sensors subsystem + if (ocre_sensors_init(0) != 0) { + printf("Failed to initialize sensors\n"); + return -1; + } + + // Discover available sensors + int sensor_count = ocre_sensors_discover(); + if (sensor_count <= 0) { + printf("Failed to discover sensors\n"); + return -1; + } + + printf("Discovered %d sensors\n", sensor_count); + + // Find RNG sensor + int rng_sensor_id = -1; + for (int i = 0; i < sensor_count; i++) { + int channel_count = ocre_sensors_get_channel_count(i); + + // Check each channel of this sensor + for (int j = 0; j < channel_count; j++) { + int channel_type = ocre_sensors_get_channel_type(i, j); + + // Check if this is an RNG channel (using SENSOR_CHAN_CUSTOM + 1 value) + if (channel_type == 2) { // SENSOR_CHAN_CUSTOM + 1 = 2 + rng_sensor_id = i; + break; + } + } + + if (rng_sensor_id >= 0) break; + } + + if (rng_sensor_id < 0) { + printf("RNG sensor not found\n"); + return -1; + } + + // Get handle for the RNG sensor + ocre_sensor_handle_t rng_handle = ocre_sensors_get_handle(rng_sensor_id); + if (rng_handle < 0) { + printf("Failed to get handle for RNG sensor\n"); + return -1; + } + + // Open the RNG sensor + if (ocre_sensors_open(rng_handle) != 0) { + printf("Failed to open RNG sensor\n"); + return -1; + } + + // Read a random value, using SENSOR_CHAN_CUSTOM + 1 (value 2) as the channel + int random_value = ocre_sensors_read(rng_sensor_id, 2); // Channel 2 is the RNG channel + if (random_value < 0) { + printf("Failed to read random value\n"); + return -1; + } + + printf("Random value: %d\n", random_value); + + return 0; +} +``` \ No newline at end of file