docs: Log design

Basic design for Log component.

Author: arkjedrz

docs/module/log/architecture/_assets/interface.puml

@@ -0,0 +1,74 @@
+@startuml log_interface
+
+package log <<component>> {
+    +enum Level <<enum>> {
+        Fatal
+        Error
+        Warn
+        Info
+        Debug
+        Trace
+    }
+
+    +enum LevelFilter <<enum>> {
+        Off
+        Fatal
+        Error
+        Warn
+        Info
+        Debug
+        Trace
+    }
+
+    class mw_log <<module>> {
+        +set_logger(logger: &'static dyn Log) : Result<(), SetLoggerError>
+        +set_boxed_logger(logger: Box<dyn Log>) : Result<(), SetLoggerError>
+        +set_max_level(level: LevelFilter) : ()
+        +max_level() : LevelFilter
+        +logger() : &'static dyn Log
+
+        +log!(context: &str, level: Level, ...) : ()
+        +log_enabled!(context: &str, level: Level) : bool
+        +fatal!(...) : ()
+        +error!(...) : ()
+        +warn!(...) : ()
+        +info!(...) : ()
+        +debug!(...) : ()
+        +trace!(...) : ()
+    }
+
+    class mw_log_macro <<module>> {
+        +mw_log_format_args!(format_string: &str, args...) : Arguments<'_>
+        +mw_log_format_args_nl!(format_string: &str, args...) : Arguments<'_>
+    }
+
+    package "mw_log_fmt" {
+        +interface ScoreDebug <<trait>> {
+            +fmt(&self, f: &mut dyn ScoreWrite, spec: &FormatSpec) : Result
+        }
+
+        +interface ScoreDisplay <<trait>> {
+            +fmt(&self, f: &mut dyn ScoreWrite, spec: &FormatSpec) : Result
+        }
+
+        class mw_log_fmt <<module>> {
+            +write(output: &mut dyn ScoreWrite, args: Arguments<'_>) : Result
+
+            +score_write!(format_string: &str, args...) : Result
+            +score_writeln!(format_string: &str, args...) : Result
+        }
+
+        ScoreDebug -[hidden]down- ScoreDisplay
+        ScoreDisplay -[hidden]down- mw_log_fmt
+
+    }
+
+    mw_log -- Level
+    mw_log -- LevelFilter
+    mw_log -- mw_log_macro
+    mw_log -right- mw_log_fmt
+}
+
+
+
+@enduml

docs/module/log/architecture/_assets/log_with_global_logger.puml

@@ -0,0 +1,22 @@
+@startuml log_with_global_logger
+
+participant "User" as actor
+participant "<<component>> log" as frontend
+participant "<<component>> mw_log_subscriber" as backend
+participant "no-op logger" as nop_logger
+
+actor -> frontend : Log message
+
+frontend -> frontend : Get global logger instance
+
+alt registered
+    frontend -> backend : Log message
+    backend --> frontend
+else not-registered
+    frontend -> nop_logger : No-op operation
+    nop_logger --> frontend
+end
+
+frontend --> actor
+
+@enduml

docs/module/log/architecture/_assets/log_with_local_logger.puml

@@ -0,0 +1,17 @@
+@startuml log_with_global_logger
+
+participant "User" as actor
+participant "<<component>> log" as frontend
+participant "<<component>> mw_log_subscriber" as backend
+
+actor -> backend : Create concrete logger instance
+backend --> actor : Logger instance
+
+actor -> frontend : Log message with logger instance
+
+frontend -> backend : Log message
+backend --> frontend
+
+frontend --> actor
+
+@enduml

docs/module/log/architecture/_assets/register_global_logger.puml

@@ -0,0 +1,17 @@
+@startuml register_global_logger
+
+participant "User" as actor
+participant "<<component>> mw_log_subscriber" as backend
+participant "<<component>> log" as frontend
+
+actor -> backend : Create concrete logger instance
+backend --> actor : Logger instance
+
+actor -> frontend : Set logger
+alt set-success
+    frontend --> actor : Ok
+else set-failed
+    frontend --> actor : Error code
+end
+
+@enduml

docs/module/log/architecture/_assets/static_view.puml

@@ -0,0 +1,20 @@
+@startuml log_static_view
+
+package "log" <<component>> {
+    component "mw_log" <<interface>>
+
+    component "mw_log_fmt"
+
+    component "mw_log_macro"
+
+    mw_log ..> mw_log_fmt : use
+    mw_log ..> mw_log_macro : use
+}
+
+component "mw_log_subscriber" <<component>>
+note bottom: "Backend implementation."
+
+mw_log --> "mw_log_subscriber" : implements
+
+
+@enduml

docs/module/log/architecture/index.rst

@@ -20,7 +20,7 @@ Component Architecture
 .. document:: Log Architecture
    :id: doc__log_architecture
    :status: draft
-   :safety: QM
+   :safety: ASIL_B
    :security: NO
    :realizes: wp__component_arch
    :tags: log
@@ -35,63 +35,77 @@ Document describes Log component architecture.
 Description
 -----------
 
-TODO: description
+Log component is modelled after `log` library, which is ubiquitous in Rust ecosystem.
+This provides familiar APIs and syntax - provided APIs can be replaced at compile time with `log`.
+
+Component provides new formatting functionality (replacement to `core::fmt`) to ensure improved flexibility in formatting on backend side.
+E.g., numeric types are formatted by the backend, and not by the core library.
+
+Even though design is similar - existing `log` implementations are not compatible.
 
 
 Rationale Behind Architecture Decomposition
 *******************************************
 
-TODO: decomposition rationale
+Architecture is not decomposed.
+Log component is a monolithic frontend.
+
 
 Static Architecture
 -------------------
 
-TODO: static architecture
-
-.. .. comp_arc_sta:: Log (Static View)
-..    :id: comp_arc_sta__log__static_view
-..    :security: YES
-..    :safety: QM
-..    :status: invalid
-..    :implements: logic_arc_int__log__interface_name
-..    :fulfils:
-..    :includes:
+.. comp_arc_sta:: Log (Static View)
+   :id: comp_arc_sta__log__static_view
+   :security: NO
+   :safety: ASIL_B
+   :status: valid
+   :implements:
+   :fulfils:
+   :includes:
 
-..    .. uml:: _assets/TODO.puml
+   .. uml:: _assets/static_view.puml
 
 
 Dynamic Architecture
 --------------------
 
-TODO: dynamic architecture
-
-.. .. comp_arc_dyn:: Dynamic View
-..    :id: comp_arc_dyn__log__dynamic_view
-..    :security: YES
-..    :safety: QM
-..    :status: invalid
-..    :fulfils: comp_req__log__some_title
+.. comp_arc_dyn:: Register global logger
+   :id: comp_arc_dyn__log__register_global_logger
+   :security: NO
+   :safety: ASIL_B
+   :status: valid
+   :fulfils:
 
-.. .. uml:: _assets/TODO.puml
+   .. uml:: _assets/register_global_logger.puml
 
+.. comp_arc_dyn:: Log with global logger instance
+   :id: comp_arc_dyn__log__log_with_global_logger
+   :security: NO
+   :safety: ASIL_B
+   :status: valid
+   :fulfils:
 
-Interfaces
-----------
+   .. uml:: _assets/log_with_global_logger.puml
 
-TODO: put log interfaces.
+.. comp_arc_dyn:: Log with local logger instance
+   :id: comp_arc_dyn__log__log_with_local_logger
+   :security: NO
+   :safety: ASIL_B
+   :status: valid
+   :fulfils:
 
-.. .. code-block:: rst
+   .. uml:: _assets/log_with_local_logger.puml
 
-..    .. real_arc_int:: mw_log
-..       :id: real_arc_int__log__interface
-..       :security: NO
-..       :safety: QM
-..       :fulfils:
-..       :language: rust
 
-..    .. uml:: _assets/TODO.puml
+Interfaces
+----------
 
-Lower Level Components
-----------------------
+.. real_arc_int:: Log interface
+   :id: real_arc_int__log__interface
+   :security: NO
+   :safety: ASIL_B
+   :status: valid
+   :fulfils:
+   :language: rust
 
-TODO: remove section if unused
+   .. uml:: _assets/interface.puml

docs/module/log/component_classification.rst

@@ -19,7 +19,7 @@ Component Classification
 .. document:: Log Component Classification
    :id: doc__log_comp_class
    :status: draft
-   :safety: QM
+   :safety: ASIL_B
    :security: NO
    :realizes: wp__sw_component_class
    :tags: log