diff --git a/src/a_few_basics.adoc b/src/a_few_basics.adoc index 2742a71..404c214 100644 --- a/src/a_few_basics.adoc +++ b/src/a_few_basics.adoc @@ -236,3 +236,712 @@ This example renders as: <> describes how index markers work. For more information about options, see https://docs.asciidoctor.org/asciidoc/latest/macros/xref/#internal-cross-references[Cross References]. + + +[[tables_symbols_math]] +=== Tables + +By using tables, you can group information into logical units, which can make the infromation presented easier to understand. + +[[tables-gen]] +==== General rules for tables +Follow these general rules when you create a table. + +* Avoid tables in the middle of lists. +* Do not use tables to lay out a page. For example, if you have a long list of items, do not use a 2 column table to save space. The information should make sense side by side. +* Do not create a table that has a single row or a single column, unless you are following a previous layout. For example, if each section in a chapter includes a table of options, then use a table even if one of the sections has only a single option. +* Always use table headers and captions to make your tables more accessible. +* Use introductory sentences for your table. For example, "The following table contains the options for the CSR." You can use either a period or a colon for your introductory sentence. +* Do not refer to the "table above" or the "below table". Use words such as "The following table" or "The preceeding table". + +[WARNING] +==== +*Never* use automated wrapping for table titles, figure captions, and example captions. Asciidoctor reads a hard return as an indicator to start a new "Normal" paragraph. +==== + +==== Simple table + +The following example shows a simple table with 2 rows and 2 columns. To indicate a new row, put a empty line between them. + +[source,adoc] +---- +[cols="1,1"] +|=== +|Cell in column 1, row 1 +|Cell in column 2, row 1 + +|Cell in column 1, row 2 +|Cell in column 2, row 2 +|=== +---- + +Results in the following table. + +[cols="1,1"] +|=== +|Cell in column 1, row 1 +|Cell in column 2, row 1 + +|Cell in column 1, row 2 +|Cell in column 2, row 2 +|=== + +==== Adding table headers + +Headers can add additional information to your table, making them easier to understand. + +You can add a header row by adding the first row of cells directly in a line. + +---- +[cols="1,1,1"] +|=== +|Col 1, header row|Col 2, header row|Col 3, header row + +|Cell in col 1, row 2 +|Cell in col 2, row 2 +|Cell in col 3, row 2 +|=== +---- + +Or you can use the `header` option. + +---- +[%header,cols="1,1,1"] +|=== +|Col 1, header row +|Col 2, header row +|Col 3, header row + +|Cell in col 1, row 2 +|Cell in col 2, row 2 +|Cell in col 3, row 2 +|=== +---- + +Either table renders with table headers. + +[cols="1,1,1"] +|=== +|Col 1, header row|Col 2, header row|Col 3, header row + +|Cell in col 1, row 2 +|Cell in col 2, row 2 +|Cell in col 3, row 2 +|=== + +==== Table captions + +The `book_header.adoc` file in the docs-templates repo sets the `full` cross-reference attribute to enable captions to display from targets in the anchors. This ability allows you to set captions for tables, blocks, and illustrations. If you do not provide a caption, Asciidoctor defaults to the _basic_ cross reference style. + +To set a caption for a table or image, use the pattern as follows: + +[source,adoc] +---- +The following table, <> shows the characteristics of each kind of trap. +---- + +[source,adoc] +---- +[[trapcharacteristics,Characteristics of traps]] +.Characteristics of traps. +[cols="<,^,^,^,^",options="header",] +|=== +| |Contained |Requested |Invisible |Fatal +|Execution terminates |No |Nolatexmath:[$^{1}$] |No |Yes +|Software is oblivious |No |No |Yes |Yeslatexmath:[$^{2}$] +|Handled by environment |No |Yes |Yes |Yes +|=== +---- + +The following table, <> shows the characteristics of each +kind of trap. + +[[trapcharacteristics]] +.Characteristics of traps. +[cols="<,^,^,^,^",options="header",] +|=== +| |Contained |Requested |Invisible |Fatal +|Execution terminates |No |Nolatexmath:[$^{1}$] |No |Yes +|Software is oblivious |No |No |Yes |Yeslatexmath:[$^{2}$] +|Handled by environment |No |Yes |Yes |Yes +|=== + + +==== AsciiDoc tables from CSV data. + +AsciiDoc tables can also be created directly from CSV data. Set the format block attribute to `csv` and insert the data inside the block delimiters directly: + +[source,adoc] +---- +[%header,format=csv] +|=== +Artist,Track,Genre +Baauer,Harlem Shake,Hip Hop +The Lumineers,Ho Hey,Folk Rock +|=== +---- + +The previous example renders as follows: + +[%header,format=csv] +|=== +Artist,Track,Genre +Baauer,Harlem Shake,Hip Hop +The Lumineers,Ho Hey,Folk Rock +|=== + + +There are numerous formatting options available. While some of the property settings are cryptic, they can be quite useful. There are numerous examples available at https://asciidoc.org/newtables.html. Here one example of what can be done with spans alignment in tables from that page: + +[source,adoc] +---- +[cols="e,m,^,>s",width="25%"] +|============================ +|1 >s|2 |3 |4 +^|5 2.2+^.^|6 .3+<.>m|7 +^|8 +|9 2+>|10 +|============================ +---- + +Which renders as follows: + +[cols="e,m,^,>s",width="25%"] +|============================ +|1 >s|2 |3 |4 +^|5 2.2+^.^|6 .3+<.>m|7 +^|8 +|9 2+>|10 +|============================ + +The following example is code for a numbered encoding table with link target. + +NOTE: Annotations have been added to the code to illustrate their use. + +[source,adoc] +---- +[[proposed-16bit-encodings-1] <1> +.proposed 16-bit encodings-1 <2> +[width="100%",options=header] +|=== +|15 |14 |13 |12 |11 |10 |9 |8 |7 |6 |5 |4 |3 |2 |1 |0 |instruction +3+|100|1|0|0|0 2+|field|0 |0 2+|00 | field 2+|00|mnemonic1 +3+|100|1|0|0 3+|field|bit|1 3+|field 2+|00|mnemonic2 +3+|110|1|0|0 3+|field|1 |0 3+|field 2+|00|mnemonic3 +17+|This row spans the whole table +3+|100|1|1|1 8+| field 2+| 00 | mnemonic4 +|=== +---- +. Link target. +. Numbered table title. + +The previous example results in the following table. + +[#proposed-16bit-encodings-1] +.proposed 16-bit encodings-1 +[width="100%",options=header] +|=== +|15 |14 |13 |12 |11 |10 |9 |8 |7 |6 |5 |4 |3 |2 |1 |0 |instruction +3+|100|1|0|0|0 2+|field|0 |0 2+|00 | field 2+|00|mnemonic1 +3+|100|1|0|0 3+|field|bit|1 3+|field 2+|00|mnemonic2 +3+|110|1|0|0 3+|field|1 |0 3+|field 2+|00|mnemonic3 +17+|This row spans the whole table +3+|100|1|1|1 8+| field 2+| 00 | mnemonic4 +|=== + +=== Unicode symbols + +For PDFs, five-digit unicode symbols generally don't work and some other unicode symbols are buggy. This failure happens because the Ruby asciidoctor-pdf toolchain makes use of Prawn to build PDFs and it's Prawn that has the problems. + +Here are a few unicode examples from https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references that might be useful: + +As an example, ♦ is encoded as follows: + +```unicode +♦ +``` + +[[useful-unicode]] +.Useful unicode for specifications +[width="100%",options=header,format=csv] +|=== +sym,num,name +^,94,caret +ˆ,136, +⋮,8942,vdots +♦,9830,name +",0034,name +w,0077,w +∴,8756,therefore +♯,9839,sharp +ш,1096,shcy +ϖ,982,piv varpi +ω,969,omega +℘,8472,weierp wp +∑,8721,sum +∞,8734,infin +∫,8747,integral +≠,8800,not equal to +≤,8804,le +≥,8805,ge +≈,8776,numerical approximation +D,68,mathematical D? +⇒,8658,rightwards double arrow +X,88,Latin Capital x +χ,967,Greek x +×,215,times +☑,9745,boxed checkmark +r,114,latin small letter r +|=== + +For many other symbols, use asciidoctor-mathematical. See <>. + +[[unicode-not-working]] +.Unicode identified as not working +[width="100%",options=header,format=csv] +|=== +sym,num,name +⍼,9084,angzarr not working +⋙,8921,ggg not working +↩,8617,hookleftarrow not working +⍻,9083,not checkmark not working +|=== + + +=== Mathematical notations + +WARNING: Asciidoctor-mathematical has some limitations. For inline expressions, the graphical representations appear small and they are centered vertically. In some cases where there is a single-character Asciidoctor-mathematical expression, it unintentionally looks like a superscript. For this reason, always use viable alternatives like _italics_ or unicode (see <>). + + +==== Superscripts and subscripts + +To indicate a superscript, enclose the string for the superscript in carets as in the following example: + +---- +2^8^ +---- + +Which renders as: + +2^8^ + +You can indicate text in a superscript as well: + +---- +1234^NOTE^ +---- + +Which renders as: + +1234^NOTE^ + +For subscripts, use tildes: + +---- +C~2~ H~6~ +---- + +With the following result: + +C~2~ H~6~ + +An example: +---- +"`Well the H~2~O formula written on their whiteboard could be part +of a shopping list, but I don't think the local bodega sells +E=mc^2^,`" Lazarus replied. +---- + +Renders as: + +"Well the H~2~O formula written on their whiteboard could be part +of a shopping list, but I don't think the local bodega sells +E=mc^2^," Lazarus replied. + +==== Latexmath + +You can make use of LaTeX notation as in the following: + +---- +latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$] +---- + +Which renders as: + +latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$] + +[TIP] +==== +Latexmath rendering has some limitations with respect to sizing and placement inline. This happens because of how the images for the mathematical symbols are rendered within the build process. For this reason, please avoid using single character latexmath expressions inline and preferentially make use of unicode or superscripts and subscripts when possible. +==== + +==== Stem content + +The `:stem: latexmath` setting makes use of asciidoctor-mathematical for asciidoctor-pdf output. + +Asciidoctor Mathematical is a Ruby gem that uses native extensions. It has a few system prerequisites which limit installation to Linux and macOS. Please refer to the https://github.com/riscv/docs-templates[README in the RISC-V docs-templates repo] for information on the asciidoctor-mathematical install. + +[source,adoc] +---- +[stem] +++++ +sqrt(4) = 2 +++++ +---- + +[stem] +++++ +sqrt(4) = 2 +++++ + +In some cases, you might want to make use of unicode characters. Keep in mind that asciidoctor-pdf supports only decimal character references. See https://github.com/asciidoctor/asciidoctor-pdf/issues/486 + +For updates to asciidoctor-pdf, see https://github.com/asciidoctor/asciidoctor-pdf. + +[[blocks_notes_markers]] +=== Admonition blocks + +Five types of standard link:https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/[admonition blocks] are available in AsciiDoc. RISC-V uses these five types with the default icons. + +NOTE: The admonition type is not displayed, only the icon. + +Note:: Highlight extra information that should stand out from the rest of the text. A "by the way, you should know this" statement. + +NOTE: example of note type + +Caution:: Cautions users about a condition or action that can lead to bad outcomes such as personal injury or damage equipment. A "we don’t recommend" statement. + +CAUTION: example of caution type + +Warning:: Warns users about a situation that is undesirable. A "Do not do this!" or "You must do this" statement. + +WARNING: example of warning type + +Important:: Information that a user must have. For example, "After you set your password, you cannot change it." + +IMPORTANT: example of important type + +Tip:: Used for Non-normative text such as clarification or hints for implementers or to convey design rationale and why other options were discontinued. RISC-V tech team is working on a solution that will allow these admonitions to be turned off. + +TIP: example of tip type + +As a general rule, follow these guidelines for admonitions: + +* Understand that admonitions are interruptions. They should be relevant to the topic, but not necessary. If the reader skips reading it, they can still succeed. +* If the information is necessary, make it part of the topic and even add a heading. Don't put it in an admonition. +* Limit admonitions to a maximum of 3 on a page (standard PDF page - longer HTML pages can use more.) +* Do not include results, steps, or prerequisites in admonitions. +* Make your admonition clear and concise. + +==== Single paragraph admonition + +For a single paragraph admonition, use a double colon: + +[source,adoc] +---- +NOTE: Note content. +---- + +which renders as: + +NOTE: Note content. + +==== Admonition blocks + +An admonition block can contain any AsciiDoc content. + +[source,adoc] +---- +[IMPORTANT] +==== +As a general rule, follow these guidelines for admonitions: + +* Understand that admonitions are interruptions. They should be relevant to the topic, but not necessary. If the reader skips reading it, they can still succeed. +* If the information is necessary, make it part of the topic and even add a heading. Don't put it in an admonition. +* Limit admonitions to a maximum of 3 on a page (standard PDF page - longer HTML pages can use more.) +* Do not include results, steps, or prerequisites in admonitions. +* Make your admonition clear and concise. +==== +---- + +which renders as: + +[IMPORTANT] +==== +As a general rule, follow these guidelines for admonitions: + +* Understand that admonitions are interruptions. They should be relevant to the topic, but not necessary. If the reader skips reading it, they can still succeed. +* If the information is necessary, make it part of the topic and even add a heading. Don't put it in an admonition. +* Limit admonitions to a maximum of 3 on a page (standard PDF page - longer HTML pages can use more.) +* Do not include results, steps, or prerequisites in admonitions. +* Make your admonition clear and concise. +==== + +==== Admonition with a title + +You can add a title to your admonition block. + +[source,adoc] +---- +[WARNING] +.Security vulnerability +==== +*Be aware that RLB introduces a security vulnerability if it is set after the boot process is over.* Use with caution, even when you use it temporarily. Editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It doesn’t make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors durring debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*. +==== +---- + +Rendered: + +[WARNING] +.Security vulnerability +==== +*Be aware that RLB introduces a security vulnerability if it is set after the boot process is over.* Use with caution, even when you use it temporarily. Editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It doesn’t make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors durring debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*. +==== + +==== RISC-V admonition icon colors + +The admonition icons are set in `risc-v_spec-pdf.yml`. RISC-V uses custom colors, as indicated in the <>. + +NOTE: note + +TIP: tip + +WARNING: warning + +CAUTION: caution + +IMPORTANT: important + +[[custom-color-icons]] +.Customized colors for icons +[width="100%",options=header,format=csv] +|=== +Icon,default,customized +NOTE,19407c,6489b3 +TIP,111111,5g27ag +WARNING,bf6900,9c4d4b +CAUTION,bf3400,c99a2c +IMPORTANT,bf0000,b58f5b +|=== + + +=== Code blocks + +AsciiDoc enables code blocks that support syntax highlighting. + +For example, preceding a block with a macro `[source,json]` enables `json` syntax highlighting: + +[source,json] +---- +{ + "weather": { + "city": "Zurich", + "temperature": 25, + } +} +---- + +While syntax highlighters for machine code that integrate with the Asciidoctor Ruby toolchain do leave something to be desired, the Rouge highlighter enables line numbers within the code examples. + +We are numbering examples as in the following: + +[source,adoc] +---- +.A spinlock with fences +[source%linenums,asm] +.... + sd x1, (a1) # Arbitrary unrelated store + ld x2, (a2) # Arbitrary unrelated load + li t0, 1 # Initialize swap value. + again: + amoswap.w t0, t0, (a0) # Attempt to acquire lock. + fence r, rw # Enforce "acquire" memory ordering + bnez t0, again # Retry if held. + # ... + # Critical section. + # ... + fence rw, w # Enforce "release" memory ordering + amoswap.w x0, x0, (a0) # Release lock by storing 0. + sd x3, (a3) # Arbitrary unrelated store + ld x4, (a4) # Arbitrary unrelated load +.... +---- + +With the following result: + +[[spinlock_fences]] +.A spinlock with fences +[source%linenums,asm] +.... + sd x1, (a1) # Arbitrary unrelated store + ld x2, (a2) # Arbitrary unrelated load + li t0, 1 # Initialize swap value. + again: + amoswap.w t0, t0, (a0) # Attempt to acquire lock. + fence r, rw # Enforce "acquire" memory ordering + bnez t0, again # Retry if held. + # ... + # Critical section. + # ... + fence rw, w # Enforce "release" memory ordering + amoswap.w x0, x0, (a0) # Release lock by storing 0. + sd x3, (a3) # Arbitrary unrelated store + ld x4, (a4) # Arbitrary unrelated load +.... + + +=== Change bars + +Change indicators within text files are exceedingly useful and also can be equally complex to implement. Please consider the fact that much of the software programming for Git revolves around handling various kinds of change indicators. + +In exploring possible implementation of change bars for RISC-V, we have looked for a solution that is as simple as possible while maximizing value with respect to the time invested in implementing, maintaining, and using the tools and procedures. + +The suggested solution makes use of: + +- an AsciiDoc `role`. +- modification of two files in the Ruby gem with code snippets (see procedure in the README for https://github.com/riscv/docs-templates). +- Git features. +- a few procedures associated, specifically, with Git updates. + +==== Indicate changes + +Indicators for the changed lines must be inserted manually: + +[source,adoc] +---- +[.Changed]#SELECT clause# + +Text without the change bar + +[.Changed]#Text with the change bar# +---- + +[.Changed]#SELECT clause# + +Text without the change bar + +[.Changed]#Text with the change bar# + + +For change bars associated with headings, place the change indicator after the heading indicator and before the text, like the following: + +---- +== [.Changed]#SELECT clause# +---- + +==== Check for changed lines before a `git commit` + +You can double check for all changed lines before committing by using this pattern: + +[source,cmd] +---- +git blame | grep -n '^0\{8\} ' | cut -f1 -d: +---- + +This lists the line numbers of changes within the specified file like the following example: + +[source,cmd] +---- +5 +38 +109 +237 +---- + + +=== Footnotes + +AsciiDoc has a limitation in that footnotes appear at the end of each chapter. Asciidoctor does not support footnotes appearing at the bottom of each page. + +You can add footnotes to your presentation using the footnote macro. If you plan to reference a footnote more than once, use the footnote macro with a target that you identify in the brackets. + +[source,adoc] +---- +Initiate the hail-and-rainbow protocol at one of three levels: + +- doublefootnote:[The double hail-and-rainbow level makes my toes tingle.] +- tertiary +- apocalyptic + +A bold statement!footnote:disclaimer[Opinions are my own.] + +Another outrageous statement.footnote:disclaimer[] +---- + +Renders as: + +The hail-and-rainbow protocol can be initiated at three levels: + +- doublefootnote:[The double hail-and-rainbow level makes my toes tingle.] +- tertiary +- apocalyptic + +A bold statement!footnote:disclaimer[Opinions are my own.] + +Another outrageous statement.footnote:disclaimer[] + +=== Sidebars + +Sidebars provide for a form of commentary. + +[source,adoc] +---- + +**** +This is content in a sidebar block. + +image:example-3.svg[] + +This is more content in the sidebar block. +**** +---- + +This renders as follows: + +**** +This is content in a sidebar block. + +image:example-3.svg[] + +This is more content in the sidebar block. +**** + + +You can add a title, along with any kind of content. Best practice for many of the "commentaries" in the LaTeX source that elucidate the decision-making process is to convert to this format with the `TIP` icon that illustrates a conversation or discussion, as in the following example: + +[source,adoc] +---- +.Optional Title +**** +Sidebars are used to visually separate auxiliary bits of content +that supplement the main text. + +TIP: They can contain any type of content, including admonitions like this, and code examples like the following. + +.Source code block within a sidebar +[source,js] +/---- (1) +const { expect, expectCalledWith, heredoc } = require('../test/test-utils') +/---- (2) +**** + +---- + +1 and 2. Escapes are necessary to preserve this as an AsciiDoc code example. + +Once the escapes are removed, the above renders with both the admonition and code blocks within the sidebar: + +.Optional Title +**** +Sidebars are used to visually separate auxiliary bits of content +that supplement the main text. + +TIP: They can contain any type of content, including admonitions like this, and code examples like the following. + +.Source code block in a sidebar +[source,js] +---- +const { expect, expectCalledWith, heredoc } = require('../test/test-utils') +---- +**** + diff --git a/src/blocks_notes_markers.adoc b/src/blocks_notes_markers.adoc deleted file mode 100644 index 8daabb5..0000000 --- a/src/blocks_notes_markers.adoc +++ /dev/null @@ -1,346 +0,0 @@ -[[blocks_notes_markers]] -=== Admonition blocks - -Five types of standard link:https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/[admonition blocks] are available in AsciiDoc. RISC-V uses these five types with the default icons. - -NOTE: The admonition type is not displayed, only the icon. - -Note:: Highlight extra information that should stand out from the rest of the text. A "by the way, you should know this" statement. - -NOTE: example of note type - -Caution:: Cautions users about a condition or action that can lead to bad outcomes such as personal injury or damage equipment. A "we don’t recommend" statement. - -CAUTION: example of caution type - -Warning:: Warns users about a situation that is undesirable. A "Do not do this!" or "You must do this" statement. - -WARNING: example of warning type - -Important:: Information that a user must have. For example, "After you set your password, you cannot change it." - -IMPORTANT: example of important type - -Tip:: Used for Non-normative text such as clarification or hints for implementers or to convey design rationale and why other options were discontinued. RISC-V tech team is working on a solution that will allow these admonitions to be turned off. - -TIP: example of tip type - -As a general rule, follow these guidelines for admonitions: - -* Understand that admonitions are interruptions. They should be relevant to the topic, but not necessary. If the reader skips reading it, they can still succeed. -* If the information is necessary, make it part of the topic and even add a heading. Don't put it in an admonition. -* Limit admonitions to a maximum of 3 on a page (standard PDF page - longer HTML pages can use more.) -* Do not include results, steps, or prerequisites in admonitions. -* Make your admonition clear and concise. - -==== Single paragraph admonition - -For a single paragraph admonition, use a double colon: - -[source,adoc] ----- -NOTE: Note content. ----- - -which renders as: - -NOTE: Note content. - -==== Admonition blocks - -An admonition block can contain any AsciiDoc content. - -[source,adoc] ----- -[IMPORTANT] -==== -As a general rule, follow these guidelines for admonitions: - -* Understand that admonitions are interruptions. They should be relevant to the topic, but not necessary. If the reader skips reading it, they can still succeed. -* If the information is necessary, make it part of the topic and even add a heading. Don't put it in an admonition. -* Limit admonitions to a maximum of 3 on a page (standard PDF page - longer HTML pages can use more.) -* Do not include results, steps, or prerequisites in admonitions. -* Make your admonition clear and concise. -==== ----- - -which renders as: - -[IMPORTANT] -==== -As a general rule, follow these guidelines for admonitions: - -* Understand that admonitions are interruptions. They should be relevant to the topic, but not necessary. If the reader skips reading it, they can still succeed. -* If the information is necessary, make it part of the topic and even add a heading. Don't put it in an admonition. -* Limit admonitions to a maximum of 3 on a page (standard PDF page - longer HTML pages can use more.) -* Do not include results, steps, or prerequisites in admonitions. -* Make your admonition clear and concise. -==== - -==== Admonition with a title - -You can add a title to your admonition block. - -[source,adoc] ----- -[WARNING] -.Security vulnerability -==== -*Be aware that RLB introduces a security vulnerability if it is set after the boot process is over.* Use with caution, even when you use it temporarily. Editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It doesn’t make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors durring debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*. -==== ----- - -Rendered: - -[WARNING] -.Security vulnerability -==== -*Be aware that RLB introduces a security vulnerability if it is set after the boot process is over.* Use with caution, even when you use it temporarily. Editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It doesn’t make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors durring debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*. -==== - -==== RISC-V admonition icon colors - -The admonition icons are set in `risc-v_spec-pdf.yml`. RISC-V uses custom colors, as indicated in the <>. - -NOTE: note - -TIP: tip - -WARNING: warning - -CAUTION: caution - -IMPORTANT: important - -[[custom-color-icons]] -.Customized colors for icons -[width="100%",options=header,format=csv] -|=== -Icon,default,customized -NOTE,19407c,6489b3 -TIP,111111,5g27ag -WARNING,bf6900,9c4d4b -CAUTION,bf3400,c99a2c -IMPORTANT,bf0000,b58f5b -|=== - - -=== Code blocks - -AsciiDoc enables code blocks that support syntax highlighting. - -For example, preceding a block with a macro `[source,json]` enables `json` syntax highlighting: - -[source,json] ----- -{ - "weather": { - "city": "Zurich", - "temperature": 25, - } -} ----- - -While syntax highlighters for machine code that integrate with the Asciidoctor Ruby toolchain do leave something to be desired, the Rouge highlighter enables line numbers within the code examples. - -We are numbering examples as in the following: - -[source,adoc] ----- -.A spinlock with fences -[source%linenums,asm] -.... - sd x1, (a1) # Arbitrary unrelated store - ld x2, (a2) # Arbitrary unrelated load - li t0, 1 # Initialize swap value. - again: - amoswap.w t0, t0, (a0) # Attempt to acquire lock. - fence r, rw # Enforce "acquire" memory ordering - bnez t0, again # Retry if held. - # ... - # Critical section. - # ... - fence rw, w # Enforce "release" memory ordering - amoswap.w x0, x0, (a0) # Release lock by storing 0. - sd x3, (a3) # Arbitrary unrelated store - ld x4, (a4) # Arbitrary unrelated load -.... ----- - -With the following result: - -[[spinlock_fences]] -.A spinlock with fences -[source%linenums,asm] -.... - sd x1, (a1) # Arbitrary unrelated store - ld x2, (a2) # Arbitrary unrelated load - li t0, 1 # Initialize swap value. - again: - amoswap.w t0, t0, (a0) # Attempt to acquire lock. - fence r, rw # Enforce "acquire" memory ordering - bnez t0, again # Retry if held. - # ... - # Critical section. - # ... - fence rw, w # Enforce "release" memory ordering - amoswap.w x0, x0, (a0) # Release lock by storing 0. - sd x3, (a3) # Arbitrary unrelated store - ld x4, (a4) # Arbitrary unrelated load -.... - - -=== Change bars - -Change indicators within text files are exceedingly useful and also can be equally complex to implement. Please consider the fact that much of the software programming for Git revolves around handling various kinds of change indicators. - -In exploring possible implementation of change bars for RISC-V, we have looked for a solution that is as simple as possible while maximizing value with respect to the time invested in implementing, maintaining, and using the tools and procedures. - -The suggested solution makes use of: - -- an AsciiDoc `role`. -- modification of two files in the Ruby gem with code snippets (see procedure in the README for https://github.com/riscv/docs-templates). -- Git features. -- a few procedures associated, specifically, with Git updates. - -==== Indicate changes - -Indicators for the changed lines must be inserted manually: - -[source,adoc] ----- -[.Changed]#SELECT clause# - -Text without the change bar - -[.Changed]#Text with the change bar# ----- - -[.Changed]#SELECT clause# - -Text without the change bar - -[.Changed]#Text with the change bar# - - -For change bars associated with headings, place the change indicator after the heading indicator and before the text, like the following: - ----- -== [.Changed]#SELECT clause# ----- - -==== Check for changed lines before a `git commit` - -You can double check for all changed lines before committing by using this pattern: - -[source,cmd] ----- -git blame | grep -n '^0\{8\} ' | cut -f1 -d: ----- - -This lists the line numbers of changes within the specified file like the following example: - -[source,cmd] ----- -5 -38 -109 -237 ----- - - -=== Footnotes - -AsciiDoc has a limitation in that footnotes appear at the end of each chapter. Asciidoctor does not support footnotes appearing at the bottom of each page. - -You can add footnotes to your presentation using the footnote macro. If you plan to reference a footnote more than once, use the footnote macro with a target that you identify in the brackets. - -[source,adoc] ----- -Initiate the hail-and-rainbow protocol at one of three levels: - -- doublefootnote:[The double hail-and-rainbow level makes my toes tingle.] -- tertiary -- apocalyptic - -A bold statement!footnote:disclaimer[Opinions are my own.] - -Another outrageous statement.footnote:disclaimer[] ----- - -Renders as: - -The hail-and-rainbow protocol can be initiated at three levels: - -- doublefootnote:[The double hail-and-rainbow level makes my toes tingle.] -- tertiary -- apocalyptic - -A bold statement!footnote:disclaimer[Opinions are my own.] - -Another outrageous statement.footnote:disclaimer[] - -=== Sidebars - -Sidebars provide for a form of commentary. - -[source,adoc] ----- - -**** -This is content in a sidebar block. - -image:example-3.svg[] - -This is more content in the sidebar block. -**** ----- - -This renders as follows: - -**** -This is content in a sidebar block. - -image:example-3.svg[] - -This is more content in the sidebar block. -**** - - -You can add a title, along with any kind of content. Best practice for many of the "commentaries" in the LaTeX source that elucidate the decision-making process is to convert to this format with the `TIP` icon that illustrates a conversation or discussion, as in the following example: - -[source,adoc] ----- -.Optional Title -**** -Sidebars are used to visually separate auxiliary bits of content -that supplement the main text. - -TIP: They can contain any type of content, including admonitions like this, and code examples like the following. - -.Source code block within a sidebar -[source,js] -/---- (1) -const { expect, expectCalledWith, heredoc } = require('../test/test-utils') -/---- (2) -**** - ----- - -1 and 2. Escapes are necessary to preserve this as an AsciiDoc code example. - -Once the escapes are removed, the above renders with both the admonition and code blocks within the sidebar: - -.Optional Title -**** -Sidebars are used to visually separate auxiliary bits of content -that supplement the main text. - -TIP: They can contain any type of content, including admonitions like this, and code examples like the following. - -.Source code block in a sidebar -[source,js] ----- -const { expect, expectCalledWith, heredoc } = require('../test/test-utils') ----- -**** diff --git a/src/docs-dev-guide.adoc b/src/docs-dev-guide.adoc index bfb9d23..3e5238e 100755 --- a/src/docs-dev-guide.adoc +++ b/src/docs-dev-guide.adoc @@ -76,10 +76,6 @@ include::authoring.adoc[] include::a_few_basics.adoc[] -include::tables_symbols_math.adoc[] - -include::blocks_notes_markers.adoc[] - include::index_bib.adoc[] include::graphics.adoc[] diff --git a/src/tables_symbols_math.adoc b/src/tables_symbols_math.adoc deleted file mode 100644 index e8bba5e..0000000 --- a/src/tables_symbols_math.adoc +++ /dev/null @@ -1,359 +0,0 @@ -[[tables_symbols_math]] -=== Tables - -By using tables, you can group information into logical units, which can make the infromation presented easier to understand. - -[[tables-gen]] -==== General rules for tables -Follow these general rules when you create a table. - -* Avoid tables in the middle of lists. -* Do not use tables to lay out a page. For example, if you have a long list of items, do not use a 2 column table to save space. The information should make sense side by side. -* Do not create a table that has a single row or a single column, unless you are following a previous layout. For example, if each section in a chapter includes a table of options, then use a table even if one of the sections has only a single option. -* Always use table headers and captions to make your tables more accessible. -* Use introductory sentences for your table. For example, "The following table contains the options for the CSR." You can use either a period or a colon for your introductory sentence. -* Do not refer to the "table above" or the "below table". Use words such as "The following table" or "The preceeding table". - -[WARNING] -==== -*Never* use automated wrapping for table titles, figure captions, and example captions. Asciidoctor reads a hard return as an indicator to start a new "Normal" paragraph. -==== - -==== Simple table - -The following example shows a simple table with 2 rows and 2 columns. To indicate a new row, put a empty line between them. - -[source,adoc] ----- -[cols="1,1"] -|=== -|Cell in column 1, row 1 -|Cell in column 2, row 1 - -|Cell in column 1, row 2 -|Cell in column 2, row 2 -|=== ----- - -Results in the following table. - -[cols="1,1"] -|=== -|Cell in column 1, row 1 -|Cell in column 2, row 1 - -|Cell in column 1, row 2 -|Cell in column 2, row 2 -|=== - -==== Adding table headers - -Headers can add additional information to your table, making them easier to understand. - -You can add a header row by adding the first row of cells directly in a line. - ----- -[cols="1,1,1"] -|=== -|Col 1, header row|Col 2, header row|Col 3, header row - -|Cell in col 1, row 2 -|Cell in col 2, row 2 -|Cell in col 3, row 2 -|=== ----- - -Or you can use the `header` option. - ----- -[%header,cols="1,1,1"] -|=== -|Col 1, header row -|Col 2, header row -|Col 3, header row - -|Cell in col 1, row 2 -|Cell in col 2, row 2 -|Cell in col 3, row 2 -|=== ----- - -Either table renders with table headers. - -[cols="1,1,1"] -|=== -|Col 1, header row|Col 2, header row|Col 3, header row - -|Cell in col 1, row 2 -|Cell in col 2, row 2 -|Cell in col 3, row 2 -|=== - -==== Table captions - -The `book_header.adoc` file in the docs-templates repo sets the `full` cross-reference attribute to enable captions to display from targets in the anchors. This ability allows you to set captions for tables, blocks, and illustrations. If you do not provide a caption, Asciidoctor defaults to the _basic_ cross reference style. - -To set a caption for a table or image, use the pattern as follows: - -[source,adoc] ----- -The following table, <> shows the characteristics of each kind of trap. ----- - -[source,adoc] ----- -[[trapcharacteristics,Characteristics of traps]] -.Characteristics of traps. -[cols="<,^,^,^,^",options="header",] -|=== -| |Contained |Requested |Invisible |Fatal -|Execution terminates |No |Nolatexmath:[$^{1}$] |No |Yes -|Software is oblivious |No |No |Yes |Yeslatexmath:[$^{2}$] -|Handled by environment |No |Yes |Yes |Yes -|=== ----- - -The following table, <> shows the characteristics of each -kind of trap. - -[[trapcharacteristics]] -.Characteristics of traps. -[cols="<,^,^,^,^",options="header",] -|=== -| |Contained |Requested |Invisible |Fatal -|Execution terminates |No |Nolatexmath:[$^{1}$] |No |Yes -|Software is oblivious |No |No |Yes |Yeslatexmath:[$^{2}$] -|Handled by environment |No |Yes |Yes |Yes -|=== - - -==== AsciiDoc tables from CSV data. - -AsciiDoc tables can also be created directly from CSV data. Set the format block attribute to `csv` and insert the data inside the block delimiters directly: - -[source,adoc] ----- -[%header,format=csv] -|=== -Artist,Track,Genre -Baauer,Harlem Shake,Hip Hop -The Lumineers,Ho Hey,Folk Rock -|=== ----- - -The previous example renders as follows: - -[%header,format=csv] -|=== -Artist,Track,Genre -Baauer,Harlem Shake,Hip Hop -The Lumineers,Ho Hey,Folk Rock -|=== - - -There are numerous formatting options available. While some of the property settings are cryptic, they can be quite useful. There are numerous examples available at https://asciidoc.org/newtables.html. Here one example of what can be done with spans alignment in tables from that page: - -[source,adoc] ----- -[cols="e,m,^,>s",width="25%"] -|============================ -|1 >s|2 |3 |4 -^|5 2.2+^.^|6 .3+<.>m|7 -^|8 -|9 2+>|10 -|============================ ----- - -Which renders as follows: - -[cols="e,m,^,>s",width="25%"] -|============================ -|1 >s|2 |3 |4 -^|5 2.2+^.^|6 .3+<.>m|7 -^|8 -|9 2+>|10 -|============================ - -The following example is code for a numbered encoding table with link target. - -NOTE: Annotations have been added to the code to illustrate their use. - -[source,adoc] ----- -[[proposed-16bit-encodings-1] <1> -.proposed 16-bit encodings-1 <2> -[width="100%",options=header] -|=== -|15 |14 |13 |12 |11 |10 |9 |8 |7 |6 |5 |4 |3 |2 |1 |0 |instruction -3+|100|1|0|0|0 2+|field|0 |0 2+|00 | field 2+|00|mnemonic1 -3+|100|1|0|0 3+|field|bit|1 3+|field 2+|00|mnemonic2 -3+|110|1|0|0 3+|field|1 |0 3+|field 2+|00|mnemonic3 -17+|This row spans the whole table -3+|100|1|1|1 8+| field 2+| 00 | mnemonic4 -|=== ----- -. Link target. -. Numbered table title. - -The previous example results in the following table. - -[#proposed-16bit-encodings-1] -.proposed 16-bit encodings-1 -[width="100%",options=header] -|=== -|15 |14 |13 |12 |11 |10 |9 |8 |7 |6 |5 |4 |3 |2 |1 |0 |instruction -3+|100|1|0|0|0 2+|field|0 |0 2+|00 | field 2+|00|mnemonic1 -3+|100|1|0|0 3+|field|bit|1 3+|field 2+|00|mnemonic2 -3+|110|1|0|0 3+|field|1 |0 3+|field 2+|00|mnemonic3 -17+|This row spans the whole table -3+|100|1|1|1 8+| field 2+| 00 | mnemonic4 -|=== - -=== Unicode symbols - -For PDFs, five-digit unicode symbols generally don't work and some other unicode symbols are buggy. This failure happens because the Ruby asciidoctor-pdf toolchain makes use of Prawn to build PDFs and it's Prawn that has the problems. - -Here are a few unicode examples from https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references that might be useful: - -As an example, ♦ is encoded as follows: - -```unicode -♦ -``` - -[[useful-unicode]] -.Useful unicode for specifications -[width="100%",options=header,format=csv] -|=== -sym,num,name -^,94,caret -ˆ,136, -⋮,8942,vdots -♦,9830,name -",0034,name -w,0077,w -∴,8756,therefore -♯,9839,sharp -ш,1096,shcy -ϖ,982,piv varpi -ω,969,omega -℘,8472,weierp wp -∑,8721,sum -∞,8734,infin -∫,8747,integral -≠,8800,not equal to -≤,8804,le -≥,8805,ge -≈,8776,numerical approximation -D,68,mathematical D? -⇒,8658,rightwards double arrow -X,88,Latin Capital x -χ,967,Greek x -×,215,times -☑,9745,boxed checkmark -r,114,latin small letter r -|=== - -For many other symbols, use asciidoctor-mathematical. See <>. - -[[unicode-not-working]] -.Unicode identified as not working -[width="100%",options=header,format=csv] -|=== -sym,num,name -⍼,9084,angzarr not working -⋙,8921,ggg not working -↩,8617,hookleftarrow not working -⍻,9083,not checkmark not working -|=== - - -=== Mathematical notations - -WARNING: Asciidoctor-mathematical has some limitations. For inline expressions, the graphical representations appear small and they are centered vertically. In some cases where there is a single-character Asciidoctor-mathematical expression, it unintentionally looks like a superscript. For this reason, always use viable alternatives like _italics_ or unicode (see <>). - - -==== Superscripts and subscripts - -To indicate a superscript, enclose the string for the superscript in carets as in the following example: - ----- -2^8^ ----- - -Which renders as: - -2^8^ - -You can indicate text in a superscript as well: - ----- -1234^NOTE^ ----- - -Which renders as: - -1234^NOTE^ - -For subscripts, use tildes: - ----- -C~2~ H~6~ ----- - -With the following result: - -C~2~ H~6~ - -An example: ----- -"`Well the H~2~O formula written on their whiteboard could be part -of a shopping list, but I don't think the local bodega sells -E=mc^2^,`" Lazarus replied. ----- - -Renders as: - -"Well the H~2~O formula written on their whiteboard could be part -of a shopping list, but I don't think the local bodega sells -E=mc^2^," Lazarus replied. - -==== Latexmath - -You can make use of LaTeX notation as in the following: - ----- -latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$] ----- - -Which renders as: - -latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$] - -[TIP] -==== -Latexmath rendering has some limitations with respect to sizing and placement inline. This happens because of how the images for the mathematical symbols are rendered within the build process. For this reason, please avoid using single character latexmath expressions inline and preferentially make use of unicode or superscripts and subscripts when possible. -==== - -==== Stem content - -The `:stem: latexmath` setting makes use of asciidoctor-mathematical for asciidoctor-pdf output. - -Asciidoctor Mathematical is a Ruby gem that uses native extensions. It has a few system prerequisites which limit installation to Linux and macOS. Please refer to the https://github.com/riscv/docs-templates[README in the RISC-V docs-templates repo] for information on the asciidoctor-mathematical install. - -[source,adoc] ----- -[stem] -++++ -sqrt(4) = 2 -++++ ----- - -[stem] -++++ -sqrt(4) = 2 -++++ - -In some cases, you might want to make use of unicode characters. Keep in mind that asciidoctor-pdf supports only decimal character references. See https://github.com/asciidoctor/asciidoctor-pdf/issues/486 - -For updates to asciidoctor-pdf, see https://github.com/asciidoctor/asciidoctor-pdf.