Add a documentation page for the runtime variables

[martin-frbg]

fixes #3967

[rgommers]

Thanks Martin, this looks useful. I noticed a couple of other environment variables through a search that you may want to consider for inclusion: GOTO_DEBUG, GET_OPENBLAS_CORETYPE (this may be a mistake?), LD_HWCAP_MASK, OPENBLAS_L2_SIZE.

Full details:

Details

rg -g'!/benchmark' 'getenv|readenv'
common.h
484:#define readenv(p, n) 0
488:#define readenv(p, n) GetEnvironmentVariable((LPCTSTR)(n), (LPTSTR)(p), sizeof(p))
491:#define readenv(p, n) ((p)=getenv(n))
743:static __inline int readenv_atoi(char *env) {
748:static __inline int readenv_atoi(char *env) {
750:  return readenv(p,env) ? 0 : atoi(p);
753:static __inline int readenv_atoi(char *env) {
755:  if (( p = getenv(env) ))
926:#define PRINT_DEBUG_CNAME if (readenv_atoi("GOTO_DEBUG")) fprintf(stderr, "GotoBLAS : %s\n", CHAR_CNAME)
927:#define PRINT_DEBUG_NAME  if (readenv_atoi("GOTO_DEBUG")) fprintf(stderr, "GotoBLAS : %s\n", CHAR_NAME)

driver/others/dynamic.c
1129:  p = getenv("OPENBLAS_CORETYPE");

driver/others/dynamic_arm64.c
451:  p = getenv("OPENBLAS_CORETYPE");

driver/others/dynamic_riscv64.c
243:	p = getenv("OPENBLAS_CORETYPE");

driver/others/dynamic_mips64.c
182:  p = getenv("OPENBLAS_CORETYPE");

driver/others/dynamic_power.c
322:	p = getenv("OPENBLAS_CORETYPE");
342:		if (getenv("GET_OPENBLAS_CORETYPE")) {

driver/others/openblas_env.c
55:  if (readenv(p,"OPENBLAS_VERBOSE")) ret = atoi(p);
60:  if (readenv(p,"OPENBLAS_BLOCK_FACTOR")) ret = atoi(p);
65:  if (readenv(p,"OPENBLAS_THREAD_TIMEOUT")) ret = atoi(p);
70:  if (readenv(p,"OPENBLAS_DEFAULT_NUM_THREADS")) ret = atoi(p);
75:  if (readenv(p,"OPENBLAS_NUM_THREADS")) ret = atoi(p);
81:  if (readenv(p,"GOTO_NUM_THREADS")) ret = atoi(p);
86:  if (readenv(p,"OMP_NUM_THREADS")) ret = atoi(p);
91:  if (readenv(p,"OMP_ADAPTIVE")) ret = atoi(p);

driver/others/dynamic_loongarch64.c
161:  p = getenv("OPENBLAS_CORETYPE");

driver/others/init.c
820:  numprocs = readenv_atoi("OPENBLAS_NUM_THREADS");
821:  if (numprocs == 0) numprocs = readenv_atoi("GOTO_NUM_THREADS");
824:  if (numprocs == 0) numprocs = readenv_atoi("OMP_NUM_THREADS");
826:  if (numprocs == 0) numprocs = readenv_atoi("OPENBLAS_DEFAULT_NUM_THREADS");
973:    if (readenv_atoi("OPENBLAS_MAIN_FREE") || readenv_atoi("GOTOBLAS_MAIN_FREE")) {

driver/others/dynamic_zarch.c
116:	p = getenv("OPENBLAS_CORETYPE");

driver/others/memory.c
1712:inline char *getenv(const char *name) { return ""; }

cpuid_zarch.h
35:	maskenv = getenv("LD_HWCAP_MASK");

kernel/setparam-ref.c
1373:  l2 = readenv_atoi("OPENBLAS_L2_SIZE");

Changelog.txt
1647:	* Avoid potential getenv segfault. (#716)

lapack-netlib/LAPACKE/src/lapacke_nancheck.c
50:    env = getenv( "LAPACKE_NANCHECK" );

Also, do you mind if I push a style cleanup after you're done, for consistency with the rest of the rendered html docs? (can take it along in a follow-up too if that's better)

[martin-frbg]

That's why I haven't committed that one yet - but I'm fairly sure most others are IBM internal dev options that made it in by accident (and GOTO_DEBUG doesn't do anything useful anymore either - assuming it ever did in K.Goto's time)

[martin-frbg]

GOTO_DEBUG is ifdef'd out in common.h by default - if activated at compile time, all it (still?) allows is printing the name of the BLAS function from the interface code, making it of very limited value nowadays (I think). LD_HWCAP_MASK looks to be an IBM "toy" variable to suppress some HWCAP information provided by in-development cpus, I don't think this needs to be documented. GET_OPENBLAS_CORETYPE appears to be an IBM-internal use duplicate of OPENBLAS_VERBOSE=2 that could perhaps even be deleted from the current codebase.

[rgommers]

Thanks for the context!

I'll fold some rendering fixes and the change to add this new page into the sidebar into gh-5049.

[martin-frbg]

Thank you - I still need to learn about decent formatting with this tool

[rgommers]

No worries at all. Mostly it's standard Markdown, things like blank lines around lists are easy to forget unless you look at the rendered version.