[llvm] [LLVM][MDL] First integration of MDL with LLVM (PR #78002)
Reid Tatge via llvm-commits
llvm-commits at lists.llvm.org
Tue Jan 23 13:53:16 PST 2024
https://github.com/reidtatge updated https://github.com/llvm/llvm-project/pull/78002
>From fe5dca29bf78a9a44861fce6b5a50c1c3e406315 Mon Sep 17 00:00:00 2001
From: Reid Tatge <tatge at google.com>
Date: Sat, 13 Jan 2024 00:00:24 +0000
Subject: [PATCH 01/14] [LLVM][MDL] First integration of MDL with LLVM
This is the initial pull request for the Machine Description Language
(MDL) project described at https://discourse.llvm.org/t/rfc-mdl-a-micro-architecture-description-language-for-llvm/66409
This commit includes just the original RFC and documentation for the
project, the language, and its use in LLVM.
The work in its entirety can be found at https://github.com/MPACT-ORG/llvm-project/tree/all, if you're interested in seeing where this work is headed.
---
llvm/docs/Mdl/MachineDescriptionNotes.md | 2803 ++++++++++++++++++++++
llvm/docs/Mdl/RFC.md | 64 +
2 files changed, 2867 insertions(+)
create mode 100644 llvm/docs/Mdl/MachineDescriptionNotes.md
create mode 100644 llvm/docs/Mdl/RFC.md
diff --git a/llvm/docs/Mdl/MachineDescriptionNotes.md b/llvm/docs/Mdl/MachineDescriptionNotes.md
new file mode 100644
index 000000000000000..ae9e8b974a7f89f
--- /dev/null
+++ b/llvm/docs/Mdl/MachineDescriptionNotes.md
@@ -0,0 +1,2803 @@
+
+## MPACT Microarchitecture Description Language
+
+Reid Tatge [tatge at google.com](mailto:tatge at google.com)
+
+
+[TOC]
+
+
+
+### **Goals for a Machine Description Language**
+
+Modern processors are complex: multiple execution pipelines, dynamically dispatched, out-of-order execution, register renaming, forwarding networks, and (often) undocumented micro-operations. Instruction behaviors, including micro-operations, often can’t be _statically_ modeled in an accurate way, but only _statistically_ modeled. In these cases, the compiler’s model of a microarchitecture (Schedules and Itineraries in LLVM) is effectively closer to a heuristic than a formal model. And this works quite well for general purpose microprocessors.
+
+However, modern accelerators have different and/or additional dimensions of complexity: VLIW instruction issue, unprotected pipelines, tensor/vector ALUs, software-managed memory hierarchies. And it's more critical that compilers can precisely model the details of that complexity. Currently, LLVM’s Schedules and Itineraries aren’t adequate for directly modeling many accelerator architectural features.
+
+So we have several goals:
+
+
+
+1. We want a first-class, purpose-built, intuitive language that captures all the scheduling and latency details of the architecture - much like Schedules and Itineraries - that works well for all current targets, but also for a large class of accelerator architectures..
+2. The complexity of the specification should scale with the complexity of the hardware.
+3. The description should be succinct, avoiding duplicated information, while reflecting the way things are defined in a hardware architecture specification.
+4. We want to generate artifacts that can be used in a machine-independent way for back-end optimization, register allocation, instruction scheduling, etc - anything that depends on the behavior and constraints of instructions.
+5. We want to support a much larger class of architectures in one uniform manner.
+
+For this document (and language), the term “instructions” refers to the documented instruction set of the machine, as represented by LLVM instructions descriptions, rather than undocumented micro-operations used by many modern microprocessors.
+
+
+
+The process of compiling a processor’s machine description creates several primary artifacts:
+
+
+
+* For each target instruction (described in td files), we create an object that describes the detailed behaviors of the instruction in any legal context (for example, on any functional unit, on any processor)
+* A set of methods with machine independent APIs that leverage the information associated with instructions to inform and guide back-end optimization passes.
+
+The details of the artifacts are described later in this document.
+
+_Note: A full language grammar description is provided in an appendix. Snippets of grammar throughout the document only provide the pertinent section of the grammar, see the Appendix A for the full grammar._
+
+The proposed language can be thought of as an _optional extension to the LLVM machine description_. For most upstream architectures, the new language offers minimal benefit other than a much more succinct way to specify the architecture vs Schedules and Itineraries. But for accelerator-class architectures, it provides a level of detail and capability not available in the existing tablegen approaches.
+
+
+#### **Background**
+
+Processor families evolve over time. They accrete new instructions, and pipelines change - often in subtle ways - as they accumulate more functional units and registers; encoding rules change; issue rules change. Understanding, encoding, and using all of this information - over time, for many subtargets - can be daunting. When the description language isn’t sufficient to model the architecture, the back-end modeling evolves towards heuristics, and leads to performance issues or bugs in the compiler. And it certainly ends with large amounts of target specific code to handle “special cases”.
+
+LLVM uses the [TableGen](https://llvm.org/docs/TableGen/index.html) language to describe a processor, and this is quite sufficient for handling most general purpose architectures - there are 20+ processor families currently upstreamed in LLVM! In fact, it is very good at modeling instruction definitions, register classes, and calling conventions. However, there are “features” of modern accelerator micro-architectures which are difficult or impossible to model in tablegen.
+
+We would like to easily handle:
+
+
+
+* Complex pipeline behaviors
+ * An instruction may have different latencies, resource usage, and/or register constraints on different functional units or different operand values.
+ * An instruction may read source registers more than once (in different pipeline phases).
+ * Pipeline structure, depth, hazards, scoreboarding, and protection may differ between family members.
+* Functional units
+ * Managing functional unit behavior differences across subtargets of a family.
+ * Impose different register constraints on instructions (local register files, for example).
+ * Share execution resources with other functional units (such as register ports)
+ * Functional unit clusters with separate execution pipelines.
+* VLIW Architecture
+ * issue rules can get extremely complex, and can be dependent on encoding, operand features, and pipeline behavior of candidate instructions.** \
+**
+
+More generally, we’d like specific language to:
+
+
+
+* Support all members of a processor family
+* Describe CPU features, parameterized by subtarget
+ * Functional units
+ * Issue slots
+ * Pipeline structure and behaviors
+
+Since our emphasis is on easily supporting accelerators and VLIW processors, in addition to supporting all existing targets, much of this is overkill for most upstreamed CPUs. CPU’s typically have much simpler descriptions, and don’t require much of the capability of our machine description language. Incidentally, MDL descriptions of these targets (generated automatically from the tablegen Schedules and Itineraries) are typically much more concise than the original tablegen descriptions.
+
+
+#### **Approach - “Subunits” and Instruction Behaviors**
+
+We developed a DSL that allows us to describe an arbitrary processor microarchitecture in terms that reflect what is typically documented in the hardware specification. The MDL compiler creates a database that provides microarchitecture behavior information that can _automatically _inform critical back-end compiler passes, such as instruction scheduling and register allocation, in a machine-independent way.
+
+It’s important to note the difference between an instruction definition, as described in LLVM, and an instruction instance. Generally, instructions defined in LLVM share the same behaviors across all instances of that instruction in a single subtarget. Exceptions to this require non-trivial code in the back-end to model variant behavior. In VLIW and accelerator architectures, each generated instance of an instruction can have different behaviors, depending on how it's issued, its operand values, the functional unit it runs on, and the subtarget. So we provide a way to model those differences in reasonable ways.
+
+The MDL introduces the concept of a “subunit” to abstractly represent a class of instructions with the same behaviors. Subunit instances concretely connect instructions to descriptions of their behaviors, _and_ to the functional units that they can be issued on. A subunit is vaguely analogous to collections of SchedRead and SchedWrite resources.
+
+Naively, we could create unique subunits for each behavior for each instruction, the set of which would enumerate the cross-product of the instruction’s behaviors on every subtarget, functional unit, and issue slot. But subunits can be specialized by subtarget, functional unit, and each instruction definition, so a single subunit definition can properly describe behaviors for sets of instructions in many different contexts.
+
+A key aspect of this language design is that we can explicitly represent the potentially polymorphic behavior of each generated instance of any instruction, on any functional unit, on any subtarget. The representation also comprehends that this information can vary between each of an instruction’s instances.
+
+
+
+We define a subunit as an object that defines the _behavior sets_ of an instruction instance in all legal contexts (functional units, issue slots), for each subtarget. In particular, we want to know: \
+
+
+
+
+* What resources are shared or reserved, in what pipeline phases.
+ * Encoding resources
+ * Issue slot(s) used
+ * Functional unit resources
+ * Shared/private busses, register ports, resources, or pooled resources
+* What registers are read and written, in which pipeline phases (ie, the instruction’s “latencies”)
+* What additional register constraints does a functional unit instance impose on an instruction’s registers.
+
+The critical artifact generated by the MDL compiler is a set of instruction behaviors for each instruction definition. For each subtarget, for each instruction, we generate a list of every possible behavior of that instruction on that CPU. While this sounds daunting, in practice it's rare to have more than a few behaviors for an instruction, and most instruction definitions share their behaviors with many other instructions, across subtargets.
+
+
+### **Overview of a Processor Family Description**
+
+This document generally describes the language in a bottom up order - details first. But let's start with a brief tops-down overview of what a processor family description looks like, without going into details about each part.
+
+A minimal processor family description has the following components:
+
+
+
+* A set of CPU definitions - one for each subtarget.
+* A set of functional unit template definitions,
+* A set of subunit template definitions,
+* A set of latency template definitions.
+
+A CPU definition specifies a set of functional unit instances that define the processor, as well as pipeline descriptions, issue slot resources, and binding of functional units to issue slots. Each functional unit instance can be parameterized and specialized.
+
+A functional unit template specifies a set of subunits instances implemented by an instance of the functional unit. It can be parameterized and specialized for each instance in different CPUs.
+
+A subunit template abstractly defines a set of related operations that have similar behaviors. They specify these behaviors with a set of “latency” instances. They can also be parameterized and specialized for each instance in different functional unit templates. Subunits tie instruction definitions both to functional units on which they can execute, and instruction behaviors described in latency templates.
+
+A latency template defines the pipeline behavior of a set of instructions. It can be parameterized and specialized for each instance in a subunit instance. It is also specialized for each instruction that is tied to it (through a subunit). A latency rule, at a minimum, specifies when each operand is read and written in the execution pipeline.
+
+Here’s a very simple example of a trivial CPU, with three functional units, two issue slots, and a four-deep pipeline:
+
+
+```
+ cpu myCpu {
+ phases cpu { E1, E2, E3, E4 };
+ issue slot1, slot2;
+ func_unit FU_ALU my_alu1(); // an instance of FU_ALU
+ func_unit FU_ALU my_alu2(); // an instance of FU_ALU
+ func_unit FU_LOAD my_load(); // an instance of FU_LOAD
+ }
+
+ func_unit FU_ALU() { // template definition for FU_ALU
+ subunit ALU(); // an instance of subunit ALU
+ }
+ func_unit FU_LOAD() { // template definition for FU_LOAD
+ subunit LOAD(); // an instance of subunit LOAD
+ }
+
+ subunit ALU() { // template definition for ALU
+ latency LALU(); // an instance of latency LALU
+ }
+ subunit LOAD() { // template definition for LOAD
+ latency LLOAD(); // an instance of latency LLOAD
+ }
+
+ latency LALU() { // template definition for LALU
+ def(E2, $dst); use(E1, $src1); use(E1, $src2);
+ }
+ latency LLOAD() { // template definition for LLOAD
+ def(E4, $dst); use(E1, $addr);
+ }
+```
+
+
+A more complete description of each part of this description is provided in the section “Defining a Processor Family”.
+
+**Defining an ISA**
+
+We need to map a microarchitecture model back to LLVM instruction, operand, and register definitions. So, the MDL contains constructs for defining instructions, operands, registers, and register classes.
+
+When writing a target machine description, its not necessary to write descriptions for instructions, operands, and registers - we scrape all of this information about the CPU ISA from the tablegen output as part of the build process, and produce an MDL file which contains these definitions. The machine description compiler uses these definitions to tie architectural information back to LLVM instructions, operands, and register classes.
+
+We will describe these language features here, primarily for completeness.
+
+
+#### **Defining Instructions**
+
+Instruction definitions are scraped from tablegen files, and provide the following information to the MDL compiler for each instruction:
+
+
+
+* The instruction’s name (as defined in the td files)
+* Its operands, with the operand type and name provided in the order they are declared, and indicating whether each is an input or output of the instruction.
+* A set of “legal” subunit definitions (a “subunit” is described later in this document)
+* An optional list of instructions derived from this one.
+
+As in tablegen, an operand type must be either an operand name defined in the td description, a register class name defined in the td description, or simply a defined register name. If the operand type is a register name, the operand name is optional (and ignored) (these register operands are used to represent implied operands in LLVM instructions).
+
+Grammar:
+
+
+```
+ instruction_def : 'instruction' IDENT
+ '(' (operand_decl (',' operand_decl)*)? ')'
+ '{'
+ ('subunit' '(' name_list ')' ';' )?
+ ('derived' '(' name_list ')' ';' )?
+ '}' ';'? ;
+ operand_decl : ((IDENT (IDENT)?) | '...') ('(I)' | '(O)')? ;
+```
+
+
+An example:
+
+
+```
+ instruction ADDSWri(GPR32 Rd(O), GPR32sp Rn(I), addsub_shifted_imm32 imm(I), NZCV(O)) {
+ subunit(sub24,sub26);
+ }
+```
+
+
+This describes an ARM add instruction that has two defined input operands (Rn, imm), one defined output operand (Rd), and one implicit output operand (NZCV), which is associated with two subunits (sub24, sub26).
+
+
+#### **Defining Operands**
+
+Operand definitions are scraped from tablegen files (like instructions), and provide the following information to the MDL compiler for each operand:
+
+
+
+* The operand’s name,
+* Its sub-operands, with the operand type and operand name provided in the order they are declared. Note that operand names are optional, and if not present we would refer to these by their sub-operand id (0, 1, etc),
+* The operand’s value type.
+
+As in LLVM, an operand definition’s sub-operand types may in turn refer to other operand definitions. (Note that operand’s sub-operands are declared with the same syntax as instruction operands.)
+
+Grammar:
+
+
+```
+ operand_def : 'operand' IDENT
+ '(' (operand_decl (',' operand_decl)*)? ')'
+ '{' operand_type '}' ';'? ;
+```
+
+
+Some examples:
+
+
+```
+ operand GPR32z(GPR32 reg) { type(i32); }
+ operand addsub_shifted_imm32(i32imm, i32imm) { type(i32); }
+```
+
+
+
+#### **Defining Registers and Register Classes**
+
+Registers and register classes are scraped from tablegen output. We provide a general method in the language to define registers and classes of registers which can reflect the registers defined in tablegen.
+
+Grammar:
+
+
+```
+ register_def : 'register' register_decl (',' register_decl)* ';' ;
+ register_decl : IDENT ('[' range ']')? ;
+ register_class : 'register_class' IDENT
+ '{' register_decl (',' register_decl)* '}' ';'?
+ | 'register_class' IDENT '{' '}' ';'? ;
+```
+
+
+Examples:
+
+
+```
+ register a0, a1, a2, a3; // 4 registers
+ register a[4..7]; // definition of a4, a5, a6, and a7
+
+ register_class low3 { a0, a1, a2 }; // a class of 3 registers
+ register_class high5 { a[3..7] }; // a class of a3, a4, a5, a6, and a7
+```
+
+
+The order of register definitions is generally insignificant in the current MDL - we use the register names defined in LLVM, and there’s no cases in the MDL where we depend on order. Register “ranges”, such as “a[0..20]” are simply expanded into the discrete names of the entire range of registers.
+
+
+#### **Defining Derived Operands**
+
+LLVM doesn’t necessarily provide all the information we want to capture about an instruction, so the MDL allows for defining “derived” operands with which we can associate named values. A derived operand is essentially an alias to one or more LLVM-defined operands (or derived operands), and provides a mechanism to add arbitrary attributes to operand definitions. Derived operands also allow us to treat a set of operand types as identical in latency reference rules (so you don’t have to specify a long set of operand types for some references.)
+
+Grammar:
+
+
+```
+ derived_operand_def : 'operand' IDENT (':' IDENT)+ ('(' ')')?
+ '{' (operand_type | operand_attribute)* '}' ';'? ;
+ operand_attribute_stmt : 'attribute' IDENT '=' (snumber | tuple)
+ ('if' ('lit' | 'address' | 'label')
+```
+
+
+
+ ` ('[' pred_value (',' pred_value)* ']' )? )? ';' `;
+
+
+```
+ pred_value : snumber
+ | snumber '..' snumber
+ | '{' number '}' ;
+ tuple : '[' snumber (',' snumber)* ']' ;
+```
+
+
+
+##### **Derivation**
+
+Each derived operand is declared with one or more “base” operands, for which it is an alias. Circular or ambiguous derivations are explicitly disallowed - there must be only one derivation path for a derived operand to any of its base concrete operands.
+
+Derived operands are used in place of their base operands in operand latency rules in latency templates (described later). This allows a rule to match a set of operands, rather than a single operand, and also can provide access to instruction attributes to the latency rule.
+
+
+##### **Derived operand attributes**
+
+Derived operand attributes associate name/value-tuple pairs with the operand type. Tuples are appropriate when an attribute is used as a set of masks for resource sharing, described later.
+
+Some examples:
+
+
+```
+ attribute my_attr_a = 1;
+ attribute my_attr_b = 123;
+ attribute my_tuple = [1, 2, 3];
+```
+
+
+Attributes can have predicates that check if the operand contains a data address, a code address, or any constant. Additionally, attributes can have multiple definitions with different predicates, with the first “true” predicate determining the final value of the attribute for that operand instance:
+
+
+```
+ attribute my_attr = 5 if address; // if operand is a relocatable address
+ attribute my_attr = 2 if label; // if operand is a code address
+ attribute my_attr = 3 if lit; // if operand is any literal constant
+```
+
+
+Predicates for literal constants can also take an optional list of “predicate values”, where each predicate value is either an integer, a range of integers, or a “mask”. Mask predicate values are explicitly checking for non-zero bits:
+
+
+```
+ attribute my_attr = 5 if lit [1, 2, 4, 8]; // looking for specific values
+ attribute my_attr = 12 if lit [100..200]; // looking for a range of values
+ attribute my_attr = 1 if lit [{0x0000FFFF}]; // looking for a 16 bit number
+ attribute my_attr = 2 if lit [{0x00FFFF00}]; // also a 16-bit number!
+ attribute my_attr = 3 if lit [1, 4, 10..14, 0x3F800000, {0xFF00FF00}];
+```
+
+
+Note that we explicitly don’t directly support floating point numbers: this should be done instead with specific bit patterns or masks. This avoids problems with floating point precision and format differences across systems:
+
+
+```
+ attribute my_attr = 1 if lit [0xBF800000, 0x402DF854]; // -1.0, or pi
+ attribute my_attr = 2 if lit [{0x7FFF000}]; // +BF16 number
+```
+
+
+If all of an attribute’s predicates are “false” for an instance of an operand, the compiler recursively checks the attribute’s value in each of the operand’s bases until if finds a true predicate (or an unpredicated attribute):
+
+
+```
+ operand i32imm() { type(i32); } // scraped from llvm td file.
+
+ operand huge_imm : i32imm() {
+ attribute size = 3;
+ }
+ operand medium_imm : big_imm() {
+ attribute size = 2 if lit [-32768..32676];
+ }
+ operand small_imm : medium_imm() {
+ attribute size = 1 if lit [0-16];
+ }
+```
+
+
+
+##### **Derived operand attribute usage**
+
+There is currently only a single context in which instruction attributes are used directly in the machine description, as part of resource references in latency rules (see “latency\_resource\_ref”). In this context, you can specify an attribute name which provides the number of resources needed for a resource allocation, and the mask used to determine shared operand bits associated with the resource. An example:
+
+
+```
+ … my_resource:my_size_attribute:my_mask_attribute …
+```
+
+
+This resource reference uses the attributes from the operand associated with this reference to determine how many resources to allocate, and what bits in the operand to share.
+
+
+### **Overview of Resources**
+
+Resources are used to abstractly describe hardware constructs that are used by an instruction in its execution. They can represent:
+
+
+
+* functional units,
+* issue slots,
+* register ports,
+* shared encoding bits,
+* or can name any hardware resource an instruction uses when it executes that could impact the instruction’s behavior (such as pipeline hazards).
+
+Its important to note that different instances of an instruction can use completely different resources depending on which functional unit, and which subtarget, it's issued on. The MDL has an explicit way to model this.
+
+The machine description provides a mechanism for defining and associating resources with the pipeline behaviors of instructions through the specialization of functional unit templates, subunit templates, and latency templates. It also allows automatic allocation of shared resources for an instruction instance from resource pools. The MDL compiler generates behavior descriptions which explicitly reference each resource (or resource pool) the instruction uses, and in what pipeline phases. This provides a direct methodology for managing instruction issue and pipeline behaviors such as hazards.
+
+
+#### Defining Resources
+
+There are a few ways that resources are defined:
+
+
+
+* **Functional Units:** A resource is implicitly defined for every functional unit instance in a CPU definition. An instruction that executes on a particular instance will reserve that resource implicitly.
+* **Issue Slots: **Each CPU, or cluster of functional units in a CPU, can explicitly define a set of issue slots. For a VLIW, these resources directly correspond to instruction encoding slots in the machine instruction word, and can be used to control which instruction slots can issue to which functional units. For dynamically scheduled CPUs, these correspond to the width of the dynamic instruction issue.
+* **Named Resources** can be explicitly defined in several contexts, described below.
+* **Ports:** Ports are functional unit resources that model a register class constraint and a set of associated resources. These are intended to model register file ports that are shared between functional units.
+
+Explicitly defined resources have scope - they can be defined globally (and apply to all CPU variants), within a CPU, within a cluster, or within a functional unit template. Intuitively, shared resources are typically defined at higher levels in the machine description hierarchy. Resources and ports defined within a functional unit template are replicated for each instance of that functional unit. “Issue” resources are defined in CPU and cluster instances.
+
+Named resource definitions have the following grammar:
+
+
+```
+ resource_def : 'resource' ('(' IDENT ')')?
+ resource_decl (',' resource_decl)* ';' ;
+ resource_decl : IDENT (':' number)? ('[' number ']')?
+ | IDENT (':' number)? '{' name_list '}'
+ | IDENT (':' number)? '{' group_list '}' ;
+
+ port_def : 'port' port_decl (',' port_decl)* ';' ;
+ port_decl : IDENT ('<' IDENT '>')? ('(' resource_refs ')')? ;
+ issue_resource : 'issue' ('(' IDENT ')')? name_list ';' ;
+```
+
+
+
+##### Simple resource definitions
+
+The simplest resource definition is simply a comma-separated list of names:
+
+ **<code>resource name1, name2, name3;</code></strong>
+
+A resource can also have an explicit pipeline stage associated with it, indicating that the defined resources are always used in the specified pipeline phase:
+
+ **<code>resource(E4) name1, name2; // define resources that are always used in E4</code></strong>
+
+A resource can have a set of bits associated with it. This defines a resource that can be shared between two references if the bits in an associated operand reference are identical.
+
+ **<code>resource immediate:8; // define a resource with 8 bits of data</code></strong>
+
+
+##### Grouped resource definitions
+
+We can declare a set of named, related resources:
+
+ **<code>resource bits { bits_1, bits_2, bits_3 };</code></strong>
+
+A resource group typically represents a pool of resources that are shared between instructions executing in parallel, where an instruction may require one or all of the resources. This is a common attribute of VLIW architectures, and used to model things like immediate pools and register ports.
+
+Any defined resource can be included in a group, and the order of the members of a group is significant when members are allocated. If a group mentions an undefined resource (in either the current or enclosing scope), the member is declared as a resource in the current scope. In the case above, if the members (bits\_1, etc) are not declared, the compiler would create the definition:
+
+ **<code>resource bits_1, bits_2, bits_3;</code></strong>
+
+and the group members would refer to these definitions. (Note: we don’t support nested groups).
+
+The resource group can be referenced by name, referring to the entire pool, or by individual members, such as “bits.bits\_2” to specify the use of a specific pooled resource. Consider the following example:
+
+
+```
+ resource bits_1, bits_2, bits_3;
+```
+
+
+ **<code>resource bits_x { bits_1, bits_2, bits_3 };</code></strong>
+
+ **<code>resource bits_y { bits_3, bits_1, bits_2 };</code></strong>
+
+“bits\_x” and “bits\_y” are distinct groups that reference the same members, but members are allocated in a different order. Groups can also be defined with syntax that indicates how its members are allocated by default.
+
+ **<code>resource bits_or { bits_1 | bits_2 | bits_3 }; // allocate one of these</code></strong>
+
+ **<code>resource bits_and { bits_1 & bits_2 & bits_3 }; // allocate all of these</code></strong>
+
+Groups can also be implicitly defined in functional unit and subunit template instantiations as a resource parameter.
+
+ **<code>func_unit func my_fu(bits_1 | bits_2 | bits_3);</code></strong>
+
+This implicitly defines a resource group with three members, and passes that group as a parameter of the instance.
+
+
+##### Pooled resource definitions
+
+We can also declare a set of “unnamed” pooled resources:
+
+
+```
+ resource shared_bits[0..5];
+```
+
+
+This describes a resource pool with 6 members. The entire pool can be referenced by name (ie “shared\_bits”), or each member can be referenced by index (“shared\_bits[3]”), or a subrange of members (“shared\_bits[2..3]). A resource reference can also indicate that it needs some number of resources allocated with the syntax: shared\_bits:<number>.
+
+Resource pools can also have data associated with them, each member has its own set of bits:
+
+
+```
+resource bits:20 { bits_1, bits_2, bits_3 };
+resource shared_bits:5[6];
+```
+
+
+Resource pools, like resource groups, are used to model things like shared encoding bits and shared register ports, where instructions need one or more members of a set of pooled resources.
+
+Finally, resource definitions can pin a resource to a particular pipeline phase. All references to that resource will be automatically modeled only at that pipeline stage. This is particularly useful for modeling shared encoding bits (typically for resource pools). The syntax for that looks like:
+
+
+```
+ resource(E1) my_pool { res1, res2, res3 };
+```
+
+
+where E1 is the name of a pipeline phase. The resource “my\_pool” (and each of its elements) is always modeled to be reserved in pipeline phase E1.
+
+
+#### **Using Resources**
+
+Resource references appear in several contexts. They are used in all template instantiations to specialize architecture templates (functional units, subunit, or latency templates) and are ultimately used in latency rules to describe pipeline behaviors. These will be described later in the document.
+
+When used to specialize template instances, resource references have the following grammar:
+
+
+```
+ resource_ref : IDENT ('[' range ']')?
+ | IDENT '.' IDENT
+ | IDENT '[' number ']'
+ | IDENT ('|' IDENT)+
+ | IDENT ('&' IDENT)+ ;
+```
+
+
+Some examples of resource uses in functional unit instantiations, subunit instantiations, latency instantiations, and latency reference rules:
+
+
+```
+some_resource // reference a single resource or an entire group/pool
+some_resource_pool[1] // use a specific member from an unnamed pool.
+register_ports[6..9] // select a subset of unnamed pooled resources.
+group.xyzzy // select a single named item from a group.
+res1 | res2 | res3 // select one of these resources
+res6 & res7 & res8 // select all of these resources
+```
+
+
+References in latency reference rules have additional syntax to support the allocation of resources from groups and pools:
+
+
+```
+ latency_resource_ref : resource_ref ':' number (':' IDENT)?
+ | resource_ref ':' IDENT (':' IDENT)?
+ | resource_ref ':' ':' IDENT
+ | resource_ref ':' '*'
+ | resource_ref ;
+```
+
+
+
+##### **Allocating Grouped and Pooled Resources**
+
+Latency references allow you to optionally manage allocation of pooled resources, as well as specifying the significant bits of operands whose values can be shared with other instructions.
+
+A reference of the form:
+
+
+```
+ some_resource_pool:1
+```
+
+
+indicates that a reference needs one element from a group/pooled resource associated with a latency reference. A reference of the form:
+
+
+```
+ some_resource_pool:2
+```
+
+
+indicates that the reference needs 2 (or more) _adjacent_ elements from a pooled resource associated with a latency reference. A reference of the form:
+
+
+```
+ some_resource_pool:*
+```
+
+
+indicates that a reference needs _all _elements from a resource group or pool. Note that grouped resources can only use :1 and :\*.
+
+A reference of the form:
+
+ `some_resource_pool:size`
+
+indicates an operand reference that requires some number of resources from the resource pool. The number of resources needed is specified in the “size” attribute of the associated operand type. This enables us to decide at compile time how many resources to allocate for an instruction’s operand based on its actual value. For example, large operand constant values may require more resources than small constants, while some operand values may not require any resources. There’s a specific syntax for describing these attributes in derived operand definitions (described earlier).
+
+In the examples above, if the resource has shared bits associated with it (it’s shareable by more than one instruction), the entire contents of the operand are shared. In some cases, only part of the operand’s representation is shared, and we can can specify that with the following reference form:
+
+ `some_resource_pool:size:mask`
+
+This indicates that the associated operand’s “mask” attribute indicates which of the operand bits are sharable. Finally, we can use a share-bits mask without allocation:
+
+ `some_resource_pool::mask`
+
+This reference utilizes the resource - or an entire pool - and uses the operand’s “mask” attribute to determine which bits are shared with other references.
+
+We will describe how these references work when we describe latency rules.
+
+
+### **Defining a Processor Family**
+
+A TableGen description describes a family of processors, or subtargets, that share instruction and register definitions. Information about instruction behaviors are described with Schedules and Itineraries. The MDL also uses common instruction and register descriptions, scraped from TableGen, and adds first-class descriptions of CPUs, functional units, and pipeline modeling.
+
+In an MDL CPU description, a CPU is described as an explicit set of functional units. Each functional unit is tied to a set of subunits, and subunits are in turn explicitly tied to instruction definitions and pipeline behaviors. There are two approaches for associating subunits with functional units, and the choice of which one to use is dependent on the attributes of the architecture you’re describing:
+
+
+
+1. Subunit templates specify (either directly or through Latencies) which functional units they use, or
+2. You define functional unit templates that specify exactly which subunits they use.
+
+More detail on this below.
+
+
+#### **Method 1: SuperScalar and Out-Of-Order CPUs**
+
+Fully protected pipelines, forwarding, out-of-order issue and retirement, imprecise micro-operation modeling, and dynamic functional unit allocation make this class of
+
+CPUs difficult to model_ precisely._ However, because of their dynamic nature, precise modeling is both impossible and unnecessary. But it is still important to provide descriptions that enable scheduling heuristics to understand the relative temporal behavior of instructions.
+
+This method is similar to the way Tablegen “Schedules” associate instructions with a set of ReadWrite resources, which are in turn associated with sets of ProcResources (or functional units), latencies and micro-operations. This approach works well for superscalar and out-of-order CPUs, and can also be used to describe scalar processors.
+
+The upside of this method is that you don’t need to explicitly declare functional unit templates. You simply declare CPU instances of the functional units you want, and the MDL compiler creates implicit definitions for them.
+
+The downside of this method is that you can’t specialize functional unit instances, which in turn means you can’t specialize subunit instances, or associated latency instances. Fortunately, specialization generally isn’t necessary for this class of CPUs. It would also be difficult to use this method to describe a typical VLIW processor (which is why we have method 2!).
+
+We generally describe this as a “bottoms-up” approach (subunits explicitly tying to functional unit instances), and is the approach used by the Tablegen scraper (tdscan) for “Schedule-based” CPUs.
+
+
+#### **Method 2: VLIWs, and everything else**
+
+This method is appropriate for machines where we must provide more information about the detailed behavior of an instruction so that we can correctly model its issuing and pipeline behavior. It is particularly important for machines with deep, complex pipelines that _must_ be modeled by the compiler. It has a powerful, flexible user-defined resource scheme which provides a lot more expressiveness than either “Schedules” or “Itineraries”.
+
+In this method, a functional unit instance is an instantiation of an _issuing_ functional unit, which is more typical of scalar and VLIW CPUs. In the common case where different instances of a functional unit have different behaviors, we can easily model that using functional unit, subunit, and latency instance specialization, and more detailed latency rules.
+
+This approach allows a very high degree of precision and flexibility that's not available with method 1. Its strictly more expressive than the first method, but much of that expressiveness isn’t required by superscalar CPUs.
+
+We describe this as a “tops-down” approach (explicit functional unit template definitions
+
+assert which subunits they support). This is the method tdscan uses when scraping information about itineraries.
+
+
+#### **Schema of a Full Processor Family Description**
+
+ By convention, a description generally describes things in the following order (although the order of these definitions doesn’t matter):
+
+
+
+* Definition of the family name.
+* Describe the pipeline model(s).
+* Describe each CPU (subtarget) in terms of functional unit instances.
+* Describe each functional unit template in terms of subunit instances (tops-down approach)
+* Describe each subunit template type. A subunit represents a class of instruction definitions with similar execution behaviors, and ties those instructions to a latency description.
+* Describe each latency in terms of operand and resource references.
+
+We will describe each of these items in more detail. A machine description for a target has the following general schema: (a full syntax is provided in Appendix A)
+
+
+```
+ <family name definition>
+ <pipeline phase descriptions>
+ <global resource definitions>
+ <derived operand definitions>
+
+ // Define CPUs
+ cpu gen_1 {
+ <cpu-specific resource definitions>
+ <functional unit instance>
+ <functional unit instance>
+ …
+ }
+ cpu gen_2 { … }
+ …
+
+ // Define Functional Unit Template Definitions (Tops-down approach)
+ func_unit a_1(<functional unit parameters>) {
+ <functional-unit-specific resource and port definitions>
+ <subunit instance>
+ <subunit instance>
+ …
+}
+ func_unit b_1(…) { … }
+ …
+
+ // Define Subunit Template Definitions
+ subunit add(<subunit parameters>) {
+ <latency instance>
+ <latency instance>
+ …
+ }
+ subunit mul(…) { … }
+ …
+
+ // Latency Template Definitions
+ latency add(<latency parameters>) {
+ <latency reference>
+ <latency reference>
+ …
+ }
+ latency mul(…) { … }
+ …
+
+ // Instruction information scraped from Tablegen description
+ <register descriptions>
+ <register class descriptions>
+ <operand descriptions>
+ <instruction descriptions>
+```
+
+
+
+##### **Bottoms-up vs Tops-down CPU Definition Schemas \
+**
+
+In the “tops-down” schema, we define CPUs, which instantiate functional units, which instantiate subunits, which instantiate latencies. At each level of instantiation, the object (functional unit, subunit, latency) can be specialized for the context that it’s instantiated in. We think of this as a “top-down” definition of a processor family. We provide detailed descriptions for each functional unit template, which we can specialize for each instance.
+
+However, for many processors, this specialization is unnecessary, and the normal schema is overly verbose. For these kinds of processors, we can use the “bottoms-up” schema.
+
+In this schema, the MDL compiler _implicitly_ creates functional unit and latency templates:
+
+
+
+* A CPU definition specifies which functional units are used in the normal syntax.
+* Subunits directly implement latency rules inline (rather than instantiate a latency template), including an explicit functional unit instance that they can execute on.
+
+Here’s an example of this kind of bottom-up description:
+
+
+```
+ cpu dual_cpu {
+ func_unit ALU alu1(); // a "my_alu" functional unit, named "alu1"
+ func_unit ALU alu2(); // a "my_alu" functional unit, named "alu2"
+ }
+ subunit alu2() {{ def(E2, $dst); use(E1, $src); fus(ALU, 3); }}
+ subunit alu4() {{ def(E4, $dst); use(E1, $src); fus(ALU, 7); }}
+```
+
+
+ `subunit alu7() {{ def(E7, $dst); use(E1, $src); fus(ALU, 42); }}`
+
+Note that we don’t explicitly define the ALU functional unit template, but it is instantiated (twice) and used in three subunit/latency templates. Similarly, we don’t explicitly define the three latency templates. Both the functional unit template and the latency templates are implicitly created in the MDL compiler.
+
+While this schema is much more compact, neither the functional units nor the subunits/latencies can be specialized. This is an appropriate approach for scalar and superscalar processors, and is used by tdscan for CPUs that use Tablegen Schedules.
+
+
+#### **Specifying the Family Name**
+
+A family name must be specified that ties the description to the LLVM name for the processor family. It has the following grammar:
+
+
+```
+family_name : 'family' IDENT ';' ;
+```
+
+
+
+#### **Pipeline Definitions**
+
+We don’t explicitly define instruction “latencies” in the MDL. Instead, we specify when instructions’ reads and writes happen in terms of pipeline phases. From this, we can calculate actual latencies. Rather than specify pipeline phases with numbers, we provide a way of naming pipeline stages, and refer to those stages strictly by name. A pipeline description has the following grammar:
+
+
+```
+ pipe_def : protection? 'phases' IDENT '{' pipe_phases '}' ';'? ;
+ protection : 'protected' | 'unprotected' | 'hard' ;
+ pipe_phases : phase_id (',' phase_id)* ;
+ phase_id : '#'? IDENT ('[' range ']')? ('=' number)? ;
+```
+
+
+ For example:
+
+
+```
+phases my_pipeline { fetch, decode, read1, read2, ex1, ex2, write1, write2 };
+```
+
+
+We typically define these in a global phase namespace, and they are shared between CPU definitions. All globally defined phase names must be unique. However, each CPU definition can have private pipeline definitions, and names defined locally override globally defined names.
+
+You can define more than one pipeline, and each pipeline can have the attribute “protected”, “unprotected”, or “hard”. “Protected” is the default if none is specified.
+
+
+```
+protected phases alu { fetch, decode, ex1, ex2 };
+unprotected phases vector { vfetch, vdecode, vex1, vex2 };
+hard phases branch { bfetch, bdecode, branch };
+```
+
+
+A “protected” latency describes a machine where the hardware manages latencies between register writes and reads by injecting stalls into a pipeline when reads are issued earlier than their inputs are available, or resources are oversubscribed (pipeline hazards). Most modern general purpose CPUs have protected pipelines, and in the MDL language this is the default behavior.
+
+An “unprotected” pipeline never inserts stalls for read-after-writes or pipeline hazards. In this type of pipeline, reads fetch whatever value is in the register (in the appropriate pipeline phase). A resource conflict (hazard) results in undefined behavior (ie, the compiler must avoid hazards!). In this model, if an instruction stalls for some reason, the entire pipeline stalls. This kind of pipeline is used in several DSP architectures.
+
+A “hard” latency typically describes the behavior of branch and call instructions, whose side effect occurs at a particular pipeline phase. The occurrence of the branch or call always happens at that pipeline phase, and the compiler must accommodate that (by inserting code in the “delay slots” of the branch/call).
+
+You can define multiple stages as a group - the following rule is equivalent to the first example above.
+
+**<code>phases alu { fetch, decode, read[1..2], ex[1..2], write[1..2] };</code></strong> \
+
+
+Like C enumerated values, each defined name is implicitly assigned an integer value, starting at zero and increasing sequentially, that represents its integer stage id. You can explicitly assign values to pipeline phases, as in C, with the syntax “`phase=value`”. You can also explicitly assign sequential values to a range, by using the syntax `"name[2..5]=value`”.
+
+Finally, there is specific syntax to annotate the first “execute” phase in a pipeline spec, using the ‘#’ syntax:
+
+
+```
+phases my_pipeline { fetch, decode, #read1, read2, ex1, ex2, write1, write2 };
+```
+
+
+This indicates that “read1” is the first execute stage in the pipeline, which serves as the “default” phase for any operand that isn’t explicitly described in a latency rule.
+
+
+#### **CPU Definitions**
+
+In the definition of a single CPU/subtarget, we specify a high-level description of the processor:
+
+
+
+* CPU-specific resource definitions
+* Specification of issue slots and issue-slot usage.
+* Specialized instances of available functional units, and/or clusters of functional units.
+* CPU-specific pipeline definitions.
+
+Note that a CPU definition does not attempt to describe the pipeline behavior of functional units, but only specifies which functional units are implemented. The _behavior_ of functional units, and instructions that run on them, are explicitly described in the functional unit _templates._
+
+Grammar:
+
+
+```
+ cpu_def : 'cpu' IDENT ('(' STRING (',' STRING)* ')')?
+ '{' cpu_stmt* '}' ';'? ;
+ cpu_stmt : pipe_def
+ | resource_def
+ | reorder_buffer_def
+ | issue_statement
+ | cluster_instantiation
+ | func_unit_instantiation
+ | forward_stmt ;
+
+ reorder_buffer_def : 'reorder_buffer' '<' number '>' ';' ;
+
+ cluster_instantiation : 'cluster' IDENT '{' cluster_stmt+ '}' ';'? ;
+ cluster_stmt : resource_def
+ | issue_statement
+ | func_unit_instantiation
+ | forward_stmt ;
+
+ issue_statement : 'issue' '(' IDENT ')' name_list ';' ;
+
+func_unit_instantiation : 'func_unit' func_unit_instance func_unit_bases*
+ IDENT '(' resource_refs? ')'
+ ('->' (pin_one | pin_any | pin_all))? ';'
+
+func_unit_instance : IDENT ('<>' | ('<' number '>'))?
+ func_unit_bases : ':' func_unit_instance
+
+ pin_one : IDENT ;
+ pin_any : IDENT ('|' IDENT)+ ;
+ pin_all : IDENT ('&' IDENT)+ ;
+```
+
+
+The overall schema of a CPU definition looks like this:
+
+
+```
+ cpu gen_1 {
+ <cpu-specific resource definitions>
+ <cpu-specific issue definitions>
+ <cpu-specific pipeline definitions>
+ <cluster definition or functional unit instance>
+ <cluster definition or functional unit instance>
+ <optional forwarding info>
+ …
+ }
+```
+
+
+and a cluster definition has the schema:
+
+ `cluster xyz { `
+
+
+```
+ <cpu-specific resource definitions>
+ <cpu-specific issue definitions>
+ <functional unit instance>
+ <functional unit instance>
+ <optional forwarding info>
+ …
+ }
+```
+
+
+Below are some examples of increasingly complex CPU definitions.
+
+
+##### **Simple Scalar CPU Definition**
+
+In the simplest case, an empty CPU indicates a processor with no specific functional unit information. We assume a serial execution of instructions, with “default” latencies:
+
+
+```
+ cpu simplest_cpu { }
+```
+
+
+A single-alu CPU that has a scheduling model looks like this:
+
+
+```
+ cpu simple_cpu {
+ func_unit my_alu alu(); // a "my_alu" functional unit, named "alu"
+ }
+```
+
+
+A slightly more complex example is a CPU that is single-issue, but has more than one execution pipeline:
+
+
+```
+ cpu dual_alu_cpu {
+ issue slot0; // a single issue pipeline
+ func_unit my_alu alu1(); // a "my_alu" functional unit, named "alu1"
+ func_unit my_alu alu2(); // a "my_alu" functional unit, named "alu2"
+ }
+```
+
+
+
+##### **Multi-Issue CPUs**
+
+Here’s an example of a 2-issue processor with two identical functional units:
+
+
+```
+ cpu dual_issue_cpu {
+ func_unit my_alu alu1(); // a "my_alu" functional unit, named "alu1"
+ func_unit my_alu alu2(); // a "my_alu" functional unit, named "alu2"
+ }
+```
+
+
+Processors commonly have functional units with different capabilities - memory units, multipliers, floating point units, etc. The following is a four-issue CPU with 4 different types of functional units.
+
+
+```
+ cpu quad_cpu {
+ func_unit int_math imath(); // a "int_math" functional unit
+ func_unit float_math fmath(); // a "float_math" functional unit
+ func_unit memory mem(); // a "memory" functional unit
+ func_unit branch br(); // a "branch" functional unit
+ }
+```
+
+
+
+##### **Defining Issue Slots**
+
+Multi-issue CPUs always have a constrained set of instructions they can issue in parallel. For superscalar, OOO processors this is generally tied to the number of issue pipelines that are available. For VLIW, issue slots map directly to encoding bits in a parallel instruction. In the MDL, you can explicitly define issue slots. An example:
+
+
+```
+ cpu tri_cpu {
+ issue slot0, slot1;
+ func_unit my_alu alu1(); // a "my_alu" functional unit, named "alu1"
+ func_unit my_alu alu2(); // a "my_alu" functional unit, named "alu2"
+ func_unit my_alu alu3(); // a "my_alu" functional unit, named "alu3"
+ }
+```
+
+
+In this example, we have 3 functional units, but only two issue slots. So any of the three functional units can issue in either issue slot, but only two can be issued in parallel.
+
+When issue slots are not specified, each functional unit runs in its own dedicated issue slot.
+
+
+##### **Reservation of Issue Slots**
+
+In VLIW architectures (in particular), some functional units may be “pinned” to a specific set of issue slots, or use multiple issue slots in some cases. We provide syntax for specifying this:
+
+
+```
+ cpu three_issue_quad_cpu {
+ issue s0, s1, s2;
+ func_unit int_math alu1() -> s0; // alu1 must issue in s0
+ func_unit float_math alu2() -> s1 | s2; // alu2 must be in s1 or s2
+ func_unit memory alu3() -> s0 & s1; // alu3 uses both s0 and s1
+ func_unit branch br(); // branches can run in any slot
+ }
+```
+
+
+
+##### **SuperScalar and Out-Of-Order CPUs**
+
+In general, the overall approach for defining superscalar CPUs is quite different from other CPU types. This class of architecture requires information about the size of the reorder buffer, and details about queues for each functional unit. Actual functional unit utilization is described in latency or subunit rules, which can specify exactly which functional units are used.
+
+Functional units can be unreserved (like alu1, below), which means that an instruction or micro-operation that runs on that unit doesn’t actually use that specific resource. A functional unit can have a single-entry queue - in which case it is unbuffered - or a specific size queue.
+
+
+```
+ cpu three_issue_superscalar_cpu {
+ issue s0, s1, s2;
+ reorder_buffer<20>; // the reorder buffer is size 20
+ func_unit int_math<> alu1(); // alu1 is unreserved
+ func_unit float_math<10> alu2(); // alu2 has 10 queue entries
+ func_unit memory<20> alu3(); // alu3 has 20 queue entries
+ func_unit branch br(); // branch has a single entry
+ }
+```
+
+
+
+##### **Parameterized/Specialized Functional Unit Instances**
+
+A functional unit template can be parameterized with register classes and resource references so that each instance of that functional unit template can be specialized for a specific context. The actual use of these parameters is specified in the functional unit template, explained in the following sections. This section describes template specialization parameters.
+
+A **register class parameter** asserts that the functional unit instance may impose a register constraint on instructions that execute on it. This constraint is an addition to the register class constraints specified by an instruction’s operand definitions. This enables us to model functional units that are connected to a subset - or a partition - of a register file. It can also be used to describe functional-unit-local register files. Finally, it can disqualify instructions from running on a functional unit if they have register operands or operand constraints that are incompatible with the functional unit constraints.
+
+
+```
+ register r[0..31];
+ register_class ALL { r[0..31] };
+ register_class LOW { r[0..15] };
+ register_class HI { r[16..31] };
+
+ cpu my_cpu {
+ func_unit my_alu alu0(LOW); // instructions use r0..r15
+ func_unit my_alu alu1(HI); // instructions use r16..31
+ }
+ instruction add(ALL dst, ALL src1, ALL src2) { … }
+```
+
+
+A **resource parameter** indicates that instructions that execute on the functional unit may use that resource or a member of a resource pool. This is generally used to specify how shared resources are used across functional unit instances.
+
+
+```
+ cpu my_cpu {
+ resource shared_thing; // a single shared resource
+ resource reg_ports { p1, p2, p3 }; // three associated resources
+ resource shared_stuff[20]; // 20 associated resources
+
+ func_unit math alu0(shared_thing); // share a named resource
+ func_unit math alu1(reg_ports.p1); // share one member of a group
+ func_unit math alu2(shared_stuff[12]); // share one member of a pool
+
+ func_unit mem mem0(reg_ports); // share an entire group
+ func_unit mem mem1(shared_stuff); // share an entire pool
+ func_unit mem mem2(shared_stuff[3..14]); // share part of a pool
+ }
+```
+
+
+
+##### **Functional Unit Clusters**
+
+A processor definition can include named “clusters” of functional units. Each cluster can define local resources, and define its own issue rules. The purpose of clusters is primarily as a syntactic convenience for describing processors with functional unit clusters. An example:
+
+ **<code>cpu my_cpu {</code></strong>
+
+
+```
+ cluster A {
+ issue a, b;
+ func_unit my_alu alu1();
+ func_unit my_alu alu2();
+ func_unit my_alu alu3();
+ }
+ cluster B {
+ issue a, b;
+ func_unit my_alu alu1();
+ func_unit my_alu alu2();
+ func_unit my_alu alu3();
+ }
+ }
+
+
+```
+
+
+This describes a 4-issue machine, where 2 instructions can be issued on each cluster per cycle.
+
+
+##### **Defining Compound Functional Unit Instances**
+
+Its often convenient to define “compound” functional unit instances as collections that include 2 or more “component” units. A compound unit includes all the capabilities of its component units. Each component can specify its own reservation queue size.
+
+
+```
+ cpu compound_units {
+ Issue s0, s1, s2;
+ func_unit int_math<5>:load<6> alu1();
+ func_unit int_math<5>:store<3> alu2();
+ func_unit float_math<20>:branch<2> alu3();
+ func_unit misc<30> alu4();
+ }
+```
+
+
+This construct is similar to the “super-unit” concept in tablegen. Only one component of a compound functional unit can be used per cycle. In the above example, “alu3” is the only unit that supports floating point math or branches. Consequently those operations can’t be issued in parallel. Similarly, you can issue two integer math operations in parallel, but only if you’re not also issuing a load or store.
+
+Currently, we don’t support specialization parameters on compound functional unit instances. However, you can define functional unit templates with base units, and this provides similar capability.
+
+
+##### **Associating a CPU definition with an LLVM subtarget**
+
+A cpu definition can be directly associated with one or more LLVM subtargets, for example:
+
+ **<code>cpu SiFive7 ("sifive-7-series", "sifive-e76", "sifive-s76", "sifive-u74") { …</code></strong>
+
+At compile time, we can select which CPU definition to use based on normal target-selection command-line options.
+
+
+##### **Modeling Forwarding**
+
+Forwarding is modeled by describing a forwarding network between functional units. The necessity of the concept of a “forwarding” network implies that such networks aren’t fully connected or uniform.
+
+Grammar:
+
+
+```
+forward_stmt : 'forward' IDENT '->'
+ forward_to_unit (',' forward_to_unit)* ';' ;
+forward_to_unit : IDENT ('(' snumber ')')? ;
+```
+
+
+Example:
+
+
+```
+ forward my_alu -> my_adder(1), my_load(2);
+```
+
+
+In a forwarding specification, a unit name can be a functional unit instance name, a functional unit group name, or a functional unit template name. When using template or group names, all members of the group, or all instances of the specified template type, are implicitly referenced.
+
+For many processors, late functional unit assignment creates a phase-ordering problem in the compiler. Similarly, runtime functional unit assignment implies that we can’t necessarily know if a value will be forwarded or not. Unless we know with certainty the functional unit assignments for two instructions, we can’t always tell if there is a forwarding path between the two instructions.
+
+This isn’t necessarily a problem for downstream analysis tools, which work with fully scheduled code where all the functional units may have been determined by the compiler. There are several cases that we handle separately:
+
+Case 1: two instructions are both tied to specific functional units: in this case, we can fully determine whether forwarding is supported between the two functional units.
+
+Case 2: two instructions are tied to two sets of functional units (set A and set B) and all functional units in A are forwarded to all functional units in B. In this case, we can also determine whether forwarding is supported between the two instructions. (We don’t attempt to manage this today.)
+
+Case 3: Same as Case 2, but not all members of A are forwarded to B. In this case, the compiler could use a probability of forwarding, perhaps.
+
+Case 4: Same as Case 3, but there is no forwarding between A and B.
+
+Note that case 3 is quite common, and can be mitigated if the compiler uses a pass to pre-constrain the sets of functional units each instruction uses. This is quite common in compilers for clustered architectures - a pre-scheduling pass chooses a cluster for each instruction, which effectively constrains the functional units each instruction can run on, and often improves the chances for forwarding between instructions.
+
+Indeed the most common case currently modeled in tablegen files is a functional unit forwarding to itself or the superunit of itself, or a functional unit group forwarding to itself.
+
+In short, there are architectural cases that cannot be modeled precisely, and there are cases where we simply need a heuristic. We provide the hooks necessary for a compiler to provide the heuristic based on the existing model.
+
+Note: there is a philosophical question of whether we should provide best case or worst case latencies when the forwarding cannot be statically predicted. Generally, we believe that worst case latencies are better than best case latencies, simply because too-short latencies can produce code which occasionally (or always) stalls. On the other hand, overestimating the latency produces schedules where a pair of dependent instructions _tend _to be scheduled far enough apart to avoid stalls. In effect, schedulers will separate instructions by the requested latency only when there’s other useful work to do. Otherwise, there’s no reason to separate them - the stall is inevitable.
+
+
+#### **Functional Unit Template Definitions**
+
+A functional unit template describes, abstractly, what operations can be performed on any instance of the unit, and how those operations use the template parameters - register classes and resource references. An abstract set of operations is represented by a subunit instance, which represents a set of instructions with similar behavior in terms of functional unit usage, resource usage, and register classes. Functional unit templates are defined in their own private namespace.
+
+Functional unit templates are similar to C++ templates in that each instantiation in CPU definitions creates a specialized instance of the functional unit based on the template parameters - register classes and resources.
+
+For superscalar processors, it's not necessary to specify explicit templates for each functional unit used in a CPU description. The MDL compiler instantiates these automatically depending on how the functional units are referenced in latency templates, tying functional units automatically to their associated subunits. (The implication of this is that implicitly defined templates cannot be parameterized.)
+
+A functional unit template has the following grammar:
+
+
+```
+ func_unit_template : 'func_unit' IDENT base_list
+ '(' func_unit_params? ')'
+ '{' func_unit_template_stmt* '}' ';'? ;
+
+ func_unit_params : fu_decl_item (';' fu_decl_item)* ;
+ fu_decl_item : 'resource' name_list
+ | 'register_class' name_list ;
+
+ func_unit_template_stmt : resource_def
+ | port_def
+ | connect_stmt
+ | subunit_instantiation ;
+
+ port_def : 'port' port_decl (',' port_decl)* ';' ;
+ port_decl : IDENT ('<' IDENT '>')? ('(' resource_refs ')')? ;
+ connect_stmt : 'connect' IDENT
+ ('to' IDENT)? ('via' resource_refs)? ';' ;
+
+ subunit_instantiation : (name_list ':')? subunit_statement
+ | name_list ':' '{' subunit_statement* '}' ';'? ;
+
+ subunit_statement : 'subunit' subunit_instance (',' subunit_instance)* ';' ;
+ subunit_instance : IDENT '(' resource_refs? ')' ;
+```
+
+
+The general schema of a functional unit template looks like this: \
+
+
+
+```
+ func_unit a_1 [: <base_units>] (<functional unit parameters>) {
+ <functional-unit-specific resource and port definitions>
+ <subunit instance>
+ <subunit instance>
+ …
+}
+```
+
+
+
+##### **Simplest Functional Unit Template Definition**
+
+The simplest example of a functional unit template would define a functional unit that has no parameters, and implements a single subunit:
+
+ **<code>func_unit simple() {</code></strong>
+
+
+```
+ subunit xyzzy();
+}
+```
+
+
+In this case, any instruction that is defined to use the subunit “xyzzy” can run on this functional unit. This template doesn’t impose any additional constraints on those instructions, and no shared resources are used.
+
+
+##### **Defining Functional Unit Resources**
+
+A functional unit template can locally define resources which represent hardware resources tied to _each instance_ of the functional unit. These can be used to specialize subunit instances:
+
+ **<code>func_unit unit_with_local_resources() {</code></strong>
+
+
+```
+ resource my_resource;
+ resource my_pooled_resource[4];
+
+ subunit add(my_resource, my_pooled_resource[0..1]);
+ subunit subtract(my_resource, my_pooled_resource[2..3]);
+ subunit multiply(my_pooled_resource);
+}
+```
+
+
+In this example, the functional unit supports 3 classes of instructions (add, subtract, multiply), and passes slightly different local resources to each. Each instance of this functional unit has an independent set of resources (my\_resource, my\_pooled\_resource).
+
+Importantly: functional-unit-local resources which are used for multiple cycles can be used to model non-pipelined functional units - i.e.units which are reserved for some number of cycles.
+
+
+##### **Defining “Port” Resources**
+
+A port is a resource type that explicitly binds a named register class with a resource reference. A port is used to specialize subunit instances, and adding functional-unit-specific register constraints on instructions associated with the subunit.
+
+A port definition has the general form:
+
+ **<code>'port' <port_name> ('<' <register_class_name> '>')? ('(' resource_ref ')')? ;</code></strong>
+
+When a port is tied to more than one resource, any references to that port refer to all of the associated resources. Some examples:
+
+ **<code>port port_a <GPR>; // port_a tied to GPR regs</code></strong>
+
+
+```
+ port port_b <LOW> (res1); // port_b tied to LOW regs and res1
+ port port_c (pool[0..4]); // port_c tied to pool[0..4]
+```
+
+
+You can also use a “connect” statement to tie a port to register classes and resources:
+
+ **<code>'connect' <port_name> 'to' <register_class_name> 'via' resource_ref ;</code></strong>
+
+The following is equivalent to the above definition of “port\_b”:
+
+ **<code>port port_b;</code></strong>
+
+
+```
+connect port_b to LOW via res1;
+```
+
+
+This syntax could potentially be used to connect a port to more than one constraint/resource set, but this capability isn’t currently supported, and this syntax may be deprecated.
+
+Ports can be used to specialize subunit and latency instances, described in subsequent sections.
+
+
+##### **Using Template Parameters**
+
+Resource parameters can be used exactly like locally defined resources to specialize subunit instances. Register class parameters are used to define ports. Resource parameters can refer to a single resource, a pool of resources, or a group of resources.
+
+Here is an example subunit instance:
+
+
+```
+ subunit adder(res, porta, res2, portc);
+```
+
+
+The parameters refer to resources (or ports) defined in the functional unit, cluster, cpu, or globally. The resource parameters themselves can include constrained versions of the resources they refer to, in particular specifying a particular member or a subset of a pooled resource, for example:
+
+
+```
+ subunit load(pool1.member, pool2[5], pool3[2..4]);
+```
+
+
+A simple example of a full functional unit template definition:
+
+ **<code>func_unit specialized(resource shared_pool; class regs) {</code></strong>
+
+
+```
+ resource my_resource;
+ port my_port<regs> (shared_pool[3..5]);
+
+ subunit load(my_resource, my_port);
+ subunit store(my_port);
+}
+```
+
+
+
+##### **Conditional Subunit Instances**
+
+In a functional unit template, a subunit instance can be conditionally instantiated based on a predicate. Predicates are simply names of the instantiating cpu definition and functional unit instance. This allows us to specialize a functional unit instance based on how its instantiated, for example:
+
+ **<code>cpu my_cpu {</code></strong>
+
+
+```
+ func_unit my_func xyzzy();
+ func_unit my_func plugh();
+ }
+func_unit my_func() {
+ resource pooled_resource[4];
+ xyzzy: subunit add(pooled_resource[0..1]);
+ plugh: subunit add(pooled_resource[2..3]);
+}
+```
+
+
+
+##### **Using Base Functional Units**
+
+Functional units tend to get more capable over generations of a processor, so we’d like a way to derive functional units from other functional units. A functional unit template can be defined to have a base functional unit, for example:
+
+
+```
+ func_unit base_func() { … }
+ func_unit my_func : base_func() { … }
+```
+
+
+In this example, the template “my\_func” simply includes the definition of “base\_func” in its definition. In effect, anything “base\_func” can do, “my\_func” can do. The base functional unit definition must have the same leading parameters as the derived functional unit definition.
+
+In effect, when you instantiate a based functional unit, you implicitly instantiate its bases and any subbases. This language feature allows us to easily extend functional unit definitions over processor generations.
+
+
+##### **Defining functional unit groups**
+
+When defining a superscalar CPU, its generally not necessary to provide a functional unit template definition for each functional unit, since latency rules specify which functional units are used by a subunit. In this case, its helpful to be able to easily specify an arbitrary pool of functional units that can be used for an instruction. So the MDL has a way to do that.
+
+
+```
+ func_unit_group : 'func_group' IDENT ('<' number '>')? : name_list ;
+```
+
+
+For example:
+
+
+```
+ func_group MyGroup<42> member1, member2, member3;
+```
+
+
+This defines a functional unit group with 3 members, and a single input queue of length 42. These groups are used in latency rules to tie subunits to a pool of functional units.
+
+
+#### **Subunit Template Definitions**
+
+Subunits are used to link sets of instruction definitions to their pipeline behaviors and candidate functional units. Subunits appear in three contexts:
+
+
+
+* Each subunit template has a definition.
+* Functional unit templates instantiate subunits that they support.
+* Instructions can declare which subunits they are associated with. \
+
+
+A subunit definition abstractly represents a set of instruction definitions that logically have the same behaviors:
+
+
+
+* When operands are read and written
+* What resources are used/held/reserved
+* What functional units they can issue on
+* What issue slots and/or encoding bits they use
+* What subtargets are supported
+
+An instruction - or set of instructions - may behave differently between subtargets, and/or functional units, and/or issue slots. Subunit templates are therefore parameterized so that their instances can be specialized for the contexts in which they are instantiated, and they can in turn specialize their associated latency instantiations.
+
+A subunit template definition has the following grammar:
+
+
+```
+ subunit_template : 'subunit' IDENT su_base_list
+ '(' su_decl_items? ')'
+ (('{' subunit_body* '}' ';'?) |
+ ('{{' latency_items* '}}' ';'? )) ;
+
+ su_base_list : (':' (IDENT | STRING_LITERAL))* ;
+ su_decl_items : su_decl_item (';' su_decl_item)* ;
+ su_decl_item : 'resource' name_list
+ | 'port' name_list ;
+ subunit_body : latency_instance ;
+ latency_instance : (name_list ':')? latency_statement
+ | name_list ':' '{' latency_statement* '}' ';'? ;
+ latency_statement : 'latency' IDENT '(' resource_refs? ')' ';' ;
+```
+
+
+A subunit template has the following general schema:
+
+
+```
+ subunit add <base subunits> (<subunit parameters>) {
+ <latency instance>
+ <latency instance>
+ …
+ }
+```
+
+
+Latency instance instances (in subunit templates) have the following general forms:
+
+ **<code>latency <latency_name> ( <subunit parameters> );</code></strong>
+
+
+```
+ <predicate> : latency <latency_name> ( <latency parameters> );
+ <predicate> : { <latency statements> }
+```
+
+
+The optional predicate is a comma-separated list of names which refers to the CPU or functional unit the current subunit is instantiated in. This allows subunits to specify different latencies depending on the CPU or functional unit they are instantiated from. This is similar to the support in functional unit templates for conditional subunit instances. For example:
+
+
+```
+ cpu1, cpu3 : latency xyzzy(port1, port2, etc);
+ alu7: latency plugh(resource1, resource2, etc);
+```
+
+
+A subunit template can specify as many latency instances as needed - the resulting subunit is the union of all the valid latency templates. This allows you to separate different classes of behaviors into different latency templates. Since latency templates are also specialized, you can manage the separation in latencies. The typical practice is for a subunit to have a single latency instance.
+
+
+##### Subunit Template Parameters
+
+Subunit template parameters can be a mix of ports and resources, and are used to specialize a subunit for the context in which it is instantiated, for example:
+
+
+```
+ subunit add (resource A, B; port C) { … }
+```
+
+
+In general, these work exactly the same way functional unit templates are used. They can be used as latency parameters to specialize latency instances.
+
+
+##### Tying Instructions to Subunits
+
+There are two ways to associate subunits to instructions:
+
+
+
+* Instructions can specify which subunits they can run on, or
+* Subunits can specify which instructions they support.
+
+We discuss these two approaches below.
+
+
+###### Subunits in Instructions
+
+Subunits are associated with instruction definitions to...
+
+
+
+* Define each of their possible pipeline behaviors
+* Determine which functional units they can be issued on (if any!)
+* To provide functional-unit-specific register constraints to operand registers
+* To determine whether an instruction is valid for the selected architecture
+
+Each defined instruction must specify at least one subunit that it is bound to. This is done in tablegen by introduction of a Subunit attribute on each instruction (or instruction class) definition.
+
+We allow more than one subunit per instruction, which implies different instruction behaviors across CPUs or functional units. In general, this isn’t necessary, since a subunit can specify different behaviors for different functional units and/or CPUs. So this is strictly a stylistic choice.
+
+
+###### Subunit Bases
+
+A subunit template definition can have one or more “bases”. A base is either the name of another subunit, or a string representing a regular expression of instruction names. Bases tie a subunit to sets of instructions, either directly by instruction name, or transitively through their base subunits. A subunit does not need to have the same parameters as its bases, and does not inherit any latency information from its bases.
+
+This example ties the “add” subunit to any instruction with “ADD” as a name prefix, and also to any instructions tied to the “base\_add” subunit.
+
+
+```
+ subunit add : "ADD*" : base_add() {...}
+```
+
+
+Subunit bases provide an alternate way of tying instructions to subunits without modifying the instruction definitions (where each instruction can tie itself to a set of subunits). This effectively allows a single “base” subunit - and all of its associated instructions - to have different latency behaviors for each target.
+
+
+##### Shorthand Subunit Template Definitions
+
+Often a subunit template simply specifies a single latency template instance, and the latency template may only be used in a single subunit template. In that case, we have a shorthand that combines the latency template into the subunit template. For example:
+
+
+```
+subunit load(resource a, b, c) {
+ latency load(resource a, b, c);
+}
+latency load(resource a, b, c) { def(E1, $dst); use(E1, $src); … }
+```
+
+
+Can be alternatively expressed as:
+
+
+```
+subunit load(resource a, b, c) {{
+ def(E1, $dst); use(E1, $src); …
+}}
+```
+
+
+
+#### **Latency Template Definitions**
+
+A latency template specifies the detailed pipeline behavior for a class of instructions. The class of “client” instructions for a latency template is the set of instructions that use any subunit that instantiates the latency template.
+
+Latency templates are specialized for the exact context they are instantiated in - so they are statically polymorphic: a single latency template instantiated in many contexts can describe many different behavior sets for a single instruction depending on the CPU, the functional unit instance, subunit instance, the latency instance, and the instruction itself.
+
+Latency templates:
+
+
+
+* describe what happens at each stage of the execution pipeline in terms of register operands and resources used and reserved.
+* optionally imposes additional functional-unit-specific constraints on register operands.
+
+A latency template definition has the following general schema:
+
+ `latency <name> : base_latencies ( <parameters> ) {`
+
+
+```
+ <latency reference>
+ <latency reference>
+ …
+ }
+```
+
+
+Latency templates can be derived from other latencies, and take resources or ports as parameters. The body of the template is simply a set of latency references.
+
+The full grammar:
+
+
+```
+ latency_template : 'latency' IDENT base_list
+ '(' su_decl_items? ')'
+ '{' latency_items* '}' ';'? ;
+ latency_items : latency_refs
+ | micro_ops_statement ;
+ latency_refs : (name_list ':')?
+ (latency_item | ('{' latency_item* '}' ';'?)) ;
+ latency_item : latency_ref
+ | conditional_ref
+ | fus_statement ;
+
+ conditional_ref : 'if' IDENT '{' latency_item* '}'
+ (conditional_elseif | conditional_else)? ;
+ conditional_elseif : 'else' 'if' IDENT '{' latency_item* '}'
+ (conditional_elseif | conditional_else)? ;
+ conditional_else : 'else' '{' latency_item* '}' ;
+
+ latency_ref : ref_type '(' latency_spec ')' ';' ;
+ ref_type : ('use' | 'def' | 'usedef' | 'kill' |
+ 'hold' | 'res' | 'predicate' | 'fus') ;
+ latency_spec : expr (':' number)? ',' latency_resource_refs
+ | expr ('[' number (',' number)? ']')? ',' operand
+ | expr ',' operand ',' latency_resource_refs ;
+ expr : '-' negate=expr
+ | expr ('*' | '/') expr
+ | expr ('+' | '-') expr
+ | '{' expr '}'
+ | '(' expr ')'
+ | IDENT
+ | number
+ | operand ;
+
+ fus_statement : 'fus' '(' (fus_item ('&' fus_item)* ',')?
+ snumber (',' fus_attribute)* ')' ';'
+
+ fus_item : IDENT ('<' (expr ':')? number '>')? ;
+ fus_attribute : 'BeginGroup' | 'EndGroup' | 'SingleIssue'
+ | 'RetireOOO' ;
+
+ latency_resource_refs : latency_resource_ref (',' latency_resource_ref)* ;
+ latency_resource_ref : resource_ref ':' number (':' IDENT)?
+ | resource_ref ':' IDENT (':' IDENT)?
+ | resource_ref ':' ':' IDENT // no allocation
+ | resource_ref ':' '*' // allocate all
+ | resource_ref ;
+ operand : (IDENT ':')? '$' IDENT ('.' operand_ref)*
+ | (IDENT':')? '$' number
+ | (IDENT':')? '$$' number
+
+ operand_ref : (IDENT | number) ;
+```
+
+
+
+##### **Derived Latency Templates**
+
+A latency template can be derived from one or more base latency templates. Any hierarchy is allowed (except recursive), as long as the base template has the exact same leading parameters as the derived latency. A base latency can be included more than once in the hierarchy - this doesn’t matter, since all occurrences of that base are identical (so duplicates are ignored):
+
+
+```
+ latency base1 (resource a) { … }
+ latency base2 (resource a, b) { … }
+ latency base3 : base1 (resource a) { … }
+ latency my_latency : base2 : base3(resource a, b, c) { … }
+```
+
+
+In this example, my\_latency includes base1, base2, and base3. Deriving latency templates is a fairly common pattern: instruction classes often share _some_ behaviors, but not all. So those shared behaviors can be put in a base latency template. A common example is an instruction predicate, perhaps shared by all instructions.
+
+
+##### **Latency References**
+
+A latency reference statement describes a single operand reference and/or resource references in a specified pipeline stage. It references instruction operands _by name, _as well as resource and port parameters, and ties the operations to named pipeline phases.
+
+Latency references have the following general form:
+
+
+```
+<operator> (<phase expression>, <operand specifier>, <ports/resources>);
+```
+
+
+where either the operand specifier or ports/resources may be omitted. A single reference statement asserts that an operand and resources are referenced in a specific pipeline phase for any instruction that this rule could apply to, ie: _any instruction that uses a subunit that instantiates this latency template._ Each aspect of a latency reference are described below.
+
+
+###### **Operand and resource latency operators:**
+
+There are 6 basic operator types in a latency reference:
+
+
+
+* use - read a register, and/or use a resource
+* def - write a register, and optional use of a resource
+* predicate - specifies which register operand is an instruction predicate
+* reserve - reserve a resource until a specific pipeline stage.
+* hold - hold issue until a resource is available for reservation.
+* fus - reserve a functional unit for a specified number of cycles, and/or a specified number of micro-ops needed for the instruction.
+
+There are 3 additional operator types which are primarily used as shortcuts (these are currently parsed, but unimplemented in the llvm integration):
+
+
+
+* usedef - a use and a def of an operand (a shorthand syntax)
+* kill - the register value is wiped and no value is defined (typically used in call instructions)
+* or - this is essentially a conditional def, but the instruction has no explicit predicate (useful for status-setting instructions).
+
+
+###### **Phase Expressions**
+
+The phase expression specifies the pipeline phase that the operation occurs in. The expression can refer directly to a defined phase name, or an expression based on a phase name:
+
+
+```
+ use(E7, $operand, res); // use operand and res in cycle E7
+ use(E7+5, $operand, res); // use operand and res in cycle E7+5
+```
+
+
+An instruction may perform a reference at a cycle which is a function of immediate operands of the instruction instance. For example:
+
+
+```
+ use(E1 + $width - 12, $operand, res);
+```
+
+
+where “$width” is an immediate instruction operand. Its value is fetched from the instruction instance and used in the expression. As with any operand specifier, if the client instruction doesn’t have an immediate operand named “width”, the rule is ignored for that instruction.
+
+Phase expressions have a limited set of operators: +, -, \*, /, (). Since latencies must be positive integers, we also provide a “floor” operator which converts negative expressions to 0. Simply enclose the expression in curly braces ({...}).
+
+
+###### **Operand Specifiers**
+
+The operand specifier has the same grammar as in tablegen, which allows you to specify an optional operand type, the operand name, and optional sub-operand names:
+
+
+```
+ operand : (IDENT ':')? '$' IDENT ('.' operand_ref)*
+ | (IDENT':')? '$' number
+ | (IDENT':')? '$$' number
+
+ operand_ref : (IDENT | number) ;
+```
+
+
+Operand specifiers act as predicates for the validity of a reference for a particular instruction. Some examples:
+
+
+```
+ GPR:$dst // an operand named "dst" with operand type GPR
+ ADR:$dst // an operand named "dst" with operand type ADR
+ $dst // an operand named "dst", with any operand type
+```
+
+
+` opnd:$src.reg // an operand named "src", type "opnd", suboperand "reg"`
+
+Because a latency could be specialized for many instructions which have different sets of operands, the operand specifier acts as a predicate for the application of a reference to a particular instruction. When the operand isn’t present in a client instruction, the latency reference is ignored for that instruction. For example, you can differentiate on operand type:
+
+
+```
+ def(E5, GPR:$dst);
+ def(E7, FPR:$dst);
+```
+
+
+In this example, instructions with a GPR dst operand write their results in cycle E5, while instructions with an FPR dst operand write their results in cycle E7.
+
+Or you can differentiate based on the operand name:
+
+
+```
+ use(E2, $src1); // most instructions have at least one src opnd
+ use(E3, $src2); // some instructions have 2 source operands
+```
+
+
+` use(E4, $src3); // and some instructions have 3!` \
+
+
+Note that operands _can _be referenced by their index in an instruction’s operand list, but this is error-prone and this isn’t considered best practice because we can’t thoroughly check the validity of the index. The syntax is simply “$<index>”. Note that sub-operands often aren’t given names in tablegen, and must be referenced by index, for example: $src.1. Unnamed variant operands (obviously) don’t have names, and are referenced by their position past the end of the operands defined for an instruction, ie “$$1”, “$$2”, etc.
+
+
+###### **Resource References**
+
+Any latency reference can include an optional set of resource references. These have slightly different semantics depending on the operator type (def/use/predicate/hold/reserve).
+
+For “use”, “def”, and “predicate” statements, a set of resource references can be specified that are associated with the operand reference. As with all latency references, the operand must match an operand of the client instruction. If the reference is valid, the resource is “used” - for any of these operators - at the pipeline phase specified, unless the resource was defined with a specific phase. The “use” of the resource is equivalent to a single-cycle hold/reserve of that resource. Some examples:
+
+
+```
+ use(E1, $src, my_res); // use "my_res" at cycle E1
+ def(E32, $dst, my_res); // use "my_res" at cycle E32
+```
+
+
+For “hold” and “reserve” operations, the operand specifier is optional, and if present serves _only _as a predicate that indicates whether the reference is valid or not. However, at least one resource reference is required for these statements. A few examples:
+
+
+```
+ hold(E1, my_res); // hold issue at E1 until resources are available
+ res(E32, $dst, my_res); // reserve resources up to cycle E32
+```
+
+
+
+##### **Conditional References**
+
+Any reference in a latency rule can be conditional, using a predicate identifier. The predicates are generally identical to LLVM predicates, and check an attribute of a client instruction.
+
+Conditional references can be nested, for arbitrarily complex references. These have the following general form:
+
+
+```
+if <predicate_name> { <set of refs> }
+else if <predicate_name> { <set of refs> }
+else { <set of refs> }
+```
+
+
+
+##### **Functional Unit and Micro-op References**
+
+A latency rule can directly specify a set of functional units and how long they are used, as well as specifying the number of micro-ops required for the operation. Each functional unit can optionally specify a pipeline “StartAt” cycle, which by default is the first execution phase.
+
+
+```
+ fus(13); // Instruction has 13 micro-operations.
+fus(ALU, 2); // use ALU for 1 cycle, 2 micro-operations.
+ fus(ALU<3>, 1); // use ALU for 3 cycles, 1 micro-operation.
+ fus(ALU<E5:4>, 1); // use ALU starting at E5 for 4 cycles.
+ fus(ALU1<12>&ALU2<E12:30>&LOAD<E42:2>); // use ALU1, ALU2, and LOAD
+```
+
+
+These statements allow a latency rule (or subunit) to tie a set of instructions to functional unit instances. When there is more than one instance of the specified unit, or if the unit is declared to be a functional unit group, at compile time _one_ of those units is selected. Likewise, if the unit is a subunit of one or more functional units, one of the “parent” functional units is selected.
+
+
+### **Machine Description Compiler Artifacts**
+
+What does all of this produce?
+
+The primary artifact of the MDL compiler is a set of data that we associate with each instruction description in a targeted compiler. For each instruction, at compiler-build time we produce a list of objects, each of which describe that instruction’s behavior on a single functional unit instance. The instruction will have one of these objects for each functional unit instance that it can be scheduled on across all CPUs. These are written out as a set of auto-initialized collections of objects that are attached to instruction templates in the target compiler.
+
+Each of these objects describe the behavior of each instruction cycle by cycle:
+
+
+
+* What operand’s registers it reads and write,
+* What register constraints are applied to operands,
+* What resources it uses, holds on, or reserves.
+* What explicit functional unit and issue slots it uses.
+* What pooled resources need to be allocated.
+
+The other primary artifact is a set of objects and methods for managing the low-level details of instruction scheduling and register allocation. This includes methods to build and manage resource pools, pipeline models, resource reservation infrastructure, and instruction bundling, all specialized for the input machine description.
+
+As part of this effort, we will incrementally modify the LLVM compiler to alternatively use this information alongside of SchedMachineModel and Itinerary methodologies.
+
+
+
+<p id="gdcalert1" ><span style="color: red; font-weight: bold">>>>> GDC alert: inline image link here (to images/image1.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert2">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>> </span></p>
+
+
+
+
+
+
+### **Using the MDL Language in LLVM**
+
+The proposed use case for the MDL language is as an alternative specification for the architecture description currently embodied in TableGen Schedules and Itineraries, particularly for architectures for which Schedules and Itineraries are not expressive enough. It is explicitly _not_ the intent that it “replace TableGen”. But we believe that the MDL language is a better language (vs Schedules and Itineraries) for a large class of accelerators, and can be used effectively alongside TableGen.
+
+We’ve written a tool (TdScan) which extracts enough information from TableGen descriptions so that we can sync instruction definitions with architecture definitions. TdScan can also optionally scrape all of the Schedule and Itinerary information from a tablegen description and produce an equivalent\*\* MDL description.
+
+So there are several possible MDL usage scenarios:
+
+
+
+* _Current: _Given a complete tablegen description with schedules or itineraries, scrape the architecture information and create an MDL description of the architecture every time you build the compiler.
+* _Transitional: _Scrape an existing tablegen description and keep the generated MDL file, using it as the architecture description going forward.
+* _Future (potentially): _when writing a compiler for a new architecture, write an MDL description rather than schedules and/or itineraries.
+
+The general development flow of using an MDL description in LLVM looks like this:
+
+
+
+1. Write an architecture description (or scrape one from an existing tablegen description).
+ 1. Instructions, operands, register descriptions in .td files
+ 2. Microarchitecture description in .mdl files
+2. Compile TD files with TableGen
+3. Use TdScan to scrape instruction, operand, and register information from tablegen, producing a .mdl file
+4. Compile the top-level MDL file (which includes the scraped Tablegen information). This produces C++ code for inclusion in llvm.
+5. Build LLVM.
+
+
+
+<p id="gdcalert2" ><span style="color: red; font-weight: bold">>>>> GDC alert: inline image link here (to images/image2.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert3">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>> </span></p>
+
+
+
+
+
+
+#### **TdScan**
+
+To synchronize an MDL architecture description with llvm TableGen descriptions, we’ve written a tool which scrapes information that the MDL compiler needs from Tablegen files. In the general case, it collects basic information about registers, register classes, operands, and instruction definitions, and it produces an “mdl” file which can be processed by the MDL compiler to sync an architecture description to the tablegen descriptions of instructions.
+
+For currently upstreamed targets that use Schedules or Itineraries, TdScan can also extract the whole architecture specification from the tablegen files, and produce an MDL description of the architecture. We’ve used this approach to prove out our llvm integration with upstreamed targets. The integration and testing of this is ongoing.
+
+
+#### **Upstream Targets**
+
+In general, upstream targets have no compelling need for MDL descriptions - the existing Schedules and/or Itinerary descriptions are field tested. However, there are a few benefits to using an MDL description for existing targets. The primary benefit is that the MDL descriptions are typically quite a bit smaller, succinct, and (we believe) intuitive than the equivalent TableGen descriptions.
+
+
+<table>
+ <tr>
+ <td><strong>CPU</strong>
+ </td>
+ <td><strong>MDL Lines of Code</strong>
+ </td>
+ <td><strong>Tablegen Lines of Code</strong>
+ </td>
+ </tr>
+ <tr>
+ <td><strong>AArch64</strong>
+ </td>
+ <td>3927/4877
+ </td>
+ <td>28612
+ </td>
+ </tr>
+ <tr>
+ <td><strong>AMDGPU</strong>
+ </td>
+ <td>530/512
+ </td>
+ <td>440
+ </td>
+ </tr>
+ <tr>
+ <td><strong>ARM</strong>
+ </td>
+ <td>3486/3853
+ </td>
+ <td>10352
+ </td>
+ </tr>
+ <tr>
+ <td><strong>Hexagon</strong>
+ </td>
+ <td>3061/3061
+ </td>
+ <td>18743
+ </td>
+ </tr>
+ <tr>
+ <td><strong>Lanai</strong>
+ </td>
+ <td>54/54
+ </td>
+ <td>69
+ </td>
+ </tr>
+ <tr>
+ <td><strong>Mips</strong>
+ </td>
+ <td>874/967
+ </td>
+ <td>3003
+ </td>
+ </tr>
+ <tr>
+ <td><strong>PowerPC</strong>
+ </td>
+ <td>5103/5442
+ </td>
+ <td>4105
+ </td>
+ </tr>
+ <tr>
+ <td><strong>RISCV</strong>
+ </td>
+ <td>305/374
+ </td>
+ <td>3231
+ </td>
+ </tr>
+ <tr>
+ <td><strong>Sparc</strong>
+ </td>
+ <td>273/273
+ </td>
+ <td>123
+ </td>
+ </tr>
+ <tr>
+ <td><strong>SystemZ</strong>
+ </td>
+ <td>1643/1524
+ </td>
+ <td>9224
+ </td>
+ </tr>
+ <tr>
+ <td><strong>X86</strong>
+ </td>
+ <td>7263/9237
+ </td>
+ <td>30815
+ </td>
+ </tr>
+</table>
+
+
+\*\* Note: the MDL numbers are generated both with and without “index-based” references in subunit/latency rules, vs symbolic references. These are typically 10-20% less lines of MDL description than when operand names are used, almost entirely due to operand name differences between instruction definitions (like “dest” vs “dst”, or “src1” vs “s1”). However, the databases produced by the two approaches are virtually identical - albeit ordered differently.
+
+
+#### **Syncing Instruction Information**
+
+The MDL compiler needs 3 pieces of information from tablegen for each machine instruction:
+
+
+
+1. The instruction opcode name
+2. Each operand’s name, type, and order of appearance in an instruction instance
+3. The name(s) of the subunit(s) it can run on.
+
+Subunits are a new concept introduced with the MDL. The normal approach is to modify each tablegen instruction description to explicitly specify subunit assignments, which become an additional instruction attribute. The other approach is to use subunit template bases to use regular expressions to tie instructions to subunits (just like InstRW records).
+
+As part of the build process, we use a program (“tdscan”) which scrapes the instruction information - including the subunit information from a target’s tablegen files and generates information about the target’s instructions. Tdscan allows us to stay in sync with changes to instruction definitions.
+
+
+#### **Using the generated microarchitecture information in LLVM**
+
+There are two classes of services that the MDL database and associated APIs provide:
+
+
+
+* Detailed pipeline modeling for instructions (for all processors, for all functional units) including instruction latencies calculations and resource usage (hazard management)
+* Parallel instruction bundling and instruction scheduling.
+
+The tablegen scraper (tdscan) can correctly scan all upstreamed targets and generate correct instruction, operand, and register class information for all of them.
+
+We can also extract high-level architecture information and generate correct MDL descriptions for all the upstreamed targets that have Schedules or Itineraries (AArch64, AMDGPU, AMD/R600, ARM, Hexagon, Lanai, Mips, PPC, RISCV, Sparc, SystemZ, X86). Usually, the new architecture spec is dramatically simpler than the tablegen descriptions.
+
+We provide code and libraries to do the following things - in machine-independent ways:
+
+
+
+* Calculate accurate instruction latencies.
+* A set of APIs to build and manage instruction bundles (parallel instructions), performing all the required legality checks and resource allocation based on information in the generated database.
+* Manage resource reservations and hazard management for an instruction scheduler.
+* Determine latencies between instructions based on resource holds and reservations.
+* Methods to query functional unit, issue slot, and resource assignments for a bundled/scheduled instruction.
+* Methods to query the set of all register uses and defs for an instruction instance, with accurate timing information.
+* Manage functional unit register forwarding.
+
+There’s more we can do here, and a deeper integration with upstreamed LLVM is a long-term goal.
+
+
+#### **Current Status of the LLVM Integration (briefly)**
+
+
+
+* We can generate MDL full architecture specs for all upstreamed targets, and properly represent and use all metadata associated with Schedules and Itineraries.
+* We’ve integrated the MDL methodology into LLVM’s build flow, so that you can select whether or not to include it at build time.
+* The MDL database is (optionally, under command line control) used to properly calculate instruction latencies for all architectures. Caveat: we don’t yet fully convert Itinerary and Schedule forwarding information, since the LLVM model for forwarding is fundamentally different from the MDL model, and the provided information is typically incomplete.
+* We’ve integrated the MDL-based bundle-packing and hazard management into all the LLVM schedulers, with the exception of the Swing scheduler, which is still in progress.
+* We’ve run all the standard tests, passing all but 190 (out of 93007 tests), with any performance deltas in the noise.
+
+
+
+
+### **Appendix A: Full Language Grammar**
+
+This may be slightly out of date. The definitive Antlr4-based grammar is in llvm/utils/MdlCompiler/mdl.g4.
+
+
+```
+architecture_spec : architecture_item+ EOF ;
+architecture_item : family_name
+ | cpu_def
+ | register_def
+ | register_class
+ | resource_def
+ | pipe_def
+ | func_unit_template
+ | func_unit_group
+ | subunit_template
+ | latency_template
+ | instruction_def
+ | operand_def
+ | derived_operand_def
+ | import_file
+ | predicate_def ;
+
+import_file : 'import' STRING ;
+
+family_name : 'family' IDENT ';' ;
+
+//---------------------------------------------------------------------------
+// Top-level CPU instantiation.
+//---------------------------------------------------------------------------
+cpu_def : 'cpu' IDENT ('(' STRING (',' STRING)* ')')?
+ '{' cpu_stmt* '}' ';'? ;
+
+cpu_stmt : pipe_def
+ | resource_def
+ | reorder_buffer_def
+ | issue_statement
+ | cluster_instantiation
+ | func_unit_instantiation
+ | forward_stmt ;
+
+cluster_instantiation : 'cluster' IDENT '{' cluster_stmt+ '}' ';'? ;
+
+cluster_stmt : resource_def
+ | issue_statement
+ | func_unit_instantiation
+ | forward_stmt ;
+
+issue_statement : 'issue' '(' IDENT ')' name_list ';' ;
+
+func_unit_instantiation : 'func_unit' func_unit_instance func_unit_bases*
+ IDENT '(' resource_refs? ')'
+ ('->' (pin_one | pin_any | pin_all))? ';'
+
+func_unit_instance : IDENT ('<>' | ('<' number '>'))?
+func_unit_bases : ':' func_unit_instance
+
+pin_one : IDENT ;
+pin_any : IDENT ('|' IDENT)+ ;
+pin_all : IDENT ('&' IDENT)+ ;
+
+//---------------------------------------------------------------------------
+// A single forwarding specification (in CPUs and Clusters).
+//---------------------------------------------------------------------------
+forward_stmt : 'forward' IDENT '->'
+ forward_to_unit (',' forward_to_unit)* ';' ;
+forward_to_unit : IDENT ('(' snumber ')')? ;
+
+//---------------------------------------------------------------------------
+// Functional unit template definition.
+//---------------------------------------------------------------------------
+func_unit_template : 'func_unit' IDENT base_list
+ '(' func_unit_params? ')'
+ '{' func_unit_template_stmt* '}' ';'? ;
+
+func_unit_params : fu_decl_item (';' fu_decl_item)* ;
+fu_decl_item : 'resource' name_list
+ | 'register_class' name_list ;
+
+func_unit_template_stmt : resource_def
+ | port_def
+ | connect_stmt
+ | subunit_instantiation ;
+
+port_def : 'port' port_decl (',' port_decl)* ';' ;
+port_decl : IDENT ('<' IDENT '>')? ('(' resource_ref ')')? ;
+connect_stmt : 'connect' IDENT
+ ('to' IDENT)? ('via' resource_ref)? ';' ;
+
+//---------------------------------------------------------------------------
+// Functional unit group definition.
+//---------------------------------------------------------------------------
+func_unit_group : FUNCGROUP IDENT ':' name_list ';' ;
+
+//---------------------------------------------------------------------------
+// Definition of subunit template instantiation.
+//---------------------------------------------------------------------------
+subunit_instantiation : (name_list ':')? subunit_statement
+ | name_list ':' '{' subunit_statement* '}' ';'? ;
+
+subunit_statement : 'subunit' subunit_instance (',' subunit_instance)* ';' ;
+subunit_instance : IDENT '(' resource_refs? ')' ;
+
+//---------------------------------------------------------------------------
+// Definition of subunit template definition.
+//---------------------------------------------------------------------------
+subunit_template : 'subunit' IDENT su_base_list '(' su_decl_items? ')'
+ (('{' subunit_body* '}' ';'?) |
+ ('{{' latency_items* '}}' ';'? )) ;
+
+su_decl_items : su_decl_item (';' su_decl_item)* ;
+su_decl_item : 'resource' name_list
+ | 'port' name_list ;
+
+su_base_list : (':' (IDENT | STRING_LITERAL))* ;
+
+subunit_body : latency_instance ;
+latency_instance : (name_list ':')? latency_statement
+ | name_list ':' '{' latency_statement* '}' ';'? ;
+latency_statement : 'latency' IDENT '(' resource_refs? ')' ';' ;
+
+//---------------------------------------------------------------------------
+// Latency template definition.
+//---------------------------------------------------------------------------
+latency_template : 'latency' IDENT base_list
+ '(' su_decl_items? ')'
+ '{' latency_items* '}' ';'? ;
+
+latency_items : (name_list ':')?
+ (latency_item | ('{' latency_item* '}' ';'?)) ;
+
+latency_item : latency_ref
+ | conditional_ref
+ | fus_statement ;
+
+//---------------------------------------------------------------------------
+// Conditional references
+//---------------------------------------------------------------------------
+conditional_ref : 'if' IDENT '{' latency_item* '}'
+ (conditional_elseif | conditional_else)? ;
+conditional_elseif : 'else' 'if' IDENT '{' latency_item* '}'
+ (conditional_elseif | conditional_else)? ;
+conditional_else : 'else' '{' latency_item* '}' ;
+
+//---------------------------------------------------------------------------
+// Basic references
+//---------------------------------------------------------------------------
+latency_ref : ref_type '(' latency_spec ')' ';' ;
+
+ref_type : ('use' | 'def' | 'usedef' | 'kill' |
+ 'hold' | 'res' | 'predicate') ;
+
+latency_spec : expr (':' number)? ',' latency_resource_refs
+ | expr ('[' number (',' number)? ']')? ',' operand
+ | expr ',' operand ',' latency_resource_refs ;
+
+expr : '-' expr
+ | expr ('*' | '/') expr
+ | expr ('+' | '-') expr
+ | '{' expr '}'
+ | '(' expr ')'
+ | IDENT
+ | number
+ | operand ;
+
+//---------------------------------------------------------------------------
+// Shorthand for a reference that uses functional units.
+//---------------------------------------------------------------------------
+fus_statement : 'fus' '(' (fus_item ('&' fus_item)* ',')?
+ snumber (',' fus_attribute)* ')' ';'
+ ;
+fus_item : IDENT ('<' (expr ':')? number '>')? ;
+
+fus_attribute : 'BeginGroup' | 'EndGroup' | 'SingleIssue' | 'RetireOOO' ;
+
+//---------------------------------------------------------------------------
+// Latency resource references
+//---------------------------------------------------------------------------
+latency_resource_refs : latency_resource_ref (',' latency_resource_ref)* ;
+
+latency_resource_ref : resource_ref ':' number (':' IDENT)?
+ | resource_ref ':' IDENT (':' IDENT)?
+ | resource_ref ':' ':' IDENT // no allocation
+ | resource_ref ':' '*' // allocate all members
+ | resource_ref ;
+
+operand : (IDENT ':')? '$' IDENT ('.' operand_ref)*
+ | (IDENT ':')? '$' number
+ | (IDENT ':')? '$$' number
+
+operand_ref : (IDENT | number) ;
+
+//---------------------------------------------------------------------------
+// Pipeline phase names definitions.
+//---------------------------------------------------------------------------
+pipe_def : protection? 'phases' IDENT '{' pipe_phases '}' ';'? ;
+protection : 'protected' | 'unprotected' | 'hard' ;
+pipe_phases : phase_id (',' phase_id)* ;
+phase_id : '#'? IDENT ('[' range ']')? ('=' number)? ;
+
+//---------------------------------------------------------------------------
+// Resource definitions: global in scope, CPU- or Datapath- or FU-level.
+//---------------------------------------------------------------------------
+resource_def : 'resource' ( '(' IDENT ('..' IDENT)? ')' )?
+ resource_decl (',' resource_decl)* ';' ;
+
+resource_decl : IDENT (':' number)? ('[' number ']')?
+ | IDENT (':' number)? '{' name_list '}'
+ | IDENT (':' number)? '{' group_list '}' ;
+
+resource_refs : resource_ref (',' resource_ref)* ;
+
+resource_ref : IDENT ('[' range ']')?
+ | IDENT '.' IDENT
+ | IDENT '[' number ']'
+ | IDENT ('|' IDENT)+
+ | IDENT ('&' IDENT)+ ;
+
+//---------------------------------------------------------------------------
+// List of identifiers.
+//---------------------------------------------------------------------------
+name_list : IDENT (',' IDENT)* ;
+group_list : IDENT ('|' IDENT)+
+ | IDENT ('&' IDENT)+ ;
+
+//---------------------------------------------------------------------------
+// List of template bases
+//---------------------------------------------------------------------------
+base_list : (':' IDENT)* ;
+
+//---------------------------------------------------------------------------
+// Register definitions.
+//---------------------------------------------------------------------------
+register_def : 'register' register_decl (',' register_decl)* ';' ;
+register_decl : IDENT ('[' range ']')? ;
+
+register_class : 'register_class' IDENT
+ '{' register_decl (',' register_decl)* '}' ';'?
+ | 'register_class' IDENT '{' '}' ';'? ;
+
+//---------------------------------------------------------------------------
+// Instruction definition.
+//---------------------------------------------------------------------------
+instruction_def : 'instruction' IDENT
+ '(' (operand_decl (',' operand_decl)*)? ')'
+ '{'
+ ('subunit' '(' name_list ')' ';' )?
+ ('derived' '(' name_list ')' ';' )?
+ '}' ';'? ;
+
+//---------------------------------------------------------------------------
+// Operand definition.
+//---------------------------------------------------------------------------
+operand_def : 'operand' IDENT
+ '(' (operand_decl (',' operand_decl)*)? ')'
+ '{' (operand_type | operand_attribute)* '}' ';'?
+ ;
+operand_decl : ((IDENT (IDENT)?) | '...') ('(I)' | '(O)')? ;
+
+operand_type : 'type' '(' IDENT ')' ';' ;
+
+operand_attribute : (name_list ':')? operand_attribute_stmt
+ | name_list ':' '{' operand_attribute_stmt* '}' ';'? ;
+operand_attribute_stmt : 'attribute' IDENT '=' (snumber | tuple)
+ ('if' ('lit' | 'address' | 'label')
+ ('[' pred_value (',' pred_value)* ']' )? )? ';' ;
+pred_value : snumber
+ | snumber '..' snumber
+ | '{' number '}' ;
+
+//---------------------------------------------------------------------------
+// Derived Operand definition.
+//---------------------------------------------------------------------------
+derived_operand_def : 'operand' IDENT base_list ('(' ')')?
+ '{' (operand_type | operand_attribute)* '}' ';'? ;
+
+//---------------------------------------------------------------------------
+// Predicate definition.
+//---------------------------------------------------------------------------
+predicate_def : 'predicate' IDENT ':' predicate_op? ';' ;
+
+predicate_op : pred_opcode '<' pred_opnd (',' pred_opnd)* ','? '>'
+ | code_escape
+ | IDENT ;
+code_escape : '[' '{' .*? '}' ']' ;
+
+pred_opnd : IDENT
+ | snumber
+ | STRING_LITERAL
+ | '[' IDENT (',' IDENT)* ']'
+ | predicate_op
+ | operand ;
+
+pred_opcode : 'CheckAny' | 'CheckAll' | 'CheckNot' | 'CheckOpcode'
+ | 'CheckIsRegOperand' | 'CheckRegOperand'
+ | 'CheckSameRegOperand' | 'CheckNumOperands'
+ | 'CheckIsImmOperand' | 'CheckImmOperand'
+ | 'CheckZeroOperand' | 'CheckInvalidRegOperand'
+ | 'CheckFunctionPredicate' | 'CheckFunctionPredicateWithTII'
+ | 'TIIPredicate'
+ | 'OpcodeSwitchStatement' | 'OpcodeSwitchCase'
+ | 'ReturnStatement' | 'MCSchedPredicate' ;
+
+//---------------------------------------------------------------------------
+// Match and convert a number, a set of numbers, and a range of numbers.
+//---------------------------------------------------------------------------
+number : NUMBER ;
+snumber : NUMBER | '-' NUMBER ;
+tuple : '[' snumber (',' snumber)* ']' ;
+range : number '..' number ;
+```
+
+
+
+### **Appendix B: Future Directions**
+
+
+#### **Memory Hierarchy**
+
+We need a first class representation of any compiler-managed memory hierarchy.
+
+Compiler-managed memory
+
+
+
+* Per level
+ * Size
+ * Addressable units
+ * Speed
+ * Latency
+ * Access method(s)
+ * Banking
+ * Sharing
+* Separate address spaces
+ * Code, Data, I/O, etc
+
+Caches
+
+
+
+* Per level
+ * Size
+ * Type (I, D, I/D)
+ * Replacement policy
+ * Mapping (direct, associativity)
+ * Line size
+ * Prefetching
+ * Miss cost modeling
+ * etc
+
+Synchronization policies
+
+Virtual Memory
+
+DMA system descriptions
+
+Multi-Processor System Topology
+
+
+### **Appendix C: RISC-V Generated Architecture Description**
+
+This is a complete, automatically generated machine description for RISC-V using our tool to scrape information from tablegen files. We can automatically generate MDL specifications for all targets that have schedules and/or itineraries. We include RISC-V here for illustrative purposes.
+
+The “Schedule” td files for RISC-V are approximately 3231 lines of tablegen, describing three full schedule models and one “default” model. The generated MDL file is ~374 lines of MDL.
+
+
+```
+//---------------------------------------------------------------------
+// This file is autogenerated from an LLVM Target Description File.
+//---------------------------------------------------------------------
+import "RISCV_instructions.mdl"
+
+//---------------------------------------------------------------------
+// Pipeline phase definitions
+//---------------------------------------------------------------------
+protected phases RISCV { F1, E[1..1921] };
+
+//---------------------------------------------------------------------
+// CPU Description Classes (4 entries)
+//---------------------------------------------------------------------
+cpu RISCV("generic", "generic-rv32", "generic-rv64", "sifive-p450", "veyron-v1", "xiangshan-nanhu") {
+}
+
+cpu Rocket("rocket", "rocket-rv32", "rocket-rv64", "sifive-e20", "sifive-e21", "sifive-e24", "sifive-e31", "sifive-e34", "sifive-s21", "sifive-s51", "sifive-s54", "sifive-u54") {
+ protected phases defaults { LOAD_PHASE=3 };
+ issue(F1) s0;
+ func_unit RocketUnitALU<0> U0();
+ func_unit RocketUnitB<0> U1();
+ func_unit RocketUnitFPALU<0> U2();
+ func_unit RocketUnitFPDivSqrt<1> U3();
+ func_unit RocketUnitIDiv<1> U4();
+ func_unit RocketUnitIMul<0> U5();
+ func_unit RocketUnitMem<0> U6();
+}
+
+cpu SiFive7("sifive-7-series", "sifive-e76", "sifive-s76", "sifive-u74", "sifive-x280") {
+ protected phases defaults { LOAD_PHASE=3 };
+ issue(F1) s0, s1;
+ func_unit SiFive7FDiv<0> U0();
+ func_unit SiFive7IDiv<0> U1();
+ func_unit SiFive7PipeA<0> U2();
+ func_unit SiFive7PipeB<0> U3();
+ func_unit SiFive7VA<0> U4();
+ func_unit SiFive7VCQ<0> U5();
+ func_unit SiFive7VL<0> U6();
+ func_unit SiFive7VS<0> U7();
+}
+
+cpu SyntacoreSCR1("syntacore-scr1-base", "syntacore-scr1-max") {
+ protected phases defaults { LOAD_PHASE=2 };
+ issue(F1) s0;
+ func_unit SCR1_ALU<0> U0();
+ func_unit SCR1_CFU<0> U1();
+ func_unit SCR1_DIV<0> U2();
+ func_unit SCR1_LSU<0> U3();
+ func_unit SCR1_MUL<0> U4();
+}
+
+//---------------------------------------------------------------------
+// Functional Unit Groups
+//---------------------------------------------------------------------
+func_group SiFive7PipeAB: SiFive7PipeA, SiFive7PipeB;
+
+//---------------------------------------------------------------------
+// Functional Unit Templates
+//---------------------------------------------------------------------
+
+//---------------------------------------------------------------------
+// Subunit Definitions (232 entries)
+//---------------------------------------------------------------------
+subunit sub72() {{ Rocket : { def(E1, $X1); fus(RocketUnitALU, 1); fus(RocketUnitB, 1);} }}
+subunit sub35() {{ Rocket : { def(E1, $X1); fus(RocketUnitB, 1);} }}
+subunit sub78() {{ Rocket : { def(E1, $dst); fus(1); fus(Rocket, 0);} }}
+subunit sub16() {{ Rocket : { def(E1, $dst); fus(RocketUnitALU, 1);} }}
+subunit sub8() {{ Rocket : { def(E1, $rd); fus(1); fus(Rocket, 0);} }}
+subunit sub75() {{ Rocket : { def(E1, $rd); fus(RocketUnitALU, 1); fus(RocketUnitB, 1);} }}
+subunit sub0() {{ Rocket : { def(E1, $rd); fus(RocketUnitALU, 1);} }}
+subunit sub68() {{ Rocket : { def(E1, $rd); fus(RocketUnitB, 1);} }}
+subunit sub185() {{ Rocket : { def(E1, $rd); fus(RocketUnitMem, 1);} }}
+subunit sub24() {{ Rocket : { def(E1, $rd_wb); fus(RocketUnitALU, 1);} }}
+subunit sub44() {{ Rocket : { def(E1, $rs1); fus(RocketUnitALU, 1);} }}
+subunit sub190() {{ Rocket : { def(E1, $rs1_up); fus(RocketUnitMem, 1);} }}
+subunit sub21() {{ Rocket : { def(E1, $rs1_wb); fus(RocketUnitALU, 1);} }}
+subunit sub196() {{ Rocket : { def(E1, $vd); fus(1); fus(Rocket, 0);} }}
+subunit sub204() {{ Rocket : { def(E1, $vd_wb); fus(1); fus(Rocket, 0);} }}
+subunit sub60() {{ Rocket : { def(E2, $rd); fus(RocketUnitFPALU, 1);} }}
+subunit sub187() {{ Rocket : { def(E2, $rd); fus(RocketUnitMem, 1); def(E2, $rs2); fus(RocketUnitMem, 1);} }}
+subunit sub4() {{ Rocket : { def(E2, $rd); fus(RocketUnitMem, 1);} }}
+subunit sub61() {{ Rocket : { def(E20, $rd); fus(RocketUnitFPDivSqrt<20>, 1);} }}
+subunit sub67() {{ Rocket : { def(E25, $rd); fus(RocketUnitFPDivSqrt<25>, 1);} }}
+subunit sub39() {{ Rocket : { def(E3, $rd); fus(RocketUnitMem, 1);} }}
+subunit sub51() {{ Rocket : { def(E33, $rd); fus(RocketUnitIDiv<33>, 1);} }}
+subunit sub54() {{ Rocket : { def(E34, $rd); fus(RocketUnitIDiv<34>, 1);} }}
+subunit sub59() {{ Rocket : { def(E4, $rd); fus(RocketUnitFPALU, 1);} }}
+subunit sub70() {{ Rocket : { def(E4, $rd); fus(RocketUnitIMul, 1);} }}
+subunit sub41() {{ Rocket : { def(E4, $rd_wb); fus(RocketUnitIMul, 1);} }}
+subunit sub66() {{ Rocket : { def(E5, $rd); fus(RocketUnitFPALU, 1);} }}
+subunit sub56() {{ Rocket : { def(E6, $rd); fus(RocketUnitFPALU, 1);} }}
+subunit sub65() {{ Rocket : { def(E7, $rd); fus(RocketUnitFPALU, 1);} }}
+subunit sub47() {{ Rocket : { fus(1); fus(Rocket, 0);} }}
+subunit sub81() {{ Rocket : { fus(RocketUnitALU, 1); fus(RocketUnitB, 1);} }}
+subunit sub12() {{ Rocket : { fus(RocketUnitB, 1);} }}
+subunit sub193() {{ Rocket : { fus(RocketUnitMem, 1); fus(RocketUnitMem, 1);} }}
+subunit sub31() {{ Rocket : { fus(RocketUnitMem, 1);} }}
+subunit sub156() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<17>, 1); }
+ else { def(E131, $rd); fus(SiFive7VCQ&SiFive7VL<129>, 1); }
+} }}
+subunit sub150() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<17>, 1); }
+ else { def(E259, $rd); fus(SiFive7VCQ&SiFive7VL<257>, 1); }
+} }}
+subunit sub164() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<17>, 1); }
+ else { def(E515, $rd); fus(SiFive7VCQ&SiFive7VL<513>, 1); }
+} }}
+subunit sub160() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<17>, 1); }
+ else { def(E67, $rd); fus(SiFive7VCQ&SiFive7VL<65>, 1); }
+} }}
+subunit sub152() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<2>, 1); }
+ else { def(E11, $rd); fus(SiFive7VCQ&SiFive7VL<9>, 1); }
+} }}
+subunit sub151() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<2>, 1); }
+ else { def(E19, $rd); fus(SiFive7VCQ&SiFive7VL<17>, 1); }
+} }}
+subunit sub165() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<2>, 1); }
+ else { def(E35, $rd); fus(SiFive7VCQ&SiFive7VL<33>, 1); }
+} }}
+subunit sub157() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<3>, 1); }
+ else { def(E11, $rd); fus(SiFive7VCQ&SiFive7VL<9>, 1); }
+} }}
+subunit sub153() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<3>, 1); }
+ else { def(E19, $rd); fus(SiFive7VCQ&SiFive7VL<17>, 1); }
+} }}
+subunit sub147() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<3>, 1); }
+ else { def(E35, $rd); fus(SiFive7VCQ&SiFive7VL<33>, 1); }
+} }}
+subunit sub161() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<3>, 1); }
+ else { def(E67, $rd); fus(SiFive7VCQ&SiFive7VL<65>, 1); }
+} }}
+subunit sub162() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<5>, 1); }
+ else { def(E131, $rd); fus(SiFive7VCQ&SiFive7VL<129>, 1); }
+} }}
+subunit sub158() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<5>, 1); }
+ else { def(E19, $rd); fus(SiFive7VCQ&SiFive7VL<17>, 1); }
+} }}
+subunit sub154() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<5>, 1); }
+ else { def(E35, $rd); fus(SiFive7VCQ&SiFive7VL<33>, 1); }
+} }}
+subunit sub148() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<5>, 1); }
+ else { def(E67, $rd); fus(SiFive7VCQ&SiFive7VL<65>, 1); }
+} }}
+subunit sub149() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<9>, 1); }
+ else { def(E131, $rd); fus(SiFive7VCQ&SiFive7VL<129>, 1); }
+} }}
+subunit sub163() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<9>, 1); }
+ else { def(E259, $rd); fus(SiFive7VCQ&SiFive7VL<257>, 1); }
+} }}
+subunit sub159() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<9>, 1); }
+ else { def(E35, $rd); fus(SiFive7VCQ&SiFive7VL<33>, 1); }
+} }}
+subunit sub155() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<9>, 1); }
+ else { def(E67, $rd); fus(SiFive7VCQ&SiFive7VL<65>, 1); }
+} }}
+subunit sub222() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $vd); fus(SiFive7VCQ&SiFive7VL<17>, 1); }
+ else { def(E131, $vd); fus(SiFive7VCQ&SiFive7VL<129>, 1); }
+} }}
+subunit sub221() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $vd); fus(SiFive7VCQ&SiFive7VL<17>, 1); }
+ else { def(E259, $vd); fus(SiFive7VCQ&SiFive7VL<257>, 1); }
+} }}
+subunit sub224() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $vd); fus(SiFive7VCQ&SiFive7VL<17>, 1); }
+ else { def(E515, $vd); fus(SiFive7VCQ&SiFive7VL<513>, 1); }
+} }}
+subunit sub223() {{ SiFive7 : {
+ if VLDSX0Pred { def(E4, $vd); fus(SiFive7VCQ&SiFive7VL<17>, 1); }
+ else { def(E67, $vd); fus(SiFive7VCQ&SiFive7VL<65>, 1); }
+} }}
+subunit sub15() {{ SiFive7 : { def(E1, $rd); fus(1); fus(SiFive7, 0);} }}
+subunit sub186() {{ SiFive7 : { def(E1, $rd); fus(SiFive7PipeA, 1);} }}
+subunit sub20() {{ SiFive7 : { def(E1, $rd); fus(SiFive7PipeB, 1);} }}
+subunit sub191() {{ SiFive7 : { def(E1, $rs1_up); fus(SiFive7PipeA, 1);} }}
+subunit sub96() {{ SiFive7 : { def(E11, $rd); fus(SiFive7VCQ&SiFive7VA<9>, 1);} }}
+subunit sub145() {{ SiFive7 : { def(E11, $rd); fus(SiFive7VCQ&SiFive7VL<9>, 1);} }}
+subunit sub102() {{ SiFive7 : { def(E112, $rd); fus(SiFive7VCQ&SiFive7VA<113>, 1);} }}
+subunit sub103() {{ SiFive7 : { def(E114, $rd); fus(SiFive7VCQ&SiFive7VA<115>, 1);} }}
+subunit sub101() {{ SiFive7 : { def(E120, $rd); fus(SiFive7VCQ&SiFive7VA<121>, 1);} }}
+subunit sub98() {{ SiFive7 : { def(E131, $rd); fus(SiFive7VCQ&SiFive7VA<129>, 1);} }}
+subunit sub142() {{ SiFive7 : { def(E131, $rd); fus(SiFive7VCQ&SiFive7VL<129>, 1);} }}
+subunit sub218() {{ SiFive7 : { def(E131, $vd); fus(SiFive7VCQ&SiFive7VL<129>, 1);} }}
+subunit sub63() {{ SiFive7 : { def(E14, $rd); fus(SiFive7PipeB&SiFive7FDiv<13>, 1);} }}
+subunit sub134() {{ SiFive7 : { def(E1536, $rd); fus(SiFive7VCQ&SiFive7VA<1537>, 1);} }}
+subunit sub210() {{ SiFive7 : { def(E1536, $vd); fus(SiFive7VCQ&SiFive7VA<1537>, 1);} }}
+subunit sub95() {{ SiFive7 : { def(E19, $rd); fus(SiFive7VCQ&SiFive7VA<17>, 1);} }}
+subunit sub144() {{ SiFive7 : { def(E19, $rd); fus(SiFive7VCQ&SiFive7VL<17>, 1);} }}
+subunit sub227() {{ SiFive7 : { def(E19, $vd); fus(SiFive7VCQ&SiFive7VA<17>, 1);} }}
+subunit sub130() {{ SiFive7 : { def(E192, $rd); fus(SiFive7VCQ&SiFive7VA<193>, 1);} }}
+subunit sub113() {{ SiFive7 : { def(E1920, $rd); fus(SiFive7VCQ&SiFive7VA<1921>, 1);} }}
+subunit sub202() {{ SiFive7 : { def(E1920, $vd); fus(SiFive7VCQ&SiFive7VA<1921>, 1);} }}
+subunit sub30() {{ SiFive7 : { def(E2, $rd); fus(SiFive7PipeA, 1);} }}
+subunit sub105() {{ SiFive7 : { def(E224, $rd); fus(SiFive7VCQ&SiFive7VA<225>, 1);} }}
+subunit sub106() {{ SiFive7 : { def(E228, $rd); fus(SiFive7VCQ&SiFive7VA<229>, 1);} }}
+subunit sub104() {{ SiFive7 : { def(E240, $rd); fus(SiFive7VCQ&SiFive7VA<241>, 1);} }}
+subunit sub99() {{ SiFive7 : { def(E259, $rd); fus(SiFive7VCQ&SiFive7VA<257>, 1);} }}
+subunit sub143() {{ SiFive7 : { def(E259, $rd); fus(SiFive7VCQ&SiFive7VL<257>, 1);} }}
+subunit sub217() {{ SiFive7 : { def(E259, $vd); fus(SiFive7VCQ&SiFive7VL<257>, 1);} }}
+subunit sub64() {{ SiFive7 : { def(E27, $rd); fus(SiFive7PipeB&SiFive7FDiv<26>, 1);} }}
+subunit sub73() {{ SiFive7 : { def(E3, $X1); fus(SiFive7PipeAB, 1); fus(SiFive7PipeB, 1);} }}
+subunit sub38() {{ SiFive7 : { def(E3, $X1); fus(SiFive7PipeB, 1); use(E3, $rs1);} }}
+subunit sub36() {{ SiFive7 : { def(E3, $X1); fus(SiFive7PipeB, 1);} }}
+subunit sub79() {{ SiFive7 : { def(E3, $dst); fus(SiFive7PipeA&SiFive7PipeB, 2);} }}
+subunit sub17() {{ SiFive7 : { def(E3, $dst); fus(SiFive7PipeAB, 1);} }}
+subunit sub188() {{ SiFive7 : { def(E3, $rd); fus(SiFive7PipeA, 1); def(E3, $rs2); fus(SiFive7PipeA, 1);} }}
+subunit sub231() {{ SiFive7 : { def(E3, $rd); fus(SiFive7PipeA, 1); use(E3, $rs1); use(E3, $rs2);} }}
+subunit sub179() {{ SiFive7 : { def(E3, $rd); fus(SiFive7PipeA, 1); use(E3, $rs1);} }}
+subunit sub5() {{ SiFive7 : { def(E3, $rd); fus(SiFive7PipeA, 1);} }}
+subunit sub76() {{ SiFive7 : { def(E3, $rd); fus(SiFive7PipeAB, 1); fus(SiFive7PipeB, 1);} }}
+subunit sub1() {{ SiFive7 : { def(E3, $rd); fus(SiFive7PipeAB, 1); use(E3, $rs1); use(E3, $rs2);} }}
+subunit sub3() {{ SiFive7 : { def(E3, $rd); fus(SiFive7PipeAB, 1); use(E3, $rs1);} }}
+subunit sub7() {{ SiFive7 : { def(E3, $rd); fus(SiFive7PipeAB, 1);} }}
+subunit sub9() {{ SiFive7 : { def(E3, $rd); fus(SiFive7PipeB, 1); use(E3, $rs1); use(E3, $rs2);} }}
+subunit sub11() {{ SiFive7 : { def(E3, $rd); fus(SiFive7PipeB, 1); use(E3, $rs1);} }}
+subunit sub19() {{ SiFive7 : { def(E3, $rd); fus(SiFive7PipeB, 1);} }}
+subunit sub27() {{ SiFive7 : { def(E3, $rd_wb); fus(SiFive7PipeAB, 1); use(E3, $rd); use(E3, $rs2);} }}
+subunit sub25() {{ SiFive7 : { def(E3, $rd_wb); fus(SiFive7PipeAB, 1); use(E3, $rd);} }}
+subunit sub42() {{ SiFive7 : { def(E3, $rd_wb); fus(SiFive7PipeB, 1);} }}
+subunit sub45() {{ SiFive7 : { def(E3, $rs1); fus(SiFive7PipeAB, 1); use(E3, $rs2);} }}
+subunit sub22() {{ SiFive7 : { def(E3, $rs1_wb); fus(SiFive7PipeAB, 1); use(E3, $rs1); use(E3, $rs2);} }}
+subunit sub28() {{ SiFive7 : { def(E3, $rs1_wb); fus(SiFive7PipeAB, 1); use(E3, $rs1);} }}
+subunit sub116() {{ SiFive7 : { def(E30, $rd); fus(SiFive7VCQ&SiFive7VA<31>, 1);} }}
+subunit sub119() {{ SiFive7 : { def(E32, $rd); fus(SiFive7VCQ&SiFive7VA<33>, 1);} }}
+subunit sub55() {{ SiFive7 : { def(E34, $rd); fus(SiFive7PipeB&SiFive7IDiv<33>, 1);} }}
+subunit sub122() {{ SiFive7 : { def(E34, $rd); fus(SiFive7VCQ&SiFive7VA<35>, 1);} }}
+subunit sub94() {{ SiFive7 : { def(E35, $rd); fus(SiFive7VCQ&SiFive7VA<33>, 1);} }}
+subunit sub140() {{ SiFive7 : { def(E35, $rd); fus(SiFive7VCQ&SiFive7VL<33>, 1);} }}
+subunit sub225() {{ SiFive7 : { def(E35, $vd); fus(SiFive7VCQ&SiFive7VL<33>, 1);} }}
+subunit sub129() {{ SiFive7 : { def(E36, $rd); fus(SiFive7VCQ&SiFive7VA<37>, 1);} }}
+subunit sub118() {{ SiFive7 : { def(E37, $rd); fus(SiFive7VCQ&SiFive7VA<38>, 1);} }}
+subunit sub125() {{ SiFive7 : { def(E38, $rd); fus(SiFive7VCQ&SiFive7VA<39>, 1);} }}
+subunit sub132() {{ SiFive7 : { def(E384, $rd); fus(SiFive7VCQ&SiFive7VA<385>, 1);} }}
+subunit sub121() {{ SiFive7 : { def(E39, $rd); fus(SiFive7VCQ&SiFive7VA<40>, 1);} }}
+subunit sub92() {{ SiFive7 : { def(E4, $rd); fus(SiFive7VCQ&SiFive7VA<17>, 1);} }}
+subunit sub93() {{ SiFive7 : { def(E4, $rd); fus(SiFive7VCQ&SiFive7VA<2>, 1);} }}
+subunit sub89() {{ SiFive7 : { def(E4, $rd); fus(SiFive7VCQ&SiFive7VA<3>, 1);} }}
+subunit sub90() {{ SiFive7 : { def(E4, $rd); fus(SiFive7VCQ&SiFive7VA<5>, 1);} }}
+subunit sub91() {{ SiFive7 : { def(E4, $rd); fus(SiFive7VCQ&SiFive7VA<9>, 1);} }}
+subunit sub138() {{ SiFive7 : { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<17>, 1);} }}
+subunit sub139() {{ SiFive7 : { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<2>, 1);} }}
+subunit sub135() {{ SiFive7 : { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<3>, 1);} }}
+subunit sub136() {{ SiFive7 : { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<5>, 1);} }}
+subunit sub137() {{ SiFive7 : { def(E4, $rd); fus(SiFive7VCQ&SiFive7VL<9>, 1);} }}
+subunit sub199() {{ SiFive7 : { def(E4, $vd); fus(SiFive7VCQ&SiFive7VA<17>, 1);} }}
+subunit sub207() {{ SiFive7 : { def(E4, $vd); fus(SiFive7VCQ&SiFive7VA<2>, 1);} }}
+subunit sub201() {{ SiFive7 : { def(E4, $vd); fus(SiFive7VCQ&SiFive7VA<3>, 1);} }}
+subunit sub228() {{ SiFive7 : { def(E4, $vd); fus(SiFive7VCQ&SiFive7VA<5>, 1);} }}
+subunit sub229() {{ SiFive7 : { def(E4, $vd); fus(SiFive7VCQ&SiFive7VA<9>, 1);} }}
+subunit sub216() {{ SiFive7 : { def(E4, $vd); fus(SiFive7VCQ&SiFive7VL<17>, 1);} }}
+subunit sub213() {{ SiFive7 : { def(E4, $vd); fus(SiFive7VCQ&SiFive7VL<3>, 1);} }}
+subunit sub214() {{ SiFive7 : { def(E4, $vd); fus(SiFive7VCQ&SiFive7VL<5>, 1);} }}
+subunit sub215() {{ SiFive7 : { def(E4, $vd); fus(SiFive7VCQ&SiFive7VL<9>, 1);} }}
+subunit sub226() {{ SiFive7 : { def(E4, $vd_wb); fus(SiFive7VCQ&SiFive7VA<17>, 1);} }}
+subunit sub208() {{ SiFive7 : { def(E4, $vd_wb); fus(SiFive7VCQ&SiFive7VA<2>, 1);} }}
+subunit sub128() {{ SiFive7 : { def(E41, $rd); fus(SiFive7VCQ&SiFive7VA<42>, 1);} }}
+subunit sub117() {{ SiFive7 : { def(E42, $rd); fus(SiFive7VCQ&SiFive7VA<43>, 1);} }}
+subunit sub124() {{ SiFive7 : { def(E43, $rd); fus(SiFive7VCQ&SiFive7VA<44>, 1);} }}
+subunit sub120() {{ SiFive7 : { def(E44, $rd); fus(SiFive7VCQ&SiFive7VA<45>, 1);} }}
+subunit sub108() {{ SiFive7 : { def(E448, $rd); fus(SiFive7VCQ&SiFive7VA<449>, 1);} }}
+subunit sub109() {{ SiFive7 : { def(E456, $rd); fus(SiFive7VCQ&SiFive7VA<457>, 1);} }}
+subunit sub127() {{ SiFive7 : { def(E46, $rd); fus(SiFive7VCQ&SiFive7VA<47>, 1);} }}
+subunit sub170() {{ SiFive7 : { def(E47, $rd); fus(SiFive7VCQ&SiFive7VA<48>, 1);} }}
+subunit sub123() {{ SiFive7 : { def(E48, $rd); fus(SiFive7VCQ&SiFive7VA<49>, 1);} }}
+subunit sub107() {{ SiFive7 : { def(E480, $rd); fus(SiFive7VCQ&SiFive7VA<481>, 1);} }}
+subunit sub171() {{ SiFive7 : { def(E49, $rd); fus(SiFive7VCQ&SiFive7VA<50>, 1);} }}
+subunit sub58() {{ SiFive7 : { def(E5, $rd); fus(SiFive7PipeB, 1);} }}
+subunit sub168() {{ SiFive7 : { def(E5, $rd); fus(SiFive7VCQ&SiFive7VA<3>, 1);} }}
+subunit sub167() {{ SiFive7 : { def(E5, $rd); fus(SiFive7VCQ&SiFive7VL<3>, 1);} }}
+subunit sub126() {{ SiFive7 : { def(E51, $rd); fus(SiFive7VCQ&SiFive7VA<52>, 1);} }}
+subunit sub100() {{ SiFive7 : { def(E515, $rd); fus(SiFive7VCQ&SiFive7VA<513>, 1);} }}
+subunit sub146() {{ SiFive7 : { def(E515, $rd); fus(SiFive7VCQ&SiFive7VL<513>, 1);} }}
+subunit sub200() {{ SiFive7 : { def(E515, $vd); fus(SiFive7VCQ&SiFive7VA<513>, 1);} }}
+subunit sub220() {{ SiFive7 : { def(E515, $vd); fus(SiFive7VCQ&SiFive7VL<513>, 1);} }}
+subunit sub172() {{ SiFive7 : { def(E53, $rd); fus(SiFive7VCQ&SiFive7VA<54>, 1);} }}
+subunit sub62() {{ SiFive7 : { def(E56, $rd); fus(SiFive7PipeB&SiFive7FDiv<55>, 1);} }}
+subunit sub115() {{ SiFive7 : { def(E56, $rd); fus(SiFive7VCQ&SiFive7VA<57>, 1);} }}
+subunit sub209() {{ SiFive7 : { def(E56, $vd); fus(SiFive7VCQ&SiFive7VA<57>, 1);} }}
+subunit sub114() {{ SiFive7 : { def(E60, $rd); fus(SiFive7VCQ&SiFive7VA<61>, 1);} }}
+subunit sub173() {{ SiFive7 : { def(E61, $rd); fus(SiFive7VCQ&SiFive7VA<62>, 1);} }}
+subunit sub230() {{ SiFive7 : { def(E61, $vd); fus(SiFive7VCQ&SiFive7VA<62>, 1);} }}
+subunit sub52() {{ SiFive7 : { def(E66, $rd); fus(SiFive7PipeB&SiFive7IDiv<65>, 1);} }}
+subunit sub97() {{ SiFive7 : { def(E67, $rd); fus(SiFive7VCQ&SiFive7VA<65>, 1);} }}
+subunit sub141() {{ SiFive7 : { def(E67, $rd); fus(SiFive7VCQ&SiFive7VL<65>, 1);} }}
+subunit sub219() {{ SiFive7 : { def(E67, $vd); fus(SiFive7VCQ&SiFive7VL<65>, 1);} }}
+subunit sub57() {{ SiFive7 : { def(E7, $rd); fus(SiFive7PipeB, 1);} }}
+subunit sub169() {{ SiFive7 : { def(E7, $rd); fus(SiFive7VCQ&SiFive7VA<5>, 1);} }}
+subunit sub166() {{ SiFive7 : { def(E7, $rd); fus(SiFive7VCQ&SiFive7VL<5>, 1);} }}
+subunit sub133() {{ SiFive7 : { def(E768, $rd); fus(SiFive7VCQ&SiFive7VA<769>, 1);} }}
+subunit sub87() {{ SiFive7 : { def(E8, $rd); fus(SiFive7VCQ&SiFive7VA<17>, 1);} }}
+subunit sub88() {{ SiFive7 : { def(E8, $rd); fus(SiFive7VCQ&SiFive7VA<2>, 1);} }}
+subunit sub84() {{ SiFive7 : { def(E8, $rd); fus(SiFive7VCQ&SiFive7VA<3>, 1);} }}
+subunit sub85() {{ SiFive7 : { def(E8, $rd); fus(SiFive7VCQ&SiFive7VA<5>, 1);} }}
+subunit sub86() {{ SiFive7 : { def(E8, $rd); fus(SiFive7VCQ&SiFive7VA<9>, 1);} }}
+subunit sub197() {{ SiFive7 : { def(E8, $vd); fus(SiFive7VCQ&SiFive7VA<17>, 1);} }}
+subunit sub211() {{ SiFive7 : { def(E8, $vd); fus(SiFive7VCQ&SiFive7VA<9>, 1);} }}
+subunit sub205() {{ SiFive7 : { def(E8, $vd_wb); fus(SiFive7VCQ&SiFive7VA<17>, 1);} }}
+subunit sub212() {{ SiFive7 : { def(E8, $vd_wb); fus(SiFive7VCQ&SiFive7VA<9>, 1);} }}
+subunit sub111() {{ SiFive7 : { def(E896, $rd); fus(SiFive7VCQ&SiFive7VA<897>, 1);} }}
+subunit sub112() {{ SiFive7 : { def(E912, $rd); fus(SiFive7VCQ&SiFive7VA<913>, 1);} }}
+subunit sub131() {{ SiFive7 : { def(E96, $rd); fus(SiFive7VCQ&SiFive7VA<97>, 1);} }}
+subunit sub110() {{ SiFive7 : { def(E960, $rd); fus(SiFive7VCQ&SiFive7VA<961>, 1);} }}
+subunit sub203() {{ SiFive7 : { def(E960, $vd); fus(SiFive7VCQ&SiFive7VA<961>, 1);} }}
+subunit sub48() {{ SiFive7 : { fus(1); fus(SiFive7, 0);} }}
+subunit sub194() {{ SiFive7 : { fus(SiFive7PipeA, 1); fus(SiFive7PipeA, 1);} }}
+subunit sub32() {{ SiFive7 : { fus(SiFive7PipeA, 1);} }}
+subunit sub82() {{ SiFive7 : { fus(SiFive7PipeAB, 1); fus(SiFive7PipeB, 1); use(E3, $X2);} }}
+subunit sub13() {{ SiFive7 : { fus(SiFive7PipeB, 1); use(E3, $rs1); use(E3, $rs2);} }}
+subunit sub29() {{ SiFive7 : { fus(SiFive7PipeB, 1); use(E3, $rs1);} }}
+subunit sub34() {{ SiFive7 : { fus(SiFive7PipeB, 1);} }}
+subunit sub182() {{ SiFive7 : { fus(SiFive7VCQ&SiFive7VS<129>, 1);} }}
+subunit sub177() {{ SiFive7 : { fus(SiFive7VCQ&SiFive7VS<17>, 1);} }}
+subunit sub183() {{ SiFive7 : { fus(SiFive7VCQ&SiFive7VS<257>, 1);} }}
+subunit sub178() {{ SiFive7 : { fus(SiFive7VCQ&SiFive7VS<2>, 1);} }}
+subunit sub180() {{ SiFive7 : { fus(SiFive7VCQ&SiFive7VS<33>, 1);} }}
+subunit sub174() {{ SiFive7 : { fus(SiFive7VCQ&SiFive7VS<3>, 1);} }}
+subunit sub184() {{ SiFive7 : { fus(SiFive7VCQ&SiFive7VS<513>, 1);} }}
+subunit sub175() {{ SiFive7 : { fus(SiFive7VCQ&SiFive7VS<5>, 1);} }}
+subunit sub181() {{ SiFive7 : { fus(SiFive7VCQ&SiFive7VS<65>, 1);} }}
+subunit sub176() {{ SiFive7 : { fus(SiFive7VCQ&SiFive7VS<9>, 1);} }}
+subunit sub74() {{ SyntacoreSCR1 : { def(E1, $X1); fus(SCR1_ALU, 1); fus(SCR1_CFU, 1);} }}
+subunit sub37() {{ SyntacoreSCR1 : { def(E1, $X1); fus(SCR1_CFU, 1);} }}
+subunit sub80() {{ SyntacoreSCR1 : { def(E1, $dst); fus(1); fus(SyntacoreSCR1, 0);} }}
+subunit sub18() {{ SyntacoreSCR1 : { def(E1, $dst); fus(SCR1_ALU, 1);} }}
+subunit sub10() {{ SyntacoreSCR1 : { def(E1, $rd); fus(1); fus(SyntacoreSCR1, 0);} }}
+subunit sub77() {{ SyntacoreSCR1 : { def(E1, $rd); fus(SCR1_ALU, 1); fus(SCR1_CFU, 1);} }}
+subunit sub2() {{ SyntacoreSCR1 : { def(E1, $rd); fus(SCR1_ALU, 1);} }}
+subunit sub69() {{ SyntacoreSCR1 : { def(E1, $rd); fus(SCR1_CFU, 1);} }}
+subunit sub6() {{ SyntacoreSCR1 : { def(E1, $rd); fus(SCR1_LSU, 1);} }}
+subunit sub71() {{ SyntacoreSCR1 : { def(E1, $rd); fus(SCR1_MUL, 1);} }}
+subunit sub26() {{ SyntacoreSCR1 : { def(E1, $rd_wb); fus(SCR1_ALU, 1);} }}
+subunit sub43() {{ SyntacoreSCR1 : { def(E1, $rd_wb); fus(SCR1_MUL, 1);} }}
+subunit sub46() {{ SyntacoreSCR1 : { def(E1, $rs1); fus(SCR1_ALU, 1);} }}
+subunit sub23() {{ SyntacoreSCR1 : { def(E1, $rs1_wb); fus(SCR1_ALU, 1);} }}
+subunit sub198() {{ SyntacoreSCR1 : { def(E1, $vd); fus(1); fus(SyntacoreSCR1, 0);} }}
+subunit sub206() {{ SyntacoreSCR1 : { def(E1, $vd_wb); fus(1); fus(SyntacoreSCR1, 0);} }}
+subunit sub189() {{ SyntacoreSCR1 : { def(E2, $rd); fus(SCR1_LSU<2>, 1); def(E2, $rs2); fus(SCR1_LSU<2>, 1);} }}
+subunit sub40() {{ SyntacoreSCR1 : { def(E2, $rd); fus(SCR1_LSU<2>, 1);} }}
+subunit sub192() {{ SyntacoreSCR1 : { def(E2, $rs1_up); fus(SCR1_LSU<2>, 1);} }}
+subunit sub53() {{ SyntacoreSCR1 : { def(E33, $rd); fus(SCR1_DIV<33>, 1);} }}
+subunit sub49() {{ SyntacoreSCR1 : { fus(1); fus(SyntacoreSCR1, 0);} }}
+subunit sub83() {{ SyntacoreSCR1 : { fus(SCR1_ALU, 1); fus(SCR1_CFU, 1);} }}
+subunit sub14() {{ SyntacoreSCR1 : { fus(SCR1_CFU, 1);} }}
+subunit sub33() {{ SyntacoreSCR1 : { fus(SCR1_LSU, 1);} }}
+subunit sub195() {{ SyntacoreSCR1 : { fus(SCR1_LSU<2>, 1); fus(SCR1_LSU<2>, 1);} }}
+subunit sub50() {{ SyntacoreSCR1 : { fus(SCR1_LSU<2>, 1);} }}
+
+//---------------------------------------------------------------------
+// Predicate Definitions
+//---------------------------------------------------------------------
+
+predicate VLDSX0Pred : CheckRegOperand<3,X0>;
+
diff --git a/llvm/docs/Mdl/RFC.md b/llvm/docs/Mdl/RFC.md
new file mode 100644
index 000000000000000..e6fa6e350058a7a
--- /dev/null
+++ b/llvm/docs/Mdl/RFC.md
@@ -0,0 +1,64 @@
+
+## MDL: A Micro-Architecture Description Language for LLVM
+
+November 2022 Reid Tatge [tatge at google.com](mailto:tatge at google.com)
+
+Updated January 2024
+
+
+#### **TL;DR:**
+
+We’ve created a DSL and compiler for modeling micro-architecture that handles a very broad class of architectures - CPUs, GPUs, VLIWs, DSPs, ML accelerators, and embedded devices. This effort grew out of a need to quickly develop and experiment with high-quality compilers and tools to facilitate rapid architecture exploration. We named the DSL “MDL” for “Microarchitecture Description Language”.
+
+While being significantly more expressive than TableGen’s Schedules and Itineraries used in LLVM, MDL is also more concise, and simpler to read and write while supporting a much broader class of embedded and accelerator architectures. We currently can automatically _generate _MDL descriptions for all upstream targets which are in many cases 1/10 the size of the equivalent TableGen descriptions. We’ve integrated this with LLVM, and are sending out this RFC because we believe it could be valuable to the larger LLVM community. \
+
+
+The MDL compiler, associated tools, and documentation are available as open source (at https://github.com/MPACT-ORG/llvm-project/tree/all), and we would like to explore adding this to the LLVM project, and encourage contributions from others.
+
+
+#### **Background**
+
+Over the last few years, we have been using LLVM to develop a compiler backend for Google’s TPU machine learning accelerators. TPUs have complex microarchitectures and pose a number of challenges that are not seen in in typical LLVM targets:
+
+
+
+* Clustered VLIW with partitioned register files.
+* Extremely deep pipelines with complex hazard conditions
+* Instructions with functional-unit-specific and/or cluster-specific behaviors
+ * Non-trivial and/or instance-specific latencies
+ * Complex resource usage
+ * Functional-unit-specific register constraints
+* Shared/allocated encoding resources (instructions need 1..M of N resources)
+* Explicitly managed hardware resources (register ports, internal datapaths, busses, etc)
+
+While some of these problems manifest in a few upstream LLVM targets, this collection of problems is a superset of the problems directly addressed by LLVM - Schedules and Itineraries are simply not sufficient to model everything. Supporting this class of architecture is therefore code-intensive - it takes around 20,000 lines of C++ code to model the TPU sub-targets. This is brittle, hard to write, debug, test, and evolve over time. In contrast, the MDL description for these sub-targets is ~2,000 lines of text, and requires very little (if any) target-specific code in the backend.
+
+
+#### **Status**
+
+
+
+* We’ve created the MDL language and compiler for describing microarchitecture details, a methodology for integrating it with TableGen files for any target, and a set of APIs that can be used in a machine-independent way to inform back-end passes such as bundle-packing, instruction scheduling, and register allocation.
+* To facilitate integration with LLVM, we built a tool which scrapes architectural information from TableGen files, and produces our MDL language for all upstream targets.
+* We’ve modified the CodeGen and MC libraries to (optionally) use our methodology for latency management.
+
+
+#### **Building**
+
+
+
+* You can build llvm with or without MDL support. It is included by using the LLVM\_ENABLE\_MDL CMake parameter. If included, it is currently used by default, and can be disabled with a command line option (--schedmdl=0).
+
+
+#### **Testing**
+
+
+
+* When built without MDL support, the compiler passes all check-all tests.
+* When built with MDL support, but disabled on the command line, the compielr passes all check-all tests.
+* When MDL support is enabled, it passs all but 190 tests (out of ~90K+ tests).
+
+There is a lot more to do. For example, we plan to enhance existing back-end scheduling passes and register allocation passes to cleanly handle a larger class of embedded and accelerator architectures, based on MDL-generated information.
+
+We welcome feedback on the language design and associated tools and use model. You can find the MDL design documentation, compiler, and other tools in our github repo in llvm/docs/mdl.
+
>From c3359e02026637b4b6630cc3d3b4bc99562102d9 Mon Sep 17 00:00:00 2001
From: Reid Tatge <35816723+reidtatge at users.noreply.github.com>
Date: Fri, 12 Jan 2024 16:44:00 -0800
Subject: [PATCH 02/14] Update MachineDescriptionNotes.md
---
llvm/docs/Mdl/MachineDescriptionNotes.md | 142 +++++++++++------------
1 file changed, 71 insertions(+), 71 deletions(-)
diff --git a/llvm/docs/Mdl/MachineDescriptionNotes.md b/llvm/docs/Mdl/MachineDescriptionNotes.md
index ae9e8b974a7f89f..d6624051ef59d6d 100644
--- a/llvm/docs/Mdl/MachineDescriptionNotes.md
+++ b/llvm/docs/Mdl/MachineDescriptionNotes.md
@@ -1,5 +1,5 @@
-## MPACT Microarchitecture Description Language
+# MPACT Microarchitecture Description Language
Reid Tatge [tatge at google.com](mailto:tatge at google.com)
@@ -8,7 +8,7 @@ Reid Tatge [tatge at google.com](mailto:tatge at google.com)
-### **Goals for a Machine Description Language**
+## **Goals for a Machine Description Language**
Modern processors are complex: multiple execution pipelines, dynamically dispatched, out-of-order execution, register renaming, forwarding networks, and (often) undocumented micro-operations. Instruction behaviors, including micro-operations, often can’t be _statically_ modeled in an accurate way, but only _statistically_ modeled. In these cases, the compiler’s model of a microarchitecture (Schedules and Itineraries in LLVM) is effectively closer to a heuristic than a formal model. And this works quite well for general purpose microprocessors.
@@ -42,7 +42,7 @@ _Note: A full language grammar description is provided in an appendix. Snippets
The proposed language can be thought of as an _optional extension to the LLVM machine description_. For most upstream architectures, the new language offers minimal benefit other than a much more succinct way to specify the architecture vs Schedules and Itineraries. But for accelerator-class architectures, it provides a level of detail and capability not available in the existing tablegen approaches.
-#### **Background**
+### **Background**
Processor families evolve over time. They accrete new instructions, and pipelines change - often in subtle ways - as they accumulate more functional units and registers; encoding rules change; issue rules change. Understanding, encoding, and using all of this information - over time, for many subtargets - can be daunting. When the description language isn’t sufficient to model the architecture, the back-end modeling evolves towards heuristics, and leads to performance issues or bugs in the compiler. And it certainly ends with large amounts of target specific code to handle “special cases”.
@@ -78,7 +78,7 @@ More generally, we’d like specific language to:
Since our emphasis is on easily supporting accelerators and VLIW processors, in addition to supporting all existing targets, much of this is overkill for most upstreamed CPUs. CPU’s typically have much simpler descriptions, and don’t require much of the capability of our machine description language. Incidentally, MDL descriptions of these targets (generated automatically from the tablegen Schedules and Itineraries) are typically much more concise than the original tablegen descriptions.
-#### **Approach - “Subunits” and Instruction Behaviors**
+### **Approach - “Subunits” and Instruction Behaviors**
We developed a DSL that allows us to describe an arbitrary processor microarchitecture in terms that reflect what is typically documented in the hardware specification. The MDL compiler creates a database that provides microarchitecture behavior information that can _automatically _inform critical back-end compiler passes, such as instruction scheduling and register allocation, in a machine-independent way.
@@ -108,7 +108,7 @@ We define a subunit as an object that defines the _behavior sets_ of an instruct
The critical artifact generated by the MDL compiler is a set of instruction behaviors for each instruction definition. For each subtarget, for each instruction, we generate a list of every possible behavior of that instruction on that CPU. While this sounds daunting, in practice it's rare to have more than a few behaviors for an instruction, and most instruction definitions share their behaviors with many other instructions, across subtargets.
-### **Overview of a Processor Family Description**
+## **Overview of a Processor Family Description**
This document generally describes the language in a bottom up order - details first. But let's start with a brief tops-down overview of what a processor family description looks like, without going into details about each part.
@@ -175,7 +175,7 @@ When writing a target machine description, its not necessary to write descriptio
We will describe these language features here, primarily for completeness.
-#### **Defining Instructions**
+### **Defining Instructions**
Instruction definitions are scraped from tablegen files, and provide the following information to the MDL compiler for each instruction:
@@ -215,7 +215,7 @@ An example:
This describes an ARM add instruction that has two defined input operands (Rn, imm), one defined output operand (Rd), and one implicit output operand (NZCV), which is associated with two subunits (sub24, sub26).
-#### **Defining Operands**
+### **Defining Operands**
Operand definitions are scraped from tablegen files (like instructions), and provide the following information to the MDL compiler for each operand:
@@ -247,7 +247,7 @@ Some examples:
-#### **Defining Registers and Register Classes**
+### **Defining Registers and Register Classes**
Registers and register classes are scraped from tablegen output. We provide a general method in the language to define registers and classes of registers which can reflect the registers defined in tablegen.
@@ -278,7 +278,7 @@ Examples:
The order of register definitions is generally insignificant in the current MDL - we use the register names defined in LLVM, and there’s no cases in the MDL where we depend on order. Register “ranges”, such as “a[0..20]” are simply expanded into the discrete names of the entire range of registers.
-#### **Defining Derived Operands**
+### **Defining Derived Operands**
LLVM doesn’t necessarily provide all the information we want to capture about an instruction, so the MDL allows for defining “derived” operands with which we can associate named values. A derived operand is essentially an alias to one or more LLVM-defined operands (or derived operands), and provides a mechanism to add arbitrary attributes to operand definitions. Derived operands also allow us to treat a set of operand types as identical in latency reference rules (so you don’t have to specify a long set of operand types for some references.)
@@ -306,14 +306,14 @@ Grammar:
-##### **Derivation**
+#### **Derivation**
Each derived operand is declared with one or more “base” operands, for which it is an alias. Circular or ambiguous derivations are explicitly disallowed - there must be only one derivation path for a derived operand to any of its base concrete operands.
Derived operands are used in place of their base operands in operand latency rules in latency templates (described later). This allows a rule to match a set of operands, rather than a single operand, and also can provide access to instruction attributes to the latency rule.
-##### **Derived operand attributes**
+#### **Derived operand attributes**
Derived operand attributes associate name/value-tuple pairs with the operand type. Tuples are appropriate when an attribute is used as a set of masks for resource sharing, described later.
@@ -377,7 +377,7 @@ If all of an attribute’s predicates are “false” for an instance of an oper
-##### **Derived operand attribute usage**
+#### **Derived operand attribute usage**
There is currently only a single context in which instruction attributes are used directly in the machine description, as part of resource references in latency rules (see “latency\_resource\_ref”). In this context, you can specify an attribute name which provides the number of resources needed for a resource allocation, and the mask used to determine shared operand bits associated with the resource. An example:
@@ -390,7 +390,7 @@ There is currently only a single context in which instruction attributes are use
This resource reference uses the attributes from the operand associated with this reference to determine how many resources to allocate, and what bits in the operand to share.
-### **Overview of Resources**
+## **Overview of Resources**
Resources are used to abstractly describe hardware constructs that are used by an instruction in its execution. They can represent:
@@ -407,7 +407,7 @@ Its important to note that different instances of an instruction can use complet
The machine description provides a mechanism for defining and associating resources with the pipeline behaviors of instructions through the specialization of functional unit templates, subunit templates, and latency templates. It also allows automatic allocation of shared resources for an instruction instance from resource pools. The MDL compiler generates behavior descriptions which explicitly reference each resource (or resource pool) the instruction uses, and in what pipeline phases. This provides a direct methodology for managing instruction issue and pipeline behaviors such as hazards.
-#### Defining Resources
+### Defining Resources
There are a few ways that resources are defined:
@@ -437,7 +437,7 @@ Named resource definitions have the following grammar:
-##### Simple resource definitions
+#### Simple resource definitions
The simplest resource definition is simply a comma-separated list of names:
@@ -452,7 +452,7 @@ A resource can have a set of bits associated with it. This defines a resource th
**<code>resource immediate:8; // define a resource with 8 bits of data</code></strong>
-##### Grouped resource definitions
+#### Grouped resource definitions
We can declare a set of named, related resources:
@@ -491,7 +491,7 @@ Groups can also be implicitly defined in functional unit and subunit template in
This implicitly defines a resource group with three members, and passes that group as a parameter of the instance.
-##### Pooled resource definitions
+#### Pooled resource definitions
We can also declare a set of “unnamed” pooled resources:
@@ -525,7 +525,7 @@ Finally, resource definitions can pin a resource to a particular pipeline phase.
where E1 is the name of a pipeline phase. The resource “my\_pool” (and each of its elements) is always modeled to be reserved in pipeline phase E1.
-#### **Using Resources**
+### **Using Resources**
Resource references appear in several contexts. They are used in all template instantiations to specialize architecture templates (functional units, subunit, or latency templates) and are ultimately used in latency rules to describe pipeline behaviors. These will be described later in the document.
@@ -567,7 +567,7 @@ References in latency reference rules have additional syntax to support the allo
-##### **Allocating Grouped and Pooled Resources**
+#### **Allocating Grouped and Pooled Resources**
Latency references allow you to optionally manage allocation of pooled resources, as well as specifying the significant bits of operands whose values can be shared with other instructions.
@@ -616,7 +616,7 @@ This reference utilizes the resource - or an entire pool - and uses the operand
We will describe how these references work when we describe latency rules.
-### **Defining a Processor Family**
+## **Defining a Processor Family**
A TableGen description describes a family of processors, or subtargets, that share instruction and register definitions. Information about instruction behaviors are described with Schedules and Itineraries. The MDL also uses common instruction and register descriptions, scraped from TableGen, and adds first-class descriptions of CPUs, functional units, and pipeline modeling.
@@ -630,7 +630,7 @@ In an MDL CPU description, a CPU is described as an explicit set of functional u
More detail on this below.
-#### **Method 1: SuperScalar and Out-Of-Order CPUs**
+### **Method 1: SuperScalar and Out-Of-Order CPUs**
Fully protected pipelines, forwarding, out-of-order issue and retirement, imprecise micro-operation modeling, and dynamic functional unit allocation make this class of
@@ -645,7 +645,7 @@ The downside of this method is that you can’t specialize functional unit insta
We generally describe this as a “bottoms-up” approach (subunits explicitly tying to functional unit instances), and is the approach used by the Tablegen scraper (tdscan) for “Schedule-based” CPUs.
-#### **Method 2: VLIWs, and everything else**
+### **Method 2: VLIWs, and everything else**
This method is appropriate for machines where we must provide more information about the detailed behavior of an instruction so that we can correctly model its issuing and pipeline behavior. It is particularly important for machines with deep, complex pipelines that _must_ be modeled by the compiler. It has a powerful, flexible user-defined resource scheme which provides a lot more expressiveness than either “Schedules” or “Itineraries”.
@@ -658,7 +658,7 @@ We describe this as a “tops-down” approach (explicit functional unit templat
assert which subunits they support). This is the method tdscan uses when scraping information about itineraries.
-#### **Schema of a Full Processor Family Description**
+### **Schema of a Full Processor Family Description**
By convention, a description generally describes things in the following order (although the order of these definitions doesn’t matter):
@@ -727,7 +727,7 @@ We will describe each of these items in more detail. A machine description for
-##### **Bottoms-up vs Tops-down CPU Definition Schemas \
+#### **Bottoms-up vs Tops-down CPU Definition Schemas \
**
In the “tops-down” schema, we define CPUs, which instantiate functional units, which instantiate subunits, which instantiate latencies. At each level of instantiation, the object (functional unit, subunit, latency) can be specialized for the context that it’s instantiated in. We think of this as a “top-down” definition of a processor family. We provide detailed descriptions for each functional unit template, which we can specialize for each instance.
@@ -761,7 +761,7 @@ Note that we don’t explicitly define the ALU functional unit template, but it
While this schema is much more compact, neither the functional units nor the subunits/latencies can be specialized. This is an appropriate approach for scalar and superscalar processors, and is used by tdscan for CPUs that use Tablegen Schedules.
-#### **Specifying the Family Name**
+### **Specifying the Family Name**
A family name must be specified that ties the description to the LLVM name for the processor family. It has the following grammar:
@@ -772,7 +772,7 @@ family_name : 'family' IDENT ';' ;
-#### **Pipeline Definitions**
+### **Pipeline Definitions**
We don’t explicitly define instruction “latencies” in the MDL. Instead, we specify when instructions’ reads and writes happen in terms of pipeline phases. From this, we can calculate actual latencies. Rather than specify pipeline phases with numbers, we provide a way of naming pipeline stages, and refer to those stages strictly by name. A pipeline description has the following grammar:
@@ -829,7 +829,7 @@ phases my_pipeline { fetch, decode, #read1, read2, ex1, ex2, write1, write2 };
This indicates that “read1” is the first execute stage in the pipeline, which serves as the “default” phase for any operand that isn’t explicitly described in a latency rule.
-#### **CPU Definitions**
+### **CPU Definitions**
In the definition of a single CPU/subtarget, we specify a high-level description of the processor:
@@ -914,7 +914,7 @@ and a cluster definition has the schema:
Below are some examples of increasingly complex CPU definitions.
-##### **Simple Scalar CPU Definition**
+#### **Simple Scalar CPU Definition**
In the simplest case, an empty CPU indicates a processor with no specific functional unit information. We assume a serial execution of instructions, with “default” latencies:
@@ -947,7 +947,7 @@ A slightly more complex example is a CPU that is single-issue, but has more than
-##### **Multi-Issue CPUs**
+#### **Multi-Issue CPUs**
Here’s an example of a 2-issue processor with two identical functional units:
@@ -974,7 +974,7 @@ Processors commonly have functional units with different capabilities - memory u
-##### **Defining Issue Slots**
+#### **Defining Issue Slots**
Multi-issue CPUs always have a constrained set of instructions they can issue in parallel. For superscalar, OOO processors this is generally tied to the number of issue pipelines that are available. For VLIW, issue slots map directly to encoding bits in a parallel instruction. In the MDL, you can explicitly define issue slots. An example:
@@ -994,7 +994,7 @@ In this example, we have 3 functional units, but only two issue slots. So any o
When issue slots are not specified, each functional unit runs in its own dedicated issue slot.
-##### **Reservation of Issue Slots**
+#### **Reservation of Issue Slots**
In VLIW architectures (in particular), some functional units may be “pinned” to a specific set of issue slots, or use multiple issue slots in some cases. We provide syntax for specifying this:
@@ -1011,7 +1011,7 @@ In VLIW architectures (in particular), some functional units may be “pinned”
-##### **SuperScalar and Out-Of-Order CPUs**
+#### **SuperScalar and Out-Of-Order CPUs**
In general, the overall approach for defining superscalar CPUs is quite different from other CPU types. This class of architecture requires information about the size of the reorder buffer, and details about queues for each functional unit. Actual functional unit utilization is described in latency or subunit rules, which can specify exactly which functional units are used.
@@ -1031,7 +1031,7 @@ Functional units can be unreserved (like alu1, below), which means that an instr
-##### **Parameterized/Specialized Functional Unit Instances**
+#### **Parameterized/Specialized Functional Unit Instances**
A functional unit template can be parameterized with register classes and resource references so that each instance of that functional unit template can be specialized for a specific context. The actual use of these parameters is specified in the functional unit template, explained in the following sections. This section describes template specialization parameters.
@@ -1073,7 +1073,7 @@ A **resource parameter** indicates that instructions that execute on the functio
-##### **Functional Unit Clusters**
+#### **Functional Unit Clusters**
A processor definition can include named “clusters” of functional units. Each cluster can define local resources, and define its own issue rules. The purpose of clusters is primarily as a syntactic convenience for describing processors with functional unit clusters. An example:
@@ -1102,7 +1102,7 @@ A processor definition can include named “clusters” of functional units. Eac
This describes a 4-issue machine, where 2 instructions can be issued on each cluster per cycle.
-##### **Defining Compound Functional Unit Instances**
+#### **Defining Compound Functional Unit Instances**
Its often convenient to define “compound” functional unit instances as collections that include 2 or more “component” units. A compound unit includes all the capabilities of its component units. Each component can specify its own reservation queue size.
@@ -1123,7 +1123,7 @@ This construct is similar to the “super-unit” concept in tablegen. Only one
Currently, we don’t support specialization parameters on compound functional unit instances. However, you can define functional unit templates with base units, and this provides similar capability.
-##### **Associating a CPU definition with an LLVM subtarget**
+#### **Associating a CPU definition with an LLVM subtarget**
A cpu definition can be directly associated with one or more LLVM subtargets, for example:
@@ -1132,7 +1132,7 @@ A cpu definition can be directly associated with one or more LLVM subtargets, fo
At compile time, we can select which CPU definition to use based on normal target-selection command-line options.
-##### **Modeling Forwarding**
+#### **Modeling Forwarding**
Forwarding is modeled by describing a forwarding network between functional units. The necessity of the concept of a “forwarding” network implies that such networks aren’t fully connected or uniform.
@@ -1177,7 +1177,7 @@ In short, there are architectural cases that cannot be modeled precisely, and th
Note: there is a philosophical question of whether we should provide best case or worst case latencies when the forwarding cannot be statically predicted. Generally, we believe that worst case latencies are better than best case latencies, simply because too-short latencies can produce code which occasionally (or always) stalls. On the other hand, overestimating the latency produces schedules where a pair of dependent instructions _tend _to be scheduled far enough apart to avoid stalls. In effect, schedulers will separate instructions by the requested latency only when there’s other useful work to do. Otherwise, there’s no reason to separate them - the stall is inevitable.
-#### **Functional Unit Template Definitions**
+### **Functional Unit Template Definitions**
A functional unit template describes, abstractly, what operations can be performed on any instance of the unit, and how those operations use the template parameters - register classes and resource references. An abstract set of operations is represented by a subunit instance, which represents a set of instructions with similar behavior in terms of functional unit usage, resource usage, and register classes. Functional unit templates are defined in their own private namespace.
@@ -1230,7 +1230,7 @@ The general schema of a functional unit template looks like this: \
-##### **Simplest Functional Unit Template Definition**
+#### **Simplest Functional Unit Template Definition**
The simplest example of a functional unit template would define a functional unit that has no parameters, and implements a single subunit:
@@ -1246,7 +1246,7 @@ The simplest example of a functional unit template would define a functional uni
In this case, any instruction that is defined to use the subunit “xyzzy” can run on this functional unit. This template doesn’t impose any additional constraints on those instructions, and no shared resources are used.
-##### **Defining Functional Unit Resources**
+#### **Defining Functional Unit Resources**
A functional unit template can locally define resources which represent hardware resources tied to _each instance_ of the functional unit. These can be used to specialize subunit instances:
@@ -1269,7 +1269,7 @@ In this example, the functional unit supports 3 classes of instructions (add, su
Importantly: functional-unit-local resources which are used for multiple cycles can be used to model non-pipelined functional units - i.e.units which are reserved for some number of cycles.
-##### **Defining “Port” Resources**
+#### **Defining “Port” Resources**
A port is a resource type that explicitly binds a named register class with a resource reference. A port is used to specialize subunit instances, and adding functional-unit-specific register constraints on instructions associated with the subunit.
@@ -1307,7 +1307,7 @@ This syntax could potentially be used to connect a port to more than one constra
Ports can be used to specialize subunit and latency instances, described in subsequent sections.
-##### **Using Template Parameters**
+#### **Using Template Parameters**
Resource parameters can be used exactly like locally defined resources to specialize subunit instances. Register class parameters are used to define ports. Resource parameters can refer to a single resource, a pool of resources, or a group of resources.
@@ -1343,7 +1343,7 @@ A simple example of a full functional unit template definition:
-##### **Conditional Subunit Instances**
+#### **Conditional Subunit Instances**
In a functional unit template, a subunit instance can be conditionally instantiated based on a predicate. Predicates are simply names of the instantiating cpu definition and functional unit instance. This allows us to specialize a functional unit instance based on how its instantiated, for example:
@@ -1363,7 +1363,7 @@ func_unit my_func() {
-##### **Using Base Functional Units**
+#### **Using Base Functional Units**
Functional units tend to get more capable over generations of a processor, so we’d like a way to derive functional units from other functional units. A functional unit template can be defined to have a base functional unit, for example:
@@ -1379,7 +1379,7 @@ In this example, the template “my\_func” simply includes the definition of
In effect, when you instantiate a based functional unit, you implicitly instantiate its bases and any subbases. This language feature allows us to easily extend functional unit definitions over processor generations.
-##### **Defining functional unit groups**
+#### **Defining functional unit groups**
When defining a superscalar CPU, its generally not necessary to provide a functional unit template definition for each functional unit, since latency rules specify which functional units are used by a subunit. In this case, its helpful to be able to easily specify an arbitrary pool of functional units that can be used for an instruction. So the MDL has a way to do that.
@@ -1400,7 +1400,7 @@ For example:
This defines a functional unit group with 3 members, and a single input queue of length 42. These groups are used in latency rules to tie subunits to a pool of functional units.
-#### **Subunit Template Definitions**
+### **Subunit Template Definitions**
Subunits are used to link sets of instruction definitions to their pipeline behaviors and candidate functional units. Subunits appear in three contexts:
@@ -1478,7 +1478,7 @@ The optional predicate is a comma-separated list of names which refers to the CP
A subunit template can specify as many latency instances as needed - the resulting subunit is the union of all the valid latency templates. This allows you to separate different classes of behaviors into different latency templates. Since latency templates are also specialized, you can manage the separation in latencies. The typical practice is for a subunit to have a single latency instance.
-##### Subunit Template Parameters
+#### Subunit Template Parameters
Subunit template parameters can be a mix of ports and resources, and are used to specialize a subunit for the context in which it is instantiated, for example:
@@ -1491,7 +1491,7 @@ Subunit template parameters can be a mix of ports and resources, and are used to
In general, these work exactly the same way functional unit templates are used. They can be used as latency parameters to specialize latency instances.
-##### Tying Instructions to Subunits
+#### Tying Instructions to Subunits
There are two ways to associate subunits to instructions:
@@ -1503,7 +1503,7 @@ There are two ways to associate subunits to instructions:
We discuss these two approaches below.
-###### Subunits in Instructions
+##### Subunits in Instructions
Subunits are associated with instruction definitions to...
@@ -1519,7 +1519,7 @@ Each defined instruction must specify at least one subunit that it is bound to.
We allow more than one subunit per instruction, which implies different instruction behaviors across CPUs or functional units. In general, this isn’t necessary, since a subunit can specify different behaviors for different functional units and/or CPUs. So this is strictly a stylistic choice.
-###### Subunit Bases
+##### Subunit Bases
A subunit template definition can have one or more “bases”. A base is either the name of another subunit, or a string representing a regular expression of instruction names. Bases tie a subunit to sets of instructions, either directly by instruction name, or transitively through their base subunits. A subunit does not need to have the same parameters as its bases, and does not inherit any latency information from its bases.
@@ -1534,7 +1534,7 @@ This example ties the “add” subunit to any instruction with “ADD” as a n
Subunit bases provide an alternate way of tying instructions to subunits without modifying the instruction definitions (where each instruction can tie itself to a set of subunits). This effectively allows a single “base” subunit - and all of its associated instructions - to have different latency behaviors for each target.
-##### Shorthand Subunit Template Definitions
+#### Shorthand Subunit Template Definitions
Often a subunit template simply specifies a single latency template instance, and the latency template may only be used in a single subunit template. In that case, we have a shorthand that combines the latency template into the subunit template. For example:
@@ -1558,7 +1558,7 @@ subunit load(resource a, b, c) {{
-#### **Latency Template Definitions**
+### **Latency Template Definitions**
A latency template specifies the detailed pipeline behavior for a class of instructions. The class of “client” instructions for a latency template is the set of instructions that use any subunit that instantiates the latency template.
@@ -1644,7 +1644,7 @@ The full grammar:
-##### **Derived Latency Templates**
+#### **Derived Latency Templates**
A latency template can be derived from one or more base latency templates. Any hierarchy is allowed (except recursive), as long as the base template has the exact same leading parameters as the derived latency. A base latency can be included more than once in the hierarchy - this doesn’t matter, since all occurrences of that base are identical (so duplicates are ignored):
@@ -1660,7 +1660,7 @@ A latency template can be derived from one or more base latency templates. Any
In this example, my\_latency includes base1, base2, and base3. Deriving latency templates is a fairly common pattern: instruction classes often share _some_ behaviors, but not all. So those shared behaviors can be put in a base latency template. A common example is an instruction predicate, perhaps shared by all instructions.
-##### **Latency References**
+#### **Latency References**
A latency reference statement describes a single operand reference and/or resource references in a specified pipeline stage. It references instruction operands _by name, _as well as resource and port parameters, and ties the operations to named pipeline phases.
@@ -1675,7 +1675,7 @@ Latency references have the following general form:
where either the operand specifier or ports/resources may be omitted. A single reference statement asserts that an operand and resources are referenced in a specific pipeline phase for any instruction that this rule could apply to, ie: _any instruction that uses a subunit that instantiates this latency template._ Each aspect of a latency reference are described below.
-###### **Operand and resource latency operators:**
+##### **Operand and resource latency operators:**
There are 6 basic operator types in a latency reference:
@@ -1697,7 +1697,7 @@ There are 3 additional operator types which are primarily used as shortcuts (the
* or - this is essentially a conditional def, but the instruction has no explicit predicate (useful for status-setting instructions).
-###### **Phase Expressions**
+##### **Phase Expressions**
The phase expression specifies the pipeline phase that the operation occurs in. The expression can refer directly to a defined phase name, or an expression based on a phase name:
@@ -1721,7 +1721,7 @@ where “$width” is an immediate instruction operand. Its value is fetched fro
Phase expressions have a limited set of operators: +, -, \*, /, (). Since latencies must be positive integers, we also provide a “floor” operator which converts negative expressions to 0. Simply enclose the expression in curly braces ({...}).
-###### **Operand Specifiers**
+##### **Operand Specifiers**
The operand specifier has the same grammar as in tablegen, which allows you to specify an optional operand type, the operand name, and optional sub-operand names:
@@ -1773,7 +1773,7 @@ Or you can differentiate based on the operand name:
Note that operands _can _be referenced by their index in an instruction’s operand list, but this is error-prone and this isn’t considered best practice because we can’t thoroughly check the validity of the index. The syntax is simply “$<index>”. Note that sub-operands often aren’t given names in tablegen, and must be referenced by index, for example: $src.1. Unnamed variant operands (obviously) don’t have names, and are referenced by their position past the end of the operands defined for an instruction, ie “$$1”, “$$2”, etc.
-###### **Resource References**
+##### **Resource References**
Any latency reference can include an optional set of resource references. These have slightly different semantics depending on the operator type (def/use/predicate/hold/reserve).
@@ -1796,7 +1796,7 @@ For “hold” and “reserve” operations, the operand specifier is optional,
-##### **Conditional References**
+#### **Conditional References**
Any reference in a latency rule can be conditional, using a predicate identifier. The predicates are generally identical to LLVM predicates, and check an attribute of a client instruction.
@@ -1811,7 +1811,7 @@ else { <set of refs> }
-##### **Functional Unit and Micro-op References**
+#### **Functional Unit and Micro-op References**
A latency rule can directly specify a set of functional units and how long they are used, as well as specifying the number of micro-ops required for the operation. Each functional unit can optionally specify a pipeline “StartAt” cycle, which by default is the first execution phase.
@@ -1828,7 +1828,7 @@ fus(ALU, 2); // use ALU for 1 cycle, 2 micro-operations.
These statements allow a latency rule (or subunit) to tie a set of instructions to functional unit instances. When there is more than one instance of the specified unit, or if the unit is declared to be a functional unit group, at compile time _one_ of those units is selected. Likewise, if the unit is a subunit of one or more functional units, one of the “parent” functional units is selected.
-### **Machine Description Compiler Artifacts**
+## **Machine Description Compiler Artifacts**
What does all of this produce?
@@ -1857,7 +1857,7 @@ As part of this effort, we will incrementally modify the LLVM compiler to altern
-### **Using the MDL Language in LLVM**
+## **Using the MDL Language in LLVM**
The proposed use case for the MDL language is as an alternative specification for the architecture description currently embodied in TableGen Schedules and Itineraries, particularly for architectures for which Schedules and Itineraries are not expressive enough. It is explicitly _not_ the intent that it “replace TableGen”. But we believe that the MDL language is a better language (vs Schedules and Itineraries) for a large class of accelerators, and can be used effectively alongside TableGen.
@@ -1892,14 +1892,14 @@ The general development flow of using an MDL description in LLVM looks like this
-#### **TdScan**
+### **TdScan**
To synchronize an MDL architecture description with llvm TableGen descriptions, we’ve written a tool which scrapes information that the MDL compiler needs from Tablegen files. In the general case, it collects basic information about registers, register classes, operands, and instruction definitions, and it produces an “mdl” file which can be processed by the MDL compiler to sync an architecture description to the tablegen descriptions of instructions.
For currently upstreamed targets that use Schedules or Itineraries, TdScan can also extract the whole architecture specification from the tablegen files, and produce an MDL description of the architecture. We’ve used this approach to prove out our llvm integration with upstreamed targets. The integration and testing of this is ongoing.
-#### **Upstream Targets**
+### **Upstream Targets**
In general, upstream targets have no compelling need for MDL descriptions - the existing Schedules and/or Itinerary descriptions are field tested. However, there are a few benefits to using an MDL description for existing targets. The primary benefit is that the MDL descriptions are typically quite a bit smaller, succinct, and (we believe) intuitive than the equivalent TableGen descriptions.
@@ -2007,7 +2007,7 @@ In general, upstream targets have no compelling need for MDL descriptions - the
\*\* Note: the MDL numbers are generated both with and without “index-based” references in subunit/latency rules, vs symbolic references. These are typically 10-20% less lines of MDL description than when operand names are used, almost entirely due to operand name differences between instruction definitions (like “dest” vs “dst”, or “src1” vs “s1”). However, the databases produced by the two approaches are virtually identical - albeit ordered differently.
-#### **Syncing Instruction Information**
+### **Syncing Instruction Information**
The MDL compiler needs 3 pieces of information from tablegen for each machine instruction:
@@ -2022,7 +2022,7 @@ Subunits are a new concept introduced with the MDL. The normal approach is to m
As part of the build process, we use a program (“tdscan”) which scrapes the instruction information - including the subunit information from a target’s tablegen files and generates information about the target’s instructions. Tdscan allows us to stay in sync with changes to instruction definitions.
-#### **Using the generated microarchitecture information in LLVM**
+### **Using the generated microarchitecture information in LLVM**
There are two classes of services that the MDL database and associated APIs provide:
@@ -2050,7 +2050,7 @@ We provide code and libraries to do the following things - in machine-independen
There’s more we can do here, and a deeper integration with upstreamed LLVM is a long-term goal.
-#### **Current Status of the LLVM Integration (briefly)**
+### **Current Status of the LLVM Integration (briefly)**
@@ -2063,7 +2063,7 @@ There’s more we can do here, and a deeper integration with upstreamed LLVM is
-### **Appendix A: Full Language Grammar**
+## **Appendix A: Full Language Grammar**
This may be slightly out of date. The definitive Antlr4-based grammar is in llvm/utils/MdlCompiler/mdl.g4.
@@ -2377,10 +2377,10 @@ range : number '..' number ;
-### **Appendix B: Future Directions**
+## **Appendix B: Future Directions**
-#### **Memory Hierarchy**
+### **Memory Hierarchy**
We need a first class representation of any compiler-managed memory hierarchy.
@@ -2422,7 +2422,7 @@ DMA system descriptions
Multi-Processor System Topology
-### **Appendix C: RISC-V Generated Architecture Description**
+## **Appendix C: RISC-V Generated Architecture Description**
This is a complete, automatically generated machine description for RISC-V using our tool to scrape information from tablegen files. We can automatically generate MDL specifications for all targets that have schedules and/or itineraries. We include RISC-V here for illustrative purposes.
>From 0cb3f6d31647e611959a64faa9e7b4eda47e84d7 Mon Sep 17 00:00:00 2001
From: Reid Tatge <35816723+reidtatge at users.noreply.github.com>
Date: Fri, 12 Jan 2024 16:44:38 -0800
Subject: [PATCH 03/14] Update RFC.md
---
llvm/docs/Mdl/RFC.md | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/llvm/docs/Mdl/RFC.md b/llvm/docs/Mdl/RFC.md
index e6fa6e350058a7a..f8d35dc27c16447 100644
--- a/llvm/docs/Mdl/RFC.md
+++ b/llvm/docs/Mdl/RFC.md
@@ -1,12 +1,12 @@
-## MDL: A Micro-Architecture Description Language for LLVM
+# MDL: A Micro-Architecture Description Language for LLVM
November 2022 Reid Tatge [tatge at google.com](mailto:tatge at google.com)
Updated January 2024
-#### **TL;DR:**
+## **TL;DR:**
We’ve created a DSL and compiler for modeling micro-architecture that handles a very broad class of architectures - CPUs, GPUs, VLIWs, DSPs, ML accelerators, and embedded devices. This effort grew out of a need to quickly develop and experiment with high-quality compilers and tools to facilitate rapid architecture exploration. We named the DSL “MDL” for “Microarchitecture Description Language”.
@@ -16,7 +16,7 @@ While being significantly more expressive than TableGen’s Schedules and Itiner
The MDL compiler, associated tools, and documentation are available as open source (at https://github.com/MPACT-ORG/llvm-project/tree/all), and we would like to explore adding this to the LLVM project, and encourage contributions from others.
-#### **Background**
+## **Background**
Over the last few years, we have been using LLVM to develop a compiler backend for Google’s TPU machine learning accelerators. TPUs have complex microarchitectures and pose a number of challenges that are not seen in in typical LLVM targets:
@@ -34,7 +34,7 @@ Over the last few years, we have been using LLVM to develop a compiler backend f
While some of these problems manifest in a few upstream LLVM targets, this collection of problems is a superset of the problems directly addressed by LLVM - Schedules and Itineraries are simply not sufficient to model everything. Supporting this class of architecture is therefore code-intensive - it takes around 20,000 lines of C++ code to model the TPU sub-targets. This is brittle, hard to write, debug, test, and evolve over time. In contrast, the MDL description for these sub-targets is ~2,000 lines of text, and requires very little (if any) target-specific code in the backend.
-#### **Status**
+## **Status**
@@ -43,14 +43,14 @@ While some of these problems manifest in a few upstream LLVM targets, this colle
* We’ve modified the CodeGen and MC libraries to (optionally) use our methodology for latency management.
-#### **Building**
+## **Building**
* You can build llvm with or without MDL support. It is included by using the LLVM\_ENABLE\_MDL CMake parameter. If included, it is currently used by default, and can be disabled with a command line option (--schedmdl=0).
-#### **Testing**
+## **Testing**
>From e568c9cedd2910c9cb8cf3781c70c4ab51d0aa86 Mon Sep 17 00:00:00 2001
From: Reid Tatge <tatge at google.com>
Date: Tue, 16 Jan 2024 19:57:21 +0000
Subject: [PATCH 04/14] Fix some documentation errors
---
llvm/docs/Mdl/MachineDescriptionNotes.md | 13 ++-----------
.../Mdl/images/MachineDescriptionDevFlow.png | Bin 0 -> 80187 bytes
.../Mdl/images/MachineDescriptionSchema.png | Bin 0 -> 54791 bytes
3 files changed, 2 insertions(+), 11 deletions(-)
create mode 100644 llvm/docs/Mdl/images/MachineDescriptionDevFlow.png
create mode 100644 llvm/docs/Mdl/images/MachineDescriptionSchema.png
diff --git a/llvm/docs/Mdl/MachineDescriptionNotes.md b/llvm/docs/Mdl/MachineDescriptionNotes.md
index d6624051ef59d6d..8cdd233a2b91e95 100644
--- a/llvm/docs/Mdl/MachineDescriptionNotes.md
+++ b/llvm/docs/Mdl/MachineDescriptionNotes.md
@@ -1848,12 +1848,7 @@ The other primary artifact is a set of objects and methods for managing the low-
As part of this effort, we will incrementally modify the LLVM compiler to alternatively use this information alongside of SchedMachineModel and Itinerary methodologies.
-
-
-<p id="gdcalert1" ><span style="color: red; font-weight: bold">>>>> GDC alert: inline image link here (to images/image1.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert2">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>> </span></p>
-
-
-
+
@@ -1884,11 +1879,7 @@ The general development flow of using an MDL description in LLVM looks like this
5. Build LLVM.
-
-<p id="gdcalert2" ><span style="color: red; font-weight: bold">>>>> GDC alert: inline image link here (to images/image2.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert3">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>> </span></p>
-
-
-
+
diff --git a/llvm/docs/Mdl/images/MachineDescriptionDevFlow.png b/llvm/docs/Mdl/images/MachineDescriptionDevFlow.png
new file mode 100644
index 0000000000000000000000000000000000000000..8e4c887bee1aedc3ff8c03f9b6949f9b5122bfba
GIT binary patch
literal 80187
zcmeFZWmuKp_BN_?cY`1y2olmrE>h_ZNu|4_(<NP!(y<Vb?rxD5frV1iA>G|@CjR!`
z at 7d@5U+4XJz8pVsc`cqbpE1WA;~w{YPr_7`USeZVU_5y609*Ezl-h#_h+iK(K%hcH
z0RK}bro#H*!TSfYQsNpOhT9paIvTy-g4GqB?-=;&=ify4l!f)g8HZDt7#p+7DyVem
zJivU+S3&m%*}FTq^)Vfv3Tr{Aag_01<=ed{){#wjYeQySKb%QONTg1^vpjv=@-tq%
z8*19as(zQri7$ah8;B>t^@H0B>HY^a+AcB-o_~JggFqSo`7e~G at V`F<PCh_Rz5h at k
z9wiJy`1c26L?X+79%B0*LGka?La|j~=zpJ4`SAaL*#Ac{%aS|Y{vDtE?e^yC#568M
z!1+&T%eau+Haz}*YvPvwAVYV5=0!w53_!uAc;RfSprGLFTxGazwL0z4?kd;u`}b>Q
z#>VJcn~6>Le9hJ2EDj7WZ|?z{n+{Z(+_F#iS)lyB<uP13oG3Q<ZBUczmW;Hth|jqS
z#~qOb)Q`^R^tVOTw1}|qv1zeF@^kUTK{OGsV?1Q$`&4>m-w8$1-5=ziPZw~KC||M)
zK)8|mC!@Olyhp%h(I}{J-!p7Y%*VhuCWQWzSL$<w>lD1!Sej_)=uYq6J$qf1`{Qwe
zPUTV%Ch2i_CiPReGLjHRO?i2_SB@?LDJc_%+I<?v%*YrLTDrTti~Kfia^IWli>1dT
zW?`s?j+g3fUHtpkjx$BPkEu}pCT`43uq0Z|o7pB;@Z`i79YYyHCko8zFW#AhkhXfA
z5a`iikv)I&yUNUccV?vOk*JS=#Ny99d0iA)Q`6iZZl~L?*-oOxZbPG^LslX>FD@^Y
zGKDV|Is$b0!W0pFmwTe5BS=oRCX_X(iHHJw^jp0&hm#Nl<@hwsg?ulMb7kYZf|(vZ
zd^j>PLYA1zekO+VNRT1I;dhmEkHd7GV&(!&Jb+c`u72JxB0T)??Cd3qm{@z`yS2Gi
zZ|#8`r<+UHblo>^U<Gx`S)xa4!~9JcxYWWi*ocQ~xdO4Do at sxU{Y=1f2;yMfk;d;3
zPDlJqD`D2K-rnH#Sbsdz*tJz0H$oJ(`Y>`v*!1L~pQQFc58_Er4;!2NV5c239fy9y
zV|oswHdgMO9MdNQNgPQB_ggyG14W|v8fB{VpcDQsS>a_gwcT7xW2&NBi^l;J5w)n!
zY2oWb-p<KNlTWF)NOcTHu-b_-gLv5r!BDFp4B`aq+dpXzZBTa>-kWGF44&h9 at 3UPH
zC(WX38Z!B>!5oGy1xcJK6#VwA)jLzQm}{6BW2<`^Kjizf6}{fZqvz8fg;EDUn<!L&
z$$TmHTq%Y`$aQm+%j~-)d69Pc?N)jFmm-m%XWC`320l6hB37LW$q<}Gc^5}I>$<D6
zJxM$#`2=<Y-6&Ln-(iGI-#?HMSd#OQu<I94G1*n=!JOP^X=xLSKS7`f$h!6RzSrkY
zy#9l!yk^1s`;O#d7DH6z97(Y*J5!onFpJTTHy3MJX69HXro#7!t=@?h+6MBu(Rsym
zwaRSZo6#5+CJC#@R%yLyFwezy^{`TwC|g8<wGP;Xyectr9?O^?%d4x5%Wr>1QSipe
zS|L25;<ry%`)$HS2X~y8`^3V`oA;1mQVp&NRZ>vsl4XA4 at _2n}=zS`rT(_1*F at W@|
zktz~P2~+Na;a_F==POA at bDnFDL~N`bv+M0=ixPh#QDE5T9f9nip`qcxSoMSUV870h
z!Opwn`MS at +$S6aS!e^JN03w$e`I18xlXRH|i+f)dpL288`}W%NMahSpHRzxnDEBc~
zOF9U4RgSfYs5pJOdGbl$5Jxp8^{!5L3=9lvW#v2~^`~K%bS3hxHnJz1V`iC?lREgG
zXS=f;?bm8O0U(K|ySuvw28!KwrmTgNg*~fu-!>umZjLe!pwIF^*{q(CXh4;;2foJ8
zN{%jBhw#`=;xXm at 8S5AU8CKf+g;7vYx77dc_C_~Dvsf!=vetgK$$90wwQyBowACom
z)cPJ)++O>gA<>T&1mC08!D!LTSB2Af=es>ol+uNI_4b9o#x_y2Erv7csx%7K&i3Y`
zBO>B|6A%!X@}2Cx09zdYH@!1^7m>W?T0FU`<LNBchBDNBKda@*sqreT7H)|Lpmao=
z1%o#T%au=JFC3s;kgZC1GvDURRjc3V>}+6_CF*M`ynl4m?0Z$mTKjHINwXP~lpQN7
zzHl7*awO;Fyw6e8j|J0An~+sTMn?PJRmgKWiu2#%%!(BXk#*l^c5IaE)#G$$AHoHA
zYu|KyXm;OA?AC-PjuvS?V`XKfqeHm)@+8cV&9Fs45Q)4ek~{}nThMir;aSLVVf!CR
zW_^|P@>jm+`-`B8g%dwx<bH$3psYw}`7l@^#vvh<*M`K!Nb#E)u{IKKI#-StORyjv
z!S(61LsgKBC4z|U<nu-^9mFJAw&XI1x0e?SvC!f%A_9VAWu5)3pxO5XT(N5vMK+_h
z7Jc#2R&RImy}dn-XTl!)u$D3HQr#z%?<v*Xcnu5cJ2uCP&745%U>II at L}-26iIPJ8
zBbigO%YAEHQKs!=TyHZl-Sq4Ghg`T=l0)`QO-<iDPRbWQEG)c9nX0x>#!pF4FR|vQ
zdg7Yh3*JP=!0~ftsw?zkRMe-!2N-#S5k?J;;sywqbO~cWQX!zc=;<j(E=om^u#F0{
z>D46^CL&;~sv{flN{D}A(Hwp4n4Bf3b#b{>ZbrbP&Ae9QvZ0p3AfB80GBY&~(mATB
zCrw}5j$VL>7;oUdSRs+dXE*v`9GQZ@=+c5PGNGo?F7lz@`66n{!@$76PzKF}fduB9
zTNVv=`wjyp)WppNl^d#TP0!_rS@#7J#Yq4<S7jFQ1M7`<==IInynMn_T6$k!-xFhV
zzpEX7SLYf~u;~nW`N+cRHaeKHeCX6y#tAz^aFb%6Z at gO@DwJlRmx)xVHfZ-V=+Yy#
z)Lb9Qd?e&%Nv>dipoZP{wlkPZmU!K`JG^80lk*)SSCJCra}g!KeJFz>to>?NXt1o#
zZu*P)`@1Jko)nV5Zwg%ji%2 at y{9v0yy!K#-tvdT5of_f#2V_j^cdc($f23GbUpx~O
zXD71s_xI1UoQjZTH)zT&TPxHkj8l+U>pL$fcuF2U!DXmYW2t)5TW&X9_enO<=J>wp
zwnTNJ9~WsBo0>m&-_ at 6r$Q^z4jMBLf)52z~=n388e34G^)~7K$!8bp-3~w%UGXz~t
zTTlY^%-^YvE9>E}i`|~*cpNNo)%x9BS{H>!L`3{xOnR2AhUo&}iW=!9p<;qrzSRL}
zUrGkM2X$W7C at 1b#1g@{YHSe`OqjQ*RDI8K5NYRiF#v-SyUL19VDv%&#td>@}ZfWrj
zg9<!4s{a(8<#$=AP^we;c|^f+Z?4sh at 3H$Ujb1<J+_zlwKUW5lwB>Ry>HEiuwO4Q@
z=e at Srp6SsMfZX*Y2q9dD!&OqqOI}y^m~!qVi^FiLbWiHTHf?u7mp5yfbdreKWhAir
z&=awwg>?BNg<B3iAG}FnA&W`xN6mNCqCPrZ#R#RD5y4G$)3W4zmI!PXU!JJ=@CHn=
z5!8z1L71LAVP3I?l;Dma2 at ZOy@8nh~!**&>bXzZeQH7&@&dD+3t8iYC!;iM1<*)Bq
zkecODY3)r{a~QE~RHvnVovZL0>t;R0l**-WZXgivYS9tl=9jV<^IfMv*a``G)*}t5
zW8b_+;Q#>!(bLDI*zzk9rU3of1`EojJH0XZ+&~PSYxi$g`{rn4eZPOa`7^`p0SHmQ
zRON)Q9|>x7O-sXWuCGl|nBgG5G`|0Suk$?}A3E;EafLL+-t2f^I^;eD%SS7a_?x7N
z`L`*kS!}I1ZXIv at +B6kAUy9%`#dm$!x^hS<!S!%APm=WP`6MSy{=|?ma1ytdU>!t>
zm{mu`Jkf at wrt}3sgDPx at qXnvxrTVj<-%iz7F&;(Nm`2VJD#Gj=f={<JDIb%hCzoKj
z^jN at ZZ<cK{pyP>2eZLR32`%ls8bDR|LM3+u9Yx)c$WnbXZT|bOjanM5GTmA^#=_|r
z?MFjGOKX{jb1L=Hq?lrU7b~RXCT8S<w0w(F&^mX=&k(}641pMknAdTEY&;`Zems{|
zljo5+uPCUzt|M64x9lqGT$@RpjxM~_m&>JxD+9%{<Q?G<$@imnacu6$u?6u5_ej#a
zvJk<b)>_jQ5u13hJ<rBG3o_s0seZEvUiXnYsa%LKGkjBKcKzu<$Pn7-t&802UvvQI
z#>*O;ynN9sYzcq-f@^!eT`W$}eV3KHnEQ92DKZmAO=|!lvf!TDmmhc3_R`zZ8$ZoX
z43%(S;#<B-J4GYbSp}JFW?iV3XZjOh(&VP&EHd=){_Aam3++8{)D4?lWOZLv8h3-f
znP*PTZ5}C{9$)1n(Yfwe1nCT@)i`-LV5ye+X>X=cJtI=vAM(Y{B<YLglFO*93zf7e
zvG5fV1&<{h5=GjMQ^PRmS6vR#d+nIc_?rO^Ago-e6{Q`>tft-<?CFW(29yEfU(z>v
z%|!gJ8(Oqg at l42G2m?%(-gNYcc7u+_N_JbK at Mj)tYYM^++QO3k3!mtYkF<nYNi7_3
z(3y?EGPR9-pB$kvDy0{g|B_-Dj1q9$o>cuT6=pt|8Wa>%C{`a=aP)oi);KdWQ+EjT
z*aCm5a)4s;Fh#wN(Rwe>m!ko$Yz3bNE%ZBsCTzw0F~P}*6HK?(TG!^SG=K_isV`^0
zDG;tp1Yxl0R6v+-JR(rWMl#emRQk1`A0s0*!oRfQqh69oQ}Ede7<ZvHI>7qp5N<|Z
z()2faTIQv)DQ?rj_utsrI-c*pb){JclYzs0o5A3F)z7ET-5TQzr435<78hv^Bi<5U
zsw-U=H&2A2TS;(zB+O6Qp(r`akKd7iWRj#mg`eW2oVWbpg|Zv9UAr at X<y!o>NpthW
z-roN3%pbucSWrl<M5mIR+Z at s+&62<=EUZ6UTm~SswG;HRT3FL&yv(53f;R=scMRO`
zX+Wdu3M1q?0l2>?mjs+HP4=<ThudOwbjG0Js-2J89j5<SA|@jXRTa0jwQcvi8NGP5
z4{&U;uK5Ln#KPt#hUaX96FmyGqZgYi7>=qu>M)K$ciI{)q>n#b8;<@JTYc5=g-p0$
zcrIY|d#o(zlqSTy#KxP;%K<jfTOQqYy8aqSu{`7Zq$JX^6L_|y#ZWpkmkZdy!S~UU
zN$duR>;~awU-2ZS_mDGEzU(Sz2x<;8hQ9JdQ5;BQt7VvpF*bWaOWxaGw9h&DKSpW@
zjhdP|@mK3(QBgyKF#xEB1E_gzCsnwISTu`rFV+bQ!Y-+-#Jj_Zf9b0}SotYD+21np
zkZvrf6k(8y*COtCeMHh!!28q|OeDvDYQ7d)9sMeT_#gH&ZE_3zloB1&k10jKe*OcV
zdOWV at Fjj6va}%6yEnF5P_$bX4I-c2H at Okh`H_i$wb60@;L@|{IpWJ at Ft#lW~4jGG)
z-)<_Q>GBS$r|p{<6MxYYGq9vxZdl3)T^&rzXHkBI;#kGvgH?yJb+cjGj2EMioFx1^
zDK783ju$twU=9K{ZQ_xeRh7?$vm!lf;p=Mi)GdCb3RyOP6_uDwW at H`tUtbh!uPI`v
z<-14Sp2QcVnNtZk-siQ~$5F`cm^2Q89qC6fb`}>a^1w>*)N4K5FnK1M-8p)m%RRE%
z9}?QLooP^I`vmY*SeUB1=1*bFPYRekC|IC&X$@dF?wDqRd7+r_$O?fraat at t?2^YD
zo+nS55{SRxz1N!m<;%rOVhM%o at nMw6aX}$f*b$FXx_O;V#atFhV}U>jDVr`)CMgLC
zBTbz}(64-DZ%@y>LRQBr)f}1EcZ;I{h1RG!a*4!$%Xu07t+R8i*SNT$sYw^3>@g3|
zsIx1^jP at X+_}+YbJD)H6Q>~KZ_V)HmNAs{1J~wcd>yEiygjkY_^%-6~hBF=&zAlr-
zC*m-q%6HrN`K0vKIP#QfCT`vKDTqhd;Ion#D=10?DM#J)Ku<4?f5|N^GO6+QWTllT
z43(eT-fCu2?voWvl=oNvQb=h>M+etNPPFJxEeJlHQ<b$VRtlPofi)3_`iYHXCQEt=
z22DU|hnK(k(oq~Kk{8&9u%2{5R~AB})8_-p$;kkix$e!0FfbrhA!ogE&nWH}*3PH)
z1u5-?gZTKn$}pH8z-VN%4$oFqRXwy~m0 at 6F0#NW#%3D`3PVjOukooKD&#aH+Tpe#9
zR!gmd8UB0wke)F!{6nc;{bw4lvt8_@@X*i(=aq1^b>*Q<k>b<$X8DWG1>`?%Pb*D&
z!IbHak3R$WflLZp>im1uZYQIExW6d5QV|9Y;mEsW8pY46vPV=S3(V?YLhX%eEMqTy
zsGeEQ#>G~qe+Mmu6HZ}mzW6N&OkHE|lEocz4iA=l&vvFs>)Gw!%=D1^kMcF?@(erY
z^@0>LTXu4-(U4#mF9p at Rqd-1t$*joFu1`J4b<w1PS7&cn!N>6M1BCF(m;um1aqR#7
zxmUY6SRnN&b83f_h%Dn~?@5`Ip8ldSPE$HE*Fx16g|Tw%eqWt>!C(cX9CqIDq{7Qu
zSzHXBk!(Opaz(iooAgON-&D)-NGUR+jJv9^|G)28JT;N!XGuV9no?|O^~Qv~8O at V9
z;L>d8V>o*|yGh1{AK5he)bPvZ1f$4PxKs$>p89$IpX=*v`oFJ5(Mtsuh69+<II9x9
zN0N*mRFf#W2Q+S`VrD}AYb|NVfaA(=-5Qt9#UmxnXCjmc<@`TC8o=pE?Emvp!HBUP
z{9j-9KfXEuux|go{QohOfVOA`;n*g_NuM_(XYO2ZLbPB{Hzw!!mMDoXI@?NdqtUL}
zoTY95k(#GzzNgg&zuixp%CLN{Zl<b_5bHn3!<pv4U+`zZJ(<^K4>r#`Xb#c4#&XM=
zoTF2oqg5k+jx_NA4V7b?U9;{F_ptEMu>VbtPq#Co%xU))x$4_jsZ`YA6Os}EZ1N%<
z|F66DuTWIWPx{-F@|<0LiDHd6t)PS3_`QZM&GQsJn`4iR*x#IDxA)$r#o+08`tNPa
zMZIUaLuWzWxS_u$T3<iGRGs06RhtnYr~Y|9Udp~ES^ki)&FW9p##aXq5iVP1Lk>gl
zNiIr>Z*!DlH`|}u-;D4dk>XGYmdZxp><FF_%kIv#rg^*6vc_@$=QRAUNHmp%m{F2w
z-&An%oEhC+Xpcn~NtLFC^xas*H=(++z5ddbc5!z#l25~`%RT=JCUkblY*a}VPRgQ&
z*KHvcq?k$>PKvoqhm-dNPPi6%wXke`=X$9OmAIh1)iE-l&Tw%~dl at qBki>GE#eZi|
z(xq3nJIMD)$HB9!1ohv?hqe)SODpLpd+u!T0DrP#kJ0eT1=q8s$!d{tz!uH04KYUd
zi;vl>(}cdjyO!55wXtYvwci+;7{s2_Rj-Er>lFSgb*iYx_rh)F^RU|*2eh8<jMZj5
zpYodbk4heHFWMl5uM}Up8hYQ1t!4SMD?+J-d~=V6#pvFh42wz~tOo{ZjYH11=dm50
zX|P0-&b95lU30kJ!6s{YRccT_KETm_{El+swi7X}=6s{uha-_)+xqT>jhNjJ{r^7q
zFKD>f;kE7d*E8>iOXZtb=Ypk6vKl=iJQV+G8 at Avi{C;97FR<D>)G<wC(4IstELbC>
zkctph!6S-MIE&C6UN3{tYQI)QYUq>g6&0OJ=rGfKN^^JZUAw7y;B_^kI4pWqQtZwB
zn$3kOxYhYx%?f at s*}qFj at E_3<Jp-+8A2hF4d$uPV?h-vPnKD~lDCyYVmCbsh?@~5z
z9FyoFHT95U-|me~ur1e<p}G7BURI|g)N&BAND+HG?8 at _?)S&$;)vT!Wf5;udW+X+}
z^m)T#X*!wAq#MJCCCa5rFmjWHm{?0 at -J2@i at jO>TkE1V$TW1V+hu@!Zkh1DOkUnMH
zs}K%<6!2e#s+u=2GUBUZg#SFd<{~-wooDse<AN^QWzy at Ny*nb#mATR;>*?3A{=Yhe
z*rwdPS3cbl%JOdVlo*_aSo|bhFK9rdYlm4L{0yzB3N%@o;q8`7AWq5h-fc`Z;)}zE
zSg!m&TG76xQ#)Gm-njZgt#-*x`tLa1m)idvS~$`r$c_Ed5<AR{c9=Q|@>HYevIX^3
zZ at cOztn&5)LAuVQK?#&Qagj{_Mb8%B6^?QrwPLS at H+MTP`Cn7BZ~Z4suXgYEmm&~y
zH(y-N?`B0R_|9zjcG<{>b3W|?vorGs;U)c-*rVkU^Xl;oDZewETaT-i`l0G1d(4bl
zjHQU^pWGYhF5fb at 3W|(BZ9aEsNp5=6Nn!%cth9XBmSh+ViB4`Y9hs68xeRH$oH80n
zC}(ADoZlxG2#nBM^Bjm at m2$W%3lp0APD5|b{_oCp-!1-C(k+r;=*Of+{<qgh!&aVi
zUd@&y$d}EG*auCu7V_m~J2j8}<r=KFs&Hn7pJ|q!e~aLFd?a>vquixK%^C5(zvaZ`
zrV#m2|Jn)OFK;-*fg9MU^443F8Pf9X3J-(b*`hSuS>nRt`V8-za(`uQm^3`mkqrGf
zBx}?Y#E^a3Lv3|i%$TGIn~ICLyxrmQ{0ytOK8sY=Qnqz3%^j11p4;L-{rCUz7B25_
zNm~q>O at e+nE?k#s8+r3aAk3CkqZ)GPke4OSx-oEWbZH%U4P*!A#!q)`J!-c<-JT-3
z7$M_rH~8;%S<Q<E)k3bRlo#q^HFTHiA!1c)QMmZ-!O86NC{EA?SIeeg8dmrSS at 7*%
zl+T5s*WQgXX{iW9XUn9)u*ew|P9WCo)koje1KbbA$Llmjd|c1|6R7`HaRr+L14!M(
zuC}YO{YyCJzWE+JnrV}#OnJL~96M}!@iOpT4$YlY<B0N|(0AJEh9vKL+cuvIJ{o;7
z-wxAUx9vqX^@+W3$;fv{J&7-W7=xPA#WCMty0q<di|Fm;QGYwvIAT#N>RT at NBoF}^
zBY|06=3n^27Fz;#6`lOV#Lsp&Ecuh(o&G!h21|5WxG|&7U?hC1IO!3xm+bY31y;eK
zIJW7e%R)U(YOU`<w+~%apWc&Mq4V-t&;CP4a@>En*n2$lx2gA?RuQ;m&1JU3e!a}{
zdu%dyK23RdzBb?5R2Lw=WH%_7C31KD&V!PgyL!Ijef#ZBIedl{gGVC6!CK5Db2GEi
za<c|G9`r~=2T)KRaSgZ}#C03`T|5CNjidw%HzN7{YBo09et_PblgyQQ$!5G{V|8`B
z-T!XmSAMxpB^@*KMnXymF3l!s at E^Gny^K<Ev|||OB3Dm11Q$I at O6}`HuROEqeH|db
zLcgza1&i^+TR}tmg~*L-vm{49W53d>x7$x{)7)L+9!3x|rr`XKFBzv~-#Nh&sM&M8
zJ-_ow+fc@|{NXHa3idRp6QoD2=aCmozA;nZq%qA5U}ubbmOH->$0iJYdwy&=w9I9v
zt#x2FOK+wcX=&VTOU5EOc5(ia(fOxra36e9cBULJ9U6ZV4|!QO6OsF+RIrG5^tx(<
z`;>595!FvJvuaO66|-#KcTmjZFnxW;<B_1vCqd*)j|I0+xYW4nIfQ<i5tBs!TV;#g
zF?%`bYTbNFqV{a!$@H^rv9v&I{9M7}x4q?Qu{D0$>1J`Q;3$|cJ<IyT2f9Yn!(f)P
zj!EMj2tCB^?y_e-sf&i#VXbGo at 9gKYQ(-HTm;CphpB*M^{pt3rnsgan*u<Y&&W%M~
z-8Z9c{GyUeN|r!gG8HGVt82CMZHV7DJY)WJEZb<>U*Je&0J&6538gNnqk?^d%d|!(
ztZJ#W6hXwMe|+NhvflrCORQ|yAhqteW9x2}!_)}+aW-8a=2!{(^<puKB5Vkh{(Fsg
zzVKKaz at Aqb)Su3O4wS<l4(hr~6issHHine1EOJqUK<s9b{<Q%#zcuy7O2PTg^P1&*
zVy)*;<R3n;9FBm86qkzhNhEg7Vf8TvEkU2YV~I=V)5?fCQf4>4)CQ96q1~VFtw#K|
zT7OF8o(!~XkqQWUYzzOHcUj<Ph{DnfpNN>C){1^ANqV<9&+C-rkXEz)_{>4(Mj%{4
zw{=Iq_*6tL!EbHwI!OLg at o3q*n9DBlnntD8EZE5_- at E0hsnqTJIl>hXeG+K>wF0WJ
zok!cZ-OA3mGIhN%8vts$-BGFjQ?xN^W&>v1&t-Qz`cBEX9>Md}=?T4X(Ol1tuj*po
zeX^#}^eMNF{p|3G#cr*A@?Vu6{1PIvAg&~|&Kr{CcXKi!;(eOVWhMuPx>)*`N`U-6
z+cjw2s>b>UcfueM6?e8jFLTER2ou@$IsJ7#Cc8GW1A?*9D9GU1)$V%3e7kltoBSow
zaF}Yq*}Q*y5o~HXM$F$Yf7G$`9d$5*-PuBdI-=4)VP8~1X!X;cS<;M+w@@S#aDnu)
zi?Zp}Tf!?u0~<{H;{exDq*ba5D4lzifP;gBh9-+vG8pTTpbHQI at bU4%R2s&7uha|Q
zNbRqW(6=hf&IN(*_-hb3JdR~T_L?Z%sie%wA50UrTz{~qWEj=vpphp>oNl%9{nOS&
z`8-e_00FL;!ew at _)GZNu&(NP?(prf_6KVY>KILsi54~=(lasn$a5_Tym_AncvO;^J
zZBW;XcGPCH#%(qjZA`56#y+ozc>c=h>7`bs*qx3EBcYI>1<pV37>kPJH60rjTe(Ot
z5#qWtckyzK=50S9!%BfFSgck0;ll^>AIbPMH2#NwWN&_;S3Y`4xUM-pG^kr;HW`RK
z8z57=0S5)7nPZdBr~Lbs1MxG%lJn_3%`)AqfpSV7>zOYGs18|WH>lX;T(+Y>ejly=
z$fy@~8w-w#zB8`27^Xhq;Jdd2T=C at pH8NCEDrZ0(M3eC<ZHFo<B?T`oM;*@Xemk3i
ziT-A%e*W^}LJ@=%%>7JC>2T#ZJfYYSWUrO+YLHNuI2jnKWp at EvA!9a>Snvya#ivPS
zV)eT#Gy+~f8a$8a7rT0+Y1)C9ILF&a{jUh5A$#358aPcGTX3Y4a5=-=nTE^TZi`$}
zeu6!)nXGsVL{}!|OezqAgC*&k1hjs>!$?T^l$*WUdFmWu at 7?yuMYXQcr>Ck#3MtM;
z<2OCi`P@=3`1ss_km+e_Mfgv4zK_!?(Kv|Uu;F*ITl!sTu;(Wtqev~v=6v{>_h>m@
zYftnhB5%U{rN{MA8*l8}cTA@=KPRe9u4Lx<OLR-EfqpJ}y)S8DVZqPOPfD5u7<Ge2
zXKAsA63#LC8ZbiKnUA50803_5bvbwSQGP52U-S!qnzfbA_m%4n7pmvm%{HA()!JMZ
zuD<vOGxn!&TL2EY()M?i)vqr=ofz%yMXkFW(>Bs9)vdK0`3&f*GPT<87QCXR6R=GA
z2=m>YS;0%U{k{2O?RILDZ!(b?T-F+s6(j1wFIm&<h*rCQc%{GFEWlq5Io+7Y%=Qhb
zD;3f8n}*G;)!Jy5=-{iVZM4dPDIP4v6@<p(M{*?~&k327`mou1qG_Uq#l^)7DV1I+
z9o3*6hY$8=bDMY{Q~oNEZjKf!)ogH#RTeA$JvC^uJ?T`eUEb!n_`%N@=dZKs)sPcV
zveomIcBbn&I5{~51qA^;3l5>=;Q7_nRq_TryVJeL=kDf=E)Doxo(g~-+}GC|!3>I|
zFR-25#E?J=Y1#e!{JaooU&!wgt#@zXgbeAASil489yLuA-$`z8nE~SIOmaEv at _2(A
zoI_BHW}4lV#Rz-<8O<w0qoRTuz`u3$z(1@&+%43pRNLWbyB=w@(i{GG>x+s at BP3$$
z_G6|S{TUy%Uh7Ru-s}`-$&?$r&+m`$lmXO_$x|a7>-k^UL~m<k7U`tFCoo^x-JmSF
z*El&j0hagMIuX6*b#c~v#CsYBZ%Kzr&;{);fxZF0Qoy<Y7to1l3xTxh;_7M#hl$r(
zkHIDyRG+mRDUDh0O*l*z_yz1u)$A>dlu3pt&E5o{oMBK2duU81%f5U0v7V&q41I%~
z>}R7MWQ%XER9LwEqHe^3*IKhsjSXOJv+s$euZy*+%?EvaeP2dV)PfRd(Ch}dZApjE
z{ei*RPeAP(A*A}p2-mv=98`cWex?HZ3Z%dj9tmf1QVv65&qGsV<E3D1O1d8kfTm_O
z+#JaX(HSxg>Igukx3IK)iZPTWMsu<~T|Yc-VTeP?hlLPTbc}=={Fnb&w47<+415f{
z3(AiJb)Ng2J7UzJ{5 at ZtoNvD&p+VEq(lQ}vm2bL2 at y}a;y1b5#^G|o^bh^F10J;qc
zv)UgZEP7GUGVn^k0s;a~{{3uxpcw at ao?l*Wq6fx|MpC_qLn!^*{g*<w=USVAg9Q|P
zLC?e7Oc^v)JOmM-D~WVK at 2N91CzY0#mIhiL+6 at V4UEtr9iZ_D%oV0ca-+KRDL4d4P
zh4KD9dQ=Gj?1lGwN#@Z0vi^B-v<5`f;vT%Eib!e^3YvIe`q}*Vs+YOITU9c-fS`|h
zfDUuQM*A at mZ~Y-6%70#L*?Fle4EVe5T{s4PP*Nk`6V1)YKmm53j&-Bv0*i;&2gG=O
z<V&z0pd`+=`8H?15wo9bAtxsX<|ie#+sl(J(5Zmx|7$6h at M3SaIlmk8BaN7-aaZWf
zwY;NCVSRo5h<Y=iM<Y&YUN}oBR}eNN2zUW`Dl-NfaODryoPoDRgccDv7ajv`kB?6a
z?9Lx!V5HD!bT+GuSq4(h`FUslbgfPP8hw{4IyN>~84!2wSB8pw2^?iW^BNi&B4kv6
z|Jv>aJhrf~@Kl{$v52B5 at MwhK;Noi2L-X^QZllNPo`9|)Q~2WDYG}Pc5QxOr9<?>E
zI0$S+B0VGXjrquD=~o%R4wLzYiO+WO{UzrQIAIkOkgm%*GLpzqfL8`3sJ|Ytx8kp7
z$mB?XscsDjJYa8GR6ipTWdowNtgKAQXPtr;W2rwQ<{8-Jej5Z|u#q1h3Dr5w-vTH%
zqy^<m*<+gg2}t76S31t|jEX)!KBKR$_ew4+pFCd$*07m2U%eI)$At%ncL%*Rh3`aU
zOE8aTo83olL0{iOccWuMz67=opyKgd>Op0I7;(CM)790rofgIvXi9iqPU#1b$t_4(
z!IZ@|s=!x3y9>pY296kT8W@$)kGmsCXJ==dUANpop8_GYsE6Dg4scX7_4U0Xr<Zyi
zdQ#qg%d(vF`7_=-ps10XWSpO$=gY&Y)6$77)Ao;#|J1Y6dOo<`V;g%NQyTFA-LnbU
zh`2<FTD{N438|8WpTMK3MRXgT^Cmr>q9R=aymSX-E$`E9W)mPY%+Ab!>OI!t`OdYi
z5$G|_mA#<90Cx)zZbVG`V!kM*g%e8yKhx3aDM at hDhqku1{cafSac-GmtFFceVJH*|
zOhTRFppuw1{<s7wQt$^*^(H-$POh#ypkRY at 5QB~SP0s~QLz!Km(eK7fM~6%|0`cPf
zyugUK{pNHU%!eRPVn!=XUb+-AOT(N#0LO~;MA;)l69%u#V=Gmp9Aqjlkl0IhpnN`W
z0u@@C!TEH31hF*k1Xy0)f-1qLTVwe%7kx-oF>b*T95d^&qE7<wnZ|dT&>q>vrErbo
zQek$TI@=VWy)7MZ^sqUT{{Y6uo12 at F#Ri_vU~EG9bntLNkNpMEluq~NX`;l7 at fv|)
zg69g<8OC=Ui at a^GN!j%$zbH~_M92Zu8k8G=iu*ZB6@&aT6~9-)8vrcY>1vZ+9M2hG
z*zv?@z<b&NfKiP&57`~(B82V)7!-jxLdY};cBZRK3O_mx^@hWcP+~hGIWSSb&FA&7
zcxVp7v#%i%#ME*5NV-o at ktiVDFqNNXZ$B@=LPOfaU**yb-}@t{lat9_?E at dAgoFeg
zJ^jJB>9|k<0TFpQzr$Q4LrV}_cW-Y*imd>hoOsbf$@3wAJ;l{(rGLgqBz!3B?0;ik
zfMky185H)}oaaFy$Yau!w`J!HUw^0^eT5<#=<9>Xgq#Bt3gSV91=XXxrKP2Xaxwxm
zXz<B53RR at 2KpDyMpjaBvwhC30RbLR%6aq7$qMRH!>Xc2$r4rb$fCmkOh35I2uK?i3
z#mDC>WrPc|`B#SEBjoyD9Io^w#>6~MFqmYzrY2r$c`gh|8wpt_ue3G>8?kQf!c0Y)
zk3vh5!_0$qK>zaNjGZ|EIP!_CoGGZnmRLxnFX-v$#!FrYymG<+_{0w$HonBm{=^H{
zpvh^u=hR$<4JT?yoTZ29z+6guK|!@$0JG*{FE%!|^lN=%OF=Ig9WJgM)*(!b at Y|Ux
zGfZ}p1YLb~&br?<R)k7O%Xr6e1$f=6-<`Lm(E0^88C-yM;Mi1xDj7`q%kM^jz3Xqc
zut2BPlV|~zBzVG at PlNRZ-n-)Gsx66Eu8_TblC#fhiY%bAbPv5aA^2Ek&@7R<GCf`I
z(8=-EfU75g4i2O at 5{IDce!JnfwvIxa{nlJI1s)H9&K;Q!w^x_58GB&>#j~uH2kx<z
zbh^|;gecm;AL!8u7W|;^y1SnVx$pLA6zqe<T+vhiE=RW5fKd5G8qGyRgUE%(f=NBQ
zVyOi#JXsn^8rnDq(#}Tgj3 at 7yn?-}34Vhw at B!y*s=j(>zs;6<wc%tJgXwM>?%ys$#
z6oyBfK<%R=Hp{b4Q}Z&M;RdtW2b}>1bQ$`-FTDg3+kxqUtJH3R1q(J5S(svCV*kV<
z4EP9nZN{+>EV%Y^7lCop91rwD%noTRL)=G#HDC-ez8wRv4S<72k?c!Yxj}PqJ=j<x
z?u-w7c2kzm;({QZHfC5;Us44bep=$DGAgEq at -l(`VGoXRo{er96ubn#@#*fYjhs9z
zUm=C=-7T=Ky_#+D<Ti9)hd-3mIgvs at K&a6QV<+HVLU6@)0S at 4#q$J%=;7IB&=i`iX
z;!{S?(L5xQst--^!yXx)>g-`f_5vnmF5;h&Z3GcKpsWLYT{G~OE1Jg9WPuSMfo&HL
zdcIOXW*HP5yfn4=w9(T-QsR)>SO_N+;jDsQ$_(V-x&B|I0nmwH@$uFKZW~&A;24-}
zRC^?s at d7+1xo5O{FojyYPKqKq^O)fM{rw(7wv!coqkY#OT#%>c=f$2rebo|t4cvo1
z3tyqeR^<tepu at WZQvgY<4#vGN8!y0Lu?~%=Onx|1q?RxiQyyvQc<hC<CX5qdceF5G
zs}rCzsUaYWh6hcY-x9{x0$AdvHC|SrGjyExlhATuX^GCBZ3_WA>}AoZHbUh9ZI1!)
zCMZSUm3CpAfa3oMH2h%}G}_-`$^Yyw$Sc&W2v7vJ?g5NoaaT`|U|P~cfqcV@$LY#l
z4nQaGv5<f*>fI~+@~kB>PSD^iS71v9{X=CASfU<(0keq2s!S9`P+7b*!zsZ!u+D{|
zdp`>`$Qv`-FF?TF*aLV`K`tKbF$yYb4sd0>1i)m=))i%n5gI&BZ at xRz_~jT$msKh(
zB0^og^V_$D`Hdk6W(>B&0gV=b at Z1fh)U*r{p|X~{Ws;#7ZS1sgtD*82tT+ttdWZR;
zk1yl(n_SS{wpLeHcX!Li{nv&bRh}US%4R4GHb4e6X&8^@a6lWc*MFTI2bMoTm+w<S
zlNzOt$5rojV!cMhrd62)8BTveSUB#Fl9Z6}C*5nv0|>xF%m`69QZ_3nk7dx#6crSR
zY+`@Sv~mR?l;RjH4Hj2|QN)g`+-m%?D;MqF9&(_Y(M#a}1sLYvGn--8xI#%niT at Z6
z@>|16(t%{D1WIE=$Rk=7GBpWUYilcjv5e*D$G at vB&Qh!Z26A+)@WB2A)t9h9#icGG
ztw2 at Ld-`$4LXyk053dXJZJenTEQ!PDWBs{1D4oE_&7X2s5rCa at 6Egsslf=ejizyUG
za#G9D;B?SaKSX5{)KqvLtxBvu4$2U6mst at w25xUq-i1X(Mv6}fEDN|<&Q4Cc_0rLN
zh{~P5a8>uS9*c^K0#^w-I=UqbMR5K7`|~YtVKau4d`3Bc@<)e9l#9z5oCHfY8Q!;V
z-~Jp8I{8S+zYBJBe-xnQ#aiZ0gs71b04khF&g%gku`bCO*U|0~Q8@?>brS1qI=V3f
zfi9;J0vE2sh2Sp5r)8<cP??{h`1Eil at NPYinVvtd02PK#88m1(*$Go};2-M!#;x7y
z#_!(5-Fy3e at p;xOa`vTus|e4HNk4!7?5O_wR$)FCz&#P*-gCg*oox=e`@JX#K*<Q^
zWWf5mC6%;ZtSy)FF`c3BXmx+fZv?vTZ|MD^W;B-Zo*55v at dSg?hzS_!XmtRfRs3;p
zi_xQeBljDXLYLWOAp at A#V;n-TDH+e)k~vL+Ckaczt~=g`@;i1gZ3d`pft$3%ZqKv`
zBw?zJm+x&}aU1WKGne|pG{;1JFL~6!@ur<KZ1HdcmgJ>%OIp@(XI}&cvZYWgVABmW
zTVk`0QD0qe1!&hKlA*~GSpI-*ohzkT)g`vt)8Fzqxdd;Pj+H7;CYm~`jVt90daCsM
zh0^C;L^dRf0BD=<)e>?rxj@<FSs*CO3sP`x;7%txm=c9Ipmv>O1dwac(WssGweW{F
z6>@j!&Pg{kkTJj#A|fzr^lHXU%c$s42X^WHgatGo2Uu(Ris<b`L^ruRZv}9-KNtS(
zc$hTFOn;^I)aWCQV%1RG6Zyw*kRbO%zywk%o{(`P3h)9jiZoq(%VgvIxY&;(;IgH~
zc2X=I8U=tc1O_1IKa*f6E#U6CUaiOxpOr^f5eWn{Q7Y}|sMdb>z8s_Lk})<hp at jor
z2mfan4Gw+jdGz~9V6J?}2jsnsrSDPtq<&(xr7GDHe?P8OZio$ab8`Ck>>5+ at fkRu~
z+oTWsVUkR{Zs26!eGby|TK$w#c6{@9gsYNcCtCMrs_&6j5^ivcHH$+N(hgx_%`_&@
z>P0|KHO&YNM4EYZ at 5aqs`1+U4H2sv0Zz*s9e?J5_9$*-7e7l!wk?GmfTw4u(Im=&d
zN9^vh+02I;6F4_q2?z<D=zY&--9c<5p+o9a;0h3cq+Z+ct6(XVe6|(0M9D3v>{6zt
ze?X}?3EW-;UMPUahCjYU&O`rbcJYI>*%4fr0n13c#I7f?e{SdCdQ}BZFhCHSm9G~-
zt7s7UgAzoLJ^-*tOs>6CsBNffR!IV8KRNVcx-gPbi{+FfSSSQa0`3u24JESaInv)-
z!v2Q9GaS_A0_ErZ0_Q^{$`jR?AkEayvNHJ{GOMerXI7 at f@o;-bGJnSThKBHhQ>3l@
z>Ma-r5^<A%@F1dKB at 4P1QQP3Y2^WZUaW9Js5C4`d-XaRTjqf(|e@>DXaBogz+NR>4
z?o3-8Lz)2q%27H<W<cM5!NAZpJuL(rd-e|;<UIR6Ha+xY4 at AhYK?E^>^a{Z~*P-n~
z=3gsRz;v;+EI1YTTJk`33p5QM%q(yZp*m*}vQ`1<ECVqvRhan*Y=D5J at Uk`U7ljTj
z%>D!y1719d{GnH8J3_5wYP8U?WVOl1>3iuCiF&NVZH2+JORlZ0J%Bo^4wKd)=4?Bt
zH~JdpZ at q73)P72LI9}OR8PLRkUeuFM)1rO#>+D9TF>AI~jzJb`C~8sC2d_0aif?C4
zBDO~Gy*sW;F}aLLS8OkCb~Y>+f4`oRlge|6QD~QT=V&W`9N5vCAHDfZz5J0J*=Vt3
z1_cdWfOc^fj;+qq_&V0Kjrrfpt0Pg_9U@!fMIW(dTlF&M3G>IY6#s4)h`AH}7`W8)
zPcSevVF$cE^H^=ZV5BReK>uL^2sqF|;y6K_DuNibdJ!YvBQIhZb4&8uPyXUPnE1?d
zqF|^2<+wma7zb|Z7n8{XUy_YEWYcxtp5*+~?sHKUDfN006;$`@tG)IChAw(;oVUKd
zANt(Z;j||lvjXfmA-RAd3S)xG$6%*8v0l6p>nn at N1#Y-yF-&}pA$DeF*&%m2nHs7T
zC#fBdt93W3tv~(osSqY6CVFmbE$(7i>}SLg7T3C4Frhy!kp0x~AzwKwk#p&DUok6J
zp9TMidyI+ at Rc9sgUY$_Haq%1S at dNt@ykcL2I)7(pq(X8$1*lRlEwqjd0{e{oZ#1Kb
zUaVk;Nn##IN7GVcf6YrW2xl;bFieGM{7$iaaH+N9sc(7mFbd$LXCH6zZG@%btUC`;
z>Wm8-mOk at 4CV&%`_5*i73V&;ynt<RlI!|~GqLZ>n(1QrnkDaRosKdicHaJ?dgJV
zwK4xf5(kYZu-3NF*m21 at FWmp&H)?33m!oe=T=!w?IbBJ;=dxFpuMT-(5N3<#jpMff
zBB)=n<1ML?$3t?z5~H=TyQ=}Q+tUe=EjsC-BFLSe^)!F2nD}k<e0g9IOCm?mgt*_%
zpAm0&7fCFfkkP}uc^MI4cyV~z{3<A^-Jk|fSM6?KSl|Er%h$BKi-Bhxy+e<f)UwZ?
zUTF?SgXc~-CCCxWE!&0FW6a;W#+Qg)-IuOM*BpVAg}~_hPwjc}1`7ayRDia(e^+NW
zIuePzOjJdtzz_lhMHdnZ%Do1E&QAKh3IrdBA>!`=55lOB{J<NM37*l|*y!o){Zd+*
z7PqY%bm7gFm7sDvjSuCfEiuvAJ(w-T^S>$_6C^YRFp6ettbT#ZDf{2LyO9q7Ma-RI
zu?N1F<@-{Js%Hq!BOpb9S^fSfjue4Yi-d~WxeSbbzv}GtO!1r_OhfE^uTHx+U>P!m
zO+dMjuyd3G_xr%YUvU6NA*ciP*t%y6+&{qg-(L`?Lhc3jYn5iVovy+TG5GfRxkn8N
z(^DxD3+Pe-$w`DofaHfX9xE=udxD8QTeFWfYy4xC07fd*gD4gO*swinFnm9nfQv&q
zrsEJH(9`*x|GY|Yc6aAbIl*V^QUy0CJ}fy022l4*bDH$P>;N<U^5{(&*(MA|CJb)T
zLG+DX=-Fwe;EnGrJj1$|bkn)Me=b~ia|zPndPv_}SZdTxosyx>fd;);WP!asCsq8`
zN{f7dld6C`N=p9nY>xv)j7%!K7mgyegh$7;%RUn>P*`>kf2+a$pc!1_SlsvI5zvr^
zXDUqgsxFK;n~RH3IskEl=|8Uwt>!l at yL8n`26P*v&kQ$w2k=1(Us-wBu+=M!l6V4V
zr{g8=r-jf4_|oq~0b^2b%NIjKmf83p*~<<A)#S8mNxW-!jHuLWS&N<;mG+PnA&O`~
z{<$qgM1aH#1}=qxqxTLTC4j$26eG@~Mr?_N*k$oBBVY>PJrl0zp#6tZ_$~r;fOTLk
z9^`a}z-V+>7vC=|vC)~K+znBOhNW^Hi-$wRfbgzn8o#vKVPoT?A>E>hEZEgf&xMP*
zO;>Eae0ftnESg3p@~FJNJoyMXm2OnZ`Gl{ao at G-jR}L{o7(6xL2H#=W547j!-}e%4
zCd6*tmivNHnGp=K70`KPP4{gt2#rYsMeHryP=TFI at O%%G|L47}l}X?^(Rw-}0>dMs
z&xnOpqIs$4JkXvqp1 at 91Ey=fm0(5PoZ}S+d;REEXWEFyl*qvV|D)yz%V`3pWC{#{>
zbC7T^GiqmFRmn!!#HwL|-`?Kl$V3rTPdrx*#c>%lC9$MZRS2JN^(K{L5-vAt_XA?#
z=aP}pDFED5+w~VBa&lNWX~N=zK4C<3Z*<~x2NrMUR2ZJ;G3O<{@di=rLjEQzt`OAm
zAf1tFz|@|vs>8ke^>Bs|DWe5f8a577Qdv(|mp~e_ZV8O|SDweSwGCbsT3akbcJsIR
z+`xN}<t=5DEuiLP83|EIOYZLpTTtj8OF+PW6H=j|zA2B at 9LEjs3*h5;T_x25W)&$G
zE&xc;l?d~sa6_>kXg?HWw`Zav6=4M8VVzw==+br!4FXfon;2~;Geu at n9JVgAZ<=_q
z#%@#yY$$vM>glzNaDjqkww~+}^Mbm5*2^k+WHlJ)e&<tZDtwW!E7VWPYE(psY_T*i
z1HUaHUn0q|;e^PW9LH)PQ at F=IAAPy{WPmJSqfz}U?H?>2F3AQa#Z-p5Z=)G(<}jz>
zh4`oQOAx?yToLB5jw}Frc&Y4bREUzzY*Xzz1kkem=TysKXvbv at p|4G@?qXXE%t7a-
zCTGMx at sFW{&yQaylxDmB3WhKJ$#_PSOS1mcfs{?F;l1uyx33NDAT|5^a&5Gpx`wN*
ze2s!gJJW6uX(mYcDV4QhF~4GJG=gZl>RxOQ at TmBZlh{HVIwm at EsrfSNSX+#HFt=|P
zO1Tk$EBY6Wx(sFC^r0I?xm~L!K?p4;lNCO!eBF6t;@G>`8B**&!w<}efQ5{6h(fvq
zt<VGNZ>9u|g<yW_f at m>zm<0MmU;sxwTV8y!#IFZ80!+#}jO87Liq4569vYR>I?*32
zx2N%Mo`Xr_z1?F;HMO6j+$xY7j6_DHsY4eeM-H7YfGAx-AR7&+cT57pOmkynzuWgG
zRO?T95Sy$TS3Y1U$m^7NfLn-QX8j!dAj+uOjg6hEMJ|+;D+euMC>M=~2tGUe=%efE
z5As?+O&Cx|pZ!r7WlhE4B{eQGe2gCX+92w2lH<LYL8`<@P at mQCu_5U361b}qFTL;)
zXncpI55ScujfrrbA;<s&6~2i?JRn;$p8vfJyel%wL8bB0 at J%OBA-Pg0AD~7>L{zhb
zUOwP~C84o0rh=^Nqw{BteUKNvfx!bYb#bZLcEr+f42kHVr7+<U9(b4;3alTVge1!3
zA}~FsXmeK^&ATm|a=K1{sAzK0YV_IIJ~;j+UW{JL&4b*z`4D0W-1*<lwm6CKwp^>V
zMHjV2VDT1f->l8g!zt94O20|KOx8Y1W_)5v&>9%OJLHx+-M4>&+a&Yb*WoJsMJV}9
zevX!f8`6CVAuC&!DbjDO`V0Ht;hcESn%=4fHWhNd?hS`@?gT!h67!=n4=A4o0Bv9c
zA`cC2>c4kNdY{?1;Bn;xU$^nNqQNB<H8p#pC%8iDvaV7&vjpzk0x%!2RO2u|w;nsy
zhrXy~;#g%|rb>8!#gGaOF^q&wSLzFjH64<!9d!?7A6C?sY0tpGfGI8fn|`+C`VQa{
zzgKNiSh{GG8 at BG(fs&ItAqPj%$G<oQ@=qTP3CR~ewGt*7Zv;fdx1ANH$C)~H+3brD
zJ}R^%GHr1~UQO5tld)3-#*BQZRjLrJ at dHLJOtf6cvf+o(qLa{RtX3Y6{Wl(Lmx{I?
zA at yKhj^#xQY%k)}LZT3f6q+&Bgx!ljbNx%HpE&`(V_;aIex8C#3k0d|*?SG)X<O5|
zVfQOob_;M%oO2slYd}d5O95ROTAxB_>9iL%&nVXwgUip-L~-*R6tJyl)zx84bnp<u
zq=aXhRGiOeG0fy3dO}V7zmRkdK0%+GNj;`Z8lpOZ;IGSHP0$^--`(~COr9T<ID{RO
zt($k~aC?=dYvO203&;FMt<0CiV%Sx6-sjhbtA^xt^I42$N&?ELOnQDt!v7Oojx7FH
zOQ<Sfmq-Rzyz{)wV<XXO9{8bf29bo;k0a||FUU^S5v>C`Ti{u|H32=8WB at l183Xnb
zjL<yfm^BY{5$oS8>rfAvQl~(aSM*GSWkNk)E5hD>1q3y8h%R6yGA9orc at Ae8S!iew
z*g}XR0p<^_#M+r4#C#4H^_~K$FC><glZ=CkaP#5JsND~z9il;;X=>onq-Z-KD&h4-
z5XnAxN at 9CTH64624mX|--Vm{Hz-5T&E|7}BFMX!~=*1GKYNafUw&63%GlVG7E>y*y
z96qNnG6-zH!Ht$nxz-)cDt0(fSnP(<Arb9mI=@TsI!&&bV!|GsRSgm1uMdlsr0;c;
z(lZ8!=Jn&MktjvtZk#-phBbTFYuK!BO;E?Sm!uy- at GXh_nT<pbI=gr}aZjw<_rDz(
zi&vwaDLZ&CpG*WodO5HpGj5tZbxDZ8yprj*AM}B;P$7luU!Ze;1>AQbp`?u1d(%>J
zb&0LsgQR=wfj>VON>r|@;_Dc|2#<L&8O*c&>PV^87 at MbUZ>4JJ{z9CHHwgy`hasyL
zG3F>Q+>$s!e)T2d<1dUR(6;2NYNSBKPY^vI-iIX?aNl3akdC`%BW2A6ilA{3E)I+G
zpCltc at j7mcAsDNIHhXEX>>hVHSsjt(C}JmJIT$_c4PYZ!YY8-S;4gOI5zr%1>?B3-
z!}%63pEET!>B7)?$at+a0E6se?9r~1JzZrcf9&bwa}7?PRLK2KwRAQ7`a at O-q*+J%
z1B%jbjeWe*PoJdPNyA3S)?t<paKf#FAUWD2{m!$Pab1_Tzk|U?!xk}yNICxOqx*g|
zl+%V?ooq2_LGMR4_XsjXSkO at 6OM5k#6Xo(~S0eLMG6DiR8A}<2D6$vNu!NG at iesIi
zJ?P&#)4;8t>t;f)2QL%c>Fuu+&}#Zyn$Rs6*pa-@&mP=<@(xJ;(TU}{pJMVS5)#p9
zct9y0m}K<*Y);5*6l<y16K@>grW>W-aWMw5;iSX^NgsITg&I%9H+kWpR!ZA3)p5jY
z?idQ)?E$l3Ug<MKWlHkEq8{Y4n8J!v3pGC}kE8XT3Bw!tAg(95z4VWd{O at j}FXB<e
zV37EH8Xx3k86dv~{!=z7e71l_)VI#j{hGl5+UB$@18$J-BeQ<V(k|0yR#OG{qqQ7`
zDvw_i0 at h89{3AlIG{Fy9 at J7OvJG;9dUp?h844sb(BTfNj6)@d|Z5yD!Y)A^gCSr)G
zoUYFgBtAtVQN+UKT4eAmA3WF$$gxqcR+043QBlEDdN>x&i^y0FiBQCK{O<AS(Id8{
zx6=Z?l}e-{0hc3K^3Y5Hr_Vr&)*u`FYO{r4$E94b{Ip^YY;kzT6Ic;&CA|+_j)ePB
z$v?$sNys6E=0TQ?vvC255iKL(59Hcl(U(Cg1;Fmm$+~DEV3Yg#Kn)g)n$HLP1WsYy
z=Ut|!EIfz=tO+=zI5}uFgx#@rfJTf45lsF9p(nTiTrc7v#BPP1YH at MV5@iT&r$g2b
z{NaPa_h?JbFcVN_nM#QQ at Q!gQqRr1QE*6n~5nGN13<S~{=it(QJfE0uIm6t2a-gow
z3}4RzSF9Gbx;$wSl~f`PK}-TT(?u^a+|f39ywczHAPWizkVWC|NDVJMT_>3lW~}B}
z4tTFeltiHYP&Nh65=+P_YeB0EeF<KG%@m}y2=sy_zD`vA*=(-fK60qx3l5^WjhX!c
z%Oi?NFrE5=f>7DtbJB@^)9iiksqMp?nO?hx`M^+YKS+@=-FkVQ*#HVO9(PfDR)He%
zdP85>y*rt~L;VMq$7xUAukQ&STL6B|Q*kdtFa9sO-ZHGpu4@~WUUWCoAe~D}x<$G~
zQo5v(k`SaDBovUA5(EUL8w5mTAuXt+fQr%$?!oiC`+L71d;jyeZ(S^|YtAvpIBSwF
zXMX2Tu*LFqOUPrnyl(w*NYH;tUfRX|e2covJt<sAsWz<$X5SXSjh*Nq3a8!1C;z6r
z*eJR6{|n>=;vMLHLn$11EToziwR`$Y;PtC$LE3{gv`z3n`_nNdZBG)KU<(#yJiDjt
z=Iw>P;1xrAfTIcOfpGP>3v!a$cyzp8D{v^XJL+gT at EZA(Mx({P?Iq!6-~}t?C-dS;
z67CVg%pzInllv+wyVS|=NI<GhTwmq7tH>Av{4Mk<cG7r%=9_dZu&hONGM1HLa!AgK
zwVElyAmzUMI5uf&_4TaNjR&flV||Yz5sD$6%#F(0<i(E$K2~6k>QXl$7 at r?~RP9+A
zOi8F>F7d|uZg**qoW$eg$zj=z-Ly34J787ZL`iNxXc@=U#`G9Bl{DkyTuD;(2iaZE
zy~R?`H_dOV99QHwI5IL{q`XS}AY7<l`(`-UcF`C0w0IEZZQV__z`sn4UY5bZK=XNV
zw+LtQ!PN{xx+e34UekRNw!q63F13t~zA#Y_a)Iy5ibHbu7A+O6iUu3+)UwLSO2h|=
zmN2dI_>9m9*C{lO<akw&=87lC_Ru=Na%%kI$-MKNEGhfwSu>?q#7{MB`|&%?IX^E7
zo<b%1F7c+waEEp5+3jyFWI1Pl!!9k_L*BQ`?f*O>w+!Vjm<@!;A;*z|cxrAgk at n+W
z{P0dUd$%u741Z`57`vW93-=gj#E|Rw=zDN7U23HMgxWzA>r9Q2MQLx#qm#yH>yc%9
z4XXJLPQ_CF!rP3 at U9>y=N}8}#Ce!lrq;205$V^{zBlP{l!o#ESn!5>C_;%bIUEZOM
z<DC_LYN~bG#+xX1 at u!gc<9W22r6nvXHu$mG$7T;>?<rzNSv&G9-hLEO?$;lmNt61e
zBsbeqrkPP?THsk at z$xM+Rgv@)dyQ1**4RyYM1`nu(CKe43^FPmy#jC6tYB%OzcV|(
zrfKv}@CBv+p7x2mcroB(%lV%dy45#K9lOSmp~x~ag(Xs*a&!1|0lArtDppBYwiL;+
z_LAp9t#V@&SV~f63qbpkG4Z at 5UQ>sBc>!3H&n0Ta9v&V5jl{;rYTnH}!v%3oSc|&1
zC`e%1{eOmKJwNKLxD54Zzx)!-VPKzVk|ZO|bwkYilSa2n&&%;zDwcN!Z|tDlo;Jzi
zT>1Q1*k1*kUi3Yor#8bg|AtT#7rX$liCSR$2cX>ss+fm=HV(hM3JYv=VyW+!6vr{o
z(2=`TzXH~^;YTu~vPN!Qr at 9hjrdEIcR&vl^gqDS#?b!R{8SPuy*N3}zQtnE2?VP&u
zhgOBTAGwS?XyIQhZuI!|+KONCK{;gBkT{j7(MmA?N6vrGe*Rqz<#+BdukWUJVr&ES
z(Xuh92ma{%W=$TBVG2crPlt|e4e1u{5y9M&keG-(bv9L0j96%NhjFLH+PN|%MMqyh
zozYd~%ESK0B=2ml_2H}2Yl^qLL173oftPbC#<Ae at Z4&&*;Pc}nX^QtpV^0_FnRj({
zLR<Ha&=;B@@CeSGEP8K%3Y+8N<MqAM%oTL+cMmdkb_LE=%cVD&ePB at 1j{ctPVcBqh
zcaW)riGrfS>V~3-3J79YP~QJo6~jN>ie1No;4rg4?=$oA78;!mc4+KSHD=-mx5IVt
zkhi4;bunb|tjTJDK$3y*tI17Tdl0%n=Q3%#m9!?h^?Lw_U2_YIiAjx281r7~q!Azx
z8$kP}=hFgd_txU at 4TgD0ivkcyeV~agkh<8p-#t3YFDnZ|r at fyZ9MEQDW8BTMivY*;
zRJ9)46%w`@7jZ|o!GW;8R*uDQ3G8J3HBo~0GCg`l^6S?l<(nSNefB;T1H*1Qh?@YK
zZLz*V#};m!8{<PdrZbEQjjmpk<|j at F<<R<}l{WF!*QYlU_opvkv`&@|cN67o)tb=9
zKc&1VU=D$)onY01`T0daV4&o4rh9z;gf}7|dvsk;F%iB-r0W*?<UnDzzILO4 at qt>T
zeBVoOD8F<^Hh6rOy?b{C<YDUJS8)F+?JUq*fL((0qyLFCNF~}`rg(w_ffb%8Plzd!
zF9*B-Ew?X7lgd*}!e>-(APs at VQkK%@;`9KjyrkE1e<H2us?|5W6L>C5GP^7hiiJB=
zYT-AAxdCHQPQy`&c=81LjO!2x#Uu~_u4$8- at yxlc1z$nH^yAZugb9kX>9{xWj?(N`
zmX{~_w@~-%v+%K=rl+GGrKP29V6s%hn<H22X)y^+S#GZI`&@b((!rp?d&`5m>QOm1
zbRO~((mi>{qVM+DK8DY<5%GdqY874_rw`jep9tt=#>t-T0Gp4R_x5o`ew&%`2idYy
ziUe!C$Ct*<ut6a?F0W+TojP~4oFsDPIe4Q>g%bYH*}Ll at d&ypeUiuVmJ%I)gO{Y0}
z^aYmU3uvYLpBMLR+%^wczyPtV9us;53ywC6loXwt7#Z{vh6_y+PQiG)OY2qgC5j7U
z0SP6q#y%*pe_$0E#o;Bh>95c$>1TKUHC^M=r;NeU5_vVk`h@@MKEPCqLVw}YtpXr%
z9dvdQgw?%&`XpFT02)SleHi3Z670ulEo#v(R7+;yE_VRfU>?q5NDGt5%FdnvQSzd-
zfPjFL3lJHA2s3jC*_zN*McHWQN$h|yk4gh?#2L5^b#=sYS_{0EURfZwQ%+ at MWUg=%
z#ub8*2jAKyO*y>rUQxZ$fW#+^l>NiQEMm-XqWD2aW*;2UqN1YZ at nvAm`?s&1Vm-wt
zAn1>aW%V at fUqP;q=FR|KTTxUo0b*%;Ydy}rhS4;wRq^KqZpkd+!__qsS^&xHM7lh^
z=av>PI-rN*$tx5iOngwmU`rWb22H?A`N97F=C(FA#_0G at 6eF=LqZ`8YFNIHaj~UWG
z|4xM<xsuThaqB6k=m04xUsPWo#*U}Kf^>zhFW)X(O2C&EiR- at CrF0t|K^^RrPjk1h
zIYS%CsD$se<Z16k*;w<|YnoNmG$9vnP^Dmn!jmu1)p?OqK|7BbuUJ?@AUQd!kV08m
z_RIl#%4SDTb0n@{H3Atg4k8?Cj!8|R at jP!N7;>YU1tjqEWThCWsn at yQ(>D`(CO0!k
z;L#QQ;ge+{BS^Hy1#A0Y*G-qn?td0RM2ZY#K#B!(c`vRD>)>BOr<_Hyzv-|GJ4dDT
zVZs$6uAkAgv0>d`14<7#G{a7iuY;t;MTRRm2xUr(adQ(YQ?Q at -0)-z}sj{p-eSVU@
z4H5n66o}?_Hf*1sSkI8i4pjv3hD$4W^}CvI#)Ir-4zQfzb06V{xHu1VG`6AWGLJ5A
zu1Vlas_ at f-AhtEKFJ8W+x%KtP_wQDCOrPikDn2o=-Dtfldr7y>fl0TX5a3%Gt0rE&
z&Lkc17 at xo0+~%dy{YO73YI#sjrN7;dS&4XFBR<`+=w-n=1s;sc8?tanQ<4>l at w+0;
zKV+^|kneo)(773&Wzf}};JJVdF+?E0aDOW{@@BbZnm{i6{7kvyJ0zkdVwyg-Ob_dM
z>|=(9j4r9Tce#lX*x%y6_2nUOkF4n=x!p9BS&zLQ$ji$YDMoF#0t$buBY5lbf%=d^
zWLw)US)wdgWjG^!KM4a!cCZDN<@YUIkYv at WCDI53@PeQ+yuI+p8E?NmaIdgb<9Z5+
zkPc?-s5Bl9Z^DvFQ}{|i#)cM4x1j!j7VQELAOC4(ta7NcB-um4eaN0G4Wq~1hn6f2
zCx`Mm`lMgYb7YOc3i?-A>$JpzgK>+6yIeH<6<weEP{kmq*sU?gAoTC2T}m*{$hqY&
zV2VHXUb0xR5tB-Q&iSR%<P>$;Bs$@(?41p_Nl(yWKCPFB at I&3Rn=IPO3k1!)lWzx{
z^8I*S(D{k%M2H!;#YS&VD;BP)+d`7VE^BXBnw^MTx4D~st83u|<pwMj1>e=oUN^ya
z2i;pSJ(L3CO?({h$Y3&?_IUQOM0Y_C!ZZ~$<H$Iq{C>w0C$HVeCQ-X)#c<4Q7m{5r
z4HlwxR457ItJH=}KLyGSpdZ_so8`YOYA(;*hernGoq6y-kF4f(g3)>iS}6%FaN^k4
zBU5{1p at Jmg8HMKq<nyu1euQeZDfsdo4+_e&_T9o-^Ogu{C~@=U*Iq?`?JZSd%uK{@
zY$bj{(gTNYl^SSPTR#dxoMLykoPTsWdJ=W2*joyciD4SPCB9U`A4$oh>M;md9RW2a
zeQxY1q2nu5FyJvg^XK+$wh8p4TVfy&vg`-N4J)qy2pnQlTUG$iG<P~xeOX$jB1 at P|
zi!@MroArcOF|pf`Fbg#Q7_?88WUwQRstie8OO_@;f?x}x`b*;MuxvK=F%0tVi`q|R
zk`h;YRGTyD1b*Q0znP6Aljlm5FigiGzG?hZHz>SYZL$RFr<;BHg)B<mZ|jGvFSqky
zgdH3hP(Zyjr^CI{tmrPm(y~wNHV%)b?9q+Vttym}XgqDZ9nOiW3x0S<f-M{y<;6SF
z4r!3F4Ot%Jj4UV`y+T at JMxUTx)BM)2i<MTF at ovAzqU%g(TK4z=m_-_P>z&Y^f0t)}
zKdTjFTvf_|fB^Luls<>c4}W0N&1ip{a`uM#jKS2bR5_M1nNbGsPK9MhYySPqTI{25
zz(NaZ(m{I3`Bkfji`(<>rT0B*mcVq-&Mf8^z}%j{SOJYg#_a4Yoc=mDeGYya$w<07
zp%bdbDBiwz+n|u;1tfz+C&YG)En3^)0&M{c;Gvfn>4+IiEO3(K1M6c2f7jP>Y6tW{
zeOifxcoa*_2th^$BFQyBJX+GL)ry6QSs1wNu><pY>RsWzAZV!I#4UP3bIlhNhpmYQ
z?|(t{OrY$jU>6e7%>uEyHv}UVo$215rKuiQFC at i?k%idV;r4g*U-;j#lEx13NZ at HR
z at FXg<oRhL#hS5SijmgEEuz#WT$qb+4YVDq$pck1IRc-pk%9~;EKOhT<a?f6g2dy>1
zd(V at 8JZEkc%9VkL8ht&%FfSC2!Kkw at dWBbwBWS@Gc-a7H>^+0YAYvp^s_60_g_AjT
zy&=YWEPhfx#n&k6WuC?9hYuePps<>hK~=UE$`<Lg$QjO&!FNwzN4LA1;9tzjHzhId
ziNzQG-<;ua4F>xST@%B<eT7}JW4}JF<XY4JX%Ug()3CU-ew;Y;moVF5F=FGqrEq$B
zGGkgNkVc51TcnGkt|*U*!Et%4+uI6oL<v^#A+rlf8L0eYRUMQIcT}Q0xY^^dmD=yW
zykaZ~k`rcZP8s3}I8 at k`nPhLQ;@*gOBf<6QP9qw2v~+A at T$}=15+<G1BcMaNQRvT$
z>QKIJ26nz>P8ga*e-iLiq@@U1W5t+p-w3P<val3&&>AABslQiVJ;~hg_nyViY0VW*
zo`RHJtcR48JIhfW#JLtsK}qiy<$-L at B(L|QaN1{2RCqA8oR=@3`*Cl%*jD(Rg0!i?
zuATPPFWL(_%wom;YoAD)NQfe>d6FaQsiH}2M&!(0&8bK3g(>oJ8&y##D_j?&56^Xj
zK9J@`P*4ykk}NWvZ|vEmfZS)LA!SKGmK%qNVJLiS3U`=uy9 at cpC6V|)os<@%Z40Bg
z)@O5{^dC(76YNja>ic)iZj4raPMrKuMcjBN8_Anta{H}jE12G>Y&CduNxg9g*+fl$
zVu+fSvX8R*v6E*yp7)EY=TN$Y<j47u4Ju1}X}QZj^#UA%k(ydOXdgm=kLa*<?9R9Q
zh=sHI9$P&a3|t)|6)5G@!2-udHz5NFN#P9%9vHy#(P1EtO#R&leM>R(W$9B&A at lE$
zg$$)@i2-aCx{g|99Dv at rEi`+<nupUXd<9ZF2R1z7BBi+<KIO$dn(|&3h>1ei8ZwXv
zhso(31x58kVOXfKy&y3^h~)DDoyx`8k)TDZ at 9Iz*umu%XU6;51wwKKN;=wo>;RC?p
z5eyJcpFuITva$kwqRT|VIHI1K=F8GM!!V`4i~kX1rOJ_-DFBRNt~104mW2+mqkuOA
z2-u_Fa}xstFF}I}4vU#6(;{%l6@*<%dY_)25;4h2gR=}IlhBvm at u{R?@v{agaP!fs
zM=0XThlDtJ3MxK%3fbdD3>g;3mf(|Jki%N<0WI)*qC6!xcYX$RD1X}i{uFzW0}8lM
zh{%#V-+lsPr>EyOC?K)~tuA4(+NN$~PpF3MQt at XECzU4s%2$prMZ-(TVe5q+m`j)0
zUm#0<?|xrgTpXme0jm at Y%>(q8^Z-EDnBLs^?Zw;O)di7(pu%_vjyX75VK_9ex4}Zb
z82in>c@^onpa_{mGvo}E|8YX5$3r9s!RxC4X&IIo9~fkiw*&+ra9~c?F4h|i2*Aeg
z`If&{c&U-udA at rGOo&&~h~JRr2*QudjEsIOB-ztIvycULc;nz8`F}t5pW|QY?qaEF
zxd%C$Yd<)}kLYgZ^gAJQ`pHU!Rke_D?~xuKc#P!r(0Ela(e#u_^?sX>=+!;uDrUu_
zBEh#&>-lCoGSyFZ$M>Jy*pZ{iM}f%B*0YYWzyLo-u=t6Jjs&j%{>=cIp=NM3M9}R#
z_5nxK at 87>yS64x?$>j}^Y}M7(Qb46KbhyKC1+UJ{%?-RW^?zZcE7}A{%aWRqDFOx#
z1 at YsJl9WlrohYmvYno_lJQ4;5g1ZQOd;_+RIamHdh+&?pGJ;UiC{|(`p~B-JP?GP#
z8 at 63sT3Hdb?u`V^y1jz~qfC&Y^ln at rsz<#tM+{#*sm{=(kT%+yrtI4O$Job at uifm8
zkPO^ig?1PqZAln3K_mh)aGmmrkkid_2rt%mYh{MFqbAbaY$9q0>>qr)mcYHTAc7yV
zKfpKSGz#{r3eqe*d}N;xK_A6c?x-i$&VE3d6G%X=o&Xd`c1R>vRtA+$Yjd;j=I6CO
zV!3LgS6MuhWPdx)+~GOA$jduFKd)PX>_u4idk|q>iF5xC2EdYL5ZDcwfm0h#t at uf(
zoZzcRb9aM<q|pB=OO@?ex(}FPoxC(OGz<+5;aJGcrC(@;UtXn}Rv#!vh~AcvkO1 at L
zgy<MZ`S)QotGXwec?ZtWaVg;9+UTs)>f}WU`h+ym;H@#^!7OjY_RM<?D#hH~9IR at C
zGEG_$yVw^mKtZ<k4Pr!%D)z$tu6pL}MJUFkFqKL|vSbdMK^oG1fu?2~c1;B-74H8$
z4`v}Dl42ncDUtRz$?-mgP4^HA4xkE3<Nzpa`bt$axJ=N&LcQFd(1FJQLp;keoQ(j`
zXXRWs&~9}9O7}1nltMRqS*^nzU at bg*WZoW-W(meXvSJ~y<&iSd)1TdydQSmPuQLec
zgD><PM7=2~#MP$|5PLVO)$}dAs3zx$_v7PUFmK(yefz<qHFbFGdVP>6ugk_q_TLBF
z64TZ755T)^RwS~~^pb*T)(3v)Hw_I_lOIE_+>>xtcYxax+(GK1lP6ae-HcY)dtkEI
zJv at BR6&upZcU7D##u5_={;%)LaLcb6w!fH|7%~cjPU~<1wkkxvRaHJeONR*9AFHc;
z7OhAwuAxt#UW4vFUS|e^`IfG%Mg|o+`O=cgCGx6?XhcLr72RNH``?FqE(aRUin7t_
z0V^k8kXmi`!hoeUC at leABuO?lKw5f-hvP!AZyZCp0#iZ$vu7q+xo6>|8Lgsh<F!_D
zhLd1xn?xi;{&$yMGPUAr`Eg7O{Wzij(GN;i*pVl5js+dy)tKyTY!|lNhkc?ost(qA
zinmBmfc at _;*;SZ}LeKBA4!!>@(pbzqHpfGenvnl54IN#TstG$E3RW1w9<^=-I3y93
z%kcSl&W#JxQ^%aXX(+Zo5XSnyUjvW%d*szONb(lH`V<9CO at b=K)XV?#F$UMX$aB^`
zOb~BW8<?q7_4Ubq4h|3BPO4M?@7`98a#!3tCrpSyo*v9tt>>atZ|mp`#w<fK`oHg5
zuV_so;8Jx!5316+vxw$!#XrB0w_?0e;3-(yfaC0c|EjPebnau{D<leS0^7!RjN=K7
z%BLM(dP0Ue0|cr5aEVmuMIVLDZ^%bThvW*tNvh=fIpa|{eR-jA6I3kjQ=053 at X65=
zSwKGe|9NCQRK_ng<~3g$zkK{irBdAB?JoRi*U5^VpRZ~!!QkhTx7PDNA6u=F`R=(!
zjRx9LyuJtL1N&34&9HxG1$5Sd|J}Qk_^<R|x^Wu5O7HC`p3KEHYXOtA#3^_(CJ`e~
z{_}DxO-vxuLA1y;lj0BM%Ws;qA7Is1z1N}seE&bY>VLjXg)v9e)wdyk_a-xwGP%=X
zl<sEl?*HFkfnt-~=`_yz|M6E|{_a at b8|!@2 at W+|P@{gH*Z}e4yCA*tgVtoGdZH0!c
zy>)h4Robt??W*mjHQ3&+XSW~q&DyxbZwJT?gA6OHVp5&-e_rUb_?N${`ptyJ$*YWR
zb3dv*o*DUfx&6dAdTFgQkZ3=w#=))6^TEoXW(=Xua}qZi`{o*x^c|EEu|nY^iDoRU
zNLo&=9}d07jN<ML$&3sP)ex8Rp9QHopzmkY`_5yXHi(qE;ltbPv(}93(av>SAEc6J
zX$@=$OBiFd@*FnB{^ti*Aj92Htbe_ho1>3j&(tmKQ*vbX+Nh|E*5mjB4;0M160POs
z<^TIy?$8=>yRL)_eE<1AN*QGqR-jjx+S`fzo|7MAlIyM=t#@>imDgN<?<p1i^lxM$
z&!vOnTOMwXpOiF$Dr1@^LjD7Ps>xYVx`j<1QqmrW`lbC`ypCtw9ORSy#dY at ftK53G
zni!IjOrtA|MntA6Y6c+(gNIi{5p`ixOm^f at Ai{(4WoGa8)W&ou{d2fO7v5i at s;PeG
z8)tlzG|Tn4bv40ka_Wxfb(tWWjV`$*DOpLHh4Y`nZBU<~o=MOI525I~gCMFS at 3d%@
z5B1?)=s~hE|Ge?=I+I|#g!96K_;f5ffmdhahY%l2&i(IX`Od_RL0!JavyrhbQoR)E
z^Pw at h+1T8R4Lu#%lZ at Dq@}5VPyba1|Wm<V>v$iQ)v%!(yh>n=f7JLMCKis`MV0uKq
z&XX?h=*XB(y#G;j4Es1**YL^d-+0f|j5=#KZ@(u^^l_=>1)&ZVN9tY+tYYNvyd4}k
zlfOZb=l`z4ESoBQYkGX&o&PQw?b at Na(5g?l2lty4(5!Q(|0bkZ92mc7f|8k&-pE~B
zD1YnAfx_0o)(Y;?sQOnKVLqU^KFe8g-cdbPB9@^5bF1qLniKDD+Bl30#l1!*1Vlje
zefPaYTe?RZSX5HR`VSsTtcZ#K!v~i=YWqQl`x2`Y)wdHk at C_!?n<Q@?avX7lfBO26
zYAxK2c!!}gu<sIHSQ@|0Ag0c+s2|ShO3D{&X%ZP;>-DUXk>!~XR3nGTAbtyWBJ78?
zg#~kl4j6r0BB3C-aW1qzOt3r$FSDeiBvci%o`4BYuw+74WC1sE5J|&u3!uPiYP_mp
zvYvotdo0}<MAJ>hipbY^LNj?&5o0N~!)qm)u1Cm0!^^O;&TT(7?&0?;;;n$aq^2QT
z^}-v8FQ!^njs)AcQy at fpYf!+Le&SF!NGUw}PRD%RPQ#dV3<Gu>F+QExpC=CdM}N<w
zY#Ky~CBL+_Tef{7Pmx2rOTYMoztc=DUme$RmyY6bNRb!eH}}Y08Y=w<sP6 at rt`-fd
z{HxJ6j|jHsn^ur2UqwqD_}BiP!je@)d|q|F1mEPtjPncs+^m61EvQK^B|6ZjqNKu8
z;!_9q447ZAo&UW+*P+^|?L7a};Ai#W%<rt_*5S+K9p`z${LoX{@i!HLhP#uvK08wE
zPGsrhu3tPQjxIZw-D+mOk$B8Ey8oLr&?!lYn;o0?r$SG9?X9zH(XPyw(HhzjeY2`d
z)nhO at KN?fCT%fS&U+ at k`(T`bUfzb{3d3+ZEMZ9^~>tH1A9tQ(R1=NxsoG9oe=plOg
z#ful2nVHZ;08&0lLD>!B0#Ha!HhEaR(4GN3Bot%^d;7{bo^(<+RS7An&kdU?43ZHx
zb`B0zad=k~jC+(11iS>~lWqL^bqjbcaFx6Yyj`dbxdy&;0AzSi!t at 1X1b>Vn7xZV)
z#+kjbi$nBmC{Ei?Uc<YW$AY7L{vngsr9v1*oVE^{vMB^%B-^`mHBtgw#rP79C^sLr
zY~MeVSYOZ#ytdZzvjtJxMVx=dnZ$e(4g6<7b$k9c=PlHmJV$0!-^JjvTc7{8J$kZ*
zk;?B7YI(LScNs_0D%@hbmlpJp9!4C>%_lK2|IVL`vZY9Wc|E$m&DdY|`lI3pDUZnk
zfkUxRGS|;~XGuidmaX1!csLKwTLx`faXout at mIbJB`6h~)UPX$eh}D at z08lt_xUeW
zUXt0c{4%f6oW^c521LBav%vo;{Mxm34S(XK?sa`RCRQa}m!EhiCP}Y)rZAB;>%UdC
zh3IKU)CynjFl-cL)G25axP`1PsWGq7^eK<Ves9<+WoUC4F#g at _t4G%{z+Cn4mChRG
zew#d*lkWh}(RqMuP{gdS+!xl=ACX+>Uk{%iPAWy9_u`%DRgaHG)+D}iyb8F52=`9^
z7mUguH43dC9UdNnX$rjN+FDu%hlkOUpe)zX0>0+``*d+gzm)-Ygp>3A!~{7 at X3NI_
zm<oaE47)hE8#0U)1bw8}2?2y^oGB)&3<2^B10^wLv9Zd1xPj- at D_-=SWf*2$lD{N5
z;^5#oT>wfp)vQ6i0iYN#MU(?&P0%6^nk5#gL at eVYa{_=MgEtPRrD~Z(m0`bwFWw-|
zsA;@p^^&cl at pxzF7%vw}*M(;9QBuzD(aV2kDG4^|MMFlrSgrmkmq)*E1Sd;SVK!-8
zO5w7j>efF#l%#0m3%#z`dHJ)8wWB at ca_;U>@KSpwYiY`!eCZ7q0n at _00KAy`tyh9w
zN-tt- at iVljHeQ$|+XNdO)tsit_<7LnL*Ve?7`0U|{*Z6J7$v5~^6-uP>f)V(u)DvO
z7FF3^OS^F-x%>;vEG`_PIYA7+Z~g_hycD4s`TbyF-`K6u7Qo19)993+h$Jlem|~d^
ztC4=@&qd=FHOgP(N$-lMZ*{Tw#JgQU9G;-VK%kdYCj{?hFo}MqT!)E<tOH6Mb~|vO
zrT43L?I4*!s0f&0lQIU7F};Va_<@BI4?Cjx8V98lt-9RdRiHbAI=T$Z6OtrqdEy?7
zy~6iX`{Gtt?UX4GH>>Qzv3D8B^yfe0f-#vHj>wFN<qCb$T)pt*XGk4w3^W&AP_9Ox
zYuOOGrWu5u>$UNmpkJ7d&bZD586<y&B1eJ8lLwnEUP$KbqtB26QIVVfbR29q^SFp9
zNczeAbMK8jFGcy?;Q14^$>C2mg9IhJczC{h#IixhOEI at XcK8{PVlH#ZqiU`5hgIo<
zs7988O7b73n+%DvA24|qW(Hn4uMm?SEHsSuxs%TRc}ny><bs^zanuTlXHcLZ!z*~0
z{wJ?_EhqM!>`Un9<K-u!m*y%+$vw-)<ih?o#bGS8ubGtOI-8w5)sbzP at e2%eiHx!~
zM(^-kQdD7pKnXYoS5v()%l<4bUc1g06klU$Z~~CHVlLpnJTV25KGD+j({0WZoJ*cy
z6H&D3kIw*nzAVHG`0}P@<XQ_RDEFu==5z~T`9Fe@&aN4-({`$*XbP*sxT_THd-ve;
zv~gq1=I7?P!_k$(Wy3C|@e=o1{kC!#lAFK`*5lN_O(Hb;^oGs{7MN(V)*0Xm0?`{c
zaHd{r;=vz%tkIJ+RDXkFGf|AI>Jwbeqg$93=I19?b(hKpaBpXrYjMh%iEj{K(Wxnm
zMDk|V&hXq|W5b9M%9ByNZ~;UK>{w*s;LlK1`d4}72HxNIJ+Y&G&rYG189$qdhYYzX
z_%6jX82#-iY$}X1qMl!oQLd{Qt41VF54KrM1bsEWF$S)VLv>tT!*6V`wF*4SzC000
z=7>S5em}T1dtluAJ$R+Yw6-H{5Zz7QD+o)g16sW(MEF3baf8 at T9v!lcmkFO!f5-f7
z8$SE|+b-vpa8Q4LYT<2GJgtA)PmUM^k4f8~$=$%cP|j}|AA2a|M?n0dUi=J>G#P&4
z?r#AdMA#O)dKKd7@^HYuvJvWY+&$((2KoIcf)(1qzsGDY7vvD3-V)ds%J2sc*$-{>
zUp41H0FtMG=4q|Z#z)XV<`e~@-+d^0;G%F*mQ>(*2Xy_-VrE?>H8r(Ij~<DOH^Cuy
zdVGw?&H>B>Za3o8$zK3X3r+dcr{snKfC;KYV7EUz-0xJHk;-1-Vr)$HnVG3Qx((l1
zl?YOsN at qZc-3#zf+I$^Iokzgv?_AZWr@@1Qp<6M7i(R4N76GY`vt4-fs*19*@2~06
z`T0kX_0M$!nNyr9`E9vfH`EZTG_N-f(lqGl>37^P7)YIgN at gSDyY~hYS2ut_+SB*6
zVuFDZ?Wb0OAPVA}ij%gpfAk at A_Ym1f7k~~NeChC`Afrt1Qz+zO$3=cS1Zx=-ZzpqC
zS6443Q&Okn5J5s1NX*RUQ&UN-w}G at 8^wN`rTU>fKQ4ISa>S1;Pv|>YSC>W5vSVfHS
zL}VgsD)eI`dIdw|H=@2pTq at CuB;Mvq=Ao>orQFz`wD8V>Zc+B=_g)|tR%>knwWVNw
z0c$x0I-yKev6h$L*4pa_vX*SSSH*b at ZTC+UTts94T>batS0mioJqMYf*z35BCX;+R
zZE_Y-Sgk{D2fO?<V~x&VEj4Fof69=(RTksJloD{DMDN-<FPSAZ)%1~s?xlOaEJ?2a
zSmUE;*?^4Y$xPU8V*vpx?FCPon5mg<=>D#xD3#KirMIjfLb`R836GfWcr=LY3Q1j+
z8k)(aLXVk8INqALx}m-!IX7L#`6%uc`n$^<?oW(O*3RgD6jaQH3rTp|tr%X{jW*UK
z^5Wyw1?<?|?ClkD47Y6atI^(l=j{mMo}sRd at 1J|V6$%2r!NvhsfiPeqh_w78SWr at 0
z@;g*j>zkW#p}6FLlZ)9QeiHvGK1(KHE{(iD{#BVvLi#P_C}rrtCJ$!zoK4^iSoDB{
zmDI-+Rt*<@@zu2&kz+YG at xS=XGVQ9ApkJq_$G3-$n4}|Wr1vIV`j$9T!G#bWtyk^f
zJ_v>qv<j0lRS>>a<Pa-wePdK at t>8%`9}4jQCtNH1?-{vhZVTZe$tEmZ44HEt0JN7u
z93G?^<f0)}*+vJ**u5tA>y+s~8dIsB$^)5+sw^VHz`*cw at kQJ#9M9mA+-13lYA&%~
z8V%Y?K<IftPPZ*p5YH7xMIgb8r-uVKHSkGY(^iJH39R|ml{J=acL at 8UzeClhA=hUx
z;;|9sLG4=He&9*btZu0g{$3!UraE_Lc(A}|xS)3j&R3UhKQ>7*oe5^s*G0<c9kzR<
zLsX*|B=oz1yTj$OPSYZS|Jp+JeZEX{I^MMozicCnID^T!$A7$R|JAK?4kk+Uq-o_}
zY;)NKVNZ5+$^|<^cH?fCA^(}o@~8 at W8X%8gev_Czczw4CjVy&$Qc}mYS=_P~L+fAl
z*KDU>eg(b(a5~M0eIeCLJ`_m$7HB0vKu4k0-^qpXVejwVDr+kiRN$8s<8eYrVx|0=
z;`cplPqg|v$8-9YNSjP<hHs4F0SOEbYJyBQ89b$QfA%-O-6c(OFLSduH_&|?8;iJF
zKxX05SYPJn)l^lhNY`-ovC3F=8ig=Bv1A}*r?k8rKQ~goB$bs1Vh;3{e;q>~wz35W
z%)tpdAwPK>P^c`5c;rs4YD6;>kKm3cLb9 at t86+8og)AGT`5MOn(z2kIx1ik`;QqxC
z{{D}|1%x*wWS|sqaAGDW4cnvLqhn&I#nvM^4ZCk`^2?5;YOh8cOuLF&>RxNz;=xCn
zymiTZoyyI?irGg1ioPA=YvE#fy)5!N^0I~jWKIN2%6z`YkwfT7QflwK6WH0=?{71w
z$F=>Qe1m+7lNtRq^NjLm-Um(e7a1As#h*Wa_SNsQdG?|FS(V`|_EJT9*E4s^PWh1(
z<Fd8BQwidaqQ|65K4Y at PIAm6+8+_(UV_%rVFaP{1U{=yKOEc0mw8=bw^qhliL)wi_
z;KA*DGcpPiV~#N6U-2BY0fgb?^}c@%5J)1!my3B{^&gZOy&}^)w<MJjE%GTBpowX8
zKiJg$o3`wZY&YN&%Faw%pZrScTvz15r=vcoi;2hk-U8;+qFrvZ-p#uq|GNIZ#|SwK
zc;_-lr6;sfXuYyQlInbfrj*(HdsH?m`s}#GPkrJ0C_Rp%`|cN?o%&ay$DQ=ohgx5i
zoICYJ?HRLreO^9bWw-g<4wGCm+5EgjIfsV<k)yAu8*d+u?&B*n7AaM9ARf{jO_7$4
z&a}w?>y at qGQIQ^q=KwWaO@&_WXQRjL0XDjpHXkQ(syA>0O0c1JtLNa5+1T~yq2fec
z at s6$=_wUPk@>wi>w$cyp4A@~UCWt8-pm0Kx_u>%HFvsIOaC37;BX8~b4w1l+9|)yB
zVF8n-TjJKOzEV9~i3MoFp}kaV>RYO;(?8w1&y7i^6ajZ%#5G0qV$xyFzICO(D5eNI
zcps`9+shp3&Od^Fos2BPAj|a{rHz}L*7L=7q2*!*T^5?e at oZctgMEg;T7ayJ#r8i_
z5P3P#sTJAAl0;Y9#n)=6HVxn#-yP2?_JI+t;erBpA9^yZrN^dFm(R}k1P#O9aw56L
z?$fp{E-e`~9uOAJY}Ysz1QKajaD-XoaP9hxbv*tWf`g-HyuAYX24Wn}q61m#g)273
zGB9euh>Ja==6+$0v*Pwb{MWe0qPPDGl}VW3etvc(X&fH^h83e47%Bf$Ck$HuU1UnS
z`+pY7drRwKXb@>31#_{uMAd}GfeS^#{p?C)2Gm{6`%GSdwWG7;T_+K^L&YK*Y at 4O_
zaU-lKKq?SL^sl3Ek)wr>=#lqKi=~VyHrNiTHpn)VC at y)HILMsx-s($xjZv=08u)m6
zK5pT>aU+2Mx2gbgP<roemKRI7va7cBJqG^e_ArlOq3~lbe}A>LlCG$jm|u9*PI(yu
zVdG>fh1MT62xIT<0&`I at 3@NaST-w^&pqME41cw$}7HKb-^Ys(@=t4|}UM6!JU^wB%
zXQmy&chpg(cVA6C6Ja at hn^ViSS`@?R^7W^IaK}Tl9}4}S<HsAd7 at 4N3Z{uT%Rs8z{
zU32Hg_5qAIoHlp)hMlI~)R<`ezBtP1nc>C at v=OXTK=Zc#=DclbJu+);1~A^)U$K|f
z`N7M>fPL_n_1WA>G~>-*KY#!0;g7M~r-jZVj707fxh(?g9jaO+2fHJ+G(XHgjyAd&
zv3{84<qL$}0N2wLU)weMCL$~z9xZe9bBY)Ef(=EywGrS%H{o)l8of|YPK;VbI?2dC
z3?MhWZ6y|N+2D{Q at DKl@7c=Kj#C*0$NP``PfE#GSfQ;S9uh106It4x8^z^hUb?;M!
z%L>&#dl?~uZgpIYXOAC01~0aTv#TpGF~;m=l at zD(uvbX5ML9U4u-Wb4W$wf7Bu&rC
zDih>F!OfIP&%w~ct&az^*UI{O6YyLM3k%R74LJjEADtt9iiMAl^kLHXs=^!`{c!xN
z-t)sdpAkKYU$3iIycc7b8c)Z%rgk5E_m$ue%;jsdpL<ufPAN=|QOuX0Yw{=8d8$g;
z(7aaY47v+~Bn7lDO&+yZE06<qWde}F!N#WhiJ-tyRcXDKZ0G2xRD?}HBahEU0_{AV
zlrPs;+vujv-M{3&-r96yEiJIWfWfa`5lb5d1NtEUsahnQ`LOJOVkA$wrJzpgDo$lp
zSo8!4Y`|E6&&_4frZ6Zx_+rQtTUdR?-f#+*7Lbuakx&!aF at B7vEE8KWy?OKKV0TwB
zmc&M-aH%bTS8nO$F}j<rtte0>J7U7Zq_^UCFhbZ^@Egy!lmh}Jl;^h9B9S^u+Hpkk
zTJk&$bae6iuvaR4ygV2)D|wxULFH2Z)F#~FkCNs~jm^roD#Oa%?|<9kNsh1P>uCV#
zqT at zwMPYnI7#!e<&O#Rt`b`zIZ;$@UT%DXu;n8#ux at A^An)7n16VV>!hbku2<$c&B
zf+6~(lywgTIo)4DVXS6fXcW)V4D5L0n>TPrt+}RVVpEeiyJj#c6iYupzi2N-ouW_h
zhsKW)ou1*-u47Amq%zXd5Y_`(Uy;Swn3x$hcsRS|E$_A+C@@$m%%0Wf>FWlEM{}&y
zl$5Y(qj4xp!c!w^P<AbLP)%mQB~_Nt4$pd~%k22j-=CVrP>-t|p@*3h)C;4;{bBIl
ze$H0Dx};B+hk{ZqvYeGSkMk1;KR=;OQoPE+2lOOOU<$|oK$@ZY?WTeQ?2*~DSlgqG
zjSWbGT()y2B%yP+UR^BXe;tF|P+!K)9-?9a!nE5GRN=A3xYK;7k0G(RMsfM&UyDx$
zWf&F~M|ETl_JO-Bu4Zx5{?BTAR(Dr=<7yrTc6cA at QIf*?j^U$PVUf-9y$L+sZeZ>p
z at v6;tZ2ipaHCRo94t~PjL-I9?{Sxsa7j*9lI25mPPKR{3lqJ4aa5CE&ng%_BWQ_I;
z06O+hED^S<h~4LaG(?fZ;M*&>q@&KJb11J-L3tRTm>8);J-*`O?Oj(J{OfLQh#}sj
zgZaYpKmri2M*S2%{qNW0q|9oQjCYI|94sMV7WT0UUrw|Oakp&Lkc}V(y-|D>@5f1y
z3XH)%mZW+cW4olR9BUmVUzWz-{uEm>FfdS^dAe)D)u+-xU%%fBO&jf at 1Zd>IgE!8M
z8B>;CJCpxBqO0)-?sbYVmeJU#%8~DS^0lPAyk|v9F+$q%8W|cCj4P>NU5X33gi%Tu
zGvanaaj{&X^dyt=r6I<LyR3#Zq`g9!iMU4Gz*=;%^wgMzoSKe)`Fqo4+37E9{)k)F
z|Mj4U%~}8h;OYys?fTnv^`J-T`y^3`b1N_q>^x&YCoYRpTa}M)`DblZ)i}E9Vieqb
zHzP<ikhjTohRB{Ph*G2>2J5uvG1eD!V0bq{v14K~>zxFO<y*Jfe*b=O^LpRHQ5}!b
z7YFaRJhD`?yoXy79l&S6^iK83LYU=&!|^QbH^x5fN0`1%58oeNG|7dWs5m}gdi&t(
z at kQBe4$?ik1{4-kc)NZbr!H>B0&*Ao<nh+c*x4#Q=ok0zAHS5d#f2PSA&^}W5k5-h
zwUc=OU$<V~NMy=53G2(`{13u2@|DjHnsJ15RMTTq4Zp_xJeSL~WGf8TYhb7nbN>8$
zkH{+YZ1kuj&*Jomo&p(cIJ8mkQ)2sLG)YTad#;Yf79<Fuq?Ti0853&P@$~Ug+PiW{
zB-OG14_7u|ZnP=8U{c8IGoPN{#^tc~Y;hRlH0W1oqw|H=y!iL(iNecUTVFyQrl#J9
zq|O}I;d&)dm6v-+`~7|<`4t@>4^MF~iAm1#|N2A%!^((v7G^1NfA`rqM+up3+1f2i
zc%)eW!3f at Ty<lqf-8vqadC}S4^z}@!YuL){g_Ory*vo&^2fxr`isi3edwlJ-vVx(w
zuIs<hmtUSt^NLl^-E?#~_xz_j_ at _h8^(gRb)6Wiz+DqyJf8U3j)KZ*$EY_QVE`Wl_
z|3G>)4HB}8Pue>=rVw``uv!^}PNngqt@&^+Z|EY4^LR36-ie=4oYQzqOG>*ach91^
zKiR5&Bp)m1{FMsZ9P%DO>C at pn;gDJfp+v7^o;D;TTmcShDMZhOte4Mcu|T(@sjdC#
zquQk at lk~=Gzk;Lq#?|Vf&4g$|!uqDoxp!J;SC6gEx`gTStRZ_n^`59B+-4rdc<J(-
zor9z3gn at wpq$=>$szLv=FgjX8CQxw2%s at W=RW5C;jSoP-d3kxRGp{R2fAoToKu-n0
zD`Pe!g!jFLg011iT>=^rx{!@TOS4{v0a at RTR66S&RB!U~j&MK+{JV(T8mfwl=={}|
zo#zmo2okOz`xg&dd<tIa&o#-+Yri&qhue8m#M4~v?pQ%s<4L1i42S?t8h*HLuXuD`
zej4v_j&1S?IF5vhBp<cYg}^rNw<*k$hcxnUVYS2STes$XeP|}XJ5I)K1L>E|r}4GU
zA={ep?#4Smqr>*OJAX&}J?S+?g&~(UYT5e!%GR3bBftH3Zga$^o-c!Y)(Dt>f>^hT
zGz$~o_Z}`D9`O7bbf##FT{W*4CyMUi$xw}N7cCGAc-rp}D0aN_MQVEjq^=Ls4G5QQ
zl4Mg~`gYGGba7&<{)D+&Pw6JaPp3pc_JBrGU4Zdx^SGQAXxTd;qmY-b{(gG8wXH2V
zEp26V7A=7m4k4W(sbntU4|Y`BJ4Um5b{U&p>9B(Pu)4a=+xOa%zCGazn|w1hCin26
z|4|-^tk>q}m(UZ+K`UxXs;S^<G5 at UIEA(T8FpDkDzJJqChxyBfvF~BE!cv;RJvKfV
z|2ZNkHE(+Bz}NTSkS4n4HdKm+GJX>Yf0f|hRR^#9QSUqko%<Y$`5#TNXfz-N2p?$`
zNE1sE>=5|=T5*5bp!P$HPQ1plL+Ud0Oe?$79pim;vQ>I&GpJfYOp?KZL>lr7mxS{Q
z{wxRKs!JqC54r{Cl|K<bn3Q->K<$G7imRr)-0_}w^LGRSk;>F^w^81<|M#CimdQz(
zIXR~1j%IJ<vm<a+phZ!9`tIF3hw}q%+CX`%9P_}_)o0hf>&Y;fONH({EQ$ULMjPnq
z#KflkLX|LnD62pm<j&R2wz#4Y`a<L5<1-=tATjB=ob73KnnH>60?v`Q-)2?AW$Rv(
zRp at x7^QHN=|F at PSUE-4V17i#JK5W53%XeajAwg})2nI>7-c=R+6_g*CnZ!?Ju1&Vk
z;rlKDXNixI0yiX5?Kp`+nQqnmm at 9r2xZ>h8pz9YdCI?~e2EpM1{y)YF#vm3(S|0rZ
zu<_Zsxte<os!8{eKWA$HeS4H7=Qh8z&Qx<ILA-rHgvWG?jg!Y~?Q^2mQI8KA%Lne;
zx$CN&k;ysBlAaYWv{HcF3u^l|zx at QnH+`8QA?K`YC7&lI*3`O190>6Dzbg{6HLlj)
zGbtSD2k^0^q-0>ew6yfUL at Fh9=q%Z{_;v3B>A-YOV#q-!&fbO?xB3}Sk}@xYhOd9>
zuI3Rt<gZ0$47q at R0Guim==^ePxrODywz^!3pc~Q?W5EBn at 4Q?qqCyiDnPJu9jU@=p
zFn0J;>fCm}Ejq<A$kny*+}NXw9_zlM`#_0U5s6eu%(tmoNG~c6oM6|Z;ACU71 at RyJ
z-=3BPBpln7m6btT#=<TbjCoI=KKYp076eeO@&GHzS#JgWrcrhhAsy@}rzp at TvOWd%
zS?u-AxaqFT(^r=CGJ}JICDIa=pr{0t^SVm<7}3qd9JRMle2TYH6aCmd at c_D~6Sl#O
z){&&!B_D#UsCc}4aGT=!{sS_nlDBSLSDO3x-PeY7#ZKn_25ou$st})K3_`z&my=nn
ztGF+Wq{U+{HK>)jbpaZ^ih3YWR^!lP-MN)6!h>q9!%(iG>C}8CB&4J)a$Xj-GHIbO
zI#hH(ZWD9X&){5aqR8ZM?PkzEc8H}gaVY=TU-e1r153mVc<v08LJ1yOqj&ginJO8n
zw0V4OHNx%ZW at dO8@k9QC3q6T3K}zA5EuY=-6lM<1dV-1XoebT`l6#eLJ9jOgKLX_!
zoSozzv{=E{c66LK^?k=<ul-vBcU<U^TlO?llXJya+5YduxncWj)Gum$55Ky-z<Gq3
zYNta--QxKN?*WjP8*RrIx59*xi at jn&?pW_u`;&(3rW>(_L{T0DHC{Vf>jG}3VW)@l
zgphvywRk}7-^Hbx_)KVtT2frn^DfYKf#lGbE5RNvjbAubndl68WH=7e|0zU5I9BWa
zVvdWwJ=P8x3uylEh>2qiml|S-8Ev4=-uRplHmHkce$0XfK;a*_L>V0}G#2&yZNlF7
z(jT;xv)A=(^#20CeBS~bZapuh!2Bl&ZanH8(@RMTO?;Ns9H2B9Z at N&tQ4t2DK2f?T
zDCh}&BV5KSA#kB0TwPNGy|y|lixh$h^0+{9m3PfvmG2vmYScuJ9<<s^OfU*TH2k)6
zUIq}9MEvE-Zx=JtB+oz2&(k~7QBq>fy=iJ1#Mi)h`}14JElF~1D*NcerJG2VRg9gj
z at e&*cMCaP_a)b%!LwTxX|6$g%-Nbwy7J&b>EQBR603UzS)fTtCOllC<hPpi}!9XKX
zSXXEg`;d@;K$+rOan|k~FP(NzDX44}RN{m#_!JO44HP*jJ^!QZj#Mh)PO}EX*`O0M
z?ay#*>3DhD*r*_R&Wb5`D9c>S**<mh45SxmjBy(8ExF{9r0&<lG$UdEJ4&Ra8#LX8
z9WXCGzI?2-B6t%?H?lpLp{{EZc1_o>%8cQ<v#ugt<6{UrTQo;;NpR<h$b>RvC9VVo
z1}@oo3BZ8(<ZJQ0C&<((h{tpGPkiesAVC^QKr5nL9-_%rB^3UC1AS?COkjtO1&mPi
zB?J|LNSsrQ_#_)h<Q8Vbi+N95l%FQKZ}B_9rGGP#NsjS}nOy`?bWe)qFWU|8WAhcH
z9({$6a8~y=K at 5qc5C=MC0%Mz(t;0g`ao~7;51Sg!G1lSc)|bBFlV6{{`(6H=|G^Zj
zZZ!vSz81j>#78gH-VV>heZQ2rF4Gmazc2Pprs*`j78{y)RQLB;YQ3;<ePyNdvFC7!
z7Hubv^Kh#Cid+$0&+3zZsTIW<XCIDaBVl!>9;K#|rd~rt3f(vVly;4*aE#i?Jg(>&
zt4y)y990nJ#dQf!=Da7>Sk%t#l;Zf}?h6&X`SMrMRiCJ`RQ-hsvFO}GK->_No1PwF
z()y2 at iHTT=tSNM<S(hn at 9}>c>wok%8kDF!ChN@=8^)hQLyos^~hX}M-OE>MX9Jm|F
zvNb6(H4*4Z=paBew4_G}AO=Vqs;{mW*f)$(kKT_qkSM%ayn1|uGr*#Alfo&Ww2leE
z^g%N{GVFzr;!<**KEeHsw**9`noF|{jwuy>6xglUmBme-H+_k{Z1Ybs-bV4EXo?H*
zi)NQMNF*95zFBsKUgw~Yi|99EG77g0pWzbQ9pu){u)K9$Pi$XmH4rp_LAhC3(S5W6
zj%eWm)p8F2V6GjWJothjd>AoN6d$Eg95Q~o>yKqvu>4M-lvY(cM85U~1)h#f<ev`{
z66EEQaCt_f1P8BXp%-%^iI7C8XUBA{?wt=0q%m2a9~WbPRYf4*6HDN!B9`ya2fy*G
z{`gU|<B%W6(%|dQx2oat6GeL7h{o9jDT44%aRyW#&p)8K?aZ{g)2+Q_z>|&M##pnw
zX3J71|BwH;HkK#7E3ye`Qh0~>D^un=56S|$LnU_2i=~|1y4Q;I)r`YqNW=cXBE-Xf
zD`=m~ULdR{Ofd(;qETMy*`heB286CcLa?eWw5<GNThVuVQv1!&T at V(jFL2S(Zb$TY
zr;tXm>Ph4gw<+E9tn9<*ik-z;l+Q at VG-XWP*qhQ?xEE;&dWMN#z3^X1YVS2*vmir-
zD4Y_J${O(;nK5^VzYp|bWje4DV40%b<lEKzAz$Lr-M7)zz=uL^r1ORcp{v at 1^d|Kc
zy5#)_ at _h}U8)nsD%vA^`Rm7m&#|gZ4jcIBv<(C~ZYIkZGko{s2B_*Y$>0JuyeVKlc
z-fZ3sSM?d$Guk(Oxr8}j_On1S%Gp2gUG%jJJUyg4pC)uqg+w87hPW0Z)6>THtgzw}
zPt$&x3yy|!su)vIMd};;g~IIb<&{<foyuPbIiaqvuisczy=zs}8N?*(o6UWl50&+w
z=EBHs|4({UH at Zd8kkigxkd+WJTh`fybjtI(UeH-C4kwC=iVm+k{ovBm43Ay|dQ<CC
z#8kIY{vY)Bt-(q25SVU<Wr~g8V+lHw=%=^f?jr)XVq5|dc9Nkvtu_xlW>4RS)Vyj?
z1AP!+f5U!tFlVJie6^kh(a_BLt5S(y%LrtiW%*qB<zLJoU at 2SAv5X*Yb!%(u_Fp0f
ziN%c#u5t<*N~b*8H;Si#ZY$*s{Ilv~A_c$u+41oPJ|2=NX+}u$WqdM-l&ZRygpd(c
zHeBhcsn?#eIY)mh>d3ITmc&329_`C>pvr}=HI<u}S3UCwc@;;QX_(8FY?5JIi;Jwf
zlRQO_K;C at ad{aGCP$$0+ciCjy)-XXJjLRfaer0kyEA-A|pB}Z_AF*y!7*|H3v!F5>
zq*t%O=;l4~<9?yV{Z$Qno9(h0yB8X<snFGY5WnTTZM#o>@$m@)zmem~zvp}?6;Y3G
z(uSm?YHu~KmN#wrGu$e1PE_;s=g~VQ=rzHFHDlBXqjatMxQ&*%&nck&D8?M1cDgq9
zIAf!6vr9;BEj##H1cK5S9Sc;?<Ia1S8;R<g!^5ldKSflrObg`3*B}Ru<YseWGqI@`
zdXmzWrhXH|`sDfS--9XPvK=Cv`LehnC+__iR!q7+G6oeZ-9nbM*7I9~(TmEuJk8fX
z- at ngUX5BwH$fkUWTd6sRMW<raIZ;?o@^zoTM1EzTr5cWIg={5``xRxp(el6Eo-xhh
z+e+s#2bCah#6wo0dNzP8U~4HAwDf#4iBwf^?8YHi>%Uj>D3(?Yx<aQH5zfzXXsDd-
zL}QwEDvRJbJ3Cht13r8&sgCCAsk|;}j`+}8hS*P{7xz?nd8bV;{BUpYNzM?<D(#iY
z-g^~c2_0~31%#OV+QrHV6;au{iF>cG$T-?x^#D8c9&{AOH8nNhB4xHAESe*Y;(x3m
zo)4{l3f|8CKE=}ho-Fs06$K|M?0g4DYg@(b=@=>H4OE56vwPOEJi3^4lw4za)2=^E
zpUFe>Z!wg|hvIsyO|KA_A<~>RlAw;L*xpU&6tSmvLb5(Ex%|pv#7XN(ixmXQtL3AN
z)AL8$1EfwL*m-#HmUgKXFf|hB@<GLnP$-~ysI8=XLfx%SOkYO#Ow^I+)6j+~hY0MA
zsoT7FirKyIIx_mI7xJIbyWENX3&ju;Q7eieLKEmE41C|`2m*qP8ie00h~iJ3Cqab*
zjWkCni=$!TrhoWyGT%9|Bp43#Yb}0TSXe;2pzhkYBv?bCaMyJM3sW44%=nYoTVpM!
zcuU<)<z3hLF8)1>9jqYeN2IpI{UqQ%DhW&;gQo|kw9E_ at XggC^SJ?Fb{kZ?7I5asq
znM5s+=9=TybWJXaa$dHH>1&~I?D6sOis368s<zMC2g=fN+9^ASH4aqj9R?yBoHWH9
zPkmMDu<J5G$ggNBw^0kF2Ai9k6acVV5){~ltGa%!v1fl at hj$=P?2wH`M<@lxt$o&d
zS-NO_$bp|kIguK2`}#o)H<$FM*lC&4wmO=`I41XH<;V}&7KLf_JTMSM$A^p2l`6=6
z;VqH3B~di+-8aoWJv;jqe*+cdW`!C5m2w+Rp=YRuWn({(J-qBhsDjpowEd;C5Yhvu
zPqE?<w#)5b&PyseLRxYLCFjGv1OB>B*H8TOK0YD3lzAg>#`l52sn0%v#=KKc1%O9A
zHa={s4Uu}A0X#&~vjfD%07nbFKR|e)<$d?&jUswH=$Ws<#pfiP<{?Y{vwAeEFv$XI
z$6_sHv3eU{H+J5_cZ4>b&@JM<f_tQ2H})bjV7 at CX%r4;^R(D)CNacb_gD~~rf&&JM
z=f<cf*0KGV?Re#JWS{SDdlH?{LlTl=#;riz*FZeK5R0OC#L@$U;ccn}5~my?W~z2_
z2y!aY*2Q&-f{)0^mhUTedMJ8MOo%|p|9G>H&pbUlFgHhg^YP(8WlxCp3FtLJPt+$L
zo0U}3PvX?BLQD%x#AUIbvSg<H at 9k-z9&mL<H?$=bX2mW;O0a}YyIFLF63YPU8n at Qn
zLiYDc7PpW_c>3P>ovep*;y#CET6 at t>nH1Gm^l6+QNB!4uhF;-tI!n*SgCQ`N7~g#m
zUPh^s at f{rx#k64?`zczr-vsfQ&wYuF>IK7k1QqCCdgg}Zs+E08xSe+t@(_OIDw5j@
zZ1#iOxM%S at dr(?Q-1i5gK4RcWv7gIZcBKn at to}bteRn+7?f-ur)Uo$Ek(EtG_B^&^
zk3zPRk(o-ej-4$kAsu8Sh0F-qyAC0t?3q0>Dt at nX*XQy3-v8Z?INs-aU*mPXo{Nb5
zBG!dkEqvy9z;-DuV0pN{`r3>BS5 at 3_vhlDJULG*UNkrh2rC<W?WRl8qzi3)~(p<B{
zdHMwaO^xDT7>r4Y)IA1OID)rU%-=^0PwG(KRsYy&Yt#M%+<Q7{>pqKg?TqTlyr4Fb
zDyuUu*DZOi7irFt>=D$H!cB#!M1jl}NzHDsNJ>!wP}IGPBGX_3;G1H0a;?%v?X1z{
zb2<_`U+nWokBH>O-jm0bw-a-+9d;CCVr}ZK#84et=Z+J~kl6IxGBxxIw}N_3@&q||
z3J)Z25to at bRnx+DuR=RJKR<Alh3~=zS_eIjPMtwfRoopuf>G4<$CP?)4AP0aqoR($
zT9Xl(<uO)Ww`=$LgA1T6RIb;cJ7qmWDkX9SAz+a;g<d$%mcUo698G1)(;fEPo9-Qx
zvz`%w57sJ5XQnxE^K!slOje?fnt|pI!%aT!goG~+cRBz9R=>dmR)VYfe=eI*q&8s+
zdtdxwa_X!{YN?QNGWgt-S!ZceOQwoNJ^nH*17`%Zw)@wnpQ`)2Z&C&Pj{j*he=>q-
zbYNp|kCC)I#_Ypp<0}wrDM(4_0B~h=X-lL at h=gJBEe$iXESQ_shMzf#-cTW&zvk%3
zHQ^a~nc}R%NVu&5$isYLpM{PL+AXj%QM47^396cL4k>y_@>{gq;)_@#Ia5>`5mHoI
zUQX+FDTB&S**|)!JEWJO4_+k4=|?}GM~TVqFW8nl>HRioLq8*w1M$~?Y9~(3rN_E}
zu))I&>c!$arIP{_<u9%_&U4`W`+DK_xm4w*tsNZ}rUn6AQ>rYF)I2=id>jc=7N8)D
z at lyBnTnB80j7^E<*Z`LDONAG?TNu9ketu|X*dpTZG`UrfzHYtw6b{$1v9XMztKC-M
z%Xdt;|Fit53PPA6>xR%tt6kh8fE#VWSKd31lyV#~l<_1+I8J>sw#S?|fN}^c6t_F+
z1D(O%-d^rYkL|qf?JOEe*3!rZAH7###`*wRX9e=|AZ!DANZ|2XpqYWx4ghpnN2mMk
z^`0t^Z?03HR%Adi{xx7c?H7pkNW(o;uLvSPP4JP`8hDmX4E$B=#OVO^M_NIoDxFQF
z5S)vIm;@sYkTIKa2@(7iq8UMF8ZjF(On+VI^c;@_d_X8 at 5OZUKes5|?HjDq2<1jq}
zn!hRqn6C^X+sBhVLGu*PDFZ=gMTMa3bq&A%;Xn0|r~rhbg|g87Ogq~iCkq_|5H%KU
z{*G^)0a09Gp7eJ=wfIu9f6A%rTeDq56%oDgi3kvMDFn}WzPwU$R-jw_ipll=bV5vz
z;6;2OgMrA`6lFNkhgWI^UjoM7h8WOh5>fUi|9#1B5YgJ50$Y1mLPzHC$jB}DlWpDI
zBy6-P%Fey#{x=jLi|qaI>61acolXzzKd0{BlX4rK{a&)2wlx{%q?gIU>T~PXQ0*Hb
zV4oVsL8O{wGva^WA4=9Mj+pbxcAtcmZmvx&r<Dh7#?M?mR(RHT^=tLa*RJyR(^9Vc
z2`^dXgoMc0Qh;<1;<*!lm5GJWgCTI51haTe(Y)sSrM#f8J$X;?*QuyGD;@>IetD&K
zO^5(p|Gl->n&v0|3fOYR-G+tIFo}tYsHW7I{P>B9YWuS6-<y|zuD1R(W0P<%hTlud
z%1TJ=x;qhA at c(}gmLBnijh{a+bEO#r$Q6Hv*Kb}k;-<90wV`4Qwbz?EQy^U2PYVDp
zm1{WB|6UvjibM$@ZBR0lpT1C6ZF}bRdnwZr%b7>bFdMuV!Dz{1GKTx#qk#_x`Gt**
z4bX%dL-#m4<0T<#5OjoE5MK8lWxw{n*MfH at AzE8ob0stp5KzH-KI<JVz4q9?W at I#I
zu=rM#0a;6*-Gyv)Fk~ak9K!iJh`bf`R~~2z6E&L%5Pehpw;)FRS?cI3V~&h{y>_NV
zGOz?=U&DNpht3(8m at JC2vKH~8cmK_*h~b6hiN;3!nCVb0E+5|m+Ts?}i^WdK_|=CO
zbuv8y&8iA1Fa`#Z`KG3Y=m~}7+s at l>kAMHjOH}fs6gkhP&1l5 at Ai2Dq=%xkrp8^cp
zR=(C{=yz9i{Bvf1r5mpwF07i2iKpaHWl+gp{+Lv?lA2byfo{!j)A;Qj5Q|i<mR=pH
zqW8lzZu6XO(`CNrsulCrQv)7&5eVT^ix8XT8vd^3-;&wf+{7WkN(Vpk^a8k~K>-?S
z#{lZIC+{kz#%`-m-enyddUH at j<;-`x@`?>ZS>lz~sAXltYsl50^2_AZzY-UoU&_3Y
zmGiSW*3EF8oSMky)e#$^@lDEC=Vf$~s(%2}Mz^f<p8uj at i};guCsj;-mp&L>fx4OX
z-wtq5Tf5NdWuo~jBye5G*U=MlPlpPRt{N!sUi;mPQ<nS at Sgm5cSWLBece&o8;Evw8
z_8*_+uT*>V&rU_Lef(BK==o{IlHBpl!E)ml-rg61KN>biFBm9CT<fg*o>6JzzeyBR
z>woQY1=U2<S^vchkx|1cs>P18ffa|rHW#B=?t6Gzx>~ggiZt#IrWpJdxf^C**5eKH
zq98ACY7rFZ<^O+5>42k9#fPt7Enp36M36|hZ?P;^Zhp at 0X{onTUpa~+<a<ly?7Vhm
z^=j-${f`+f%GF>m6Hc3`{oRfRK}VhkBWByYY8_X4GyD|p&sE!2<;jmbyt3VkKlH5E
zFX6zAJSl!wl}&J;^Bk9$@%OxOX<CvUh)wYZ at M)}wdY<Cna)vgM3MqhW|IMGb=+k~X
zp;b-=t)0ZE!TV~+og1$+xKv)vuP1J;Rtw(F&Rl`7tgt&v3rnyI6FJt!`f6aB({4<p
zeqZ(3s3d<9p=H({*_dYMa)b%_ExwMvaKxX+<3E&I!M|3khyMSP0Az|-*vrcczv_&-
z5UT@!ZaDvVu-fGl`tx}JAK_u|o1t&Dz5&ylMG_|O=3gD3m2F)e?z%rPp0iXZSyb<k
zrtB_1+`GQ>wd0e*AG%fZSDKZ<3dfn8xJK4qs-+u|2N~69 at Tac^+?nqK+}Z|Z$|L`+
zMq^{+NkZsh{<n}Vu=U?qu&;j&F!m5zRy*eiIiCJ(jgq9O(o^PRQLIo#j8)t`{1mKE
za!r41O8DX at rR_m@w=&~B-28HxYZB4{bqU<068n>3l!hU|0x6_+BL6q8FY@!7iQ#}A
z!mrD>XpuN3a`$)^Hg<<&nTEMG#w;$3Qn_2DfpW*}NEheNC*R!82JR$_j0J{&30w(o
zZrJ&yI-210+7H~`lGVmT-&?<;%bX6F*&kkb9ylNWrRek39=b)mf58cmGr5La{BH#U
z<{3eYZ;Ie26*p2s=;t$k&+kf=<Rv96AB&Av>BBR>ze{%r{3UPJWg9UweRSJEX;a3=
zR`Klvhw_ID9K(6PKKa$(JIDmp?|w&#JoJyQ@|LsI1?~a;)!l-cb>%Z-7f<3=e!W*Q
z=HoE(-tNS44pk4Gv%I`KogL^!{?D_3&MSoWH|W#<?U{`SIpn6hwj%X1?ZGF$!w#eH
ztJmcCcgJ?^dc%I{#aza$`&Ig@=?)}Xg~uNRMh6$(OavcTcih1*-q)z1*36|ToAc2c
z{uyiy{&o89?|&{WL~qP|6}0u=j3`P}{5esgRDOJrad>;8(0Y65ao_jAm3}Rexo`JJ
zVy=@^fDaW3-lJWzx%hv3C$t1*Q~;{^Z|;YppO0loy(r0DO?=iy7ps=>gxt64s3_1)
zTFZK^ojZAkAV1+J_0pGigLTJalV1i(zYoSlRDT}|UXm;jd8SdOe|e%OMUleuqR+bf
zShgOi-@%K?rYjUToOm?ISw~WalWbsKmCW6sh1JC#&d~X)rmq44!AQ<@>;PlNi at N=<
zmH=SKD-;Y4^#8uX3U1GQ`b8)ba!=UU*!-X2g(5YK)^~0Ezx at NM6OYUhSLdMjj{?=&
zh6|0X;dHzP%D5pR&wk&3o8#9q$J3cuuqwd6kaVe_;E6~?Z1?76n==AcE;D<Bs1kLd
zTMe}TW-wmzp%3TlY5Z>f9lB|6C?dByu6~uKWIXNpNyRn(3MX^}_Di8)(fmJ;4?dG#
zp`f;UNv->`1~f3Sl*%D$3&pkpGcup%_ at c;%qPxQttDTQd7F~fyB-HAN$^$OU|M^}3
z2!_)JfUyWXr6txPOz~TWq>EKNKd<4_FvZhPhqIdStr at _204tx2K;3Bg-w_R at 0d_t%
zSVpKO^Ali$2VdQ~>Mh<>YH$RyWQ#P at ME)K6KG07`s=z=GLBVE+InU4Jn$r&ED8>Kh
zM<7=lsRGE?|9%8?->UJ~Z`^oAJr9IDylF)tZaoK{;RO_QA0Q76clg%?LbVhw-SK((
z`LN6W?<c`ofLYbBF(^<nwCn`5lwu%r%vI?8dHr}%+kfwU4(dv((EnU9;-HkVHije`
zL&pnFy at p)9jQ?IB<gzk^PgZ`hG2vn&Wj}Wg at C9{TQcI3geEEN76mi|4g|{6tgntbo
zgyJpkyXD|kd!8c%sTGO=kyElcz#bDc`3_zW<Th_M+Qi#2X_hql%*Av)7yqDu9W1t>
z)%W`K(_J!DObaxyd^SBMGF1PJBA8&j)Z)oe*SdLQu84zr6IM>T>@6pF;jAny5ULH0
z*&(_)5(?-NW=AgXGF444!mWskjjiPK5?-hW^N3emT)g)7k19yRm7ETm8+>U3dO!wA
z#@EOV%BGJW^~ql|!Tt<(CvZqXp-jmG+!LP6Nzh|LIh+8!LlMi0Xq#AK;?f294i<yU
zH}f3f>QN{L!Se9s!~`)7pm_p){V4b$*#lDo@)|^YK#C-3ePHkI9-sIWRrKZ8!ND$&
z`^bgq0ke(=GgLKhT|pdEneXZ-{KhL+^|ljFK$>`2t%qPI1-P(<*{D*^!41%+4E at JR
zv6dMJaBMKzr at 5o!26QT>SAp4u^`7q0A}tUn^52|pTNDVE9|k at ki*ZqQ at 1G9vB_ZeC
zU#*^i`vD97E&)cV?l*4&4ertpG%zrmvoa*z+9x)TgrOT*C}!n9h}>=~CPWE5XqSiB
zyn2nqy^W1R_6bfXJjHk#o)h`Qn9KO*5&K$MSrJJtg7*e6^$puQQXK9M8n+Qw046Vl
zJMknSt3t~(AN?ctix~)E&9Q7qn68Apll*9~K{`o*n}&PcZ7;76z}PusIr{#)aXF|u
z28XIAf?mNw0E(#K<zjQt$+C#M44i|qPWD9re?EEwNC`Rb0)O4P7ekNX at Pwn3+BG5o
zgkj8UuuH+N1eP#Hgs4$p(21zqlUaKe+ at DyPF^@JIT!w(;r%#^(RQ`|v_!8c9^_Nvs
ze}jpQPq7`8ahgOZB52?5LG=tir^V`BAGYtTjX$_WJ*OpRcvhA??i?>~R5w0?T?1=$
zTjsHiynJS5%@to*r0`qNnD}bwOjQX6s+p-Q5pRss&@(HBC%hA!b<$}csBzKGO~({M
z6^=azMk=%ziQc5E2he^2!*iV5Q?5;LPTD*KJ02hkaK_ubBG=);Lu<HbZOzxYUwoiX
zg?3zwMhNOf9)+;>7s~`v`)$wbr7|o5o*b5d`OH7xC&fbdI<l(eLFW{oXy8Qrt)^p>
zybb@==pBnBLAKY4tVU#m-=TkLsO{Z&dI8T4&P-6Cq*n|_vGPU~lO=|dB~#{XOnVZc
zxK$RKV)3E0?%uFZQAd1!;c;`M#oKVOVC$vIYIfn4GecJrZ at NuG*mclN at Zp>hvylo$
zw>hcqXV(_KHWHTM?_bm9#=W>mD}x#5jJu~Mo&AbFe8H3M^zT>d)`4J>;TnG6a2fGB
zM37uF1=fHWS9c;{9`9cO at X7SC_T4+kG`$UdZ90lZOxf4bQBZeLGVa497g&1>I>qoG
z=d|^_RBqq7Q&m=`64}WR26=@WCkUsv;u-<e&5-ftydIGWf}Z4JU`s@|VMEXV-v0rh
zkMS<_{mZnu&VQ1Tc(aLYB3%g`hhV;+$J{-q3-}pD#KoagyanXl#B`OfP?N$w07O~#
z)7=f)k(iSXModL)el*SSknzRr4XI at MVI%lUwNFw;KuvM6(7BD>-3SiIO^im+($Z2#
zH}c{6V at CBdgj;kSdY3Mhe?gl~ww8&InRi({Z6PsHXBW~bq0dMN{i(`R$RZnD!{~ap
zBkwS3jf?6v`wb=6K|Vs5i410hCCh-rBl=HMK at -V0b+&}SEoDXHG~C at sVLm4_S(8Sg
zD?be3H2Fe0$J^R8O5&+DEQOpY4{}+{NJ-*~7^=t>HDs2rLCh^ut3Vau$J>S?k_;Ku
z)On#b<(&?cT^coUIzMpxmGM4@=17*+<Y{IF7#K*o(I1CF1W$J#I?i+nLD8u)taJn-
zxbreZ75fkqy1`J-8k}72<>9N~`v6E19JH?TMXrdxsJBz<IFjhy%}stwEG)(cJNuc_
zB5$|0wsJN=Gd(S2IJPLzc~VbvYM+S$#MB(x53If9WN^^4rH;Vx`N#z9mqJMZ31zwA
zJISr5$;0Adqu}^->?urM#KQ8-pTZw;hZ%OaKpLYm?XdbJ`n)Jj6R|WMEL=vt5ZaGW
zO=%*&w3Z*XrDM9l>(kKsdBD~Klzl^50eS{e6>#8V^?j1ux1cDLF9AK%9n&LhO#z9s
z1b>FyzO;cbWNJXaE$oa6;UjKda5W?EYUjQM>cj=f4KYoBnUgP`-U&Bm54LVVt9^v#
z#^NrJa=H#qkc9LoSbs61L9%_5j-YMvxHvA>si~AiJldvDkWaLyanUQi=8a%=N*UKp
z;`^+SV$+t($#EKq19H{kbA3(CQ{PeFJ;TB{)r?eA3Ey6d3@;D4VB{f6+{y5ax|__s
zjo8>7_sn$gOfNxj_PY(y*%RI>bzoYOd!q2h?1}4`=pT~wJTCe3=rWgD0Uu3 at tgI}b
zkD$bjTtq+GKphYg5oOOhtF%r_`ak0n)|~b4vo+!!iS?K at ac^m-3ROx<Pxptm8R`?A
zFb*mgTqX3imMV|JSa8q0gy?h&^!hdDO))X(sPOO)zMB(zC6!9;vW0}pQRi at gedO8*
z3Mf!A*t8ObY07{*M~(`0<h{2fxgYio at kGl{>`h?0mdq4*!U%S^QuovtajlcM^AfI{
z7)^OjhRTyE!)|9GvPWO~c=1NEgJ|3*M*Wiy`iK2uPoB9`V1nkx${M;1lE|o_umcI2
z*~2P7T1>os4|7hi5=4b;nxF!x4E<_{;xTOL50q4rTq<PbC~u2eV3UPiBk!ohMpJ}Q
zy?Bt2kpD6Ni;`BSq4ottKcQ*fIb0!goSNY!8Lb8a>!*M at 5bk`n7b5)Iw&U6V6uIpB
z{r$UtlLnP|iQ at bxxL^s*Um3{Dl|hi-ieMJheE8^5o}k|aVvd?|0p&d&>y!d7I3l>z
z8 at M<Pra}lOKfme4vC9LiIhi1SdU-kKl}vr)EwqFN-NhGE^<B`cTqMz-`cV1Y<1GnR
z1puWjJ?BiuqU&Hytb<(o1xsa;78KKww?0_TT99Kfm~J|X8dBfKJ8gWXTYz;fOG-uw
zp`NkCWs+tz+w<YTR*k-FL*dz-J-QP6=bas*!G39PCg~_>AjdPch!3L#vc-V&92_bM
z+}fS9{48(LYUtZU!6zR~L)j7gxQ-X|cpb;ZtxC3lBA(0z+I^B5&bahyx&sE$^Ey#8
zs_rvC)@{m!KbVS2HB56kM?>UHsBV&Mefz>Co4Het!Yle=5}gtP%Xp8Y=s#opEa!0D
zBFDH?=+XEfH9b15N_KOgaEb8>P|#?)hG`$6>3DQW)vlOZ=hCEFc+mOd0##(6A{VB;
zi$UxKcs&Atzl9iN5YXv!iVwhhN71DK=@(o3U(uT;GS81A96ZU0=e6SnhAfKb&Z(0R
z{qQ!7M%71lOwvUE5IY~!d};Bc6^Kpklr~huqixYNkr0AydK1mCC<zh0w*l(&HmsrM
z#$Juo2p}b%2pt0*8o_lippzh)=ELueE=g$KzG5oi0qmL0qMwWWk?2ePz^hl#ca^Gu
zt+0=t+MyQCq;ny6Vl^U=MSQY^9!4Xqq2NHiK2|LP+7XNXXZon#!X*jBB~F|d7xks>
z45Rypzjx)lYzl+#QTW><gugs!(8lDGaOhp(v&4S>{CU&zsb#!^ONbWYS$euaj<fN7
z`xK>%X8rf)&?|3x*6p^0Z#jTNd4)LN3bVLywanp}Az9)I`}G00Qx9m>Y0>FzH%Ln6
zK1oWFd=(yK_+zWS6f2C|N}B at QwA72Q*vfLJ9q6h{l8%~MIbvrb$$=u~Fv3qN5fkqn
z5f(;}ZssAQhM^!OZ3(71Fo%*w{p8L8qR$PN9s at W2CSo#A7SVa~ql_WYkD;K+O<W^~
zZO2>8;Va-9nBj#9{Z};;h9Gw8Da5LA!6w-{2KNGkG|?vg43SIH7E4NBLFjqw9JGiZ
zy=#vAFAvf at I#t~|Vg_tdl5Sd6B`ZImIKUWjhbl)v2E4cd%?S;@T=erV^O=0*d7lRc
zsQh5JqE_v~_G~Q?Y{piA*evIF;rY2M*_bxkMX+&;GiT2QK1IP&BP?_VF%c_{QUyZG
z5<OGwVZjm!o%tP1Bpa7vkwyYHAoMNWU)&~$aTw6GRb)mF at cDctBl2&JrUsifoZE!w
zWaYrLgoA_tZvQSm(!y8Yz`$Vkf&E2q2z)V?sE;0aqJw>jDA3EuPra-=_MzWJG{op+
z4DZiJfcxp?s=j33ky|}|N<tEH6T}MD=J+~tEEI)s`E%g68%4`>G~w8LwwBo4&)c44
z2HsF%*%zDpdT=iTDMi0u&7Bz8Sal6ji8leD_v)6TEamKEyQWPs=q5;jp1*nXCJ6ZS
z(m9X6Pw>Gw-v4<sjal!{xw!L=QKKR4*-VDU>E|8%Xo;R|!+=LcL_BbrPC61Nkw}Q8
zO<f3DtdzfFP5OqOTo`=>I6Vm;)6qSm)2G!=CTF~FSB0<lCa$HQ#W}DcGa21-Thug(
zmbCj4mUyrQj0_FQ4s9CJ5ahNi-|OpGI0JlPCDp1jNQziuUv7Zo!-3oB`tMiOY<)2K
zkzp3y7^Z?LU6-Ku*=RL#m-B=xPlH@;L>po9tMV<H{oQl4;g8Lr<H%<-H1nvOLmcgK
zf>B8JKTNVS1eLcI^lRP*2x(x6Ky>(d?h}m|opS&h_i2u at 5=0{v_y&&`;(EMxI}P?J
zKp(m4<M%iIyehH$sCa*y+PVHG?Rl$_ at bh?AWMEDD?p-Re9y_{heo4o}<NV;sC%3$R
z(0#dYp1!}CWb at 1ZvG(({G-o%r`w&|%^QyjH at eMBLm5M)ENnNzY5%l#r33*<8eyoSZ
z`?y3=FK-c9Dlr at _Iog^cazIUh6`B6|6Yd~JCw_<F<}&hZ>ZYPb1z)1UY?W?m%hCye
zWoWoiaiqQ$e`Z?Jr$OD=$_WS-x;)Ce0k(gp$96BkHku-qraZ=*q5F at 98eZ0HyD7!R
zrIyK4OmthdvE{Sdkl=Cvq)u!-IVBE6n0H50x(*{~8}3iJq5?P|3HY%0on&XzFheil
zh8-lOO<B#v2Y!&~lnUW0xUQL2D3Qd4_E!_agd({qvliN!<KKp*meV$2U4#hpRqh0h
zFzL)<C0oupvVKaJn9^*t$tOlyKitU}*$BLI=a!LZNK^0$4xCKV;szoYp=T^e`F(>L
zd$m(L(f)!`&mzs at B_FoOM5qUClt-eqxVhsrn&(>Y8I<b=-JZB+3TZZT60%)gJ{5_G
zN2vv(D&6zPRn*k5Uy3bqp^JfrgKDnE?j7XHx(C<@Ei|TB5KEkw^%A%G#_K$J8>;Cp
zOF%sfQy2;bv=*o8Ylf#|D4w>s{r*IMm&BV|Lkvu3iL@}}ScU03;%_Ro$+#_Ryf{pU
zphdZ85aIl?7;vb=JmvF+BScXl9qgr0-2r3fiwlC>t!WIDlc4Yb-s20P$vL=-$PI&{
z%`g%u1*r^DVQ)Feec8S^j+~${jgiMuX@$2aP4&HyHx#7H1+S4(-AthslJ8t=TqK=0
z4P|9W3n^VG^Fk-ULKV%UExD6!cJ~p(W^_VA``Am9f at uktAtE(Q{!%m0(Zfmgfzj;|
zWv!jD(Uh;zM-}VZ!LPQjeUX0wO6muhL?Cq at R6cc6hGj@ulX_ZTIFKLjSRalvrh)sa
zfK!RE3evv$1i|$)63$6A*|BQa7 at Q5CY<FTR)E)k>6Z at O*AzM!nD5^6!*Gq*V3&=|H
zST|8!i^Z`F&T#>TH?OmvsbMFHT+>;Nt<n at 1n>uU6NA{7fLv=3qgTriO(HZ$WLWfhp
zk2R_i8?8MLp#%Poh}U0)m}Lu`u|u;H^mH&6?xtcqQlJuLV9`cO)MkF16y(oE#8c8K
zi4<PD7J5siJVwLuyz`H<1LDzg<i0-XO`N27+juYEIMJz{&LW@`O}lZLqLlm>4`fIW
zzlka~dw~y0A+toixlgMhJ`eY`1ha{^-8o7Qz8({8=7>||C|n{yjX5fRPPqzaL_<p_
zM?vFv{zR{+Ac!259a`x5fJx06-IG;g5P6C5{H5Su(ccEV!A#%kz4x<7HZ&)_MR+V)
z5*X6<wKWahM)=&Z>g<XdZO at TXl_1mb6Lo4b&CSi&>*qLYrXL1R8vDaln1$ktW$l-U
zOY%CQx3n%|owwp#nMBWzL^s<^U*;nTQRDK0i&CLn+B9T|@WsTOyQB575S{+y<%!eH
zUpa1h*HLh{a-Y^w^ca^xhEJ*SA!{hciMk9gP$36Und#zf47>@=xIX0yF4s8JlU53O
zfu-HiR@=c7KKa-8lM2$5Ffl+ZQ4(uy?vMD)G%tkao*8fZIwi?s-I{};QZ-P`KJ4%#
z*3!CR(lD+iqaQw;*kZeqrx2lDQi<%P<bTNo#v6UKd>2hk=|~=oJ{D$sm#vI_jx!}s
z|Dg8c8ZC4s!ooSo+f55;y|vh+;!<S?494Mv)@YLQ7>{nsm|7(qq+d=Nm4*WH&H41^
zGWRhlx>IFdw%$VZPPK({nd}4DDvi6UY*H)Md at YbfZAdS3JyT|xxz3Qz(&`{v;11(a
zd>M1^*(khpNS{TIYj_X+Y%(tOc%8}4?rvWH?r7hAKY_qQ9E(IDnq5<Jafp*#Nsr3e
za)=NWU%aS%!e2-UHNsdBa+Yr)k<(~(N=-nH7)9L|b9`!Fut7$%IKb8aHKpBT!EauB
z0VG)pJ7MH2FY&xnyHBfsv3SnaWa|uBN>T4jwsSIgi(lx~14Chc5xj%&zycNXM@&P>
z2N|8>G$T1t%i$$o2Zkh at TjO8^$5?;LRu&<$x4UZ=wEe-9YVi{l;?O6IpAqCIfpx)z
zwE#o%#qFyOtl+!)?J__Bi`=^&JFmpJI5J}1Qg_6Ss0AkzLue3Qs|@;c2-fv8?r>H<
zvZcAg0^FN!I<EZbjjgRvs?J7L`)(wu?>o=EM07Af%6xIZKT~hxaicUJE?L>HD>oQH
zkRvE5c^mA%;W_{pHJR%TY&YKky-5Yh$;k;gLPaV1$*()dNW8DCAydm7RWJSD-mRD_
zr1OPiONq#z8bfz?ZR`&h4pdoc_On_-8Pb3I(vIPf?~QEwqae712_vc<ul}WlmG at l?
zX*U1Ja^c^{G{f1?P6(yd6|S^_=6 at fA?@imMcEmgtgSuuRQTfOmTFv&Kf&>{C%lKUj
z`A2|J^!}99yIUaUXujNcp&KX=&<=2pfB!4$VU~tic8a9c<25CFXx>%e-g3Z>+IB;|
zSff+)Q44tPvJ*xq=BDx!3E}1%z9}RAKqE6pv^&hR4=9tLZ$Y2 at nSQnZuB&9u?~U#4
z7LG*=N{tgLFOi-pPbFONX3B#&pU^B9<K8h1pt9t;mQ__fW>kF>Fj=`ZK;_FY{WWL~
zkv{b0%M<;_3^{LD*nezoGsd>Jv^YWq=vsJ6(IET^t)swGFe^efL3s**TE+MRSVTzh
z`#T}(v*hg8T1&NCBr3pubWQr)KG;8fwb-+IC&2~b3qI4D;hqz|OeIf*bS200LaSgz
z;nkj|bAqO!YxvV<gu6d9Rqf9Lv=Uqw at +3FcQR9<Mks+qRYYK5rR{>MvylBxEEMHhi
zXy|l6tt>+dA>$4(VsN3YDlflq$dXBN9ab)s6^3f07^3ud6WZF^AyhliU&d220?*?N
z6pmT}w9_a#)39x`YUzo}&t3(W&zHt|-QWnh2gZQRl3Zs?2m;io8vG9!-rrf0?DTp<
zGP=fwSp(G`Njb=NB%5{ZF;a?;*l}%B(4ppQClJPQbF#Bz1J<`5qkwiy;;)%+2Tn>6
z?_44tK70tix(YRL6;?ym-d%qKM2)tagtZ_+1fv;ckQ9U8q-&j<$lm^l*}ccYI1q>M
z#dTfJ9{?mo5IO|0j3Nm!G2Okrbcr8f98@(mBW*J1sM**W;eW1QZ-sQFN!xAMVQ at nb
zTV!vF-E#xWDrrT<K<HsP_%DK!3^n2 at G>(ZCRV?wo)<RdS$c&)14Fe?)Ib5&=se=}A
z90%{lkp<U)Y+Dh&3c*;XqSVCT*?oL`X1nr%EBb+$a}(<EHpeJ_#fo`=3V<>WfxC~M
zj|dGETUL_DPn++gdDLUjjwK*;;);R^GUp`vF|a>J1AI#$Hmgo%4T$cBMxD37S1K~`
z4f;>6DbSwss=>Wl=FZ9p*sH<kM_C&($$bT4;v at _FQSgt<$i>`rVKk+4rGFq6`IvF<
z8?@k{R^8H)%n`n`{yiSO65S2aD01mEdb*E(!X+a2rq1o9%C at kVtjWfyRNqeY#kh7X
znRxhzmE+uqK&-B-t)1ld!0FSB2ucDjq{L*w^%(QnabQ at 2LzeejX9_yal3fG3iwcb(
z?21Easa)=~$U-#$DOKHm0+Lv!>6~>G)6?`X2i>d*$x>aPoJ4ofuSV3f5ASzkd$-hV
zFJd+BbHqDCyGfI76v@%4es6<b$#5|#T2*O5vbDU<C at 4T8Rf!l!Qb at uQvCK>^P)q38
zg(X!%;`Z=cR$3H#y-$hg(otFLBl}ctQh*P*NWx-6QTF+;o1L{<0x`hr;$lr_07&R-
z(MB7 at zduEAg7opU%OULFpfKZL28+5#b&%W9E`^1K0oOO4WG9 at M7Sfn+^rm6V&z#8s
zD|<p!8M~m)JJ4Q%fMwVPz-EIyFUomZSO<7MOKWTT_W>6nH4?p at n)0xTNK7|eo-+#C
zf#gi0C$ge?!6X#gsq^#mk>V!PKw;uaDJ?C<=S_V8jOSc;>BV#HLv0^FQV?%kAv=pi
zn&5lC`b_1GjmjjNx9qR~*L_J?o1G1B$^KA?_U2-UiA2m08fhr{|7N?taPo3n+0V_^
z at rtWHZXOM8H1%R)nteBP2kBDAnM&UA<U5b*QE(b-B=Llj(>G~S6P?RpcOW7a=!+x~
zFhAKAsk)-5Y2>)l9CW<$>seO~sg?o at 9mV?k*QgtJod6(l`t)@|=$6wj+`A`_9^Lcv
z!}{^v^YRi+c;yX|!zH<<BTuBV<M>1?$apW^mISV01!@Z at uZ7QIo{(6$fPVQ-hYehQ
z3dvJVb_{ZIbB)Rh$&1Xic at ez2X(0hg$2HzFhAD++erbSlTMDzYpWuHva-#OZWlf at K
zUGMH1CK3`7DvEeDdJgW7)NN>4`rX=xpQb@(s2xTK32riOgT_`?EH7mbwY48O<W|5f
zNiCABiN{~Qf(s*{D)W)GEjLAj_oSAVj*Nr=b3xc|`rRmhP#dcp!N|)n=){h;SLz&K
z5#GkmJefjo&=oTJ3}zC5Y at 3FvtP*r~Xn4q&fP5uWh?VgQX)~nkg`&Yx#+2wz2O}Jv
zLasigB<X;G(_Po3SbWYWhtYg#D0MAV at Z@v$7wXb+IbOt5(IB7Mr<=SLRc~loq{}BR
zKq4GbZ+O#HWRx^M_OhDB6pMF$A?>+WZpy;f*A#24I0#`w#%YSq8^1!VF3nTEw9b0G
zx4x$wPzx at +(r!vV=1k2qyu9^?I`_jT*W>o-k{fCkXG at zLEvs*a72cg#%glOc!iu3_
z`(+(<$Fu3- at zLz@`|sI~BWY=I8g6AY at -BBSUPsjX*<AiYsno_%YInUWbm&mQ?d>2d
zru~W>NeZ~T#FrYIW8DY|wa1T4OiaA1d8XJw at u3<?XZGN5Z(Ss)n_M|W-x at 6Wr67Lw
zTA?a78)bOXpGh-?cTzvGxKn^`_aw2$&s6%^Q{UC5w8;c@^!4-gEU+ACKpbf)wIad>
zat-exPg at bnX&78>0yvkW&Qzbqxs&q`r{0A!f?k3{B2R{?9Y2G2)>xyPrl at D6-2`DO
zm3*!qhMZzZri>lcB|LY`zcp9o53O at OIu`-QzFr1wgzCk924 at 9MD(U=S7ZIT>o0e77
zA$lIhZ>*t$O{O2z at gPM?bgON}9}$c)x+gz+q#=vl^=9zB16fU6=jmz02f<G8jb_(m
zhs+y=a5d0hunr_XrdM7YFSQR-S*_*M#AqtUx)EO??FJKgJx8ZwN($b at 1Q?u<fm<GO
zkY&I^7$a-!rJku2qazt|i!rxwiO%aS#1mw<)?6-oDXm{v<b*tZXe49Ny$yYBKH=JE
zx(JdE4qQ{No&?Kz<ytc6Z8pfrr6(#`u`4RFUg2S7WjuQuMZbGe+24CdhEVoH!BpS0
zEw^Y;fTlC;qcAl_dU_+eAp`fsSN6+F`<KJ1 at PxuqWV@BC8CH3D^v}!2<C(<Z-zHB!
zvc0Q2RK-rcwGHmyrfdvu9-h25(X)HE at s}c<?A<;Jo#TTW6YNdD)&nPJWC_2=U87Xo
z$&e at 68E1A`3j}(=ldIJcZ$Dks)k}YBGsLu5vp$b^#MaADSor2?7+jLgHvslDa&Dsz
zfmKc-x3#eK at 827y0lm|etC)_#Ire1r2fZg*;mPQpZA$P%o1}Qnl&7_pV<veDWsFd!
zJr2BVN~s1e#z5a5KeBJ%$-N>I?xl62B(wontBD0YYyz9|d1D%Xj3x!XyZn$37|Mnc
zZG5;SRoTnvBFiN&S6W9bqlishy<O&ptp9JJLt;Wg)YPF738Eg|GZ$sYaXFw$5<y<M
zwYy87!7eS$xb!mW1V(c^xr3A)=Otby3mq^4W%q~4JzQdhKDW{soNEiUpAdoiHQnL;
z<5 at wxA270?%*7BmfO=J(v<?DMU^>LbeDOlM+MDN~6lK@(O~P${nD5Wk(m<$+;7|xN
zXKUqCs2e&4bFhbdO@^q at 1Zu24U>^KI-ZeSCb(-*celR1JEm|T+y0DN-mr9ku)61$q
z&uFlPgRSqv?fjF*mX;(Oe(Uvn71VL>2CL9&HuZ|9K0E!4LEMyb9dzD&FGRw8hUGz0
zQh&d>ZR&fPAGSdrTzA%IW+Rg1NhBUy6LlnQjg_oAmkVGt-!}ePUGK|sYjFR3QpciV
z&TyO2#(#c^r%i)*_iK7Je)UUBkw900#XbBH6z3-FHAzmL6CmmER_1v!L at IHf--l<P
zEe8_pG*XE%`NywGvB=2okVU?tZ{P_EC6%Vp?Q8%zr(Is%yeWE$uUI9}hj at a9a&`xy
z7bYixqg>a<y0C<1rKZxg4s5uQ`(q+IpvhtP1by3B_Mxc^6-nHYnyG1O(pmL>J|c7K
zYnHj?-OmVXb8?#5$q8^s2^}I1hKv}wHN=ujI2j?To<jC=Ke2?5rvK*7U1;x}$_=FP
zx;`6uA+MYY6In!*ek$M1=@Z&M^VzdU-Gu4tmnY<lOtF$8R=0h82HwBjhw4X~>3O#s
zA<E|g-)1mb03n$s^P`uh*q)vqux7gy at 2aI{SYw0rHatXjBJ>n#6 at 4Wil6(%oP;)fZ
zbbnBmr2OsM3i(3A(-*mLA3n-B$GCK24UimuGx5^+*ELRnVW3PaQ`n4Bt_oPXUiMDZ
zg@}f1ld at e-QRAc4TbtH-Prksyel-TV#r>{}=9FZ}<ULj?KQhEZU-#e*x9`Sx3FY88
zjJT+)JE&>SFNB*Xp!^V_nk&Rm#8kwAgX<2MsKpd6lS=eaSq*WG0BZ2rYZ;W$&4F{6
z-(W1fTyAbo9TT65V?;F+Gdj<nnxM}R&nHUH;=Us1mL-I{e*HSm8<-K!!(c%$8F4BX
ze#LoxXJ-fM7UmZn?R>6AM*XS$CM&C}Wx2m;CGwmQ at kPV$OZR|RrEQQ)=L+ckH28tl
z)zv{Z9dL$n=E;X>ooO8UJ_+`}^z!yL5)#IB(iZSXr9OU)8q6MunIlBW{g|7ZTUdy4
zqj|!2Sr_RGF&i|3)ua+;#Yg6??`|!4sfQi%qcdWNA32ARxUN*eSI0ipIRNW>4np_Q
zihlgLIEMHJ=s~?kfqJLy at m6*9gulVf^I45LNZ)G8I%Oa<rt>y^Qux*yiijt$|I;=v
zY`cy#66&+{TRJ&o;uR|dn-e(7J!sZ_CTDiWKCcv=LD@=lS>W0nXiOqqkrKoyH>-yj
zo%zJYlRI2GKlEbbyik7#5hx792k`7mH&PM7dGSCMz;O|V(;sqeBFE&35f)eoUzyZ(
z$d3RBA?zHEFd^Yuy1(HduiBx`s|R at WGwBtv_B&^%I24I5+^0#n+E>8u?o1Ic?rke6
z9IFP$r%Q{`xl-72pHA2a$=iEcI1%wCU<jq7txd(jXJ&?o at 9kfM5~q6=p?5<#@pDpB
zo<1u_U%`p%7ntM;{P82zWJbv0Hx<G7Z^M9ms}>(5;o-A{XRY}{xZ|a*O||&5qt!DN
znMVgseZqXWAf=YlqajAAERUn~i23*BoiOkGp+~?MH?I;$--2*g!m)3*@Q<(9E8xe*
zxVd%`eJuv3<(H-zhO9>m7A2!q!e3g|c%A&Nt7g={`r})jG?^qfH<36V+S(iwx4;?+
zh`m8M4VT|A(5brd=`3BC(?l-j{fj}ktMM4r=IL)~XgXVBjm|>W88l5k8%zic?umXb
z5x$N&3xy;V&mh4txh5tuAhwL#kPn57WeG<;M7y!n^ML&$znoN|x$jv+Rk=MBNd?%Y
zK!++~hS1wN%n1APS87()8>Uy*7f4TkWYyvq6wK9oXo)&`(*l#9{DZR^Fwg7}hmg1T
z5PIb`R##NQaxRk(;O?bDj&Z|V^h_vYc~4$m9&_B6G$CBf;WZRv+Ww#OcT^k>wMgDD
z1fcVEpN1Now4 at D`wI47|;S5gSPS%H8^h-J`Qv<Mx0_XhPc)Q-bHKecSn3DM?3nM-U
zj?cmSe`sOFmx_s*CnBG5u3xQ~!~N_#y?Zac9(Le_=xDUP#BoohgE_YEbZtnTkOZ}H
zY$H5qMB{fOEWMd-SuTKVYl{*kL{hK#aithIYg+ulsJrw&G%K(&=US=Qwa=P*f~bd&
zGRF()AHYW{aYxJV+O=!u=1d4k8dRM!G>1hGcFw at 56SGIQQn&!W%DGtMxl*8WKH at Xt
zbzypfNm#d?mO1IqJa6P%bc<&a at iinS=>pvVmPCT?^iuuc(y}29ctWEJ<${j_=uRzh
z<aRO_y|^c5LyI{DD64wg;lTk1i&;2llLvnh^y~RRAQ12xs|Ti=qQFCecjFz^j&Y7r
zOs7-j!khW2#A2;M)q+jy)XEIKPGo6R$#gKoC&Q2sO`n}HPb^`ENT(s!d6pu!9KZ+%
z|9+9i at ioZV0?v04?cn61Gtr86<FSb^BJk+<Ju9XfrVZ*3YtEHm-+Xwb9UsoT-82_Z
zO3BPg5|z((YEndX!=l9uqc)?P9CsuP(hE}!Kx-!nw~9A(^$O(?dL@*p3mLJ`Bz~QY
zJ&N}Fvz#;Wdwz;y_4`AuM*&;?3))E!uSFPOAyV3qX>+7)*&g$TTJ#aL1|XI6;n~R5
z at pma6L%0MWo;*1HAx7?Y$h;ZPh at hZg?11N3m7an=?FUrbN)?K#^5$3Zw3PjO7A`LQ
z0jgPF;i5{GuUd}i5i!Q>tc+HYI%Os&XFml~$5IHI<~ly2TnMEKZ>eonxW2<le_%%E
zA9QqZ!<QEfWbKR`v{J3IluvT2ghF_T--UDhA|i?5r>X at r?}Jzgm?E>T>cJ=IDV9on
zV<`W`no7*HQ45}<ynQ}jm==Ap9E at vZx467Co+(_NU;xz<uy12W)IU0eO11fsM at RkP
zyXfjFASVlqoNTd02Q7bAV#}0elVeW$RKmJkV#71dOY}3brn7>l%aHwvQ~W|gbhpk5
zKC*relBV2AbD10~0uZWd%E#!*S(H5xJe_g){I-Cr at Kme!rlE&3Kwzqck=|`F!CdU*
zN`}B9^mM*%(XsTLDV at rS09bc?uhZU~k;UHN&i`#Pcx;JIZL?a+;qgX_wN>W)beWsj
z6>z<xzCEUwZ$D6b+f4?u&q!sWCM1ZXZJEyU_`R~h;pnpch7i>Q#qEY+Zq$3lQz90n
z{x`j5pC9ckXq~->KPuY3HW6ezlfNBNBBE<)za38?b^LkGF)-`DVipp^4bvbB)A_$*
zR`6sIiBXa at NtL~u&wzAfnK<^_qC|J2O~kdCTiN$0`C3e$|HnU=U1Knzg~xEz)DKTQ
z^rOh`tD|3JJ<vM(mAC2{v at MEY3trg_QOV7aa&fZ2e1}~*_;@P#VB40>@ZL_p7Wr{y
zhxfmo;bUhf+I~@bjr=5ov)~kPN<mQsZbPKx<ni(GtQVZfhTH12nesU{Aom4SeRLF%
zZs50B+YRAi&Y#6}EAK5lyE{oZe!86QF}-uF(3mt^uZ at vm#axn7w=t;%D(b`A3&({@
zRgsszQ7=N{DM!>HBxeYAf3p?X&p{&jU8tQvR5wgD&ak<FotL*@;2j-v{vjBC66vGM
zA6$?updj%Lv|Ua>Gcqvbh~ha at Qq4Mlx$0@%81fIq5^A%|<@T7WeK=ogv+Lib{FO8a
zEW9dd2&KjC=;-$S``1Hgm+|$wmDK;eh6;zw2m0x%g`9b2k3vAZ&kNDl6UX$wk2(Yz
zB%dy at dn>6glaTuA at e2s}czGr9{x0H%h8^RXGq0Z4RUcZ_-4Rw)v{tsY3A_O?3(TmB
z1|TsG8k_YQSy?H7!s}d8ft|@<*ImefJRg<DBO>ytr{|LHL9b|B<@Cx58E?`AYtJAd
z++*-p8x at e(LFCNRDW6-{VCmD-(*x1ry|iag!QFM2-t{*S>ZVCCy!V)0q6yj?&d<J|
z=C?@~4s&{2Rz^%tu7SFz<ERlR`_tO22lfo_tJYOFpGt+=GyMQ(eAZA-8=1C2P!hsl
z(!tsW9b8W>!2FJSOjN50uY$4mj%U`=uoYIs<~<V|o2`{qaeU!|sTTI`>S)9Uyg1k9
z2X*w$8iCI7^%dD<E#{2C&!9qVIvM6imZGl)yfi`l`8nn(?IHSE=`H#Ta=*}z+S}da
z7N+WQ5f}Kx0*Yy-Cf`f72u=DKG at O2;$VmHQWI#O{xnIBbIFu;;adZ5{La~sQ=nadl
z;<!cP&pDjaQ50nD)7RGLN9xwAk5_m5qn_XSwNZW?fP4MTjrAzl<;&DiRf*(qf03D+
zyYPfEAa0SIl1b7vW$*;Hwzdadtw3G{UxizM+yS|S95kQ7ZNFaqT%VvEdsA3wUUk#L
z&d$!)S0ci;-d|E!*d26yF#prR2Vnl&Xs3H~IB}-{4^KW8i$?B1Tg}nYvF%J8{VsPq
z65s4}w`mBF<>tPg+6{ofBK-th64g;+*-Ky+a(8X~9&~e4X}iE6Nq3!|H%XR;i^ZcB
zvO{kRpv1s-Y7{0|@`?Irkn?YHdS~uJK}=N#P60sJ=cLVaym#;2`;t at F64GUFFVoS3
zZ<m^pZ9Wq-^MgJx4m((#212NTuC97zcz8Huna(BPSvfJSJ5J2ZVrEsESR+ax$$#)R
z^2 at X{8--@=1kk<R`C3FT6E=*q6GBe%7vL}T*EAt_=6CO3U?|axvt?3Rt5YG+M8_&0
z72Yq{lWPexA{J>F$x(~?qWr6(Be?OX>UrG)`dEcyrn$MLgO|52LpfM!P5zA8*7kOy
z&fp(uhoJ2~X_-0 at 6uNO0Q!_YkzXK9IY$FQk!+m}3 at D6~xVqO^92Trj`2T*hqJ4nN=
z at b2BaY0MRAJ|H>13z5X9Pd!Aju#5xh-G4g_h3}qvkds48NbC+BLQhR=R{tywJK^`@
z!p883uWIWIKy8IE33EFre4Bw-8!v&(wuZVRl7e*^!aKpoV<lk+c!w`0_fx_4JvRxj
zzv;o}Sjx&a70lV5!d?*d+n59lEPF%LG*d_-mF7dgH at l4BdxjX|r|nM0#t%oXKp?_r
z!xMw2-h+PH%`KLGknE at GrXgVSCv+ZooalZqlVc~tC_W=kQt|vb8%l5(=}O<#Dk2V7
zb0CcZAVLGz`CKC}Ay*+qfX8yUT1Df`LPZRaP4x%am()HS68e9tq7}R#rT1JeSQke~
zS$)zr=%{au^%w-5<- at OSgO2|Mk1_cl{@f#_OiX*Cpe!wY7hr=8yK%+JT?b(Zf695V
zzN~ey3zCR!4z_OqY#}k~s)L;l(B2WCc~Q9jnFkZO3Oa7R7Y6$Jkz%nNgZqX}ud^eo
zO<_RVcwd7>c{+mpWQ0jKSNTQ0T?Dy3eV&HFi83N0q8Pakj9UU(@6SUF214(LxXfK|
zxt);A7<KTc%b+ABRkKySxr{;Q_D&~@vM|cd&dv4DgM_*CV&cNmN)W(GF{&I>HTguS
zUg%>RpO>n3AG`brog0rUp;`z6%cHcr7cUaKcZ1qG7xUlFLcQ;Sq4K)&)p+nO=3~!y
zSzhn18l&Vthlh8LcV7Kmwej4#nF4J5FYR{n*StOq at _PgH(n at YQZhi(;!<zfx;{D>Y
z_+e0ftVrK|hL)C#`#{6EBaS(jiO3(KwS0u$$2$-iYMyK9D5<ER6WlshnH9sq<B?F<
z(;GoY#~@S2s8!X5Is<r=g}L%c54`q366GtX(XAtUYo6>5>=cy_bk5pE(QO^X91h_R
z&LS(Iy+6_m2dV$&C7bTj!a{8$<>z1y%$a9gFNPbU!^hKeu{gcgYHn+bh)i`x3#(LC
z;x|$1eWwsAb#--TE~fHAErc~RPuiy|%Tk=knVAMZ+Z}&zlvAEqIgmR3)xDtDu(NkY
zf?JAWPu at A?C*(Z=2%t(k6ZtB>6t1#;3m}_MdJVg4ELA-^kx9$}5>;c2uyY+lA3#E~
z{k-YnLz=L|+1mi|nJ3 at qEzC!^_=DU+fVJ#~B^DIuQRX{Y^tVq)bU#i at Lndl<fyIwJ
zEY4)(5XbCGqPOOC_XSOjuf1Vh1coU4EZ}X8YXR~oOup7f2gAyM24H!qJ0u&I6{1ZF
zIwvNcM<$XA1X40D-+)y=YWUw)e^C|L+|p7>9cNK-^Xt}7)#}l<iuBd6u#zuHWlgjN
z?Y%Z>6#?IhR@=r57KML)7rOUV-sItxR^3dcn;Xu&r}q+-epk$0dYvxiKAPQfhT`W(
zaKh8OXc3<A4M?dK3oYXm<oD9Wug6F=qW~9V^S6BG_T at Zv4x@7oYrOIsQ>?X>mBcY~
zs}^0?mKj;Kav2bU<_pA34~Q%3>;FJEN+T6}h#;q-p at H;VyJMUd;c_qnd4>W!<9Gn3
zlQ&hLuN1(E{sI8~zwdbr;jG9{A3rki>rpW?cU7B3mU-Zb`Gl~<@oiF2HB{aEJRd>I
zprIdkc2W67^|O|aZ%XbHZ(7PBlzBQ<c(nRH>yhjB>-v=XF&w6;iK{u6S2u$p<GtO-
zw-pgzH*VsqsliKLW<8Oa)+5}4w=VdkDcx4`IU_67I_7A%ZgXA+_k;C&z|XHd?xXJq
zR&xywYj(&fP#4_hGhq*&X^6bDKKL?4Vfo=ZE|`sl(gCg&)WZPg$9vtr{b<54kJ_0@
z>P38z!j+e3pyA!~_wP<oVE6u%rC2rthh6g7=l0YZVRG77sQb<h6Qj6P5ae?aUzQgV
z3LDTV*jy&g%aq2WBO~|-T`3pBPDQFk5C(ln)98+gApsG_CFr36l4EPuh#Cy3hl|GF
zIS*t6DnwtYSpH*B!Xef?&TL5uS!BxHYG3hoR3nHaySx6Qzi0U9vw?pAE>BRQ&bp4G
z&(`_-h<48t%YGrxlKSC>Zz4S+KfJt?Cm%_<mtE>eSZ9yQlDf0zk;N4mpGo(}8rpF0
z-;>wy|5#^?@fX1ob9>E*1`1xgh8j%bWmrU=BzP=BhpYg(8TpW~pddbN4_I}5<S-6u
zlapAmHj&tIfW{vPXc7_=3r1k4ha-!f+|&>7Ggx*s196n^A(@C~^2a<R+ag=@shp#E
zhWW>UJ^-kzLAnI-!4+F9K929<2j{TRP%j36X~CE~-Sa8b%}jAz=6I{mvkTuyeEt1v
zpFf`f0#<4r^&)IE#f}p&X86ffQ=k1%m>YMZAcT*ODNmy>SF*obVt{oh;v?~{?#82{
zr(qFL+7Z}hQH4Uy;L4RI*8+9g?7QzFN4EJ+UT|^(VHmp${k&ND=m!%UqM^jJJRl1k
zasXKo;BV7=pwb2#1GqYWz)r8NH2|kE1{#_4x7SElG?wiBfVii61Yq{m>Z+bm=Qb!I
zWFGr1zXv%~G*?@*H}sFlG%=?DgYfqCePM1c6Mqrrg_;>CnPPTRQ&V5OILCDE8nrY{
zvbj+n^I<F}2OA}2BIu5xsXP7%4GAo$I7ho8$PB!qec>6(^+ZIb!o9ada7Pbrj&8<r
z;F7f=?uo45SccO~{E%|7Vk3Busl67$7%)`ML92ZdRG at BRrlHyT6nvB-f%?PuM=vwE
z$({A~?P?L8R|Tc`DwI}8;KGFzDHkL}<h0q--=iWj&Vqh&mX<}x4jcx*fPV>B>zqUg
z5~p%-*#=Maw_y(T5YMf<82NkdEB92ueqm3bcj{>ubqbt`*a-r5<~B~|S$S#cE9w}i
z+!o)m<P<VbOBkujnea(oPf+6$eAh^^G)PCu-efcr>sVTn)}n88qf^u0$R{uoIAioF
zi&G_jeL8ukjeQTe1kcfCy?#lep~&ek1f9cVYZk3+-6UmKg8FB+ckP(kQB%A)vNaPZ
zoBY<^Eja6H!>JFrGbt&l at K)wnH+F&y|2{bZ&-t!<>g6%DeITJN$<B{<(1Jcy#dd<%
z+t&M!<e8zN2x!ZQ^_*=H9VSV{I7PpG`xX}X-KBvD2~>r1KSDYb3IJdzTsibDKG|%5
zeOfmO9`Fu^;kS_$ISEZ0o10~om5 at fT4D9g+E|~Hi_3kGdE&@jPg8VvD`!bf-RR|Xc
zS{?$BBjCBWVA%qtEXO%fQBkOm!R+SnI8=(tc~pzRdHxOHAuG_xdO`lW8a%F9c<|X-
z+ljnPkuGUCTFI>Tg#NIxKqsepFxFOrrYi)rT6RkKfkI39a4{F|%B^i}udVAY$5mAL
zFKUJVWeI)8X7jo}Y8ZQDPnfg>DyhOkJ}s>dsIt4n_23)kT&?zi3k!63fGi<={=Ae}
ziQAuldGKk+jEJD?G`Fr~%HQ<>_7N<9(RmO#HEcAKT4rCyxCU>wF=~TB^gH+*7|Qg$
zs-wRd&7yHM)YMQ!_qz2Ao`vaj6|nnMe>iw2f_}Nf0a_{LJ`3T?poS~2uMY&iKTxCn
z{r&CjrvR$2lpW at 7&2&Uzh8uBx>3?lV(z=Pks+G!gd-VmGNgzB!6~K>Rz`_l@!BeN?
z<mB#vt`h)C%WNs|X-%mHemmT9w>CF1+0gM_n4dqZ;AeRJJ?uUuiP~r5E>`_;^SvH_
zi at z!LK0qC0C)|=RV9LJ?ElWWGf$q-EXt?A{-DGO51&zE&<L|eZ3%N(D+<!q^ysox3
z0W=L at rVJYwe3`n_j>T=)xFRAVK;;oBMv7^dQ>6;}b at npRU*WGQm?xNMg;3!mK|t^Z
zq)ec(?rm-!Z1spt1Z?ZwlTsw7`T-|j at 8{1K6chp=z6%)HWh;hB6%`WxN8~AMxNL$r
z=2M9?(;~yv4&Oc>l>N<;pTkj6FgWL*hcMGFV5dMGdJVojY{PFWD+Bkw-OZ44FQRvS
z#AxG}4KEk|1I6((X-}J=poXs^M6uD)RO<~)vOed;JwNBi at 5d&MrCdGpchZ>1!XtY2
zI%1z561Vz8h8R3FoZhfK{+dlO(01R2nKKRGqtD&Di3tfGdwa+0?t0$-{u+saokuny
zr!ZGW;-2N+KKZ|yR1`{>eq+k6IP!VWp$p6hC>vlsgqz_(BnZ()?Gb%a*w%#*5kQXA
zR8=1fS%g}{LGYq0MpI#L>9dxRmiPO^<yQ`OU$Hf2{}piSnr%qj(N)8O>aVoa3*u0K
zT>yKxXZ`MDL;I&72p%0Bjf{+(Usw=qH#iLpw|WPbHWl+f|L2*A(p}Q5>izLdWuO&7
zApk>ke6-gH@>-tXHD!kkY48lV!^WfC62Q4Tb7hKyen<YB;AZ&L at KC5KMXpx$_Vwv0
z+uqjI)z#1-s&9YK5jSD at SEijWpp8A#`RW04J3f_>f`lZL#cl8 at 9xVXd@r$`KsOJCw
zII7#O4v{XM00iX1{;8-4`k2<PuBH0D at Av1Q-UwHNafs6NmI&WGL-KE4;pbNxI(Lwp
zn;QrW&d3>QfPKN`CGsT+>?Yrno`ZMh at c-lLz2m9w!~by^A$zavlD${<Rz|jDM#(4{
zQ8vfkRAeQ`9wmE3NH)naLiUJkvdQ>f=f3an at ALWo{=4rUbsX>aYh2g$T(v_!TM&7m
zA~R&WNl^O2ertaIGl*WD*r)#U^f>K-wbNE_iCi=ZE60N--|??TdL2Id;ZmNZd|JSo
z3ah}O>rMSS8}GdosJENpQ4EVGVgLIbPJ2KM+*W_C9^%H^It+;9(&xX=J4Jll_Bc9w
z{mgfSA2ki;Ydbg;)wIO?``*5lQc_d%o7W|bhz*Ugeny-sM18VzUmbQ>>+$kNEG#w&
zM9zfzo$Zf~Ul#fASvTtgEC!`4H0NmGN{Mt@!JnmlQY1~(!EK|<xUun%+e~sM at e{}K
zs{i$KoWM$O5Gs5iG>{D{aMamuUa$MIx7wk}cn>A at KObJJIP?>~jxL_)2!lil{?k++
zd;)h1%m3bAy`iBYL_KH0B5i4DsSAc3$k0U)mFn}&k8HVc0BgqQy~WR_eG{Ebs?dF>
z_pkQ5SHHg!7a<RwY&uD9nfF?WG_h)QDV9rZ|4)?viC{UeZR_)H+)?j>M9TPV6JAwv
z<s1T+>B#zp_((w*NvHR7jkj|5rtam35Gk`hqi&zkx20d}Hc;B@=KasR;G2a)j^snn
z)5``7WeRugKIx`41U&0lR8D{T-@%ZPmz_PIbk~yXU=qx)nVMUMFN;wwXWS&H<xM}^
zZL#`BPC!YKe$2BpEeXERy~nT2RW>FPyw^5y=>M|y_i5TiVnr^V44i)bkXs#HaAsn@
zXgH$!c<I55K`Y*_heLz+#xyg at dsi$TyHU4ia+>DFXXoi7_$O-R1Z2s)jK%V9xAf!&
zn<cNdYX4`U at azSOlQ^i;S+F{U4ztm*g_8Eyhub+5Ro;ItB{iQP#|zHJ{2b6Z-|wd!
zEN<UbzmjZllHN%WcKG6W%9**K at cY*1r+<HR{-Ct)dMY38%oMP$H-6Y3;L9dw6B5yW
zVxV&#n$6_9-BK#IqU2?BFOd}S<=8b#pmAGAV_QDpVy)v_D#85M1pLq{zfbK&8SlBy
z%r>l!%XTLO|3U(lN_pmsHC{Inp^$|^L at a-emCR}S49c<)@l)u53O at P`j~+ at NoNpCS
zHVDd at s~Fk+H)L&4W@>MNmuUL+2_lTNVgKA)xg+M&>rR`-KL$Eq8E=FWt9ISj!M*0P
zd3-aEgmE*t&)LVfPQ<6>jcp|>Dq#v2aL6%&NZf<UnZ~DN2Y$a}@0Nd3)0UAH#*=Qk
zcpm<Fug#A^-!)O4$^WQYoUioiv~Mpb3g9efKMN<lTspm$2)~*?1_2inR>tb*By
zJS;^dm*U9j7<2Tq`3{nRy_f39X3ED(NcppVAD2xe;%WP*XoAXD-oATHygglWIy$G9
zHsywUy9ZFpv|eKWcZo`Kb8}nz?Hf%hdYu#H9|)QOt>v@^Z)N|-4ZKv*=Vf?^$Qr*-
zIL1$}_6DqWH&;3AXVVV<89FEGKV2wV#oIgYqeIy?l**H_-gxoB`?OrW(c($Mg#7t=
z?IZ2XH at F@lxCiRSq-$nsi1RJG3$pUu8bOEg&t9Kr;g!x$Nm%7*<B8hL&9j|tpY!7(
z9A}D6k)wRKzeq_DLgdc+VzQ<ExjDsnhypv}r@{08P8AE~97*(!@JRtlY^$G2m#)B#
zko9l(IF&3P4^_19YL{2|?aQd(oa`q(+jcpvk-}tT7Q)o)UFulQi5mGfn!@u29vaJJ
zSik&dTgv4z6b6|lu54nnR><eE4-S88N*ow5&%VlMCOw-de{^XOm&m=rs9IqtvY<aI
zXf3+Edh{+{TMwTR()x5X-cdc|?z8{9NW#=yw~zjPiVGbiG_0+ at Z^?Gf^4-ZWg&?i|
zEn~@T-`=Cbqc}_=FI7qvW9Dj^6=@Z1V#Z?pfO(SUwc+wJu&wP+r{~W8WyL=jMBalr
zwP at wsbuZ)R>)<`Vji!3|8WVnJy*Y;(-P-B?npDen4D#3QeD3~dCNe1o!*aMDX8$l~
zZCKYR+|atprKE+omzG$E`;>VKas6S+A=VGl<$+*XQlqkpS1ZDt6Zne$ZnJ$0IPtP4
zw_xp03ty=^&1r-w9_=5k-j`n&Z^<K_OU;ac`k940LZcI};3eAov+=QW5$0LH-Bx{A
z`@aYGFso_p(~@)X_;T7peJ4JVeMCn!FRHWFPRwz*t2;mZEtYIuV~&DA1c8qNeYI9^
zr^R&j#gfRw=t4`YGbx#qH?HR4;S063-^iDnFE#{r)_tz^MCvui6n=yVY8+2%zm>PQ
zZ3KAl?LPQ at hv_e@zuJFK?Z=q4d9O0$w{2S5+cMr2^#YCO!ODq$=gir`AB)EZ_LY(^
zgtQ%As3YX8Ui~e&alUPu{wA6DNp1oWod_HwifK|g2Av1+%SU+P9_{BGXL at Xen9xgG
zhbhRj#NvPQwWm-z-~Kx at xHo8oFM8)#qS>oZd18d7xj%=Igof8=r!>HSiCJeL1oclb
z6|?^Z)9KH at -vk&c)3vPo%mEh+hGP@$9i4f<t<LvUD)V*jsw2z47+4p=q1Df78HYZF
z&c|~4G9N4H6Of^I*_U<;A3v(ujmd*WYLZ*c#-hr|fWJo%1l?MHGqcqi^SuKEnoN7y
z^}QpaLs)2xdF0%8$nNq%WhZ|2t$3MJm!)<4sDI4`Kj5OF4vx(|EsG99#B{ZI-eG{e
zMeQ}kkX$W>_=KT`kqFX=bruqza<97k_pBO9Egh!j`<^@5bPyq|*v>)+%~cdL%A4%Y
zY|aq&KNEx&(l;&4!~;HRzo$8yT>m9O%rx_Eam{gJGs$>+3XbGgV)Di+i=`>iPipxy
z*_9r3#*pFW;asQuN`wd-S;&>!+~N0S{8XZIws>2d&+rzf^avbLWlat%ykrd=*EgFp
z&kBA-_m$;r+-2?!uIVJ+&(#}V;^UAr{^#*(ISo|UzPIZ5ElfS1mu$NFBNeCKa_DFi
zXPldc+}`i#%tFie!$0dHWjtF*-l1mMCR<K>awWB13os>q=99%Aenh at S!I*v<x8zLK
zC+@?{kS@$RW&CT%_8*%L_{;Z at Yg`#pjmeGnY17m6<NCNb-fOFgpsjUa_=fjS8T3F-
zhBc#INcN60a~GyXDI_U<Z(y8}to%KSXeWBsox<42!mq{b-%MTA)!^J5Ix--h0w4fX
zY8}2>oQwkS%M=g0C)PNncz-RNed#pu`6`W&o3mx{Pl1f3b~b`l=90h~h3FW1F^vgB
z at _!fAaf+^#<u@}e!=e>VrwPIR at Y52rN%N~xjT7a!U)#lAMBU%SDh#L!@?kDGJ at x&k
z+N)}>gY-1?m&=qdjV<&8B>Oj%R6{3FTA`WkuO{E+e%xJ%mxsJ0^fVMe8%l&p=O-2o
z4STsRC+OY^c~ncT>pfU<1vzix26VgQ5z=~=mT`<Q2UAH0%lNWk{2-_guikW1VKA+|
z>AB6a3jcuxUP-=dBYaNwKW1CqPLKZ7AADSDkd6L(YoRzPj%Jsd!pKodV?vzpnR8 at B
z#21f<=5f5oZH_o6Fnc5>CI<TVfSL*Y<cm3F<#1v#TJSW~($*GJF8THd8f(BOABLdF
z5-)KSYa5C|MoSw%u$0H~*i}_k!LAn?+p14qyN_HeRDf;)Z0P2TbDuuT2vZ1cyjqA$
zMa94neL6KcsTM=4XKKowoxtig20(n`r0>7;&aT&|XJ at Lhskmvhw!smP**CGT(n#||
z7MPv@)7xs8kD~i^Z98gv_J@|by2#i<an3;y?>_G5Ah{|T_%VO%TThP?0>JFtYhvi}
zQWvRHNo-*Znh2w#I_jd$9|q3<O}@t!W6(vEoZp*#@&Bv{+NEhA25teSc7jw4zJIHl
z4^{hgDh-TFpLzi8`d+;|*EeBlX$Ee5MrhJMihGm at +4fLMigv&KiAi+-&bZ`$B$qoy
zIXxmSI at -+cA(#!F{XOiwR{-|ojKF3Y!{IYBF)55KD^$pFTVG$Fy<UZHOC$D(iJHt_
z5HJYfnk_^%$|j`(o5j=1tEHog?8g#twm2>MWdEwvz-&7)8iL{YNk~Wr_{HE;v1P{q
z(0t6!jm2yPoEP7RRb+=(_YM|ynCo9kMnl7X`}Qh7N8<nc(t*rz2+S}L^+<4Y7uVoO
zadF|-T)I0VQ!Wh*&b)VA(|nHz+~M_MVq)&aGg*HTd;t2aSOthSvb=Ly;$*X7>({p9
z718yp<V8eA<wymXT#?7waOoKF-avW8!qj at 4Vi{IC`)=A%qwUIQDRUD~Ro3BK;LXq$
zFE@=4{Qn<$P{YlStuPY=?g1GOr9B>WrBh&A0Q4hZh{sMa5mVCA7AD^zg0KJpH*Vd&
zt@!iTg;nyKH`FvV%EqvlYV8Nu=xKalW&-@=YhgVRZ>^b7#^~TO-^eJLVYH9I*AxJg
zx`W%<luwf`w0T(&YWVx6F<<LGebRm>;{`Tk`7rPMf$Hrg&{tA6-Qq+oKLCrh&hBpf
z#viieHk=Wb$nsu58}@$(NuhOSUtOsSoyhp{NJx at 93l)q33s70he#-j1a15ph+QgEj
z5dLE?3^wHmd&S|TF`PaPFY>NS_z757;tdjTyg_Sa)7B2-Qs|t+l3<ab;qLGu!g#e#
zUYMfk*;i<kO8pAN(vwH1wa$RODSVl(D>NxGGHQAPRBw5|>RrA99=@mW$9kW^J|Kq`
zjc}>*5nfjao~NvFo{95Fd<LCA8xQ>$U%Jqp*B|S_gol3gj#KzIS1<P69QAnaB%){P
z<-m(6UjUfwm&=D7D$0HKgyNvrROOiFR9(6;onLV00JokO3DvHbTp54n?%qZtYvEzf
zK8{lz^6h0^S(z@=+gJm&)Rmzq6K?r&;zh+&$ZLqpzX=&+*~V!9>;bJbMeU>Y1p{Ro
z@;t-g-M-#l<!TmO%HUPqXVh%if7$FDX|my)0a=-*6^75c80KFNn*wZ<Ry>8Ah4k|B
zbE=$L1rMpIm%Ry}J_0*3Ful?pMi2o4QkOYb6W%-?F at Zqtt^XXFnF#<+7-Yz8>-`Z}
z0Cg~0nQ{eyPnQpSt3L?x=YRjkHDeThh$jqAw*`rHTL2i$UdESImFvRxx`Goj%VuXf
ziYKZy0A}av at i2{o%)?g$u~uQ&^zTA6XIfj8{k5VQ#HH|El2`FW18LZzR5qZBY=oI)
zOC-R!o^*=4bEUUf2t+>+*T}leD$oZaG!&lk6w5*`Eq$uOOTC+Lc1p6lQf34Du28o8
zc<RNB^$SyVg6yZi`_jWni_P9vcwWW3w*o;(8dQ*)`bKHVeZE4W6x38}6&rBA0x&Wt
zb(L&?2AD==WrDx9*4B6k+;82&`yM(nXQW#Xca1&|B(~4ys_5XWt5{^k>Us`i2`k<d
z`$5p4Bzg9ViY;^>W(H_+(5I~8a;^?>g;AFgz+;A3Ytf<|7x2wU6sgAfLE95dK6p$Y
z!|s(p{x at pjt1ekJsLRH4-zaHk&jdZ|yoY=iVY9HKEDV_W!#nZ*u0<@^8O-Bkqw>#H
zFpD{T+1l{gi1f2l6Yy>HRP71OA5ijqS#(N}OR|4)briCdn1vGQ^!EDhj50YYnEMFo
zncu1lA&o$Lq1e0oK1Au{e*oM(s-K<y<tj)vST3289^-;Z&lo4wHCie;n>M^+mk8;N
zIJu<sD_7$6v$9rRrz9jO{0QQt#JU at o{XFDXB_|h`;yd^GBmXavIayp+#KIC`rbZe4
zo_H}?+W8QJLZdU<D>{-}j4{uNA?#Bv4C(K>&?I+aLGikfZ(BEXk+X8}=FJ<mbl`h~
z75*2eSLdq4h%oX2tS$hRCNEt2)oKzYK`?fx<gKqNAN#d0>D}u&E$gv5A_F-i{5|0L
zyUc`ApoTO~+ohgvB<izZqwm)`3E1c<U+1h*1oYo5v=L!L(F_-iIB9_#*?Db`+}+*t
zFwcPC#D2Yp<vR`$QEv-c!}anB9AH(W at Onj?XLI!^z7A4mD6mt at seAYw@7SsUk`ZUa
z+E<nhso{ehY3c6 at jIEG*j|>+;M`};u=1^#gBr4v~uT)woV>gl}4#`)<)VS at YMG|bg
zhZ)PAjhURBykPFqhg>a-dke^bw$EGzC5g&P at tbfL1*Gde$VnlmiuPM+X~svWVOCMb
z at i29_a&akp4|4}Re2B<r9MB^p2}Uc)D)afV!IFTahdRJDV_D!4$X3K$orXB1LL#UP
zkh3m3q{O~={zOvfjJP%(nM7_;;EDcX%8*E;$k5`x=Alu<9u9}l$7PCGgRtu8UJM!$
z)9{a4RUBuVZ_u24qFR!<1RVO#uUrZ!RljT+gqyxZQj at jrEk~NfD`9*e3w?s|^D1X6
z8n){S(gVg)X#FVpUe3ARDg!xy_7UmDeSt%SPYvVfR*<dRu-1CDgT<edAF3uT!e~W@
zFz at +UIQ#RZD%BHCDAxb25C5$OtXdlTVD}ShmN+5u1D+EI6;nn~ZWisx2f03Lx7^G0
z#uJrMQ+fG1@?v6MEl%4zMFR*4GGQt7G5y}}$?f%(kL9Pjh-xkSj-IfhqKbJr$>~gd
zePsxPpMHZ0i<GqYHwU2W?#g<sCf<saYWsxrbk{wpRnD7rPr#tRp|l4MI2$lypPZVa
z%IS<K at DqlAbxQ}xu*=8%S#($>H1>bGC}uI$`gm5GjR`xV74 at 8G9~G6FH7c~;Q-v|V
zl+x_b*wpv${JgwcOu8zD+^9mkPfJv<F}3&a>Fe)2c4W`Tk-BjMcWp=K1cjxtk%fVV
z>-9M6<QC&evS{pmrBrx-MAo^BVM4|ZpVS at fH2mLp_VE!NqtW@!mk~_T&p(W{^<h2Y
z74IJ1Pa at Pk7PK&x;6n{_C6!v5D at nSZ3@0e`wmP5|R8#q+MUW0!oEbPYDSxm?WVR2?
zwpMcNSH>49t_9*g{@Q#tPCRG8(KoPFQM){RA at k!XwIF?c!qwY)FbdajyzwMV&emIl
zxc$K6V5HO3_kXU3H;{*G9u6aJAk(vtu%iG&Xpg-nA#oV<va74>%NK<YDStFeR~4k#
zW+0G`smSX!ktl)BfPAMIW+O0ERU+*Wby at T=I&}M(u?*Zw_LS;InA*a*>LL%4c~ONt
zknUE9AESM)<0^*Z4KBJ7*<4~kdK|VG2tEnf01qDeVFWHP^oDfa6WWRvE_ka(IG`&)
zcA{*Nq!*Ni21o~e0xzl126B5mItS|SWOUhPI#^Fo{Pv8o!}@huj)?q`ECRx{u1m?x
z{O{)HZC>W<Bh)m?Z>NyjpV&I(jR1Mv4l)ouVzW+8PV^;A1W<L?P((*!MNtk2wOG1b
zYpM!`92=t5g at Bi|v*XGvM3=%9)@C#SS2u4=cv60wh&$i{#o`fB-Q3(9A5VglMr}XL
zJtCGd4a^}?gnp{RYnVG8p-)A-mi8xzJGV_Ex8vp4vu12hhH)Zx{#*_6AYble_W2Ap
z?<ZR38I8=2d!*=Tco;N)K at +)ISK4mb^ny2N&^Ivmt0p6_zJYRIxVBrUfplG~E-(MI
z5OW2s*RWvzN_q7vAv0C&oa2=}U=EfEG=6BSz$7YH{+ at L17N-!8NksIwwzhUu<~-ze
zq;G@|2MSQ!LBk*~U~S7U1q&R2ZPLI1S?b-BSGlVMRoTRPCRO%iJITGRn0(|s)DZh5
zMt%r}h>O6ycpzkkEU)q`r}}0hU%xOE-|V}bHG|^6hGIVdEpkdkD{A_B=cirTbKhMn
zXz~oW=HFz|eRWkoD;zb6S6HCte<%C+odU#Ls-};VD=fLFxAB?F6ViuftzEVa9Pb&o
zv%%}Mz;}Q2h(pO<KcW~r?de6*xrl`tJ4%oiNC&MOn?|5GDry;3ebHWl87uON;2ss4
zm}j)ypoO9rsxd37QFt9Y<%)+(B=GY0CMjktcG!d!rA>{3x{Asd+r>XU-kTaoe0sWg
zV`Lwc+h;pQPkJ!5F9?d=^~HxUL2>I;_yi9KMIwpgH1>f6{d=Uul{oZCF>BU99M87V
z`wa(0{m#C!Bv{;o&w+ywD~i-cB{VMe8ZPzINs{;e7mXzLud&A)W{|(r#YSW1O$1-u
z%<j0X{SfgeMWZD)*q=)UQ+ro|UF9^tm%E$^F~S~?=-9xnH9NL at NIeH2EASFJoM>ww
zo<x!mCuU~Gr*obi#7!E0yFgx$%~{}A(Jq-88;2=JSm_#FM{yFqYVl}`aYlQ3MwhA~
zsrKijh7}L|hcM5e3FbGg!uuHfFuTF#9-_(rtiGYa2SPJEtI%O|70PcJ>4Pu_Kp`!}
z7=p1$&cwuz76(L~6jp;hO19ptkfC0Mf`MkF6=X^Fu=vYf9%w7S^|hzBcP{60C3bzl
z#ksw9og{Ir at B;GWyWc(z{SCIT?rd at BH61dR^s-zB_XO+o5n(UpdkVrg>+Ya#3f+=t
zb9Zxl6|fg3j8b%v6p$S#7}E$)xz(v!qx%~)NImjwAB+%93-Ne;)b_sQFDvcchr{Bp
zI1SziJ<n740Uj=59^AK&)l>J_l~!ph6{6ci6rArhZ at mOEcEN)iH(kDUS%rAQMKn%{
z7QvR%wGT|x=nQf64+z at BtYW|ba=t%3v!ku_e0gPrOn-%E at IzP_8%lICTipLGaW{kD
z{Xj(=aV?%QwzLzBFMKSQB=-t?^2-}|5C{AF?L-X6_XSKcJb&Fw0s+gnxd>AFbsU;D
zKM4rb5g`TTp7$PR$)&iYganq0g?Cj7!T#eRj#sL(d#LXW{rs8wy&c&^q^EaA_&c<w
zqbMtiB`tdg$AzrxO~PMLV{y}QKXG=}!Byoraah;QEaObHuDjBPXUD43Jc|_8$nYhS
zb(4HUhbarRt=u*T*rT4o-m(NmY{gutTY--17Fiv-ZorPwRME3DYmM~u at mb(qZt=>)
zjGZRn=XNBhqS;YARNFIi8JPE-8s?gCp)};Mu#gn3V$hH7rOp0eC=|=sH-C3U^f`0^
z%Lyu~s&hk8YAU!Gv2qW)NWJK#E1{LUKm-!HO6DrI&M7D%SHf{Q35kW=e%;Eea9Ce{
z|G<!HXslczIfc at mcS>&k92oOEBkPo`8&*EM-8VA1r~QM(Llp#cdS9!%uJcLl56 at i8
zZLanL1ZjjwzYizU{clHcUtw@!q8<^cmuws;Mj*N=HQy9u3|7*|jJP5xxSI_?F1W3u
z(^>KuVsv+S?%++<xV9=kfdrT(Rql!z1&xv0TMJ(@7}9?YT|?=zr3mdHE_E&F|Dq`}
z*SE at aUHV2x#$!1XSTW#hM&HxZQx?5)_Xag3Wki4w`>scAu=hy3muk0IccA~0Sfcq;
z8oalHkIu}*T}IsbT>wX*uz&jK(W9u7;xr8_iHLbctG4*#gXwcNs;jCpxp#+o)cq-l
z4lD}Jw+R}eH;Gi7GEUOS$J at jdaB?nGBa$mgC2{HuO-<?dGjuI%II1mbn{VNG^{iHc
zk*~L4<a-)Mtea6G`se*k`aeMvk^B_dF+wLG_;w3Id<=$Zo^{=g&X#+dpOz~g`gir>
zaTcx46|R-9Uv76l5Sd-Bn<kCsF>f-~b6(bm^um`ZtLe1u-}S7#gACrZmd7Q!jTR0D
z4G^fqlju at r*ClU at Vzzn;zC#xofy5+ at w{SA9^hF!)HPfn1bR*Jemb-|&TaSbpPxD+Q
zcjVhpqMC1bTa2`6QkHmCBAObPTcexVuuB3He7t6av)rl8LDRSA)53b*QuWDk<qa;g
zFUqLGniX|@HDzVg(l6tyosLxy_^`SGSD^!Y`E=pR6Es+_8ISdW_A#~nV<q{^X`jr1
zLI!~Gek;=|4seqo%nLL`!W--B%hn>Tlj`UKCz<}r-gLG>EQ9<|{STh1mANHcM3`DM
zc7?*>Aw9R6EA9Ej-#qFP%@~oN03vGT0Z1#}#JI+UhTBKMJ?HUvnCrB*wmx2=$*b;z
zLLSP$so~M$&W?^aCfV`n>35b+eS(KH=o>o^^hfPOea!f83KlmeTu-2A`h0vM?e>8e
zbuTsDfl~d?0Y$+1kkw^R+(dwHVr~Q81l$Uq^-n;=J>0pte~3f9d~%6M1i3Po64nje
zEtqB`X1~hFC}I8$KLqEWAF_m*QR!v|c=e=(-|I*D?6xY)lsAp3?RiVg8V5IjNRa1$
z3)pVK9p&v8DAL5ts1fw>?Rv=EuQ=oDG_g2iG0`}3skgFU+~HWC2L`C$WJA<kNsZ<G
zmH!299E0#DDrfbdAv$*Mblw3G at 6*wtMV)|?-H$;J+!EE0XMah;onH8F$(J?_zEc7f
z2FL->11t^>4lyw?dHIV%4Ozyw9VQezoW%b_S`cdq*|_Jzia7uK`eIl0&{>RNxTcL0
z#q6>1F_MT7k1SOstdq5m+5ZCjs_E-yHDu*oN*N&fh$aN1f5c;kK<m}Z0Oyo89?<g-
zKqF at M|IrzW at Hw9J2Wbx6%rsHPz>r+Mt)gi7Mp;L~zh=;Oq^kY;YU$aYp2?FYSJKpV
zZpj0i-8XpO%s=0G9Weg&Nl5P&%lcj^$vdz5?yz->s!uX}B>1O(>h{k+#I~y>RVavf
z(9yRKkajq80-1?LM8rVrjyV;~A>pN&fvxlTVzfud=g%@;#tuZl?1-l38w?XBG{Djt
zV}jZC{Kc#{8V7R12rCjnamIxSqMvb-0GP69yqg^fdT48#nz0MDmsYd=5|FFFDhcKi
zz^t%pcwQo2FAg)#qEl}&if?ak4s~>>F*si1<b-G`YczS*QQ-mPFbc#T3yB!W7ZnzQ
z!?L<EEqcw)_ at FOa<W4UmZ#&H65_TZ~42G8rahTc$D+4|$Ti2nFZg<@;Ehs{hCO&nd
zwHom1wNRjym^kNYnIxh<WhN%rYg~ef6RKsL)V}A_0XB>#Z(l6^^1&ER1vSkoZ!E)S
z1?LIh`@qhP{#}|T at 8hr+;$RY_7DB{GDdX}*&<<C^PQ6w@?qci4RDHmX>*0m(w)NlV
zjP@(2a}VBr*-<T at a7czX;(3=4SM;ib=$zv2>%8(s?*d+wm at QQB6dYQ#fR+Kx9ta~v
zh0nxczx8ab0G`LG1YU#~4H>dN;_fbBlCr07rRwM5qNJn*ggy|Tfd{e(c%P3y2G**H
zIwZldPj-c8v$3-~l#!9^eg_|Ks+&Bkb<r^VSBgW&d%1XVtU#Z_2XntvNRoOwSvOFH
z4x+)id|3(Uzyyh0HoszCf8|O}Oax*!s4F5Q2x%xO;kIM_4HA;>t<7nu58T|q_&!<B
zu#GJfIG-@)Zt*UUeD!#mtE6zNLTz#O^ES;&J44M&H(>0H5wu%YJ0=~4li}|HEf;(*
z^iqL$luUpmvmd^^qayq;$n at 3BZaDopOn4LISLw7PYdHD%@(Mx5`aNADe$@$jADe?h
zr->R?iHENs5lW`@>sL}X;fJ)3+gF``OB2L>yw~K>^47LF<<GXR)mF<L;*Vu>Kn`oz
z;3=Kov+^xh4JR&rv3Br>#>#hPaS{5-U;$iTo{r8=0bLl+{45OG!cOzJ<FdbM<P<6#
zbNd6lpZ5g754mJ)=j=?v6;cK)(1Df~guexDsfW9J2))f2z#^muN7UCyns8o*63?$u
z9pLk*V*0*k!?vn`XzyHGJeV1mRaeKx#f7~_3vbr8pGa}aFvQ{g4rYhrV_pFzt^M6a
zQq|}ebVC9HrNDhP;TVD7 at a4bs?<ByS4BEds-bpeyH0g>0Qx*iF>(L7x#R at NB?j6+H
zmnwpb12lK+gS_3)uV|UbLFB8P(=l7%l_hq=+i_*%yc{J93aqO_FlcWN&b4X(@dI7A
za#s494`Y3x!40~yP}g+{@%L~`y*kI#B?7#X+OlsbtlUPDg|<b6@;@+ee+2oL4zA0f
z9?n@!D1jdCL$Zo5%y%Vm at MP1HgjHI~vI`s8B_t$%#h<8 at uw9*E=ppSx5MbyHI~MA%
zbFN9Znp`)2COuPg{AKX^8b$s$1`5%ZA-^vYR)@aLL(OK at j%WP=a)%>kjPhH5LJJCL
znzH{)1#OA?Ixk44GNlQAYix6rb3L>L?0{l@@)N~s4S+mknBBktZS8?Ijl5SS2O5_Y
zq3*nFxr`r#Xgd|-9_Q4sLPoKsI)*!uSGP-I_d$Lz@$+X3y{g6^j9 at pIFMaW5O`9+0
z-$86E-UjXOVjHRYQ58PovWu;kJB*Unk3osgRt7i+0z~K(th%??Rj~wTiy}hb=~Ko~
zr0d#^Pu4gwh=Xel+rf4F^=g at r1yByMQIL|6T{_P9*qO at CW*b-8Y9AdP1ucNMEds2w
zcDA=kJ>o7awPzET!;-L at L$IOan at _-U2h_VP?~F1fT`|LRMskO;u2NPffY-O`Py5%_
zACgWyrTcrQKi%J~=-MvA!i_1b^jO{5`p9Qi<2ZfVemJu=*-(2HL56^wEtpb&Nj?R$
z)9M at F1P_x=jw0Vn!#d8m4_P13Gy!6D$i!YIfp@(f9BLUIain36UqI`LG~`27kgd|e
z)Ee~vXi02v8?1`a{6a0{T->&*o=l(?NEgVcXlXgCUJ1&EC>KF-`{~2|kq`Ia5Z^KQ
z1zXidAdMv++jQ at GS4w+ij&ooiyq+jO{6>YxfjR7#7!BnwOWnLlR}KR1*KGKrZS?ho
zB5!y)AuI#dZj at v9UI2y-oNr)3@}&okmY2scwOnkx- at SL54*AyCK+Q$#uGz)`>&fHz
zd6U=KbWHnWiUsNz{IuCQx!GQUrj?@+Y3+1Tzs01QOuzA|-XR`gVYlvA*N^zgXEX^7
zI*WQU>*|}K%)tj9DEPvvO%aP4UJJ}@DP(aPykm4_4@~KE4V!^CevkG>Y#Vr4Wcvbx
zjniE>*b=Gt8K5}_4apaq<|<&-lyIBi8-=~l^Pq@`2$vTxl9ef|X(b6%Z=iJTo`64F
zw79GO7$hH3N|PsD5p}-_`vWGnuT~cqL$UX+Sqh*dG!)h$T!QL0^7aTk>C&RB^lYz^
zlf$3(gFyi(aLU2ot?&TOchWemvgFLn%tr!yj)^_k^we_TGg{s)XnY&I1TFoK17<wW
z`gG)1p6- at pROXm{nbpg|>{QoD5r1ad6LhopP2SQ+v+BnCt%oP+_xh6e-$xlgdh%7T
zDLRcz{Q0Ykz`3}CkD2ak(^+S0+G(O*pZ0q#>U~k~lc%=l*a3#y_KW!b`O#b2)?opt
z4J*(O&&I|^Mpm{uOAVqR79fnE^hsd~ZPN!sGh{NK*&}CXdAN<17obx`)?7mY-}09E
z%ENwdM8}lU={3Dzn6a#%M1^8|1A`S#Nw-_zEC(aS`Gp0lUVPEjp&viQBqeFxVx~X>
zu7xM+#dpSRj3>H at yp_-O8JV4pX-aq)ng+T8avY>f;?;YKADng0FQB+2dIQN+S)gaK
zvPBo-G&oX&P+&|?%hkv_LBLuxdY5FiuECyZD|vsf@^@Cv#>5NH##RQ>O&z&S;-A%(
z9&WB~otVexw&PI~G*Ks?J4Z!dw&PmV*Eo-6O+DUVc+c`a;B2k2-^X{LwsZne+MMic
zWEW>QV5b03^3%A1R`OP<7Zd~g#MH}ayu2t6%m~VB>)_Hlj+cWt{`+@<;i?3=*YFb$
z$Z)~mc!Mj#LP2hS#70h#_j-W9{o%vh at Nf{wDqVgGJZ6sm=W(Zx`BAxDaM)6?igKsD
z8!**Cs>jd@!A2;*y=0n%HoiczE3WO(qE#n``}G6hoxTSo_Q9grtYM?6KxieF;-E21
zeUuqEJJ?3a!p9f;=)GVIG)r86psFlyIK6J54X at azKt?LsdX*iDk$Wb{HEcogl%H?_
zI(U9TpRl at ITwGDE^^xG_&AobY2JOcE%&JjHQ_ccj^u4i+TwMVaZ~{md!l*n{F1f)0
z{G+8C+6D(&(Oh&y1N5VMF;5#or1(-~5J?N(`T4BOK$E?5>lV`L)5|2d;z=HnP`v~H
zQDQwP#HYwCiCgmQeo3;)cII8ArrkgRcU{#J%=Ux}8aP(3GMQUiek`n1fmHP_%-DUf
zRY{j{&i);Ehgf{&#cOczXaswV;!E5N^gNKeoc08qu_Bbp)r*G4z(`K>6jT$joReEC
zbH=bZLHX*D4MdQ9ehMn8P at fy#!ywBox(n<4A>24T3UT3tbT)#RuY)N8tR0-5wiNG0
z+hfUUYG{-ZTkr4g=In_^z*vJtPL2s7I1a^UM at Pq3f_4+fIxb$)a$U<{sgAUc8(lY}
z3wV!@j|EMyU<1~aV5&;>2S7)CmTNvAHTqy`5KDbb8`B=V9+mnI&XucO5W5-`WrocD
z-WV&KLnCzm3&yWZn7bul(?{z0aB>fV(L!70!+S8x3cv%8>O>KJH8r(tn%u%hf`<f}
zYA^7rLp(m+$5a11XenyV%$SBQVug<i=cjK1f!GPVb(rVB?aYT9fcHa|<_Ttqz!>Sm
z!hm|3Ovx?3Fuwul!x0>L5DP_b<2?PDYmg$5Z-ry<t$cuG9J(;I5p!lz{O)tOsha4!
z2d`*jrkOcX>?Y?bg-wW6or|I#iJq}>{%sa4u|$$^<@*#jc&;B)aWl!L(<p?N6Ug2)
z9*&$Y<GNg{8 at 6NakC~ghOU}wEvQt1h{_+l8lJB2+)emo_Jg(r2+PPb*61NNtlq)XH
ztDw>5t|}P`W;{GRaBikfFXUMdQcKi)@BD&t&^<|*@L7LEbaZQ at h@hY at LyO=(MD?P#
zBB6m<f<i%lepLBFdwV;;xp3^%-groxFZVJfCBo;1RO|nG?~hVUAA+kkJXbiOzycHu
z$|0C`=RKNn9S_kNbJHuoe;35wPw`eQxw6;9SRj)8Av2 at w+I5G;@25E@*!zCaV5E#M
zLX$HSaB&7l;r3k-I_g%z{g;qRvM|lH^vgQMTZ0dOZ}aQIG*j@!L2a}A{a=4N1J=eS
zoYc?B{A at J&rsU7)aZM{_teE%PC;}YMeF^+LiT*EhlK{l at aXtl}_kfIT;HZqOb(T9?
z<=L34V4OL<+qJy>6JL`fM7v!|$<ld->}kmikc<B1aSuB{weGTYda_npO-5)?T1bRA
z-+9Im@!>_YV%oMqeL(a!q6v|<y<$Ma!YyB_l1cRsl!YW2g@;I#2LBk&m&eL<VV`EM
zO1a<qmf9tFl-<#|3mSnzH9 at V$uk)B0joGtVY9wb{y-tT4k|mMjX=XdM&2q;ZqtDZ}
z!IFWsY0cPa^tW1crJwvYlwBd5I1HjcfBu9=oYb_ at UjZ7Z!QS4-P<M?-IAW#3OP(%&
z5H6nm2q at a%+`$7Z_<#65uE4r5>T`M#ps1OJ>F}yy6-{a4fVVRY;lahR4Gb=!TIu2?
z#iN0DDMYP|wiG`QOVa#e;h6q-6QtwnVIT_|QcJleC+83FeU+uDX_Q))#HD+0!8tf<
zt}07Q8HbU3QW`DX_-DWH@}pWW#~1AhRYr#5n8M+}D&ais{_Gh=Dd7hr7>zgz(gGo*
z0Ej_1Z{F-;Wn)uf(8B@=q&QsH57%aAF(_7nkTL=qOc-+HYI`@MIXyl3nS>MAP!Um#
z)BF|#$vnNrG*ktydvK6AvTt7YwA1F8gJjyImLp;M=!Eq2#|hKp2HG9*%%Cv|FjX&M
z3pYJsCO(ORCz96Pm3o;#?r+_T8v6mIf7X69!CtM^M2n5x4c-BDqiPdl<c4>>XZ`Wx
zH;_#lgEOA?v)<!<Ny)~P+^}eT8o?d_x=7u$7p21?a7aV3c2infIk)YvE~%vT*AO5}
z+_d%bx at j0WJ$9EXqGaRu$Rj+_M*O$aQzp;EpH3cui0QHNRu~MR(1E&_P-Y{1m{JMv
z at 0OlJh-wuX$0s{XBH-viHg^e;E&Vl^Z$QP-vSHwRPe{wJZ62L~YxUJ;i2Bi5&M({D
zlSUH5mNiBxwo7g(HQE-|J-RovIQ85n$dc5;!a}s(Px*0p8bMV%J~1(P?n--ZBgK_)
zf6<1*lW7)L!jTYf8`&n?ViZzF0xQcUXdLxdod~Bs&P4!6>iYF|ka95eh#JCVBYNUD
z9K}_z8v at Ge6b>s~!%Dv2*7~8|tvN8#I{#<8!TCi8Kk;)v2a$*FqU2Aye)5rjK3HA5
zH9NPYp8lFcYt+u<tFk1$Fp$19wY90z;kp5vvxzcmtWylr*@Xr6uyC99{{AiC at StO3
zUgIOa+&zY(0MhXi!0$FIZFH*T*j~2{qSqh>FGQhLMT}kj?gtYD>7R&0=ncT+63#22
zU=d!q!p+ZbJj_~li=7yOwxsxI)jT~qN^>*Eb7y%BULH&eNauiw0s<~B?wyz}No*U?
z+Hfmr={`fKm7}jR-Oi}Cj*crNVLs6AgKF<Rs9`Gla>Swj(!+;E1av at 6Ev-ZxbmrOe
z1&c&mHuqkC7|a7<?D%q*lWI6AyQz)ASUWZdM$mY9>iE{RU|a(M+d;65w&z-%d++!$
z*Ll)QfnGYX0LrmY^-C;XJKM{^76j+vAwAtNI0A=QeC{D#9f9yi)({AuXjw8<aXl)R
zM1Odot>7{2?`Z@(cB-nDfQBWAu>C?`SI|7W?tZ>@`qJ|97%V8jR?z}K8=Nj`I{iM3
zM6`ck-MK5 at fT|hDIQ}v<>lP`X$pyn8!Mk1{1LU&W+C$h<;9C-ol at +_ZpiCnl7gr1=
zOzrE}Ly$DLm|RG}89;D88d@}pwzIA6*AUPQD-tj<M>@!KEWf0HnHu%=(#g8#I(ZEy
zj(E5P?!gNn%ggowpMlGB{_>FChy68WZb*=XKIjuVcqVN4GA{1x81CX$Me|uAa1p2*
zYGq1z1h;G=!|>H~wC|Jz%OxT)4#afBi_#^O3vURDGXfTfl6QiWwKZ!+XcX*@+j?jC
z4v<!>+JJg|z#@Aq>_dY5!!@8cMHMraNl}tFfYdPkvP91Pva7Bt^txt!%wi+DNC!@w
zhs2?Zde-+1NeYb;DfH1{9U%+m$X-AY^oM0&3Pe;5#7H7;(f~m7zyXY(ho|)u`=xA{
za$L%2k1LcoM%MLabCnZdlZ8wB9trNWu_lmwXUtQ5XD=6$P|r#lsz}kgpyvTj>26Pv
zKr7<pF6nG*yKm*L2ZlYh3fQVdEE21y$ggBU*wD}+t*=%511{>udR<`Np|)UDJ*(z?
z4w5o8BbH})?%;p$)iqxdyiAGnbZ*`HvLD$?sE#noNqWh;-_j*bCJY_^hn(}5`jnP|
zSlxGdpR1Q-C)Ak_TwNy3rae(VhaPLhwMaQ`<;pc(x5P_Sm`Uow593VR=~!{i6OMed
zl!LCiu<dwtqe8=Z%o$olZ at JJd92C*r?-1N4fHSfuCbn!Wp!p(8&e3_Gs3SJhYki<o
zwA8>FVGLCgrZ2(aqd_rDi6g-C|6E&#ju|#%$XhNoL|jY^Wn>GO>afaI2z_}!+jQ3m
zSvf|jCz+7t4PjJ4zg9A7R&l(+0U*07S9s5p+*a+w7+F{@b2o;%iuYNt8C_z6H$j5u
zHMGdO4^B;XYH_XfM5-r|BS4Q^)B^oum}!tr4<ZW6|99_p48~v^fq!`ngTx)Z00oZX
z=s+L37|aYPVYpwZTR>(Qr+6f&j at Q|W at tDH2y`<vM7TDNLg|t4DlImpd71>deTzVLy
z5>GeWi;yDs3zcvI&0PM$5)QPyo^mLiV?CCePA^`wtH-fi1IHC1OF}ogroWrg<_R{h
zQ3RsJdV3Wbnwn&qPJ9MQ3JWJHm)gvR^lolDbF%{f#x1Je^ADSNyCIW3OO=mNb6k6#
zS;1vFp+hoow4RjnGLd;8Ue|lI1ap#J-1u at 6D~%z;Bs<$?NIMR_X2abX`{BZY4-U~{
zbL?Sp!L$CypJF-Q{&UmfL-uQ%g}MI|e8iiiyL!!~ASkEIQ5XtVP;B-;W1(=n<?k=|
zO7R at TuAx*%sS#4#u?TTK6sY{@4Q}jV%DT?0kZB65VBy~{?@}QgOOX#~@@L^9;zD3Q
z{%Q*)jg65m-{t*FGET4ZT6XOzSl)0jV!?3xl?WH;WNG^>!#Wb|nK-l|5QM`UylLwM
zo~%QY&ZfbHwXwD)ZI42FkV8?weCIUnWt1AydJH`gNeq=FRdUe<7gdfWUlbnX3^!aQ
zz{!nPw{lYy!=Wbv>ZG%|Pr}{f at N_W5lb&+<`{RA#4<$zOpO5iZf7wqvex$J%Eswa~
z*9TJsRuv;mqK-JmXqzD^e%0X(@P38gzc<Gm*>1Sec8jW<3s|q2^xv7fOo-~_T>lOq
zcBGyVH+gp39B$266 at 5}uS0}i{DCvTX$9_s at r2*bji$sx7tw?<IS#B%~(_EVOKwFqH
z1)SD4St^e{I?HZnsCcozCXFuSWRHItn2hEMOxDT!s4BV+-1alB`t>`B1tBLRWs_Er
zegR~rs&33Fg{&K>9VD=SAi5OdU`&LrR6QcZlB-P<Y7=~Nt+%hQJ)D_`)RxQ$$Y&dh
z&3hyUNg(*Is1WXweM=s>!n_7LdNMA2 at 2i^JzUq#`A;Ir<R<$!GHASqLyqJcaU^J9g
z0C}6B$|a@~R*|{j*z4yK!;F23|788(TJuBIDJpV%3WMihE(<|W^`3jzX at LJiwSNVn
zn=K=_0w%HvM?ILa(pN?nFZ?-+!{$e_mp>Z|S>Ct#B4KTcbch+Uz~6&sQvM0ro)0<K
zY&v8c6&61KioQB!=sVJuPbg=5^2U~);|OE^;NK?dnfw<C^3BI^rn1en-{tJ)Z|dxF
z|C7bh>EY_i+ORQFlCC=enq0-Tq-q_I)?RODiiI1emyO at W-96E7O0-Tgbos98f+?vz
z at 9uBj$2;rt%yk)W1R6iH`31|B|Lj$_XkecRz0G6)8mAtCdHhA&!aq9163Kc+R9ig{
zlPGjhhJcHcQ=tMzjSt^<n^W7<hH)7CV?uu(GhGuwZfJ$JTb<*Vr0JT3+gwvqQ&qSH
zz&-0HfEz;XI^3~R7^!fVyC<q#scnUHFM(E7seIsN!teL5aOfM;R=-((AhV|z<(2<O
z=ls#+4szguVmD95jt)Dj&=-xsVLGL~eH$|gGqS=-eiRh!t at V$jFlhy2qwB0NV^382
z`NYNFgat%sf^aThcyi;tCGBHd7(~|jtp?2YrVwogS71YOFWzMtk5xlo#Zd6^q#R_o
zJh~qF$SJ}Zo-60>iy6OK{b!JS`IZ!QukumkjiLK+*Ux8(eHo2&)$I^SOiFU-KlUH0
zdyY-732 at _30sr<c-O|d^)|!~1e0I)K at A`^nnz#c;{<m~#cD{%1duU5YE_S5?t+=!z
zlG3 at s6sQRmM6N|><5fXq$9jteSpFq)gPkhQ&!mfcBpzk8wc$^dw986mjN=p2u+!88
zy5ufdiPGZG>&Knf%X~>jTRzzD<^8C9*iC*d_`u;Redw@^;KxXXAs3f3B;`5|Zjvl*
z`<L4T3)d4{ki=nR<&lHDR|Ox?jxjdViD7E at tJ^Z<uuAM{YG{HRqkkTWwk<+!=JF3V
zN2a at EAFswLP=L}qdjS|YGzCv;JL8#Ya<aFQ6|m~$z7t5?cPCNln at Ixe=ZYa+PyZ|l
z<yivi+Wy(u`!{t(1d9+L8Ncm&b2hBny7h9`B2+rJrT(ObhM{e$NDXdr8}5TTf7E1s
zYVf0l^sk}v2kJW(p5op7a=q at lzF999<{yWwQ_oN-Iqe_TT~=B!rC9bUdjez<;3^ak
zr)>58^Ykzl$eJJO8zO3|t3!jX%6O7iggU>4Y3V at xF*lWc7j=CXTqnHT++X<t=n8I$
z_{lI!2MTUcs#Yju9Q1GQ6z}Y~rLZNwM<S7Rb+jCFtE-NJSN348R?glOe4nHXIx4y=
zI5b5~3YoG#BT$SYgL3Y_Sf<BRwZZhdlP21YyfZ2YgV_|ib=*$Xh(}j<0SVM~qfNTX
z8EkUqPK243 at DK*ok{JLyqpRc_q1))YR)&@J5>>QmP~%+NMQNiCBAV;sLQ-z?`9?);
zrzJ=Gc%J#hwO<v5Bevzy?eQp8)hxH$+>QpOuT<*SmyF+E|1r}TO`4TxxRy4-R(p2a
z<dnB&_(Ej&$BJa at 6Rr%0r88e&W+uC)-`~K$cQi)CZtO2T7w3wPk_0apayY)L$y)rg
zcu6}}^=x&1UI~rfX(lf$E#=oqN3kGRChokTw%~ON0GjPd@*A$Hv56%|Zsf}9vhWJ-
z10dzP-(`~XO*zjl!y?<kO56BZ0g4~c|D3FVQoo?GEHK}h>}&&g`Z80t?$1wBza?xb
z@=IR9ZO69dJPRymzI(+Olobc;xntGU)F}7#mCHkCU5)8wAGj}R&%}Zv!sY!kQ?4^_
zEuDQG5Q+yg`@!_cMPzTtEcHV9{m?QU<{}4#<t==H1M?mQBxes`5y;x>ega>)Or;ud
z=M4H%5(5f at K`$^ryN5lLDf2OKWs9J91{|vE9lg73=6J at Q5f*EhCS#2|q^(u7TSx6y
zi|69mQz-@<ad~|jt>r{=u|N#eN~-7?RYAA|e*t73am_+x0rz)a^>~i+^YcW4VO&GO
z(*-6}4xubYc?z;BdnqSuiI_qClDdWF?`(C2V(cqqH>O>YT<_36tb7?6Oq at UEXrnq2
zkNz?V2Au8Fl-MHfG;Xe}c$tFrg0f*NG(bT)#Lt#r4s>>gf3*MX8*f%@cD~jm7JB}@
zJioTOdXc$2rKi8OHF)XgrSxN;bX}SXBZxf65<oD@!1>}QVf?|w+SXQ;L057oe)-!^
zNE>;5D(E;#=ob#t;$_Uv-uMiy-pRwaP32YPulkQEuHu?*Uv%x=2xkn<(XzbQ6RXGx
z9<pNR_Ib{*tj@#25-3gJQ~stV%RApCm*r6>B7Z_b=gC-dN1S|D&BazU{DGZVV*7f7
zMluCGeNW>xof)+P8WPbvG)f{t at h%23#G(P2{@$y%9#b8 at D-ekF887lwwcV*GC`}8X
zO_knRP}sFfDljRK|2El8<z~C1oIA8d;N!14BYNZb<xyRq0 at gsK?q;|ASpq6kXVZb{
zObzcKxcC_e$5fkDKE$kC3aR+f*B9%*USta?DYqPY<$TL`2nh+7&0)*uY9evfPPB9F
zKD(FijVU#|?n$SxUZ at yp`(H9~AFRKM$|m8$G*y-HIrug(AS5M~mSH%FThDK!{)Tk@
znbtt-G!ee;UDRuyliS8S0hmbqWxcd_S`}g7u8=LCIa#Ue{jpuv`+YvN!C-t1-!tlN
zae#n;fOkjl^K2Bf#Z_DHb(IY$0^qE3R|ET(k+!`jZ}~-pgkA<6K at m^cCg3-NQ^>-F
zSx>JV6==)|%?yM&uE*N0lA*w#5lHO^dwbvd`<sD$1Wh=&wED$P62xM7e1&B7qwspH
zSSm6yYa1ISqDBZWKH2RiW}>H|0VEwnbwp1q0Z30~lG};RzTuhJ1*vZk)nRyGSPM}l
zK#*ED=)9n^74 at 08npFP&{p0)h(P8#QF<jB{%<^~c#mIjC5l?x^B9>KE;XQGW_S60)
z90F>W3j(VGJ<(E=@}LbSh4`gCk3aFZh;(o0rrmee<b2)yI|~5vVH6;7`SO`i{O(l_
zfGa at SoHI2njTx)=m!|;z15gbBZ+K>q1Dz`6u?m6F5HYNXBY<avfY(YyFB-AYQw>*{
zH;2NMj;k-g_b}SUFTE at p{NEQ+-k4>sAi_Y#!H&$4e+!>EGBDr(4vc^t<_a*8N^x*3
z8D+K`c!B%`#sGw&!bu+?5;-)q9VQ%!%+=afR+;2K2M1p@`fEv`&oba;l3ukT4`f$W
zxclH1843dfBgq}yh7a5XE`k>ahlYNR!~X4;zmNfkmv#{@1ATootDvo|4YVkZR@`pa
zr7f0MR#MZ_^mU-j22|w9RJ|BG`vOc{90M>&Jt=bWmK_PXFzGQckUKDx?Tj~tESiy0
zaB>0X5Ez`7jt49NG)mc!_!(`G^M)79ei#Msf6<J8Isi10^RvI;XytHzdQ3(}w$75P
zK|F)MP5-|?6d1 at y<&PgcFyIJSm<8S3%C(7r1wdgbdknkbs(T_~>*VBg{^<x#X<G+}
zV;EGzPtDKELmLu$CSf=S{`YLLFfa_6+QBMID7kqZ<2l$Dt^a}<Vqq4<iuX8u85kPM
zdBr5=m<WMX3JPBU!qLf)3Jq>TnEbCVqXCg)CKQ!eW9{&OUYD3w&s#d=8|S~8hJg{x
z7LRd1Vd;|5GocEeIp=P4Pf*u7x7PEu^p1LZo&MUacd5vejkTVMqZRf%N>FTVpm$#g
zt2rR>G4ohP=^YXIS>V}YV4(1zudwTE6BH7%cE0-S!WMj)p<&&H2X&kogpYL0O(R38
zlVnbizb3C2ensw8T(Z!$)p;PiIh5Z=1HP9+qN4P2Puj4b5#au%o0jK4ad>$VW+kEK
zJXU9?v)U3IPQs|w?7JfTchYlbiI^iS at G=I5c1xVy at 3}c^d;6|ZJ2^(i4C~e~`0cKA
znqH>5X4Dz at UDAcy&Er(5G_U4$L24 at D;E+>k!Kgp#3oHD;r_b?+dyP*IH)ZX1`-_LO
z&d|#Y$u;(89VDj5?H>vXB!I#RaC|_(#Sug<yakozCSE^2l75&Sd3fz%*hiBsQNPVH
zXLViv7wag8^^`xmvY$svqk$n=Owk<p&r at Lmgsi5vR-H$g(MTQZ<kom<wS4Ed)SH=6
zpPVM1PsMthnEed-aAg8oKRvyd+tD8gNa0&-3jh?qA=m$-3l(_rl`kT%Aq$aF-43fK
z^pL_H!+{Zh+2H1AZD+yxFA7oX&q>yI*)1$&cmGfTJPVFC;EyCbch?A)6?q9mfv(sN
zkXLg?r#l5sUivOozto7s>T+0acui@{@MlP6XNe_n<GMTUl$XtNb~^Cqb6`zWIXrN*
zSz2ACW?=9E%w;ZF at 9^J`A|ZKk_l9(POe^UNUF8W=GrTQ6-51{88$NW0=lv$TKSieA
z{0(<H at vs|zC)56>B-B-=;l8 at BBQijeY8S;iv$DGCvEgX%<V3-A{><3;%{Vg;<0T>t
zj2?FpQJH5h(KcVKBcwkrZEjANyx*S2^tfwo?h88%Vk@?{w;`?ote1Kq_fB2Cz)oj@
zY$iU<M%oY2u+{VB$G}=G#}ir4Utb*BxBX)O_>3%`H9Yf=o at 6SMbg!xW8}jE(qtCw6
z)X6gg1CdU;JI$v%nx>{{`HdME|NMN&k(K`xB`ab0RHiYlBqxXObFBiqo{`mO&p%-B
z23|_0HBWv*!_*neVCU#qTv{rSq#^x$d2Fh%bK81msI0oCwlZ}|@JFgtIs?;3x!vE#
zWwtNwI!|;HSM`-S+fEG8H76WbsK>v1pce1pn#w><UIEiS7<_}o3Ew%KLs0<>BT#q`
z*Q9(}(9rtU<IQK0im@;ZxA^3CT^WvTeq(;v!P~ZA+CFv}?xZT&3^HcEJ$>{N(^Y$h
zDJ6Ye8)KmtwaYCH%g5&5k4vLK$<{wVuc)q>|J*~2EgEQoURp>(OjBE2OnL?0fBy01
zOC=Rpmxx%Xu|+X3ICHLC@)LSi&@lANS^F=c_{zrb&7;v{<tK7d!_FSa(Gr6qraR(~
ztPWGQTWcN6Mh8zL&s+^S&QbkiE~~i%G;!;*R>L2OT82J!9Bln?QgCLslir;<bXqdT
z$CR>tRyX>#2!G&xUFwD&4{rxy4p_c>(^?Q;*r?LMcPVH2XSEJsrRndN<ZH`$mLAuU
z1&62YJE4&NxKjd~8L!3m%AA`<{#NY&mNMNKugW&!oAxWvYYpS^{VneEx1>q7!QbhL
z2~Y>#WcuyQ+DJ8Ut~x}j3{D|mFOJR45UtKs-G*T{y(^qgxO;I{cL%v07yr at _SJE-;
zlDS(3fA at B`%qf)`-1)#oLFMe^^gqumrtZ?&^3Kb6`IA8MV{gkV=|4&5)&JC^eq^aI
zp{kxZ3#FAvmDv(y<l5(-+KO0K7NEY3?Dskx+v|(+8Q?yn at pqY!I{*18F#lmemH5U)
zFpu-|yk`aX+<tq!NYfILR`p|~|K}Z4rGU09Iy(BNo4@}#1h8A0Td_(@|Ah<s>phG>
z37yHnI}w(u8T3nAEq#<$@-+_;&w7@&U+n}orKNu>aU3qo@>jQby3pv_jJiB`zN`6=
zc`Es{knf-B&r_$p1sk1&7h!yrfp<>%avffG1Z#U=Yz>k<t at Q5*+p4ucKTOhk8rE~3
z at yI!z-m#~-%9IKHRtn7&O5wIYjfVLR=ValMq_p&I>0=;9!e|EUzsa8-3Im=XEFnQc
zO#J8u7<j=*{$QSi%G}%>6b(49!DTt0CpIdI{M&1&LI#VW9&r_+Tyyt8*Jw_lT5zs<
zQ}gM?7E{K+)YO?#=Krbc+T)qr|M=rFDNHFOqEiWD3PUAKij>N2Xu3+7OPoq6ml+kE
z2`9^KMJsZvNpiRNopL#13>C|z<RsOYqTFVFpRLz<)!83=&Fp!e at AdutT;HEfJ9<66
zyuhNf!~>zwmCPAwVeGq-R`eCj%0d|I1a;GQ?X0=BUR-mg&qJd)!_yy5w)yg=u{<4q
z6?$QYy!5>>bN*Pqn%7Q=y?X`jT^n#Sw77K(-UV6K5p`E!9SFW0o(SzN^J{qXAXU5%
zKB;iz-oI-BIyqLye$E|AmeFxLVii=O)7QTbiKy0Lle;PlVCPACdG!L%>G`jF7vb*g
zDK0IA;?BQCC37mS4s+i>rfdK at xaEP3oY9;z7&rEBLHO{tlI&ZS7uOs<P55IQ!;3YC
zj*69>t+AP}q6sL%x!uF{9k$wMwi0i5UMy%+$K|&xl3sN+_D=#qeQRB(or1axe#*pb
zg*;1Afsye7%K$5mi>vFE$HDTbNyx&UHUU5Tz1p1g;r;G*Sm_Y3l<x&!=NBD^GiQw1
zT969&U>l==2R<cDYqCMlS19(m$=tl+(IbEd68f}M*cJXk>gyNNvO=HjlZBI+*R=`q
zBieGe{J7jUmhJ-LHCMOCo)jB at bjgTlKTZ0Z-8)NbOh~Bxw5uiXrLR_$59dHq)Xu_9
zBFJ&RPXVe-bi*64LtfS&SlK|a3LVqvm)Y$?B+pLjrHK50Rb?Pu;hr6q5`MTHMVbLo
zEHK3z54ruKsxFX5Odfx0lOR0_Lbk^0)gSLp(=Pj`4|A>54H!T%jx{ha3m!1&>4fs1
zX21+#_oEZDJ!1(kDh<&peewi;9KT{Ej^W{;EJYvon|W2>7BmWIgqxUu`=NIt>FFcR
z%V_tRDvJ`@@j7);-BV#eXZP3h0g<zhMlWCQa~xF^f#eGe103|B-<JeLL<qn;1c8-n
z`|jrI$%Gs{*atp32zxl-u9+?Hh%hlWCJn==GTuY9R+n-AzH+J-=S2xHFXPP3j}#w`
z1`iWN;sUoqp%&*d_15sj#6(pF#2t3YvmeuVW+GBRz$3`)70g$0<$56gAjB1f5V~z2
zCD*7YClp4z+hE}fUq8bmQ9Dudq at CZ*Qlruws)S_|SqU57e(pk;Y0dQPqt$gq0^U#(
zsj)OzvE0a-p{43`F6d2a(Nw*#Qt4t7khblbigyo*4*9ynKXBu^c at Q}Vbu|#W15=Vd
zYGnj9LVy<@vyTV`Q6R=vImqMe^c>!mDI+7(Sq5=OC1np+b3#;zDH$2f`vxjcKWl8v
zwUeX=DSeBCf<orYH8uB{fXMOQ>?ojQM>cp)&v>QYxB={$Q0_LRIT!<{&DpD(oQigy
zmj5dcmob3%N^_LE9wRt&x9P|OdmZ2(2iAjm#eo1#o;m*}+44<rhoIvGSHfIcD<?Un
zGTQ93d+oX=m`vhra%=y!Q2G;gRPbG0 at yS)TWW;#p at bbXum|!p_4ZRUKZ+^gJMz(C(
zy0x<vB<1NETb3QZrm70-Sxm9;IG`{p#g;~)4tRPN_wUM2hB6?eSg#fo4hxK&y?uSR
z`iWs at wzs4i9>Und8e0hmQi4fbd0^uB8x^(s(Z3vrhQC;*C2klu&!zzg<rvqdSJ5Ir
z?fyfsIrO8&x^AXt`YNrz62CZ}+o!(G at Ndj@ev0#-wEDWz`&G at QsTN_Yu|7O1_25U^
z(kIk8+>T}cVo(I=m*CWe!cwY5`CF(pzdNmUB{kO9-yp1GfI0;HE&gK%PnfRa0P{o+
z0a86mZzU&hZxO6>oRFetT?XmI7ovPYS3Ljw?@;BvT(rwqfJm(4k%W1r9$R^74E{Pb
z_ymQNZO at ddb`-i8_I`e=;4Du9np-PC^O9}_(kF6*lv(#teAoLf_VHlt9KIrUV(QG`
zB3v_ at eUAoAl4Zrkx&{V5G=R8-PX1>r->wRM84c0hZ;&IeU71orUMx9>2F at m7@AKyv
zV`G=fyTdFT1B%Wx&wd5-T at 01!h^K+&-2hV0VKNeAaNM#0Rc8NVU&Z-7EdoLeWdrzG
z?q&e~2FXY$Fr0JupS>zO=`O!n{`8`Ly{=qOIX)K2SN2!t0O at VtfGqIaE1=O?I6ox|
zsz$H&EKq)LymjZbw8T89hv3*w+-RM@)6efCloE)DjO6ZNt(b&<Kr28_pa)&Fv5~OI
z$jY*UXogktBuqF25nEVT1o at H@z45?xK?_n`$UZhLk$Ll`x~l3_VG>pvG5r(5uEq&z
zPrK%n)zP*OY(nFr$$7j7ANZz=D8yVV2?*!_$<do?4bj^E?of>fh(*WnD!lPlQ(?6p
z3YSvkx`k*47y<rP)f+ICyf7&#DFEtMMTfjHD25o!-2^Na8yOMN*Vi`!RgNdZ33xfj
ztZh|*=qL!5U}u^e7+gC!@`f5ubCoCU6i~8Ee9@=&drZCCfH2%g9_0rI54F~hy!+g=
z;y60ntSP%CqhO&TH~68Z)xhDWbBhuG_*rS3?Hv{z$LZ<mV1mQA1=Z%{Tqb at 8LI&2U
z0KB`q%G8ztaQI#7bxuF~u6}W~WypO<46sRAC{%Q5Zg00f^N(z35xC(v3gD`QQ<4OA
zb(Ap+OmZttXa96}n+8}TGY?g+#U>b1E%+j0lvp9Na`Tq&gBzoSGkHg|l7cXEJx`5i
zJRq%L(k at 9^7Aah_b?fVT9|}MsBo~B6H&cXy{!a+wdw~~7$Ovoq(W7fjb?5aDN+3?k
zumlm#3V6?7_TwX*BCuoe-^99#YcYkKtyPRd=wcC{E(wCZspt*)<)eQQbQvoxE$xH{
zN{7Y65=f!6=qLU`;G6-Hixcl9*oUKY)#$20OAx2UqQ^L$g%}tJ)pu*{bKXqKI7vEO
zsfXaT#lkB)1xl}}sW}_XL1r|*tFF}1WO at YwxnL>2Flu06;6~e_>X1R<J+(nQuxMNo
z>9F6 at px994vhQyYO1D_4{pLX=zAkXpDav}ZAcMF8J|GA#CNED%mD3X?g%kqlA;_xe
zI at Lv@Yd+ycx`Q3yHl!dm3Dps&$RDG@^VAUke6hICF{2I9^X3SHF4h6`z+nqvqd&hH
z=L0>`UPs5$($dPQ!DwA#S*M!Ca2%MA2Q8(MGFj0*7M?aW<psAtL|>>ND-j>^R2Roy
z9rE*hl7MDgd at O&y`Oo#N+X$mvJQ5i^Uf`v+>d=@^`i&Z~o<qf6G{b6ad)9O10WZW!
zU)+e+kVQ47=e2ar06x}rmS>EPSUnAwL;O*q4&V6L-7+3?#I}I~x at Mm&iSvY(2r40k
z7%dvJ6CtHuDsjiVeN)u62bETz!ir%{JiE_#-E(OOd**cIx0(P1FE1W>yAx7j%qu<(
zJs(<na~)W5d$Q&Y`f}+*?FhFa_L^$j{l8%lucAbqe4ZbOpAv5WI%D6S#td`Vb-MER
zoBoL`R7w2HIk(LZ*Z$O%E>S=Pp&;VMcKk!J8q=%kLEm2df#3rpP#+_1<|lW&Z?(g0
z1+9K><gu0=_FSLFZOx;2?)GGw&qqb2{{8Fuxa*nQ2DPi|T#Ua3G&k{g6It47zU%df
zLcuju{0Y_G&vJu=U)%SBNg*p?W{NWm;%B_jpVwYoIMqC~wE0{V_vEP6_0n0VcUC)$
zTO2z}uLou*RUNV5&Y|ohw0r- at nwv1Ol26Ulczxi)ON_BdX8WNgp3`UeaZgin$d=sr
zra;1=u|u|uQXIMDgbGIsN84Lc_L%KsV!PF0cT3XS4ubvHfnMeA&dNJJ-bqv%#`Kr_
z7&5pP3#r$_YB3jX at qAKi0y9vP7qY2x2ZHr(ayM0Z$G%b;`zMdBy>ElE4#EGIK{|-<
z+Qdl>NwzvNHbCrr6am*6Jf_Ocu<gufBc4Vk1$lw7;WpLJe3P}}2oDGaumqOMiO0Pl
z9`@%sVZZB{Hv96W<Ig58s&FP`2nS{5M%L$1)ok!nGcF}xt(61*^E_|7DmD%0ryG8g
z at xjUA*=&j83ZIFG%Q!7fyU=W==Y5x-lkBQ0MQ>bb%k3~D$@5)|W>!fspa1e-dnr0S
zo$GzX=)g-#t$-F-)t>g>XSta%>_bx~Pt8SePcU-6#U(2p#&?w*(|1TqO^$ks*|4C#
zruUi!eo?}yE+3Oc!)~pu#x!;@rM7%WxuZut^VhyQb198Km+1(p!T|j+&og-CJ9M>c
z2yrc}xgT3&_M0*5ZMT!r+fDVWL-Hm~0 at txB;7s_jEkB~q2k at +%M2Be;y_uc6f734;
z(h>6cY<&AIY`*<_tl7+^au3*F7N6=O1A#zJOY3&6r9z@%kgHB&;)8)92htNMP5#vA
ztG1 at _=y9?n<+W(#Q=(Ks*6{Yed+(k$%DLkZK2*AY_0w=!#DAG+-oOg6L<9lwB2Yvd
z1wry9MfXP#yt1gF at G2C;HsCEvw1p9bf)N27yxb)Iy at gQAR<JxhV+<=V`rcvZz8yu|
HkH-8T+7g)r
literal 0
HcmV?d00001
diff --git a/llvm/docs/Mdl/images/MachineDescriptionSchema.png b/llvm/docs/Mdl/images/MachineDescriptionSchema.png
new file mode 100644
index 0000000000000000000000000000000000000000..6d2cf05b988f9bfdd74c4ef56f408cef254dd0df
GIT binary patch
literal 54791
zcmeFZWmMH&_cn?MNH-`Af~0_S!v-X!L^?!L8WluR+ybH?(p{VGE&&B4BqX+kv?u}s
zf^^qA@&4b>`@G|vaXy`KJ{><XaI^RNtu@!2*SxN4?pHcmDn$6S_!t-%L~5!xbuln5
ze!#%Mq{qdC-_*(JT*tt8hM{&-UeD|9O4=nO%FeTpEp2{UU#SaZw|!Jdxpc9qDl9+Z
zb5pNmeR>&eWQAuh{OL;Nr?T5I1p)%`8P{l=zFd*Ax=i4yM7kf)Fw%F!a7;@4ZQ#IB
zulvBaSeN?wwD;pl^^Y#Vr at _By@34q}e!?ig!6f?o<1-ut>Yx8cW8ez^^S`thNSwbv
zAuckb|M`_Y1{Uo<KM_4cT>SeJ>H?|#Kfe;j`2XMR|D8Rnx%=Sfr|??BrKKf5;*q(z
zxeD8}lRXRBOK7*j!ND<$$mUH6kKRAiO&z&wW0is0I1LRg$D3hq!`{$Kv~s|?a9Uq^
zhj_9yn9JLidn;j|zQ^le({{AXeEfO6>-4M;6>GrpM#$?QYb|FB?ga}Y#fHw~<t?Yl
z1DV>_Et*rOSFf*5)Y1vsbX~Ua+xQtF_wBuJ0>81(cuRoX5y7CLtO^TC$m)zvFUcZb
zE3G{@Bsh4Z`>-clCBmT0Y`ol}1%+aMBB7Zg${=iyuCo2?`t4o!FFyJ=Z{E!E9j;Ul
z?At)V*b)X_UOe3S9VRCF{7;@Av2AaLTn4X_S+if#fZpp^2IT4HXa4b8{otr5vXKXG
znB at 8s_`?_VP%5vlu=J0Qk0)uzTR*@|i;EMn{`4A$i1uZ1pL{2Ye(BlqmUeSa-QRGo
zh!sWV(fwK)%0JLJ at IKrwOiN=hRmVZ{@v-68V4Nh!uxn-!&Hd7Ce1>qksjRGgw7c3t
zWkBMv-4;S}U~EtPH`s4EP}pbr?)~x0JMK-Dh~c>!h`4;27Ow`Op`o$lX^&f at Tw$um
z+}zx(^l1HmK2-t9{)SPe=a;Xdk56N8Ft){qNbHG<?^r&k#|N`b##sKV<JI|vg<L5i
zi8m}U<ye`CxG-H1sWQG_ySh}Tu2N9M2v~nwnQGW-4JJ@|LvP&j^dyo+ at j5SW2Vu+E
zsgxW+>EGLTk1Gvxy3AZkc7~2!E4Axa{6!=mqd3ywuxd1%PE7L2pI$rG`;rf5u`)<h
zQL%X2h8F%E^p~rscnsDh=3J!X`OF>f-yhA>q?6S&{d>cW)bkM(un9k_7Z$!X`#0Tv
z at 8f46p^kkB=fq=JmUCp=`Gz4l{VEO#<2$bnt5*!+4ANc?mWK<co1R?m*<BuS+Fcp{
zHIVUZtB~5hN7`jVI5R&=D^2oCjg=dVgoK0|;U!{v(in)+tDmYPW_SNgOIfyJS!Q2l
zWp%hlb^r6j!|f%A!^Zmq>8*8WWz7s(^S+p;`l at 7$X5LM)iHTQ4IaaY`hv at 9tx3dYa
z+&~zKO=NBS>~x!HmJt$)8AxWDkb@(=YV7tUOX>I5(x%71Mco&Atvlar9BeAmsQ%2#
z$_nb(S^N^X`+D%(#qzuFx&NFUZ2bz`@OS{{C3*Gg?8<nxndtN8P>F!kgZmx(5C;)-
zVrBkEyR9Vhzy0QWs48D}rAoLL=&7o{d`rT6{d#*t<@CtO{?7<2X@>P)=}q|%TPv%p
zF69+JJfw$SWJtKb7}$F;|2ZM7T2oV#>ME1m(|0~Q%bAKH_(GYip={zjJUjun<It}6
ziSft7F7xlxyQykxw><cP$@Cdv7<lbgJRz;Hsu6`GgMIm6Qo(k`ZEo~Hx=i-;NWGhd
zC2`veqRCn(!)7ad>44MJr$hVuUPW_Zx%MOl%MFjtPETfKryAVzNe{M{hV+XKi0H+2
z5*3}DSMoGd79~GW!x>&>$W^dV^jJbw>uU~())<)9yPnL3 at n>ac2YU~$DRk=7c!yoa
zz^FkD<9pcKb7qK$CH(R8YZiNedGaeGV9-3|q&hJdP8jasZTBtq4m at Jwg|PR?oL>{Q
zPR>u2ka at mrYRZsI#=Tkx2cx$Wc#HFhgeS*wr}N$C_pF(iGR_{gAnlGuEdox&?%+gw
ziL5yXhlHGM4aoV?jHpuD&vwUfl+>c#J|^dWfW!DXI}5ii(fBl^sp)8;FQwrsrkLv#
zbKnnxcgUPO4%6S;Ur~6NZ8XdvX8ReGoPXLG8XAT+1f0o^V6}HCh7dm-w>g+Z#B^3{
z=%rrI=su#IxTwe4)73>vKyF}Q;3tbC=p}F;>4GXe9ELqQ!~Yc$nxB)iZu`hRMZ}4H
zAu}+ZSg#1dEn~UFnRPLpznsuj<n5N~RkjUQl{b2i$KEzHoIutxBU3`MlhoDL+V;GE
zvCtbw#r)Cy?Sst0t62Igg^b0Ee^v<SASiPacYcpfj*Z<=vQYfPLz(}ZyfkpO_VdS&
z@*8@&6i87O%>Z`2O1;AeP?&qfbJbA|DMNKGlVhocg at r4;F`s+Cv5}LLkFn|3IFCo)
zp}x?lNlQn!)v%@5+9S)ofR(IQ=)JYzOi1wR%X{Cw_NqZ_A2<j{gV&TlAm*)%k-VmL
ziAhNt##@RbuQHw<zTzpsU&7S%+navkya0h$QTVGr&1tNHB}Ja=XJ^DO#{S&gTq>hT
zVyd!(l_LFOJ+1^?hVT_3RV@^gjL+QK+JMcd21?9jBBy4Pb+FFG)Ic#z9ktY{?;O`J
zPgf?6Nx*}S?U9jQ(3wx8H*fN^y>&Zx{$t=JKlWO)MvubV*~%*#u?iwKyA?mMOe&c)
z;-PX067&Z4Uw7?`8_ZH7_;XvB13mNfh&Lwf{zQ#~htk#gd5Uk}mzKI^S7zS(K0)5E
z*EsDA9+We}z(8HUQ-sy162Vw%QcK=~gM(95|KY+#oR at 0E#KaWr8l){fn*`hZEyq_s
z!2z_lx1-azxVRkFzkgggQWI=QeU*##wbZoJPUqruJm1}SoUyZ5$tRQMTtareqzRn2
zQGtPh-5zJ3^9lc~9YJz<*mH%9Oddztd(-BTh-mt|RM$_=#`^YbXehbXLL_kQG#VfO
zj*p3<NLl{<`<7fMWMV1?hCV!|rY79vh{T&mL2PkP&B%M!*B@*|$(=|#S5p_Ma>@?g
zQGf5V)Bc810{LgAMJ`5wBpho3N?&&_eI3*GRkFpF)5GEqj)543V}*C}$Er#YF|>l-
zaR at mY{TpMm>S`JqbNI<ADV-f1E;G&Mm52FVkf;etq+X$KvryY$H#!XEEtB9JmX7m~
zXu8K;YAhmTkc?fB^V@&WNL{JsL0UDCX^hOfV|4Op3B at 32gUgh{BpKb2bZ1)8Z&!l@
zGi at 3V53k0+gVEd9w>npR3(%s at 1Xl8&y<S_3UAV#o<Nc`;ZQp#UuNxuu at Yt<ok^TMs
zu7f#h*~;NvFB&G5eS9Q~u^<2bYU`VHjbZMT at Y<KDO6yLDR at bSwl|DO;jn!3!R at UlT
zC~R6W*LTk2RgePQCThAre-6{U%0PCR`!-7H_~c}?#MphVi>!#_LBy=li4WBIu&}U1
z8#lKBSwW6P9^bY6Uft8+QB at S4Nm*h8Tna0{y+6|(UW0o~Pxp~rvG>2Nu=@2dpL(Bc
z&fhX9Z}^p$z-PWZlpk^ZZ0OI?-kN(ra?HH*WZi0iniShOov8Er`ue>)N?-2xB?{}+
zxL3vO at 9(>{oEX^0!-BA<rluAPR5dko105k#M at 2=My(l%U5AATzeSfn+9cA&(>!YzR
z0`URT*U;dgecNcc#Q;Nms$J#%P>j_JMM`Md{I&>UJ*~cmme;Y5P7WXImkXc=Cd$m4
zVC7sc+E>w#`s-c-lu2Xt_!Fb9Yx|<;t}{1- at 9fq+0~B_bIMnE)^W?miTTr^fItj(6
zTCK9OawSRO(p<sq>@mV>yFT(eak~v_rYtLMuP8XU>o%ji>G;3ME6|9#PIaYs2nLHW
z7Yb^KWI$9s;>}s2?K&Y->6A$MClP6)+~)&*!vt)&TN%>)F>m5WCnXgs!!KJ)YrJtD
zZZF=hW1j4ZcP((%H8Z0h^?H^QQu7vWiOsrm*xmDzATjwV`DV<t?x2T&8Y?nylA~Ds
zGXGs0y2n`9*ss*su3AY?=NK1Lu>88WHnZaUs0gixa)@j1ox86v2jP+EJx4)IHZfAN
zy}dkg>m^5%RcMduo2`V;KLgH=nDB!3<F=pkDvS_{iWth~)s&a>>&M&YzjFIL&z&gn
z<LA$8ap`mqr0Y;#A0)M;Ebj+R!s6nIn!K+O?wuq{Tzjzz1}~hPZr0uuh at -G4pIM!(
z7s_?N-<$Z+E>Y?UUrG_a<WKx#{#@J7 at p^J|{j!pU<85)fI7{Lw$SY#5^!g!P3`>Uh
zq#_rvCcb`+|4p6uWbK<XPUUTiG}n^W!BDQ%gyb at FD@G{$Un;1ulY0|+3&wanp|tu&
zrb>H9PdiGgCk=XQW5qTjlZz`BF5(b=cgMg$(Bx6#3qNTys&%B|;-_Ps`Z+>SL#vuT
z#&LhfZ!4Tsdrzs(Tx2?3pX=?_R76ZTSA2MQxb4<EzXRQu34CY>!c<*S50%S8xcrTH
z6{U|^uU<_gKe#tt3>m<$3NsmBcrrN`GO)rN1P-6FiIGvk;aYmTNw2b8(z?Y*K$GpN
zR%n#GqYp<{+}T<G>5`kZ_10WBg=`GIxKLh(z5@^TD@;vHpI`k9c~egIMC0+ds*W$Y
zTVf^qlf}oE)fC6yO5m%^zo<{#!KQ^WuBZN<yr_{bo%9(MdM97&@gf?@TTD4Y?U~lV
zcU}Mey&_5j)RI-z{Q*Y4iz8u)-k+&?P1xGkrW#_x4V}68)}e8!8ozl4MQ(ZS;Pb{M
z!2JLM`{p;cwkU+q-hH`6$W^?MlTiZLIxfn^sblRxxRzsLd;WfYK^zEdd=CQyYVXyt
zO6zW^;Igzu&*;cV#FLxu?(UV}bJSvjj_>!US}t%L0TkLC&}K+Q at c45?^d|PP%GyNp
zq1Bso?aut`>gz9GWs>E}#g^QQ=ZEN_mD8oMVq4|Da;A3i%`TwKzt#w at rbB)>+N
zh at 4G5$LXH1OwZAlMV>ug8no?87E#Yo9`YOOC7*dr at qJEt1jR^>EqUWcBv&kn>#gx`
zQMJ^I+uI&>6XW^X8OOn=fvYu>!^3*ct)KC0>g(&R=ELu$3~@H!MlnWfNq%0$y8H{J
z3SDD|I>BThzJ8Ff<1oB%@Q_Wvt(~y_o%dFd*X}bhK|yE>=mQd)kqqA*h6`>hJk&ys
zpNU}=y!c>8>a+a)9+R7|xA#VOLj&|tB<3U?#P~}d`_QvNXV)znOMZ3+IUv&11p5$L
zlcH~aP={k8Ro)}qrW^HVKP%5Nd$*kI($TfJPD^^eSiZgT>CHgqy*3lvn%R~!tjSYd
z%0;+!Li551&GHYJw0Od$Hzr$i0CXz&A=4B%l~(91*S@`niZCBDubC_5xv~#sq}s98
zZAMl!!s-%%qmK2b>yA}wl=gorC69JfzG7<XUQ;FqP~dW^a3<h?=po8c`kHhAzh-~(
zVTIegBRBeLO%dcf-JSF-qYm52A?SZ4&!q7Ym2^^XU|&ONY~bQ+O0g+CCeIY-K$}fw
znguuhfro1##5&sL=0MxbIUc&(Y(T~*z=V64?}0BY;IXK)FngB#{rkNQfkay5-6|Wr
zJxAgsl at w8zsp)B|ndg_WlZR8oIWnm48!=zwL_53V-bMio_z*jUk?Yi-6 at _poF@V-N
zna52bd%L3$(=x?AL-KLxZ`Gh+Hbr`c=SKvmolF6g_jQ>adlQv3MPFf_tp8B7!#OxT
zL7Si&_8vCm)n9jZ_nrlKui#gSSA)Cs9fG-`r#dAiC9=o!R+gO^W3D|fTK#C1kM!Yn
z{WSdT@#_1frKONu`pTCKx3;$Ktd!B66E at d#4N&FgO?msN(Js%RK=GS5wl`-{0z5f&
zIXpgaPsU4;r?l4!6!y_8bi?$A7WOQ(+lGivl=5_vmvl!VwKx+|y;_Y|Nk>{&+5p{d
z3puxr^HV6p4$-1zQqo9h&T&K90mzSgiI7-P-TwCo%dmNk6B2W3A at O1y>7 at kzE|Yh@
zbN3jNx58<Z?_oNo0*`my04dk%j&TjOeOcfegHn@?&RjtN=IoTCX^3BQb7(EnpWP7+
zmXu4}?aeIs=X6!PE)Ti^-{0y%z(f)GB7A6A6blPW=#!GEV*)DdLtrviww4MC3XX$^
zGu<#xW;+NxgMyp=j~4iIWB?)0_ry7CH3o!DU#?i|jXGW6&lj*E4<TX7n at RiaAipj_
z&RW-;Q*%<xJ)9^Imh4=DxTB9;6^fcqacj1;i!3L4{}nSWD(WNS#hQVw%ZDVMUYDh$
zq&Bn}&2feM{JNvBVT)QU9J*5Am at bVJCtR_1b}rekN~4A6b6up!&99^N;6OVYin6n_
zhw>vy196DRx6UbrXSu=z+i6ly#_CVrW)|t=2_GdC4 at yaPUpr!|<U}_d%;;uGTM1#r
zU%W&NBtm at Huo$wxZ-$P!FlF!$>!bO#8ymMBqd3ukT)v;ayq`kan=X^0sVjmjq3;lz
z{56>1@;;};9Kv~q6$*udAK-@$)go4|T}2goiAOgdrrL<u^=7ftjfSULaS%3a?$Vht
zk(JO^VXl7v{vq~=Bo{L+<?IS-{Lf^41lKn0VQ#xLRzq at P4gvDpJ8z-+?X9isJ1?|-
z+qQlUjDN;tP;IrW0Bk3qn>XvP(`dgkR;gG?LSKrV>|5_O+y3g{^ZOTHjhDFcq>y$z
z1y($liFd7V|DNpNb##LUNpq+sBkX`w;`2eV at I}#q*cc)vSu>5<iIv8;ZyzXr2Ug6`
z$g+{{i{H(yAw}fE=_MvWu6GtifS1VcW2wI)?X~_XoUS8%XBc%C)y<-6L75UBJyN;+
zVDFFl?h_J1LOuF6r3%X)YAULoHWIm)tN4JuwRey}KjfOXRu;*tJSSBvW>fB&qwUcT
zCuWdjt0})m_9`OcveKP!n(Bh?Jn=|;nk%L}%mG$XNm27_s(fNCh#0IeH}AXeyl$`X
zDaM^g{0Z7jg)bIKC-IV-+{!VEK$zj8^QG&W$-)N<DQ=6*Hd|=24x%HDH!X_#7G-%X
zyYgHJsp`^qw$l3Ve0P>>?fPgd4QXK4P!=~|iwOzcnV{)U6tFIErDkN*8ol<A?X#IV
z{x)>saFo_Lxw-TFu}_Su%GayTc!7N5oX6Bu=kOrQ9ebb5ja<Naf=W58zCRGeHppJ5
z$a$fWmCvHttP3^9%0Hci15Aqrv6}SWF5R?9 at N=K at fMY_Cv$<!Lpi8Lv at Aft$Z`S2_
zJuwWTu;<c|xw#=Bwnr+-%#0W|*!&EA{mAI3p~f|9>XT<!hA(rN0NOvCYkp3x!&P)v
z5l&4`LDA7s8OjwShOs!5PqO+An}9m<es#J$v?6+(xu0Ge58K?Kv`>1cC{RQ*cw5YK
z#i;H+-UU}KU>oi3s1bFO1*f^Mf0t*8;6}2)jUrz1$|E{EJz9g_wb*DN(-F_Kt_wnI
zf>)u1zgyVlvKU*=GcTWog?i-+l8+W+EgBwOTjg|pr&h%EDqq7A>u|0+X65KgP2J~s
zUJ5Dxe7(9RTjNt|@kR>!vS~ki`-1(dPJo0<-wjs^mFdHA&+)}&dyxY2MLIFp3hHYy
zDe+BBO=)RqSK7i!Kgy=%`bG>U3{pa$L{@uO4m<fzU#PNzH>K~l+^%y#WUHT9h={qu
z#lRI_lHiNxj48%D(Ve>S*rtANNTIN|SEDSm`dM|gkYVV}EjY{BSqQ~}UDZ+?IXSt^
z4wo_$A-mf#;Z*ia5*o_aI7M$UXU__~m-idh2}eLjY-knm#>Q^yg25c-dx)31+wqiL
zMGaABFG!gB at 9W|)kTgA6qrOF at jKUMN6V+!g4~39(ZN at kP8kY|{*?ziF<c=_jn8d81
z<hL<`>uDCfW*0C}8W)jIiH?Z-BIHiHWbW9|h&WOj3#K5QzC|V{_lV}|tJ~PHNjZl+
z#rG(C_eyB8!j!9~(rUmK`>Hvr at SC8+Ae*PO`<n!Q3+~mD$c|5+UeGlMJzd1Ce>tbT
z!fzJjXkgZ%7A5L3Q4tVaEMQG7GXD0ixUR15+tHs!R#sM&lYTK5s?*{tUh>~80#@)q
zN6`5Rk$R?Xs0&7 at 8MGiRm}$>K8CE!Rfv^qjl$PM+RrS|?sb{*-n8TTa_|;>2Z?xDj
zqOZ-;#zq*rb*-q!+-Q$nU6Tw-Tzvejp^P}^bM at mT0%g(mKB)Q0+TFU^Ttu-!X?q#^
zJW{<nc0bMuu$51}e1du5!UeWPGbe at jRIrX?!xEz}IcgMkTIB#0j4JLSWAg^CV&e;s
zGai^ddb9~W?S5;|SoMAFCeKw$|E`G%AINp;bdtY%W|Xoe3HJ;GHTVP|#mhckrnEp1
zpOip&>}+q(sdvw5_ZXI%bjYme{Vkkap4KX+z^gO=A-Z+xQixI*b)jPxycu5IC9$M;
zFA!z?yAGvyVJqmgwhWJ at 6xe6hp#yZM<3kZ3shOS3>YR<CyQOU6iSK4&yfX+b?SU0x
z2r)yJbm)%FqxPU6td1|!1pMgsI3B~<*;z`FWP`+~_PH+Euu~12>_7F^X0 at 2a#Ofv7
z7jQM_98_LO(VU}*t2q2<=wvT<w(7rIE&TB%Tg6IVVdIN=nO{(Kt<z|<tm|}R9Cdqc
zx?DgyrOiyUf6?`D at h5+#2IS5(+>NU3h}2TVRp~l`0v(GZoB3nKa$>txQLihSUTahK
zQukvPT}7h&$TD6|P7a#AB)ZyRh`r->aPIm!Dhl_C^+}{$%+FWHJuzZ)2jZ9YqCsON
zJq-=bKjgX02|_P^0p%g=rUYb;s_#9h^2LVbd3Yx7vLW=za!rpz{iSdradV<E^_o!D
zx<;!|NjYVFjP2d%Wqe`<hx#**r+6-SV1(T=^o#6O=sX7MNa1s?^)q4|Nw$4 at LSdeV
zbw&M}yT?>1&8i`FzXx+~c at USyDINtq^$|HUd4T?+s&Dn9B2!z}NMD6Hjds>2FF${)
zdsBo=$gD4b_7Qp+h;$t@&eC^dj3#7%C>LVpNruM>L-~E at dgz#6(NJ1I-{mCC at M*i+
zb*$nCBq=j)24~Yc=kYq16stXXAYSYQypT93%53$&I-bsRzzt}NzpVZ<Moc6QA^`bU
zu=BwMQR4*ruTr<j0 at B^~<-d9#D&+t22NJ%!E2m<ds~lI(^}P;~|Bt1=SVm`OXB$KU
znsMQYB&Y9RY314AMVh-S%kj941T`TCX~aE at f5k`CHU{$R<7bFKv%k-xll%<vTM~hi
z=li>4PV8YPodlPBf>7$ALv~X853n8ZK!l7mjMBdaE1E825<Ox$7dR1I7?`C)pnB5(
zeb*1`6?Ju1$yc6bg*eq+K;m5gpWoh#BbL96jIr}fJ`+HUU;Mk3S70ILmvDu3F8=+<
z8-yh#yfZcY7)m6Qc8a%?S<uh^+43tmC7)O*y}x_%W6>5|_~%b?NbS>baD^lPk(+K1
zGNUDlNbQ*!{yxjSD+ttMT4ppt@}Ez?0gon(Kp{Q;Ia*72a0d{Bmi}%JM%({9z~DcJ
z{o(?aNj`i^&c%P8_#$qN7A#Qp(*OMj4-<HV4bWn5yXTP}HmKA~Xi^F3EbhA8X_3|1
zE=<%5%3RyL(V==m@?VQ9xV%Wa!{e<q9)%G5V|6EUfur=3FV}*=!;&B4eWE^3Us~zj
z#!mLW=w{vF^?&>!B`5m!*4>m!Z4%!E10wsZ6Jd)c(rRUfQtS8{dy)QXv$zOaWux{U
zCPULpiHCcSL(NC3j-Gt{s7NPSU&55MIOAaVOmWL6Hvd=aLTtE)w0&f;%TS{W#{qiu
zn_N(Iz?~Pncl?)}ei<X*WG<As&~B@`vX{MhQsaNkxB-1TJbBxL)G9gR!J4etSW8CC
zeM8gy^~2V!wYy=-O||tkBm&vNp|-a~|7)XlPzVBTRCjuDvVpzO#}vKVM(<qWp_61{
z&(cv<Wi7K(*I+Fn%r4hH+ONxkQs at T#lTYT(SDT#`tTeqjU*XrK%--^GakfZXFfQ9v
zX at 1YZ$}U!@vqhona?64uBYl^F;)Kg|_}#t3oScgNPqn4Rp~dnY;j2Yos%*aMcc&Cm
zmKtT)TDrAtiT1^RE%JFEO6f4GBg57oew_X_a%YX4 at V^d4mCSz4{wTDzCn{g}wFQ$(
z)z}NNcuLvB?Tdq7lZm+ZPFaR0TC^_mvxa)u-`2L%55}69$`+k>qyD8V$uoEMb~fZa
zb$!>C-9c}0l0F+=87B`1AD?s0CA^x*q+_Y&qfwHUrhdGl-zImAB*(o!KTOy9v2#?0
zn=L^=vn)PhFE^6#RfY3b at y*Y+VmUdO{}pf8_%-ODz?FuojeLPyiYG^s62j%9J1NZg
zyq!L}gHA}|8$^q18c}I>SdlV!m~-F6)z?;Ri+HC6q~4#Q`XS6 at xiB)1$txX_S6<q(
zPE0#z((=%S#l84pdMx)GCAOs9!!VP0{gR8zH`xzk5HZgQXdEZ?!c)l*e0;GkQeRZ^
zU8-{7j{fJOvEd72hfwdRre!yiuv}#4-F;J6K3QR~LWg9RV6P=&8X6NVaLrbAx{Xrv
zE>85Lm9Ak)sz-ANQrIWwJJE$vXNVM8-Yxv~+)n?u9&<SH%9=(sReQ2R#GGB+>z*NL
zhl$q7v92;&%}7McN&lp#j|4hZlio?^b&@G>gx1&0Y}#(qK!`9T<d*Y%ba4k$^X{!j
z*EKq?6Tv=Ax#@e=H)y`kT6vDsh^zgQOS>iRhwzuDMdkO!OgBf38aDAYWv%A@?f17U
zNM1gEV?6l0S(NS%U%MF7k`}hZ3zoJi)y`lXIz4oL{`&yA{JUXWf?+J%?j)8kV%1p;
z_|R-UeX~=lsNlGjCh6B-L+wT$Ymu7PVf}Z4SjIM)d2Yd!PrDH3!`t(_Pm$EVL)wSx
zztYi->qu9zj=dH#Q-fM(4!7aVf&b1oZRGZW1ph|nq6jFiv)LY>K(ggGd;6iYh#hE9
zUf%Es>|j<7j*tkSKp&*5?4S%P!~I^sFN2 at bzWjYo_op7Ea*RqE3*77 at aFFT_sk+V8
zF|2 at -T#7ylk;nS?G`FKVBbb2HZ!&9m<o14tdb;AAUP(*qyU*?D=jR6$M0;n^cc`1S
zjw6DiqEB~MXfkl{KZ2f6?>sK(^tA*4nk-1Dn!5bxkv?w87s+C;D?IRp$~k#1SHBI`
zju>@2D#T+O_x$*ni_X?SgV$#9_%SN!-5yCG?th+-0VHl{-~<E&j6t>ms=66^Il#%{
ze0*;P42MAv`ts!q at P0q7<;fmGg97_tYGf1?5~7_Vsu{V2iEXk%(m$2$xu5vyqay9D
z8M@>EcW;4pdR3v<UP0A``j;JrJuT^P`XgnOFPj(v<HQX+2LOVGmKA^as<$LNQC_2>
z)Wp1tPRvauZ!8XO+x+Ac6}V+0ytKsZu>pbO*3QO6zNZ}ZHD at zQ2=gY=KytCZ8T&t5
z_(tw@|7U6aw~6<@^;d-a54ZQe`SSDfx`1E<4BGOS?2zK(- at uG<ErFo|l;^G8-9N*H
zL*O3a$^$wa$S-_cT%#KMFEasW)0NgL92^{iKVQFo{d=?=RKe}0wPsesykqdR#0J1$
z183?AGCgn{Mo3~jyzwgAu=4V?o;aQi8DCLQpiH2VuyJ%;-kkqj4BB<E0k69M!R9=u
zCR{?A{HArU at pYF$?fv=l=gIN$;_uzn$rLd+E&b<nb2gR_YhpoRADrqU3%0#|4JnA$
zczQ5@`S1|hdGz5>(I7s06a-uJ^6gU~#afJ;20ws8Q&m;9KQ=W*!J&mqu^k4=ohf^W
zO(O#NCUNTK6`@?K(nq(qp8pn!j%qbI8m(Lx_#?^DHQZna+2{PGm3K#UNBjGX5nxU`
z*kLFs`!j8xs;s@}6k{KuK6ERyHNFN3w66{lw?cKKQG>o==^doUczu1gi;g*z9+u5a
zEC=Em at jD60@)ylHYl|F$yVwHA?W3J at 1E2mj{kOs+))ED6dtfI&*Nuz&Y;$t$fFKNv
zuExaSkhYv=;*B3^Prj+Csl9shhJ8mGybm9c7u77e+((M^!G6%KSxDKi(wihycrTn*
zq#4>|pk#*pI5{LFlV}|HIwF&`)1|%P$tm0Lw>dKWbm6{2KTx#})CWI5zex|6Q0!+x
zvaLab!-rex*1`8c5>SlZf?p$)iYIynb~%A^2;hE$`>%AVCvWngaj6YBd-}+=h$@oj
z4q^B9Y)6=bEisd<21QK?(7aKmLwQlc&<&<9XpB6AtCE;A^YP=4>H%5ce#gLd(lH{$
zY(JSH?R`~a57eH5U!*RRb?-e_lW%A~PW+s}PcU@*_HBiqkGNIka$mjbeo4mqXR6^2
z3K7$4A}UbnVp9M3`Q?t6nA5JIZYA%cYOD*qq3rbx-Dn+ at ZSNgxmgGR!UgsuoFLu^T
zPi+Fs5p<!x`<ZF at Knh3j_e>&l6A{t`x}-(71%u+ztcAI$6N49qg53P<c-kmMIYZh1
z^ZL*T*}Xg2orJc-suvi=p!<VtXi(g<6XE%E)4_G)ces?#$jF#umYJEEGu`kAnJ#qy
zjZr+MC-fttqM~pqD6kGQ0!}mcL11K*@rnEyU5d|N_E1w?)iF3^>L$F5PQ>x%Ej$8(
z?0MbOmoH!PnK$Z?(|88sQ)SIX<_#o^gkenpYrvV9n5asAJ%^TtCaN$7K}SbNPzaLA
zDNqOwnyS}=uRQ-6O0UGJTV^Jqy9GBY=4SMtn46*F+o?G at Y#ZUdkh<<RJW@)O_1$&0
zvs(x_&{N#iXra{)YA at x}K{c?P+=N?^IvQ-Y9{GZ=l+MVDZs_Ky+w-e2$CKJS^H>vI
zqH7=BOZ*61U1vl~UGJ)0dC=5{wU$n><>Qe at O8#qs(oT!w#2}cUPr=dHU}M?!*Jx)H
zR%2F4YGmoWk#@2io`;d2wI>?F+=Aq=)a^eN<^9j|r)W7lY5{-3O99XnOZ5r|fw;Pf
ze0sReHE&$+%23FQ_uE$Dd2SSf->3q?IaY2V2NZ12JtrqApzRG%&@|C7Flb8N!soLw
zptL9VuxtcF4tN6YC0xbd2JuHVA(-vlc2Xnm<m8meeBc2YyJHxv1eKU4A1^VL7+1ge
zngbb0f$&SdHWS>7$}Z?y?X6*DzLzdt0u4zZg;CJ1Hxasd{2|~Ws7$)-J7G(Kxc;Pn
z1-M?g<Ug!wV-`F$wn<K=vg;n}SDEs(NZP!2#7dTRn$+7_veb?@>zKP!sTcu()KH`p
z5k<s$y}OGmPfa@{g6Aox4YR!4R7ak1s%alioKzn!GxE=gV!@5YCx}z|mL1-IVJj+v
zkWqU7WN(J!<k~cwzW>o`J$42=(iM&R$P{oaVAB-|*%gSQgsF+a!AH<Ivo+0CH5_0!
zT6KixQ~>QQDk7rKjfQ8xM#f=i+UUX6rxS<RTbs#<Kl)wXQf5-S9LC?=Ws8-(u=~w-
z4g6YgB&!b}J_Lrr3S08pwfXD_S#?!akS032qFA*vWJ@{G1ef`8q=iA=Uxws6<Y)h)
zySw{bG+GUTz522ZJI~b(HaN}#IrJa%cV3k@{I?b~cLM at j5sz_Xi<r+5f;oMUDXxN;
zCmR}h(d=FJ3Ity8{!9K8FVAWsx>d527P=<c&#ggSV`70`LxdL(C4TKJL|OD at FJQ;`
z#VGEX?)cnW$NBb2L3f7A+u9>Wch79hY~_>I2x{hkV;l6Hczz2;T3Rq{OhPd^J6Q`*
zV8g2^E_O09G6MG(>A~^A7D%SIMSG5q)>?k`^ci{Wy-5^vW4s0qGgbkChhTmHMkK#H
zVcx|B$`k++bqY%DsGOplFDs@#HMoM0Ee|`wE(4KC9j{QOB>>78B)Y1|Mo4jRDerLi
zZNU!JEP!VtKqzJE+`2(0=(oQPNXKogA``Y+L03ly4GfO^qes!v(VU82Ui;}XzMSd8
zGUDQ6Gcy at qZ-6b18z*)Gf))TyXf?0Ay>E9)@Dk{XuQUbmBYcnsRH~>+t?k>d`HLd=
z98sDhFV!T?Zf^VsSP|k?;$7mj0}E$^$C9q4BrmU~^N?ApJqH?4`r>wj8{GQ|?a#hy
zU(o*njxX9Fb3+;V+=-d?@XwTl<$29e;PAip(i1bBS>WI3#CY~dP)Mk)t?k?r!4XRe
zsw_ZfD1XO?;*U?*-L6oY2dxW)TYvMw)s&}CRdP7*3rDj?{hurb{96z)p82(RbTG*J
zB}R-~g#PuYuo<wouSeZR_`{OhExL%acSxKt>BPq26=-BPik(aeI;5=%X5M<vy~co+
z^nbTak-m%Q%)m<|_(Nc?Qon?I{UN*^?`Lj?yd%6JKv8}sCqLmbh7h__eA*yBIexrH
z3n0zpQX&qK$E&!A3Qd~S*52R^g4O3+FQ`^TIR+w5jwB9t9#*-S7$)BTmiWzum-cau
z=);13e2<vB#M?CJ0f~whAzRly+q)q{HD>jm at vf`9&^`80Eb4o^SK|riioA-Gt6?9#
z{52;=c1h&lJ__|(A^tis)>{>=Q;+wG;fOtRGJ~=n6=w~9?d*y#jN57p>Q9}WEo7{s
zNgT?QD69`1>GVch%I_HY{S2*o#8zd~4c(>Zsbpk(a!EpH%ic#R${ERz#g1wCm7Bzw
zY5{6hGbi5}3{b_%3%O5?PEVel_PcN#>P1In>2?+>ucO~ptpyx2;?<~dI6d0ttG;*+
zi8^Cy4U1F6$}%g>MKUi-%i#TsiJuAfoSqzkZExR5MmY_^Pr_rdYAyPyb<&8`K9fvo
z=wn%#%k|zVN8?Mw4p%JIFwG5Rm6<hh4<`M`+j)BW2S;z(na4F76db%FwHPn(>y4%!
z>E*_^Xke#*j;KyLD%*DxcFV+52|tXZHyO?j7F`#ub4jijhlYA?YPyAh`d2o|f2xN}
z$5d9jhN9zWS)Ym;O8nMHeL<(&{f$lF5Vf_nWxpaK!L^DHctC}{nUOnppz22SL^?rA
z4B|<w3eL8>=bF9#fcaOyAYTZ1$*1$9mW at n!HFv!H)m_rQ>rdu60uqc;I~6SEu5?qr
zO3ChXMrzVAw_})#*=P5sp4-feSo7l)t2W9>w18fqTV-*zY^YZ{g+r5r)$k0{YU7gY
zUX?|I!)eF`Tat6;XOU~!Ma==7rRrRnFk4 at 3WItLq4H+WX;nCvpE1bYX|8Gx=_>BwQ
z+&TfMIGGw!nQ%bQ+i{LK!&Z+U->ViEvu<+a?erF17u*bgNQs?1+c)J{oAlj<!p5ZS
zov!m!j=TX#g6Y%FfjEut&b~A)V<*d&UeusdG7)1~Ih1eMQ$zXtObkh)6`*SsW?Ett
z><y3CdSp?n6<n~kMfAX^>VI#o(tBPmA`{A2yt}%`p3ARU6koi2FAnZkWw{xG;g^_u
z-f*)oRC=?zh51`VA}*0QEHc<~NFU~+J+nv(D{i!U?yWr!9zC_1XGPxm$X6YxnrA&j
zIM1uKZB9l#Cby<3&s{JU&XCYB)3c6}FFQR+H3{D%Z>-GLt<fR($W$G`?z5WzRBp&x
z at o#cL<x|?<3Y8DLTG??obf#ay9hyVPdX_$86_%5AE);p)=^1hXrxvnpDq;Rwn7p2S
zNR({BWqUFx`u{nDSm`-$zzg1+b9i)x!MqN)+3Ln_RZbRg0mf^^GTsDr>zYOYfL^Fy
zDK~hNJqmAz`7<WX4anY5)}eSi{rM^H+(QC&rgQ2JO|ZK*<L2VRKt)vx9)yoMwH4QR
zL))o+xt at NWm-g9Kb<XzNoa+|4-;X;4t<(hAuW!h}Cxae_I|NLu#N*}I8|I#9*9=zG
z|75L20%%uC%$w?xl9J-$sMK<(>vEK$#;o|`Vq at 8y-J<C&B_$-hL9%b%27_AN<KG6B
zhc)z;wD$D_WNbJ}Nb1U(s_y}WI(6rKA>!4;h2A9K^=q6)`-g{PT?avj-d_6k>k0H-
zW~I(*|Ff9{2*HU}cdS>)$@k(0NZ=-ceV&qrmhDGtFo+_6a5pwK0Ka?ft{9t`B$t-D
zJbLuV)3Yv8lfZQFZ#?(32tC93XAS>$pP><8w9`(!@v*0;C;&Q>y|w!>KyOEbsPxI+
z^4340wIYfc{?7(f9UD!e>WNU~=U0XD5<EV1J%FL%lN}r!{Hg?N{<FJMNSm6;U%2EK
ziM9UWR2Nghe0y+ku(LA01%=8l+42AB#gQv3EA8z!IXLoRpkc!SJM-T-*qFp)%bu21
ziM;aQ0p?%+6=9f at pAVXb1Q^MoD*Gj4T`#?EORL-D=_0F+*<su>I1xRg#Z2Sm#Pc-d
zc~)D`MCi;<jDo*oGm<RVu64AvSwje%vm`@62wf38j~h-On0@%OxcJs_gj*KOH_v{Y
zley2XE<kIyySoef{G9?`9E<<=9AfFEz0e>oLA3k9aM80tpx-bsLSI9e7 at 3&3j#mY1
z!;5u7p?+c at zJO%6{QY|cXoKhPj99`v=Y^F%Koyjhk%@_kIlzJ!=Mw+j<9OHycqlj`
z<lncT{Tnit;4uYfB=4awtVs|)jFLL~MQ?8}wEZh9&ay<$1V6lCkTNqjucdP$h4rui
z_dXFB6SKAWB^!8w^D77~A$V`0=w9YCL*a$yuyqM at vYNg38G%M{{YTqBk3oP%Yu_8g
zp$)opiC(ObkPsN@{eFHTie3Wq(0jjw=&MV=0c1Ws*%|Fi5d%N+HXtZxG7Q3ml9Cd;
zzGPmbif4b9T?ES}>gw)RyLF4z_b&|;&osCQR^vLinQz0x!y_Xi!ooF%<#&O_5&khd
zs}N=0=mB)jWALh4kYlu2!n6aloPOscTZ6#Zt6r0mI$9nn1{=E0jC7!`VVT*|;^G*f
zEog)D^726P-vIRE%(%G*on3=P%TsD<Y8l_%cVO{PF;Vt{^M(RB+H47u7#!M9p$jq#
z`x`$!QnQzY;8f*-Y9j|)3D8uN|B+}$B-7x0WMm}dhg4aAlh?4*?;g$LQw{X=SZywV
zdqW`L)DKj_A8jF*#kU48tagJns?_~g|H8t;j~_o2zmbAZdE^xeg)*+T13ULd$FuYe
z at W8mat--c!;lXkDU_kAD1?0?B<KwW1z5!S at JkVQU$z<jGPmcD$9<&XvAX)iu->hLT
z>gwu>dg5sdo__(ycagR8ScSYjbANPNn*Ur^6o`9M6BCUq!<>Y%58<?~+;|p&4dEvW
zQq6OgJs`;(wX}#cKCA<I5hb%W(~_Zm?=2W60Tt`lX5_I6eqLO(H=)lk;6|lcySZhg
zrj|4lX_UQF7O?G!t<uT9p;J({xV(G_6<juRv8$_V-Cq%4_Hc%A;{uQ*VJ}~jwty=l
z+iA2+LlSmVf*Fm%=z0Q=kTZ7p{Ct?jX5f5Wg<>-%DardsD|U}3_-$o1iFs{-^y1^=
zyF|h`H$+JPF<oSkx#%|5rAvD&<1tS1#Om>2SoQMqLJJIVP;z;Ed%yG56xts69G7qJ
z4pf-@^}bsm8m-%3l0g(ux8S?+-&lg at UVv-&*yjFym?<dmvAd3_y5;C~y#G*Eo(5R4
zUvuktgrLah(ZuI{%>@JEm*I5m0%d`Rvo{S5&-to#2UHMB at -B>Z9E at ctlP-dbf9Skj
za!BqcNIu=03AjW=dlUa0#+n`Afo11Pk!`6(OM0^`P<h4W&7q;8S=v8pu3?|SM3?<+
z{mj#Bhh$ZC^+T}OIq)=}9y%R1LZrZ}3Bj=L<#vAgz&5-cN6l9Dnj3j8OxrTvxc33r
zJxz<kJQ?S)8_6jZML-!P!4OkvFSL>!Rq&9K=MOm*-_|LpQv^BWK}&2GNXY=E%cjH`
z7#M;>{9c?YPXl*z5fk&=WY3}cf->az2-bhOnf8!az+RPxfu24zvxQO~1ygOGp}mi0
zf(v;9bg5nnuSK(;f<i0I;K-hA55c=USsA;%_)=0<Ru=e1a8DMQ!UErih22tB#qH~C
zZ?}Pwq=rq;%fgxzu`P}xMQ{zE;q=gX59}t`B~yS;t8o~D at t?zuPNq9rCa%D;blhc+
z!xtX;V=oKao+{$>HTv4E#fqHr*qEFag<$-g;kmEhzI}tPKTmZhz!LmfAA!Q>hB_-T
zT`?j&mYZS)z4X#<H%GxWA))FIpBNi9Wm_SC0#zpP^w>+b55+tU94ZM at F-s1sUiMh6
z(`8LMcyu!uxKc7ONo<Vtz(SVk=JtdzJ+*gszV5Lj?l7369>;yHizPb^TFkU(9?2!p
zeZxhW8`8TeuDTeLS6Ee~hXQEBb3GR(T|R#NIID1p at CxEH`GWTIQ at CJw8>xuB)yV{`
zWGx$VTayc!r_xXUn3?EjmNYaR05cA*BK`8aGLL?r+ahhj>EQuND7TuXra!<Rm`2*`
z0=B8ZyI~y?wn89LI7(MxgX>P-`N+VZj|aaTRa3<uwsv&ns(urd0&235e1wP4C*+Fo
zjQ^fF+_VFuX=c$MW55iaoy?q-0*i7LnqsvF3Ga~ou{AZqRi;TAcDA-koj6nyVDc$D
zw$Fqu(&nMEuT&n*QVR22op?oXJ~sy at M)826X8aBK-vAhkR3c&jwY$CD8&|)F;=%CV
zg1Q(J9j*GOqpD^R?(b_Fp}aTrJBH*K7&pWrn at V_W-PtM1_z=aaLeIc3vX>|?dc1!?
zpxM?SMkEdMG*G!zi8lvEBH<pj0Udo{RH~|>vAwtV#M4uBk-_RMC=9{eH}s0<C_FAs
z;xvNqSieZG0mw{9(ck>{reUmRs_6;8ghZ0oAlL|`;lLrcuf5wMR{C0`?*uMtfCwzv
zx$Yc1JjIr6FQA&tjgyg)g<{IMOw_<9o&lWzjOsLac45p0eo+r8akAcRAVq8q4qTxQ
ztReo}UsNnDEn`Dc6NA!qxt;>;0yB|-Yj!p_vl_3Kwn0g95K%=rxGa&&kA|G1%7Io3
zH&F7=fdT>#Fh-WCot+(f#`=rbuL)rg3v*_RCkFvJcm{=i4j*a~?C)>lnaD4H1zSrJ
zy)4mUI+Xu`G^vD$5gN8~C~XR>VU*+3)8>nwK7boV9EV9gcA at IB_2j&RE0Zc<jguR#
zeTOP6C{8xGo)C<;Cbf?Gk`V=7aP7EW`1x!vereTRyqQ<7z(XeZD3pb+Os|l<Pe at QO
zdiB&6<PqSguPTWO3Efgx?}^(}R}+y8g?z;FD=!foi-XT)_rC`M4c+(*UBazbpi^oh
zQiK<_1($K~0v0Xj4-f>FF98+e5FP9JK9~|bIxbD%LFv6t^a=_n9MXDaFf%ZNqN3EA
z;-MMfXN{zs)f9&chzS;fn5d|SOM}-$)`)>nfy;hZT?H%nGQ5eq{cdsQI=JKykB+t~
zmE<dHuVP?A_J-kB4z1LGpqM^0`dT0u at YgNgDH|D^ZU_xt03ygx?vV;y&xGs7t)1M8
zjR;dy(=Ah;3p`FvPosPkJv at MjY^kmLx`3Ohd;A)aNh9rb!{;29fn9-*rt5M4v_!5$
z<Wlp-Z%ByXh#K}Nsf6eO53<NWzHttLu*<}&VW;F5R%0v^Ebkt$HwWfo*En1nxNlFp
z?HO`~56HF0Po5ac#h=5lDjcjv8?-5searWFUx4WdXAt-D<pf}&Hu1PQt1;6eBX58^
zO4fja8GVS at cs&8I at Wc0Khy=nzE_6=+vTusIy856!>CY-Iw6U=<%v1$C7ZM`BUiuWl
zRQ}}x3Cv%;#(-6C>!5&|g2jUCr=R294 at mcb7nY?$7C2Kd-vfaa&uh9_Ned77Fo^HR
za0~n)2Fm&TdEqaIhK5EyZ-C^Gr<K;zS(NLH?*aEHf!Fj?rz0*b|9qY|Bm`{I#~(Q`
z?sXZN7<WJGFL1N`xb{%T2MKExl%ZIJqzh at f833ZTR~s<2zZVw^mb~8C>YxBXIy*QR
z?^ib2k}i_lf)^gL=Dc+n+3L;CuCBz0XhdbaAYZfY;nXc{HTkA%i(xdllK6sV$j{`Y
zi_!9V_c71$8eGe*N<v_I0p|%YnUcaA15}#?pO>tGyA8b18eRmkrMD&OB7jO;L{ZW`
zkmSsoPQM9lLsuNvd8FLMgK31XaI;5VSJi>#49Ex(8oh^Fg1O45?Ck9G`JhfmVywm-
zR8I~la1fCDL9<FyU*x$&zk86P%M$#V8LX>)#OHdL|E^3M^PDjiX~SQbn+pmGa-OJp
zr5*X9L2wuA5couZpAn2QvlPNAFb9oSRb35_AP2^I+03yhhvL_vQP?kZ%|d5NZOK=6
z8J}-6|FNWhWQ&jM(T$SBJOSXh!<z35(^=p<a}+GdEWz7`GlcnFNRtpBxG>DI3N%{#
z!{_)B$wTT=OaHS-*EJSZ64J#gyz{tYLTYJh>JNPd7(dk3_7f7e-*e%fWCS?m*P-Hl
zx30y+G(QGoaNEd;eqW1#Qa|Xlg at ce(&Slz1GOCUoGMpVasl=EQt1?(i7ck95&(GWE
zDw>2*`mN_GEz{@7)YPd`Q!!ZsL0ffHbyZbKX(<d_?PI|rFAI5G6&Dw$2hLC%Ed#lj
z24- at DgM;hqpV-*Uog2FZOVhUDpnCR~?isW+6D|@~PFFw3`4PzjYW*!7R#w(ikJxA4
z{_anegAra&bTmgFM=;5;=ZgF8Ue92rS;BO2wrX`N#p+!i`FYv+5p-lXV8SS3BwjKv
z at A#|whv6DN82P>+Iec<*0zFR`$0Cm8(kXaWK|~FQY6V#wdg!S&Ba1TG(+q8cScM(=
zyi$8^W$G)0S$ev<(G>%Lt3X=2rg2^>KwY8^crzI4DMci2b?-^JIBy^#;o5m%X^^BN
zpy4=y2E*@qTP)Wd at bm2(X-4v)1=|8JW%P-eig^X4VHzH2SeOWc%X^My2QuVls_&C9
zuz+?aC?-aNk53B*YGW8QZ#o~6cAXL at APB3dsDRNSygrGVYNlALi@uW3|F1*xZ{2<Y
z(eC!`x`rFf%YoErRW}&)pOuC4JV=7073 at +sIiDGgO-?RaV90}BV{BsL8?+nR=peys
zXz=Tw<8JF(C5TXJkY%mr78g4{0 at ee8s~9#3$Yq!}*@2<v at r8c-i@XB%=AqNM>MSvU
zQDblTgRv5d`0>(<pg5|=;vp926rvxCx~cJM;&X^X2p0HwJyh@~x at 9*is3)&pz49x0
z0pB;!?EdRbTwENrxoxom4)UuElt`EX)P}kR+jCIUDsT7B{!12!I6$d%bat*y)}L2n
zKlbfb7719uOsONyjeE}ypD1k8ukMmRZ~w4*cehx)bcy8>A?*qIc_sopb98V3!$0$Y
zm4R0}Sjx|UN$bGp&w~P{?D|uo0|_=epp%1U-R3hp2gfBGoIxs`rEv9`$hZQ;(6>7?
zUO&;9im<_RjISKz$H^7}b#%11LnTANiUstLIT^3{L>%v4L}N-WfcFuo5ctl9fK5AD
zW5J1TQuRvt-$Te{IS8<M>mA1bUgZv~k_=V}hx&MBYy(yb2;^FKb~)f`Kp!U%XW)W8
z{QfZzCb4k$a-bFW@$!0!eU4M0 at r!PS6iB_gs-w~c)0z$ecUzvOMc6`{?eMi^9NhK?
zSbbblm@*H(e>ng0fq#~J%|;beclJ)+*82lsioMG4#KYtG at OSx$p-wI;jWCmvu11yt
z^yp1U@#~d75uUzy@>XD+JJL`6dKh`}#mlF7!V&_Lp|My#J+WM^9uFSen9k6{tAX!}
z at Xp-VzXOWMV%@Lbzv;-x1OPol&t2g5O~=dT8XMZfT2)QWduN#{;{%W%$uM;*62NyW
ze+9QDCT0klmHjaVW*%!y7b{(rJYHaxj#q{s!8i*fX33$jIcAQhAfy3^c=qhsd3zTZ
zWol%+G0Am-)!G_(p4{5l+&HQhQ<3}7d4O~VTaB~&hJu+a*MEfTDOJ8LjxRQj3CiMp
zO6(K{-(Oi6BX_s9SnG+2h(P0UbA5U)W;%dTrCoO-Dn8!x^w?YXSCY{EI at jrm*49}N
z$9YVySw+PKA%;p}fF*1><t>2BM6-3^4g8)P#F8QN`kaRg$e2vUZEQ7ATm3I%944^C
z>wJL51I9 at 1WSb%bMFsJPM at X2nEF&SDfuoKMVxN|__Agj#|1xQ)C}*urM>*u{S5NV_
zgYYOCJy+G!pTP4#Xu_ZzjO#UnK0Vyt9 at JY7Y@LPwj=rboE{LaN9B4p>FgrE?DI0>L
zuUFgmd~_KKjFeQ<+qdE(7k3;qHwd=De+yiWM$=2}t^pWIRenR?-RbyQqWek>g5RXZ
zet-RkpYxArh+8D&^^zhYwGgswO?u&TL&724NdVq*8faz%P7nlTW(}>fGhYCwND`^@
z8gKAmH9BWmU}~1pGcm2f*)uTsLtB%n<^c|t*0#0?1}SA4(6ZFj8OX`2;PwDD6NU{X
z`qq;wNNHDBRIVGIihK4Z3b?wu!dF0WWEhBt8lwt(<bk8l$VRVzga!wfhwxX=CyGVb
z0m=~yO)}h?ZJqB1ciu<wvFkCVi at BvA?%vWx6{DYBxR{!j25`VsFC6jgR5775%YPtK
z_1wVuU)w8uX)-7qYy7>hn8Q4 at Ir~8hI;ohNyBf7ofY>(h4nPZC-`wP$2*~>U91#-<
zaEmGruUVHFJs6l=%08a^`DJP8D)=6TTcmif2j|Zxnr})A2vn~74`Z|`sl0!2tNk4^
z7>bzwYWlc?zMA03=vAFVv=j1My;}x)wxPWN+!XcoV$-h<uw0_35)d)pqGV<o+(Wc=
zo-K0&b at 0QQK*gAJ5l(*p9P$P$;~?YdDeIGo_W^oU0%PzG?W(jXsOaeE2ne^WwKXVR
zSUzbUzRDvsJp3F}_0OHhl!&#fiGK8KEpDvUwh3w{6iD8XpdgJ5*)(l*=q%YHuvw7g
zZ&m(+o$rLNK~UEU=On;90sR^fOL7FSFsc0#vL|{PEFSJ3pJM|vB{6dU`t|ED7yvF5
zBfaS*T#|I)b1bSN7?HBTGRDNmf9j-WJ@?n<+VyG{s|!x?+(2XE*5E*gHt_kg6HH|J
zJzuy&L(?tX**f?<Bgzrbl_z{}4iunuJbWE33yT at 3Hd}bX%8dx8(Xb@%lf&byVQFAA
zBgj6c<js5Bw_h6fEXi2rsWQ&<k_VX65X<m&7*NLTz}y5%Ex$q^%rhE*Af7DZWWZL=
z_<Rsc{~W*X8%?tYBF_ECh9fmaY&2Mn*DoNyzJ_}tDJ8WwQ47T|QrcX{>x0?7NUui#
z<)%QVUoo~4>XQf06rJen2wwagf|}kN8HkvIrK}4ceCY@$a*z5Ez2chM+BC_>j%37x
z#Og$_$^20l2w2W9NMB-#L0nFg6B$~O8BKdWGq0l3sn8smBZUMibR6ac+`hfzs;oys
zmWIPFUZXd0Qh$$t(Zrt7(FFLw^QhyiJD;LE=kA6JzJM~mFN~p1xr4bX<6JU|7Er*|
zP}S{4WOjGqm3^r^wa(*aXZfFl=POe}xFHcvZSa*q$zpDI69w8Hv!K~N!VS3v=@<+g
z8F|m4qaTHK>&cmBf)5hfhEv$k{jn?zOkNqv1A{ZD572D@%Ri`nO($LgbP?pmOZ!G?
znRih${D#fx7B_-Ti1{+~isj2n67&7~ChRnyAOC#JiDo=e879Hke?5AJ8h+gX_dw|>
zFXka3mdULbgfzN|7gR!ZP!{k|KzhM9-9$<b1#Q1^06Bhke!lkMPi3GNId?Fpp+kbG
zOZsOg6v<q7fHggW0D1e+T83Wm;vz5X_UKY at tm1n_fL>*lxXW-wrAtb`@E5P|oMCpQ
z=8b!~4x@{wOa=vWV}%@=Vk;7nvvfOjT0?ggXQzEgDv90J_6`#6Dt79;yOVGwl;p}@
z+%3Hl_t9?#nPkn`?DHM3(_Alq>1edQ)bhn*&~WYT!&nKo7rhtVs at XM*MJqgii at c;}
zX-Cs1zuwQXESIlQ_armF*vX-r6L3tKV!+^HqO?5l^T9uNfx8vrAb=TdvI(eOPOb$?
z*(Tl~jF)yt05AtlegimqsV9FT#Vp=FK>j&QmgQz${WF*w#@85ek82uJvn3dM+&AAk
zLm*2lRgHiq1~fws(>d2Tcsq<8BNS@~^W;Z9m3g)`m-zo8>$~Hr{`>a}$IQyg$f{%~
zJ0r&`D<mT`WJZz^DdQlcQb>ewNXk}}5e*tfaVV9FC}dR<C5hj4`rP;Tdw=iW=a2i3
z`|<fW=e*yq*K=Ig^}L=2yP~Zs=}T*OuX6IF?8&>cQ2M#A{pRu9$Fw_tHw4-I+}Y;;
z_E?qMXQHk1Kn2P1sq5UEAQg{slAL7psW%cHJ)r`>Uw&s1^Nsr1#$HPH{Qh$EVO`Rp
z%-bGMGw$8Ak1QBrD(F1hkw3jemlN^pOt~)qp*NZrlAdcBSN!>S&9-dcd9yz)=XJzR
zREcn#1c_WqwJtrEy=U4eXhM2Hmb?C{L9CV1c!|vxo{n3L8<;tKK8tDA)z)hMt?1Wc
z$}VKbmMvRUR4x`{0{8dmw?2^_wP%HPq|-ULYx-8=VMLBU<)@O!x09$j>(sj`&<@ZD
zHQu at NbMiUW4Ckccnsoac?vL=FQ_<TNBFi52_KP|dmdQ at p?q)5tXPva$_sKcdZ5d!q
zR~sSsn3RlfzR7*y+EK29VcXWbr at Nj$LQy{Z&TjV2`Eu(`q!nwg%}<-17IJVZ>=ep2
zom>!BJvVO5o1fJfI-1BMlUzRX?v|QdmW0n9rxWw_ho2`e=h8Km<khB*Tqx at oTu8a1
z!r7Tw?$YIF)V#l$F798ye$Ihz9SdVf;cFadI4LPdF6BBhlE%G at c~B+;Qgo=eU6K(%
za%l?jg|&l-qXCh8m7%g;W7DRCs9me7st|WH!e>Pb*2N?UX at pDwg*xfK_lgVok%SQ5
z<sr>G&*PI5&mSiSkKCwpd^${4quC=oL)o4q?p)+9$S!0^Gbq}y<<YC}N4%!Swv8Tn
z9W2Tea#f?6;nSvPhZR4ZF$sMdU!Ah_DD7~r@*J<?on1fq?DV-O5?bif?%LJXeEZ`s
z&Qw=pq8mgiDem-QjlWsPw(@P?!w*|FWaMmDtCTjL_TyAA5T%^*TweU<aMr{omPXs}
zrR;$N2b|}dOWFZW_87Nu5Sq|6In<9xaUivmAK60I6ww+FYa=!U2#w=&oAL96H|-_U
za;5LAJpAEx={1T`Tkxz;7w=)ZXdb#8gY0*2{3bS>u46m0jk)ebfg8`+J;tS<-yACq
z at O{D*lKQUMxoD|zL0E4<Yw0}ss<QBGw*Hgr(&L#Q4p}A$ykzrutL)rc9I(gn30Z4I
zcqOWF?n`9ifMH0f?<XOJV at q5652aqY^ON79D&kqp_UHfc>(1cUIpNoB0kR0T64Jhp
zTraGwP)^Kz{J3v)6I<B_r_v~z&oeWZ!K*&u<wQc&U9v^o3q?*{Sy}n=<qKM#dnbP>
z7SP5NxdN+13j1{M4C4aL;ogdi>d>cqnQ at sryW_Y@8i(8UNLM(gzN?YC_~8^EtG0XM
zodto-+#xCFR1Upvh_bx?{?mc<S8wW0bAPDR+ca^Z?)3{za#dK&&zhsUb84I^gIdpM
zbAF%8k(JLGy>yy|y?Kwoah9*L=|sHB!kaiR at haa06idtx9@w`nx<|L*3??%El}qOR
zI3)>0@|iVry=XWODL0vXV+lbCijakNDrCMd*UIDu at qz|Q&e<D=40H|=miPL>%?&gh
z-L!Gp#l;19-KJe<CA)>65C=AI*<u)W<PzBbNEVMzJbR{?BLh;2uWp9zeR{=Cx0FBl
zd0G04180a*v^37j7>RxeX7WYpzLT-cs10#A-T;vU+^BPWF5cq#maF^8Fr>L+_<SQs
z;j0YNCqURBtD}>lI&y&``hz59oT0C;FDEC5NzsGu?&CcLtKiCJO$o#&7>|uRFRh%g
zg`!$1{^(j4F8G}v8_1V-SN|(S at qgjj;Io#lsr_|RXgO+}hdQV5N9CRi9Xz-xYS()8
z;PJEP&-XxXcP3ih9bklq$3uV-*SYVte{hHR0pKwzGPbz4Vy6sj)k(K&YlFkW*xA?u
z(65tq;{dib!Dt5*@Xqkrm;>pg)V#cwX;yT>A1<8XE4#e>HF}lnUOIQ5gH&Xz$*qiS
zcNb$*;Hl%Krx!c2!f|S|hDKAnUw~p9Rrx>j#YP2}4sE<C-c>r3;&&PwVTDDquoSi6
z;}%xn+n}ty0}!Fn+|1|CuRsP}<6-F|IC%M3khQh7Z%se26bC?&DYP!Eynhz`e*I8H
zIXIlhj~^>@^6)(RB)JPynN)(|+ceN}pNknQd6<mO2^%_|n6e{il+n}N*w}58uAAjH
z$_LA#R+f|8Clj_xdVP$2KOx1v{KRbG_wv1CPYroOlpQw`{*@Llz7i(`@8Z-io0^yi
zpLxA~r<l$oQOf8y;30<wZeHase8qXyh735#|M1~k(<Dc6+ at c48^$x7DL{L!A=h58z
z=9pO<bv}K1^2bc}r3>fuzx=Aoc+!H}y=d+8cRu;<eE=mD6%`*=HxiiUq3U^bt at kqV
zee>}PTvW at C?YGRf1D8U_I(x%`TG{-bIGDXppV?;0{zYBSbV%cE(@l^3oobj<$dsB-
z#BY%g#MiYd$ejMR#Q#s2E46kx6C*83G3){Pjwee6O}8q*Jdx^@cj$$rVl(u!6V`Lg
z#dXY77p(O#dw9Yt_3z(NL0rXKzA}j>zi(0tDpAl7 at c(E;KL?TlE&|uBu9^Uyr=g{l
z`h+6i<iy7~_MHlfif?Wo7JRfpP%!%YGd1P3j122*<{NVunV2Tg*Fr^G8oS4|&?5b#
z#m-+I;8%-#@qhD;>jaG&9rd(kQtsajKul+OR^OqBvb9N)VtoWwl2K?{r~AvdGE#9y
zpYA%RBS(%n1Ro9Xj7PD-ZS!;Y6k(~&Lgw`I0_(~lkB5AE>>IkBPu%&r(QBZnl3I_J
z`Gr&%*1kmjN8f_ED7TLS3umr~e~C;Oxb at lnxrU<aJ3HOE+g-M9pHYDD-aY*Qfn0j5
zujPQNUb_AhAF=ez4_s<PI#H(&Pn%PZ3`~2*tJSH>@BedN>dYJ9h)BgCMjn32oE(2}
z?05;hjr>ARo@~B#YXSV)!icejFAoCLZYpba(m#!clqpO-*rJRfU_`DI6&Y!OgELHn
zE~479kmmS?tDuxlfJp=f6Wizlj0B7?D)Y_kCDj-x_bA_X;I6earTEq6v5;&5ohYq6
z&poHW{D+X1e!M-h$IPt#tW*iuD)-&~n<=Y5qgTC`=&g?Fk|)>0I>Vp~$7=?#4%KV#
z49#FusGmbUiWU^KEHrz%K0}*PQ`YL=C1E|i_~p)5Ds1?-h(2juswh=WnGQC*(DXPU
zzqq&HrQ+Nl|Dw?F-wr?Iy9bwStNhG6Wf+x9E3=O%BrhcLNF#Hp_>Ss-5L7r8LAatZ
ze{u9q)2)^U(VL$vJRc*M9NN*4>iGO*yvt|lSCy!LM^XFKF*5g8&Jal5g7bH7Cm;Oe
z@{as|iTD4W?xxr;LLN7OXNPRPBA7pWEjlRZ=Iq2(A57Vw#Qg%C5_<ILuc`9t(^ETk
zk4RP0Y~<h|-!XR~P`j9sfLj7|BsLZnmUZhkd-FJWp53rLmhO$+Ianp2KcUj$R*q_F
zYC(P)5~b}_&U*)%P?P6?HqKj-V0BSl!<~cimkSLP0HYXB*>frS&(Z>3ZJ3x#I8Ed)
z)(}rFx|}NCIukwNvikD^Dkj`M4w>XRcP_TFV5{}cS72wd;6?IG1O9>|?UWermb=
zB~c{3+3LEN+opA_iw at +JJ*N`d7nXAeZcmz-`*ZenmV_4HxKm$xO=K%YajRPA0Q!o)
z16g1G7~MUE$%Xbu-TBiDryS~MI5r>oV74pZxpcaFdzs&x9Vb}NRXe;lY2Rfl$5`ii
zMpeasG%l*XQ|<ph#{q at 8tb?voFDqqE&^Ge at 3don2Ts%r5nNW`l%DE7=CCCTv{{C_Y
z(8-DLaCJ>hb~K~z8F%>(#AcX~q84Yx`p<+6UQJ#{Be!G27u#}O|5n{8GeM(6xiVR<
zTwGjLf7;M$Oo;0TP%UDl#p~W7k;x>hH0ESy4}h(Wzj>Nwurb(ML`3AMEl?!8H+LG#
zB!or>a7Mc>{^Ym1vWvA-f?4_3Jg`vT4}c_NG1#ALaGqaj{B!+#`R<{Kg>1kex at V%k
zcpM_+9Bvh(`^FS<|MjHuUY#0(l>e_B#cSOy@!RXP86vxxl<if<iWjGBk7cCne6+Uy
zRJP^yPkjDwRgci|uJ^Gzyt*ib>P at Pz(eKFll})8dsn1%zD(I30=@L<a9 at m}-JHJZ*
z=Vkr<FD^Ey5=_Q!F<uA4eNxt?8AQaJ5FKz2eGcSj&z=nq4jSj&37Le`RE_&1=DZ(-
zy+$Tii5JK)o}Ig4_-wT{OgM0l^XHGNt3&l&r%rGTD9yC9nU+YZTUtI$i5=Fne5f7x
zwb!AtJizgRO})+Z<CduyTSuPK)3iK$_j0aS1i3s9muFHVnZEq~M at vL!YtN3K?|9O`
zwhUd4qj|PdIjnk2^v}9^aJYrdhu^Bsb|X*1Y7<ZGad)>oh)^*xH_*6&Vyt$Pt~UVZ
zCY(=#;sSm`ZM*4Y0i+%F_07)Aq#u9AO~ryvLiPCP5z!8XL78K{ysRRk_~Ip+Rf%UF
zO!LS(7=07mf5N~3Lh`ySMrD6}bOx?1K-CP$VCR9N(^s*J#P!{?f8qHO1lKrU0k;Wr
zU174Pk)y(3)3cOitF6iTS7uq~jQMv9-%s5{S-Dcuf9TzdE73O{?}?EIJxsV6e=ZiX
zK9!A3IH%$_(Al(Scl#_|K*X~Y@>;rz7uxbnO@~~)4C$8M8{fO4lRNJ?SmdNs(s{G2
zZmyOw4O(-Rw2K!#{ruiS?tqb*#SeQO$dgh1f|cA8P&LRpHKcaisz_31^n-sou#qnX
zo;vyMgW+5d4xwqLtQ42dnl&1^`T0?(55kYb7q+Gk+}fw{@yz4`p}5Q%(M$ZlEYe$B
z^{zYDxUPMzy6h++{G7 at Krt>_ICf9>K(~exKGt)XX1Zh5Mt_Y|GjdQ`C?a9}&pF>Cf
zz2-D<_lwC#6!iNcb`gd>fP at NLh_P`8$_v=h9sN3_ZF!Pna6M;dq(;V3BTWhX>+oCV
z$m3ye+$bnWwNy3UI>u6GGtFk5VD^rc<}e at U!HJQN+3G?ru^(f%3pOxsEQ)9~oju4%
z at w0TPnc~&{pl@(*<K-zzqg~RXJ=>gC-I31l$^5(%TLc=84;)Kk<6V{H5QxjTApPF$
zV at k{NgG$GeJqeGTm)0?IS}d`CmWyq>y7iB3z2vL2r8g_2E0<;UJV-Ro8&R2g!3nXi
ztz_yPvDP4tPD4wpSztVN7s*Q`=guoey_o4O9VcbLV|BN;r&_0M)XdzPW7t&#e)wTA
zenAC?Hm$aohSC9>kv`3|cd1^szP1^DkFD)(d7^kHF-Tsf8%CFNyteTjg_|TVEe*y<
z{O6E5fshmF^TlNo;{`-mZ!a%-hdRbij5tzFm#$vj@|A0&M#!+#7K&WNLx$*`jL!WD
z!96QeI(yV|Q+GDs#6g*@HM&M5*|Lf|yDlC*Rd_V|@|&#`uqt4eife`L>yx}T;_D}|
z&7r5K;v{oa$h-TpaVIqigoG$d at o{sb3HEtjvIh-<L>QTM-8wxzJ?UTufjH0q`vcYz
z9P|khkI(W0PQ6+y6!Xu8<=j|UTs#V4)Yh@(<&(*hd^|kH`MXyEQK39{xqDKogPWH(
zcDu~dx;hW(BaCxCL7 at q&*L~C7G%j%}yPaEYmwMXlVA$wocG1&j#5>KLL{ljM;H`U~
z5ID at HO$!MvM8ORkC?~pT+79W6!qx^d!lGIsS63gSuW~HwSXn2}Dbu-(L3-I+bn400
zVP(TzyU^#TK~fBkjcU5KYu97=M}kDwHJJ$A#Q3B+dR2HR)&KF`lh8u(>o~G$HPZaC
z`K&R%wvc1VT>h4T+Tm=~?16+kHNLL~Hi at 0e-a3+|P|;Y+pj2%u78&k|FZ#`r9LmJ)
z(=Xabc+5J^tp9OEeSk&Tg6j(rOeV&Z=I}j32n at 5cY|7KAGofhZsxD!Su`RS4Gk5oM
zaf+Z|3sIOvpaXyA;OO}F?c2n}M0NpXA3zkq=d$v}xpm7 at 0pT9Fb1bDhlcCwP^zGB2
z)NK@%DV5X=)_2V_n#l==eh4U1V at lRg^5(C?Sr6H#M_(RcJU-d0lPxmTp&jLu6h6eI
zXqJeF9B|Z_^wF#7$3~C$rGoPu3SLdl24{Wrj(pP|w}?EQ at G6x~^5%i5%_H}%N65-i
z;l(&+o7wrpCts*!GAf4zJXh^346b(lrtPcyQ{9OEY`(eIM!UoRoR5p+Q8b%OV({K9
z$truvpf6sQ?%S%-#YzoKy)EF0Cc!~sgqg;jN*(d>@zqR01_|5FSPN=9>as?6e=x)V
ziu{}Jue5}~C+UY$Sv%jvk@=~#4wK97?tUr(%sDbb%0>Bw$-&j}<MR2#&xW6*RQh)?
zJ`+xE6Vm*7$itWR7OUK%XoJVo at l=bjGk+2+mT&Ib^ZowInhYP&=5yOAad)qr2_#z=
zjO1<hQ$wo#a?yvA+qS2@&hTeL!niFi*qKZfMM8Fh4Y7c9(0l6Jx{X&(IM$zwsnU~p
z7N_NZ{_X`C|24tq%XW0C94wP9H|gyWH at KpUt0zgxk))u|hpU-t-WWZ%&yT&oTB4v>
zMHS5_yPpD`g`i+AI)ifn+!0+<ujPs-IZ;)>2p+uybD)vhP at YZ5vW&7QACISP{*l|X
z&_aJc{%rD*R8qO+=-rVt*DCUhTLLOK*0CkhyolAlKofrKpr2+5 at s)})XFr=z at 57gA
z6|G^f={UxsfBOe)w!dRQ?vQ;CV6{^3ZSE5N4#S_MEF1yK)`}uh>6UE4Wqd^J<DMU;
zdDgXV2Wi!|O>W$4^Uv$F8Phq#!HPL=6*AGUh`8Ip0GhejZrj+tJ}Zp{ocbSo$4*3|
z89<dk|M~5!H*YkQl|vvA#(V*Fym{i7le_QXXZwU`H*L~*L_ at pjApUpZK<DY6YwR*=
z5SH#XH0&KXEh#N6pm|I-m*I+3co4y1jxo_NQ2n?|tI-6*F4F+h3!juvT0I`9OX>T_
zuWqp5<LYHxviqC40IQ<hdY^9|l9Y7DkWDg<y<ICEMRy*3$k$$<xc&ELF-{*voimY7
z0&FYa at Sk8v^;U|f-B)PwM7||=hq~!FJ$t?agDTnfW67S+g!Cxu4Sk7rwusQxW%$XV
z^!UlMIKq3#4+>yoU;eTPdYK#OCy at wAS^KoV*V&P?zcXJf%_f>Ig2sd%dzcQ<Ce|$M
z^P5miFZX|cT6fYoou?rqB=F~BNiOz^?I<{k?#=Ej?H0M#sUxtS#FnpYQQgRSsXY8N
zm(16~gNq}1?X1II=ema}UModX4V4aI3L!revMdR<pAmHKCZBqhx|cq{rH^K#a at 4WU
zC0gfKI)<O5{;IIxv*>u!#p6>SrB8eonf^qefw{0Jb5oz6n(sKWC!N6No#7we(U)XW
zlwRna7#Fq)HWG2M_w?d<0LRyzj!8daabLr6bR{V7Qr7&z&q0igEg;a*!H11Ad)&90
zm=&2buv1+<9QXI3mO(V<Iwddu{#qz~?hQc!T;tY8M?)$ocn^@tZCge|Wc&KbYVRK;
zQ)33cBWDr+Or4HHA7|pU_x-(Sk*bHI%U}1MYS$5Xd02e2XZ3?khu?-VarP9^L@?VR
zFtwWgZvQg;WVz;?Xtmgd at d3k!F?5;+3!<i^M*<OxP4mKQ$~G!^CFqZ?&bi)y+?t74
zjap0b_vW?kpOr!?{N6uk)!j6F^;3*>eM2$FH)R>}q<L at T&cV~dYs(e<2AJsvHGNS;
zS9CRn8W`PTZ`plne&nK!mu>G>rrx!dWScl6z70`MZa(i0l&Uh#qY=i%C3?&3*}E5#
z at wZm{_C3ho5+~?zX7zXe<P#oxS(PJ0T7BQOwjXjlmz*r7=@$@i7j93z2k6?)+V2Xz
z%gTrlpWw{M!V;&X0zm<4w+7}S!5hSLhTld_(kt#?ExuAVv;o9>OW0RoscrT*H>;`r
z{2p;C&8)acsB<Ihy3D_sCfjD-STAJFKba;$#BPJYPrD at szwkrbC;)nzAkWXMq{GDO
z9<buye*yS)0EG;!5j}Fmj~OOaY&($2ze%&FdY7D782LeAM|Y-g>&A(oj-H;?U!Mw~
zZ5`2C`t=JU`v=FDL1EgP|Bzqh7oI%gmx&j-+jD3`pgmeDdn;%q{(wT#skTe_ at WEZ<
zD);|>#|~4bW5<sD`+MGh&QJ0h@|RZ&pOT}9-f=auSzKM1y*M*GtN>AtLe0%NVHWD)
zQVP3mc97tZ16 at spQ==lL2QUqatkBiPQpEx05i%VH+ZK3iHux`MinpCVYuDU53rvzi
z2fevxR^i?onRQMk8rRhlMtjeIgdQ6kOPfP0Kz$gUcnA)#JC(w0mxQKfZbo^0diweX
zM!PT3(vlgP0vlxYmu5SqFJ#Rp>xQiR&xgxbu0qp-@&?@DbNj2|5H%oPWB7Aqm=bC=
zi~HYYIM4S$;b3NA!U?L>8)CiR(5U~0Mute<w{IUFD5 at 6t_g=nyIh at DM*OzIP{#^d!
z<zrbQT326~oXJX$I^+YesQ7YP+6`2kRte<-fu2 at Tt1H@4fd=T1@~loXpWijykR9+R
zftVzG)a!+<@#0nU^o+QzPt$bX7ls^MV4rN0DK~TJ+e+WN9VeHTo#1eVE&?ik>hg=)
z(--pcK2J{WfJzs?x#>$V?sx^-gB;OD+RtCV>fj|b(>_~wHLK|SE$NtYDGi$)qav(m
zQc(7&{5a$*>tA~92r(hHYVP{;ipJs at P5<WOu6|y*L4xJch#+OMdv39&Cta6AK}$-c
zsoYB=$IT3EbfO~GsUh$|N5^E=fv7^6&bUOHXBuedzVZ8H7S3DsC0g55?7!g-(mLe!
z`t}_H4=#-N2lPGN>M3-5a!9AKDm;_xQ~sYv-$QpVu at w-@oFdq30-mRt71E@$${p4;
zU^tgMnU?C_-xPN+<m)g~FwNtqfzxUR9M4~sID1PbCV9Qhr}unyH?BBO-E}^soh~Jp
zuzGt!*!#JvG;z6L>)L}QZ*PD7(C2-BRlp)=>x3|a3}GZ8i&D8NxwjTA#h=~gY4as>
zD5<TpcXA~K#8GQd!Q~^(gi{LJw-;(!9eK at C2Me5*dRYZU)e^gowdiAb80kW6b*mu2
z0s;#^@g_a`goMtgNpS5m2rCwwg)J`>a?~9)>Vd<6432$yC&jO%`|QD9_5BHbroD+a
zJk2M5Rvp@%oEfZ4Oq$N!Z{&SQCE!hvL6dL~rTsa(wT;F5HO;)Tw^4fT4~;yiRO3CZ
z${EUfRxYj${mkatLuilWVq2RN&;7dTCCA|>InCk}x3#;{&&OS4U{FhRzDq!5)p>F_
z?U~T!KUP~K?XS>J+_LfcU2 at wzHL?4%#$#gr>aV#jj&B^j5<_cUU)RX{%y10Ey=rCE
zy1V^-e&Z(Tb(3wT7blfS6ROk(rkLfd;8UK2$A8w=^7-ToyeADI2|)WgQ6WA$HrCkC
zAfz4`Q<cif{*_qEwqF$y4H^h&Egb87_9A`^`?QU90uG@{wU!qAB0O_qgpAX<kS%?_
z6vUkz6=LmK+t$&%HGPfaf-(QKCrXS0I)W}aO9V~BpQVG=1tP*s$5 at K|$3>WF4)-_d
zCoPWnj@;)o-+lx6kwcWi`mEB(rMfZgQ_PE!W8z9|oF^JRc-E7uygj5llfJ}GpBYzK
zuG>=l?N#XfjJUz`FtuBJG2Z(0nPr0+*KF$x^f&a$I+yg&6}=@B%jwhP6_y)XDGfTV
zpE)LAFVbOgE`wZCqoAN**}MDtaonjZ?^;%%u!dTgkBh7A(|4@=If at p$=~Tp~-RYxr
z@>@2J-Q8Z6f>lV6LTH~{Os%@E9CVKUQou9%lq8wNq=JU)d+!xabRP}A;`)tli`Pn}
zkjBrl{_Ci44HPe^?pI_~4wrkO5t?$?)oYAnpzU at fpEzaDBAeI;U&e*-1YxV%<I~9n
z>%_!3ClbbAZid5KhlFa8=a!UvFUw`J at 4gMYG+~@Bp?dCCuJQ#fn<5G1ljByy`$HMw
zZ*^$6km#30Y^%qP2-?>hoFB05Z$>Tx#(zylI+l8MN53urScm({i9$;#PcXM>Xjd+y
zHITk}YoOF*>gwa`^uvE7K1pr7nij3RIFgo9`B`gyV&fBbd|P9QCsl|Yp}FT;b$uhW
zXjjwrJ>+7({li%J)r*%*#rEQqlBfrnVuuS!cQ2R*d$XI65!`y8tHlHmwnyGu92e{m
zKw;Bs at Igx-)y?G-KURDA4iIl<FFsb9XL1}9&hmIG_J-2-N>1K5<bq>=ExSqL{D{pj
zN5;M0|Cz}}YIzyw!RA0iX6$WW3t2r3OPHU$b8V$I#r{78%yqrIO3t6R2nj(MTR(Yd
zp{=|7+%@&|4p|;O$E?1WjtOWCS=YWfG_%q51J?waDi0$0vu3iygoKhmgT>`8_GzEt
z at iFeftp-|wiJxLd#6A?z=KM-L&1)v)#n;;({lYr2yT#~);+6(r6cYnwp$wD*9aF at H
z!h)FXN;8_FTlsTu?=5=Vwv}k-I_fcS|AtbbKfn)|IG*L#AekkFyBsYjJh-K$RI8YM
z+xbV{EJd}{vnkA6m%xbew(k(1Ps(b38ETmx9wuL|LQ`tb at VkXR#RUfZmow081Zq!g
zE2>452>{FL^zMX&wIt=~8q#=xnU5R`w@*A=zsu0o at 1xU@l{ITz{kgjM?VyK8vBwvB
zLtWq=r at t)VNFb+ytt>lMwu4UWzTi6f=1Kql!gwM})55;;C!1gF2)FW?j&>Kdp~1Q0
zn51btFSE|jP<PCyiTLT$CoC?JREztGl0;lwJR at HpIpdi|#@lHi_?j9TULGD49>$`f
zS#Ca`bw3K<ePSw#qyEA{PM^%{*N9Yw9yo-MOoE}IAq{C53WX4YpCx%9vF`*pNk|iS
zVl&egVXNI760^G^zI`C%RUWb=?_j;EW5MA}i*kPA98u|rYL?)X6a|xS7{JBfLUACV
z5h9sqLq~08vRk4s+=eMRY#agvGpRwhHx&pMwh&RFwed__t#~Ebii*ii=S0V-&;-&c
ziZ4u{)Ze~MwR3Ua%LzSqO?`c0^dz$(?p5tMlP at aQgTbOwtz2$Be<aq#v~q+#c7pMr
zhy91Jgkl at +8CPp%A at IzmHjOqM|1^#Aa&jA$yw<7LC73%Vi897oEB*Vwp;G%)Pm)?5
zDyD|v$<Fs(26#m_H(w1?z!4{%KHciQgJX+&&}cihxJ<~#ioRjN3$YByq{9ryzi<=*
zfj;0UfVU$q+9YOWWv#zQV`gevzWmwyKBftV9C<hJ3qIfI%h=q>6oL^&lwpvpUAk~V
zAH*0{J&x($hYxX_&Q<AiG$Q0Xw?tg*7H2GKArm(VwYrdxA3Dac1n>nLR8E_p!lD}5
z24!hUNwN%gVqzE$r|b#z5-20%Rw7QE04@&z6TNTZyvBY at D8^ynBq&%uzZl0DE1D!9
zLz5DiG|oKFuCuJ*{*Y0_krQXJK+%&q&xRRKOZW2v{?L=N{Iqt80GhhHx-L|?1KSd5
z3Yk>IG-4BtZs#T)9qQ(+5MEu5!wdw05sqg(6R^Ujit4*N#~>fZoCkhZiA)9!V7QDs
zuOKYT)`{NfGY?HTPh`a}Xw9HEfTF)ph9mv~B*K`B(evh{>pf;k=49)&Bt^|na9*DU
zUNgzu7*mBZy4T*5dUJvhUB)mnfPZj^Et<^b8yg#GNW|VVl61Np2D^!*UFrq^)6g_x
zBs|1c{?VgH!x$1CERxBfLW0%}ub at -{{eQYUIT(=cerc4kRYVRt-4J2iTYY6~vS#Si
zJPPAJ`$p=d14a)~Sdodf?5ZbNj~H&-R{izv?{ihDUFcro_1sj<y3hKE%h*=Du0JA@
zXUJio_V*ib5j1pk3VJ at tD5u){`j+0i7mbY*&U=|~#Tejlt|Z9KT|7~(g*bC3bUGm}
zNYo4p3{Y{a6nlIVTIx4haZOob#Ez442F!JOkKy>GfivnI=p+FieEoF+92W>zd|B%z
zJypn)U at nK61!vnwTav<<xLimIBV#+*wF!$Sn6<)iu&%cZ1GDmPOP}fog`iq7L11Xt
zK91L at S2+8(w&ZXg!^eSEEUsmYomfx(D?Z?*TTZ;{?fr%m5OT^t;Qd`W4o2>X(YSwM
zP&gjJp`k#ZwmFOC0;AASSC`zbbTtUV?a|fbQlQ(I#k_bRU+Q5jfu;SiGNjlTv;n<c
z=r|#ad#4q-q)dHmS$`kf$G<!BsB~y;5I?540ew&SU!}fxlNsu%95G>%kD6c}z at D}z
z&z{NQ5mybb5vKsdnL*)0-Pd8gSRv>Cm^x!fqRxT8=<B=LSzxQjLDy^W_hhM)pn<*{
zGPyqQ;xnjC4<A0<m at 17^U-- at itA(Ucg%s|vg~%Pys;!fgnVq$Y0a?xe^_npVWAw9|
z<?1mfjxa!>P at rCK?Lw0kGV{6 at W;;%;RHZ5!#n>$96Fnrp<37av)OW-8^2oRZp(J$2
zJ0v9N<+)8wP2J89i{3X+bMt;#Vb8UGJ<T?D_{a}z5T_Jt1r8H&gC*}D6-2zMD96zq
z%~zHc<lvy-z at c(zHGQpjv$W>fY!E#2C>GG%Vr&J{>%QmDjT3A5 at kk+wH8U}Z9dbW-
zu;T#N<`GW>9IDvbp^T|N at CWV~BlStRZKEXY+NJeqyOP>9JA0=4dx_-93a6;W5eCEE
zXT6edBr{QK^6lHNYW8u2V;2sGW}t!LliavqJPid6nJn;s>=@`qC^sNuzLP~@3Q6h1
z2Sm0Y%!Lc69GV$w`HhPTvM)hL-ts9*J<F$X{R2bzptV(8Lt_aV71t^~Aj8;1(u+CA
zLIs at VodxWt0O)}fibmswxyHD#BjAn{A7UPe)~p^AvNh_>(AH&onC}s%q(Y~-UDnhi
z5>lo7{CqTxnnJ|=uP`RG^1Wbn=KVbp)vvHD#Asg39zs~+x)5l-D>3>R1%(12LgyRq
zgc)l{6R6TpoGFMI1Ox!0Jx~QU%t}Yy2#8{U>iq-)BNuCq0zL+|5r{l&KhKFKjmIL6
zGM*rfmp<4yQCC+7EUVXkAm%wT9(6{v>N<0HI73e8{hO{1<dEScoCD3^@pXfD)}iD7
zJT?{zG!_>Z;R%fl*2^I}T;(9$zHtLH6WJgrezm+o1c%z<^=>mLer>B=2C?ez^-tpq
z5~z7O<X2re6&!qyFV4D2ei|FQC_{ln&qEH at a=43G72KUzdR82bs)+H)D8J8axTVKy
z`gH%k;^aGbH0x$4g|ri)QBimE^M&gMYTRg-oi}gY+E!+4H~bD_A_584j0AgLCy^g4
z>7cvB_C-Z~d&F1cMrnW&q~<(Tz(8GL#>;yf<2V2>Z)W6>Dbe<#j75*A`Km~l#@X7M
z?)?}j^CB6KS`4+-Flaa$QiEuROPldBn)=}~FQ}0S1VTY|;Yss?ou5B^D54}W<2lpr
z!xGRP&U-_RghwE%_<+#FRK#Q)XbBGv&4QRbLN=|=vCvTL70|&h8(F=m at x`}C?s1Z+
z)71m!z9eXV#QfGerX(k)Rn(y)f^IQ=WlM?V at p$S${=!uMo#@r5?8TFNE~}^2A?3<@
ztU!?ke*)4#+XIU|dkD^%Ap}0 at ns1{e>TVcP#XV0b=bI3U7YzADHL*-FUIkLeV2`CK
zs;^#2Bc&oDBcswY%_EN;Ja`b-2orHYE)BiQ8UH3!m5Db1z8<L94><^H9`g?hQp~&9
zrL($Bo6|iwyrHj$2pX1NYYzDxSobePG3- at X_nVNw{I(|Q&l18EKFij^g8k&HckhJa
z7jba_LXe)td4g4 at I;{-fUkmkV2{En~{D3!ZV_^RcsJOu5Qn7H#TQF3*v0HlDjOYYx
z-8?-BZ=4+*axyYJfTFxg4dfX1(f<g>oVpM8TvC#ekx_eRXY3xr*Tg*p_Ndw6wOc5z
zZ!zC{-M)4lQE<dFBn0AEC1n at b?NzWH`-}k{y6hhd3wa7|u^v)9b11^ln2ns&V2m~T
z8`VMiAtV)!6yRsTiK2uO6UIzUVx5E2P*!X-=a7_eey}E9&_P;5nqQJk6dm at F@K)Tf
z(zr%aUjECQTQdAYUWf!Z+n{?;t1#r{X`i at _{sJ at p1M5=#Iee~v#yCCyt&ix6DHiC9
zA6(p`BTh%y>bG{|WmPyr)rUbo)4pw$8g4ginE3RGK|3oWBh?FaD=ce at q0_SW2?UqB
z|2G6WZqBob- at CTmixCGzC8$cT8ndj{jc(L!U*UH^xvlas<bB_{P{(pqu^Khj)C9Jt
zictjpnVi<ZGlOM`G=xH}oD$6z$RH&1<2=0>V-d^WTOmag33~}k$x{K_kgn5K_kW_E
z4l%##?{jlWEPXudpcvp05|Z7!EAzf#2DSzA-=on*;*$ECxVTBe+ua``m`zsrWAwzs
z&#!B;WxF$%kJ3J+{F|=_26_i0i!czarFHq)5q-#s5Ha?6%X~mary;rGOoR}M<lv{U
z4Kg%p-In*aZcE{q00AD$s&nGU*{alMsLr7HwD2zH&OgVb9CkmOhxruG&dU4?7d~Qg
z_MstXbBD8&6G~SjJ5h(Vuaz#lYn%~H>W;(tZx^Z9TS&x^Iy_ at jx;ud~szEX9F}n5(
zkyNEO%qqdbD1AA7lZr|xb$MeZVb*JQeje)x_?=1AnnmiLn&n3r8O!^0E4g#{-EdXW
zT7=v#(<N0oU}@}!@o|Y&`tK-2pkQqmiaI?9 at yGr9#D?`Bzl2>i3Z>yQ^v_>L5$LT;
zEdu`#B0#-Dw^CetbFKE={JgbK(~&WJnIH*^e5aARG&Ca{x4YBjdG5vxK4yziN*N at 0
z=_}{7wzgt&pIV8fTKs);<224zRv)lDj<PKtMlr(t{Knop))1OHrR3!?yY&`}k)6fB
z#BIZrABe@>b~RV(>OwG50hkI-D&%PnR^7qzodz5R+JC>=GeQK~MqJO5+90%Hdwm*w
zP~?oqLY%onQ?sj}I1o|{SmK1(avu9S^m$^U-HY*%!C(V|m6O;N{Y{KkV$vKF5b;SW
zy9Ifw!}R6Uy}R48z(P}}eY?e((J`c)JsW=dV1S!$b-Iek&XXL>r@$Fpk at 3LTM;Z)Z
zrhWyfAi4j{B$SkRh3szs1n(l#@vo9u7@&DOFp$P{_2M|<5$+rk7j;V9`3a5RUDn7$
z_EdiO+J17S>A>sPeTf%0_WxLj7fsrAg at yzTsa)=EBP^HV5fIeP0n~e;6}8f?6oCc%
zjhe81y^J+$-kb!K9?ggD(X#Rx!DR;}I`TVJItYeOc!)Hf0D#|iv9=doHdSNaEzRgu
zsH-z-Tc;O1pOM at XWwdnCkTxrw?bHe{LOxg|VVprmaX}u&d6Xo><zsNEK^i%M?+tep
zs4Df#n3<V}w`?vviNXXdar!c12wVlKATLBS2`d+)D3fi+t#4pHO-ANSbG$=XSXg at W
z!qi2NlLsb7;a-_4wyopHXWg-`$e|lGHM4&^pS>KncznX!knL+4Q!lJJq5#2?;nwnf
z0^B}d_5&u!e&xUma}<o2lF+|Cg6Rlpx(XwMNYBqhZ|-&A&+cH>Ka*9&UhcnwMuyvm
zPM2GcK!ZFOgjh$N1JckqHvLj=`}W?>PUhlY2uyl~foN7SlZ6eKan(YoBPFTwJuFi_
zwM`47N}$cmvlTtDcB!}=9evw9$TepVBhb+uuto`#boMNDE>Jcctp<jvk at 59&G40sY
z)TB26Ni)#)xU(%SkxowU03~9#@udsj%yX1|F=}PKelPbe9;)Mv%#zMJ+?K!nz7o7(
zY2}AU92j at XOfX9UkHe|e_r6Hj8H_9b95Om|d9{s-cK`cZW#Z5qng*2m$lShtOe@}W
z^lAKQAGI=WAIVfREFl?Y at q#cP!+sZ)5yW#x*_0WTPxhrL?ju7bjR?G3(bL`c!aI@#
z4WiIHd<NbfaU3&{G^91mvn4%v#;sJ-Aq>5Ce29Pj`t_mTJrQ!dv<XYdfPotq&^Dvw
z0`CZ$jIwUAD4>l_*fN-p%DT^9YFLT6Y8G+8)Xq8<k^**q#rU32sBwppZ-eruho#ET
zKJ_?N_=pNHKSd(!2-D48blkN<8FpAB#89wz$A)*OD#8Sc7Oq>7VM=XOg4PjN5|hzx
zxO$Zp6;#=rVgk{WzQCP1<P5JIG_`t)o?}e&$bx7 at _9zDXs$qM(O{=kit~G!V>bO(a
zLz=v-EQV94R<{?Nf`o*wza)KzB*%RqXXQ*HH)_W-n07vW+JsjLZoNJQU_VgvfThC1
z!=fVbrrpmBv<a}sSwW3-wKj+pHf*8u$H2QW9&phXwADy|TP^a7Ws0$W>HPe~<2Gv_
z-$ot+AiKC38z~i+JK{>(5{VdK!x(f2>)!mEo$Y3}8yuQ5MlZG5t!Z?&k`VSJ?DXAY
z<G{{N$oY8R!a2_{g)S$9g_#+<njw1^Hzj|1noY~*EFt``9v!SDjEi4mGgzsdj0G82
za1g^LbH&tAs${b+KA+&=?`3(cVs at v|$=t6Whn7L{A$G$@<IvXR)!Y+(>G~R)&zdyA
z2Q{F9d=Yhr&|{!E?07yR5HG+y4{<<CbMvsqX(Tkv&7w&U9g33ICynQ0ax|uv`lg%F
zVs$lII2q&W^`M`x0y8z6{N#5$G>8zVW!UcWy4gzkaCJENqR<oyK<W8)O}wsg76F0D
zBq<Ssz}`*Nt$!UT>Ojpq;_Bh>BY4B_jvD2(XyrI3z!_c2$w6h?g5L<Wv@{oH7`ouQ
zrK<x{EfUZJ;4-S at 2P()8B??vx`}CLfQz_rivu+L&cH|M6S{QuvWlw#=H3EwV1ZD*u
zMO)1-t+_*=*wx<7cw3~iW)t}Z`P#hup at b%;c^q12XJ?+A9aqhklQ`RX^Tsv^Gb=x-
z$+lM1(h}M!G9k-=)o+^0%G at he9bA1{o)^=yD-`O&rIsY8*K0L at d+G@uYGd at ZNkwEA
zJpSg$-?y({pMc_QGq|rm^OO51FQNUr|EeD>wGq|1P4tQ9hwTZQ<9sucMJ%YTtD9Tl
zXxCRDPvq|O)nZ^9yw|;rjhRNbe6)GsfP{D<H`mmK>J47O7;*RbcM0S5!?`@8jv7~X
zV!n~@M<g^l$oWG<L#PvBaO3(qkU(Q65aMU^ox!hcHyL;k`#C*;Awa-T>wF2&@1!9#
z3GA;AaE4D(-bEVueQ+|Eko_rH`M-A+(89Q~B{@y;BBQd^DeC at pw0d}3fTpWquyN)L
zi~0vlXHuhZQ>pZ#e%==%^kNAK3DWbk^x;acm4Z_<4<XwNpc*|E7$_MgYD(i2&vHud
zS6FEy(bv;MLS~(u%jumJO?1r4*U$@OfCJ#iEgVD$L=T5i1_I3k3|GLm&AMYpzjPdM
z9h}#^%a^%Zs$${>3iZ()$&rb6?C9?^R}0po;>TuD1-!qj|MQA!rq-13c0P4Wt}&RK
zP+}(t=#pN#2L%U5!&Mx9n=$H3OH1dlh!h{#zpP}S!bx>M!bWmq;Va(8M~`lIN=!{m
zDiaZA4!O1F)n$}sfmM^IEwCcC at 9|@azd*|R|GC at Tk^4i}_}*x{K9?%w!tGPMj^MDH
zYOL|A<=(}MJj-{`l>zvmq^J`&(lsGeNJ>ti2`HA4cE{8!(2tPYFwU=1{Wt7%bpwVm
z&`3|pX8q at TVfg30aQZ^>bp|aJsuavy+<@Gjh9nA4K$sUlJ=9H at A-n;EdQF`-Gjm>A
z=M$0;+>-F1N at S!z;Hm at 83Cce=Ccw2%DdLE|tCyE~SiJQ^pc9xwo~Yo)#gTKUyWV|t
z-C_U3ll!`2$LZ-qP80eYGe}mZQuXqHaF=QhNu3n*9Fk)+z0Ns}Vw*{l(qtMC at CELW
z0B7!VM at B~OP7%0;Yg at MQPfiQ*yLtm{Bq|5s6y30wtE<bXDran{y97==uW}c<{-!3V
zSa7gR;Th#DW{Btyn=)N*P6O7|%pGT?**h<G?diKl*UO3z<3xeDA6vQLH?er~Zhiev
zB;N;>V=@FmPzuOzA)%qCTF5f{1K~%cAl={1kWAy8M;)3r>)Ct;Ku6isr(#BN5v=H>
zB?v&+s;q~hAle}&Hdcwlo}T at vchK4%e%J5~6+yaKlYP;85)dLGB`-5%AgUGrs~f|p
zhv17wP3ndVvH0`LP%zMt$i>C+Rf}}im|_GO|22dVd!5novR~@K_BKH+ZXW}BNlKCy
zaTg at cu*zoJ3D-7%KvCo4yl`Cbp^%a3(G47dtvvu&av5a?5D&0g4{4QHSyI$;g=^Q3
zjqD;ir4FP7n`-;o$Nl}G=(cOd`fO%M!WzeBu0Px-V#C5tXo`U0{e|d9w{Yq*GPqIf
zN$b5CQD|Tcir-7-v`2w{`Y2uoWMcks1woo4Q2k~0n45#XIe{e-L}CmCfVXa`oFp at z
zYMqz>=@@^Uh1bh}@YvG3U%%N!j5X&AH|<7#eskNeKI)@{g6~y=!0k_%H$saZeDb7L
zK at USM!})7!IVu1&f&v3mpSqOlS(3~78v;$t%!+HRxVgDeY}~&`eMB_eK2_8=!OpB~
zwQv&U43vmq0Q2zu7L&OS{{F$r#w6zMEbof=OAu&U`1zCJ1S+=Ru>yxLud3gpgPp99
z2HRn`&GqrD3xXAovlziiM&ABre7CrfO6<XaK<415taIC#m0Rhk(7XNlz~!%Ob+<x8
zUR7OerrlG0b3OQ$o}M0y!p6IekPA3}#&bQ0f-1!JG_q27L`3U?7`m?hQ*}*l*2fh>
zv$NeKCNIQK;DrJ={`RCGI^zlGJ?ykQ`fJY9c-I(>^ZxxXS}ZF&&XA2TrGwXcE+yq^
zZ2=cA at 39Gr7~V-gPTsW#FFd^xvWqR&7YS1Prn$r!O^Wq(C-OckD>ytDd)qKDhb(-@
zmUX!7{?gHT_VnpY?-hnT!_+Cz1kYWk6qVY{`k))4-V3%~ZW7c`)wmIuh?!*W2S>CX
zk7G+TT^oclm|RB^>f>RwLf{M*Fmv|ux at 5exS*&R-o{N}(7zGZmAhxKR*iM;1OUUHf
zGfWBj5sd7fnV)a&%~|X~4L_Hfo<3E$K$Y11#oYf9BUl`Dm5R7{`Z>nEVTVhxw>fy_
zg)CDI_aJ8xBhc}>n>W*SE+arxwY2=9GF!}aBf|Mkq?ch|Y+tqK(e>QAW;ey-CHUR;
z<Mf0k^OC=tt&L6iHRt-2B~rHCDzp&A|Mj8D7KUL|<0wI1-X9}v3{5n>Hn7}i0=ua3
zdk5<MfjVC<faG7&woyXE&A;fIpYGgrMAfgiUpa7d$BFaJV!l_rhi9 at +p3COjefw<l
zb$$D7*(rnc%P%R4NhX<hDlCqlDOdQfpZdayTw7a<OAGXC8$Qtu*ocxxI|n|I3g@!1
zmDDn}YWou+tk02l>s*N89DewW&RJkT{S<%0>tibqB<6l^^HcSodd(!%bhp%EQ<UJW
zZ&o~Q>`uo+YPHq9_h0Pv+7tZq_0qW9v_O-6eF4Lt7Xe- at s!lx*0g+^}ZTEANW3AL{
zH`T9ROR;d?q}DadpZ-i?j(_=9{@u{ujVgkU>zxC9cxG}Ir_~lx1oqRtP+CxB5nwfr
zdMK`~|B9Y>Me9}m)5yKX|8;(^*An at 7dBK8piTvd2)m{1ZNdz(e*Q(TB2ZyPzUkj*w
zyC~xm1lNdXjxP?mJ72kb<8H88^@!cf6+4yC)3MT$uMQpBbm+O$@WqHn?O{otxuvsK
z6mP$SZv#1e6#VDbkG|eLzu|F;LrP`y?xDpp^L;^2ns(_c8O3^^*zEbh^vui2*r9CK
zo+6v`%}jYGQWo?46GqwUqRwpiT~)4~kY9CVd^+#gpK^zk=G{)T*Qy6!@GeyhP~OQb
zNGtpKzhY}jAL6tj?90mL_e$SsoD}evu6x6*%xH;OQ<yYa*ohk1+ruN;{Ia^Pw~jYP
z5~wf<udaHD9_g4!(0b+iQvKa?%L&KJnL_6`j%;B{wS&H4MpIeg=T_r`?>BQyl$^^W
zYu{^IcG$C+{-f26&rkKHXkMH~+}D>ruHyE2hhJD-zo`5}C?a8W3(e;jnzVD{VjnBt
zJfkO7`AzH+AXXmy$y#(`q#!eN>Xv=PZfl<Zx_yUaD9A0Rlaf-Svp9S0hd*zJHVWqo
z`bKO`zZbo_6Vb=1br-o1TRX3iO84~?e7>{t`n9T%V(Um2tJX)u!#f8_sx15r+wwjh
z%S|+=BL$4V7}$N1p(($#{`_KM%(KCRk-LVtwG+g?TxJY89LezW!IP0KjP?3Y9kliB
zQiHyxsgbuQY5Gp8&Kl94S!4B5DX{9u)JK(N=0;jpZDOG<m)}T at smhcf%RYIc;B)fc
zs$>S^6aDo6_0%Jn=iw at RIWG^825vcLFidO<EsebS0hU-~E1m*Fn*}*_g00x-FJ{Ky
zmsA#>ImW)3b2{--=|_d%Xu$JtntKJOIcoOzWPBg(@S=?I{yC<{(UPDrCv5$yot0PY
zyb4!A!kVo=1isxl*i$ei(A2N?U1eUF(U@!1ErMQt!7QG)@WSTYwSQjqhSACKsu>-g
z+Az6Eb*_3!`LOE<yQBM{?tI8CyswsVxvAV=lbT^yqKmH={Z}O2t53Qcy?U1 at YFQw4
zhjRfN6Rx%%$V&e<gS?}U%i!IP9k%Ntv%Z|uR{fPkXgapf(TnyLbBVl?($me6=^TS=
zsCg!oYXSyh=)w^KFIN#$d*Gq$2m&R~lS4!V)~eFT0+$QzX$D{1xZn}bidWEnf8&(U
zf1Qo!ni2uJCK!HVLk372WK0E!xQHNVCuHML_kz0~Zkso{g+Ekz^#98z8iOR*6rDeN
z_T<km8*zxJT*|Xg-v`XpHo#XMMl1LZ?=U{$``<y~Jh6KJ4RKM?VW4#Q%yu$(H8fNu
zwd(*ZuIJ{qc5pDklVHHx^osRSJRhdbwe8Hy3y}|la~jw+9{Wpelyk4oC7cfx4B-|~
z@{{4OIW`xppThWG&j?jF at SQtNP2*!@y*vP=8YapD6*To=p7r{=YOJ;JFB<1N+1mV%
z%`XK}58<bVL1AP2^xiR#XN8|Bhx6{5hWSYFKhQV-*rT^X;s4-(i0a|RD`KB_ecylm
zq#8aSaNzkLHVE+dmU{#O!A44?R^|BEEd09T$B#n+5AbR?=s&0y0 at s|+BkC*HtP7dB
zQObEwMbcmCS~u&{KZ0*>S9*US1bp5xZ>G&v=p%eY-|p4g#AM=~`S<Mn=f$qwZx-CY
z_-bTFHsL%eO17=!mC91sI}PIr&9Jzgg$%!|boA=0k`qrF#Jyzwv|F}jvTlF%ah8dP
z_my14DMiNjo}DZ;zSl1Yoec{5|2R%RXr6r>XH!;BC5oy?Evw^Y$_9po-3$K2mgfo0
z!Uy=y1CWQ<pe%=((3G}k|Gva?xL&6p9}zyjPn@#M_Pvl~->yz^r|nsJ`T0|;=@VhW
zT#a2;G=KJJ>+iQzUI at b-pY8I{JL2Q?{%McOH at lnS*IaT7w{vTyo7>;Y^Xw0}ed9>_
z`S3T~)i26b1nn6Uo!3{&ho22z#xhU5m{s$o!T4?2m>i2O?RvUS$+%$izsUVtG=H$-
z#loTo;$wWl*Kp~29F)<7H(w6}wa$Y0p_`tj1s1Z{QuZfM1QOmFw5H<Qw)H%GI7*$N
zJSA`eZPbPhzz0n1Cf4&X*O9|YreoT^#95 at CH6ZJ{ja+q}H_7+w*|khb$kg><JB)CU
zL42k3V{_L_e}ATq>V^3&Tmcu%MepCcDsqYbEpKI0kLn-Z?L(WYj3u_s|C(n^JUqJI
zXhm}}Y|h^J|G&yS%poBEux}0J5#pNLGr*;2)^xqQXkYNt2`J}OT^Bm|_-ya<=Z*j=
zV8KJ?;N#m}pQ;PE$xTW_<`I7C>igB-(SIT37aM44<3Molq)PE98lz6hHW(t<t!`vQ
zmt(f#{Z8>w(Sir9Tl5 at P8}E&`a&OEE32zLHG6`cmZ1<?)-)_pL_hyuSVW#ztg>D}o
zxd?@}$k}ft=6fw;qNj7~Ly%<ZTsN^GhJLt}*eY!hM*jHog-XbGP91tV?aBJ4|IU?V
zbOJL2Jw0DR)?Ja|FyLfnVS#BdXobnsbLz)tHZ)JezI5WW$r_qLc-vZmObG$~OP&Rq
z17}$vsAK3=i>J_N0$W13(Sh}K2dFavSR+OQu|cd7w*guSY;^q#lfS+b=oFFM*lcR3
zLKl0`mm!kAH5jwJ{^rI(hU3SfVGU>EyH45Q0?*y_8_Q_hjoB%~n9=)#kyT8`vHk+>
z(&lBBtNI!9UWr-TT$*E8^EHrP{azU*63xxKfuln}z@&|aeGb5dhhTTUwxh&des;mj
zn97W7?LvP+?8h3m_5phcw4K)9|B>o<iHf0pBW2;cC1j!WkLS_N1tQj(sGt4X5=sU(
znKv-R*x?DJAR~$?ktQN0C0;Jg-|g1gCk*mKP(g%XvGk!b(_b`$_r-^6MQBbJSRdOM
zxPh+eZuWslrT34IeMSxQ-E8OE`>pr#lkFn+iDWIdxVG#XigV&(M>hJoAwu9ys%OXM
zp_iY>lO*1$E^MEj*)~{9^47Yp8X`WCH at PWFpx8@4*veC+#YFjDeQCWfMY8t|p*L08
zcZXRI#YTBDY&v8z>V@<_<!j$o#@>z8?qF{+vCU2;{3%dtQ#;Y54+aJXF)V%d{04 at G
zFb21PWXFhZ34QHG&11 at HYSA!@C6RQox(T}|0LBqz!1xo6&-v>^><^;M`G+wXiwC`Y
ze6XXt2RUEWhcb-zk=%G7>X)a93G+-=9WibXk{@3cFAWV1QKO}$MPE<vei$~g(X}=q
z`%N&oK!?mv$NdmT<_JiZyLaybWg*vKfq>Ze?wAMq^$;wvzm}7Ahb?2viLjf`C}OgG
z(C{kgp+J4T(T6sR&Y+Zp4<s~=eg9R%3TYnYcwiva_`*$)xa1~C_MSKl-iX?jqN{#z
z&+*nFf+kJZo40RsFI at r=5n~18FqS65pHrc_?3Oaz%p(e|oRE;iwqlFNuCp6 at fwVSA
zkc2TINgV=kWQ<_dUdOLE3a|uxKz!vMBO}WZ(f6}^RUz|Im%@PLCFl~;e1Fl%$q>mM
zEpA_0oBlXGk5Tq=sr`3M-0 at FLEM6iA+zlFLS$}u9R4Z2U32qQzWixM2Dr{kAXQ$xM
zq-Reg-&>lJiH=^y>@i8`D{>P?xm**0bSJ(6K!4)+aX_tXZ(@#SCbv+!yQ^j{5cLmA
z##rg|JMmUYKi~t0>+m={o|bNDb>-{o{hC6w*GI2AV8T|GATP+rr-t?N7!u%cQe@}6
zwB3VjX=%B}^noq35x~Yqzf9t4u^*FfOan;%?fvQspBdj0T)i{T at -Y5syE$r?TP!l`
z;KPMx9t-oz6Q1Jz7rsQT1kH#gp_4^$7L6;1Psew;6?Zc4v9-Kw1?frjf(g<M&7^X+
ziK*NpchmCAHqHy&7U4x{RDR&z3P3)$2WTNv-}d(t8~6RVU$~|*u}8UK-Ei{SY+G}(
z?%^%xw*_;KS3Z8F_I-<v(2I$GRc_vF|MbA6UZg14ub(_B at 6=$akt}*~1P>MlsUfzi
zR7D<4AM$K?IecatH at UYf6J4tiUW$)_BO*T{C&MIeGrxj)(32cS<?A}udzKzzL>Yqd
z?I9BsMShw+ouUsd2`;9YZyJNQZkPg<TIfyj2 at 3lG3tmx(Co*Ly=H}+btQl~UFyfE#
zbd&0^P1~*5xsyrx_;MJURZB=2WPSDDIg3*Q>F!Gz^MtS+Vx!T9hNtg5VAbmC>f-2z
z{4~aS+?of2xLx$l52RP>bv-?)cM3&`(TUWcb|lGlw?(SV)R%bX at b;nmvFK!A6WX92
zC at R&)W>Q6mUtWU&pg<q>h``ZARzZ5j%FD!qHS7MVymlN&s-mhdz&@8Y6XUcQ=;&h1
zj4DNRrMvKa7Ei8#r<r8tj~QpCi$!($oX14$&pPF`bkkT|N8OC4D+#Iq13gfy83!Jq
z$i997hT;}{QgHS}G(s3(Q0?wLKX{)6h>z_BpU204;H1Jb-JXVZiN*9V7O|Pl1Y#v#
zG*}+|18xlA1*?AE1N#Nh0THC$Y7Mu)8T at hJvgko9$);%m<FvZ`NvDRt#-(9>L&So#
zETK!UAJT%&Pi!5?ZYiSG5aFCsl)aRjD<emN3~r5K!r<E4tt)bJRFw~WwrU<w*8FHP
zTV_nGBW5M at G~?S92haM##tmpw+gdvPQ+{hCsbfc$ZxPHE7sLB1`|i7modQ2iB|w8*
zT!aVse%<%IRa={@epK9lL&yJsC>=c(0!1=^;hWu|gQV`B9)=TCBfd}5yHlk_RaI^0
zKJHMBIhzn4Un3G^&SplE=XyU%-$=D?1<(!H+EU`K+ at D(;0>j*+(nUD+*i#w45!kyr
zI at S(Av?6uM2S6u0d~B+Sv>-XFsOABLXm{5p#9i#RcSF4q8ykBX8UQ*_V#f6#X5_g1
ze4v05<>KdOsxo6zRzSa?V22M=2<PZL{(Zck<6uC5{4c5EIwGxW4^#tjs<`j>R+h@^
zh!?IYx`qY{5slqAeM$72e*XNK=(pxNjyI`)J7EbCC{W1t#MzXT5z+f;B<<MHNC?Bg
zKb{&SUCg<3N%_doGEmE6$FZ0$_L^X;1pS|&VSA>>U=Dv3RF3hBY|#Vcg}ggyrOjgD
zRoX39)e3K~TPTOlY?iW9PYYMl<@37P8TYq*l!}by7+i}+Ds_qzwey$ze8r=y8Jxw3
zeu31%x!&bH)`trKQlBzV_7Q9t$m6u`n9Cgzu2|bp-<R at W2IYsm&4Hc6dBYFVvubuJ
z4kyqB>dr~3u6?N|teEx)=lkl37*Clx<3oayuGcyvLoUtE3 at 9nmB??{d2DmO6Ik0Iu
z+?LV**#7;OJm%LO+Q9lF_0t=vQI?R6`OjAqZU`Q)wLeo;LfT}UpRb>r6YIEg_T816
zU5AZ-+Pet;+IBVZOr}~|Lxa<u(n=3gkE*7=|LV`ISpO<qu&xAO`1$m%RB39v2-62}
z{E*TF2L{3t7=qu=RD1vQ?PUXIuBAf%fiQ{Y{U^e-_C;-4XgNxZDP=y!C4a6GCm+`@
z?~_Cv9N#}E4NLHNbGZ723}p at Tt(-SNmi%UNAAVIh&~v}>?s3y^ksqRe*G)H at -8|N%
zx=-x+YY8XxB&g|!d|&0hzLn?&T*O#u|Ly!_%O1)_v-K+jCuI~R)+hSKL_E%Cm8H2`
zHc0n!ni8q)zh8ek^)d8Bjky|z_6d7_3PsSXS}E=d_564K`&Um;EI{|>(W5bJB%VLb
zS!_Z&Q-||+rn?jRIJu~(C>wQghN5wZGmI5qtA+u460II41Ads+4Ert+^=M}VPxgd?
zvP#%KLCW--XET8A#x;g(g6}y?tdy4gzwX{V8te6a8#bph)sCGhQdFi2nd3H;xfB^g
znUkSJG8EFJNK}Rl-G<CmGGuNv$E`#Zl_^7JGRAX!YJd0M-{14BXRY^L>;325f9%$_
zbKjrgy3Xr7kMlT=Qze<)it=ULCY9uGnq1-N92zcjQd(-;yNrP54o}nOhKwgEkgTeZ
zy<N)_`3K at xbGdY0a6MC`H2zj{o=22L+oJ7*T8n$Ho=M%7LBnELX@<*+Zm*aS?MMKE
zM-|8soHw_>An=iLWls?S2FW}LI!T4PPP-&i_kS-sVO)lyGdB7tJf1B at E*kDZr=~aD
z`m!eI2%4JYC)YS0pI<!tBbmo&b=h?cgfjIw*_yb;`@+kz_m|`sZbr!EKUWbWsz?vo
z%bo*;xiS15O7_gAh5Ko5`_uc(r72MKvd_O_V2amlweE6Ke7~(Wh@^I{BQ5SKL)C>^
zqpy-$?2P%SZj##A$ZZ#uKGv~24hFw6pZ?f>jZfPWBgnEDFInbUmWtPJcI#D0*{}8_
z(<dFO#EAa_mq9^Mv>PM6%Ti}!`2g+-XTHj2ocC?1dfYsBkJdvt9 at Kj^47Tv at 2`~F;
zq-jRBRM?sSpP(v>KUgDzsd#;zonN^zN4Rt=^H^SYW#uj|WmcqFS-6%q7peGS^N at G1
z-Yvrc>N at 6}i!RBS>GIL&ZJO;!k^&`nZz9#<u9nAtC|f61obfuh+U)3)aQf|e35g<_
zyXMLrbH{q0zyo7iz5Av3#pi0i6TAZe6Q!KDwwM*f at 4&mRV*PmHdn{d^_+X~Q|JaV;
zr#h~}0R&FzA?tgi at Q_H<e+n~GfW0Q*(XvAl at G3S@8_ov+Vz(;4roEBl*7er6m-$u)
zw!yI~Y2Hd&PWHV~&ZAaslsAcsKD)l4AoUTlWNZ9+_W9vsA3Z}q-CJG4HgaW?rdwgS
zPR;jE{fU35*gjailg&%V#Z*xd<91$BxkyFh_<KFxEr||}48s>0u%aJX4t$pIyV8`F
z at j|QSp5~{_5m86hSn88kXXJk at tzJV>-l%Bexg~a&%Ke;20w1=tU9u7^-@*GofFv}Z
zTG at DbbQuhd?w}JuxaPJ$xtdFox{eA5Zdsv?MhcVkW(CwVdKc!?ihn(u4O?#&E3f1I
z)iyx`>!jwvgT_7)1c{rGj^<{6zS`3sq-;P=Qcz{tNxxh<9h%>iVgA9>vTAHjO!A at 1
z?@t-{BWPd~(JR3zY4#G6^*9JZnCY3tA1<t{VPN6BWp{tv|M5ae)9Xki+V6I7q^}(I
z<2GLyIK_H&$`9;W52FX;Ehgjw{@<`j3hDkv^;v=|iA!td0xV}^XZK(_Wuskpj0SAh
zpnq*&`L4U#{IK;pK4#PFO7fphjdhj7`}VDAfl6`m)#nn?CAxNurvN+r>w|<qLk;7R
zQ*~fZOi$mwW5;SKu4So#l1cp+k#|g9X{bdeg&lYgSezJ)j#PSG9cYOlU!|I-GqdxQ
zhs)?KU48Fr|Ipz}_Sjns+3y0KWZ at V3(foT)@^k)SX0&lpDEzdflmKxH2Am6i{PIjh
z>&5>O1NagC9HJ)rf<eouS-~x$_7M>mPaRfDqcIoW`S({pz at VRK+p`lWx+4`l3rjYy
z3~<gfwYshA+1t%^2QfmY%8=vrHv=b0h69m%b);>KMi at A#-yZm`G<R-3bl-V<nZngx
z!Jl;``aE*&kpw;>7>&1-;S7?r50cqLaFsobc1%uAVyq7a+Myv2+N-v)ziNfpU2bjB
z?&Qrn%^DgzPz at 3FxHrg4*AMK<aPQ?Se>gl@;}^Jfn#m%5al{D&?gH(O*_580dE-}p
z#p*PldtUBi4KzHOpEU*D?C|>e_+~}2BW1uccHa}fk5>Sd1y^U*XEaloj&j}$f1Uv3
z9QbpfZs<bQTN=Hp>$&egtZAjGJ8<P<zlP}BlU+1iZO)D?G$RqGNKMZ;jm$o`R7=js
z1^Ww655}M6jSyQ{e(`DDk$ni<&+EAEe<Cf at 6L2inZ!E$T?foYIAKy7G5=HsXApZnK
z45<ld)wg1R9v}y;c|vE$-hQ|^@s)rQS6+)l^?`LTlE=gz&coOwIr7Shhc>(4+*C7x
zCQFK>UVM^sa^ywQ%SxrB<Iz{m^AngZo_wbzb?(XeX<-1w{1pC*@%3>ZgeHCYCQ^iZ
zTW9|K+%ltG-YqH29TL;<K%k^(@1*^k{T#Z1%X#){ldl-t860Up(q6`)Mj~@hsHsrC
zKCqi(>WSPzS)HA<uCf44iiis>n~6na+#h<?QRYAUYCjhEFAlXxHArfZ73k{e!BFH?
zz+ndmhp5^DLDS#2bf@>)^SdFxrRrMy?<qiZ23CL;r})0DHVJVGUgF!fUA?o1cV1&`
zxI}R*-=FVxx?8`<z!PS=jy)4>Wpr-R<KL}5m)WTevq^9lp7^54Hqbx%Sby!p$5$0<
z=p9f-OZK}eS+5rQ+2ZWH<KCOtZ|auP-9^XO<a^kRe at 7FjM#p3=T&_-7w<Tn^NI1*)
z<|s5Qju{sy8Z_!G9J)%h`$T_Msj-3Pu#N at v&- at VBd%y~!xm{R5M5O-Hr#RXCm>AA%
zoqv`kvcE8%bO;KbKi}L3dKdm%hlRZVvxR-o5;}dH4!sJO?(A!_zjjB)++&rz`)XUJ
z^7U9|{l!1>TxC{S%Fi at Da#Hx?-t)ubZ-xC*akOu!arRfTW*4#uUfWKtN%C!w7$y04
z$)*8=KIJ;m`|(G&0wssny7hXYu+Lqh|C8C-&<NO0|E!ks5ZfIRtx&)8v>b_TH}QG^
zJtGU4Jn?`HX8+T|>n`a4Rk at _PIlhl6;i$Q=%zt+H%>x1}1Kw$!yMX!J6E~l}b7uRz
z_x%A*#~T4Ysa<-!@~X69DF!odmWE=^q4D9Vr#SH8d{FSpF1`udjxTSJ4Bji931m<@
zY~XVHA`sCDsg4S?L;#a&8fm94rgABGm~V4(9-<X-*IQywN_f1j%=y^YvG6<e+_hmQ
zbZ?G%s%O97iltT2$2Lz?G-x at kU1Oz}Ab%I4xpmAc{A`*RE?4cDbjkRn|DVVzAG}_J
zmCh{ZLV8-`-$7*!z5MX^;%CpumgT<5q%HSepj?)5=>U&T<zGRW_|>KlZs{kxRqQtf
zapF<=67M{G3nlD6dkC*`7exGNZ#XZ{F-axKErEIVUfLjjePPP4t-0a6hsXN9o0}Nw
zzi1tYl?&f_x^Nm|qnpx{uYB3eda&tLAnh4G#jTv+bR}(uMo>;(zK*l3c+H`I!uibu
zNuQcu9^;&oR{KDZvKbA?D<x5}7)%mdy4Xd#DrE}CCd1d^VX$L8<?E^KBc*%oH~PXA
z>Oh)_ez^`OWd}#JdG|3!0jM#LGO$(}u(c8oPC$%8fB9j>;)US&_|D!813qOD@~eAS
zkzlZ(TCxD(NVKOPKQ35Ys-wx!o|Bes<A1?HsMxmBoSz%m?Y|Px*xcOaYHu(Uf?wi6
zg?}wLI1w^4u*Zo8CnMuDWI1ShcVGwt_--qkxe?%kwu_497Zzd?W2y)gdcPY{*NG!4
zB?XN4Hwg-3gEyiYN*m9u;%Yt$9V}+0qP73m-^}poLaz~ag_zhfGxm9<@uwm{18_5%
zMd7%sY*$BcNg#9s?LqSh0!&1BI9M>vC`3^vD{o9bRkH at y@Z{;Kuc{Cl;0Avy^HS<C
z-m?gbK9F7D7_EupuG#2|S#woYKlsLIE<pxEi-&gP8A@%{*DwrLmv6EpGlz!MY*$@#
z+}>5ZT%IoD03hQcB+9=pfeNo>l0dV7tEi}`pbo^PD_i7TBTW&<*$K?}mBvIl^cyeo
z%TwX~GohaQfGz{d3uyej06vr~{DBYQz at TG`K$8C6Gd^4Jcb&k>NZN=r7QU)Mm|YJV
zC($)F_GiJ*JLl%-|I(R4(~6(Ghy)Of)+YGh%v at 3fgech48+X#dytGdg6I6eFJ at FS0
z?}mr~H0xEK7_jyhc%+(fJ at FV^4<snI1JV3-Q;rI_9$k!`{4KiJ$j0^v^bK%go5h5&
zu$x`cFL?HC3QcXI^LCNnj2R!yg8$FE*C!uSgZ=#c2+iah5USOO11rPPZ2A4Uu;r_%
z1WHG^o5;$VY~KKgXdE%$V=euB5dP=2E0bVFZxa%F3kE-%dKO}C9kCLi=>#wXQRX&5
zK~T=GyC#bIf8ljh{|L{PqJn~-I84!nf)-&X!T$oa)X2!l$w}Dnr^f#M;EGo~dUVUx
zP!2oVf(%FyvI#IGuzm@@pECh60JzS=)fNI>aOS}-JP+YaXZm#{bsm9$00HfX{(gQC
z59f{pM8d`i-MCwopN)>59szy~Y<rL7OyV)p6V?~Q!#clK@(4Y>S-m%?lPIO}dK$h>
zf#Db_Zh;|v7A5N(5Q_nMCUi%en@~{99QiUj$};wQRS}vBGtCnx2#+un+#mp%pFBDI
z^yyQm at cO@fdpGj*D!6RK`l{89-gO+*Jwg{k*L+x?T(IiVdoX~itE)eDbU;Z48tYyW
z5uJh{Vqwd_0JRGTz#yd1j7bmRWhD)wIfQjOy1JNSw_(j?V3VKWDBD-<mMe_sMflj!
zEi;@sa|X>Oyb*3t7k9zH4&t at 1cr>qGy)rR3UtCzguC}$eCt9a^@8Qg&?zIuBBj9hp
zzbG_4o&*Hs0tR$?6cRff(j*o6EOx8}>@i!UJ&;nM*2Y@{<c>ksLf^;Gz!_+DV!&co
zh*LUWLS%%$ZgGFh0WxgU-liSogZvp1w-^B38^DGugM_`r><lclN`TApTtYwZ`RP+<
z&-PEvL#~k^dzwHrz?(s_J80Lkk+{gesD67wSc0*5(s|e!Jx-sVKxC+Sc at aAgx!6|!
zmF4qu3<5Nu(7pq6QMF!TLd>L=iLk&4 at +U?u{1`DGpkCNKkI<&%zs$4dbMR)Z>i~(M
zgo|m+WchG8E-nt at hFr6PHA_#yCIbWrf-I0qE=*)a#KhW38w at i{!posw+6>xV*srx_
zrs27E8tf^^#PCa<U<)F$p*~TKG34at4w4BX!9^fI4O4C3)z+>S{ez1n`8E|Xczg^O
ziZ}dR0*z$2Nv at 5-7;*##2Rpmx0?@R8Z*t#gP8k_9?RgeX30p)hL-w?1d#E&bIe);l
z5Vzqu)PlZ3(aE+0{A_4+Vwm^(GH=j35wRfOXDe2u2rVDOmQSLGTJkko82?-`b_1|h
zL9aXY>;v!;jnF-JZVrFeu at 9{NLx==&F)P8RUffF2--t2L#a?6}g=iuibT9?cEaF#p
z^2sZny*^TE4M6X{;o~4)>+S7D5u|TBeopDWo3%B~<(e8z%1?l<;+AC_&yIt4HzcXg
zkhTQX^g7-xU<!aF{Cly8XPT4iUoD(O+Xjp<pp%5D8WUkZ`&<@R2vq$xq0m&iuw;@*
zLjRA`<1CmBl<3^s)Qr2w{s579(_t_V39-xWT5D(oSB=0So>l^bRcq0p3vkF<30rzf
zZ2Uc6UOHh<{Pnel{1m(Hj7bKjjZ~?nn78uCHo_SiVnM>7ssqPE^ltC$aXbuXx&^Qv
z1&?e%`3CarFReRUBN2E)QS-wAQO2zctN?^6jzgU^%*%vdJ^DQX_1J>*kSoDX9m5^~
zx!z`!0 at acGW>^?-(pAHdPGw)d{2Fah%s5GV_|OWZbcn|LhKCg}?R}7Q4o69NL<CI*
zRs;*L_9SB)f|2ZE#NyBIfe!|b2wck~jKBBqXZUq==3g7)7?60ZMj*rz6V*69SoxHe
z(9QtX9XNxBHwXL$7X3s~sDAPII!AQ6xFtduq;4 at CJPmaI?dqrJV&=M}2QW)sI^*ss
zOtptSlwQG<*)aci`g=q|=R&QN4eb_T(ZHCrFP%hQM*yzPD){j28`ivcqUa*}q&N{0
zETYcVixf4Dh>O#8V86N~lmZAHb3EbinV4mF3NIl&JslNeGrN;6q$a;K6UZxC*omA5
zA+0loOn%nd`U6f?9+xi?LuS!8z*B_6=$${b$7mkE6RWeqJ%D|TXp%Guj3T$cwh9we
zx3Mt}ID2EjPJKry;06s1jd#RBb@!K^7#reA2mlE}Bxj^TBF9RdP_08JZX6 at R`tYbQ
zIkz7ofnGw74kh+23 at ZJ$QslMm%kKC^+Ui5T0-M8conM!ywRLl_=A_1-Vnuf%4;waj
z4DTOy_YF5YIr2iR)59%T#A%21pIoJx9b7u!O9g(I++Nu^WtnE9Dj`{0%>460!qmAg
z?<NTcp%$;y>W1e*Xx4OKT-2wA-G0-QFy-a#)IMkopIAWa9QMU10sto+X~h|7$&!bz
zHz(B7E at +fXD7$n>&5UW?L7)3bVRP3KVelHezI*8NZ7gI{X^a_3)~&NhcR{Cls|=O{
zP?tX9=^={e`Qjvi@&Ncn9?}NjsI~UsT1LGw$~H;-aS!^>xZt=)anBHEG3gE2n>*8e
zr?<$su)pe6APn0arYb%6^(tS>Yzxh^`<DZ*++=iIvg1X|Ojh>kEk1^a^!aq@$l at Rs
zvr|N{g2_ExzlYJaMb|j0^wjCogB=CKn6_pPp@$cS3}CKJreQ{eb348g!@}TtQ*h#)
zJvtc})fS;FA+h6IWOVdEU!UNr49oJ8lqn>GI(N3O+q7wPWF$T^GIjJk=F}mzjk=Iy
zQThWTrEMjP+u=?L1*4Yti2-U_23dJ|Y1s1%3v1tuyL(qqa!3(xA2oa=N_mW|tl68I
zmR3JlTPrIkR~z4m4#6g4ycrn$L)^7}R?xS0n0d!JIcCoKaty>(G1A&!zhi!Gu12M|
zATTZM+uEIF6l9DAe^M=(GCB at i3#hU(1#g<q!}MazRx+RO_uV^czz5Nh&E$!iURwOT
zl5p>yJX{u6*I|}OZ3j5NqaPltNmpF>S;9dKX+&qerHdOR>(Y`-Jw%tR?oRlzyFr?b
zRn^s50n2E at 7nC9!iqz#(IGZiK#X{t~DD7&~9W#J?>h!c6V&u+^lfPFWliHSWPE~at
zx&@~w2pJrsPSyD7>W2I{q&XyJD|hjG5=$=qG|VGxQ;}6+H{A+ssl+#;5tH{LIZUbB
zrjUAR at UI(c2PCGdrZ#1H!&zyyBX-vO8AEWdz9sk`u-|$|Pyi##CK?%#CxHAA8H-FC
zD{ZJ}ydc2xvGqO>DIa7CK0Omc;{z3#`z=6sSwWiDvI0OdD?i(oX$N9`0VjI(!Nz-l
zsm{;!gbDgX?|p_zON{%WdC>tUOM6?<uL-xek*$13_Uu8<S!w%N{Yg+zkfCQ|Id!?m
z;NcjA#3DlM at fu_GAko6hb9i&_fj!ligDNC74LAaJ+H9iX3QNIC&fIyp;O5!Y8fIo@
z8HXRFgxK-$@MK?vL{UfEFv3j2aL8a`4 at NarZzqE;vK?B+pR-siZyFm%kqjsA4|Qi^
z7cWi!qx96*7ia=bGUSi{_z^kPwEO5yckD9|;i0TIb%khCPa05=OILu=>~?xl8I(r%
zqocRmJ-lhpLz%QDo$vXsygU&`Lu)ovj0DO_L#{%RE#u5gztr!A<Oox;o`-sGpCEDQ
z*ta24Vp-!7o-lM72&Tl0%dP&f?dwgY8wHsq#bdZ7qi1x~GF3MQ4YZ7aND31$(~yum
zVvEy*TQue{y5PYJsQXf2j&s|^+1aTz`-Fo7G!jo283<=4yVz&Xo?)+o4{r++gu8^h
z6izrWY4%p1qQ0U<(wV$+`LY%>h*<mkkqz{2g39LX_YcQ;C~oC5kvzg(<YxgWS`H&!
z+^eWaj4EX<gUrfZ=}dn^vF|;9PZgEtxfDGNihbw6vx}dcxP^ub$?-)WzP2?GNOTnC
zcHz~a{2vmt4DQFyh*vsqRs~g*VbnT|%}Y}WVgPfh*l#|sWR2<B`I$B=Xa?Z0xn+x5
z);tz)tqMA{X}pSK8s;^fT7`9yL-v^d3(;aWFVWjS+$A?VDxTx_<ym0qs+ynOCNqyW
zxfh~g{J!5#Qmzq&VM}w$;Lf8@`I~oEhx>+e%IzL>FF5VvQ?j5-@^(bJc6agpP1^aU
zV at nFdCLU&U<_xT=SXgvYr_dNhApHpic&f<tYa1MXsrb(zc$pQs=B(lN=cUWfUF%=}
zMFo4QW+~vTm)A<qN=(d~m+#(9iwAaZlanh(Hr%mFpX&0T8yfC%FHDZlY$J!W(s0R3
zD3dL`S8;{qBTM6$+%iIClUp{CJ(ZMjd^z%Y5F3TEj+%KpLRF?g+RcRyW%4+qWBH#n
zT=QFgJzh#fyh0H~DtO7eET~Ox2DJKaCWkBIa|OuMHlV+2X=?6 at r*Gh3+t|CNGkrK=
zwPSS9uXz5<1j#-`-o(_9ckBV)hVLH_<Zo0ir<0o0_;u6Ax^Y&*`UX9!RFTnbyK1_N
zxH~_6(oJhP)@d2&RcXhzBAH8<pKxR1T~<}@l338H-*3F;BslP><G`7cvIxJ*USRuL
zeB$zl`st8F$>9r!MeW7uq#AyI#VIRdl;+yCi~X@~y2hXCubbsrN6o2zxAUo@#CR(2
z;E=?f_Tx^I_u6kEPZ*!Us|EkXbAWOjQ6_bGG%qPK`-5Nwn{Q0QZV&s;gV$d-;Ix{@
zTOf88Eh|L8IZaB7qObyf7C?=sC}H7pM9lQDj^E}V5_ at e18cObOxDm6Knt5v7uLr$h
z0Kph*5PQ%R-hg25Db4rZMlq3o#Hb~Lz4X<e)(?I8)_6Gl`>U=6Ff`<&Ef3$8r?ASV
z at S~`#&iv1<EbJox_igvD$}cS~)n0YuoR4=*m*6-BYbd^zg2NM{de4HgzwW4fw##>@
z_p_vaPX>dNB6b)-dvHR%(~UNF`UDO?xYoQk at vY{i&l}zL+PdF*X*%<<2zBVM*Dyuf
zao39+sF<BDC~`J<=PS!p2j^2 at 3}F{#OrQ!NHdYmp6Sx}npgz$&m^Fche!<QtI880%
z*ld|YJGSFA*<|*%_3ks9$;Xv`Evdj4kN$b$rxRT|OO7m>M8NbPg6OQrOsMZ>tIzr$
zY5kdE(r}c~F*@wmQX}vB*JWhKqJ-Wg at 1Yrri7f?=%>sM6kQAWIUimP3=zl)fH820Q
zBvwR_j2i}F;wgN}^g<zwh5mC;S=wiV>Hp;_C+-h{uQUsPj@&9fzwzf=<{R_>y|fUc
zwlld^QW@(M7soV4zsxN6b7F{2IQ<x|Emkn45UCzt#|P$!(-Pw;LGsMeko%T<&i1)+
zDpFB1^RA;%Eg!{I#qGAa!bKF=;1A8_`q!{gO8&FTeH-?ZXeqID)9~_dk;T&3v171n
zhBc6e#;1krv;FyzGS!jt;d9cX0y26s+Z|UA$%>Dq6t?I^_b(P*Dw`7WEml|Nlj+_z
zlInFkA^fL9UuV|Fzdsw;9qBQ=$)7{qwFllxC(X<{%7<@cEYWrh2OC at 1bo5pYr|*#%
z_b&13a+$PpKI+sT-xB%ZYnIIw(MAQgJmYEesUD4-_pb6+WkLrQUAoGze^n*D^rMsV
zP$$uDUxr)7Q%v001G|z=R6Ao9Rw2E76uXhkDi-sMD&{M>*SKUgv`c)-IasJ4-~ANS
zviOQUzN{}b-Z)(&*|;~=*Y9d(0r$s6b-Ie_n`56B_8JvlG<>?a;+cJPOJ35GgXJ;~
zb;92srMYA-UY?yVIS_WxBI$nE+~VwA#f!X4+#jCK%~#5bKKkj{t~0t%f!S0fgLi3i
z?$a9 at YnROV^^|kdzvJVVuM%*@!hw=8 at jLBxA6rm1RifsV=}vS1(I|9#{TuN^Vs?}-
zBX;bWK2>36<|P*`Ty62^^JcaF2d=|Hx;M0ra!n5Peu}*^8zD#*OtoWM=-BYSV$Z$V
z*$bIhIVgp$)DoO~jvcW3%;>Vy<q)-tLC%#=86{ezo at TXQ;WFTA8*+k}@bJW{&wf*S
zr{``B`q7w0y5G%u9cq$8JS)aQ`Pw2=tIBT->73?mW)h~&?HZkTJR+ at 5dL@`Vus7Vd
z&26RC?c0Ga=7ElfWqfW=2iiCD=Q at p49dUX;>ysDDK{>GbV4Yd5tHMM14$BT}#(^Vv
z*e!2{!kgCpeiY&J)FXglo#Zg->0K!u6|W}gzJk|*P~w7IAjSAuy?@`<`!*&0+?3+B
zy)q+NRc}j2Pw%An<T2hWG24ATdb5uE=fH}OZ=Bd<B;HI-<X$Pb at gVWcwt|3BiQP)G
zlYI^;FYLbjH1vA7&GP3Kvf5gvf%k8RXIAZuh|OcB4%J}AmWbh_<d)Ggf7$#P6$v6t
z)@c&y8A`SH$h_xqe)~H+<e+kg$=)eIen1KVfJj>2^(V<}EJ-r!tZetb^1-_`mt&#`
z%d}+=1vg(bwI-)it|&OGCFC%7R-i_5V_spNoBA6gx4r|dnPaWw9IxA!iJeN3v4JBR
zAAPSDs~30#JM}dW+#Of4@|GSwJQm7%c&ONG_D3F8WBs#&<+Uu-r#nu_GW at jqbnQKU
zGveK;aX0<q{kEMKw1m>k6#qJQ5F4H)>xm2^HGpM}ekkOc5Id*7Ss8!H>f{^_+AtHZ
ze9Pz0m1sA?c+FsUyg%v52KT?iCG`@$))7oQKNz~xqU26=bb1w#PYg~n=mCsS1x9<k
z4CmD=SCnR2400LPzax@}zmFoSS;24 at ckin6$XgmQh~eG4CxF7>akQE2Y4LYxrFwL)
z1>B%<04jp<@0qA`hX2{V0iG8yX$Hx`iNWj*Y?S2I1*wsf!yL!Hu at AL=dCj0^9PO&V
z;Rg2U5UX~xE0_Oe?XK6uwXTO~`+MVeCj9G4T8rKLt`8cjP>;;m&SJH_W at -Alec+zh
zis|dIO1`Iu@^7e-j*fcqbd_`dY~q`8O%^+lcu+}{@A<leq?hXvOY*Co>7=MOY+nfw
zH!k-1{>X3y5yG+a(uqdTd$J6BJl1%>cwQNp9lG3hv2KrmU22}2#fi at y7D7gojN(?W
z_hh$y%L|=$6`UmnkIgAsE$~v#J`J%;RXuXBC%}l0#>JqsY4@(K#;lv>&I-kxEys07
z9X`;%GV=Hl9?<wx`_!1cdzw4T?qHqr*y%eqRiV1KYp=Cc)-IBkv;UnekeX|^k!`N#
zh>m at +S2QTMoca<~twUPn$+JyH(EMbfPkoNc$7es1d(Kn_jnlS8ORuL4ZHapj93&rd
zH*h*Pzkq3U{_WVIlfv at eeHBIV3geC36g%h4^qr%*Uk1c0wPn6pk|dmRa<VFU^xu{p
z2y3#fXq^heB}D{%SX7t2taPNOT_)t<+(D~<Uha0)c{-1>ue<|K!%uX)5iYQP;p at MH
zns+|TbmEHF<-J at L-@ot~)b7<>IKnX#8ibwvI&0_g;JH|vV}1qK?0+bIow&kiRQ))k
zpIg#aOEB!1r-75K8;RSEN5;B9uYhYPmB)a_tnl${Zt`f$w-_Y}K8ourn?B*pesQIL
zz5ac8Z;=~*APjO{t&lcVmAlYlwt4_hr#{4?M|?Tw^V!f7f8dpTx>NYWO;SpRyz(&l
zQ})aYw%U`NmuBLGA9MSUMP2w-G2u6>XIC5}Lmq3Foo(a73$fF$-K$Si;&dvR(w18D
z=2q_Qiwfl;S<am_OJ+-IlV%DBPMiGK(^%#4>Dv8IJs&@MU+!4Eq`<HzgiF>~NRW)P
z!Z3q#glAdzQ%(LrQNM8p=YxvlrCqU-YNhAneDz){3=1qa<xORetbc!aO{sQHG_j7v
zzMlNX*^NioE~Cnl)S1!H+bNqeTsd|j%&WX+xwg2Cw5VRA*DkwYwN{a<d_Be0w(P6G
zAMCBKZU5Tg$lXy09Tof5(_`ZkMKwO){swnfs!7tA{wY1CsMGa&Zt#eWF%1_h31<Wn
zKM^FQB$aGN$A{ZWHGVXeGu(Ud?5{P5EHXgAb|2|UbR`>Q7vJyXLjMw at qs2eLi0V4q
zf9-J6I)VQR2HREtJA~}J7SQVX*R|Hw)O;YyW2!akq~VfZUlD2 at h%cpChh#;FT5O3n
zNY|esfSUThe(bXFopwK?<A$}w2L9*cUei!BQ_&OO&SdPeWUPPc(clx-jho4bMCn$o
z;$DfW*Iio0^33YG2zAc4?z&isUEKKl&t3-peLYkGS84yg7b+^&tIx>%J at p^-^J(TN
z^3kCI3{+H9q9hV5U8p$t$<+8`EgJ>@4xndr#2?RSa6MF1$Ea~bR8)_Ui{THGfd2=-
zMtKdK5#%5w4kt>wb5T%3pi}Qr$PZVNkAN at q9QgS6?uFOL>(nPyROC~Pj^u%yqs4Dq
zTU(z$PgD<HPpBg-T)y=5Og&%47v0E_f{y^SBOwbw3^lHvF}Iesb{;$lArc#0Lq(-8
zODCm24H+O1sjWdU^4vSXY%@$l5NV0gI?sWk1MR at Cg}02hKS>)DrJ~v{h2+!+ylA*K
zpao?h1F*s*Nj(^(j=HA+G$RV-t^`B|Vh-u+>+F?FlR7aOW(7m={}v~*WK7MdA)`JA
zq4XgTR^S%f^zNmM0EF^se+rAcuC6W|zv!vt+LFt+?LFQ7Y7M*ahmRi at 7Z*VjVdasf
zw6+=*y0ztYqMZfMXB5*C;G_zit3I(s9PdDvxFK{Xfk}ur^Kfto^{k at zz;!}0ql7X@
zL7^02>?axWeZR?C45$aP0(WJuG4w7^jqp0Q|HKGIj7>W1c0eSr2MtE?Uj|41V=!|?
z3kCI%yVrV(yAs-s+Io6-%kwSp_T?BINq-_4jj)Cd?b*|(z4b|1I<gq{C~{I#LSmGg
z;#M|sg$XU{ogY5|Yp9?GFg1+Z(!8m|xiUK%N>c)0+MUZO4?P`pVuZ<kn+igysRB?k
zk_Se*%FUT87KXC4?+RNKyYIW`38X`Ab}iASfXD76-VmO|O7HE1?xL&%JZhJfry3*!
z0|PrkI4CO%ZI!@VGK4<npP2goq-i}C>jnmD<_(YWp1?NPzi%G~1*6wj3 at Z$Y!LhLw
zKw!jDgU-c_)CTK8ln!}AFpr3efzJL4#>?@@p~8FeEMR#cIn3GFnSq7p95Q{t1Q&j^
zJ7BTi-r|^+NIwnznXOJcAqWLPih1K-SA at t&6HMXja$*)JGkjpHJUkCHB0JsDbY;+4
z1)mCFr<Xn`1l;=-yo6X+Jb^~y2>>j2gzdumn^xy%?ixO9_zuJkvnx<MEkk^l2K~Ry
zoYw{P{01 at PQi|{~Kf`oiw+#*AbzAns at fXd8TDdDSkKV76)1kv~Ls10<!l1#)t9 at S~
z9E}KLTMTVO`*rWx?<PI>mVj6RXlgM at n#w8a(uRAYj?V2^<Vcap at yh;|AD`CLu14G4
z2PT2;Txdlp`^`NX<Y;Bc&p(GX&}*l5^DBK7dQEyoR8%AfI;nsp7<L%~a|Wj5C<z_)
z0+{u7w_;*;%!_9klIs1CYgS^qo at v4HmkcAxKW$^-|26Wt(#rBgjr2pjc`!$8%K)am
z8yOkFLKfL6nePiApuEgAoLStWBt?&gN<SX~Xx|u&8rN4J$uu0qR$WL71z>=(Hu5<z
zRP8(4C(uLJAw>xv(VodA7Nau6H9L3i^rRacLn{rhsXp^hE5Fm|=%JxV7!wtA+KC2X
zy=q%#SwK`P;I+`{^|>6YLt=R>1EHe at pbs+UT|z?pm+Oj(ipE-VJ|cV(*o_-4ER+cU
z=)FFM(rXzR^~bV;0a(<S&4}}kKT<f|ed&@jnqIvJpTq7P8>B;!2LT15y%IN4eHFTm
zkukS!-2#EcskHw7pPU=5UOWcWC1F>m8z+0ng_SDc0FI!BI5~sm1xOz2vHR^lp_D}r
z3WGT_RWGlB*B&4uYy;S}<vnOXKWG1lC+M83X$HUh-lSJ-Kn?kIXlS8PVGOk+lr`T$
zj##GV<=}un>mxrJuupw~?xS6OORPYPit0KKb<SGc6GB#ut~Lox^vnr7ZJoQqg8rXB
z%aG9}+>uC0KeXk<O=Qu_r>}K8;kCLKPG${WU(`Byu=3Q`i-Xymz4Of#9OelzFxOe?
znt6S#?9^c^@wrN3g`#N=a4I^trVZGq*v at ad4mWDhrD($oz={UL;jWnZSy;DCE?RZZ
z!Pe2rZ{jisWpdFUv^uPc+ktUSSRzEH>$o?~S|-Q&9s^8upPv$7wdx#13m3_LzHRM#
z8JQyAMh2<?fqkSu%Yp6GT8(=zYOQq~3<8e;&)}Ql7v2G&Qw`PC4v60pN?xOJ6Drr!
zP%PEQ#LhpU;F%6R;TILGehANAu7j{Gzz&<u-MJqph;4r?8NOGye(Z_g(}ecKBb#a#
z&XklCP3_Fb^I-EJ?AgnktEU8`4I)rko`u=7&@S=3WamYJNOV#Zm>C&wJ&Bh)V~^MZ
zd;JZCx^-hK2v)Vj0^XvN3kJ&}M2!Z6Uz`&|2HGfmAZ>fKMdM~oh|eRepNR9m(*ud4
z({E%xgH4im|2_f&Um6V+>ChJPjV=(0Q-lDxIZ5oKw&>1<=QET``-EWjJ%@#m&Wsk2
zU>3|I<FH}j<p!%(t;?UzT<g|eOSorYqO3I{+*_&1r$jsIBq$h*m_`edfuf|OK>|l@
zGVm{LMVxF0H)VeplmSy)3D(LpwXfjgwSu9$wuE-h+p`(a67b=pmY!wPZ*_2F<h7$y
zDwxyqO&T103l at QoA$-b~=f___-iFcb?(Mom+T}Yg3{Vn5G6BQD7sp3cTF!kev`ki4
z1 at B2)BcsT;fQ8c{>-{?p{<v#w8Qx*US0_}esgC}V&dCG-+UJGhzl)#5DR$fDDUUS}
z)}i~=#Az~Vm>|-wn{Wwz-K?hi+hTnc`EKq6*u8Y+&aS)b_junhOYqNSXP|nvhAv-x
zX=y3p!orE$TB{woxw(TkXK=dY!3+`;r}MZ7Z at Y*@sC^<P5ZuiQo##K;glWw>a{p;=
zM$*|)_a!4O!3P};y!6Q~-!ZKxb;-*(v=~@7i5}m!LzJ6|OKLm3M3LHHA+WApJ4{Io
zGCUSs`uRQK{w$<-uZCY-96TDIyoV`MFlquo39i!&9G;0}<?zd)^(-+=EG!8UcG at tC
z#3Tm0{uqaZ(`U~@)s`K1#iv?+>sIwOmWAO{#ox+2(QM`OEO$efzn2=xf`PU1`JCY1
zJVddwixF)b*Z-Vk0w1k5q|7hEL3h(lMOJvqjh<=R+x9@`&vwg%?J?m30DDU at O;u3<
zHpXZtOCjg(hg;j{b3LK=FDz(PVVy;M`;33u+KdasukM@>+bP+rg<y!;8fZo~S5VaD
zOLb!;&{CF^KZ&%FgU0MnxJo|IzUzefj4cW3v6%Y~fGhN2V5_F8mY at zTF-%lg<L755
ztp~`qw1u=8wY6fuA7+Z7%l9do!7=UMch?x+P2!1&V!KT5+MLrclGcwprAewcInNcW
z=yW>()_PG52yrT<QAmAGMx9Czh|Cr>%}dFAhO?~x2cq<y03y|Ezz@~!w+i&lgtYVm
ze8o`6g5<$ES#qD&t-!5rAno+g)kTVBEstIDF))?B9s1sKJ!LY*qU_uuOY1)7fm8<f
zOQN(RhmW=IU+dT|C at egLAcTgCyBA{LV>%B67o0&mOKXmyu{>1Kdm_rBcTa4|YAPz=
z at WcDe#?fes<j2Uc at SC-}m!1gsxS6%$X$cAlyl87HLgX4+S=<RDFl<t^{qV{SVvaO)
z%8-%jyn}X~=cTgIjj*t&5V%Lza#PlymGh!Cvna`=F?(xjk7T337e5^ug;Y4+<|)5Q
zd=Lkvqf&Vh>g^O!kt3NcfGtNHOC(qZaCp`o16ynIo;Cv*JL1N<af-KqPWSe%b{tVq
zK^HD6sttyc?>l&soAPRQuR$Nqal~=bT(fFD1wAvTs at htu(mY2*j=USWR{I&Lo+V!o
z*uSo38yVDrwA@)hDWlQ5ZMM?c5veBFa~-ne%XGQU{FlZ0wo#wQg9hh?aIHji&ije8
zSx7fpA1fc4Mejq2#7XtBy82r|o8 at gb9tqoPP-;5I$&f)vIfFg}7N((P)5iFMo0F>@
zPk((uFX!MLc*llu02?X8yC;CK0mtbPduH~$hc{s`|9<WI(^!$X)4H++ll5ZcKK6?x
zXEirHym6x*2Oi%B%H*An_V$e3C~z35Lk0L>i at FF`Vvp%E4Ba2q>Ji$yH6=AwyGJ_<
zXQ$@*t at kf^!qy%W573MdZl425a)_VE?)4K@!TG at iilp4NQ7?W>P6`{OhNvgDe1-a=
z|LfPy>~p^<e{kouEW{`1sH<P<wE=2}hjE5!Mbr&hr-VM=7vxbeQ!+pkSFQ!~FHX(g
znVBI6MBZa%W+rBym&NHvsT0n9$Z^r at oK$@wO9s7h%Dt~nYrl>ITEY2_;fn0=k<2!J
z*o78!--C;aS(v;4<m?@dSpsv+oiv at oiK(gE#yeTpIC|$KDXl^kXmUM(;d&Qxmz3o*
zOjep1xp}h40vB%9!qv0(7!vfM?l_1c!LqYhBU?S5`zZT8OCF#{Sm4&I4M<7ZIwN6&
zb35;$PdtAw`{n5g&`t#7?JUcq{E-TvD<_E7Mbjq?dAk+s<STcRM<o>O<djCX-(QWg
o^8eE^^#5h``v2Qs3tU-6Il&oUGLXT7d!*9ZcR)Q?_1MM#1>Dzao&W#<
literal 0
HcmV?d00001
>From 1508e0cf0c601749669fd0167dfdbaf9aa6defb5 Mon Sep 17 00:00:00 2001
From: Reid Tatge <tatge at google.com>
Date: Thu, 18 Jan 2024 22:24:11 +0000
Subject: [PATCH 05/14] Fixed more documentation issues
---
llvm/docs/Mdl/index.rst | 18 ++++++++++++++++++
llvm/docs/UserGuides.rst | 4 ++++
2 files changed, 22 insertions(+)
create mode 100644 llvm/docs/Mdl/index.rst
diff --git a/llvm/docs/Mdl/index.rst b/llvm/docs/Mdl/index.rst
new file mode 100644
index 000000000000000..f90dc618bac2af1
--- /dev/null
+++ b/llvm/docs/Mdl/index.rst
@@ -0,0 +1,18 @@
+==========================================
+Machine Description Language Documentation
+==========================================
+
+.. contents::
+ :local:
+
+.. toctree::
+ :hidden:
+
+ RFC.md
+ MachineDescriptionNotes.md
+
+Overview
+========
+
+These documents describe the design and usage of the Machine Description
+Language and its use in LLVM.
diff --git a/llvm/docs/UserGuides.rst b/llvm/docs/UserGuides.rst
index 2f450ef46025aa8..b0b3421ddfa2cd3 100644
--- a/llvm/docs/UserGuides.rst
+++ b/llvm/docs/UserGuides.rst
@@ -196,6 +196,10 @@ Code Generation
Describes the TableGen tool, which is used heavily by the LLVM code
generator.
+:doc:`Mdl <mdl/index>`
+ Describes the Machine Description Language compiler that can be optionally
+ used to describe a targets's microarchitecture.
+
==========
GlobalISel
==========
>From 75e278b9d703655f50feb375ef535c95188c702e Mon Sep 17 00:00:00 2001
From: Reid Tatge <tatge at google.com>
Date: Fri, 19 Jan 2024 20:37:26 +0000
Subject: [PATCH 06/14] [LLVM][MDL] Even more documentation fixes.
---
llvm/docs/UserGuides.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/llvm/docs/UserGuides.rst b/llvm/docs/UserGuides.rst
index b0b3421ddfa2cd3..5d72518edad6afa 100644
--- a/llvm/docs/UserGuides.rst
+++ b/llvm/docs/UserGuides.rst
@@ -55,6 +55,7 @@ intermediate LLVM representation.
ORCv2
OpaquePointers
JITLink
+ Mdl/index
NewPassManager
NVPTXUsage
Phabricator
>From bb6966e3ce61679005179f9b99c89526d8323cc3 Mon Sep 17 00:00:00 2001
From: Reid Tatge <tatge at google.com>
Date: Fri, 19 Jan 2024 20:43:14 +0000
Subject: [PATCH 07/14] [LLVM][MDL] And yet more documentation changes...
---
llvm/docs/UserGuides.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/llvm/docs/UserGuides.rst b/llvm/docs/UserGuides.rst
index 5d72518edad6afa..d257ae975a96b88 100644
--- a/llvm/docs/UserGuides.rst
+++ b/llvm/docs/UserGuides.rst
@@ -197,7 +197,7 @@ Code Generation
Describes the TableGen tool, which is used heavily by the LLVM code
generator.
-:doc:`Mdl <mdl/index>`
+:doc:`Mdl <Mdl/index>`
Describes the Machine Description Language compiler that can be optionally
used to describe a targets's microarchitecture.
>From cdf3212cd6e1dc01b67014bc5f06fed8b22c08ad Mon Sep 17 00:00:00 2001
From: Reid Tatge <tatge at google.com>
Date: Fri, 19 Jan 2024 21:42:56 +0000
Subject: [PATCH 08/14] [LLVM][MDL] Fixed formatting problems in doc.
---
llvm/docs/Mdl/MachineDescriptionNotes.md | 219 +++++++++++++----------
1 file changed, 126 insertions(+), 93 deletions(-)
diff --git a/llvm/docs/Mdl/MachineDescriptionNotes.md b/llvm/docs/Mdl/MachineDescriptionNotes.md
index 8cdd233a2b91e95..5b099c02a981dde 100644
--- a/llvm/docs/Mdl/MachineDescriptionNotes.md
+++ b/llvm/docs/Mdl/MachineDescriptionNotes.md
@@ -1,4 +1,5 @@
+
# MPACT Microarchitecture Description Language
Reid Tatge [tatge at google.com](mailto:tatge at google.com)
@@ -8,7 +9,7 @@ Reid Tatge [tatge at google.com](mailto:tatge at google.com)
-## **Goals for a Machine Description Language**
+## **Goals for a Machine Description Language** {#goals-for-a-machine-description-language}
Modern processors are complex: multiple execution pipelines, dynamically dispatched, out-of-order execution, register renaming, forwarding networks, and (often) undocumented micro-operations. Instruction behaviors, including micro-operations, often can’t be _statically_ modeled in an accurate way, but only _statistically_ modeled. In these cases, the compiler’s model of a microarchitecture (Schedules and Itineraries in LLVM) is effectively closer to a heuristic than a formal model. And this works quite well for general purpose microprocessors.
@@ -42,7 +43,7 @@ _Note: A full language grammar description is provided in an appendix. Snippets
The proposed language can be thought of as an _optional extension to the LLVM machine description_. For most upstream architectures, the new language offers minimal benefit other than a much more succinct way to specify the architecture vs Schedules and Itineraries. But for accelerator-class architectures, it provides a level of detail and capability not available in the existing tablegen approaches.
-### **Background**
+### **Background** {#background}
Processor families evolve over time. They accrete new instructions, and pipelines change - often in subtle ways - as they accumulate more functional units and registers; encoding rules change; issue rules change. Understanding, encoding, and using all of this information - over time, for many subtargets - can be daunting. When the description language isn’t sufficient to model the architecture, the back-end modeling evolves towards heuristics, and leads to performance issues or bugs in the compiler. And it certainly ends with large amounts of target specific code to handle “special cases”.
@@ -78,7 +79,7 @@ More generally, we’d like specific language to:
Since our emphasis is on easily supporting accelerators and VLIW processors, in addition to supporting all existing targets, much of this is overkill for most upstreamed CPUs. CPU’s typically have much simpler descriptions, and don’t require much of the capability of our machine description language. Incidentally, MDL descriptions of these targets (generated automatically from the tablegen Schedules and Itineraries) are typically much more concise than the original tablegen descriptions.
-### **Approach - “Subunits” and Instruction Behaviors**
+### **Approach - “Subunits” and Instruction Behaviors** {#approach-“subunits”-and-instruction-behaviors}
We developed a DSL that allows us to describe an arbitrary processor microarchitecture in terms that reflect what is typically documented in the hardware specification. The MDL compiler creates a database that provides microarchitecture behavior information that can _automatically _inform critical back-end compiler passes, such as instruction scheduling and register allocation, in a machine-independent way.
@@ -108,7 +109,7 @@ We define a subunit as an object that defines the _behavior sets_ of an instruct
The critical artifact generated by the MDL compiler is a set of instruction behaviors for each instruction definition. For each subtarget, for each instruction, we generate a list of every possible behavior of that instruction on that CPU. While this sounds daunting, in practice it's rare to have more than a few behaviors for an instruction, and most instruction definitions share their behaviors with many other instructions, across subtargets.
-## **Overview of a Processor Family Description**
+## **Overview of a Processor Family Description** {#overview-of-a-processor-family-description}
This document generally describes the language in a bottom up order - details first. But let's start with a brief tops-down overview of what a processor family description looks like, without going into details about each part.
@@ -175,7 +176,7 @@ When writing a target machine description, its not necessary to write descriptio
We will describe these language features here, primarily for completeness.
-### **Defining Instructions**
+### **Defining Instructions** {#defining-instructions}
Instruction definitions are scraped from tablegen files, and provide the following information to the MDL compiler for each instruction:
@@ -215,7 +216,7 @@ An example:
This describes an ARM add instruction that has two defined input operands (Rn, imm), one defined output operand (Rd), and one implicit output operand (NZCV), which is associated with two subunits (sub24, sub26).
-### **Defining Operands**
+### **Defining Operands** {#defining-operands}
Operand definitions are scraped from tablegen files (like instructions), and provide the following information to the MDL compiler for each operand:
@@ -247,7 +248,7 @@ Some examples:
-### **Defining Registers and Register Classes**
+### **Defining Registers and Register Classes** {#defining-registers-and-register-classes}
Registers and register classes are scraped from tablegen output. We provide a general method in the language to define registers and classes of registers which can reflect the registers defined in tablegen.
@@ -278,7 +279,7 @@ Examples:
The order of register definitions is generally insignificant in the current MDL - we use the register names defined in LLVM, and there’s no cases in the MDL where we depend on order. Register “ranges”, such as “a[0..20]” are simply expanded into the discrete names of the entire range of registers.
-### **Defining Derived Operands**
+### **Defining Derived Operands** {#defining-derived-operands}
LLVM doesn’t necessarily provide all the information we want to capture about an instruction, so the MDL allows for defining “derived” operands with which we can associate named values. A derived operand is essentially an alias to one or more LLVM-defined operands (or derived operands), and provides a mechanism to add arbitrary attributes to operand definitions. Derived operands also allow us to treat a set of operand types as identical in latency reference rules (so you don’t have to specify a long set of operand types for some references.)
@@ -306,14 +307,14 @@ Grammar:
-#### **Derivation**
+#### **Derivation** {#derivation}
Each derived operand is declared with one or more “base” operands, for which it is an alias. Circular or ambiguous derivations are explicitly disallowed - there must be only one derivation path for a derived operand to any of its base concrete operands.
Derived operands are used in place of their base operands in operand latency rules in latency templates (described later). This allows a rule to match a set of operands, rather than a single operand, and also can provide access to instruction attributes to the latency rule.
-#### **Derived operand attributes**
+#### **Derived operand attributes** {#derived-operand-attributes}
Derived operand attributes associate name/value-tuple pairs with the operand type. Tuples are appropriate when an attribute is used as a set of masks for resource sharing, described later.
@@ -377,7 +378,7 @@ If all of an attribute’s predicates are “false” for an instance of an oper
-#### **Derived operand attribute usage**
+#### **Derived operand attribute usage** {#derived-operand-attribute-usage}
There is currently only a single context in which instruction attributes are used directly in the machine description, as part of resource references in latency rules (see “latency\_resource\_ref”). In this context, you can specify an attribute name which provides the number of resources needed for a resource allocation, and the mask used to determine shared operand bits associated with the resource. An example:
@@ -390,7 +391,7 @@ There is currently only a single context in which instruction attributes are use
This resource reference uses the attributes from the operand associated with this reference to determine how many resources to allocate, and what bits in the operand to share.
-## **Overview of Resources**
+## **Overview of Resources** {#overview-of-resources}
Resources are used to abstractly describe hardware constructs that are used by an instruction in its execution. They can represent:
@@ -407,7 +408,7 @@ Its important to note that different instances of an instruction can use complet
The machine description provides a mechanism for defining and associating resources with the pipeline behaviors of instructions through the specialization of functional unit templates, subunit templates, and latency templates. It also allows automatic allocation of shared resources for an instruction instance from resource pools. The MDL compiler generates behavior descriptions which explicitly reference each resource (or resource pool) the instruction uses, and in what pipeline phases. This provides a direct methodology for managing instruction issue and pipeline behaviors such as hazards.
-### Defining Resources
+### Defining Resources {#defining-resources}
There are a few ways that resources are defined:
@@ -437,32 +438,52 @@ Named resource definitions have the following grammar:
-#### Simple resource definitions
+#### Simple resource definitions {#simple-resource-definitions}
The simplest resource definition is simply a comma-separated list of names:
- **<code>resource name1, name2, name3;</code></strong>
+
+```
+ resource name1, name2, name3;
+```
+
A resource can also have an explicit pipeline stage associated with it, indicating that the defined resources are always used in the specified pipeline phase:
- **<code>resource(E4) name1, name2; // define resources that are always used in E4</code></strong>
+
+```
+ resource(E4) name1, name2; // define resources that are always used in E4
+```
+
A resource can have a set of bits associated with it. This defines a resource that can be shared between two references if the bits in an associated operand reference are identical.
- **<code>resource immediate:8; // define a resource with 8 bits of data</code></strong>
+```
+ resource immediate:8; // define a resource with 8 bits of data
+```
-#### Grouped resource definitions
+
+
+#### Grouped resource definitions {#grouped-resource-definitions}
We can declare a set of named, related resources:
- **<code>resource bits { bits_1, bits_2, bits_3 };</code></strong>
+
+```
+ resource bits { bits_1, bits_2, bits_3 };
+```
+
A resource group typically represents a pool of resources that are shared between instructions executing in parallel, where an instruction may require one or all of the resources. This is a common attribute of VLIW architectures, and used to model things like immediate pools and register ports.
Any defined resource can be included in a group, and the order of the members of a group is significant when members are allocated. If a group mentions an undefined resource (in either the current or enclosing scope), the member is declared as a resource in the current scope. In the case above, if the members (bits\_1, etc) are not declared, the compiler would create the definition:
- **<code>resource bits_1, bits_2, bits_3;</code></strong>
+
+```
+ resource bits_1, bits_2, bits_3;
+```
+
and the group members would refer to these definitions. (Note: we don’t support nested groups).
@@ -470,34 +491,39 @@ The resource group can be referenced by name, referring to the entire pool, or b
```
- resource bits_1, bits_2, bits_3;
+ resource bits_1, bits_2, bits_3;
+ resource bits_x { bits_1, bits_2, bits_3 };
+ resource bits_y { bits_3, bits_1, bits_2 };
```
- **<code>resource bits_x { bits_1, bits_2, bits_3 };</code></strong>
-
- **<code>resource bits_y { bits_3, bits_1, bits_2 };</code></strong>
-
“bits\_x” and “bits\_y” are distinct groups that reference the same members, but members are allocated in a different order. Groups can also be defined with syntax that indicates how its members are allocated by default.
- **<code>resource bits_or { bits_1 | bits_2 | bits_3 }; // allocate one of these</code></strong>
- **<code>resource bits_and { bits_1 & bits_2 & bits_3 }; // allocate all of these</code></strong>
+```
+ resource bits_or { bits_1 | bits_2 | bits_3 }; // allocate one of these
+ resource bits_and { bits_1 & bits_2 & bits_3 }; // allocate all of these
+```
+
Groups can also be implicitly defined in functional unit and subunit template instantiations as a resource parameter.
- **<code>func_unit func my_fu(bits_1 | bits_2 | bits_3);</code></strong>
+
+```
+ func_unit func my_fu(bits_1 | bits_2 | bits_3);
+```
+
This implicitly defines a resource group with three members, and passes that group as a parameter of the instance.
-#### Pooled resource definitions
+#### Pooled resource definitions {#pooled-resource-definitions}
We can also declare a set of “unnamed” pooled resources:
```
- resource shared_bits[0..5];
+ resource shared_bits[0..5];
```
@@ -507,8 +533,8 @@ Resource pools can also have data associated with them, each member has its own
```
-resource bits:20 { bits_1, bits_2, bits_3 };
-resource shared_bits:5[6];
+ resource bits:20 { bits_1, bits_2, bits_3 };
+ resource shared_bits:5[6];
```
@@ -525,7 +551,7 @@ Finally, resource definitions can pin a resource to a particular pipeline phase.
where E1 is the name of a pipeline phase. The resource “my\_pool” (and each of its elements) is always modeled to be reserved in pipeline phase E1.
-### **Using Resources**
+### **Using Resources** {#using-resources}
Resource references appear in several contexts. They are used in all template instantiations to specialize architecture templates (functional units, subunit, or latency templates) and are ultimately used in latency rules to describe pipeline behaviors. These will be described later in the document.
@@ -567,7 +593,7 @@ References in latency reference rules have additional syntax to support the allo
-#### **Allocating Grouped and Pooled Resources**
+#### **Allocating Grouped and Pooled Resources** {#allocating-grouped-and-pooled-resources}
Latency references allow you to optionally manage allocation of pooled resources, as well as specifying the significant bits of operands whose values can be shared with other instructions.
@@ -599,7 +625,11 @@ indicates that a reference needs _all _elements from a resource group or pool. N
A reference of the form:
- `some_resource_pool:size`
+
+```
+some_resource_pool:size
+```
+
indicates an operand reference that requires some number of resources from the resource pool. The number of resources needed is specified in the “size” attribute of the associated operand type. This enables us to decide at compile time how many resources to allocate for an instruction’s operand based on its actual value. For example, large operand constant values may require more resources than small constants, while some operand values may not require any resources. There’s a specific syntax for describing these attributes in derived operand definitions (described earlier).
@@ -616,7 +646,7 @@ This reference utilizes the resource - or an entire pool - and uses the operand
We will describe how these references work when we describe latency rules.
-## **Defining a Processor Family**
+## **Defining a Processor Family** {#defining-a-processor-family}
A TableGen description describes a family of processors, or subtargets, that share instruction and register definitions. Information about instruction behaviors are described with Schedules and Itineraries. The MDL also uses common instruction and register descriptions, scraped from TableGen, and adds first-class descriptions of CPUs, functional units, and pipeline modeling.
@@ -630,7 +660,7 @@ In an MDL CPU description, a CPU is described as an explicit set of functional u
More detail on this below.
-### **Method 1: SuperScalar and Out-Of-Order CPUs**
+### **Method 1: SuperScalar and Out-Of-Order CPUs** {#method-1-superscalar-and-out-of-order-cpus}
Fully protected pipelines, forwarding, out-of-order issue and retirement, imprecise micro-operation modeling, and dynamic functional unit allocation make this class of
@@ -645,7 +675,7 @@ The downside of this method is that you can’t specialize functional unit insta
We generally describe this as a “bottoms-up” approach (subunits explicitly tying to functional unit instances), and is the approach used by the Tablegen scraper (tdscan) for “Schedule-based” CPUs.
-### **Method 2: VLIWs, and everything else**
+### **Method 2: VLIWs, and everything else** {#method-2-vliws-and-everything-else}
This method is appropriate for machines where we must provide more information about the detailed behavior of an instruction so that we can correctly model its issuing and pipeline behavior. It is particularly important for machines with deep, complex pipelines that _must_ be modeled by the compiler. It has a powerful, flexible user-defined resource scheme which provides a lot more expressiveness than either “Schedules” or “Itineraries”.
@@ -658,7 +688,7 @@ We describe this as a “tops-down” approach (explicit functional unit templat
assert which subunits they support). This is the method tdscan uses when scraping information about itineraries.
-### **Schema of a Full Processor Family Description**
+### **Schema of a Full Processor Family Description** {#schema-of-a-full-processor-family-description}
By convention, a description generally describes things in the following order (although the order of these definitions doesn’t matter):
@@ -728,7 +758,7 @@ We will describe each of these items in more detail. A machine description for
#### **Bottoms-up vs Tops-down CPU Definition Schemas \
-**
+** {#bottoms-up-vs-tops-down-cpu-definition-schemas}
In the “tops-down” schema, we define CPUs, which instantiate functional units, which instantiate subunits, which instantiate latencies. At each level of instantiation, the object (functional unit, subunit, latency) can be specialized for the context that it’s instantiated in. We think of this as a “top-down” definition of a processor family. We provide detailed descriptions for each functional unit template, which we can specialize for each instance.
@@ -761,7 +791,7 @@ Note that we don’t explicitly define the ALU functional unit template, but it
While this schema is much more compact, neither the functional units nor the subunits/latencies can be specialized. This is an appropriate approach for scalar and superscalar processors, and is used by tdscan for CPUs that use Tablegen Schedules.
-### **Specifying the Family Name**
+### **Specifying the Family Name** {#specifying-the-family-name}
A family name must be specified that ties the description to the LLVM name for the processor family. It has the following grammar:
@@ -772,7 +802,7 @@ family_name : 'family' IDENT ';' ;
-### **Pipeline Definitions**
+### **Pipeline Definitions** {#pipeline-definitions}
We don’t explicitly define instruction “latencies” in the MDL. Instead, we specify when instructions’ reads and writes happen in terms of pipeline phases. From this, we can calculate actual latencies. Rather than specify pipeline phases with numbers, we provide a way of naming pipeline stages, and refer to those stages strictly by name. A pipeline description has the following grammar:
@@ -799,9 +829,9 @@ You can define more than one pipeline, and each pipeline can have the attribute
```
-protected phases alu { fetch, decode, ex1, ex2 };
-unprotected phases vector { vfetch, vdecode, vex1, vex2 };
-hard phases branch { bfetch, bdecode, branch };
+ protected phases alu { fetch, decode, ex1, ex2 };
+ unprotected phases vector { vfetch, vdecode, vex1, vex2 };
+ hard phases branch { bfetch, bdecode, branch };
```
@@ -829,7 +859,7 @@ phases my_pipeline { fetch, decode, #read1, read2, ex1, ex2, write1, write2 };
This indicates that “read1” is the first execute stage in the pipeline, which serves as the “default” phase for any operand that isn’t explicitly described in a latency rule.
-### **CPU Definitions**
+### **CPU Definitions** {#cpu-definitions}
In the definition of a single CPU/subtarget, we specify a high-level description of the processor:
@@ -914,7 +944,7 @@ and a cluster definition has the schema:
Below are some examples of increasingly complex CPU definitions.
-#### **Simple Scalar CPU Definition**
+#### **Simple Scalar CPU Definition** {#simple-scalar-cpu-definition}
In the simplest case, an empty CPU indicates a processor with no specific functional unit information. We assume a serial execution of instructions, with “default” latencies:
@@ -947,7 +977,7 @@ A slightly more complex example is a CPU that is single-issue, but has more than
-#### **Multi-Issue CPUs**
+#### **Multi-Issue CPUs** {#multi-issue-cpus}
Here’s an example of a 2-issue processor with two identical functional units:
@@ -974,7 +1004,7 @@ Processors commonly have functional units with different capabilities - memory u
-#### **Defining Issue Slots**
+#### **Defining Issue Slots** {#defining-issue-slots}
Multi-issue CPUs always have a constrained set of instructions they can issue in parallel. For superscalar, OOO processors this is generally tied to the number of issue pipelines that are available. For VLIW, issue slots map directly to encoding bits in a parallel instruction. In the MDL, you can explicitly define issue slots. An example:
@@ -994,7 +1024,7 @@ In this example, we have 3 functional units, but only two issue slots. So any o
When issue slots are not specified, each functional unit runs in its own dedicated issue slot.
-#### **Reservation of Issue Slots**
+#### **Reservation of Issue Slots** {#reservation-of-issue-slots}
In VLIW architectures (in particular), some functional units may be “pinned” to a specific set of issue slots, or use multiple issue slots in some cases. We provide syntax for specifying this:
@@ -1011,7 +1041,7 @@ In VLIW architectures (in particular), some functional units may be “pinned”
-#### **SuperScalar and Out-Of-Order CPUs**
+#### **SuperScalar and Out-Of-Order CPUs** {#superscalar-and-out-of-order-cpus}
In general, the overall approach for defining superscalar CPUs is quite different from other CPU types. This class of architecture requires information about the size of the reorder buffer, and details about queues for each functional unit. Actual functional unit utilization is described in latency or subunit rules, which can specify exactly which functional units are used.
@@ -1031,7 +1061,7 @@ Functional units can be unreserved (like alu1, below), which means that an instr
-#### **Parameterized/Specialized Functional Unit Instances**
+#### **Parameterized/Specialized Functional Unit Instances** {#parameterized-specialized-functional-unit-instances}
A functional unit template can be parameterized with register classes and resource references so that each instance of that functional unit template can be specialized for a specific context. The actual use of these parameters is specified in the functional unit template, explained in the following sections. This section describes template specialization parameters.
@@ -1073,7 +1103,7 @@ A **resource parameter** indicates that instructions that execute on the functio
-#### **Functional Unit Clusters**
+#### **Functional Unit Clusters** {#functional-unit-clusters}
A processor definition can include named “clusters” of functional units. Each cluster can define local resources, and define its own issue rules. The purpose of clusters is primarily as a syntactic convenience for describing processors with functional unit clusters. An example:
@@ -1102,7 +1132,7 @@ A processor definition can include named “clusters” of functional units. Eac
This describes a 4-issue machine, where 2 instructions can be issued on each cluster per cycle.
-#### **Defining Compound Functional Unit Instances**
+#### **Defining Compound Functional Unit Instances** {#defining-compound-functional-unit-instances}
Its often convenient to define “compound” functional unit instances as collections that include 2 or more “component” units. A compound unit includes all the capabilities of its component units. Each component can specify its own reservation queue size.
@@ -1123,16 +1153,20 @@ This construct is similar to the “super-unit” concept in tablegen. Only one
Currently, we don’t support specialization parameters on compound functional unit instances. However, you can define functional unit templates with base units, and this provides similar capability.
-#### **Associating a CPU definition with an LLVM subtarget**
+#### **Associating a CPU definition with an LLVM subtarget** {#associating-a-cpu-definition-with-an-llvm-subtarget}
A cpu definition can be directly associated with one or more LLVM subtargets, for example:
- **<code>cpu SiFive7 ("sifive-7-series", "sifive-e76", "sifive-s76", "sifive-u74") { …</code></strong>
+
+```
+ cpu SiFive7 ("sifive-7-series", "sifive-e76", "sifive-s76", "sifive-u74") { …
+```
+
At compile time, we can select which CPU definition to use based on normal target-selection command-line options.
-#### **Modeling Forwarding**
+#### **Modeling Forwarding** {#modeling-forwarding}
Forwarding is modeled by describing a forwarding network between functional units. The necessity of the concept of a “forwarding” network implies that such networks aren’t fully connected or uniform.
@@ -1177,7 +1211,7 @@ In short, there are architectural cases that cannot be modeled precisely, and th
Note: there is a philosophical question of whether we should provide best case or worst case latencies when the forwarding cannot be statically predicted. Generally, we believe that worst case latencies are better than best case latencies, simply because too-short latencies can produce code which occasionally (or always) stalls. On the other hand, overestimating the latency produces schedules where a pair of dependent instructions _tend _to be scheduled far enough apart to avoid stalls. In effect, schedulers will separate instructions by the requested latency only when there’s other useful work to do. Otherwise, there’s no reason to separate them - the stall is inevitable.
-### **Functional Unit Template Definitions**
+### **Functional Unit Template Definitions** {#functional-unit-template-definitions}
A functional unit template describes, abstractly, what operations can be performed on any instance of the unit, and how those operations use the template parameters - register classes and resource references. An abstract set of operations is represented by a subunit instance, which represents a set of instructions with similar behavior in terms of functional unit usage, resource usage, and register classes. Functional unit templates are defined in their own private namespace.
@@ -1230,7 +1264,7 @@ The general schema of a functional unit template looks like this: \
-#### **Simplest Functional Unit Template Definition**
+#### **Simplest Functional Unit Template Definition** {#simplest-functional-unit-template-definition}
The simplest example of a functional unit template would define a functional unit that has no parameters, and implements a single subunit:
@@ -1246,7 +1280,7 @@ The simplest example of a functional unit template would define a functional uni
In this case, any instruction that is defined to use the subunit “xyzzy” can run on this functional unit. This template doesn’t impose any additional constraints on those instructions, and no shared resources are used.
-#### **Defining Functional Unit Resources**
+#### **Defining Functional Unit Resources** {#defining-functional-unit-resources}
A functional unit template can locally define resources which represent hardware resources tied to _each instance_ of the functional unit. These can be used to specialize subunit instances:
@@ -1269,7 +1303,7 @@ In this example, the functional unit supports 3 classes of instructions (add, su
Importantly: functional-unit-local resources which are used for multiple cycles can be used to model non-pipelined functional units - i.e.units which are reserved for some number of cycles.
-#### **Defining “Port” Resources**
+#### **Defining “Port” Resources** {#defining-“port”-resources}
A port is a resource type that explicitly binds a named register class with a resource reference. A port is used to specialize subunit instances, and adding functional-unit-specific register constraints on instructions associated with the subunit.
@@ -1307,7 +1341,7 @@ This syntax could potentially be used to connect a port to more than one constra
Ports can be used to specialize subunit and latency instances, described in subsequent sections.
-#### **Using Template Parameters**
+#### **Using Template Parameters** {#using-template-parameters}
Resource parameters can be used exactly like locally defined resources to specialize subunit instances. Register class parameters are used to define ports. Resource parameters can refer to a single resource, a pool of resources, or a group of resources.
@@ -1343,7 +1377,7 @@ A simple example of a full functional unit template definition:
-#### **Conditional Subunit Instances**
+#### **Conditional Subunit Instances** {#conditional-subunit-instances}
In a functional unit template, a subunit instance can be conditionally instantiated based on a predicate. Predicates are simply names of the instantiating cpu definition and functional unit instance. This allows us to specialize a functional unit instance based on how its instantiated, for example:
@@ -1363,7 +1397,7 @@ func_unit my_func() {
-#### **Using Base Functional Units**
+#### **Using Base Functional Units** {#using-base-functional-units}
Functional units tend to get more capable over generations of a processor, so we’d like a way to derive functional units from other functional units. A functional unit template can be defined to have a base functional unit, for example:
@@ -1379,7 +1413,7 @@ In this example, the template “my\_func” simply includes the definition of
In effect, when you instantiate a based functional unit, you implicitly instantiate its bases and any subbases. This language feature allows us to easily extend functional unit definitions over processor generations.
-#### **Defining functional unit groups**
+#### **Defining functional unit groups** {#defining-functional-unit-groups}
When defining a superscalar CPU, its generally not necessary to provide a functional unit template definition for each functional unit, since latency rules specify which functional units are used by a subunit. In this case, its helpful to be able to easily specify an arbitrary pool of functional units that can be used for an instruction. So the MDL has a way to do that.
@@ -1400,7 +1434,7 @@ For example:
This defines a functional unit group with 3 members, and a single input queue of length 42. These groups are used in latency rules to tie subunits to a pool of functional units.
-### **Subunit Template Definitions**
+### **Subunit Template Definitions** {#subunit-template-definitions}
Subunits are used to link sets of instruction definitions to their pipeline behaviors and candidate functional units. Subunits appear in three contexts:
@@ -1478,7 +1512,7 @@ The optional predicate is a comma-separated list of names which refers to the CP
A subunit template can specify as many latency instances as needed - the resulting subunit is the union of all the valid latency templates. This allows you to separate different classes of behaviors into different latency templates. Since latency templates are also specialized, you can manage the separation in latencies. The typical practice is for a subunit to have a single latency instance.
-#### Subunit Template Parameters
+#### Subunit Template Parameters {#subunit-template-parameters}
Subunit template parameters can be a mix of ports and resources, and are used to specialize a subunit for the context in which it is instantiated, for example:
@@ -1491,7 +1525,7 @@ Subunit template parameters can be a mix of ports and resources, and are used to
In general, these work exactly the same way functional unit templates are used. They can be used as latency parameters to specialize latency instances.
-#### Tying Instructions to Subunits
+#### Tying Instructions to Subunits {#tying-instructions-to-subunits}
There are two ways to associate subunits to instructions:
@@ -1503,7 +1537,7 @@ There are two ways to associate subunits to instructions:
We discuss these two approaches below.
-##### Subunits in Instructions
+##### Subunits in Instructions {#subunits-in-instructions}
Subunits are associated with instruction definitions to...
@@ -1519,7 +1553,7 @@ Each defined instruction must specify at least one subunit that it is bound to.
We allow more than one subunit per instruction, which implies different instruction behaviors across CPUs or functional units. In general, this isn’t necessary, since a subunit can specify different behaviors for different functional units and/or CPUs. So this is strictly a stylistic choice.
-##### Subunit Bases
+##### Subunit Bases {#subunit-bases}
A subunit template definition can have one or more “bases”. A base is either the name of another subunit, or a string representing a regular expression of instruction names. Bases tie a subunit to sets of instructions, either directly by instruction name, or transitively through their base subunits. A subunit does not need to have the same parameters as its bases, and does not inherit any latency information from its bases.
@@ -1534,7 +1568,7 @@ This example ties the “add” subunit to any instruction with “ADD” as a n
Subunit bases provide an alternate way of tying instructions to subunits without modifying the instruction definitions (where each instruction can tie itself to a set of subunits). This effectively allows a single “base” subunit - and all of its associated instructions - to have different latency behaviors for each target.
-#### Shorthand Subunit Template Definitions
+#### Shorthand Subunit Template Definitions {#shorthand-subunit-template-definitions}
Often a subunit template simply specifies a single latency template instance, and the latency template may only be used in a single subunit template. In that case, we have a shorthand that combines the latency template into the subunit template. For example:
@@ -1558,7 +1592,7 @@ subunit load(resource a, b, c) {{
-### **Latency Template Definitions**
+### **Latency Template Definitions** {#latency-template-definitions}
A latency template specifies the detailed pipeline behavior for a class of instructions. The class of “client” instructions for a latency template is the set of instructions that use any subunit that instantiates the latency template.
@@ -1644,7 +1678,7 @@ The full grammar:
-#### **Derived Latency Templates**
+#### **Derived Latency Templates** {#derived-latency-templates}
A latency template can be derived from one or more base latency templates. Any hierarchy is allowed (except recursive), as long as the base template has the exact same leading parameters as the derived latency. A base latency can be included more than once in the hierarchy - this doesn’t matter, since all occurrences of that base are identical (so duplicates are ignored):
@@ -1660,7 +1694,7 @@ A latency template can be derived from one or more base latency templates. Any
In this example, my\_latency includes base1, base2, and base3. Deriving latency templates is a fairly common pattern: instruction classes often share _some_ behaviors, but not all. So those shared behaviors can be put in a base latency template. A common example is an instruction predicate, perhaps shared by all instructions.
-#### **Latency References**
+#### **Latency References** {#latency-references}
A latency reference statement describes a single operand reference and/or resource references in a specified pipeline stage. It references instruction operands _by name, _as well as resource and port parameters, and ties the operations to named pipeline phases.
@@ -1675,7 +1709,7 @@ Latency references have the following general form:
where either the operand specifier or ports/resources may be omitted. A single reference statement asserts that an operand and resources are referenced in a specific pipeline phase for any instruction that this rule could apply to, ie: _any instruction that uses a subunit that instantiates this latency template._ Each aspect of a latency reference are described below.
-##### **Operand and resource latency operators:**
+##### **Operand and resource latency operators:** {#operand-and-resource-latency-operators}
There are 6 basic operator types in a latency reference:
@@ -1697,7 +1731,7 @@ There are 3 additional operator types which are primarily used as shortcuts (the
* or - this is essentially a conditional def, but the instruction has no explicit predicate (useful for status-setting instructions).
-##### **Phase Expressions**
+##### **Phase Expressions** {#phase-expressions}
The phase expression specifies the pipeline phase that the operation occurs in. The expression can refer directly to a defined phase name, or an expression based on a phase name:
@@ -1721,7 +1755,7 @@ where “$width” is an immediate instruction operand. Its value is fetched fro
Phase expressions have a limited set of operators: +, -, \*, /, (). Since latencies must be positive integers, we also provide a “floor” operator which converts negative expressions to 0. Simply enclose the expression in curly braces ({...}).
-##### **Operand Specifiers**
+##### **Operand Specifiers** {#operand-specifiers}
The operand specifier has the same grammar as in tablegen, which allows you to specify an optional operand type, the operand name, and optional sub-operand names:
@@ -1773,7 +1807,7 @@ Or you can differentiate based on the operand name:
Note that operands _can _be referenced by their index in an instruction’s operand list, but this is error-prone and this isn’t considered best practice because we can’t thoroughly check the validity of the index. The syntax is simply “$<index>”. Note that sub-operands often aren’t given names in tablegen, and must be referenced by index, for example: $src.1. Unnamed variant operands (obviously) don’t have names, and are referenced by their position past the end of the operands defined for an instruction, ie “$$1”, “$$2”, etc.
-##### **Resource References**
+##### **Resource References** {#resource-references}
Any latency reference can include an optional set of resource references. These have slightly different semantics depending on the operator type (def/use/predicate/hold/reserve).
@@ -1796,7 +1830,7 @@ For “hold” and “reserve” operations, the operand specifier is optional,
-#### **Conditional References**
+#### **Conditional References** {#conditional-references}
Any reference in a latency rule can be conditional, using a predicate identifier. The predicates are generally identical to LLVM predicates, and check an attribute of a client instruction.
@@ -1811,7 +1845,7 @@ else { <set of refs> }
-#### **Functional Unit and Micro-op References**
+#### **Functional Unit and Micro-op References** {#functional-unit-and-micro-op-references}
A latency rule can directly specify a set of functional units and how long they are used, as well as specifying the number of micro-ops required for the operation. Each functional unit can optionally specify a pipeline “StartAt” cycle, which by default is the first execution phase.
@@ -1828,7 +1862,7 @@ fus(ALU, 2); // use ALU for 1 cycle, 2 micro-operations.
These statements allow a latency rule (or subunit) to tie a set of instructions to functional unit instances. When there is more than one instance of the specified unit, or if the unit is declared to be a functional unit group, at compile time _one_ of those units is selected. Likewise, if the unit is a subunit of one or more functional units, one of the “parent” functional units is selected.
-## **Machine Description Compiler Artifacts**
+## **Machine Description Compiler Artifacts** {#machine-description-compiler-artifacts}
What does all of this produce?
@@ -1848,11 +1882,11 @@ The other primary artifact is a set of objects and methods for managing the low-
As part of this effort, we will incrementally modify the LLVM compiler to alternatively use this information alongside of SchedMachineModel and Itinerary methodologies.
-
+
-## **Using the MDL Language in LLVM**
+## **Using the MDL Language in LLVM** {#using-the-mdl-language-in-llvm}
The proposed use case for the MDL language is as an alternative specification for the architecture description currently embodied in TableGen Schedules and Itineraries, particularly for architectures for which Schedules and Itineraries are not expressive enough. It is explicitly _not_ the intent that it “replace TableGen”. But we believe that the MDL language is a better language (vs Schedules and Itineraries) for a large class of accelerators, and can be used effectively alongside TableGen.
@@ -1882,15 +1916,14 @@ The general development flow of using an MDL description in LLVM looks like this
-
-### **TdScan**
+### **TdScan** {#tdscan}
To synchronize an MDL architecture description with llvm TableGen descriptions, we’ve written a tool which scrapes information that the MDL compiler needs from Tablegen files. In the general case, it collects basic information about registers, register classes, operands, and instruction definitions, and it produces an “mdl” file which can be processed by the MDL compiler to sync an architecture description to the tablegen descriptions of instructions.
For currently upstreamed targets that use Schedules or Itineraries, TdScan can also extract the whole architecture specification from the tablegen files, and produce an MDL description of the architecture. We’ve used this approach to prove out our llvm integration with upstreamed targets. The integration and testing of this is ongoing.
-### **Upstream Targets**
+### **Upstream Targets** {#upstream-targets}
In general, upstream targets have no compelling need for MDL descriptions - the existing Schedules and/or Itinerary descriptions are field tested. However, there are a few benefits to using an MDL description for existing targets. The primary benefit is that the MDL descriptions are typically quite a bit smaller, succinct, and (we believe) intuitive than the equivalent TableGen descriptions.
@@ -1998,7 +2031,7 @@ In general, upstream targets have no compelling need for MDL descriptions - the
\*\* Note: the MDL numbers are generated both with and without “index-based” references in subunit/latency rules, vs symbolic references. These are typically 10-20% less lines of MDL description than when operand names are used, almost entirely due to operand name differences between instruction definitions (like “dest” vs “dst”, or “src1” vs “s1”). However, the databases produced by the two approaches are virtually identical - albeit ordered differently.
-### **Syncing Instruction Information**
+### **Syncing Instruction Information** {#syncing-instruction-information}
The MDL compiler needs 3 pieces of information from tablegen for each machine instruction:
@@ -2013,7 +2046,7 @@ Subunits are a new concept introduced with the MDL. The normal approach is to m
As part of the build process, we use a program (“tdscan”) which scrapes the instruction information - including the subunit information from a target’s tablegen files and generates information about the target’s instructions. Tdscan allows us to stay in sync with changes to instruction definitions.
-### **Using the generated microarchitecture information in LLVM**
+### **Using the generated microarchitecture information in LLVM** {#using-the-generated-microarchitecture-information-in-llvm}
There are two classes of services that the MDL database and associated APIs provide:
@@ -2041,7 +2074,7 @@ We provide code and libraries to do the following things - in machine-independen
There’s more we can do here, and a deeper integration with upstreamed LLVM is a long-term goal.
-### **Current Status of the LLVM Integration (briefly)**
+### **Current Status of the LLVM Integration (briefly)** {#current-status-of-the-llvm-integration-briefly}
@@ -2054,7 +2087,7 @@ There’s more we can do here, and a deeper integration with upstreamed LLVM is
-## **Appendix A: Full Language Grammar**
+## **Appendix A: Full Language Grammar** {#appendix-a-full-language-grammar}
This may be slightly out of date. The definitive Antlr4-based grammar is in llvm/utils/MdlCompiler/mdl.g4.
@@ -2368,10 +2401,10 @@ range : number '..' number ;
-## **Appendix B: Future Directions**
+## **Appendix B: Future Directions** {#appendix-b-future-directions}
-### **Memory Hierarchy**
+### **Memory Hierarchy** {#memory-hierarchy}
We need a first class representation of any compiler-managed memory hierarchy.
@@ -2413,7 +2446,7 @@ DMA system descriptions
Multi-Processor System Topology
-## **Appendix C: RISC-V Generated Architecture Description**
+## **Appendix C: RISC-V Generated Architecture Description** {#appendix-c-risc-v-generated-architecture-description}
This is a complete, automatically generated machine description for RISC-V using our tool to scrape information from tablegen files. We can automatically generate MDL specifications for all targets that have schedules and/or itineraries. We include RISC-V here for illustrative purposes.
>From d1b90ef6756cac26eaea502834c54c39cc3b7ef1 Mon Sep 17 00:00:00 2001
From: Reid Tatge <tatge at google.com>
Date: Fri, 19 Jan 2024 22:11:20 +0000
Subject: [PATCH 09/14] [LLVM][MDL] Fix more formatting errors
---
llvm/docs/Mdl/MachineDescriptionNotes.md | 333 ++++++++++++-----------
1 file changed, 175 insertions(+), 158 deletions(-)
diff --git a/llvm/docs/Mdl/MachineDescriptionNotes.md b/llvm/docs/Mdl/MachineDescriptionNotes.md
index 5b099c02a981dde..8b30c756fe4015d 100644
--- a/llvm/docs/Mdl/MachineDescriptionNotes.md
+++ b/llvm/docs/Mdl/MachineDescriptionNotes.md
@@ -1,15 +1,20 @@
+<p style="color: red; font-weight: bold">>>>> GDC alert: ERRORs: 0; WARNINGs: 0; ALERTS: 2.</p>
+<ul style="color: red; font-weight: bold"><li>See top comment block for details on ERRORs and WARNINGs. <li>In the converted Markdown or HTML, search for inline alerts that start with >>>> GDC alert: for specific instances that need correction.</ul>
-# MPACT Microarchitecture Description Language
+<p style="color: red; font-weight: bold">Links to alert messages:</p><a href="#gdcalert1">alert1</a>
+<a href="#gdcalert2">alert2</a>
+
+<p style="color: red; font-weight: bold">>>>> PLEASE check and correct alert issues and delete this message and the inline alerts.<hr></p>
-Reid Tatge [tatge at google.com](mailto:tatge at google.com)
-[TOC]
+# MPACT Microarchitecture Description Language
+Reid Tatge [tatge at google.com](mailto:tatge at google.com)
-## **Goals for a Machine Description Language** {#goals-for-a-machine-description-language}
+## **Goals for a Machine Description Language**
Modern processors are complex: multiple execution pipelines, dynamically dispatched, out-of-order execution, register renaming, forwarding networks, and (often) undocumented micro-operations. Instruction behaviors, including micro-operations, often can’t be _statically_ modeled in an accurate way, but only _statistically_ modeled. In these cases, the compiler’s model of a microarchitecture (Schedules and Itineraries in LLVM) is effectively closer to a heuristic than a formal model. And this works quite well for general purpose microprocessors.
@@ -43,7 +48,7 @@ _Note: A full language grammar description is provided in an appendix. Snippets
The proposed language can be thought of as an _optional extension to the LLVM machine description_. For most upstream architectures, the new language offers minimal benefit other than a much more succinct way to specify the architecture vs Schedules and Itineraries. But for accelerator-class architectures, it provides a level of detail and capability not available in the existing tablegen approaches.
-### **Background** {#background}
+### **Background**
Processor families evolve over time. They accrete new instructions, and pipelines change - often in subtle ways - as they accumulate more functional units and registers; encoding rules change; issue rules change. Understanding, encoding, and using all of this information - over time, for many subtargets - can be daunting. When the description language isn’t sufficient to model the architecture, the back-end modeling evolves towards heuristics, and leads to performance issues or bugs in the compiler. And it certainly ends with large amounts of target specific code to handle “special cases”.
@@ -79,7 +84,7 @@ More generally, we’d like specific language to:
Since our emphasis is on easily supporting accelerators and VLIW processors, in addition to supporting all existing targets, much of this is overkill for most upstreamed CPUs. CPU’s typically have much simpler descriptions, and don’t require much of the capability of our machine description language. Incidentally, MDL descriptions of these targets (generated automatically from the tablegen Schedules and Itineraries) are typically much more concise than the original tablegen descriptions.
-### **Approach - “Subunits” and Instruction Behaviors** {#approach-“subunits”-and-instruction-behaviors}
+### **Approach - “Subunits” and Instruction Behaviors**
We developed a DSL that allows us to describe an arbitrary processor microarchitecture in terms that reflect what is typically documented in the hardware specification. The MDL compiler creates a database that provides microarchitecture behavior information that can _automatically _inform critical back-end compiler passes, such as instruction scheduling and register allocation, in a machine-independent way.
@@ -109,7 +114,7 @@ We define a subunit as an object that defines the _behavior sets_ of an instruct
The critical artifact generated by the MDL compiler is a set of instruction behaviors for each instruction definition. For each subtarget, for each instruction, we generate a list of every possible behavior of that instruction on that CPU. While this sounds daunting, in practice it's rare to have more than a few behaviors for an instruction, and most instruction definitions share their behaviors with many other instructions, across subtargets.
-## **Overview of a Processor Family Description** {#overview-of-a-processor-family-description}
+## **Overview of a Processor Family Description**
This document generally describes the language in a bottom up order - details first. But let's start with a brief tops-down overview of what a processor family description looks like, without going into details about each part.
@@ -176,7 +181,7 @@ When writing a target machine description, its not necessary to write descriptio
We will describe these language features here, primarily for completeness.
-### **Defining Instructions** {#defining-instructions}
+### **Defining Instructions**
Instruction definitions are scraped from tablegen files, and provide the following information to the MDL compiler for each instruction:
@@ -216,7 +221,7 @@ An example:
This describes an ARM add instruction that has two defined input operands (Rn, imm), one defined output operand (Rd), and one implicit output operand (NZCV), which is associated with two subunits (sub24, sub26).
-### **Defining Operands** {#defining-operands}
+### **Defining Operands**
Operand definitions are scraped from tablegen files (like instructions), and provide the following information to the MDL compiler for each operand:
@@ -248,7 +253,7 @@ Some examples:
-### **Defining Registers and Register Classes** {#defining-registers-and-register-classes}
+### **Defining Registers and Register Classes**
Registers and register classes are scraped from tablegen output. We provide a general method in the language to define registers and classes of registers which can reflect the registers defined in tablegen.
@@ -279,7 +284,7 @@ Examples:
The order of register definitions is generally insignificant in the current MDL - we use the register names defined in LLVM, and there’s no cases in the MDL where we depend on order. Register “ranges”, such as “a[0..20]” are simply expanded into the discrete names of the entire range of registers.
-### **Defining Derived Operands** {#defining-derived-operands}
+### **Defining Derived Operands**
LLVM doesn’t necessarily provide all the information we want to capture about an instruction, so the MDL allows for defining “derived” operands with which we can associate named values. A derived operand is essentially an alias to one or more LLVM-defined operands (or derived operands), and provides a mechanism to add arbitrary attributes to operand definitions. Derived operands also allow us to treat a set of operand types as identical in latency reference rules (so you don’t have to specify a long set of operand types for some references.)
@@ -307,14 +312,14 @@ Grammar:
-#### **Derivation** {#derivation}
+#### **Derivation**
Each derived operand is declared with one or more “base” operands, for which it is an alias. Circular or ambiguous derivations are explicitly disallowed - there must be only one derivation path for a derived operand to any of its base concrete operands.
Derived operands are used in place of their base operands in operand latency rules in latency templates (described later). This allows a rule to match a set of operands, rather than a single operand, and also can provide access to instruction attributes to the latency rule.
-#### **Derived operand attributes** {#derived-operand-attributes}
+#### **Derived operand attributes**
Derived operand attributes associate name/value-tuple pairs with the operand type. Tuples are appropriate when an attribute is used as a set of masks for resource sharing, described later.
@@ -378,7 +383,7 @@ If all of an attribute’s predicates are “false” for an instance of an oper
-#### **Derived operand attribute usage** {#derived-operand-attribute-usage}
+#### **Derived operand attribute usage**
There is currently only a single context in which instruction attributes are used directly in the machine description, as part of resource references in latency rules (see “latency\_resource\_ref”). In this context, you can specify an attribute name which provides the number of resources needed for a resource allocation, and the mask used to determine shared operand bits associated with the resource. An example:
@@ -391,7 +396,7 @@ There is currently only a single context in which instruction attributes are use
This resource reference uses the attributes from the operand associated with this reference to determine how many resources to allocate, and what bits in the operand to share.
-## **Overview of Resources** {#overview-of-resources}
+## **Overview of Resources**
Resources are used to abstractly describe hardware constructs that are used by an instruction in its execution. They can represent:
@@ -408,7 +413,7 @@ Its important to note that different instances of an instruction can use complet
The machine description provides a mechanism for defining and associating resources with the pipeline behaviors of instructions through the specialization of functional unit templates, subunit templates, and latency templates. It also allows automatic allocation of shared resources for an instruction instance from resource pools. The MDL compiler generates behavior descriptions which explicitly reference each resource (or resource pool) the instruction uses, and in what pipeline phases. This provides a direct methodology for managing instruction issue and pipeline behaviors such as hazards.
-### Defining Resources {#defining-resources}
+### Defining Resources
There are a few ways that resources are defined:
@@ -438,7 +443,7 @@ Named resource definitions have the following grammar:
-#### Simple resource definitions {#simple-resource-definitions}
+#### Simple resource definitions
The simplest resource definition is simply a comma-separated list of names:
@@ -465,7 +470,7 @@ A resource can have a set of bits associated with it. This defines a resource th
-#### Grouped resource definitions {#grouped-resource-definitions}
+#### Grouped resource definitions
We can declare a set of named, related resources:
@@ -517,7 +522,7 @@ Groups can also be implicitly defined in functional unit and subunit template in
This implicitly defines a resource group with three members, and passes that group as a parameter of the instance.
-#### Pooled resource definitions {#pooled-resource-definitions}
+#### Pooled resource definitions
We can also declare a set of “unnamed” pooled resources:
@@ -551,7 +556,7 @@ Finally, resource definitions can pin a resource to a particular pipeline phase.
where E1 is the name of a pipeline phase. The resource “my\_pool” (and each of its elements) is always modeled to be reserved in pipeline phase E1.
-### **Using Resources** {#using-resources}
+### **Using Resources**
Resource references appear in several contexts. They are used in all template instantiations to specialize architecture templates (functional units, subunit, or latency templates) and are ultimately used in latency rules to describe pipeline behaviors. These will be described later in the document.
@@ -593,7 +598,7 @@ References in latency reference rules have additional syntax to support the allo
-#### **Allocating Grouped and Pooled Resources** {#allocating-grouped-and-pooled-resources}
+#### **Allocating Grouped and Pooled Resources**
Latency references allow you to optionally manage allocation of pooled resources, as well as specifying the significant bits of operands whose values can be shared with other instructions.
@@ -646,7 +651,7 @@ This reference utilizes the resource - or an entire pool - and uses the operand
We will describe how these references work when we describe latency rules.
-## **Defining a Processor Family** {#defining-a-processor-family}
+## **Defining a Processor Family**
A TableGen description describes a family of processors, or subtargets, that share instruction and register definitions. Information about instruction behaviors are described with Schedules and Itineraries. The MDL also uses common instruction and register descriptions, scraped from TableGen, and adds first-class descriptions of CPUs, functional units, and pipeline modeling.
@@ -660,7 +665,7 @@ In an MDL CPU description, a CPU is described as an explicit set of functional u
More detail on this below.
-### **Method 1: SuperScalar and Out-Of-Order CPUs** {#method-1-superscalar-and-out-of-order-cpus}
+### **Method 1: SuperScalar and Out-Of-Order CPUs**
Fully protected pipelines, forwarding, out-of-order issue and retirement, imprecise micro-operation modeling, and dynamic functional unit allocation make this class of
@@ -675,7 +680,7 @@ The downside of this method is that you can’t specialize functional unit insta
We generally describe this as a “bottoms-up” approach (subunits explicitly tying to functional unit instances), and is the approach used by the Tablegen scraper (tdscan) for “Schedule-based” CPUs.
-### **Method 2: VLIWs, and everything else** {#method-2-vliws-and-everything-else}
+### **Method 2: VLIWs, and everything else**
This method is appropriate for machines where we must provide more information about the detailed behavior of an instruction so that we can correctly model its issuing and pipeline behavior. It is particularly important for machines with deep, complex pipelines that _must_ be modeled by the compiler. It has a powerful, flexible user-defined resource scheme which provides a lot more expressiveness than either “Schedules” or “Itineraries”.
@@ -688,7 +693,7 @@ We describe this as a “tops-down” approach (explicit functional unit templat
assert which subunits they support). This is the method tdscan uses when scraping information about itineraries.
-### **Schema of a Full Processor Family Description** {#schema-of-a-full-processor-family-description}
+### **Schema of a Full Processor Family Description**
By convention, a description generally describes things in the following order (although the order of these definitions doesn’t matter):
@@ -758,7 +763,7 @@ We will describe each of these items in more detail. A machine description for
#### **Bottoms-up vs Tops-down CPU Definition Schemas \
-** {#bottoms-up-vs-tops-down-cpu-definition-schemas}
+**
In the “tops-down” schema, we define CPUs, which instantiate functional units, which instantiate subunits, which instantiate latencies. At each level of instantiation, the object (functional unit, subunit, latency) can be specialized for the context that it’s instantiated in. We think of this as a “top-down” definition of a processor family. We provide detailed descriptions for each functional unit template, which we can specialize for each instance.
@@ -791,7 +796,7 @@ Note that we don’t explicitly define the ALU functional unit template, but it
While this schema is much more compact, neither the functional units nor the subunits/latencies can be specialized. This is an appropriate approach for scalar and superscalar processors, and is used by tdscan for CPUs that use Tablegen Schedules.
-### **Specifying the Family Name** {#specifying-the-family-name}
+### **Specifying the Family Name**
A family name must be specified that ties the description to the LLVM name for the processor family. It has the following grammar:
@@ -802,7 +807,7 @@ family_name : 'family' IDENT ';' ;
-### **Pipeline Definitions** {#pipeline-definitions}
+### **Pipeline Definitions**
We don’t explicitly define instruction “latencies” in the MDL. Instead, we specify when instructions’ reads and writes happen in terms of pipeline phases. From this, we can calculate actual latencies. Rather than specify pipeline phases with numbers, we provide a way of naming pipeline stages, and refer to those stages strictly by name. A pipeline description has the following grammar:
@@ -843,7 +848,8 @@ A “hard” latency typically describes the behavior of branch and call instruc
You can define multiple stages as a group - the following rule is equivalent to the first example above.
-**<code>phases alu { fetch, decode, read[1..2], ex[1..2], write[1..2] };</code></strong> \
+
+ **<code>phases alu { fetch, decode, read[1..2], ex[1..2], write[1..2] };</code></strong> \
Like C enumerated values, each defined name is implicitly assigned an integer value, starting at zero and increasing sequentially, that represents its integer stage id. You can explicitly assign values to pipeline phases, as in C, with the syntax “`phase=value`”. You can also explicitly assign sequential values to a range, by using the syntax `"name[2..5]=value`”.
@@ -859,7 +865,7 @@ phases my_pipeline { fetch, decode, #read1, read2, ex1, ex2, write1, write2 };
This indicates that “read1” is the first execute stage in the pipeline, which serves as the “default” phase for any operand that isn’t explicitly described in a latency rule.
-### **CPU Definitions** {#cpu-definitions}
+### **CPU Definitions**
In the definition of a single CPU/subtarget, we specify a high-level description of the processor:
@@ -944,7 +950,7 @@ and a cluster definition has the schema:
Below are some examples of increasingly complex CPU definitions.
-#### **Simple Scalar CPU Definition** {#simple-scalar-cpu-definition}
+#### **Simple Scalar CPU Definition**
In the simplest case, an empty CPU indicates a processor with no specific functional unit information. We assume a serial execution of instructions, with “default” latencies:
@@ -977,7 +983,7 @@ A slightly more complex example is a CPU that is single-issue, but has more than
-#### **Multi-Issue CPUs** {#multi-issue-cpus}
+#### **Multi-Issue CPUs**
Here’s an example of a 2-issue processor with two identical functional units:
@@ -1004,7 +1010,7 @@ Processors commonly have functional units with different capabilities - memory u
-#### **Defining Issue Slots** {#defining-issue-slots}
+#### **Defining Issue Slots**
Multi-issue CPUs always have a constrained set of instructions they can issue in parallel. For superscalar, OOO processors this is generally tied to the number of issue pipelines that are available. For VLIW, issue slots map directly to encoding bits in a parallel instruction. In the MDL, you can explicitly define issue slots. An example:
@@ -1024,7 +1030,7 @@ In this example, we have 3 functional units, but only two issue slots. So any o
When issue slots are not specified, each functional unit runs in its own dedicated issue slot.
-#### **Reservation of Issue Slots** {#reservation-of-issue-slots}
+#### **Reservation of Issue Slots**
In VLIW architectures (in particular), some functional units may be “pinned” to a specific set of issue slots, or use multiple issue slots in some cases. We provide syntax for specifying this:
@@ -1041,7 +1047,7 @@ In VLIW architectures (in particular), some functional units may be “pinned”
-#### **SuperScalar and Out-Of-Order CPUs** {#superscalar-and-out-of-order-cpus}
+#### **SuperScalar and Out-Of-Order CPUs**
In general, the overall approach for defining superscalar CPUs is quite different from other CPU types. This class of architecture requires information about the size of the reorder buffer, and details about queues for each functional unit. Actual functional unit utilization is described in latency or subunit rules, which can specify exactly which functional units are used.
@@ -1061,7 +1067,7 @@ Functional units can be unreserved (like alu1, below), which means that an instr
-#### **Parameterized/Specialized Functional Unit Instances** {#parameterized-specialized-functional-unit-instances}
+#### **Parameterized/Specialized Functional Unit Instances**
A functional unit template can be parameterized with register classes and resource references so that each instance of that functional unit template can be specialized for a specific context. The actual use of these parameters is specified in the functional unit template, explained in the following sections. This section describes template specialization parameters.
@@ -1103,25 +1109,24 @@ A **resource parameter** indicates that instructions that execute on the functio
-#### **Functional Unit Clusters** {#functional-unit-clusters}
+#### **Functional Unit Clusters**
A processor definition can include named “clusters” of functional units. Each cluster can define local resources, and define its own issue rules. The purpose of clusters is primarily as a syntactic convenience for describing processors with functional unit clusters. An example:
- **<code>cpu my_cpu {</code></strong>
-
```
- cluster A {
- issue a, b;
- func_unit my_alu alu1();
- func_unit my_alu alu2();
- func_unit my_alu alu3();
+ cpu my_cpu {
+ cluster A {
+ issue a, b;
+ func_unit my_alu alu1();
+ func_unit my_alu alu2();
+ func_unit my_alu alu3();
}
cluster B {
- issue a, b;
- func_unit my_alu alu1();
- func_unit my_alu alu2();
- func_unit my_alu alu3();
+ issue a, b;
+ func_unit my_alu alu1();
+ func_unit my_alu alu2();
+ func_unit my_alu alu3();
}
}
@@ -1132,16 +1137,16 @@ A processor definition can include named “clusters” of functional units. Eac
This describes a 4-issue machine, where 2 instructions can be issued on each cluster per cycle.
-#### **Defining Compound Functional Unit Instances** {#defining-compound-functional-unit-instances}
+#### **Defining Compound Functional Unit Instances**
Its often convenient to define “compound” functional unit instances as collections that include 2 or more “component” units. A compound unit includes all the capabilities of its component units. Each component can specify its own reservation queue size.
```
cpu compound_units {
- Issue s0, s1, s2;
- func_unit int_math<5>:load<6> alu1();
- func_unit int_math<5>:store<3> alu2();
+ Issue s0, s1, s2;
+ func_unit int_math<5>:load<6> alu1();
+ func_unit int_math<5>:store<3> alu2();
func_unit float_math<20>:branch<2> alu3();
func_unit misc<30> alu4();
}
@@ -1153,7 +1158,7 @@ This construct is similar to the “super-unit” concept in tablegen. Only one
Currently, we don’t support specialization parameters on compound functional unit instances. However, you can define functional unit templates with base units, and this provides similar capability.
-#### **Associating a CPU definition with an LLVM subtarget** {#associating-a-cpu-definition-with-an-llvm-subtarget}
+#### **Associating a CPU definition with an LLVM subtarget**
A cpu definition can be directly associated with one or more LLVM subtargets, for example:
@@ -1166,7 +1171,7 @@ A cpu definition can be directly associated with one or more LLVM subtargets, fo
At compile time, we can select which CPU definition to use based on normal target-selection command-line options.
-#### **Modeling Forwarding** {#modeling-forwarding}
+#### **Modeling Forwarding**
Forwarding is modeled by describing a forwarding network between functional units. The necessity of the concept of a “forwarding” network implies that such networks aren’t fully connected or uniform.
@@ -1211,7 +1216,7 @@ In short, there are architectural cases that cannot be modeled precisely, and th
Note: there is a philosophical question of whether we should provide best case or worst case latencies when the forwarding cannot be statically predicted. Generally, we believe that worst case latencies are better than best case latencies, simply because too-short latencies can produce code which occasionally (or always) stalls. On the other hand, overestimating the latency produces schedules where a pair of dependent instructions _tend _to be scheduled far enough apart to avoid stalls. In effect, schedulers will separate instructions by the requested latency only when there’s other useful work to do. Otherwise, there’s no reason to separate them - the stall is inevitable.
-### **Functional Unit Template Definitions** {#functional-unit-template-definitions}
+### **Functional Unit Template Definitions**
A functional unit template describes, abstractly, what operations can be performed on any instance of the unit, and how those operations use the template parameters - register classes and resource references. An abstract set of operations is represented by a subunit instance, which represents a set of instructions with similar behavior in terms of functional unit usage, resource usage, and register classes. Functional unit templates are defined in their own private namespace.
@@ -1264,37 +1269,35 @@ The general schema of a functional unit template looks like this: \
-#### **Simplest Functional Unit Template Definition** {#simplest-functional-unit-template-definition}
+#### **Simplest Functional Unit Template Definition**
The simplest example of a functional unit template would define a functional unit that has no parameters, and implements a single subunit:
- **<code>func_unit simple() {</code></strong>
-
```
- subunit xyzzy();
-}
+ func_unit simple() {
+ subunit xyzzy();
+ }
```
In this case, any instruction that is defined to use the subunit “xyzzy” can run on this functional unit. This template doesn’t impose any additional constraints on those instructions, and no shared resources are used.
-#### **Defining Functional Unit Resources** {#defining-functional-unit-resources}
+#### **Defining Functional Unit Resources**
A functional unit template can locally define resources which represent hardware resources tied to _each instance_ of the functional unit. These can be used to specialize subunit instances:
- **<code>func_unit unit_with_local_resources() {</code></strong>
-
```
- resource my_resource;
- resource my_pooled_resource[4];
+ func_unit unit_with_local_resources() {
+ resource my_resource;
+ resource my_pooled_resource[4];
- subunit add(my_resource, my_pooled_resource[0..1]);
- subunit subtract(my_resource, my_pooled_resource[2..3]);
- subunit multiply(my_pooled_resource);
-}
+ subunit add(my_resource, my_pooled_resource[0..1]);
+ subunit subtract(my_resource, my_pooled_resource[2..3]);
+ subunit multiply(my_pooled_resource);
+ }
```
@@ -1303,36 +1306,42 @@ In this example, the functional unit supports 3 classes of instructions (add, su
Importantly: functional-unit-local resources which are used for multiple cycles can be used to model non-pipelined functional units - i.e.units which are reserved for some number of cycles.
-#### **Defining “Port” Resources** {#defining-“port”-resources}
+#### **Defining “Port” Resources**
A port is a resource type that explicitly binds a named register class with a resource reference. A port is used to specialize subunit instances, and adding functional-unit-specific register constraints on instructions associated with the subunit.
A port definition has the general form:
- **<code>'port' <port_name> ('<' <register_class_name> '>')? ('(' resource_ref ')')? ;</code></strong>
-When a port is tied to more than one resource, any references to that port refer to all of the associated resources. Some examples:
+```
+ 'port' <port_name> ('<' <register_class_name> '>')? ('(' resource_ref ')')? ;
+```
- **<code>port port_a <GPR>; // port_a tied to GPR regs</code></strong>
+
+When a port is tied to more than one resource, any references to that port refer to all of the associated resources. Some examples:
```
- port port_b <LOW> (res1); // port_b tied to LOW regs and res1
- port port_c (pool[0..4]); // port_c tied to pool[0..4]
+ port port_a <GPR>; // port_a tied to GPR regs
+ port port_b <LOW> (res1); // port_b tied to LOW regs and res1
+ port port_c (pool[0..4]); // port_c tied to pool[0..4]
```
You can also use a “connect” statement to tie a port to register classes and resources:
- **<code>'connect' <port_name> 'to' <register_class_name> 'via' resource_ref ;</code></strong>
-The following is equivalent to the above definition of “port\_b”:
+```
+ 'connect' <port_name> 'to' <register_class_name> 'via' resource_ref ;
+```
+
- **<code>port port_b;</code></strong>
+The following is equivalent to the above definition of “port\_b”:
```
-connect port_b to LOW via res1;
+ port port_b;
+ connect port_b to LOW via res1;
```
@@ -1341,7 +1350,7 @@ This syntax could potentially be used to connect a port to more than one constra
Ports can be used to specialize subunit and latency instances, described in subsequent sections.
-#### **Using Template Parameters** {#using-template-parameters}
+#### **Using Template Parameters**
Resource parameters can be used exactly like locally defined resources to specialize subunit instances. Register class parameters are used to define ports. Resource parameters can refer to a single resource, a pool of resources, or a group of resources.
@@ -1349,7 +1358,7 @@ Here is an example subunit instance:
```
- subunit adder(res, porta, res2, portc);
+ subunit adder(res, porta, res2, portc);
```
@@ -1357,54 +1366,52 @@ The parameters refer to resources (or ports) defined in the functional unit, clu
```
- subunit load(pool1.member, pool2[5], pool3[2..4]);
+ subunit load(pool1.member, pool2[5], pool3[2..4]);
```
A simple example of a full functional unit template definition:
- **<code>func_unit specialized(resource shared_pool; class regs) {</code></strong>
-
```
- resource my_resource;
- port my_port<regs> (shared_pool[3..5]);
+ func_unit specialized(resource shared_pool; class regs) {
+ resource my_resource;
+ port my_port<regs> (shared_pool[3..5]);
- subunit load(my_resource, my_port);
- subunit store(my_port);
-}
+ subunit load(my_resource, my_port);
+ subunit store(my_port);
+ }
```
-#### **Conditional Subunit Instances** {#conditional-subunit-instances}
+#### **Conditional Subunit Instances**
In a functional unit template, a subunit instance can be conditionally instantiated based on a predicate. Predicates are simply names of the instantiating cpu definition and functional unit instance. This allows us to specialize a functional unit instance based on how its instantiated, for example:
- **<code>cpu my_cpu {</code></strong>
-
```
- func_unit my_func xyzzy();
- func_unit my_func plugh();
- }
-func_unit my_func() {
- resource pooled_resource[4];
- xyzzy: subunit add(pooled_resource[0..1]);
- plugh: subunit add(pooled_resource[2..3]);
-}
+ cpu my_cpu {
+ func_unit my_func xyzzy();
+ func_unit my_func plugh();
+ }
+ func_unit my_func() {
+ resource pooled_resource[4];
+ xyzzy: subunit add(pooled_resource[0..1]);
+ plugh: subunit add(pooled_resource[2..3]);
+ }
```
-#### **Using Base Functional Units** {#using-base-functional-units}
+#### **Using Base Functional Units**
Functional units tend to get more capable over generations of a processor, so we’d like a way to derive functional units from other functional units. A functional unit template can be defined to have a base functional unit, for example:
```
- func_unit base_func() { … }
- func_unit my_func : base_func() { … }
+ func_unit base_func() { … }
+ func_unit my_func : base_func() { … }
```
@@ -1413,13 +1420,13 @@ In this example, the template “my\_func” simply includes the definition of
In effect, when you instantiate a based functional unit, you implicitly instantiate its bases and any subbases. This language feature allows us to easily extend functional unit definitions over processor generations.
-#### **Defining functional unit groups** {#defining-functional-unit-groups}
+#### **Defining functional unit groups**
When defining a superscalar CPU, its generally not necessary to provide a functional unit template definition for each functional unit, since latency rules specify which functional units are used by a subunit. In this case, its helpful to be able to easily specify an arbitrary pool of functional units that can be used for an instruction. So the MDL has a way to do that.
```
- func_unit_group : 'func_group' IDENT ('<' number '>')? : name_list ;
+ func_unit_group : 'func_group' IDENT ('<' number '>')? : name_list ;
```
@@ -1434,7 +1441,7 @@ For example:
This defines a functional unit group with 3 members, and a single input queue of length 42. These groups are used in latency rules to tie subunits to a pool of functional units.
-### **Subunit Template Definitions** {#subunit-template-definitions}
+### **Subunit Template Definitions**
Subunits are used to link sets of instruction definitions to their pipeline behaviors and candidate functional units. Subunits appear in three contexts:
@@ -1491,12 +1498,11 @@ A subunit template has the following general schema:
Latency instance instances (in subunit templates) have the following general forms:
- **<code>latency <latency_name> ( <subunit parameters> );</code></strong>
-
```
- <predicate> : latency <latency_name> ( <latency parameters> );
- <predicate> : { <latency statements> }
+ latency <latency_name> ( <subunit parameters> );
+ <predicate> : latency <latency_name> ( <latency parameters> );
+ <predicate> : { <latency statements> }
```
@@ -1512,7 +1518,7 @@ The optional predicate is a comma-separated list of names which refers to the CP
A subunit template can specify as many latency instances as needed - the resulting subunit is the union of all the valid latency templates. This allows you to separate different classes of behaviors into different latency templates. Since latency templates are also specialized, you can manage the separation in latencies. The typical practice is for a subunit to have a single latency instance.
-#### Subunit Template Parameters {#subunit-template-parameters}
+#### Subunit Template Parameters
Subunit template parameters can be a mix of ports and resources, and are used to specialize a subunit for the context in which it is instantiated, for example:
@@ -1525,7 +1531,7 @@ Subunit template parameters can be a mix of ports and resources, and are used to
In general, these work exactly the same way functional unit templates are used. They can be used as latency parameters to specialize latency instances.
-#### Tying Instructions to Subunits {#tying-instructions-to-subunits}
+#### Tying Instructions to Subunits
There are two ways to associate subunits to instructions:
@@ -1537,7 +1543,7 @@ There are two ways to associate subunits to instructions:
We discuss these two approaches below.
-##### Subunits in Instructions {#subunits-in-instructions}
+##### Subunits in Instructions
Subunits are associated with instruction definitions to...
@@ -1553,7 +1559,7 @@ Each defined instruction must specify at least one subunit that it is bound to.
We allow more than one subunit per instruction, which implies different instruction behaviors across CPUs or functional units. In general, this isn’t necessary, since a subunit can specify different behaviors for different functional units and/or CPUs. So this is strictly a stylistic choice.
-##### Subunit Bases {#subunit-bases}
+##### Subunit Bases
A subunit template definition can have one or more “bases”. A base is either the name of another subunit, or a string representing a regular expression of instruction names. Bases tie a subunit to sets of instructions, either directly by instruction name, or transitively through their base subunits. A subunit does not need to have the same parameters as its bases, and does not inherit any latency information from its bases.
@@ -1568,7 +1574,7 @@ This example ties the “add” subunit to any instruction with “ADD” as a n
Subunit bases provide an alternate way of tying instructions to subunits without modifying the instruction definitions (where each instruction can tie itself to a set of subunits). This effectively allows a single “base” subunit - and all of its associated instructions - to have different latency behaviors for each target.
-#### Shorthand Subunit Template Definitions {#shorthand-subunit-template-definitions}
+#### Shorthand Subunit Template Definitions
Often a subunit template simply specifies a single latency template instance, and the latency template may only be used in a single subunit template. In that case, we have a shorthand that combines the latency template into the subunit template. For example:
@@ -1592,7 +1598,7 @@ subunit load(resource a, b, c) {{
-### **Latency Template Definitions** {#latency-template-definitions}
+### **Latency Template Definitions**
A latency template specifies the detailed pipeline behavior for a class of instructions. The class of “client” instructions for a latency template is the set of instructions that use any subunit that instantiates the latency template.
@@ -1607,14 +1613,13 @@ Latency templates:
A latency template definition has the following general schema:
- `latency <name> : base_latencies ( <parameters> ) {`
-
```
- <latency reference>
- <latency reference>
- …
- }
+ latency <name> : base_latencies ( <parameters> ) {
+ <latency reference>
+ <latency reference>
+ …
+ }
```
@@ -1678,7 +1683,7 @@ The full grammar:
-#### **Derived Latency Templates** {#derived-latency-templates}
+#### **Derived Latency Templates**
A latency template can be derived from one or more base latency templates. Any hierarchy is allowed (except recursive), as long as the base template has the exact same leading parameters as the derived latency. A base latency can be included more than once in the hierarchy - this doesn’t matter, since all occurrences of that base are identical (so duplicates are ignored):
@@ -1694,7 +1699,7 @@ A latency template can be derived from one or more base latency templates. Any
In this example, my\_latency includes base1, base2, and base3. Deriving latency templates is a fairly common pattern: instruction classes often share _some_ behaviors, but not all. So those shared behaviors can be put in a base latency template. A common example is an instruction predicate, perhaps shared by all instructions.
-#### **Latency References** {#latency-references}
+#### **Latency References**
A latency reference statement describes a single operand reference and/or resource references in a specified pipeline stage. It references instruction operands _by name, _as well as resource and port parameters, and ties the operations to named pipeline phases.
@@ -1709,7 +1714,7 @@ Latency references have the following general form:
where either the operand specifier or ports/resources may be omitted. A single reference statement asserts that an operand and resources are referenced in a specific pipeline phase for any instruction that this rule could apply to, ie: _any instruction that uses a subunit that instantiates this latency template._ Each aspect of a latency reference are described below.
-##### **Operand and resource latency operators:** {#operand-and-resource-latency-operators}
+##### **Operand and resource latency operators:**
There are 6 basic operator types in a latency reference:
@@ -1731,7 +1736,7 @@ There are 3 additional operator types which are primarily used as shortcuts (the
* or - this is essentially a conditional def, but the instruction has no explicit predicate (useful for status-setting instructions).
-##### **Phase Expressions** {#phase-expressions}
+##### **Phase Expressions**
The phase expression specifies the pipeline phase that the operation occurs in. The expression can refer directly to a defined phase name, or an expression based on a phase name:
@@ -1755,7 +1760,7 @@ where “$width” is an immediate instruction operand. Its value is fetched fro
Phase expressions have a limited set of operators: +, -, \*, /, (). Since latencies must be positive integers, we also provide a “floor” operator which converts negative expressions to 0. Simply enclose the expression in curly braces ({...}).
-##### **Operand Specifiers** {#operand-specifiers}
+##### **Operand Specifiers**
The operand specifier has the same grammar as in tablegen, which allows you to specify an optional operand type, the operand name, and optional sub-operand names:
@@ -1773,13 +1778,14 @@ Operand specifiers act as predicates for the validity of a reference for a parti
```
- GPR:$dst // an operand named "dst" with operand type GPR
- ADR:$dst // an operand named "dst" with operand type ADR
- $dst // an operand named "dst", with any operand type
+ GPR:$dst // an operand named "dst" with operand type GPR
+ ADR:$dst // an operand named "dst" with operand type ADR
+ $dst // an operand named "dst", with any operand type
```
-` opnd:$src.reg // an operand named "src", type "opnd", suboperand "reg"`
+
+ `opnd:$src.reg // an operand named "src", type "opnd", suboperand "reg"`
Because a latency could be specialized for many instructions which have different sets of operands, the operand specifier acts as a predicate for the application of a reference to a particular instruction. When the operand isn’t present in a client instruction, the latency reference is ignored for that instruction. For example, you can differentiate on operand type:
@@ -1796,18 +1802,19 @@ Or you can differentiate based on the operand name:
```
- use(E2, $src1); // most instructions have at least one src opnd
- use(E3, $src2); // some instructions have 2 source operands
+ use(E2, $src1); // most instructions have at least one src opnd
+ use(E3, $src2); // some instructions have 2 source operands
```
-` use(E4, $src3); // and some instructions have 3!` \
+
+ `use(E4, $src3); // and some instructions have 3!` \
Note that operands _can _be referenced by their index in an instruction’s operand list, but this is error-prone and this isn’t considered best practice because we can’t thoroughly check the validity of the index. The syntax is simply “$<index>”. Note that sub-operands often aren’t given names in tablegen, and must be referenced by index, for example: $src.1. Unnamed variant operands (obviously) don’t have names, and are referenced by their position past the end of the operands defined for an instruction, ie “$$1”, “$$2”, etc.
-##### **Resource References** {#resource-references}
+##### **Resource References**
Any latency reference can include an optional set of resource references. These have slightly different semantics depending on the operator type (def/use/predicate/hold/reserve).
@@ -1830,7 +1837,7 @@ For “hold” and “reserve” operations, the operand specifier is optional,
-#### **Conditional References** {#conditional-references}
+#### **Conditional References**
Any reference in a latency rule can be conditional, using a predicate identifier. The predicates are generally identical to LLVM predicates, and check an attribute of a client instruction.
@@ -1838,31 +1845,31 @@ Conditional references can be nested, for arbitrarily complex references. These
```
-if <predicate_name> { <set of refs> }
-else if <predicate_name> { <set of refs> }
-else { <set of refs> }
+ if <predicate_name> { <set of refs> }
+ else if <predicate_name> { <set of refs> }
+ else { <set of refs> }
```
-#### **Functional Unit and Micro-op References** {#functional-unit-and-micro-op-references}
+#### **Functional Unit and Micro-op References**
A latency rule can directly specify a set of functional units and how long they are used, as well as specifying the number of micro-ops required for the operation. Each functional unit can optionally specify a pipeline “StartAt” cycle, which by default is the first execution phase.
```
- fus(13); // Instruction has 13 micro-operations.
-fus(ALU, 2); // use ALU for 1 cycle, 2 micro-operations.
- fus(ALU<3>, 1); // use ALU for 3 cycles, 1 micro-operation.
- fus(ALU<E5:4>, 1); // use ALU starting at E5 for 4 cycles.
- fus(ALU1<12>&ALU2<E12:30>&LOAD<E42:2>); // use ALU1, ALU2, and LOAD
+ fus(13); // Instruction has 13 micro-operations.
+ fus(ALU, 2); // use ALU for 1 cycle, 2 micro-operations.
+ fus(ALU<3>, 1); // use ALU for 3 cycles, 1 micro-operation.
+ fus(ALU<E5:4>, 1); // use ALU starting at E5 for 4 cycles.
+ fus(ALU1<12>&ALU2<E12:30>&LOAD<E42:2>); // use ALU1, ALU2, and LOAD
```
These statements allow a latency rule (or subunit) to tie a set of instructions to functional unit instances. When there is more than one instance of the specified unit, or if the unit is declared to be a functional unit group, at compile time _one_ of those units is selected. Likewise, if the unit is a subunit of one or more functional units, one of the “parent” functional units is selected.
-## **Machine Description Compiler Artifacts** {#machine-description-compiler-artifacts}
+## **Machine Description Compiler Artifacts**
What does all of this produce?
@@ -1883,10 +1890,15 @@ The other primary artifact is a set of objects and methods for managing the low-
As part of this effort, we will incrementally modify the LLVM compiler to alternatively use this information alongside of SchedMachineModel and Itinerary methodologies.
-
+<p id="gdcalert1" ><span style="color: red; font-weight: bold">>>>> GDC alert: inline image link here (to images/image1.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert2">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>> </span></p>
+
+
+
-## **Using the MDL Language in LLVM** {#using-the-mdl-language-in-llvm}
+
+
+## **Using the MDL Language in LLVM**
The proposed use case for the MDL language is as an alternative specification for the architecture description currently embodied in TableGen Schedules and Itineraries, particularly for architectures for which Schedules and Itineraries are not expressive enough. It is explicitly _not_ the intent that it “replace TableGen”. But we believe that the MDL language is a better language (vs Schedules and Itineraries) for a large class of accelerators, and can be used effectively alongside TableGen.
@@ -1913,17 +1925,22 @@ The general development flow of using an MDL description in LLVM looks like this
5. Build LLVM.
-
+
+<p id="gdcalert2" ><span style="color: red; font-weight: bold">>>>> GDC alert: inline image link here (to images/image2.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert3">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>> </span></p>
+
+
+
+
-### **TdScan** {#tdscan}
+### **TdScan**
To synchronize an MDL architecture description with llvm TableGen descriptions, we’ve written a tool which scrapes information that the MDL compiler needs from Tablegen files. In the general case, it collects basic information about registers, register classes, operands, and instruction definitions, and it produces an “mdl” file which can be processed by the MDL compiler to sync an architecture description to the tablegen descriptions of instructions.
For currently upstreamed targets that use Schedules or Itineraries, TdScan can also extract the whole architecture specification from the tablegen files, and produce an MDL description of the architecture. We’ve used this approach to prove out our llvm integration with upstreamed targets. The integration and testing of this is ongoing.
-### **Upstream Targets** {#upstream-targets}
+### **Upstream Targets**
In general, upstream targets have no compelling need for MDL descriptions - the existing Schedules and/or Itinerary descriptions are field tested. However, there are a few benefits to using an MDL description for existing targets. The primary benefit is that the MDL descriptions are typically quite a bit smaller, succinct, and (we believe) intuitive than the equivalent TableGen descriptions.
@@ -2031,7 +2048,7 @@ In general, upstream targets have no compelling need for MDL descriptions - the
\*\* Note: the MDL numbers are generated both with and without “index-based” references in subunit/latency rules, vs symbolic references. These are typically 10-20% less lines of MDL description than when operand names are used, almost entirely due to operand name differences between instruction definitions (like “dest” vs “dst”, or “src1” vs “s1”). However, the databases produced by the two approaches are virtually identical - albeit ordered differently.
-### **Syncing Instruction Information** {#syncing-instruction-information}
+### **Syncing Instruction Information**
The MDL compiler needs 3 pieces of information from tablegen for each machine instruction:
@@ -2046,7 +2063,7 @@ Subunits are a new concept introduced with the MDL. The normal approach is to m
As part of the build process, we use a program (“tdscan”) which scrapes the instruction information - including the subunit information from a target’s tablegen files and generates information about the target’s instructions. Tdscan allows us to stay in sync with changes to instruction definitions.
-### **Using the generated microarchitecture information in LLVM** {#using-the-generated-microarchitecture-information-in-llvm}
+### **Using the generated microarchitecture information in LLVM**
There are two classes of services that the MDL database and associated APIs provide:
@@ -2074,7 +2091,7 @@ We provide code and libraries to do the following things - in machine-independen
There’s more we can do here, and a deeper integration with upstreamed LLVM is a long-term goal.
-### **Current Status of the LLVM Integration (briefly)** {#current-status-of-the-llvm-integration-briefly}
+### **Current Status of the LLVM Integration (briefly)**
@@ -2087,7 +2104,7 @@ There’s more we can do here, and a deeper integration with upstreamed LLVM is
-## **Appendix A: Full Language Grammar** {#appendix-a-full-language-grammar}
+## **Appendix A: Full Language Grammar**
This may be slightly out of date. The definitive Antlr4-based grammar is in llvm/utils/MdlCompiler/mdl.g4.
@@ -2401,10 +2418,10 @@ range : number '..' number ;
-## **Appendix B: Future Directions** {#appendix-b-future-directions}
+## **Appendix B: Future Directions**
-### **Memory Hierarchy** {#memory-hierarchy}
+### **Memory Hierarchy**
We need a first class representation of any compiler-managed memory hierarchy.
@@ -2446,7 +2463,7 @@ DMA system descriptions
Multi-Processor System Topology
-## **Appendix C: RISC-V Generated Architecture Description** {#appendix-c-risc-v-generated-architecture-description}
+## **Appendix C: RISC-V Generated Architecture Description**
This is a complete, automatically generated machine description for RISC-V using our tool to scrape information from tablegen files. We can automatically generate MDL specifications for all targets that have schedules and/or itineraries. We include RISC-V here for illustrative purposes.
>From e8a71f8c7a055138e181c78950442651ce93684b Mon Sep 17 00:00:00 2001
From: Reid Tatge <tatge at google.com>
Date: Fri, 19 Jan 2024 22:14:06 +0000
Subject: [PATCH 10/14] [LLVM][MDL] Fix endless formatting problems
---
llvm/docs/Mdl/MachineDescriptionNotes.md | 10 ----------
1 file changed, 10 deletions(-)
diff --git a/llvm/docs/Mdl/MachineDescriptionNotes.md b/llvm/docs/Mdl/MachineDescriptionNotes.md
index 8b30c756fe4015d..2cfc3fdf9d5ef5e 100644
--- a/llvm/docs/Mdl/MachineDescriptionNotes.md
+++ b/llvm/docs/Mdl/MachineDescriptionNotes.md
@@ -1,14 +1,4 @@
-<p style="color: red; font-weight: bold">>>>> GDC alert: ERRORs: 0; WARNINGs: 0; ALERTS: 2.</p>
-<ul style="color: red; font-weight: bold"><li>See top comment block for details on ERRORs and WARNINGs. <li>In the converted Markdown or HTML, search for inline alerts that start with >>>> GDC alert: for specific instances that need correction.</ul>
-
-<p style="color: red; font-weight: bold">Links to alert messages:</p><a href="#gdcalert1">alert1</a>
-<a href="#gdcalert2">alert2</a>
-
-<p style="color: red; font-weight: bold">>>>> PLEASE check and correct alert issues and delete this message and the inline alerts.<hr></p>
-
-
-
# MPACT Microarchitecture Description Language
Reid Tatge [tatge at google.com](mailto:tatge at google.com)
>From 8eee8222af88ef7b69af9cba3b077f596a22e9ee Mon Sep 17 00:00:00 2001
From: Reid Tatge <tatge at google.com>
Date: Fri, 19 Jan 2024 22:23:33 +0000
Subject: [PATCH 11/14] [LLVM][MDL] Even more formatting problems
---
llvm/docs/Mdl/MachineDescriptionNotes.md | 13 ++-----------
1 file changed, 2 insertions(+), 11 deletions(-)
diff --git a/llvm/docs/Mdl/MachineDescriptionNotes.md b/llvm/docs/Mdl/MachineDescriptionNotes.md
index 2cfc3fdf9d5ef5e..421f391e73f19b9 100644
--- a/llvm/docs/Mdl/MachineDescriptionNotes.md
+++ b/llvm/docs/Mdl/MachineDescriptionNotes.md
@@ -1879,12 +1879,7 @@ The other primary artifact is a set of objects and methods for managing the low-
As part of this effort, we will incrementally modify the LLVM compiler to alternatively use this information alongside of SchedMachineModel and Itinerary methodologies.
-
-
-<p id="gdcalert1" ><span style="color: red; font-weight: bold">>>>> GDC alert: inline image link here (to images/image1.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert2">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>> </span></p>
-
-
-
+
@@ -1915,11 +1910,7 @@ The general development flow of using an MDL description in LLVM looks like this
5. Build LLVM.
-
-<p id="gdcalert2" ><span style="color: red; font-weight: bold">>>>> GDC alert: inline image link here (to images/image2.png). Store image on your image server and adjust path/filename/extension if necessary. </span><br>(<a href="#">Back to top</a>)(<a href="#gdcalert3">Next alert</a>)<br><span style="color: red; font-weight: bold">>>>> </span></p>
-
-
-
+
>From 6ed81f0695873ccf344aa671fb5e3064eff74439 Mon Sep 17 00:00:00 2001
From: Reid Tatge <35816723+reidtatge at users.noreply.github.com>
Date: Tue, 23 Jan 2024 12:50:51 -0800
Subject: [PATCH 12/14] Update RFC.md
---
llvm/docs/Mdl/RFC.md | 20 +++-----------------
1 file changed, 3 insertions(+), 17 deletions(-)
diff --git a/llvm/docs/Mdl/RFC.md b/llvm/docs/Mdl/RFC.md
index f8d35dc27c16447..9cf9e3195ad77d1 100644
--- a/llvm/docs/Mdl/RFC.md
+++ b/llvm/docs/Mdl/RFC.md
@@ -10,18 +10,14 @@ Updated January 2024
We’ve created a DSL and compiler for modeling micro-architecture that handles a very broad class of architectures - CPUs, GPUs, VLIWs, DSPs, ML accelerators, and embedded devices. This effort grew out of a need to quickly develop and experiment with high-quality compilers and tools to facilitate rapid architecture exploration. We named the DSL “MDL” for “Microarchitecture Description Language”.
-While being significantly more expressive than TableGen’s Schedules and Itineraries used in LLVM, MDL is also more concise, and simpler to read and write while supporting a much broader class of embedded and accelerator architectures. We currently can automatically _generate _MDL descriptions for all upstream targets which are in many cases 1/10 the size of the equivalent TableGen descriptions. We’ve integrated this with LLVM, and are sending out this RFC because we believe it could be valuable to the larger LLVM community. \
-
+While being significantly more expressive than TableGen’s Schedules and Itineraries used in LLVM, MDL is also more concise, and simpler to read and write while supporting a much broader class of embedded and accelerator architectures. We currently can automatically generate MDL descriptions for all upstream targets which are in many cases 1/10 the size of the equivalent TableGen descriptions. We’ve integrated this with LLVM, and are sending out this RFC because we believe it could be valuable to the larger LLVM community.
The MDL compiler, associated tools, and documentation are available as open source (at https://github.com/MPACT-ORG/llvm-project/tree/all), and we would like to explore adding this to the LLVM project, and encourage contributions from others.
-
## **Background**
Over the last few years, we have been using LLVM to develop a compiler backend for Google’s TPU machine learning accelerators. TPUs have complex microarchitectures and pose a number of challenges that are not seen in in typical LLVM targets:
-
-
* Clustered VLIW with partitioned register files.
* Extremely deep pipelines with complex hazard conditions
* Instructions with functional-unit-specific and/or cluster-specific behaviors
@@ -33,32 +29,22 @@ Over the last few years, we have been using LLVM to develop a compiler backend f
While some of these problems manifest in a few upstream LLVM targets, this collection of problems is a superset of the problems directly addressed by LLVM - Schedules and Itineraries are simply not sufficient to model everything. Supporting this class of architecture is therefore code-intensive - it takes around 20,000 lines of C++ code to model the TPU sub-targets. This is brittle, hard to write, debug, test, and evolve over time. In contrast, the MDL description for these sub-targets is ~2,000 lines of text, and requires very little (if any) target-specific code in the backend.
-
## **Status**
-
-
* We’ve created the MDL language and compiler for describing microarchitecture details, a methodology for integrating it with TableGen files for any target, and a set of APIs that can be used in a machine-independent way to inform back-end passes such as bundle-packing, instruction scheduling, and register allocation.
* To facilitate integration with LLVM, we built a tool which scrapes architectural information from TableGen files, and produces our MDL language for all upstream targets.
* We’ve modified the CodeGen and MC libraries to (optionally) use our methodology for latency management.
-
## **Building**
-
-
-* You can build llvm with or without MDL support. It is included by using the LLVM\_ENABLE\_MDL CMake parameter. If included, it is currently used by default, and can be disabled with a command line option (--schedmdl=0).
-
+* You can build llvm with or without MDL support. It is included by using the LLVM_ENABLE_MDL CMake parameter. If included, it is currently used by default, and can be disabled with a command line option (--schedmdl=0).
## **Testing**
-
-
* When built without MDL support, the compiler passes all check-all tests.
-* When built with MDL support, but disabled on the command line, the compielr passes all check-all tests.
+* When built with MDL support, but disabled on the command line, the compiler passes all check-all tests.
* When MDL support is enabled, it passs all but 190 tests (out of ~90K+ tests).
There is a lot more to do. For example, we plan to enhance existing back-end scheduling passes and register allocation passes to cleanly handle a larger class of embedded and accelerator architectures, based on MDL-generated information.
We welcome feedback on the language design and associated tools and use model. You can find the MDL design documentation, compiler, and other tools in our github repo in llvm/docs/mdl.
-
>From 1aeb5ae775386760fc82fd13f6c17a32932f6e43 Mon Sep 17 00:00:00 2001
From: Reid Tatge <35816723+reidtatge at users.noreply.github.com>
Date: Tue, 23 Jan 2024 12:59:35 -0800
Subject: [PATCH 13/14] Update RFC.md
---
llvm/docs/Mdl/RFC.md | 8 ++++----
1 file changed, 4 insertions(+), 4 deletions(-)
diff --git a/llvm/docs/Mdl/RFC.md b/llvm/docs/Mdl/RFC.md
index 9cf9e3195ad77d1..5ec39b6285300f2 100644
--- a/llvm/docs/Mdl/RFC.md
+++ b/llvm/docs/Mdl/RFC.md
@@ -12,7 +12,7 @@ We’ve created a DSL and compiler for modeling micro-architecture that handles
While being significantly more expressive than TableGen’s Schedules and Itineraries used in LLVM, MDL is also more concise, and simpler to read and write while supporting a much broader class of embedded and accelerator architectures. We currently can automatically generate MDL descriptions for all upstream targets which are in many cases 1/10 the size of the equivalent TableGen descriptions. We’ve integrated this with LLVM, and are sending out this RFC because we believe it could be valuable to the larger LLVM community.
-The MDL compiler, associated tools, and documentation are available as open source (at https://github.com/MPACT-ORG/llvm-project/tree/all), and we would like to explore adding this to the LLVM project, and encourage contributions from others.
+The MDL compiler, associated tools, and documentation are available as open source at [MPACT-ORG](https://github.com/MPACT-ORG/llvm-project/tree/all), and we would like to explore adding this to the LLVM project, and encourage contributions from others.
## **Background**
@@ -37,14 +37,14 @@ While some of these problems manifest in a few upstream LLVM targets, this colle
## **Building**
-* You can build llvm with or without MDL support. It is included by using the LLVM_ENABLE_MDL CMake parameter. If included, it is currently used by default, and can be disabled with a command line option (--schedmdl=0).
+* You can build llvm with or without MDL support. It is included by using the LLVM_ENABLE_MDL CMake parameter. If included, it is currently used by default, and can be disabled with a command line option `--schedmdl=0`.
## **Testing**
* When built without MDL support, the compiler passes all check-all tests.
* When built with MDL support, but disabled on the command line, the compiler passes all check-all tests.
-* When MDL support is enabled, it passs all but 190 tests (out of ~90K+ tests).
+* When MDL support is enabled, it pass all but 190 tests (out of ~90K+ tests).
There is a lot more to do. For example, we plan to enhance existing back-end scheduling passes and register allocation passes to cleanly handle a larger class of embedded and accelerator architectures, based on MDL-generated information.
-We welcome feedback on the language design and associated tools and use model. You can find the MDL design documentation, compiler, and other tools in our github repo in llvm/docs/mdl.
+We welcome feedback on the language design and associated tools and use model. You can find the MDL design documentation, compiler, and other tools in our github repo in [llvm/docs/mdl](https://github.com/llvm/llvm-project/tree/main/llvm/docs/Mdl).
>From 2143797a12a66c1196c7a63d27ed84477d6da21e Mon Sep 17 00:00:00 2001
From: Reid Tatge <35816723+reidtatge at users.noreply.github.com>
Date: Tue, 23 Jan 2024 13:53:01 -0800
Subject: [PATCH 14/14] Update MachineDescriptionNotes.md
---
llvm/docs/Mdl/MachineDescriptionNotes.md | 546 +++++------------------
1 file changed, 105 insertions(+), 441 deletions(-)
diff --git a/llvm/docs/Mdl/MachineDescriptionNotes.md b/llvm/docs/Mdl/MachineDescriptionNotes.md
index 421f391e73f19b9..eced841c2e38c94 100644
--- a/llvm/docs/Mdl/MachineDescriptionNotes.md
+++ b/llvm/docs/Mdl/MachineDescriptionNotes.md
@@ -12,8 +12,6 @@ However, modern accelerators have different and/or additional dimensions of comp
So we have several goals:
-
-
1. We want a first-class, purpose-built, intuitive language that captures all the scheduling and latency details of the architecture - much like Schedules and Itineraries - that works well for all current targets, but also for a large class of accelerator architectures..
2. The complexity of the specification should scale with the complexity of the hardware.
3. The description should be succinct, avoiding duplicated information, while reflecting the way things are defined in a hardware architecture specification.
@@ -22,12 +20,8 @@ So we have several goals:
For this document (and language), the term “instructions” refers to the documented instruction set of the machine, as represented by LLVM instructions descriptions, rather than undocumented micro-operations used by many modern microprocessors.
-
-
The process of compiling a processor’s machine description creates several primary artifacts:
-
-
* For each target instruction (described in td files), we create an object that describes the detailed behaviors of the instruction in any legal context (for example, on any functional unit, on any processor)
* A set of methods with machine independent APIs that leverage the information associated with instructions to inform and guide back-end optimization passes.
@@ -37,7 +31,6 @@ _Note: A full language grammar description is provided in an appendix. Snippets
The proposed language can be thought of as an _optional extension to the LLVM machine description_. For most upstream architectures, the new language offers minimal benefit other than a much more succinct way to specify the architecture vs Schedules and Itineraries. But for accelerator-class architectures, it provides a level of detail and capability not available in the existing tablegen approaches.
-
### **Background**
Processor families evolve over time. They accrete new instructions, and pipelines change - often in subtle ways - as they accumulate more functional units and registers; encoding rules change; issue rules change. Understanding, encoding, and using all of this information - over time, for many subtargets - can be daunting. When the description language isn’t sufficient to model the architecture, the back-end modeling evolves towards heuristics, and leads to performance issues or bugs in the compiler. And it certainly ends with large amounts of target specific code to handle “special cases”.
@@ -46,8 +39,6 @@ LLVM uses the [TableGen](https://llvm.org/docs/TableGen/index.html) language to
We would like to easily handle:
-
-
* Complex pipeline behaviors
* An instruction may have different latencies, resource usage, and/or register constraints on different functional units or different operand values.
* An instruction may read source registers more than once (in different pipeline phases).
@@ -58,13 +49,10 @@ We would like to easily handle:
* Share execution resources with other functional units (such as register ports)
* Functional unit clusters with separate execution pipelines.
* VLIW Architecture
- * issue rules can get extremely complex, and can be dependent on encoding, operand features, and pipeline behavior of candidate instructions.** \
-**
+ * issue rules can get extremely complex, and can be dependent on encoding, operand features, and pipeline behavior of candidate instructions.
More generally, we’d like specific language to:
-
-
* Support all members of a processor family
* Describe CPU features, parameterized by subtarget
* Functional units
@@ -73,10 +61,9 @@ More generally, we’d like specific language to:
Since our emphasis is on easily supporting accelerators and VLIW processors, in addition to supporting all existing targets, much of this is overkill for most upstreamed CPUs. CPU’s typically have much simpler descriptions, and don’t require much of the capability of our machine description language. Incidentally, MDL descriptions of these targets (generated automatically from the tablegen Schedules and Itineraries) are typically much more concise than the original tablegen descriptions.
-
### **Approach - “Subunits” and Instruction Behaviors**
-We developed a DSL that allows us to describe an arbitrary processor microarchitecture in terms that reflect what is typically documented in the hardware specification. The MDL compiler creates a database that provides microarchitecture behavior information that can _automatically _inform critical back-end compiler passes, such as instruction scheduling and register allocation, in a machine-independent way.
+We developed a DSL that allows us to describe an arbitrary processor microarchitecture in terms that reflect what is typically documented in the hardware specification. The MDL compiler creates a database that provides microarchitecture behavior information that can _automatically_ inform critical back-end compiler passes, such as instruction scheduling and register allocation, in a machine-independent way.
It’s important to note the difference between an instruction definition, as described in LLVM, and an instruction instance. Generally, instructions defined in LLVM share the same behaviors across all instances of that instruction in a single subtarget. Exceptions to this require non-trivial code in the back-end to model variant behavior. In VLIW and accelerator architectures, each generated instance of an instruction can have different behaviors, depending on how it's issued, its operand values, the functional unit it runs on, and the subtarget. So we provide a way to model those differences in reasonable ways.
@@ -86,12 +73,7 @@ Naively, we could create unique subunits for each behavior for each instruction,
A key aspect of this language design is that we can explicitly represent the potentially polymorphic behavior of each generated instance of any instruction, on any functional unit, on any subtarget. The representation also comprehends that this information can vary between each of an instruction’s instances.
-
-
-We define a subunit as an object that defines the _behavior sets_ of an instruction instance in all legal contexts (functional units, issue slots), for each subtarget. In particular, we want to know: \
-
-
-
+We define a subunit as an object that defines the _behavior sets_ of an instruction instance in all legal contexts (functional units, issue slots), for each subtarget. In particular, we want to know:
* What resources are shared or reserved, in what pipeline phases.
* Encoding resources
@@ -103,15 +85,12 @@ We define a subunit as an object that defines the _behavior sets_ of an instruct
The critical artifact generated by the MDL compiler is a set of instruction behaviors for each instruction definition. For each subtarget, for each instruction, we generate a list of every possible behavior of that instruction on that CPU. While this sounds daunting, in practice it's rare to have more than a few behaviors for an instruction, and most instruction definitions share their behaviors with many other instructions, across subtargets.
-
## **Overview of a Processor Family Description**
This document generally describes the language in a bottom up order - details first. But let's start with a brief tops-down overview of what a processor family description looks like, without going into details about each part.
A minimal processor family description has the following components:
-
-
* A set of CPU definitions - one for each subtarget.
* A set of functional unit template definitions,
* A set of subunit template definitions,
@@ -127,11 +106,10 @@ A latency template defines the pipeline behavior of a set of instructions. It c
Here’s a very simple example of a trivial CPU, with three functional units, two issue slots, and a four-deep pipeline:
-
```
cpu myCpu {
phases cpu { E1, E2, E3, E4 };
- issue slot1, slot2;
+ issue slot1, slot2;
func_unit FU_ALU my_alu1(); // an instance of FU_ALU
func_unit FU_ALU my_alu2(); // an instance of FU_ALU
func_unit FU_LOAD my_load(); // an instance of FU_LOAD
@@ -159,7 +137,6 @@ Here’s a very simple example of a trivial CPU, with three functional units, tw
}
```
-
A more complete description of each part of this description is provided in the section “Defining a Processor Family”.
**Defining an ISA**
@@ -170,13 +147,10 @@ When writing a target machine description, its not necessary to write descriptio
We will describe these language features here, primarily for completeness.
-
### **Defining Instructions**
Instruction definitions are scraped from tablegen files, and provide the following information to the MDL compiler for each instruction:
-
-
* The instruction’s name (as defined in the td files)
* Its operands, with the operand type and name provided in the order they are declared, and indicating whether each is an input or output of the instruction.
* A set of “legal” subunit definitions (a “subunit” is described later in this document)
@@ -186,7 +160,6 @@ As in tablegen, an operand type must be either an operand name defined in the td
Grammar:
-
```
instruction_def : 'instruction' IDENT
'(' (operand_decl (',' operand_decl)*)? ')'
@@ -197,26 +170,21 @@ Grammar:
operand_decl : ((IDENT (IDENT)?) | '...') ('(I)' | '(O)')? ;
```
-
An example:
```
instruction ADDSWri(GPR32 Rd(O), GPR32sp Rn(I), addsub_shifted_imm32 imm(I), NZCV(O)) {
- subunit(sub24,sub26);
+ subunit(sub24,sub26);
}
```
-
This describes an ARM add instruction that has two defined input operands (Rn, imm), one defined output operand (Rd), and one implicit output operand (NZCV), which is associated with two subunits (sub24, sub26).
-
### **Defining Operands**
Operand definitions are scraped from tablegen files (like instructions), and provide the following information to the MDL compiler for each operand:
-
-
* The operand’s name,
* Its sub-operands, with the operand type and operand name provided in the order they are declared. Note that operand names are optional, and if not present we would refer to these by their sub-operand id (0, 1, etc),
* The operand’s value type.
@@ -225,31 +193,25 @@ As in LLVM, an operand definition’s sub-operand types may in turn refer to oth
Grammar:
-
```
operand_def : 'operand' IDENT
'(' (operand_decl (',' operand_decl)*)? ')'
'{' operand_type '}' ';'? ;
```
-
Some examples:
-
```
operand GPR32z(GPR32 reg) { type(i32); }
operand addsub_shifted_imm32(i32imm, i32imm) { type(i32); }
```
-
-
### **Defining Registers and Register Classes**
Registers and register classes are scraped from tablegen output. We provide a general method in the language to define registers and classes of registers which can reflect the registers defined in tablegen.
Grammar:
-
```
register_def : 'register' register_decl (',' register_decl)* ';' ;
register_decl : IDENT ('[' range ']')? ;
@@ -258,10 +220,8 @@ Grammar:
| 'register_class' IDENT '{' '}' ';'? ;
```
-
Examples:
-
```
register a0, a1, a2, a3; // 4 registers
register a[4..7]; // definition of a4, a5, a6, and a7
@@ -270,62 +230,47 @@ Examples:
register_class high5 { a[3..7] }; // a class of a3, a4, a5, a6, and a7
```
-
The order of register definitions is generally insignificant in the current MDL - we use the register names defined in LLVM, and there’s no cases in the MDL where we depend on order. Register “ranges”, such as “a[0..20]” are simply expanded into the discrete names of the entire range of registers.
-
### **Defining Derived Operands**
LLVM doesn’t necessarily provide all the information we want to capture about an instruction, so the MDL allows for defining “derived” operands with which we can associate named values. A derived operand is essentially an alias to one or more LLVM-defined operands (or derived operands), and provides a mechanism to add arbitrary attributes to operand definitions. Derived operands also allow us to treat a set of operand types as identical in latency reference rules (so you don’t have to specify a long set of operand types for some references.)
Grammar:
-
```
derived_operand_def : 'operand' IDENT (':' IDENT)+ ('(' ')')?
'{' (operand_type | operand_attribute)* '}' ';'? ;
operand_attribute_stmt : 'attribute' IDENT '=' (snumber | tuple)
('if' ('lit' | 'address' | 'label')
-```
-
-
-
- ` ('[' pred_value (',' pred_value)* ']' )? )? ';' `;
-
+ ('[' pred_value (',' pred_value)* ']' )? )? ';' `;
-```
pred_value : snumber
| snumber '..' snumber
| '{' number '}' ;
- tuple : '[' snumber (',' snumber)* ']' ;
+ tuple : '[' snumber (',' snumber)* ']' ;
```
-
-
#### **Derivation**
Each derived operand is declared with one or more “base” operands, for which it is an alias. Circular or ambiguous derivations are explicitly disallowed - there must be only one derivation path for a derived operand to any of its base concrete operands.
Derived operands are used in place of their base operands in operand latency rules in latency templates (described later). This allows a rule to match a set of operands, rather than a single operand, and also can provide access to instruction attributes to the latency rule.
-
#### **Derived operand attributes**
Derived operand attributes associate name/value-tuple pairs with the operand type. Tuples are appropriate when an attribute is used as a set of masks for resource sharing, described later.
Some examples:
-
```
attribute my_attr_a = 1;
attribute my_attr_b = 123;
attribute my_tuple = [1, 2, 3];
```
-
Attributes can have predicates that check if the operand contains a data address, a code address, or any constant. Additionally, attributes can have multiple definitions with different predicates, with the first “true” predicate determining the final value of the attribute for that operand instance:
-
```
attribute my_attr = 5 if address; // if operand is a relocatable address
attribute my_attr = 2 if label; // if operand is a code address
@@ -335,7 +280,6 @@ Attributes can have predicates that check if the operand contains a data address
Predicates for literal constants can also take an optional list of “predicate values”, where each predicate value is either an integer, a range of integers, or a “mask”. Mask predicate values are explicitly checking for non-zero bits:
-
```
attribute my_attr = 5 if lit [1, 2, 4, 8]; // looking for specific values
attribute my_attr = 12 if lit [100..200]; // looking for a range of values
@@ -344,19 +288,15 @@ Predicates for literal constants can also take an optional list of “predicate
attribute my_attr = 3 if lit [1, 4, 10..14, 0x3F800000, {0xFF00FF00}];
```
-
Note that we explicitly don’t directly support floating point numbers: this should be done instead with specific bit patterns or masks. This avoids problems with floating point precision and format differences across systems:
-
```
attribute my_attr = 1 if lit [0xBF800000, 0x402DF854]; // -1.0, or pi
attribute my_attr = 2 if lit [{0x7FFF000}]; // +BF16 number
```
-
If all of an attribute’s predicates are “false” for an instance of an operand, the compiler recursively checks the attribute’s value in each of the operand’s bases until if finds a true predicate (or an unpredicated attribute):
-
```
operand i32imm() { type(i32); } // scraped from llvm td file.
@@ -371,27 +311,20 @@ If all of an attribute’s predicates are “false” for an instance of an oper
}
```
-
-
#### **Derived operand attribute usage**
There is currently only a single context in which instruction attributes are used directly in the machine description, as part of resource references in latency rules (see “latency\_resource\_ref”). In this context, you can specify an attribute name which provides the number of resources needed for a resource allocation, and the mask used to determine shared operand bits associated with the resource. An example:
-
```
… my_resource:my_size_attribute:my_mask_attribute …
```
-
This resource reference uses the attributes from the operand associated with this reference to determine how many resources to allocate, and what bits in the operand to share.
-
## **Overview of Resources**
Resources are used to abstractly describe hardware constructs that are used by an instruction in its execution. They can represent:
-
-
* functional units,
* issue slots,
* register ports,
@@ -402,13 +335,10 @@ Its important to note that different instances of an instruction can use complet
The machine description provides a mechanism for defining and associating resources with the pipeline behaviors of instructions through the specialization of functional unit templates, subunit templates, and latency templates. It also allows automatic allocation of shared resources for an instruction instance from resource pools. The MDL compiler generates behavior descriptions which explicitly reference each resource (or resource pool) the instruction uses, and in what pipeline phases. This provides a direct methodology for managing instruction issue and pipeline behaviors such as hazards.
-
### Defining Resources
There are a few ways that resources are defined:
-
-
* **Functional Units:** A resource is implicitly defined for every functional unit instance in a CPU definition. An instruction that executes on a particular instance will reserve that resource implicitly.
* **Issue Slots: **Each CPU, or cluster of functional units in a CPU, can explicitly define a set of issue slots. For a VLIW, these resources directly correspond to instruction encoding slots in the machine instruction word, and can be used to control which instruction slots can issue to which functional units. For dynamically scheduled CPUs, these correspond to the width of the dynamic instruction issue.
* **Named Resources** can be explicitly defined in several contexts, described below.
@@ -418,7 +348,6 @@ Explicitly defined resources have scope - they can be defined globally (and appl
Named resource definitions have the following grammar:
-
```
resource_def : 'resource' ('(' IDENT ')')?
resource_decl (',' resource_decl)* ';' ;
@@ -431,128 +360,100 @@ Named resource definitions have the following grammar:
issue_resource : 'issue' ('(' IDENT ')')? name_list ';' ;
```
-
-
#### Simple resource definitions
The simplest resource definition is simply a comma-separated list of names:
-
```
resource name1, name2, name3;
```
-
A resource can also have an explicit pipeline stage associated with it, indicating that the defined resources are always used in the specified pipeline phase:
-
```
resource(E4) name1, name2; // define resources that are always used in E4
```
-
A resource can have a set of bits associated with it. This defines a resource that can be shared between two references if the bits in an associated operand reference are identical.
-
```
resource immediate:8; // define a resource with 8 bits of data
```
-
-
#### Grouped resource definitions
We can declare a set of named, related resources:
-
```
resource bits { bits_1, bits_2, bits_3 };
```
-
A resource group typically represents a pool of resources that are shared between instructions executing in parallel, where an instruction may require one or all of the resources. This is a common attribute of VLIW architectures, and used to model things like immediate pools and register ports.
Any defined resource can be included in a group, and the order of the members of a group is significant when members are allocated. If a group mentions an undefined resource (in either the current or enclosing scope), the member is declared as a resource in the current scope. In the case above, if the members (bits\_1, etc) are not declared, the compiler would create the definition:
-
```
resource bits_1, bits_2, bits_3;
```
-
and the group members would refer to these definitions. (Note: we don’t support nested groups).
The resource group can be referenced by name, referring to the entire pool, or by individual members, such as “bits.bits\_2” to specify the use of a specific pooled resource. Consider the following example:
-
```
resource bits_1, bits_2, bits_3;
resource bits_x { bits_1, bits_2, bits_3 };
resource bits_y { bits_3, bits_1, bits_2 };
```
-
“bits\_x” and “bits\_y” are distinct groups that reference the same members, but members are allocated in a different order. Groups can also be defined with syntax that indicates how its members are allocated by default.
-
```
resource bits_or { bits_1 | bits_2 | bits_3 }; // allocate one of these
resource bits_and { bits_1 & bits_2 & bits_3 }; // allocate all of these
```
-
Groups can also be implicitly defined in functional unit and subunit template instantiations as a resource parameter.
-
```
func_unit func my_fu(bits_1 | bits_2 | bits_3);
```
-
This implicitly defines a resource group with three members, and passes that group as a parameter of the instance.
-
#### Pooled resource definitions
We can also declare a set of “unnamed” pooled resources:
-
```
resource shared_bits[0..5];
```
-
This describes a resource pool with 6 members. The entire pool can be referenced by name (ie “shared\_bits”), or each member can be referenced by index (“shared\_bits[3]”), or a subrange of members (“shared\_bits[2..3]). A resource reference can also indicate that it needs some number of resources allocated with the syntax: shared\_bits:<number>.
Resource pools can also have data associated with them, each member has its own set of bits:
-
```
resource bits:20 { bits_1, bits_2, bits_3 };
resource shared_bits:5[6];
```
-
Resource pools, like resource groups, are used to model things like shared encoding bits and shared register ports, where instructions need one or more members of a set of pooled resources.
Finally, resource definitions can pin a resource to a particular pipeline phase. All references to that resource will be automatically modeled only at that pipeline stage. This is particularly useful for modeling shared encoding bits (typically for resource pools). The syntax for that looks like:
-
```
resource(E1) my_pool { res1, res2, res3 };
```
-
where E1 is the name of a pipeline phase. The resource “my\_pool” (and each of its elements) is always modeled to be reserved in pipeline phase E1.
-
### **Using Resources**
Resource references appear in several contexts. They are used in all template instantiations to specialize architecture templates (functional units, subunit, or latency templates) and are ultimately used in latency rules to describe pipeline behaviors. These will be described later in the document.
When used to specialize template instances, resource references have the following grammar:
-
```
resource_ref : IDENT ('[' range ']')?
| IDENT '.' IDENT
@@ -561,23 +462,19 @@ When used to specialize template instances, resource references have the followi
| IDENT ('&' IDENT)+ ;
```
-
Some examples of resource uses in functional unit instantiations, subunit instantiations, latency instantiations, and latency reference rules:
-
```
-some_resource // reference a single resource or an entire group/pool
-some_resource_pool[1] // use a specific member from an unnamed pool.
-register_ports[6..9] // select a subset of unnamed pooled resources.
-group.xyzzy // select a single named item from a group.
-res1 | res2 | res3 // select one of these resources
-res6 & res7 & res8 // select all of these resources
+ some_resource // reference a single resource or an entire group/pool
+ some_resource_pool[1] // use a specific member from an unnamed pool.
+ register_ports[6..9] // select a subset of unnamed pooled resources.
+ group.xyzzy // select a single named item from a group.
+ res1 | res2 | res3 // select one of these resources
+ res6 & res7 & res8 // select all of these resources
```
-
References in latency reference rules have additional syntax to support the allocation of resources from groups and pools:
-
```
latency_resource_ref : resource_ref ':' number (':' IDENT)?
| resource_ref ':' IDENT (':' IDENT)?
@@ -586,75 +483,66 @@ References in latency reference rules have additional syntax to support the allo
| resource_ref ;
```
-
-
#### **Allocating Grouped and Pooled Resources**
Latency references allow you to optionally manage allocation of pooled resources, as well as specifying the significant bits of operands whose values can be shared with other instructions.
A reference of the form:
-
```
- some_resource_pool:1
+ some_resource_pool:1
```
-
indicates that a reference needs one element from a group/pooled resource associated with a latency reference. A reference of the form:
-
```
- some_resource_pool:2
+ some_resource_pool:2
```
indicates that the reference needs 2 (or more) _adjacent_ elements from a pooled resource associated with a latency reference. A reference of the form:
-
```
- some_resource_pool:*
+ some_resource_pool:*
```
-
indicates that a reference needs _all _elements from a resource group or pool. Note that grouped resources can only use :1 and :\*.
A reference of the form:
-
```
-some_resource_pool:size
+ some_resource_pool:size
```
-
indicates an operand reference that requires some number of resources from the resource pool. The number of resources needed is specified in the “size” attribute of the associated operand type. This enables us to decide at compile time how many resources to allocate for an instruction’s operand based on its actual value. For example, large operand constant values may require more resources than small constants, while some operand values may not require any resources. There’s a specific syntax for describing these attributes in derived operand definitions (described earlier).
In the examples above, if the resource has shared bits associated with it (it’s shareable by more than one instruction), the entire contents of the operand are shared. In some cases, only part of the operand’s representation is shared, and we can can specify that with the following reference form:
- `some_resource_pool:size:mask`
+```
+ some_resource_pool:size:mask
+```
This indicates that the associated operand’s “mask” attribute indicates which of the operand bits are sharable. Finally, we can use a share-bits mask without allocation:
- `some_resource_pool::mask`
+```
+ some_resource_pool::mask
+```
This reference utilizes the resource - or an entire pool - and uses the operand’s “mask” attribute to determine which bits are shared with other references.
We will describe how these references work when we describe latency rules.
-
## **Defining a Processor Family**
A TableGen description describes a family of processors, or subtargets, that share instruction and register definitions. Information about instruction behaviors are described with Schedules and Itineraries. The MDL also uses common instruction and register descriptions, scraped from TableGen, and adds first-class descriptions of CPUs, functional units, and pipeline modeling.
In an MDL CPU description, a CPU is described as an explicit set of functional units. Each functional unit is tied to a set of subunits, and subunits are in turn explicitly tied to instruction definitions and pipeline behaviors. There are two approaches for associating subunits with functional units, and the choice of which one to use is dependent on the attributes of the architecture you’re describing:
-
-
1. Subunit templates specify (either directly or through Latencies) which functional units they use, or
2. You define functional unit templates that specify exactly which subunits they use.
More detail on this below.
-
### **Method 1: SuperScalar and Out-Of-Order CPUs**
Fully protected pipelines, forwarding, out-of-order issue and retirement, imprecise micro-operation modeling, and dynamic functional unit allocation make this class of
@@ -669,7 +557,6 @@ The downside of this method is that you can’t specialize functional unit insta
We generally describe this as a “bottoms-up” approach (subunits explicitly tying to functional unit instances), and is the approach used by the Tablegen scraper (tdscan) for “Schedule-based” CPUs.
-
### **Method 2: VLIWs, and everything else**
This method is appropriate for machines where we must provide more information about the detailed behavior of an instruction so that we can correctly model its issuing and pipeline behavior. It is particularly important for machines with deep, complex pipelines that _must_ be modeled by the compiler. It has a powerful, flexible user-defined resource scheme which provides a lot more expressiveness than either “Schedules” or “Itineraries”.
@@ -682,12 +569,9 @@ We describe this as a “tops-down” approach (explicit functional unit templat
assert which subunits they support). This is the method tdscan uses when scraping information about itineraries.
-
### **Schema of a Full Processor Family Description**
- By convention, a description generally describes things in the following order (although the order of these definitions doesn’t matter):
-
-
+By convention, a description generally describes things in the following order (although the order of these definitions doesn’t matter):
* Definition of the family name.
* Describe the pipeline model(s).
@@ -698,7 +582,6 @@ assert which subunits they support). This is the method tdscan uses when scrapi
We will describe each of these items in more detail. A machine description for a target has the following general schema: (a full syntax is provided in Appendix A)
-
```
<family name definition>
<pipeline phase descriptions>
@@ -715,13 +598,13 @@ We will describe each of these items in more detail. A machine description for
cpu gen_2 { … }
…
- // Define Functional Unit Template Definitions (Tops-down approach)
+ // Define Functional Unit Template Definitions (Tops-down approach)
func_unit a_1(<functional unit parameters>) {
- <functional-unit-specific resource and port definitions>
- <subunit instance>
- <subunit instance>
- …
-}
+ <functional-unit-specific resource and port definitions>
+ <subunit instance>
+ <subunit instance>
+ …
+ }
func_unit b_1(…) { … }
…
@@ -750,10 +633,7 @@ We will describe each of these items in more detail. A machine description for
<instruction descriptions>
```
-
-
-#### **Bottoms-up vs Tops-down CPU Definition Schemas \
-**
+#### **Bottoms-up vs Tops-down CPU Definition Schemas**
In the “tops-down” schema, we define CPUs, which instantiate functional units, which instantiate subunits, which instantiate latencies. At each level of instantiation, the object (functional unit, subunit, latency) can be specialized for the context that it’s instantiated in. We think of this as a “top-down” definition of a processor family. We provide detailed descriptions for each functional unit template, which we can specialize for each instance.
@@ -761,14 +641,11 @@ However, for many processors, this specialization is unnecessary, and the normal
In this schema, the MDL compiler _implicitly_ creates functional unit and latency templates:
-
-
* A CPU definition specifies which functional units are used in the normal syntax.
* Subunits directly implement latency rules inline (rather than instantiate a latency template), including an explicit functional unit instance that they can execute on.
Here’s an example of this kind of bottom-up description:
-
```
cpu dual_cpu {
func_unit ALU alu1(); // a "my_alu" functional unit, named "alu1"
@@ -776,32 +653,25 @@ Here’s an example of this kind of bottom-up description:
}
subunit alu2() {{ def(E2, $dst); use(E1, $src); fus(ALU, 3); }}
subunit alu4() {{ def(E4, $dst); use(E1, $src); fus(ALU, 7); }}
+ subunit alu7() {{ def(E7, $dst); use(E1, $src); fus(ALU, 42); }}
```
-
- `subunit alu7() {{ def(E7, $dst); use(E1, $src); fus(ALU, 42); }}`
-
Note that we don’t explicitly define the ALU functional unit template, but it is instantiated (twice) and used in three subunit/latency templates. Similarly, we don’t explicitly define the three latency templates. Both the functional unit template and the latency templates are implicitly created in the MDL compiler.
While this schema is much more compact, neither the functional units nor the subunits/latencies can be specialized. This is an appropriate approach for scalar and superscalar processors, and is used by tdscan for CPUs that use Tablegen Schedules.
-
### **Specifying the Family Name**
A family name must be specified that ties the description to the LLVM name for the processor family. It has the following grammar:
-
```
-family_name : 'family' IDENT ';' ;
+ family_name : 'family' IDENT ';' ;
```
-
-
### **Pipeline Definitions**
We don’t explicitly define instruction “latencies” in the MDL. Instead, we specify when instructions’ reads and writes happen in terms of pipeline phases. From this, we can calculate actual latencies. Rather than specify pipeline phases with numbers, we provide a way of naming pipeline stages, and refer to those stages strictly by name. A pipeline description has the following grammar:
-
```
pipe_def : protection? 'phases' IDENT '{' pipe_phases '}' ';'? ;
protection : 'protected' | 'unprotected' | 'hard' ;
@@ -809,20 +679,16 @@ We don’t explicitly define instruction “latencies” in the MDL. Instead, we
phase_id : '#'? IDENT ('[' range ']')? ('=' number)? ;
```
-
- For example:
-
+For example:
```
-phases my_pipeline { fetch, decode, read1, read2, ex1, ex2, write1, write2 };
+ phases my_pipeline { fetch, decode, read1, read2, ex1, ex2, write1, write2 };
```
-
We typically define these in a global phase namespace, and they are shared between CPU definitions. All globally defined phase names must be unique. However, each CPU definition can have private pipeline definitions, and names defined locally override globally defined names.
You can define more than one pipeline, and each pipeline can have the attribute “protected”, “unprotected”, or “hard”. “Protected” is the default if none is specified.
-
```
protected phases alu { fetch, decode, ex1, ex2 };
unprotected phases vector { vfetch, vdecode, vex1, vex2 };
@@ -838,29 +704,24 @@ A “hard” latency typically describes the behavior of branch and call instruc
You can define multiple stages as a group - the following rule is equivalent to the first example above.
-
- **<code>phases alu { fetch, decode, read[1..2], ex[1..2], write[1..2] };</code></strong> \
-
+```
+ phases alu { fetch, decode, read[1..2], ex[1..2], write[1..2] };
+```
Like C enumerated values, each defined name is implicitly assigned an integer value, starting at zero and increasing sequentially, that represents its integer stage id. You can explicitly assign values to pipeline phases, as in C, with the syntax “`phase=value`”. You can also explicitly assign sequential values to a range, by using the syntax `"name[2..5]=value`”.
Finally, there is specific syntax to annotate the first “execute” phase in a pipeline spec, using the ‘#’ syntax:
-
```
-phases my_pipeline { fetch, decode, #read1, read2, ex1, ex2, write1, write2 };
+ phases my_pipeline { fetch, decode, #read1, read2, ex1, ex2, write1, write2 };
```
-
This indicates that “read1” is the first execute stage in the pipeline, which serves as the “default” phase for any operand that isn’t explicitly described in a latency rule.
-
### **CPU Definitions**
In the definition of a single CPU/subtarget, we specify a high-level description of the processor:
-
-
* CPU-specific resource definitions
* Specification of issue slots and issue-slot usage.
* Specialized instances of available functional units, and/or clusters of functional units.
@@ -870,7 +731,6 @@ Note that a CPU definition does not attempt to describe the pipeline behavior of
Grammar:
-
```
cpu_def : 'cpu' IDENT ('(' STRING (',' STRING)* ')')?
'{' cpu_stmt* '}' ';'? ;
@@ -892,11 +752,11 @@ Grammar:
issue_statement : 'issue' '(' IDENT ')' name_list ';' ;
-func_unit_instantiation : 'func_unit' func_unit_instance func_unit_bases*
- IDENT '(' resource_refs? ')'
+ func_unit_instantiation : 'func_unit' func_unit_instance func_unit_bases*
+ IDENT '(' resource_refs? ')'
('->' (pin_one | pin_any | pin_all))? ';'
-func_unit_instance : IDENT ('<>' | ('<' number '>'))?
+ func_unit_instance : IDENT ('<>' | ('<' number '>'))?
func_unit_bases : ':' func_unit_instance
pin_one : IDENT ;
@@ -904,10 +764,8 @@ func_unit_instance : IDENT ('<>' | ('<' number '>'))?
pin_all : IDENT ('&' IDENT)+ ;
```
-
The overall schema of a CPU definition looks like this:
-
```
cpu gen_1 {
<cpu-specific resource definitions>
@@ -920,15 +778,12 @@ The overall schema of a CPU definition looks like this:
}
```
-
and a cluster definition has the schema:
- `cluster xyz { `
-
-
```
+ cluster xyz {
<cpu-specific resource definitions>
- <cpu-specific issue definitions>
+ <cpu-specific issue definitions>
<functional unit instance>
<functional unit instance>
<optional forwarding info>
@@ -936,33 +791,26 @@ and a cluster definition has the schema:
}
```
-
Below are some examples of increasingly complex CPU definitions.
-
#### **Simple Scalar CPU Definition**
In the simplest case, an empty CPU indicates a processor with no specific functional unit information. We assume a serial execution of instructions, with “default” latencies:
-
```
cpu simplest_cpu { }
```
-
A single-alu CPU that has a scheduling model looks like this:
-
```
cpu simple_cpu {
func_unit my_alu alu(); // a "my_alu" functional unit, named "alu"
}
```
-
A slightly more complex example is a CPU that is single-issue, but has more than one execution pipeline:
-
```
cpu dual_alu_cpu {
issue slot0; // a single issue pipeline
@@ -971,13 +819,10 @@ A slightly more complex example is a CPU that is single-issue, but has more than
}
```
-
-
#### **Multi-Issue CPUs**
Here’s an example of a 2-issue processor with two identical functional units:
-
```
cpu dual_issue_cpu {
func_unit my_alu alu1(); // a "my_alu" functional unit, named "alu1"
@@ -985,26 +830,21 @@ Here’s an example of a 2-issue processor with two identical functional units:
}
```
-
Processors commonly have functional units with different capabilities - memory units, multipliers, floating point units, etc. The following is a four-issue CPU with 4 different types of functional units.
-
```
cpu quad_cpu {
func_unit int_math imath(); // a "int_math" functional unit
func_unit float_math fmath(); // a "float_math" functional unit
- func_unit memory mem(); // a "memory" functional unit
- func_unit branch br(); // a "branch" functional unit
+ func_unit memory mem(); // a "memory" functional unit
+ func_unit branch br(); // a "branch" functional unit
}
```
-
-
#### **Defining Issue Slots**
Multi-issue CPUs always have a constrained set of instructions they can issue in parallel. For superscalar, OOO processors this is generally tied to the number of issue pipelines that are available. For VLIW, issue slots map directly to encoding bits in a parallel instruction. In the MDL, you can explicitly define issue slots. An example:
-
```
cpu tri_cpu {
issue slot0, slot1;
@@ -1014,56 +854,47 @@ Multi-issue CPUs always have a constrained set of instructions they can issue in
}
```
-
In this example, we have 3 functional units, but only two issue slots. So any of the three functional units can issue in either issue slot, but only two can be issued in parallel.
When issue slots are not specified, each functional unit runs in its own dedicated issue slot.
-
#### **Reservation of Issue Slots**
In VLIW architectures (in particular), some functional units may be “pinned” to a specific set of issue slots, or use multiple issue slots in some cases. We provide syntax for specifying this:
-
```
cpu three_issue_quad_cpu {
issue s0, s1, s2;
func_unit int_math alu1() -> s0; // alu1 must issue in s0
func_unit float_math alu2() -> s1 | s2; // alu2 must be in s1 or s2
- func_unit memory alu3() -> s0 & s1; // alu3 uses both s0 and s1
- func_unit branch br(); // branches can run in any slot
+ func_unit memory alu3() -> s0 & s1; // alu3 uses both s0 and s1
+ func_unit branch br(); // branches can run in any slot
}
```
-
-
#### **SuperScalar and Out-Of-Order CPUs**
In general, the overall approach for defining superscalar CPUs is quite different from other CPU types. This class of architecture requires information about the size of the reorder buffer, and details about queues for each functional unit. Actual functional unit utilization is described in latency or subunit rules, which can specify exactly which functional units are used.
Functional units can be unreserved (like alu1, below), which means that an instruction or micro-operation that runs on that unit doesn’t actually use that specific resource. A functional unit can have a single-entry queue - in which case it is unbuffered - or a specific size queue.
-
```
cpu three_issue_superscalar_cpu {
issue s0, s1, s2;
- reorder_buffer<20>; // the reorder buffer is size 20
+ reorder_buffer<20>; // the reorder buffer is size 20
func_unit int_math<> alu1(); // alu1 is unreserved
- func_unit float_math<10> alu2(); // alu2 has 10 queue entries
- func_unit memory<20> alu3(); // alu3 has 20 queue entries
- func_unit branch br(); // branch has a single entry
+ func_unit float_math<10> alu2(); // alu2 has 10 queue entries
+ func_unit memory<20> alu3(); // alu3 has 20 queue entries
+ func_unit branch br(); // branch has a single entry
}
```
-
-
#### **Parameterized/Specialized Functional Unit Instances**
A functional unit template can be parameterized with register classes and resource references so that each instance of that functional unit template can be specialized for a specific context. The actual use of these parameters is specified in the functional unit template, explained in the following sections. This section describes template specialization parameters.
A **register class parameter** asserts that the functional unit instance may impose a register constraint on instructions that execute on it. This constraint is an addition to the register class constraints specified by an instruction’s operand definitions. This enables us to model functional units that are connected to a subset - or a partition - of a register file. It can also be used to describe functional-unit-local register files. Finally, it can disqualify instructions from running on a functional unit if they have register operands or operand constraints that are incompatible with the functional unit constraints.
-
```
register r[0..31];
register_class ALL { r[0..31] };
@@ -1077,10 +908,8 @@ A **register class parameter** asserts that the functional unit instance may imp
instruction add(ALL dst, ALL src1, ALL src2) { … }
```
-
A **resource parameter** indicates that instructions that execute on the functional unit may use that resource or a member of a resource pool. This is generally used to specify how shared resources are used across functional unit instances.
-
```
cpu my_cpu {
resource shared_thing; // a single shared resource
@@ -1097,92 +926,75 @@ A **resource parameter** indicates that instructions that execute on the functio
}
```
-
-
#### **Functional Unit Clusters**
A processor definition can include named “clusters” of functional units. Each cluster can define local resources, and define its own issue rules. The purpose of clusters is primarily as a syntactic convenience for describing processors with functional unit clusters. An example:
-
```
cpu my_cpu {
- cluster A {
- issue a, b;
- func_unit my_alu alu1();
- func_unit my_alu alu2();
- func_unit my_alu alu3();
- }
- cluster B {
- issue a, b;
- func_unit my_alu alu1();
- func_unit my_alu alu2();
- func_unit my_alu alu3();
+ cluster A {
+ issue a, b;
+ func_unit my_alu alu1();
+ func_unit my_alu alu2();
+ func_unit my_alu alu3();
+ }
+ cluster B {
+ issue a, b;
+ func_unit my_alu alu1();
+ func_unit my_alu alu2();
+ func_unit my_alu alu3();
+ }
}
- }
-
-
```
-
This describes a 4-issue machine, where 2 instructions can be issued on each cluster per cycle.
-
#### **Defining Compound Functional Unit Instances**
-Its often convenient to define “compound” functional unit instances as collections that include 2 or more “component” units. A compound unit includes all the capabilities of its component units. Each component can specify its own reservation queue size.
-
+Its often convenient to define “compound” functional unit instances as collections that include 2 or more “component” units. A compound unit includes all the capabilities of its component units. Each component can specify its own reservation queue size.
```
cpu compound_units {
- Issue s0, s1, s2;
- func_unit int_math<5>:load<6> alu1();
- func_unit int_math<5>:store<3> alu2();
- func_unit float_math<20>:branch<2> alu3();
- func_unit misc<30> alu4();
+ Issue s0, s1, s2;
+ func_unit int_math<5>:load<6> alu1();
+ func_unit int_math<5>:store<3> alu2();
+ func_unit float_math<20>:branch<2> alu3();
+ func_unit misc<30> alu4();
}
```
-
This construct is similar to the “super-unit” concept in tablegen. Only one component of a compound functional unit can be used per cycle. In the above example, “alu3” is the only unit that supports floating point math or branches. Consequently those operations can’t be issued in parallel. Similarly, you can issue two integer math operations in parallel, but only if you’re not also issuing a load or store.
Currently, we don’t support specialization parameters on compound functional unit instances. However, you can define functional unit templates with base units, and this provides similar capability.
-
#### **Associating a CPU definition with an LLVM subtarget**
A cpu definition can be directly associated with one or more LLVM subtargets, for example:
-
```
cpu SiFive7 ("sifive-7-series", "sifive-e76", "sifive-s76", "sifive-u74") { …
```
-
At compile time, we can select which CPU definition to use based on normal target-selection command-line options.
-
#### **Modeling Forwarding**
Forwarding is modeled by describing a forwarding network between functional units. The necessity of the concept of a “forwarding” network implies that such networks aren’t fully connected or uniform.
Grammar:
-
```
-forward_stmt : 'forward' IDENT '->'
+ forward_stmt : 'forward' IDENT '->'
forward_to_unit (',' forward_to_unit)* ';' ;
-forward_to_unit : IDENT ('(' snumber ')')? ;
+ forward_to_unit : IDENT ('(' snumber ')')? ;
```
-
Example:
-
```
- forward my_alu -> my_adder(1), my_load(2);
+ forward my_alu -> my_adder(1), my_load(2);
```
-
In a forwarding specification, a unit name can be a functional unit instance name, a functional unit group name, or a functional unit template name. When using template or group names, all members of the group, or all instances of the specified template type, are implicitly referenced.
For many processors, late functional unit assignment creates a phase-ordering problem in the compiler. Similarly, runtime functional unit assignment implies that we can’t necessarily know if a value will be forwarded or not. Unless we know with certainty the functional unit assignments for two instructions, we can’t always tell if there is a forwarding path between the two instructions.
@@ -1205,7 +1017,6 @@ In short, there are architectural cases that cannot be modeled precisely, and th
Note: there is a philosophical question of whether we should provide best case or worst case latencies when the forwarding cannot be statically predicted. Generally, we believe that worst case latencies are better than best case latencies, simply because too-short latencies can produce code which occasionally (or always) stalls. On the other hand, overestimating the latency produces schedules where a pair of dependent instructions _tend _to be scheduled far enough apart to avoid stalls. In effect, schedulers will separate instructions by the requested latency only when there’s other useful work to do. Otherwise, there’s no reason to separate them - the stall is inevitable.
-
### **Functional Unit Template Definitions**
A functional unit template describes, abstractly, what operations can be performed on any instance of the unit, and how those operations use the template parameters - register classes and resource references. An abstract set of operations is represented by a subunit instance, which represents a set of instructions with similar behavior in terms of functional unit usage, resource usage, and register classes. Functional unit templates are defined in their own private namespace.
@@ -1216,7 +1027,6 @@ For superscalar processors, it's not necessary to specify explicit templates for
A functional unit template has the following grammar:
-
```
func_unit_template : 'func_unit' IDENT base_list
'(' func_unit_params? ')'
@@ -1243,42 +1053,33 @@ A functional unit template has the following grammar:
subunit_instance : IDENT '(' resource_refs? ')' ;
```
-
-The general schema of a functional unit template looks like this: \
-
-
+The general schema of a functional unit template looks like this:
```
func_unit a_1 [: <base_units>] (<functional unit parameters>) {
<functional-unit-specific resource and port definitions>
<subunit instance>
- <subunit instance>
- …
-}
+ <subunit instance>
+ …
+ }
```
-
-
#### **Simplest Functional Unit Template Definition**
The simplest example of a functional unit template would define a functional unit that has no parameters, and implements a single subunit:
-
```
func_unit simple() {
- subunit xyzzy();
+ subunit xyzzy();
}
```
-
In this case, any instruction that is defined to use the subunit “xyzzy” can run on this functional unit. This template doesn’t impose any additional constraints on those instructions, and no shared resources are used.
-
#### **Defining Functional Unit Resources**
A functional unit template can locally define resources which represent hardware resources tied to _each instance_ of the functional unit. These can be used to specialize subunit instances:
-
```
func_unit unit_with_local_resources() {
resource my_resource;
@@ -1290,79 +1091,63 @@ A functional unit template can locally define resources which represent hardware
}
```
-
In this example, the functional unit supports 3 classes of instructions (add, subtract, multiply), and passes slightly different local resources to each. Each instance of this functional unit has an independent set of resources (my\_resource, my\_pooled\_resource).
Importantly: functional-unit-local resources which are used for multiple cycles can be used to model non-pipelined functional units - i.e.units which are reserved for some number of cycles.
-
#### **Defining “Port” Resources**
A port is a resource type that explicitly binds a named register class with a resource reference. A port is used to specialize subunit instances, and adding functional-unit-specific register constraints on instructions associated with the subunit.
A port definition has the general form:
-
```
'port' <port_name> ('<' <register_class_name> '>')? ('(' resource_ref ')')? ;
```
-
When a port is tied to more than one resource, any references to that port refer to all of the associated resources. Some examples:
-
```
port port_a <GPR>; // port_a tied to GPR regs
port port_b <LOW> (res1); // port_b tied to LOW regs and res1
port port_c (pool[0..4]); // port_c tied to pool[0..4]
```
-
You can also use a “connect” statement to tie a port to register classes and resources:
-
```
'connect' <port_name> 'to' <register_class_name> 'via' resource_ref ;
```
-
The following is equivalent to the above definition of “port\_b”:
-
```
port port_b;
connect port_b to LOW via res1;
```
-
This syntax could potentially be used to connect a port to more than one constraint/resource set, but this capability isn’t currently supported, and this syntax may be deprecated.
Ports can be used to specialize subunit and latency instances, described in subsequent sections.
-
#### **Using Template Parameters**
Resource parameters can be used exactly like locally defined resources to specialize subunit instances. Register class parameters are used to define ports. Resource parameters can refer to a single resource, a pool of resources, or a group of resources.
Here is an example subunit instance:
-
```
subunit adder(res, porta, res2, portc);
```
-
The parameters refer to resources (or ports) defined in the functional unit, cluster, cpu, or globally. The resource parameters themselves can include constrained versions of the resources they refer to, in particular specifying a particular member or a subset of a pooled resource, for example:
-
```
subunit load(pool1.member, pool2[5], pool3[2..4]);
```
-
A simple example of a full functional unit template definition:
-
```
func_unit specialized(resource shared_pool; class regs) {
resource my_resource;
@@ -1373,13 +1158,10 @@ A simple example of a full functional unit template definition:
}
```
-
-
#### **Conditional Subunit Instances**
In a functional unit template, a subunit instance can be conditionally instantiated based on a predicate. Predicates are simply names of the instantiating cpu definition and functional unit instance. This allows us to specialize a functional unit instance based on how its instantiated, for example:
-
```
cpu my_cpu {
func_unit my_func xyzzy();
@@ -1392,60 +1174,45 @@ In a functional unit template, a subunit instance can be conditionally instantia
}
```
-
-
#### **Using Base Functional Units**
Functional units tend to get more capable over generations of a processor, so we’d like a way to derive functional units from other functional units. A functional unit template can be defined to have a base functional unit, for example:
-
```
func_unit base_func() { … }
func_unit my_func : base_func() { … }
```
-
In this example, the template “my\_func” simply includes the definition of “base\_func” in its definition. In effect, anything “base\_func” can do, “my\_func” can do. The base functional unit definition must have the same leading parameters as the derived functional unit definition.
In effect, when you instantiate a based functional unit, you implicitly instantiate its bases and any subbases. This language feature allows us to easily extend functional unit definitions over processor generations.
-
#### **Defining functional unit groups**
When defining a superscalar CPU, its generally not necessary to provide a functional unit template definition for each functional unit, since latency rules specify which functional units are used by a subunit. In this case, its helpful to be able to easily specify an arbitrary pool of functional units that can be used for an instruction. So the MDL has a way to do that.
-
```
func_unit_group : 'func_group' IDENT ('<' number '>')? : name_list ;
```
-
For example:
-
```
func_group MyGroup<42> member1, member2, member3;
```
-
This defines a functional unit group with 3 members, and a single input queue of length 42. These groups are used in latency rules to tie subunits to a pool of functional units.
-
### **Subunit Template Definitions**
Subunits are used to link sets of instruction definitions to their pipeline behaviors and candidate functional units. Subunits appear in three contexts:
-
-
* Each subunit template has a definition.
* Functional unit templates instantiate subunits that they support.
-* Instructions can declare which subunits they are associated with. \
-
+* Instructions can declare which subunits they are associated with.
A subunit definition abstractly represents a set of instruction definitions that logically have the same behaviors:
-
-
* When operands are read and written
* What resources are used/held/reserved
* What functional units they can issue on
@@ -1456,7 +1223,6 @@ An instruction - or set of instructions - may behave differently between subtarg
A subunit template definition has the following grammar:
-
```
subunit_template : 'subunit' IDENT su_base_list
'(' su_decl_items? ')'
@@ -1473,10 +1239,8 @@ A subunit template definition has the following grammar:
latency_statement : 'latency' IDENT '(' resource_refs? ')' ';' ;
```
-
A subunit template has the following general schema:
-
```
subunit add <base subunits> (<subunit parameters>) {
<latency instance>
@@ -1485,26 +1249,21 @@ A subunit template has the following general schema:
}
```
-
Latency instance instances (in subunit templates) have the following general forms:
-
```
latency <latency_name> ( <subunit parameters> );
<predicate> : latency <latency_name> ( <latency parameters> );
<predicate> : { <latency statements> }
```
-
The optional predicate is a comma-separated list of names which refers to the CPU or functional unit the current subunit is instantiated in. This allows subunits to specify different latencies depending on the CPU or functional unit they are instantiated from. This is similar to the support in functional unit templates for conditional subunit instances. For example:
-
```
cpu1, cpu3 : latency xyzzy(port1, port2, etc);
alu7: latency plugh(resource1, resource2, etc);
```
-
A subunit template can specify as many latency instances as needed - the resulting subunit is the union of all the valid latency templates. This allows you to separate different classes of behaviors into different latency templates. Since latency templates are also specialized, you can manage the separation in latencies. The typical practice is for a subunit to have a single latency instance.
@@ -1512,33 +1271,25 @@ A subunit template can specify as many latency instances as needed - the resulti
Subunit template parameters can be a mix of ports and resources, and are used to specialize a subunit for the context in which it is instantiated, for example:
-
```
subunit add (resource A, B; port C) { … }
```
-
In general, these work exactly the same way functional unit templates are used. They can be used as latency parameters to specialize latency instances.
-
#### Tying Instructions to Subunits
There are two ways to associate subunits to instructions:
-
-
* Instructions can specify which subunits they can run on, or
* Subunits can specify which instructions they support.
We discuss these two approaches below.
-
##### Subunits in Instructions
Subunits are associated with instruction definitions to...
-
-
* Define each of their possible pipeline behaviors
* Determine which functional units they can be issued on (if any!)
* To provide functional-unit-specific register constraints to operand registers
@@ -1548,46 +1299,37 @@ Each defined instruction must specify at least one subunit that it is bound to.
We allow more than one subunit per instruction, which implies different instruction behaviors across CPUs or functional units. In general, this isn’t necessary, since a subunit can specify different behaviors for different functional units and/or CPUs. So this is strictly a stylistic choice.
-
##### Subunit Bases
A subunit template definition can have one or more “bases”. A base is either the name of another subunit, or a string representing a regular expression of instruction names. Bases tie a subunit to sets of instructions, either directly by instruction name, or transitively through their base subunits. A subunit does not need to have the same parameters as its bases, and does not inherit any latency information from its bases.
This example ties the “add” subunit to any instruction with “ADD” as a name prefix, and also to any instructions tied to the “base\_add” subunit.
-
```
subunit add : "ADD*" : base_add() {...}
```
-
Subunit bases provide an alternate way of tying instructions to subunits without modifying the instruction definitions (where each instruction can tie itself to a set of subunits). This effectively allows a single “base” subunit - and all of its associated instructions - to have different latency behaviors for each target.
-
#### Shorthand Subunit Template Definitions
Often a subunit template simply specifies a single latency template instance, and the latency template may only be used in a single subunit template. In that case, we have a shorthand that combines the latency template into the subunit template. For example:
-
```
-subunit load(resource a, b, c) {
+ subunit load(resource a, b, c) {
latency load(resource a, b, c);
-}
-latency load(resource a, b, c) { def(E1, $dst); use(E1, $src); … }
+ }
+ latency load(resource a, b, c) { def(E1, $dst); use(E1, $src); … }
```
-
Can be alternatively expressed as:
-
```
-subunit load(resource a, b, c) {{
+ subunit load(resource a, b, c) {{
def(E1, $dst); use(E1, $src); …
-}}
+ }}
```
-
-
### **Latency Template Definitions**
A latency template specifies the detailed pipeline behavior for a class of instructions. The class of “client” instructions for a latency template is the set of instructions that use any subunit that instantiates the latency template.
@@ -1596,28 +1338,23 @@ Latency templates are specialized for the exact context they are instantiated in
Latency templates:
-
-
* describe what happens at each stage of the execution pipeline in terms of register operands and resources used and reserved.
* optionally imposes additional functional-unit-specific constraints on register operands.
A latency template definition has the following general schema:
-
```
latency <name> : base_latencies ( <parameters> ) {
- <latency reference>
- <latency reference>
+ <latency reference>
+ <latency reference>
…
}
```
-
Latency templates can be derived from other latencies, and take resources or ports as parameters. The body of the template is simply a set of latency references.
The full grammar:
-
```
latency_template : 'latency' IDENT base_list
'(' su_decl_items? ')'
@@ -1671,45 +1408,35 @@ The full grammar:
operand_ref : (IDENT | number) ;
```
-
-
#### **Derived Latency Templates**
A latency template can be derived from one or more base latency templates. Any hierarchy is allowed (except recursive), as long as the base template has the exact same leading parameters as the derived latency. A base latency can be included more than once in the hierarchy - this doesn’t matter, since all occurrences of that base are identical (so duplicates are ignored):
-
```
- latency base1 (resource a) { … }
- latency base2 (resource a, b) { … }
- latency base3 : base1 (resource a) { … }
- latency my_latency : base2 : base3(resource a, b, c) { … }
+ latency base1 (resource a) { … }
+ latency base2 (resource a, b) { … }
+ latency base3 : base1 (resource a) { … }
+ latency my_latency : base2 : base3(resource a, b, c) { … }
```
-
In this example, my\_latency includes base1, base2, and base3. Deriving latency templates is a fairly common pattern: instruction classes often share _some_ behaviors, but not all. So those shared behaviors can be put in a base latency template. A common example is an instruction predicate, perhaps shared by all instructions.
-
#### **Latency References**
A latency reference statement describes a single operand reference and/or resource references in a specified pipeline stage. It references instruction operands _by name, _as well as resource and port parameters, and ties the operations to named pipeline phases.
Latency references have the following general form:
-
```
-<operator> (<phase expression>, <operand specifier>, <ports/resources>);
+ <operator> (<phase expression>, <operand specifier>, <ports/resources>);
```
-
where either the operand specifier or ports/resources may be omitted. A single reference statement asserts that an operand and resources are referenced in a specific pipeline phase for any instruction that this rule could apply to, ie: _any instruction that uses a subunit that instantiates this latency template._ Each aspect of a latency reference are described below.
-
##### **Operand and resource latency operators:**
There are 6 basic operator types in a latency reference:
-
-
* use - read a register, and/or use a resource
* def - write a register, and optional use of a resource
* predicate - specifies which register operand is an instruction predicate
@@ -1719,42 +1446,33 @@ There are 6 basic operator types in a latency reference:
There are 3 additional operator types which are primarily used as shortcuts (these are currently parsed, but unimplemented in the llvm integration):
-
-
* usedef - a use and a def of an operand (a shorthand syntax)
* kill - the register value is wiped and no value is defined (typically used in call instructions)
* or - this is essentially a conditional def, but the instruction has no explicit predicate (useful for status-setting instructions).
-
##### **Phase Expressions**
The phase expression specifies the pipeline phase that the operation occurs in. The expression can refer directly to a defined phase name, or an expression based on a phase name:
-
```
- use(E7, $operand, res); // use operand and res in cycle E7
- use(E7+5, $operand, res); // use operand and res in cycle E7+5
+ use(E7, $operand, res); // use operand and res in cycle E7
+ use(E7+5, $operand, res); // use operand and res in cycle E7+5
```
-
An instruction may perform a reference at a cycle which is a function of immediate operands of the instruction instance. For example:
-
```
- use(E1 + $width - 12, $operand, res);
+ use(E1 + $width - 12, $operand, res);
```
-
where “$width” is an immediate instruction operand. Its value is fetched from the instruction instance and used in the expression. As with any operand specifier, if the client instruction doesn’t have an immediate operand named “width”, the rule is ignored for that instruction.
Phase expressions have a limited set of operators: +, -, \*, /, (). Since latencies must be positive integers, we also provide a “floor” operator which converts negative expressions to 0. Simply enclose the expression in curly braces ({...}).
-
##### **Operand Specifiers**
The operand specifier has the same grammar as in tablegen, which allows you to specify an optional operand type, the operand name, and optional sub-operand names:
-
```
operand : (IDENT ':')? '$' IDENT ('.' operand_ref)*
| (IDENT':')? '$' number
@@ -1763,46 +1481,33 @@ The operand specifier has the same grammar as in tablegen, which allows you to s
operand_ref : (IDENT | number) ;
```
-
Operand specifiers act as predicates for the validity of a reference for a particular instruction. Some examples:
-
```
GPR:$dst // an operand named "dst" with operand type GPR
ADR:$dst // an operand named "dst" with operand type ADR
$dst // an operand named "dst", with any operand type
+ opnd:$src.reg // an operand named "src", type "opnd", suboperand "reg"
```
-
-
- `opnd:$src.reg // an operand named "src", type "opnd", suboperand "reg"`
-
Because a latency could be specialized for many instructions which have different sets of operands, the operand specifier acts as a predicate for the application of a reference to a particular instruction. When the operand isn’t present in a client instruction, the latency reference is ignored for that instruction. For example, you can differentiate on operand type:
-
```
- def(E5, GPR:$dst);
- def(E7, FPR:$dst);
+ def(E5, GPR:$dst);
+ def(E7, FPR:$dst);
```
-
In this example, instructions with a GPR dst operand write their results in cycle E5, while instructions with an FPR dst operand write their results in cycle E7.
Or you can differentiate based on the operand name:
-
```
use(E2, $src1); // most instructions have at least one src opnd
use(E3, $src2); // some instructions have 2 source operands
+ use(E4, $src3); // and some instructions have 3!
```
-
-
- `use(E4, $src3); // and some instructions have 3!` \
-
-
-Note that operands _can _be referenced by their index in an instruction’s operand list, but this is error-prone and this isn’t considered best practice because we can’t thoroughly check the validity of the index. The syntax is simply “$<index>”. Note that sub-operands often aren’t given names in tablegen, and must be referenced by index, for example: $src.1. Unnamed variant operands (obviously) don’t have names, and are referenced by their position past the end of the operands defined for an instruction, ie “$$1”, “$$2”, etc.
-
+Note that operands _can _be referenced by their index in an instruction’s operand list, but this is error-prone and this isn’t considered best practice because we can’t thoroughly check the validity of the index. The syntax is simply `$<index>`. Note that sub-operands often aren’t given names in tablegen, and must be referenced by index, for example: `$src.1`. Unnamed variant operands (obviously) don’t have names, and are referenced by their position past the end of the operands defined for an instruction, ie `$$1`, `$$2`, etc.
##### **Resource References**
@@ -1810,43 +1515,34 @@ Any latency reference can include an optional set of resource references. These
For “use”, “def”, and “predicate” statements, a set of resource references can be specified that are associated with the operand reference. As with all latency references, the operand must match an operand of the client instruction. If the reference is valid, the resource is “used” - for any of these operators - at the pipeline phase specified, unless the resource was defined with a specific phase. The “use” of the resource is equivalent to a single-cycle hold/reserve of that resource. Some examples:
-
```
- use(E1, $src, my_res); // use "my_res" at cycle E1
- def(E32, $dst, my_res); // use "my_res" at cycle E32
+ use(E1, $src, my_res); // use "my_res" at cycle E1
+ def(E32, $dst, my_res); // use "my_res" at cycle E32
```
-
-For “hold” and “reserve” operations, the operand specifier is optional, and if present serves _only _as a predicate that indicates whether the reference is valid or not. However, at least one resource reference is required for these statements. A few examples:
-
+For “hold” and “reserve” operations, the operand specifier is optional, and if present serves _only_ as a predicate that indicates whether the reference is valid or not. However, at least one resource reference is required for these statements. A few examples:
```
- hold(E1, my_res); // hold issue at E1 until resources are available
- res(E32, $dst, my_res); // reserve resources up to cycle E32
+ hold(E1, my_res); // hold issue at E1 until resources are available
+ res(E32, $dst, my_res); // reserve resources up to cycle E32
```
-
-
#### **Conditional References**
Any reference in a latency rule can be conditional, using a predicate identifier. The predicates are generally identical to LLVM predicates, and check an attribute of a client instruction.
Conditional references can be nested, for arbitrarily complex references. These have the following general form:
-
```
if <predicate_name> { <set of refs> }
else if <predicate_name> { <set of refs> }
else { <set of refs> }
```
-
-
#### **Functional Unit and Micro-op References**
A latency rule can directly specify a set of functional units and how long they are used, as well as specifying the number of micro-ops required for the operation. Each functional unit can optionally specify a pipeline “StartAt” cycle, which by default is the first execution phase.
-
```
fus(13); // Instruction has 13 micro-operations.
fus(ALU, 2); // use ALU for 1 cycle, 2 micro-operations.
@@ -1855,10 +1551,8 @@ A latency rule can directly specify a set of functional units and how long they
fus(ALU1<12>&ALU2<E12:30>&LOAD<E42:2>); // use ALU1, ALU2, and LOAD
```
-
These statements allow a latency rule (or subunit) to tie a set of instructions to functional unit instances. When there is more than one instance of the specified unit, or if the unit is declared to be a functional unit group, at compile time _one_ of those units is selected. Likewise, if the unit is a subunit of one or more functional units, one of the “parent” functional units is selected.
-
## **Machine Description Compiler Artifacts**
What does all of this produce?
@@ -1867,8 +1561,6 @@ The primary artifact of the MDL compiler is a set of data that we associate with
Each of these objects describe the behavior of each instruction cycle by cycle:
-
-
* What operand’s registers it reads and write,
* What register constraints are applied to operands,
* What resources it uses, holds on, or reserves.
@@ -1881,8 +1573,6 @@ As part of this effort, we will incrementally modify the LLVM compiler to altern
-
-
## **Using the MDL Language in LLVM**
The proposed use case for the MDL language is as an alternative specification for the architecture description currently embodied in TableGen Schedules and Itineraries, particularly for architectures for which Schedules and Itineraries are not expressive enough. It is explicitly _not_ the intent that it “replace TableGen”. But we believe that the MDL language is a better language (vs Schedules and Itineraries) for a large class of accelerators, and can be used effectively alongside TableGen.
@@ -1891,16 +1581,12 @@ We’ve written a tool (TdScan) which extracts enough information from TableGen
So there are several possible MDL usage scenarios:
-
-
* _Current: _Given a complete tablegen description with schedules or itineraries, scrape the architecture information and create an MDL description of the architecture every time you build the compiler.
* _Transitional: _Scrape an existing tablegen description and keep the generated MDL file, using it as the architecture description going forward.
* _Future (potentially): _when writing a compiler for a new architecture, write an MDL description rather than schedules and/or itineraries.
The general development flow of using an MDL description in LLVM looks like this:
-
-
1. Write an architecture description (or scrape one from an existing tablegen description).
1. Instructions, operands, register descriptions in .td files
2. Microarchitecture description in .mdl files
@@ -1909,23 +1595,18 @@ The general development flow of using an MDL description in LLVM looks like this
4. Compile the top-level MDL file (which includes the scraped Tablegen information). This produces C++ code for inclusion in llvm.
5. Build LLVM.
-
-
-
### **TdScan**
To synchronize an MDL architecture description with llvm TableGen descriptions, we’ve written a tool which scrapes information that the MDL compiler needs from Tablegen files. In the general case, it collects basic information about registers, register classes, operands, and instruction definitions, and it produces an “mdl” file which can be processed by the MDL compiler to sync an architecture description to the tablegen descriptions of instructions.
For currently upstreamed targets that use Schedules or Itineraries, TdScan can also extract the whole architecture specification from the tablegen files, and produce an MDL description of the architecture. We’ve used this approach to prove out our llvm integration with upstreamed targets. The integration and testing of this is ongoing.
-
### **Upstream Targets**
In general, upstream targets have no compelling need for MDL descriptions - the existing Schedules and/or Itinerary descriptions are field tested. However, there are a few benefits to using an MDL description for existing targets. The primary benefit is that the MDL descriptions are typically quite a bit smaller, succinct, and (we believe) intuitive than the equivalent TableGen descriptions.
-
<table>
<tr>
<td><strong>CPU</strong>
@@ -2028,13 +1709,10 @@ In general, upstream targets have no compelling need for MDL descriptions - the
\*\* Note: the MDL numbers are generated both with and without “index-based” references in subunit/latency rules, vs symbolic references. These are typically 10-20% less lines of MDL description than when operand names are used, almost entirely due to operand name differences between instruction definitions (like “dest” vs “dst”, or “src1” vs “s1”). However, the databases produced by the two approaches are virtually identical - albeit ordered differently.
-
### **Syncing Instruction Information**
The MDL compiler needs 3 pieces of information from tablegen for each machine instruction:
-
-
1. The instruction opcode name
2. Each operand’s name, type, and order of appearance in an instruction instance
3. The name(s) of the subunit(s) it can run on.
@@ -2043,13 +1721,10 @@ Subunits are a new concept introduced with the MDL. The normal approach is to m
As part of the build process, we use a program (“tdscan”) which scrapes the instruction information - including the subunit information from a target’s tablegen files and generates information about the target’s instructions. Tdscan allows us to stay in sync with changes to instruction definitions.
-
### **Using the generated microarchitecture information in LLVM**
There are two classes of services that the MDL database and associated APIs provide:
-
-
* Detailed pipeline modeling for instructions (for all processors, for all functional units) including instruction latencies calculations and resource usage (hazard management)
* Parallel instruction bundling and instruction scheduling.
@@ -2059,8 +1734,6 @@ We can also extract high-level architecture information and generate correct MDL
We provide code and libraries to do the following things - in machine-independent ways:
-
-
* Calculate accurate instruction latencies.
* A set of APIs to build and manage instruction bundles (parallel instructions), performing all the required legality checks and resource allocation based on information in the generated database.
* Manage resource reservations and hazard management for an instruction scheduler.
@@ -2071,24 +1744,17 @@ We provide code and libraries to do the following things - in machine-independen
There’s more we can do here, and a deeper integration with upstreamed LLVM is a long-term goal.
-
### **Current Status of the LLVM Integration (briefly)**
-
-
* We can generate MDL full architecture specs for all upstreamed targets, and properly represent and use all metadata associated with Schedules and Itineraries.
* We’ve integrated the MDL methodology into LLVM’s build flow, so that you can select whether or not to include it at build time.
* The MDL database is (optionally, under command line control) used to properly calculate instruction latencies for all architectures. Caveat: we don’t yet fully convert Itinerary and Schedule forwarding information, since the LLVM model for forwarding is fundamentally different from the MDL model, and the provided information is typically incomplete.
* We’ve integrated the MDL-based bundle-packing and hazard management into all the LLVM schedulers, with the exception of the Swing scheduler, which is still in progress.
* We’ve run all the standard tests, passing all but 190 (out of 93007 tests), with any performance deltas in the noise.
-
-
-
## **Appendix A: Full Language Grammar**
-This may be slightly out of date. The definitive Antlr4-based grammar is in llvm/utils/MdlCompiler/mdl.g4.
-
+This may be slightly out of date. The definitive Antlr4-based grammar is in [llvm/utils/MdlCompiler/mdl.g4](https://github.com/llvm/llvm-project/tree/main/llvm/utils/MdlCompiler/mdl.g4).
```
architecture_spec : architecture_item+ EOF ;
@@ -2443,14 +2109,12 @@ DMA system descriptions
Multi-Processor System Topology
-
## **Appendix C: RISC-V Generated Architecture Description**
This is a complete, automatically generated machine description for RISC-V using our tool to scrape information from tablegen files. We can automatically generate MDL specifications for all targets that have schedules and/or itineraries. We include RISC-V here for illustrative purposes.
The “Schedule” td files for RISC-V are approximately 3231 lines of tablegen, describing three full schedule models and one “default” model. The generated MDL file is ~374 lines of MDL.
-
```
//---------------------------------------------------------------------
// This file is autogenerated from an LLVM Target Description File.
More information about the llvm-commits
mailing list