{"id":13423237,"url":"https://github.com/auxoncorp/ferros","last_synced_at":"2026-02-14T01:12:34.650Z","repository":{"id":37212496,"uuid":"164517349","full_name":"auxoncorp/ferros","owner":"auxoncorp","description":"A Rust-based userland which also adds compile-time assurances to seL4 development.","archived":false,"fork":false,"pushed_at":"2023-07-25T23:12:11.000Z","size":2411,"stargazers_count":107,"open_issues_count":26,"forks_count":11,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-10-26T22:17:26.034Z","etag":null,"topics":["rust","sel4","userland"],"latest_commit_sha":null,"homepage":"https://ferros.auxon.io/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/auxoncorp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-01-08T00:03:28.000Z","updated_at":"2024-10-21T06:53:39.000Z","dependencies_parsed_at":"2024-01-06T20:54:33.491Z","dependency_job_id":null,"html_url":"https://github.com/auxoncorp/ferros","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auxoncorp%2Fferros","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auxoncorp%2Fferros/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auxoncorp%2Fferros/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/auxoncorp%2Fferros/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/auxoncorp","download_url":"https://codeload.github.com/auxoncorp/ferros/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243750466,"owners_count":20342065,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["rust","sel4","userland"],"created_at":"2024-07-31T00:00:25.714Z","updated_at":"2026-02-14T01:12:34.608Z","avatar_url":"https://github.com/auxoncorp.png","language":"Rust","funding_links":[],"categories":["Tools"],"sub_categories":["Community Chat Rooms","Paid and commercially available materials"],"readme":"# ferros\n\n## Overview\n\nA Rust library to add extra assurances to seL4 development.\n\n`ferros` provides smart type-safe wrappers around seL4 features\nwith an emphasis on compile-time resource tracking.\n\n`ferros` builds on top of the `selfe-sys` library.\n\n## Build\n\nInstall `cargo-xbuild` then run `cargo xbuild --target\narmv7-unknown-linux-gnueabihf` from the root project directory.\n\nIntegration test execution is as simple as `cd qemu-test \u0026\u0026 cargo test` and\nrequires the installation of `qemu-system-arm`.\n\n## Usage\n\nAdd `ferros` as a cargo dependency. \n\n```\n[dependencies]\nferros = { git = \"https://github.com/auxoncorp/ferros\" }\n```\n\n## Quick Start\n\nThe following code walkthrough assumes execution selfe with the example sel4_start library,\nand introduces some aspects of `ferros`.\n\n```rust\nuse selfe_sys;\nuse ferros::alloc::{self, micro_alloc, smart_alloc};\nuse ferros::userland::{root_cnode, BootInfo};\n\n// The raw boot info is provided by the sel4_start library\nlet raw_boot_info: \u0026'static selfe_sys::seL4_BootInfo = unsafe { \u0026*selfe_start::BOOTINFO };\n\n\n// Utility for finding and claiming `Untyped` instances supplied by the boot info.\nlet mut allocator = micro_alloc::Allocator::bootstrap(\u0026raw_boot_info)?;\nlet initial_untyped = allocator\n    .get_untyped::\u003cU20\u003e() // The size of the Untyped instance, as bits\n    .expect(\"Couldn't find an untyped instance of the desired size\");\n\n// Create the top-level CNode wrapper with type-level-tracked remaining slot capacity\nlet (root_cnode, local_slots) = root_cnode(\u0026raw_boot_info);\n\n// Once we have an initial Untyped instance, memory distribution from it\n// can be tracked with compile-time checks. The smart_alloc macro synthesizes\n// the allocation code, and the capacity bounds are statically verified by\n// the type checker. The effect is that you can write 'slots' in the macro body \n// anywhere you need some slots, and you'll get the right number allocated\n// with type inference. A reference to 'ut' does the same for untyped memory. \nsmart_alloc!(|slots from local_slots, ut from uts| {\n\n    // Create a page table seL4 kernel object and return a capability pointer to it.\n    // Here we use a variable binding type annotation and Rust's type system can figure out\n    // if it can allocate a large enough Untyped instance and enough cnode slots\n    // to represent this particular kernel object.\n    let example_page_table: LocalCap\u003cUnmappedPageTable\u003e = retype(ut, slots)?;\n\n    // Create a resource-tracking wrapper around the raw boot info to assist in\n    // virtual memory related operations.\n    let boot_info  = BootInfo::wrap(raw_boot_info, ut, slots);\n    let (root_page_table, boot_info) = boot_info.map_page_table(root_page_table)?;\n});\n```\n\n## Features\n\n### Context-Aware Automatic Capability Management\n\nCapabilities are the mechanism by which seL4 applications manage their\naccess to useful kernel objects, like notifications, endpoints, and pages.\n\nCapabilities are stored in specialized collections of capability-holding-capacity,\ncalled CNodes. In basic seL4 development, knowledge of a complex addressing scheme\n(CPointers) is required to generate and manipulate capabilities. In C seL4 development there\nare few guard-rails against misinterpreting what type of kernel object is referenced\nby a CPointer, let alone whether that CPointer is even valid in the current execution\ncontext.\n\n`ferros` solves these problems by tracking capabilities with a smart pointer type, `Cap`.\n\n`Cap` pointers are parameterized at the type level by the kernel object kind they point at,\nas well as by whether the pointer is valid in the local execution context (or in the context\nof a child process); e.g. `Cap\u003cEndpoint, Local\u003e` , `Cap\u003cNotification, Child\u003e`\n\nThe `ferros` APIs\n\n\n### Compile Time Resource Management\n\nseL4 offers several resources worth tracking -- available free slots in a `CNode`, raw memory\nin `Untyped` instances, the portions of virtual memory space yet unclaimed, and so\nforth. `ferros` tracks these resources at compile time.\n\n`CNode`s have a self-explanatory `FreeSlots` type parameter, `Untyped`s have a `BitSize` type parameter\nthat shows how many bits of memory they could store, and `VSpace`'s `PageDirFreeSlots`\nand `PageTableFreeSlots` params collaborate to show which portions of virtual address space\nhave yet to be claimed or mapped.\n\nWhenever a function needs to take some subset of resources from these objects,\nthe function consumes the object as a whole and returns an instance of that object\nwith the necessary type parameters decremented to track the resources expended. If a resource\ncontainer's contents aren't sufficient to a given task at hand, the developer will experience\na compile time failure (as opposed to a runtime one).\n\nFollowing initialization the `ferros` framework renders accidental resource exhaustion in production deployment impossible\nby making correct usage mandatory during design and development.\n\n### Isolation and Communication\n\nAtop the basic building blocks of capability creation and storage, `ferros` provides higher-level\nprimitives for creating fully isolated subprocesses (see `vspace.rs`) as well as several\noptions for well-typed synchronous and asynchronous communication between processes\n(see `multi_consumer.rs`, `ipc.rs`, and `shared_memory_ipc.rs`).\n\n## License\n\nSee [LICENSE](./LICENSE) for more details.\n\nCopyright 2021 [Auxon Corporation](https://auxon.io)\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n[http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauxoncorp%2Fferros","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fauxoncorp%2Fferros","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fauxoncorp%2Fferros/lists"}