Skip to content

Commit

Permalink
Docs: Fixing broken documentation links.
Browse files Browse the repository at this point in the history
Utilizing `cargo-rdme` as an alternative to `cargo readme` to fix the
broken links between github and crates.io.

Resolves: virtee#169

Signed-off-by: Larry Dewey <larry.dewey@amd.com>
  • Loading branch information
larrydewey committed Apr 12, 2024
1 parent def1174 commit b9d6fae
Show file tree
Hide file tree
Showing 11 changed files with 42 additions and 48 deletions.
7 changes: 4 additions & 3 deletions .github/workflows/lint.yml
Original file line number Diff line number Diff line change
Expand Up @@ -35,15 +35,16 @@ jobs:
- run: cargo clippy --features=crypto_nossl,hw_tests,dangerous_hw_tests --all-targets -- -D clippy::all -D unused_imports -D warnings

readme:
name: cargo readme
name: cargo rdme
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
with:
toolchain: nightly
- run: cargo install cargo-readme
- run: cargo readme > README.md && git diff --exit-code
- run: |
cargo install cargo-rdme
cargo rdme --check
check-spdx-headers:
runs-on: ubuntu-latest
Expand Down
46 changes: 19 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,4 @@
[![Workflow Status](https://github.com/virtee/sev/workflows/test/badge.svg)](https://github.com/virtee/sev/actions?query=workflow%3A%22test%22)
[![Average time to resolve an issue](https://isitmaintained.com/badge/resolution/virtee/sev.svg)](https://isitmaintained.com/project/virtee/sev "Average time to resolve an issue")
[![Percentage of issues still open](https://isitmaintained.com/badge/open/virtee/sev.svg)](https://isitmaintained.com/project/virtee/sev "Percentage of issues still open")
![Maintenance](https://img.shields.io/badge/maintenance-activly--developed-brightgreen.svg)

# sev
<!-- cargo-rdme start -->

The `sev` crate provides an implementation of the [AMD Secure Encrypted
Virtualization (SEV)][SEV] APIs and the [SEV Secure Nested Paging
Expand All @@ -12,7 +7,7 @@ Firmware (SNP)][SNP] ABIs.
[SEV]: https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/programmer-references/55766_SEV-KM_API_Specification.pdf
[SNP]: https://www.amd.com/content/dam/amd/en/documents/epyc-technical-docs/specifications/56860.pdf

### SEV APIs
## SEV APIs

The linux kernel exposes two technically distinct AMD SEV APIs:

Expand All @@ -22,7 +17,7 @@ The linux kernel exposes two technically distinct AMD SEV APIs:
This crate implements both of those APIs and offers them to client.
code through a flexible and type-safe high-level interface.

### SNP ABIs
## SNP ABIs

Like SEV, the linux kernel exposes another two different AMD SEV-SNP ABIs:

Expand All @@ -33,27 +28,27 @@ These new ABIs work only for **SEV-SNP** enabled hosts and guests.

This crate implements APIs for both SEV and SEV-SNP management.

### SEV and SEV-SNP enablement
## SEV and SEV-SNP enablement

By default, both the SEV and SEV-SNP libraries are compiled.
Because many modules provide support to both legacy SEV and SEV-SNP, they have been split into individual sub-modules `sev.rs` and `snp.rs`, isolating generation specific behavior.
If desired, you may opt to exclude either of the sub-modules by disabling its feature in your project's `Cargo.toml`

For example, to include the SEV APIs only:
`sev = { version = "1.2.1", default-features = false, features = ["sev"] }`
If desired, you may opt to exclude either of the sub-modules by disabling its feature in your project's `Cargo.toml`

To include the SEV-SNP APIs only:
`sev = { version = "1.2.1", default-features = false, features = ["snp"] }`
For example, to include the SEV APIs only:
`sev = { version = "1.2.1", default-features = false, features = ["sev"] }`

To include the SEV-SNP APIs only:
`sev = { version = "1.2.1", default-features = false, features = ["snp"] }`

### Platform Management
## Platform Management

Refer to the [`firmware`] module for more information.
Refer to the [firmware] module for more information.

### Guest Management
## Guest Management

Refer to the [`launch`] module for more information.
Refer to the [launch] module for more information.

### Cryptographic Verification
## Cryptographic Verification

To enable the cryptographic verification of certificate chains and
attestation reports, either the `openssl` or `crypto_nossl` feature
Expand All @@ -63,7 +58,7 @@ verification and instead pure-Rust libraries (e.g., `p384`, `rsa`,
etc.) are used. `openssl` and `crypto_nossl` are mutually exclusive,
and enabling both at the same time leads to a compiler error.

### Remarks
## Remarks

Note that the linux kernel provides access to these APIs through a set
of `ioctl`s that are meant to be called on device nodes (`/dev/kvm` and
Expand All @@ -72,16 +67,13 @@ of the `sev` crate. Binaries that result from consumers of this crate are
expected to run as a process with the necessary privileges to interact
with the device nodes.

### Using the C API
## Using the C API

Projects in C can take advantage of the C API for the SEV [`launch`] ioctls.
Projects in C can take advantage of the C API for the SEV [launch] ioctls.
To install the C API, users can use `cargo-c` with the features they would
like to produce and install a `pkg-config` file, a static library, a dynamic
library, and a C header:

`cargo cinstall --prefix=/usr --libdir=/usr/lib64`

[`firmware`]: ./src/firmware/
[`launch`]: ./src/launch/

License: Apache-2.0
<!-- cargo-rdme end -->
2 changes: 2 additions & 0 deletions build.sh
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
# SPDX-License-Identifier: Apache-2.0

#!/bin/sh
set -e

Expand Down
2 changes: 2 additions & 0 deletions src/cargo-build.sh
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
# SPDX-License-Identifier: Apache-2.0

#!/bin/bash
set -e

Expand Down
4 changes: 2 additions & 2 deletions src/error.rs
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ pub enum VmmError {
impl error::Error for VmmError {}

impl From<u32> for VmmError {
/// Takes a raw u32 and translates it into the correlated [`VmmError`]
/// Takes a raw u32 and translates it into the correlated [VmmError](self::VmmError)
/// type.
///
/// * value - The raw u32 value which we would like to interpret.
Expand All @@ -82,7 +82,7 @@ impl From<u32> for VmmError {
}

impl From<u64> for VmmError {
/// Takes a raw u64 and translates it into the correlated [`VmmError`]
/// Takes a raw u64 and translates it into the correlated [VmmError](self::VmmError)
/// type.
///
/// * value - The raw u64 value which we would like to interpret.
Expand Down
6 changes: 3 additions & 3 deletions src/firmware/guest/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ use std::fs::{File, OpenOptions};

// Disabled until upstream Linux kernel is patched.
//
// /// Checks the `fw_err` field on the [`GuestRequest`] structure
// /// Checks the `fw_err` field on the [GuestRequest](crate::firmware::linux::guest::ioctl::GuestRequest) structure
// /// to make sure that no errors were encountered by the VMM or the AMD
// /// Secure Processor.
// fn check_fw_err(raw_error: RawFwError) -> Result<(), UserApiError> {
Expand Down Expand Up @@ -116,7 +116,7 @@ impl Firmware {
/// Request an extended attestation report from the AMD Secure Processor.
/// The `message_version` will default to `1` if `None` is specified.
///
/// Behaves the same as [`get_report`](crate::firmware::guest::Firmware::get_report).
/// Behaves the same as [get_report](crate::firmware::guest::Firmware::get_report).
pub fn get_ext_report(
&mut self,
message_version: Option<u8>,
Expand All @@ -137,7 +137,7 @@ impl Firmware {

// Construct the object needed to perform the IOCTL request.
// *NOTE:* This is __important__ because a fw_err value which matches
// [`INVALID_CERT_BUFFER`] will indicate the buffer was not large
// [InvalidCertificatePageLength](crate::error::VmmError::InvalidCertificatePageLength) will indicate the buffer was not large
// enough.
let mut guest_request: GuestRequest<ExtReportReq, ReportRsp> = GuestRequest::new(
message_version,
Expand Down
2 changes: 1 addition & 1 deletion src/firmware/guest/types/snp.rs
Original file line number Diff line number Diff line change
Expand Up @@ -144,7 +144,7 @@ pub struct AttestationReport {
/// Information about the platform. See PlatformInfo
pub plat_info: PlatformInfo,
/// Private variable as only the first bit is important.
/// See [`AttestationReport::_author_key_en`].
/// See [author_key_en()](self::AttestationReport::author_key_en).
_author_key_en: u32,
_reserved_0: u32,
#[serde(with = "BigArray")]
Expand Down
4 changes: 2 additions & 2 deletions src/firmware/host/types/snp.rs
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: Apache-2.0

/// A representation of the type of data provided to [`parse_table`](crate::firmware::host::parse_table)
/// A representation of the type of data provided to [parse_table](crate::firmware::host::parse_table)
pub use crate::firmware::linux::host::types::RawData;

pub(crate) use crate::firmware::linux::host as FFI;
Expand Down Expand Up @@ -37,7 +37,7 @@ bitflags::bitflags! {

#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
#[repr(C)]
/// Certificates which are accepted for [`CertTableEntry`](self::CertTableEntry)
/// Certificates which are accepted for [CertTableEntry](self::CertTableEntry)
pub enum CertType {
/// Empty or closing entry for the CertTable
Empty,
Expand Down
6 changes: 3 additions & 3 deletions src/firmware/linux/guest/types.rs
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ pub struct DerivedKeyRsp {

reserved_0: [u8; 28],

/// The requested derived key if [`DerivedKeyRsp::status`] is 0h.
/// The requested derived key if [DerivedKeyRsp::status](self::DerivedKeyRsp::status) is 0h.
pub key: [u8; 32],
}

Expand All @@ -82,7 +82,7 @@ pub struct DerivedKeyRsp {
#[repr(C)]
#[derive(Clone, Copy, Default)]
pub struct ExtReportReq {
/// Address of the [`ReportReq`].
/// The [ReportReq](self::ReportReq).
pub data: ReportReq,

/// Starting address of the certificate data buffer.
Expand Down Expand Up @@ -131,7 +131,7 @@ impl Default for ReportReq {
}

impl ReportReq {
/// Instantiates a new [`ReportReq`] for fetching an [`AttestationReport`] from the PSP.
/// Instantiates a new [ReportReq](self::ReportReq) for fetching an [AttestationReport](crate::firmware::guest::types::snp::AttestationReport) from the PSP.
///
/// # Arguments
///
Expand Down
2 changes: 1 addition & 1 deletion src/firmware/linux/host/types/snp.rs
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ pub struct CertTableEntry {
impl CertTableEntry {
/// Builds a Kernel formatted CertTable for sending the certificate content to the PSP.
///
/// Users should pass the rust-friendly vector of [`UAPI::CertTableEntry`], and this function
/// Users should pass the rust-friendly vector of [UAPI::CertTableEntry](crate::firmware::host::types::snp::CertTableEntry), and this function
/// will handle adding the last entry and the structuring of the buffer sent to the hypervisor.
///
/// The contiguous memory layout should look similar to this:
Expand Down
9 changes: 3 additions & 6 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,11 @@
//!
//! ## Platform Management
//!
//! Refer to the [`firmware`] module for more information.
//! Refer to the [firmware] module for more information.
//!
//! ## Guest Management
//!
//! Refer to the [`launch`] module for more information.
//! Refer to the [launch] module for more information.
//!
//! ## Cryptographic Verification
//!
Expand All @@ -69,15 +69,12 @@
//!
//! ## Using the C API
//!
//! Projects in C can take advantage of the C API for the SEV [`launch`] ioctls.
//! Projects in C can take advantage of the C API for the SEV [launch] ioctls.
//! To install the C API, users can use `cargo-c` with the features they would
//! like to produce and install a `pkg-config` file, a static library, a dynamic
//! library, and a C header:
//!
//! `cargo cinstall --prefix=/usr --libdir=/usr/lib64`
//!
//! [`firmware`]: ./src/firmware/
//! [`launch`]: ./src/launch/
#![deny(clippy::all)]
#![deny(missing_docs)]
Expand Down

0 comments on commit b9d6fae

Please sign in to comment.