| // Copyright 2019 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| library fuchsia.diagnostics.stream; |
| using zx; |
| |
| /// A component with records for the Diagnostics system to retrieve. |
| /// |
| /// To record diagnostics, a component allocates a VMO and begins writing records into the buffer, |
| /// incrementing a header value after each write to inform readers how much of the buffer has been |
| /// filled. |
| /// |
| /// If any retrievers are connected, the `Source` sends them `OnBufferInit` events for each |
| /// diagnostic buffer created. |
| /// |
| /// When the buffer fills, the `Source` sends `OnBufferDone` to the retrievers, and will wait for |
| /// all notified retrievers to reply with `RetireBuffer` when they have finished reading from the |
| /// buffer. |
| /// |
| /// When all readers of the buffer have finished, the `Source` may recycle the buffer by zeroing it |
| /// and sending `OnBufferInit` again to connected retrievers. |
| /// |
| /// Once a `Source` has sent `OnBufferDone` to a retriever, it is up to the `Source` to handle new |
| /// records that are generated while the retriever drains the buffer. Double buffering is |
| /// recommended to prevent excessive blocking, but this protocol does not mandate a specific |
| /// approach to handling records generated while buffers are full. |
| [Discoverable] |
| protocol Source { |
| /// Notifies the connected retriever of a new stream buffer. Should be emitted as soon as each |
| /// buffer is (re)initialized. |
| /// |
| /// `latest` should be read-only. |
| -> OnBufferInit(handle<vmo> latest); |
| |
| /// Asks the connected retriever to finish working with `buffer`, usually because the `Source` |
| /// does not intend to write further records. |
| -> OnBufferDone(zx.koid buffer); |
| |
| /// Notifies the `Source` that the retriever is done reading from the buffer. If the `Source` |
| /// wishes it should zero the buffer's contents and recycle it for future records. Buffers must |
| /// be re-sent via `OnBufferInit` after they're zeroed. |
| RetireBuffer(zx.koid buffer); |
| |
| /// Notifies the component of interest in a subset of diagnostic records. |
| /// |
| /// Before the component receives this request it should filter according to a default interest |
| /// specifier. |
| /// |
| /// After receiving this message components begin writing records according to the new |
| /// specifier. `Source` components must be prepared to handle multiple client connections, |
| /// and may filter records according to the union of all interest specifiers. Clients may |
| /// receive records outside the scope of their interest. |
| RegisterInterest(Interest desired); |
| }; |
| |
| /// The system's current interest in records. |
| /// |
| /// Without having received an interest specifier or receiving one with empty fields, components |
| /// should assume a default interest specifier, as documented for each field in this table. |
| table Interest { |
| /// Minimum desired severity. The default is `INFO`. |
| 1: Severity min_severity; |
| }; |
| |
| /// The severity of a given record. |
| enum Severity { |
| /// Components should only record fatal records prior to terminating operation. Fatal |
| /// records are informative only, and front-end libraries which trigger an exit in response |
| /// to them should clearly document this behavior to their users. |
| FATAL = 5; |
| /// Components should include error records as well as more severe records. |
| ERROR = 4; |
| /// Components should include warning records as well as more severe records. |
| WARN = 3; |
| /// Components should include informative records as well as more severe records. (default) |
| INFO = 2; |
| /// Components should include developer-facing debug records as well as more severe records. |
| DEBUG = 1; |
| /// Components should include all records. |
| ANY = 0; |
| }; |