@@ -506,6 +506,72 @@ potential by introducing lower-level IR ops and *smaller* Linalg ops.
506506This gradually reduces the potential, all the way to Loops + VectorOps
507507and LLVMIR.
508508
509+ ### Interchangeability of Forms<a  name =" forms " ></a >  
510+ 
511+ #### The Linalg Forms  
512+ 
513+ The core Linalg operation set has four forms:
514+ *  ** Generic:**  Represented by ` linalg.generic `  and can encode all perfectly-nested
515+ loop operations.
516+ *  ** Category:**  For example, ` linalg.contract `  and ` linalg.elementwise ` , that encode
517+ higher-level semantics of a ` linalg.generic `  while still representing multiple _ named_ 
518+ operations via attributes and syntax. In the future, other category operations are
519+ planned (e.g.: ` linalg.convolution `  and ` linalg.pooling ` ).
520+ *  ** Named:**  For example, ` linalg.matmul ` , ` linalg.add ` , etc. All _ named_  forms that
521+ can be converted to either a single _ category_  or _ generic_  forms, ie. are _ perfectly nested_ .
522+ *  ** Composite:**  For example ` linalg.softmax `  and the ` winograd `  variations. These
523+ operations are not perfectly nested, and are converted to a list of other operations
524+ (of various dialects).
525+ 
526+ The forms correlate in the following manner:
527+ ``` 
528+ + generic 
529+  \__ + category 
530+       \__ + named 
531+ + composite 
532+ ``` 
533+ 
534+ The ` category `  and ` named `  forms are derived from ` linalg.generic `  and are * equivalent* .
535+ It should always be possible to convert a ` named `  operation into a ` category `  and that
536+ into a ` generic `  and back to ` named ` . However, it may not be possible to convert a
537+ ` generic `  into a ` named `  if there is no such ` named `  form.
538+ 
539+ ` Composite `  operations cannot be converted to the other three classes and forms a
540+ sub-set on its own. But they can use other Linalg forms when expanding. There can be
541+ a pattern-matching transform to detect a graph of operations and convert into a
542+ ` composite `  operation.
543+ 
544+ The various forms in the Linalg dialect are meant to facilitate
545+ pattern matching (single operations or DAGs) and to be able to consider
546+ different forms as * canonical*  for different transforms.
547+ 
548+ Linalg's various forms also carry information, and that
549+ information should be preserved as much as possible during the progressive
550+ lowering. A ` matmul `  operation is a special case of a ` contract `  operation,
551+ which in turn is a special case of a ` generic `  operation. Transformations on
552+ Linalg operations (in any form) should avoid breaking down into
553+ loops + arithmetic if they can still be represented as a Linalg operation,
554+ preferably in their original form.
555+ 
556+ #### Canonical Forms<a  name =" canonical_forms " ></a >  
557+ 
558+ With multiple (often exchangeable) forms, and with transformation simplicity
559+ in mind, compilers should aim for reducing matching and replacing complexity
560+ as much as possible. When matching a single operation with a complex pattern,
561+ having all the information in a ` generic `  Op is useful to iteratively match
562+ different patterns in turn. However, when assembling a DAG of operations to
563+ form a pattern, it's much simpler to match against named operations (like
564+ ` max `  + ` div `  + ` reduce `  + ` broadcast ` ) than their generic counterparts.
565+ 
566+ This is where the interchangeability of forms comes in handy. Linalg has the
567+ ability to specialize and generalize in order to convert the IR to a form that
568+ is easier for a particular type of transform. With forms being semantically
569+ equivalent, one can convert back-and-forth throughout the various transforms
570+ to match the needs of each transform. For that particular transform, such
571+ form can be considered _ canonical_  and therefore "expected" for the pattern
572+ to _ match_ . This reduces complexity of pattern matchers and simplifies compiler
573+ pipelines.
574+ 
509575### Composable and Declarative Transformations<a  name =" declarative_transformations " ></a >  
510576Complex and impactful transformations need not be hard to manipulate, write or
511577maintain. Mixing XLA-style high-level op semantics knowledge with generic
0 commit comments