From 2e01fda194e3f9221270b1cf04ef2f8f7241aebe Mon Sep 17 00:00:00 2001 From: Knox Lively Date: Thu, 1 May 2025 09:41:02 -0600 Subject: [PATCH 1/2] 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/2] 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