libbpf-rs: Addressed API code review

libbpf-rs/Cargo.toml

@@ -7,3 +7,4 @@ license = "LGPL-2.1 OR BSD-2-Clause"
 
 [dependencies]
 thiserror = "1.0"
+bitflags = "1.2"

libbpf-rs/src/lib.rs

@@ -18,6 +18,7 @@ mod perf_buffer;
 pub use crate::error::{Error, Result};
 pub use crate::link::Link;
 pub use crate::object::{
-    Map, MapOptions, MapType, Object, ObjectOptions, Program, ProgramAttachType, ProgramType,
+    CgroupAttachFlags, Map, MapBuilder, MapBuilderFlags, MapFlags, MapType, Object, Program,
+    ProgramAttachType, ProgramBuilder, ProgramType,
 };
-pub use crate::perf_buffer::{PerfBuffer, PerfBufferOpts};
+pub use crate::perf_buffer::{PerfBuffer, PerfBufferBuilder};

libbpf-rs/src/link.rs

@@ -1,35 +1,16 @@
-use crate::object::{Object, Program};
 use crate::*;
 
-/// Represents a loaded and attached [`Program`].
+/// Represents an attached [`Program`].
 ///
 /// This struct is used to model ownership. The underlying program will be detached
-/// and unloaded from the system when this object is dropped.
+/// when this object is dropped if nothing else is holding a reference count.
 pub struct Link {}
 
 impl Link {
-    /// Attach `prog` to the system. The attach point is determined by looking
-    /// at which section the `prog` is assigned to.
-    pub fn attach(_prog: Program) -> Result<Self> {
-        unimplemented!();
-    }
-
-    /// Convenience function to [`Link::attach`] all [`Program`]s in `obj`.
-    ///
-    /// Note that this excludes [perf events](https://linux.die.net/man/2/perf_event_open)
-    /// because libbpf does not have enough information to construct an event.
-    pub fn attach_all(_obj: Object) -> Result<Vec<Self>> {
-        unimplemented!();
-    }
-
-    /// Attach a `prog` to a [perf event](https://linux.die.net/man/2/perf_event_open)
-    /// file descriptor.
-    pub fn attach_perf_event(_prog: Program, _pfd: i64) -> Result<Self> {
-        unimplemented!();
-    }
-
     /// Replace the underlying prog with `prog`.
-    pub fn update_prog(&mut self, _prog: Program) -> Result<()> {
+    ///
+    /// Returns the replaced [`Program`] on success.
+    pub fn update_prog(&mut self, _prog: Program) -> Result<Program> {
         unimplemented!();
     }
 }

libbpf-rs/src/object.rs

@@ -1,63 +1,119 @@
 use std::path::Path;
 
+use bitflags::bitflags;
+
 use crate::*;
 
 /// Represents a BPF object file. An object may contain zero or more
 /// [`Program`]s and [`Map`]s.
 pub struct Object {}
 
 impl Object {
-    pub fn with_path<P: AsRef<Path>>(_path: P, _opts: ObjectOptions) -> Result<Self> {
+    pub fn from_path<P: AsRef<Path>>(_path: P) -> Result<Self> {
+        unimplemented!();
+    }
+
+    pub fn from_memory(_name: &str, _mem: &[u8]) -> Result<Self> {
+        unimplemented!();
+    }
+
+    /// Override the generated name that would have been inferred from the constructor.
+    pub fn set_name<T: AsRef<str>>(&mut self, _name: T) -> &mut Self {
         unimplemented!();
     }
 
-    pub fn with_memory(_name: &str, _mem: &[u8], _opts: ObjectOptions) -> Result<Self> {
+    /// Option to parse map definitions non-strictly, allowing extra attributes/data
+    pub fn set_relaxed_maps(&mut self, _relaxed_maps: bool) -> &mut Self {
         unimplemented!();
     }
 
     pub fn name(&self) -> &str {
         unimplemented!();
     }
 
-    pub fn maps(&self) -> Vec<&Map> {
+    pub fn map<T: AsRef<str>>(&mut self, _name: T) -> Option<&mut MapBuilder> {
+        unimplemented!();
+    }
+
+    pub fn prog<T: AsRef<str>>(&mut self, _name: T) -> Option<&mut ProgramBuilder> {
+        unimplemented!();
+    }
+}
+
+/// Represents a parsed but not yet loaded map.
+///
+/// Some methods require working with raw bytes. You may find libraries such as
+/// [`plain`](https://crates.io/crates/plain) helpful.
+pub struct MapBuilder {}
+
+impl MapBuilder {
+    pub fn set_map_ifindex(&mut self, _idx: u32) -> &mut Self {
+        unimplemented!();
+    }
+
+    pub fn set_max_entries(&mut self, _entries: u32) -> &mut Self {
+        unimplemented!();
+    }
+
+    pub fn set_initial_value(&mut self, _data: &[u8]) -> &mut Self {
         unimplemented!();
     }
 
-    /// Acquire ownership of [`Map`] s in this object for which `f` returns `true`.
-    pub fn take_maps<F>(&mut self, _f: F) -> Vec<Map>
-    where
-        F: FnMut(&Map),
-    {
+    pub fn set_numa_node(&mut self, _node: u32) -> &mut Self {
         unimplemented!();
     }
 
-    pub fn progs(&self) -> Vec<&Program> {
+    pub fn set_inner_map_fd(&mut self, _inner: Map) -> &mut Self {
         unimplemented!();
     }
 
-    /// Acquire ownership of [`Program`]s in this object for which `f` returns `true`.
-    pub fn take_progs<F>(&mut self, _f: F) -> Vec<Program>
-    where
-        F: FnMut(&Program),
-    {
+    pub fn set_flags(&mut self, _flags: MapBuilderFlags) -> &mut Self {
+        unimplemented!();
+    }
+
+    pub fn load(&mut self) -> Result<Map> {
         unimplemented!();
     }
 }
 
-/// Options to configure [`Object`] processing.
-pub struct ObjectOptions {}
+#[rustfmt::skip]
+bitflags! {
+    pub struct MapBuilderFlags: u64 {
+	const NO_PREALLOC     = 1 << 0;
+	const NO_COMMON_LRU   = 1 << 1;
+	const NUMA_NODE       = 1 << 2;
+	const RDONLY          = 1 << 3;
+	const WRONLY          = 1 << 4;
+	const STACK_BUILD_ID  = 1 << 5;
+	const ZERO_SEED       = 1 << 6;
+	const RDONLY_PROG     = 1 << 7;
+	const WRONLY_PROG     = 1 << 8;
+	const CLONE           = 1 << 9;
+	const MMAPABLE        = 1 << 10;
+    }
+}
 
-/// Represents a map.
+/// Represents a created map.
+///
+/// The kernel ensure the atomicity and safety of operations on a `Map`. Therefore,
+/// this handle is safe to clone and pass around between threads. This is essentially a
+/// file descriptor.
 ///
 /// Some methods require working with raw bytes. You may find libraries such as
 /// [`plain`](https://crates.io/crates/plain) helpful.
+#[derive(Clone)]
 pub struct Map {}
 
 impl Map {
     pub fn name(&self) -> &str {
         unimplemented!();
     }
 
+    /// Returns a file descriptor to the underlying map.
+    pub fn fd(&self) -> u32 {
+        unimplemented!();
+    }
+
     pub fn map_type(&self) -> MapType {
         unimplemented!();
     }
@@ -75,7 +131,7 @@ impl Map {
     /// Returns map value as `Vec` of `u8`.
     ///
     /// `key` must have exactly [`Map::key_size()`] elements.
-    pub fn lookup(&self, _key: &[u8]) -> Result<Option<Vec<u8>>> {
+    pub fn lookup(&self, _key: &[u8], _flags: MapFlags) -> Result<Option<Vec<u8>>> {
         unimplemented!();
     }
 
@@ -89,45 +145,54 @@ impl Map {
     /// Same as [`Map::lookup()`] except this also deletes the key from the map.
     ///
     /// `key` must have exactly [`Map::key_size()`] elements.
-    pub fn lookup_and_delete(&mut self, _key: &[u8], _opts: MapOptions) -> Result<Option<Vec<u8>>> {
+    pub fn lookup_and_delete(&mut self, _key: &[u8], _flags: MapFlags) -> Result<Option<Vec<u8>>> {
         unimplemented!();
     }
 
     /// Update an element.
     ///
     /// `key` must have exactly [`Map::key_size()`] elements. `value` must have exatly
     /// [`Map::value_size()`] elements.
-    pub fn update(&mut self, _key: &[u8], _value: &[u8], _opts: MapOptions) -> Result<()> {
+    pub fn update(&mut self, _key: &[u8], _value: &[u8], _flags: MapFlags) -> Result<()> {
         unimplemented!();
     }
 }
 
-/// Options to configure [`Map`] operations.
-pub struct MapOptions {}
+#[rustfmt::skip]
+bitflags! {
+    /// Flags to configure [`Map`] operations.
+    pub struct MapFlags: u64 {
+	const ANY      = 0;
+	const NO_EXIST = 1 << 0;
+	const EXIST    = 1 << 1;
+	const LOCK     = 1 << 2;
+    }
+}
 
 /// Type of a [`Map`]. Maps to `enum bpf_map_type` in kernel uapi.
 #[non_exhaustive]
 pub enum MapType {}
 
-/// Represents a BPF program.
-pub struct Program {}
+/// Represents a parsed but not yet loaded BPF program.
+pub struct ProgramBuilder {}
 
-impl Program {
-    pub fn name(&self) -> &str {
+impl ProgramBuilder {
+    pub fn set_prog_type(&mut self, _prog_type: ProgramType) -> &mut Self {
         unimplemented!();
     }
 
-    /// Name of the section this `Program` belongs to. This information is used by
-    /// [`crate::link::Link`] constructors to determine where to attach the prog.
-    pub fn section(&self) -> &str {
+    pub fn set_attach_type(&mut self, _attach_type: ProgramAttachType) -> &mut Self {
         unimplemented!();
     }
 
-    pub fn prog_type(&self) -> ProgramType {
+    pub fn set_ifindex(&mut self, _idx: i32) -> &mut Self {
         unimplemented!();
     }
 
-    pub fn attach_type(&self) -> ProgramAttachType {
+    // TODO: more flags here:
+    // https://github.com/torvalds/linux/blob/master/include/uapi/linux/bpf.h#L267
+
+    pub fn load(&mut self) -> Result<Program> {
         unimplemented!();
     }
 }
@@ -139,3 +204,55 @@ pub enum ProgramType {}
 /// Attach type of a [`Program`]. Maps to `enum bpf_attach_type` in kernel uapi.
 #[non_exhaustive]
 pub enum ProgramAttachType {}
+
+/// Represents a loaded [`Program`].
+///
+/// The kernel ensure the atomicity and safety of operations on a `Program`. Therefore,
+/// this handle is safe to clone and pass around between threads. This is essentially a
+/// file descriptor.
+///
+/// If you attempt to attach a `Program` with the wrong attach method, the `attach_*`
+/// method will fail with the appropriate error.
+#[derive(Clone)]
+pub struct Program {}
+
+impl Program {
+    pub fn name(&self) -> &str {
+        unimplemented!();
+    }
+
+    /// Name of the section this `Program` belongs to.
+    pub fn section(&self) -> &str {
+        unimplemented!();
+    }
+
+    pub fn prog_type(&self) -> ProgramType {
+        unimplemented!();
+    }
+
+    /// Returns a file descriptor to the underlying program.
+    pub fn fd(&self) -> u32 {
+        unimplemented!();
+    }
+
+    pub fn attach_type(&self) -> ProgramAttachType {
+        unimplemented!();
+    }
+
+    pub fn attach_cgroup(&mut self, _cgroup_fd: u32, _flags: CgroupAttachFlags) -> Result<Link> {
+        unimplemented!();
+    }
+
+    pub fn attach_perf_event(&mut self, _pfd: u32) -> Result<Link> {
+        unimplemented!();
+    }
+}
+
+#[rustfmt::skip]
+bitflags! {
+    pub struct CgroupAttachFlags: u64 {
+	const ALLOW_OVERRIDE   = 1 << 0;
+	const ALLOW_MULTI      = 1 << 1;
+	const REPLACE          = 1 << 2;
+    }
+}