Overview¶
The Platform Environment Control Interface (PECI) is a communication interface between Intel processor and management controllers (e.g. Baseboard Management Controller, BMC). PECI provides services that allow the management controller to configure, monitor and debug platform by accessing various registers. It defines a dedicated command protocol, where the management controller is acting as a PECI originator and the processor - as a PECI responder. PECI can be used in both single processor and multiple-processor based systems.
NOTE: Intel PECI specification is not released as a dedicated document, instead it is a part of External Design Specification (EDS) for given Intel CPU. External Design Specifications are usually not publicly available.
PECI Wire¶
PECI Wire interface uses a single wire for self-clocking and data transfer. It does not require any additional control lines - the physical layer is a self-clocked one-wire bus signal that begins each bit with a driven, rising edge from an idle near zero volts. The duration of the signal driven high allows to determine whether the bit value is logic ‘0’ or logic ‘1’. PECI Wire also includes variable data rate established with every message.
For PECI Wire, each processor package will utilize unique, fixed addresses within a defined range and that address should have a fixed relationship with the processor socket ID - if one of the processors is removed, it does not affect addresses of remaining processors.
PECI subsystem internals¶
-
struct peci_controller_ops¶
PECI controller specific methods
Definition:
struct peci_controller_ops {
int (*xfer)(struct peci_controller *controller, u8 addr, struct peci_request *req);
};
Members
xferPECI transfer function
Description
PECI controllers may have different hardware interfaces - the drivers implementing PECI controllers can use this structure to abstract away those differences by exposing a common interface for PECI core.
-
struct peci_controller¶
PECI controller
Definition:
struct peci_controller {
struct device dev;
const struct peci_controller_ops *ops;
struct mutex bus_lock;
u8 id;
};
Members
devdevice object to register PECI controller to the device model
opspointer to device specific controller operations
bus_locklock used to protect multiple callers
idPECI controller ID
Description
PECI controllers usually connect to their drivers using non-PECI bus, such as the platform bus. Each PECI controller can communicate with one or more PECI devices.
-
struct peci_device¶
PECI device
Definition:
struct peci_device {
struct device dev;
struct {
u32 x86_vfm;
u8 peci_revision;
u8 socket_id;
} info;
u8 addr;
bool deleted;
};
Members
devdevice object to register PECI device to the device model
infoPECI device characteristics
info.x86_vfmdevice vendor-family-model
info.peci_revisionPECI revision supported by the PECI device
info.socket_idthe socket ID represented by the PECI device
addraddress used on the PECI bus connected to the parent controller
deletedindicates that PECI device was already deleted
Description
A peci_device identifies a single device (i.e. CPU) connected to a PECI bus. The behaviour exposed to the rest of the system is defined by the PECI driver managing the device.
-
struct peci_request¶
PECI request
Definition:
struct peci_request {
struct peci_device *device;
struct {
u8 buf[PECI_REQUEST_MAX_BUF_SIZE];
u8 len;
} rx, tx;
};
Members
devicePECI device to which the request is sent
rxRX buffer specific data
rx.bufRX buffer
rx.lenreceived data length in bytes
txTX buffer specific data
tx.bufTX buffer
tx.lentransfer data length in bytes
Description
A peci_request represents a request issued by PECI originator (TX) and a response received from PECI responder (RX).
-
struct peci_device_id¶
PECI device data to match
Definition:
struct peci_device_id {
const void *data;
u32 x86_vfm;
};
Members
datapointer to driver private data specific to device
x86_vfmdevice vendor-family-model
-
struct peci_driver¶
PECI driver
Definition:
struct peci_driver {
struct device_driver driver;
int (*probe)(struct peci_device *device, const struct peci_device_id *id);
void (*remove)(struct peci_device *device);
const struct peci_device_id *id_table;
};
Members
driverinherit device driver
probeprobe callback
removeremove callback
id_tablePECI device match table to decide which device to bind
-
peci_driver_register¶
peci_driver_register (driver)
register PECI driver
Parameters
driverthe driver to be registered
Description
PECI drivers that don’t need to do anything special in module init should use the convenience “module_peci_driver” macro instead
Return
zero on success, else a negative error code.
-
module_peci_driver¶
module_peci_driver (__peci_driver)
helper macro for registering a modular PECI driver
Parameters
__peci_driverpeci_driver struct
Description
Helper macro for PECI drivers which do not do anything special in module
init/exit. This eliminates a lot of boilerplate. Each module may only
use this macro once, and calling it replaces module_init() and module_exit()
-
struct peci_controller *devm_peci_controller_add(struct device *dev, const struct peci_controller_ops *ops)¶
add PECI controller
Parameters
struct device *devdevice for devm operations
const struct peci_controller_ops *opspointer to controller specific methods
Description
In final stage of its probe(), peci_controller driver calls
devm_peci_controller_add() to register itself with the PECI bus.
Return
Pointer to the newly allocated controller or ERR_PTR() in case of failure.
-
int peci_request_status(struct peci_request *req)¶
return -errno based on PECI completion code
Parameters
struct peci_request *reqthe PECI request that contains response data with completion code
Description
It can’t be used for Ping(), GetDIB() and GetTemp() - for those commands we don’t expect completion code in the response.
Return
-errno
-
struct peci_request *peci_request_alloc(struct peci_device *device, u8 tx_len, u8 rx_len)¶
allocate
struct peci_requests
Parameters
struct peci_device *devicePECI device to which request is going to be sent
u8 tx_lenTX length
u8 rx_lenRX length
Return
A pointer to a newly allocated struct peci_request on success or NULL otherwise.
-
void peci_request_free(struct peci_request *req)¶
free peci_request
Parameters
struct peci_request *reqthe PECI request to be freed
PECI CPU Driver API¶
-
int peci_temp_read(struct peci_device *device, s16 *temp_raw)¶
read the maximum die temperature from PECI target device
Parameters
struct peci_device *devicePECI device to which request is going to be sent
s16 *temp_rawwhere to store the read temperature
Description
It uses GetTemp PECI command.
Return
0 if succeeded, other values in case errors.
-
int peci_pcs_read(struct peci_device *device, u8 index, u16 param, u32 *data)¶
read PCS register
Parameters
struct peci_device *devicePECI device to which request is going to be sent
u8 indexPCS index
u16 paramPCS parameter
u32 *datawhere to store the read data
Description
It uses RdPkgConfig PECI command.
Return
0 if succeeded, other values in case errors.
-
int peci_pci_local_read(struct peci_device *device, u8 bus, u8 dev, u8 func, u16 reg, u32 *data)¶
read 32-bit memory location using raw address
Parameters
struct peci_device *devicePECI device to which request is going to be sent
u8 busbus
u8 devdevice
u8 funcfunction
u16 regregister
u32 *datawhere to store the read data
Description
It uses RdPCIConfigLocal PECI command.
Return
0 if succeeded, other values in case errors.
-
int peci_ep_pci_local_read(struct peci_device *device, u8 seg, u8 bus, u8 dev, u8 func, u16 reg, u32 *data)¶
read 32-bit memory location using raw address
Parameters
struct peci_device *devicePECI device to which request is going to be sent
u8 segPCI segment
u8 busbus
u8 devdevice
u8 funcfunction
u16 regregister
u32 *datawhere to store the read data
Description
Like peci_pci_local_read, but it uses RdEndpointConfig PECI command.
Return
0 if succeeded, other values in case errors.
-
int peci_mmio_read(struct peci_device *device, u8 bar, u8 seg, u8 bus, u8 dev, u8 func, u64 address, u32 *data)¶
read 32-bit memory location using 64-bit bar offset address
Parameters
struct peci_device *devicePECI device to which request is going to be sent
u8 barPCI bar
u8 segPCI segment
u8 busbus
u8 devdevice
u8 funcfunction
u64 address64-bit MMIO address
u32 *datawhere to store the read data
Description
It uses RdEndpointConfig PECI command.
Return
0 if succeeded, other values in case errors.