This web page catalogs ASCII diagrams extracted from four open source code-bases: Chromium, Linux, LLVM, and TensorFlow. There are 2156 diagrams in total, of which 504 have been annotated with our design framework.
For information on how the dataset was collected and on the design framework, please refer to the paper.
A summary of the design framework and its dimensions is presented below, clicking on any of the tags will filter diagrams that contain the tag.
Visual Encoding
Connection
Linear
Tree
Graph
Directed
Undirected
Geometry
Table
Nested
Sequential
Single
Aligned
Math Notation
Code Annotation
Pictorial
Annotation
Point
Multi-Point
Range
Legend
Abstraction
Unpatterned Elision
Fragment Of Bigger Thing
Patterned Elision
Enumerative
Multiples
Multiple Representations
Multiple Scenarios
Over Time
Scope
File
Class
Multiple Functions
Function
Multiple Statements
Statement
References
Identifiers
Constants
Expressions
Concept
Hardware
Data
Data Format
Bit Interpretation
Data Structure
Memory Layout
Resource Management
Memory
Geometry / Graphics
User Interface Sketch
Algorithm / Data Processing
Math Formulas / Calculation
Test Case
Synchronization
Threads
Hardware Signal Timing
Queuing / Scheduling
Layout / Architecture
Actor Interactions
Class Diagrams
Information Flow / Instructions
Conditional Control Flow
State Machines
Data Flow
Programs
The dataset can be downloaded here.
// WebView metrics set up happens like so:
//
// startup
// │
// ├────────────┐
// │ ▼
// │ query GMS for consent
// ▼ │
// Initialize() │
// │ ▼
// │ SetHaveMetricsConsent()
// │ │
// │ ┌──────────┘
// ▼ ▼
// MaybeStartMetrics()
// │
// ▼
// MetricsService::Start()
//
// All the named functions in this diagram happen on the UI thread. Querying GMS
// happens in the background, and the result is posted back to the UI thread, to
// SetHaveMetricsConsent(). Querying GMS is slow, so SetHaveMetricsConsent()
// typically happens after Initialize(), but it may happen before.
// It is easy to visualize the trie edges as hostname components of a url in
// reverse order. For example an allowlist of google.com will have a tree
// tree structure as below.
// root
// | com
// Node1
// google/ \ example
// Node2 Node3
//
// Normally, a search in the tree should end in a leaf node for a positive
// match. For example in the tree above com.google and com.example are matches.
// However, the allowlisting also allows matching subdomains if there is a
// leading dot, for example, see ."google.com" and a.google.com below:
// root
// | com
// Node1
// | google
// Node2
// | a
// Node3
// Here, both Node2 and Node3 are valid terminal nodes to terminate a match.
// The boolean is_terminal indicates whether a node can successfully terminate
// a search (aka. whether this rule was entered to the allowlist) and
// match_prefix indicate if this should match exactly, or just do a prefix
// match.
// The service that runs in ARC and allows the browser to invoke the TWA payment
// app that is installed in ARC, if it implements payment intents as described
// in https://web.dev/android-payment-apps-overview/. At first, only
// "https://play.google.com/billing" payment method is supported.
//
// -------------------- --------------------------------------------------
// | Browser | | ARC |
// | | | |
// | --------------- | | -------------- ------- ---------------- |
// | | Web Payment |<-|------|->| PaymentApp |<-->| TWA |<-->| Play Billing | |
// | --------------- | | -------------- ------- ---------------- |
// | | | |
// -------------------- --------------------------------------------------
//
// Next method ID: 3
// The layout is as follows:
//
// +-----------------------------------------------+
// | |icon| Header text. [x] |
// | |
// | Body text. |
// | [ Open Chrome ] [No Thanks] |
// +-----------------------------------------------+
//
// Some variants do not have body text, or only have one button.
// Note that speech recognition is activated on VR UI thread. This means it
// usually involves 3 threads. In the simplest case, the thread communication
// looks like the following:
// VR UI thread Browser thread IO thread
// | | |
// |----ActivateVS----->| |
// | |------Start------> |
// | | |
// | |<-NotifyStateChange-|
// |<--OnSRStateChanged-| |
// | | |
// | |<--OnSpeechResult---|
// |<--OnSRStateChanged-| |
// | navigate |
// | | |
// VS = voice search, SR = speech recognition
// A rounded rect is subdivided into a number of triangles.
// _______________
// | / _,-' \ |
// |/_,,-'______\|
// | /|
// | / |
// | / |
// | / |
// | / |
// | / |
// | / |
// | / |
// | / |
// | / |
// | / |
// | / |
// |/____________|
// |\ _,-'' /|
// |_\ ,-'____ /_|
//
// Most of these do not contain an arc. To simplify the rendering of those
// that do, we include a "corner position" attribute. The corner position is
// the distance from the center of the nearest "corner circle". Only those
// triangles containing arcs have a non-zero corner position set. The result
// is that for interior triangles, their corner position is uniformly (0, 0).
// I.e., they are always deemed "inside".
| |
| |
| |
| |
| |
| _ _ |
|( ) _ ( ) _ |
|| | ( ) | | __ _ _ _ __ _ ___ ___ (_) ___ __ |
|| | | | | | /'__`\ ( '_`\ ( '__)/'_`\ /' _ ` _ `\| |/',__) /'__`\ |
|| (_/ \_) |( ___/ | (_) )| | ( (_) )| ( ) ( ) || |\__, \( ___/ |
|`\___x___/'`\____) | ,__/'(_) `\___/'(_) (_) (_)(_)(____/`\____) |
| | | |
| (_) |
| _ _ |
|( )_ ( )_ |
|| ,_) _ ___ | ,_) _ _ _ |
|| | /'_`\ /',__)| | /'_`\ ( '_`\ |
|| |_ ( (_) ) \__, \| |_ ( (_) )| (_) ) |
|`\__)`\___/' (____/`\__)`\___/'| ,__/' |
| | | |
| (_) |
| _ ___ _ _ |
| _ ( )_ _ ( _`\ ( ) ( ) |
| _ _ _ _ __ (_)| ,_)(_) ___ __ | ( (_)__| |__ __| |__ |
|( ) ( ) ( )( '__)| || | | |/' _ `\ /'_ `\ | | _(__ __)(__ __) |
|| \_/ \_/ || | | || |_ | || ( ) |( (_) | | (_( ) | | | | |
|`\___x___/'(_) (_)`\__)(_)(_) (_)`\__ | (____/' (_) (_) |
| ( )_) | |
| \___/' |
| _ _ _____ |
|(_ ) _ ( ) (___ ) |
| | | (_)| |/') __ | | _ _ _ _ _ _ |
| | | | || , < /'__`\ _ | | /'_` )( ) ( ) /'_` ) |
| | | | || |\`\ ( ___/ ( )_| |( (_| || \_/ |( (_| | _ |
|(___)(_)(_) (_)`\____) `\___/'`\__,_)`\___/'`\__,_)(_) |
| |
| |
| |
| |
// For historical reasons, "update" policy has different enum values in Manage
// Preferences from the Device Management. This function converts the former
// to latter.
// +----------------+---------------------+--------------------+
// | Update policy | Managed Preferences | Device Management |
// +----------------+---------------------+--------------------+
// | Enabled | 0 | 1 |
// +----------------+---------------------+--------------------+
// | Automatic only | 1 | 3 |
// +----------------+---------------------+--------------------+
// | Manual only | 2 | 2 |
// +----------------+---------------------+--------------------+
// | Disabled | 3 | 0 |
// +----------------+---------------------+--------------------+
// | Machine only | 4 | 4 |
// +----------------+---------------------+--------------------+
// Circular _________________________________
// Throbber | |
// View | |
// ___________ | |
// | | | |
// | | | |
// | . | | Hint Box |
// | | | |
// |___________| | |
// | |
// | |
// |_________________________________|
//
// This view is set next to the throbber circle view such that their centers
// align. The hint box has a label text and a sublabel text to assist the
// user by informing them about the next step in the calibration process.
// Let AutofillAgent-N, ContentAutofillRouter-N, and AutofillManager-N
// correspond to the Frame-N. ContentAutofillRouter would route an event
// concerning any of the forms in Frame-3 from ContentAutofillDriver-3 to
// ContentAutofillDriver-0:
//
// +---Tab---+ +---Tab----+ +----Tab----+
// | Agent-0 | +---> | Driver-0 | ---------> | Manager-0 |
// | | | | | | |
// | Agent-1 | | | Driver-1 | | Manager-1 |
// | | | | | | |
// | Agent-2 | | | Driver-2 | | Manager-2 |
// | | | | | | |
// | Agent-3 | -----|---> | Driver-3 | -----+ | Manager-3 |
// +---------+ | +----------+ | +-----------+
// | |
// | +--Tab---+ |
// +----- | Router | <-----+
// +--------+
//
// If the event name is `f`, the control flow is as follows:
// Driver-3's ContentAutofillDriver::f(args...) calls
// Router's ContentAutofillRouter::f(this, args..., callback) calls
// Driver-0's ContentAutofillDriver::callback(args...).
// The laser segment calcuates the path needed to draw a laser segment. A laser
// segment is used instead of just a regular line segments to avoid overlapping.
// A laser segment looks as follows:
// _______ _________ _________ _________
// / \ \ / / / / \ |
// | A | 2|. B .|1 2|. C .|1 2|. D \.1 |
// | | | | | | | / |
// \_____/ /_______\ \_________\ \_________/ |
//
//
// Given a start and end point (represented by the periods in the above
// diagrams), we create each segment by projecting each point along the normal
// to the line segment formed by the start(1) and end(2) points. We then
// create a path using arcs and lines. There are three types of laser segments:
// head(B), regular(C) and tail(D). A typical laser is created by rendering one
// tail(D), zero or more regular segments(C), one head(B) and a circle at the
// end(A). They are meant to fit perfectly with the previous and next segments,
// so that no whitespace/overlap is shown.
// A more detailed version of this is located at https://goo.gl/qixdux.
// MessagePortAdapters are used to adapt between two different implementations
// of cast_api_bindings::MessagePort.
//
// PostMessageWithTransferables flow including adaptation:
//+---+ +-------+ +---------+ +---------+ +-------+ +---+
//| A | | PortA | | AdptrA | | AdptrB | | PortB | | B |
//+---+ +-------+ +---------+ +---------+ +-------+ +---+
// | Post | | | | |
// |---------->| | | | |
// | | OnMsg | | | |
// | |------------>| | | |
// | | | Adapt Ports | | |
// | | |-----------| | | |
// | | |<----------| | | |
// | | | Post | | |
// | | |----------------->| | |
// | | | | OnMsg | |
// | | | |----------->| |
// | | | | | OnMsg |
// | | | | |-------->|
//
// Error flow including deletion, for example when OnMessage fails
// | | | | | false |
// | | | | |<--------|
// | | | | OnErr | |
// | | | |<-----------| |
// | | | delete | | |
// | | |<-----------------| | |
// | | delete | | | |
// | |<------------| | | |
// | OnErr | | | | |
// |<----------| | | | |
// | | | | delete | |
// | | | |------| | |
// | | | |<-----| | |
// AndroidMetricsServiceClient metrics set up happens like so:
//
// startup
// │
// ├────────────┐
// │ ▼
// │ query for consent
// ▼ │
// Initialize() │
// │ ▼
// │ SetHaveMetricsConsent()
// │ │
// │ ┌──────────┘
// ▼ ▼
// MaybeStartMetrics()
// │
// ▼
// MetricsService::Start()
//
// All the named functions in this diagram happen on the UI thread. Querying GMS
// happens in the background, and the result is posted back to the UI thread, to
// SetHaveMetricsConsent(). Querying GMS is slow, so SetHaveMetricsConsent()
// typically happens after Initialize(), but it may happen before.
//
// Each path sets a flag, |init_finished_| or |set_consent_finished_|, to show
// that path has finished, and then calls MaybeStartMetrics(). When
// MaybeStartMetrics() is called the first time, it sees only one flag is true,
// and does nothing. When MaybeStartMetrics() is called the second time, it
// decides whether to start metrics.
//
// If consent was granted, MaybeStartMetrics() determines sampling by hashing
// the client ID (generating a new ID if there was none). If this client is in
// the sample, it then calls MetricsService::Start(). If consent was not
// granted, MaybeStartMetrics() instead clears the client ID, if any.
// Read down this diagram for temporal ordering.
//
// Main thread History thread
// ----------- --------------
// AutocompleteController::Start
// -> HistoryURLProvider::Start
// -> VerbatimMatchForInput
// [params_ allocated]
// -> DoAutocomplete (for inline autocomplete)
// -> URLDatabase::AutocompleteForPrefix (on in-memory DB)
// -> HistoryService::ScheduleAutocomplete
// (return to controller) ----
// /
// HistoryBackend::ScheduleAutocomplete
// -> HistoryURLProvider::ExecuteWithDB
// -> DoAutocomplete
// -> URLDatabase::AutocompleteForPrefix
// /
// HistoryService::QueryComplete
// [params_ destroyed]
// -> AutocompleteProviderListener::OnProviderUpdate
//
// The autocomplete controller calls us, and must be called back, on the main
// thread. When called, we run two autocomplete passes. The first pass runs
// synchronously on the main thread and queries the in-memory URL database.
// This pass promotes matches for inline autocomplete if applicable. We do
// this synchronously so that users get consistent behavior when they type
// quickly and hit enter, no matter how loaded the main history database is.
// Doing this synchronously also prevents inline autocomplete from being
// "flickery" in the AutocompleteEdit. Because the in-memory DB does not have
// redirect data, results other than the top match might change between the
// two passes, so we can't just decide to use this pass' matches as the final
// results.
// -----------------------------------------------------------------------------
// | | |
// 1s 2s 3s
// Subframe1 Main Frame Subframe2
// LID (15ms) LID (100ms) LID (200ms)
//
// Delivery order: Main Frame -> Subframe1 -> Subframe2.
// The following tests verify both typical and edge case behavior of Prefetch()
// requests: they should prevent the FacetManager from being discarded, and keep
// the data fresh by initial fetches and refetches (scheduled as described in
// facet_manager.cc).
//
// Legend:
// [---): Interval representing a finite Prefetch request (open from right).
// The data should be kept fresh, the FacetManager not discarded.
// [--->: Interval representing a indefinite Prefetch request.
// The data should be kept fresh, the FacetManager not discarded.
// F: Fetch (initial or refetch) should take place here.
// Fn: The time of the n-th fetch (starting from 1).
// D: Time interval equal to GetShortTestPeriod().
// N: Fetch is signaled to be needed here.
// X: A corresponding CancelPrefetch call is placed here.
// S: |kCacheSoftExpiryInHours| hours
// H: |kCacheHardExpiryInHours| hours
//
// Note: It is guaranteed that S < H and that H < 2*S.
//
// Prefetches with the cache is initially stale/empty:
//
// t=0 S H F2+S F2+H
// / / / / /
// ---o--------------------------o-------o---------------o-------o---------> t
// : : : : :
// [) : : : :
// [F--) : : : :
// [F------------------------): : : :
// [F--------------------------------): : :
// [F-------------------------F----------) : :
// [F-------------------------F----------------------): :
// [F-------------------------F------------------------------):
// [F-------------------------F-----------------------F------------------>
//
// A property key to store the PIP snap fraction for this window.
// The fraction is defined in a clockwise fashion against the PIP movement area.
//
// 0 1
// 4 +---+ 1
// | |
// 3 +---+ 2
// 3 2
// The native bridge for Java to interact with the payment handler host.
// Object relationship diagram:
//
// ChromePaymentRequestService.java --- implements --->
// PaymentRequestUpdateEventListener
// | ^
// owns |________________________
// | |
// v |
// PaymentHandlerHost.java |
// | |
// owns |
// | listener
// v |
// android/payment_handler_host.h |
// | | |
// owns | |
// | owns |
// | | |
// | v |
// | android/payment_request_update_event_listener.h
// | ^ \ ---- implements ---> PaymentHandlerHost::Delegate
// | |
// | delegate
// v |
// payment_handler_host.h
// A bridge for Android to own a C++ PaymentRequestSpec object.
//
// Object ownership diagram:
//
// ChromePaymentRequestService.java
// |
// v
// PaymentRequestSpec.java
// |
// v
// android/payment_request_spec.h
// |
// v
// payment_request_spec.h
// The following graph topology is created to emulate a scenario where a page
// contains a single frame that creates a single dedicated worker.
//
// Pg Pr_
// \ / |
// F |
// \ |
// W__|
//
// Where:
// Pg: page
// F: frame(frame_tree_id:0)
// W: worker
// Pr: process(pid:1)
// This file contains the top-level class for the RulesetService. There are
// associated classes that tie this into the dealer as well as the filter
// agents. The distribution pipeline looks like this:
//
// RulesetService
// |
// v Browser
// RulesetPublisher(Impl)
// | |
// - - - - - - -|- - - - - - - |- - - - - - - - - -
// | | |
// v v
// *RulesetDealer | *RulesetDealer
// | | |
// | | | v
// v | SubresourceFilterAgent
// SubresourceFilterAgent | v
// SubresourceFilterAgent
// |
//
// Renderer #1 | Renderer #n
//
// Note: UnverifiedRulesetDealer is shortened to *RulesetDealer above. There is
// also a VerifiedRulesetDealer which is used similarly on the browser side.
// Ignoring the suspend/resume issues since this code is not using them, the
// job state machine implemented by BITS is something like this:
//
// Suspended--->Queued--->Connecting---->Transferring--->Transferred
// | ^ | | |
// | | V V | (complete)
// +----------|---------+-----------------+-----+ V
// | | | | Acknowledged
// | V V |
// | Transient Error------->Error |
// | | | |(cancel)
// | +-------+---------+--->-+
// | V |
// | (resume) | |
// +------<----------+ +---->Cancelled
//
// The job is created in the "suspended" state. Once |Resume| is called,
// BITS queues up the job, then tries to connect, begins transferring the
// job bytes, and moves the job to the "transferred state, after the job files
// have been transferred. When calling |Complete| for a job, the job files are
// made available to the caller, and the job is moved to the "acknowledged"
// state.
// The state machine representing how a CRX component changes during an update.
//
// +------------------------- kNew
// | |
// | V
// | kChecking
// | |
// V error V no no
// kUpdateError <------------- [update?] -> [action?] -> kUpToDate kUpdated
// ^ | | ^ ^
// | yes | | yes | |
// | update disabled V | | |
// +-<--------------------- kCanUpdate +--------> kRun |
// | | |
// | no V |
// | +-<- [differential update?] |
// | | | |
// | | yes | |
// | | error V |
// | +-<----- kDownloadingDiff kRun---->-+
// | | | ^ |
// | | | yes | |
// | | error V | |
// | +-<----- kUpdatingDiff ---------> [action?] ->-+
// | | ^ no
// | error V |
// +-<-------- kDownloading |
// | | |
// | | |
// | error V |
// +-<-------- kUpdating --------------------------------+
// This class should be used only by the component updater. It is inspired by
// and overlaps with code in the extension's SandboxedUnpacker.
// The main differences are:
// - The public key hash is full SHA256.
// - Does not use a sandboxed unpacker. A valid component is fully trusted.
// - The manifest can have different attributes and resources are not
// transcoded.
//
// If the CRX is a delta CRX, the flow is:
// [ComponentUpdater] [ComponentPatcher]
// Unpack
// \_ Verify
// \_ Unzip
// \_ BeginPatching ---> DifferentialUpdatePatch
// ...
// EndPatching <------------ ...
// \_ EndUnpacking
//
// For a full CRX, the flow is:
// [ComponentUpdater]
// Unpack
// \_ Verify
// \_ Unzip
// \_ BeginPatching
// |
// V
// EndPatching
// \_ EndUnpacking
//
// During unzip step we also check for verified_contents.json in the header
// of crx file and unpack it to metadata_ folder if it doesn't already contain
// verified_contents file.
// In both cases, if there is an error at any point, the remaining steps will
// be skipped and EndUnpacking will be called.
// One surface.
//
// +e---------+
// | |
// | |
// | |
// +----------+
//
// Check if draw occlusion works well with rotation transform.
//
// +-----+ +----+
// | | rotation (by 45 on y-axis) -> | | same height
// +-----+ +----+ reduced weight
// Tests that the overlay will be partially rendered (clipped) when any part of
// it extends outside the video frame's content region.
//
// For this test, the content region is a rectangle, centered within the frame
// (e.g., the content is being letterboxed), and the test attempts to locate the
// overlay such that part of it should be clipped. The test succeeds if the
// overlay is clipped to the content region in the center. For example:
//
// +-------------------------------+
// | |
// | ...... |
// | ..****//////////// | **** the drawn part of the overlay
// One surface.
//
// +----------+
// | |
// | |
// | |
// +----------+
// Test the race condition where a document is evicted from the BackForwardCache
// while it is in the middle of being restored and before URL loader starts a
// response.
//
// ┌───────┐ ┌────────┐
// │Browser│ │Renderer│
// └───┬───┘ └───┬────┘
// (Freeze & store the cache) │
// │────────────────────────>│
// │ │
// (Navigate to cached document) │
// │──┐ │
// │ │ │
// │EvictFromBackForwardCache│
// │<────────────────────────│
// │ │ │
// │ x Navigation cancelled │
// │ and reissued │
// ┌───┴───┐ ┌───┴────┐
// │Browser│ │Renderer│
// └───────┘ └────────┘
//
// When the eviction occurs, the in flight NavigationRequest to the cached
// document should be reissued (cancelled and replaced by a normal navigation).
// Test that unload handlers in iframes are run, even when the removed subtree
// is complicated with nested iframes in different processes.
// A1 A1
// / \ / \
// B1 D --- Navigate ---> E D
// / \
// C1 C2
// | |
// B2 A2
// |
// C3
// TODO(crbug.com/1012185): Flaky timeouts on Linux and Mac.
// Now is at 11 PM.
//
// 20:00 23:00 5:00
// <----- + ----------------- + ----------------------- + ------->
// | | |
// sunset now sunrise
//
// Tests that when the user logs in for the first time between sunset and
// sunrise with Auto Night Light enabled, and the notification has never been
// dismissed before, the notification should be shown.
// For the synchronous compositor feature of webview it is necessary
// that the UI thread to block until the renderer process has processed
// certain messages entirely. (beginframe and resulting compositor frames).
// This object is used to manage the waiting and signaling behavior on the UI
// thread. The UI thread will wait on a WaitableEvent (via FrameFuture class)
// or condition variable which is then signal by handlers in this class.
// This object is a cross thread object accessed both on the UI and IO threads.
//
// Examples of call graphs are:
// Browser UI Thread Browser IO Thread Renderer
//
// ->VSync Java
// ----------------------------------------------->BeginFrame
// CV Wait
// BeginFrameRes<----------
// CVSignal
// WakeUp
//
//
// ->DrawHwAsync
// RegisterFrameFuture
// ----------------------------------------------->DrawHwAsync
// Do some stuff
// FrameFuture::GetFrame()
// WaitableEvent::Wait()
// ReceiveFrame<---------------
// WaitableEvent::Signal()
// WakeUp
//
// This may seem simple but it gets a little more complicated when
// multiple views are involved. Each view will have it's own SyncCallBridge.
//
// Once example is:
//
// Browser UI Thread Browser IO Thread Renderer1 Renderer2
//
// ->VSync Java
// ----------------------------------------------->BeginFrame
// BeginFrameRes<----------
// CVSignal
// ------------------------------------------------------------>BeginFrame
// CV Wait
// BeginFrameRes<----------------------------
// CVSignal
// WakeUp
//
// Notice that it is possible that before we wait on a CV variable a renderer
// may have already responded to the BeginFrame request.
// Information about a physical attribute of the screen which that creates a
// Logical separator or divider (e.g. a fold or mask).
// This is a visual example of a vertically oriented display feature that masks
// content underneath
//
// Orientation: vertical
//
// offset
// |
// +---------|===|---------+
// | | | |
// | | | |
// | | | |
// | | | |
// | | | |
// +---------|===|---------+
// \
// mask_length
//
// Note that the implicit height of the display feature is the entire height of
// the screen on which it exists.
// Build the following frame opener graph and see that it can be properly
// traversed when creating opener proxies:
//
// +-> root4 <--+ root3 <---- root2 +--- root1
// | / | ^ / \ | / \ .
// | 42 +-----|------- 22 23 <--+ 12 13
// | +------------+ | | ^
// +-------------------------------+ +-+
//
// The test starts traversing openers from root1 and expects to discover all
// four FrameTrees. Nodes 13 (with cycle to itself) and 42 (with back link to
// root3) should be put on the list of nodes that will need their frame openers
// set separately in a second pass, since their opener routing IDs won't be
// available during the first pass of CreateOpenerProxies.
// This class is related to ForwardingAudioStreamFactory as follows:
//
// WebContentsImpl <-- RenderFrameHostImpl
// ^ ^
// | |
// ForwardingAudioStreamFactory RenderFrameAudioOutputStreamFactory
// ^ ^
// | |
// FASF::Core <-- RFAOSF::Core
//
// Both FASF::Core and RFAOSF::Core live on (and are destructed on) the IO
// thread. A weak pointer to ForwardingAudioStreamFactory is used since
// WebContentsImpl is sometimes destructed shortly before RenderFrameHostImpl.
// Manages network requests and maintains relevant state for interaction with
// the Identity Provider across a FedCM transaction. Owned by
// FederatedAuthRequestImpl and has a lifetime limited to a single identity
// transaction between an RP and an IDP.
//
// Diagram of the permission-based data flows between the browser and the IDP:
// .-------. .---.
// |Browser| |IDP|
// '-------' '---'
// | |
// | GET /fedcm.json |
// |-------------------------------->|
// | |
// | JSON{idp_url} |
// |<--------------------------------|
// | |
// | POST /idp_url with OIDC request |
// |-------------------------------->|
// | |
// | token or signin_url |
// |<--------------------------------|
// .-------. .---.
// |Browser| |IDP|
// '-------' '---'
//
// If the IDP returns an token, the sequence finishes. If it returns a
// signin_url, that URL is loaded as a rendered Document into a new window for
// the user to interact with the IDP.
// Creates compact textual representations of the state of the frame tree that
// is appropriate for use in assertions.
//
// The diagrams show frame tree structure, the SiteInstance of current frames,
// presence of pending frames, and the SiteInstances of any and all proxies.
// They look like this:
//
// Site A (D pending) -- proxies for B C
// |--Site B --------- proxies for A C
// +--Site C --------- proxies for B A
// |--Site A ---- proxies for B
// +--Site A ---- proxies for B
// +--Site A -- proxies for B
// Where A = http://127.0.0.1/
// B = http://foo.com/ (no process)
// C = http://bar.com/
// D = http://next.com/
//
// SiteInstances are assigned single-letter names (A, B, C) which are remembered
// across invocations of the pretty-printer.
// Input signature:
//
// Name Index Mask Register SysValue Format Used
// -------------------- ----- ------ -------- -------- ------- ------
// POSITION 0 xy 0 NONE float xy
// TEXCOORD 0 xy 1 NONE float xy
// TEXCOORD 1 x 2 NONE uint x
//
//
// Output signature:
//
// Name Index Mask Register SysValue Format Used
// -------------------- ----- ------ -------- -------- ------- ------
// SV_POSITION 0 xyzw 0 POS float xyzw
// TEXCOORD 0 xy 1 NONE float xy
// TEXCOORD 1 x 2 NONE uint x
//
//
// Runtime generated constant mappings:
//
// Target Reg Constant Description
// ---------- --------------------------------------------------
// c0 Vertex Shader position offset
// Cell representation for SettingsCheckItem.
// +---------------------------------------------------------+
// | +--------+ +---------+ |
// | | | One line title |trailing | |
// | | leading| |image | |
// | | image | Multiline detail text |spinner | |
// | | | Multiline detail text |or button| |
// | +--------+ +---------+ |
// +---------------------------------------------------------+
// Bottom toolbar for TabGrid. The appearance of the toolbar is decided by
// screen size, current TabGrid page and mode:
//
// Horizontal-compact and vertical-regular screen size:
// Small newTabButton, translucent background.
// Incognito & Regular page: [CloseAllButton newTabButton DoneButton]
// Remote page: [ DoneButton]
// Selection mode: [CloseTabButton shareButton AddToButton]
//
// Other screen size:
// Large newTabButton, floating layout without UIToolbar.
// Normal mode: [ newTabButton]
// Remote page: [ ]
// Selection mode: [CloseTabButton shareButton AddToButton]
// Top toolbar for TabGrid. The appearance of the toolbar is decided by screen
// size, current TabGrid page and mode:
//
// Horizontal-compact and vertical-regular screen size:
// Normal mode: [ PageControl Select]
// Remote page: [ PageControl ]
// Selection mode: [SelectAll SelectedTabsCount Done]
// Other screen size:
// Normal mode: [CloseAll PageControl Select Done]
// Remote page: [ PageControl Done]
// Selection mode: [SelectAll SelectedTabsCount Done]
// A manager for audio debug recording that handles registration of data
// sources and hands them a recorder (AudioDebugRecordingHelper) to feed data
// to. The recorder will unregister with the manager automatically when deleted.
// When debug recording is enabled, it is enabled on all recorders and
// constructs a unique file name for each recorder by using a running ID.
// A somewhat simplified diagram of the the debug recording infrastructure,
// interfaces omitted:
//
// AudioDebugFileWriter
// ^
// | owns
// owns | owns
// OnMoreDataConverter ----> AudioDebugRecordingHelper <---------
// ^ ^ |
// | owns several | raw pointer to several |
// | AudioDebugRecordingManager |
// AudioOutputResampler ^ |
// ^ | AudioInputStreamDataInterceptor
// | | ^
// | owns several | owns owns several |
// ------------------ AudioManagerBase ----------------
//
// AudioDebugRecordingManager is created when
// AudioManager::InitializeDebugRecording() is called. That is done in
// AudioManager::Create() in WebRTC enabled builds, but not in non WebRTC
// enabled builds. If AudioDebugRecordingManager is not created, neither is
// AudioDebugRecordingHelper or AudioDebugFileWriter. In this case the pointers
// to AudioDebugRecordingManager and AudioDebugRecordingHelper are null.
// Overview of operation:
// 1) An object of CrasUnifiedStream is created by the AudioManager
// factory: audio_man->MakeAudioStream().
// 2) Next some thread will call Open(), at that point a client is created and
// configured for the correct format and sample rate.
// 3) Then Start(source) is called and a stream is added to the CRAS client
// which will create its own thread that periodically calls the source for more
// data as buffers are being consumed.
// 4) When finished Stop() is called, which is handled by stopping the stream.
// 5) Finally Close() is called. It cleans up and notifies the audio manager,
// which likely will destroy this object.
//
// Simplified data flow for output only streams:
//
// +-------------+ +------------------+
// | CRAS Server | | Chrome Client |
// +------+------+ Add Stream +---------+--------+
// |<----------------------------------|
// | |
// | Near out of samples, request more |
// |---------------------------------->|
// | | UnifiedCallback()
// | | WriteAudio()
// | |
// | buffer_frames written to shm |
// |<----------------------------------|
// | |
// ... Repeats for each block. ...
// | |
// | |
// | Remove stream |
// |<----------------------------------|
// | |
//
// For Unified streams the Chrome client is notified whenever buffer_frames have
// been captured. For Output streams the client is notified a few milliseconds
// before the hardware buffer underruns and fills the buffer with another block
// of audio.
// Crops an image such that its aspect ratio matches that of a target size, but
// does not perform any "scaling". The cropping is calculated with the image
// and the target rect "center-aligned". The image dimension with the smaller
// (target_size / original_size) ratio gets cropped.
//
// A visual example with a portrait image whose dimensions exceeds a landscape
// target size:
//
// Before:
//
// Portrait Image
// +---------------------------+
// | |
// | |
// | |
// | |
// | Landscape Target |
// | +-----------------+ |
// | | | |
// | | | |
// | | | |
// | | | |
// | | | |
// | +-----------------+ |
// | |
// | |
// | |
// | |
// | |
// +---------------------------+
//
// After (ok, maybe it's not the exact same aspect ratio, but you get the idea):
//
// Cropped Image
// +---------------------------+
// | |
// | Landscape Target |
// | +-----------------+ |
// | | | |
// | | | |
// | | | |
// | | | |
// | | | |
// | +-----------------+ |
// | |
// | |
// +---------------------------+
//
// The ultimate result is always a cropped image whose aspect ratio matches that
// of the target size. Therefore, the cropped image can subsequently be scaled
// up or down to match the dimensions of the target size.
// This module provides a display of frame-level performance metrics, rendered
// in the lower-right corner of a VideoFrame. It looks like this:
//
// +---------------------------------------------------------------------+
// | @@@@@@@@@@@@@@@@@@@@@@@ |
// | @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ |
// | @@@@@@@@@@@@@@@@@@@@@@@ @@@@@@@@@@@@ |
// | @@@@@@@@@@@@@ @@@@ |
// | @@@@@@@@@@ @@@@ |
// | @@@@@ @@@ @@@ @@@@ |
// | @@@ @ @@@ @@@@ @@@@ |
// | @@@@ @@@@ @@@@ |
// | @@@@ @@@ @@@ |
// | @@@@ @@ @@@ |
// | @@@@@ @@@ @@@ @@@ |
// | @@@@@ @@@@@ @@@@ @@@@ |
// | @@@@@ @@@@@@@@@@@@@ @@@@ |
// | @@@@@@ @@@@ 1 45% 75% |
// | @@@@@@@@ @@@@@@ 22 400. 4000 |
// | @@@@@@@@@@@@@@@@ 16.7 1280x720 0:15.12 |
// +---------------------------------------------------------------------+
//
// Line 1: Reads as, "1 frame ago, the encoder utilization for the frame was 45%
// and the lossy utilization was 75%." For CPU-bound encoders, encoder
// utilization is usually measured as the amount of real-world time it took to
// encode the frame, divided by the maximum amount of time allowed. Lossy
// utilization is the amount of "complexity" in the frame's content versus the
// target encoded byte size, where a value over 100% means the frame's content
// is too complex to encode within the target number of bytes.
//
// Line 2: Reads as, "Capture of this frame took 22 ms. The current target
// playout delay is 400 ms and low-latency adjustment mode is not active. The
// target bitrate for this frame is 4000 kbps." If there were an exclamation
// mark (!) after the playout delay number instead of a period (.), it would
// indicate low-latency adjustment mode is active. See VideoSender for more
// details.
//
// Line 3: Contains the frame's duration (16.7 milliseconds), resolution, and
// media timestamp in minutes:seconds.hundredths format.
// Routines for encoding and decoding a small number of bits into an image
// in a way that is decodable even after scaling/encoding/cropping.
//
// The encoding is very simple:
//
// #### #### ######## #### #### ####
// #### #### ######## #### #### ####
// #### #### ######## #### #### ####
// #### #### ######## #### #### ####
// 1 2 3 4 5 6 7 8 9 10 11 12 13 14
// <-----start----><--one-bit-><-zero bit-><----stop---->
//
// We use a basic unit, depicted here as four characters wide.
// We start with 1u black 1u white 1u black 1u white. (1-4 above)
// From there on, a "one" bit is encoded as 2u black and 1u white,
// and a zero bit is encoded as 1u black and 2u white. After
// all the bits we end the pattern with the same pattern as the
// start of the pattern.
// Using position based test API:
// DTS : 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
// PTS : 0 4 1 2 3 5 9 6 7 8 10 14 11 12 13 15 19 16 17 18 20
// old : A a a a a A a a a a
// new : B b b b b B b b
// after: B b b b b B b b A a a a a
/*
Window shape (global coordinates)
(0,0)_____________
|. * | * | <- mouse move (1,1)
| * | * |
|*_____| *|
|* (r,r) *|
| * * |
|____*___*____|
(2r, 2r)
This mouse event hits the square but not the circular window targeter.*/
// State diagram.
//
// [Uninitialized] <-> (init failed)
// | |
// (no enc.) (encrypted)
// | |
// | [WaitingForMediaCrypto] -- (OMCR failure) --> [Uninitialized]
// | | (OnMediaCryptoReady success)
// v v
// (Create Codec and MediaCodecLoop)
// |
// \--> [Ready] -(any error)-> [Error]
//
// -[Any state]-
// | |
// (Reset ok) (Reset fails)
// | |
// [Ready] [Error]
// VASurfaceID is allocated in VaapiWrapper.
// |
// +----->|
// | v
// | VASurfaceID is put onto VaapiVideoDecodeAccelerator::available_va_surfaces_
// | | list.
// | v
// | VASurfaceID is taken off of the VVDA:available_va_surfaces_ when
// | | VaapiH264Decoder requests more output surfaces, is wrapped into
// | | a VASurface and passed to VaapiH264Decoder.
// | v
// | VASurface is put onto VaapiH264Decoder::available_va_surfaces_, keeping
// | | the only reference to it until it's needed for decoding.
// | v
// | VaapiH264Decoder starts decoding a new frame. It takes a VASurface off of
// | | VHD::available_va_surfaces_ and assigns it to a DecodeSurface,
// | | which now keeps the only reference.
// | v
// | DecodeSurface is used for decoding, putting data into associated VASurface.
// | |
// | |--------------------------------------------------+
// | | |
// | v v
// | DecodeSurface is to be output. VaapiH264Decoder uses the
// | VaapiH264Decoder passes the associated DecodeSurface and associated
// | VASurface to VaapiVideoDecodeAccelerator, VASurface as reference for
// | which stores it (taking a ref) on decoding more frames.
// | pending_output_cbs_ queue until an output |
// | VaapiPicture becomes available. v
// | | Once the DecodeSurface is not
// | | needed as reference anymore,
// | v it is released, releasing the
// | A VaapiPicture becomes available after associated VASurface reference.
// | the client of VVDA returns |
// | a PictureBuffer associated with it. VVDA |
// | puts the contents of the VASurface into |
// | it and releases the reference to VASurface. |
// | | |
// | '---------------------------------------'
// | |
// | v
// | Neither VVDA nor VHD hold a reference to VASurface. VASurface is released,
// | ReleaseCB gets called in its destructor, which puts the associated
// | VASurfaceID back onto VVDA::available_va_surfaces_.
// | |
// '-------------------------------------|
// |
// v
// VaapiWrapper frees VASurfaceID.
//
// Client VideoEncodeAccelerator
// | ---> Initialize |
// | RequireBitstreamBuffers(N) <--- |
// | ---> UseOutputBitstreamBuffer(0) |
// | ---> UseOutputBitstreamBuffer(1) |
// | ... |
// = =
// The Client requests a remote Encode() and eventually the VEA will leave the
// encoded results in a pre-shared BitstreamBuffer, that is then restored to the
// VEA when the Client is finished with it. Note that there might not be a 1:1
// relationship between Encode() and BitstreamBufferReady() calls.
// | ---> Encode() |
// | BitstreamBufferReady(k) <--- |
// | ---> UseOutputBitstreamBuffer(k) |
// = =
// Data pipe attachments come in two parts within a message's handle list: the
// DataPipe object wherever it was placed by the sender, and its control portal
// as a separate attachment at the end of the handle list. For a message with
// two data pipes endpoints (X and Y) and two message pipe endpoints(A and B),
// sent in the order AXBY, a well-formed message will have 6 total handles
// attached:
//
// Message Pipe A Message Pipe B DataPipe X's portal
// | | |
// 0:A 1:X 2:B 3:Y 4:x 5:y
// | | |
// DataPipe X DataPipe Y DataPipe Y's portal
//
// This function validates that each DataPipe in `handles` has an associated
// portal, and it fixes up `handles` by stripping those portals off the end of
// the list and passing ownership to their corresponding DataPipe object.
//
// Returns true if and only if the handle list is well-formed in this regard.
// An interface proxy can represent either end of a cross-process interface
// call. The "source" side is where the call is invoked, and the "target" side
// is where the call ends up being executed.
//
// Plugin side | Browser side
// -------------------------------------|--------------------------------------
// |
// "Source" | "Target"
// InterfaceProxy ----------------------> InterfaceProxy
// |
// |
// "Target" | "Source"
// InterfaceProxy <---------------------- InterfaceProxy
// |
// Transposes matrix [ m0, m1, m2, m3, m4, m5, m6, m7, m8 ]:
//
// | m0, m1, m2, | | x |
// | m3, m4, m5, | * | y |
// | m6, m7, m8 | | 1 |
//
// Into [ m0, m3, m6, m1, m4, m7, m2, m5, m8 ].
// A 2D non-skew equally scaled transformation matrix.
// | SCALE, 0, OFFSET_X, |
// | 0, SCALE, OFFSET_Y, |
// | 0, 0, 1 |
// Set up multiple displays:
// +-----------+
// | 800x600 |---------------+
// | 0 | 1024x768 |
// +-----------+ 1 |
// | |
// +---------------+
// Calculate the offset from the origin of the desktop to the origin of the
// specified display.
//
// For Mac and ChromeOS, the origin of the desktop is the origin of the default
// display.
//
// For Windows/Linux, the origin of the desktop is the upper-left of the
// entire desktop region.
//
// x b-----------+ ---
// | | | y-offset to c
// a---------+ | |
// | +-------c---+-------+ ---
// | | | |
// +---------+ | |
// +-----------+
//
// |-----------------|
// x-offset to c
//
// x = upper left of desktop
// a,b,c = origin of display A,B,C
// o---------+
// | 0 |
// | 300x200 |
// +---------+
// o = desktop origin
// A view that shows the contents of the corresponding desk in its mini_view.
// This view has the following layer hierarchy:
//
// +---------------------------+
// | <-------------+------ This view's layer.
// +---------------------------+
// / | | \ ----->>>>> Higher in Z-order.
// / | | \
// +-----+ +-----+ +-----+ +-----+
// | | | | | | | |
// +-----+ +-----+ +-----+ +-----+
// ^ ^ ^ \ ^
// | | | \ +-----+ |
// | | | | | |
// | | | +-----+ |
// | | | ^ |
// | | | | `highlight_overlay_`'s layer:
// | | | | A solid color layer that is
// | | | | visible when `mini_view_`'s
// | | | | `DeskActionContextMenu` is open.
// | | | |
// | | | |
// | | | The root layer of the desk's mirrored
// | | | contents layer tree. This tree is owned by
// | | | `desk_mirrored_contents_layer_tree_owner_`.
// | | |
// | | |
// | | `desk_mirrored_contents_view_`'s layer: Will be the
// | | parent layer of the desk's contents mirrored layer
// | | tree.
// | |
// | |
// | `wallpaper_preview_`'s layer: On which the wallpaper is painted
// | without the dimming and blur that overview mode adds.
// |
// |
// `shadow_layer_`: A layer that paints a shadow behind this view.
//
// Note that `desk_mirrored_contents_view_`, `wallpaper_preview_`, and
// `highlight_overlay_` paint to layers with rounded corners. In order to use
// the fast rounded corners implementation we must make them sibling layers,
// rather than one being a descendant of the other. Otherwise, this will trigger
// a render surface.
// Default display = Left (A)
// o-------------+-----------------+
// | A | B |
// | 2560x1440 | 3840x2160 |
// | | |
// |-------------+ |
// +-----------------+
// o = desktop origin
// THREADING
//
// This class is supplied TaskRunners to use for capture, encode and network
// operations. Capture, encode and network transmission tasks are interleaved
// as illustrated below:
//
// | CAPTURE ENCODE NETWORK
// | .............
// | . Capture .
// | .............
// | ............
// | . .
// | ............. . .
// | . Capture . . Encode .
// | ............. . .
// | . .
// | ............
// | ............. ............ ..........
// | . Capture . . . . Send .
// | ............. . . ..........
// | . Encode .
// | . .
// | . .
// | ............
// | Time
// v
//
// VideoFramePump would ideally schedule captures so as to saturate the slowest
// of the capture, encode and network processes. However, it also needs to
// rate-limit captures to avoid overloading the host system, either by consuming
// too much CPU, or hogging the host's graphics subsystem.
// | path + null_byte |
// This is the IPC server interface for CrossCall: The IPC for the Sandbox
// On the server, CrossCall needs two things:
// 1) threads: Or better said, someone to provide them, that is what the
// ThreadPool is for. These thread(s) are
// the ones that will actually execute the IPC data retrieval.
//
// 2) a dispatcher: This interface represents the way to route and process
// an IPC call given the IPC tag.
//
// The other class included here CrossCallParamsEx is the server side version
// of the CrossCallParams class of /sandbox/crosscall_params.h The difference
// is that the sever version is paranoid about the correctness of the IPC
// message and will do all sorts of verifications.
//
// A general diagram of the interaction is as follows:
//
// ------------
// | |
// ThreadPool<-------(1)Register--| IPC |
// | | Implemen |
// | | -tation |
// (2) | | OnMessage
// IPC fired --callback ------>| |--(3)---> Dispatcher
// | |
// ------------
//
// The IPC implementation sits as a middleman between the handling of the
// specifics of scheduling a thread to service the IPC and the multiple
// entities that can potentially serve each particular IPC.
//
// <<<<<-------------------------- move left.
// +-----------+
// | Animation |
// | layer |
// +-----------+
// / \
// +------------+ +------------+
// | start desk | | end desk |
// | screenshot | | screenshot |
// | layer | | layer |
// +------------+ +------------+
// ^
// start here
//
// Animation layer transforms:
// * Begin transform: The transform that will make the starting desk
// screenshot visible. In this case it is a transform with translation
// (edge_padding_width_dp_, 0).
// * End transform: The transform that will make the ending desk
// screenshot visible. In this case it is a transform with translation
// (-|edge_padding_width_dp_| - |x_translation_offset_| -
// |kDesksSpacing|, 0).
//
// - Or to the right (starting_desk_index_ > ending_desk_index_), when the
// starting desk is on the right.
//
// move right. -------------------------->>>>>
// +-----------+
// | Animation |
// | layer |
// +-----------+
// / \
// +------------+ +------------+
// | end desk | | start desk |
// | screenshot | | screenshot |
// | layer | | layer |
// +------------+ +------------+
// ^
// start here
//
// Animation layer transforms:
// * Begin transform: The transform that will make the starting desk
// screenshot visible. In this case it is a transform with translation
// (-|edge_padding_width_dp_| - |x_translation_offset_| -
// |kDesksSpacing|, 0).
// * End transform: The transform that will make the ending desk
// screenshot visible. In this case it is a transform with translation
// (edge_padding_width_dp_, 0).
// An OutputController controls an AudioOutputStream and provides data to this
// output stream. It executes audio operations like play, pause, stop, etc. on
// the audio manager thread, while the audio data flow occurs on the platform's
// realtime audio thread.
//
// Here is a state transition diagram for the OutputController:
//
// *[ Empty ] --> [ Created ] --> [ Playing ] -------.
// | | | ^ |
// | | | | |
// | | | | v
// | | | `----- [ Paused ]
// | | | |
// | v v |
// `-----------> [ Closed ] <-----------'
//
// * Initial state
//
// At any time after reaching the Created state but before Closed, the
// OutputController may be notified of a device change via OnDeviceChange(). As
// the OnDeviceChange() is processed, state transitions will occur, ultimately
// ending up in an equivalent pre-call state. E.g., if the state was Paused,
// the new state will be Created, since these states are all functionally
// equivalent and require a Play() call to continue to the next state.
// The Perfetto tracing backend mediates between the Perfetto client library and
// the mojo-based tracing service. It allows any process to emit trace data
// through Perfetto and privileged processes (i.e., the browser) to start
// tracing sessions and read back the resulting data.
//
// Perfetto : Tracing backend : Tracing service
// : :
// : mojo
// calls : .------------------. : .--------------.
// .---------->| ConsumerEndpoint |<--->| ConsumerHost |
// .--------------. : `------------------' : `--------------'
// | TracingMuxer | : :
// `--------------' : .------------------. : .--------------.
// `---------->| ProducerEndpoint |<--->| ProducerHost |
// : `------------------' : `--------------'
// : :
/* From http://www.khronos.org/registry/gles/extensions/OES/OES_compressed_ETC1_RGB8_texture.txt
The number of bits that represent a 4x4 texel block is 64 bits if
<internalformat> is given by ETC1_RGB8_OES.
The data for a block is a number of bytes,
{q0, q1, q2, q3, q4, q5, q6, q7}
where byte q0 is located at the lowest memory address and q7 at
the highest. The 64 bits specifying the block is then represented
by the following 64 bit integer:
int64bit = 256*(256*(256*(256*(256*(256*(256*q0+q1)+q2)+q3)+q4)+q5)+q6)+q7;
ETC1_RGB8_OES:
a) bit layout in bits 63 through 32 if diffbit = 0
63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48
-----------------------------------------------
| base col1 | base col2 | base col1 | base col2 |
| R1 (4bits)| R2 (4bits)| G1 (4bits)| G2 (4bits)|
-----------------------------------------------
47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
---------------------------------------------------
| base col1 | base col2 | table | table |diff|flip|
| B1 (4bits)| B2 (4bits)| cw 1 | cw 2 |bit |bit |
---------------------------------------------------
b) bit layout in bits 63 through 32 if diffbit = 1
63 62 61 60 59 58 57 56 55 54 53 52 51 50 49 48
-----------------------------------------------
| base col1 | dcol 2 | base col1 | dcol 2 |
| R1' (5 bits) | dR2 | G1' (5 bits) | dG2 |
-----------------------------------------------
47 46 45 44 43 42 41 40 39 38 37 36 35 34 33 32
---------------------------------------------------
| base col 1 | dcol 2 | table | table |diff|flip|
| B1' (5 bits) | dB2 | cw 1 | cw 2 |bit |bit |
---------------------------------------------------
c) bit layout in bits 31 through 0 (in both cases)
31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16
-----------------------------------------------
| most significant pixel index bits |
| p| o| n| m| l| k| j| i| h| g| f| e| d| c| b| a|
-----------------------------------------------
15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 0
--------------------------------------------------
| least significant pixel index bits |
| p| o| n| m| l| k| j| i| h| g| f| e| d| c | b | a |
--------------------------------------------------
Add table 3.17.2: Intensity modifier sets for ETC1 compressed textures:
table codeword modifier table
------------------ ----------------------
0 -8 -2 2 8
1 -17 -5 5 17
2 -29 -9 9 29
3 -42 -13 13 42
4 -60 -18 18 60
5 -80 -24 24 80
6 -106 -33 33 106
7 -183 -47 47 183
Add table 3.17.3 Mapping from pixel index values to modifier values for
ETC1 compressed textures:
pixel index value
---------------
msb lsb resulting modifier value
----- ----- -------------------------
1 1 -b (large negative value)
1 0 -a (small negative value)
0 0 a (small positive value)
0 1 b (large positive value)
*/
* @animations
* | Animation | Occurs |
* |----------------------------------|-------------------------------------|
* | {@link ng.$animate#addClass addClass} | just before the class is applied to the element |
* | {@link ng.$animate#removeClass removeClass} | just before the class is removed from the element |
* `ReactCompositeComponent` maintains an auxiliary life cycle state in
* `this._compositeLifeCycleState` (which can be null).
*
* This is different from the life cycle state maintained by `ReactComponent` in
* `this._lifeCycleState`. The following diagram shows how the states overlap in
* time. There are times when the CompositeLifeCycle is null - at those times it
* is only meaningful to look at ComponentLifeCycle alone.
*
* Top Row: ReactComponent.ComponentLifeCycle
* Low Row: ReactComponent.CompositeLifeCycle
*
* +-------+------------------------------------------------------+--------+
* | UN | MOUNTED | UN |
* |MOUNTED| | MOUNTED|
* +-------+------------------------------------------------------+--------+
* | ^--------+ +------+ +------+ +------+ +--------^ |
* | | | | | | | | | | | |
* | 0--|MOUNTING|-0-|RECEIV|-0-|RECEIV|-0-|RECEIV|-0-| UN |--->0 |
* | | | |PROPS | | PROPS| | STATE| |MOUNTING| |
* | | | | | | | | | | | |
* | | | | | | | | | | | |
* | +--------+ +------+ +------+ +------+ +--------+ |
* | | | |
* +-------+------------------------------------------------------+--------+
// TextFragmentAnchor is a state machine that transitions state via
// InvokeSelector (and some external events). Here are the state transitions:
//
// ┌──────┐
// │ ┌──┴────────────────────────┐
// └───► kSearching ├────────────┐
// └─────────────┬─────────────┘ │
// │ │
// ┌─────┬─────────────▼─────────────┐ │
// └────►│ kBeforeMatchEventQueued │ │
// └─────────────┬─────────────┘ │
// │ │
// ┌─────────────▼─────────────┐ │
// │ kBeforeMatchEventFired ├────────────┤
// └─────────────┬─────────────┘ │
// │ │
// ┌─────┬─────────────▼─────────────┐ │
// └────►│ kEffectsAppliedKeepInView │ │
// └─────────────┬─────────────┘ │
// │ │
// ┌------------─▼-------------┐ │
// ┌─────┤ [[SearchFinished]] |◄───────────┘
// │ └-------------┬-------------┘
// │ │
// │ ┌─────────────▼─────────────┬─────┐
// │ │ kScriptableActions │◄────┘
// │ └───────────────────────────┘
// │ │
// │ ┌─────────────▼─────────────┐
// └─────► kDone │
// └───────────────────────────┘
// Implements Myer's Algorithm from
// "An O(ND) Difference Algorithm and Its Variations", particularly the
// linear space refinement mentioned in section 4b.
//
// The differ is input agnostic.
//
// The algorithm works by finding the shortest edit string (SES) in the edit
// graph. The SES describes how to get from a string A of length N to a string
// B of length M via deleting from A and inserting from B.
//
// Example: A = "abbaa", B = "abab"
//
// A
//
// a b b a a
// o---o---o---o---o---o
// a | \ | | | \ | \ |
// o---o---o---o---o---o
// b | | \ | \ | | |
// B o---o---o---o---o---o
// a | \ | | | \ | \ |
// o---o---o---o---o---o
// b | | \ | \ | | |
// o---o---o---o---o---o
//
// The edit graph is constructed with the characters from string A on the x-axis
// and the characters from string B on the y-axis. Starting from (0, 0) we can:
//
// - Move right, which is equivalent to deleting from A
// - Move downwards, which is equivalent to inserting from B
// - Move diagonally if the characters from string A and B match, which
// means no insertion or deletion.
//
// Any path from (0, 0) to (N, M) describes a valid edit string, but we try to
// find the path with the most diagonals, conversely that is the path with the
// least insertions or deletions.
// Note that a path with "D" insertions/deletions is called a D-path.
// ***** THE BOX MODEL *****
// The CSS box model is based on a series of nested boxes:
// http://www.w3.org/TR/CSS21/box.html
//
// |----------------------------------------------------|
// | |
// | margin-top |
// | |
// | |-----------------------------------------| |
// | | | |
// | | border-top | |
// | | | |
// | | |--------------------------|----| | |
// | | | | | | |
// | | | padding-top |####| | |
// | | | |####| | |
// | | | |----------------| |####| | |
// | | | | | | | | |
// | ML | BL | PL | content box | PR | SW | BR | MR |
// | | | | | | | | |
// | | | |----------------| | | | |
// | | | | | | |
// | | | padding-bottom | | | |
// | | |--------------------------|----| | |
// | | | ####| | | |
// | | | scrollbar height ####| SC | | |
// | | | ####| | | |
// | | |-------------------------------| | |
// | | | |
// | | border-bottom | |
// | | | |
// | |-----------------------------------------| |
// | |
// | margin-bottom |
// | |
// |----------------------------------------------------|
//
// BL = border-left
// BR = border-right
// ML = margin-left
// MR = margin-right
// PL = padding-left
// PR = padding-right
// SC = scroll corner (contains UI for resizing (see the 'resize' property)
// SW = scrollbar width
// Creates a region like this:
// █ █ █
// ███████
// █ █ █
// ███████
// █ █ █
// ███████
// █ █ █
// LayoutTableCell is used to represent a table cell (display: table-cell).
//
// Because rows are as tall as the tallest cell, cells need to be aligned into
// the enclosing row space. To achieve this, LayoutTableCell introduces the
// concept of 'intrinsic padding'. Those 2 paddings are used to shift the box
// into the row as follows:
//
// --------------------------------
// ^ ^
// | |
// | | cell's border before
// | |
// | v
// | ^
// | |
// | | m_intrinsicPaddingBefore
// | |
// | v
// | -----------------------------
// | | |
// row | | cell's padding box |
// height | | |
// | -----------------------------
// | ^
// | |
// | | m_intrinsicPaddingAfter
// | |
// | v
// | ^
// | |
// | | cell's border after
// | |
// v v
// ---------------------------------
//
// Note that this diagram is not impacted by collapsing or separate borders
// (see 'border-collapse').
// Also there is no margin on table cell (or any internal table element).
//
// LayoutTableCell is positioned with respect to the enclosing
// LayoutTableSection. See callers of
// LayoutTableSection::setLogicalPositionForCell() for when it is placed.
// To store all last row/col edges, an extra imaginary cell is used.
//
// A grid with R rows and C columns has |2 * (R+1) * (C+1)| edges.
// Example; R=1, C=3, 2*(1+1)*(3+1) = 16 edges.
// Edges 7, 9, 11, 13, 14, 15 are unused.
//
// 1 3 5 7
// ------------------ <= edges for 3 cols X 1 row
// |0 |2 |4 |6
// | | | |
// ------------------
// | 8 | 10| 12 | 14
// | | | |
// |9 |11 |13 |15
/* The BoxShape is based on a 100x50 rectangle at 0,0. The shape-margin value is
* 10, so the shape is a rectangle (120x70 at -10,-10) with rounded corners
* (radius=10):
*
* -10,-10 110,-10
* (--------)
* | |
* (--------)
* -10,60 110,60
*/
// Tests that apps with multiple window are counted correctly.
// ______________________________________________________
// | ________ ________ ________________ ________ |
// | | | | | | | | | | |
// | | I | | I | | I + 1 | | + 5 | |
// | |_______| |_______| |_______|_______| |_______| |
// |____________________________________________________|
// The NinePieceImageGrid class is responsible for computing drawing information
// for the nine piece image.
//
// https://drafts.csswg.org/css-backgrounds/#border-image-process
//
// Given an image, a set of slices and a border area:
//
// | |
// +---+---------+---+ +------------------+
// | 1 | 7 | 4 | | border |
// --+---+---------+---+--- | +------------+ |
// | | | | | | | |
// | 3 | 9 | 6 | | | css | |
// | | image | | | | box | |
// | | | | | | | |
// --+---+---------+---+--- | | | |
// | 2 | 8 | 5 | | +------------+ |
// +---+---------+---+ | |
// | | +------------------+
//
// it generates drawing information for the nine border pieces.
// Prepares a path for a cubic Bezier curve repeated three times, yielding a
// wavy pattern that we can cut into a tiling shader (PrepareWavyTileRecord).
//
// The result ignores the local origin, line offset, and (wavy) double offset,
// so the midpoints are always at y=0.5, while the phase is shifted for either
// wavy or spelling/grammar decorations so the desired pattern starts at x=0.
//
// The start point, control points (cp1 and cp2), and end point of each curve
// form a diamond shape:
//
// cp2 cp2 cp2
// --- + + +
// | x=0
// | control |--- spelling/grammar ---|
// | point . . . . . .
// | distance . . . . . .
// | . . . . . .
// +-- y=0.5 . + . + . +
// . . . . . .
// . . . . . .
// . . . . . .
// |-------- other ---------|
// x=0
// + + +
// cp1 cp1 cp1
// |-----------|------------|
// step step
* degenerateEllipse() handles a degenerated ellipse using several lines.
*
* Let's see a following example: line to ellipse to line.
* _--^\
* ( )
* -----( )
* )
* /--------
*
* If radiusX becomes zero, the ellipse of the example is degenerated.
* _
* // P
* //
* -----//
* /
* /--------
*
* To draw the above example, need to get P that is a local maximum point.
* Angles for P are 0.5Pi and 1.5Pi in the ellipse coordinates.
*
* If radiusY becomes zero, the result is as follows.
* -----__
* --_
* ----------
* ``P
* Angles for P are 0 and Pi in the ellipse coordinates.
*
* To handle both cases, degenerateEllipse() lines to start angle, local maximum
* points(every 0.5Pi), and end angle.
// This class is the host side correspondent to the IceTransportProxy. See the
// IceTransportProxy documentation for background. This class lives on the host
// thread and proxies calls between the IceTransportProxy and the
// P2PTransportChannel (which is single-threaded).
//
// proxy thread host thread
// +------------------+ unique_ptr +------------------------------+
// | | =========> | |
// | client <-> Proxy | | Host <-> P2PTransportChannel |
// | | <--------- | |
// +------------------+ WeakPtr +------------------------------+
//
// Since the client code controls the Proxy lifetime, the Proxy has a unique_ptr
// to the Host that lives on the host thread. The unique_ptr has an
// OnTaskRunnerDeleter so that when the Proxy is destroyed a task will be queued
// to delete the Host as well (and the P2PTransportChannel with it). The Host
// needs a pointer back to the Proxy to post callbacks, and by using a WeakPtr
// any callbacks run on the proxy thread after the proxy has been deleted will
// be safely dropped.
// Tests whether idle_time_ won't be updated in Start() when there was an
// event. The timeline is something like:
// [StartEvent] [EndEvent]
// +----------+
// ^
// +-- idle_time_ --+
// v
// [TimerStart] [UpdateStatus]
// +-- kUpdateInterval --+
// In the first UpdateStatus() the idle callback should be triggered.
// Manages highlighting items while in overview. Responsible for telling
// highlightable items to show or hide their focus ring borders, when tabbing
// through highlightable items with arrow keys and trackpad swipes, or when tab
// dragging. In this context, an highlightable item can represent anything
// focusable in overview mode such as a desk textfield, saved desk button and an
// `OverviewItem`. The idea behind the movement strategy is that it should be
// possible to access any highlightable view via keyboard by pressing the tab or
// arrow keys repeatedly.
// +-------+ +-------+ +-------+
// | 0 | | 1 | | 2 |
// +-------+ +-------+ +-------+
// +-------+ +-------+ +-------+
// | 3 | | 4 | | 5 |
// +-------+ +-------+ +-------+
// +-------+
// | 6 |
// +-------+
// Example sequences:
// - Going right to left
// 0, 1, 2, 3, 4, 5, 6
// The highlight is switched to the next window grid (if available) or wrapped
// if it reaches the end of its movement sequence.
// Input buffer layout, dividing the total buffer into regions (r0 - r5):
//
// |----------------|-----------------------------------------|----------------|
//
// blockSize + kernelSize / 2
// <--------------------------------------------------------->
// r0
//
// kernelSize / 2 kernelSize / 2 kernelSize / 2 kernelSize / 2
// <---------------> <---------------> <---------------> <--------------->
// r1 r2 r3 r4
//
// blockSize
// <---------------------------------------->
// r5
// Internal leadings can be distributed to ascent and descent.
// -------------------------------------------
// | - Internal Leading (in ascent)
// |--------------------------------
// Ascent - | |
// | |
// | | - Em height
// ----------|--------------|
// | |
// Descent - |--------------------------------
// | - Internal Leading (in descent)
// -------------------------------------------
// The HarfBuzzFontCache is thread specific cache for mapping
// from |FontPlatformData| to |HarfBuzzFace|, and
// from |FontPlatformData::UniqueID()| to |HarfBuzzFontData|.
//
// |HarfBuzzFace| holds shared |HarfBuzzData| per unique id.
//
// |FontPlatformData-1| |FontPlatformData-2|
// | |
// |HarfBuzzFace-1| |HarfBuzzFace-2|
// | |
// +----------+---------+
// |
// |HarfBuzzFontData|
* Checks a right triangle. This test covers all of the trivial FloatPolygon
* accessors.
*
* 200,100
* /|
* / |
* / |
* -----
* 100,200 200,200
* FloatRoundedRect geometry for this test. Corner radii are in parens, x and y
* intercepts for the elliptical corners are noted. The rectangle itself is at
* 0,0 with width and height 100.
*
* (10, 15) x=10 x=90 (10, 20)
* (--+---------+--)
* y=15 +--| |-+ y=20
* | |
* | |
* y=85 + -| |- + y=70
* (--+---------+--)
* (25, 15) x=25 x=80 (20, 30)
// All matrices here are 3x3 matrices.
// They are stored in SkM44 which is 4x4 matrix in the following form.
// |a b c 0|
// |d e f 0|
// |g h i 0|
// |0 0 0 1|
// P2PSocketDispatcher is a per-renderer object that dispatchers all
// P2P messages received from the browser and relays all P2P messages
// sent to the browser. P2PSocketClient instances register themselves
// with the dispatcher using RegisterClient() and UnregisterClient().
//
// Relationship of classes.
//
// P2PSocketHost P2PSocketClient
// ^ ^
// | |
// v IPC v
// P2PSocketDispatcherHost <---------> P2PSocketDispatcher
//
// P2PSocketDispatcher receives and dispatches messages on the
// IO thread.
// MainThreadEventQueue implements a queue for events that need to be
// queued between the compositor and main threads. This queue is managed
// by a lock where events are enqueued by the compositor thread
// and dequeued by the main thread.
//
// Below some example flows are how the code behaves.
// Legend: B=Browser, C=Compositor, M=Main Thread, NB=Non-blocking
// BL=Blocking, PT=Post Task, ACK=Acknowledgement
//
// Normal blocking event sent to main thread.
// B C M
// ---(BL)-->
// (queue)
// ---(PT)-->
// (deque)
// <-------(ACK)------
//
// Non-blocking event sent to main thread.
// B C M
// ---(NB)-->
// (queue)
// ---(PT)-->
// (deque)
//
// Non-blocking followed by blocking event sent to main thread.
// B C M
// ---(NB)-->
// (queue)
// ---(PT)-->
// ---(BL)-->
// (queue)
// ---(PT)-->
// (deque)
// (deque)
// <-------(ACK)------
// This class allows GWP-ASan allocations to be backed by PartitionAlloc and,
// consequently, protected by MiraclePtr.
//
// GWP-ASan mainly operates at the system memory page granularity. During
// process startup, it reserves a certain number of consecutive system pages.
//
// The standard layout is as follows:
//
// +-------------------+--------
// | | ▲ ▲
// | system page 0 |(a) (c)
// | | ▼ ▼
// +-------------------+--------
// | | ▲ ▲
// | system page 1 |(b) |
// | | ▼ |
// +-------------------+--- (d) (a) inaccessible
// | | ▲ | (b) accessible
// | system page 2 |(a) | (c) initial guard page
// | | ▼ ▼ (d) allocation slot
// +-------------------+--------
// | | ▲ ▲
// | system page 3 |(b) |
// | | ▼ |
// +-------------------+--- (d)
// | | ▲ |
// | system page 4 |(a) |
// | | ▼ ▼
// |-------------------|--------
// | | ▲ ▲
// | ... |(a) (d)
//
// Unfortunately, PartitionAlloc can't provide GWP-ASan an arbitrary number of
// consecutive allocation slots. Allocations need to be grouped into 2MB super
// pages so that the allocation metadata can be easily located.
//
// Below is the new layout:
//
// +-----------------------------------
// | | ▲ ▲
// | system page 0 | | |
// | | | |
// +-------------------+ | |
// | | | |
// | ... | (e) |
// | | | |
// +-------------------+------- | |
// | | ▲ ▲ | |
// | system page k-1 |(a) (c) | |
// | | ▼ ▼ ▼ |
// +-------------------+----------- (f)
// | | ▲ ▲ |
// | system page k |(b) | |
// | | ▼ | |
// +-------------------+--- (d) |
// | | ▲ | |
// | system page k+1 |(a) | |
// | | ▼ ▼ |
// +-------------------+----------- |
// | | | (a) inaccessible
// | ... | | (b) accessible
// | | ▼ (c) initial guard page
// +----------------------------------- (d) allocation slot
// | | ▲ ▲ (e) super page metadata
// | system page m | | | (f) super page
// | | | | (g) pseudo allocation slot
// +-------------------+------- | |
// | | ▲ | |
// | ... | | (e) |
// | | | | |
// +-------------------+--- (g) | |
// | | ▲ | | |
// | system page m+k-1 |(a) | | |
// | | ▼ ▼ ▼ |
// +-------------------+----------- (f)
// | | ▲ ▲ |
// | system page m+k |(b) | |
// | | ▼ | |
// +-------------------+--- (d) |
// | | ▲ | |
// | system page m+k+1 |(a) | |
// | | ▼ ▼ |
// +-------------------+----------- |
// | | |
// | ... | |
// | | ▼
// +-------------------+---------------
//
// This means some allocation slots will be reserved to hold PA
// metadata. We exclude these pseudo slots from the GWP-ASan free list so that
// they are never used for anything other that storing the metadata.
// 2D matrix transforms:
//
// [m11 m21 0 m41] [1 0 0 Tx] [cos(R) -sin(R) 0 0] [1 K 0 0] [Sx 0 0 0]
// [m12 m22 0 m42] = [0 1 0 Ty] [sin(R) cos(R) 0 0] [0 1 0 0] [0 Sy 0 0]
// [ 0 0 1 0 ] [0 0 1 0 ] [ 0 0 1 0] [0 0 1 0] [0 0 1 0]
// [ 0 0 0 1 ] [0 0 0 1 ] [ 0 0 0 1] [0 0 0 1] [0 0 0 1]
//
//
// OC(i) = open cursor i
// RD(i, j) = read result of cursor i, which should be at item j
// CC(i) = continue cursor i
// | = wait for onsuccess on the previous OC or CC
//
// OC(1) | RD(1, 1) OC(2) | RD(2, 1) OC(3) | ... | RD(n-1, 1) CC(n) |
// RD(n, 1) CC(1) | RD(1, 2) CC(2) | RD(2, 2) CC(3) | ... | RD(n-1, 2) CC(n) |
// RD(n, 2) CC(1) | RD(1, 3) CC(2) | RD(2, 3) CC(3) | ... | RD(n-1, 3) CC(n) |
// ...
// RD(n, k-1) CC(1) | RD(1, k) CC(2) | RD(2, k) CC(3) | ... | RD(n-1, k) CC(n) |
// RD(n, k) done
// The tree appears as following, with the starred nodes dirty:
// div [relayout-common-ancestor]
// / \
// *div *div
// / /
// *div *div
/* __kernel_cos( x, y )
* kernel cos function on [-pi/4, pi/4], pi/4 ~ 0.785398164
* Input x is assumed to be bounded by ~pi/4 in magnitude.
* Input y is the tail of x.
*
* Algorithm
* 1. Since cos(-x) = cos(x), we need only to consider positive x.
* 2. if x < 2^-27 (hx<0x3E400000 0), return 1 with inexact if x!=0.
* 3. cos(x) is approximated by a polynomial of degree 14 on
* [0,pi/4]
* 4 14
* cos(x) ~ 1 - x*x/2 + C1*x + ... + C6*x
* where the remez error is
*
* | 2 4 6 8 10 12 14 | -58
* |cos(x)-(1-.5*x +C1*x +C2*x +C3*x +C4*x +C5*x +C6*x )| <= 2
* | |
*
* 4 6 8 10 12 14
* 4. let r = C1*x +C2*x +C3*x +C4*x +C5*x +C6*x , then
* cos(x) = 1 - x*x/2 + r
* since cos(x+y) ~ cos(x) - sin(x)*y
* ~ cos(x) - x*y,
* a correction term is necessary in cos(x) and hence
* cos(x+y) = 1 - (x*x/2 - (r - x*y))
* For better accuracy when x > 0.3, let qx = |x|/4 with
* the last 32 bits mask off, and if x > 0.78125, let qx = 0.28125.
* Then
* cos(x+y) = (1-qx) - ((x*x/2-qx) - (r-x*y)).
* Note that 1-qx and (x*x/2-qx) is EXACT here, and the
* magnitude of the latter is at least a quarter of x*x/2,
* thus, reducing the rounding error in the subtraction.
*/
* Input: Algorithm created box: Maximum box:
* +---------------------+ +---------------------+ +---------------------+
* | B1 | B2 | | B1 B2 | | B1 B2 |
* | | | | +-------------+ | |+-------------------+|
* |---------x-----------| | | | | || ||
* | | | | | | | || ||
* | | | | | | | || ||
* | | | | | | | || ||
* | | | | | | | || ||
* | | | | +-------------+ | |+-------------------+|
* | B4 | B3 | | B4 B3 | | B4 B3 |
* +---------------------+ +---------------------+ +---------------------+
* Creates a 2D affine transform. An affine transform performs a linear
* mapping from 2D coordinates to other 2D coordinates that preserves the
* "straightness" and "parallelness" of lines.
*
* Such a coordinate transformation can be represented by a 3 row by 3 column
* matrix with an implied last row of [ 0 0 1 ]. This matrix transforms source
* coordinates (x,y) into destination coordinates (x',y') by considering them
* to be a column vector and multiplying the coordinate vector by the matrix
* according to the following process:
* <pre>
* [ x'] [ m00 m01 m02 ] [ x ] [ m00x + m01y + m02 ]
* [ y'] = [ m10 m11 m12 ] [ y ] = [ m10x + m11y + m12 ]
* [ 1 ] [ 0 0 1 ] [ 1 ] [ 1 ]
* </pre>
* Pre-concatenates this transform with a scaling transformation,
* i.e. calculates the following matrix product:
*
* <pre>
* [sx 0 0] [m00 m01 m02]
* [ 0 sy 0] [m10 m11 m12]
* [ 0 0 1] [ 0 0 1]
* </pre>
* Class for representing and manipulating matrices.
*
* The entry that lies in the i-th row and the j-th column of a matrix is
* typically referred to as the i,j entry of the matrix.
*
* The m-by-n matrix A would have its entries referred to as:
* [ a0,0 a0,1 a0,2 ... a0,j ... a0,n ]
* [ a1,0 a1,1 a1,2 ... a1,j ... a1,n ]
* [ a2,0 a2,1 a2,2 ... a2,j ... a2,n ]
* [ . . . . . ]
* [ . . . . . ]
* [ . . . . . ]
* [ ai,0 ai,1 ai,2 ... ai,j ... ai,n ]
* [ . . . . . ]
* [ . . . . . ]
* [ . . . . . ]
* [ am,0 am,1 am,2 ... am,j ... am,n ]
* Solves a linear system where the matrix is square tri-diagonal. That is,
* given a system of equations:
*
* A * result = vecRight,
*
* this class computes result = inv(A) * vecRight, where A has the special form
* of a tri-diagonal matrix:
*
* |dia(0) sup(0) 0 0 ... 0|
* |sub(0) dia(1) sup(1) 0 ... 0|
* A =| ... |
* |0 ... 0 sub(n-2) dia(n-1) sup(n-1)|
* |0 ... 0 0 sub(n-1) dia(n)|
* The following line is the regular expression for breaking-down a
* well-formed URI reference into its components.
*
* <pre>
* ^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?
* 12 3 4 5 6 7 8 9
* </pre>
*
* The numbers in the second line above are only to assist readability; they
* indicate the reference points for each subexpression (i.e., each paired
* parenthesis). We refer to the value matched for subexpression <n> as $<n>.
* For example, matching the above expression to
* <pre>
* http://www.ics.uci.edu/pub/ietf/uri/#Related
* </pre>
* results in the following subexpression matches:
* <pre>
* $1 = http:
* $2 = http
* $3 = //www.ics.uci.edu
* $4 = www.ics.uci.edu
* $5 = /pub/ietf/uri/
* $6 = <undefined>
* $7 = <undefined>
* $8 = #Related
* $9 = Related
* </pre>
* where <undefined> indicates that the component is not present, as is the
* case for the query component in the above example. Therefore, we can
* determine the value of the five components as
* <pre>
* scheme = $2
* authority = $4
* path = $5
* query = $7
* fragment = $9
* </pre>
*
* The regular expression has been modified slightly to expose the
* userInfo, domain, and port separately from the authority.
* The modified version yields
* <pre>
* $1 = http scheme
* $2 = <undefined> userInfo -\
* $3 = www.ics.uci.edu domain | authority
* $4 = <undefined> port -/
* $5 = /pub/ietf/uri/ path
* $6 = <undefined> query without ?
* $7 = Related fragment without #
* </pre>
// In the example below, assume node A is designated as the broker. Nodes A and
// B have been connected directly by ConnectNode() calls in the application.
// Nodes A and C have been similarly connected:
//
// ┌───────┐
// ConnectNode() │ │ ConnectNode()
// ┌──────────>O A O<───────────┐
// │ │ │ │
// │ └───────┘ │
// │ │
// v ConnectNode() v ConnectNode()
// ┌───O───┐ ┌───O───┐
// │ │ │ │
// │ B │ │ C │
// │ │ │ │
// └───────┘ └───────┘
//
// ConnectNode() establishes initial portal pairs to link the two nodes
// together, illustrated above as "O"s. Once ConnectNode() returns, the
// application may immediately begin transmitting parcels through these portals.
//
// Now suppose node B creates a new local pair of portals (using OpenPortals())
// and sends one of those new portals in a parcel through its
// already-established portal to node A. The sent portal is effectively
// transferred to node A, and because its entangled peer still lives on node B
// there are now TWO portal pairs between nodes A and B:
//
// ┌───────┐
// │ │
// ┌──────────>O A O<───────────┐
// │ ┌────────>O │ │
// │ │ └───────┘ │
// │ │ │
// v v v
// ┌───O─O─┐ ┌───O───┐
// │ │ │ │
// │ B │ │ C │
// │ │ │ │
// └───────┘ └───────┘
//
// Finally, suppose now the application takes this new portal on node A and
// sends it further along, through node A's already-established portal to node
// C. Because the transferred portal's peer still lives on node B, there is now
// a portal pair spanning nodes B and C:
//
// ┌───────┐
// │ │
// ┌──────────>O A O<───────────┐
// │ │ │ │
// │ └───────┘ │
// │ │
// v v
// ┌───O───┐ ┌───O───┐
// │ │ │ │
// │ B O────────────────────────O C │
// │ │ │ │
// └───────┘ └───────┘
// The demangler is implemented to be used in async signal handlers to
// symbolize stack traces. We cannot use libstdc++'s
// abi::__cxa_demangle() in such signal handlers since it's not async
// signal safe (it uses malloc() internally).
//
// Note that this demangler doesn't support full demangling. More
// specifically, it doesn't print types of function parameters and
// types of template arguments. It just skips them. However, it's
// still very useful to extract basic information such as class,
// function, constructor, destructor, and operator names.
//
// See the implementation note in demangle.cc if you are interested.
//
// Example:
//
// | Mangled Name | The Demangler | abi::__cxa_demangle()
// |---------------|---------------|-----------------------
// | _Z1fv | f() | f()
// | _Z1fi | f() | f(int)
// | _Z3foo3bar | foo() | foo(bar)
// | _Z1fIiEvi | f<>() | void f<int>(int)
// | _ZN1N1fE | N::f | N::f
// | _ZN3Foo3BarEv | Foo::Bar() | Foo::Bar()
// | _Zrm1XS_" | operator%() | operator%(X, X)
// | _ZN3FooC1Ev | Foo::Foo() | Foo::Foo()
// | _Z1fSs | f() | f(std::basic_string<char,
// | | | std::char_traits<char>,
// | | | std::allocator<char> >)
//
// See the unit test for more examples.
// Provides a router with a new outward link to replace its existing outward
// link to some other node. Given routers X and Y on the central link, and a
// router Z as Y's inward peer:
//
// X ==== (central) ==== Y ======== Z
//
// Z sends this message to X's node to establish a new direct link to X. Both
// X's and Z's existing links to Y are left intact in a decaying state:
//
// - - - Y - - -
// / \
// X === (central) === Z
//
// The recipient of this message must send a StopProxying message to Y, as well
// as a ProxyWillStop message to Z, in order for those decaying links to be
// phased out.
//
// Z must send this message to X only after receiving a BypassPeer request from
// Y. That request signifies that X's node has been adequately prepared by Y to
// authenticate this request from Z.
* Matrix of resampling methods used:
* Fs_out (kHz)
* 8 12 16 24 48
*
* 8 C UF U UF UF
* 12 AF C UF U UF
* Fs_in (kHz) 16 D AF C UF UF
* 24 AF D AF C U
* 48 AF AF AF D C
*
* C -> Copy (no resampling)
* D -> Allpass-based 2x downsampling
* U -> Allpass-based 2x upsampling
* UF -> Allpass-based 2x upsampling followed by FIR interpolation
* AF -> AR2 filter followed by FIR interpolation
// Previous input character Current character Case
// Any Non-alphanumeric Skipped
// None - first char of input Alphanumeric Upper
// Non-letter (e.g. _ or 1) Alphanumeric Upper
// Numeric Alphanumeric Upper
// Lower letter Alphanumeric Same as current
// Upper letter Alphanumeric Lower
/// Whether it is possible or not to automatically derive trait for an item.
///
/// ```ignore
/// No
/// ^
/// |
/// Manually
/// ^
/// |
/// Yes
/// ```
///
/// Initially we assume that we can derive trait for all types and then
/// update our understanding as we learn more about each type.
//! Fix-point analyses on the IR using the "monotone framework".
//!
//! A lattice is a set with a partial ordering between elements, where there is
//! a single least upper bound and a single greatest least bound for every
//! subset. We are dealing with finite lattices, which means that it has a
//! finite number of elements, and it follows that there exists a single top and
//! a single bottom member of the lattice. For example, the power set of a
//! finite set forms a finite lattice where partial ordering is defined by set
//! inclusion, that is `a <= b` if `a` is a subset of `b`. Here is the finite
//! lattice constructed from the set {0,1,2}:
//!
//! ```text
/// The result of the `Sizedness` analysis for an individual item.
///
/// This is a chain lattice of the form:
///
/// ```ignore
/// NonZeroSized
/// |
/// DependsOnTypeParam
/// |
/// ZeroSized
/// ```
///
/// We initially assume that all types are `ZeroSized` and then update our
/// understanding as we learn more about each type.
// The same path should be used even if the focus ring was initialized with
// a rectangle and not a paragraph shape - this makes it possible to
// smoothly animate between one object and the next simply by interpolating
// points.
//
// Noncontiguous shapes should be handled by drawing multiple focus rings.
//
// The 36 points are defined as follows:
//
// 2 3------------------------------4 5
// / |
// 1 6
// | First line of paragraph |
// 0 7
// / |
// 32 33-34 35 8 9---------------10 11
// / |
// 31 Middle line of paragraph.......................... 12
// | |
// | |
// | Middle line of paragraph.......................... |
// | |
// | |
// 30 Middle line of paragraph.......................... 13
// | |
// 29 28---------27 26 17 16---------15 14
// | |
// 25 18
// | Last line of paragraph |
// 24 19
// | |
// 23 22-----------------------21 20
// If |left_| <= |right_| and |top_| <= |bottom_|, IndexRect is considered to
// hold valid indices and this can be checked using is_valid().
//
// If IndexRect is valid, it has a coverage of all the indices from |left_| to
// |right_| both inclusive and |top_| to |bottom_| both inclusive. So for
// |left_| == |right_|, num_indices_x() is 1, meaning |left_| and |right_| point
// to the same index.
//
// The following diagram shows how indices span in different quadrants and the
// positive quadrant. In the positive quadrant all indices are >= 0. The first
// index in this quadrant is (0, 0). The indices in positive quadrant represent
// the visible region and is_in_positive_quadrant() can be used to check whether
// all indices lie within this quadrant or not.
//
// │
// │
// -ve index_x │ +ve index_x
// -ve index_y │ -ve index_y
// │
// ────────────┼────────────
// │
// -ve index_x │ +ve index_x
// +ve index_y │ +ve index_y
// │
// │ (+ve Quadrant)
//
// In the following example, region has |left_| = 0, |right_| = 4, |top_| = 0
// and |bottom_| = 4. Here x indices are 0, 1, 2, 3, 4 and y indices are
// 0, 1, 2, 3, 4.
//
// x 0 1 2 3 4
// y ┌───┬───┬───┬───┬───┐
// 0 │ │ │ │ │ │
// ├───┼───┼───┼───┼───┤
// 1 │ │ │ │ │ │
// ├───┼───┼───┼───┼───┤
// 2 │ │ │ │ │ │
// ├───┼───┼───┼───┼───┤
// 3 │ │ │ │ │ │
// ├───┼───┼───┼───┼───┤
// 4 │ │ │ │ │ │
// └───┴───┴───┴───┴───┘
* Method:
* Bit by bit method using integer arithmetic. (Slow, but portable)
* 1. Normalization
* Scale x to y in [1,4) with even powers of 2:
* find an integer k such that 1 <= (y=x*2^(2k)) < 4, then
* sqrt(x) = 2^k * sqrt(y)
* 2. Bit by bit computation
* Let q = sqrt(y) truncated to i bit after binary point (q = 1),
* i 0
* i+1 2
* s = 2*q , and y = 2 * ( y - q ). (1)
* i i i i
*
* To compute q from q , one checks whether
* i+1 i
*
* -(i+1) 2
* (q + 2 ) <= y. (2)
* i
* -(i+1)
* If (2) is false, then q = q ; otherwise q = q + 2 .
* i+1 i i+1 i
*
* With some algebraic manipulation, it is not difficult to see
* that (2) is equivalent to
* -(i+1)
* s + 2 <= y (3)
* i i
*
* The advantage of (3) is that s and y can be computed by
* i i
* the following recurrence formula:
* if (3) is false
*
* s = s , y = y ; (4)
* i+1 i i+1 i
*
* otherwise,
* -i -(i+1)
* s = s + 2 , y = y - s - 2 (5)
* i+1 i i+1 i i
*
* One may easily use induction to prove (4) and (5).
* Note. Since the left hand side of (3) contain only i+2 bits,
* it does not necessary to do a full (53-bit) comparison
* in (3).
* 3. Final rounding
* After generating the 53 bits result, we compute one more bit.
* Together with the remainder, we can decide whether the
* result is exact, bigger than 1/2ulp, or less than 1/2ulp
* (it will never equal to 1/2ulp).
* The rounding mode can be detected by checking whether
* huge + tiny is equal to huge, and whether huge - tiny is
* equal to huge for some floating point number "huge" and "tiny".
*
* Special cases:
* sqrt(+-0) = +-0 ... exact
* sqrt(inf) = inf
* sqrt(-ve) = NaN ... with invalid signal
* sqrt(NaN) = NaN ... with invalid signal for signaling NaN
// This module implements Identifier, a short-optimized string allowed to
// contain only the ASCII characters hyphen, dot, 0-9, A-Z, a-z.
//
// As of mid-2021, the distribution of pre-release lengths on crates.io is:
//
// length count length count length count
// 0 355929 11 81 24 2
// 1 208 12 48 25 6
// 2 236 13 55 26 10
// 3 1909 14 25 27 4
// 4 1284 15 15 28 1
// 5 1742 16 35 30 1
// 6 3440 17 9 31 5
// 7 5624 18 6 32 1
// 8 1321 19 12 36 2
// 9 179 20 2 37 379
// 10 65 23 11
//
// and the distribution of build metadata lengths is:
//
// length count length count length count
// 0 364445 8 7725 18 1
// 1 72 9 16 19 1
// 2 7 10 85 20 1
// 3 28 11 17 22 4
// 4 9 12 10 26 1
// 5 68 13 9 27 1
// 6 73 14 10 40 5
// 7 53 15 6
//
// Therefore it really behooves us to be able to use the entire 8 bytes of a
// pointer for inline storage. For both pre-release and build metadata there are
// vastly more strings with length exactly 8 bytes than the sum over all lengths
// longer than 8 bytes.
//
// To differentiate the inline representation from the heap allocated long
// representation, we'll allocate heap pointers with 2-byte alignment so that
// they are guaranteed to have an unset least significant bit. Then in the repr
// we store for pointers, we rotate a 1 into the most significant bit of the
// most significant byte, which is never set for an ASCII byte.
//
// Inline repr:
//
// 0xxxxxxx 0xxxxxxx 0xxxxxxx 0xxxxxxx 0xxxxxxx 0xxxxxxx 0xxxxxxx 0xxxxxxx
//
// Heap allocated repr:
//
// 1ppppppp pppppppp pppppppp pppppppp pppppppp pppppppp pppppppp pppppppp 0
// ^ most significant bit least significant bit of orig ptr, rotated out ^
//
// Since the most significant bit doubles as a sign bit for the similarly sized
// signed integer type, the CPU has an efficient instruction for inspecting it,
// meaning we can differentiate between an inline repr and a heap allocated repr
// in one instruction. Effectively an inline repr always looks like a positive
// i64 while a heap allocated repr always looks like a negative i64.
// Verify that non-overlapping windows have a VISIBLE occlusion state.
// _____ _____
// | | | |
// |____| |____|
// The rectangle's position is calculated by dividing the space in areas defined
// by the |reference|'s diagonals and finding the area |rectangle|'s center
// point belongs. If the |rectangle| in the calculated layout does not share a
// part of the bounds with the |reference|, the |rectangle| position in set to
// the more suitable neighboring position (e.g. if |rectangle| is completely
// over the |reference| top bound, it will be set to TOP) and the layout is
// recalculated with the new position. This is to handle the case where the
// rectangle shares an edge with the reference, but it's center is not in the
// same area as the reference's edge, e.g.
//
// +---------------------+
// | |
// | REFERENCE |
// | |
// | |
// +---------------------+
// +-------------------------------------------------+
// | RECTANGLE x |
// +-------------------------------------------------+
//
// The rectangle shares an edge with the reference's bottom edge, but its
// center point is in the left area.
// DisplayPlacement specifies where the display (D) is placed relative to
// parent (P) display. In the following example, D given by |display_id| is
// placed at the left side of P given by |parent_display_id|, with a negative
// offset and a top-left offset reference.
//
// + +--------+
// offset | | |
// + | D +--------+
// | | |
// +--------+ P |
// | |
// +--------+
// Returns a DisplayPlacement for |current| relative to |parent|.
// Note that DisplayPlacement's are always in DIPs, so this also performs the
// required scaling.
//
// Examples (The offset is indicated by the arrow.):
// Scaled and Unscaled Coordinates
// +--------------+ + Since both DisplayInfos are of the same scale
// | | | factor, relative positions remain the same.
// | Parent | V
// | 1x +----------+
// | | |
// +--------------+ Current |
// | 1x |
// +----------+
//
// Unscaled Coordinates
// +--------------+ The 2x DisplayInfo is offset to maintain a
// | | similar neighboring relationship with the 1x
// | Parent | parent. Current's position is based off of the
// | 1x +----------+ percentage position along its parent. This
// | | | percentage position is preserved in the scaled
// +--------------+ Current | coordinates.
// | 2x |
// +----------+
// Scaled Coordinates
// +--------------+ +
// | | |
// | Parent | V
// | 1x +-----+
// | + C 2x|
// +--------------+-----+
//
//
// Unscaled Coordinates
// +--------------+ The parent DisplayInfo has a 2x scale factor.
// | | The offset is adjusted to maintain the
// | | relative positioning of the 1x DisplayInfo in
// | Parent +----------+ the scaled coordinate space. Current's
// | 2x | | position is based off of the percentage
// | | Current | position along its parent. This percentage
// | | 1x | position is preserved in the scaled
// +--------------+ | coordinates.
// | |
// +----------+
// Scaled Coordinates
// +-------+ +
// | | V
// | Parent+----------+
// | 2x | |
// +-------+ Current |
// | 1x |
// | |
// | |
// +----------+
//
// Unscaled Coordinates
// +----------+ In this case, parent lies between the top and
// | | bottom of parent. The roles are reversed when
// +-------+ | this occurs, and current is placed to maintain
// | | Current | parent's relative position along current.
// | Parent| 1x |
// | 2x | |
// +-------+ |
// +----------+
// Scaled Coordinates
// ^ +----------+
// | | |
// + +----+ |
// |Prnt| Current |
// | 2x | 1x |
// +----+ |
// | |
// +----------+
//
// Scaled and Unscaled Coordinates
// +--------+ If the two DisplayInfos are bottom aligned or
// | | right aligned, the DisplayPlacement will
// | +--------+ have an offset of 0 relative to the
// | | | bottom-right of the DisplayInfo.
// | | |
// +--------+--------+
// Five 1x displays laid out as follows (not to scale):
// +---------+----------------+
// | | |
// | 0 | |
// | | 1 |
// +---------+ |
// | 2 | |
// | +----------------+-----+
// +---------+ | |
// | 3 |
// | |
// +--+--+
// |4 |
// +--+
// Text baseline offset types.
// Figure of font metrics:
// +--------+--------+------------------------+-------------+
// | | | internal leading | SUPERSCRIPT |
// | | +------------+-----------| |
// | | ascent | | SUPERIOR |-------------+
// | height | | cap height |-----------|
// | | | | INFERIOR |-------------+
// | |--------+------------+-----------| |
// | | descent | SUBSCRIPT |
// +--------+---------------------------------+-------------+
// In this example, the text is rendered in a highlight that stretches above and
// below the height of the H as well as to the left and right of the text
// (|desired_visual_padding| = {2, 2, 2, 2}). Note that the descender of the 'y'
// overlaps with the padding, as it is outside the capital letter box.
//
// The resulting padding is {1, 2, 1, 2}.
//
// . . . . . . . . . . | actual top
// . . | | leading space
// . | | _ . | font | capital
// . |--| /_\ \ / . | height | height
// . | | \_ \/ . | |
// . / . | | descender
// . . . . . . . . . . | actual bottom
// ___ ___
// actual actual
// left right
// This is the underlying data structure of Transform. Don't use this type
// directly.
//
// Throughout this class, we will be speaking in column vector convention.
// i.e. Applying a transform T to vector V is T * V.
// The components of the matrix and the vector look like:
// \ col
// r \ 0 1 2 3
// o 0 | scale_x skew_xy skew_xz trans_x | | x |
// w 1 | skew_yx scale_y skew_yz trans_y | * | y |
// 2 | skew_zx skew_zy scale_z trans_z | | z |
// 3 | persp_x persp_y persp_z persp_w | | w |
//
// Note that the names are just for remembering and don't have the exact
// meanings when other components exist.
//
// The components correspond to the DOMMatrix mij (i,j = 1..4) components:
// i = col + 1
// j = row + 1
// <-a->
// [ ***** ]
// ____ | |
// <-a-> <------b----->
// a: object_width
// b: frame_width
// *: animating object
//
// - the animation goes from "[" to "]" repeatedly.
// - the animation offset is at first "|"
// For example, the following configuration shows 2 different screens being
// initialized separately.
// ------------- -------------
// | Connector | | Connector |
// | HDMI | | VGA |
// ------------- -------------
// ^ ^
// | |
// ------------- -------------
// | Encoder1 | | Encoder2 |
// ------------- -------------
// ^ ^
// | |
// ------------- -------------
// | CRTC1 | | CRTC2 |
// ------------- -------------
//
// In the following configuration 2 different screens are associated with the
// same CRTC, so on scanout the same framebuffer will be displayed on both
// monitors.
// ------------- -------------
// | Connector | | Connector |
// | HDMI | | VGA |
// ------------- -------------
// ^ ^
// | |
// ------------- -------------
// | Encoder1 | | Encoder2 |
// ------------- -------------
// ^ ^
// | |
// ----------------------
// | CRTC1 |
// ----------------------
//
// Note that it is possible to have more connectors than CRTCs which means that
// only a subset of connectors can be active independently, showing different
// framebuffers. Though, in this case, it would be possible to have all
// connectors active if some use the same CRTC to mirror the display.
// ___________
// | 1 |
// |___________|
// | 3 | 4 | 5 | <-- 2 (encapsulates 3, 4 and 5)
// |___|___|___|
// | 7 | 8 | <-- 6 (encapsulates 7 and 8)
// |_______|___|
//
// |r_0| encapsulates 1, 2 and 6.
// Test that wm::RecreateLayers() recreates the layers for all child windows and
// all child views and that the z-order of the recreated layers matches that of
// the original layers.
// Test hierarchy:
// w1
// +-- v1
// +-- v2 (no layer)
// +-- v3 (no layer)
// +-- v4
// +-- w2
// +-- v5
// +-- v6
// +-- v7
// +-- v8
// +-- v9
// Test if SaveLayer and Restore work together.
// 1. Move cursor to (25, 25) draw a black rect of size 25x25.
// 2. save layer, move the cursor by (100, 100) or to point (125, 125), draw a
// red rect of size 25x25.
// 3. Restore layer, so the cursor moved back to (25, 25), move cursor by (100,
// 0) or at the point (125, 25), draw a yellow rect of size 25x25.
// (25, 25)
// +---+
// | |
// +---+
// (25, 125) (125, 125)
// +---+ +---+
// | | | |
// +---+ +---+
// Opacity -->|
// RoundedCorners ----->|
// This class provides states to manage life cycle of a task and given below is
// how it is used by TaskGraphWorkQueue to process life cycle of a task.
// Task is in NEW state when it is created. When task is added to
// |ready_to_run_tasks| then its state is changed to SCHEDULED. Task can be
// canceled from NEW state (not yet scheduled to run) or from SCHEDULED state,
// when new ScheduleTasks() is triggered and its state is changed to CANCELED.
// When task is about to run it is added |running_tasks| and its state is
// changed to RUNNING. Once task finishes running, its state is changed to
// FINISHED. Both CANCELED and FINISHED tasks are added to |completed_tasks|.
// ╔═════╗
// +------║ NEW ║------+
// | ╚═════╝ |
// v v
// ┌───────────┐ ╔══════════╗
// │ SCHEDULED │------> ║ CANCELED ║
// └───────────┘ ╚══════════╝
// |
// v
// ┌─────────┐ ╔══════════╗
// │ RUNNING │-------> ║ FINISHED ║
// └─────────┘ ╚══════════╝
// Tests the following tricky case:
// - Scrolling Layer A with scrolling children:
// - Ordinary Layer B with NonFastScrollableRegion
// - Ordinary Layer C
//
// +---------+
// +---------| |+
// | Layer A | ||
// | +-----+-----+ ||
// | | Layer C | ||
// | +-----+-----+ ||
// | | Layer B ||
// +---------| |+
// +---------+
//
//
// Both B and C scroll with A but overlap each other and C appears above B. If
// we try scrolling over C, we need to check if we intersect the NFSR on B
// because C may not be fully opaque to hit testing (e.g. the layer may be for
// |pointer-events:none| or be a squashing layer with "holes").
* Helper class for creating a view with three labels and an icon.
*
* +--------------+------------+
* | TOP LABEL | |
* | MID LABEL | ICON |
* | BOTTOM LABEL | |
* +--------------+------------+
*
* Used for showing the uneditable parts of server cards. For example:
*
* +--------------+------------+
* | Visa***1234 | |
* | First Last | VISA |
* | Exp: 12/2020 | |
* +--------------+------------+
// Given a vector of rects that all overlap, already sorted from top to bottom
// and left to right, split them into three shapes covering the top, middle,
// and bottom of a "paragraph shape".
//
// Input:
//
// +---+---+
// | 1 | 2 |
// +---------------------+---+---+
// | 3 |
// +--------+---------------+----+
// | 4 | 5 |
// +--------+---------------+--+
// | 6 |
// +---------+-----------------+
// | 7 |
// +---------+
//
// Output:
//
// +-------+
// | Top |
// +---------------------+-------+
// | |
// | |
// | Middle |
// | |
// | |
// +---------+-------------------+
// | Bottom |
// +---------+
//
// When there's no clear "top" or "bottom" segment, split the overall rect
// evenly so that some of the area still fits into the "top" and "bottom"
// segments.
// CertificateManagerModel is created on the UI thread. It needs a
// NSSCertDatabase handle (and on ChromeOS it needs to get the TPM status) which
// needs to be done on the IO thread.
//
// The initialization flow is roughly:
//
// UI thread IO Thread
//
// CertificateManagerModel::Create
// \--------------------------------------v
// CertificateManagerModel::GetCertDBOnIOThread
// |
// NssCertDatabaseGetter
// |
// CertificateManagerModel::DidGetCertDBOnIOThread
// v--------------------------------------/
// CertificateManagerModel::DidGetCertDBOnUIThread
// |
// new CertificateManagerModel
// |
// callback
// ListCerts and related functions are implemented to make sure the above
// requirements are respected. Here's a diagram of the interaction between UI
// and IO threads.
//
// UI Thread IO Thread
//
// ListCerts
// |
// NssService::CreateNSSCertDatabaseGetterForIOThread
// |
// \----------------------------v
// ListCertsWithDbGetterOnIO
// |
// database_getter.Run()
// |
// ListCertsOnIO
// |
// ListCertsInSlot
// |
// PostListedCertsBackToOriginalTaskRunner
// |
// v----------------------------/
// Process certs / Repeat ListCerts for system slot
// ListCerts and related functions are implemented to make sure the above
// requirements are respected. Here's a diagram of the interaction between UI
// and IO threads.
//
// UI Thread IO Thread
//
// IsSystemSlotAvailable
// |
// run_loop.QuitClosure
// |
// NssService::CreateNSSCertDatabaseGetterForIOThread
// |
// \--------------------------------v
// IsSystemSlotAvailableWithDbGetterOnIO
// |
// database_getter.Run
// |
// IsSystemSlotAvailableOnIO
// |
// GetSystemSlot
// |
// quit_closure.Run
// A view that shows display options for input overlay, this is the entry
// point for customizing key bindings and turning the feature on/off.
//
// The class reports back to DisplayOverlayController, who owns this.
// +---------------------------------+
// | Game Controls |Alpha| [ o] [x] |
// | |
// | Key mapping [Edit] |
// | |
// | Show key mapping [ o] |
// | |
// | Send feedback |
// +---------------------------------+
// Draw the cross shape path with round corner. It starts from bottom to up on
// line #0 and draws clock-wisely.
// |overall_length| is the total length of one side excluding the stroke
// thickness. |mid_length| is the length of the middle part which is close to
// the one third of |overall_length|.
// __
// _0^ |__
// |__ __|
// |__|
// An interface that defines an out-of-box-experience (OOBE) or login screen
// host. It contains code specific to the login UI implementation.
//
// The inheritance graph is as folllows:
//
// LoginDisplayHost
// / |
// LoginDisplayHostCommon MockLoginDisplayHost
// / |
// LoginDisplayHostMojo LoginDisplayHostWebUI
//
//
// - LoginDisplayHost defines the generic interface.
// - LoginDisplayHostCommon is UI-agnostic code shared between the views and
// webui hosts.
// - MockLoginDisplayHost is for tests.
// - LoginDisplayHostMojo is for the login screen which is implemented in Ash.
// TODO(estade): rename LoginDisplayHostMojo since it no longer uses Mojo.
// - LoginDisplayHostWebUI is for OOBE, which is written in HTML/JS/CSS.
// This class manages the behavior of the Oobe UI dialog.
// And its lifecycle is managed by the widget created in Show().
// WebDialogView<----delegate_----OobeUIDialogDelegate
// |
// |
// V
// clientView---->Widget's view hierarchy
// This is used to fetch discounts for active Carts in cart_db. It starts
// to work after calling Start() and continue to work util Chrome is finished.
// The flow looks as follow:
//
// UI Thread | backend_task_runner_
// ===========================================
// 1) Start |
// 2) PrepareToFetch (delay)|
// 3) ReadyToFetch |
// 4) | FetchInBackground
// 5) | DoneFetchingInBackground
// 6) AfterDiscountFetched |
// 7) OnUpdatingDiscounts |
// 8) Start |
// 0123456789
// mmmm
// + ddd
// = nmmmmndddn
// The attribution text box's coordinates must be baked into the Lottie file.
// However, UX requires that it is positioned such that the bottom-right of the
// text box has 24 pixels of padding from the bottom-right of the view.
// Additionally, the text box's width should extend from the left side of the
// view all the way to (width - 24) to account for long attributions.
// Visually, it looks like this:
//
// View:
// +-----------------------------------------------+
// | |
// | |
// | |
// | |
// | |
// | |
// | |
// | |
// | |
// |-------------------------------------------+ |
// | Attribution Text| |
// |-------------------------------------------+ |
// | |
// +-----------------------------------------------+
//
// The animation already right-aligns the text within the box, but since the
// view's boundaries can vary from device to device, it is impossible to
// specify text box coordinates in the lottie file that work for all devices.
// This is a profile-scoped implementation of `AccountManagerFacade`, intended
// to be used by the identity manager. Account updates generally follow the
// path:
//
// AccountManagerFacadeImpl
// |
// V
// AccountProfileMapper
// |
// V
// ProfileAccountManager
// |
// V
// IdentityManager
//
// The `ProfileAccountManager` is not intended to have much logic and mostly
// forwards calls to the `AccountProfileMapper`.
// Init() must be invoked before any other method. It starts a "long" interval.
// After that, StartShortInterval() and EndInterval() should be invoked in
// alternance to start a "short" interval, end both intervals and start a new
// "long" interval:
//
// | Long | Long | Long |
// | Short | | Short | | Short |
// Init SSI EI SSI EI SSI EI
//
// SSI = StartShortInterval
// EI = EndIntervals
//
// See //components/power_metrics/resource_coalition_mac.h for more details
// about resource coalitions.
// Initialization basically follows these steps:
// 1) Get some info from user_manager::UserManager about the User for this
// profile.
// 2) Tell nss_util to initialize the software slot for this profile.
// 3) Wait for the TPM module to be loaded by nss_util if it isn't already.
// 4) Ask CryptohomePkcs11Client which TPM slot id corresponds to this profile.
// 5) Tell nss_util to use that slot id on the TPM module.
//
// Some of these steps must happen on the UI thread, others must happen on the
// IO thread:
// UI thread IO Thread
//
// NssService::NssService
// |
// ProfileHelper::Get()->GetUserByProfile()
// \---------------------------------------v
// StartNSSInitOnIOThread
// |
// crypto::InitializeNSSForChromeOSUser
// |
// crypto::IsTPMTokenEnabled
// |
// StartTPMSlotInitializationOnIOThread
// v---------------------------------------/
// GetTPMInfoForUserOnUIThread
// |
// ash::TPMTokenInfoGetter::Start
// |
// DidGetTPMInfoForUserOnUIThread
// \---------------------------------------v
// crypto::InitializeTPMForChromeOSUser
// Generates a set of integers drawn from a mesa shaped probability distribution
// with replacement.
//
// The PDF is:
//
// ⎧ 0 ... if x < 0
// ⎪
// P(x) = ⎨ λ ... if 0 <= x < T
// ⎪
// ⎩ (1 - τ) * γ * (1 - γ)^{X - T} ... otherwise
//
// where
//
// T = Value at which the PDF switches from a uniform to a geometric
// distribution. Referred to in code as the `pivot_point`.
//
// τ = Ratio of probability between linear region of the PDF. I.e. if τ = 0.9,
// then 90% of the probability space is in the linear region. The ratio is
// referred to in code as `dist_ratio`.
//
// γ = Parameter of the geometric distribution.
//
// τ
// λ = ───
// T
//
// In otherwords, the PDF is uniform up to T with a probability of λ, and then
// switches to a geometric distribution with parameter γ that extends to
// infinity.
//
// It looks like this in the form of a graph which should make a little bit more
// sense.
//
// P(x) ▲
// │
// probability λ│┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┬,
// density │ uniform ┊ L geometric
// │ distribution ┊ "._ distribution
// │ ┊ `--..______
// └────────────────┴──────────────────▶ x
// 0 T
//
// Why this odd combination of disjoint probability distributions?
//
// Such a distribution is useful when you want to select some set of elements
// uniformly up to a threshold, but want to allow for a tail distribution that
// extends arbitrarily past that range.
* |optionLabel_| toggle is enabled:
* +-------------------------------------------------+
* | Category |<-- Not defined here
* | |
* | optionLabel_ ( O) |
* | optionDescription_ |
* | |
* | subOptionLabel ( O) |<-- SubOptionMode.PREF
* | subOptionDescription | (optional)
* | |
* +-------------------------------------------------+
*
* |optionLabel_| toggle is disabled:
* +-------------------------------------------------+
* | Category |<-- Not defined here
* | |
* | optionLabel_ (O ) |
* | optionDescription_ |
* | |
* | subOptionLabel (O ) |<-- Toggle is off and
* | subOptionDescription | disabled; or hidden
* | |
* +-------------------------------------------------+
// Ensure that sequential focus navigation (advancing focused elements with
// <tab> and <shift-tab>) works across cross-process subframes.
// The test sets up six inputs fields in a page with two cross-process
// subframes:
// child1 child2
// /------------\ /------------\.
// | 2. <input> | | 4. <input> |
// 1. <input> | 3. <input> | | 5. <input> | 6. <input>
// \------------/ \------------/.
//
// The test then presses <tab> six times to cycle through focused elements 1-6.
// The test then repeats this with <shift-tab> to cycle in reverse order.
* Coordinates horizontal alignment of the tail suggestions.
* Tail suggestions are aligned to
* - the user input in the Omnibox, when possible,
* - to each other (left edge) when longest tail suggestion makes it impossible to align it to
* user input.
*
* Examples:
* 1. Aligned to User input:
* ( User Query In Omni )
* [ ... Omnibox ]
* [ ... Omnibox Android ]
*
* 2. Aligned to longest suggestion:
* ( Longer User Query In The Omni )
* [ ... Omnibox ]
* [ ... Omnibox Android]
* This class takes care of the various dialogs that must be shown when the user changes the
* account they are syncing to (either directly, or by signing in to a new account). Most of the
* complexity is due to many of the decisions getting answered through callbacks.
*
* This class progresses along the following state machine:
*
* E-----\ G--\
* ^ | ^ |
* | v | v
* A->B->C->D->+->F->H
* | ^
* v |
* \--------/
*
* Where:
* A - Start
* B - Decision: progress to C if the user signed in previously to a different account, F otherwise.
* C - Decision: progress to E if we are switching from a managed account, D otherwise.
* D - Action: show Import Data Dialog.
* E - Action: show Switching from Managed Account Dialog.
* F - Decision: progress to G if we are switching to a managed account, H otherwise.
* G - Action: show Switching to Managed Account Dialog.
* H - End: perform {@link ConfirmImportSyncDataDialogCoordinator.Listener#onConfirm} with the
* result of the Import Data Dialog, if displayed or true if switching from a managed account.
// The view that is used as a content view of the permissions subpages in page
// info. It contains information about the permission (icon, title, state label)
// and controls to change the permission state (toggle, checkbox and manage
// button).
// *---------------------------------------------------------------*
// | Icon | Title | Toggle |
// | | State label | |
// | | | |
// | | "Remember this setting" checkbox | |
// |---------------------------------------------------------------|
// | Manage button |
// *---------------------------------------------------------------*
// Adds the product logo to the footer.
// +---------------------------------------------------------+
// | (•) chrome | PAY | CANCEL |
// +---------------------------------------------------------+
// Creates the body.
// +------------------------------------------+
// | [header image] |
// | |
// | No matching credentials text |
// | [OK] |
// +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~+
// Creates the header view, which contains the icon and a progress bar. The icon
// covers the whole header view with the progress bar at the top of the header.
// +------------------------------------------+
// |===============progress bar===============|
// | |
// | icon |
// +------------------------------------------+
* When resolving a BTF_KIND_PTR, it needs to keep resolving if
* it is referring to another BTF_KIND_PTR. Otherwise, we cannot
* detect a pointer loop, e.g.:
* BTF_KIND_CONST -> BTF_KIND_PTR -> BTF_KIND_CONST -> BTF_KIND_PTR +
* ^ |
* +-----------------------------------------+
* As the trie is empty initially, the new node (1) will be places as root
* node, denoted as (R) in the example below. As there are no other node, both
* child pointers are %NULL.
*
* +----------------+
* | (1) (R) |
* | 192.168.0.0/16 |
* | value: 1 |
* | [0] [1] |
* +----------------+
*
* Next, let's add a new node (2) matching 192.168.0.0/24. As there is already
* a node with the same data and a smaller prefix (ie, a less specific one),
* node (2) will become a child of (1). In child index depends on the next bit
* that is outside of what (1) matches, and that bit is 0, so (2) will be
* child[0] of (1):
*
* +----------------+
* | (1) (R) |
* | 192.168.0.0/16 |
* | value: 1 |
* | [0] [1] |
* +----------------+
* |
* +----------------+
* | (2) |
* | 192.168.0.0/24 |
* | value: 2 |
* | [0] [1] |
* +----------------+
*
* The child[1] slot of (1) could be filled with another node which has bit #17
* (the next bit after the ones that (1) matches on) set to 1. For instance,
* 192.168.128.0/24:
*
* +----------------+
* | (1) (R) |
* | 192.168.0.0/16 |
* | value: 1 |
* | [0] [1] |
* +----------------+
* | |
* +----------------+ +------------------+
* | (2) | | (3) |
* | 192.168.0.0/24 | | 192.168.128.0/24 |
* | value: 2 | | value: 3 |
* | [0] [1] | | [0] [1] |
* +----------------+ +------------------+
*
* Let's add another node (4) to the game for 192.168.1.0/24. In order to place
* it, node (1) is looked at first, and because (4) of the semantics laid out
* above (bit #17 is 0), it would normally be attached to (1) as child[0].
* However, that slot is already allocated, so a new node is needed in between.
* That node does not have a value attached to it and it will never be
* returned to users as result of a lookup. It is only there to differentiate
* the traversal further. It will get a prefix as wide as necessary to
* distinguish its two children:
*
* +----------------+
* | (1) (R) |
* | 192.168.0.0/16 |
* | value: 1 |
* | [0] [1] |
* +----------------+
* | |
* +----------------+ +------------------+
* | (4) (I) | | (3) |
* | 192.168.0.0/23 | | 192.168.128.0/24 |
* | value: --- | | value: 3 |
* | [0] [1] | | [0] [1] |
* +----------------+ +------------------+
* | |
* +----------------+ +----------------+
* | (2) | | (5) |
* | 192.168.0.0/24 | | 192.168.1.0/24 |
* | value: 2 | | value: 5 |
* | [0] [1] | | [0] [1] |
* +----------------+ +----------------+
*
* 192.168.1.1/32 would be a child of (5) etc.
*
* An intermediate node will be turned into a 'real' node on demand. In the
* example above, (4) would be re-used if 192.168.0.0/23 is added to the trie.
*
* A fully populated trie would have a height of 32 nodes, as the trie was
* created with a prefix length of 32.
*
* The lookup starts at the root node. If the current node matches and if there
* is a child that can be used to become more specific, the trie is traversed
* downwards. The last node in the traversal that is a non-intermediate one is
* returned.
* In futex wake up scenarios where no tasks are blocked on a futex, taking
* the hb spinlock can be avoided and simply return. In order for this
* optimization to work, ordering guarantees must exist so that the waiter
* being added to the list is acknowledged when the list is concurrently being
* checked by the waker, avoiding scenarios like the following:
*
* CPU 0 CPU 1
* val = *futex;
* sys_futex(WAIT, futex, val);
* futex_wait(futex, val);
* uval = *futex;
* *futex = newval;
* sys_futex(WAKE, futex);
* futex_wake(futex);
* if (queue_empty())
* return;
* if (uval == val)
* lock(hash_bucket(futex));
* queue();
* unlock(hash_bucket(futex));
* schedule();
*
* This would cause the waiter on CPU 0 to wait forever because it
* missed the transition of the user space value from val to newval
* and the waker did not find the waiter in the hash bucket queue.
*
* The correct serialization ensures that a waiter either observes
* the changed user space value before blocking or is woken by a
* concurrent waker:
*
* CPU 0 CPU 1
* val = *futex;
* sys_futex(WAIT, futex, val);
* futex_wait(futex, val);
*
* waiters++; (a)
* smp_mb(); (A) <-- paired with -.
* |
* lock(hash_bucket(futex)); |
* |
* uval = *futex; |
* | *futex = newval;
* | sys_futex(WAKE, futex);
* | futex_wake(futex);
* |
* `--------> smp_mb(); (B)
* if (uval == val)
* queue();
* unlock(hash_bucket(futex));
* schedule(); if (waiters)
* lock(hash_bucket(futex));
* else wake_waiters(futex);
* waiters--; (b) unlock(hash_bucket(futex));
*
* Where (A) orders the waiters increment and the futex value read through
* atomic operations (see futex_hb_waiters_inc) and where (B) orders the write
* to futex and the waiters read (see futex_hb_waiters_pending()).
*
* This yields the following case (where X:=waiters, Y:=futex):
*
* X = Y = 0
*
* w[X]=1 w[Y]=1
* MB MB
* r[Y]=y r[X]=x
*
* Which guarantees that x==0 && y==0 is impossible; which translates back into
* the guarantee that we cannot both miss the futex variable change and the
* enqueue.
* Example based on real values:
*
* Example 1 : MMC write/read interrupt interval:
*
* 223947, 1240, 1384, 1386, 1386,
* 217416, 1236, 1384, 1386, 1387,
* 214719, 1241, 1386, 1387, 1384,
* 213696, 1234, 1384, 1386, 1388,
* 219904, 1240, 1385, 1389, 1385,
* 212240, 1240, 1386, 1386, 1386,
* 214415, 1236, 1384, 1386, 1387,
* 214276, 1234, 1384, 1388, ?
*
* For each element, apply ilog2(value)
*
* 15, 8, 8, 8, 8,
* 15, 8, 8, 8, 8,
* 15, 8, 8, 8, 8,
* 15, 8, 8, 8, 8,
* 15, 8, 8, 8, 8,
* 15, 8, 8, 8, 8,
* 15, 8, 8, 8, 8,
* 15, 8, 8, 8, ?
*
* Max period of 5, we take the last (max_period * 3) 15 elements as
* we can be confident if the pattern repeats itself three times it is
* a repeating pattern.
*
* 8,
* 15, 8, 8, 8, 8,
* 15, 8, 8, 8, 8,
* 15, 8, 8, 8, ?
*
* Suffixes are:
*
* 1) 8, 15, 8, 8, 8 <- max period
* 2) 8, 15, 8, 8
* 3) 8, 15, 8
* 4) 8, 15 <- min period
*
* From there we search the repeating pattern for each suffix.
*
* buffer: 8, 15, 8, 8, 8, 8, 15, 8, 8, 8, 8, 15, 8, 8, 8
* | | | | | | | | | | | | | | |
* 8, 15, 8, 8, 8 | | | | | | | | | |
* 8, 15, 8, 8, 8 | | | | |
* 8, 15, 8, 8, 8
*
* When moving the suffix, we found exactly 3 matches.
*
* The first suffix with period 5 is repeating.
*
* The next event is (3 * max_period) % suffix_period
*
* In this example, the result 0, so the next event is suffix[0] => 8
*
* However, 8 is the index in the array of exponential moving average
* which was calculated on the fly when storing the values, so the
* interval is ema[8] = 1366
*
*
* Example 2:
*
* 4, 3, 5, 100,
* 3, 3, 5, 117,
* 4, 4, 5, 112,
* 4, 3, 4, 110,
* 3, 5, 3, 117,
* 4, 4, 5, 112,
* 4, 3, 4, 110,
* 3, 4, 5, 112,
* 4, 3, 4, 110
*
* ilog2
*
* 0, 0, 0, 4,
* 0, 0, 0, 4,
* 0, 0, 0, 4,
* 0, 0, 0, 4,
* 0, 0, 0, 4,
* 0, 0, 0, 4,
* 0, 0, 0, 4,
* 0, 0, 0, 4,
* 0, 0, 0, 4
*
* Max period 5:
* 0, 0, 4,
* 0, 0, 0, 4,
* 0, 0, 0, 4,
* 0, 0, 0, 4
*
* Suffixes:
*
* 1) 0, 0, 4, 0, 0
* 2) 0, 0, 4, 0
* 3) 0, 0, 4
* 4) 0, 0
*
* buffer: 0, 0, 4, 0, 0, 0, 4, 0, 0, 0, 4, 0, 0, 0, 4
* | | | | | | X
* 0, 0, 4, 0, 0, | X
* 0, 0
*
* buffer: 0, 0, 4, 0, 0, 0, 4, 0, 0, 0, 4, 0, 0, 0, 4
* | | | | | | | | | | | | | | |
* 0, 0, 4, 0, | | | | | | | | | | |
* 0, 0, 4, 0, | | | | | | |
* 0, 0, 4, 0, | | |
* 0 0 4
*
* Pattern is found 3 times, the remaining is 1 which results from
* (max_period * 3) % suffix_period. This value is the index in the
* suffix arrays. The suffix array for a period 4 has the value 4
* at index 1.
/*
* printk the shortest lock dependencies from @leaf to @root.
*
* We have a lock dependency path (from a backwards search) as follow:
*
* @leaf @root
* | |
* V V
* ->parent ->parent
* | lock_list | ---------> | lock_list | ... | lock_list | ---------> | lock_list |
* | L2 <- L1 | | L3 <- L2 | ... | Ln <- Ln-1 | | <- Ln |
*
* , so when we iterate from @leaf to @root, we actually print the lock
* dependency path L1 -> L2 -> .. -> Ln in the non-reverse order.
*
* Another thing to notice here is that ->class of L2 <- L1 is L1, while the
* ->trace of L2 <- L1 is the call trace of L2, in fact we don't have the call
* trace of L1 in the dependency path, which is alright, because most of the
* time we can figure out where L1 is held from the call trace of L2.
*/
/**
* clear_pending - clear the pending bit.
* @lock: Pointer to queued spinlock structure
*
* *,1,* -> *,0,*
*/
/*
* All this does is approximate the hierarchical proportion which includes that
* global sum we all love to hate.
*
* That is, the weight of a group entity, is the proportional share of the
* group weight based on the group runqueue weights. That is:
*
* tg->weight * grq->load.weight
* ge->load.weight = ----------------------------- (1)
* \Sum grq->load.weight
*
* Now, because computing that sum is prohibitively expensive to compute (been
* there, done that) we approximate it with this average stuff. The average
* moves slower and therefore the approximation is cheaper and more stable.
*
* So instead of the above, we substitute:
*
* grq->load.weight -> grq->avg.load_avg (2)
*
* which yields the following:
*
* tg->weight * grq->avg.load_avg
* ge->load.weight = ------------------------------ (3)
* tg->load_avg
*
* Where: tg->load_avg ~= \Sum grq->avg.load_avg
*
* That is shares_avg, and it is right (given the approximation (2)).
*
* The problem with it is that because the average is slow -- it was designed
* to be exactly that of course -- this leads to transients in boundary
* conditions. In specific, the case where the group was idle and we start the
* one task. It takes time for our CPU's grq->avg.load_avg to build up,
* yielding bad latency etc..
*
* Now, in that special case (1) reduces to:
*
* tg->weight * grq->load.weight
* ge->load.weight = ----------------------------- = tg->weight (4)
* grp->load.weight
*
* That is, the sum collapses because all other CPUs are idle; the UP scenario.
*
* So what we do is modify our approximation (3) to approach (4) in the (near)
* UP case, like:
*
* ge->load.weight =
*
* tg->weight * grq->load.weight
* --------------------------------------------------- (5)
* tg->load_avg - grq->avg.load_avg + grq->load.weight
*
* But because grq->load.weight can drop to 0, resulting in a divide by zero,
* we need to use grq->avg.load_avg as its lower bound, which then gives:
*
*
* tg->weight * grq->load.weight
* ge->load.weight = ----------------------------- (6)
* tg_load_avg'
*
* Where:
*
* tg_load_avg' = tg->load_avg - grq->avg.load_avg +
* max(grq->load.weight, grq->avg.load_avg)
*
* And that is shares_weight and is icky. In the (near) UP case it approaches
* (4) while in the normal case it approaches (3). It consistently
* overestimates the ge->load.weight and therefore:
*
* \Sum ge->load.weight >= tg->weight
*
* hence icky!
*/
/*
* Handle NO_HZ for the global load-average.
*
* Since the above described distributed algorithm to compute the global
* load-average relies on per-CPU sampling from the tick, it is affected by
* NO_HZ.
*
* The basic idea is to fold the nr_active delta into a global NO_HZ-delta upon
* entering NO_HZ state such that we can include this as an 'extra' CPU delta
* when we read the global state.
*
* Obviously reality has to ruin such a delightfully simple scheme:
*
* - When we go NO_HZ idle during the window, we can negate our sample
* contribution, causing under-accounting.
*
* We avoid this by keeping two NO_HZ-delta counters and flipping them
* when the window starts, thus separating old and new NO_HZ load.
*
* The only trick is the slight shift in index flip for read vs write.
*
* 0s 5s 10s 15s
* +10 +10 +10 +10
* |-|-----------|-|-----------|-|-----------|-|
* r:0 0 1 1 0 0 1 1 0
* w:0 1 1 0 0 1 1 0 0
*
* This ensures we'll fold the old NO_HZ contribution in this window while
* accumulating the new one.
*
* - When we wake up from NO_HZ during the window, we push up our
* contribution, since we effectively move our sample point to a known
* busy state.
*
* This is solved by pushing the window forward, and thus skipping the
* sample, for this CPU (effectively using the NO_HZ-delta for this CPU which
* was in effect at the time the window opened). This also solves the issue
* of having to deal with a CPU having been in NO_HZ for multiple LOAD_FREQ
* intervals.
*
* When making the ILB scale, we should try to pull this in as well.
*/
/*
* Accumulate the three separate parts of the sum; d1 the remainder
* of the last (incomplete) period, d2 the span of full periods and d3
* the remainder of the (incomplete) current period.
*
* d1 d2 d3
* ^ ^ ^
* | | |
* |<->|<----------------->|<--->|
* ... |---x---|------| ... |------|-----x (now)
*
* p-1
* u' = (u + d1) y^p + 1024 \Sum y^n + d3 y^0
* n=1
*
* = u y^p + (Step 1)
*
* p-1
* d1 y^p + 1024 \Sum y^n + d3 y^0 (Step 2)
* n=1
*/
/*
* The clock_pelt scales the time to reflect the effective amount of
* computation done during the running delta time but then sync back to
* clock_task when rq is idle.
*
*
* absolute time | 1| 2| 3| 4| 5| 6| 7| 8| 9|10|11|12|13|14|15|16
* @ max capacity ------******---------------******---------------
* @ half capacity ------************---------************---------
* clock pelt | 1| 2| 3| 4| 7| 8| 9| 10| 11|14|15|16
*
*/
/*
* NUMA topology (first read the regular topology blurb below)
*
* Given a node-distance table, for example:
*
* node 0 1 2 3
* 0: 10 20 30 20
* 1: 20 10 20 30
* 2: 30 20 10 20
* 3: 20 30 20 10
*
* which represents a 4 node ring topology like:
*
* 0 ----- 1
* | |
* | |
* | |
* 3 ----- 2
*
* We want to construct domains and groups to represent this. The way we go
* about doing this is to build the domains on 'hops'. For each NUMA level we
* construct the mask of all nodes reachable in @level hops.
*
* For the above NUMA topology that gives 3 levels:
*
* NUMA-2 0-3 0-3 0-3 0-3
* groups: {0-1,3},{1-3} {0-2},{0,2-3} {1-3},{0-1,3} {0,2-3},{0-2}
*
* NUMA-1 0-1,3 0-2 1-3 0,2-3
* groups: {0},{1},{3} {0},{1},{2} {1},{2},{3} {0},{2},{3}
*
* NUMA-0 0 1 2 3
*
*
* As can be seen; things don't nicely line up as with the regular topology.
* When we iterate a domain in child domain chunks some nodes can be
* represented multiple times -- hence the "overlap" naming for this part of
* the topology.
*
* In order to minimize this overlap, we only build enough groups to cover the
* domain. For instance Node-0 NUMA-2 would only get groups: 0-1,3 and 1-3.
*
* Because:
*
* - the first group of each domain is its child domain; this
* gets us the first 0-1,3
* - the only uncovered node is 2, who's child domain is 1-3.
*
* However, because of the overlap, computing a unique CPU for each group is
* more complicated. Consider for instance the groups of NODE-1 NUMA-2, both
* groups include the CPUs of Node-0, while those CPUs would not in fact ever
* end up at those groups (they would end up in group: 0-1,3).
*
* To correct this we have to introduce the group balance mask. This mask
* will contain those CPUs in the group that can reach this group given the
* (child) domain tree.
*
* With this we can once again compute balance_cpu and sched_group_capacity
* relations.
*
* XXX include words on how balance_cpu is unique and therefore can be
* used for sched_group_capacity links.
*
*
* Another 'interesting' topology is:
*
* node 0 1 2 3
* 0: 10 20 20 30
* 1: 20 10 20 20
* 2: 20 20 10 20
* 3: 30 20 20 10
*
* Which looks a little like:
*
* 0 ----- 1
* | / |
* | / |
* | / |
* 2 ----- 3
*
* This topology is asymmetric, nodes 1,2 are fully connected, but nodes 0,3
* are not.
*
* This leads to a few particularly weird cases where the sched_domain's are
* not of the same number for each CPU. Consider:
*
* NUMA-2 0-3 0-3
* groups: {0-2},{1-3} {1-3},{0-2}
*
* NUMA-1 0-2 0-3 0-3 1-3
*
* NUMA-0 0 1 2 3
*
*/
/**
* ktime_get_mono_fast_ns - Fast NMI safe access to clock monotonic
*
* This timestamp is not guaranteed to be monotonic across an update.
* The timestamp is calculated by:
*
* now = base_mono + clock_delta * slope
*
* So if the update lowers the slope, readers who are forced to the
* not yet updated second array are still using the old steeper slope.
*
* tmono
* ^
* | o n
* | o n
* | u
* | o
* |o
* |12345678---> reader order
*
* o = old slope
* u = update
* n = new slope
*
* So reader 6 will observe time going backwards versus reader 5.
*
* While other CPUs are likely to be able to observe that, the only way
* for a CPU local observation is when an NMI hits in the middle of
* the update. Timestamps taken from that NMI context might be ahead
* of the following timestamps. Callers need to be aware of that and
* deal with it.
*/
/*
* The ring buffer is made up of a list of pages. A separate list of pages is
* allocated for each CPU. A writer may only write to a buffer that is
* associated with the CPU it is currently executing on. A reader may read
* from any per cpu buffer.
*
* The reader is special. For each per cpu buffer, the reader has its own
* reader page. When a reader has read the entire reader page, this reader
* page is swapped with another page in the ring buffer.
*
* Now, as long as the writer is off the reader page, the reader can do what
* ever it wants with that page. The writer will never write to that page
* again (as long as it is out of the ring buffer).
*
* Here's some silly ASCII art.
*
* +------+
* |reader| RING BUFFER
* |page |
* +------+ +---+ +---+ +---+
* | |-->| |-->| |
* +---+ +---+ +---+
* ^ |
* | |
* +---------------+
*
*
* +------+
* |reader| RING BUFFER
* |page |------------------v
* +------+ +---+ +---+ +---+
* | |-->| |-->| |
* +---+ +---+ +---+
* ^ |
* | |
* +---------------+
*
*
* +------+
* |reader| RING BUFFER
* |page |------------------v
* +------+ +---+ +---+ +---+
* ^ | |-->| |-->| |
* | +---+ +---+ +---+
* | |
* | |
* +------------------------------+
*
*
* +------+
* |buffer| RING BUFFER
* |page |------------------v
* +------+ +---+ +---+ +---+
* ^ | | | |-->| |
* | New +---+ +---+ +---+
* | Reader------^ |
* | page |
* +------------------------------+
*
*
* After we make this swap, the reader can hand this page off to the splice
* code and be done with it. It can even allocate a new page if it needs to
* and swap that into the ring buffer.
*
* We will be using cmpxchg soon to make all this lockless.
*
*/
* eBPF prog stack layout:
*
* high
* original $sp ------------> +-------------------------+ <--LOONGARCH_GPR_FP
* | $ra |
* +-------------------------+
* | $fp |
* +-------------------------+
* | $s0 |
* +-------------------------+
* | $s1 |
* +-------------------------+
* | $s2 |
* +-------------------------+
* | $s3 |
* +-------------------------+
* | $s4 |
* +-------------------------+
* | $s5 |
* +-------------------------+ <--BPF_REG_FP
* | prog->aux->stack_depth |
* | (optional) |
* current $sp -------------> +-------------------------+
* low
/*
* Allocator uses a trailing node argument --------+ (e.g. kmalloc_node())
* Allocator uses the gfp_t argument -----------+ | (e.g. kmalloc())
* Allocator uses a special leading argument + | | (e.g. devm_kmalloc())
* | | |
*/
/*
* Set up a sequence of staggered jumps, forwards and backwards with
* increasing offset. This tests the conversion of relative jumps to
* JITed native jumps. On some architectures, for example MIPS, a large
* PC-relative jump offset may overflow the immediate field of the native
* conditional branch instruction, triggering a conversion to use an
* absolute jump instead. Since this changes the jump offsets, another
* offset computation pass is necessary, and that may in turn trigger
* another branch conversion. This jump sequence is particularly nasty
* in that regard.
*
* The sequence generation is parameterized by size and jump type.
* The size must be even, and the expected result is always size + 1.
* Below is an example with size=8 and result=9.
*
* ________________________Start
* R0 = 0
* R1 = r1
* R2 = r2
* ,------- JMP +4 * 3______________Preamble: 4 insns
* ,----------|-ind 0- if R0 != 7 JMP 8 * 3 + 1 <--------------------.
* | | R0 = 8 |
* | | JMP +7 * 3 ------------------------.
* | ,--------|-----1- if R0 != 5 JMP 7 * 3 + 1 <--------------. | |
* | | | R0 = 6 | | |
* | | | JMP +5 * 3 ------------------. | |
* | | ,------|-----2- if R0 != 3 JMP 6 * 3 + 1 <--------. | | | |
* | | | | R0 = 4 | | | | |
* | | | | JMP +3 * 3 ------------. | | | |
* | | | ,----|-----3- if R0 != 1 JMP 5 * 3 + 1 <--. | | | | | |
* | | | | | R0 = 2 | | | | | | |
* | | | | | JMP +1 * 3 ------. | | | | | |
* | | | | ,--t=====4> if R0 != 0 JMP 4 * 3 + 1 1 2 3 4 5 6 7 8 loc
* | | | | | R0 = 1 -1 +2 -3 +4 -5 +6 -7 +8 off
* | | | | | JMP -2 * 3 ---' | | | | | | |
* | | | | | ,------5- if R0 != 2 JMP 3 * 3 + 1 <-----' | | | | | |
* | | | | | | R0 = 3 | | | | | |
* | | | | | | JMP -4 * 3 ---------' | | | | |
* | | | | | | ,----6- if R0 != 4 JMP 2 * 3 + 1 <-----------' | | | |
* | | | | | | | R0 = 5 | | | |
* | | | | | | | JMP -6 * 3 ---------------' | | |
* | | | | | | | ,--7- if R0 != 6 JMP 1 * 3 + 1 <-----------------' | |
* | | | | | | | | R0 = 7 | |
* | | Error | | | JMP -8 * 3 ---------------------' |
* | | paths | | | ,8- if R0 != 8 JMP 0 * 3 + 1 <-----------------------'
* | | | | | | | | | R0 = 9__________________Sequence: 3 * size - 1 insns
* `-+-+-+-+-+-+-+-+-> EXIT____________________Return: 1 insn
*
*/
* ARCHITECTURE
*
* .. code-block:: none
*
* User
* +----------------+
* | finish()|<--------------(6)-----------------+
* |get_next_block()|<--------------(5)---------------+ |
* | | Algorithm | |
* | | +------------------------------+
* | | | init() find() destroy() |
* | | +------------------------------+
* | | Core API ^ ^ ^
* | | +---------------+ (2) (4) (8)
* | (1)|----->| prepare() |---+ | |
* | (3)|----->| find()/next() |-----------+ |
* | (7)|----->| destroy() |----------------------+
* +----------------+ +---------------+
*
* (1) User configures a search by calling textsearch_prepare() specifying
* the search parameters such as the pattern and algorithm name.
* (2) Core requests the algorithm to allocate and initialize a search
* configuration according to the specified parameters.
* (3) User starts the search(es) by calling textsearch_find() or
* textsearch_next() to fetch subsequent occurrences. A state variable
* is provided to the algorithm to store persistent variables.
* (4) Core eventually resets the search offset and forwards the find()
* request to the algorithm.
* (5) Algorithm calls get_next_block() provided by the user continuously
* to fetch the data to be searched in block by block.
* (6) Algorithm invokes finish() after the last call to get_next_block
* to clean up any leftovers from get_next_block. (Optional)
* (7) User destroys the configuration by calling textsearch_destroy().
* (8) Core notifies the algorithm to destroy algorithm specific
* allocations. (Optional)
/*
State transitions between above modes -
(most modes can go to the BAD or MEM mode -- not shown for clarity)
Process header:
HEAD -> (gzip) or (zlib)
(gzip) -> FLAGS -> TIME -> OS -> EXLEN -> EXTRA -> NAME
NAME -> COMMENT -> HCRC -> TYPE
(zlib) -> DICTID or TYPE
DICTID -> DICT -> TYPE
Read deflate blocks:
TYPE -> STORED or TABLE or LEN or CHECK
STORED -> COPY -> TYPE
TABLE -> LENLENS -> CODELENS -> LEN
Read deflate codes:
LEN -> LENEXT or LIT or TYPE
LENEXT -> DIST -> DISTEXT -> MATCH -> LEN
LIT -> LEN
Process trailer:
CHECK -> LENGTH -> DONE
*/
/*
* CD/DVDs are error prone. When a medium error occurs, the driver may fail
* a _large_ part of the i/o request. Imagine the worst scenario:
*
* ---R__________________________________________B__________
* ^ reading here ^ bad block(assume 4k)
*
* read(R) => miss => readahead(R...B) => media error => frustrating retries
* => failing the whole request => read(R) => read(R+1) =>
* readahead(R+1...B+1) => bang => read(R+2) => read(R+3) =>
* readahead(R+3...B+2) => bang => read(R+3) => read(R+4) =>
* readahead(R+4...B+3) => bang => read(R+4) => read(R+5) => ......
*
* It is going insane. Fix it by quickly scaling down the readahead size.
*/
/*
* setpoint - dirty 3
* f(dirty) := 1.0 + (----------------)
* limit - setpoint
*
* it's a 3rd order polynomial that subjects to
*
* (1) f(freerun) = 2.0 => rampup dirty_ratelimit reasonably fast
* (2) f(setpoint) = 1.0 => the balance point
* (3) f(limit) = 0 => the hard limit
* (4) df/dx <= 0 => negative feedback control
* (5) the closer to setpoint, the smaller |df/dx| (and the reverse)
* => fast response on large errors; small oscillation near setpoint
*/
/*
* This function populates subtree_max_size from bottom to upper
* levels starting from VA point. The propagation must be done
* when VA size is modified by changing its va_start/va_end. Or
* in case of newly inserting of VA to the tree.
*
* It means that __augment_tree_propagate_from() must be called:
* - After VA has been inserted to the tree(free path);
* - After VA has been shrunk(allocation path);
* - After VA has been increased(merging path).
*
* Please note that, it does not mean that upper parent nodes
* and their subtree_max_size are recalculated all the time up
* to the root node.
*
* 4--8
* /\
* / \
* / \
* 2--2 8--8
*
* For example if we modify the node 4, shrinking it to 2, then
* no any modification is required. If we shrink the node 2 to 1
* its subtree_max_size is updated only, and set to 1. If we shrink
* the node 8 to 6, then its subtree_max_size is set to 6 and parent
* node becomes 4--6.
*/
/*
* Map a file extent to a stripe unit within an object.
* Fill in objno, offset into object, and object extent length (i.e. the
* number of bytes mapped, less than or equal to @l->stripe_unit).
*
* Example for stripe_count = 3, stripes_per_object = 4:
*
* blockno | 0 3 6 9 | 1 4 7 10 | 2 5 8 11 | 12 15 18 21 | 13 16 19
* stripeno | 0 1 2 3 | 0 1 2 3 | 0 1 2 3 | 4 5 6 7 | 4 5 6
* stripepos | 0 | 1 | 2 | 0 | 1
* objno | 0 | 1 | 2 | 3 | 4
* objsetno | 0 | 1
*/
/* To define the outgoing port and to discover the incoming port a regular
* VLAN tag is used by the LAN9303. But its VID meaning is 'special':
*
* Dest MAC Src MAC TAG Type
* ...| 1 2 3 4 5 6 | 1 2 3 4 5 6 | 1 2 3 4 | 1 2 |...
* |<------->|
* TAG:
* |<------------->|
* | 1 2 | 3 4 |
* TPID VID
* 0x8100
*
* VID bit 3 indicates a request for an ALR lookup.
*
* If VID bit 3 is zero, then bits 0 and 1 specify the destination port
* (0, 1, 2) or broadcast (3) or the source port (1, 2).
*
* VID bit 4 is used to specify if the STP port state should be overridden.
* Required when no forwarding between the external ports should happen.
*/
* DMA transfers are limited to the lower 16MB of _physical_ memory.
* Note that addresses loaded into registers must be _physical_ addresses,
* not logical addresses (which may differ if paging is active).
*
* Address mapping for channels 0-3:
*
* A23 ... A16 A15 ... A8 A7 ... A0 (Physical addresses)
* | ... | | ... | | ... |
* | ... | | ... | | ... |
* | ... | | ... | | ... |
* P7 ... P0 A7 ... A0 A7 ... A0
* | Page | Addr MSB | Addr LSB | (DMA registers)
*
* Address mapping for channels 5-7:
*
* A23 ... A17 A16 A15 ... A9 A8 A7 ... A1 A0 (Physical addresses)
* | ... | \ \ ... \ \ \ ... \ \
* | ... | \ \ ... \ \ \ ... \ (not used)
* | ... | \ \ ... \ \ \ ... \
* P7 ... P1 (0) A7 A6 ... A0 A7 A6 ... A0
* | Page | Addr MSB | Addr LSB | (DMA registers)
*
* Again, channels 5-7 transfer _physical_ words (16 bits), so addresses
* and counts _must_ be word-aligned (the lowest address bit is _ignored_ at
* the hardware level, so odd-byte transfers aren't possible).
* The core algorithm does not react directly to packet losses or delays,
* although BBR may adjust the size of next send per ACK when loss is
* observed, or adjust the sending rate if it estimates there is a
* traffic policer, in order to keep the drop rate reasonable.
*
* Here is a state transition diagram for BBR:
*
* |
* V
* +---> STARTUP ----+
* | | |
* | V |
* | DRAIN ----+
* | | |
* | V |
* +---> PROBE_BW ----+
* | ^ | |
* | | | |
* | +----+ |
* | |
* +---- PROBE_RTT <--+
*
* A BBR flow starts in STARTUP, and ramps up its sending rate quickly.
* When it estimates the pipe is full, it enters DRAIN to drain the queue.
* In steady state a BBR flow only uses PROBE_BW and PROBE_RTT.
* A long-lived BBR flow spends the vast majority of its time remaining
* (repeatedly) in PROBE_BW, fully probing and utilizing the pipe's bandwidth
* in a fair manner, with a small, bounded queue. *If* a flow has been
* continuously sending for the entire min_rtt window, and hasn't seen an RTT
* sample that matches or decreases its min_rtt estimate for 10 seconds, then
* it briefly enters PROBE_RTT to cut inflight to a minimum value to re-probe
* the path's two-way propagation delay (min_rtt). When exiting PROBE_RTT, if
* we estimated that we reached the full bw of the pipe then we enter PROBE_BW;
* otherwise we enter STARTUP to try to fill the pipe.
* SACK block validation.
* ----------------------
*
* SACK block range validation checks that the received SACK block fits to
* the expected sequence limits, i.e., it is between SND.UNA and SND.NXT.
* Note that SND.UNA is not included to the range though being valid because
* it means that the receiver is rather inconsistent with itself reporting
* SACK reneging when it should advance SND.UNA. Such SACK block this is
* perfectly valid, however, in light of RFC2018 which explicitly states
* that "SACK block MUST reflect the newest segment. Even if the newest
* segment is going to be discarded ...", not that it looks very clever
* in case of head skb. Due to potentional receiver driven attacks, we
* choose to avoid immediate execution of a walk in write queue due to
* reneging and defer head skb's loss recovery to standard loss recovery
* procedure that will eventually trigger (nothing forbids us doing this).
*
* Implements also blockage to start_seq wrap-around. Problem lies in the
* fact that though start_seq (s) is before end_seq (i.e., not reversed),
* there's no guarantee that it will be before snd_nxt (n). The problem
* happens when start_seq resides between end_seq wrap (e_w) and snd_nxt
* wrap (s_w):
*
* <- outs wnd -> <- wrapzone ->
* u e n u_w e_w s n_w
* | | | | | | |
* |<------------+------+----- TCP seqno space --------------+---------->|
* ...-- <2^31 ->| |<--------...
* ...---- >2^31 ------>| |<--------...
*
* Current code wouldn't be vulnerable but it's better still to discard such
* crazy SACK blocks. Doing this check for start_seq alone closes somewhat
* similar case (end_seq after snd_nxt wrap) as earlier reversed check in
* snd_nxt wrap -> snd_una region will then become "well defined", i.e.,
* equal to the ideal case (infinite seqno space without wrap caused issues).
* Insertion
* ---------
*
* - For each packet field:
*
* - divide the b packet bits we want to classify into groups of size t,
* obtaining ceil(b / t) groups
*
* Example: match on destination IP address, with t = 4: 32 bits, 8 groups
* of 4 bits each
*
* - allocate a lookup table with one column ("bucket") for each possible
* value of a group, and with one row for each group
*
* Example: 8 groups, 2^4 buckets:
*
* ::
*
* bucket
* group 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
* 0
* 1
* 2
* 3
* 4
* 5
* 6
* 7
*
* - map the bits we want to classify for the current field, for a given
* entry, to a single rule for non-ranged and netmask set items, and to one
* or multiple rules for ranges. Ranges are expanded to composing netmasks
* by pipapo_expand().
*
* Example: 2 entries, 10.0.0.5:1024 and 192.168.1.0-192.168.2.1:2048
* - rule #0: 10.0.0.5
* - rule #1: 192.168.1.0/24
* - rule #2: 192.168.2.0/31
*
* - insert references to the rules in the lookup table, selecting buckets
* according to bit values of a rule in the given group. This is done by
* pipapo_insert().
*
* Example: given:
* - rule #0: 10.0.0.5 mapping to buckets
* < 0 10 0 0 0 0 0 5 >
* - rule #1: 192.168.1.0/24 mapping to buckets
* < 12 0 10 8 0 1 < 0..15 > < 0..15 > >
* - rule #2: 192.168.2.0/31 mapping to buckets
* < 12 0 10 8 0 2 0 < 0..1 > >
*
* these bits are set in the lookup table:
*
* ::
*
* bucket
* group 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
* 0 0 1,2
* 1 1,2 0
* 2 0 1,2
* 3 0 1,2
* 4 0,1,2
* 5 0 1 2
* 6 0,1,2 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
* 7 1,2 1,2 1 1 1 0,1 1 1 1 1 1 1 1 1 1 1
*
* - if this is not the last field in the set, fill a mapping array that maps
* rules from the lookup table to rules belonging to the same entry in
* the next lookup table, done by pipapo_map().
*
* Note that as rules map to contiguous ranges of rules, given how netmask
* expansion and insertion is performed, &union nft_pipapo_map_bucket stores
* this information as pairs of first rule index, rule count.
*
* Example: 2 entries, 10.0.0.5:1024 and 192.168.1.0-192.168.2.1:2048,
* given lookup table #0 for field 0 (see example above):
*
* ::
*
* bucket
* group 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
* 0 0 1,2
* 1 1,2 0
* 2 0 1,2
* 3 0 1,2
* 4 0,1,2
* 5 0 1 2
* 6 0,1,2 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
* 7 1,2 1,2 1 1 1 0,1 1 1 1 1 1 1 1 1 1 1
*
* and lookup table #1 for field 1 with:
* - rule #0: 1024 mapping to buckets
* < 0 0 4 0 >
* - rule #1: 2048 mapping to buckets
* < 0 0 5 0 >
*
* ::
*
* bucket
* group 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
* 0 0,1
* 1 0,1
* 2 0 1
* 3 0,1
*
* we need to map rules for 10.0.0.5 in lookup table #0 (rule #0) to 1024
* in lookup table #1 (rule #0) and rules for 192.168.1.0-192.168.2.1
* (rules #1, #2) to 2048 in lookup table #2 (rule #1):
*
* ::
*
* rule indices in current field: 0 1 2
* map to rules in next field: 0 1 1
*
* - if this is the last field in the set, fill a mapping array that maps
* rules from the last lookup table to element pointers, also done by
* pipapo_map().
*
* Note that, in this implementation, we have two elements (start, end) for
* each entry. The pointer to the end element is stored in this array, and
* the pointer to the start element is linked from it.
*
* Example: entry 10.0.0.5:1024 has a corresponding &struct nft_pipapo_elem
* pointer, 0x66, and element for 192.168.1.0-192.168.2.1:2048 is at 0x42.
* From the rules of lookup table #1 as mapped above:
*
* ::
*
* rule indices in last field: 0 1
* map to elements: 0x66 0x42
*
*
* Matching
* --------
*
* We use a result bitmap, with the size of a single lookup table bucket, to
* represent the matching state that applies at every algorithm step. This is
* done by pipapo_lookup().
*
* - For each packet field:
*
* - start with an all-ones result bitmap (res_map in pipapo_lookup())
*
* - perform a lookup into the table corresponding to the current field,
* for each group, and at every group, AND the current result bitmap with
* the value from the lookup table bucket
*
* ::
*
* Example: 192.168.1.5 < 12 0 10 8 0 1 0 5 >, with lookup table from
* insertion examples.
* Lookup table buckets are at least 3 bits wide, we'll assume 8 bits for
* convenience in this example. Initial result bitmap is 0xff, the steps
* below show the value of the result bitmap after each group is processed:
*
* bucket
* group 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
* 0 0 1,2
* result bitmap is now: 0xff & 0x6 [bucket 12] = 0x6
*
* 1 1,2 0
* result bitmap is now: 0x6 & 0x6 [bucket 0] = 0x6
*
* 2 0 1,2
* result bitmap is now: 0x6 & 0x6 [bucket 10] = 0x6
*
* 3 0 1,2
* result bitmap is now: 0x6 & 0x6 [bucket 8] = 0x6
*
* 4 0,1,2
* result bitmap is now: 0x6 & 0x7 [bucket 0] = 0x6
*
* 5 0 1 2
* result bitmap is now: 0x6 & 0x2 [bucket 1] = 0x2
*
* 6 0,1,2 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
* result bitmap is now: 0x2 & 0x7 [bucket 0] = 0x2
*
* 7 1,2 1,2 1 1 1 0,1 1 1 1 1 1 1 1 1 1 1
* final result bitmap for this field is: 0x2 & 0x3 [bucket 5] = 0x2
*
* - at the next field, start with a new, all-zeroes result bitmap. For each
* bit set in the previous result bitmap, fill the new result bitmap
* (fill_map in pipapo_lookup()) with the rule indices from the
* corresponding buckets of the mapping field for this field, done by
* pipapo_refill()
*
* Example: with mapping table from insertion examples, with the current
* result bitmap from the previous example, 0x02:
*
* ::
*
* rule indices in current field: 0 1 2
* map to rules in next field: 0 1 1
*
* the new result bitmap will be 0x02: rule 1 was set, and rule 1 will be
* set.
*
* We can now extend this example to cover the second iteration of the step
* above (lookup and AND bitmap): assuming the port field is
* 2048 < 0 0 5 0 >, with starting result bitmap 0x2, and lookup table
* for "port" field from pre-computation example:
*
* ::
*
* bucket
* group 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
* 0 0,1
* 1 0,1
* 2 0 1
* 3 0,1
*
* operations are: 0x2 & 0x3 [bucket 0] & 0x3 [bucket 0] & 0x2 [bucket 5]
* & 0x3 [bucket 0], resulting bitmap is 0x2.
*
* - if this is the last field in the set, look up the value from the mapping
* array corresponding to the final result bitmap
*
* Example: 0x2 resulting bitmap from 192.168.1.5:2048, mapping array for
* last field from insertion example:
*
* ::
*
* rule indices in last field: 0 1
* map to elements: 0x66 0x42
*
* the matching element is at 0x42.
*
*
* References
* ----------
*
* [Ligatti 2010]
* A Packet-classification Algorithm for Arbitrary Bitmask Rules, with
* Automatic Time-space Tradeoffs
* Jay Ligatti, Josh Kuhn, and Chris Gage.
* Proceedings of the IEEE International Conference on Computer
* Communication Networks (ICCCN), August 2010.
* https://www.cse.usf.edu/~ligatti/papers/grouper-conf.pdf
*
* [Rottenstreich 2010]
* Worst-Case TCAM Rule Expansion
* Ori Rottenstreich and Isaac Keslassy.
* 2010 Proceedings IEEE INFOCOM, San Diego, CA, 2010.
* http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.212.4592&rep=rep1&type=pdf
*
* [Kogan 2014]
* SAX-PAC (Scalable And eXpressive PAcket Classification)
* Kirill Kogan, Sergey Nikolenko, Ori Rottenstreich, William Culhane,
* and Patrick Eugster.
* Proceedings of the 2014 ACM conference on SIGCOMM, August 2014.
* https://www.sigcomm.org/sites/default/files/ccr/papers/2014/August/2619239-2626294.pdf
*/
* This function does not validate the targets or matches themselves, it
* only tests that all the offsets and sizes are correct, that all
* match structures are aligned, and that the last structure ends where
* the target structure begins.
*
* Also see xt_compat_check_entry_offsets for CONFIG_NETFILTER_XTABLES_COMPAT version.
*
* The arp/ip/ip6t_entry structure @base must have passed following tests:
* - it must point to a valid memory location
* - base to base + next_offset must be accessible, i.e. not exceed allocated
* length.
*
* A well-formed entry looks like this:
*
* ip(6)t_entry match [mtdata] match [mtdata] target [tgdata] ip(6)t_entry
* e->elems[]-----' | |
* matchsize | |
* matchsize | |
* | |
* target_offset---------------------------------' |
* next_offset---------------------------------------------------'
*
* elems[]: flexible array member at end of ip(6)/arpt_entry struct.
* This is where matches (if any) and the target reside.
* target_offset: beginning of target.
* next_offset: start of the next rule; also: size of this rule.
* Since targets have a minimum size, target_offset + minlen <= next_offset.
*
* Every match stores its size, sum of sizes must not exceed target_offset.
/*
* State of the queue, when used for network output buffering:
*
* plug(i+1) plug(i) head
* ------------------+--------------------+---------------->
* | |
* | |
* pkts_current_epoch| pkts_last_epoch |pkts_to_release
* ----------------->|<--------+--------->|+--------------->
* v v
*
*/
* The local node uses the REMOTE NODE NUMBER + OFFSET to point to the
* First board info on the remote node. The remote node list is
* traversed as the local list, using the REMOTE BASE ADDRESS and not
* the local base address and ignoring all rboard values.
*
*
KLCONFIG
+------------+ +------------+ +------------+ +------------+
| lboard | +-->| lboard | +-->| rboard | +-->| lboard |
+------------+ | +------------+ | +------------+ | +------------+
| board info | | | board info | | |errinfo,bptr| | | board info |
+------------+ | +------------+ | +------------+ | +------------+
| offset |--+ | offset |--+ | offset |--+ |offset=NULL |
+------------+ +------------+ +------------+ +------------+
+------------+
| board info |
+------------+ +--------------------------------+
| compt 1 |------>| type, rev, diaginfo, size ... | (CPU)
+------------+ +--------------------------------+
| compt 2 |--+
+------------+ | +--------------------------------+
| ... | +--->| type, rev, diaginfo, size ... | (MEM_BANK)
+------------+ +--------------------------------+
| errinfo |--+
+------------+ | +--------------------------------+
+--->|r/l brd errinfo,compt err flags |
+--------------------------------+
*
* Each BOARD consists of COMPONENTs and the BOARD structure has
* pointers (offsets) to its COMPONENT structure.
* The COMPONENT structure has version info, size and speed info, revision,
* error info and the NIC info. This structure can accommodate any
* BOARD with arbitrary COMPONENT composition.
*
* Encoding key for single-list chunks (HLOO = Handle32 Length32 Offset64):
*
* Read chunklist (a linked list):
* N elements, position P (same P for all chunks of same arg!):
* 1 - PHLOO - 1 - PHLOO - ... - 1 - PHLOO - 0
/* The structure of the shared state of the rings are a simple
* circular buffer, as outlined in
* Documentation/core-api/circular-buffers.rst. For the Rx and
* completion ring, the kernel is the producer and user space is the
* consumer. For the Tx and fill rings, the kernel is the consumer and
* user space is the producer.
*
* producer consumer
*
* if (LOAD ->consumer) { (A) LOAD.acq ->producer (C)
* STORE $data LOAD $data
* STORE.rel ->producer (B) STORE.rel ->consumer (D)
* }
*
* (A) pairs with (D), and (B) pairs with (C).
*
* Starting with (B), it protects the data from being written after
* the producer pointer. If this barrier was missing, the consumer
* could observe the producer pointer being set and thus load the data
* before the producer has written the new data. The consumer would in
* this case load the old data.
*
* (C) protects the consumer from speculatively loading the data before
* the producer pointer actually has been read. If we do not have this
* barrier, some architectures could load old data as speculative loads
* are not discarded as the CPU does not know there is a dependency
* between ->producer and data.
*
* (A) is a control dependency that separates the load of ->consumer
* from the stores of $data. In case ->consumer indicates there is no
* room in the buffer to store $data we do not. The dependency will
* order both of the stores after the loads. So no barrier is needed.
*
* (D) protects the load of the data to be observed to happen after the
* store of the consumer pointer. If we did not have this memory
* barrier, the producer could observe the consumer pointer being set
* and overwrite the data with a new value before the consumer got the
* chance to read the old value. The consumer would thus miss reading
* the old entry and very likely read the new entry twice, once right
* now and again after circling through the ring.
*/
/* xfrm inexact policy search tree:
* xfrm_pol_inexact_bin = hash(dir,type,family,if_id);
* |
* +---- root_d: sorted by daddr:prefix
* | |
* | xfrm_pol_inexact_node
* | |
* | +- root: sorted by saddr/prefix
* | | |
* | | xfrm_pol_inexact_node
* | | |
* | | + root: unused
* | | |
* | | + hhead: saddr:daddr policies
* | |
* | +- coarse policies and all any:daddr policies
* |
* +---- root_s: sorted by saddr:prefix
* | |
* | xfrm_pol_inexact_node
* | |
* | + root: unused
* | |
* | + hhead: saddr:any policies
* |
* +---- coarse policies and all any:any policies
*
* Lookups return four candidate lists:
* 1. any:any list from top-level xfrm_pol_inexact_bin
* 2. any:daddr list from daddr tree
* 3. saddr:daddr list from 2nd level daddr tree
* 4. saddr:any list from saddr tree
*
* This result set then needs to be searched for the policy with
* the lowest priority. If two results have same prio, youngest one wins.
*/
/* Implementation is a simple linked list for now...
This priority queue orders the events on timestamp. For events with an
equeal timestamp the queue behaves as a FIFO.
*
* +-------+
* Head --> | first |
* +-------+
* |next
* +-----v-+
* | |
* +-------+
* |
* +-----v-+
* | |
* +-------+
* |
* +-----v-+
* Tail --> | last |
* +-------+
*
*/
/*
* possible hardware ports (selected by 0xf5 port message)
* 0x00 all ports
* 0x01 .. 0x08 this MTP's ports 1..8
* 0x09 .. 0x10 networked MTP's ports (9..16)
* 0x11 networked MTP's computer port
* 0x63 to ADAT
*
* mappig:
* subdevice 0 - (X-1) ports
* X - (2*X-1) networked ports
* X computer
* X+1 ADAT
* X+2 all ports
*
* where X = chip->num_ports
*/
/* Parallel Port Status Register BUSY and SELECT lines are multiplexed
* between several functions. Depending on which 2x4 "register" is
* currently selected (b1..b3), the BUSY and SELECT lines are
* assigned as follows:
*
* SELECT LINE: A3 A2 A1
* --------
*/
/*
* the hdac_stream library is intended to be used with the following
* transitions. The states are not formally defined in the code but loosely
* inspired by boolean variables. Note that the 'prepared' field is not used
* in this library but by the callers during the hw_params/prepare transitions
*
* |
* stream_init() |
* v
* +--+-------+
* | unused |
* +--+----+--+
* | ^
* stream_assign() | | stream_release()
* v |
* +--+----+--+
* | opened |
* +--+----+--+
* | ^
* stream_reset() | |
* stream_setup() | | stream_cleanup()
* v |
* +--+----+--+
* | prepared |
* +--+----+--+
* | ^
* stream_start() | | stream_stop()
* v |
* +--+----+--+
* | running |
* +----------+
*/
/*
* CEA speaker placement:
*
* FLH FCH FRH
* FLW FL FLC FC FRC FR FRW
*
* LFE
* TC
*
* RL RLC RC RRC RR
*
* The Left/Right Surround channel _notions_ LS/RS in SMPTE 320M corresponds to
* CEA RL/RR; The SMPTE channel _assignment_ C/LFE is swapped to CEA LFE/FC.
*/
/*********************************************************************************************
Example hierarchy of stream control blocks in the SP
hfgTree
Ptr____Call (c)
\
-------+------ ------------- ------------- ------------- -----
| SBlaster IF |______\| Foreground |___\| Middlegr'nd |___\| Background |___\| Nul |
| |Goto /| tree header |g /| tree header |g /| tree header |g /| SCB |r
-------------- (g) ------------- ------------- ------------- -----
|c |c |c |c
| | | |
\/ ------------- ------------- -------------
| Foreground |_\ | Middlegr'nd |_\ | Background |_\
| tree |g/ | tree |g/ | tree |g/
------------- ------------- -------------
|c |c |c
| | |
\/ \/ \/
*********************************************************************************************/
* ** connected chips **
*
* WM8740
* A 2ch-DAC of main outputs.
* It setuped as I2S mode by wire, so no way to setup from software.
* The sample-rate are automatically changed.
* ML/I2S (28pin) --------+
* MC/DM1 (27pin) -- 5V |
* MD/DM0 (26pin) -- GND |
* MUTEB (25pin) -- NC |
* MODE (24pin) -- GND |
* CSBIW (23pin) --------+
* |
* RSTB (22pin) --R(1K)-+
* Probably it reduce the noise from the control line.
*
* WM8766
* A 6ch-DAC for surrounds.
* It's control wire was connected to GPIOxx (3-wire serial interface)
* ML/I2S (11pin) -- GPIO18
* MC/IWL (12pin) -- GPIO17
* MD/DM (13pin) -- GPIO16
* MUTE (14pin) -- GPIO01
*
* WM8776
* A 2ch-ADC(with 10ch-selector) plus 2ch-DAC.
* It's control wire was connected to SDA/SCLK (2-wire serial interface)
* MODE (16pin) -- R(1K) -- GND
* CE (17pin) -- R(1K) -- GND 2-wire mode (address=0x34)
* DI (18pin) -- SDA
* CL (19pin) -- SCLK
*
*
* ** output pins and device names **
*
* 7.1ch name -- output connector color -- device (-D option)
*
* FRONT 2ch -- green -- plughw:0,0
* CENTER(Lch) SUBWOOFER(Rch) -- black -- plughw:0,2,0
* SURROUND 2ch -- orange -- plughw:0,2,1
* SURROUND BACK 2ch -- white -- plughw:0,2,2
/*
* CEA speaker placement for HDMI 1.4:
*
* FL FLC FC FRC FR FRW
*
* LFE
*
* RL RLC RC RRC RR
*
* Speaker placement has to be extended to support HDMI 2.0
*/
/**
* fsl_dma_open: open a new substream.
*
* Each substream has its own DMA buffer.
*
* ALSA divides the DMA buffer into N periods. We create NUM_DMA_LINKS link
* descriptors that ping-pong from one period to the next. For example, if
* there are six periods and two link descriptors, this is how they look
* before playback starts:
*
* The last link descriptor
* ____________ points back to the first
* | |
* V |
* ___ ___ |
* | |->| |->|
* |___| |___|
* | |
* | |
* V V
* _________________________________________
* | | | | | | | The DMA buffer is
* | | | | | | | divided into 6 parts
* |______|______|______|______|______|______|
*
* and here's how they look after the first period is finished playing:
*
* ____________
* | |
* V |
* ___ ___ |
* | |->| |->|
* |___| |___|
* | |
* |______________
* | |
* V V
* _________________________________________
* | | | | | | |
* | | | | | | |
* |______|______|______|______|______|______|
*
* The first link descriptor now points to the third period. The DMA
* controller is currently playing the second period. When it finishes, it
* will jump back to the first descriptor and play the third period.
*
* There are four reasons we do this:
*
* 1. The only way to get the DMA controller to automatically restart the
* transfer when it gets to the end of the buffer is to use chaining
* mode. Basic direct mode doesn't offer that feature.
* 2. We need to receive an interrupt at the end of every period. The DMA
* controller can generate an interrupt at the end of every link transfer
* (aka segment). Making each period into a DMA segment will give us the
* interrupts we need.
* 3. By creating only two link descriptors, regardless of the number of
* periods, we do not need to reallocate the link descriptors if the
* number of periods changes.
* 4. All of the audio data is still stored in a single, contiguous DMA
* buffer, which is what ALSA expects. We're just dividing it into
* contiguous parts, and creating a link descriptor for each one.
*/
/*
* period/frame/sample image
*
* ex) PCM (2ch)
*
* period pos period pos
* [n] [n + 1]
* |<-------------------- period--------------------->|
* ==|============================================ ... =|==
* | |
* ||<----- frame ----->|<------ frame ----->| ... |
* |+--------------------+--------------------+- ... |
* ||[ sample ][ sample ]|[ sample ][ sample ]| ... |
* |+--------------------+--------------------+- ... |
* ==|============================================ ... =|==
*/
/*
* driver data Image
*
* rsnd_priv
* |
* | ** this depends on Gen1/Gen2
* |
* +- gen
* |
* | ** these depend on data path
* | ** gen and platform data control it
* |
* +- rdai[0]
* | | sru ssiu ssi
* | +- playback -> [mod] -> [mod] -> [mod] -> ...
* | |
* | | sru ssiu ssi
* | +- capture -> [mod] -> [mod] -> [mod] -> ...
* |
* +- rdai[1]
* | | sru ssiu ssi
* | +- playback -> [mod] -> [mod] -> [mod] -> ...
* | |
* | | sru ssiu ssi
* | +- capture -> [mod] -> [mod] -> [mod] -> ...
* ...
* |
* | ** these control ssi
* |
* +- ssi
* | |
* | +- ssi[0]
* | +- ssi[1]
* | +- ssi[2]
* | ...
* |
* | ** these control src
* |
* +- src
* |
* +- src[0]
* +- src[1]
* +- src[2]
* ...
*
*
* for_each_rsnd_dai(xx, priv, xx)
* rdai[0] => rdai[1] => rdai[2] => ...
*
* for_each_rsnd_mod(xx, rdai, xx)
* [mod] => [mod] => [mod] => ...
*
* rsnd_dai_call(xxx, fn )
* [mod]->fn() -> [mod]->fn() -> [mod]->fn()...
*
*/
/*
* image of SRC (Sampling Rate Converter)
*
* 96kHz <-> +-----+ 48kHz +-----+ 48kHz +-------+
* 48kHz <-> | SRC | <------> | SSI | <-----> | codec |
* 44.1kHz <-> +-----+ +-----+ +-------+
* ...
*
*/
/*
* FW Boot State Transition Diagram
*
* +----------------------------------------------------------------------+
* | |
* ------------------ ------------------ |
* | | | | |
* | BOOT_FAILED |<-------| READY_FAILED | |
* | |<--+ | | ------------------ |
* ------------------ | ------------------ | | |
* ^ | ^ | CRASHED |---+ |
* | | | | | | |
* (FW Boot Timeout) | (FW_READY FAIL) ------------------ | |
* | | | ^ | |
* | | | |(DSP Panic) | |
* ------------------ | | ------------------ | |
* | | | | | | | |
* | IN_PROGRESS |---------------+------------->| COMPLETE | | |
* | | (FW Boot OK) (FW_READY OK) | | | |
* ------------------ | ------------------ | |
* ^ | | | |
* | | | | |
* (FW Loading OK) | (System Suspend/Runtime Suspend)
* | | | | |
* | (FW Loading Fail) | | |
* ------------------ | ------------------ | | |
* | | | | |<-----+ | |
* | PREPARE |---+ | NOT_STARTED |<---------------------+ |
* | | | |<--------------------------+
* ------------------ ------------------
* | ^ | ^
* | | | |
* | +-----------------------+ |
* | (DSP Probe OK) |
* | |
* | |
* +------------------------------------+
* (System Suspend/Runtime Suspend)
*/
/*
* Audio DSP states may transform as below:-
*
* Opportunistic D0I3 in S0
* Runtime +---------------------+ Delayed D0i3 work timeout
* suspend | +--------------------+
* +------------+ D0I0(active) | |
* | | <---------------+ |
* | +--------> | New IPC | |
* | |Runtime +--^--+---------^--+--+ (via mailbox) | |
* | |resume | | | | | |
* | | | | | | | |
* | | System| | | | | |
* | | resume| | S3/S0IX | | | |
* | | | | suspend | | S0IX | |
* | | | | | |suspend | |
* | | | | | | | |
* | | | | | | | |
* +-v---+-----------+--v-------+ | | +------+----v----+
* | | | +-----------> |
* | D3 (suspended) | | | D0I3 |
* | | +--------------+ |
* | | System resume | |
* +----------------------------+ +----------------+
*
* S0IX suspend: The DSP is in D0I3 if any D0I3-compatible streams
* ignored the suspend trigger. Otherwise the DSP
* is in D3.
*/
/*
* Audio paths on Pandora board:
*
* |O| ---> PCM DAC +-> AMP -> Headphone Jack
* |M| A +--------> Line Out
* |A| <~~clk~~+
* |P| <--- TWL4030 <--------- Line In and MICs
*/
/*
* Topology of SB Extigy (see on the wide screen :)
USB_IN[1] --->FU[2]------------------------------+->MU[16]-->PU[17]-+->FU[18]--+->EU[27]--+->EU[21]-->FU[22]--+->FU[23] > Dig_OUT[24]
^ | | | |
USB_IN[3] -+->SU[5]-->FU[6]--+->MU[14] ->PU[15]->+ | | | +->FU[25] > Dig_OUT[26]
^ ^ | | | |
Dig_IN[4] -+ | | | | +->FU[28]---------------------> Spk_OUT[19]
| | | |
Lin-IN[7] -+-->FU[8]---------+ | | +----------------------------------------> Hph_OUT[20]
| | |
Mic-IN[9] --+->FU[10]----------------------------+ |
|| |
|| +----------------------------------------------------+
VV V
++--+->SU[11]-->FU[12] --------------------------------------------------------------------------------------> USB_OUT[13]
*/
* <ditaa>
* /--------------\ 18chn 6chn /--------------\
* | Hardware in +--+-------\ /------+--+ ALSA PCM out |
* \--------------/ | | | | \--------------/
* | | | |
* | v v |
* | +---------------+ |
* | \ Matrix Mux / |
* | +-----+-----+ |
* | | |
* | | 18chn |
* | v |
* | +-----------+ |
* | | Mixer | |
* | | Matrix | |
* | | | |
* | | 18x6 Gain | |
* | | stages | |
* | +-----+-----+ |
* | | |
* | | |
* | 18chn | 6chn | 6chn
* v v v
* =========================
* +---------------+ +--—------------+
* \ Output Mux / \ Capture Mux /
* +-----+-----+ +-----+-----+
* | |
* | 6chn |
* v |
* +-------------+ |
* | Master Gain | |
* +------+------+ |
* | |
* | 6chn | 18chn
* | (3 stereo pairs) |
* /--------------\ | | /--------------\
* | Hardware out |<--/ \-->| ALSA PCM in |
* \--------------/ \--------------/
* </ditaa>
/*
* PCM ring buffer handling
*
* The hardware provides a ring buffer with the fixed 4 buffer descriptors
* (BDs). The driver maps these 4 BDs onto the PCM ring buffer. The mapping
* moves at each period elapsed. The below illustrates how it works:
*
* At time=0
* PCM | 0 | 1 | 2 | 3 | 4 | 5 | .... |n-1|
* BD | 0 | 1 | 2 | 3 |
*
* At time=1 (period elapsed)
* PCM | 0 | 1 | 2 | 3 | 4 | 5 | .... |n-1|
* BD | 1 | 2 | 3 | 0 |
*
* At time=2 (second period elapsed)
* PCM | 0 | 1 | 2 | 3 | 4 | 5 | .... |n-1|
* BD | 2 | 3 | 0 | 1 |
*
* The bd_head field points to the index of the BD to be read. It's also the
* position to be filled at next. The pcm_head and the pcm_filled fields
* point to the indices of the current position and of the next position to
* be filled, respectively. For PCM buffer there are both _head and _filled
* because they may be difference when nperiods > 4. For example, in the
* example above at t=1, bd_head=1 and pcm_head=1 while pcm_filled=5:
*
* pcm_head (=1) --v v-- pcm_filled (=5)
* PCM | 0 | 1 | 2 | 3 | 4 | 5 | .... |n-1|
* BD | 1 | 2 | 3 | 0 |
* bd_head (=1) --^ ^-- next to fill (= bd_head)
*
* For nperiods < 4, the remaining BDs out of 4 are marked as invalid, so that
* the hardware skips those BDs in the loop.
*
* An exceptional setup is the case with nperiods=1. Since we have to update
* BDs after finishing one BD processing, we'd need at least two BDs, where
* both BDs point to the same content, the same address, the same size of the
* whole PCM buffer.
*/
/*
* CEA speaker placement:
*
* FL FLC FC FRC FR
*
* LFE
*
* RL RLC RC RRC RR
*
* The Left/Right Surround channel _notions_ LS/RS in SMPTE 320M
* corresponds to CEA RL/RR; The SMPTE channel _assignment_ C/LFE is
* swapped to CEA LFE/FC.
*/
/*
* Linux IRQ vector layout.
*
* There are 256 IDT entries (per CPU - each entry is 8 bytes) which can
* be defined by Linux. They are used as a jump table by the CPU when a
* given vector is triggered - by a CPU-external, CPU-internal or
* software-triggered event.
*
* Linux sets the kernel code address each entry jumps to early during
* bootup, and never changes them. This is the general layout of the
* IDT entries:
*
* Vectors 0 ... 31 : system traps and exceptions - hardcoded events
* Vectors 32 ... 127 : device interrupts
* Vector 128 : legacy int80 syscall interface
* Vectors 129 ... LOCAL_TIMER_VECTOR-1
* Vectors LOCAL_TIMER_VECTOR ... 255 : special interrupts
*
* 64-bit x86 has per CPU IDT tables, 32-bit has one shared IDT table.
*
* This file enumerates the exact layout of them:
*/
* Visually this process can be shown as below. Suppose we have two main
* programs mainA and mainB and BPF object contains three subprogs: subA,
* subB, and subC. mainA calls only subA, mainB calls only subC, but subA and
* subC both call subB:
*
* +--------+ +-------+
* | v v |
* +--+---+ +--+-+-+ +---+--+
* | subA | | subB | | subC |
* +--+---+ +------+ +---+--+
* ^ ^
* | |
* +---+-------+ +------+----+
* | mainA | | mainB |
* +-----------+ +-----------+
*
* We'll start relocating mainA, will find subA, append it and start
* processing sub A recursively:
*
* +-----------+------+
* | mainA | subA |
* +-----------+------+
*
* At this point we notice that subB is used from subA, so we append it and
* relocate (there are no further subcalls from subB):
*
* +-----------+------+------+
* | mainA | subA | subB |
* +-----------+------+------+
*
* At this point, we relocate subA calls, then go one level up and finish with
* relocatin mainA calls. mainA is done.
*
* For mainB process is similar but results in different order. We start with
* mainB and skip subA and subB, as mainB never calls them (at least
* directly), but we see subC is needed, so we append and start processing it:
*
* +-----------+------+
* | mainB | subC |
* +-----------+------+
* Now we see subC needs subB, so we go back to it, append and relocate it:
*
* +-----------+------+------+
* | mainB | subC | subB |
* +-----------+------+------+
*
* At this point we unwind recursion, relocate calls in subC, then in mainB.
/*
* Explanation of delta-time stats:
*
* t = time of current schedule out event
* tprev = time of previous sched out event
* also time of schedule-in event for current task
* last_time = time of last sched change event for current task
* (i.e, time process was last scheduled out)
* ready_to_run = time of wakeup for current task
*
* -----|------------|------------|------------|------
* last ready tprev t
* time to run
*
* |-------- dt_wait --------|
* |- dt_delay -|-- dt_run --|
*
* dt_run = run time of current task
* dt_wait = time between last schedule out event for task and tprev
* represents time spent off the cpu
* dt_delay = time between wakeup and schedule-in of task
*/
* In the compat mode kernel runs in 64-bit and perf tool runs in 32-bit mode,
* 32-bit perf tool cannot access 64-bit value atomically, which might lead to
* the issues caused by the below sequence on multiple CPUs: when perf tool
* accesses either the load operation or the store operation for 64-bit value,
* on some architectures the operation is divided into two instructions, one
* is for accessing the low 32-bit value and another is for the high 32-bit;
* thus these two user operations can give the kernel chances to access the
* 64-bit value, and thus leads to the unexpected load values.
*
* kernel (64-bit) user (32-bit)
*
* if (LOAD ->aux_tail) { --, LOAD ->aux_head_lo
* STORE $aux_data | ,--->
* FLUSH $aux_data | | LOAD ->aux_head_hi
* STORE ->aux_head --|-------` smp_rmb()
* } | LOAD $data
* | smp_mb()
* | STORE ->aux_tail_lo
* `----------->
* STORE ->aux_tail_hi
*
* For this reason, it's impossible for the perf tool to work correctly when
* the AUX head or tail is bigger than 4GB (more than 32 bits length); and we
* can not simply limit the AUX ring buffer to less than 4GB, the reason is
* the pointers can be increased monotonically, whatever the buffer size it is,
* at the end the head and tail can be bigger than 4GB and carry out to the
* high 32-bit.
* bperf tries to reduce such wastes by allowing multiple perf_events of
* "cycles" or "instructions" (at different scopes) to share PMUs. Instead
* of having each perf-stat session to read its own perf_events, bperf uses
* BPF programs to read the perf_events and aggregate readings to BPF maps.
* Then, the perf-stat session(s) reads the values from these BPF maps.
*
* ||
* shared progs and maps <- || -> per session progs and maps
* ||
* --------------- ||
* | perf_events | ||
* --------------- fexit || -----------------
* | --------||----> | follower prog |
* --------------- / || --- -----------------
* cs -> | leader prog |/ ||/ | |
* --> --------------- /|| -------------- ------------------
* / | | / || | filter map | | accum_readings |
* / ------------ ------------ || -------------- ------------------
* | | prev map | | diff map | || |
* | ------------ ------------ || |
* \ || |
* = \ ==================================================== | ============
* \ / user space
* \ /
* \ /
* BPF_PROG_TEST_RUN BPF_MAP_LOOKUP_ELEM
* \ /
* \ /
* \------ perf-stat ----------------------/
*
* The figure above shows the architecture of bperf. Note that the figure
* is divided into 3 regions: shared progs and maps (top left), per session
* progs and maps (top right), and user space (bottom).
/*
* State machine of bkw_mmap_state:
*
* .________________(forbid)_____________.
* | V
* NOTREADY --(0)--> RUNNING --(1)--> DATA_PENDING --(2)--> EMPTY
* ^ ^ | ^ |
* | |__(forbid)____/ |___(forbid)___/|
* | |
* \_________________(3)_______________/
*
* NOTREADY : Backward ring buffers are not ready
* RUNNING : Backward ring buffers are recording
* DATA_PENDING : We are required to collect data from backward ring buffers
* EMPTY : We have collected data from backward ring buffers.
*
* (0): Setup backward ring buffer
* (1): Pause ring buffers for reading
* (2): Read from ring buffers
* (3): Resume ring buffers for recording
*/
/*
* data structure:
*
* +==================+ +============+ +======================+
* | class | | work | | atom |
* +==================+ +============+ +======================+
* +------------+ | +-----+ | | +------+ | | +-------+ +-----+ |
* | perf_kwork | +-> | irq | --------|+-> | eth0 | --+-> | raise | - | ... | --+ +-----------+
* +-----+------+ || +-----+ ||| +------+ ||| +-------+ +-----+ | | | |
* | || ||| ||| | +-> | atom_page |
* | || ||| ||| +-------+ +-----+ | | |
* | class_list ||| |+-> | entry | - | ... | ----> | |
* | || ||| ||| +-------+ +-----+ | | |
* | || ||| ||| | +-> | |
* | || ||| ||| +-------+ +-----+ | | | |
* | || ||| |+-> | exit | - | ... | --+ +-----+-----+
* | || ||| | | +-------+ +-----+ | |
* | || ||| | | | |
* | || ||| +-----+ | | | |
* | || |+-> | ... | | | | |
* | || | | +-----+ | | | |
* | || | | | | | |
* | || +---------+ | | +-----+ | | +-------+ +-----+ | |
* | +-> | softirq | -------> | RCU | ---+-> | raise | - | ... | --+ +-----+-----+
* | || +---------+ | | +-----+ ||| +-------+ +-----+ | | | |
* | || | | ||| | +-> | atom_page |
* | || | | ||| +-------+ +-----+ | | |
* | || | | |+-> | entry | - | ... | ----> | |
* | || | | ||| +-------+ +-----+ | | |
* | || | | ||| | +-> | |
* | || | | ||| +-------+ +-----+ | | | |
* | || | | |+-> | exit | - | ... | --+ +-----+-----+
* | || | | | | +-------+ +-----+ | |
* | || | | | | | |
* | || +-----------+ | | +-----+ | | | |
* | +-> | workqueue | -----> | ... | | | | |
* | | +-----------+ | | +-----+ | | | |
* | +==================+ +============+ +======================+ |
* | |
* +----> atom_page_list ---------------------------------------------------------+
*
*/
/*
* When perf record finishes a pass on every buffers, it records this pseudo
* event.
* We record the max timestamp t found in the pass n.
* Assuming these timestamps are monotonic across cpus, we know that if
* a buffer still has events with timestamps below t, they will be all
* available and then read in the pass n + 1.
* Hence when we start to read the pass n + 2, we can safely flush every
* events with timestamps below t.
*
* ============ PASS n =================
* CPU 0 | CPU 1
* |
* cnt1 timestamps | cnt2 timestamps
* 1 | 2
* 2 | 3
* - | 4 <--- max recorded
*
* ============ PASS n + 1 ==============
* CPU 0 | CPU 1
* |
* cnt1 timestamps | cnt2 timestamps
* 3 | 5
* 4 | 6
* 5 | 7 <---- max recorded
*
* Flush every events below timestamp 4
*
* ============ PASS n + 2 ==============
* CPU 0 | CPU 1
* |
* cnt1 timestamps | cnt2 timestamps
* 6 | 8
* 7 | 9
* - | 10
*
* Flush every events below timestamp 7
* etc...
*/
/*
* http://en.wikipedia.org/wiki/Algorithms_for_calculating_variance
*
* (\Sum n_i^2) - ((\Sum n_i)^2)/n
* s^2 = -------------------------------
* n - 1
*
* http://en.wikipedia.org/wiki/Stddev
*
* The std dev of the mean is related to the std dev by:
*
* s
* s_mean = -------
* sqrt(n)
*
*/
/*
* Use trigger to model operations which need to be executed when
* an event (a signal, for example) is observed.
*
* States and transits:
*
*
* OFF--> ON --> READY --(hit)--> HIT
* ^ |
* | (ready)
* | |
* \_____________/
*
* is_hit and is_ready are two key functions to query the state of
* a trigger. is_hit means the event already happen; is_ready means the
* trigger is waiting for the event.
*/
/* This magnitude comparison uses the signless first words and
* the regular part2 words. The comparison is graphically:
*
* 1st greater? -------------
* |
* 1st less?-----------------+---------
* | |
* 2nd greater or equal----->| |
* False True
*/
/*
* Generate an NFIT table to describe the following topology:
*
* BUS0: Interleaved PMEM regions, and aliasing with BLK regions
*
* (a) (b) DIMM BLK-REGION
* +----------+--------------+----------+---------+
* +------+ | blk2.0 | pm0.0 | blk2.1 | pm1.0 | 0 region2
* | imc0 +--+- - - - - region0 - - - -+----------+ +
* +--+---+ | blk3.0 | pm0.0 | blk3.1 | pm1.0 | 1 region3
* | +----------+--------------v----------v v
* +--+---+ | |
* | cpu0 | region1
* +--+---+ | |
* | +-------------------------^----------^ ^
* +--+---+ | blk4.0 | pm1.0 | 2 region4
* | imc1 +--+-------------------------+----------+ +
* +------+ | blk5.0 | pm1.0 | 3 region5
* +-------------------------+----------+-+-------+
*
* +--+---+
* | cpu1 |
* +--+---+ (Hotplug DIMM)
* | +----------------------------------------------+
* +--+---+ | blk6.0/pm7.0 | 4 region6/7
* | imc0 +--+----------------------------------------------+
* +------+
*
*
* *) In this layout we have four dimms and two memory controllers in one
* socket. Each unique interface (BLK or PMEM) to DPA space
* is identified by a region device with a dynamically assigned id.
*
* *) The first portion of dimm0 and dimm1 are interleaved as REGION0.
* A single PMEM namespace "pm0.0" is created using half of the
* REGION0 SPA-range. REGION0 spans dimm0 and dimm1. PMEM namespace
* allocate from from the bottom of a region. The unallocated
* portion of REGION0 aliases with REGION2 and REGION3. That
* unallacted capacity is reclaimed as BLK namespaces ("blk2.0" and
* "blk3.0") starting at the base of each DIMM to offset (a) in those
* DIMMs. "pm0.0", "blk2.0" and "blk3.0" are free-form readable
* names that can be assigned to a namespace.
*
* *) In the last portion of dimm0 and dimm1 we have an interleaved
* SPA range, REGION1, that spans those two dimms as well as dimm2
* and dimm3. Some of REGION1 allocated to a PMEM namespace named
* "pm1.0" the rest is reclaimed in 4 BLK namespaces (for each
* dimm in the interleave set), "blk2.1", "blk3.1", "blk4.0", and
* "blk5.0".
*
* *) The portion of dimm2 and dimm3 that do not participate in the
* REGION1 interleaved SPA range (i.e. the DPA address below offset
* (b) are also included in the "blk4.0" and "blk5.0" namespaces.
* Note, that BLK namespaces need not be contiguous in DPA-space, and
* can consume aliased capacity from multiple interleave sets.
*
* BUS1: Legacy NVDIMM (single contiguous range)
*
* region2
* +---------------------+
* |---------------------|
* || pm2.0 ||
* |---------------------|
* +---------------------+
*
* *) A NFIT-table may describe a simple system-physical-address range
* with no BLK aliasing. This type of region may optionally
* reference an NVDIMM.
*/
/* This program shows clang/llvm is able to generate code pattern
* like:
* _tcp_send_active_reset:
* 0: bf 16 00 00 00 00 00 00 r6 = r1
* ......
* 335: b7 01 00 00 0f 00 00 00 r1 = 15
* 336: 05 00 48 00 00 00 00 00 goto 72
*
* LBB0_3:
* 337: b7 01 00 00 01 00 00 00 r1 = 1
* 338: 63 1a d0 ff 00 00 00 00 *(u32 *)(r10 - 48) = r1
* 408: b7 01 00 00 03 00 00 00 r1 = 3
*
* LBB0_4:
* 409: 71 a2 fe ff 00 00 00 00 r2 = *(u8 *)(r10 - 2)
* 410: bf a7 00 00 00 00 00 00 r7 = r10
* 411: 07 07 00 00 b8 ff ff ff r7 += -72
* 412: bf 73 00 00 00 00 00 00 r3 = r7
* 413: 0f 13 00 00 00 00 00 00 r3 += r1
* 414: 73 23 2d 00 00 00 00 00 *(u8 *)(r3 + 45) = r2
*
* From the above code snippet, the code generated by the compiler
* is reasonable. The "r1" is assigned to different values in basic
* blocks "_tcp_send_active_reset" and "LBB0_3", and used in "LBB0_4".
* The verifier should be able to handle such code patterns.
*/
/* Array_A <------------------+
* elem_type == Array_B |
* | |
* | |
* Array_B <-------- + |
* elem_type == Array A --+
*/
/*
* End-to-end eBPF tunnel test suite
* The file tests BPF network tunnel implementation.
*
* Topology:
* ---------
* root namespace | at_ns0 namespace
* |
* ----------- | -----------
* | tnl dev | | | tnl dev | (overlay network)
* ----------- | -----------
* metadata-mode | metadata-mode
* with bpf | with bpf
* |
* ---------- | ----------
* | veth1 | --------- | veth0 | (underlay network)
* ---------- peer ----------
*
*
* Device Configuration
* --------------------
* root namespace with metadata-mode tunnel + BPF
* Device names and addresses:
* veth1 IP 1: 172.16.1.200, IPv6: 00::22 (underlay)
* IP 2: 172.16.1.20, IPv6: 00::bb (underlay)
* tunnel dev <type>11, ex: gre11, IPv4: 10.1.1.200, IPv6: 1::22 (overlay)
*
* Namespace at_ns0 with native tunnel
* Device names and addresses:
* veth0 IPv4: 172.16.1.100, IPv6: 00::11 (underlay)
* tunnel dev <type>00, ex: gre00, IPv4: 10.1.1.100, IPv6: 1::11 (overlay)
*
*
* End-to-end ping packet flow
* ---------------------------
* Most of the tests start by namespace creation, device configuration,
* then ping the underlay and overlay network. When doing 'ping 10.1.1.100'
* from root namespace, the following operations happen:
* 1) Route lookup shows 10.1.1.100/24 belongs to tnl dev, fwd to tnl dev.
* 2) Tnl device's egress BPF program is triggered and set the tunnel metadata,
* with local_ip=172.16.1.200, remote_ip=172.16.1.100. BPF program choose
* the primary or secondary ip of veth1 as the local ip of tunnel. The
* choice is made based on the value of bpf map local_ip_map.
* 3) Outer tunnel header is prepended and route the packet to veth1's egress.
* 4) veth0's ingress queue receive the tunneled packet at namespace at_ns0.
* 5) Tunnel protocol handler, ex: vxlan_rcv, decap the packet.
* 6) Forward the packet to the overlay tnl dev.
*/
/*
* Topology:
* ---------
* NS0 namespace | NS1 namespace | NS2 namespace
* | |
* +---------------+ | +---------------+ |
* | ipsec0 |---------| ipsec0 | |
* | 192.168.1.100 | | | 192.168.1.200 | |
* | if_id: bpf | | +---------------+ |
* +---------------+ | |
* | | | +---------------+
* | | | | ipsec0 |
* \------------------------------------------| 192.168.1.200 |
* | | +---------------+
* | |
* | | (overlay network)
* ------------------------------------------------------
* | | (underlay network)
* +--------------+ | +--------------+ |
* | veth01 |----------| veth10 | |
* | 172.16.1.100 | | | 172.16.1.200 | |
* ---------------+ | +--------------+ |
* | |
* +--------------+ | | +--------------+
* | veth02 |-----------------------------------| veth20 |
* | 172.16.2.100 | | | | 172.16.2.200 |
* +--------------+ | | +--------------+
*
*
* Test Packet flow
* -----------
* The tests perform 'ping 192.168.1.200' from the NS0 namespace:
* 1) request is routed to NS0 ipsec0
* 2) NS0 ipsec0 tc egress BPF program is triggered and sets the if_id based
* on the requested value. This makes the ipsec0 device in external mode
* select the destination tunnel
* 3) ping reaches the other namespace (NS1 or NS2 based on which if_id was
* used) and response is sent
* 4) response is received on NS0 ipsec0, tc ingress program is triggered and
* records the response if_id
* 5) requested if_id is compared with received if_id
*/
/* instructions used to output a skb based software event, produced
* from code snippet:
* struct TMP {
* uint64_t tmp;
* } tt;
* tt.tmp = 5;
* bpf_perf_event_output(skb, &connection_tracking_event_map, 0,
* &tt, sizeof(tt));
* return 1;
*
* the bpf assembly from llvm is:
* 0: b7 02 00 00 05 00 00 00 r2 = 5
* 1: 7b 2a f8 ff 00 00 00 00 *(u64 *)(r10 - 8) = r2
* 2: bf a4 00 00 00 00 00 00 r4 = r10
* 3: 07 04 00 00 f8 ff ff ff r4 += -8
* 4: 18 02 00 00 00 00 00 00 00 00 00 00 00 00 00 00 r2 = 0ll
* 6: b7 03 00 00 00 00 00 00 r3 = 0
* 7: b7 05 00 00 08 00 00 00 r5 = 8
* 8: 85 00 00 00 19 00 00 00 call 25
* 9: b7 00 00 00 01 00 00 00 r0 = 1
* 10: 95 00 00 00 00 00 00 00 exit
*
* The reason I put the code here instead of fill_helpers is that map fixup
* is against the insns, instead of filled prog.
*/
/*
* NOTES about DMA transfers:
*
* controller 1: channels 0-3, byte operations, ports 00-1F
* controller 2: channels 4-7, word operations, ports C0-DF
*
* - ALL registers are 8 bits only, regardless of transfer size
* - channel 4 is not used - cascades 1 into 2.
* - channels 0-3 are byte - addresses/counts are for physical bytes
* - channels 5-7 are word - addresses/counts are for physical words
* - transfers must not cross physical 64K (0-3) or 128K (5-7) boundaries
* - transfer count loaded to registers is 1 less than actual count
* - controller 2 offsets are all even (2x offsets for controller 1)
* - page registers for 5-7 don't use data bit 0, represent 128K pages
* - page registers for 0-3 use bit 0, represent 64K pages
*
* On CHRP, the W83C553F (and VLSI Tollgate?) support full 32 bit addressing.
* Note that addresses loaded into registers must be _physical_ addresses,
* not logical addresses (which may differ if paging is active).
*
* Address mapping for channels 0-3:
*
* A23 ... A16 A15 ... A8 A7 ... A0 (Physical addresses)
* | ... | | ... | | ... |
* | ... | | ... | | ... |
* | ... | | ... | | ... |
* P7 ... P0 A7 ... A0 A7 ... A0
* | Page | Addr MSB | Addr LSB | (DMA registers)
*
* Address mapping for channels 5-7:
*
* A23 ... A17 A16 A15 ... A9 A8 A7 ... A1 A0 (Physical addresses)
* | ... | \ \ ... \ \ \ ... \ \
* | ... | \ \ ... \ \ \ ... \ (not used)
* | ... | \ \ ... \ \ \ ... \
* P7 ... P1 (0) A7 A6 ... A0 A7 A6 ... A0
* | Page | Addr MSB | Addr LSB | (DMA registers)
*
* Again, channels 5-7 transfer _physical_ words (16 bits), so addresses
* and counts _must_ be word-aligned (the lowest address bit is _ignored_ at
* the hardware level, so odd-byte transfers aren't possible).
*
* Transfer count (_not # bytes_) is limited to 64K, represented as actual
* count - 1 : 64K => 0xFFFF, 1 => 0x0000. Thus, count is always 1 or more,
* and up to 128K bytes may be transferred on channels 5-7 in one operation.
*
*/
* CPU
* X: smp_muxed_ipi_set_message():
* X: smp_mb()
* X: message[RESCHEDULE] = 1
* X: doorbell_global_ipi(42):
* X: kvmppc_set_host_ipi(42)
* X: ppc_msgsnd_sync()/smp_mb()
* X: ppc_msgsnd() -> 42
* 42: doorbell_exception(): // from CPU X
* 42: ppc_msgsync()
* // STORE DEFERRED DUE TO RE-ORDERING
* -- 42: kvmppc_clear_host_ipi(42)
* | 42: smp_ipi_demux_relaxed()
* | 105: smp_muxed_ipi_set_message():
* | 105: smb_mb()
* | 105: message[CALL_FUNCTION] = 1
* | 105: doorbell_global_ipi(42):
* | 105: kvmppc_set_host_ipi(42)
* | // RE-ORDERED STORE COMPLETES
* -> 42: kvmppc_clear_host_ipi(42)
* 42: // returns to executing guest
* 105: ppc_msgsnd_sync()/smp_mb()
* 105: ppc_msgsnd() -> 42
* 42: local_paca->kvm_hstate.host_ipi == 0 // IPI ignored
* 105: // hangs waiting on 42 to process messages/call_single_queue
/*
* layout1 hierarchy:
*
* tmp
* ├── s1d1
* │ ├── f1
* │ ├── f2
* │ └── s1d2
* │ ├── f1
* │ ├── f2
* │ └── s1d3
* │ ├── f1
* │ └── f2
* ├── s2d1
* │ ├── f1
* │ └── s2d2
* │ ├── f1
* │ └── s2d3
* │ ├── f1
* │ └── f2
* └── s3d1
* ├── f1
* └── s3d2
* └── s3d3
*/
/*
* Parent + child domain (siblings)
* .------.
* | P1 ---. P1 -> P2 : deny
* '------' \ P2 -> P1 : deny
* .---'--.
* | P2 |
* '------'
*/
/* Stack layout:
*
* ^
* User stack |
* Back chain ------+ <- r1 <-------+
* ... |
* Red zone / ABI Gap |
* ... |
* vr63 <+ |
* vr0 | |
* VSCR | |
* FSCR | |
* r31 | Save area |
* r0 | |
* XER | |
* CTR | |
* LR | |
* CCR <+ |
* ... <+ |
* LR | Caller frame |
* CCR | |
* Back chain <+ <- updated r1 --------+
*
*/
* ----------------------------------------------
* | PHYSICAL ALLOCATION OF VIRTUAL STRUCT PAGES|
* ----------------------------------------------
*
* f000000000000000 c000000000000000
* vmemmap +--------------+ +--------------+
* + | page struct | +--------------> | page struct |
* | +--------------+ +--------------+
* | | page struct | +--------------> | page struct |
* | +--------------+ | +--------------+
* | | page struct | + +------> | page struct |
* | +--------------+ | +--------------+
* | | page struct | | +--> | page struct |
* | +--------------+ | | +--------------+
* | | page struct | | |
* | +--------------+ | |
* | | page struct | | |
* | +--------------+ | |
* | | page struct | | |
* | +--------------+ | |
* | | page struct | | |
* | +--------------+ | |
* | | page struct | +-------+ |
* | +--------------+ |
* | | page struct | +-----------+
* | +--------------+
* | | page struct | No mapping
* | +--------------+
* | | page struct | No mapping
* v +--------------+
*
* -----------------------------------------
* | RELATION BETWEEN STRUCT PAGES AND PFNS|
* -----------------------------------------
*
* vmemmap +--------------+ +---------------+
* + | page struct | +-------------> | PFN |
* | +--------------+ +---------------+
* | | page struct | +-------------> | PFN |
* | +--------------+ +---------------+
* | | page struct | +-------------> | PFN |
* | +--------------+ +---------------+
* | | page struct | +-------------> | PFN |
* | +--------------+ +---------------+
* | | |
* | +--------------+
* | | |
* | +--------------+
* | | |
* | +--------------+ +---------------+
* | | page struct | +-------------> | PFN |
* | +--------------+ +---------------+
* | | |
* | +--------------+
* | | |
* | +--------------+ +---------------+
* | | page struct | +-------------> | PFN |
* | +--------------+ +---------------+
* | | page struct | +-------------> | PFN |
* v +--------------+ +---------------+
* Split/unsplit procedure:
*
* A core can be in one of three states, unsplit, 2-way split, and 4-way split.
*
* The mapping to subcores_per_core is simple:
*
* State | subcores_per_core
* ------------|------------------
* Unsplit | 1
* 2-way split | 2
* 4-way split | 4
*
* The core is split along thread boundaries, the mapping between subcores and
* threads is as follows:
*
* Unsplit:
* ----------------------------
* Subcore | 0 |
* ----------------------------
* Thread | 0 1 2 3 4 5 6 7 |
* ----------------------------
*
* 2-way split:
* -------------------------------------
* Subcore | 0 | 1 |
* -------------------------------------
* Thread | 0 1 2 3 | 4 5 6 7 |
* -------------------------------------
*
* 4-way split:
* -----------------------------------------
* Subcore | 0 | 1 | 2 | 3 |
* -----------------------------------------
* Thread | 0 1 | 2 3 | 4 5 | 6 7 |
* -----------------------------------------
*
*
* Transitions
* -----------
*
* It is not possible to transition between either of the split states, the
* core must first be unsplit. The legal transitions are:
*
* ----------- ---------------
* | | <----> | 2-way split |
* | | ---------------
* | Unsplit |
* | | ---------------
* | | <----> | 4-way split |
* ----------- ---------------
-=-=-= FORMAT =-=-=-
+----+-------+-------+-------+-------+ +------------+-------+-------+-------+
RRR | op | RC | RB | RA | RT | RI7 | op | I7 | RA | RT |
+----+-------+-------+-------+-------+ +------------+-------+-------+-------+
0 3 1 1 2 3 0 1 1 2 3
0 7 4 1 0 7 4 1
+-----------+--------+-------+-------+ +---------+----------+-------+-------+
RI8 | op | I8 | RA | RT | RI10 | op | I10 | RA | RT |
+-----------+--------+-------+-------+ +---------+----------+-------+-------+
0 9 1 2 3 0 7 1 2 3
7 4 1 7 4 1
+----------+-----------------+-------+ +--------+-------------------+-------+
RI16 | op | I16 | RT | RI18 | op | I18 | RT |
+----------+-----------------+-------+ +--------+-------------------+-------+
0 8 2 3 0 6 2 3
4 1 4 1
+------------+-------+-------+-------+ +-------+--+-----------------+-------+
RR | op | RB | RA | RT | LBT | op |RO| I16 | RO |
+------------+-------+-------+-------+ +-------+--+-----------------+-------+
0 1 1 2 3 0 6 8 2 3
0 7 4 1 4 1
+------------+----+--+-------+-------+
LBTI | op | // |RO| RA | RO |
+------------+----+--+-------+-------+
0 1 1 1 2 3
0 5 7 4 1
/*
* ioctl flag definitions
*
* POINT - Toggle decimal point (0=absent 1=present)
* ALARM - Toggle alarm LED (0=green 1=red)
* FLIP - Toggle inverted mode (0=normal 1=flipped)
* bits 0-4 - Character displayed (see definitions below)
*
* Display segments are defined as follows,
* subject to D7S_FLIP register state:
*
* a
* ---
* f| |b
* -g-
* e| |c
* ---
* d
*/
/* The Sparc PSR fields are laid out as the following:
*
* ------------------------------------------------------------------------
* | impl | vers | icc | resv | EC | EF | PIL | S | PS | ET | CWP |
* | 31-28 | 27-24 | 23-20 | 19-14 | 13 | 12 | 11-8 | 7 | 6 | 5 | 4-0 |
* ------------------------------------------------------------------------
*/
/*
* When booting in 64-bit mode on 32-bit EFI firmware, startup_64_mixed_mode()
* is the first thing that runs after switching to long mode. Depending on
* whether the EFI handover protocol or the compat entry point was used to
* enter the kernel, it will either branch to the 64-bit EFI handover
* entrypoint at offset 0x390 in the image, or to the 64-bit EFI PE/COFF
* entrypoint efi_pe_entry(). In the former case, the bootloader must provide a
* struct bootparams pointer as the third argument, so the presence of such a
* pointer is used to disambiguate.
*
* +--------------+
* +------------------+ +------------+ +------>| efi_pe_entry |
* | efi32_pe_entry |---->| | | +-----------+--+
* +------------------+ | | +------+----------------+ |
* | startup_32 |---->| startup_64_mixed_mode | |
* +------------------+ | | +------+----------------+ V
* | efi32_stub_entry |---->| | | +------------------+
* +------------------+ +------------+ +---->| efi64_stub_entry |
* +-------------+----+
* +------------+ +----------+ |
* | startup_64 |<----| efi_main |<--------------+
* +------------+ +----------+
*/
/* AES inverse affine and S2 combined:
* 1 1 0 0 0 0 0 1 x0 0
* 0 1 0 0 1 0 0 0 x1 0
* 1 1 0 0 1 1 1 1 x2 0
* 0 1 1 0 1 0 0 1 x3 1
* 0 1 0 0 1 1 0 0 * x4 + 0
* 0 1 0 1 1 0 0 0 x5 0
* 0 0 0 0 0 1 0 1 x6 0
* 1 1 1 0 0 1 1 1 x7 1
*/
/*
* The CPU_BUS_NUMBER MSR returns the values of the respective CPUBUSNO CSR
* that BIOS programmed. MSR has package scope.
* | Bit | Default | Description
* | [63] | 00h | VALID - When set, indicates the CPU bus
* numbers have been initialized. (RO)
* |[62:48]| --- | Reserved
* |[47:40]| 00h | BUS_NUM_5 - Return the bus number BIOS assigned
* CPUBUSNO(5). (RO)
* |[39:32]| 00h | BUS_NUM_4 - Return the bus number BIOS assigned
* CPUBUSNO(4). (RO)
* |[31:24]| 00h | BUS_NUM_3 - Return the bus number BIOS assigned
* CPUBUSNO(3). (RO)
* |[23:16]| 00h | BUS_NUM_2 - Return the bus number BIOS assigned
* CPUBUSNO(2). (RO)
* |[15:8] | 00h | BUS_NUM_1 - Return the bus number BIOS assigned
* CPUBUSNO(1). (RO)
* | [7:0] | 00h | BUS_NUM_0 - Return the bus number BIOS assigned
* CPUBUSNO(0). (RO)
*/
* DMA transfers are limited to the lower 16MB of _physical_ memory.
* Note that addresses loaded into registers must be _physical_ addresses,
* not logical addresses (which may differ if paging is active).
*
* Address mapping for channels 0-3:
*
* A23 ... A16 A15 ... A8 A7 ... A0 (Physical addresses)
* | ... | | ... | | ... |
* | ... | | ... | | ... |
* | ... | | ... | | ... |
* P7 ... P0 A7 ... A0 A7 ... A0
* | Page | Addr MSB | Addr LSB | (DMA registers)
*
* Address mapping for channels 5-7:
*
* A23 ... A17 A16 A15 ... A9 A8 A7 ... A1 A0 (Physical addresses)
* | ... | \ \ ... \ \ \ ... \ \
* | ... | \ \ ... \ \ \ ... \ (not used)
* | ... | \ \ ... \ \ \ ... \
* P7 ... P1 (0) A7 A6 ... A0 A7 A6 ... A0
* | Page | Addr MSB | Addr LSB | (DMA registers)
*
* Again, channels 5-7 transfer _physical_ words (16 bits), so addresses
* and counts _must_ be word-aligned (the lowest address bit is _ignored_ at
* the hardware level, so odd-byte transfers aren't possible).
*
* Transfer count (_not # bytes_) is limited to 64K, represented as actual
* count - 1 : 64K => 0xFFFF, 1 => 0x0000. Thus, count is always 1 or more,
* and up to 128K bytes may be transferred on channels 5-7 in one operation.
/*
* Check for clue free BIOS implementations who use
* the following QA technique
*
* [ Write BIOS Code ]<------
* | ^
* < Does it Compile >----N--
* |Y ^
* < Does it Boot Win98 >-N--
* |Y
* [Ship It]
*
* Phoenix A04 08/24/2000 is known bad (Dell Inspiron 5000e)
* Phoenix A07 09/29/2000 is known good (Dell Inspiron 5000)
*/
/*---------------------------------------------------------------------------+
| Divide the 96 bit quantity pointed to by a, by that pointed to by b, and |
| put the 96 bit result at the location d. |
| |
| The result may not be accurate to 96 bits. It is intended for use where |
| a result better than 64 bits is required. The result should usually be |
| good to at least 94 bits. |
| The returned result is actually divided by one half. This is done to |
| prevent overflow. |
| |
| .aaaaaaaaaaaaaa / .bbbbbbbbbbbbb -> .dddddddddddd |
| |
| void div_Xsig(Xsig *a, Xsig *b, Xsig *dest) |
| |
+---------------------------------------------------------------------------*/
* The logical flat p2m table is mapped to a linear kernel memory area.
* For accesses by Xen a three-level tree linked via mfns only is set up to
* allow the address space to be sparse.
*
* Xen
* |
* p2m_top_mfn
* / \
* p2m_mid_mfn p2m_mid_mfn
* / /
* p2m p2m p2m ...
*
* The p2m_mid_mfn pages are mapped by p2m_top_mfn_p.
*
* The p2m_top_mfn level is limited to 1 page, so the maximum representable
* pseudo-physical address space is:
* P2M_TOP_PER_PAGE * P2M_MID_PER_PAGE * P2M_PER_PAGE pages
*
* P2M_PER_PAGE depends on the architecture, as a mfn is always
* unsigned long (8 bytes on 64-bit, 4 bytes on 32), leading to
* 512 and 1024 entries respectively.
/* NOTE: the time values in jiffies should be in msec!
CMOS drive type
| Maximum data rate supported by drive type
| | Head load time, msec
| | | Head unload time, msec (not used)
| | | | Step rate interval, usec
| | | | | Time needed for spinup time (jiffies)
| | | | | | Timeout for spinning down (jiffies)
| | | | | | | Spindown offset (where disk stops)
| | | | | | | | Select delay
| | | | | | | | | RPS
| | | | | | | | | | Max number of tracks
| | | | | | | | | | | Interrupt timeout
| | | | | | | | | | | | Max nonintlv. sectors
| | | | | | | | | | | | | -Max Errors- flags */
/*
* Clock dividers in Berlin2 SoCs comprise a complex cell to select
* input pll and divider. The virtual structure as it is used in Marvell
* BSP code can be seen as:
*
* +---+
* pll0 --------------->| 0 | +---+
* +---+ |(B)|--+--------------->| 0 | +---+
* pll1.0 -->| 0 | +-->| 1 | | +--------+ |(E)|----->| 0 | +---+
* pll1.1 -->| 1 | | +---+ +-->|(C) 1:M |-->| 1 | |(F)|-->|(G)|->
* ... -->|(A)|--+ | +--------+ +---+ +-->| 1 | +---+
* ... -->| | +-->|(D) 1:3 |----------+ +---+
* pll1.N -->| N | +---------
* +---+
*
* (A) input pll clock mux controlled by <PllSelect[1:n]>
* (B) input pll bypass mux controlled by <PllSwitch>
* (C) programmable clock divider controlled by <Select[1:n]>
* (D) constant div-by-3 clock divider
* (E) programmable clock divider bypass controlled by <Switch>
* (F) constant div-by-3 clock mux controlled by <D3Switch>
* (G) clock gate controlled by <Enable>
*
* For whatever reason, above control signals come in two flavors:
* - single register dividers with all bits in one register
* - shared register dividers with bits spread over multiple registers
* (including signals for the same cell spread over consecutive registers)
*
* Also, clock gate and pll mux is not available on every div cell, so
* we have to deal with those, too. We reuse common clock composite driver
* for it.
*/
/*
* We have to follow a strict procedure when changing the LDB clock source,
* otherwise we risk introducing a glitch that can lock up the LDB divider.
* Things to keep in mind:
*
* 1. The current and new parent clock inputs to the mux must be disabled.
* 2. The default clock input for ldb_di0/1_clk_sel is mmdc_ch1_axi, which
* has no CG bit.
* 3. pll2_pfd2_396m can not be gated if it is used as memory clock.
* 4. In the RTL implementation of the LDB_DI_CLK_SEL muxes the top four
* options are in one mux and the PLL3 option along with three unused
* inputs is in a second mux. There is a third mux with two inputs used
* to decide between the first and second 4-port mux:
*
* pll5_video_div 0 --|\
* pll2_pfd0_352m 1 --| |_
* pll2_pfd2_396m 2 --| | `-|\
* mmdc_ch1_axi 3 --|/ | |
* | |--
* pll3_usb_otg 4 --|\ | |
* 5 --| |_,-|/
* 6 --| |
* 7 --|/
*
* The ldb_di0/1_clk_sel[1:0] bits control both 4-port muxes at the same time.
* The ldb_di0/1_clk_sel[2] bit controls the 2-port mux. The code below
* switches the parent to the bottom mux first and then manipulates the top
* mux to ensure that no glitch will enter the divider.
*/
/*
* CKEN clock type
* This clock takes it source from 2 possible parents :
* - a low power parent
* - a normal parent
*
* +------------+ +-----------+
* | Low Power | --- | x mult_lp |
* | Clock | | / div_lp |\
* +------------+ +-----------+ \+-----+ +-----------+
* | Mux |---| CKEN gate |
* +------------+ +-----------+ /+-----+ +-----------+
* | High Power | | x mult_hp |/
* | Clock | --- | / div_hp |
* +------------+ +-----------+
*/
/*
* This is a frequency table for "General Purpose" clocks.
* These clocks can be muxed to the SoC pins and may be used by
* external devices. They're often used as PWM source.
*
* Please note that MND divider must be enabled for duty-cycle
* control to be possible. (M != N) Also since D register is configured
* with a value multiplied by 2, and duty cycle is calculated as
* (2 * D) % 2^W
* DutyCycle = ----------------
* 2 * (N % 2^W)
* (where W = .mnd_width)
* N must be half or less than maximum value for the register.
* Otherwise duty-cycle control would be limited.
* (e.g. for 8-bit NMD N should be less than 128)
*/
/*
* Register a clock branch.
* Most clock branches have a form like
*
* src1 --|--\
* |M |--[GATE]-[DIV]-
* src2 --|--/
*
* sometimes without one of those components.
*/
/*
* sunxi_divs_clk_setup() - Setup function for leaf divisors on clocks
*
* These clocks look something like this
* ________________________
* | ___divisor 1---|----> to consumer
* parent >--| pll___/___divisor 2---|----> to consumer
* | \_______________|____> to consumer
* |________________________|
*/
/*
* Copy architecture-specific thread state
*
* Layout of Child kernel mode stack as setup at the end of this function is
*
* | ... |
* | ... |
* | unused |
* | |
* ------------------
* | r25 | <==== top of Stack (thread.ksp)
* ~ ~
* | --to-- | (CALLEE Regs of kernel mode)
* | r13 |
* ------------------
* | fp |
* | blink | @ret_from_fork
* ------------------
* | |
* ~ ~
* ~ ~
* | |
* ------------------
* | r12 |
* ~ ~
* | --to-- | (scratch Regs of user mode)
* | r0 |
* ------------------
* | SP |
* | orig_r0 |
* | event/ECR |
* | user_r25 |
* ------------------ <===== END of PAGE
*/
/*
* i.MX8M DRAM Controller clocks have the following structure (abridged):
*
* +----------+ |\ +------+
* | dram_pll |-------|M| dram_core | |
* +----------+ |U|---------->| D |
* /--|X| | D |
* dram_alt_root | |/ | R |
* | | C |
* +---------+ | |
* |FIX DIV/4| | |
* +---------+ | |
* composite: | | |
* +----------+ | | |
* | dram_alt |----/ | |
* +----------+ | |
* | dram_apb |-------------------->| |
* +----------+ +------+
*
* The dram_pll is used for higher rates and dram_alt is used for lower rates.
*
* Frequency switching is implemented in TF-A (via SMC call) and can change the
* configuration of the clocks, including mux parents. The dram_alt and
* dram_apb clocks are "imx composite" and their parent can change too.
*
* We need to prepare/enable the new mux parents head of switching and update
* their information afterwards.
*/
/*****************************************************************************
* MVEBU GPIO IRQ
*
* GPIO_IN_POL register controls whether GPIO_DATA_IN will hold the same
* value of the line or the opposite value.
*
* Level IRQ handlers: DATA_IN is used directly as cause register.
* Interrupt are masked by LEVEL_MASK registers.
* Edge IRQ handlers: Change in DATA_IN are latched in EDGE_CAUSE.
* Interrupt are masked by EDGE_MASK registers.
* Both-edge handlers: Similar to regular Edge handlers, but also swaps
* the polarity to catch the next line transaction.
* This is a race condition that might not perfectly
* work on some use cases.
*
* Every eight GPIO lines are grouped (OR'ed) before going up to main
* cause register.
*
* EDGE cause mask
* data-in /--------| |-----| |----\
* -----| |----- ---- to main cause reg
* X \----------------| |----/
* polarity LEVEL mask
*
****************************************************************************/
/*
* TS-5500 DIO1 block
*
* value control dir hw
* addr bit addr bit in out irq name pin offset
*
* 0x7b 0 0x7a 0 x x DIO1_0 1 0
* 0x7b 1 0x7a 0 x x DIO1_1 3 1
* 0x7b 2 0x7a 0 x x DIO1_2 5 2
* 0x7b 3 0x7a 0 x x DIO1_3 7 3
* 0x7b 4 0x7a 1 x x DIO1_4 9 4
* 0x7b 5 0x7a 1 x x DIO1_5 11 5
* 0x7b 6 0x7a 1 x x DIO1_6 13 6
* 0x7b 7 0x7a 1 x x DIO1_7 15 7
* 0x7c 0 0x7a 5 x x DIO1_8 4 8
* 0x7c 1 0x7a 5 x x DIO1_9 6 9
* 0x7c 2 0x7a 5 x x DIO1_10 8 10
* 0x7c 3 0x7a 5 x x DIO1_11 10 11
* 0x7c 4 x DIO1_12 12 12
* 0x7c 5 x 7 DIO1_13 14 13
*/
* reflect-x::
*
* |o | | o|
* | | -> | |
* | v| |v |
*
* reflect-y::
*
* |o | | ^|
* | | -> | |
* | v| |o |
* For historical reference, the vertical blanking period was designed to
* give the electron gun (on CRTs) enough time to move back to the top of
* the screen to start scanning out the next frame. Similar for horizontal
* blanking periods. They were designed to give the electron gun enough
* time to move back to the other side of the screen to start scanning the
* next scanline.
*
* ::
*
*
* physical → ⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽
* top of | |
* display | |
* | New frame |
* | |
* |↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓|
* |~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~| ← Scanline,
* |↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓↓| updates the
* | | frame as it
* | | travels down
* | | ("scan out")
* | Old frame |
* | |
* | |
* | |
* | | physical
* | | bottom of
* vertical |⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽| ← display
* blanking ┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆
* region → ┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆
* ┆xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx┆
* start of → ⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽⎽
* new frame
*
* "Physical top of display" is the reference point for the high-precision/
* corrected timestamp.
/**
* speakersToChannels
*
* @brief
* translate speakers to channels
*
* FL - Front Left
* FR - Front Right
* RL - Rear Left
* RR - Rear Right
* RC - Rear Center
* FC - Front Center
* FLC - Front Left Center
* FRC - Front Right Center
* RLC - Rear Left Center
* RRC - Rear Right Center
* LFE - Low Freq Effect
*
* FC
* FLC FRC
* FL FR
*
* LFE
* ()
*
*
* RL RR
* RLC RRC
* RC
*
* ch 8 7 6 5 4 3 2 1
* 0b00000011 - - - - - - FR FL
* 0b00000111 - - - - - LFE FR FL
* 0b00001011 - - - - FC - FR FL
* 0b00001111 - - - - FC LFE FR FL
* 0b00010011 - - - RC - - FR FL
* 0b00010111 - - - RC - LFE FR FL
* 0b00011011 - - - RC FC - FR FL
* 0b00011111 - - - RC FC LFE FR FL
* 0b00110011 - - RR RL - - FR FL
* 0b00110111 - - RR RL - LFE FR FL
* 0b00111011 - - RR RL FC - FR FL
* 0b00111111 - - RR RL FC LFE FR FL
* 0b01110011 - RC RR RL - - FR FL
* 0b01110111 - RC RR RL - LFE FR FL
* 0b01111011 - RC RR RL FC - FR FL
* 0b01111111 - RC RR RL FC LFE FR FL
* 0b11110011 RRC RLC RR RL - - FR FL
* 0b11110111 RRC RLC RR RL - LFE FR FL
* 0b11111011 RRC RLC RR RL FC - FR FL
* 0b11111111 RRC RLC RR RL FC LFE FR FL
* 0b11000011 FRC FLC - - - - FR FL
* 0b11000111 FRC FLC - - - LFE FR FL
* 0b11001011 FRC FLC - - FC - FR FL
* 0b11001111 FRC FLC - - FC LFE FR FL
* 0b11010011 FRC FLC - RC - - FR FL
* 0b11010111 FRC FLC - RC - LFE FR FL
* 0b11011011 FRC FLC - RC FC - FR FL
* 0b11011111 FRC FLC - RC FC LFE FR FL
* 0b11110011 FRC FLC RR RL - - FR FL
* 0b11110111 FRC FLC RR RL - LFE FR FL
* 0b11111011 FRC FLC RR RL FC - FR FL
* 0b11111111 FRC FLC RR RL FC LFE FR FL
*
* @param
* speakers - speaker information as it comes from CEA audio block
*/
/*
* Split is introduced for workaround scaler's input/output size limitation.
* The idea is simple, if one scaler can not fit the requirement, use two.
* So split splits the big source image to two half parts (left/right) and do
* the scaling by two scaler separately and independently.
* But split also imports an edge problem in the middle of the image when
* scaling, to avoid it, split isn't a simple half-and-half, but add an extra
* pixels (overlap) to both side, after split the left/right will be:
* - left: [0, src_length/2 + overlap]
* - right: [src_length/2 - overlap, src_length]
* The extra overlap do eliminate the edge problem, but which may also generates
* unnecessary pixels when scaling, we need to crop them before scaler output
* the result to the next stage. and for the how to crop, it depends on the
* unneeded pixels, another words the position where overlay has been added.
* - left: crop the right
* - right: crop the left
*
* The diagram for how to do the split
*
* <---------------------left->out_w ---------------->
* |--------------------------------|---right_crop-----| <- left after split
* \ \ /
* \ \<--overlap--->/
* |-----------------|-------------|(Middle)------|-----------------| <- src
* /<---overlap--->\ \
* / \ \
* right after split->|-----left_crop---|--------------------------------|
* ^<------------------- right->out_w --------------->^
*
* NOTE: To consistent with HW the output_w always contains the crop size.
*/
* A note about interlacing. Let's consider HDMI 1920x1080i.
* The timing parameters we have from X are:
* Hact HsyA HsyI Htot Vact VsyA VsyI Vtot
* 1920 2448 2492 2640 1080 1084 1094 1125
* Which get translated to:
* Hact HsyA HsyI Htot Vact VsyA VsyI Vtot
* 1920 2448 2492 2640 540 542 547 562
*
* This is how it is defined by CEA-861-D - line and pixel numbers are
* referenced to the rising edge of VSYNC and HSYNC. Total clocks per
* line: 2640. The odd frame, the first active line is at line 21, and
* the even frame, the first active line is 584.
*
* LN: 560 561 562 563 567 568 569
* DE: ~~~|____________________________//__________________________
* HSYNC: ____|~|_____|~|_____|~|_____|~|_//__|~|_____|~|_____|~|_____
* VSYNC: _________________________|~~~~~~//~~~~~~~~~~~~~~~|__________
* 22 blanking lines. VSYNC at 1320 (referenced to the HSYNC rising edge).
*
* LN: 1123 1124 1125 1 5 6 7
* DE: ~~~|____________________________//__________________________
* HSYNC: ____|~|_____|~|_____|~|_____|~|_//__|~|_____|~|_____|~|_____
* VSYNC: ____________________|~~~~~~~~~~~//~~~~~~~~~~|_______________
* 23 blanking lines
*
* The Armada LCD Controller line and pixel numbers are, like X timings,
* referenced to the top left of the active frame.
* Assumptions about the fictitious mode used in this example:
* vblank_start >= 3
* vsync_start = vblank_start + 1
* vsync_end = vblank_start + 2
* vtotal = vblank_start + 3
*
* start of vblank:
* latch double buffered registers
* increment frame counter (ctg+)
* generate start of vblank interrupt (gen4+)
* |
* | frame start:
* | generate frame start interrupt (aka. vblank interrupt) (gmch)
* | may be shifted forward 1-3 extra lines via PIPECONF
* | |
* | | start of vsync:
* | | generate vsync interrupt
* | | |
* ___xxxx___ ___xxxx___ ___xxxx___ ___xxxx___ ___xxxx___ ___xxxx
* . \hs/ . \hs/ \hs/ \hs/ . \hs/
* ----va---> <-----------------vb--------------------> <--------va-------------
* | | <----vs-----> |
* -vbs-----> <---vbs+1---> <---vbs+2---> <-----0-----> <-----1-----> <-----2--- (scanline counter gen2)
* -vbs-2---> <---vbs-1---> <---vbs-----> <---vbs+1---> <---vbs+2---> <-----0--- (scanline counter gen3+)
* -vbs-2---> <---vbs-2---> <---vbs-1---> <---vbs-----> <---vbs+1---> <---vbs+2- (scanline counter hsw+ hdmi)
* | | |
* last visible pixel first visible pixel
* | increment frame counter (gen3/4)
* pixel counter = vblank_start * htotal pixel counter = 0 (gen3/4)
*
* x = horizontal active
* _ = horizontal blanking
* hs = horizontal sync
* va = vertical active
* vb = vertical blanking
* vs = vertical sync
* vbs = vblank_start (number)
*
* Summary:
* - most events happen at the start of horizontal sync
* - frame start happens at the start of horizontal blank, 1-4 lines
* (depending on PIPECONF settings) after the start of vblank
* - gen3/4 pixel and frame counter are synchronized with the start
* of horizontal active on the first line of vertical active
* Generally on VLV/CHV the common lane corresponds to the pipe and
* the spline (PCS/TX) corresponds to the port.
*
* For dual channel PHY (VLV/CHV):
*
* pipe A == CMN/PLL/REF CH0
*
* pipe B == CMN/PLL/REF CH1
*
* port B == PCS/TX CH0
*
* port C == PCS/TX CH1
*
* This is especially important when we cross the streams
* ie. drive port B with pipe B, or port C with pipe A.
*
* For single channel PHY (CHV):
*
* pipe C == CMN/PLL/REF CH0
*
* port D == PCS/TX CH0
*
* On BXT the entire PHY channel corresponds to the port. That means
* the PLL is also now associated with the port rather than the pipe,
* and so the clock needs to be routed to the appropriate transcoder.
* Port A PLL is directly connected to transcoder EDP and port B/C
* PLLs can be routed to any transcoder A/B/C.
*
* Note: DDI0 is digital port B, DD1 is digital port C, and DDI2 is
* digital port D (CHV) or port A (BXT). ::
*
*
* Dual channel PHY (VLV/CHV/BXT)
* ---------------------------------
* | CH0 | CH1 |
* | CMN/PLL/REF | CMN/PLL/REF |
* |---------------|---------------| Display PHY
* | PCS01 | PCS23 | PCS01 | PCS23 |
* |-------|-------|-------|-------|
* |TX0|TX1|TX2|TX3|TX0|TX1|TX2|TX3|
* ---------------------------------
* | DDI0 | DDI1 | DP/HDMI ports
* ---------------------------------
*
* Single channel PHY (CHV/BXT)
* -----------------
* | CH0 |
* | CMN/PLL/REF |
* |---------------| Display PHY
* | PCS01 | PCS23 |
* |-------|-------|
* |TX0|TX1|TX2|TX3|
* -----------------
* | DDI2 | DP/HDMI port
* -----------------
* Note that for packed YCbCr 4:2:2 formats there is no way to
* control chroma siting. The hardware simply replicates the
* chroma samples for both of the luma samples, and thus we don't
* actually get the expected MPEG2 chroma siting convention :(
* The same behaviour is observed on pre-SKL platforms as well.
*
* Theory behind the formula (note that we ignore sub-pixel
* source coordinates):
* s = source sample position
* d = destination sample position
*
* Downscaling 4:1:
* -0.5
* | 0.0
* | | 1.5 (initial phase)
* | | |
* v v v
* | s | s | s | s |
* | d |
*
* Upscaling 1:4:
* -0.5
* | -0.375 (initial phase)
* | | 0.0
* | | |
* v v v
* | s |
* | d | d | d | d |
/*
* +------------+---------------------------------------------------+
* | PHASE | FIRMWARE STATUS TRANSITIONS |
* +============+===================================================+
* | | UNINITIALIZED |
* +------------+- / | \ -+
* | | DISABLED <--/ | \--> NOT_SUPPORTED |
* | init_early | V |
* | | SELECTED |
* +------------+- / | \ -+
* | | MISSING <--/ | \--> ERROR |
* | fetch | V |
* | | AVAILABLE |
* +------------+- | \ -+
* | | | \--> INIT FAIL |
* | init | V |
* | | /------> LOADABLE <----<-----------\ |
* +------------+- \ / \ \ \ -+
* | | LOAD FAIL <--< \--> TRANSFERRED \ |
* | upload | \ / \ / |
* | | \---------/ \--> RUNNING |
* +------------+---------------------------------------------------+
*/
/*
* Hardware-wise, we have a two level page table structure, where the first
* level has 4096 entries, and the second level has 256 entries. Each entry
* is one 32-bit word. Most of the bits in the second level entry are used
* by hardware, and there aren't any "accessed" and "dirty" bits.
*
* Linux on the other hand has a three level page table structure, which can
* be wrapped to fit a two level page table structure easily - using the PGD
* and PTE only. However, Linux also expects one "PTE" table per page, and
* at least a "dirty" bit.
*
* Therefore, we tweak the implementation slightly - we tell Linux that we
* have 2048 entries in the first level, each of which is 8 bytes (iow, two
* hardware pointers to the second level.) The second level contains two
* hardware PTE tables arranged contiguously, preceded by Linux versions
* which contain the state information Linux needs. We, therefore, end up
* with 512 entries in the "PTE" level.
*
* This leads to the page tables having the following layout:
*
* pgd pte
* | |
* +--------+
* | | +------------+ +0
* +- - - - + | Linux pt 0 |
* | | +------------+ +1024
* +--------+ +0 | Linux pt 1 |
* | |-----> +------------+ +2048
* +- - - - + +4 | h/w pt 0 |
* | |-----> +------------+ +3072
* +--------+ +8 | h/w pt 1 |
* | | +------------+ +4096
*
* See L_PTE_xxx below for definitions of bits in the "Linux pt", and
* PTE_xxx for definitions of bits appearing in the "h/w pt".
*
* PMD_xxx definitions refer to bits in the first level page table.
*
* The "dirty" bit is emulated by only granting hardware write permission
* iff the page is marked "writable" and "dirty" in the Linux PTE. This
* means that a write to a clean page will cause a permission fault, and
* the Linux MM layer will mark the page dirty via handle_pte_fault().
* For the hardware to notice the permission change, the TLB entry must
* be flushed, and ptep_set_access_flags() does that for us.
*
* The "accessed" or "young" bit is emulated by a similar method; we only
* allow accesses to the page if the "young" bit is set. Accesses to the
* page will cause a fault, and handle_pte_fault() will set the young bit
* for us as long as the page is marked present in the corresponding Linux
* PTE entry. Again, ptep_set_access_flags() will ensure that the TLB is
* up to date.
*
* However, when the "young" bit is cleared, we deny access to the page
* by clearing the hardware PTE. Currently Linux does not flush the TLB
* for us in this case, which means the TLB will retain the transation
* until either the TLB entry is evicted under pressure, or a context
* switch which changes the user space mapping occurs.
*/
* The hardware has four display pipes, and the layout is a little
* bit like this::
*
* Memory -> Overlay -> Channel -> FIFO -> 8 formatters -> DSI/DPI
* External 0..5 0..3 A,B, 6 x DSI bridge
* source 0..9 C0,C1 2 x DPI
*
* FIFOs A and B are for LCD and HDMI while FIFO CO/C1 are for
* panels with embedded buffer.
* 6 of the formatters are for DSI, 3 pairs for VID/CMD respectively.
* 2 of the formatters are for DPI.
* Clock generator scheme :
*
* .. code::
*
* __________ _________ _____
* | | | | | |--ENCI
* | HDMI PLL |-| PLL_DIV |--- VCLK--| |--ENCL
* |__________| |_________| \ | MUX |--ENCP
* --VCLK2-| |--VDAC
* |_____|--HDMI-TX
*
* Final clocks can take input for either VCLK or VCLK2, but
* VCLK is the preferred path for HDMI clocking and VCLK2 is the
* preferred path for CVBS VDAC clocking.
/*
* As of now, there are only 2 combinations possible for source split:
*
* Left | Right
* -----|------
* LM0 | LM1
* LM2 | LM5
*
*/
/*
* DSI PLL 14nm - clock diagram (eg: DSI0):
*
* dsi0n1_postdiv_clk
* |
* |
* +----+ | +----+
* dsi0vco_clk ---| n1 |--o--| /8 |-- dsi0pllbyte
* +----+ | +----+
* | dsi0n1_postdivby2_clk
* | +----+ |
* o---| /2 |--o--|\
* | +----+ | \ +----+
* | | |--| n2 |-- dsi0pll
* o--------------| / +----+
* |/
*/
/*
* DSI PLL 28nm (8960/A family) - clock diagram (eg: DSI1):
*
*
* +------+
* dsi1vco_clk ----o-----| DIV1 |---dsi1pllbit (not exposed as clock)
* F * byte_clk | +------+
* | bit clock divider (F / 8)
* |
* | +------+
* o-----| DIV2 |---dsi0pllbyte---o---> To byte RCG
* | +------+ | (sets parent rate)
* | byte clock divider (F) |
* | |
* | o---> To esc RCG
* | (doesn't set parent rate)
* |
* | +------+
* o-----| DIV3 |----dsi0pll------o---> To dsi RCG
* +------+ | (sets parent rate)
* dsi clock divider (F * magic) |
* |
* o---> To pixel rcg
* (doesn't set parent rate)
*/
/*
* DSI PLL 7nm - clock diagram (eg: DSI0): TODO: updated CPHY diagram
*
* dsi0_pll_out_div_clk dsi0_pll_bit_clk
* | |
* | |
* +---------+ | +----------+ | +----+
* dsi0vco_clk ---| out_div |--o--| divl_3_0 |--o--| /8 |-- dsi0_phy_pll_out_byteclk
* +---------+ | +----------+ | +----+
* | |
* | | dsi0_pll_by_2_bit_clk
* | | |
* | | +----+ | |\ dsi0_pclk_mux
* | |--| /2 |--o--| \ |
* | | +----+ | \ | +---------+
* | --------------| |--o--| div_7_4 |-- dsi0_phy_pll_out_dsiclk
* |------------------------------| / +---------+
* | +-----+ | /
* -----------| /4? |--o----------|/
* +-----+ | |
* | |dsiclk_sel
* |
* dsi0_pll_post_out_div_clk
*/
/****************************************************************
* Log2(block height) ----------------------------+ *
* Page Kind ----------------------------------+ | *
* Gob Height/Page Kind Generation ------+ | | *
* Sector layout -------+ | | | *
* Compression ------+ | | | | */
/****************************************************************
* Log2(block height) ----------------------------+ *
* Page Kind ----------------------------------+ | *
* Gob Height/Page Kind Generation ------+ | | *
* Sector layout -------+ | | | *
* Compression ------+ | | | | */
* These adjust what grayscale voltage will be output for input data V1 = 0,
* V2 = 16, V3 = 48, V4 = 96, V5 = 160, V6 = 208, V7 = 240 and V8 = 255.
* The curve is shaped like this:
*
* ^
* | V8
* | V7
* | V6
* | V5
* | V4
* | V3
* | V2
* | V1
* +----------------------------------------------------------->
* 0 16 48 96 160 208 240 255
*
* The negative and postive gamma values adjust the V1 thru V8 up/down
* according to the datasheet specifications. This is a property of the
* physical display connected to the display controller and may vary.
* If defined, both arrays must be supplied in full. If the properties
* are not supplied, hardware defaults will be used.
* Gamma correction arrays are 10bit numbers, two consecutive bytes
* makes out one point on the gamma correction curve. The points are
* not linearly placed along the X axis, we get points 0, 1, 3, 5
* 7, 11, 15, 23, 31, 47, 63, 95, 127, 128, 160, 192, 208, 224, 232,
* 240, 244, 248, 250, 252, 254, 255. The voltages tuples form
* V0, V1, V3 ... V255, with 0x0000 being the lowest voltage and
* 0x03FF being the highest voltage.
*
* Each value must be strictly higher than the previous value forming
* a rising curve like this:
*
* ^
* | V255
* | V254
* | ....
* | V5
* | V3
* | V1
* | V0
* +------------------------------------------->
*
* The details about all settings can be found in the NT35510 Application
* Note.
/*
* (1) each frame starts at the start of the Vsync pulse which is signaled by
* the "FRAME_SYNC" interrupt.
* (2) the active data region of each frame ends at dsp_vact_end
* (3) we should program this same number (dsp_vact_end) into dsp_line_frag_num,
* to get "LINE_FLAG" interrupt at the end of the active on screen data.
*
* VOP_INTR_CTRL0.dsp_line_frag_num = VOP_DSP_VACT_ST_END.dsp_vact_end
* Interrupts
* LINE_FLAG -------------------------------+
* FRAME_SYNC ----+ |
* | |
* v v
* | Vsync | Vbp | Vactive | Vfp |
* ^ ^ ^ ^
* | | | |
* | | | |
* dsp_vs_end ------------+ | | | VOP_DSP_VTOTAL_VS_END
* dsp_vact_start --------------+ | | VOP_DSP_VACT_ST_END
* dsp_vact_end ----------------------------+ | VOP_DSP_VACT_ST_END
* dsp_total -------------------------------------+ VOP_DSP_VTOTAL_VS_END
*/
/*
* VOP2 architecture
*
+----------+ +-------------+ +-----------+
| Cluster | | Sel 1 from 6| | 1 from 3 |
| window0 | | Layer0 | | RGB |
+----------+ +-------------+ +---------------+ +-------------+ +-----------+
+----------+ +-------------+ |N from 6 layers| | |
| Cluster | | Sel 1 from 6| | Overlay0 +--->| Video Port0 | +-----------+
| window1 | | Layer1 | | | | | | 1 from 3 |
+----------+ +-------------+ +---------------+ +-------------+ | LVDS |
+----------+ +-------------+ +-----------+
| Esmart | | Sel 1 from 6|
| window0 | | Layer2 | +---------------+ +-------------+ +-----------+
+----------+ +-------------+ |N from 6 Layers| | | +--> | 1 from 3 |
+----------+ +-------------+ --------> | Overlay1 +--->| Video Port1 | | MIPI |
| Esmart | | Sel 1 from 6| --------> | | | | +-----------+
| Window1 | | Layer3 | +---------------+ +-------------+
+----------+ +-------------+ +-----------+
+----------+ +-------------+ | 1 from 3 |
| Smart | | Sel 1 from 6| +---------------+ +-------------+ | HDMI |
| Window0 | | Layer4 | |N from 6 Layers| | | +-----------+
+----------+ +-------------+ | Overlay2 +--->| Video Port2 |
+----------+ +-------------+ | | | | +-----------+
| Smart | | Sel 1 from 6| +---------------+ +-------------+ | 1 from 3 |
| Window1 | | Layer5 | | eDP |
+----------+ +-------------+ +-----------+
*
*/
/*
* Overview
* --------
*
* The display controller part of ZynqMP DP subsystem, made of the Audio/Video
* Buffer Manager, the Video Rendering Pipeline (blender) and the Audio Mixer.
*
* +------------------------------------------------------------+
* +--------+ | +----------------+ +-----------+ |
* | DPDMA | --->| | --> | Video | Video +-------------+ |
* | 4x vid | | | | | Rendering | -+--> | | | +------+
* | 2x aud | | | Audio/Video | --> | Pipeline | | | DisplayPort |---> | PHY0 |
* +--------+ | | Buffer Manager | +-----------+ | | Source | | +------+
* | | and STC | +-----------+ | | Controller | | +------+
* Live Video --->| | --> | Audio | Audio | |---> | PHY1 |
* | | | | Mixer | --+-> | | | +------+
* Live Audio --->| | --> | | || +-------------+ |
* | +----------------+ +-----------+ || |
* +---------------------------------------||-------------------+
* vv
* Blended Video and
* Mixed Audio to PL
*
* Only non-live input from the DPDMA and output to the DisplayPort Source
* Controller are currently supported. Interface with the programmable logic
* for live streams is not implemented.
*
* The display controller code creates planes for the DPDMA video and graphics
* layers, and a CRTC for the Video Rendering Pipeline.
*/
* Note that the input frame must be split up into the same number
* of tiles as the output frame:
*
* +---------+-----+
* +-----+---+ | A | B |
* | A | B | | | |
* +-----+---+ --> +---------+-----+
* | C | D | | C | D |
* +-----+---+ | | |
* +---------+-----+
*
* Clockwise 90° rotations are handled by first rescaling into a
* reusable temporary tile buffer and then rotating with the 8x8
* block rotator, writing to the correct destination:
*
* +-----+-----+
* | | |
* +-----+---+ +---------+ | C | A |
* | A | B | | A,B, | | | | |
* +-----+---+ --> | C,D | | --> | | |
* | C | D | +---------+ +-----+-----+
* +-----+---+ | D | B |
* | | |
* +-----+-----+
*
* If the 8x8 block rotator is used, horizontal or vertical flipping
* is done during the rotation step, otherwise flipping is done
* during the scaling step.
* With rotation or flipping, tile order changes between input and
* output image. Tiles are numbered row major from top left to bottom
* right for both input and output image.
/* Framebuffer
*
* The PicoLCD use a Topway LCD module of 256x64 pixel
* This display area is tiled over 4 controllers with 8 tiles
* each. Each tile has 8x64 pixel, each data byte representing
* a 1-bit wide vertical line of the tile.
*
* The display can be updated at a tile granularity.
*
* Chip 1 Chip 2 Chip 3 Chip 4
* +----------------+----------------+----------------+----------------+
* | Tile 1 | Tile 1 | Tile 1 | Tile 1 |
* +----------------+----------------+----------------+----------------+
* | Tile 2 | Tile 2 | Tile 2 | Tile 2 |
* +----------------+----------------+----------------+----------------+
* ...
* +----------------+----------------+----------------+----------------+
* | Tile 8 | Tile 8 | Tile 8 | Tile 8 |
* +----------------+----------------+----------------+----------------+
*/
/*
* TRBE Buffer Management
*
* The TRBE buffer spans from the base pointer till the limit pointer. When enabled,
* it starts writing trace data from the write pointer onward till the limit pointer.
* When the write pointer reaches the address just before the limit pointer, it gets
* wrapped around again to the base pointer. This is called a TRBE wrap event, which
* generates a maintenance interrupt when operated in WRAP or FILL mode. This driver
* uses FILL mode, where the TRBE stops the trace collection at wrap event. The IRQ
* handler updates the AUX buffer and re-enables the TRBE with updated WRITE and
* LIMIT pointers.
*
* Wrap around with an IRQ
* ------ < ------ < ------- < ----- < -----
* | |
* ------ > ------ > ------- > ----- > -----
*
* +---------------+-----------------------+
* | | |
* +---------------+-----------------------+
* Base Pointer Write Pointer Limit Pointer
*
* The base and limit pointers always needs to be PAGE_SIZE aligned. But the write
* pointer can be aligned to the implementation defined TRBE trace buffer alignment
* as captured in trbe_cpudata->trbe_align.
*
*
* head tail wakeup
* +---------------------------------------+----- ~ ~ ------
* |$$$$$$$|################|$$$$$$$$$$$$$$| |
* +---------------------------------------+----- ~ ~ ------
* Base Pointer Write Pointer Limit Pointer
*
* The perf_output_handle indices (head, tail, wakeup) are monotonically increasing
* values which tracks all the driver writes and user reads from the perf auxiliary
* buffer. Generally [head..tail] is the area where the driver can write into unless
* the wakeup is behind the tail. Enabled TRBE buffer span needs to be adjusted and
* configured depending on the perf_output_handle indices, so that the driver does
* not override into areas in the perf auxiliary buffer which is being or yet to be
* consumed from the user space. The enabled TRBE buffer area is a moving subset of
* the allocated perf auxiliary buffer.
*/
/* MUX logic description.
* Driver can support different mux control logic, according to CPLD
* implementation.
*
* Connectivity schema.
*
* i2c-mlxcpld Digital Analog
* driver
* *--------* * -> mux1 (virt bus2) -> mux -> |
* | I2CLPC | i2c physical * -> mux2 (virt bus3) -> mux -> |
* | bridge | bus 1 *---------* |
* | logic |---------------------> * mux reg * |
* | in CPLD| *---------* |
* *--------* i2c-mux-mlxpcld ^ * -> muxn (virt busn) -> mux -> |
* | driver | |
* | *---------------* | Devices
* | * CPLD (i2c bus)* select |
* | * registers for *--------*
* | * mux selection * deselect
* | *---------------*
* | |
* <--------> <----------->
* i2c cntrl Board cntrl reg
* reg space space (mux select,
* IO, LED, WD, info)
*
*/
/*
* The diagram below details the relationship of the mapping structures
*
* Since the mapping now allows for non-uniform send contexts per vl, the
* number of send contexts for a vl is either the vl_scontexts[vl] or
* a computation based on num_kernel_send_contexts/num_vls:
*
* For example:
* nactual = vl_scontexts ? vl_scontexts[vl] : num_kernel_send_contexts/num_vls
*
* n = roundup to next highest power of 2 using nactual
*
* In the case where there are num_kernel_send_contexts/num_vls doesn't divide
* evenly, the extras are added from the last vl downward.
*
* For the case where n > nactual, the send contexts are assigned
* in a round robin fashion wrapping back to the first send context
* for a particular vl.
*
* dd->pio_map
* | pio_map_elem[0]
* | +--------------------+
* v | mask |
* pio_vl_map |--------------------|
* +--------------------------+ | ksc[0] -> sc 1 |
* | list (RCU) | |--------------------|
* |--------------------------| ->| ksc[1] -> sc 2 |
* | mask | --/ |--------------------|
* |--------------------------| -/ | * |
* | actual_vls (max 8) | -/ |--------------------|
* |--------------------------| --/ | ksc[n-1] -> sc n |
* | vls (max 8) | -/ +--------------------+
* |--------------------------| --/
* | map[0] |-/
* |--------------------------| +--------------------+
* | map[1] |--- | mask |
* |--------------------------| \---- |--------------------|
* | * | \-- | ksc[0] -> sc 1+n |
* | * | \---- |--------------------|
* | * | \->| ksc[1] -> sc 2+n |
* |--------------------------| |--------------------|
* | map[vls - 1] |- | * |
* +--------------------------+ \- |--------------------|
* \- | ksc[m-1] -> sc m+n |
* \ +--------------------+
* \-
* \
* \- +----------------------+
* \- | mask |
* \ |----------------------|
* \- | ksc[0] -> sc 1+m+n |
* \- |----------------------|
* >| ksc[1] -> sc 2+m+n |
* |----------------------|
* | * |
* |----------------------|
* | ksc[o-1] -> sc o+m+n |
* +----------------------+
*
*/
/*
*
* The diagram below details the relationship of the mapping structures
*
* Since the mapping now allows for non-uniform engines per vl, the
* number of engines for a vl is either the vl_engines[vl] or
* a computation based on num_sdma/num_vls:
*
* For example:
* nactual = vl_engines ? vl_engines[vl] : num_sdma/num_vls
*
* n = roundup to next highest power of 2 using nactual
*
* In the case where there are num_sdma/num_vls doesn't divide
* evenly, the extras are added from the last vl downward.
*
* For the case where n > nactual, the engines are assigned
* in a round robin fashion wrapping back to the first engine
* for a particular vl.
*
* dd->sdma_map
* | sdma_map_elem[0]
* | +--------------------+
* v | mask |
* sdma_vl_map |--------------------|
* +--------------------------+ | sde[0] -> eng 1 |
* | list (RCU) | |--------------------|
* |--------------------------| ->| sde[1] -> eng 2 |
* | mask | --/ |--------------------|
* |--------------------------| -/ | * |
* | actual_vls (max 8) | -/ |--------------------|
* |--------------------------| --/ | sde[n-1] -> eng n |
* | vls (max 8) | -/ +--------------------+
* |--------------------------| --/
* | map[0] |-/
* |--------------------------| +---------------------+
* | map[1] |--- | mask |
* |--------------------------| \---- |---------------------|
* | * | \-- | sde[0] -> eng 1+n |
* | * | \---- |---------------------|
* | * | \->| sde[1] -> eng 2+n |
* |--------------------------| |---------------------|
* | map[vls - 1] |- | * |
* +--------------------------+ \- |---------------------|
* \- | sde[m-1] -> eng m+n |
* \ +---------------------+
* \-
* \
* \- +----------------------+
* \- | mask |
* \ |----------------------|
* \- | sde[0] -> eng 1+m+n |
* \- |----------------------|
* >| sde[1] -> eng 2+m+n |
* |----------------------|
* | * |
* |----------------------|
* | sde[o-1] -> eng o+m+n|
* +----------------------+
*
*/
/*
* DEC LK201 and LK401 keyboard driver for Linux (primary for DECstations
* and VAXstations, but can also be used on any standard RS232 with an
* adaptor).
*
* DISCLAIMER: This works for _me_. If you break anything by using the
* information given below, I will _not_ be liable!
*
* RJ10 pinout: To DE9: Or DB25:
* 1 - RxD <----> Pin 3 (TxD) <-> Pin 2 (TxD)
* 2 - GND <----> Pin 5 (GND) <-> Pin 7 (GND)
* 4 - TxD <----> Pin 2 (RxD) <-> Pin 3 (RxD)
* 3 - +12V (from HDD drive connector), DON'T connect to DE9 or DB25!!!
*
* Pin numbers for DE9 and DB25 are noted on the plug (quite small:). For
* RJ10, it's like this:
*
* __=__ Hold the plug in front of you, cable downwards,
* /___/| nose is hidden behind the plug. Now, pin 1 is at
* |1234|| the left side, pin 4 at the right and 2 and 3 are
* |IIII|| in between, of course:)
* | ||
* |____|/
* || So the adaptor consists of three connected cables
* || for data transmission (RxD and TxD) and signal ground.
* Additionally, you have to get +12V from somewhere.
* Most easily, you'll get that from a floppy or HDD power connector.
* It's the yellow cable there (black is ground and red is +5V).
*
* The keyboard and all the commands it understands are documented in
* "VCB02 Video Subsystem - Technical Manual", EK-104AA-TM-001. This
* document is LK201 specific, but LK401 is mostly compatible. It comes
* up in LK201 mode and doesn't report any of the additional keys it
* has. These need to be switched on with the LK_CMD_ENABLE_LK401
* command. You'll find this document (scanned .pdf file) on MANX,
* a search engine specific to DEC documentation. Try
* http://www.vt100.net/manx/details?pn=EK-104AA-TM-001;id=21;cp=1
*/
/* Map device buttons to internal key events.
*
* The "up" and "down" keys, are symbolised by arrows on the button.
* The "pickup" and "hangup" keys are symbolised by a green and red phone
* on the button.
Komunikate KIP1000 Keyboard Matrix
-> -- 1 -- 2 -- 3 --> GPI pin 4 (0x10)
| | | |
<- -- 4 -- 5 -- 6 --> GPI pin 5 (0x20)
| | | |
END - 7 -- 8 -- 9 --> GPI pin 6 (0x40)
| | | |
OK -- * -- 0 -- # --> GPI pin 7 (0x80)
| | | |
/|\ /|\ /|\ /|\
| | | |
GPO
pin: 3 2 1 0
0x8 0x4 0x2 0x1
*/
/* Map device buttons to internal key events.
*
* USB-P1K button layout:
*
* up
* IN OUT
* down
*
* pickup C hangup
* 1 2 3
* 4 5 6
* 7 8 9
* * 0 #
*
* The "up" and "down" keys, are symbolised by arrows on the button.
* The "pickup" and "hangup" keys are symbolised by a green and red phone
* on the button.
*/
/* LCD, each segment must be driven separately.
*
* Layout:
*
* |[] [][] [][] [][] in |[][]
* |[] M [][] D [][] : [][] out |[][]
* store
*
* NEW REP SU MO TU WE TH FR SA
*
* [] [] [] [] [] [] [] [] [] [] [] []
* [] [] [] [] [] [] [] [] [] [] [] []
*/
/*
* Building an adaptor to DE9 / DB25 RS232
* ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
*
* DISCLAIMER: Use this description AT YOUR OWN RISK! I'll not pay for
* anything if you break your mouse, your computer or whatever!
*
* In theory, this mouse is a simple RS232 device. In practice, it has got
* a quite uncommon plug and the requirement to additionally get a power
* supply at +5V and -12V.
*
* If you look at the socket/jack (_not_ at the plug), we use this pin
* numbering:
* _______
* / 7 6 5 \
* | 4 --- 3 |
* \ 2 1 /
* -------
*
* DEC socket DE9 DB25 Note
* 1 (GND) 5 7 -
* 2 (RxD) 2 3 -
* 3 (TxD) 3 2 -
* 4 (-12V) - - Somewhere from the PSU. At ATX, it's
* the thin blue wire at pin 12 of the
* ATX power connector. Only required for
* VSXXX-AA/-GA mice.
* 5 (+5V) - - PSU (red wires of ATX power connector
* on pin 4, 6, 19 or 20) or HDD power
* connector (also red wire).
* 6 (+12V) - - HDD power connector, yellow wire. Only
* required for VSXXX-AB digitizer.
* 7 (dev. avail.) - - The mouse shorts this one to pin 1.
* This way, the host computer can detect
* the mouse. To use it with the adaptor,
* simply don't connect this pin.
*
* So to get a working adaptor, you need to connect the mouse with three
* wires to a RS232 port and two or three additional wires for +5V, +12V and
* -12V to the PSU.
*
* Flow specification for the link is 4800, 8o1.
*
* The mice and tablet are described in "VCB02 Video Subsystem - Technical
* Manual", DEC EK-104AA-TM-001. You'll find it at MANX, a search engine
* specific for DEC documentation. Try
* http://www.vt100.net/manx/details?pn=EK-104AA-TM-001;id=21;cp=1
*/
/*
* The PS2 protocol specifies a clock frequency between 10kHz and 16.7kHz,
* therefore the maximal interrupt interval should be 100us and the minimum
* interrupt interval should be ~60us. Let's allow +/- 20us for frequency
* deviations and interrupt latency.
*
* The data line must be samples after ~30us to 50us after the falling edge,
* since the device updates the data line at the rising edge.
*
* ___ ______ ______ ______ ___
* \ / \ / \ / \ /
* \ / \ / \ / \ /
* \______/ \______/ \______/ \______/
*
* |-----------------| |--------|
* 60us/100us 30us/50us
*/
/*
* When we are running in the non-secure world and the secure world
* has not explicitly given us access to the TCM we will get an
* undefined error when reading the TCM region register in the
* setup_tcm_bank function (above).
*
* There are two variants of this register read that we need to trap,
* the read for the data TCM and the read for the instruction TCM:
* c0370628: ee196f11 mrc 15, 0, r6, cr9, cr1, {0}
* c0370674: ee196f31 mrc 15, 0, r6, cr9, cr1, {1}
*
* Our undef hook mask explicitly matches all fields of the encoded
* instruction other than the destination register. The mask also
* only allows operand 2 to have the values 0 or 1.
*
* The undefined hook is defined as __init and __initdata, and therefore
* must be removed before tcm_init returns.
*
* In this particular case (MRC with ARM condition code ALways) the
* Thumb-2 and ARM instruction encoding are identical, so this hook
* will work on a Thumb-2 kernel.
*
* See A8.8.107, DDI0406C_C ARM Architecture Reference Manual, Encoding
* T1/A1 for the bit-by-bit details.
*
* mrc p15, 0, XX, c9, c1, 0
* mrc p15, 0, XX, c9, c1, 1
* | | | | | | | +---- opc2 0|1 = 000|001
* | | | | | | +------- CRm 0 = 0001
* | | | | | +----------- CRn 0 = 1001
* | | | | +--------------- Rt ? = ????
* | | | +------------------- opc1 0 = 000
* | | +----------------------- coproc 15 = 1111
* | +-------------------------- condition ALways = 1110
* +----------------------------- instruction MRC = 1110
*
* Encoding this as per A8.8.107 of DDI0406C, Encoding T1/A1, yields:
* 1111 1111 1111 1111 0000 1111 1101 1111 Required Mask
* 1110 1110 0001 1001 ???? 1111 0001 0001 mrc p15, 0, XX, c9, c1, 0
* 1110 1110 0001 1001 ???? 1111 0011 0001 mrc p15, 0, XX, c9, c1, 1
* [ ] [ ] [ ]| [ ] [ ] [ ] [ ]| +--- CRm
* | | | | | | | | +----- SBO
* | | | | | | | +------- opc2
* | | | | | | +----------- coproc
* | | | | | +---------------- Rt
* | | | | +--------------------- CRn
* | | | +------------------------- SBO
* | | +--------------------------- opc1
* | +------------------------------- instruction
* +------------------------------------ condition
*/
/*
* YP(open)--+-------------+
* | |--+
* | | |
* YM(-)--+-------------+ |
* +--------------+
* | |
* XP(weak+) XM(open)
*
* "weak+" means 200k Ohm VDDIO
* (-) means GND
*/
* To find the function start of dump_stack we can look at the stored LR of
* show_stack. It points at the instruction directly after the bl dump_stack.
* We can then read the offset from the bl opcode to determine where the branch
* takes us. The address calculated must be the start of dump_stack.
*
* c_backtrace frame dump_stack:
* {[LR] } ============| ...
* {[FP] } =======| | bl c_backtrace
* | |=> ...
* {[R4-R10]} |
* {[R0-R3] } | show_stack:
* dump_stack frame | ...
* {[LR] } =============| bl dump_stack
* {[FP] } <=======| |=> ...
* {[R4-R10]}
* {[R0-R3] }
/*
* Data is received through COM1 at 9600bit/s,8bit,no parity in packets
* of 5 byte each.
*
* +--------+ +--------+ +--------+ +--------+ +--------+
* |1000000p| |0xxxxxxx| |0xxxxxxx| |0yyyyyyy| |0yyyyyyy|
* +--------+ +--------+ +--------+ +--------+ +--------+
* MSB LSB MSB LSB
*
* The value of p is 1 as long as the screen is touched and 0 when
* reporting the location where touching stopped, e.g. where the pen was
* lifted from the screen.
*
* When holding the screen in landscape mode as the BIOS text output is
* presented, x is the horizontal axis with values growing from left to
* right and y is the vertical axis with values growing from top to
* bottom.
*
* When holding the screen in portrait mode with the Sahara logo in its
* correct position, x ist the vertical axis with values growing from
* top to bottom and y is the horizontal axis with values growing from
* right to left.
*/
* Overall diagram of the Armada XP interrupt controller:
*
* To CPU 0 To CPU 1
*
* /\ /\
* || ||
* +---------------+ +---------------+
* | | | |
* | per-CPU | | per-CPU |
* | mask/unmask | | mask/unmask |
* | CPU0 | | CPU1 |
* | | | |
* +---------------+ +---------------+
* /\ /\
* || ||
* \\_______________________//
* ||
* +-------------------+
* | |
* | Global interrupt |
* | mask/unmask |
* | |
* +-------------------+
* /\
* ||
* interrupt from
* device
*
* The "global interrupt mask/unmask" is modified using the
* ARMADA_370_XP_INT_SET_ENABLE_OFFS and
* ARMADA_370_XP_INT_CLEAR_ENABLE_OFFS registers, which are relative
* to "main_int_base".
/* STRUCTURE:
*
* The dsp module provides layer 2 for b-channels (64kbit). It provides
* transparent audio forwarding with special digital signal processing:
*
* - (1) generation of tones
* - (2) detection of dtmf tones
* - (3) crossconnecting and conferences (clocking)
* - (4) echo generation for delay test
* - (5) volume control
* - (6) disable receive data
* - (7) pipeline
* - (8) encryption/decryption
*
* Look:
* TX RX
* ------upper layer------
* | ^
* | |(6)
* v |
* +-----+-------------+-----+
* |(3)(4) |
* | CMX |
* | |
* | +-------------+
* | | ^
* | | |
* |+---------+| +----+----+
* ||(1) || |(2) |
* || || | |
* || Tones || | DTMF |
* || || | |
* || || | |
* |+----+----+| +----+----+
* +-----+-----+ ^
* | |
* v |
* +----+----+ +----+----+
* |(5) | |(5) |
* | | | |
* |TX Volume| |RX Volume|
* | | | |
* | | | |
* +----+----+ +----+----+
* | ^
* | |
* v |
* +----+-------------+----+
* |(7) |
* | |
* | Pipeline Processing |
* | |
* | |
* +----+-------------+----+
* | ^
* | |
* v |
* +----+----+ +----+----+
* |(8) | |(8) |
* | | | |
* | Encrypt | | Decrypt |
* | | | |
* | | | |
* +----+----+ +----+----+
* | ^
* | |
* v |
* ------card layer------
* TX RX
*
* Above you can see the logical data flow. If software is used to do the
* process, it is actually the real data flow. If hardware is used, data
* may not flow, but hardware commands to the card, to provide the data flow
* as shown.
/*
* CR0014114 SPI protocol descrtiption:
* +----+-----------------------------------+----+
* | CMD| BRIGHTNESS |CRC |
* +----+-----------------------------------+----+
* | | LED0| LED1| LED2| LED3| LED4| LED5| |
* | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
* | |R|G|B|R|G|B|R|G|B|R|G|B|R|G|B|R|G|B| |
* | 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1 |
* | |1|1|1|1|1|1|1|1|1|1|1|1|1|1|1|1|1|1| |
* | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
* | | 18 | |
* +----+-----------------------------------+----+
* | 20 |
* +---------------------------------------------+
*
* PS: Boards can be connected to the chain:
* SPI -> board0 -> board1 -> board2 ..
*/
/*
* A target may call dm_accept_partial_bio only from the map routine. It is
* allowed for all bio types except REQ_PREFLUSH, REQ_OP_ZONE_* zone management
* operations, REQ_OP_ZONE_APPEND (zone append writes) and any bio serviced by
* __send_duplicate_bios().
*
* dm_accept_partial_bio informs the dm that the target only wants to process
* additional n_sectors sectors of the bio and the rest of the data should be
* sent in a next bio.
*
* A diagram that explains the arithmetics:
* +--------------------+---------------+-------+
* | 1 | 2 | 3 |
* +--------------------+---------------+-------+
*
* <-------------- *tio->len_ptr --------------->
* <----- bio_sectors ----->
* <-- n_sectors -->
*
* Region 1 was already iterated over with bio_advance or similar function.
* (it may be empty if the target doesn't use bio_advance)
* Region 2 is the remaining bio size that the target wants to process.
* (it may be empty if region 1 is non-empty, although there is no reason
* to make it empty)
* The target requires that region 3 is to be sent in the next bio.
*
* If the target wants to receive multiple copies of the bio (via num_*bios, etc),
* the partially processed part (the sum of regions 1+2) must be the same for all
* copies of the bio.
*/
/*
* RAID10 provides a combination of RAID0 and RAID1 functionality.
* The layout of data is defined by
* chunk_size
* raid_disks
* near_copies (stored in low byte of layout)
* far_copies (stored in second byte of layout)
* far_offset (stored in bit 16 of layout )
* use_far_sets (stored in bit 17 of layout )
* use_far_sets_bugfixed (stored in bit 18 of layout )
*
* The data to be stored is divided into chunks using chunksize. Each device
* is divided into far_copies sections. In each section, chunks are laid out
* in a style similar to raid0, but near_copies copies of each chunk is stored
* (each on a different drive). The starting device for each section is offset
* near_copies from the starting device of the previous section. Thus there
* are (near_copies * far_copies) of each chunk, and each is on a different
* drive. near_copies and far_copies must be at least one, and their product
* is at most raid_disks.
*
* If far_offset is true, then the far_copies are handled a bit differently.
* The copies are still in different stripes, but instead of being very far
* apart on disk, there are adjacent stripes.
*
* The far and offset algorithms are handled slightly differently if
* 'use_far_sets' is true. In this case, the array's devices are grouped into
* sets that are (near_copies * far_copies) in size. The far copied stripes
* are still shifted by 'near_copies' devices, but this shifting stays confined
* to the set rather than the entire array. This is done to improve the number
* of device combinations that can fail without causing the array to fail.
* Example 'far' algorithm w/o 'use_far_sets' (each letter represents a chunk
* on a device):
* A B C D A B C D E
* ... ...
* D A B C E A B C D
* Example 'far' algorithm w/ 'use_far_sets' enabled (sets illustrated w/ []'s):
* [A B] [C D] [A B] [C D E]
* |...| |...| |...| | ... |
* [B A] [D C] [B A] [E C D]
*/
/*
* Before recovery, the log looks like the following
*
* ---------------------------------------------
* | valid log | invalid log |
* ---------------------------------------------
* ^
* |- log->last_checkpoint
* |- log->last_cp_seq
* Now we scan through the log until we see invalid entry
*
* ---------------------------------------------
* | valid log | invalid log |
* ---------------------------------------------
* ^ ^
* |- log->last_checkpoint |- ctx->pos
* |- log->last_cp_seq |- ctx->seq
*
* From this point, we need to increase seq number by 10 to avoid
* confusing next recovery.
*
* ---------------------------------------------
* | valid log | invalid log |
* ---------------------------------------------
* ^ ^
* |- log->last_checkpoint |- ctx->pos+1
* |- log->last_cp_seq |- ctx->seq+10001
*
* However, it is not safe to start the state machine yet, because data only
* parities are not yet secured in RAID. To save these data only parities, we
* rewrite them from seq+11.
*
* -----------------------------------------------------------------
* | valid log | data only stripes | invalid log |
* -----------------------------------------------------------------
* ^ ^
* |- log->last_checkpoint |- ctx->pos+n
* |- log->last_cp_seq |- ctx->seq+10000+n
*
* If failure happens again during this process, the recovery can safe start
* again from log->last_checkpoint.
*
* Once data only stripes are rewritten to journal, we move log_tail
*
* -----------------------------------------------------------------
* | old log | data only stripes | invalid log |
* -----------------------------------------------------------------
* ^ ^
* |- log->last_checkpoint |- ctx->pos+n
* |- log->last_cp_seq |- ctx->seq+10000+n
*
* Then we can safely start the state machine. If failure happens from this
* point on, the recovery will start from new log->last_checkpoint.
*/
* PPL consists of a 4KB header (struct ppl_header) and at least 128KB for
* partial parity data. The header contains an array of entries
* (struct ppl_header_entry) which describe the logged write requests.
* Partial parity for the entries comes after the header, written in the same
* sequence as the entries:
*
* Header
* entry0
* ...
* entryN
* PP data
* PP for entry0
* ...
* PP for entryN
*
* An entry describes one or more consecutive stripe_heads, up to a full
* stripe. The modifed raid data chunks form an m-by-n matrix, where m is the
* number of stripe_heads in the entry and n is the number of modified data
* disks. Every stripe_head in the entry must write to the same data disks.
* An example of a valid case described by a single entry (writes to the first
* stripe of a 4 disk array, 16k chunk size):
*
* sh->sector dd0 dd1 dd2 ppl
* +-----+-----+-----+
* 0 | --- | --- | --- | +----+
* 8 | -W- | -W- | --- | | pp | data_sector = 8
* 16 | -W- | -W- | --- | | pp | data_size = 3 * 2 * 4k
* 24 | -W- | -W- | --- | | pp | pp_size = 3 * 4k
* +-----+-----+-----+ +----+
*
* data_sector is the first raid sector of the modified data, data_size is the
* total size of modified data and pp_size is the size of partial parity for
* this entry. Entries for full stripe writes contain no partial parity
* (pp_size = 0), they only mark the stripes for which parity should be
* recalculated after an unclean shutdown. Every entry holds a checksum of its
* partial parity, the header also has a checksum of the header itself.
/*
* This function is only called when CACHE_SET_IO_DISABLE is set, which means
* cache set is unregistering due to too many I/O errors. In this condition,
* the bcache device might be stopped, it depends on stop_when_cache_set_failed
* value and whether the broken cache has dirty data:
*
* dc->stop_when_cache_set_failed dc->has_dirty stop bcache device
* BCH_CACHED_STOP_AUTO 0 NO
* BCH_CACHED_STOP_AUTO 1 YES
* BCH_CACHED_DEV_STOP_ALWAYS 0 YES
* BCH_CACHED_DEV_STOP_ALWAYS 1 YES
*
* The expected behavior is, if stop_when_cache_set_failed is configured to
* "auto" via sysfs interface, the bcache device will not be stopped if the
* backing device is clean on the broken cache device.
*/
/*
* The AO-CECB embeds a dual/divider to generate a more precise
* 32,768KHz clock for CEC core clock.
* ______ ______
* | | | |
* ______ | Div1 |-| Cnt1 | ______
* | | /|______| |______|\ | |
* Xtal-->| Gate |---| ______ ______ X-X--| Gate |-->
* |______| | \| | | |/ | |______|
* | | Div2 |-| Cnt2 | |
* | |______| |______| |
* |_______________________|
*
* The dividing can be switched to single or dual, with a counter
* for each divider to set when the switching is done.
* The entire dividing mechanism can be also bypassed.
*/
/*
* The IMX290 pixel array is organized as follows:
*
* +------------------------------------+
* | Optical Black | } Vertical effective optical black (10)
* +---+------------------------------------+---+
* | | | | } Effective top margin (8)
* | | +----------------------------+ | | \
* | | | | | | |
* | | | | | | |
* | | | | | | |
* | | | Recording Pixel Area | | | | Recommended height (1080)
* | | | | | | |
* | | | | | | |
* | | | | | | |
* | | +----------------------------+ | | /
* | | | | } Effective bottom margin (9)
* +---+------------------------------------+---+
* <-> <-> <--------------------------> <-> <->
* \---- Ignored right margin (4)
* \-------- Effective right margin (9)
* \------------------------- Recommended width (1920)
* \----------------------------------------- Effective left margin (8)
* \--------------------------------------------- Ignored left margin (4)
*
* The optical black lines are output over CSI-2 with a separate data type.
*
* The pixel array is meant to have 1920x1080 usable pixels after image
* processing in an ISP. It has 8 (9) extra active pixels usable for color
* processing in the ISP on the top and left (bottom and right) sides of the
* image. In addition, 4 additional pixels are present on the left and right
* sides of the image, documented as "ignored area".
*
* As far as is understood, all pixels of the pixel array (ignored area, color
* processing margins and recording area) can be output by the sensor.
*/
/*
* PLL1 Clock Tree:
*
* +-< EXTCLK
* |
* +-+ pll_pre_div_half (0x30a [0])
* |
* +-+ pll_pre_div (0x300 [2:0], special values:
* | 0: 1, 1: 1.5, 3: 2.5, 4: 3, 5: 4, 7: 8)
* +-+ pll_mul (0x301 [1:0], 0x302 [7:0])
* |
* +-+ m_div (0x303 [3:0])
* | |
* | +-> PHY_SCLK
* | |
* | +-+ mipi_div (0x304 [1:0], special values: 0: 4, 1: 5, 2: 6, 3: 8)
* | |
* | +-+ pclk_div (0x3020 [3])
* | |
* | +-> PCLK
* |
* +-+ sys_pre_div (0x305 [1:0], special values: 0: 3, 1: 4, 2: 5, 3: 6)
* |
* +-+ sys_div (0x306 [0])
* |
* +-+ sys_sel (0x3032 [7], 0: PLL1, 1: PLL2)
* |
* +-+ sclk_sel (0x3033 [1], 0: sys_sel, 1: PLL2 DAC_CLK)
* |
* +-+ sclk_pre_div (0x3106 [3:2], special values:
* | 0: 1, 1: 2, 2: 4, 3: 1)
* |
* +-+ sclk_div (0x3106 [7:4], special values: 0: 1)
* |
* +-> SCLK
*/
/*
* Update v4l2_bt_timings per current status.
* frame_top/frame_bottom/frame_left/frame_right need to be ready.
*
* The following registers start counting from sync's rising edge:
* 1. VR090: frame edge's left and right
* 2. VR094: frame edge's top and bottom
* 3. VR09C: counting from sync's rising edge to falling edge
*
* [Vertical timing]
* +--+ +-------------------+ +--+
* | | | v i d e o | | |
* +--+ +-----+ +-----+ +---+
* vsync+--+
* frame_top+--------+
* frame_bottom+----------------------------+
*
* +-------------------+
* | v i d e o |
* +--+ +-----+ +-----+ +---+
* | | | |
* +--+ +--+
* vsync+-------------------------------+
* frame_top+-----+
* frame_bottom+-------------------------+
*
* [Horizontal timing]
* +--+ +-------------------+ +--+
* | | | v i d e o | | |
* +--+ +-----+ +-----+ +---+
* hsync+--+
* frame_left+--------+
* frame_right+----------------------------+
*
* +-------------------+
* | v i d e o |
* +--+ +-----+ +-----+ +---+
* | | | |
* +--+ +--+
* hsync+-------------------------------+
* frame_left+-----+
* frame_right+-------------------------+
*
* @v: the struct of aspeed_video
* @det: v4l2_bt_timings to be updated.
*/
/*
* convert us back into redrat3 lengths
*
* length * 1000 length * 1000000
* ------------- = ---------------- = micro
* rr3clk / 1000 rr3clk
* 6 * 2 4 * 3 micro * rr3clk micro * rr3clk / 1000
* ----- = 4 ----- = 6 -------------- = len ---------------------
* 3 2 1000000 1000
*/
/*
* RX graphical example to better understand the difference between ST IR block
* output and standard definition used by LIRC (and most of the world!)
*
* mark mark
* |-IRB_RX_ON-| |-IRB_RX_ON-|
* ___ ___ ___ ___ ___ ___ _
* | | | | | | | | | | | | |
* | | | | | | space 0 | | | | | | space 1 |
* _____| |__| |__| |____________________________| |__| |__| |_____________|
*
* |--------------- IRB_RX_SYS -------------|------ IRB_RX_SYS -------|
*
* |------------- encoding bit 0 -----------|---- encoding bit 1 -----|
*
* ST hardware returns mark (IRB_RX_ON) and total symbol time (IRB_RX_SYS), so
* convert to standard mark/space we have to calculate space=(IRB_RX_SYS-mark)
* The mark time represents the amount of time the carrier (usually 36-40kHz)
* is detected.The above examples shows Pulse Width Modulation encoding where
* bit 0 is represented by space>mark.
*/
/* ---- Remote Button Layout ----
POWER SOURCE SCAN MUTE
TV/FM 1 2 3
|> 4 5 6
<| 7 8 9
^^UP 0 + RECALL
vvDN RECORD STOP PLAY
MINIMIZE ZOOM
CH+
VOL- VOL+
CH-
SNAPSHOT MTS
<< FUNC >> RESET
*/
/**
* IsSpurInBand() - Checks to see if a spur will be present within the IF's
* bandwidth. (fIFOut +/- fIFBW, -fIFOut +/- fIFBW)
*
* ma mb mc md
* <--+-+-+-------------------+-------------------+-+-+-->
* | ^ 0 ^ |
* ^ b=-fIFOut+fIFBW/2 -b=+fIFOut-fIFBW/2 ^
* a=-fIFOut-fIFBW/2 -a=+fIFOut+fIFBW/2
*
* Note that some equations are doubled to prevent round-off
* problems when calculating fIFBW/2
*
* @pAS_Info: Avoid Spurs information block
* @fm: If spur, amount f_IF1 has to move negative
* @fp: If spur, amount f_IF1 has to move positive
*
* Returns 1 if an LO spur would be present, otherwise 0.
*/
/* GPO:
* 3 - ATSC/MH# | 1 = ATSC transport, 0 = MH transport | default 0
* 4 - ATSC_RST## | 1 = ATSC enable, 0 = ATSC Reset | default 0
* 5 - ATSC_EN | 1 = ATSC power enable, 0 = ATSC power off | default 0
* 6 - MH_RESET# | 1 = MH enable, 0 = MH Reset | default 0
* 7 - MH_EN | 1 = MH power enable, 0 = MH power off | default 0
*/
/*
* Scan the UVC descriptors to locate a chain starting at an Output Terminal
* and containing the following units:
*
* - one or more Output Terminals (USB Streaming or Display)
* - zero or one Processing Unit
* - zero, one or more single-input Selector Units
* - zero or one multiple-input Selector Units, provided all inputs are
* connected to input terminals
* - zero, one or mode single-input Extension Units
* - one or more Input Terminals (Camera, External or USB Streaming)
*
* The terminal and units must match on of the following structures:
*
* ITT_*(0) -> +---------+ +---------+ +---------+ -> TT_STREAMING(0)
* ... | SU{0,1} | -> | PU{0,1} | -> | XU{0,n} | ...
* ITT_*(n) -> +---------+ +---------+ +---------+ -> TT_STREAMING(n)
*
* +---------+ +---------+ -> OTT_*(0)
* TT_STREAMING -> | PU{0,1} | -> | XU{0,n} | ...
* +---------+ +---------+ -> OTT_*(n)
*
* The Processing Unit and Extension Units can be in any order. Additional
* Extension Units connected to the main chain as single-unit branches are
* also supported. Single-input Selector Units are ignored.
*/
/*
* Memory Controller (MC) has few Memory Clients that are issuing memory
* bandwidth allocation requests to the MC interconnect provider. The MC
* provider aggregates the requests and then sends the aggregated request
* up to the External Memory Controller (EMC) interconnect provider which
* re-configures hardware interface to External Memory (EMEM) in accordance
* to the required bandwidth. Each MC interconnect node represents an
* individual Memory Client.
*
* Memory interconnect topology:
*
* +----+
* +--------+ | |
* | TEXSRD +--->+ |
* +--------+ | |
* | | +-----+ +------+
* ... | MC +--->+ EMC +--->+ EMEM |
* | | +-----+ +------+
* +--------+ | |
* | DISP.. +--->+ |
* +--------+ | |
* +----+
*/
/*
* N: next DDCB, this is where the next DDCB will be put.
* A: active DDCB, this is where the code will look for the next completion.
* x: DDCB is enqueued, we are waiting for its completion.
* Situation (1): Empty queue
* +---+---+---+---+---+---+---+---+
* | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
* | | | | | | | | |
* +---+---+---+---+---+---+---+---+
* A/N
* enqueued_ddcbs = A - N = 2 - 2 = 0
*
* Situation (2): Wrapped, N > A
* +---+---+---+---+---+---+---+---+
* | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
* | | | x | x | | | | |
* +---+---+---+---+---+---+---+---+
* A N
* enqueued_ddcbs = N - A = 4 - 2 = 2
*
* Situation (3): Queue wrapped, A > N
* +---+---+---+---+---+---+---+---+
* | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
* | x | x | | | x | x | x | x |
* +---+---+---+---+---+---+---+---+
* N A
* enqueued_ddcbs = queue_max - (A - N) = 8 - (4 - 2) = 6
*
* Situation (4a): Queue full N > A
* +---+---+---+---+---+---+---+---+
* | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
* | x | x | x | x | x | x | x | |
* +---+---+---+---+---+---+---+---+
* A N
*
* enqueued_ddcbs = N - A = 7 - 0 = 7
*
* Situation (4a): Queue full A > N
* +---+---+---+---+---+---+---+---+
* | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
* | x | x | x | | x | x | x | x |
* +---+---+---+---+---+---+---+---+
* N A
* enqueued_ddcbs = queue_max - (A - N) = 8 - (4 - 3) = 7
*/
/*
* <1> Firstly, we should know what's the GPMI-clock means.
* The GPMI-clock is the internal clock in the gpmi nand controller.
* If you set 100MHz to gpmi nand controller, the GPMI-clock's period
* is 10ns. Mark the GPMI-clock's period as GPMI-clock-period.
*
* <2> Secondly, we should know what's the frequency on the nand chip pins.
* The frequency on the nand chip pins is derived from the GPMI-clock.
* We can get it from the following equation:
*
* F = G / (DS + DH)
*
* F : the frequency on the nand chip pins.
* G : the GPMI clock, such as 100MHz.
* DS : GPMI_HW_GPMI_TIMING0:DATA_SETUP
* DH : GPMI_HW_GPMI_TIMING0:DATA_HOLD
*
* <3> Thirdly, when the frequency on the nand chip pins is above 33MHz,
* the nand EDO(extended Data Out) timing could be applied.
* The GPMI implements a feedback read strobe to sample the read data.
* The feedback read strobe can be delayed to support the nand EDO timing
* where the read strobe may deasserts before the read data is valid, and
* read data is valid for some time after read strobe.
*
* The following figure illustrates some aspects of a NAND Flash read:
*
* |<---tREA---->|
* | |
* | | |
* |<--tRP-->| |
* | | |
* __ ___|__________________________________
* RDN \________/ |
* |
* /---------\
* Read Data --------------< >---------
* \---------/
* | |
* |<-D->|
* FeedbackRDN ________ ____________
* \___________/
*
* D stands for delay, set in the HW_GPMI_CTRL1:RDN_DELAY.
*
*
* <4> Now, we begin to describe how to compute the right RDN_DELAY.
*
* 4.1) From the aspect of the nand chip pins:
* Delay = (tREA + C - tRP) {1}
*
* tREA : the maximum read access time.
* C : a constant to adjust the delay. default is 4000ps.
* tRP : the read pulse width, which is exactly:
* tRP = (GPMI-clock-period) * DATA_SETUP
*
* 4.2) From the aspect of the GPMI nand controller:
* Delay = RDN_DELAY * 0.125 * RP {2}
*
* RP : the DLL reference period.
* if (GPMI-clock-period > DLL_THRETHOLD)
* RP = GPMI-clock-period / 2;
* else
* RP = GPMI-clock-period;
*
* Set the HW_GPMI_CTRL1:HALF_PERIOD if GPMI-clock-period
* is greater DLL_THRETHOLD. In other SOCs, the DLL_THRETHOLD
* is 16000ps, but in mx6q, we use 12000ps.
*
* 4.3) since {1} equals {2}, we get:
*
* (tREA + 4000 - tRP) * 8
* RDN_DELAY = ----------------------- {3}
* RP
*/
/* Calculate the first base_time in the future that satisfies this
* relationship:
*
* future_base_time = base_time + N x cycle_time >= now, or
*
* now - base_time
* N >= ---------------
* cycle_time
*
* Because N is an integer, the ceiling value of the above "a / b" ratio
* is in fact precisely the floor value of "(a + b - 1) / b", which is
* easier to calculate only having integer division tools.
*/
/* Lo and behold: the egress scheduler from hell.
*
* At the hardware level, the Time-Aware Shaper holds a global linear arrray of
* all schedule entries for all ports. These are the Gate Control List (GCL)
* entries, let's call them "timeslots" for short. This linear array of
* timeslots is held in BLK_IDX_SCHEDULE.
*
* Then there are a maximum of 8 "execution threads" inside the switch, which
* iterate cyclically through the "schedule". Each "cycle" has an entry point
* and an exit point, both being timeslot indices in the schedule table. The
* hardware calls each cycle a "subschedule".
*
* Subschedule (cycle) i starts when
* ptpclkval >= ptpschtm + BLK_IDX_SCHEDULE_ENTRY_POINTS[i].delta.
*
* The hardware scheduler iterates BLK_IDX_SCHEDULE with a k ranging from
* k = BLK_IDX_SCHEDULE_ENTRY_POINTS[i].address to
* k = BLK_IDX_SCHEDULE_PARAMS.subscheind[i]
*
* For each schedule entry (timeslot) k, the engine executes the gate control
* list entry for the duration of BLK_IDX_SCHEDULE[k].delta.
*
* +---------+
* | | BLK_IDX_SCHEDULE_ENTRY_POINTS_PARAMS
* +---------+
* |
* +-----------------+
* | .actsubsch
* BLK_IDX_SCHEDULE_ENTRY_POINTS v
* +-------+-------+
* |cycle 0|cycle 1|
* +-------+-------+
* | | | |
* +----------------+ | | +-------------------------------------+
* | .subschindx | | .subschindx |
* | | +---------------+ |
* | .address | .address | |
* | | | |
* | | | |
* | BLK_IDX_SCHEDULE v v |
* | +-------+-------+-------+-------+-------+------+ |
* | |entry 0|entry 1|entry 2|entry 3|entry 4|entry5| |
* | +-------+-------+-------+-------+-------+------+ |
* | ^ ^ ^ ^ |
* | | | | | |
* | +-------------------------+ | | | |
* | | +-------------------------------+ | | |
* | | | +-------------------+ | |
* | | | | | |
* | +---------------------------------------------------------------+ |
* | |subscheind[0]<=subscheind[1]<=subscheind[2]<=...<=subscheind[7]| |
* | +---------------------------------------------------------------+ |
* | ^ ^ BLK_IDX_SCHEDULE_PARAMS |
* | | | |
* +--------+ +-------------------------------------------+
*
* In the above picture there are two subschedules (cycles):
*
* - cycle 0: iterates the schedule table from 0 to 2 (and back)
* - cycle 1: iterates the schedule table from 3 to 5 (and back)
*
* All other possible execution threads must be marked as unused by making
* their "subschedule end index" (subscheind) equal to the last valid
* subschedule's end index (in this case 5).
*/
/* The switch flow classification core implements TTEthernet, which 'thinks' in
* terms of Virtual Links (VL), a concept borrowed from ARINC 664 part 7.
* However it also has one other operating mode (VLLUPFORMAT=0) where it acts
* somewhat closer to a pre-standard implementation of IEEE 802.1Qci
* (Per-Stream Filtering and Policing), which is what the driver is going to be
* implementing.
*
* VL Lookup
* Key = {DMAC && VLANID +---------+ Key = { (DMAC[47:16] & VLMASK ==
* && VLAN PCP | | VLMARKER)
* && INGRESS PORT} +---------+ (both fixed)
* (exact match, | && DMAC[15:0] == VLID
* all specified in rule) | (specified in rule)
* v && INGRESS PORT }
* ------------
* 0 (PSFP) / \ 1 (ARINC664)
* +-----------/ VLLUPFORMAT \----------+
* | \ (fixed) / |
* | \ / |
* 0 (forwarding) v ------------ |
* ------------ |
* / \ 1 (QoS classification) |
* +---/ ISCRITICAL \-----------+ |
* | \ (per rule) / | |
* | \ / VLID taken from VLID taken from
* v ------------ index of rule contents of rule
* select that matched that matched
* DESTPORTS | |
* | +---------+--------+
* | |
* | v
* | VL Forwarding
* | (indexed by VLID)
* | +---------+
* | +--------------| |
* | | select TYPE +---------+
* | v
* | 0 (rate ------------ 1 (time
* | constrained) / \ triggered)
* | +------/ TYPE \------------+
* | | \ (per VLID) / |
* | v \ / v
* | VL Policing ------------ VL Policing
* | (indexed by VLID) (indexed by VLID)
* | +---------+ +---------+
* | | TYPE=0 | | TYPE=1 |
* | +---------+ +---------+
* | select SHARINDX select SHARINDX to
* | to rate-limit re-enter VL Forwarding
* | groups of VL's with new VLID for egress
* | to same quota |
* | | |
* | select MAXLEN -> exceed => drop select MAXLEN -> exceed => drop
* | | |
* | v v
* | VL Forwarding VL Forwarding
* | (indexed by SHARINDX) (indexed by SHARINDX)
* | +---------+ +---------+
* | | TYPE=0 | | TYPE=1 |
* | +---------+ +---------+
* | select PRIORITY, select PRIORITY,
* | PARTITION, DESTPORTS PARTITION, DESTPORTS
* | | |
* | v v
* | VL Policing VL Policing
* | (indexed by SHARINDX) (indexed by SHARINDX)
* | +---------+ +---------+
* | | TYPE=0 | | TYPE=1 |
* | +---------+ +---------+
* | | |
* | v |
* | select BAG, -> exceed => drop |
* | JITTER v
* | | ----------------------------------------------
* | | / Reception Window is open for this VL \
* | | / (the Schedule Table executes an entry i \
* | | / M <= i < N, for which these conditions hold): \ no
* | | +----/ \-+
* | | |yes \ WINST[M] == 1 && WINSTINDEX[M] == VLID / |
* | | | \ WINEND[N] == 1 && WINSTINDEX[N] == VLID / |
* | | | \ / |
* | | | \ (the VL window has opened and not yet closed)/ |
* | | | ---------------------------------------------- |
* | | v v
* | | dispatch to DESTPORTS when the Schedule Table drop
* | | executes an entry i with TXEN == 1 && VLINDEX == i
* v v
* dispatch immediately to DESTPORTS
*
* The per-port classification key is always composed of {DMAC, VID, PCP} and
* is non-maskable. This 'looks like' the NULL stream identification function
* from IEEE 802.1CB clause 6, except for the extra VLAN PCP. When the switch
* ports operate as VLAN-unaware, we do allow the user to not specify the VLAN
* ID and PCP, and then the port-based defaults will be used.
*
* In TTEthernet, routing is something that needs to be done manually for each
* Virtual Link. So the flow action must always include one of:
* a. 'redirect', 'trap' or 'drop': select the egress port list
* Additionally, the following actions may be applied on a Virtual Link,
* turning it into 'critical' traffic:
* b. 'police': turn it into a rate-constrained VL, with bandwidth limitation
* given by the maximum frame length, bandwidth allocation gap (BAG) and
* maximum jitter.
* c. 'gate': turn it into a time-triggered VL, which can be only be received
* and forwarded according to a given schedule.
*/
/**
* ice_gen_key_word - generate 16-bits of a key/mask word
* @val: the value
* @valid: valid bits mask (change only the valid bits)
* @dont_care: don't care mask
* @nvr_mtch: never match mask
* @key: pointer to an array of where the resulting key portion
* @key_inv: pointer to an array of where the resulting key invert portion
*
* This function generates 16-bits from a 8-bit value, an 8-bit don't care mask
* and an 8-bit never match mask. The 16-bits of output are divided into 8 bits
* of key and 8 bits of key invert.
*
* '0' = b01, always match a 0 bit
* '1' = b10, always match a 1 bit
* '?' = b11, don't care bit (always matches)
* '~' = b00, never match bit
*
* Input:
* val: b0 1 0 1 0 1
* dont_care: b0 0 1 1 0 0
* never_mtch: b0 0 0 0 1 1
* ------------------------------
* Result: key: b01 10 11 11 00 00
*/
/*
* CON5
* +--+ /-----\
* | | | |
* | | | BAT |
* | | \_____/
* | |
* | | +----+ +----+
* | | | K5 | | K1 |
* | | +----+ +----+
* | | +----+ +----+
* | | | K4 | | K2 |
* | | +----+ +----+
* | | +----+ +----+
* | | | K6 | | K3 |
* | | +----+ +----+
* .....
*/
/*
* Nexthop is pointed
* to port (not rif)
* +-------+
* +>|nexthop|
* | +-------+
* |
* +--+ +-----++
* +------->|vr|<-+ +>|nh_grp|
* | +--+ | | +------+
* | | |
* +-+-------+ +--+---+-+
* |rif_entry| |fib_node|
* +---------+ +--------+
* Rif is Fib - is exit point
* used as
* entry point
* for vr in hw
*/
/* We translate the tc filter with CT action to the following HW model:
*
* +---------------------+
* + ft prio (tc chain) +
* + original match +
* +---------------------+
* | set chain miss mapping
* | set fte_id
* | set tunnel_id
* | do decap
* |
* +-------------+
* | Chain 0 |
* | optimization|
* | v
* | +---------------------+
* | + pre_ct/pre_ct_nat + if matches +----------------------+
* | + zone+nat match +---------------->+ post_act (see below) +
* | +---------------------+ set zone +----------------------+
* | |
* +-------------+ set zone
* |
* v
* +--------------------+
* + CT (nat or no nat) +
* + tuple + zone match +
* +--------------------+
* | set mark
* | set labels_id
* | set established
* | set zone_restore
* | do nat (if needed)
* v
* +--------------+
* + post_act + original filter actions
* + fte_id match +------------------------>
* +--------------+
*
*/
/* For the following typical flow table:
*
* +-------------------------------+
* + original flow table +
* +-------------------------------+
* + original match +
* +-------------------------------+
* + sample action + other actions +
* +-------------------------------+
*
* We translate the tc filter with sample action to the following HW model:
*
* +---------------------+
* + original flow table +
* +---------------------+
* + original match +
* +---------------------+
* | set fte_id (if reg_c preserve cap)
* | do decap (if required)
* v
* +------------------------------------------------+
* + Flow Sampler Object +
* +------------------------------------------------+
* + sample ratio +
* +------------------------------------------------+
* + sample table id | default table id +
* +------------------------------------------------+
* | |
* v v
* +-----------------------------+ +-------------------+
* + sample table + + default table +
* +-----------------------------+ +-------------------+
* + forward to management vport + |
* +-----------------------------+ |
* +-------+------+
* | |reg_c preserve cap
* | |or decap action
* v v
* +-----------------+ +-------------+
* + per vport table + + post action +
* +-----------------+ +-------------+
* + original match +
* +-----------------+
* + other actions +
* +-----------------+
*/
/* Replace relevant fields, except of:
* htbl - keep the origin htbl
* miss_list + list - already took the src from the list.
* icm_addr/mr_addr - depends on the hosting table.
*
* Before:
* | a | -> | b | -> | c | ->
*
* After:
* | a | -> | c | ->
* While the data that was in b copied to a.
*/
/*
* Amount of packet buffer
* | per QoS class
* | | reserved
* | | | per egress port
* | | | |
* V V v v
* BUF_Q_RSRV_E
*/
/*
An EEPROM read command starts by shifting out 0x60+address, and then
shifting in the serial data. See the NatSemi databook for details.
* ________________
* CS : __|
* ___ ___
* CLK: ______| |___| |
* __ _______ _______
* DI : __X_______X_______X
* DO : _________X_______X
*/
/* Bit twiddling:
* Prefix: 1...110...0
* ~: 0...001...1
* + 1: 0...010...0 is power of two
* so (~x) & ((~x) + 1) == 0. Converse holds also.
*/
/* DMAC control register GDMACCNTR
*
* 1(0) enable r/tx dma
* 0000000 fixed to 0
*
* 000000 fixed to 0
* 0(1) en/disable descr writeback on force end
* 0(1) force end
*
* 000000 fixed to 0
* 00 burst alignment: 128 bytes
* 11 burst alignment: 1024 bytes
*
* 00000 fixed to 0
* 0 descr writeback size 32 bytes
* 0(1) descr chain end interrupt enable
* 0(1) descr status writeback enable
*/
* The generic software interface (GSI) is an integral component of the IPA,
* providing a well-defined communication layer between the AP subsystem
* and the IPA core. The modem uses the GSI layer as well.
*
* -------- ---------
* | | | |
* | AP +<---. .----+ Modem |
* | +--. | | .->+ |
* | | | | | | | |
* -------- | | | | ---------
* v | v |
* --+-+---+-+--
* | GSI |
* |-----------|
* | |
* | IPA |
* | |
* -------------
*
* In the above diagram, the AP and Modem represent "execution environments"
* (EEs), which are independent operating environments that use the IPA for
* data transfer.
/* RollBall SFPs do not access internal PHY via I2C address 0x56, but
* instead via address 0x51, when SFP page is set to 0x03 and password to
* 0xffffffff.
*
* address size contents description
* ------- ---- -------- -----------
* 0x80 1 CMD 0x01/0x02/0x04 for write/read/done
* 0x81 1 DEV Clause 45 device
* 0x82 2 REG Clause 45 register
* 0x84 2 VAL Register value
*/
/*
* Get/Allocate a free Tx Data Buffer
*
* *--------------*-----------------*----------------------------------*
* | PLCP | MAC Header | DST SRC Data ... |
* | (24 bytes) | (30 bytes) | (6) (6) (Ethernet Row Data) |
* *--------------*-----------------*----------------------------------*
* \ \- IEEE 802.11 -/ \-------------- len --------------/
* \-struct wl3501_80211_tx_hdr--/ \-------- Ethernet Frame -------/
*
* Return = Position in Card
*/
/*
* Fw Mode/SubMode Mask
*-----------------------------------------------------------------------------
* SUB | SUB | SUB | SUB | | | |
*MODE[3] | MODE[2] | MODE[1] | MODE[0] | MODE[3] | MODE[2] | MODE[1] | MODE[0]
* (2) | (2) | (2) | (2) | (2) | (2) | (2) | (2)
*-----------------------------------------------------------------------------
*/
/* Fw Mode/SubMode Mask
|------------------------------------------------------------------------------|
| SUB | SUB | SUB | SUB | | | |
| MODE[3] | MODE[2] | MODE[1] | MODE[0] | MODE[3] | MODE[2] | MODE[1] | MODE[0|
| (2) | (2) | (2) | (2) | (2) | (2) | (2) | (2)
|------------------------------------------------------------------------------|
*/
/* When driver needs ucode to stop beaconing, it has to make sure that
* MCTL_AP is clear and MCTL_INFRA is set
* Mode MCTL_AP MCTL_INFRA
* AP 1 1
* STA 0 1 <--- This will ensure no beacons
* IBSS 0 0
*/
/*
* Control channel position:
* For legacy set bit means upper channel, otherwise lower.
* For VHT - bit-2 marks if the control is lower/upper relative to center-freq
* bits-1:0 mark the distance from the center freq. for 20Mhz, offset is 0.
* center_freq
* For EHT - bit-3 is used for extended distance
* |
* 40Mhz |____|____|
* 80Mhz |____|____|____|____|
* 160Mhz |____|____|____|____|____|____|____|____|
* 320MHz |____|____|____|____|____|____|____|____|____|____|____|____|____|____|____|____|
* code 1011 1010 1001 1000 0011 0010 0001 0000 0100 0101 0110 0111 1100 1101 1110 1111
*/
/*
* This function checks if a scanned network is compatible with the driver
* settings.
*
* WEP WPA WPA2 ad-hoc encrypt Network
* enabled enabled enabled AES mode Privacy WPA WPA2 Compatible
* 0 0 0 0 NONE 0 0 0 yes No security
* 0 1 0 0 x 1x 1 x yes WPA (disable
* HT if no AES)
* 0 0 1 0 x 1x x 1 yes WPA2 (disable
* HT if no AES)
* 0 0 0 1 NONE 1 0 0 yes Ad-hoc AES
* 1 0 0 0 NONE 1 0 0 yes Static WEP
* (disable HT)
* 0 0 0 0 !=NONE 1 0 0 yes Dynamic WEP
*
* Compatibility is not matched while roaming, except for mode.
*/
/*
*
* key_type_e key size key format
* ---------- --------- ----------
* 0x00 5, 13, 29 Key data
* 0x01 5, 13, 29 Key data
* 0x04 16 16 bytes of key data
* 0x05 16 16 bytes of key data
* 0x0a 32 16 bytes of TKIP key data
* 8 bytes of RX MIC key data
* 8 bytes of TX MIC key data
* 0x0b 32 16 bytes of TKIP key data
* 8 bytes of RX MIC key data
* 8 bytes of TX MIC key data
*
*/
/* Set the partitions to access the chip addresses
*
* To simplify driver code, a fixed (virtual) memory map is defined for
* register and memory addresses. Because in the chipset, in different stages
* of operation, those addresses will move around, an address translation
* mechanism is required.
*
* There are four partitions (three memory and one register partition),
* which are mapped to two different areas of the hardware memory.
*
* Virtual address
* space
*
* | |
* ...+----+--> mem.start
* Physical address ... | |
* space ... | | [PART_0]
* ... | |
* 00000000 <--+----+... ...+----+--> mem.start + mem.size
* | | ... | |
* |MEM | ... | |
* | | ... | |
* mem.size <--+----+... | | {unused area)
* | | ... | |
* |REG | ... | |
* mem.size | | ... | |
* + <--+----+... ...+----+--> reg.start
* reg.size | | ... | |
* |MEM2| ... | | [PART_1]
* | | ... | |
* ...+----+--> reg.start + reg.size
* | |
*
*/
/* Modem Exception Handshake Flow
*
* Modem HW Exception interrupt received
* (MD_IRQ_CCIF_EX)
* |
* +---------v--------+
* | HIF_EX_INIT | : Disable and clear TXQ
* +------------------+
* |
* +---------v--------+
* | HIF_EX_INIT_DONE | : Wait for the init to be done
* +------------------+
* |
* +---------v--------+
* |HIF_EX_CLEARQ_DONE| : Disable and clear RXQ
* +------------------+ : Flush TX/RX workqueues
* |
* +---------v--------+
* |HIF_EX_ALLQ_RESET | : Restart HW and CLDMA
* +------------------+
*/
/* Handle backend state transitions:
*
* The backend state starts in Initialising and the following transitions are
* allowed.
*
* Initialising -> InitWait -> Connected
* \
* \ ^ \ |
* \ | \ |
* \ | \ |
* \ | \ |
* \ | \ |
* \ | \ |
* V | V V
*
* Closed <-> Closing
*
* The state argument specifies the eventual state of the backend and the
* function transitions to that state via the shortest path.
*/
/*
* A log group represents one log 'lane', and consists of four log entries.
* Two of the four entries are valid entries, and the remaining two are
* padding. Due to an old bug in the padding location, we need to perform a
* test to determine the padding scheme being used, and use that scheme
* thereafter.
*
* In kernels prior to 4.15, 'log group' would have actual log entries at
* indices (0, 2) and padding at indices (1, 3), where as the correct/updated
* format has log entries at indices (0, 1) and padding at indices (2, 3).
*
* Old (pre 4.15) format:
* +-----------------+-----------------+
* | ent[0] | ent[1] |
* | 16B | 16B |
* | lba/old/new/seq | pad |
* +-----------------------------------+
* | ent[2] | ent[3] |
* | 16B | 16B |
* | lba/old/new/seq | pad |
* +-----------------+-----------------+
*
* New format:
* +-----------------+-----------------+
* | ent[0] | ent[1] |
* | 16B | 16B |
* | lba/old/new/seq | lba/old/new/seq |
* +-----------------------------------+
* | ent[2] | ent[3] |
* | 16B | 16B |
* | pad | pad |
* +-----------------+-----------------+
*
* We detect during start-up which format is in use, and set
* arena->log_index[(0, 1)] with the detected format.
*/
/*
* The PCI NTB function driver configures the SoC with multiple PCIe Endpoint
* (EP) controller instances (see diagram below) in such a way that
* transactions from one EP controller are routed to the other EP controller.
* Once PCI NTB function driver configures the SoC with multiple EP instances,
* HOST1 and HOST2 can communicate with each other using SoC as a bridge.
*
* +-------------+ +-------------+
* | | | |
* | HOST1 | | HOST2 |
* | | | |
* +------^------+ +------^------+
* | |
* | |
* +---------|-------------------------------------------------|---------+
* | +------v------+ +------v------+ |
* | | | | | |
* | | EP | | EP | |
* | | CONTROLLER1 | | CONTROLLER2 | |
* | | <-----------------------------------> | |
* | | | | | |
* | | | | | |
* | | | SoC With Multiple EP Instances | | |
* | | | (Configured using NTB Function) | | |
* | +-------------+ +-------------+ |
* +---------------------------------------------------------------------+
*/
/*****************************************************************************
* Orion GPIO IRQ
*
* GPIO_IN_POL register controls whether GPIO_DATA_IN will hold the same
* value of the line or the opposite value.
*
* Level IRQ handlers: DATA_IN is used directly as cause register.
* Interrupt are masked by LEVEL_MASK registers.
* Edge IRQ handlers: Change in DATA_IN are latched in EDGE_CAUSE.
* Interrupt are masked by EDGE_MASK registers.
* Both-edge handlers: Similar to regular Edge handlers, but also swaps
* the polarity to catch the next line transaction.
* This is a race condition that might not perfectly
* work on some use cases.
*
* Every eight GPIO lines are grouped (OR'ed) before going up to main
* cause register.
*
* EDGE cause mask
* data-in /--------| |-----| |----\
* -----| |----- ---- to main cause reg
* X \----------------| |----/
* polarity LEVEL mask
*
****************************************************************************/
* DMA transfers are limited to the lower 16MB of _physical_ memory.
* Note that addresses loaded into registers must be _physical_ addresses,
* not logical addresses (which may differ if paging is active).
*
* Address mapping for channels 0-3:
*
* A23 ... A16 A15 ... A8 A7 ... A0 (Physical addresses)
* | ... | | ... | | ... |
* | ... | | ... | | ... |
* | ... | | ... | | ... |
* P7 ... P0 A7 ... A0 A7 ... A0
* | Page | Addr MSB | Addr LSB | (DMA registers)
*
* Address mapping for channels 5-7:
*
* A23 ... A17 A16 A15 ... A9 A8 A7 ... A1 A0 (Physical addresses)
* | ... | \ \ ... \ \ \ ... \ \
* | ... | \ \ ... \ \ \ ... \ (not used)
* | ... | \ \ ... \ \ \ ... \
* P7 ... P1 (0) A7 A6 ... A0 A7 A6 ... A0
* | Page | Addr MSB | Addr LSB | (DMA registers)
*
* Again, channels 5-7 transfer _physical_ words (16 bits), so addresses
* and counts _must_ be word-aligned (the lowest address bit is _ignored_ at
* the hardware level, so odd-byte transfers aren't possible).
/*
* +------------+ +---------------------------------------+
* | | | |
* +------------+ | +--------------+
* | NTB | | | NTB |
* | NetDev | | | NetDev |
* +------------+ | +--------------+
* | NTB | | | NTB |
* | Transfer | | | Transfer |
* +------------+ | +--------------+
* | | | | |
* | PCI NTB | | | |
* | EPF | | | |
* | Driver | | | PCI Virtual |
* | | +---------------+ | NTB Driver |
* | | | PCI EP NTB |<------>| |
* | | | FN Driver | | |
* +------------+ +---------------+ +--------------+
* | | | | | |
* | PCI Bus | <-----> | PCI EP Bus | | Virtual PCI |
* | | PCI | | | Bus |
* +------------+ +---------------+--------+--------------+
* PCIe Root Port PCI EP
*/
/*
* Embedded Display Port PLL driver block diagram for branch clocks
*
* +------------------------------+
* | EDP_VCO_CLK |
* | |
* | +-------------------+ |
* | | (EDP PLL/VCO) | |
* | +---------+---------+ |
* | v |
* | +----------+-----------+ |
* | | hsclk_divsel_clk_src | |
* | +----------+-----------+ |
* +------------------------------+
* |
* +---------<---------v------------>----------+
* | |
* +--------v----------------+ |
* | edp_phy_pll_link_clk | |
* | link_clk | |
* +--------+----------------+ |
* | |
* | |
* v v
* Input to DISPCC block |
* for link clk, crypto clk |
* and interface clock |
* |
* |
* +--------<------------+-----------------+---<---+
* | | |
* +----v---------+ +--------v-----+ +--------v------+
* | vco_divided | | vco_divided | | vco_divided |
* | _clk_src | | _clk_src | | _clk_src |
* | | | | | |
* |divsel_six | | divsel_two | | divsel_four |
* +-------+------+ +-----+--------+ +--------+------+
* | | |
* v---->----------v-------------<------v
* |
* +----------+-----------------+
* | edp_phy_pll_vco_div_clk |
* +---------+------------------+
* |
* v
* Input to DISPCC block
* for EDP pixel clock
*
*/
/*
* Register a fixed rate pipe clock.
*
* The <s>_pipe_clksrc generated by PHY goes to the GCC that gate
* controls it. The <s>_pipe_clk coming out of the GCC is requested
* by the PHY driver for its operations.
* We register the <s>_pipe_clksrc here. The gcc driver takes care
* of assigning this <s>_pipe_clksrc as parent to <s>_pipe_clk.
* Below picture shows this relationship.
*
* +---------------+
* | PHY block |<<---------------------------------------+
* | | |
* | +-------+ | +-----+ |
* I/P---^-->| PLL |---^--->pipe_clksrc--->| GCC |--->pipe_clk---+
* clk | +-------+ | +-----+
* +---------------+
*/
/*
* Register a fixed rate pipe clock.
*
* The <s>_pipe_clksrc generated by PHY goes to the GCC that gate
* controls it. The <s>_pipe_clk coming out of the GCC is requested
* by the PHY driver for its operations.
* We register the <s>_pipe_clksrc here. The gcc driver takes care
* of assigning this <s>_pipe_clksrc as parent to <s>_pipe_clk.
* Below picture shows this relationship.
*
* +---------------+
* | PHY block |<<---------------------------------------+
* | | |
* | +-------+ | +-----+ |
* I/P---^-->| PLL |---^--->pipe_clksrc--->| GCC |--->pipe_clk---+
* clk | +-------+ | +-----+
* +---------------+
*/
/**
* enum - Locking variants of the iocfg bases
*
* MT7986 have multiple bases to program pin configuration listed as the below:
* iocfg_rt:0x11c30000, iocfg_rb:0x11c40000, iocfg_lt:0x11e20000,
* iocfg_lb:0x11e30000, iocfg_tr:0x11f00000, iocfg_tl:0x11f10000,
* _i_based could be used to indicate what base the pin should be mapped into.
*
* Each iocfg register base control different group of pads on the SoC
*
*
* chip carrier
*
* A B C D E F G H
* +------------------------+
* 8 | o o o o o o o o |
* 7 | o o o o o o o o |
* 6 | o o o o o o o o |
* 5 | o o o o o o o o |
* 4 | o o o o o o o o |
* 3 | o o o o o o o o |
* 2 | o o o o o o o o |
* 1 | o o o o o o o o |
* +------------------------+
*
* inside Chip carrier
*
* A B C D E F G H
* +------------------------+
* 8 | |
* 7 | TL TR |
* 6 | +---------+ |
* 5 | LT | | RT |
* 4 | | | |
* 3 | LB | | RB |
* 2 | +---------+ |
* 1 | |
* +------------------------+
*
*/
/*
* This section supports converting to/from custom MTK_PIN_CONFIG_DRV_ADV
* and standard PIN_CONFIG_DRIVE_STRENGTH_UA pin configs.
*
* The custom value encodes three hardware bits as follows:
*
* | Bits |
* | 2 (E1) | 1 (E0) | 0 (EN) | drive strength (uA)
* ------------------------------------------------
* | x | x | 0 | disabled, use standard drive strength
* -------------------------------------
* | 0 | 0 | 1 | 125 uA
* | 0 | 1 | 1 | 250 uA
* | 1 | 0 | 1 | 500 uA
* | 1 | 1 | 1 | 1000 uA
*/
/*
* The battery charging profile of BD99954.
*
* Curve (1) represents charging current.
* Curve (2) represents battery voltage.
*
* The BD99954 data sheet divides charging to three phases.
* a) Trickle-charge with constant current (8).
* b) pre-charge with constant current (6)
* c) fast-charge, first with constant current (5) phase. After
* the battery voltage has reached target level (4) we have constant
* voltage phase until charging current has dropped to termination
* level (7)
*
* V ^ ^ I
* . .
* . .
*(4)` `.` ` ` ` ` ` ` ` ` ` ` ` ` ` ----------------------------.
* . :/ .
* . o----+/:/ ` ` ` ` ` ` ` ` ` ` ` ` `.` ` (5)
* . + :: + .
* . + /- -- .
* . +`/- + .
* . o/- -: .
* . .s. +` .
* . .--+ `/ .
* . ..`` + .: .
* . -` + -- .
* . (2) ...`` + :- .
* . ...`` + -: .
*(3)` `.`."" ` ` ` `+-------- ` ` ` ` ` ` `.:` ` ` ` ` ` ` ` ` .` ` (6)
* . + `:. .
* . + -: .
* . + -:. .
* . + .--. .
* . (1) + `.+` ` ` `.` ` (7)
* -..............` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` ` + ` ` ` .` ` (8)
* . + -
* -------------------------------------------------+++++++++-->
* | trickle | pre | fast |
*
* Details of DT properties for different limits can be found from BD99954
* device tree binding documentation.
*/
/*
* Capture using PWM input mode:
* ___ ___
* TI[1, 2, 3 or 4]: ........._| |________|
* ^0 ^1 ^2
* . . .
* . . XXXXX
* . . XXXXX |
* . XXXXX . |
* XXXXX . . |
* COUNTER: ______XXXXX . . . |_XXX
* start^ . . . ^stop
* . . . .
* v v . v
* v
* CCR1/CCR3: tx..........t0...........t2
* CCR2/CCR4: tx..............t1.........
*
* DMA burst transfer: | |
* v v
* DMA buffer: { t0, tx } { t2, t1 }
* DMA done: ^
*
* 0: IC1/3 snapchot on rising edge: counter value -> CCR1/CCR3
* + DMA transfer CCR[1/3] & CCR[2/4] values (t0, tx: doesn't care)
* 1: IC2/4 snapchot on falling edge: counter value -> CCR2/CCR4
* 2: IC1/3 snapchot on rising edge: counter value -> CCR1/CCR3
* + DMA transfer CCR[1/3] & CCR[2/4] values (t2, t1)
*
* DMA done, compute:
* - Period = t2 - t0
* - Duty cycle = t1 - t0
*/
/*
* Add serial number to information bar if signature AAh
* is found in at bit 15-9 (7 bits) of word 1.
*
* Serial Number consists fo 12 alpha-numeric digits.
*
* 1 - Product type (A,B,C,D..) Word0: 15-13 (3 bits)
* 2 - MFG Location (A,B,C,D..) Word0: 12-10 (3 bits)
* 3-4 - Product ID (0-99) Word0: 9-0 (10 bits)
* 5 - Product revision (A-J) Word0: " "
*
* Signature Word1: 15-9 (7 bits)
* 6 - Year (0-9) Word1: 8-6 (3 bits) & Word2: 15 (1 bit)
* 7-8 - Week of the year (1-52) Word1: 5-0 (6 bits)
*
* 9-12 - Serial Number (A001-Z999) Word2: 14-0 (15 bits)
*
* Note 1: Only production cards will have a serial number.
*
* Note 2: Signature is most significant 7 bits (0xFE).
*
* Returns ASC_TRUE if serial number found, otherwise returns ASC_FALSE.
*/
* In order to solve the problem we have to feed the DMA engine with SG list
* entries one-by-one. It shall keep the DW APB SSI Tx and Rx FIFOs
* synchronized and prevent the Rx FIFO overflow. Since in general the tx_sg
* and rx_sg lists may have different number of entries of different lengths
* (though total length should match) let's virtually split the SG-lists to the
* set of DMA transfers, which length is a minimum of the ordered SG-entries
* lengths. An ASCII-sketch of the implemented algo is following:
* xfer->len
* |___________|
* tx_sg list: |___|____|__|
* rx_sg list: |_|____|____|
* DMA transfers: |_|_|__|_|__|
*
* Note in order to have this workaround solving the denoted problem the DMA
* engine driver should properly initialize the max_sg_burst capability and set
* the DMA device max segment size parameter with maximum data block size the
* DMA engine supports.
/*
* The Clock Mux
* x-----------------x x------------x x------\
* |---| pow2 fixed div |---| pow2 div |----| |
* | x-----------------x x------------x | |
* src ---| | mux |-- out
* | x-----------------x x------------x | |
* |---| enh fixed div |---| enh div |0---| |
* x-----------------x x------------x x------/
*
* Clk path for GX series:
* src -> pow2 fixed div -> pow2 div -> out
*
* Clk path for AXG series:
* src -> pow2 fixed div -> pow2 div -> mux -> out
* src -> enh fixed div -> enh div -> mux -> out
*
* Clk path for G12A series:
* pclk -> pow2 fixed div -> pow2 div -> mux -> out
* pclk -> enh fixed div -> enh div -> mux -> out
*
* The pow2 divider is tied to the controller HW state, and the
* divider is only valid when the controller is initialized.
*
* A set of clock ops is added to make sure we don't read/set this
* clock rate while the controller is in an unknown state.
*/
/*
* In FlexSPI controller, flash access is based on value of FSPI_FLSHXXCR0
* register and start base address of the slave device.
*
* (Higher address)
* -------- <-- FLSHB2CR0
* | B2 |
* | |
* B2 start address --> -------- <-- FLSHB1CR0
* | B1 |
* | |
* B1 start address --> -------- <-- FLSHA2CR0
* | A2 |
* | |
* A2 start address --> -------- <-- FLSHA1CR0
* | A1 |
* | |
* A1 start address --> -------- (Lower address)
*
*
* Start base address defines the starting address range for given CS and
* FSPI_FLSHXXCR0 defines the size of the slave device connected at given CS.
*
* But, different targets are having different combinations of number of CS,
* some targets only have single CS or two CS covering controller's full
* memory mapped space area.
* Thus, implementation is being done as independent of the size and number
* of the connected slave device.
* Assign controller memory mapped space size as the size to the connected
* slave device.
* Mark FLSHxxCR0 as zero initially and then assign value only to the selected
* chip-select Flash configuration register.
*
* For e.g. to access CS2 (B1), FLSHB1CR0 register would be equal to the
* memory mapped size of the controller.
* Value for rest of the CS FLSHxxCR0 register would be zero.
*
*/
* Note that according to the manual's driver example, the following operations
* may run independent of each other:
* - area reserve/read/write/release (point 1 above)
* - mailbox operations (point 2 above)
* - switching power on/off
*
* To allow them to run independently, each operation class gets its own queue.
*
* Userspace processes A, B, C, D post tasks to the appropriate queue,
* and wait for task completion:
*
* process A B C D
* | | | |
* v v v v
* |<----- ========================================
* | | | |
* | v v v-------<-------+
* | +--------------------------------------+ |
* | | power q | mbox q | area q | |
* | |------------|------------|------------| |
* | | task | task | task | |
* | | task | task | task | |
* | | task wait | task wait | task wait | |
* | +--------------------------------------+ |
* | ^ ^ ^ |
* | | | | ^
* | +--------------------------------------+ |
* | | queue thread | |
* | |--------------------------------------| |
* | | single-threaded: | |
* | | loop: | |
* v | for each queue: | |
* | | run task state machine | |
* | | if task waiting: | |
* | | leave on queue | |
* | | if task done: | |
* | | complete task, remove from q | |
* | | if software irq event bits set: | |
* | | notify userspace | |
* | | post clear event bits task------>|>-------+
* | | wait for IND_AB changed event OR |
* | | task added event OR |
* | | timeout |
* | | end loop |
* | +--------------------------------------+
* | + wake up +
* | +--------------------------------------+
* | ^ ^
* | | |
* +-------->------- |
* |
* +--------------------------------------+
* | interrupt service routine |
* |--------------------------------------|
* | wake up queue thread on IND_AB change|
* +--------------------------------------+
*
* Note that the Anybus interrupt is dual-purpose:
* - after a reset, triggered when the card becomes ready;
* - during normal operation, triggered when AB_IND changes.
* This is why the interrupt service routine doesn't just wake up the
* queue thread, but also completes the card_boot completion.
*
* [1] https://www.anybus.com/docs/librariesprovider7/default-document-library/
* manuals-design-guides/hms-hmsi-27-275.pdf
/* ****************************************************
* Each coefficient is stored as 7bits to fit 2 of them into one
* ISP vector element, so we will store 4 coefficents on every
* memory word (32bits)
*
* 0: Coefficient 0 used bits
* 1: Coefficient 1 used bits
* 2: Coefficient 2 used bits
* 3: Coefficient 3 used bits
* x: not used
*
* xx33333332222222 | xx11111110000000
*
* ***************************************************
*/
/* Bilinear interpolation on shading tables:
* For each target point T, we calculate the 4 surrounding source points:
* ul (upper left), ur (upper right), ll (lower left) and lr (lower right).
* We then calculate the distances from the T to the source points: x0, x1,
* y0 and y1.
* We then calculate the value of T:
* dx0*dy0*Slr + dx0*dy1*Sur + dx1*dy0*Sll + dx1*dy1*Sul.
* We choose a grid size of 1x1 which means:
* dx1 = 1-dx0
* dy1 = 1-dy0
*
* Sul dx0 dx1 Sur
* .<----->|<------------->.
* ^
* dy0|
* v T
* - .
* ^
* |
* dy1|
* v
* . .
* Sll Slr
*
* Padding:
* The area that the ISP operates on can include padding both on the left
* and the right. We need to padd the shading table such that the shading
* values end up on the correct pixel values. This means we must padd the
* shading table to match the ISP padding.
* We can have 5 cases:
* 1. All 4 points fall in the left padding.
* 2. The left 2 points fall in the left padding.
* 3. All 4 points fall in the cropped (target) region.
* 4. The right 2 points fall in the right padding.
* 5. All 4 points fall in the right padding.
/*
*
*
* 802.11 Data Frame
*
*
* 802.11 frame_contorl for data frames - 2 bytes
* ,-----------------------------------------------------------------------------------------.
* bits | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | a | b | c | d | e |
* |----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|------|
* val | 0 | 0 | 0 | 1 | x | 0 | 0 | 0 | 1 | 0 | x | x | x | x | x |
* |----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|------|
* desc | ^-ver-^ | ^type-^ | ^-----subtype-----^ | to |from |more |retry| pwr |more |wep |
* | | | x=0 data,x=1 data+ack | DS | DS |frag | | mgm |data | |
* '-----------------------------------------------------------------------------------------'
* /\
* |
* 802.11 Data Frame |
* ,--------- 'ctrl' expands to >-----------'
* |
* ,--'---,-------------------------------------------------------------.
* Bytes | 2 | 2 | 6 | 6 | 6 | 2 | 0..2312 | 4 |
* |------|------|---------|---------|---------|------|---------|------|
* Desc. | ctrl | dura | DA/RA | TA | SA | Sequ | Frame | fcs |
* | | tion | (BSSID) | | | ence | data | |
* `--------------------------------------------------| |------'
* Total: 28 non-data bytes `----.----'
* |
* .- 'Frame data' expands to <---------------------------'
* |
* V
* ,---------------------------------------------------.
* Bytes | 1 | 1 | 1 | 3 | 2 | 0-2304 |
* |------|------|---------|----------|------|---------|
* Desc. | SNAP | SNAP | Control |Eth Tunnel| Type | IP |
* | DSAP | SSAP | | | | Packet |
* | 0xAA | 0xAA |0x03 (UI)|0x00-00-F8| | |
* `-----------------------------------------| |
* Total: 8 non-data bytes `----.----'
* |
* .- 'IP Packet' expands, if WEP enabled, to <--'
* |
* V
* ,-----------------------.
* Bytes | 4 | 0-2296 | 4 |
* |-----|-----------|-----|
* Desc. | IV | Encrypted | ICV |
* | | IP Packet | |
* `-----------------------'
* Total: 8 non-data bytes
*
*
* 802.3 Ethernet Data Frame
*
* ,-----------------------------------------.
* Bytes | 6 | 6 | 2 | Variable | 4 |
* |-------|-------|------|-----------|------|
* Desc. | Dest. | Source| Type | IP Packet | fcs |
* | MAC | MAC | | | |
* `-----------------------------------------'
* Total: 18 non-data bytes
*
* In the event that fragmentation is required, the incoming payload is split into
* N parts of size ieee->fts. The first fragment contains the SNAP header and the
* remaining packets are just data.
*
* If encryption is enabled, each fragment payload size is reduced by enough space
* to add the prefix and postfix (IV and ICV totalling 8 bytes in the case of WEP)
* So if you have 1500 bytes of payload with ieee->fts set to 500 without
* encryption it will take 3 frames. With WEP it will take 4 frames as the
* payload of each frame is reduced to 492 bytes.
*
* SKB visualization
*
* ,- skb->data
* |
* | ETHERNET HEADER ,-<-- PAYLOAD
* | | 14 bytes from skb->data
* | 2 bytes for Type --> ,T. | (sizeof ethhdr)
* | | | |
* |,-Dest.--. ,--Src.---. | | |
* | 6 bytes| | 6 bytes | | | |
* v | | | | | |
* 0 | v 1 | v | v 2
* 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
* ^ | ^ | ^ |
* | | | | | |
* | | | | `T' <---- 2 bytes for Type
* | | | |
* | | '---SNAP--' <-------- 6 bytes for SNAP
* | |
* `-IV--' <-------------------- 4 bytes for IV (WEP)
*
* SNAP HEADER
*
*/
/*
* I2C Software Master Driver:
* ===========================
* Each i2c cycle is split into 4 sections. Each of these section marks
* a point in time where the SCL or SDA may be changed.
*
* 1 Cycle == | Section I. | Section 2. | Section 3. | Section 4. |
* +-------------+-------------+-------------+-------------+
* | SCL set LOW |SCL no change| SCL set HIGH|SCL no change|
*
* ____________ _____________
* SCL == XXXX _____________ ____________ /
*
* I.e. the SCL may only be changed in section 1. and section 3. while
* the SDA may only be changed in section 2. and section 4. The table
* below gives the changes for these 2 lines in the varios sections.
*
* Section changes Table:
* ======================
* blank = no change, L = set bit LOW, H = set bit HIGH
*
* | 1.| 2.| 3.| 4.|
* ---------------+---+---+---+---+
* Tx Start SDA | | H | | L |
* SCL | L | | H | |
* ---------------+---+---+---+---+
* Tx Stop SDA | | L | | H |
* SCL | L | | H | |
* ---------------+---+---+---+---+
* Tx bit H SDA | | H | | |
* SCL | L | | H | |
* ---------------+---+---+---+---+
* Tx bit L SDA | | L | | |
* SCL | L | | H | |
* ---------------+---+---+---+---+
*
*/
* Regulation Logic: a two point regulation, deliver cooling state depending
* on the previous state shown in this diagram:
*
* Fan: OFF ON
*
* |
* |
* trip_temp: +---->+
* | | ^
* | | |
* | | Temperature
* (trip_temp - hyst): +<----+
* |
* |
* |
*
* * If the fan is not running and temperature exceeds trip_temp, the fan
* gets turned on.
* * In case the fan is running, temperature must fall below
* (trip_temp - hyst) so that the fan gets turned off again.
/**
* DOC: bandgap driver data structure
* ==================================
*
* +----------+----------------+
* | struct temp_sensor_regval |
* +---------------------------+
* * (Array of)
* |
* |
* +-------------------+ +-----------------+
* | struct ti_bandgap |-->| struct device * |
* +----------+--------+ +-----------------+
* |
* |
* V
* +------------------------+
* | struct ti_bandgap_data |
* +------------------------+
* |
* |
* * (Array of)
* +------------+------------------------------------------------------+
* | +----------+------------+ +-------------------------+ |
* | | struct ti_temp_sensor |-->| struct temp_sensor_data | |
* | +-----------------------+ +------------+------------+ |
* | | |
* | + |
* | V |
* | +----------+-------------------+ |
* | | struct temp_sensor_registers | |
* | +------------------------------+ |
* | |
* +-------------------------------------------------------------------+
*
* Above is a simple diagram describing how the data structure below
* are organized. For each bandgap device there should be a ti_bandgap_data
* containing the device instance configuration, as well as, an array of
* sensors, representing every sensor instance present in this bandgap.
*/
/*
* We use atomic64_read() here because the ASID for an 'mm_struct' can
* be reallocated when scheduling one of its threads following a
* rollover event (see new_context() and flush_context()). In this case,
* a concurrent TLBI (e.g. via try_to_unmap_one() and ptep_clear_flush())
* may use a stale ASID. This is fine in principle as the new ASID is
* guaranteed to be clean in the TLB, but the TLBI routines have to take
* care to handle the following race:
*
* CPU 0 CPU 1 CPU 2
*
* // ptep_clear_flush(mm)
* xchg_relaxed(pte, 0)
* DSB ISHST
* old = ASID(mm)
* | <rollover>
* | new = new_context(mm)
* \-----------------> atomic_set(mm->context.id, new)
* cpu_switch_mm(mm)
* // Hardware walk of pte using new ASID
* TLBI(old)
*
* In this scenario, the barrier on CPU 0 and the dependency on CPU 1
* ensure that the page-table walker on CPU 1 *must* see the invalid PTE
* written by CPU 0.
*/
* Note that at the moment this function tends to front-pack the schedule.
* In some cases that's really non-ideal (it's hard to schedule things that
* need to repeat every period). In other cases it's perfect (you can easily
* schedule bigger, less often repeating things).
*
* Here's the algorithm in action (8 periods, 5 bits per period):
* |** | |** | |** | |** | | OK 2 bits, intv 2 at 0
* |*****| ***|*****| ***|*****| ***|*****| ***| OK 3 bits, intv 3 at 2
* |*****|* ***|*****| ***|*****|* ***|*****| ***| OK 1 bits, intv 4 at 5
* |** |* |** | |** |* |** | | Remv 3 bits, intv 3 at 2
* |*** |* |*** | |*** |* |*** | | OK 1 bits, intv 6 at 2
* |**** |* * |**** | * |**** |* * |**** | * | OK 1 bits, intv 1 at 3
* |**** |**** |**** | *** |**** |**** |**** | *** | OK 2 bits, intv 2 at 6
* |*****|*****|*****| ****|*****|*****|*****| ****| OK 1 bits, intv 1 at 4
* |*****|*****|*****| ****|*****|*****|*****| ****| FAIL 1 bits, intv 1
* | ***|*****| ***| ****| ***|*****| ***| ****| Remv 2 bits, intv 2 at 0
* | ***| ****| ***| ****| ***| ****| ***| ****| Remv 1 bits, intv 4 at 5
* | **| ****| **| ****| **| ****| **| ****| Remv 1 bits, intv 6 at 2
* | *| ** *| *| ** *| *| ** *| *| ** *| Remv 1 bits, intv 1 at 3
* | *| *| *| *| *| *| *| *| Remv 2 bits, intv 2 at 6
* | | | | | | | | | Remv 1 bits, intv 1 at 4
* |** | |** | |** | |** | | OK 2 bits, intv 2 at 0
* |*** | |** | |*** | |** | | OK 1 bits, intv 4 at 2
* |*****| |** **| |*****| |** **| | OK 2 bits, intv 2 at 3
* |*****|* |** **| |*****|* |** **| | OK 1 bits, intv 4 at 5
* |*****|*** |** **| ** |*****|*** |** **| ** | OK 2 bits, intv 2 at 6
* |*****|*****|** **| ****|*****|*****|** **| ****| OK 2 bits, intv 2 at 8
* |*****|*****|*****| ****|*****|*****|*****| ****| OK 1 bits, intv 4 at 12
*
* This function is pretty generic and could be easily abstracted if anything
* needed similar scheduling.
*
* Returns either -ENOSPC or a >= 0 start bit which should be passed to the
* unschedule routine. The map bitmap will be updated on a non-error result.
/* Host side RX (IN) using Mentor DMA works as follows:
submit_urb ->
- if queue was empty, ProgramEndpoint
- first IN token is sent out (by setting ReqPkt)
LinuxIsr -> RxReady()
/\ => first packet is received
| - Set in mode 0 (DmaEnab, ~ReqPkt)
| -> DMA Isr (transfer complete) -> RxReady()
| - Ack receive (~RxPktRdy), turn off DMA (~DmaEnab)
| - if urb not complete, send next IN token (ReqPkt)
| | else complete urb.
| |
---------------------------
*
* Nuances of mode 1:
* For short packets, no ack (+RxPktRdy) is sent automatically
* (even if AutoClear is ON)
* For full packets, ack (~RxPktRdy) and next IN token (+ReqPkt) is sent
* automatically => major problem, as collecting the next packet becomes
* difficult. Hence mode 1 is not used.
/*
* image of mod_host
*
* +--------+
* | udev 0 | --> it is used when set address
* +--------+
*
* +--------+ pipes are reused for each uep.
* | udev 1 |-+- [uep 0 (dcp) ] --+ pipe will be switched when
* +--------+ | | other device requested
* +- [uep 1 (bulk)] --|---+ +--------------+
* | +--------------> | pipe0 (dcp) |
* +- [uep 2 (bulk)] -@ | +--------------+
* | | pipe1 (isoc) |
* +--------+ | +--------------+
* | udev 2 |-+- [uep 0 (dcp) ] -@ +----------> | pipe2 (bulk) |
* +--------+ | +--------------+
* +- [uep 1 (int) ] ----+ +------> | pipe3 (bulk) |
* | | +--------------+
* +--------+ +-----|------> | pipe4 (int) |
* | udev 3 |-+- [uep 0 (dcp) ] -@ | +--------------+
* +--------+ | | | .... |
* +- [uep 1 (bulk)] -@ | | .... |
* | |
* +- [uep 2 (bulk)]-----------+
*
* @ : uep requested free pipe, but all have been used.
* now it is waiting for free pipe
*/
/*
* We have to take note of the VIDC20's 16-bit palette here.
* The VIDC20 looks up a 16 bit pixel as follows:
*
* bits 111111
* 5432109876543210
* red ++++++++ (8 bits, 7 to 0)
* green ++++++++ (8 bits, 11 to 4)
* blue ++++++++ (8 bits, 15 to 8)
*
* We use a pixel which looks like:
*
* bits 111111
* 5432109876543210
* red +++++ (5 bits, 4 to 0)
* green +++++ (5 bits, 9 to 5)
* blue +++++ (5 bits, 14 to 10)
*/
Generic video timings
---------------------
Timings used by the frame buffer interface:
+----------+---------------------------------------------+----------+-------+
| | ^ | | |
| | |upper_margin | | |
| | v | | |
+----------###############################################----------+-------+
| # ^ # | |
| # | # | |
| # | # | |
| # | # | |
| left # | # right | hsync |
| margin # | xres # margin | len |
|<-------->#<---------------+--------------------------->#<-------->|<----->|
| # | # | |
| # | # | |
| # | # | |
| # |yres # | |
| # | # | |
| # | # | |
| # | # | |
| # | # | |
| # | # | |
| # | # | |
| # | # | |
| # | # | |
| # v # | |
+----------###############################################----------+-------+
| | ^ | | |
| | |lower_margin | | |
| | v | | |
+----------+---------------------------------------------+----------+-------+
| | ^ | | |
| | |vsync_len | | |
| | v | | |
+----------+---------------------------------------------+----------+-------+
Amiga video timings
-------------------
The Amiga native chipsets uses another timing scheme:
- hsstrt: Start of horizontal synchronization pulse
- hsstop: End of horizontal synchronization pulse
- htotal: Last value on the line (i.e. line length = htotal + 1)
- vsstrt: Start of vertical synchronization pulse
- vsstop: End of vertical synchronization pulse
- vtotal: Last line value (i.e. number of lines = vtotal + 1)
- hcenter: Start of vertical retrace for interlace
You can specify the blanking timings independently. Currently I just set
them equal to the respective synchronization values:
- hbstrt: Start of horizontal blank
- hbstop: End of horizontal blank
- vbstrt: Start of vertical blank
- vbstop: End of vertical blank
Horizontal values are in color clock cycles (280 ns), vertical values are in
scanlines.
(0, 0) is somewhere in the upper-left corner :-)
/*
* Calculate the PCD value from the clock rate (in picoseconds).
* We take account of the PPCR clock setting.
* From PXA Developer's Manual:
*
* PixelClock = LCLK
* -------------
* 2 ( PCD + 1 )
*
* PCD = LCLK
* ------------- - 1
* 2(PixelClock)
*
* Where:
* LCLK = LCD/Memory Clock
* PCD = LCCR3[7:0]
*
* PixelClock here is in Hz while the pixclock argument given is the
* period in picoseconds. Hence PixelClock = 1 / ( pixclock * 10^-12 )
*
* The function get_lclk_frequency_10khz returns LCLK in units of
* 10khz. Calling the result of this function lclk gives us the
* following
*
* PCD = (lclk * 10^4 ) * ( pixclock * 10^-12 )
* -------------------------------------- - 1
* 2
*
* Factoring the 10^4 and 10^-12 out gives 10^-8 == 1 / 100000000 as used below.
*/
* The hardware cursor definition requires 2 bits per pixel. The
* Cursor size reguardless of the visible cursor size is 64 pixels
* by 64 lines. The total memory required to define the cursor is
* 16 bytes / line for 64 lines or 1024 bytes of data. The data
* must be in a contigiuos format. The 2 bit cursor code values are
* as follows:
*
* 00 - pixel colour = CURSOR_CLR_0
* 01 - pixel colour = CURSOR_CLR_1
* 10 - pixel colour = transparent (current display pixel)
* 11 - pixel colour = 1's complement of current display pixel
*
* Cursor Offset 64 pixels Actual Displayed Area
* \_________________________/
* | | | |
* |<--------------->| | |
* | CURS_HORZ_OFFSET| | |
* | |_______| | 64 Lines
* | ^ | |
* | | | |
* | CURS_VERT_OFFSET| |
* | | | |
* |____________________|____| |
*
*
* The Screen position of the top left corner of the displayed
* cursor is specificed by CURS_HORZ_VERT_POSN. Care must be taken
* when the cursor hot spot is not the top left corner and the
* physical cursor position becomes negative. It will be displayed
* if either the horizontal or vertical cursor position is negative
/**
* fb_get_hblank_by_dclk - get horizontal blank time given pixelclock
* @dclk: pixelclock in Hz
* @xres: horizontal resolution in pixels
*
* DESCRIPTION:
*
* xres * duty_cycle
* hblank = ------------------
* 100 - duty_cycle
*
* duty cycle = percent of htotal assigned to inactive display
* duty cycle = C - (M * h_period)
*
* where: h_period = SQRT(100 - C + (0.4 * xres * M)/dclk) + C - 100
* -----------------------------------------------
* 2 * M
* M = 300;
* C = 30;
*/
/*
* We have 4 levels of cache for the dispc settings. First two are in SW and
* the latter two in HW.
*
* set_info()
* v
* +--------------------+
* | user_info |
* +--------------------+
* v
* apply()
* v
* +--------------------+
* | info |
* +--------------------+
* v
* write_regs()
* v
* +--------------------+
* | shadow registers |
* +--------------------+
* v
* VFP or lcd/digit_enable
* v
* +--------------------+
* | registers |
* +--------------------+
*/
/*
* Queue all expired dirty inodes for io, eldest first.
* Before
* newly dirtied b_dirty b_io b_more_io
* =============> gf edc BA
* After
* newly dirtied b_dirty b_io b_more_io
* =============> g fBAedc
* |
* +--> dequeue for IO
*/
/*
* Check key order of two sibling extent buffers.
*
* Return true if something is wrong.
* Return false if everything is fine.
*
* Tree-checker only works inside one tree block, thus the following
* corruption can not be detected by tree-checker:
*
* Leaf @left | Leaf @right
* --------------------------------------------------------------
* | 1 | 2 | 3 | 4 | 5 | f6 | | 7 | 8 |
*
* Key f6 in leaf @left itself is valid, but not valid when the next
* key in leaf @right is 7.
* This can only be checked at tree block merge time.
* And since tree checker has ensured all key order in each tree block
* is correct, we only need to bother the last key of @left and the first
* key of @right.
*/
* Helper function to trace a subtree tree block swap.
*
* The swap will happen in highest tree block, but there may be a lot of
* tree blocks involved.
*
* For example:
* OO = Old tree blocks
* NN = New tree blocks allocated during balance
*
* File tree (257) Reloc tree for 257
* L2 OO NN
* / \ / \
* L1 OO OO (a) OO NN (a)
* / \ / \ / \ / \
* L0 OO OO OO OO OO OO NN NN
* (b) (c) (b) (c)
*
* When calling qgroup_trace_extent_swap(), we will pass:
* @src_eb = OO(a)
* @dst_path = [ nodes[1] = NN(a), nodes[0] = NN(c) ]
* @dst_level = 0
* @root_level = 1
*
* In that case, qgroup_trace_extent_swap() will search from OO(a) to
* reach OO(c), then mark both OO(c) and NN(c) as qgroup dirty.
*
* The main work of qgroup_trace_extent_swap() can be split into 3 parts:
*
* 1) Tree search from @src_eb
* It should acts as a simplified btrfs_search_slot().
* The key for search can be extracted from @dst_path->nodes[dst_level]
* (first key).
*
* 2) Mark the final tree blocks in @src_path and @dst_path qgroup dirty
* NOTE: In above case, OO(a) and NN(a) won't be marked qgroup dirty.
* They should be marked during previous (@dst_level = 1) iteration.
*
* 3) Mark file extents in leaves dirty
* We don't have good way to pick out new file extents only.
* So we still follow the old method by scanning all file extents in
* the leave.
* The payload starts at offset SVE_PT_SVE_OFFSET, and is of size
* SVE_PT_SVE_SIZE(vq, flags).
*
* Additional macros describe the contents and layout of the payload.
* For each, SVE_PT_SVE_x_OFFSET(args) is the start offset relative to
* the start of struct user_sve_header, and SVE_PT_SVE_x_SIZE(args) is
* the size in bytes:
*
* x type description
* - ---- -----------
* ZREGS \
* ZREG |
* PREGS | refer to <asm/sigcontext.h>
* PREG |
* FFR /
*
* FPSR uint32_t FPSR
* FPCR uint32_t FPCR
*
* Additional data might be appended in the future.
/*
* Transaction states and transitions
*
* No running transaction (fs tree blocks are not modified)
* |
* | To next stage:
* | Call start_transaction() variants. Except btrfs_join_transaction_nostart().
* V
* Transaction N [[TRANS_STATE_RUNNING]]
* |
* | New trans handles can be attached to transaction N by calling all
* | start_transaction() variants.
* |
* | To next stage:
* | Call btrfs_commit_transaction() on any trans handle attached to
* | transaction N
* V
* Transaction N [[TRANS_STATE_COMMIT_START]]
* |
* | Will wait for previous running transaction to completely finish if there
* | is one
* |
* | Then one of the following happes:
* | - Wait for all other trans handle holders to release.
* | The btrfs_commit_transaction() caller will do the commit work.
* | - Wait for current transaction to be committed by others.
* | Other btrfs_commit_transaction() caller will do the commit work.
* |
* | At this stage, only btrfs_join_transaction*() variants can attach
* | to this running transaction.
* | All other variants will wait for current one to finish and attach to
* | transaction N+1.
* |
* | To next stage:
* | Caller is chosen to commit transaction N, and all other trans handle
* | haven been released.
* V
* Transaction N [[TRANS_STATE_COMMIT_DOING]]
* |
* | The heavy lifting transaction work is started.
* | From running delayed refs (modifying extent tree) to creating pending
* | snapshots, running qgroups.
* | In short, modify supporting trees to reflect modifications of subvolume
* | trees.
* |
* | At this stage, all start_transaction() calls will wait for this
* | transaction to finish and attach to transaction N+1.
* |
* | To next stage:
* | Until all supporting trees are updated.
* V
* Transaction N [[TRANS_STATE_UNBLOCKED]]
* | Transaction N+1
* | All needed trees are modified, thus we only [[TRANS_STATE_RUNNING]]
* | need to write them back to disk and update |
* | super blocks. |
* | |
* | At this stage, new transaction is allowed to |
* | start. |
* | All new start_transaction() calls will be |
* | attached to transid N+1. |
* | |
* | To next stage: |
* | Until all tree blocks are super blocks are |
* | written to block devices |
* V |
* Transaction N [[TRANS_STATE_COMPLETED]] V
* All tree blocks and super blocks are written. Transaction N+1
* This transaction is finished and all its [[TRANS_STATE_COMMIT_START]]
* data structures will be cleaned up. | Life goes on
*/
/*
* Test scenario:
*
* Suppose that no extent map has been loaded into memory yet, there is a file
* extent [0, 16K), followed by another file extent [16K, 20K), two dio reads
* are entering btrfs_get_extent() concurrently, t1 is reading [8K, 16K), t2 is
* reading [0, 8K)
*
* t1 t2
* btrfs_get_extent() btrfs_get_extent()
* -> lookup_extent_mapping() ->lookup_extent_mapping()
* -> add_extent_mapping(0, 16K)
* -> return em
* ->add_extent_mapping(0, 16K)
* -> #handle -EEXIST
*/
* Termination:
*
* The midcomms layer does a 4 way handshake for termination on DLM protocol
* like TCP supports it with half-closed socket support. SCTP doesn't support
* half-closed socket, so we do it on DLM layer. Also socket shutdown() can be
* interrupted by .e.g. tcp reset itself. Additional there exists the othercon
* paradigm in lowcomms which cannot be easily without breaking backwards
* compatibility. A node cannot send anything to another node when a DLM_FIN
* message was send. There exists additional logic to print a warning if
* DLM wants to do it. There exists a state handling like RFC 793 but reduced
* to termination only. The event "member removal event" describes the cluster
* manager removed the node from internal lists, at this point DLM does not
* send any message to the other node. There exists two cases:
*
* 1. The cluster member was removed and we received a FIN
* OR
* 2. We received a FIN but the member was not removed yet
*
* One of these cases will do the CLOSE_WAIT to LAST_ACK change.
*
*
* +---------+
* | CLOSED |
* +---------+
* | add member/receive RCOM version
* | detection msg
* V
* +---------+
* | ESTAB |
* +---------+
* CLOSE | | rcv FIN
* ------- | | -------
* +---------+ snd FIN / \ snd ACK +---------+
* | FIN |<----------------- ------------------>| CLOSE |
* | WAIT-1 |------------------ | WAIT |
* +---------+ rcv FIN \ +---------+
* | rcv ACK of FIN ------- | CLOSE | member
* | -------------- snd ACK | ------- | removal
* V x V snd FIN V event
* +---------+ +---------+ +---------+
* |FINWAIT-2| | CLOSING | | LAST-ACK|
* +---------+ +---------+ +---------+
* | rcv ACK of FIN | rcv ACK of FIN |
* | rcv FIN -------------- | -------------- |
* | ------- x V x V
* \ snd ACK +---------+ +---------+
* ------------------------>| CLOSED | | CLOSED |
* +---------+ +---------+
*
* NOTE: any state can interrupted by midcomms_close() and state will be
* switched to CLOSED in case of fencing. There exists also some timeout
* handling when we receive the version detection RCOM messages which is
* made by observation.
/*
* inline xattrs (n == i_xattr_icount):
* erofs_xattr_ibody_header(1) + (n - 1) * 4 bytes
* 12 bytes / \
* / \
* /-----------------------\
* | erofs_xattr_entries+ |
* +-----------------------+
* inline xattrs must starts in erofs_xattr_ibody_header,
* for read-only fs, no need to introduce h_refcount
*/
* Atomicity of commits
* --------------------
* In order to guarantee atomicity during the commit operation, fast commit
* uses "EXT4_FC_TAG_TAIL" tag that marks a fast commit as complete. Tail
* tag contains CRC of the contents and TID of the transaction after which
* this fast commit should be applied. Recovery code replays fast commit
* logs only if there's at least 1 valid tail present. For every fast commit
* operation, there is 1 tail. This means, we may end up with multiple tails
* in the fast commit space. Here's an example:
*
* - Create a new file A and remove existing file B
* - fsync()
* - Append contents to file A
* - Truncate file A
* - fsync()
*
* The fast commit space at the end of above operations would look like this:
* [HEAD] [CREAT A] [UNLINK B] [TAIL] [ADD_RANGE A] [DEL_RANGE A] [TAIL]
* |<--- Fast Commit 1 --->|<--- Fast Commit 2 ---->|
*
* Replay code should thus check for all the valid tails in the FC area.
*
* Fast Commit Replay Idempotence
* ------------------------------
*
* Fast commits tags are idempotent in nature provided the recovery code follows
* certain rules. The guiding principle that the commit path follows while
* committing is that it stores the result of a particular operation instead of
* storing the procedure.
*
* Let's consider this rename operation: 'mv /a /b'. Let's assume dirent '/a'
* was associated with inode 10. During fast commit, instead of storing this
* operation as a procedure "rename a to b", we store the resulting file system
* state as a "series" of outcomes:
*
* - Link dirent b to inode 10
* - Unlink dirent a
* - Inode <10> with valid refcount
*
* Now when recovery code runs, it needs "enforce" this state on the file
* system. This is what guarantees idempotence of fast commit replay.
*
* Let's take an example of a procedure that is not idempotent and see how fast
* commits make it idempotent. Consider following sequence of operations:
*
* rm A; mv B A; read A
* (x) (y) (z)
*
* (x), (y) and (z) are the points at which we can crash. If we store this
* sequence of operations as is then the replay is not idempotent. Let's say
* while in replay, we crash at (z). During the second replay, file A (which was
* actually created as a result of "mv B A" operation) would get deleted. Thus,
* file named A would be absent when we try to read A. So, this sequence of
* operations is not idempotent. However, as mentioned above, instead of storing
* the procedure fast commits store the outcome of each procedure. Thus the fast
* commit log for above procedure would be as follows:
*
* (Let's assume dirent A was linked to inode 10 and dirent B was linked to
* inode 11 before the replay)
*
* [Unlink A] [Link A to inode 11] [Unlink B] [Inode 11]
* (w) (x) (y) (z)
*
* If we crash at (z), we will have file A linked to inode 11. During the second
* replay, we will remove file A (inode 11). But we will create it back and make
* it point to inode 11. We won't find B, so we'll just skip that step. At this
* point, the refcount for inode 11 is not reliable, but that gets fixed by the
* replay of last inode 11 tag. Crashes at points (w), (x) and (y) get handled
* similarly. Thus, by converting a non-idempotent procedure into a series of
* idempotent outcomes, fast commits ensured idempotence during the replay.
/*
* f2fs assigns the following node offsets described as (num).
* N = NIDS_PER_BLOCK
*
* Inode block (0)
* |- direct node (1)
* |- direct node (2)
* |- indirect node (3)
* | `- direct node (4 => 4 + N - 1)
* |- indirect node (4 + N)
* | `- direct node (5 + N => 5 + 2N - 1)
* `- double indirect node (5 + 2N)
* `- indirect node (6 + 2N)
* `- direct node
* ......
* `- indirect node ((6 + 2N) + x(N + 1))
* `- direct node
* ......
* `- indirect node ((6 + 2N) + (N - 1)(N + 1))
* `- direct node
*/
* each vnode/inode of a fileset is linked to its vfs (to facilitate
* per fileset inode operations, e.g., unmount of a fileset, etc.);
* each inode points to the mount inode (to facilitate access to
* per aggregate information, e.g., block size, etc.) as well as
* its file set inode.
*
* aggregate
* ipmnt
* mntvfs -> fileset ipimap+ -> aggregate ipbmap -> aggregate ipaimap;
* fileset vfs -> vp(1) <-> ... <-> vp(n) <->vproot;
/*
* is l2 fully contained in l1?
* start1 end1
* [----------------------------------)
* start2 end2
* [----------------)
*/
/*
* Are 2 ranges intersecting?
* start1 end1
* [----------------------------------)
* start2 end2
* [----------------)
*/
/*
* Index the hyp_vmemmap to find a potential buddy page, but make no assumption
* about its current state.
*
* Example buddy-tree for a 4-pages physically contiguous pool:
*
* o : Page 3
* /
* o-o : Page 2
* /
* / o : Page 1
* / /
* o---o-o : Page 0
* Order 2 1 0
*
* Example of requests on this pool:
* __find_buddy_nocheck(pool, page 0, order 0) => page 1
* __find_buddy_nocheck(pool, page 0, order 1) => page 2
* __find_buddy_nocheck(pool, page 1, order 0) => page 0
* __find_buddy_nocheck(pool, page 2, order 0) => page 3
*/
/*
* UTF8 valid ranges.
*
* The UTF-8 encoding spreads the bits of a 32bit word over several
* bytes. This table gives the ranges that can be held and how they'd
* be represented.
*
* 0x00000000 0x0000007F: 0xxxxxxx
* 0x00000000 0x000007FF: 110xxxxx 10xxxxxx
* 0x00000000 0x0000FFFF: 1110xxxx 10xxxxxx 10xxxxxx
* 0x00000000 0x001FFFFF: 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx
* 0x00000000 0x03FFFFFF: 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
* 0x00000000 0x7FFFFFFF: 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
*
* There is an additional requirement on UTF-8, in that only the
* shortest representation of a 32bit value is to be used. A decoder
* must not decode sequences that do not satisfy this requirement.
* Thus the allowed ranges have a lower bound.
*
* 0x00000000 0x0000007F: 0xxxxxxx
* 0x00000080 0x000007FF: 110xxxxx 10xxxxxx
* 0x00000800 0x0000FFFF: 1110xxxx 10xxxxxx 10xxxxxx
* 0x00010000 0x001FFFFF: 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx
* 0x00200000 0x03FFFFFF: 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
* 0x04000000 0x7FFFFFFF: 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx
*
* Actual unicode characters are limited to the range 0x0 - 0x10FFFF,
* 17 planes of 65536 values. This limits the sequences actually seen
* even more, to just the following.
*
* 0 - 0x7f: 0 0x7f
* 0x80 - 0x7ff: 0xc2 0x80 0xdf 0xbf
* 0x800 - 0xffff: 0xe0 0xa0 0x80 0xef 0xbf 0xbf
* 0x10000 - 0x10ffff: 0xf0 0x90 0x80 0x80 0xf4 0x8f 0xbf 0xbf
*
* Even within those ranges not all values are allowed: the surrogates
* 0xd800 - 0xdfff should never be seen.
*
* Note that the longest sequence seen with valid usage is 4 bytes,
* the same a single UTF-32 character. This makes the UTF-8
* representation of Unicode strictly smaller than UTF-32.
*
* The shortest sequence requirement was introduced by:
* Corrigendum #1: UTF-8 Shortest Form
* It can be found here:
* http://www.unicode.org/versions/corrigendum1.html
*
*/
/*
* Below is a state machine diagram for attr remove operations. The XFS_DAS_*
* states indicate places where the function would return -EAGAIN, and then
* immediately resume from after being called by the calling function. States
* marked as a "subroutine state" indicate that they belong to a subroutine, and
* so the calling function needs to pass them back to that subroutine to allow
* it to finish where it left off. But they otherwise do not have a role in the
* calling function other than just passing through.
*
* xfs_attr_remove_iter()
* │
* v
* have attr to remove? ──n──> done
* │
* y
* │
* v
* are we short form? ──y──> xfs_attr_shortform_remove ──> done
* │
* n
* │
* V
* are we leaf form? ──y──> xfs_attr_leaf_removename ──> done
* │
* n
* │
* V
* ┌── need to setup state?
* │ │
* n y
* │ │
* │ v
* │ find attr and get state
* │ attr has remote blks? ──n─┐
* │ │ v
* │ │ find and invalidate
* │ y the remote blocks.
* │ │ mark attr incomplete
* │ ├────────────────┘
* └──────────┤
* │
* v
* Have remote blks to remove? ───y─────┐
* │ ^ remove the blks
* │ │ │
* │ │ v
* │ XFS_DAS_RMTBLK <─n── done?
* │ re-enter with │
* │ one less blk to y
* │ remove │
* │ V
* │ refill the state
* n │
* │ v
* │ XFS_DAS_RM_NAME
* │ │
* ├─────────────────────────┘
* │
* v
* remove leaf and
* update hash with
* xfs_attr_node_remove_cleanup
* │
* v
* need to
* shrink tree? ─n─┐
* │ │
* y │
* │ │
* v │
* join leaf │
* │ │
* v │
* XFS_DAS_RM_SHRINK │
* │ │
* v │
* do the shrink │
* │ │
* v │
* free state <──┘
* │
* v
* done
*
*
* Below is a state machine diagram for attr set operations.
*
* It seems the challenge with understanding this system comes from trying to
* absorb the state machine all at once, when really one should only be looking
* at it with in the context of a single function. Once a state sensitive
* function is called, the idea is that it "takes ownership" of the
* state machine. It isn't concerned with the states that may have belonged to
* it's calling parent. Only the states relevant to itself or any other
* subroutines there in. Once a calling function hands off the state machine to
* a subroutine, it needs to respect the simple rule that it doesn't "own" the
* state machine anymore, and it's the responsibility of that calling function
* to propagate the -EAGAIN back up the call stack. Upon reentry, it is
* committed to re-calling that subroutine until it returns something other than
* -EAGAIN. Once that subroutine signals completion (by returning anything other
* than -EAGAIN), the calling function can resume using the state machine.
*
* xfs_attr_set_iter()
* │
* v
* ┌─y─ has an attr fork?
* │ |
* │ n
* │ |
* │ V
* │ add a fork
* │ │
* └──────────┤
* │
* V
* ┌─── is shortform?
* │ │
* │ y
* │ │
* │ V
* │ xfs_attr_set_fmt
* │ |
* │ V
* │ xfs_attr_try_sf_addname
* │ │
* │ V
* │ had enough ──y──> done
* │ space?
* n │
* │ n
* │ │
* │ V
* │ transform to leaf
* │ │
* │ V
* │ hold the leaf buffer
* │ │
* │ V
* │ return -EAGAIN
* │ Re-enter in
* │ leaf form
* │
* └─> release leaf buffer
* if needed
* │
* V
* ┌───n── fork has
* │ only 1 blk?
* │ │
* │ y
* │ │
* │ v
* │ xfs_attr_leaf_try_add()
* │ │
* │ v
* │ had enough ──────────────y─────────────┐
* │ space? │
* │ │ │
* │ n │
* │ │ │
* │ v │
* │ return -EAGAIN │
* │ re-enter in │
* │ node form │
* │ │ │
* └──────────┤ │
* │ │
* V │
* xfs_attr_node_addname_find_attr │
* determines if this │
* is create or rename │
* find space to store attr │
* │ │
* v │
* xfs_attr_node_addname │
* │ │
* v │
* fits in a node leaf? ────n─────┐ │
* │ ^ v │
* │ │ single leaf node? │
* │ │ │ │ │
* y │ y n │
* │ │ │ │ │
* v │ v v │
* update │ grow the leaf split if │
* hashvals └── return -EAGAIN needed │
* │ retry leaf add │ │
* │ on reentry │ │
* ├────────────────────────────┘ │
* │ │
* v │
* need to alloc │
* ┌─y── or flip flag? │
* │ │ │
* │ n │
* │ │ │
* │ v │
* │ done │
* │ │
* │ │
* │ XFS_DAS_FOUND_LBLK <────────────────┘
* │ │
* │ V
* │ xfs_attr_leaf_addname()
* │ │
* │ v
* │ ┌──first time through?
* │ │ │
* │ │ y
* │ │ │
* │ n v
* │ │ if we have rmt blks
* │ │ find space for them
* │ │ │
* │ └──────────┤
* │ │
* │ v
* │ still have
* │ ┌─n─ blks to alloc? <──┐
* │ │ │ │
* │ │ y │
* │ │ │ │
* │ │ v │
* │ │ alloc one blk │
* │ │ return -EAGAIN ──┘
* │ │ re-enter with one
* │ │ less blk to alloc
* │ │
* │ │
* │ └───> set the rmt
* │ value
* │ │
* │ v
* │ was this
* │ a rename? ──n─┐
* │ │ │
* │ y │
* │ │ │
* │ v │
* │ flip incomplete │
* │ flag │
* │ │ │
* │ v │
* │ XFS_DAS_FLIP_LFLAG │
* │ │ │
* │ v │
* │ need to remove │
* │ old bks? ──n──┤
* │ │ │
* │ y │
* │ │ │
* │ V │
* │ remove │
* │ ┌───> old blks │
* │ │ │ │
* │ XFS_DAS_RM_LBLK │ │
* │ ^ │ │
* │ │ v │
* │ └──y── more to │
* │ remove? │
* │ │ │
* │ n │
* │ │ │
* │ v │
* │ XFS_DAS_RD_LEAF │
* │ │ │
* │ v │
* │ remove leaf │
* │ │ │
* │ v │
* │ shrink to sf │
* │ if needed │
* │ │ │
* │ v │
* │ done <──────┘
* │
* └──────> XFS_DAS_FOUND_NBLK
* │
* v
* ┌─────n── need to
* │ alloc blks?
* │ │
* │ y
* │ │
* │ v
* │ find space
* │ │
* │ v
* │ ┌─>XFS_DAS_ALLOC_NODE
* │ │ │
* │ │ v
* │ │ alloc blk
* │ │ │
* │ │ v
* │ └──y── need to alloc
* │ more blocks?
* │ │
* │ n
* │ │
* │ v
* │ set the rmt value
* │ │
* │ v
* │ was this
* └────────> a rename? ──n─┐
* │ │
* y │
* │ │
* v │
* flip incomplete │
* flag │
* │ │
* v │
* XFS_DAS_FLIP_NFLAG │
* │ │
* v │
* need to │
* remove blks? ─n──┤
* │ │
* y │
* │ │
* v │
* remove │
* ┌────────> old blks │
* │ │ │
* XFS_DAS_RM_NBLK │ │
* ^ │ │
* │ v │
* └──────y── more to │
* remove │
* │ │
* n │
* │ │
* v │
* XFS_DAS_CLR_FLAG │
* │ │
* v │
* clear flags │
* │ │
* ├──────────┘
* │
* v
* done
*/
/*
* XFS btree block layout and addressing:
*
* There are two types of blocks in the btree: leaf and non-leaf blocks.
*
* The leaf record start with a header then followed by records containing
* the values. A non-leaf block also starts with the same header, and
* then first contains lookup keys followed by an equal number of pointers
* to the btree blocks at the previous level.
*
* +--------+-------+-------+-------+-------+-------+-------+
* Leaf: | header | rec 1 | rec 2 | rec 3 | rec 4 | rec 5 | rec N |
* +--------+-------+-------+-------+-------+-------+-------+
*
* +--------+-------+-------+-------+-------+-------+-------+
* Non-Leaf: | header | key 1 | key 2 | key N | ptr 1 | ptr 2 | ptr N |
* +--------+-------+-------+-------+-------+-------+-------+
*
* The header is called struct xfs_btree_block for reasons better left unknown
* and comes in different versions for short (32bit) and long (64bit) block
* pointers. The record and key structures are defined by the btree instances
* and opaque to the btree core. The block pointers are simple disk endian
* integers, available in a short (32bit) and long (64bit) variant.
*
* The helpers below calculate the offset of a given record, key or pointer
* into a btree block (xfs_btree_*_offset) or return a pointer to the given
* record, key or pointer (xfs_btree_*_addr). Note that all addressing
* inside the btree block is done using indices starting at one, not zero!
*
* If XFS_BTREE_OVERLAPPING is set, then this btree supports keys containing
* overlapping intervals. In such a tree, records are still sorted lowest to
* highest and indexed by the smallest key value that refers to the record.
* However, nodes are different: each pointer has two associated keys -- one
* indexing the lowest key available in the block(s) below (the same behavior
* as the key in a regular btree) and another indexing the highest key
* available in the block(s) below. Because records are /not/ sorted by the
* highest key, all leaf block updates require us to compute the highest key
* that matches any record in the leaf and to recursively update the high keys
* in the nodes going further up in the tree, if necessary. Nodes look like
* this:
*
* +--------+-----+-----+-----+-----+-----+-------+-------+-----+
* Non-Leaf: | header | lo1 | hi1 | lo2 | hi2 | ... | ptr 1 | ptr 2 | ... |
* +--------+-----+-----+-----+-----+-----+-------+-------+-----+
*
* To perform an interval query on an overlapped tree, perform the usual
* depth-first search and use the low and high keys to decide if we can skip
* that particular node. If a leaf node is reached, return the records that
* intersect the interval. Note that an interval query may return numerous
* entries. For a non-overlapped tree, simply search for the record associated
* with the lowest key and iterate forward until a non-matching record is
* found. Section 14.3 ("Interval Trees") of _Introduction to Algorithms_ by
* Cormen, Leiserson, Rivest, and Stein (2nd or 3rd ed. only) discuss this in
* more detail.
*
* Why do we care about overlapping intervals? Let's say you have a bunch of
* reverse mapping records on a reflink filesystem:
*
* 1: +- file A startblock B offset C length D -----------+
* 2: +- file E startblock F offset G length H --------------+
* 3: +- file I startblock F offset J length K --+
* 4: +- file L... --+
*
* Now say we want to map block (B+D) into file A at offset (C+D). Ideally,
* we'd simply increment the length of record 1. But how do we find the record
* that ends at (B+D-1) (i.e. record 1)? A LE lookup of (B+D-1) would return
* record 3 because the keys are ordered first by startblock. An interval
* query would return records 1 and 2 because they both overlap (B+D-1), and
* from that we can pick out record 1 as the appropriate left neighbor.
*
* In the non-overlapped case you can do a LE lookup and decrement the cursor
* because a record's interval must end before the next record.
*/
/*
* Adjusting the Reference Count
*
* As stated elsewhere, the reference count btree (refcbt) stores
* >1 reference counts for extents of physical blocks. In this
* operation, we're either raising or lowering the reference count of
* some subrange stored in the tree:
*
* <------ adjustment range ------>
* ----+ +---+-----+ +--+--------+---------
* 2 | | 3 | 4 | |17| 55 | 10
* ----+ +---+-----+ +--+--------+---------
* X axis is physical blocks number;
* reference counts are the numbers inside the rectangles
*
* The first thing we need to do is to ensure that there are no
* refcount extents crossing either boundary of the range to be
* adjusted. For any extent that does cross a boundary, split it into
* two extents so that we can increment the refcount of one of the
* pieces later:
*
* <------ adjustment range ------>
* ----+ +---+-----+ +--+--------+----+----
* 2 | | 3 | 2 | |17| 55 | 10 | 10
* ----+ +---+-----+ +--+--------+----+----
*
* For this next step, let's assume that all the physical blocks in
* the adjustment range are mapped to a file and are therefore in use
* at least once. Therefore, we can infer that any gap in the
* refcount tree within the adjustment range represents a physical
* extent with refcount == 1:
*
* <------ adjustment range ------>
* ----+---+---+-----+-+--+--------+----+----
* 2 |"1"| 3 | 2 |1|17| 55 | 10 | 10
* ----+---+---+-----+-+--+--------+----+----
* ^
*
* For each extent that falls within the interval range, figure out
* which extent is to the left or the right of that extent. Now we
* have a left, current, and right extent. If the new reference count
* of the center extent enables us to merge left, center, and right
* into one record covering all three, do so. If the center extent is
* at the left end of the range, abuts the left extent, and its new
* reference count matches the left extent's record, then merge them.
* If the center extent is at the right end of the range, abuts the
* right extent, and the reference counts match, merge those. In the
* example, we can left merge (assuming an increment operation):
*
* <------ adjustment range ------>
* --------+---+-----+-+--+--------+----+----
* 2 | 3 | 2 |1|17| 55 | 10 | 10
* --------+---+-----+-+--+--------+----+----
* ^
*
* For all other extents within the range, adjust the reference count
* or delete it if the refcount falls below 2. If we were
* incrementing, the end result looks like this:
*
* <------ adjustment range ------>
* --------+---+-----+-+--+--------+----+----
* 2 | 4 | 3 |2|18| 56 | 11 | 10
* --------+---+-----+-+--+--------+----+----
*
* The result of a decrement operation looks as such:
*
* <------ adjustment range ------>
* ----+ +---+ +--+--------+----+----
* 2 | | 2 | |16| 54 | 9 | 10
* ----+ +---+ +--+--------+----+----
* DDDD 111111DD
*
* The blocks marked "D" are freed; the blocks marked "1" are only
* referenced once and therefore the record is removed from the
* refcount btree.
*/
/**
* struct drm_crtc_commit - track modeset commits on a CRTC
*
* This structure is used to track pending modeset changes and atomic commit on
* a per-CRTC basis. Since updating the list should never block, this structure
* is reference counted to allow waiters to safely wait on an event to complete,
* without holding any locks.
*
* It has 3 different events in total to allow a fine-grained synchronization
* between outstanding updates::
*
* atomic commit thread hardware
*
* write new state into hardware ----> ...
* signal hw_done
* switch to new state on next
* ... v/hblank
*
* wait for buffers to show up ...
*
* ... send completion irq
* irq handler signals flip_done
* cleanup old buffers
*
* signal cleanup_done
*
* wait for flip_done <----
* clean up atomic state
*
* The important bit to know is that &cleanup_done is the terminal event, but the
* ordering between &flip_done and &hw_done is entirely up to the specific driver
* and modeset state change.
*
* For an implementation of how to use this look at
* drm_atomic_helper_setup_commit() from the atomic helper library.
*
* See also drm_crtc_commit_wait().
*/
* This is the kernel API display mode information structure. For the
* user-space version see struct drm_mode_modeinfo.
*
* The horizontal and vertical timings are defined per the following diagram.
*
* ::
*
*
* Active Front Sync Back
* Region Porch Porch
* <-----------------------><----------------><-------------><-------------->
* //////////////////////|
* ////////////////////// |
* ////////////////////// |.................. ................
* _______________
* <----- [hv]display ----->
* <------------- [hv]sync_start ------------>
* <--------------------- [hv]sync_end --------------------->
* <-------------------------------- [hv]total ----------------------------->*
*
* This structure contains two copies of timings. First are the plain timings,
* which specify the logical mode, as it would be for a progressive 1:1 scanout
* at the refresh rate userspace can observe through vblank timestamps. Then
* there's the hardware timings, which are corrected for interlacing,
* double-clocking and similar things. They are provided as a convenience, and
* can be appropriately computed using drm_mode_set_crtcinfo().
/*
* GPIOMUX bits:
* | 31 - 24 | 23 - 16 | 15 - 8 | 7 | 6 | 5 - 0 |
* | dout | doen | din | dout rev | doen rev | gpio nr |
*
* dout: output signal
* doen: output enable signal
* din: optional input signal, 0xff = none
* dout rev: output signal reverse bit
* doen rev: output enable signal reverse bit
* gpio nr: gpio number, 0 - 63
*/
/*
* Example: vc_data of a console that was scrolled 3 lines down.
*
* Console buffer
* vc_screenbuf ---------> +----------------------+-.
* | initializing W | \
* | initializing X | |
* | initializing Y | > scroll-back area
* | initializing Z | |
* | | /
* vc_visible_origin ---> ^+----------------------+-:
* (changes by scroll) || Welcome to linux | \
* || | |
* vc_rows --->< | login: root | | visible on console
* || password: | > (vc_screenbuf_size is
* vc_origin -----------> || | | vc_size_row * vc_rows)
* (start when no scroll) || Last login: 12:28 | /
* v+----------------------+-:
* | Have a lot of fun... | \
* vc_pos -----------------|--------v | > scroll-front area
* | ~ # cat_ | /
* vc_scr_end -----------> +----------------------+-:
* (vc_origin + | | \ EMPTY, to be filled by
* vc_screenbuf_size) | | / vc_video_erase_char
* +----------------------+-'
* <---- 2 * vc_cols ----->
* <---- vc_size_row ----->
*
* Note that every character in the console buffer is accompanied with an
* attribute in the buffer right after the character. This is not depicted
* in the figure.
*/
/*
* Types for GPADL, decides is how GPADL header is created.
*
* It doesn't make much difference between BUFFER and RING if PAGE_SIZE is the
* same as HV_HYP_PAGE_SIZE.
*
* If PAGE_SIZE is bigger than HV_HYP_PAGE_SIZE, the headers of ring buffers
* will be of PAGE_SIZE, however, only the first HV_HYP_PAGE will be put
* into gpadl, therefore the number for HV_HYP_PAGE and the indexes of each
* HV_HYP_PAGE will be different between different types of GPADL, for example
* if PAGE_SIZE is 64K:
*
* BUFFER:
*
* gva: |-- 64k --|-- 64k --| ... |
* gpa: | 4k | 4k | ... | 4k | 4k | 4k | ... | 4k |
* index: 0 1 2 15 16 17 18 .. 31 32 ...
* | | ... | | | ... | ...
* v V V V V V
* gpadl: | 4k | 4k | ... | 4k | 4k | 4k | ... | 4k | ... |
* index: 0 1 2 ... 15 16 17 18 .. 31 32 ...
*
* RING:
*
* | header | data | header | data |
* gva: |-- 64k --|-- 64k --| ... |-- 64k --|-- 64k --| ... |
* gpa: | 4k | .. | 4k | 4k | ... | 4k | ... | 4k | .. | 4k | .. | ... |
* index: 0 1 16 17 18 31 ... n n+1 n+16 ... 2n
* | / / / | / /
* | / / / | / /
* | / / ... / ... | / ... /
* | / / / | / /
* | / / / | / /
* V V V V V V v
* gpadl: | 4k | 4k | ... | ... | 4k | 4k | ... |
* index: 0 1 2 ... 16 ... n-15 n-14 n-13 ... 2n-30
*/
/*
* Combine the right initial value (type) with the right branch order
* to generate the desired result.
*
*
* type\branch| likely (1) | unlikely (0)
* -----------+-----------------------+------------------
* | |
* true (1) | ... | ...
* | NOP | JMP L
* | <br-stmts> | 1: ...
* | L: ... |
* | |
* | | L: <br-stmts>
* | | jmp 1b
* | |
* -----------+-----------------------+------------------
* | |
* false (0) | ... | ...
* | JMP L | NOP
* | <br-stmts> | 1: ...
* | L: ... |
* | |
* | | L: <br-stmts>
* | | jmp 1b
* | |
* -----------+-----------------------+------------------
*
* The initial value is encoded in the LSB of static_key::entries,
* type: 0 = false, 1 = true.
*
* The branch type is encoded in the LSB of jump_entry::key,
* branch: 0 = unlikely, 1 = likely.
*
* This gives the following logic table:
*
* enabled type branch instuction
* -----------------------------+-----------
* 0 0 0 | NOP
* 0 0 1 | JMP
* 0 1 0 | NOP
* 0 1 1 | JMP
*
* 1 0 0 | JMP
* 1 0 1 | NOP
* 1 1 0 | JMP
* 1 1 1 | NOP
*
* Which gives the following functions:
*
* dynamic: instruction = enabled ^ branch
* static: instruction = type ^ branch
*
* See jump_label_type() / jump_label_init_type().
*/
* This list is really a list of lists:
*
* - The tier 1 list is the prio_list, different priority nodes.
*
* - The tier 2 list is the node_list, serialized nodes.
*
* Simple ASCII art explanation:
*
* pl:prio_list (only for plist_node)
* nl:node_list
* HEAD| NODE(S)
* |
* ||------------------------------------|
* ||->|pl|<->|pl|<--------------->|pl|<-|
* | |10| |21| |21| |21| |40| (prio)
* | | | | | | | | | | |
* | | | | | | | | | | |
* |->|nl|<->|nl|<->|nl|<->|nl|<->|nl|<->|nl|<-|
* |-------------------------------------------|
*
* The nodes on the prio_list list are sorted by priority to simplify
* the insertion of new nodes. There are no nodes with duplicate
* priorites on the list.
*
* The nodes on the node_list are ordered by priority and can contain
* entries which have the same priority. Those entries are ordered
* FIFO
*
* Addition means: look for the prio_list node in the prio_list
* for the priority of the node and insert it before the node_list
* entry of the next prio_list node. If it is the first node of
* that priority, add it to the prio_list in the right position and
* insert it into the serialized node_list list
* Ordinary CC/CV charging will stop charging when the charge current goes
* below charge_term_current_ua, and then restart it (if the device is still
* plugged into the charger) at charge_restart_voltage_uv. This happens in most
* consumer products because the power usage while connected to a charger is
* not zero, and devices are not manufactured to draw power directly from the
* charger: instead they will at all times dissipate the battery a little, like
* the power used in standby mode. This will over time give a charge graph
* such as this:
*
* Energy
* ^ ... ... ... ... ... ... ...
* | . . . . . . . . . . . . .
* | .. . .. . .. . .. . .. . .. . ..
* |. .. .. .. .. .. ..
* +-------------------------------------------------------------------> t
*
* Practically this means that the Li-ions are wandering back and forth in the
* battery and this causes degeneration of the battery anode and cathode.
* To prolong the life of the battery, maintenance charging is applied after
* reaching charge_term_current_ua to hold up the charge in the battery while
* consuming power, thus lowering the wear on the battery:
*
* Energy
* ^ .......................................
* | . ......................
* | ..
* |.
* +-------------------------------------------------------------------> t
*
* Maintenance charging uses the voltages from this table: a table of settings
* is traversed using a slightly lower current and voltage than what is used for
* CC/CV charging. The maintenance charging will for safety reasons not go on
* indefinately: we lower the current and voltage with successive maintenance
* settings, then disable charging completely after we reach the last one,
* and after that we do not restart charging until we reach
* charge_restart_voltage_uv (see struct power_supply_battery_info) and restart
* ordinary CC/CV charging from there.
/**
* hlists_swap_heads_rcu - swap the lists the hlist heads point to
* @left: The hlist head on the left
* @right: The hlist head on the right
*
* The lists start out as [@left ][node1 ... ] and
* [@right ][node2 ... ]
* The lists end up as [@left ][node2 ... ]
* [@right ][node1 ... ]
*/
/*
* ==NOCB Offloading state machine==
*
*
* ----------------------------------------------------------------------------
* | SEGCBLIST_RCU_CORE |
* | |
* | Callbacks processed by rcu_core() from softirqs or local |
* | rcuc kthread, without holding nocb_lock. |
* ----------------------------------------------------------------------------
* |
* v
* ----------------------------------------------------------------------------
* | SEGCBLIST_RCU_CORE | SEGCBLIST_LOCKING | SEGCBLIST_OFFLOADED |
* | |
* | Callbacks processed by rcu_core() from softirqs or local |
* | rcuc kthread, while holding nocb_lock. Waking up CB and GP kthreads, |
* | allowing nocb_timer to be armed. |
* ----------------------------------------------------------------------------
* |
* v
* -----------------------------------
* | |
* v v
* --------------------------------------- ----------------------------------|
* | SEGCBLIST_RCU_CORE | | | SEGCBLIST_RCU_CORE | |
* | SEGCBLIST_LOCKING | | | SEGCBLIST_LOCKING | |
* | SEGCBLIST_OFFLOADED | | | SEGCBLIST_OFFLOADED | |
* | SEGCBLIST_KTHREAD_CB | | SEGCBLIST_KTHREAD_GP |
* | | | |
* | | | |
* | CB kthread woke up and | | GP kthread woke up and |
* | acknowledged SEGCBLIST_OFFLOADED. | | acknowledged SEGCBLIST_OFFLOADED|
* | Processes callbacks concurrently | | |
* | with rcu_core(), holding | | |
* | nocb_lock. | | |
* --------------------------------------- -----------------------------------
* | |
* -----------------------------------
* |
* v
* |--------------------------------------------------------------------------|
* | SEGCBLIST_LOCKING | |
* | SEGCBLIST_OFFLOADED | |
* | SEGCBLIST_KTHREAD_GP | |
* | SEGCBLIST_KTHREAD_CB |
* | |
* | Kthreads handle callbacks holding nocb_lock, local rcu_core() stops |
* | handling callbacks. Enable bypass queueing. |
* ----------------------------------------------------------------------------
*/
* To solve this issue, ISO 11898-1 introduces in section 11.3.3
* "Transmitter delay compensation" a SSP (Secondary Sample Point)
* equal to the distance from the start of the bit time on the TX pin
* to the actual measurement on the RX pin.
*
* This structure contains the parameters to calculate that SSP.
*
* -+----------- one bit ----------+-- TX pin
* |<--- Sample Point --->|
*
* --+----------- one bit ----------+-- RX pin
* |<-------- TDCV -------->|
* |<------- TDCO ------->|
* |<----------- Secondary Sample Point ---------->|
*
* To increase precision, contrary to the other bittiming parameters
* which are measured in time quanta, the TDC parameters are measured
* in clock periods (also referred as "minimum time quantum" in ISO
* 11898-1).
/*
* can_get_relative_tdco() - TDCO relative to the sample point
*
* struct can_tdc::tdco represents the absolute offset from TDCV. Some
* controllers use instead an offset relative to the Sample Point (SP)
* such that:
*
* SSP = TDCV + absolute TDCO
* = TDCV + SP + relative TDCO
*
* -+----------- one bit ----------+-- TX pin
* |<--- Sample Point --->|
*
* --+----------- one bit ----------+-- RX pin
* |<-------- TDCV -------->|
* |<------------------------>| absolute TDCO
* |<--- Sample Point --->|
* | |<->| relative TDCO
* |<------------- Secondary Sample Point ------------>|
*/
* Note: The last link-list pointer should point to the physical address
* of 'configuration 1', which can avoid DMA controller loads incorrect
* configuration when the last configuration transaction is done.
*
* DMA controller linklist memory
* ====================== -----------------------
*| | | configuration 1 |<---
*| DMA controller | ------->| | |
*| | | | | |
*| | | | | |
*| | | | | |
*| linklist pointer reg |---- ----| linklist pointer | |
* ====================== | ----------------------- |
* | |
* | ----------------------- |
* | | configuration 2 | |
* --->| | |
* | | |
* | | |
* | | |
* ----| linklist pointer | |
* | ----------------------- |
* | |
* | ----------------------- |
* | | configuration 3 | |
* --->| | |
* | | |
* | . | |
* . |
* . |
* . |
* | . |
* | ----------------------- |
* | | configuration n | |
* --->| | |
* | | |
* | | |
* | | |
* | linklist pointer |----
* -----------------------
*
* To support the link-list mode, DMA slaves should allocate one segment memory
* from always-on IRAM or dma coherent memory to store these groups of DMA
* configuration, and pass the virtual and physical address to DMA controller.
/**
* arch_scale_cpu_capacity - get the capacity scale factor of a given CPU.
* @cpu: the CPU in question.
*
* Return: the CPU scale factor normalized against SCHED_CAPACITY_SCALE, i.e.
*
* max_perf(cpu)
* ----------------------------- * SCHED_CAPACITY_SCALE
* max(max_perf(c) : c \in CPUs)
*/
/*
* Processor error section:
*
* +-sal_log_processor_info_t *info-------------+
* | sal_log_section_hdr_t header; |
* | ... |
* | sal_log_mod_error_info_t info[0]; |
* +-+----------------+-------------------------+
* | CACHE_CHECK | ^ num_cache_check v
* +----------------+
* | TLB_CHECK | ^ num_tlb_check v
* +----------------+
* | BUS_CHECK | ^ num_bus_check v
* +----------------+
* | REG_FILE_CHECK | ^ num_reg_file_check v
* +----------------+
* | MS_CHECK | ^ num_ms_check v
* +-struct cpuid_info *id----------------------+
* | regs[5]; |
* | reserved; |
* +-sal_processor_static_info_t *regs----------+
* | valid; |
* | ... |
* | fr[128]; |
* +--------------------------------------------+
*/
/*
* In the 4 OP mode there is four possible configurations how the
* operators can be connected together (in 2 OP modes there is just
* AM or FM). The 4 OP connection mode is defined by the rightmost
* bit of the FEEDBACK_CONNECTION (0xC0-0xC8) on the both halves.
*
* First half Second half Mode
*
* +---+
* v |
* 0 0 >+-1-+--2--3--4-->
*
*
*
* +---+
* | |
* 0 1 >+-1-+--2-+
* |->
* >--3----4-+
*
* +---+
* | |
* 1 0 >+-1-+-----+
* |->
* >--2--3--4-+
*
* +---+
* | |
* 1 1 >+-1-+--+
* |
* >--2--3-+->
* |
* >--4----+
*/
* The state transitions of ACRN I/O request:
*
* FREE -> PENDING -> PROCESSING -> COMPLETE -> FREE -> ...
*
* An I/O request in COMPLETE or FREE state is owned by the hypervisor. HSM and
* ACRN userspace are in charge of processing the others.
*
* On basis of the states illustrated above, a typical lifecycle of ACRN IO
* request would look like:
*
* Flow (assume the initial state is FREE)
* |
* | Service VM vCPU 0 Service VM vCPU x User vCPU y
* |
* | hypervisor:
* | fills in type, addr, etc.
* | pauses the User VM vCPU y
* | sets the state to PENDING (a)
* | fires an upcall to Service VM
* |
* | HSM:
* | scans for PENDING requests
* | sets the states to PROCESSING (b)
* | assigns the requests to clients (c)
* V
* | client:
* | scans for the assigned requests
* | handles the requests (d)
* | HSM:
* | sets states to COMPLETE
* | notifies the hypervisor
* |
* | hypervisor:
* | resumes User VM vCPU y (e)
* |
* | hypervisor:
* | post handling (f)
* V sets states to FREE
*
* Note that the procedures (a) to (f) in the illustration above require to be
* strictly processed in the order. One vCPU cannot trigger another request of
* I/O emulation before completing the previous one.
*
* Atomic and barriers are required when HSM and hypervisor accessing the state
* of &struct acrn_io_request.
/*
* KVM dirty GFN flags, defined as:
*
* |---------------+---------------+--------------|
* | bit 1 (reset) | bit 0 (dirty) | Status |
* |---------------+---------------+--------------|
* | 0 | 0 | Invalid GFN |
* | 0 | 1 | Dirty GFN |
* | 1 | X | GFN to reset |
* |---------------+---------------+--------------|
*
* Lifecycle of a dirty GFN goes like:
*
* dirtied harvested reset
* 00 -----------> 01 -------------> 1X -------+
* ^ |
* | |
* +------------------------------------------+
*
* The userspace program is only responsible for the 01->1X state
* conversion after harvesting an entry. Also, it must not skip any
* dirty bits, so that dirty bits are always harvested in sequence.
*/
/* This file provides translation primitives and tables for the conversion
* of (ASCII) characters to a 14-segments notation.
*
* The 14 segment's wikipedia notation below is used as standard.
* See: https://en.wikipedia.org/wiki/Fourteen-segment_display
*
* Notation: +---a---+
* |\ | /|
* f h i j b
* | \|/ |
* +-g1+-g2+
* | /|\ |
* e k l m c
* |/ | \|
* +---d---+
*
* Usage:
*
* Register a map variable, and fill it with a character set:
* static SEG14_DEFAULT_MAP(map_seg14);
*
*
* Then use for conversion:
* seg14 = map_to_seg14(&map_seg14, some_char);
* ...
*
* In device drivers it is recommended, if required, to make the char map
* accessible via the sysfs interface using the following scheme:
*
* static ssize_t map_seg14_show(struct device *dev,
* struct device_attribute *attr, char *buf)
* {
* memcpy(buf, &map_seg14, sizeof(map_seg14));
* return sizeof(map_seg14);
* }
* static ssize_t map_seg14_store(struct device *dev,
* struct device_attribute *attr,
* const char *buf, size_t cnt)
* {
* if (cnt != sizeof(map_seg14))
* return -EINVAL;
* memcpy(&map_seg14, buf, cnt);
* return cnt;
* }
* static DEVICE_ATTR_RW(map_seg14);
*/
/**
* struct omap3isp_prev_rgbtorgb - RGB to RGB Blending
* @matrix: Blending values(S12Q8 format)
* [RR] [GR] [BR]
* [RG] [GG] [BG]
* [RB] [GB] [BB]
* @offset: Blending offset value for R,G,B in 2's complement integer format.
*/
/*
* Synchronize ar.itc of the current (slave) CPU with the ar.itc of the MASTER CPU
* (normally the time-keeper CPU). We use a closed loop to eliminate the possibility of
* unaccounted-for errors (such as getting a machine check in the middle of a calibration
* step). The basic idea is for the slave to ask the master what itc value it has and to
* read its own itc before and after the master responds. Each iteration gives us three
* timestamps:
*
* slave master
*
* t0 ---\
* ---\
* --->
* tm
* /---
* /---
* t1 <---
*
*
* The goal is to adjust the slave's ar.itc such that tm falls exactly half-way between t0
* and t1. If we achieve this, the clocks are synchronized provided the interconnect
* between the slave and the master is symmetric. Even if the interconnect were
* asymmetric, we would still know that the synchronization error is smaller than the
* roundtrip latency (t0 - t1).
*
* When the interconnect is quiet and symmetric, this lets us synchronize the itc to
* within one or two cycles. However, we can only *guarantee* that the synchronization is
* accurate to within a round-trip time, which is typically in the range of several
* hundred cycles (e.g., ~500 cycles). In practice, this means that the itc's are usually
* almost perfectly synchronized, but we shouldn't assume that the accuracy is much better
* than half a micro second or so.
*/
/*
* Single "mode" entry. This describes one set of signal timings a display can
* have in one setting. This struct can later be converted to struct videomode
* (see include/video/videomode.h). As each timing_entry can be defined as a
* range, one struct display_timing may become multiple struct videomodes.
*
* Example: hsync active high, vsync active low
*
* Active Video
* Video ______________________XXXXXXXXXXXXXXXXXXXXXX_____________________
* |<- sync ->|<- back ->|<----- active ----->|<- front ->|<- sync..
* | | porch | | porch |
*
* HSync _|¯¯¯¯¯¯¯¯¯¯|___________________________________________|¯¯¯¯¯¯¯¯¯
*
* VSync ¯|__________|¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯|_________
*/
/* Notes on per-window bpp settings
*
* Value Win0 Win1 Win2 Win3 Win 4
* 0000 1(P) 1(P) 1(P) 1(P) 1(P)
* 0001 2(P) 2(P) 2(P) 2(P) 2(P)
* 0010 4(P) 4(P) 4(P) 4(P) -none-
* 0011 8(P) 8(P) -none- -none- -none-
* 0100 -none- 8(A232) 8(A232) -none- -none-
* 0101 16(565) 16(565) 16(565) 16(565) 16(565)
* 0110 -none- 16(A555) 16(A555) 16(A555) 16(A555)
* 0111 16(I555) 16(I565) 16(I555) 16(I555) 16(I555)
* 1000 18(666) 18(666) 18(666) 18(666) 18(666)
* 1001 -none- 18(A665) 18(A665) 18(A665) 16(A665)
* 1010 -none- 19(A666) 19(A666) 19(A666) 19(A666)
* 1011 24(888) 24(888) 24(888) 24(888) 24(888)
* 1100 -none- 24(A887) 24(A887) 24(A887) 24(A887)
* 1101 -none- 25(A888) 25(A888) 25(A888) 25(A888)
* 1110 -none- -none- -none- -none- -none-
* 1111 -none- -none- -none- -none- -none-
*/
*-------------------------------- Normal flow --------------------------------
*
* Front Back
* ================================= =====================================
* XenbusStateInitialising XenbusStateInitialising
* o Query backend device identification
* data.
* o Open and validate backend device.
* |
* |
* V
* XenbusStateInitWait
*
* o Query frontend configuration
* o Allocate and initialize
* event channels per configured
* connector.
* o Publish transport parameters
* that will be in effect during
* this connection.
* |
* |
* V
* XenbusStateInitialised
*
* o Query frontend transport parameters.
* o Connect to the event channels.
* |
* |
* V
* XenbusStateConnected
*
* o Create and initialize OS
* virtual display connectors
* as per configuration.
* |
* |
* V
* XenbusStateConnected
*
* XenbusStateUnknown
* XenbusStateClosed
* XenbusStateClosing
* o Remove virtual display device
* o Remove event channels
* |
* |
* V
* XenbusStateClosed
// WebAssembly instructions for exception handling are structured as follows:
// try
// instructions*
// catch ----|
// instructions* | -> A WebAssemblyException consists of this region
// end ----|
//
// A WebAssemblyException object contains BBs that belong to a 'catch' part of
// the try-catch-end structure to be created later. 'try' and 'end' markers
// are not present at this stage and will be generated in CFGStackify pass.
// Because CFGSort requires all the BBs within a catch part to be sorted
// together as it does for loops, this pass calculates the nesting structure of
// catch part of exceptions in a function.
//
// An exception catch part is defined as a BB with catch instruction and all
// other BBs dominated by this BB.
// This function creates additional block for storing varargs guarded
// registers. It adds check for %al into entry block, to skip
// GuardedRegsBlk if xmm registers should not be stored.
//
// EntryBlk[VAStartPseudoInstr] EntryBlk
// | | .
// | | .
// | | GuardedRegsBlk
// | => | .
// | | .
// | TailBlk
// | |
// | |
//
/// If Front End not use O0 but the Mid/Back end use O0, (e.g. "Clang -O2 -S
/// -emit-llvm t.c" + "llc t.ll") we should make sure the amx data is volatile,
/// because that is necessary for AMX fast register allocation. (In Fast
/// registera allocation, register will be allocated before spill/reload, so
/// there is no additional register for amx to identify the step in spill.)
/// The volatileTileData() will handle this case.
/// e.g.
/// ----------------------------------------------------------
/// | def %td = ... |
/// | ... |
/// | "use %td" |
/// ----------------------------------------------------------
/// will transfer to -->
/// ----------------------------------------------------------
/// | def %td = ... |
/// | call void @llvm.x86.tilestored64.internal(mem, %td) |
/// | ... |
/// | %td2 = call x86_amx @llvm.x86.tileloadd64.internal(mem)|
/// | "use %td2" |
/// ----------------------------------------------------------
// Test values
// duration hours minutes seconds fractional
// 5000s 1 23 20 0
// 5000 minutes 83 20 0 0
// 123456789ms 34 17 36 789ms
// 123456789us 0 2 3 456789us
// 123456789ns 0 0 0 123456789ns
// 1000mfn 0 20 9 0.6 (6000/10000)
// 10000mfn 3 21 36 0
// Transform each threading path to effectively jump thread the DFA. For
// example, the CFG below could be transformed as follows, where the cloned
// blocks unconditionally branch to the next correct case based on what is
// identified in the analysis.
//
// sw.bb sw.bb
// / | \ / | \
// case1 case2 case3 case1 case2 case3
// \ | / | | |
// determinator det.2 det.3 det.1
// br sw.bb / | \
// sw.bb.2 sw.bb.3 sw.bb.1
// br case2 br case3 br case1§
//
// Definitions and Terminology:
//
// * Threading path:
// a list of basic blocks, the exit state, and the block that determines
// the next state, for which the following notation will be used:
// < path of BBs that form a cycle > [ state, determinator ]
//
// * Predictable switch:
// The switch variable is always a known constant so that all conditional
// jumps based on switch variable can be converted to unconditional jump.
//
// * Determinator:
// The basic block that determines the next state of the DFA.
//
// Representing the optimization in C-like pseudocode: the code pattern on the
// left could functionally be transformed to the right pattern if the switch
// condition is predictable.
//
// X = A goto A
// for (...) A:
// switch (X) ...
// case A goto B
// X = B B:
// case B ...
// X = C goto C
//
// The pass first checks that switch variable X is decided by the control flow
// path taken in the loop; for example, in case B, the next value of X is
// decided to be C. It then enumerates through all paths in the loop and labels
// the basic blocks where the next state is decided.
// CHI keeps information about values flowing out of a basic block. It is
// similar to PHI but in the inverse graph, and used for outgoing values on each
// edge. For conciseness, it is computed only for instructions with multiple
// occurrences in the CFG because they are the only hoistable candidates.
// A (CHI[{V, B, I1}, {V, C, I2}]
// / \
// / \
// B(I1) C (I2)
// The Value number for both I1 and I2 is V, the CHI node will save the
// instruction as well as the edge where the value is flowing to.
// Given an element pointer \p BasePtr to the start of a (sub) matrix, compute
// the start address of vector \p VecIdx with type (\p EltType x \p NumElements)
// assuming \p Stride elements between start two consecutive vectors.
// \p Stride must be >= \p NumElements.
// For column-major matrixes, the function computes the address of a column
// vectors and \p NumElements must be set to the number of elements in a column
// (= number of rows of the matrix). For row-major matrixes, the function
// computes the address of a row vector and \p NumElements must be set to the
// number of elements in a column (= number of columns of the matrix).
//
// Consider a 4x4 matrix in column-mjaor layout like below
//
// 0 1 2 3
// 0 v_0_0 v_0_1 v_0_2 v_0_3
// 1 v_1_0 v_1_1 v_1_2 v_1_3
// 2 v_2_0 v_2_1 v_2_2 v_2_3
// 3 v_3_0 v_3_1 v_3_2 v_3_3
// Example:
// Diamond shaped code before merge:
//
// header:
// br %cond, label %if.then, label %if.else
// + +
// + +
// + +
// if.then: if.else:
// %lt = load %addr_l %le = load %addr_l
// <use %lt> <use %le>
// <...> <...>
// store %st, %addr_s store %se, %addr_s
// br label %if.end br label %if.end
// + +
// + +
// + +
// if.end ("footer"):
// <...>
//
// Diamond shaped code after merge:
//
// header:
// %l = load %addr_l
// br %cond, label %if.then, label %if.else
// + +
// + +
// + +
// if.then: if.else:
// <use %l> <use %l>
// <...> <...>
// br label %if.end br label %if.end
// + +
// + +
// + +
// if.end ("footer"):
// %s.sink = phi [%st, if.then], [%se, if.else]
// <...>
// store %s.sink, %addr_s
// <...>
/// A leaf node is either not a binary operation of the same kind as the root
/// node 'I' (i.e. is not a binary operator at all, or is, but with a different
/// opcode), or is the same kind of binary operator but has a use which either
/// does not belong to the expression, or does belong to the expression but is
/// a leaf node. Every leaf node has at least one use that is a non-leaf node
/// of the expression, while for non-leaf nodes (except for the root 'I') every
/// use is a non-leaf node of the expression.
///
/// For example:
/// expression graph node names
///
/// + | I
/// / \ |
/// + + | A, B
/// / \ / \ |
/// * + * | C, D, E
/// / \ / \ / \ |
/// + * | F, G
///
/// The leaf nodes are C, E, F and G. The Ops array will contain (maybe not in
/// that order) (C, 1), (E, 1), (F, 2), (G, 2).
///
/// The expression is maximal: if some instruction is a binary operator of the
/// same kind as 'I', and all of its uses are non-leaf nodes of the expression,
/// then the instruction also belongs to the expression, is not a leaf node of
/// it, and its operands also belong to the expression (but may be leaf nodes).
///
/// NOTE: This routine will set operands of non-leaf non-root nodes to undef in
/// order to ensure that every non-root node in the expression has *exactly one*
/// use by a non-leaf node of the expression. This destruction means that the
/// caller MUST either replace 'I' with a new expression or use something like
/// RewriteExprTree to put the values back in if the routine indicates that it
/// made a change by returning 'true'.
///
/// In the above example either the right operand of A or the left operand of B
/// will be replaced by undef. If it is B's operand then this gives:
///
/// + | I
/// / \ |
/// + + | A, B - operand of B replaced with undef
/// / \ \ |
/// * + * | C, D, E
/// / \ / \ / \ |
/// + * | F, G
///
/// Note that such undef operands can only be reached by passing through 'I'.
/// For example, if you visit operands recursively starting from a leaf node
/// then you will never see such an undef operand unless you get back to 'I',
/// which requires passing through a phi node.
// An irreducible SCC is one which has multiple "header" blocks, i.e., blocks
// with control-flow edges incident from outside the SCC. This pass converts a
// irreducible SCC into a natural loop by applying the following transformation:
//
// 1. Collect the set of headers H of the SCC.
// 2. Collect the set of predecessors P of these headers. These may be inside as
// well as outside the SCC.
// 3. Create block N and redirect every edge from set P to set H through N.
//
// This converts the SCC into a natural loop with N as the header: N is the only
// block with edges incident from outside the SCC, and all backedges in the SCC
// are incident on N, i.e., for every backedge, the head now dominates the tail.
//
// INPUT CFG: The blocks A and B form an irreducible loop with two headers.
//
// Entry
// / \
// v v
// A ----> B
// ^ /|
// `----' |
// v
// Exit
//
// OUTPUT CFG: Edges incident on A and B are now redirected through a
// new block N, forming a natural loop consisting of N, A and B.
//
// Entry
// |
// v
// .---> N <---.
// / / \ \
// | / \ |
// \ v v /
// `-- A B --'
// |
// v
// Exit
//
// The transformation is applied to every maximal SCC that is not already
// recognized as a loop. The pass operates on all maximal SCCs found in the
// function body outside of any loop, as well as those found inside each loop,
// including inside any newly created loops. This ensures that any SCC hidden
// inside a maximal SCC is also transformed.
// CHECK-I386: SectionData (
// CHECK-I386: 0000: 00000000 00000000 05000000 00000000 |................|
// CHECK-I386: 0010: 05000000 09000000 09000000 00000000 |................|
// CHECK-I386: 0020: 00000000 00000000 0D000000 0D000000 |................|
// CHECK-I386: 0030: CFFFFFFF FFFFFFFF |........|
// CHECK-I386: )
/*
Format of unsymbolized profile:
[frame1 @ frame2 @ ...] # If it's a CS profile
number of entries in RangeCounter
from_1-to_1:count_1
from_2-to_2:count_2
......
from_n-to_n:count_n
number of entries in BranchCounter
src_1->dst_1:count_1
src_2->dst_2:count_2
......
src_n->dst_n:count_n
[frame1 @ frame2 @ ...] # Next context
......
Note that non-CS profile doesn't have the empty `[]` context.
*/
* Terminal nodes are nodes that represent actual exports. They can appear
* anywhere in the tree other than at the root; they do not need to be leaf
* nodes. When reading the data out of the trie this routine reads it in-order,
* but it puts the child names and offsets directly into the child nodes. This
* results in looping over the children twice during serialization and
* de-serialization, but it makes the YAML representation more human readable.
*
* Below is an example of the graph from a "Hello World" executable:
*
* -------
* | '' |
* -------
* |
* -------
* | '_' |
* -------
* |
* |----------------------------------------|
* | |
* ------------------------ ---------------------
* | '_mh_execute_header' | | 'main' |
* | Flags: 0x00000000 | | Flags: 0x00000000 |
* | Addr: 0x00000000 | | Addr: 0x00001160 |
* ------------------------ ---------------------
*
* This graph represents the trie for the exports "__mh_execute_header" and
* "_main". In the graph only the "_main" and "__mh_execute_header" nodes are
* terminal.
/*
IR forming a call graph with a diamond of triangle-shaped SCCs:
d1
/ \
d3--d2
/ \
b1 c1
/ \ / \
b3--b2 c3--c2
\ /
a1
/ \
a3--a2
All call edges go up between SCCs, and clockwise around the SCC.
*/
// Bug: During phi optimization, the walker wouldn't cache to the proper result
// in the farthest-walked BB.
//
// Specifically, it would assume that whatever we walked to was a clobber.
// "Whatever we walked to" isn't a clobber if we hit a cache entry.
//
// ...So, we need a test case that looks like:
// A
// / \
// B |
// \ /
// C
//
// Where, when we try to optimize a thing in 'C', a blocker is found in 'B'.
// The walk must determine that the blocker exists by using cache entries *while
// walking* 'B'.
// Verify that the PDT is correctly updated in case an edge removal results
// in an infinite loop. Also make sure that the updated PDT is the
// same as a freshly recalculated one.
//
// Test case:
//
// CFG PDT
//
// A Exit
// | |
// _B D
// / | \ |
// ^ v \ B
// \ / D / \
// C \ C A
// / \ v
// ^ v Exit
// \_/
//
// After deleting the edge C->B, C is part of an infinite reverse-unreachable
// loop:
//
// CFG' PDT'
//
// A Exit
// | / | \
// B C B D
// | \ |
// v \ A
// / D
// C \
// / \ v
// ^ v Exit
// \_/
//
// As C now becomes reverse-unreachable, it forms a new non-trivial root and
// gets connected to the virtual exit.
// D does not postdominate B anymore, because there are two forward paths from
// B to the virtual exit:
// - B -> C -> VirtualExit
// - B -> D -> VirtualExit.
//
//====- LowerToLLVM.cpp - Lowering from Toy+Affine+Std to LLVM ------------===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
// This file implements full lowering of Toy operations to LLVM MLIR dialect.
// 'toy.print' is lowered to a loop nest that calls `printf` on each element of
// the input array. The file also sets up the ToyToLLVMLoweringPass. This pass
// lowers the combination of Arithmetic + Affine + SCF + Func dialects to the
// LLVM one:
//
// Affine --
// |
// v
// Arithmetic + Func --> LLVM (Dialect)
// ^
// |
// 'toy.print' --> Loop (SCF) --
//
//===----------------------------------------------------------------------===//
//====- LowerToLLVM.cpp - Lowering from Toy+Affine+Std to LLVM ------------===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
// This file implements full lowering of Toy operations to LLVM MLIR dialect.
// 'toy.print' is lowered to a loop nest that calls `printf` on each element of
// the input array. The file also sets up the ToyToLLVMLoweringPass. This pass
// lowers the combination of Arithmetic + Affine + SCF + Func dialects to the
// LLVM one:
//
// Affine --
// |
// v
// Arithmetic + Func --> LLVM (Dialect)
// ^
// |
// 'toy.print' --> Loop (SCF) --
//
//===----------------------------------------------------------------------===//
/// Fills `forwardSlice` with the computed forward slice (i.e. all
/// the transitive uses of op), **without** including that operation.
///
/// This additionally takes a TransitiveFilter which acts as a frontier:
/// when looking at uses transitively, an operation that does not pass the
/// filter is never propagated through. This allows in particular to carve out
/// the scope within a ForOp or the scope within an IfOp.
///
/// The implementation traverses the use chains in postorder traversal for
/// efficiency reasons: if an operation is already in `forwardSlice`, no
/// need to traverse its uses again. Since use-def chains form a DAG, this
/// terminates.
///
/// Upon return to the root call, `forwardSlice` is filled with a
/// postorder list of uses (i.e. a reverse topological order). To get a proper
/// topological order, we just just reverse the order in `forwardSlice` before
/// returning.
///
/// Example starting from node 0
/// ============================
///
/// 0
/// ___________|___________
/// 1 2 3 4
/// |_______| |______|
/// | | |
/// | 5 6
/// |___|_____________|
/// | |
/// 7 8
/// |_______________|
/// |
/// 9
///
/// Assuming all local orders match the numbering order:
/// 1. after getting back to the root getForwardSlice, `forwardSlice` may
/// contain:
/// {9, 7, 8, 5, 1, 2, 6, 3, 4}
/// 2. reversing the result of 1. gives:
/// {4, 3, 6, 2, 1, 5, 8, 7, 9}
///
/// Given two polyhedra `a` and `b` at positions `i` and `j` in
/// `disjuncts` and `redundantIneqsA` being the inequalities of `a` that
/// are redundant for `b` (similarly for `cuttingIneqsA`, `redundantIneqsB`,
/// and `cuttingIneqsB`), Checks whether the facets of all cutting
/// inequalites of `a` are contained in `b`. If so, a new polyhedron
/// consisting of all redundant inequalites of `a` and `b` and all
/// equalities of both is created.
///
/// An example of this case:
/// ___________ ___________
/// / / | / / /
/// \ \ | / ==> \ /
/// \ \ | / \ /
/// \___\|/ \_____/
///
///
// Blocks from the given `spirv.mlir.selection` operation must satisfy the
// following layout:
//
// +-----------------------------------------------+
// | header block |
// | spirv.BranchConditionalOp %cond, ^case0, ^case1 |
// +-----------------------------------------------+
// / \
// ...
//
//
// +------------------------+ +------------------------+
// | case #0 | | case #1 |
// | spirv.Store %ptr %value0 | | spirv.Store %ptr %value1 |
// | spirv.Branch ^merge | | spirv.Branch ^merge |
// +------------------------+ +------------------------+
//
//
// ...
// \ /
// v
// +-------------+
// | merge block |
// +-------------+
//
// Test Case:
// bb0
// / \
// bb1 bb2 <- Initial position of AllocOp
// \ /
// bb3
// BufferDeallocation expected behavior: bb2 contains an AllocOp which is
// passed to bb3. In the latter block, there should be an deallocation.
// Since bb1 does not contain an adequate alloc and the alloc in bb2 is not
// moved to bb0, we need to insert allocs and copies.
// Illustrates an 8x8 Sparse Matrix x Vector implemented with only operations
// of the vector dialect (and some std/scf). Essentially, this example performs
// the following multiplication:
//
// 0 1 2 3 4 5 6 7
// +------------------------+
// 0 | 1 0 2 0 0 1 0 1 | | 1 | | 21 |
// 1 | 1 8 0 0 3 0 1 0 | | 2 | | 39 |
// 2 | 0 0 1 0 0 2 6 2 | | 3 | | 73 |
// 3 | 0 3 0 1 0 1 0 1 | x | 4 | = | 24 |
// 4 | 5 0 0 1 1 1 0 0 | | 5 | | 20 |
// 5 | 0 3 0 0 2 1 2 0 | | 6 | | 36 |
// 6 | 4 0 7 0 1 0 1 0 | | 7 | | 37 |
// 7 | 0 3 0 2 0 0 1 1 | | 8 | | 29 |
// +------------------------+
//
// The sparse storage scheme used is an extended column scheme (also referred
// to as jagged diagonal, which is essentially a vector friendly variant of
// the general sparse row-wise scheme (also called compressed row storage),
// using fixed length vectors and no explicit pointer indexing into the
// value array to find the rows.
//
// The extended column storage for the matrix shown above is as follows.
//
// VALUE INDEX
// +---------+ +---------+
// 0 | 1 2 1 1 | | 0 2 5 7 |
// 1 | 1 8 3 1 | | 0 1 4 6 |
// 2 | 1 2 6 2 | | 2 5 6 7 |
// 3 | 3 1 1 1 | | 1 3 5 7 |
// 4 | 5 1 1 1 | | 0 3 4 5 |
// 5 | 3 2 1 2 | | 1 4 5 6 |
// 6 | 4 7 1 1 | | 0 2 4 6 |
// 7 | 3 2 1 1 | | 1 3 6 7 |
// +---------+ +---------+
//
// This example illustrates a DOT version for the operation. Another example
// in this directory illustrates an effective SAXPY version that operates on the
// transposed jagged diagonal storage to obtain higher vector lengths.
// Illustrates an 8x8 Sparse Matrix x Vector implemented with only operations
// of the vector dialect (and some std/scf). Essentially, this example performs
// the following multiplication:
//
// 0 1 2 3 4 5 6 7
// +------------------------+
// 0 | 1 0 2 0 0 1 0 1 | | 1 | | 21 |
// 1 | 1 8 0 0 3 0 1 0 | | 2 | | 39 |
// 2 | 0 0 1 0 0 2 6 2 | | 3 | | 73 |
// 3 | 0 3 0 1 0 1 0 1 | x | 4 | = | 24 |
// 4 | 5 0 0 1 1 1 0 0 | | 5 | | 20 |
// 5 | 0 3 0 0 2 1 2 0 | | 6 | | 36 |
// 6 | 4 0 7 0 1 0 1 0 | | 7 | | 37 |
// 7 | 0 3 0 2 0 0 1 1 | | 8 | | 29 |
// +------------------------+
//
// The sparse storage scheme used is an extended column scheme (also referred
// to as jagged diagonal, which is essentially a vector friendly variant of
// the general sparse row-wise scheme (also called compressed row storage),
// using fixed length vectors and no explicit pointer indexing into the
// value array to find the rows.
//
// The extended column storage for the matrix shown above is as follows.
//
// VALUE INDEX
// +---------+ +---------+
// 0 | 1 2 1 1 | | 0 2 5 7 |
// 1 | 1 8 3 1 | | 0 1 4 6 |
// 2 | 1 2 6 2 | | 2 5 6 7 |
// 3 | 3 1 1 1 | | 1 3 5 7 |
// 4 | 5 1 1 1 | | 0 3 4 5 |
// 5 | 3 2 1 2 | | 1 4 5 6 |
// 6 | 4 7 1 1 | | 0 2 4 6 |
// 7 | 3 2 1 1 | | 1 3 6 7 |
// +---------+ +---------+
//
// This example illustrates an effective SAXPY version that operates
// on the transposed jagged diagonal storage to obtain higher vector
// lengths. Another example in this directory illustrates a DOT
// version of the operation.
// Test Case:
// bb0
// / \
// bb1 bb2 <- Initial position of AllocOp
// \ /
// bb3
// PromoteBuffersToStack expected behavior: It should convert %0 into an
// AllocaOp.
/* First the states
(head,tail) = 0, 0 means lock is unheld, nobody on queue
UINT_MAX or -1, 0 means lock is held, nobody on queue
h, h means lock held or about to transition,
1 element on queue
h, t h <> t, means lock is held or about to
transition, >1 elements on queue
Now the transitions
Acquire(0,0) = -1 ,0
Release(0,0) = Error
Acquire(-1,0) = h ,h h > 0
Release(-1,0) = 0 ,0
Acquire(h,h) = h ,t h > 0, t > 0, h <> t
Release(h,h) = -1 ,0 h > 0
Acquire(h,t) = h ,t' h > 0, t > 0, t' > 0, h <> t, h <> t', t <> t'
Release(h,t) = h',t h > 0, t > 0, h <> t, h <> h', h' maybe = t
And pictorially
+-----+
| 0, 0|------- release -------> Error
+-----+
| ^
acquire| |release
| |
| |
v |
+-----+
|-1, 0|
+-----+
| ^
acquire| |release
| |
| |
v |
+-----+
| h, h|
+-----+
| ^
acquire| |release
| |
| |
v |
+-----+
| h, t|----- acquire, release loopback ---+
+-----+ |
^ |
| |
+------------------------------------+
*/
/* ****************************************************************
Class to implement an event
There are four components to an event: start time, stop time
nest_level, and timer_name.
The start and stop time should be obvious (recorded in clock ticks).
The nest_level relates to the bar width in the timeline graph.
The timer_name is used to determine which timer event triggered this event.
the interface to this class is through four read-only operations:
1) getStart() -- returns the start time as 64 bit integer
2) getStop() -- returns the stop time as 64 bit integer
3) getNestLevel() -- returns the nest level of the event
4) getTimerName() -- returns the timer name that triggered event
*MORE ON NEST_LEVEL*
The nest level is used in the bar graph that represents the timeline.
Its main purpose is for showing how events are nested inside eachother.
For example, say events, A, B, and C are recorded. If the timeline
looks like this:
Begin -------------------------------------------------------------> Time
| | | | | |
A B C C B A
start start start end end end
Then A, B, C will have a nest level of 1, 2, 3 respectively.
These values are then used to calculate the barwidth so you can
see that inside A, B has occurred, and inside B, C has occurred.
Currently, this is shown with A's bar width being larger than B's
bar width, and B's bar width being larger than C's bar width.
**************************************************************** */
// Tests OMP 5.x task dependence "omp_all_memory",
// emulates compiler codegen versions for new dep kind
//
// Task tree created:
// task0 - task1 (in: i1, i2)
// \
// task2 (inoutset: i2), (in: i1)
// /
// task3 (omp_all_memory) via flag=0x80
// /
// task4 - task5 (in: i1, i2)
// /
// task6 (omp_all_memory) via addr=-1
// /
// task7 (omp_all_memory) via flag=0x80
// /
// task8 (in: i3)
//
/* Test for guided scheduling
* Ensure threads get chunks interleavely first
* Then judge the chunk sizes are decreasing to a stable value
* Modified by Chunhua Liao
* For example, 100 iteration on 2 threads, chunksize 7
* one line for each dispatch, 0/1 means thread id
* 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 24
* 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 18
* 0 0 0 0 0 0 0 0 0 0 0 0 0 0 14
* 1 1 1 1 1 1 1 1 1 1 10
* 0 0 0 0 0 0 0 0 8
* 1 1 1 1 1 1 1 7
* 0 0 0 0 0 0 0 7
* 1 1 1 1 1 1 1 7
* 0 0 0 0 0 5
*/
// Create a subfunction of the following (preliminary) structure:
//
// PrevBB
// |
// v
// HeaderBB
// / | _____
// / v v |
// / PreHeaderBB |
// | | |
// | v |
// | CheckNextBB |
// \ | \_____/
// \ |
// v v
// ExitBB
//
// HeaderBB will hold allocations, loading of variables and kmp-init calls.
// CheckNextBB will check for more work (dynamic / static chunked) or will be
// empty (static non chunked).
// If there is more work to do: go to PreHeaderBB, otherwise go to ExitBB.
// PreHeaderBB loads the new boundaries (& will lead to the loop body later on).
// Just like CheckNextBB: PreHeaderBB is (preliminary) empty in the static non
// chunked scheduling case. ExitBB marks the end of the parallel execution.
// The possibly empty BasicBlocks will automatically be removed.
// When a DataRef contains pointers, gets the rightmost one (unless it is
// the entity being defined, in which case the last pointer above it);
// otherwise, returns the leftmost symbol. The resulting symbol is the
// relevant base object for definabiliy checking. Examples:
// ptr1%ptr2 => ... -> ptr1
// nonptr%ptr => ... -> nonptr
// nonptr%ptr = ... -> ptr
// ptr1%ptr2 = ... -> ptr2
// ptr1%ptr2%nonptr = ... -> ptr2
// nonptr1%nonptr2 = ... -> nonptr1
// Expand a constant expression `Cur`, which is used at instruction `Parent`
// at index `index`.
// Since a constant expression can expand to multiple instructions, store all
// the expands into a set called `Expands`.
// Note that this goes inorder on the constant expression tree.
// A * ((B * D) + C)
// will be processed with first A, then B * D, then B, then D, and then C.
// Though ConstantExprs are not treated as "trees" but as DAGs, since you can
// have something like this:
// *
// / \
// \ /
// (D)
//
// For the purposes of this expansion, we expand the two occurences of D
// separately. Therefore, we expand the DAG into the tree:
// *
// / \
// D D
// TODO: We don't _have_to do this, but this is the simplest solution.
// We can write a solution that keeps track of which constants have been
// already expanded.
/* Basic map "i" has an inequality "k" that is adjacent
* to some inequality of basic map "j". All the other inequalities
* are valid for "j".
* If not NULL, then "extra" contains extra wrapping constraints that are valid
* for both "i" and "j".
* Check if basic map "j" forms an extension of basic map "i",
* taking into account the extra constraints, if any.
*
* Note that this function is only called if some of the equalities or
* inequalities of basic map "j" do cut basic map "i". The function is
* correct even if there are no such cut constraints, but in that case
* the additional checks performed by this function are overkill.
*
* In particular, we replace constraint k, say f >= 0, by constraint
* f <= -1, add the inequalities of "j" that are valid for "i",
* as well as the "extra" constraints, if any,
* and check if the result is a subset of basic map "j".
* To improve the chances of the subset relation being detected,
* any variable that only attains a single integer value
* in the tableau of "i" is first fixed to that value.
* If the result is a subset, then we know that this result is exactly equal
* to basic map "j" since all its constraints are valid for basic map "j".
* By combining the valid constraints of "i" (all equalities and all
* inequalities except "k"), the valid constraints of "j" and
* the "extra" constraints, if any, we therefore
* obtain a basic map that is equal to their union.
* In this case, there is no need to perform a rollback of the tableau
* since it is going to be destroyed in fuse().
*
*
* |\__ |\__
* | \__ | \__
* | \_ => | \__
* |_______| _ |_________\
*
*
* |\ |\
* | \ | \
* | \ | \
* | | | \
* | ||\ => | \
* | || \ | \
* | || | | |
* |__||_/ |_____/
*
*
* _______ _______
* | | __ | \__
* | ||__| => | __|
* |_______| |_______/
*/
/* Return rows that extend a basis of "mat1" to one
* that covers both "mat1" and "mat2".
* The Hermite normal form of the concatenation of the two matrices is
*
* [ Q1 ]
* [ M1 ] = [ H1 0 0 ] [ Q2 ]
* [ M2 ] = [ H2 H3 0 ] [ Q3 ]
*
* The number of columns in H1 and H3 determine the number of rows
* in Q1 and Q2. Q1 is a basis for M1, while Q2 extends this basis
* to also cover M2.
*/
* We first handle some simple cases
* - the row sign may be known already
* - the row may be obviously non-negative
* - the parametric constant may be equal to that of another row
* for which we know the sign. This sign will be either "pos" or
* "any". If it had been "neg" then we would have pivoted before.
*
* If none of these cases hold, we check the value of the row for each
* of the currently active samples. Based on the signs of these values
* we make an initial determination of the sign of the row.
*
* all zero -> unk(nown)
* all non-negative -> pos
* all non-positive -> neg
* both negative and positive -> all
*
* If we end up with "all", we are done.
* Otherwise, we perform a check for positive and/or negative
* values as follows.
*
* samples neg unk pos
* <0 ? Y N Y N
* pos any pos
* >0 ? Y N Y N
* any neg any neg
*
* There is no special sign for "zero", because we can usually treat zero
* as either non-negative or non-positive, whatever works out best.
* However, if the row is "critical", meaning that pivoting is impossible
* then we don't want to limp zero with the non-positive case, because
* then we we would lose the solution for those values of the parameters
* where the value of the row is zero. Instead, we treat 0 as non-negative
* ensuring a split if the row can attain both zero and negative values.
* The same happens when the original constraint was one that could not
* be satisfied with equality by any integer values of the parameters.
* In this case, we normalize the constraint, but then a value of zero
* for the normalized constraint is actually a positive value for the
* original constraint, so again we need to treat zero as non-negative.
* In both these cases, we have the following decision tree instead:
*
* all non-negative -> pos
* all negative -> neg
* both negative and non-negative -> all
*
* samples neg pos
* <0 ? Y N
* any pos
* >=0 ? Y N
* any neg
* We first compute a schedule that respects the dependences
* of the original program and select the outermost bands
* of tilable dimensions that have at least one parallel loop.
* If the --load-schedule is specified, then the loaded schedule
* is used instead of a computed schedule.
*
* Each of these bands B is then tiled according to "tile" sizes, resulting
* in two nested bands, with a kernel marker on top
*
* K
* |
* T
* |
* P
*
* We then split off at most 2 parallel dimensions from the T band and
* at most 3 parallel dimension from the P band
*
* K
* |
* T
* T1
* |
* T2
* |
* P1
* |
* P2
*
* A filter is introduced in front of T1 that maps the domain instances
* to block identifiers. Similarly, a filter is introduced in front of P1
* that maps the domain instances to thread identifiers.
/* Construct the basic hexagonal tile shape.
* "space" is the 2D space in which the hexagon should be constructed.
* h is st-1, with st the tile size in the time dimension
* s0 is the tile size in the space dimension
* dl is a bound on the negative relative dependence distances, i.e.,
*
* d_s >= -dl d_t
*
* du is a bound on the positive relative dependence distances, i.e.,
*
* d_s <= du d_t
*
* with (d_t,d_s) any dependence distance vector.
* dlh = floor(dl * h)
* duh = floor(du * h)
*
* The shape of the hexagon is as follows:
*
* 0 dlh dlh+s0-1
* ______ __
* 0 / \_ /
* / \_ /
* h / \ ______ /
* h+1 \_ // \\_
* \_ // \\_
* 2h+1 \______// \\
* 0 duh duh+s0-1
* duh+s0-1+dlh
* duh+s0-1+dlh+1+s0+1
*
* The next hexagon is shifted by duh + dlh + 2 * s0.
*
* The slope of the "/" constraints is dl.
* The slope of the "\_" constraints is du.
*/
// When the method augments a flow (moving left_[l] from some r1 to some
// other r2), this can be thought of as "undoing" the above steps with
// respect to r1 and "redoing" them with respect to r2.
//
// It bears repeating that the flow graph and residual flow graph are
// never represented explicitly, but can be derived by looking at the
// information in 'graph' and in left_.
//
// As an optimization, there is a second vector<int> called right_ which
// does not provide any new information. Instead, it enables more
// efficient queries about edges entering or leaving the right-side nodes
// of the flow or residual flow graphs. The following invariants are
// maintained:
//
// left[l] == kUnused or right[left[l]] == l
// right[r] == kUnused or left[right[r]] == r
//
// . [ source ] .
// . ||| .
// . ||| .
// . ||\--> left[0]=1 ---\ right[0]=-1 ----\ .
// . || | | .
// . |\---> left[1]=-1 \--> right[1]=0 ---\| .
// . | || .
// . \----> left[2]=2 ------> right[2]=2 --\|| .
// . ||| .
// . elements matchers vvv .
// . [ sink ] .
//
// See Also:
// [1] Cormen, et al (2001). "Section 26.2: The Ford-Fulkerson method".
// "Introduction to Algorithms (Second ed.)", pp. 651-664.
// [2] "Ford-Fulkerson algorithm", Wikipedia,
// 'http://en.wikipedia.org/wiki/Ford%E2%80%93Fulkerson_algorithm'
// Inheritance graph for the parse tree visitation classes that follow:
// BaseVisitor
// + AttrsVisitor
// | + DeclTypeSpecVisitor
// | + ImplicitRulesVisitor
// | + ScopeHandler -----------+--+
// | + ModuleVisitor ========|==+
// | + InterfaceVisitor | |
// | +-+ SubprogramVisitor ==|==+
// + ArraySpecVisitor | |
// + DeclarationVisitor <--------+ |
// + ConstructVisitor |
// + ResolveNamesVisitor <------+
// This is a partial implementation of the Mach-O export trie format. It's
// essentially a symbol table encoded as a compressed prefix trie, meaning that
// the common prefixes of each symbol name are shared for a more compact
// representation. The prefixes are stored on the edges of the trie, and one
// edge can represent multiple characters. For example, given two exported
// symbols _bar and _baz, we will have a trie like this (terminal nodes are
// marked with an asterisk):
//
// +-+-+
// | | // root node
// +-+-+
// |
// | _ba
// |
// +-+-+
// | |
// +-+-+
// r / \ z
// / \
// +-+-+ +-+-+
// | * | | * |
// +-+-+ +-+-+
//
// More documentation of the format can be found in
// llvm/tools/obj2yaml/macho2yaml.cpp.
// In the below given dataset
//
// [a, b] <- (x)
//
// 'a' and 'b' describe a range and 'x' the value for that interval.
//
// The following data are purely for illustrative purposes:
//
// [30, 35] <- (3035), [39, 50] <- (3950), [55, 61] <- (5561),
// [31, 56] <- (3156), [12, 21] <- (1221), [25, 41] <- (2541),
// [49, 65] <- (4965), [71, 79] <- (7179), [11, 16] <- (1116),
// [20, 30] <- (2030), [36, 54] <- (3654), [60, 70] <- (6070),
// [74, 80] <- (7480), [15, 40] <- (1540), [43, 43] <- (4343),
// [50, 75] <- (5075), [10, 85] <- (1085)
//
// The data represents a set of overlapping intervals:
//
// 30--35 39------------50 55----61
// 31------------------------56
// 12--------21 25------------41 49-------------65 71-----79
// 11----16 20-----30 36----------------54 60------70 74---- 80
// 15---------------------40 43--43 50--------------------75
// 10----------------------------------------------------------------------85
//
// The items are stored in a binary tree with each node storing:
//
// MP: A middle point.
// IL: All intervals whose left value are completely to the left of the middle
// point. They are sorted in ascending order by their beginning point.
// IR: All intervals whose right value are completely to the right of the
// middle point. They are sorted in descending order by their ending point.
// LS: Left subtree.
// RS: Right subtree.
//
// As IL and IR will contain the same intervals, in order to optimize space,
// instead of storing intervals on each node, we use two vectors that will
// contain the intervals described by IL and IR. Each node will contain an
// index into that vector (global bucket), to indicate the beginning of the
// intervals assigned to the node.
//
// The following is the output from print():
//
// 0: MP:43 IR [10,85] [31,56] [36,54] [39,50] [43,43]
// 0: MP:43 IL [10,85] [31,56] [36,54] [39,50] [43,43]
// 1: MP:25 IR [25,41] [15,40] [20,30]
// 1: MP:25 IL [15,40] [20,30] [25,41]
// 2: MP:15 IR [12,21] [11,16]
// 2: MP:15 IL [11,16] [12,21]
// 2: MP:36 IR []
// 2: MP:36 IL []
// 3: MP:31 IR [30,35]
// 3: MP:31 IL [30,35]
// 1: MP:61 IR [50,75] [60,70] [49,65] [55,61]
// 1: MP:61 IL [49,65] [50,75] [55,61] [60,70]
// 2: MP:74 IR [74,80] [71,79]
// 2: MP:74 IL [71,79] [74,80]
//
// with:
// 0: Root Node.
// MP: Middle point.
// IL: Intervals to the left (in ascending order by beginning point).
// IR: Intervals to the right (in descending order by ending point).
//
// Root
// |
// V
// +------------MP:43------------+
// | IL IR |
// | [10,85] [10,85] |
// LS | [31,56] [31,56] | RS
// | [36,54] [36,54] |
// | [39,50] [39,50] |
// | [43,43] [43,43] |
// V V
// +------------MP:25------------+ MP:61------------+
// | IL IR | IL IR |
// | [15,40] [25,41] | [49,65] [50,75] |
// LS | [20,30] [15,40] | RS [50,75] [60,70] | RS
// | [25,41] [20,30] | [55,61] [49,65] |
// | | [60,70] [55,61] |
// V V V
// MP:15 +-------MP:36 MP:74
// IL IR | IL IR IL IR
// [11,16] [12,21] LS | [] [] [71,79] [74,80]
// [12,21] [11,16] | [74,80] [71,79]
// V
// MP:31
// IL IR
// [30,35] [30,35]
//
// The creation of an interval tree is done in 2 steps:
// 1) Insert the interval items by calling
// void insert(PointT Left, PointT Right, ValueT Value);
// Left, Right: the interval left and right limits.
// Value: the data associated with that specific interval.
//
// 2) Create the interval tree by calling
// void create();
//
// Once the tree is created, it is switched to query mode.
// Query the tree by using iterators or container.
//
// a) Iterators over intervals overlapping the given point with very weak
// ordering guarantees.
// find_iterator begin(PointType Point) const;
// find_iterator end() const;
// Point: a target point to be tested for inclusion in any interval.
//
// b) Container:
// IntervalReferences getContaining(PointT Point);
// Point: a target point to be tested for inclusion in any interval.
// Returns vector with all the intervals containing the target point.
// -- Reduction to SSA construction --
// There are two disjoint paths from A to X, if a certain variant of SSA
// construction places a phi node in X under the following set-up scheme.
//
// This variant of SSA construction ignores incoming undef values.
// That is paths from the entry without a definition do not result in
// phi nodes.
//
// entry
// / \
// A \
// / \ Y
// B C /
// \ / \ /
// D E
// \ /
// F
//
// Assume that A contains a divergent branch. We are interested
// in the set of all blocks where each block is reachable from A
// via two disjoint paths. This would be the set {D, F} in this
// case.
// To generally reduce this query to SSA construction we introduce
// a virtual variable x and assign to x different values in each
// successor block of A.
//
// entry
// / \
// A \
// / \ Y
// x = 0 x = 1 /
// \ / \ /
// D E
// \ /
// F
//
// Our flavor of SSA construction for x will construct the following
//
// entry
// / \
// A \
// / \ Y
// x0 = 0 x1 = 1 /
// \ / \ /
// x2 = phi E
// \ /
// x3 = phi
//
// The blocks D and F contain phi nodes and are thus each reachable
// by two disjoins paths from A.
//
// -- Remarks --
// * In case of loop exits we need to check the disjoint path criterion for loops.
// To this end, we check whether the definition of x differs between the
// loop exit and the loop header (_after_ SSA construction).
//
// -- Known Limitations & Future Work --
// * The algorithm requires reducible loops because the implementation
// implicitly performs a single iteration of the underlying data flow analysis.
// This was done for pragmatism, simplicity and speed.
//
// Relevant related work for extending the algorithm to irreducible control:
// A simple algorithm for global data flow analysis problems.
// Matthew S. Hecht and Jeffrey D. Ullman.
// SIAM Journal on Computing, 4(4):519–532, December 1975.
//
// * Another reason for requiring reducible loops is that points of
// synchronization in irreducible loops aren't 'obvious' - there is no unique
// header where threads 'should' synchronize when entering or coming back
// around from the latch.
//===----------------------------------------------------------------------===//
// SSAIfConv
//===----------------------------------------------------------------------===//
//
// The SSAIfConv class performs if-conversion on SSA form machine code after
// determining if it is possible. The class contains no heuristics; external
// code should be used to determine when if-conversion is a good idea.
//
// SSAIfConv can convert both triangles and diamonds:
//
// Triangle: Head Diamond: Head
// | \ / \_
// | \ / |
// | [TF]BB FBB TBB
// | / \ /
// | / \ /
// Tail Tail
//
// Instructions in the conditional blocks TBB and/or FBB are spliced into the
// Head block, and phis in the Tail block are converted to select instructions.
//
/// ValidForkedDiamond - Returns true if the 'true' and 'false' blocks (along
/// with their common predecessor) form a diamond if a common tail block is
/// extracted.
/// While not strictly a diamond, this pattern would form a diamond if
/// tail-merging had merged the shared tails.
/// EBB
/// _/ \_
/// | |
/// TBB FBB
/// / \ / \
/// FalseBB TrueBB FalseBB
/// Currently only handles analyzable branches.
/// Specifically excludes actual diamonds to avoid overlap.
// If bottom of block BB has only one successor OldTop, in most cases it is
// profitable to move it before OldTop, except the following case:
//
// -->OldTop<-
// | . |
// | . |
// | . |
// ---Pred |
// | |
// BB-----
//
// If BB is moved before OldTop, Pred needs a taken branch to BB, and it can't
// layout the other successor below it, so it can't reduce taken branch.
// In this case we keep its original layout.
// Exact first use:
// ----------------
//
// Consider the following motivating example:
//
// int foo() {
// char b1[1024], b2[1024];
// if (...) {
// char b3[1024];
// <uses of b1, b3>;
// return x;
// } else {
// char b4[1024], b5[1024];
// <uses of b2, b4, b5>;
// return y;
// }
// }
//
// In the code above, "b3" and "b4" are declared in distinct lexical
// scopes, meaning that it is easy to prove that they can share the
// same stack slot. Variables "b1" and "b2" are declared in the same
// scope, meaning that from a lexical point of view, their lifetimes
// overlap. From a control flow pointer of view, however, the two
// variables are accessed in disjoint regions of the CFG, thus it
// should be possible for them to share the same stack slot. An ideal
// stack allocation for the function above would look like:
//
// slot 0: b1, b2
// slot 1: b3, b4
// slot 2: b5
//
// Achieving this allocation is tricky, however, due to the way
// lifetime markers are inserted. Here is a simplified view of the
// control flow graph for the code above:
//
// +------ block 0 -------+
// 0| LIFETIME_START b1, b2 |
// 1| <test 'if' condition> |
// +-----------------------+
// ./ \.
// +------ block 1 -------+ +------ block 2 -------+
// 2| LIFETIME_START b3 | 5| LIFETIME_START b4, b5 |
// 3| <uses of b1, b3> | 6| <uses of b2, b4, b5> |
// 4| LIFETIME_END b3 | 7| LIFETIME_END b4, b5 |
// +-----------------------+ +-----------------------+
// \. /.
// +------ block 3 -------+
// 8| <cleanupcode> |
// 9| LIFETIME_END b1, b2 |
// 10| return |
// +-----------------------+
//
// If we create live intervals for the variables above strictly based
// on the lifetime markers, we'll get the set of intervals on the
// left. If we ignore the lifetime start markers and instead treat a
// variable's lifetime as beginning with the first reference to the
// var, then we get the intervals on the right.
//
// LIFETIME_START First Use
// b1: [0,9] [3,4] [8,9]
// b2: [0,9] [6,9]
// b3: [2,4] [3,4]
// b4: [5,7] [6,7]
// b5: [5,7] [6,7]
//
// For the intervals on the left, the best we can do is overlap two
// variables (b3 and b4, for example); this gives us a stack size of
// 4*1024 bytes, not ideal. When treating first-use as the start of a
// lifetime, we can additionally overlap b1 and b5, giving us a 3*1024
// byte stack (better).
/// Tracker for what values are in machine locations. Listens to the Things
/// being Done by various instructions, and maintains a table of what machine
/// locations have what values (as defined by a ValueIDNum).
///
/// There are potentially a much larger number of machine locations on the
/// target machine than the actual working-set size of the function. On x86 for
/// example, we're extremely unlikely to want to track values through control
/// or debug registers. To avoid doing so, MLocTracker has several layers of
/// indirection going on, described below, to avoid unnecessarily tracking
/// any location.
///
/// Here's a sort of diagram of the indexes, read from the bottom up:
///
/// Size on stack Offset on stack
/// \ /
/// Stack Idx (Where in slot is this?)
/// /
/// /
/// Slot Num (%stack.0) /
/// FrameIdx => SpillNum /
/// \ /
/// SpillID (int) Register number (int)
/// \ /
/// LocationID => LocIdx
/// |
/// LocIdx => ValueIDNum
///
/// The aim here is that the LocIdx => ValueIDNum vector is just an array of
/// values in numbered locations, so that later analyses can ignore whether the
/// location is a register or otherwise. To map a register / spill location to
/// a LocIdx, you have to use the (sparse) LocationID => LocIdx map. And to
/// build a LocationID for a stack slot, you need to combine identifiers for
/// which stack slot it is and where within that slot is being described.
///
/// Register mask operands cause trouble by technically defining every register;
/// various hacks are used to avoid tracking registers that are never read and
/// only written by regmasks.
// The SSACCmpConv class performs ccmp-conversion on SSA form machine code
// after determining if it is possible. The class contains no heuristics;
// external code should be used to determine when ccmp-conversion is a good
// idea.
//
// CCmp-formation works on a CFG representing chained conditions, typically
// from C's short-circuit || and && operators:
//
// From: Head To: Head
// / | CmpBB
// / | / |
// | CmpBB / |
// | / | Tail |
// | / | | |
// Tail | | |
// | | | |
// ... ... ... ...
//
// The Head block is terminated by a br.cond instruction, and the CmpBB block
// contains compare + br.cond. Tail must be a successor of both.
// This pass tries to make consecutive compares of values use same operands to
// allow CSE pass to remove duplicated instructions. For this it analyzes
// branches and adjusts comparisons with immediate values by converting:
// * GE -> GT
// * GT -> GE
// * LT -> LE
// * LE -> LT
// and adjusting immediate values appropriately. It basically corrects two
// immediate values towards each other to make them equal.
//
// Consider the following example in C:
//
// if ((a < 5 && ...) || (a > 5 && ...)) {
// ~~~~~ ~~~~~
// ^ ^
// x y
//
// Here both "x" and "y" expressions compare "a" with "5". When "x" evaluates
// to "false", "y" can just check flags set by the first comparison. As a
// result of the canonicalization employed by
// SelectionDAGBuilder::visitSwitchCase, DAGCombine, and other target-specific
// code, assembly ends up in the form that is not CSE friendly:
// This function does a whole lot of voodoo to determine if the tests are
// equivalent without and with a mask. Essentially what happens is that given a
// DAG resembling:
//
// +-------------+ +-------------+ +-------------+ +-------------+
// | Input | | AddConstant | | CompConstant| | CC |
// +-------------+ +-------------+ +-------------+ +-------------+
// | | | |
// V V | +----------+
// +-------------+ +----+ | |
// | ADD | |0xff| | |
// +-------------+ +----+ | |
// | | | |
// V V | |
// +-------------+ | |
// | AND | | |
// +-------------+ | |
// | | |
// +-----+ | |
// | | |
// V V V
// +-------------+
// | CMP |
// +-------------+
//
// The AND node may be safely removed for some combinations of inputs. In
// particular we need to take into account the extension type of the Input,
// the exact values of AddConstant, CompConstant, and CC, along with the nominal
// width of the input (this can work for any width inputs, the above graph is
// specific to 8 bits.
// For predicated nodes where the entire operation is controlled by a governing
// predicate, please stick to a similar naming convention as used for the
// ISD nodes:
//
// SDNode <=> AArch64ISD
// -------------------------------
// _m<n> <=> _MERGE_OP<n>
// _mt <=> _MERGE_PASSTHRU
// _z <=> _MERGE_ZERO
// _p <=> _PRED
//
// Given the context of this file, it is not strictly necessary to use _p to
// distinguish predicated from unpredicated nodes given that most SVE
// instructions are predicated.
// The diagram below shows the steps involved in the conversion of a predicated
// store instruction to its .new predicated new-value form.
//
// Note: It doesn't include conditional new-value stores as they can't be
// converted to .new predicate.
//
// p.new NV store [ if(p0.new)memw(R0+#0)=R2.new ]
// ^ ^
// / \ (not OK. it will cause new-value store to be
// / X conditional on p0.new while R2 producer is
// / \ on p0)
// / \.
// p.new store p.old NV store
// [if(p0.new)memw(R0+#0)=R2] [if(p0)memw(R0+#0)=R2.new]
// ^ ^
// \ /
// \ /
// \ /
// p.old store
// [if (p0)memw(R0+#0)=R2]
//
// The following set of instructions further explains the scenario where
// conditional new-value store becomes invalid when promoted to .new predicate
// form.
//
// { 1) if (p0) r0 = add(r1, r2)
// 2) p0 = cmp.eq(r3, #0) }
//
// 3) if (p0) memb(r1+#0) = r0 --> this instruction can't be grouped with
// the first two instructions because in instr 1, r0 is conditional on old value
// of p0 but its use in instr 3 is conditional on p0 modified by instr 2 which
// is not valid for new-value stores.
// Predicated new value stores (i.e. if (p0) memw(..)=r0.new) are excluded
// from the "Conditional Store" list. Because a predicated new value store
// would NOT be promoted to a double dot new store. See diagram below:
// This function returns yes for those stores that are predicated but not
// yet promoted to predicate dot new instructions.
//
// +---------------------+
// /-----| if (p0) memw(..)=r0 |---------\~
// || +---------------------+ ||
// promote || /\ /\ || promote
// || /||\ /||\ ||
// \||/ demote || \||/
// \/ || || \/
// +-------------------------+ || +-------------------------+
// | if (p0.new) memw(..)=r0 | || | if (p0) memw(..)=r0.new |
// +-------------------------+ || +-------------------------+
// || || ||
// || demote \||/
// promote || \/ NOT possible
// || || /\~
// \||/ || /||\~
// \/ || ||
// +-----------------------------+
// | if (p0.new) memw(..)=r0.new |
// +-----------------------------+
// Double Dot New Store
//
// Returns the most basic instruction for the .new predicated instructions and
// new-value stores.
// For example, all of the following instructions will be converted back to the
// same instruction:
// 1) if (p0.new) memw(R0+#0) = R1.new --->
// 2) if (p0) memw(R0+#0)= R1.new -------> if (p0) memw(R0+#0) = R1
// 3) if (p0.new) memw(R0+#0) = R1 --->
//
// To understand the translation of instruction 1 to its original form, consider
// a packet with 3 instructions.
// { p0 = cmp.eq(R0,R1)
// if (p0.new) R2 = add(R3, R4)
// R5 = add (R3, R1)
// }
// if (p0) memw(R5+#0) = R2 <--- trying to include it in the previous packet
// Here's a delta network for 8 inputs, only the switching routes are
// shown:
//
// Steps:
// |- 1 ---------------|- 2 -----|- 3 -|
//
// Inp[0] *** *** *** *** Out[0]
// \ / \ / \ /
// \ / \ / X
// \ / \ / / \
// Inp[1] *** \ / *** X *** *** Out[1]
// \ \ / / \ / \ /
// \ \ / / X X
// \ \ / / / \ / \
// Inp[2] *** \ \ / / *** X *** *** Out[2]
// \ \ X / / / \ \ /
// \ \ / \ / / / \ X
// \ X X / / \ / \
// Inp[3] *** \ / \ / \ / *** *** *** Out[3]
// \ X X X /
// \ / \ / \ / \ /
// X X X X
// / \ / \ / \ / \
// / X X X \
// Inp[4] *** / \ / \ / \ *** *** *** Out[4]
// / X X \ \ / \ /
// / / \ / \ \ \ / X
// / / X \ \ \ / / \
// Inp[5] *** / / \ \ *** X *** *** Out[5]
// / / \ \ \ / \ /
// / / \ \ X X
// / / \ \ / \ / \
// Inp[6] *** / \ *** X *** *** Out[6]
// / \ / \ \ /
// / \ / \ X
// / \ / \ / \
// Inp[7] *** *** *** *** Out[7]
//
//
// Reverse delta network is same as delta network, with the steps in
// the opposite order.
//
//
// Benes network is a forward delta network immediately followed by
// a reverse delta network.
// There are four SLOTS (four parallel pipelines) in Hexagon V60 machine.
// This file describes that machine information.
//
// |===========|==================================================|
// | PIPELINE | Instruction Classes |
// |===========|==================================================|
// | SLOT0 | LD ST ALU32 MEMOP NV SYSTEM |
// |-----------|--------------------------------------------------|
// | SLOT1 | LD ST ALU32 |
// |-----------|--------------------------------------------------|
// | SLOT2 | XTYPE ALU32 J JR |
// |-----------|--------------------------------------------------|
// | SLOT3 | XTYPE ALU32 J CR |
// |===========|==================================================|
//
//
// In addition to using the above SLOTS, there are also six vector pipelines
// in the CVI co-processor in the Hexagon V60 machine.
//
// |=========| |=========| |=========| |=========| |=========| |=========|
// SLOT | CVI_LD | |CVI_MPY3 | |CVI_MPY2 | |CVI_SHIFT| |CVI_XLANE| | CVI_ST |
// ==== |=========| |=========| |=========| |=========| |=========| |=========|
// S0-3 | | | CVI_VA | | CVI_VA | | CVI_VA | | CVI_VA | | |
// S2-3 | | | CVI_VX | | CVI_VX | | | | | | |
// S0-3 | | | | | | | | | CVI_VP | | |
// S0-3 | | | | | | | CVI_VS | | | | |
// S0-1 |(CVI_LD) | | CVI_LD | | CVI_LD | | CVI_LD | | CVI_LD | | |
// S0-1 |(C*TMP_LD) | | | | | | | | | |
// S01 |(C*_LDU) | | | | | | | | C*_LDU | | |
// S0 | | | CVI_ST | | CVI_ST | | CVI_ST | | CVI_ST | |(CVI_ST) |
// S0 | | | | | | | | | | |(C*TMP_ST)
// S01 | | | | | | | | | VSTU | |(C*_STU) |
// |=========| |=========| |=========| |=========| |=========| |=========|
// |=====================| |=====================|
// | CVI_MPY2 & CVI_MPY3 | |CVI_XLANE & CVI_SHIFT|
// |=====================| |=====================|
// S0-3 | CVI_VA_DV | | CVI_VA_DV |
// S0-3 | | | CVI_VP_DV |
// S2-3 | CVI_VX_DV | | |
// |=====================| |=====================|
// |=====================================================================|
// S0-3 | CVI_HIST Histogram |
// S0123| CVI_VA_EXT Extract |
// |=====================================================================|
/// ------------+---------+---------+---------+---------
/// F E D C | B A 9 | 8 7 6 | 5 4 3 | 2 1 0
/// ------------+---------+---------+---------+---------
/// 0 0 0 0 | REG | 1 0 0 | MODE | REG
/// ------------+---------+---------+---------+---------
// Example:
// ^ ^
// dy| dx| (MatMul Gradient Graph)
// | |
// MatMul_1 MatMul_2
// ^ ^ ^ ^
// | |----------| |
// | ^ |
// | dz| |
// | | |
// | Const_3 |
// | |
// | ^ |
// | z| | (MatMul Forward Graph)
// | | |
// | MatMul_0 |
// | / \ |
// | ^ ^ |
// | | | |
// |---x| y|---|
// | |
// | |
// Const_0 Const_1
//
// input1
// |
// slice
// |
// cast
// |
// output
// Basic LSTM Cell:
//
// 1name = name is at input index 1
// name1 = name is at output index 1
//
// 0input 1prev_activ
// \ /
// [[concat]]
// \
// concat_temp2 2weights 3biases
// \ / /
// [[fully-connected]]
// \
// activ_temp3 4prev_state
// \ /
// [[LSTM]]
// / \
// new_state1 activation0
//
// For full LSTM cells, see this blog post:
// https://colah.github.io/posts/2015-08-Understanding-LSTMs/
// In addition to Peephole connections and Combined Input Forget Gates (CIFG)
// described in that post, this code also adds the following optional features:
// - Configurable activations (sigmoid or TANH)
// - L2 Normalization of gates: https://arxiv.org/abs/1607.06450
// - Output projection:
// https://www.isca-speech.org/archive/interspeech_2014/i14_0338.html
// - Configurable clipping of cell state and output state.
// Fuses nodes that have auto output with auto input node using the following
// rules.
//
// Source graph:
// A B C
// \ | /
// D
//
// - A, B and C each have a single output marked as AUTO
// - Each output is used only by D
// - D has all inputs marked as AUTO
//
// Result: in the best case a single node that does (A,B,C)+D operations.
//
// Basic LSTMCell gates.
//
// inputs: 0 1
// activ_temp prev_state
// \ /
// [[LSTM gates]]
// / \
// new_state activation
// outputs: 0 1
//
// The size of activ_temp should be 4x size of new_state.
// The size of prev_state == new_state == activation.
//
// This is a model with two ops:
//
// input1 ---->
// ADD --
// input2 --> |
// -->
// SUB --> output
// input3 ---------------->
//
// Create a model with custom validation graph.
//
// 'validation model' (new subgraph)
// input (batch_size)
// |
// +-----------------------+
// |'main_model' (0) |
// | +---------------+ |
// | |input +---+ |
// | +---------------+ | |
// | ~ |
// | +---------------+ | |
// | |outputs +<--+ |
// | +---------------+ |
// | |
// +-----------------------+
// |
// output (batch_size)
//
// The new model contains all the information from main_model, with an extra
// subgraph for validation purposes. The validation graph calls the primary
// subgraph with batch_size. The input data is embedded to the validation graph.
// custom_input should have the same order as the input in the main_model. E.g.
// custom_input[i] will be mapped to main_model.input[i].
// Class for building the validation entry-point graph that calls into the main
// graph and a metrics graph. Like this (boxes are tensors with plural names
// meaning possibly multiple tensors, arrows are ops and numbers in parentheses
// are subgraph indices):
// +--------------------------------------+
// | Graph created by this class (1) |
// | |
// | +-----------input-+ |
// | |jpeg input | |
// | +-----+-----------+ |
// | | |
// | | decode |
// | v |
// | +-----+-----------+ |
// | |quantized image | |
// | +-----+-----------+ | +-----------------------+
// | | | |'main_model' (0) |
// | | dequantize (optional) | | +---------------+ |
// | v | | |input +---+ |
// | +-----+-----------+ | | +---------------+ | |
// | |float image | | | ~ |
// | +-----+-----------+ | | +---------------+ | |
// | | call | | |outputs +<--+ |
// | +<------------------------------->+ +---------------+ |
// | v | | |
// | +-----+-----output+ +---------input+ | +-----------------------+
// | |actual outputs | |golden outputs| |
// | +-----+-----------+ +-----------+--+ |
// | | | |
// | | dequantize (optional) | |
// | | | |
// | +-----+-------------------------+-+ |
// | | dequantized actual and golden | |
// | | outputs (validation inputs) | |
// | +-----+---------------------------+ | +-----------------------+
// | | call | |'validation model' (2) |
// | +<------------------------------->+ |
// | v | | +---------------+ |
// | +-----+-----output+ | | |inputs +---+ |
// | |results | | | +---------------+ | |
// | +-----------------+ | | ~ |
// | | | +---------------+ | |
// | | | |outputs +<--+ |
// | | | +---------------+ |
// | | | |
// +--------------------------------------+ +-----------------------+
//
// It's important the 'main_model' has subgraph index 0 so that it is used as
// the primary subgraph by the TFLite interpreter. The other indices are
// arbitrary.
// TODO(b/172541832): Handle a main model with more than one subgraph.
//
// Note that the jpeg input is marked as an input in this graph, as TFLite
// graphs must have inputs. However, it will be pre-filled from the jpeg_data
// and doesn't need to be filled by the user of the model.
// Matches %iota generated from the following mlir codes (rank 2 example):
//
// %iota = mhlo.constant dense<[[0, 1, 2, ..., L],
// [0, 1, 2, ..., L]
// ...
// [0, 1, 2, ..., L]]>,
// where $dimensions is of size 1.
//
// StridedArrayViews are used to check the iota property across the constant
// data so that the iota dimension does not need to be the (inner) z-dimension.
// Converts a dag of HLOs representing floor_div to tf.FloorDiv.
// The pattern matched executes the following computation:
//
// rem = remainder(arg0, arg1)
// for i in 0 to len(arg1):
// rem[i] = arg0[i] - rem[i] / arg1[i]
// if (rem[i] != 0 && sign(arg1[i]) != sign(rem[i]))
// rem[i] -= 1.0
// return round_nearest_afz(rem)
// As a dag this looks like the following:
// round
// |
// -------- select
// | | \
// && + div
// / | / \
// != != div -1
// / | / | / |
// rem 0.0 sn sn1 - $1
// / | | | / |
// $0 $1 $1 rem $0 rem
// Note that named operators like 'sn' and 'sn1' are different values produced by
// the same function in this case the sign function. Named values like 'div'
// refer to the same value produced by the same function, in this case division.
// Mathematical symbols do not indicate a re-use of the value.
// Lowers AddN op to a sequence of AddV2 ops to accumulate operands.
//
// Note that to improve the parallelism, AddN op uses tree-based reduction.
// For example, tf.AddN([0, 1, 2, 3, 4]) behaves as follows:
//
// 0 1 2 3 4
// | | | | |
// ------- ------- |
// | | |
// 5 6 |
// | | |
// ------------- |
// | |
// 7 |
// | |
// ----------------
// |
// 8
//
// Example:
//
// %result = "tf.AddN"(%0, %1, %2)
//
// is lowered to:
//
// %sum0 = "tf.AddV2"(%0, %1)
// %result = "tf.AddV2"(%sum0, %2)
//
// While
//
// %result = "tf.AddN"(%0, %1, %2, %3, %4)
//
// is lowered to:
//
// %sum0 = "tf.AddV2"(%0, %1)
// %sum1 = "tf.AddV2"(%2, %3)
// %sum2 = "tf.AddV2"(%sum0, %sum1)
// %result = "tf.AddV2"(%sum2, %4)
//
// Return the iterator of the IfRegion Op. This is the last IfRegion
// in the segment.
// For example, we have the following sequence of IfRegions
// `````
// We implement bilinear interpolation by upsampling followed by convolution.
// The basic idea is as follows. To scale from NxN to RxR:
//
// 1. S := (N - 1) / gcd(N-1, R-1)
// 2. k := (R - 1) / gcd(N-1, R-1)
// 3. Convolution((2k-1)x(2k-1), stride=S, lhs_dilation=k, padding=k-1)
//
// For example, to Scale from 7x7 -> 15x15:
//
// 1. S := (7-1) / gcd(7-1, 15-1) = 6 / gcd(6, 14) = 6 / 2 = 3
// 2. k := (15 - 1) / gcd(7-1, 15-1) = 14 / gcd(6, 14) = 14 / 2 = 7
// 3. Convolution(15x15, stride=3, lhs_dilation=7, padding=2)
//
//
// The 7x7 -> 15x15 case is much too large to write out in full as an
// example. The smallest interesting example is 3x3 -> 4x4.
//
// S := 2
// k := 3
//
// 00 03 06 00 00 00 00 00 00 00 00 00 00 00 00 02 04 06
// 09 12 15 -> 00 00 00 00 00 00 00 00 00 00 00 -> 06 08 10 12
// 18 21 24 00 00 00 00 00 03 00 00 06 00 00 12 14 16 18
// 00 00 00 00 00 00 00 00 00 00 00 18 20 22 24
// 00 00 00 00 00 00 00 00 00 00 00
// 00 00 09 00 00 12 00 00 15 00 00
// 00 00 00 00 00 00 00 00 00 00 00
// 00 00 00 00 00 00 00 00 00 00 00
// 00 00 18 00 00 21 00 00 24 00 00
// 00 00 00 00 00 00 00 00 00 00 00
// 00 00 00 00 00 00 00 00 00 00 00
//
// with the following convolutional kernel, with stride [2, 2]:
// 1 2 3 2 1
// 2 4 6 4 2
// 1/9 * 3 6 9 6 3
// 2 4 6 4 2
// 1 2 3 2 1
// Note that the convolution kernel matrix is separable and thus we can instead
// use 2 consecutive 1D kernel of the dimension 2k-1, along each axis.
// DEALING WITH CYCLES
// -------------------
//
// We map Merge nodes that are the target of a backedge to AndRecurrence
// instances. An AndRecurrence with start() = S and step() = X, printed as
// {S,&,X}, *roughly* represents the infinite list of predicates
// [S,S&X,S&X&X,S&X&X, ...]. So {S,&,X} can be used to represent the predicate
// for Merge in a graph like:
//
// Init
// |
// v
// Merge <-----------+
// | |
// v |
// Incr |
// | |
// v |
// Switch <- Cond |
// | |
// v (oidx: 1) |
// | |
// +---------------+
//
// Where S is the predicate for Init and X is the predicate that asserts that
// Cond is true. {S,&,X} states that Merge is live on the first "iteration" iff
// S is true, live on the second iteration iff "S&X" is true, live on the third
// iteration iff "S&X&X" is true etc. There is a subtlety here, S&X&X would
// normally be equivalent to S&X which isn't quite what we want to represent.
// Instead we want {S,&,X} to denote the infinite list [S, S&X,
// S&X&X',S&X&X'&X'', ...] where X, X', X'' are predicates that assert Cond is
// true on iteration 0, 1, 2 respectively. This is made more precise in the
// comment on the AndRecurrence class.
// TensorList is represented by a tuple.
// - The first part of the tuple is a buffer containing all the tensors,
// - The following parts are push indices for all nested levels of
// TensorLists. The last part is push index for the outermost TensorList.
//
// TensorList, as it name suggests, is conceptually a list of tensors. In actual
// representation of a non-nested TensorList, the buffer shape is
// [element_shape, tensor_list_size]. We will call tensor_list_size "leading
// dimension" below. Notice that the leading dimension must be a compile time
// constant, since it's part of the buffer shape.
//
// Example: consider a 3-level nested TensorList whose element type is scalar.
// Assume inner TensorList has leading dimension 4, middle TensorList has 3,
// and outer TensorList has 3.
// Assume that lower cased letter means there is data in that position, and "."
// means there is no data in that position.
// First element of outer TensorList:
// [ a . . . ]
// [ b c . . ]
// [ d e f . ]
// Second element of outer TensorList:
// [ g h i . ]
// [ j k . . ]
// [ . . . . ]
// Third element: not pushed yet.
//
// The first part of the tuple is an array of shape [3, 3, 4] containing data.
// The second part is an array of shape [3, 3], each element is push index
// for the inner TensorList. In this case, its values are:
// [ 1 2 3 ]
// [ 3 2 . ]
// [ . . . ]
// The third part is an array of shape [3], each element is push index for
// the middle TensorList. In this case, its values are:
// [ 3 ]
// [ 2 ]
// [ . ]
// The forth (and last) part is a scalar. It's the push index for the outer
// TensorList. In this case, its values is 2.
//
// Now imagine we need to push the following element to the outer TensorList:
// [ l . . . ]
// [ m n . . ]
// [ . . . . ]
// This element is represented by a tuple of 3 parts:
// First part is all data.
// Second part is push indices for the inner TensorList, which is [ 1 2 . ].
// Third part is push index for the middle TensorList, which is 2.
// Now let's do the push.
// First, we append its data to outer TensorList's data.
// Then we start to deal with push indices. Similar to data, we append push
// indices for each level of TensorList.
// For the inner TensorList: append push indices for the pushed element.
// [ 1 2 3 ] [ 1 2 3 ]
// [ 3 2 . ] + = [ 3 2 . ]
// [ . . . ] [ 1 2 . ] [ 1 2 . ]
// For the middle TensorList: append push indices for the pushed element.
// [ 3 ] [ 3 ]
// [ 2 ] + = [ 2 ]
// [ . ] [ 2 ] [ 2 ]
// For the outer TensorList: just add 1.
// 2 + 1 = 3
//
// Popping an element from the outer TensorList also follows a similar process.
// First part is data. We get data by slicing data with push index for outer
// TensorList (which is 3).
// Second part is push indices for inner TensorList. We get it by slicing
// push indices for inner TensorList with push index for outer TensorList (which
// is 3).
// [ 1 2 3 ]
// [ 3 2 . ]
// [ 1 2 . ] ===> This is what we want
// Third part is push index for middle TensorList. We get it by slicing
// push indices for middle TensorList with push index for outer TensorList
// (which is 3).
// [ 3 ]
// [ 2 ]
// [ 2 ] ===> This is what we want
// Match on variadic reduce which computes and returns (min, arg_min).
//
// p0 p2 p1 p3
// /|\ \/ |\ |\ /|
// / | \/\ | \ | \ / |
// / | /\ \| | | /\ |
// Ne Lt | \ | | | ||
// \ / | |\ | | / ||
// Or / / Eq Lt ||
// | / / \ / //
// | | | And //
// | | | | //
// select select
// \ /
// tuple
//
// Create a mask for grouped convolution that will make a normal convolution
// produce the same results as a grouped convolution. For a [2, 1, 6]
// filter this returns a [2, 3, 6] mask
// 1 1 0 0 0 0
// 0 0 1 1 0 0
// 0 0 0 0 1 1
//
// 1 1 0 0 0 0
// 0 0 1 1 0 0
// 0 0 0 0 1 1
//
// The first step is to create a rank 1 constant:
// 0 1 2
//
// This is broadcasted to
// 0 0 0 0 0 0
// 1 1 1 1 1 1
// 2 2 2 2 2 2
//
// 0 0 0 0 0 0
// 1 1 1 1 1 1
// 2 2 2 2 2 2
//
// Then we create another rank 1 constant
// 0 0 1 1 2 2
//
// This is broadcasted to
// 0 0 1 1 2 2
// 0 0 1 1 2 2
// 0 0 1 1 2 2
//
// 0 0 1 1 2 2
// 0 0 1 1 2 2
// 0 0 1 1 2 2
//
// Finally we use the Eq op of these two broadcasted constants and get the
// desired mask.
// Deep copy the given instructions 'from' and 'to' at the ShapeIndexes given in
// 'indices_to_copy'. Add control edges from the respective kCopy instructions
// in deep copy of 'from' to the respective kCopy instruction in the deep copy
// of 'to'.
//
// Requirements: 'from' and 'to' must have compatible shapes.
//
// For example, suppose 'from' and 'to' are two-element tuples where index 0 is
// the only index to copy. Prior to deep-copying we have:
//
//
// 'from'
// |
// ...
// |
// 'to'
//
// DeepCopyAndAddControlEdges produces:
//
// 'from'
// / \
// GTE GTE
// | |
// Copy |
// / \ /
// | Tuple
// | |
// ctrl ...
// edge |
// | |
// | 'to'
// | / \
// | GTE GTE
// \ | |
// Copy |
// \ /
// Tuple
//
// Tests Copy Insertion when a while feeds another while
// PARAMETER
// | |
// GTE(0) GTE(1)
// | |
// X = CreateTuple(GTE(0), GTE(1))
// |
// WHILE(X) (root)
// Test flattening of a nested calling computations.
//
// Entry
// / \
// \ /
// B
// / \
// \ /
// C
//
// Class implementing a list scheduler of HLO instructions which produces a
// sequence which minimizes memory usage by preferring to schedule the node that
// frees bigger buffer and defines smaller outputs.
//
// Note that list scheduler is a greedy algorithm which cannot guarantee a
// global optimal solution. As a counterexample, considering the following
// graph:
//
// +--> B ===> C -------+
// A -> | |
// | v
// +--> D ---> F=======>G
// | ^
// | |
// +--> E -----+
//
// --> : Buffer with size 1
// ==> : Buffer with size 2
//
// The list scheduler will always try to defer scheduling B in a greedy way
// since its output buffer is bigger than input. The sequence it creates will
// be:
// A D E F B C G
// , which has a maximum memory usage of 6 (B is alive while F is executing).
//
// An optimal way to schedule the previous graph is:
// A B C D E F G
// , which has a maximum memory usage of 5 (when F is executing).
//
// Class which maintains an ordered list of instructions with fast insertion
// before arbitrary elements.
//
// This is a skip list structure that has two lanes: express lane and slow lane.
// All nodes are presented on the slow lane but a node can be promoted into
// express lane for fast iteration.
//
// In the following case, node 2 and node + 1 are connected via an express lane.
// +--------------------------+----------->: Express lane
// | |
// node1<-> node 2 <-> .. <-> node n <-> node n+1 <->...: Slow lane
//
// Tree looks like this:
//
// add1
// |
// +- reshape2 - param2
// |
// +- reshape3 - add0
// |
// + reshape0 - param0
// |
// + reshape1 - param1
//
// We expect reshape{0,1} AND reshape{2,3} to be lifted.
// Computes a dot product between "[M,K]{0,1} lhs" with a [K,1] vector (the
// layout of the vector does not matter). This implementation uses a tiling
// scheme to improve performance.
//
// We logically separate the LHS matrix into four segments:
//
// +----------------------+---+
// | | |
// | | |
// | A | B |
// | | |
// | | |
// | | |
// +----------------------+---+
// | C | D |
// +----------------------+---+
//
// where A is the largest submatrix of the LHS that can be evenly divided into
// tiles. For each tile in A, assuming tile_rows_ == tile_cols_ == 4, we have:
//
// +---+---+---+---+ +--+--+--+--+
// |M00|M10|M20|M30| |V0|V1|V2|V3|
// +---+---+---+---+ +--+--+--+--+
// |M01|M11|M21|M31| and |V0|V1|V2|V3|
// +---+---+---+---+ +--+--+--+--+
// |M02|M12|M22|M32| |V0|V1|V2|V3|
// +---+---+---+---+ +--+--+--+--+
// |M03|M13|M23|M33| |V0|V1|V2|V3|
// +---+---+---+---+ +--+--+--+--+
//
// (Legend: rows are horizontal and columns are vertical; and each column is one
// llvm::Value of a vector type)
//
// where:
//
// a. The left tile is from the column major left matrix.
// b. The right tile is an elementwise broadcast of a [V0, V1, V2, V3]
// vector loaded from the RHS vector.
//
// As we iterate through the column dimension, we compute the change to the
// result vector by an elementwise multiplication between the two tiles above
// followed by a reduction along the major dimension:
//
// +-----------------------------------+
// | M00*V0 + M10*V1 + M20*V2 + M30*V3 |
// +-----------------------------------+
// | M01*V0 + M11*V1 + M21*V2 + M31*V3 |
// Result[R:R+4] += +-----------------------------------+
// | M02*V0 + M12*V1 + M22*V2 + M32*V3 |
// +-----------------------------------+
// | M03*V0 + M13*V1 + M23*V2 + M33*V3 |
// +-----------------------------------+
//
// Where R is the starting row for the tile.
//
// We have an inner epilogue loop to deal with the "C" submatrix and an outer
// epilogue loop to deal with the B,D submatrix.
//
// TODO(sanjoy): We should investigate if using gather loads and scatter stores
// can be used here have the same inner loop for both column-major and row-major
// matrix-vector products.
// An HLO pass that attempts to merge fusion instructions to reduce memory
// bandwidth requirements and kernel launch overhead.
//
// Consider the example below. On the left-hand side, op A is the producer and
// ops B and C are its consumers. FusionMerger duplicates producer ops and fuses
// them into all consumers. The result is depicted on the right-hand side below.
//
// p p
// | / \
// v / \
// A +fusion+ +fusion+
// / \ | A' | | A" |
// | | | | | | | |
// v v | v | | v |
// B C | B | | C |
// +------+ +------+
//
// Op A has been cloned twice and fused with B and C. The kernel launch overhead
// is reduced from 3 to 2. The memory bandwidth requirements may be reduced.
// We trade 1 read of input(A) + 1 write and 2 reads of output(A) for 2 reads of
// input(A). In general the achieveable savings in memory bandwidth depend on
// the differences in memory read and written and the number of consumers. The
// FusionMeger pass takes this into account when making fusion decisions.
//
// The pass traverses the HLO module in reverse post-order (defs before uses).
// Fusion instructions are merged into their users if some conditions are met:
// * The result of merging the fusion instruction into its users would not
// increase bytes transferred.
// * Producer ops are fusible with _all_ consumers. If they are not fusible with
// at least one consumers, they won't be fused at all.
// * Producers are kLoop fusion ops.
//
// None of these restrictions are necessary for correctness. In fact, lifting
// the latter two could be beneficial.
// The following illustrates the mechanism of the horizontal fusion. Before
// fusion, there are two trivial kernels in the illustrating example. One has
// only a Mul op, while the other consists of only an Add op. Since they are
// only consumed by the same (ROOT) tuple instruction, horizontal fusion is
// triggered.
//
// i0 i1 i2 i3
// | | | |
// v v v v
// Mul Add
// | |
// v v
// (ROOT) tuple
//
// We fuse into one of two possible patterns, depending on whether all the
// fused operations have the same shape or not.
//
// case 1: if Mul and Add's output shape and type are the same, then we fuse
// them into the below pattern: i0 i1 i2 i3
// | | | |
// v v v v
// Mul Add
// | |
// v v
// (ROOT) tuple
// the fused kernel will be kLoop type, i.e, GPU code is emitted through
// IrEmitterUnnested::EmitLoopFusion
//
// case 2: if Mul and Add's output shape are diffent, then we fuse them into
// the below pattern that adds extra indexing:
// i0 i1 i2 i3 +++ (Slice) Input Fusion
// | | | | +
// v v v v +
// Mul Add +
// | | +
// v v +
// Reshape0 Reshape1 +
// | | +
// v v +
// Concatenate +
// | | +
// v v +
// Slice0 Slice1 +++
// | |
// v v
// Reshape2 Reshape3
// | |
// v v
// (ROOT) tuple
//
// the fused kernel will be kInput type, and, the GPU code is emitted through
// IrEmitterUnnested::EmitInputFusibleNonStridedSlices
//
// In theory, the pattern in case 1 could also be fused into the case2 target
// graph, but we prefer to fuse into kLoop type, because the codegen for it does
// not have the slicing range check cost introduced by case 2 pattern.
// Multi-output fusion of sibling and producer-consumer instructions for the
// GPU backend to reduce memory bandwidth requirements.
//
// 0) Before multi- 1) Sibling multi- 2) Producer-consumer
// output fusion output fusion multi-output fusion
//
// p p p
// | | |
// v v v
// A A +-fusion--+
// / \ | | A |
// | | +-fusion--+ | / \ |
// v v | / \ | | B | |
// B C | B C | | | | |
// \ / | | | | | v v |
// v v | v v | | tuple |
// ROOT | tuple | +---------+
// +---------+ / \
// / \ gte_b gte_a
// gte_b gte_c | |
// | | | v
// \ / | C
// v v \ /
// ROOT v v
// ROOT
//
// Multi-output fusion ops have a tuple op at their root containing multiple
// elements as outputs. GetTupleElement ops (depicted as gte_* above) are
// inserted to extract tuple elements for consumers.
//
// The two different flavors of multi-output fusion this pass performs are
// depicted above.
// 1) Fusion of sibling ops reduces memory bandwidth requirements, because
// common input parameters have to be read only once.
// 2) Fusion of producer-consumer ops reduces memory bandwidth requirements by
// saving one read from memory. In the example above, B does not need to read
// the output of A from memory, while C still does (using gte_a).
// Note that sibling (1) and producer-consumer (2) multi-output fusion can be
// combined.
// Moves a cluster of memory-reducing nodes into the windowed dot-general loop
// on contracting dimensions. Such a loop has a dynamic slice on the
// non-windowed operand. If we move the input nodes into the loop, the
// dynamic-slice could be merged with them by later optimization passes, which
// reduces memory.
//
// small_operands small_operands
// | |
// input_nodes loop { |
// | => input_nodes
// loop { | |
// dynamic-slice dynamic-slice
// ... ...
// } }
//
// Later optimization passes (TpuPadSliceMover) will merge the dynamic slice
// with the input nodes.
// Regression test for b/31944287. x*y is used (at the same index) by all
// operands of the concat. We should emit x*y in three incoming basic blocks of
// the concat because these basic blocks are not control-equivalent.
//
// x*y
// / | \
// add1 add2 add3
// \ | /
// concat
// Add a restore subgraph for each variable and connect to the restore_all op.
// For each variable we add the following subgraph:
// Assign----restore_all
// | |
// RestoreV2 Variable
// Clones nodes to outside their cluster to avoid device-to-host copies. For
// instance, converts this:
//
// .....
// |
// v
// A_Clustered ====> C_Unclustered
// |
// v
// B_Clustered
//
// to:
//
// .....
// | |
// | +-------------+
// | |
// v v
// A_Clustered A_Unclustered ====> C_Unclustered
// |
// v
// B_Clustered
//
// where the ===> arrow has a hostmem source and destination and would entail a
// device to host copy if the source and destination were not in the same XLA
// cluster.
// Rewrite a tree of Add/AddN with a single AddN operation, consuming all the
// original inputs of absorbed nodes.
//
// 1) All nodes must have the same device placement.
//
// 2) If All nodes in a Add/AddN subgraph have symbolically equal shape, tree is
// optimized to a single AddN node.
//
// AddN_1
// / | \
// Add_1 z Add_2 -> AddN(x, y, z, w, q, e)
// / \ / \
// x y w Add_3
// / \
// q e
//
// 3) If some nodes have different shape (it needs to be broadcastable to the
// shape of a "root), tree is optimized to AddNs for symbolically equal
// shapes, and a tree of Add ops, that minimize broadcasts.
//
// AddN_1 Add
// / | \ / \
// Add_1 z Add_2 -> Add w
// / \ / \ / \
// x y w Add_3 AddN(x, y, q, e) z
// / \
// q e
// TODO(b/157615690): clean up function implementation swap code.
// The overall idea for the function swap is like below:
// ----------- -----------
// inp_1 ->| P_C | -> out_1 g_inp_1 ->| P_C | -> g_out_1
// inp_2 ->| forward | -> out_2 g_inp_2 ->| backward| -> g_out_2
// | FUNC_1 | -> out_3 g_inp_3 ->| FUNC_1 |
// ----------- -----------
// | | | ^ ^ ^
// v v v | | |
// s1 s2 s3 s1 s2 s3
// | ^
// | |
// | -------------- |
// |-----------> | Identity_1 | ---------->|
// --------------
// P_C: op Partitioned_call or stateful_partitioned_call
// FUNC1 (forward): TF function generated for the forward path.
// FUNC1 (backward): TF function generated for the backward path.
// inp_x: input tensors for the forward path.
// out_x: output tensors for the forward path.
// g_inp_x: gradient input tensors for the backward path.
// g_out_x: gradient output tensors for the backward path.
// s_x: intermediate result generated by forward tf function, which will be
// consumed by backward function for gradient calculation.
// In certain cases, we would like to insert an identity op between `input` and
// `op` to ensure correctness. We currently do this in 2 cases: when `input` is
// Exit node, or when `input` is already marked for allocation with another
// scoped allocator op.
//
// If `input` is an Exit node, we add an identity to avoid the case when Exit
// has inputs from different frames.
//
// If `input` is in `sa_opti->repeated_outputs()`, this means that it will be
// potentially used by multiple scope ids. Since there can be only one scope id
// per output, we insert an identity between the input and op. This will ensure
// that the identity becomes the new input to op, and this identity can be
// marked with a new scope id different from `input`.
//
// If the graph is rewritten, this function will perform the following change:
//
// input input
// | |
// op Identity
// |
// op
//
// This function returns the input to op in `new_input`, and the output index
// from input to op in `new_output_index`.
// `edge_name` gives the name of the edge from `input` to `op`, and
// `output_index` is the output index of this edge on `input`.
// The syntax above has a root ("Relu") and children (inputs), where each child
// is a sub-pattern. Graph pattern matcher finds a match for the given pattern
// syntax in a graph and returns a set of matched nodes.
//
// (2) In order to match a DAG with a given root, we extend pattern syntax with
// labels. For example, a frequently found pattern in Deep Learning models is a
// residual block like below.
//
// Placeholder Const
// | |
// +-----+-----+ |
// | | |
// | v v
// | Conv2D Const
// | | |
// | v v-----+
// | BiasAdd
// | |
// v v----------+
// AddV2
// ________________
// A more complex case: [tensor], (node), (partitioned node)
// _ _ _ _
// [0]-->(0)-->[1]-->(1)-->[5]-->(4)-->[6]-->(5)-->[7]
// \
// \
// \>[2]-->(2)-->[3]-->(3)-->[4]
//
// Greedy partitioning;
// ____
// [0]-->(0145)-->[7]
// \
// \-->[2]-->(23)-->[4]
//
// Tests scenarios involving a single delegate and control edges.
// Subgraph 0 has the form
//
// /---OP2---\
// / \
// >---OP0 OP3--->
// \ /
// \---OP1---/
//
// Delegating OP0, OP2 will generate an execution graph with a "super-node"
// {OP0->OP2}, which can be disabled by adding (in metadata) a control edge
// between OP1 and OP2:
//
// /->-OP2---\
// / ^ \
// >---OP0 ^ OP3--->
// \ ^ /
// \---OP1---/
//
// We will caculate the total compute cost for each Func Op.
//
// The compute cost is simply an add-up of the costs of all the operations
// within the FuncOp. (Excluding const ops since they're just "data".)
// We will ignore quant/dequant/requant costs within the Func Op as well,
// intuition:
//
// The assumpution is that quant/dequant/requant will only happen at the begin
// and the end of the FuncOp (basically the "boundaries" of the subgraph).
// So we can imagine if multiple "same-inference-typed" graph are presented at
// the same time, the quant/dequant ops pair can be squashed:
//
// dequant ------------
// |
// ops... FuncOp1
// |
// quant -------------
// | <--- can be squashed
// dequant -------------
// |
// ops... FuncOp2
// |
// quant ---------------
//
// But it's true quant & dequant ops can happen "within" the FuncOp as well,
// normally as "quantization params" adjust. We should check more careful to
// include those as those ops wouldn't be "squashed".