Module utils 

Utility types and functions for OSAL-RS.

This module contains common types, error definitions, and helper functions used throughout the library.

Overview

The utilities module provides essential building blocks for working with OSAL-RS in embedded environments:

• Error handling: Comprehensive Error enum for all OSAL operations
• String utilities: Fixed-size Bytes type for embedded string handling
• Conversion macros: Safe C string conversion and parameter extraction
• FFI types: Type aliases for C interoperability
• Thread safety: SyncUnsafeCell for static mutable state in Rust 2024+

Main Types

Error Handling

• Error<'a> - All possible error conditions with optional borrowed error messages
• Result<T, E> - Type alias for core::result::Result with default Error<'static>
• OsalRsBool - Boolean type compatible with RTOS return values

String Handling

• Bytes<SIZE> - Fixed-size byte buffer with string conversion utilities
• AsSyncStr - Trait for thread-safe string references

Constants

• MAX_DELAY - Maximum timeout for blocking indefinitely
• CpuRegisterSize - CPU register size detection (32-bit or 64-bit)

FFI Types

• Ptr, ConstPtr, DoublePtr - Type aliases for C pointers

Thread Safety

• SyncUnsafeCell<T> - Wrapper for static mutable variables (replaces static mut)

Macros

String Conversion

• [from_c_str!] - Convert C string pointer to Rust String (lossy conversion)
• [to_cstring!] - Convert Rust string to CString with error handling
• [to_c_str!] - Convert Rust string to C string pointer (panics on error)
• [from_str_to_array!] - Convert string to fixed-size byte array

Parameter Handling

• [thread_extract_param!] - Extract typed parameter from thread entry point
• [access_static_option!] - Access static Option variable (panics if None)

Helper Functions

Hex Conversion

• bytes_to_hex - Convert bytes to hex string (allocates)
• bytes_to_hex_into_slice - Convert bytes to hex into buffer (no allocation)
• hex_to_bytes - Parse hex string to bytes (allocates)
• hex_to_bytes_into_slice - Parse hex string into buffer (no allocation)

Platform Detection

• register_bit_size - Const function to detect CPU register size (32-bit or 64-bit)

Best Practices

1. Use Bytes<SIZE> for embedded strings: Avoids heap allocation, fixed size
2. Prefer no-alloc variants: Use _into_slice functions when possible
3. Handle errors explicitly: Always check Result returns
4. Use to_cstring! over to_c_str!: Better error handling with ? operator
5. Synchronize SyncUnsafeCell access: Use mutexes or critical sections in multi-threaded environments

Structs

Bytes

Fixed-size byte array wrapper with string conversion utilities.

SyncUnsafeCell

Thread-safe wrapper for UnsafeCell usable in static contexts.

Enums

CpuRegisterSize

CPU register size enumeration.

Error

Error types for OSAL-RS operations.

OsalRsBool

Boolean type compatible with RTOS return values.

Constants

MAX_DELAY

Maximum delay constant for blocking operations.

Traits

AsSyncStr

Trait for types that can provide a string reference in a thread-safe manner.

Functions

bytes_to_hex

Converts a byte slice to a hexadecimal string representation.

bytes_to_hex_into_slice

Converts a byte slice to hexadecimal representation into a pre-allocated buffer.

hex_to_bytes

Converts a hexadecimal string to a vector of bytes.

hex_to_bytes_into_slice

Converts a hexadecimal string to bytes into a pre-allocated buffer.

register_bit_size

Determines the CPU register size at compile time.

Type Aliases

ConstPtr

Const pointer type for C FFI.

DoublePtr

Pointer to pointer type for C FFI.

Ptr

Mutable pointer type for C FFI.

Result

Standard Result type for OSAL-RS operations.