Update Documentation

[yamaguchi1024]

Add documentation for design, imports, system overview, externs, inspection, instructions, memories, and object code. Also add the Cursor example in examples/cursors.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 88.00%. Comparing base (cebef49) to head (4c99d64).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #729   +/-   ##
=======================================
  Coverage   88.00%   88.00%           
=======================================
  Files          86       86           
  Lines       20965    20965           
=======================================
  Hits        18450    18450           
  Misses       2515     2515           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[akeley98]

Mention that this globl function is called for each unique prim_type.

By the way, this is better left for a different PR, but this means many externs don't work reliably if we mix precisions due to C name collisions. For example

@proc
def foo_sigmoid(xo : f32, yo : f64, xi : f32, yi : f64):
    xo = sigmoid(xi)
    yo = sigmoid(yi)

generates a C file that starts with

#include <math.h>
double sigmoid(double x) {
    return 1 / (1 + exp(-x));
}


#include <math.h>
float sigmoid(float x) {
    return 1 / (1 + exp(-x));
}

which is invalid (C does not support function overloading).

[yamaguchi1024]

Good catch! Yeah this is a bug, I filed it here: #737 737

[akeley98]

Isn't this restriction because externs can have side effects on their arguments, and thus we need the aliasing restriction for the same reason extended C++ has restrict?

[yamaguchi1024]

No, Exo procedures can modify their arguments (like put output in the out buffer), but externs should not be able to modify their arguments. Externs return the expression instead.

[yamaguchi1024]

Also, externs actually allow aliasing.

@proc
def foo(xo : f32, yo : f64, xi : f32, yi : f64):
    xo = select(xi, xi, xi, xi) 

gets compiled into

 float _select_float(float x,float v,float y,float z) {
    if (x < v) return y;
    else return z;
}

// foo(
//     xo : f32 @DRAM,
//     yo : f64 @DRAM,
//     xi : f32 @DRAM,
//     yi : f64 @DRAM
// )
void foo( void *ctxt, float* xo, const double* yo, const float* xi, const double* yi ) { 
*xo = _select_float((float)*xi, (float)*xi, (float)*xi, (float)*xi);
}

[akeley98]

Good new documentation, thanks.