Skip to content

Commit ad9b058

Browse files
committed
libbpf-rs: Add more doc comments
I only added comments where I was pretty sure I was right. Better to be low on docs than have wrong docs. For the stuff I didn't know I applied localized lint suppression. Done b/c next commit will trigger more missing doc warnings.
1 parent 232c8d1 commit ad9b058

File tree

2 files changed

+29
-3
lines changed

2 files changed

+29
-3
lines changed

libbpf-rs/src/map.rs

+19
Original file line numberDiff line numberDiff line change
@@ -125,10 +125,14 @@ impl<'obj> OpenMapMut<'obj> {
125125
}
126126
}
127127

128+
/// Bind map to a particular network device.
129+
///
130+
/// Used for offloading maps to hardware.
128131
pub fn set_map_ifindex(&mut self, idx: u32) {
129132
unsafe { libbpf_sys::bpf_map__set_ifindex(self.ptr.as_ptr(), idx) };
130133
}
131134

135+
/// Set the initial value of the map.
132136
pub fn set_initial_value(&mut self, data: &[u8]) -> Result<()> {
133137
let ret = unsafe {
134138
libbpf_sys::bpf_map__set_initial_value(
@@ -141,53 +145,68 @@ impl<'obj> OpenMapMut<'obj> {
141145
util::parse_ret(ret)
142146
}
143147

148+
/// Set the type of the map.
144149
pub fn set_type(&mut self, ty: MapType) -> Result<()> {
145150
let ret = unsafe { libbpf_sys::bpf_map__set_type(self.ptr.as_ptr(), ty as u32) };
146151
util::parse_ret(ret)
147152
}
148153

154+
/// Set the key size of the map in bytes.
149155
pub fn set_key_size(&mut self, size: u32) -> Result<()> {
150156
let ret = unsafe { libbpf_sys::bpf_map__set_key_size(self.ptr.as_ptr(), size) };
151157
util::parse_ret(ret)
152158
}
153159

160+
/// Set the value size of the map in bytes.
154161
pub fn set_value_size(&mut self, size: u32) -> Result<()> {
155162
let ret = unsafe { libbpf_sys::bpf_map__set_value_size(self.ptr.as_ptr(), size) };
156163
util::parse_ret(ret)
157164
}
158165

166+
/// Set the maximum number of entries this map can have.
159167
pub fn set_max_entries(&mut self, count: u32) -> Result<()> {
160168
let ret = unsafe { libbpf_sys::bpf_map__set_max_entries(self.ptr.as_ptr(), count) };
161169
util::parse_ret(ret)
162170
}
163171

172+
/// Set flags on this map.
164173
pub fn set_map_flags(&mut self, flags: u32) -> Result<()> {
165174
let ret = unsafe { libbpf_sys::bpf_map__set_map_flags(self.ptr.as_ptr(), flags) };
166175
util::parse_ret(ret)
167176
}
168177

178+
// TODO: Document member.
179+
#[allow(missing_docs)]
169180
pub fn set_numa_node(&mut self, numa_node: u32) -> Result<()> {
170181
let ret = unsafe { libbpf_sys::bpf_map__set_numa_node(self.ptr.as_ptr(), numa_node) };
171182
util::parse_ret(ret)
172183
}
173184

185+
// TODO: Document member.
186+
#[allow(missing_docs)]
174187
pub fn set_inner_map_fd(&mut self, inner_map_fd: BorrowedFd<'_>) -> Result<()> {
175188
let ret = unsafe {
176189
libbpf_sys::bpf_map__set_inner_map_fd(self.ptr.as_ptr(), inner_map_fd.as_raw_fd())
177190
};
178191
util::parse_ret(ret)
179192
}
180193

194+
// TODO: Document member.
195+
#[allow(missing_docs)]
181196
pub fn set_map_extra(&mut self, map_extra: u64) -> Result<()> {
182197
let ret = unsafe { libbpf_sys::bpf_map__set_map_extra(self.ptr.as_ptr(), map_extra) };
183198
util::parse_ret(ret)
184199
}
185200

201+
/// Set whether or not libbpf should automatically create this map during load phase.
186202
pub fn set_autocreate(&mut self, autocreate: bool) -> Result<()> {
187203
let ret = unsafe { libbpf_sys::bpf_map__set_autocreate(self.ptr.as_ptr(), autocreate) };
188204
util::parse_ret(ret)
189205
}
190206

207+
/// Set where the map should be pinned.
208+
///
209+
/// Note this does not actually create the pin.
191210
pub fn set_pin_path<P: AsRef<Path>>(&mut self, path: P) -> Result<()> {
192211
let path_c = util::path_to_cstring(path)?;
193212
let path_ptr = path_c.as_ptr();

libbpf-rs/src/program.rs

+10-3
Original file line numberDiff line numberDiff line change
@@ -123,8 +123,6 @@ pub struct OpenProgramImpl<'obj, T = ()> {
123123
_phantom: PhantomData<&'obj T>,
124124
}
125125

126-
// TODO: Document variants.
127-
#[allow(missing_docs)]
128126
impl<'obj> OpenProgram<'obj> {
129127
/// Create a new [`OpenProgram`] from a ptr to a `libbpf_sys::bpf_program`.
130128
pub fn new(prog: &'obj libbpf_sys::bpf_program) -> Self {
@@ -136,7 +134,7 @@ impl<'obj> OpenProgram<'obj> {
136134
}
137135
}
138136

139-
// The `ProgramType` of this `OpenProgram`.
137+
/// The `ProgramType` of this `OpenProgram`.
140138
pub fn prog_type(&self) -> ProgramType {
141139
ProgramType::from(unsafe { libbpf_sys::bpf_program__type(self.ptr.as_ptr()) })
142140
}
@@ -194,18 +192,23 @@ impl<'obj> OpenProgramMut<'obj> {
194192
}
195193
}
196194

195+
/// Set the program type.
197196
pub fn set_prog_type(&mut self, prog_type: ProgramType) {
198197
let rc = unsafe { libbpf_sys::bpf_program__set_type(self.ptr.as_ptr(), prog_type as u32) };
199198
debug_assert!(util::parse_ret(rc).is_ok(), "{rc}");
200199
}
201200

201+
/// Set the attachment type of the program.
202202
pub fn set_attach_type(&mut self, attach_type: ProgramAttachType) {
203203
let rc = unsafe {
204204
libbpf_sys::bpf_program__set_expected_attach_type(self.ptr.as_ptr(), attach_type as u32)
205205
};
206206
debug_assert!(util::parse_ret(rc).is_ok(), "{rc}");
207207
}
208208

209+
/// Bind the program to a particular network device.
210+
///
211+
/// Currently only used for hardware offload and certain XDP features such like HW metadata.
209212
pub fn set_ifindex(&mut self, idx: u32) {
210213
unsafe { libbpf_sys::bpf_program__set_ifindex(self.ptr.as_ptr(), idx) }
211214
}
@@ -230,6 +233,7 @@ impl<'obj> OpenProgramMut<'obj> {
230233
debug_assert!(util::parse_ret(rc).is_ok(), "{rc}");
231234
}
232235

236+
#[allow(missing_docs)]
233237
pub fn set_attach_target(
234238
&mut self,
235239
attach_prog_fd: i32,
@@ -257,6 +261,7 @@ impl<'obj> OpenProgramMut<'obj> {
257261
util::parse_ret(ret)
258262
}
259263

264+
/// Set flags on the program.
260265
pub fn set_flags(&mut self, flags: u32) {
261266
let rc = unsafe { libbpf_sys::bpf_program__set_flags(self.ptr.as_ptr(), flags) };
262267
debug_assert!(util::parse_ret(rc).is_ok(), "{rc}");
@@ -600,6 +605,7 @@ impl<'obj> Program<'obj> {
600605
}
601606

602607
#[deprecated = "renamed to Program::fd_from_id"]
608+
#[allow(missing_docs)]
603609
#[inline]
604610
pub fn get_fd_by_id(id: u32) -> Result<OwnedFd> {
605611
Self::fd_from_id(id)
@@ -617,6 +623,7 @@ impl<'obj> Program<'obj> {
617623

618624
// TODO: Remove once 0.25 is cut.
619625
#[deprecated = "renamed to Program::id_from_fd"]
626+
#[allow(missing_docs)]
620627
#[inline]
621628
pub fn get_id_by_fd(fd: BorrowedFd<'_>) -> Result<u32> {
622629
Self::id_from_fd(fd)

0 commit comments

Comments
 (0)