{"id":19061991,"url":"https://github.com/mdevctl/mdevctl","last_synced_at":"2025-04-18T01:31:57.973Z","repository":{"id":37791656,"uuid":"188761578","full_name":"mdevctl/mdevctl","owner":"mdevctl","description":"A mediated device management and persistence utility","archived":false,"fork":false,"pushed_at":"2024-09-17T13:25:32.000Z","size":385,"stargazers_count":59,"open_issues_count":5,"forks_count":17,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-10-31T11:35:00.211Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-2.1","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mdevctl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-27T02:59:58.000Z","updated_at":"2024-10-11T22:19:18.000Z","dependencies_parsed_at":"2024-04-17T15:43:21.797Z","dependency_job_id":null,"html_url":"https://github.com/mdevctl/mdevctl","commit_stats":{"total_commits":237,"total_committers":12,"mean_commits":19.75,"dds":"0.35443037974683544","last_synced_commit":"60e377742996d8406804f48b29311f34406a7abf"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdevctl%2Fmdevctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdevctl%2Fmdevctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdevctl%2Fmdevctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mdevctl%2Fmdevctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mdevctl","download_url":"https://codeload.github.com/mdevctl/mdevctl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223770458,"owners_count":17199686,"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":[],"created_at":"2024-11-09T00:23:59.478Z","updated_at":"2024-11-09T00:24:06.518Z","avatar_url":"https://github.com/mdevctl.png","language":"Rust","funding_links":[],"categories":["systemd-udev"],"sub_categories":[],"readme":"# mdevctl - a mediated device management utility for Linux\n\n## Description\n\nmdevctl is a utility for managing and persisting devices in the\nmediated device device framework of the Linux kernel.  Mediated\ndevices are sub-devices of a parent device (ex. a vGPU) which\ncan be dynamically created and potentially used by drivers like\nvfio-mdev for assignment to virtual machines.\n\n## License\n\nLicensed under the GNU Lesser General Public License aka LGPL v2.1.\nSee [COPYING](COPYING) for details.\n\n## Source repository\n\nhttps://github.com/mdevctl/mdevctl\n\n## Installation\n\nmdevctl is built with rust's `cargo` tool.  To build the executable, run `cargo\nbuild`. This will compile the code and also generate a Makefile that can be\nused for installing the executable and all support files into your system.  On\nRPM based systems, you can run `make rpm` then install the resulting package.\nOtherwise, run `make install`.\n\n## Architecture\n\nmdevctl stores defined mediated devices in /etc/mdevctl.d/ with\ndirectories matching the parent device name and config files named\nby the UUID of the mdev device itself.  The format used is JSON; a\nconfiguration file for an mdev device looks like follows:\n\n```\n  {\n   \"mdev_type\": \"$VENDOR_TYPE\",\n   \"start\": \"auto|manual\",\n   \"attrs\": [\n    ...optional list of device-specific attributes...\n   ]\n  }\n```\n\nWhen a known parent device add udev event occurs (or, for more recent\nkernels, change events with MDEV_STATE values), mdevctl is called by\na udev rule to create defined devices with \"start\": \"auto\" configured.\n\nmdevctl defines three classes of commands, those that manage device\nconfig files, those that manage the device itself, and listing\ncommands for showing defined, active, or potential mdev devices.\n\nStarting with the latter, mdevctl is able to manage mdev devices\ncreated either with mdevctl or externally, such as through direct\nsysfs interactions.  Likewise, when generating a list of currently\nactive mdev devices via the `list` command, all mdevs are included.\nWhen provided with the `--defined` option, the list command will show\nmdev device configs defined on the system, regardless of whether they\nare currently active.  The `types` command provides details of the\nmdev types supported on the system, including the number of\ninstances of each that may be created, the API exposed for each, as\nwell as vendor provided name and description as available.\n\nMediated device definitions can be created with the `define` command,\nwhich not only accepts a fully specified configuration via options,\nbut can also create a config for a currently running mdev.  Thus a\ntransient device created either through mdevctl or sysfs can be\npromoted to a defined device.  The `undefine` command simply removes\nthe config definition without modifying the running device, while\nthe `modify` command allows device config to be modified.  Config\nmodifications to a running device to not take effect until the device\nis stopped and restarted.\n\nThis leads to the final class of commands, which provides the `start`\nand `stop` functionality.  The start command can operate either on\na previously defined mdev or the mdev can be fully specified via\noptions to create a transient device, ie. a running device with no\npersistence.\n\n# Usage\n\nList running mdev devices:\n\n```\n# mdevctl list\n85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTg_V4_4\n83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 (defined)\n```\n\nList defined mdev devices:\n\n```\n# mdevctl list -d\n83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 auto\nb0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto\n5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual\n```\n\nList mdev types supported on the host system:\n\n```\n# mdevctl types\n0000:00:02.0\n  i915-GVTg_V4_2\n    Available instances: 1\n    Device API: vfio-pci\n    Description: low_gm_size: 256MB high_gm_size: 1024MB fence: 4 resolution: 1920x1200 weight: 8 \n  i915-GVTg_V4_1\n    Available instances: 0\n    Device API: vfio-pci\n    Description: low_gm_size: 512MB high_gm_size: 2048MB fence: 4 resolution: 1920x1200 weight: 16 \n  i915-GVTg_V4_8\n    Available instances: 4\n    Device API: vfio-pci\n    Description: low_gm_size: 64MB high_gm_size: 384MB fence: 4 resolution: 1024x768 weight: 2 \n  i915-GVTg_V4_4\n    Available instances: 3\n    Device API: vfio-pci\n    Description: low_gm_size: 128MB high_gm_size: 512MB fence: 4 resolution: 1920x1200 weight: 4 \n```\n\nModify a defined device from automatic start to manual:\n\n```\n# mdevctl modify --uuid 83c32df7-d52e-4ec1-9668-1f3c7e4df107 --manual\n# mdevctl list -d\n83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 manual\nb0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto\n5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual\n```\n\nStop a running mdev device:\n\n```\n# mdevctl stop -u 83c32df7-d52e-4ec1-9668-1f3c7e4df107\n```\n\nStart an mdev device that is not defined\n\n```\n# uuidgen\n6eba5b41-176e-40db-b93e-7f18e04e0b93\n# mdevctl start -u 6eba5b41-176e-40db-b93e-7f18e04e0b93 -p 0000:00:02.0 --type i915-GVTg_V4_1\n# mdevctl list\n85006552-1b4b-45ef-ad62-de05be9171df 0000:00:02.0 i915-GVTg_V4_4\n6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTg_V4_1\n```\n\nPromote the new created mdev to a defined device:\n\n```\n# mdevctl define --uuid 6eba5b41-176e-40db-b93e-7f18e04e0b93\n# mdevctl list -d\n83c32df7-d52e-4ec1-9668-1f3c7e4df107 0000:00:02.0 i915-GVTg_V4_8 manual\n6eba5b41-176e-40db-b93e-7f18e04e0b93 0000:00:02.0 i915-GVTg_V4_1 manual\nb0a3989f-8138-4d49-b63a-59db28ec8b48 0000:00:02.0 i915-GVTg_V4_8 auto\n5cf14a12-a437-4c82-a13f-70e945782d7b 0000:00:02.0 i915-GVTg_V4_4 manual\n```\n\n## Advanced usage (attributes and JSON)\n\nmdevctl provides support for specifying additional configuration via\ndevice-specific attributes. It also provides support for inspecting\nand modifying its internal JSON representation of the configuration\ndirectly.\n\nExample:\n\n```\n# mdevctl list -d\n783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual\n```\n\nAdd some attributes:\n\n```\n# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_adapter --value=5\n# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_adapter --value=6\n# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_domain --value=0xab\n# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_control_domain --value=0xab\n# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_domain --value=4\n# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --addattr=assign_control_domain --value=4\n# mdevctl list -dv\n783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual\n  Attrs:\n    @{0}: {\"assign_adapter\":\"5\"}\n    @{1}: {\"assign_adapter\":\"6\"}\n    @{2}: {\"assign_domain\":\"0xab\"}\n    @{3}: {\"assign_control_domain\":\"0xab\"}\n    @{4}: {\"assign_domain\":\"4\"}\n    @{5}: {\"assign_control_domain\":\"4\"}\n```\n\nDump the JSON configuration:\n\n```\n# mdevctl list -d -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --dumpjson\n{\n  \"mdev_type\": \"vfio_ap-passthrough\",\n  \"start\": \"manual\",\n  \"attrs\": [\n    {\n      \"assign_adapter\": \"5\"\n    },\n    {\n      \"assign_adapter\": \"6\"\n    },\n    {\n      \"assign_domain\": \"0xab\"\n    },\n    {\n      \"assign_control_domain\": \"0xab\"\n    },\n    {\n      \"assign_domain\": \"4\"\n    },\n    {\n      \"assign_control_domain\": \"4\"\n    }\n  ]\n}\n```\n\nRemove some attributes:\n\n```\n# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --delattr --index=5\n# mdevctl modify -u 783e6dbb-ea0e-411f-94e2-717eaad438bf --delattr --index=4\n# mdevctl list -dv\n783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual\n  Attrs:\n    @{0}: {\"assign_adapter\":\"5\"}\n    @{1}: {\"assign_adapter\":\"6\"}\n    @{2}: {\"assign_domain\":\"0xab\"}\n    @{3}: {\"assign_control_domain\":\"0xab\"}\n```\n\nDefine an mdev device from a file:\n\n```\n# cat vfio_ap_device.json\n{\n  \"mdev_type\": \"vfio_ap-passthrough\",\n  \"start\": \"manual\",\n  \"attrs\": [\n    {\n      \"assign_adapter\": \"5\"\n    },\n    {\n      \"assign_domain\": \"0x47\"\n    },\n    {\n      \"assign_domain\": \"0xff\"\n    }\n  ]\n}\n# mdevctl define -p matrix --jsonfile vfio_ap_device.json\ne2e73122-cc39-40ee-89eb-b0a47d334cae\n# mdevctl list -dv\n783e6dbb-ea0e-411f-94e2-717eaad438bf matrix vfio_ap-passthrough manual\n  Attrs:\n    @{0}: {\"assign_adapter\":\"5\"}\n    @{1}: {\"assign_adapter\":\"6\"}\n    @{2}: {\"assign_domain\":\"0xab\"}\n    @{3}: {\"assign_control_domain\":\"0xab\"}\ne2e73122-cc39-40ee-89eb-b0a47d334cae matrix vfio_ap-passthrough manual\n  Attrs:\n    @{0}: {\"assign_adapter\":\"5\"}\n    @{1}: {\"assign_domain\":\"0x47\"}\n    @{2}: {\"assign_domain\":\"0xff\"}\n```\n\nSee `mdevctl --help` or the manpage for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdevctl%2Fmdevctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmdevctl%2Fmdevctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdevctl%2Fmdevctl/lists"}