€•ÜI      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ(/translations/zh_CN/arch/powerpc/pmu-ebb”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/zh_TW/arch/powerpc/pmu-ebb”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/it_IT/arch/powerpc/pmu-ebb”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/ja_JP/arch/powerpc/pmu-ebb”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/ko_KR/arch/powerpc/pmu-ebb”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ(/translations/sp_SP/arch/powerpc/pmu-ebb”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒPMU Event Based Branches”h]”hŒPMU Event Based Branches”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒB/var/lib/git/docbuild/linux/Documentation/arch/powerpc/pmu-ebb.rst”h KubhŒ	paragraph”“”)”}”(hŒ“Event Based Branches (EBBs) are a feature which allows the hardware to
branch directly to a specified user space address when certain events occur.”h]”hŒ“Event Based Branches (EBBs) are a feature which allows the hardware to
branch directly to a specified user space address when certain events occur.”…””}”(hh¹hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubh¸)”}”(hŒ7The full specification is available in Power ISA v2.07:”h]”hŒ7The full specification is available in Power ISA v2.07:”…””}”(hhÇhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubhŒblock_quote”“”)”}”(hŒ<https://www.power.org/documentation/power-isa-version-2-07/
”h]”h¸)”}”(hŒ;https://www.power.org/documentation/power-isa-version-2-07/”h]”hŒ	reference”“”)”}”(hhÝh]”hŒ;https://www.power.org/documentation/power-isa-version-2-07/”…””}”(hháhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”hÝuh1hßhhÛubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K
hh×ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÕhŸh¶h K
hh£hžhubh¸)”}”(hŒ¶One type of event for which EBBs can be configured is PMU exceptions. This
document describes the API for configuring the Power PMU to generate EBBs,
using the Linux perf_events API.”h]”hŒ¶One type of event for which EBBs can be configured is PMU exceptions. This
document describes the API for configuring the Power PMU to generate EBBs,
using the Linux perf_events API.”…””}”(hhûhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khh£hžhubh¢)”}”(hhh]”(h§)”}”(hŒTerminology”h]”hŒTerminology”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj	  hžhhŸh¶h Kubh¸)”}”(hŒôThroughout this document we will refer to an "EBB event" or "EBB events". This
just refers to a struct perf_event which has set the "EBB" flag in its
attr.config. All events which can be configured on the hardware PMU are
possible "EBB events".”h]”hX  Throughout this document we will refer to an â€œEBB eventâ€ or â€œEBB eventsâ€. This
just refers to a struct perf_event which has set the â€œEBBâ€ flag in its
attr.config. All events which can be configured on the hardware PMU are
possible â€œEBB eventsâ€.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khj	  hžhubeh}”(h]”Œterminology”ah ]”h"]”Œterminology”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ
Background”h]”hŒ
Background”…””}”(hj3  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj0  hžhhŸh¶h Kubh¸)”}”(hŒWhen a PMU EBB occurs it is delivered to the currently running process. As such
EBBs can only sensibly be used by programs for self-monitoring.”h]”hŒWhen a PMU EBB occurs it is delivered to the currently running process. As such
EBBs can only sensibly be used by programs for self-monitoring.”…””}”(hjA  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Khj0  hžhubh¸)”}”(hŒÿIt is a feature of the perf_events API that events can be created on other
processes, subject to standard permission checks. This is also true of EBB
events, however unless the target process enables EBBs (via mtspr(BESCR)) no
EBBs will ever be delivered.”h]”hŒÿIt is a feature of the perf_events API that events can be created on other
processes, subject to standard permission checks. This is also true of EBB
events, however unless the target process enables EBBs (via mtspr(BESCR)) no
EBBs will ever be delivered.”…””}”(hjO  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K hj0  hžhubh¸)”}”(hX)  This makes it possible for a process to enable EBBs for itself, but not
actually configure any events. At a later time another process can come along
and attach an EBB event to the process, which will then cause EBBs to be
delivered to the first process. It's not clear if this is actually useful.”h]”hX+  This makes it possible for a process to enable EBBs for itself, but not
actually configure any events. At a later time another process can come along
and attach an EBB event to the process, which will then cause EBBs to be
delivered to the first process. Itâ€™s not clear if this is actually useful.”…””}”(hj]  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K%hj0  hžhubh¸)”}”(hX$  When the PMU is configured for EBBs, all PMU interrupts are delivered to the
user process. This means once an EBB event is scheduled on the PMU, no non-EBB
events can be configured. This means that EBB events can not be run
concurrently with regular 'perf' commands, or any other perf events.”h]”hX(  When the PMU is configured for EBBs, all PMU interrupts are delivered to the
user process. This means once an EBB event is scheduled on the PMU, no non-EBB
events can be configured. This means that EBB events can not be run
concurrently with regular â€˜perfâ€™ commands, or any other perf events.”…””}”(hjk  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K+hj0  hžhubh¸)”}”(hŒ·It is however safe to run 'perf' commands on a process which is using EBBs. The
kernel will in general schedule the EBB event, and perf will be notified that
its events could not run.”h]”hŒ»It is however safe to run â€˜perfâ€™ commands on a process which is using EBBs. The
kernel will in general schedule the EBB event, and perf will be notified that
its events could not run.”…””}”(hjy  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K0hj0  hžhubh¸)”}”(hXÂ  The exclusion between EBB events and regular events is implemented using the
existing "pinned" and "exclusive" attributes of perf_events. This means EBB
events will be given priority over other events, unless they are also pinned.
If an EBB event and a regular event are both pinned, then whichever is enabled
first will be scheduled and the other will be put in error state. See the
section below titled "Enabling an EBB event" for more information.”h]”hXÎ  The exclusion between EBB events and regular events is implemented using the
existing â€œpinnedâ€ and â€œexclusiveâ€ attributes of perf_events. This means EBB
events will be given priority over other events, unless they are also pinned.
If an EBB event and a regular event are both pinned, then whichever is enabled
first will be scheduled and the other will be put in error state. See the
section below titled â€œEnabling an EBB eventâ€ for more information.”…””}”(hj‡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K4hj0  hžhubeh}”(h]”Œ
background”ah ]”h"]”Œ
background”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒCreating an EBB event”h]”hŒCreating an EBB event”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h K=ubh¸)”}”(hŒUTo request that an event is counted using EBB, the event code should have bit
63 set.”h]”hŒUTo request that an event is counted using EBB, the event code should have bit
63 set.”…””}”(hj®  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K?hj  hžhubh¸)”}”(hŒªEBB events must be created with a particular, and restrictive, set of
attributes - this is so that they interoperate correctly with the rest of the
perf_events subsystem.”h]”hŒªEBB events must be created with a particular, and restrictive, set of
attributes - this is so that they interoperate correctly with the rest of the
perf_events subsystem.”…””}”(hj¼  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KBhj  hžhubh¸)”}”(hŒ²An EBB event must be created with the "pinned" and "exclusive" attributes set.
Note that if you are creating a group of EBB events, only the leader can have
these attributes set.”h]”hŒºAn EBB event must be created with the â€œpinnedâ€ and â€œexclusiveâ€ attributes set.
Note that if you are creating a group of EBB events, only the leader can have
these attributes set.”…””}”(hjÊ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KFhj  hžhubh¸)”}”(hŒgAn EBB event must NOT set any of the "inherit", "sample_period", "freq" or
"enable_on_exec" attributes.”h]”hŒwAn EBB event must NOT set any of the â€œinheritâ€, â€œsample_periodâ€, â€œfreqâ€ or
â€œenable_on_execâ€ attributes.”…””}”(hjØ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KJhj  hžhubh¸)”}”(hŒAn EBB event must be attached to a task. This is specified to perf_event_open()
by passing a pid value, typically 0 indicating the current task.”h]”hŒAn EBB event must be attached to a task. This is specified to perf_event_open()
by passing a pid value, typically 0 indicating the current task.”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KMhj  hžhubh¸)”}”(hŒxAll events in a group must agree on whether they want EBB. That is all events
must request EBB, or none may request EBB.”h]”hŒxAll events in a group must agree on whether they want EBB. That is all events
must request EBB, or none may request EBB.”…””}”(hjô  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KPhj  hžhubh¸)”}”(hŒ”EBB events must specify the PMC they are to be counted on. This ensures
userspace is able to reliably determine which PMC the event is scheduled on.”h]”hŒ”EBB events must specify the PMC they are to be counted on. This ensures
userspace is able to reliably determine which PMC the event is scheduled on.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KShj  hžhubeh}”(h]”Œcreating-an-ebb-event”ah ]”h"]”Œcreating an ebb event”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K=ubh¢)”}”(hhh]”(h§)”}”(hŒEnabling an EBB event”h]”hŒEnabling an EBB event”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h KXubh¸)”}”(hŒ­Once an EBB event has been successfully opened, it must be enabled with the
perf_events API. This can be achieved either via the ioctl() interface, or the
prctl() interface.”h]”hŒ­Once an EBB event has been successfully opened, it must be enabled with the
perf_events API. This can be achieved either via the ioctl() interface, or the
prctl() interface.”…””}”(hj)  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KZhj  hžhubh¸)”}”(hX=  However, due to the design of the perf_events API, enabling an event does not
guarantee that it has been scheduled on the PMU. To ensure that the EBB event
has been scheduled on the PMU, you must perform a read() on the event. If the
read() returns EOF, then the event has not been scheduled and EBBs are not
enabled.”h]”hX=  However, due to the design of the perf_events API, enabling an event does not
guarantee that it has been scheduled on the PMU. To ensure that the EBB event
has been scheduled on the PMU, you must perform a read() on the event. If the
read() returns EOF, then the event has not been scheduled and EBBs are not
enabled.”…””}”(hj7  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K^hj  hžhubh¸)”}”(hX$  This behaviour occurs because the EBB event is pinned and exclusive. When the
EBB event is enabled it will force all other non-pinned events off the PMU. In
this case the enable will be successful. However if there is already an event
pinned on the PMU then the enable will not be successful.”h]”hX$  This behaviour occurs because the EBB event is pinned and exclusive. When the
EBB event is enabled it will force all other non-pinned events off the PMU. In
this case the enable will be successful. However if there is already an event
pinned on the PMU then the enable will not be successful.”…””}”(hjE  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kdhj  hžhubeh}”(h]”Œenabling-an-ebb-event”ah ]”h"]”Œenabling an ebb event”ah$]”h&]”uh1h¡hh£hžhhŸh¶h KXubh¢)”}”(hhh]”(h§)”}”(hŒReading an EBB event”h]”hŒReading an EBB event”…””}”(hj^  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj[  hžhhŸh¶h Kkubh¸)”}”(hŒ×It is possible to read() from an EBB event. However the results are
meaningless. Because interrupts are being delivered to the user process the
kernel is not able to count the event, and so will return a junk value.”h]”hŒ×It is possible to read() from an EBB event. However the results are
meaningless. Because interrupts are being delivered to the user process the
kernel is not able to count the event, and so will return a junk value.”…””}”(hjl  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kmhj[  hžhubeh}”(h]”Œreading-an-ebb-event”ah ]”h"]”Œreading an ebb event”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kkubh¢)”}”(hhh]”(h§)”}”(hŒClosing an EBB event”h]”hŒClosing an EBB event”…””}”(hj…  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj‚  hžhhŸh¶h Ksubh¸)”}”(hŒÂWhen an EBB event is finished with, you can close it using close() as for any
regular event. If this is the last EBB event the PMU will be deconfigured and
no further PMU EBBs will be delivered.”h]”hŒÂWhen an EBB event is finished with, you can close it using close() as for any
regular event. If this is the last EBB event the PMU will be deconfigured and
no further PMU EBBs will be delivered.”…””}”(hj“  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h Kuhj‚  hžhubeh}”(h]”Œclosing-an-ebb-event”ah ]”h"]”Œclosing an ebb event”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Ksubh¢)”}”(hhh]”(h§)”}”(hŒEBB Handler”h]”hŒEBB Handler”…””}”(hj¬  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj©  hžhhŸh¶h K{ubh¸)”}”(hŒõThe EBB handler is just regular userspace code, however it must be written in
the style of an interrupt handler. When the handler is entered all registers
are live (possibly) and so must be saved somehow before the handler can invoke
other code.”h]”hŒõThe EBB handler is just regular userspace code, however it must be written in
the style of an interrupt handler. When the handler is entered all registers
are live (possibly) and so must be saved somehow before the handler can invoke
other code.”…””}”(hjº  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K}hj©  hžhubh¸)”}”(hŒ›It's up to the program how to handle this. For C programs a relatively simple
option is to create an interrupt frame on the stack and save registers there.”h]”hŒItâ€™s up to the program how to handle this. For C programs a relatively simple
option is to create an interrupt frame on the stack and save registers there.”…””}”(hjÈ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h K‚hj©  hžhubeh}”(h]”Œebb-handler”ah ]”h"]”Œebb handler”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K{ubh¢)”}”(hhh]”(h§)”}”(hŒFork”h]”hŒFork”…””}”(hjá  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjÞ  hžhhŸh¶h K†ubh¸)”}”(hŒ¿EBB events are not inherited across fork. If the child process wishes to use
EBBs it should open a new event for itself. Similarly the EBB state in
BESCR/EBBHR/EBBRR is cleared across fork().”h]”hŒ¿EBB events are not inherited across fork. If the child process wishes to use
EBBs it should open a new event for itself. Similarly the EBB state in
BESCR/EBBHR/EBBRR is cleared across fork().”…””}”(hjï  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h·hŸh¶h KˆhjÞ  hžhubeh}”(h]”Œfork”ah ]”h"]”Œfork”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K†ubeh}”(h]”Œpmu-event-based-branches”ah ]”h"]”Œpmu event based branches”ah$]”h&]”uh1h¡hhhžhhŸh¶h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h¶uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¦NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j0  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h¶Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(j
  j  j-  j*  jš  j—  j  j  jX  jU  j  j|  j¦  j£  jÛ  jØ  j  jÿ  uŒ	nametypes”}”(j
  ‰j-  ‰jš  ‰j  ‰jX  ‰j  ‰j¦  ‰jÛ  ‰j  ‰uh}”(j  h£j*  j	  j—  j0  j  j  jU  j  j|  j[  j£  j‚  jØ  j©  jÿ  jÞ  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.