Skip to content

Commit f010b96

Browse files
committed
📚 Update docs for removal of sc
Problem: - The `sc` library is no longer used, but is still in docs. Solution: - Update docs.
1 parent 0b3edad commit f010b96

File tree

4 files changed

+47
-135
lines changed

4 files changed

+47
-135
lines changed

docs/index.adoc

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,4 @@ include::logging.adoc[]
1313
include::interrupts.adoc[]
1414
include::match.adoc[]
1515
include::message.adoc[]
16-
include::sc.adoc[]
1716
include::implementation_details.adoc[]

docs/intro.adoc

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,6 @@ _cib_ contains several parts that work together:
4747
- xref:interrupt.adoc#_the_interrupt_library[`interrupt`]
4848
- xref:match.adoc#_the_match_library[`match`]
4949
- xref:message.adoc#_the_message_library[`message`]
50-
- xref:sc.adoc#_the_sc_string_constant_library[`sc` (string constant)]
5150

5251
=== Sub-library DAG
5352

@@ -58,13 +57,11 @@ library that contains all the functionality.
5857
----
5958
flowchart BT
6059
nexus(cib_nexus)
61-
sc(cib_sc)
6260
log(cib_log)
6361
match(cib_match)
6462
lookup(cib_lookup)
6563
6664
flow(cib_flow) --> nexus
67-
flow --> sc
6865
flow --> log
6966
7067
log_fmt(cib_log_fmt) --> log

docs/logging.adoc

Lines changed: 47 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ xref:logging.adoc#_logging_environments[environment].
9999

100100
The first two runtime parameters receive preprocessor `\_​_FILE_​\_` and `__LINE_​_` values
101101
respectively. The `msg` argument is a structure containing a
102-
xref:sc.adoc#_formatting_strings[compile-time format string] and runtime
102+
compile-time format string and runtime
103103
arguments to be interpolated into it. It supports an `apply` function, so one
104104
way to implement `log` is:
105105

@@ -185,11 +185,52 @@ struct my_struct {
185185
}
186186
----
187187

188-
=== String data
189-
190-
On a constrained system, space for text can be at a premium. The `sc` library
191-
and the MIPI Sys-T logger combine to
192-
xref:sc.adoc#_efficient_logging_with_mipi_sys_t[solve this problem].
188+
=== Efficient logging with MIPI Sys-T
189+
190+
On a constrained system, space for text can be limited-to-nonexistent. `cib`
191+
uses `stdx::ct_format` and the
192+
https://github.com/intel/compile-time-init-build/tree/main/include/log/catalog/mipi_encoder.hpp[MIPI
193+
Sys-T logging config] to solve this problem.
194+
195+
- First, each string constant contains string character data in its type.
196+
- The MIPI logger calls the function template specialization
197+
https://github.com/intel/compile-time-init-build/blob/main/include/log/catalog/catalog.hpp[`catalog`]
198+
to get the catalog ID corresponding to each string constant.
199+
200+
But: the `catalog` function template is just that -- only a template -- to
201+
begin with. It is specialized as follows:
202+
203+
- The application is built as a library.
204+
- Running `nm` on that library reveals missing symbols: precisely the function
205+
specializations that are required for all the string constants.
206+
- Those symbols are used to generate the template specializations in another
207+
file, which itself is compiled into a library.
208+
- String data is recovered from the symbol types and used to generate the
209+
catalog collateral in XML and/or JSON format.
210+
- Link-time optimization inlines the `catalog` function template
211+
specializations, each of which is a one-line function that returns a
212+
catalog ID.
213+
214+
Thus no string data exists in the executable, but the correct catalog IDs are
215+
used in logging, and the remote log handler can reconstitute the actual strings.
216+
The XML and JSON collateral also contains information about any runtime
217+
arguments that need to be interpolated into the string and whose values are sent
218+
by the MIPI Sys-T logger after the catalog ID.
219+
220+
==== Tooling support
221+
222+
The process of generating log strings from the type information revealed by
223+
missing symbols is automated by a
224+
https://github.com/intel/compile-time-init-build/blob/main/tools/gen_str_catalog.py[python
225+
script] provided and by a
226+
https://github.com/intel/compile-time-init-build/blob/main/cmake/string_catalog.cmake[CMake
227+
wrapper function (`gen_str_catalog`)] that drives the process. See
228+
https://github.com/intel/compile-time-init-build/blob/main/test/CMakeLists.txt[the
229+
test] that exercises that functionality for an example.
230+
231+
NOTE: This process assigns IDs to both strings and
232+
xref:logging.adoc#_modules[log modules]. `catalog` is specialized for catalog
233+
IDs; `module` is specialized for module IDs.
193234

194235
=== Version logging
195236

docs/sc.adoc

Lines changed: 0 additions & 125 deletions
This file was deleted.

0 commit comments

Comments
 (0)