freakingpenguin blog

Haunt and Hoot and Blocks oh my!

2025-03-13T00:00:00Z

This post coincides with the release of 0.2.0 of Guile Blocks, an Org Mode inspired implementation of source blocks in Guile Scheme. This post demonstrates some of the functionality I've been working on. You can find the code for this post here.

I previously wrote another post showcasing more new functionality. You can find that post here.

Hoot

Hoot is now supported! Hoot is a project by the Spritely Institute used to run Scheme code in WebAssembly (Wasm) GC-capable web browsers. From the perspective of a blogger, using Hoot works like this:

Write Scheme code that performs some kind of calculation.
Add Wasm imports to manipulate things outside the Wasm environment.
Load the Wasm module using a JavaScript shim.

That second item is where the magic happens. Imports are JavaScript functions, and can take and return values. These values can be common types like integers or strings, but also more complicated types like Scheme procedures!

In the below example, I have a Hoot block that uses two imports, one to insert text into an HTML element and one to run a Guile function on a timer.

(use-modules (guile)
             (hoot ffi)
             (ice-9 match))

(define *rotation* 0)

(define pi 3.141592654)

(define distance-max 2.0)

(define (inside-donut? coordinate)
  (match coordinate
    ((x y) (and (<= (+ (expt x 2) (expt y 2)) 1.0)
                (>= (+ (expt x 2) (expt y 2)) 0.1)))
    (e (error "Invalid coordinate" e))))

(define (coordinate->distance coordinate degrees)
  (match coordinate
    ((x y)
     (let* ((radians (* degrees pi (/ 1 180)))
            (shape-coordinate (list (/ x (cos radians)) y)))
       (if (not (inside-donut? shape-coordinate))
           (nan)
           (1+  (* (car shape-coordinate)
                   (sin radians))))))
    (e (error "Invalid coordinates" e))))

(define (distance->ascii distance)
  (define asciiscale
    ".'`^\",:;Il!i><~+_-?][}{1)(|\\/tfjrxzXYUQ0OZmwqhao*#MW&8%B@$")

  (if (nan? distance) #\space
      (string-ref asciiscale
                  ;; at distance=distance-max, we'd get (string-ref a
                  ;; (length a)), which would cause an error.
                  (min (1- (string-length asciiscale))
                       (inexact->exact (round (* (string-length asciiscale)
                                                 (/ distance distance-max))))))))

(define (coordinate->ascii coordinate rotation)
  (distance->ascii (coordinate->distance coordinate rotation)))

(define (generate-coordinates resolution)
  "Generate an equidistant list of coordinates of length @var{resolution}
between -1 and 1."
  (when (even? resolution)
    (error "Resolution must be odd." resolution))
  ;; e.g. 5->'(-1 -0.5 0 0.5 1)
  (let ((point-vals (iota (1+ resolution)
                          -1
                          ;; -1 + x*resolution = 1
                          ;; x = 2 / resolution
                          (/ 2 resolution))))
    ;; '(((-1 -1) (-1 -0.5) ...) ((-0.5 -1) ...) ...)
    (map (lambda (x)
           (map (lambda (y)
                  (list x y))
                point-vals))
         point-vals)))

(define (generate-circle resolution rotation)
  (string-join
   (map (lambda (row)
          (list->string
           (map (lambda (coordinate)
                  (coordinate->ascii coordinate rotation))
                row)))
        (generate-coordinates resolution))
   "\n"))

(define-foreign display-circle
  "my_dom" "set_element"
  (ref string) -> (ref null extern))

(define-foreign add-timer
  "my_control" "registerTimer"
  i32 (ref null extern) -> (ref null extern))

(define (update-circle)
  (let ((resolution 51))
    (set! *rotation* (if (> *rotation* 360)
                         0
                         (+ *rotation* 3)))
    (display-circle (generate-circle resolution *rotation*))))

(let ((delay-in-ms 50))
  (add-timer delay-in-ms (procedure->external update-circle)))

For those who want to set up a Hoot+Haunt environment of their own, be aware that Hoot only works on "bleeding edge" versions of Guile. If you're using Guix to set up the environment, be sure that Haunt is configured to use guile-next and not guile. Otherwise you may encounter build failures depending on how exactly you're invoking Hoot.

Here's an example of how to do that.

(define (guile->guile-next base)
  (package
    (inherit base)
    (inputs (modify-inputs (package-inputs base)
              (replace "guile" guile-next)))))

(guile->guile-next haunt)
;;=> a variant of haunt that uses guile-next

There's definitely more work to be done. For one, the JavaScript wrappers aren't handled in the most elegant way, and the scripts themselves are completely inline (as opposed to written to a file). This isn't hard for a user to fix, but it isn't great either.

It would also be nice to support more Wasm runtimes, such as Ruby or Rust. This may result in some backwards-incompatible changes to Guile Blocks's Hoot support as things are refactored.

Info!

Guile Blocks now has an info manual! An online mirror of the manual is hosted at guile-blocks.info. Forgive the rough edges, the pipeline to convert Org to TexInfo to both Info and HTML is rough.

Ngspice

Guile Blocks now supports Ngspice! As always, it is possible pipe the output from Ngspice to graphing programs like Gnuplot to generate graphs.

.title dual rc ladder
R1 int in 10k
V1 in 0 dc 0 ac 1 PULSE (0 5 1u 1u 1u 1 1)
R2 out int 1k
C1 int 0 1u
C2 out 0 100n
.control
ac dec 10 1 100k
wrdata /dev/stdout vdb(out)
.endc
.end

Guix Tricks: Managing secrets using password-store and run-time decryption scripts.

2024-12-10T12:00:00Z

Intro

Guix is a package management tool with support for declarative operation. By declarative, I mean I can write various objects—such as an operating system configuration—in a text file. Guix will take that text file and use it to create what I want. For example...

(define %simple-os
  (operating-system
    (host-name "komputilo")
    (timezone "America/New_York")
    (locale "en_US.UTF-8")

    (bootloader (bootloader-configuration
                 (bootloader grub-bootloader)
                 (targets '("/dev/sdX"))))
    (file-systems (cons (file-system
                          (device (file-system-label "my-root"))
                          (mount-point "/")
                          (type "ext4"))
                        %base-file-systems))

    (users (cons (user-account
                  (name "alice")
                  (comment "Bob's sister")
                  (group "users")
                  (supplementary-groups '("wheel" "audio" "video")))
                 %base-user-accounts))))

Generally speaking, anything stored in these files or built from them should be considered public knowledge. Even if I decide not to share the declarative files, the outputs from building them are placed in a location called the store, unencrypted and globally readable on the hard drive. It would be trivial for an attacker to capture private information from these files.

This presents a challenge. How can we use private information (i.e. secrets) in these files without leaking said secrets?

There are three solutions I can think of.

Create files containing secrets manually and avoid using Guix. Set permissions to limit readability.
Use a service to store secrets in the store encrypted, then decrypt them on boot and place them in the desired location.
Store the secrets encrypted, then run scripts to retrieve them on an as-needed basis.

In this post I will be discussing how I implement the 3rd solution. If 2 sounds interested, check out sops-guix.

Runtime Decryption and Retrieval

The Not State of the Art Solution

I store my secrets encrypted in a separate, private Git repository using password-store. For this strategy to work, the service or program being configured needs to support running a script to retrieve a secret.

Consider my git configuration. I regularly use the $ git send-email command. While I could manually decrypt my password and paste that when prompted, I would rather git do that automatically. Fortunately, git supports running an arbitrary command to retrieve the password. This is done by setting core.askPass.

I could construct my git config like this:

;; Git does not actually support arguments for askPass.
;; For brevity I am going to pretend it does.
(define rsent-git-config-file
  (plain-file "git-config"
                   "
[core]
        askPass = pass ls Passwords/MyEmailAccount"))

# Contents of .config/git/config
[core]
        askPass = pass ls Passwords/MyEmailAccount

While it works in this example, this solution is not as general purpose as it could be. This solution:

Requires an environment where the PATH environment variable is already set.
Makes it challenging to switch off of password-store in the future.
Creates an unlinked dependency in my code because I have to install password-store elsewhere.

Some of these issues can be mitigated while still invoking pass directly but I believe there's a better way.

A More Guixy Way

Instead of invoking pass directly in my git config file, I go another route. In essence, I write a function that takes a "key" for what I want to retrieve. This function returns a script that, when invoked, decrypts the secret associated with said key and returns its value.

(define rsent-get-smtp-password-script
  (get-secret-program-file "git-getpass" "Passwords/MyEmailAccount"))

(define rsent-git-config-file
  (mixed-text-file "git-config"
                   "
[core]
        askPass = " rsent-get-smtp-password-script "
"))

# Contents of .config/git/config
[core]
        askPass = /gnu/store/...-git-getpass

get-secret-program-file in turn looks something like this:

(define (get-secret-program-file name key)
  "Returns a file-like object capable of retrieving the secret for @var{key}."
  (program-file name #~(display #$(get-secret key))))

As you can probably guess, most of the magic happens in another function called get-secret. This function is quite a bit more complicated than I want to dive into, but I'll share an abbreviated version. (Until recently this function was short, but then GnuPG pinentry fun happened.)

(define (get-secret key)
  "Returns a @code{gexp} that returns the associated secret for @var{key}.
Key should be in the form of a password-store path."
  #~(begin
      (use-modules (ice-9 format)
                   (ice-9 popen)
                   (ice-9 rdelim))
      (format (current-error-port) "~!Fetching secret for ~a... " #$key)
      (let* ((port (open-input-pipe
                    (string-append
                     #$(file-append password-store "/bin/pass")
                     " ls " #$key)))
             (str (read-line port)))
        (close-pipe port)
        (when (eof-object? str)
          (error "Failed to retrieve secret for" #$key))
        (format (current-error-port) "~!done~%")
        str)))

I want to emphasize how flexible this solution is. Any arbitrary Scheme code can be placed in get-secret, invoking any combination of external programs. If in the future I want to switch to another secret management system, I only need to rework one function and everything that works with secrets will use the new system.

Conclusion

Guix does not have an official integrated method for secrets management. This leads to users creating ad-hoc solutions. One such method is creating executable scripts that can decrypt and retrieve secrets, then embedding those scripts in the appropriate program or service.

Here are the positives to this approach:

Secrets are always encrypted on disk.
Works for both Guix System and Guix Home.
It is easy to migrate between different methods for storing secrets.

However, there are limitations:

The services and/or programs being configured need to support executing programs to retrieve secrets.
User interaction is generally recommended to protect against unauthorized access.
The creator is responsible for ensuring the script is secure, especially if it is designed to operate non-interactivity
Debugging requires a thorough understanding of the context the script is running in. For example, system services have a barer environment than home services.

Guile Blocks: I Have Concepts of a Plan

2024-09-11T00:00:00Z

I recently released v0.1.0 of Guile Blocks, an Org Mode inspired implementation of source blocks in Guile Scheme. This post demonstrates some of the functionality I've been working on since then.

PlantUML

PlantUML diagrams are now supported.

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml

PlantUML was tricky to support. This is because of how PlantUML handles writing and naming the output diagram. By priority, PlantUML names the output diagram in one of two ways:

Is there a filename in the UML code? e.g. @startuml <filename> ... @enduml
What is the filename passed on the command line? e.g. $ plantuml <filename>

Option 1 is interesting, but in order to print the block, I need the PlantUML evaluator to return the filename. PlantUML is stingy and does not print the filename to stdout. This means the only way to get the output filename is by parsing the UML diagram in Guile.

This wouldn't be too bad, but unfortunately these diagrams are not restricted to @startuml tags. They may also be @startjson, @startsalt, and more. A regex could handle this, but that solution feels... icky. I want to minimize the linkage between Guile Blocks and the supported languages when possible.

Option 2 also isn't great. Behind the scenes Guile Blocks creates a temporary file (of the form /tmp/fileXXXXXX) and passes that to PlantUML. This means that any diagram that does not contain a filename in its code will have a random name.

Worse, PlantUML also does not write the output diagram to the current working directory. For whatever reason it writes to the same directory as the input file. Writing diagrams to /tmp isn't very useful.

So, if both option 1 and option 2 aren't viable, I'm left with no other choice but to create a 3rd option. To do this, I use a comparatively niche PlantUML feature, pipe output. When -pipe is passed, PlantUML writes the output diagram to stdout instead of a file. From there I can capture the diagram as a bytevector and write it to a file in Scheme.

(define* (run-plantuml code name extension flags)
  (let ((format-flag (string-append "-t" extension))
        (output-dir (dirname name))
        (filename (string-append name "." extension)))
    ;; Guile will error if the output directory does not exist.
    (mkdir-p output-dir)
    (call-with-output-file filename
      (lambda (port)
        (put-bytevector
         port
         ;; Output is a raw image, not a string. Avoid corruption
         ;; caused by conversion to string.
         ((bv-in->string-in eval-from-stdin-bytevector)
          code
          %plantuml-command
          `(,@flags ,format-flag "-pipe")))))
    filename))

This did require reworking my evaluator functions to be a bit more generic.

Bytevector Evaluators

Previously, Guile Blocks was designed around string-based evaluators, or evaluators that take and receive strings, when invoking external processes. These work well in most cases. However, the process of encoding an image into a string and writing said string to a file corrupts the image (at least for PNGs). To resolve this, I rewrote the evaluators to operate on bytevectors and added a layer of wrapper functions to convert those bytevectors to and from strings.

I quite like how the bytevector translation functions look.

(define* (bv-in->string-in bv-func #:key encoding)
  (lambda (string . args)
    (apply bv-func
           (string->bytevector string
                               (or encoding
                                   (fluid-ref %default-port-encoding)))
           args)))

(define* (bv-out->string-out bv-func #:key encoding)
  (lambda args
    (let ((result (apply bv-func args)))
      ;; Conditional as bv-func may return #<eof> which is not a
      ;; bytevector.
      (if (bytevector? result)
          (bytevector->string result
                              (or encoding
                                  (fluid-ref %default-port-encoding)))
          result))))

(define* (bv-in-out->string-in-out bv-func #:key encoding)
  (bv-in->string-in (bv-out->string-out bv-func #:encoding encoding)
                    #:encoding encoding))

I find it neat how generic these functions are. Any function that takes a bytevector as its first argument can be wrapped to take a string instead, independent of the rest of its signature. The same goes for any function that returns a bytevector.

This allows mo to trivially support both string and bytevector based evaluators. Unfortunately the naming scheme is still a bit clunky.

C

C code is also supported.

#include <stdio.h>

int main() {
  printf("Hello world!\n");
}

Results:
Hello world!

At present this support is fairly barebones. Snippets are compiled to a temporary file using GCC and executed.

The only interesting trick here is learning about GCC's -x flag. Like before, the C code is stored in a /tmp/fileXXXXXX file and passed to GCC on the command line. It turns out that when a file is missing an extension, GCC does not know how to compile it. I can override this by changing the invocation to $ gcc /tmp/fileXXXXXX -x c.

Supporting other GCC languages like C++ should be as simple as changing the extension.

Guile Blocks: Fleshing out the Concept

2024-07-30T00:00:00Z

This post is a continuation of a previous post and is meant to further showcase Guile Blocks, an Org Mode inspired implementation of source blocks in Guile Scheme.

This post will omit discussing the technical implementation. At present, documentation for Guile Blocks can be found in its README.

The source code for this page found here.

Graphs

Graphs can be created using gnuplot. You can either feed gnuplot raw data or generate the data from another block.

This graph is created by using a block containing space-delimited data:

set title 'Hello world!'
plot '-' with lines
1 1
2 2
3 3
4 4

Whereas this graph is created by running the following Ruby code with a gnuplot block in a pipeline:

def fibonacci(n)
   n <= 1 ? n :  fibonacci(n - 1) + fibonacci(n - 2)
end

10.times do |n|
  puts "#{n} #{fibonacci(n)}"
end

LaTeX

LaTeX snippets and equations are supported. These equations are converted to MathML using LaTeXML. If your browser does not support MathML, you may find odd behavior in this section.

Equations can be either simple or complex.

\frac{1}{2}

\frac{1}{2}

\oint \vec{E}\cdot \mathrm{d}\vec{A} =
\frac{q_{\mathrm{enc}}}{\varepsilon_0}

\oint\vec{E}\cdot\mathrm{d}\vec{A}=\frac{q_{\mathrm{enc}}}{\varepsilon_{0}}

Inline equations are also supported. For example, $\sqrt{54}$ .

Like before, these equations can be quite complicated. For instance, here is a special case of the Schrödinger equation: $i\hbar\frac{\partial}{\partial t}\Psi(x,t)=\left[-\frac{\hbar^{2}}{2m}\frac{% \partial^{2}}{\partial x^{2}}+V(x,t)\right]\Psi(x,t)$ .

Tables

Data can be formatted in the same style as Org-mode tables.

def fibonacci(n)
   n <= 1 ? n :  fibonacci(n - 1) + fibonacci(n - 2)
end

10.times do |n|
  puts "#{n} #{fibonacci(n)}"
end

Results:
| 0 |  0 |
| 1 |  1 |
| 2 |  1 |
| 3 |  2 |
| 4 |  3 |
| 5 |  5 |
| 6 |  8 |
| 7 | 13 |
| 8 | 21 |
| 9 | 34 |

Guix Tricks: Soft-pinning channels in a channels.scm file.

2024-05-26T12:00:00Z

Problem

Guix is a very powerful tool to integrate into a project's toolchain. This isn't just for build systems. It can also apply to tools like interactive interpreters and debuggers. By creating a project-wide channels.scm file, you can prepend tool scripts with both guix time-machine and guix shell invocations. This allows for easy integration of additional Guix channels and ensures that every developer has development tools available to them that aren't reliant on the outside environment.

You can see an example of me using this here to invoke a Guile REPL with the Guix and rsent-freakingpenguin channels. This includes a dependency of rsent-freakingpenguin: guile-blocks. I also use it in the ./bin/serve script to build and locally deploy the website for testing.

However, one challenge of guix time-machine is that unless you are willing to pin channels to specific commits, it will ALWAYS try to pull the latest version of that channel. Because channels are always changing (particularly the Guix channel) this can introduce significant delays when, say, invoking a Guile REPL after a new Guix commit was pushed.

As mentioned, one solution is to pin channels to specific version or branches. However, this has several drawbacks:

The commit needs to be updated regularly to ensure compatibility with newer tools.
When first run, developers still need to pull an entirely different commit to what they're running.
It implies that the developer tools require that specific commit to function even if that is not the case.

My proposed solution to this is a concept I'll call "soft-pinning", which means "try to use whatever commit of this channel that is currently present on the user's profile". This will let us mix and match channels into different categories. One category is kept up to date at all times while the other is only updated as the user updates their system.

Solution

To implement this, we can take advantage of the fact that channels.scm is Guile Scheme code and use the current-channels procedure in the (guix describe) module. Here's the code:

;; Use this file with time-machine -C to get an up to date copy of
;; this channel and any dependencies.
(use-modules (srfi srfi-1)
             (guix channels)
             (guix describe)
             (ice-9 control))

(define (soft-pin-channel input-channel)
  "Given @var{channel}, return a new version of channel that uses the
current profile's commit of said channel. If the channel is not present,
commit is #f."
  (define (desired-channel? channel)
    (equal? (channel-name input-channel)
            (channel-name channel)))

  (define (profile-commit input-channel)
    (call/ec
     (lambda (return)
       (map (lambda (x)
              (when (desired-channel? x)
                (return (channel-commit x))))
            (current-channels))
       #f)))

  (channel
   (inherit input-channel)
   (commit (profile-commit input-channel))))

;; Note that if you try running this in a container (say, the
;; project's interactive Guile), the commit picked up will match the
;; Guix package in the container's profile. It will not match the
;; user's current profile channel commit.
(cons*
 (channel
  (name 'freakingpenguin)
  (url (string-append "file://" (getcwd))))
 (list
  (soft-pin-channel %default-guix-channel)))

Now, invoking the Guile REPL is instantaneous as long as the freakingpenguin channel does not change. I no longer have a minute delay or more every time a new Guix commit is pushed, while still not having to pin Guix at a specific commit.

Guix Tricks: Self-contained shebang scripts.

2024-05-11T12:00:00Z

Intro

I like scripts. You like scripts. We all like scripts. But, I don't like that when I give a script to someone else, they need to install X, Y, and Z packages for that script to work. I don't like that my scripts may behave differently depending on the user's environment. I don't like needing to install a bunch of packages in a CI environment before running my./bin/*scripts. If ONLY someone could help me!

Consider the following script:

#!/usr/bin/env -S emacs -x
;; -*- mode: emacs-lisp; -*-
;; https://orgmode.org/manual/Bare-HTML.html
(setq org-html-head ""
      org-html-head-extra ""
      org-html-head-include-default-style nil
      org-html-head-include-scripts nil
      org-html-postamble nil
      org-html-preamble nil
      org-html-use-infojs nil
      org-html-mathjax-template "")

(defvar build-status-image
  (concat "#+ATTR_HTML: :alt builds.sr.ht status
[[https://builds.sr.ht/~freakingpenguin/" (getenv "repo") "]"
"[https://builds.sr.ht/~freakingpenguin/" (getenv "repo") ".svg]]
"))

(with-current-buffer (find-file-noselect (nth 0 argv))
  (insert build-status-image)
  (org-html-export-to-html))

This is a script that takes an org-mode file and generates an HTML file. A perfect task for a CI job. Ideally, we want this script to contain all the information required to run it, including the packages it requires. Keeping this information together in one file makes it easier to track and simpler for anyone to run the script.

To both install Emacs AND run the script in one go, all we have to do is replace the shebang with this:

#!/usr/bin/env -S guix shell emacs emacs-htmlize -- emacs -x

I like this because it lets me avoid needing to learn complicated tools like Docker for something that should be a simple task. A concept like "run command X with software Y in a containerized environment" can be expressed using basic tooling (shebangs) everyone is already familiar with. I may know how Docker works and how to write Dockerfiles, but without regular, consistent use it's easy to forget their syntax and need to relearn it yet again. Shell scripts are universal. 💕

Another example

You can go one step further and run the script in a containerized environment to ensure that you captured all possible dependencies and that the behavior is consistent regardless of the user's environment.

For particularly version-sensitive scripts, you can combine this with guix time-machine. Then, all dependencies required to run the script can be near-effortlessly frozen and guaranteed to run identically between invocations.

Using guix shell in shebangs makes running arbitrary projects with Emacs'scompile-command a breeze, since it boils down the complicated task of environment setup all the way down to just a running a script. Like, for example, with how I build this site. In./bin/serve:

#!/usr/bin/env -S guix shell ruby ruby-colorize -- ruby
# -*- mode: ruby; -*-
require 'optparse'
require 'colorize'
require 'socket'

bind = "localhost"
quiet = ""
no_substitutes = ""
options = {}
OptionParser.new do |opts|
  opts.on("-p", "--public", "Bind to 0.0.0.0 instead of localhost") do
    bind = "0.0.0.0"
  end

  opts.on("-q", "--quiet", "Minimize output.") do
    quiet = "-q"
  end

  opts.on("-s" "--no-substitutes", "Do not use substitutes") do
    # Helpful if there are network issues
    no_substitutes = "--no-substitutes"
  end
end.parse!

puts "Building site".red
puts site_dir = `guix time-machine -C channels.scm -- \
                      build #{no_substitutes} #{quiet} -f guix.scm`
                  .chomp + "/site"
raise "Build Failure" unless $?.success?

ip_address = Socket.ip_address_list.detect{|intf| intf.ipv4_private?}.ip_address.to_s
puts "Serving site publicly on #{ip_address}".red unless bind == "localhost"
system("guix time-machine -C channels.scm -- shell #{no_substitutes} \
              -CN --no-cwd --expose=#{site_dir}=/srv/html python --   \
              python3 -m http.server -d /srv/html --bind #{bind}")

Now I can add (compile-command . "./bin/serve -p") to .dir-locals.el, without needing to worry about direnv, syncing separate scripts and Dockerfiles, or anything else.

Guile Blocks: Proof of Concept

2024-04-01T18:49:00Z

Introduction

Hi! This is an introductory page demonstrating Guile Blocks, an Org Mode inspired implementation of source blocks in Guile Scheme.

You're encouraged to read the project README before or alongside this post. This post primarily exists to demonstrate their real-life usage. The README covers more technical details.

I also encourage checking out the source file for this post. You can find that here.

Blocks

Blocks are records primarily composed of two fields: arbitrary code (usually a string) and a language.

The syntax for defining code blocks looks like this:

(define-block foo
  #:code     bar
  #:language baz)

A language is another record composed of two elements: an alist of decorators and an evaluator. Decorators are outside the scope of this article but they are how features like syntax highlighting are executed.

Evaluators, meanwhile, are simply functions that take a value and return a result. In most cases, this means taking in a script and evaluating that script appropriately. For example, the Python evaluator invokes Python and writes the script to Python's stdin. Whatever Python prints to stdout is captured and returned.

The blocks shown in the following segment were run when the website was built. The results were not prepopulated.

It's easy to support different languages. Here's some Ruby code.

puts "Ahh, General Kenobi. You are a bold one.".upcase

Results:
AHH, GENERAL KENOBI. YOU ARE A BOLD ONE.

And here is some Elixir code. This was actually created by running two separate blocks as a pipeline.

IO.write (1 + 7)

Results:
8

Syntax highlighting isn't just supported for Guile! The provided languages that support syntax highlighting use David Thompson's guile-syntax-highlight. However, any highlighter could be used.

@media screen and (min-width: 720px) {
    pre {
        /* Don't shrink code block font when there's enough width. */
        font-size: 1em;
    }
}

Haunt can handle org-mode source blocks too! Kinda.

2024-03-02T13:15:00Z

One of the things I miss now that my blog has moved to Guile Haunt is the lack of source blocks. This post is a proof of concept for how I may go about handling them in the future.

For those who aren't aware, org-mode source blocks are a way for you to embed executable code and their result(s) in org-mode documents. They have a lot of features, but a basic source block would be

#+begin_src C
  printf("Hello world!\n");
#+end_src

#+RESULTS:
: Hello world!

I would talk about the implementation more, but the code is simple enough that I'll let it do the talking. If you're not familiar with SXML, the 12 word summary is "it's HTML, but instead of <p> it's (p and instead of </p> it's )".

Here is a barebones code block showing how by treating code as data, we can both output the code as a string and evaluate it.

(+ 1 1)

Results:

Interestingly, this method can work on itself. Here is (most of) the code used to make it happen.

(begin
  (define* (sxml-code-block
            code
            #:key
            (evaluator (cut eval <> (interaction-environment)))
            (lexer lex-scheme)
            (raw? #f))
    (let ((fmt (if raw? "~a" "~y")))
      `(div (@ (class "code-block-maybe-results"))
            (pre (code ,(highlights->sxml
                         (highlight lexer (format #f fmt code)))))
            ,@(if evaluator
                  `("Results:" (pre (code ,(format #f fmt (evaluator code)))))
                  '()))))
  (sxml-code-block '(+ 1 1)))

Results:

(div (@ (class "code-block-maybe-results"))
     (pre (code ((span (@ (class "syntax-open")) "(")
                 (span (@ (class "syntax-symbol")) "+")
                 " "
                 (span (@ (class "syntax-symbol")) "1")
                 " "
                 (span (@ (class "syntax-symbol")) "1")
                 (span (@ (class "syntax-close")) ")")
                 "\n")))
     "Results:"
     (pre (code "2\n")))

One major disadvantage of this approach is that Scheme sexps do not preserve the input formatting. For example, '(foo bar) and '(foo bar) are identical as soon as Scheme starts interpreting them. At present I am relying on Guile's "pretty-printer" to do the heavy lifting, but ideally I'd come up with a mechanism that let's me preserve the input format. This approach also does not allow for comments.

We can work around these issues by performing Fly Evaluation with eval-string instead of eval

(+ 1 ;ooooh a comment. Pretty.
   1)

Results:

But the editing experience is... unpleasant. After all, we're no longer writing code. Instead, we're writing a string of code, stripping away all of our fancy editing tools. This kind of defeats the entire goal of "code as data". Perhaps this can be made less painful using Skribe instead of raw SXML, but in another post I will instead try going down a different path; write a macro capable of taking a raw, "unquoted" sexp and converting it into a string and before callingsxml-code-block. This shouldn't be that hard... right?

One last tidbit for the road. As written, this awkward, not great source block evaluator can work with other languages, just as long as a Scheme evaluator function is written. As a very limited proof of concept, here's some Ruby code.

puts "Ah, General Kenobi. You are a bold one.".upcase

Results:

AH, GENERAL KENOBI. YOU ARE A BOLD ONE.

The code for this was:

(begin
  (define (eval-ruby code)
    (let* ((port (open-input-pipe (string-append "ruby -e '" code "'")))
           (str (read-line port)))
      (close-pipe port)
      str))
  (sxml-code-block
   "puts \"Ah, General Kenobi. You are a bold one.\".upcase"
   #:evaluator
   eval-ruby
   #:raw?
   #t))

Now from here on out, every time I need to build my blog I will spin up a Ruby VM just to capitalize a string. Do you think God stays in heaven because he too lives in fear of what he's created?

Hello world from Guile Haunt!

2024-01-15T20:56:00Z

Hello world!

(if (and (something-bad? thing) (glyph-test? (>= 1 1)))
  (error "You shouldn't have done that!"))

LaTeX math code using MathJax: $ sin (x) = \frac{y}{2a} $

MathJax was removed since this post was written in favor of MathML.

stm8-card: Frame Buffers

2021-06-24T17:30:00Z

Background

I recently designed and fabricated a printed circuit board (PCB) business card. I used a STM8S003F3 microcontroller along with a SSD1306 display. This business card has my name, contact info, and other information on a silkscreen layer. The microcontroller runs a "space-invaders-esque" game, communicating with the display over I2C.

You can view the code and board files here.

The Problem

The most natural way to control a display is to create what's called a frame buffer. We would allocate enough space in the microcontrollers memory so that every pixel is 1 bit. Every time we want to change the display, we can just set or reset bits in the frame buffer, and then transmit the entire frame buffer.

However, eight bit microcontrollers are very resource limited. My display's dimensions are 128x32, or 4096 pixels. If I used 1 bit to represent each pixel, I will use 512 bytes of RAM. The microcontroller I'm using has 1024 bytes.

This doesn't sound so bad, right? I have over twice the memory needed for my frame buffer! Well, there's a slight issue.

Of those 1024 bytes, 512 are reserved for the stack. The stack keeps track of where we are in the program, local variables that are in use, and similar. As you might expect, that means the stack is absolutely essential. We obviously can't chop out the entire stack for our frame buffer. It's possible to only store part of our frame buffer where the stack is, but it's challenging to determine how much of the stack is in use at any time. The stack could overwrite part of our frame buffer as we jump between functions, which would corrupt our display into a mess of pixels.

Okay, so we went from having 1024 bytes of memory in the microcontroller to 512. That's still enough for our frame buffer, so what's the big deal? Well, I need to store more stuff than just the frame buffer outside of the stack. The space invaders code (space_invaders.c) has several statically allocated variables. That means these variables are not stored in the stack, but in that 512 bytes area. (It works out to about 176 bytes.)

Now we're down to 336 bytes, which somehow needs to represent 512 bytes of data. Sounds like a problem, doesn't it?

Making due with less, drawing a display without a complete frame buffer

So creating a 512 byte frame buffer is a bust. Fortunately though, there are some ways I could work around this! One option, and the one I went with, was to only draw half the display at a time! I created a function in ssd1306.h with the following signature.

  /* I dunno if an enum is the best way to do this, but I'm doing it! */
  typedef enum { RIGHT, LEFT } ssd1306_side_t;
  /* ... */
  /* Draw the frame buffer to the selected side */
  signed char draw_half(ssd1306_side_t side);

Let's take a look at how ~draw_half()~ works, shall we?

  signed char draw_half(ssd1306_side_t side) {
    const uint8_t change_start_right[7] = {CONTROL_BYTE(CO_DATA, DC_COMMAND),
      CMD_ADDR_COL, SSD1306_WIDTH / 2, SSD1306_WIDTH - 1,
      CMD_ADDR_PAGE, 0, 3};
    const uint8_t change_start_left[7] = {CONTROL_BYTE(CO_DATA, DC_COMMAND),
      CMD_ADDR_COL, 0, SSD1306_WIDTH / 2 - 1,
      CMD_ADDR_PAGE, 0, 3};
    int err;
    if (side == RIGHT) {
      err = send_data(change_start_right, sizeof(change_start_right) / sizeof(change_start_right[0]));
    } else {
      err = send_data(change_start_left, sizeof(change_start_left) / sizeof(change_start_left[0]));
    }
    if (err != 0) return err;

    draw_frame_buffer();
    return 0;
  }

I have two arrays with 7 bytes of data in them called change_start_right and change_start_left. When draw_half(LEFT) is called, I send change_start_left to the display, and vice versa. [fn:4:That sizeof nonsense lets me add and remove elements to change_start_* without needing to change the second argument to send_data().] When change_start_left is sent, the pixel addressing looks like

and when change_start_right is sent

Obviously this is a little scaled down compared to a 128x32 pixel display, but it illustrates the point. The first bit of my frame buffer is sent to the top left of the half we are on, then we move across horizontally until reaching the halfway point. We then jump down a row and repeat!

For completeness, draw_frame_buffer() looks like

  struct S {
    uint8_t control_byte;
    uint8_t frame_buffer[BUF_SIZE];
  } SSD1306_Data = {.control_byte = CONTROL_BYTE(CO_DATA, DC_DATA)};
  /* ... */
  signed char draw_frame_buffer() {
    return send_data(&SSD1306_Data.control_byte, sizeof(struct S));
  }

Every transmission needs to start with a control byte. I can't start a transmission, send a control byte, stop it, start a new one, and send the frame buffer. It needs to be one continuous message. send_bytes() (which is just a wrapper for i2c_send_bytes()) takes an array of data and a size, and will just send that array over. In other words, I can't tell i2c_send_bytes() "Hey, send this byte first, then send these 256 bytes".

I could make frame_buffer a 257 byte array, and remember that the first byte represents the control byte, not pixels. This is an ugly solution in my eyes and will complicate later code. Instead, remembering that an array is just a block of continuous memory, I found a second solution. I created a structure with the control byte first, followed by the frame buffer. The elements in a structure are continuous [fn:5:Sorta. There is something called structure "padding". However, since I'm dealing with 8 bit data in an 8 bit microcontroller, it's not an issue. Even if that wasn't enough, the fact that everything is 8 bits or an array of 8 bit elements, padding won't be added. Technically though I don't know if the C standard guarantees this. Some compilers support structure "packing" with a compile-time flag, which is guaranteed to prevent this issue. I am using SDCC, which does not.], so to send_bytes(), this is just a 257 byte array.

Manipulating the frame buffer: drawing images

We're almost done here. There's just one element missing. If I had a 512 byte frame buffer, I could easily draw an image (e.g. a spaceship) by going to the x and y coordinates in the frame buffer, then drawing the pixels.

Representing images with structs

I chose to use two different structs to represent images.

  #define MAX_FRAMES    (4) /* up to 4 frames of animation */
  /* ... */
  struct Image {
    const char width;
    const char height;
    const uint8_t *pixels;
  };

  struct DrawableImage {
    signed char x;
    signed char y;
    unsigned char state;
    const struct Image *images[MAX_FRAMES];
  };

Image is a struct that contains the raw data of the image, along with the dimensions so it is drawn properly. For instance, if I want to represent

as a struct, I would write

  const uint8_t spaceship_pixels[24] = {
    0x21, 0x00, 0x00,
    0x41, 0x80, 0x00,
    0x21, 0xC1, 0xC0,
    0x8F, 0xFF, 0xFF,
    0x0F, 0xFF, 0xFF,
    0x81, 0xC1, 0xC0,
    0x41, 0x80, 0x00,
    0x61, 0x00, 0x00
  };

  const struct Image spaceship_image = {
    .width = 24, .height = 8, .pixels = spaceship_pixels
  };

This pixels array goes from the top left pixel of the image (red square), left to right, marking which pixels need to be on. 0x21 means the 3rd pixel 0b0010 and the 8th pixel 0b0001 are both lit, while the rest of that row is off. Because I include the width and height, I know when I need to wrap around to the next row, as well as how many rows there are in total. (In theory I could remove height as the pixel array length + width can be used to calculate the height. height = sizeof(spaceship_pixels) / (width/8))

This spaceship_image variable contains everything I need to know about the image itself. Because I separated Image and DrawableImage, I can declare my Image structs as const. This means the array of pixels, width, and height are all stored in program (flash) memory, not RAM. Otherwise, I'd be very limited after using 257 bytes for my frame buffer and 512 bytes for the stack, with only 255 bytes left for everything else.

By doing so, the DrawableImage struct has to contain a pointer to the Image struct, as they are in different locations in memory. I also want my images to be animated, so I have an array of pointers to Image structs. That's what const struct Image *images[MAX_FRAMES]; means. images is an array of pointers to const Image structures.

The x and y fields of the DrawableImage structure tell us the coordinates of the top left pixel of the display. state is the frame of animation we're on. Every time we want to move the image to a new frame, all we have to do is increment state, while ensuring it's a valid number.

Using these structs to draw on the display

So, hopefully now we understand how I represent images using two separate structures. By doing so, I can combine related data together, hopefully making it easier to actually draw them on the display. I want to have a method called draw_image() in ssd1306.c/h that takes a DrawableImage structure, then modifies the frame buffer so that the correct pixels are lit up. The next time the frame buffer is transmitted, the display should update accordingly.

Because my frame buffer is split in half, there's one other thing that I need to pass draw_image(). The DrawableImage can be located anywhere on the display, on either half. If I am going to use the frame buffer to update the left half of the display, and I send a DrawableImage that's located on the right half, nothing should update. If the DrawableImage is in between the two halves, only part of it should be drawn. Therefore I have a second argument called side that tells draw_image() how the DrawableImage should be drawn depending on which half we're on. (e.g. If the DrawableImage is on the left half but side says RIGHT, don't change any pixels in the frame buffer!)

Breaking apart `draw_image()`

Here's the first few lines of code of draw_image().

  /* in ssd1306.h */
  #define REDRAW_OTHER_HALF                         (1)
  /* in ssd1306.c */

  signed char draw_image(struct DrawableImage *image, ssd1306_side_t side) {
    if (image == NULL) return -1;
    char width = image->images[image->state]->width;
    char need_redraw = 0;                                         /* flag for if any pixels outside bounds of buffer */
    /* ... */

First, we perform a simple check to help verify that the DrawableImage is valid. If we did not perform this check, we'd be drawing garbage on the screen! This actually was a big issue for several days that wasn't immediately obvious. I changed an unrelated part of my code to return NULL under certain conditions, but wasn't checking if the image was NULL when calling draw_image(). This is what that looked like.

I declare two variables, width and need_redraw. width is just a shorthand so I don't need to write image->images[image->state]->width every time. (This monstrosity means "go to the DrawableImage struct pointed to by the image pointer, get the Image structure for the current frame of animation we're on, then get the width of that Image structure).

need_redraw is a flag variable. If the image we're drawing is partially or fully on the other half of the screen, it will be set to REDRAW_OTHER_HALF, telling whatever function called this one "Hey, this DrawableImage needs to be drawn again later".

  /* don't waste time drawing images that don't appear */
  if (side == LEFT && image->x > BUF_WIDTH) return need_redraw;
  if (side == RIGHT && image->x + width < BUF_WIDTH) return need_redraw;

If we're on the left half of the screen and the x coordinate of the top left of our image is greater than the halfway coordinate of our display, then we need to draw the image again! Remember, the coordinates tell us the location of the top left pixel of the DrawableImage.

There's actually a bug here at the time of this writing. I need to return REDRAW_OTHER_HALF (if I want the code to exit immediately). As need_redraw was not set yet, I am returning 0, meaning the image does not need to be redrawn!

The really ugly part of `draw_image()`

Heads up. This next part is a doozy comparatively.

  for (int i = 0; i < image->images[image->state]->height; i++) {
    for (int j = 0; j < width; j++) {
      /* ... */

We have two nested for loops that will iterate through the pixels of the Image. Unfortunately, because this is C, there's no concept of a Pixel type. I need to use as little storage as possible, so I have my pixels represented as an array of 8-bit characters.

  unsigned char subscript = (i * width + j) / 8;
  unsigned char bit_num = 7 - (i * width + j) % 8;
  /* ... */

subscript tells me which 8-bit sequence will contain the pixel I need. Similarly, bit_num is the number of the specific bit within the bit. For example, subscript = 2 and bit_num = 3 means I will be looking at the 4th bit within the 3rd byte. By looking at this bit, I'll know if the pixel should be on or off.

  if ((image->images[image->state]->pixels[subscript] & (1 << (bit_num))) != 0) {
    /* ... */

And that's exactly what I do! I access the pixel data through a fairly obtuse chain of arrow (->) operators, testing if the specific bit is high or low. If it is high, I continue.

Technically, I could clear the pixel if it is zero. This would prevent images from overlapping, which I don't want.

  signed char xcord = image->x + j, ycord = image->y + i;
  /* ... */

After that, I need to generate the x and y coordinates to place the pixel. Because I already have the coordinate for the top left of my image, I just need to add my i and j values to find the coordinates of the pixel!

  if (side == RIGHT) xcord -= SSD1306_WIDTH / 2;

There's one last small adjustment I need to make. My frame buffer is half the width of the display. (64x32 instead of 128x32). If I want to draw on the right half of the display and try using the x coordinate without modifying it, I'll be attempting to draw a pixel outside of my frame buffer! So, I subtract 64 from the x coordinate if side is RIGHT, protecting against this.

  if (draw_pixel(xcord, ycord) == INVALID) need_redraw = REDRAW_OTHER_HALF;

Before returning need_redraw, I have one final thing to do. Actually updating the pixel in my frame buffer! In the interest of space, I won't actually go into the details of how draw_pixel() works. Suffice to say that it takes a coordinate between (0, 0) and (63, 31), toggling the correct bit in the frame buffer. If that coordinate is invalid, it returns INVALID. By checking the return value, I will know if any coordinates of my image fall outside of that area, suggesting it is either corrupt or—more likely—on the other half of the screen, meaning the image needs to be redrawn to fully appear on the display.

Using `draw_image()` and pals to draw on a display

By this point, you are probably confused as to how this code actually works. I talked a lot about drawing and redrawing the display. Hopefullly a brief example of using these methods will help. Here is a modified snippet of code in my main() method that is run in an infinite loop.

  for (int i = 0; i < 3; i++) {
    lasers[i] = debug_drawableimage_playerlaser(i);
    invader_lasers[i] = debug_drawableimage_invaderlaser(i);
    invaders[i] = debug_drawableimage_invader(i);
    draw_image(lasers[i], LEFT);
    draw_image(invader_lasers[i], LEFT);
    draw_image(invaders[i], LEFT);
  }
  draw_half(LEFT);
  clear_buffer();
  for (int i = 0; i < 3; i++) {
    draw_image(lasers[i], RIGHT);
    draw_image(invader_lasers[i], RIGHT);
    draw_image(invaders[i], RIGHT);
  }
  draw_half(RIGHT);
  clear_buffer();

lasers[], invader_lasers[], and invaders[] are all arrays of 3 DrawableImages. First, I update the DrawableImage to the most recent ones reported by my Space Invaders game. How Space Invaders creates these DrawableImages is not really relevent right now.

I then attempt to draw the images on the left half of the screen. Some of these DrawableImages will not be drawn because they are on the right. This is totally fine! draw_image() does nothing in that case.

draw_half() will take the contents of the frame buffer, and send that information to the display. This is what physically causes the display to update, showing the new pixels on the screen. I then clear the buffer to all zeroes so that the left half will not overlap with the right half.

This entire process is repeated on the right half.

Here's the final result!

Circular pointers in C

2021-04-15T12:35:00Z

What is a circular pointer?

Full disclosure, I almost cannot think of any practical value to this post. It's provided also entirely as a "Huh, that's a weird thing you can do in C", rather than an actually useful technique. The only purpose I can see is to use them for a circularly linked list with one element. There may be another term that's in use, but I do not know what it is.

A circular pointer is a pointer that, well, points to itself! No matter how many times we dereference that pointer, we should still be at the same spot. For example,

Another way to think about it is ****p == p. Let's try to think of some ways to implement this!

Failed Attempt

The first thought that might come to our mind might be something like what's below. Because (spoilers) this code seg faults, I wrote a signal handler so we still see some kind of results.

Calling most library functions in signal handlers is a bad idea, so I'm using the write() system call. Headers are excluded for compactness. I'm using fflush() as printf() buffers its output. Otherwise, the first printf() will not appear. Lastly, even though an error occurs, I'm exiting with a zero exit code because of =org-babel= limitations. You can find out more about this in [*Crash and burn programming](this post).

  void segfault(int sig_num) {
    fflush(stdout);
    write(STDOUT_FILENO, "Segfault!\n", 9);
    _exit(0);
  }

  int main(void) {
    signal(SIGSEGV, segfault);
    int *p;
    printf("p 0x%x\n", p);
    ,*p = p; /* segfault occurs here */
    printf("****p %x", ****(int ****)p);
  }

#+RESULTS:
: p 0x0
: Segfault!

If we walk through the code, we can figure out the problem. We allocate space for an integer pointer p, which contains 0. We then attempt to store the value in p, 0, in the value pointed to by p, 0. In other words, we're attempting to dereference a NULL pointer, causing a seg fault.

Some background

Okay, so all we need to do is malloc() space for the pointer p to point to. Easy, right? Before we get to that though, there's a few things we have to keep in mind.

Malloc with multiple levels of pointers

First, we need to be careful allocating space for variables when using multiple levels of pointers. For example,

  int **p = malloc(sizeof (int));
  ,**p = 1;

will seg fault! p is a pointer to a pointer containing an int. When we malloc memory, malloc will return a pointer to a block of memory large enough to contain an int. If we type **p, we're saying "Go to the malloced block, then go to where the malloced block is pointing at and set that block to 1". Because malloc()'d memory can be anything, we are accessing memory at random! This is an easy recipe for a seg fault. One way to fix this is to use multiple variables, for instance...

  int *p1  = malloc(sizeof (int));
  int **p2 = &p1;
  ,**p2    = 7;
  printf("***p2 %d", **p2);

#+RESULTS:
: ***p2 7

Compile time errors dereferencing pointers

Next up, if we have int *p, then p is an int *. If we try to do **p, our compiler will complain about an invalid type argument and fail to compile. You can't dereference an int * two times!

The compiler helpfully assumes that you would never dereference a pointer more than the number of pointers you have. In other words,

  int *p = malloc(sizeof (int));
  printf("*p1 %d\n", *p);

will compile, but

  int *p  = malloc(sizeof (int));
  printf("**p1 %d\n", **p);

will not compile. The compiler sees that *p1 is an int pointer, so it knows **p is always invalid. If we pretend seg faults don't exist for a second, we can fix this issue using casts! A cast tells the compiler "Hey, I know that p is an integer pointer, but I need you to treat this as another type for right now".

  int *p  = malloc(sizeof (int));
  printf("**p %l", **(int **)p);

In this case, we're saying "Hey, you know that integer pointer p? Let's treat it as pointer to a pointer to an integer for right now".

`sizeof (int *)` vs `sizeof (int)`

The last thing to remember deals with sizes. In 64-bit systems, a pointer is 64-bits long, regardless of the type it points to. sizeof int* == sizeof char* == sizeof double** == 8. Using what we've learned so far, let's say we have the following code block.

  int *p = malloc(sizeof (int));
  ,*p = (int)p;
  printf("**p %d", **(int **)p);

We've managed to get everything right! Except for one little part. *p is an integer, not an integer pointer. We store the integer pointer p in *p. Because sizeof (int *) == 8 and sizeof (int) == 4 (on my machine), part of the pointer is chopped off! p needs to point to a type that is the same size (or larger) than an integer pointer.[fn:2:Or any non-function pointer. There is no guarantee that a function pointer is the same size as a integer/double/etc pointer, and they're more of a abstraction that exists in our code than something that's really "there", like integers in memory.]

The C standard actually includes an integer type that is guaranteed to be the same size as a pointer, the signed intptr_t or unsigned uintptr_t types defined in =stdint.h=. I'll stay away from these since I'm worried it'll make it a bit more confusing.

Time to put all of this into the most pointless (HAHAHAHAHA) practice imaginable.

Circular pointers with `malloc()`!

Let's take what we've learned and try to create a pointer that points to itself, and one where we can dereference it as many times as we want!

  int main(void) {
    long *p = malloc(sizeof (long *));
    ,*p = (long)p;  /* cast isn't required here */
    printf("p    0x%lx\n",  p);
    printf("*p   0x%lx\n",  *p);
    printf("**p  0x%lx\n",  **(long **)p);
    printf("***p 0x%lx\n",  ***(long ***)p);
  }

#+RESULTS:
| p    | 0x558366a4c2a0 |
| *p   | 0x558366a4c2a0 |
| **p  | 0x558366a4c2a0 |
| ***p | 0x558366a4c2a0 |

Look at that! We've successfully created a pointer that points to itself! No matter how many times we dereference it, we are still looking at the same pointer.

For fun, let's create a loop so we can deference the pointer as many times as we want very easily.

  int main() {
    long *p = malloc(sizeof (long *));
    ,*p = (long)p;
    for (int i = 0; i < 5; i++) {
      long ptemp = *p;
      printf("%d 0x%lx\n", i, *p);
      p = (long *)ptemp;
    }
  }

| i |    dereference |
|---+----------------|
| 0 | 0x55ffc15d32a0 |
| 1 | 0x55ffc15d32a0 |
| 2 | 0x55ffc15d32a0 |
| 3 | 0x55ffc15d32a0 |
| 4 | 0x55ffc15d32a0 |

And there we go. This is one option for how we can implement a pointer that points to itself, no matter how many times we dereference it. If we wanted to, we add more pointers, creating a circularly linked list that looks like

Circular pointers with structs!

Another option that saves us from all this casting is to use structs. Because a struct can contain anything[fn:3:Except for a struct containing itself directly.], even a pointer to a struct of the same type, we can do the following.

  struct p_self {
    struct p_self *p;
    int magic;
  };

  int main() {
    struct p_self p = { .p = &p, .magic = 4032 };
    printf("magic %d", p.p->p->p->p->p->magic);
  }

#+RESULTS:
: magic 4032

To my knowledge, we can't make p a pointer to a struct very compactly. If we create a compound literal like

  struct p_self *p = &(struct p_self){ .p = /* problem */, .magic = 4032 };

we have a problem. The compound literal needs to contain a field that contains it's own address. I don't believe it is possible to do this, as there's no way to refer to the compound literal we are inside of. (This could be avoided by not using compound literals and introducing a second variable, but I'd rather not.)

Regardless, what we can conclude from this is that pointers are weird and confusing and there's many little ways to mess up, especially as we do increasingly weird stuff with them. But it's fun!

Fourier Part 2: Integrating a discontinuous function

2021-04-10T00:00:00Z

Checking if `gsl_integration_qng()` will work

At the end of part 1, I suggested that gsl_integration_qng() would not be able to successfully integrate the function we want to find the Fourier series of. Here is the function I will find the Fourier series of.

Because this function is discontinuous, we have to approximate it with a Fourier series instead of a Taylor series. If we recall the formulas shown in the last part, we know that we will have to integrate $f(x)$ from $0$ to $2l$ , among other things. Before calculating the Fourier series, let's try using gsl_integration_qng() to perform basic integration.

#include <stdio.h>
#include <math.h>
#include <gsl/gsl_integration.h>

/* f(x) = x for 0 <= x < 4, repeating */
double f(double x, void *params) {
  const double period = 4;
  return fmod(x, period);
}

int main() {
  double result, error;
  double low = 0, high = 8;
  gsl_function F = {.function = &f};
  double err_abs = 0, err_rel = 1;
  size_t num_evals;

  gsl_integration_qng(&F, low, high,
      		err_abs, err_rel,
      		&result, &error, &num_evals);
  printf("result error num_evals\n");
  printf("%f %f %zu\n", result, error, num_evals);
}

Results:
|    result |    error | num_evals |
| 14.804436 | 8.015135 |        21 |

Well, something happened here, but it's not quite what we wanted. We told GSL to take gsl_integral-i. Since we're dealing with a discontinuous function, we can rewrite this as gsl-integral-rewrite-i. Now I'm no mathematician, but this answer should be 16, not 14.8. Additionally, our error is very large, and if I attempt to lower err_rel to a smaller value, GSL yells at me saying that it failed to reach the requested error.

This is not a problem on GSL's end. We aren't using the right integration function for the job! According to the GSL manual,

The QNG algorithm is a non-adaptive procedure which uses fixed Gauss-Kronrod-Patterson abscissae to sample the integrand at a maximum of 87 points. It is provided for fast integration of smooth functions.

While that's a lot of words, the important part is the last sentence. gsl_integration_qng() is for smooth functions. Our function is not smooth, it has a discontinuity! We will need to find an alternative function in GSL that can handle discontinuous graphs.

`gsl_integration_qng()` and discontinuities

Fortunately we do not have to look far. The very next function mentioned in the manual is what we need. gsl_integration_qag() has the following signature.

int gsl_integration_qag(const gsl_function * f,
            double a, double b,
            double epsabs, double epsrel,
            size_t limit, int key,
            gsl_integration_workspace * workspace,
            double * result, double * abserr)

f, a, b, epsabs, epsrel, result, and abserr are all the same as gsl_integration_qng(). We can see that several new terms are introduced however.

workspace is a pointer to an area of memory used by gsl_integration_qag. We allocate space by using the gsl_integration_workspace_alloc() function, This function is passed an integer to adjust how much memory we want to allocate. Whatever integer we pass to gsl_integration_workspace_alloc()we need to ensure that limit is the same. This way, gsl_integration_qag knows how much memory it has available.

key is a integer between 0 through 6. GSL recommends using higher values when integrating smooth functions, and lower values when functions are discontinuous.

Let's see how well gsl_integration_qag() performs!

#include <stdio.h>
#include <math.h>
#include <gsl/gsl_integration.h>

double f(double x, void *params) {
  const double period = 4;
  return fmod(x, period);
}

int main() {
  size_t limit = 1024;
  gsl_integration_workspace *w
    = gsl_integration_workspace_alloc(limit);
  double result, error;
  double low = 0, high = 8;
  gsl_function F = {.function = &f};
  double err_abs = 0, err_rel = 1e-7;

  gsl_integration_qag(&F, low, high,
      		err_abs, err_rel,
      		limit, 1, w,
      		&result, &error);
  /* get into the habit of freeing memory when done! */
  gsl_integration_workspace_free(w);
  printf("result error\n");
  printf("%f %f\n", result, error);
}

Results:
| result | error |
|   16.0 |   0.0 |

Look at that! We are getting the exact value we expected, even though we're integrating with a discontinuity. We are now at the point where we can calculate the Fourier series for our function.

Generating our Fourier series

Let's recall that we can find our $a_{n}$ and $b_{n}$ coefficients with the following formulas.

a_{n}=\frac{1}{l}\int_{0}^{2l}f(x)\cos(\frac{n\pi x}{l})dx

b_{n}=\frac{1}{l}\int_{0}^{2l}f(x)\sin(\frac{n\pi x}{l})dx

GSL expects us to only pass one function to it as an argument. That means that, unlike before, we can't just pass a pointer to our function f(x), as GSL won't be multiplying it by the cosine and sine terms.

There are a couple of solutions to this that I can think of. The first is to make use of the void * argument that GSL includes in the gsl_function structure. Using this, we could pass extra information to f(x), adapting it to our specific n value.

Alternatively, we could write a parent function, like aorb_subn(). This function would then be stored in the gsl_function structure. The advantage of this approach is that the function we want the Fourier series of, f(x), is distinct in our code. This should make it a bit easier to change f(x) to any function that we want. This is the approach that I will take.

To make this code hopefully a bit more modular, I moved the integration out of main, and instead into a function called get_aorb_subn(). This function calculates the nth Fourier coefficient for a function f(x), using the variable get_a to determine if it should calculate $a_{n}$ or $b_{n}$ . It may be better to wrap this in a fourier structure that contains the two terms, but I elected not to do that to hopefully maintain some vague semblance of readability.

This is what the code to calculate the Fourier series looks like.

#include <stdbool.h>
#include <stdio.h>
#include <math.h>
#include <gsl/gsl_integration.h>

#define PI 3.14159
const double period = 4;
const double l = period / 2;

struct aorb_params {
  double (*f)(double x, void *params);
  int n;
  bool calc_a;
};

double f(double x, void *params) {
  return fmod(x, period);
}

double aorb_subn(double x, struct aorb_params *params) {
  int n = params->n;
  double trig = params->calc_a ? cos(PI*n*x/l) : sin(PI*n*x/l);
  return params->f(x, NULL) * trig;
}

double get_aorb_subn(double (*f)(double x, void *params), int n,
      	       double low, double high, bool get_a) {
  double normalization = 1/l;
  if (get_a && n == 0) normalization /= 2;

  size_t limit = 1024;
  gsl_integration_workspace *w
    = gsl_integration_workspace_alloc(limit);
  double result, error;
  gsl_function F = { .function = &aorb_subn,
    .params = &(struct aorb_params){ .f = f, .n = n,
      		 .calc_a = get_a } };
  double err_abs = 0, err_rel = 1e-7;

  gsl_integration_qag(&F, low, high,
      		err_abs, err_rel,
      		limit, 1, w,
      		&result, &error);
  gsl_integration_workspace_free(w);

  return normalization * result;
}

int main() {
  const int upto = 10;
  double a_subn[upto], b_subn[upto];
  double low = 0, high = period;

  for (int i = 0; i < upto; i++) {
    a_subn[i] = get_aorb_subn(f, i, low, high, true);
    b_subn[i] = get_aorb_subn(f, i, low, high, false);
    printf("%d %f %f\n", i, a_subn[i], b_subn[i]);
  }
}

Results:
| n | a_subn |    b_subn |
|---+--------+-----------|
| 0 |    2.0 |       0.0 |
| 1 | -7e-06 | -1.273242 |
| 2 | -7e-06 | -0.636621 |
| 3 | -7e-06 | -0.424414 |
| 4 | -7e-06 |  -0.31831 |
| 5 | -7e-06 | -0.254648 |
| 6 | -7e-06 | -0.212207 |
| 7 | -7e-06 | -0.181892 |
| 8 | -7e-06 | -0.159155 |
| 9 | -7e-06 | -0.141471 |

Like I mentioned before, aorb_subn is a "parent function" that combines f(x) and the sine/cosine term. This is the function we integrate, and we provide it enough information to know what term we are calculating.

Interestingly, if we use the $\pi$ constant M_PI, the integration fails due to roundoff error. Fortunately we can get "close enough" values by just using a few less digits.

Once we graph the Fourier series generated by these coefficients, this is what we get.

And there we are! Here is a Fourier series generated for a discontinuous periodic function. The more terms we add, the more accurate the approximation.

Fourier Part 1: What is a Fourier series?

2021-04-06T00:00:00Z

An overview of Taylor series

A fourier expansion is a way for us to approximate a function. If you've taken calculus before, you may have heard of a similar concept, Taylor series. With Taylor series, we can approximate any function as a sum of polynomials. For example, we can write $\sin x$ as

\sin x=x-\frac{x^{3}}{3!}+\frac{x^{5}}{5!}-\frac{x^{7}}{7!}

If we were to graph this, we see that as more terms are added, our approximation becomes more and more accurate. Here's a small demonstration.

In the graph below, I tried demonstrating how the Taylor series can "home in" on a function. Since we can't add part of a term in a Taylor series, I tried to demonstrate this effect by multiplying the term by a value. For example, when you see 1.1 terms, that means the first term + 0.1 * the second term. For $\sin x$ , that's $\sin x=x-0.1*\frac{x^{3}}{3!}$ .

Now, Taylor series can be useful, but they have significant limitations. First, we see that the Taylor series does a poor job modeling periodic functions. Even though $\sin x$ repeats, our Taylor series does not. At large $x$ values, this Taylor series is completely wrong!

Second, a Taylor series relies on the function being continuous (no holes or jumps). In addition to the function being continous, its derivatives must be as well. Let's consider the following graph.

Even though $f(x)$ is continuous, its derivative $f^{\prime}(x)$ is not. As such, a Taylor series cannot be used to approximate this function. This issue would come up even if $f^{\prime\prime\prime\prime\prime\prime\prime\prime\prime\prime}(x)$ was discontinuous. (Keep in mind that discontinuous is not the same thing as 0! We can model $f(x)=x$ as a Taylor series, as its higher order derivatives are continuous. They just also happen to be 0. Also, $f(x)=x$ is its own Taylor series.)

So, to summarize, Taylor series have the following issues:

They do not model periodic functions well
They require the function and all of its derivatives to be continuous

Fortunately, the Fourier series provides answers to both of these problems! (At least for most functions. Some functions, like a function that is discontinuous everywhere, exist solely for the purpose of making us sad.)

What we're all here for, Fourier series

I'll be sticking to the basics of Fourier series for now. Let's assume we have a periodic function $f(x)$ that has a period of $T$ . I am going to fintroduce the symbol l-i where $l=\frac{T}{2}$ . While this isn't the only option, we can write the Fourier series as

f⁢(x)=∑n=0∞an⁢cos⁡(n⁢π⁢xl)+bn⁢sin⁡(n⁢π⁢xl)

In this case, we can find $a_{n}$ and $b_{n}$ with the formulas

a_{n}=\frac{1}{l}\int_{0}^{2l}f(x)\cos(\frac{n\pi x}{l})dx

b_{n}=\frac{1}{l}\int_{0}^{2l}f(x)\sin(\frac{n\pi x}{l})dx

I won't go into detail as to where these formulas come from. (That is left as an exercise for the reader. Hah!) However, I will point out that we can adjust the limits of integration to any values we want, just as long as the difference between the upper and lower limits equals our period.

There is one special case that we need to discuss. When $n=0$ , we need a new formula for $a_{0}$ . This formula will look like

a_{0}=\frac{1}{2l}\int_{0}^{2l}f(x)dx

Fortunately there is no special case for $b_{0}$ . This occurs due to the fact that $a_{0}$ is a constant term ( $\cos 0=1$ ) as opposed to periodic.

That is all the theory that we need to calculate the Fourier series! As long as we can find a library that can perform integration for us, we should be able to calculate the Fourier series for any periodic function.

Using GSL to calculate an integral

Explanation of `gsl_integration_qng()`

Because of inscrutible magic mumbo jumbo, I decided to use C for calculating the Fourier expansion. In order to do that, I needed to pick out a library that could perform the integration for me. I settled on GSL or the GNU Scientific Library. There are many, many, MANY functions available in this library, but luckily I only need to worry about integration.

Before going too far into Fourier stuff, I'm going to do a simple sanity check so I can make sure I'm calculating integrals correctly. I want to calculate the following integral.

\int_{0}^{8}xdx

To do this using GSL, I can use the gsl_integration_qng() function. This function has the following signature.

int gsl_integration_qng(const gsl_function * f,
            double a, double b,
            double epsabs, double epsrel,
            double * result, double * abserr,
            size_t * neval)

f is a pointer to a structure that contains a function pointer. For those who don't speak nerd, this is how gsl-integration-qng() knows what function to integrate. It's our f(x). (Mostly. The reason for making it a structure is because the structure also contains a void * or void pointer. This void pointer can be used to pass parameters to the function. This could be used to let us change the slope of the function without having to modify the function itself.

a and b are the lower and upper limits of integration. That's fairly straightforward.

epsabs and epsrel help gsl_integration_qng() decide when to stop integrating. It's not possible to integrate the function to an exact value with GSL. Instead, it tries to zero in on a specific value or best guess as to what the answer is. epsabs is the absolute error that we want. If epsabs = 0.1, we don't know what the answer is, but we know we are no more than 0.1 away from it. epsrel is similar, but percentage based instead of absolute. (e.g. epsrel = 0.01 means our answer is within 1% of the actual value.)

result and abserr are used by the function to store the result and estimated absolute error, respectively. The number of iterations it took to calculate the result is stored in neval.

It is possible for the integration to fail. This might happen if we set the error tolerances too tight. Since the function we're integrating is so simple, I don't think that's a likely concern.

`gsl_integration_qng()` in use

To compile this program, you will need to tell the compiler what external libraries to use. You can do with with the -lgsl compile flag, e.g. gcc main.c -lgsl. Because GSL depends on another library, CBLAS, you will also need the -lcblas flag. If CBLAS isn't available, you can use a version of CBLAS provided by GSL with -lgslcblas. (Don't forget to install GSL!) Since I'm using some math function, I'm also going to include the math library with -lm.

In the end, our command will look like gcc main.c -lgsl -lcblas -lm, which will compile main.c and create an output file a.out. (Actually I'm using org-babel so I don't have to deal with this, but I'm assuming most readers here are not.)

Alright! Time to integrate! I need to preface the gsl_integration.h header with gsl/ as the headers are installed in a gsl subdirectory. (If you installed this through your systems package manager, you can probably find this file in /usr/include/gsl/.)

#include <stdio.h>
#include <gsl/gsl_integration.h>
#include <math.h>

/* This is where we define the function */
double f(double x, void *params) {
  return x;
}

int main() {
  double result, error;
  double low = 0, high = 8;
  gsl_function F = {.function = &f};
  double err_abs = 0, err_rel = 1;
  size_t num_evals;

  gsl_integration_qng(&F, low, high, err_abs, err_rel,
      		&result, &error, &num_evals);
  printf("result error num_evals\n");
  printf("%f %f %zu\n", result, error, num_evals);
}

Results:
| result | error | num_evals |
|   32.0 |   0.0 |        21 |

There we go! GSL was able to successfully integrate $\int_{0}^{8}xdx$ .

In the next part, we'll start using GSL to calculate the Fourier series of a discontinuous, periodic function. We'll see if we can naively get away with using the simple gsl_integration_qng() function, or if we need to find a more complicated, but more powerful, alternative.

Are bus errors still commonplace? Plus a bonus discussion on org-babel.

2021-03-24T00:00:00Z

What is a bus error?

I was reading through Peter Linden's Expert C Programming when I noticed an interesting example. On page 189, Peter talks about how one can cause a bus error. I've never had a bus error occur before. Maybe they're a solved problem?

Before we get too far ahead of ourselves, a bus error can occur when we access a variable at an address that's not valid for that variable. An address is not valid if the address is not evenly divisible by the length of the variable. In other words...

/* sizeof (int) == 4 */
int p1 = *(int *) 5;
/* Causes a bus error, 5 % 4 != 0 */

int p2 = *(int *) 32;
/* No bus error, 32 % 4 == 0 */

Realistically these programs would immediately seg fault as we don't have access to arbitrary memory addresses. (Unless we were working with embedded systems, perhaps...). To avoid this, we can use a union.

Peter Linden's Code

Using the sample code in Expert C Programming, pg. 189, I am going to see if it causes a bus error.

The address of the union must be divisible by 4 (or sizeof int), as it can store an integer. As long as sizeof int > sizeof char (or sizeof int > 1 as sizeof char == 1), we can successfully get our bus error.

union {
  char a[10];
  int i;
} u;
int *p = (int *) &(u.a[1]);
,*p = 17;
printf("*p %d\n", *p);

#+RESULTS: : *p 17

Look at that! No problems.

x86 is very forgiving when it comes to misalignment errors. For the most part, they just don't happen. This is great for us, but what if we ported this code over to a platform that is less friendly, like ARM?

Ideally, we want to see if a bus error can occur in our code, so that way we can avoid them during development, as opposed to fixing it later.

Looking through the gcc manual, I found a compile flag that will be useful.

fsanitize=undefined
Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector. Various computations are instrumented to detect undefined behavior at runtime.

By adding the -fsanitize=undefined compile flag, our program will print a runtime error whenever one occurs.

There are similar flags, -fsanitize=address and -fsanitize=thread, that can be useful for runtime error checking; look at the gcc manual for more information. I can combine options with commas, i.e. -fsanitize=address,thread,undefined.

`-fsanitize=undefined`

There is one change that I need to make to the code. When a runtime error occurs, the results are printed to stderr. When we're looking at our code through a terminal, stderr and stdout might seem like the exact same thing.

I am not running this code through a terminal. I'm using org-babel, a very powerful tool for literate programming. If our program runs successfully, org-babel will tell us the results.

Unfortunately, these results don't include stderr. In order to see the runtime error occur, I need to close stderr, then change stderr's file descriptor to point to stdout. This is what the dup2() function is doing.

dup2(STDOUT_FILENO, STDERR_FILENO);

union {
  char a[10];
  int i;
} u;
int *p = (int *) &(u.a[1]);
,*p = 17;
printf("*p %d\n", *p);
printf("p %lld\n", p);

#+RESULTS:

/tmp/babel-YOFYnN/C-src-93AiCJ.c:17:6: runtime error: store to misaligned address 0x7ffec796bddd for type 'int', which requires 4 byte alignment
0x7ffec796bddd: note: pointer points here
 40 5a 14 84 55 00 00  e0 be 96 c7 fe 7f 00 00  00 f5 9a c3 4a 31 08 2e  00 00 00 00 00 00 00 00  25
             ^ 
/tmp/babel-YOFYnN/C-src-93AiCJ.c:18:3: runtime error: load of misaligned address 0x7ffec796bddd for type 'int', which requires 4 byte alignment
0x7ffec796bddd: note: pointer points here
 40 5a 14 84 11 00 00  00 be 96 c7 fe 7f 00 00  00 f5 9a c3 4a 31 08 2e  00 00 00 00 00 00 00 00  25
             ^ 
,*p 17
p 140732246965725

And it works! We can now see the runtime error! We're trying to access an integer at address 140732246965725, which is not divisible by 4 (AKA sizeof int). Thus, a bus error occurs.

Crash and burn programming

Running code and printing out runtime errors is great. However, there's a saying in programming called "Fail early, fail often". What if we don't just want an error message printed? What if, instead, we want the program to immediately crash? After all, this is what would actually happen if we were on a CPU architecture that couldn't handle misaligned addresses.

I looked through the gcc manual and saw the -fno-sanitize-recover=all option. Supposedly, it does the following:

-fsanitize-recover=all and -fno-sanitize-recover=all is also accepted, the former enables recovery for all sanitizers that support it, the latter disables recovery for all sanitizers that support it.

Let's try it! I'm going to add -fno-sanitize-recover=all as a compile flag. This should cause the program to immediately crash, only printing the error message.

dup2(STDOUT_FILENO, STDERR_FILENO);

union {
  char a[10];
  int i;
} u;
int *p = (int *) &(u.a[1]);
,*p = 17;
printf("p %d\n", *p);

Huh? Why wasn't the error message printed? Crashing the program is what we wanted, but not without the error message! Without an error message, all we're doing is making our program harder to debug.

Fortunately, this isn't our fault. The error message is actually being printed, and it is being printed to stdout. If we were running our program in a terminal, we'd see the error message we expect.

Unfortunately, this is a limitation of org-babel. -fno-sanitize-recover=all causes a nonzero exit code to be returned on failure. org-babel does not like nonzero exit codes and fails to evaluate stdout when this happens. It does evaluate stderr when the exit code is nonzero, but only to a separate temporary buffer. At least this works outside of org-babel.

There's a (brief) discussion of this issue on the mailing list here. Given that this thread is 5 years old, I'm not holding my breath for a fix.

There is an easy solution for sh scripts; just create a line at the end with :. Unfortunately since this is C, that's not really an option.

Wrapping it up

The entire point of this endeavour is to try to make sure our code is portable. When I write a program for one system, that program better work on as many other systems as possible.

If any college students read this, professors don't like the "but it worked on my machine!" excuse. (On the other hand, it takes one mean professor to test with a different architecture in order to if you were careful about memory alignment. We can't predict everything!)

-fsanitize=undefined is a great flag to add when compiling; it catches more than just memory alignment! If you add the flag and forget about it, you will at least get a warning when undefined behavior occurs! I'd much rather have a program that doesn't work but I know why then a program that doesn't work and I don't know why.

freakingpenguin blog

Haunt and Hoot and Blocks oh my!

Hoot

Info!

Ngspice

Guix Tricks: Managing secrets using password-store and run-time decryption scripts.

Intro

Runtime Decryption and Retrieval

The Not State of the Art Solution

A More Guixy Way

Conclusion

Guile Blocks: I Have Concepts of a Plan

PlantUML

Bytevector Evaluators

C

Guile Blocks: Fleshing out the Concept

Graphs

LaTeX

Tables

Guix Tricks: Soft-pinning channels in a channels.scm file.

Problem

Solution

Guix Tricks: Self-contained shebang scripts.

Intro

Another example

Guile Blocks: Proof of Concept

Introduction

Blocks

Haunt can handle org-mode source blocks too! Kinda.

Hello world from Guile Haunt!

stm8-card: Frame Buffers

Background

The Problem

Making due with less, drawing a display without a complete frame buffer

Manipulating the frame buffer: drawing images

Representing images with structs

Using these structs to draw on the display

Breaking apart draw_image()

The really ugly part of draw_image()

Using draw_image() and pals to draw on a display

Circular pointers in C

What is a circular pointer?

Failed Attempt

Some background

Malloc with multiple levels of pointers

Compile time errors dereferencing pointers

sizeof (int *) vs sizeof (int)

Circular pointers with malloc()!

Circular pointers with structs!

Fourier Part 2: Integrating a discontinuous function

Checking if gsl_integration_qng() will work

gsl_integration_qng() and discontinuities

Generating our Fourier series

Fourier Part 1: What is a Fourier series?

An overview of Taylor series

What we're all here for, Fourier series

Using GSL to calculate an integral

Explanation of gsl_integration_qng()

gsl_integration_qng() in use

Are bus errors still commonplace? Plus a bonus discussion on org-babel.

What is a bus error?

Peter Linden's Code

-fsanitize=undefined

Crash and burn programming

Wrapping it up

Breaking apart `draw_image()`

The really ugly part of `draw_image()`

Using `draw_image()` and pals to draw on a display

`sizeof (int *)` vs `sizeof (int)`

Circular pointers with `malloc()`!

Checking if `gsl_integration_qng()` will work

`gsl_integration_qng()` and discontinuities

Explanation of `gsl_integration_qng()`

`gsl_integration_qng()` in use

`-fsanitize=undefined`