From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.3 (2019-12-06) on atuin.qyliss.net X-Spam-Level: X-Spam-Status: No, score=0.7 required=3.0 tests=DKIM_INVALID,DKIM_SIGNED, FORGED_SPF_HELO,FREEMAIL_FORGED_FROMDOMAIN,FREEMAIL_FROM, HEADER_FROM_DIFFERENT_DOMAINS,MAILING_LIST_MULTI,MSGID_FROM_MTA_HEADER, RCVD_IN_DNSWL_NONE,RCVD_IN_MSPIKE_H2,SPF_HELO_PASS autolearn=no autolearn_force=no version=3.4.3 Received: by atuin.qyliss.net (Postfix, from userid 496) id C95FB5728; Wed, 10 Jun 2020 18:46:20 +0000 (UTC) Received: from [127.0.0.1] (localhost [IPv6:::1]) by atuin.qyliss.net (Postfix) with ESMTP id 399D75713; Wed, 10 Jun 2020 18:46:15 +0000 (UTC) Received: by atuin.qyliss.net (Postfix, from userid 496) id BB61D5711; Wed, 10 Jun 2020 18:46:13 +0000 (UTC) Received: from NAM10-MW2-obe.outbound.protection.outlook.com (mail-mw2nam10olkn2096.outbound.protection.outlook.com [40.92.42.96]) by atuin.qyliss.net (Postfix) with ESMTPS id 5A62D570F for ; Wed, 10 Jun 2020 18:46:10 +0000 (UTC) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=lS4IL084bNOZHqUUuEzTVlOwyUWLKaNKnmUbWVSdqHyUpz5nQJmQoWLpNtXZc0H/IAV3oPVK7+kjQefswLQwU7CedCuB+AHLPgSz0eavuOV6m9cwjryF15mm/LJmo/Q3BYIP3EGmG5121zgtS+tgtvBVPT8OubFId/FbmrTo9XyyVTdepXQmDkrhMVB3iYfgzqRsnBAkzIPqwo077jAEcxf37ZPhUF1pxPkWleHBa6zS3b9A6/k4P3WdBxIeg63XehSEeEF4VefvQqw/q77NSTeTQT4YANxkNG9yafmKkLvp4rIFBWltTKMLkFRBh2EjGBilF7fLHpjYynsU3mqD2w== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=euhVQHTzSzPReAtOMsosppYVbvgBgz9AeVZ3uJKCTVg=; b=KGbse+dCFahm7tTzbWT5D9v6IT2IKWn+S/f8rkKO4NQGez3iExppcGg/w2qdAg3hGfHumEnr5wPDYkdM6gABmRwcXomV2kHqlLv9CyE3UwGTWXcW6vAg8qxK5bcOEMMnB3u4LixSPES9So2zfC1hUc0SpRrQfGO4tfdwpf4yQzZ3kkDdvT101CSi0o+CHTYI2QdvcLK39QjAVkqjURoUxejiVaVYwQEqGE4ol25VPkSBD3b1l1XWmSRwYNOeuBjRNJfp3VYQIwswXc932X7HGMPzev3uaYJtAqKvBeRn1pE8EkrEmz498YJKnk/95II4ZQczK9OMG1E7IqQ/nJnn0A== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=none; dmarc=none; dkim=none; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=outlook.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=euhVQHTzSzPReAtOMsosppYVbvgBgz9AeVZ3uJKCTVg=; b=UBSJk7dIwQuH7dsGj3mClc9OHvzmMdE9qVGOYBhEjFh9dAQwK6yRGzoY3mw9e20BCXAPtBpMu9SFMPcdrehZlmuY8ynStVxKoGo/5hHZZAzzWOxo+E+3dsIF+rVr+coOaZLh1yX79kd2rMH1sjp6JnoRQAwFwNntbsd6qnYm1UutLdvHM5Am2iMU1uJB6PK0vzXpkXPtYYIdwf2e2A0HSk9KP+iMom3/GRVzqhYXPbqXbqdsphxl8XzCFXLxjLogRN6IDkAn49Y5Qu11vp07EpYQnK/hgNHnimOqboNd+fxoGiXb3ijDGG0gGy/C8WS0xBnN4lUby3Km2OOxq7g9NQ== Received: from DM6NAM10FT025.eop-nam10.prod.protection.outlook.com (2a01:111:e400:7e86::46) by DM6NAM10HT218.eop-nam10.prod.protection.outlook.com (2a01:111:e400:7e86::316) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3088.18; Wed, 10 Jun 2020 18:46:06 +0000 Received: from BL0PR14MB3572.namprd14.prod.outlook.com (2a01:111:e400:7e86::46) by DM6NAM10FT025.mail.protection.outlook.com (2a01:111:e400:7e86::133) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3088.18 via Frontend Transport; Wed, 10 Jun 2020 18:46:06 +0000 X-IncomingTopHeaderMarker: OriginalChecksum:BFF89CAC73C9DCD33315DF528F17E9E9E4DE166AAC83F9D9148EC0D3006A36B2;UpperCasedChecksum:898D46666B94B813F6AAC15CF47C02E750F3DFDED9AB0CC71B67BE0C23308EDD;SizeAsReceived:7400;Count:47 Received: from BL0PR14MB3572.namprd14.prod.outlook.com ([fe80::696e:36dd:faa:492b]) by BL0PR14MB3572.namprd14.prod.outlook.com ([fe80::696e:36dd:faa:492b%7]) with mapi id 15.20.3088.021; Wed, 10 Jun 2020 18:46:06 +0000 From: Cole Helbling To: devel@spectrum-os.org Subject: [PATCH doc v2] Document spectrum-vm Date: Wed, 10 Jun 2020 11:44:52 -0700 Message-ID: X-Mailer: git-send-email 2.26.2 Content-Type: text/plain X-ClientProxiedBy: BYAPR05CA0041.namprd05.prod.outlook.com (2603:10b6:a03:74::18) To BL0PR14MB3572.namprd14.prod.outlook.com (2603:10b6:208:1cb::17) X-Microsoft-Original-Message-ID: <20200610184451.5505-1-cole.e.helbling@outlook.com> MIME-Version: 1.0 X-MS-Exchange-MessageSentRepresentingType: 1 Received: from localhost.localdomain (67.187.170.40) by BYAPR05CA0041.namprd05.prod.outlook.com (2603:10b6:a03:74::18) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.3109.9 via Frontend Transport; Wed, 10 Jun 2020 18:46:05 +0000 X-Mailer: git-send-email 2.26.2 X-Microsoft-Original-Message-ID: <20200610184451.5505-1-cole.e.helbling@outlook.com> X-TMN: [MfmFlxgQquhikfoUSPkt+O2XwKwE7zoi] X-MS-PublicTrafficType: Email X-IncomingHeaderCount: 47 X-EOPAttributedMessage: 0 X-MS-Office365-Filtering-Correlation-Id: 28d63d48-b8d8-449c-6f0f-08d80d6e8850 X-MS-Exchange-SLBlob-MailProps: ISIDp/2nRg0k/svScPDKHef4kEHZ4uXhxOT1uSrBEGIP3hEZjK8+/uKVHvewF1k23qupiOS7rZgkKF6ri7wEdyv/aLBVcH3VaFB/lYX+zRRdN3OqfdW9UzIYoV7IbPWlGMEWRolepHbNVe5Ito6huUpA24Pd1m52VPD07cDLjScfut2i+MDZ+8SXBn1b1Tc6Hvo9/jia1i/GRbxsCi14MYhYp+Q8LFlFjpRAEeDe3hfwbStvIs/0hBbiOpIYntHm5M/g5X5fK/TknIm++Qxpg0yM8k9QZpP2G6rCkBb2iMEAGhLiCLcp2Gk2act3I/akvzfArC9k8l3v5E6oHBp1bjL9WmIjHEGooef21mBl4Fwe9qoYEyE38DIRjUE4pBMzb/ZAmlmyf7lm0Xwh12uDHOGNYMV/TrEfgT4LcmgG569Dx5zWS0rekiCdwy8nSz3vQ9Ic1fnL9SrovKX/amcYK7aGumGETAJJFXnfK4JV9/CTtjf4IvpO6WtU+mR61hNkpUAWLU2IXqMkqWI+LqCvQlVB6lKe2ABSX2rJLUuVsdglqzOPDm8zEh4d7/paOy6QzUMix17RkEtjZCRuCBZmYkMzHDAdrDYNLHL7JoZn3XwOnX/OAojxY/g6g/btzotKmCow0NwJLcmX5jbrAdGT1GGIyhuP2pmgMNIUlzS13VI9G5LijrDFLZFmCbB3k1XpkbU4JJKxqsA5ytU/ILFoyjtB8o87ESSznjD8APQ3FufJUpbFsGJjyfKqEeBW1XGd4mXcBz42dROmPgL9MGXgdwBNkKZyCGd3oIDXazvY2JKc9ERDUZ89lGt2xxOf+8lh7dzypL4T3PBM8s2JeKDAuLL8pi4KbE979emkg050Gc35sJJygIpOHQOBWxseIKtA2yUFFN7H9/E= X-MS-TrafficTypeDiagnostic: DM6NAM10HT218: X-Microsoft-Antispam: BCL:0; X-Microsoft-Antispam-Message-Info: AoTLxzM4dRTHEzqA2i6+SPG76AIStc0NLdLUSM3k1U/8pcrlAggNjXcbfDa/bvq+EzdSvuCslu0CPAGrzlXUiwij5bbxced+/s63guPoP1mdkIJe/OUiihIC/GUK3+IgHZkxuGuKEpxHNY54qXIWZqFExGyW2b5KLPnnpzdKpBiXGKlajnrMZONP0MtLmR0QH/8AEm+qWXeevNB8wzNEqRfWGIHFz9Re+O5NiOKLpoBRAl9LNgLew4Er+YSFOmOx X-Forefront-Antispam-Report: CIP:255.255.255.255;CTRY:;LANG:en;SCL:0;SRV:;IPV:NLI;SFV:NSPM;H:BL0PR14MB3572.namprd14.prod.outlook.com;PTR:;CAT:NONE;SFTY:;SFS:;DIR:OUT;SFP:1901; X-MS-Exchange-AntiSpam-MessageData: cr9Lcg4vJQkEJZZh/YjtsX+vNPo9Crtd8Ae7Gbb8a48RRczoe/idQLixdnRF2AZTfe9YLVGsMHVn0yytCdbVrLg/mkF0/YhuwXJMZQtYV9QU9KyWjcB8FuMHHvNOn7CADG8Ata9NNdSwygr5v9jZIQ== X-OriginatorOrg: outlook.com X-MS-Exchange-CrossTenant-Network-Message-Id: 28d63d48-b8d8-449c-6f0f-08d80d6e8850 X-MS-Exchange-CrossTenant-OriginalArrivalTime: 10 Jun 2020 18:46:05.9870 (UTC) X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted X-MS-Exchange-CrossTenant-Id: 84df9e7f-e9f6-40af-b435-aaaaaaaaaaaa X-MS-Exchange-CrossTenant-FromEntityHeader: Internet X-MS-Exchange-CrossTenant-RMS-PersistedConsumerOrg: 00000000-0000-0000-0000-000000000000 X-MS-Exchange-Transport-CrossTenantHeadersStamped: DM6NAM10HT218 Content-Transfer-Encoding: quoted-printable Message-ID-Hash: S5ZT4ZYLQ2M7HWGNPNTDSFWCGZ7LEDGX X-Message-ID-Hash: S5ZT4ZYLQ2M7HWGNPNTDSFWCGZ7LEDGX X-MailFrom: cole.e.helbling@outlook.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header CC: Cole Helbling X-Mailman-Version: 3.3.1 Precedence: list List-Id: Patches and low-level development discussion Archived-At: List-Archive: List-Help: List-Post: List-Subscribe: List-Unsubscribe: spectrum-vm is a handy way to start a crosvm instance for testing crosvm itself, the kernel, or the rootfs. This commit adds some fledgling documentation on its functionality and usage. --- Takes into account review suggestions and tweaks a bit of wording here and there. Specifically, I clarified that rootfs means the root filesystem, added an aside that the serial console can be used to run privileged commands, dropped the full `spectrum-vm --help` text, and moved and reformatted the usage examples. developer-manual.adoc | 53 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/developer-manual.adoc b/developer-manual.adoc index b7eb2cb..a98330f 100644 --- a/developer-manual.adoc +++ b/developer-manual.adoc @@ -106,6 +106,59 @@ the https://spectrum-os.org/doc/crosvm/crosvm/[crosv= m documentation] for the version currently used by Spectrum is hosted on the Spectrum website. =20 +=3D=3D=3D=3D spectrum-vm + +`spectrum-vm` is a shell script that allows for testing various Spectrum +VM components, including crosvm, the kernel, and the root filesystem +("rootfs" for short). The simplest way to use this tool is by running +`nix-shell -I nixpkgs=3D/path/to/nixpkgs-spectrum -p +spectrumPackages.spectrum-vm --run spectrum-vm` in a terminal, which +will start up an instance of crosvm from Nixpkgs running Wayfire in a +new window. + +**** +Be advised that Wayfire's default keymap is set to Dvorak +https://spectrum-os.org/git/nixpkgs/tree/pkgs/os-specific/linux/spectrum= /rootfs/default.nix[inside +of the rootfs] -- to change this to your preferred keymap, just set the +`xkb_layout` option (or remove it altogether for a default of QWERTY). +**** + +Once you are ready to end your crosvm session, switch back to where you +ran `spectrum-vm` and type `reboot` (not `poweroff`). This window is not +limited to just stopping the VM, however; it is a functional serial +console where you can even run commands like `env` and `cat +/etc/passwd`. + +**** +Although it is currently not possible to execute commands as root inside +the graphical environment, one can instead use the serial console to run +privileged commands. +**** + +=3D=3D=3D=3D=3D Examples + +As mentioned above, `spectrum-vm` also supports options that allow you +to specify custom components or run arbitrary commands before exiting: + +---- +nix-shell -I nixpkgs=3D/path/to/nixpkgs-spectrum -p spectrumPackages.spe= ctrum-vm + +# display the currently supported options for spectrum-vm +nix-shell$ spectrum-vm --help + +# run a command that will print out the VM's PATH to the serial terminal= and exit +nix-shell$ spectrum-vm -c 'echo $PATH' + +# use the specified crosvm and disable sandboxing +nix-shell$ spectrum-vm -C target/debug/crosvm -- --disable-sandbox + +# use the specified kernel image +nix-shell$ spectrum-vm -k result/bzImage + +# use the specified squashfs as the root filesystem image +nix-shell$ spectrum-vm -f squashfs +---- + =3D=3D=3D=3D Hacking on crosvm =20 There are a few ways to get a crosvm development environment. You can --=20 2.26.2