PCI Trusted Execution Environment Security Manager (TSM)¶

Subsystem Interfaces¶

struct pci_ide_partner¶: Per port pair Selective IDE Stream settings

Definition:

struct pci_ide_partner {
    u16 rid_start;
    u16 rid_end;
    u8 stream_index;
    unsigned int default_stream:1;
    unsigned int setup:1;
    unsigned int enable:1;
};

Members

rid_start: Partner Port Requester ID range start
rid_end: Partner Port Requester ID range end
stream_index: Selective IDE Stream Register Block selection
default_stream: Endpoint uses this stream for all upstream TLPs regardless of address and RID association registers
setup: flag to track whether to run pci_ide_stream_teardown() for this partner slot
enable: flag whether to run pci_ide_stream_disable() for this partner slot

struct pci_ide¶: PCIe Selective IDE Stream descriptor

Definition:

struct pci_ide {
    struct pci_dev *pdev;
    struct pci_ide_partner partner[PCI_IDE_PARTNER_MAX];
    u8 host_bridge_stream;
    int stream_id;
    const char *name;
    struct tsm_dev *tsm_dev;
};

Members

pdev: PCIe Endpoint in the pci_ide_partner pair
partner: per-partner settings
host_bridge_stream: allocated from host bridge ide_stream_ida pool
stream_id: unique Stream ID (within Partner Port pairing)
name: name of the established Selective IDE Stream in sysfs
tsm_dev: For TSM established IDE, the TSM device context

Description

Negative stream_id values indicate “uninitialized” on the expectation that with TSM established IDE the TSM owns the stream_id allocation.

struct pci_ide *pci_ide_stream_alloc(struct pci_dev *pdev)¶: Reserve stream indices and probe for settings

Parameters

struct pci_dev *pdev: IDE capable PCIe Endpoint Physical Function

Description

Retrieve the Requester ID range of pdev for programming its Root Port IDE RID Association registers, and conversely retrieve the Requester ID of the Root Port for programming pdev’s IDE RID Association registers.

Allocate a Selective IDE Stream Register Block instance per port.

Allocate a platform stream resource from the associated host bridge. Retrieve stream association parameters for Requester ID range and address range restrictions for the stream.

void pci_ide_stream_free(struct pci_ide *ide)¶: unwind pci_ide_stream_alloc()

Parameters

struct pci_ide *ide: idle IDE settings descriptor

Description

Free all of the stream index (register block) allocations acquired by pci_ide_stream_alloc(). The stream represented by ide is assumed to be unregistered and not instantiated in any device.

void pci_ide_stream_release(struct pci_ide *ide)¶: unwind and release an ide context

Parameters

struct pci_ide *ide: partially or fully registered IDE settings descriptor

Description

In support of automatic cleanup of IDE setup routines perform IDE teardown in expected reverse order of setup and with respect to which aspects of IDE setup have successfully completed.

Be careful that setup order mirrors this shutdown order. Otherwise, open code releasing the IDE context.

int pci_ide_stream_register(struct pci_ide *ide)¶: Prepare to activate an IDE Stream

Parameters

struct pci_ide *ide: IDE settings descriptor

Description

After a Stream ID has been acquired for ide, record the presence of the stream in sysfs. The expectation is that ide is immutable while registered.

void pci_ide_stream_unregister(struct pci_ide *ide)¶: unwind pci_ide_stream_register()

Parameters

struct pci_ide *ide: idle IDE settings descriptor

Description

In preparation for freeing ide, remove sysfs enumeration for the stream.

void pci_ide_stream_setup(struct pci_dev *pdev, struct pci_ide *ide)¶: program settings to Selective IDE Stream registers

Parameters

struct pci_dev *pdev: PCIe device object for either a Root Port or Endpoint Partner Port
struct pci_ide *ide: registered IDE settings descriptor

Description

When pdev is a PCI_EXP_TYPE_ENDPOINT then the PCI_IDE_EP partner settings are written to pdev’s Selective IDE Stream register block, and when pdev is a PCI_EXP_TYPE_ROOT_PORT, the PCI_IDE_RP settings are selected.

void pci_ide_stream_teardown(struct pci_dev *pdev, struct pci_ide *ide)¶: disable the stream and clear all settings

Parameters

struct pci_dev *pdev: PCIe device object for either a Root Port or Endpoint Partner Port
struct pci_ide *ide: registered IDE settings descriptor

Description

For stream destruction, zero all registers that may have been written by pci_ide_stream_setup(). Consider pci_ide_stream_disable() to leave settings in place while temporarily disabling the stream.

int pci_ide_stream_enable(struct pci_dev *pdev, struct pci_ide *ide)¶: enable a Selective IDE Stream

Parameters

struct pci_dev *pdev: PCIe device object for either a Root Port or Endpoint Partner Port
struct pci_ide *ide: registered and setup IDE settings descriptor

Description

Activate the stream by writing to the Selective IDE Stream Control Register.

Note that the state may go “insecure” at any point after returning 0, but those events are equivalent to a “link down” event and handled via asynchronous error reporting.

Caller is responsible to clear the enable bit in the -ENXIO case.

Return

0 if the stream successfully entered the “secure” state, and -EINVAL if ide is invalid, and -ENXIO if the stream fails to enter the secure state.

void pci_ide_stream_disable(struct pci_dev *pdev, struct pci_ide *ide)¶: disable a Selective IDE Stream

Parameters

struct pci_dev *pdev: PCIe device object for either a Root Port or Endpoint Partner Port
struct pci_ide *ide: registered and setup IDE settings descriptor

Description

Clear the Selective IDE Stream Control Register, but leave all other registers untouched.

void pci_ide_set_nr_streams(struct pci_host_bridge *hb, u16 nr)¶: sets size of the pool of IDE Stream resources

Parameters

struct pci_host_bridge *hb: host bridge boundary for the stream pool
u16 nr: number of streams

Description

Platform PCI init and/or expert test module use only. Limit IDE Stream establishment by setting the number of stream resources available at the host bridge. Platform init code must set this before the first pci_ide_stream_alloc() call if the platform has less than the default of 256 streams per host-bridge.

The “PCI_IDE” symbol namespace is required because this is typically a detail that is settled in early PCI init. I.e. this export is not for endpoint drivers.

struct pci_tsm¶: Core TSM context for a given PCIe endpoint

Definition:

struct pci_tsm {
    struct pci_dev *pdev;
    struct pci_dev *dsm_dev;
    struct tsm_dev *tsm_dev;
};

Members

pdev: Back ref to device function, distinguishes type of pci_tsm context
dsm_dev: PCI Device Security Manager for link operations on pdev
tsm_dev: PCI TEE Security Manager device for Link Confidentiality or Device Function Security operations

Description

This structure is wrapped by low level TSM driver data and returned by probe()/lock(), it is freed by the corresponding remove()/unlock().

For link operations it serves to cache the association between a Device Security Manager (DSM) and the functions that manager can assign to a TVM. That can be “self”, for assigning function0 of a TEE I/O device, a sub-function (SR-IOV virtual function, or non-function0 multifunction-device), or a downstream endpoint (PCIe upstream switch-port as DSM).

struct pci_tsm_pf0¶: Physical Function 0 TDISP link context

Definition:

struct pci_tsm_pf0 {
    struct pci_tsm base_tsm;
    struct mutex lock;
    struct pci_doe_mb *doe_mb;
};

Members

base_tsm: generic core “tsm” context
lock: mutual exclustion for pci_tsm_ops invocation
doe_mb: PCIe Data Object Exchange mailbox

int pci_tsm_link_constructor(struct pci_dev *pdev, struct pci_tsm *tsm, struct tsm_dev *tsm_dev)¶: base ‘struct pci_tsm’ initialization for link TSMs

Parameters

struct pci_dev *pdev: The PCI device
struct pci_tsm *tsm: context to initialize
struct tsm_dev *tsm_dev: Platform TEE Security Manager, initiator of security operations

int pci_tsm_pf0_constructor(struct pci_dev *pdev, struct pci_tsm_pf0 *tsm, struct tsm_dev *tsm_dev)¶: common ‘struct pci_tsm_pf0’ (DSM) initialization

Parameters

struct pci_dev *pdev: Physical Function 0 PCI device (as indicated by is_pci_tsm_pf0())
struct pci_tsm_pf0 *tsm: context to initialize
struct tsm_dev *tsm_dev: Platform TEE Security Manager, initiator of security operations

The Linux Kernel

Contents

This Page

PCI Trusted Execution Environment Security Manager (TSM)¶

Subsystem Interfaces¶