Crate arm_ffa

Crate arm_ffa 

Source
Expand description

§Arm Firmware Framework for Arm A-profile (FF-A) support library

Arm Firmware Framework for Arm A-profile (FF-A) specification

FF-A Memory Management Protocol specification

Library for handling common FF-A related functionality, create and parse interfaces and descriptors defined by FF-A. Starting from FF-A v1.2 the memory management related parts of the specification have been moved to a separate document (link above).

§Design goals

  • Keep the code exception level agnostic by default. If exception level specific parts are inevitable, make it optional via a feature flag.
  • Keep the code no_std compatible. Use only core by default, make parts using alloc optional via a feature flag.
  • The interface towards the library’s users should be ergonomic Rust and following Rust best-practices where possible.
    • Incorrect usage of this library when creating/packing/serializing data structures provided by this library is seen as a programmer error and the library will panic.
    • Parsing/unpacking/deserializing data structures provided by this library from a buffer is seen as runtime “user input data”, and the library should make all necessary checks to validate the data. In this case the library should never panic, but return rich error types (preferably use thiserror) so the library user knows what’s wrong.
  • The FF-A descriptors, packed structs and bit shifting magic should be private for the library, never exposed to the library user (i.e. ffa_v1_1 and later modules).
    • The implementation of such data structures should strictly follow the FF-A specification.
    • Preferably write a doc comment for each such definition that specifies where it comes from in the spec (i.e. Table x.y or chapter x.y.z)
    • The data structures should derive the necessary zerocopy traits.

§FF-A version handling

The FF-A specification allows different components of a system to use different versions of the specification. The version used at a specific FF-A instance (i.e. an interface between two FF-A components) is discovered at runtime, either by parsing FF-A manifests or using FFA_VERSION. An FF-A component might have to use multiple versions at runtime on its different interfaces, therefore this library must be able to support this and having a compile time fixed version is not possible. Because of this, most of the functions to create or parse FF-A messages and data structures require passing the FF-A version used at the instance where the serialized data was received from or will be sent to.

§Implemented features

  • Supports converting FF-A interface types between Rust types and the FF-A register ABI.
  • Memory transaction descriptor handling for FFA_MEM_* interfaces (partial).
  • FF-A v1.1+ boot information protocol.
  • FF-A partiton information descriptor.

§Future plans

  • Implement missing features from FF-A v1.1 and later. Implementing FF-A v1.0 features that are deprecated by v1.1 are low priority for now.
  • Increase test coverage.
  • Create more detailed documentation to capture which parts of FF-A are currently supported.

§License

The project is MIT and Apache-2.0 dual licensed, see LICENSE-APACHE and LICENSE-MIT.

§Maintainers

arm-ffa is a trustedfirmware.org maintained project. All contributions are ultimately merged by the maintainers listed below.

§Contributing

Please follow the directions of the Trusted Firmware Processes

Contributions are handled through review.trustedfirmware.org.

§Arm trademark notice

Arm is a registered trademark of Arm Limited (or its subsidiaries or affiliates).

This project uses some of the Arm product, service or technology trademarks, as listed in the Trademark List, in accordance with the Arm Trademark Use Guidelines.

Subsequent uses of these trademarks throughout this repository do not need to be prefixed with the Arm word trademark.

Copyright The arm-ffa Contributors.

Modules§

boot_info
Implementation of the FF-A Boot information protocol.
memory_management
Implementation of the FF-A Memory Management protocol.
partition_info
Implementation of FF-A partition discovery data structures.

Structs§

DirectMsg2Args
Arguments for the FFA_MSG_SEND_DIRECT_{REQ,RESP}2 interfaces.
LogChars
Generic type for storing FFA_CONSOLE_LOG character payload and its length in bytes.
MsgSend2Flags
Flags field of the FFA_MSG_SEND2 interface.
MsgWaitFlags
Flags field of the FFA_MSG_WAIT interface.
NotificationBindFlags
Flags field of the FFA_NOTIFICATION_BIND interface.
NotificationGetFlags
Flags field of the FFA_NOTIFICATION_GET interface.
NotificationInfoGetIterator
Iterator implementation for parsing the (partition ID, vCPU ID list) pairs of the FFA_SUCCESS of an FFA_NOTIFICATION_INFO_GET call.
NotificationSetFlags
Flags field of the FFA_NOTIFICATION_SET interface.
PartitionInfoGetFlags
Flags of the FFA_PARTITION_INFO_GET interface.
SuccessArgsFeatures
FFA_FEATURES specific success argument structure. This type needs further specialization based on ‘FF-A function ID or Feature ID’ field of the preceeding FFA_FEATURES request.
SuccessArgsIdGet
FFA_ID_GET specific success argument structure.
SuccessArgsNotificationGet
FFA_NOTIFICATION_GET specific success argument structure.
SuccessArgsNotificationInfoGet
FFA_NOTIFICATION_INFO_GET specific success argument structure. The MAX_COUNT parameter depends on the 32-bit or 64-bit packing.
SuccessArgsSpmIdGet
FFA_SPM_ID_GET specific success argument structure.
TargetInfo
Endpoint ID and vCPU ID pair, used by FFA_ERROR, FFA_INTERRUPT and FFA_RUN interfaces.
Uuid
A Universally Unique Identifier (UUID).
UuidHelper
Collection of helper functions for converting between Uuid type and its representations in various FF-A containers.
Version
Version number of the FF-A implementation, .0 is the major, .1 is minor the version.

Enums§

ConsoleLogChars
Argument for the FFA_CONSOLE_LOG interface.
DirectMsgArgs
Arguments for the FFA_MSG_SEND_DIRECT_{REQ,RESP} interfaces.
Error
Rich error types returned by this module. Should be converted to crate::FfaError when used with the FFA_ERROR interface.
Feature
Arguments for the FFA_FEATURES interface.
FeatureId
Feature IDs used by the FFA_FEATURES interface.
FfaError
Error status codes used by the FFA_ERROR interface.
FuncId
Function IDs of the various FF-A interfaces.
Instance
An FF-A instance is a valid combination of two FF-A components at an exception level boundary.
Interface
FF-A “message types”, the terminology used by the spec is “interfaces”.
MemAddr
Memory address argument for FFA_MEM_PERM_{GET,SET} interfaces.
MemOpBuf
Descriptor for a dynamically allocated memory buffer that contains the memory transaction descriptor.
RxTxAddr
RXTX buffer descriptor, used by FFA_RXTX_MAP.
SecondaryEpRegisterAddr
Entrypoint address argument for FFA_SECONDARY_EP_REGISTER interface.
SuccessArgs
Generic arguments of the FFA_SUCCESS interface. The interpretation of the arguments depends on the interface that initiated the request. The application code has knowledge of the request, so it has to convert SuccessArgs into/from a specific success args structure that matches the request.
VersionOut
Enum for storing the response of an FFA_VERSION request. It can either contain a Version or a NOT_SUPPORTED error code.
VmAvailabilityStatus
Composite type for capturing success and error return codes for the VM availability messages.
WarmBootType
Arguments for the Power Warm Boot FFA_MSG_SEND_DIRECT_REQ interface.

Constants§

FFA_PAGE_SIZE_4K
Constant for 4K page size. On many occasions the FF-A spec defines memory size as count of 4K pages, regardless of the current translation granule.

Type Aliases§

ConsoleLogChars32
Specialized type for 32-bit FFA_CONSOLE_LOG payload.
ConsoleLogChars64
Specialized type for 64-bit FFA_CONSOLE_LOG payload.
SuccessArgsNotificationInfoGet32
FFA_NOTIFICATION_INFO_GET_32 specific success argument structure.
SuccessArgsNotificationInfoGet64
FFA_NOTIFICATION_INFO_GET_64 specific success argument structure.