FreeBSD 13.1 Rust Kernel Programming Interface

This repository contains only bindings to the kernel!

It is unsafe, just a bindings!

It it still not tested (because structure alignment tests are now performed, see Kernel Programming Interface Test)

For the 'safe' and rust compatiable realization see Kernel Module Interface

Kernel Module Interface depends on this crate.

Variables (Features autoconfigure)

In order to build crate against the FreeBSD's kernel conf file (located in /usr/src/sys/<arch>/conf) in order to autocinfigre features

• disable default_features
• set feature BUILD_CONFIG_KERNEL
• set env variable KPI_PLATFORM_CFG_PATH

i.e

[dependencies]
freebsd-kpi-13-1 = { path = "../rsandbox_kmod", defailt_features = false, features = ["BUILD_CONFIG_KERNEL"] }

[env]
KPI_PLATFORM_CFG_PATH = "/usr/src/sys/amd64/conf/GENERIC"

If KPI_PLATFORM_CFG_PATH was not set then a deafult path /usr/src/sys/amd64/conf/GENERIC to GENERIC will be used!

Porting guide

Please refer to The Rustonomicon

Private Function

/// defined in <path to file with filename>:line number
#[repr(C)]
pub struct turnstile 
{
    _data: [u8; 0],
    _marker:
        core::marker::PhantomData<(*mut u8, core::marker::PhantomPinned)>,
}

Extern functions and variables

extern "C"
{
    #[no_mangle]
    pub 
    fn vmem_create(name: *const c_char, base: vmem_addr_t, size: vmem_size_t, 
        quantum: vmem_size_t, qcache_max: vmem_size_t, flags: c_int) -> *mut vmem_t;

    #[no_mangle]
    #[link_name = "wdog_software_attach"]
    pub static mut wdog_software_attach: Option<unsafe extern "C" fn()>;
}

Pointer to function

A function fointer like

void (*func)()

is:

Option<unsafe extern "C" fn()>

Functions

A special attributes

• C __returns_twice, Rust #[ffi_returns_twice]
• C __no_return, Rust !
• C __weak_symbol, Rust #[linkage = "extern_weak"]

Other

• volatile arguments or fields should have comment /// VOLATILE! and accessed and accessed using core::ptr::read_volatile and core::ptr::write_volatile
• C offsetof for rust there is a macros: offsetof.rs offset_of!()
• C typeof there is no alternative for the Rust.

Styles

Some guidelins on formatting and porting.

Do not use rustfmt!.

Line breaks and formatting.

Normally the length of the line should be no more than 120 chars. But it is ok up to 160.

Function fromatting:

// #[ATTRIBUTES] \n
// #[ATTRIBUTES] \n
// [FUNCTION MODIFIERS] \n
// [FUNCTION] [FUNCTION_NAME] [GENERICS][ARGUMENTS] [RETURN_DATA]\n
// [{]
//      [...]
// [}]
//
// where [ARGUMENTS] may be formatted as following:
// ([ARG], [ARG], [ARG])
// -- OR --
// (
//    [ARG],
//    [ARG]
// )
// -- OR --
// ([ARG], [ARG], [ARG],
//  [ARG], [ARG])

#[inline]
pub unsafe
fn function_name<B, C, D>(arg1: u64, arg2: u64, arg3: B, arg4: C, arg5: D) -> u64
where B: SomeTrait, C: SomeTrait, D: SomeTrait
{}

#[inline]
pub unsafe
fn function_name<B, C, D>(
    arg1: u64, 
    arg2: u64,
    arg3: B,
    arg4: C,
    arg5: D
) -> u64
where B: SomeTrait, C: SomeTrait, D: SomeTrait
{}

#[inline]
pub unsafe
fn function_name<B, C, D>(arg1: u64, arg2: u64, 
    arg3: B, arg4: C, arg5: D) -> u64
where   // optiinal \n 
    B: SomeTrait, C: SomeTrait, D: SomeTrait
{}

Const/type fromatting:

// [VISIBILITY] [CONST] [NAME][:] [DATATYPE] [=] [DATA]
// [VISIBILITY] [TYPE] [TYPE_NAME] = [TYPE]

pub const RW_VAL: u8 = 9;
const D_VAL: &[u8] = b"d_value\0";
const B_VAL: &[&[u8]] = & // \n if list if large, otherwise same line
[
    D_VAL,
    "blabla\0",
];

pub type uint32_t = u32;
pub type callback_fn = // \n if long difinition
    Option<
        unsafe extern "C"
        fn(my_var: u64) -> u64
    >;

pub type callback_fn = unsafe extern "C" fn(my_var: u64) -> u64;
pub type callback_fn = Option<unsafe extern "C" fn() -> u64>;

Assignment:

//...
let var: u64 = some_struct.read().unwrap();

let var2: Option<Arc<RefCell<MyStructLongName>>> = 
    some_s.get_instance().get_sourcer().read().unwrap();

let var3: Arc<RefCell<MyStructLongName>> =
    io_source.instance()
            .grab()
            .set_source()
            .set_name()
            .start();
//...

Structs:

//[DERIVES/MODIFIERS]
//[VISIBILITY][struct][name] \n
//[{] \n
//\t    [field][:] [data][,]
//[}]\n

#[repr(C)]
#[derive(Copy, Clone, Debug)]
pub struct StructName
{
    field: u64,
    field1: Option<Arc<Mutex<MyData>>>,
}

Match/If:

if var1 == 8
{

}
else
{

}

if var1 == 8 || var_with_long_name > 6 ||
    var_with_anothr_name > 100 ||
    var5 != 8
{

}
else if var2 < 6
{

}
else
{

}

match myvar
{
    3 => return 5,
    6 =>
    {
        something
    },
    9 => return 1,
    _ =>
}

match myvar.get_instance().foo()
    .bar().foobar()
{
    StateA0V1H3
        {
            field1: ...,
            field2: ...,
            field3: ...
        } =>
    {

    },
    StateA4N6(a,b,c,d,e) =>
    {

    },
    StateA5K3B6R3blabla =>
    {

    }
}

Security

I am trying my best to control what is pushed to this repository. No one else is allowed to commit to this repo! Mostly this crate contains structures. But sometimes '.h' files contains some static functions. A code in such functions must match with what in the originam '.h' file! Otherwise, any changes must be highlighted and a reason for changes must be in the comment sections. Also, the author of the changes must be mentioned!

Requests

Request to implement something or to fix something and ASAP are rejected.

Only if sponsored.