From de1457c932aa6829781869d99096b3f9c3ae34e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ciro=20Santilli=20=E5=85=AD=E5=9B=9B=E4=BA=8B=E4=BB=B6=20?= =?UTF-8?q?=E6=B3=95=E8=BD=AE=E5=8A=9F?= Date: Fri, 5 Jul 2019 00:00:00 +0000 Subject: [PATCH] readme: setup github pages to overcome 512k limit --- .gitignore | 24 +-- Gemfile | 2 + Gemfile.lock | 237 ++++++++++++++++++++++++++++++ README.adoc | 102 +++++++++---- _config.yml | 6 + asciidoctor/link-target-github.rb | 19 +++ asciidoctor/link-target-up.rb | 16 +- build-doc | 14 +- publish-gh-pages | 15 ++ 9 files changed, 384 insertions(+), 51 deletions(-) create mode 100644 _config.yml create mode 100644 asciidoctor/link-target-github.rb create mode 100755 publish-gh-pages diff --git a/.gitignore b/.gitignore index f8fbe8c..65082fe 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,8 @@ -# Extensions and prefixes. +# Important directories. +/out +/data + +# Temporary files. *.tmp tmp.* *.tmp.* @@ -6,12 +10,11 @@ tmp.* *.gitignore gitignore.* -# Specific files. -/data -/gem5/out +# https://github.com/cirosantilli/linux-kernel-module-cheat#prebuilt /lkmc-*.zip -/out -/out.* + +# https://github.com/cirosantilli/linux-kernel-module-cheat#bst-vs-heap-vs-hashmap +*.dat # Python trash. *.pyc @@ -23,15 +26,12 @@ __pycache__ *.o *.out -# Data to be plotted output. -*.dat - # Kernel modules. -.cache.mk +*.ko *.ko.cmd +*.mod.c *.o.cmd +.cache.mk .tmp_versions Module.symvers -*.ko -*.mod.c modules.order diff --git a/Gemfile b/Gemfile index 4b692fd..e8b6ab5 100644 --- a/Gemfile +++ b/Gemfile @@ -1,3 +1,5 @@ source 'https://rubygems.org' gem 'asciidoctor', '2.0.10' +#gem 'jekyll', '3.8.6' +gem 'github-pages' diff --git a/Gemfile.lock b/Gemfile.lock index 8972e7d..5f20acb 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -1,13 +1,250 @@ GEM remote: https://rubygems.org/ specs: + activesupport (4.2.11.1) + i18n (~> 0.7) + minitest (~> 5.1) + thread_safe (~> 0.3, >= 0.3.4) + tzinfo (~> 1.1) + addressable (2.6.0) + public_suffix (>= 2.0.2, < 4.0) asciidoctor (2.0.10) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.11.1) + colorator (1.1.0) + commonmarker (0.17.13) + ruby-enum (~> 0.5) + concurrent-ruby (1.1.5) + dnsruby (1.61.2) + addressable (~> 2.5) + em-websocket (0.5.1) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0.6.0) + ethon (0.12.0) + ffi (>= 1.3.0) + eventmachine (1.2.7) + execjs (2.7.0) + faraday (0.15.4) + multipart-post (>= 1.2, < 3) + ffi (1.11.1) + forwardable-extended (2.6.0) + gemoji (3.0.1) + github-pages (198) + activesupport (= 4.2.11.1) + github-pages-health-check (= 1.16.1) + jekyll (= 3.8.5) + jekyll-avatar (= 0.6.0) + jekyll-coffeescript (= 1.1.1) + jekyll-commonmark-ghpages (= 0.1.5) + jekyll-default-layout (= 0.1.4) + jekyll-feed (= 0.11.0) + jekyll-gist (= 1.5.0) + jekyll-github-metadata (= 2.12.1) + jekyll-mentions (= 1.4.1) + jekyll-optional-front-matter (= 0.3.0) + jekyll-paginate (= 1.1.0) + jekyll-readme-index (= 0.2.0) + jekyll-redirect-from (= 0.14.0) + jekyll-relative-links (= 0.6.0) + jekyll-remote-theme (= 0.3.1) + jekyll-sass-converter (= 1.5.2) + jekyll-seo-tag (= 2.5.0) + jekyll-sitemap (= 1.2.0) + jekyll-swiss (= 0.4.0) + jekyll-theme-architect (= 0.1.1) + jekyll-theme-cayman (= 0.1.1) + jekyll-theme-dinky (= 0.1.1) + jekyll-theme-hacker (= 0.1.1) + jekyll-theme-leap-day (= 0.1.1) + jekyll-theme-merlot (= 0.1.1) + jekyll-theme-midnight (= 0.1.1) + jekyll-theme-minimal (= 0.1.1) + jekyll-theme-modernist (= 0.1.1) + jekyll-theme-primer (= 0.5.3) + jekyll-theme-slate (= 0.1.1) + jekyll-theme-tactile (= 0.1.1) + jekyll-theme-time-machine (= 0.1.1) + jekyll-titles-from-headings (= 0.5.1) + jemoji (= 0.10.2) + kramdown (= 1.17.0) + liquid (= 4.0.0) + listen (= 3.1.5) + mercenary (~> 0.3) + minima (= 2.5.0) + nokogiri (>= 1.8.5, < 2.0) + rouge (= 2.2.1) + terminal-table (~> 1.4) + github-pages-health-check (1.16.1) + addressable (~> 2.3) + dnsruby (~> 1.60) + octokit (~> 4.0) + public_suffix (~> 3.0) + typhoeus (~> 1.3) + html-pipeline (2.11.0) + activesupport (>= 2) + nokogiri (>= 1.4) + http_parser.rb (0.6.0) + i18n (0.9.5) + concurrent-ruby (~> 1.0) + jekyll (3.8.5) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 0.7) + jekyll-sass-converter (~> 1.0) + jekyll-watch (~> 2.0) + kramdown (~> 1.14) + liquid (~> 4.0) + mercenary (~> 0.3.3) + pathutil (~> 0.9) + rouge (>= 1.7, < 4) + safe_yaml (~> 1.0) + jekyll-avatar (0.6.0) + jekyll (~> 3.0) + jekyll-coffeescript (1.1.1) + coffee-script (~> 2.2) + coffee-script-source (~> 1.11.1) + jekyll-commonmark (1.3.1) + commonmarker (~> 0.14) + jekyll (>= 3.7, < 5.0) + jekyll-commonmark-ghpages (0.1.5) + commonmarker (~> 0.17.6) + jekyll-commonmark (~> 1) + rouge (~> 2) + jekyll-default-layout (0.1.4) + jekyll (~> 3.0) + jekyll-feed (0.11.0) + jekyll (~> 3.3) + jekyll-gist (1.5.0) + octokit (~> 4.2) + jekyll-github-metadata (2.12.1) + jekyll (~> 3.4) + octokit (~> 4.0, != 4.4.0) + jekyll-mentions (1.4.1) + html-pipeline (~> 2.3) + jekyll (~> 3.0) + jekyll-optional-front-matter (0.3.0) + jekyll (~> 3.0) + jekyll-paginate (1.1.0) + jekyll-readme-index (0.2.0) + jekyll (~> 3.0) + jekyll-redirect-from (0.14.0) + jekyll (~> 3.3) + jekyll-relative-links (0.6.0) + jekyll (~> 3.3) + jekyll-remote-theme (0.3.1) + jekyll (~> 3.5) + rubyzip (>= 1.2.1, < 3.0) + jekyll-sass-converter (1.5.2) + sass (~> 3.4) + jekyll-seo-tag (2.5.0) + jekyll (~> 3.3) + jekyll-sitemap (1.2.0) + jekyll (~> 3.3) + jekyll-swiss (0.4.0) + jekyll-theme-architect (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-cayman (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-dinky (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-hacker (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-leap-day (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-merlot (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-midnight (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-minimal (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-modernist (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-primer (0.5.3) + jekyll (~> 3.5) + jekyll-github-metadata (~> 2.9) + jekyll-seo-tag (~> 2.0) + jekyll-theme-slate (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-tactile (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-theme-time-machine (0.1.1) + jekyll (~> 3.5) + jekyll-seo-tag (~> 2.0) + jekyll-titles-from-headings (0.5.1) + jekyll (~> 3.3) + jekyll-watch (2.2.1) + listen (~> 3.0) + jemoji (0.10.2) + gemoji (~> 3.0) + html-pipeline (~> 2.2) + jekyll (~> 3.0) + kramdown (1.17.0) + liquid (4.0.0) + listen (3.1.5) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + ruby_dep (~> 1.2) + mercenary (0.3.6) + mini_portile2 (2.4.0) + minima (2.5.0) + jekyll (~> 3.5) + jekyll-feed (~> 0.9) + jekyll-seo-tag (~> 2.1) + minitest (5.11.3) + multipart-post (2.1.1) + nokogiri (1.10.3) + mini_portile2 (~> 2.4.0) + octokit (4.14.0) + sawyer (~> 0.8.0, >= 0.5.3) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (3.1.1) + rb-fsevent (0.10.3) + rb-inotify (0.10.0) + ffi (~> 1.0) + rouge (2.2.1) + ruby-enum (0.7.2) + i18n + ruby_dep (1.5.0) + rubyzip (1.2.3) + safe_yaml (1.0.5) + sass (3.7.4) + sass-listen (~> 4.0.0) + sass-listen (4.0.0) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + sawyer (0.8.2) + addressable (>= 2.3.5) + faraday (> 0.8, < 2.0) + terminal-table (1.8.0) + unicode-display_width (~> 1.1, >= 1.1.1) + thread_safe (0.3.6) + typhoeus (1.3.1) + ethon (>= 0.9.0) + tzinfo (1.2.5) + thread_safe (~> 0.1) + unicode-display_width (1.6.0) PLATFORMS ruby DEPENDENCIES asciidoctor (= 2.0.10) + github-pages BUNDLED WITH 2.0.2 diff --git a/README.adoc b/README.adoc index bf295fd..fb9786e 100644 --- a/README.adoc +++ b/README.adoc @@ -13,6 +13,8 @@ The perfect emulation setup to study and develop the <> v5.1, kern TL;DR: <> +The source code for this page is located at: https://github.com/cirosantilli/linux-kernel-module-cheat[]. Due to link:https://github.com/isaacs/github/issues/1610[a GitHub limitation], this README is too long and not fully rendered on github.com. Either use: https://www.cirosantilli.com/linux-kernel-module-cheat or <>. + toc::[] == Getting started @@ -1371,8 +1373,8 @@ continue See also: -* http://stackoverflow.com/questions/11408041/how-to-debug-the-linux-kernel-with-gdb-and-qemu/33203642#33203642 -* http://stackoverflow.com/questions/4943857/linux-kernel-live-debugging-how-its-done-and-what-tools-are-used/42316607#42316607 +* https://stackoverflow.com/questions/11408041/how-to-debug-the-linux-kernel-with-gdb-and-qemu/33203642#33203642 +* https://stackoverflow.com/questions/4943857/linux-kernel-live-debugging-how-its-done-and-what-tools-are-used/42316607#42316607 ==== GDB step debug kernel boot other archs @@ -1545,7 +1547,7 @@ From inside tmux, you can create new terminals on a new window with `Ctrl-B C` s === GDB step debug kernel module -http://stackoverflow.com/questions/28607538/how-to-debug-linux-kernel-modules-with-qemu/44095831#44095831 +https://stackoverflow.com/questions/28607538/how-to-debug-linux-kernel-modules-with-qemu/44095831#44095831 Loadable kernel modules are a bit trickier since the kernel can place them at different memory locations depending on load order. @@ -4417,7 +4419,7 @@ TODO <> failed on `aarch64` with: kmscube[706]: unhandled level 2 translation fault (11) at 0x00000000, esr 0x92000006, in libgbm.so.1.0.0[7fbf6a6000+e000] .... -Tested on: link:http://github.com/cirosantilli/linux-kernel-module-cheat/commit/38fd6153d965ba20145f53dc1bb3ba34b336bde9[38fd6153d965ba20145f53dc1bb3ba34b336bde9] +Tested on: link:https://github.com/cirosantilli/linux-kernel-module-cheat/commit/38fd6153d965ba20145f53dc1bb3ba34b336bde9[38fd6153d965ba20145f53dc1bb3ba34b336bde9] ==== Graphic mode gem5 aarch64 @@ -6570,7 +6572,7 @@ sh -x ./fops.sh We have put printks on each fop, so this allows you to see which system calls are being made for each command. -No, there no official documentation: http://stackoverflow.com/questions/15213932/what-are-the-struct-file-operations-arguments +No, there no official documentation: https://stackoverflow.com/questions/15213932/what-are-the-struct-file-operations-arguments ==== seq_file @@ -6843,8 +6845,8 @@ The sleep is done with `usleep_range`, see: <>. Bibliography: -* http://stackoverflow.com/questions/10177641/proper-way-of-handling-threads-in-kernel -* http://stackoverflow.com/questions/4084708/how-to-wait-for-a-linux-kernel-thread-kthreadto-exit +* https://stackoverflow.com/questions/10177641/proper-way-of-handling-threads-in-kernel +* https://stackoverflow.com/questions/4084708/how-to-wait-for-a-linux-kernel-thread-kthreadto-exit ==== kthreads @@ -7041,7 +7043,7 @@ Therefore they produce more accurate timing than thread scheduling, which is mor Bibliography: -* http://stackoverflow.com/questions/10812858/timers-in-linux-device-drivers +* https://stackoverflow.com/questions/10812858/timers-in-linux-device-drivers * https://gist.github.com/yagihiro/310149 === IRQ @@ -7831,7 +7833,7 @@ It only appears once on every log I've seen so far, checked with `grep 0x1000000 + Then when we count the instructions that run before the kernel entry point, there is only about 100k instructions, which is insignificant compared to the kernel boot itself. + -TODO `--arch arm` and `--arch aarch64` does not count firmware instructions properly because the entry point address of the ELF file (`ffffff8008080000` for `aarch64`) does not show up on the trace at all. Tested on link:http://github.com/cirosantilli/linux-kernel-module-cheat/commit/f8c0502bb2680f2dbe7c1f3d7958f60265347005[f8c0502bb2680f2dbe7c1f3d7958f60265347005]. +TODO `--arch arm` and `--arch aarch64` does not count firmware instructions properly because the entry point address of the ELF file (`ffffff8008080000` for `aarch64`) does not show up on the trace at all. Tested on link:https://github.com/cirosantilli/linux-kernel-module-cheat/commit/f8c0502bb2680f2dbe7c1f3d7958f60265347005[f8c0502bb2680f2dbe7c1f3d7958f60265347005]. * We can also discount the instructions after `init` runs by using `readelf` to get the initial address of `init`. One easy way to do that now is to just run: + .... @@ -8492,7 +8494,7 @@ Bibliography: * https://en.wikipedia.org/wiki/Direct_Rendering_Manager * https://en.wikipedia.org/wiki/Mode_setting KMS -Tested on: link:http://github.com/cirosantilli/linux-kernel-module-cheat/commit/93e383902ebcc03d8a7ac0d65961c0e62af9612b[93e383902ebcc03d8a7ac0d65961c0e62af9612b] +Tested on: link:https://github.com/cirosantilli/linux-kernel-module-cheat/commit/93e383902ebcc03d8a7ac0d65961c0e62af9612b[93e383902ebcc03d8a7ac0d65961c0e62af9612b] ==== kmscube @@ -8541,7 +8543,7 @@ failed to initialize legacy DRM See also: https://github.com/robclark/kmscube/issues/12 and https://stackoverflow.com/questions/26920835/can-egl-application-run-in-console-mode/26921287#26921287 -Tested on: link:http://github.com/cirosantilli/linux-kernel-module-cheat/commit/2903771275372ccfecc2b025edbb0d04c4016930[2903771275372ccfecc2b025edbb0d04c4016930] +Tested on: link:https://github.com/cirosantilli/linux-kernel-module-cheat/commit/2903771275372ccfecc2b025edbb0d04c4016930[2903771275372ccfecc2b025edbb0d04c4016930] ==== kmscon @@ -9386,7 +9388,7 @@ and go back to the terminal with: Ctrl-A C .... -* http://stackoverflow.com/questions/14165158/how-to-switch-to-qemu-monitor-console-when-running-with-curses +* https://stackoverflow.com/questions/14165158/how-to-switch-to-qemu-monitor-console-when-running-with-curses * https://superuser.com/questions/488263/how-to-switch-to-the-qemu-control-panel-with-nographics When in graphic mode, we can do it from the GUI: @@ -10372,7 +10374,7 @@ Source: link:userland/libs/eigen/hello.cpp[] This example just creates a matrix and prints it out. -Tested on: link:http://github.com/cirosantilli/linux-kernel-module-cheat/commit/a4bdcf102c068762bb1ef26c591fcf71e5907525[a4bdcf102c068762bb1ef26c591fcf71e5907525] +Tested on: link:https://github.com/cirosantilli/linux-kernel-module-cheat/commit/a4bdcf102c068762bb1ef26c591fcf71e5907525[a4bdcf102c068762bb1ef26c591fcf71e5907525] ===== PARSEC benchmark @@ -11328,7 +11330,7 @@ We setup 2 big and 2 small CPUs, but `cat /proc/cpuinfo` shows 4 identical CPUs TODO: why is the `--dtb` required despite `fs_bigLITTLE.py` having a DTB generation capability? Without it, nothing shows on terminal, and the simulation terminates with `simulate() limit reached @ 18446744073709551615`. The magic `vmlinux.vexpress_gem5_v1.20170616` works however without a DTB. -Tested on: link:http://github.com/cirosantilli/linux-kernel-module-cheat/commit/18c1c823feda65f8b54cd38e261c282eee01ed9f[18c1c823feda65f8b54cd38e261c282eee01ed9f] +Tested on: link:https://github.com/cirosantilli/linux-kernel-module-cheat/commit/18c1c823feda65f8b54cd38e261c282eee01ed9f[18c1c823feda65f8b54cd38e261c282eee01ed9f] === gem5 unit tests @@ -12065,7 +12067,7 @@ Particularly important numerical analysis instruction, that is used in particula FMA is so important that <> specifies it with single precision drop compared to a separate add and multiply! -Micro-op fun: http://stackoverflow.com/questions/28630864/how-is-fma-implemented +Micro-op fun: https://stackoverflow.com/questions/28630864/how-is-fma-implemented Historically, FMA instructions have been added relatively late to instruction sets. @@ -12331,8 +12333,8 @@ Official specification: http://infocenter.arm.com/help/topic/com.arm.doc.ihi0042 Bibliography: * https://en.wikipedia.org/wiki/Calling_convention#ARM_(A32) Wiki contains the master list as usual. -* http://stackoverflow.com/questions/8422287/calling-c-functions-from-arm-assembly -* http://stackoverflow.com/questions/261419/arm-to-c-calling-convention-registers-to-save +* https://stackoverflow.com/questions/8422287/calling-c-functions-from-arm-assembly +* https://stackoverflow.com/questions/261419/arm-to-c-calling-convention-registers-to-save * https://stackoverflow.com/questions/10494848/arm-whats-the-difference-between-apcs-and-aapcs-abi === GNU GAS assembler @@ -12455,7 +12457,7 @@ Bibliography: https://stackoverflow.com/questions/27147043/n-suffix-to-branch-in link:userland/arch/x86_64/char_literals.S[] -http://stackoverflow.com/questions/33246811/how-to-use-character-literals-in-gnu-gas-to-replace-numbers +https://stackoverflow.com/questions/33246811/how-to-use-character-literals-in-gnu-gas-to-replace-numbers This syntax plays horribly with the C preprocessor: @@ -12474,7 +12476,7 @@ No OPeration. Does nothing except take up one processor cycle and occupy some instruction memory. -Applications: http://stackoverflow.com/questions/234906/whats-the-purpose-of-the-nop-opcode +Applications: https://stackoverflow.com/questions/234906/whats-the-purpose-of-the-nop-opcode == x86 userland assembly @@ -12616,7 +12618,7 @@ mov (%rsp), %rax add $8, %rsp .... -Why do those instructions exist at all vs MOV / ADD / SUB: http://stackoverflow.com/questions/4584089/what-is-the-function-of-push-pop-registers-in-x86-assembly/33583134#33583134 +Why do those instructions exist at all vs MOV / ADD / SUB: https://stackoverflow.com/questions/4584089/what-is-the-function-of-push-pop-registers-in-x86-assembly/33583134#33583134 ==== x86 CQTO and CLTQ instructions @@ -12697,14 +12699,14 @@ where `cc` are the same flags as Jcc. Vs jmp: -* http://stackoverflow.com/questions/14131096/why-is-a-conditional-move-not-vulnerable-for-branch-prediction-failure -* http://stackoverflow.com/questions/27136961/what-is-it-about-cmov-which-improves-cpu-pipeline-performance -* http://stackoverflow.com/questions/26154488/difference-between-conditional-instructions-cmov-and-jump-instructions -* http://stackoverflow.com/questions/6754454/speed-difference-between-if-else-and-ternary-operator-in-c?lq=1#comment8007791_6754495 +* https://stackoverflow.com/questions/14131096/why-is-a-conditional-move-not-vulnerable-for-branch-prediction-failure +* https://stackoverflow.com/questions/27136961/what-is-it-about-cmov-which-improves-cpu-pipeline-performance +* https://stackoverflow.com/questions/26154488/difference-between-conditional-instructions-cmov-and-jump-instructions +* https://stackoverflow.com/questions/6754454/speed-difference-between-if-else-and-ternary-operator-in-c?lq=1#comment8007791_6754495 Not necessarily faster because of branch prediction. -This is partly why the ternary `?` C operator exists: http://stackoverflow.com/questions/3565368/ternary-operator-vs-if-else +This is partly why the ternary `?` C operator exists: https://stackoverflow.com/questions/3565368/ternary-operator-vs-if-else It is interesting to compare this with ARMv7 conditional executaion: which is available for all instructions: <> @@ -12880,7 +12882,7 @@ REP and REPZ also additionally stop if the comparison operation they repeat fail link:userland/arch/x86_64/enter.S[] -These instructions were designed to allocate and deallocate function stack frames in the prologue and epilogue: http://stackoverflow.com/questions/5959890/enter-vs-push-ebp-mov-ebp-esp-sub-esp-imm-and-leave-vs-mov-esp-ebp +These instructions were designed to allocate and deallocate function stack frames in the prologue and epilogue: https://stackoverflow.com/questions/5959890/enter-vs-push-ebp-mov-ebp-esp-sub-esp-imm-and-leave-vs-mov-esp-ebp ENTER appears obsolete and is kept mostly for backwards compatibility. LEAVE is still emitted by some compilers. @@ -12897,7 +12899,7 @@ which implies an allocation of: * one dword to remember EBP * A bytes for local function variables -I didn't have the patience to study the B parameter, and it does not seem to be used often: http://stackoverflow.com/questions/26323215/do-any-languages-compilers-utilize-the-x86-enter-instruction-with-a-nonzero-ne +I didn't have the patience to study the B parameter, and it does not seem to be used often: https://stackoverflow.com/questions/26323215/do-any-languages-compilers-utilize-the-x86-enter-instruction-with-a-nonzero-ne LEAVE is equivalent to: @@ -13005,7 +13007,7 @@ Instructions such as FLDL convert standard <> 64-bit values from memor ==== x86 x87 FPU vs SIMD -http://stackoverflow.com/questions/1844669/benefits-of-x87-over-sse +https://stackoverflow.com/questions/1844669/benefits-of-x87-over-sse Modern x86 has two main ways of doing floating point operations: @@ -13622,7 +13624,7 @@ The registers are encoded as single bits inside the instruction: each bit repres As a consequence, the push order is fixed no matter how you write the assembly instruction: there is just not enough space to encode ordering. -AArch64 loses those instructions, likely because it was not possible anymore to encode all registers: http://stackoverflow.com/questions/27941220/push-lr-and-pop-lr-in-arm-arch64 and replaces them with the <> +AArch64 loses those instructions, likely because it was not possible anymore to encode all registers: https://stackoverflow.com/questions/27941220/push-lr-and-pop-lr-in-arm-arch64 and replaces them with the <> === ARM data processing instructions @@ -15772,7 +15774,9 @@ but note that this does not include script specific options. === Build the documentation -You don't need to depend on GitHub. To build the first time use: +You don't need to depend on GitHub. + +To build the first time use: .... ./build --download-dependencies docs @@ -15794,7 +15798,6 @@ Then just open the HTML output at: xdg-open out/README.html .... -[[documentation-verification]] ==== Documentation verification When running link:build-doc[], we do the following checks: @@ -15853,6 +15856,43 @@ explicitly-given One application we have in mind for this is that as of 2.0.10 Asciidoctor does not warn on header ID collisions between auto-generated IDs: https://github.com/asciidoctor/asciidoctor/issues/3147 But this script doesn't solve that yet as it would require generating the section IDs without the `-N` suffix. Section generation happens at `Section.generate_id` in Asciidoctor code. +[[asciidoctor-link-target-up-rb]] +=== asciidoctor/link-target-up.rb + +The Asciidoctor extension scripts: + +* link:asciidoctor-link-up.rb +* link:asciidoctor-link-github.rb + +hack the README `link:` targets to make them work from: + +* inside the `out/` directory with `../` +* <>, with explicit GitHub blob URLs + +==== GitHub pages + +As mentioned before the TOC, we have to push this README to GitHub pages due to: https://github.com/isaacs/github/issues/1610 + +For now, instead of pushing with `git push`, I just remember to always push with: + +.... +./publish-gh-pages +.... + +Source: link:publish-gh-pages[] + +I'm going this way for now because: + +* the Jekyll Asciidoctor plugin is not enabled by default on GitHub: https://webapps.stackexchange.com/questions/114606/can-github-pages-render-asciidoc +* link:https://stackoverflow.com/questions/1797074/local-executing-hook-after-a-git-push[post-push hooks don't exist] +* I'm lazy to setup a proper Travis CI push +* I'm the only contributor essentially, so no problems with pull requests + +The only files used by the GitHub pages are: + +* link:Gemfile[] +* link:_config.yml[] + === Clean the build You did something crazy, and nothing seems to work anymore? diff --git a/_config.yml b/_config.yml new file mode 100644 index 0000000..9fd43ff --- /dev/null +++ b/_config.yml @@ -0,0 +1,6 @@ +exclude: [ + data/, + out/, + rootfs_overlay/etc/ld.so.cache, + submodules/, +] diff --git a/asciidoctor/link-target-github.rb b/asciidoctor/link-target-github.rb new file mode 100644 index 0000000..d1920d5 --- /dev/null +++ b/asciidoctor/link-target-github.rb @@ -0,0 +1,19 @@ +#!/usr/bin/env ruby +# +# https://github.com/cirosantilli/linux-kernel-module-cheat#asciidoctor-link-target-up-rb + +require 'asciidoctor' +require 'asciidoctor/extensions' + +require_relative 'link-target-up.rb' + +class LinkTargetGitHub < LinkTargetUp + named :link + def target_base + 'https://github.com/cirosantilli/linux-kernel-module-cheat/blob/master/' + end +end + +Asciidoctor::Extensions.register do + inline_macro LinkTargetGitHub +end diff --git a/asciidoctor/link-target-up.rb b/asciidoctor/link-target-up.rb index eecedca..897e74d 100644 --- a/asciidoctor/link-target-up.rb +++ b/asciidoctor/link-target-up.rb @@ -1,29 +1,31 @@ #!/usr/bin/env ruby -=begin -README.html links break because we place that output file in out/ -This extension hacks local link targets to the right path. -=end +# https://github.com/cirosantilli/linux-kernel-module-cheat#asciidoctor-link-target-up-rb require 'asciidoctor' require 'asciidoctor/extensions' -class Main < Asciidoctor::Extensions::InlineMacroProcessor +class LinkTargetUp < Asciidoctor::Extensions::InlineMacroProcessor use_dsl named :link ExternalLinkRegex = /^https?:\/\// + + def target_base + '..' + end + def process parent, target, attrs text = attrs[1] if text.nil? || text.empty? text = target end if !ExternalLinkRegex.match?(target) - target = File.join('..', target) + target = File.join(target_base, target) end create_anchor parent, text, type: :link, target: target end end Asciidoctor::Extensions.register do - inline_macro Main + inline_macro LinkTargetUp end diff --git a/build-doc b/build-doc index 1432cb3..9e55c9a 100755 --- a/build-doc +++ b/build-doc @@ -17,14 +17,26 @@ class Main(common.LkmcCliFunction): https://github.com/cirosantilli/linux-kernel-module-cheat#build-the-documentation ''', ) + self.add_argument( + '--github-pages', + default=False, + help=''' +Build for GitHub pages instead of a local build. This redirects all links +from the README to example sources to GitHub rather than locally. +''' + ) def timed_main(self): asciidoctor_dir = os.path.join(self.env['root_dir'], 'asciidoctor') + if self.env['github_pages']: + link_target_script = 'link-target-github.rb' + else: + link_target_script = 'link-target-up.rb' exit_status = self.sh.run_cmd( [ 'asciidoctor', LF, '--failure-level', 'info', LF, - '--require', os.path.join(asciidoctor_dir, 'link-target-up.rb'), LF, + '--require', os.path.join(asciidoctor_dir, link_target_script), LF, '--out-file', self.env['readme_out'], LF, '--trace', LF, '--verbose', LF, diff --git a/publish-gh-pages b/publish-gh-pages new file mode 100755 index 0000000..db3fb13 --- /dev/null +++ b/publish-gh-pages @@ -0,0 +1,15 @@ +#!/usr/bin/env bash +# https://github.com/cirosantilli/linux-kernel-module-cheat#github-pages +set -eu +git push +./build-doc --github-pages +git branch -D gh-pages +git checkout --orphan gh-pages +git reset +cp out/README.html index.html +git add _config.yml index.html +git commit --message "$(git log -n1 --pretty='%H' master)" +git push --force +git symbolic-ref HEAD refs/heads/master +git reset +rm index.html