Commit 9f992cca authored by Michael Roth's avatar Michael Roth Committed by David Gibson
Browse files

spapr: update spapr hotplug documentation 



This updates the existing documentation to reflect recent updates to
the hotplug event structure, which are in draft form but slated
for inclusion in PAPR/LoPAPR.

Signed-off-by: default avatarMichael Roth <mdroth@linux.vnet.ibm.com>
Reviewed-by: default avatarDavid Gibson <david@gibson.dropbear.id.au>
Signed-off-by: default avatarDavid Gibson <david@gibson.dropbear.id.au>
parent 6db246f9

docs/specs/ppc-spapr-hotplug.txt

+46 −9
Original line number Original line Diff line number Diff line
@@ -233,12 +233,27 @@ tools by host-level management such as an HMC. This level of management is not 
applicable to PowerKVM, hence the reason for extending the notification

applicable to PowerKVM, hence the reason for extending the notification

framework to support hotplug events.

framework to support hotplug events.





Note that these events are not yet formally part of the PAPR+ specification,

The format for these EPOW-signalled events is described below under

but support for this format has already been implemented in DR-related

"hotplug/unplug event structure". Note that these events are not

guest tools such as powerpc-utils/librtas, as well as kernel patches that have

formally part of the PAPR+ specification, and have been superseded by a

been submitted to handle in-kernel processing of memory/cpu-related hotplug

newer format, also described below under "hotplug/unplug event structure",

events[1], and is planned for formal inclusion is PAPR+ specification. The

and so are now deemed a "legacy" format. The formats are similar, but the

hotplug-specific payload is QEMU implemented as follows (with all values

"modern" format contains additional fields/flags, which are denoted for the

purposes of this documentation with "#ifdef GUEST_SUPPORTS_MODERN" guards.



QEMU should assume support only for "legacy" fields/flags unless the guest

advertises support for the "modern" format via ibm,client-architecture-support

hcall by setting byte 5, bit 6 of it's ibm,architecture-vec-5 option vector

structure (as described by LoPAPR v11, B.6.2.3). As with "legacy" format events,

"modern" format events are surfaced to the guest via check-exception RTAS calls,

but use a dedicated event source to signal the guest. This event source is

advertised to the guest by the addition of a "hot-plug-events" node under

"/event-sources" node of the guest's device tree using the standard format

described in LoPAPR v11, B.6.12.1.



== hotplug/unplug event structure ==



The hotplug-specific payload in QEMU is implemented as follows (with all values

encoded in big-endian format):

encoded in big-endian format):





struct rtas_event_log_v6_hp {

struct rtas_event_log_v6_hp {
@@ -266,11 +281,20 @@ struct rtas_event_log_v6_hp { 
#define RTAS_LOG_V6_HP_ID_DRC_NAME          1

#define RTAS_LOG_V6_HP_ID_DRC_NAME          1

#define RTAS_LOG_V6_HP_ID_DRC_INDEX         2

#define RTAS_LOG_V6_HP_ID_DRC_INDEX         2

#define RTAS_LOG_V6_HP_ID_DRC_COUNT         3

#define RTAS_LOG_V6_HP_ID_DRC_COUNT         3

#ifdef GUEST_SUPPORTS_MODERN

#define RTAS_LOG_V6_HP_ID_DRC_COUNT_INDEXED 4

#endif

    uint8_t hotplug_identifier;         /* type of the resource identifier,

    uint8_t hotplug_identifier;         /* type of the resource identifier,

                                         * which serves as the discriminator

                                         * which serves as the discriminator

                                         * for the 'drc' union field below

                                         * for the 'drc' union field below

                                         */

                                         */

#ifdef GUEST_SUPPORTS_MODERN

    uint8_t capabilities;               /* capability flags, currently unused

                                         * by QEMU

                                         */

#else

    uint8_t reserved;

    uint8_t reserved;

#endif

    union {

    union {

        uint32_t index;                 /* DRC index of resource to take action

        uint32_t index;                 /* DRC index of resource to take action

                                         * on

                                         * on
@@ -278,6 +302,19 @@ struct rtas_event_log_v6_hp { 
        uint32_t count;                 /* number of DR resources to take

        uint32_t count;                 /* number of DR resources to take

                                         * action on (guest chooses which)

                                         * action on (guest chooses which)

                                         */

                                         */

#ifdef GUEST_SUPPORTS_MODERN

        struct {

            uint32_t count;             /* number of DR resources to take

                                         * action on

                                         */

            uint32_t index;             /* DRC index of first resource to take

                                         * action on. guest will take action

                                         * on DRC index <index> through

                                         * DRC index <index + count - 1> in

                                         * sequential order

                                         */

        } count_indexed;

#endif

        char name[1];                   /* string representing the name of the

        char name[1];                   /* string representing the name of the

                                         * DRC to take action on

                                         * DRC to take action on

                                         */

                                         */