Add lib module docs

Author: szymon-zadworny

oneapi-rs/src/lib.rs

@@ -6,6 +6,76 @@
 // SPDX-License-Identifier: MIT OR Apache-2.0
 //
 
+//! # oneAPI-rs
+//! oneAPI-rs is a set of (mostly) safe Rust bindings for SYCL. The bindings mirror the C++ API
+//! where appropriate, but they also introduce some changes. In particular - accessors and command
+//! group handlers have been replaced with USM allocations and free-function kernels.
+//!
+//! # Getting started
+//! 1. Create a [`Queue`](crate::queue::Queue). It's the main entry point to the SYCL API.
+//! ```
+//! let mut queue = Queue::new();
+//! ```
+//!
+//! 2. Create an [USM buffer](crate::buffer::Buffer) for your data.
+//! ```
+//! let mut device_buffer = queue.alloc_device::<f64>(1024).wait();
+//! ```
+//!
+//! 3. Build a SYCL kernel.
+//! ```
+//! let kernel = queue
+//!     .get_context()
+//!     .create_kernel_bundle_from_source(IOTA_SRC)
+//!     .build()
+//!     .get_kernel("iota");
+//! ```
+//!
+//! 4. Launch your kernel.
+//! ```
+//! unsafe {
+//!     queue.launch(
+//!         NdRange::new([1024], [16]),
+//!         &kernel,
+//!         (3.14, &mut device_buffer),
+//!     )
+//! }
+//! .wait();
+//! ```
+//!
+//! 5. Copy your data to the host.
+//! ```
+//! let mut host_buffer = queue.alloc_host::<f64>(1024).wait();
+//! queue.copy(&device_buffer, &mut host_buffer).wait();
+//! ```
+//!
+//! You can access your host data just like a normal Rust slice.
+//! ```
+//! for e in host_buffer.iter() {
+//!     print!("{e} ");
+//! }
+//! println!();
+//! ```
+//!
+//! # Safety model
+//! - USM allocations are represented by a zero-cost `Buffer` type managed through RAII.
+//!   - Note: Unlike SYCL buffers, oneAPI-rs buffers do not rely on accessors.
+//! - Buffers are zero-initialized by default.
+//! - Buffers can only store types that implement [`bytemuck::Pod`].
+//! - Kernel launch is inherently unsafe.
+//!
+//! # Asynchronous programming model
+//! Each queue operation returns an [`Event`](`crate::event::Event`). You can synchronously
+//! [`.wait()`](crate::event::Event::wait) for it, or asynchronously `.await` it.
+//!
+//! You can also synchronously call [`Queue::wait()`](crate::queue::Queue::wait) to wait for a
+//! [`Queue`](crate::queue::Queue) directly. To do the same asynchronously you have to `.await` an
+//! event returned by [`Queue::barrier()`](crate::queue::Queue::barrier).
+//!
+//! # System dependencies
+//! Make sure to download the [Intel oneAPI toolkit](https://www.intel.com/content/www/us/en/developer/tools/oneapi/oneapi-toolkit-download.html).
+//! Then go to your installation directory and source the `setvars.sh` file.
+
 pub mod buffer;
 pub mod context;
 pub mod device;