{"id":20708689,"url":"https://github.com/sprintersb/atest","last_synced_at":"2025-07-04T21:32:43.525Z","repository":{"id":21296446,"uuid":"24612642","full_name":"sprintersb/atest","owner":"sprintersb","description":"AVRtest is an AVR core simulator used for regression testing of avr-gcc and parts of AVR-LibC.","archived":false,"fork":false,"pushed_at":"2025-04-14T15:53:47.000Z","size":1788,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-14T16:50:57.796Z","etag":null,"topics":["avr","avr-gcc","avr-gcc-toolchain","avr-simulator"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sprintersb.png","metadata":{"files":{"readme":"README","changelog":"ChangeLog","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-09-29T20:54:37.000Z","updated_at":"2025-04-14T15:53:50.000Z","dependencies_parsed_at":"2023-12-06T12:40:28.385Z","dependency_job_id":"fdbfd5ad-a850-4e04-9005-6e681552d14d","html_url":"https://github.com/sprintersb/atest","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sprintersb%2Fatest","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sprintersb%2Fatest/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sprintersb%2Fatest/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sprintersb%2Fatest/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sprintersb","download_url":"https://codeload.github.com/sprintersb/atest/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250360249,"owners_count":21417718,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["avr","avr-gcc","avr-gcc-toolchain","avr-simulator"],"created_at":"2024-11-17T01:32:46.942Z","updated_at":"2025-07-04T21:32:43.510Z","avatar_url":"https://github.com/sprintersb.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n================\nWhat is AVRtest?\n================\n\nAVRtest is a free software simulator for the AVR family of 8-bit\nmicrocontrollers distributed under the GNU General Public License.\n\nThe main intention of AVRtest is to supply a fast, easy-to-use simulator\nto run the GCC testsuite for avr-gcc or parts of the AVR-LibC testsuite.\n\nPre-built binaries for Windows are available at\nhttps://sourceforge.net/projects/winavr/files/AVRtest\n\n\n============\nIntroduction\n============\n\navrtest is an instruction set simulator for AVR core families\n    avr51: ATmega128*, AT90USB128*, ATtiny2313, ... with a 2-byte PC.\n    avr6:  ATmega256* with a 3-byte PC.\n\navrtest-xmega is an instruction set simulator for AVR XMEGA core families\n    avrxmega6: ATxmega128*, ... with a 3-byte PC.\n    avrxmega3: ATtiny212, ATtiny816, ... that see flash in RAM address space.\n    avrxmega4: ATxmega16*, ATxmega32*, ATxmega64*, ... with a 2-byte PC.\n    avrxmega7: ATxmega128A1, ATxmega128A1U, ... with a 3-byte PC and\n               that use RAMPx as high-byte for RAM accesses.\n\navrtest-tiny is an instruction set simulator for AVR TINY core families\n    avrtiny: ATtiny40, ... with only 16 GPRs and flash seen in RAM.\n\nAlso supported are cores avr2, avr25, avr3, avr31, avr35, avr4, avr5\nand avrxmega2.  They are just aliases for one of the cores above.\n\nThe executable that supports AVR XMEGA cores is named avrtest-xmega.\nIn addition to the AVRtest simulator, it supports the XMEGA instructions\nXCH, LAS, LAC and LAT.  For avrxmega3, it also supports the command line\noption '-pm 0x4000' in order to set the location of the flash image in\nthe RAM address space for devices like ATmega4808.  The default for\nthis option and for avrxmega3 is 0x8000.\n\nThe executable that supports reduced AVR TINY cores is named avrtest-tiny.\nIt only supports general purpose registers (GPRs) R16..R31,\nand many instructions like ADIW are not supported.  The LDS and STS\ninstructions are 1-word instructions that can access SRAM in the\nrange 0x40..0xbf.\n\nIn the remainder, avrtest is explained.  avrtest-xmega and avrtext-tiny\nwork similar.  AVRtest does not simulate internal peripherals like timers,\nI/O ports, interrupts, etc.\n\n\n================\nSpecial Features\n================\n\nThe simulated program can communicate with the simulator: It can write to\nthe host's standard output and it can read from the host's standard input.\nFor example, an easy hello world program for AVR could look like this:\n\n\n#include \u003cstdio.h\u003e\n\nint main (void)\n{\n    printf (\"Hallo World!\\n\");\n    return 0;\n}\n\n\nCompile this program as usual but link against exit-atmega128.o.\nHow to build that object file is explained in the next chapter.\nStore the C source as hello.c and compile it with, e.g.\n\n    avr-gcc hello.c -O -mmcu=atmega128 -o hello.elf /someplace/avrtest/exit-atmega128.o\n\nThe exit-*.o object implements stdout as a stream writing through to the\nhost computer's stdout, similar for stderr.  Similarly, stdin reads from\nthe host stdin.  Running the program\n\n    avrtest hello.elf\n\nwill print something like\n\n\nHallo World!\n\n exit status: EXIT\n      reason: exit 0 function called\n     program: hello.elf\nexit address: 0001a4\ntotal cycles: 837\ntotal instr.: 503\n\n\nYou can also use the respective primitive functions directly:\n\n\n#include \"avrtest.h\"\n\nint main (void)\n{\n    char c;\n\n    avrtest_putchar ('Q');\n\n    c = avrtest_getchar();\n    avrtest_putchar (c + 1);\n\n    return 0;\n}\n\n\nThe avrtest_putchar and avrtest_getchar functions are defined in avrtest.h\nand act like putchar resp. getchar in an ordinary, hosted program:\nputchar writes a character to the host's standard output,\nand getchar reads a character from the host's standard input.\n\nCompile the C source with\n\n    avr-gcc inout.c -O -mmcu=atmega128 -o inout.elf -I /someplace/avrtest\n\nWhen running the program with\n\n    avrtest inout.elf\n\nthe simulator will print a 'Q' on the console and wait for input.\nType '1\u003cEnter\u003e' and the output will be\n\n\nQ1\n2\n exit status: EXIT\n      reason: infinite loop detected (normal exit)\n     program: inout.elf\nexit address: 0000be\ntotal cycles: 27\ntotal instr.: 18\n\n\nThere are more functions available for program \u003c-\u003e simulator\ninteraction, see the respective sections below.\n\n\n=========================================================\nRunning the avr-gcc Testsuite using the AVRtest Simulator\n=========================================================\n\nhttp://lists.gnu.org/archive/html/avr-gcc-list/2009-09/msg00016.html\n\n* Get avr-gcc, Binutils and AVR-LibC built from sources and working.\n  For build instructions, see for example the\n  AVR-LibC documentation at\n  https://avrdudes.github.io/avr-libc/avr-libc-user-manual/install_tools.html\n\n* Install DejaGNU, expect and TCL\n\n* Unpack the AVRtest sources top \"someplace\".\n  You find a link to the package at\n  - \"Code \u003e Download ZIP\" on https://github.com/sprintersb/atest\n  - \"Download Snapshot\" from WinAVR\n    https://sourceforge.net/p/winavr/code/HEAD/tree/trunk/avrtest/\n\n* Run\n\n    make\n\n  inside /someplace/avrtest which will build executables from the AVRtest\n  C-sources and AVR object files exit-*.o from dejagnuboards/exit.c.\n\n* Adjust your $HOME/.dejagnurc file (or create one if it not already\n  exists) as indicated in /someplace/avrtest/.dejagnurc.\n  Change the \"avrtest_dir\" path to the directory where the avrtest\n  executable is located:\n\n    set avrtest_dir \"/someplace/avrtest\"\n\n* You can add /someplace/avrtest to your PATH variable so that it's\n  more convenient to start avrtest.  In order to run the GCC test\n  suite this is not necessary, though.\n\n* The .dejagnurc file sets the \"avrlibc_include_dir\" variable that points\n  to a directory where the compiler can find stdio.h and similar headers\n  from AVR-LibC.  Adjust this path to point to the \"incude/avr\" subdir\n  of a valid AVR-LibC installation.  You can also adjust that path in\n  the *-sim.exp file.\n\n* *-sim.exp just sets some custom variables and then loads\n  avrtest.exp from the same directory to run avrtest.\n\n* Run the tests from the ./gcc subdirectory of your avr-gcc build directory\n  like:\n\n      make -k check-gcc RUNTESTFLAGS=\"--target_board=atmega128-sim\"\n\n* Look in the ./gcc/testsuite subdirectory of avr-gcc build directory for\n  logged results gcc.sum, gcc.log, or add the -all switch to see it\n  working one test at a time:\n\n      make -k check RUNTESTFLAGS=\"--target_board=atmega128-sim -all\"\n\n* You can run parts of the testsuite like this:\n\n      make -k check RUNTESTFLAGS=\"--target_board=atmega128-sim avr.exp\"\n      make -k check RUNTESTFLAGS=\"--target_board=atmega128-sim avr-torture.exp=pr41885*.c\"\n\nVoila!\n\n\n===========================\nBuilding the exit.o Modules\n===========================\n\nThe exit-*.o Modules are build during make using avr-gcc.\nWhen you want to use a different avr-gcc not found in PATH, use:\n\n    make clean-exit all-avr CC_FOR_AVR=/some-compiler-path/avr-gcc\n\nWhen you need an exit module for a device not already present in the\nMakefile like ATmega16, you can just run\n\n    make exit-atmega16.o\n\nNotice that an exit module is not strictly required in a program that's\nsimulated with AVRtest.  But it defines streams like stdout so that\nfunctions like  printf  behave like in a hosted environment without\nany further ado.  Moreover, the exit module implements  exit()  in such\na way that it reports the program's exit code to the host, whereas\nwithout the module, the simulator will just print\n\"infinite loop detected (normal exit)\" as it hits the  rjmp .-2  in\nthe stock exit implementation\n\n\n================\n-h: Getting Help\n================\n\nRunning\n\n    avrtest -h\n\nwill print a help screen with available options:\n\n  usage: avrtest [-d] [-e ENTRY] [-m MAXCOUNT] [-mmcu=ARCH] [-s SIZE]\n                 [-no-log] [-no-stdin] [-no-stdout] [-no-stderr]\n                 [-log=FILE] [-stdin=FILE] [-stdout=FILE] [-stderr=FILE]\n                 [-q] [-flush] [-runtime] [-v]\n                 [-graph[=FILE]] [-sbox=FOLDER]\n                 program [-args [...]]\n         avrtest --help\nOptions:\n  -h            Show this help and exit.\n  -args ...     Pass all following parameters as argc and argv to main.\n  -d            Initialize SRAM from .data (for ELF program)\n  -e ENTRY      Byte address of program entry.  Default for ENTRY is\n                the entry point from the ELF program and 0 for non-ELF.\n  -pm OFFSET    Set OFFSET where the program memory is seen in the\n                LD's instruction address space (avrxmega3 only).\n  -m MAXCOUNT   Execute at most MAXCOUNT instructions. Supported\n                suffixes are k for 1000 and M for a million.\n  -s SIZE       The size of the simulated flash.  For a program built\n                for ATmega8, SIZE would be 8K or 8192 or 0x2000.\n  -q            Quiet operation.  Only print messages explicitly\n                requested.  Pass exit status from the program.\n  -v            Verbose mode.  Print the loaded ELF program headers\n                and the used streams.\n  -runtime      Print avrtest execution time.\n  -no-log       Disable instruction logging in avrtest_log.  Logging\n                can still be turned on with LOG_ON etc., see README.\n  -log=FILE     Commands like LOG_U8 will print to FILE on the host.\n                FILE must be stdout (default), stderr, *.log or *.txt.\n  -no-stdin     Disable avrtest_getchar (syscall 28) from avrtest.h.\n  -no-stdout    Disable avrtest_putchar (syscall 29) from avrtest.h.\n  -no-stderr    Disable avrtest_putchar_stderr (syscall 24).\n  -stdin=FILE   stdin reads from the host's *.txt or *.data FILE.\n  -stdout=FILE  Similar, but for stdout.\n  -stderr=FILE  Similar, but for stderr.\n  -flush        Flush stdout resp. stderr after each character.\n  -sbox SANDBOX Provide the path to SANDBOX, which is a folder that the\n                target program can access via file I/O (syscall 26).\n  -graph[=FILE] Write a .dot FILE representing the dynamic call graph.\n                For the dot tool see  http://graphviz.org\n  -graph-help   Show more options to control graph generation and exit.\n  -mmcu=ARCH    Select instruction set for ARCH\n\n\n=========================================\n-s SIZE : Specifying simulated Flash Size\n=========================================\n\nThe simulator must know the flash size of the simulated controller\nso it can correctly simulare instructions like RJMP.  For example,\nan  RJMP .-4  located at address 0x0 will jump to 0x1ffe on ATmega8\nbut to 0x7fe on ATtiny2313.\n\nFor programs that use the start-up code from AVR-LibC in crt\u003cmcu\u003e.o,\nAVRtest will read the flash size from a special note section named\n.note.gnu.avr.deviceinfo contained in that startup-code.  AVRtest will\nprint its contents with -v.\n\nIn the following situations, -s SIZE can be used to specify the flash size:\n\n* The program does not use startup-code from AVR-LibC.  In that case,\n  you can specify, say  -s 8192  or  -s 0x2000  or  -s 8k  for ATmega8.\n\n* You want to use a flash size other than shipped with crt\u003cmcu\u003e.o.\n\n* Use  -s -1  if you don't want to specify a flash size and also don't\n  want to use flash size from .note.gnu.avr.deviceinfo.  AVRtest will\n  use a core-specific default value.\n\n\n====================\n-q : Quiet Operation\n====================\n\nWith -q turned on, AVRtest will print no messages except the ones\nexplicitly requested by:\n\n  - -runtime\n  - LOG_U8 (X), PERF_DUMP_ALL and similar logging commands, see below.\n\nThe following exit stati will be returned with -q:\n\n  -  0  Everything went fine.\n  -  1  Target program called abort()\n  -  x  Target program called exit(x)\n  - 10  Program timeout as set by -m MAXCOUNT\n  - 11  Something is wrong with the program file:  Does not fit into\n        memory, not an AVR executable, ELF headers broken, ...\n  - 12  The program goes haywire:  Stack overflow, illegal instruction or PC.\n  - 13  Problem with symbol information like an odd function address.\n  - 14  Problem with using file I/O with the host's file system: Bad file\n        handle or file name, illegal argument.  This does *not* encompass\n        when fopen cannot open the file; this will just return a 0-handle.\n\n  - 20  Out of memory.\n  - 21  Wrong AVRtest usage: Unknown options, etc.\n  - 22  Program file could not be found / read.\n\n  - 42  Fatal error in AVRtest.\n\nWithout -q, the exit status will be 1 (EXIT_FAILURE) for the cases \u003e= 20\nfrom above.  For all the cases \u003c 20 from above, 0 (EXIT_SUCCESS) will\nbe returned.\n\n\n===================\nSpeed of Simulation\n===================\n\nThe main incentive behind AVRtest is speed of execution.  For AVRtest\ncompiled with a reasonably optimizing compiler (like with \"gcc -O3\"),\nthe speed of a simulated program is around\n\n  45 MHz/GHz  for  avrtest              on x86_64\n  12 MHz/GHz  for  avrtest_log -no-log  on x86_64\n\nmeasured on an Intel Core2 Duo (x86_64).  On x86, the performance is\nca 70% of the above, i.e. around\n\n  30 MHz/GHz  for  avrtest              on x86\n   8 MHz/GHz  for  avrtest_log -no-log  on x86\n\nThe GHz-values refer to the execution speed of the host computer,\nand the MHz-values refer to an AVR microcontroller.  For example,\nwith a x86_64 host running at 2 GHz, AVRtest will perform as fast\nas an AVR running at around 90 MHz.\n\nAVRtest is a single-core application.  The speed values are under\nthe assumption that the simulator performs no logging or printing.\nThe timing will also depend slighly on which instructions are being\nsimulated.\n\n\n===================================================\n-m MAXCOUNT : Maximum Instruction Count to simulate\n===================================================\n\nPer default, there is no limitation of the number of simulated instructions.\nThis is a problem with malfunctioning programs.  When such cases may occur,\nthe maximal number of instructions that will be simulated can be set\nwith -m MAXCOUNT.\n\nSupported suffixes are k for 1000 and M for a million, for example -m 1M\nand -m 1e6 will simulate no more than 1000000 instructions and terminate\nwith a TIMEOUT exit status when the program requires more instructions.\n-m 0 means no limitation (default).\n\n\n============================================\n-args ... : Passing Arguments to the Program\n============================================\n\nAll arguments after -args will be passed to the target program as if the\nprogram was running from the command line.  This is accomplished by startup\ncode from exit.c located in section .init8 right before main is called.\n\nIf you have own startup code in .init8 make sure it will be located before\nthe code from exit.c, e.g. by appropriate order of the objects passed to\nthe linker or by means of a custom linker script.\n\nThe first argument (argv[0]) is the program name with directories\nstripped off to save space.  The last argument argv[argc] is set to NULL.\n\nThe simulator will transfer the arguments to RAM and set R24 to argc,\nR22 to argv and R20 to env so that you can write\n\n\nint main (int argc, char *argv[])\n{\n    ...\n}\n\n\nresp.\n\n\nint main (int argc, char *argv[], char *env[])\n{\n    ...\n}\n\n\nand use argc and argv as in any hosted application:  If the program under\nsimulation is main.elf and you run\n\n    avrtest main.elf -args hallo \"4 2\"\n\nthen:\n\n    argc       is 3\n    argv[0]    is (the address of) string \"main.elf\" (i.e. argv[0][0] = 'm')\n    argv[1]    is (the address of) string \"hallo\"\n    argv[2]    is (the address of) string \"4 2\"\n    argv[3]    is the NULL pointer\n\nenv is set to the NULL pointer if the program is executed by avrtest\nand to a non-NULL pointer when executed by avrtest_log.\n\nexit.c:avrtest_init_argc_argv() requests the command args to be put\nstarting at a RAM address hard-coded in exit.c::avrtest_init_argc_argv().\nIf you prefer a different location then adjust exit.c according to your\nneeds, following the source comments.\n\n--------\n-no-args\n--------\n\nwill act as if no -args switch was supplied:  It skips all arguments\nthereafter and sets argc = 0, argv = NULL and env as described above.\n\n\n===========================\n-no-log and Logging Control\n===========================\n\n* Instruction logging is only supported by the avrtest_log family.\n\navrtest_log will log address and action of each executed instruction to\nstandard output of the host.  In cases where that is too much a flood of\ninformation, you can start avrtest_log with -no-log and turn on instruction\nlogging by executing special commands defined in avrtest.h:\n\n    // Turn on instruction logging.\n    LOG_ON;\n\n    // Turn it off again.\n    LOG_OFF;\n\n    // Push the current state of the logging (on or off) to an\n    // internal simulator stack, and then turn logging on / off.\n    LOG_PUSH_ON;\n    LOG_PUSH_OFF;\n\n    // Pop the logging state from the top of that stack.\n    LOG_POP;\n\n    // Turn on logging for the next N instructions and then switch\n    // it off again.\n    LOG_SET (N);\n\n    // Turn on logging during performance measurement described below,\n    // i.e. if any timer is in a START / STOP round.\n    LOG_PERF;\n\nPlease notice that this method of switching logging on / off is (low)\nintrusive to the program.  The commands listed above are translated by\nthe compiler to machine instructions that might affect code generation\nfor the surrounding code (register allocation, jump offsets, ...).\nThe commands have low overhead; it's not more than an AVRtest syscall.\n\nLOG_ON, LOG_OFF, LOG_PUSH_ON, LOG_PUSH_OFF and LOG_POP are also supplied\nas macros that can be used from assembly code.  They have no effect\non the internal state of the program (except for the program counter:\nthe respective syscalls consume 4 bytes of code).\n\n\n===================================\nLogging Values to the Host Computer\n===================================\n\nThe log destination can be set with -log=FILE, where FILE\nis stdout (default), stderr or a *.log or *.txt file name.\n\nIn order to get values out of the running program, the following\nlow-overhead, low-intrusive commands might be useful:\n\n    LOG_U8 (X);         print X as unsigned 8-bit decimal value\n    LOG_S8 (X);         print X as signed 8-bit decimal value\n    LOG_X8 (X);         print X as unsigned 8-bit hexadecimal value\n\nBesides these you can use similar commands for wider values with\n16, 24 and 32 bits, e.g.\n\n    LOG_U16 (X);\n    LOG_X32 (X);\n\netc.  Moreover, there are the following commands:\n\n    LOG_STR (X);        log string X located in RAM\n    LOG_PSTR (X);       log string X located in Flash\n    LOG_ADDR (X);       log address X\n    LOG_FLOAT (X);      log float X\n    LOG_DOUBLE (X);     log double X\n    LOG_LDOUBLE (X);    log long double X\n    LOG_D64 (X);        log an uint64_t, the bit representation of which\n                        is interpreted as an IEEE double number\n                        (11-bit exponent, 52-bit encoded mantissa)\n    LOG_F7T (X);        log LibF7's f7_t*\n\nAll of these logging commands have variants that take a custom\nprintf format string to print the supplied value:\n\n    LOG_FMT_XXX (F, X);    log X using format string F located in RAM\n    LOG_PFMT_XXX (F, X);   log X using format string F located in Flash\n\n!!! Please use format strings with care!  You can easily crash AVRtest\n!!! and make it raise a Segmentation Fault or other undefined behaviour\n!!! by specifying a format string that does not match the value!\n!!! Notice that the %-formats below refer to the HOST machine, i.e. the\n!!! machine that executes AVRtest!\n\nAVRtest uses \"double\" to represent floating point values and \"unsigned int\"\nfor all other values up to 4 bytes.  The default format strings for the vanilla\nLOG_XXX are:\n\n    \" %u \"              for the \"U\" variants\n    \" %d \"              for the \"S\" variants\n    \" 0x%02x \"          for the 8-bit \"X\" variants\n    ...                 ...\n    \" 0x%08x \"          for the 32-bit \"X\" variants\n    \"%s\"                for strings\n    \" 0x%04x \"          for addresses\n    \" %.6f \"            for float, double, long double and 64-bit unsigned\n                        interpreted as a 64-bit IEEE floating point number\n    \"%s\"                for f7_t*\n\nFor 8-byte values, the internal representation is \"unsigned long long\", and\nthe default format strings are:\n\n    \" %llu \"              for the \"U\" variant\n    \" %lld \"              for the \"S\" variant\n    \" 0x%016llx \"         for the \"X\" variant\n\n\n================\nSupport of FLMAP\n================\n\nDevices from the AVR64* and AVR128* families see a 32 KiB segment of their\nprogram memory in the RAM address space.  Which segment is visible and\naccessible is determined by bit field NVMCTRL_CTRLB.FLMAP.\nAVRtest copies the segment as specified by FLMAP from program memory into\nthe RAM address space in .init4 by means of code from exit-avr*.o.\n\nThis means setting of NVMCTRL_CTRLB.FLMAP has only an effect when it happens\nprior to that in .init1 ... init3.\n\nIf you really want to test an application that switches FLMAP back and forth,\nyou have to trigger a re-write of the 32 KiB segment by means of a call to\n   avrtest_misc_flmap (uint8_t flmap);\neach time, where flmap ranges from 0 to 3.\n\n\n==================================================\nFile I/O with the File System of the Host Computer\n==================================================\n\n!!! In order to printf to a file on the host there is\n!!! -stdout=FILE where FILE is a *.txt or *.data file.\n!!! Similarly, there are -stderr=FILE and -stdin=FILE.\n!!! No file I/O complications are needed.\n\nAVRtest supports basic file I/O capabilities that enable the target program\nto communicate with the host's file system.  In order to enable this, option\n\n    -sbox SANDBOX\n\nhas to be set on the command line.  SANDBOX is the name of a folder of the\nhost file system.  SANDBOX will be prepended to the file name passed to\nfopen() without any further ado.  AVRtest implements several functionalities\nfound in stdio.h and provides them by means of a syscall that can be accessed\nby functions from avrtest.h:\n\n    unsigned long avrtest_fileio_p (char what, const void *pargs);\n    unsigned long avrtest_fileio_1 (char what, unsigned char args);\n    unsigned long avrtest_fileio_2 (char what, unsigned      args);\n    unsigned long avrtest_fileio_4 (char what, unsigned long args);\n\nWHAT specifies the host operation to perform.  For each supported function,\nthere is a macro AVRTEST_F that can be used as WHAT where F specifies the\nfunction.  For example, AVRTEST_fopen specifies to call the host's fopen().\nIn order to specify FILEs, handles are passed around instead or FILE*\npointers:  If the prototype of the stdio.h function specifies a FILE*\nargument, then the AVRtest interface uses a handle instead.  A handle is\na small 8-bit value.\n\nARGS resp. PARGS specifies the arguments to pass to the host.  If all of them\n-- after replacing FILE* by its respective handle -- fit into 4 bytes, then\nthese arguments are passed compressed as ARGS.  If they do not fit into 4 bytes,\nthen the PARGS variant has to be used where PARGS points to a memory location\nwhere to find the arguments.\n\nTo give an example, fopen whould be called as\n\n    uint8_t handle = (uint8_t) avrtest_fileio_4 (AVRTEST_fopen, args);\n\nwhere the low-word of ARGS is a const char* that points to the file name\n(which will be appended to SANDBOX as-is), and the high-word is a char\npointer to the mode to use to open the file.  The return value ships the\nhandle associated to the host's FILE* in the low-byte of the return value,\nthe other bytes of the return value are unused.  HANDLE would be used in\nsubsequent calls like AVRTEST_fclose, that passes the file handle in the\nlow-byte of ARGS.\n\n------------------------------------\nFile I/O:  Using the fileio.c Module\n------------------------------------\n\nFor convenience, AVRtest comes with a target module that supplies wrappers\nfor the available file I/O functions.  The interface of these functions is\nas specified by the C standard, and fileio.c then tries to map the FILE*\npointer to an associated handle that's needed for the respective AVRtest\nsyscall.  The following functions from stdio.h are implemented:\n\n    fopen, fclose, feof, fflush, clearerr, fread, fwrite.\n\n!!! However, using fileio.c comes with some limitations, and it needs\n!!! special options when linking.  See the next section for details.\n\nIf a handle is not found, a default action might be performed.  Suppose for\nexample a call to fread.  If fileio.c finds a handle associated to the passed\nFILE*, it will call the host's fread with the host's FILE* derived from the\nhandle; otherwise it calls the AVR-LibC implementation of fread which uses\nFILE* and operates byte-by-byte.\n\nMost functions like fputc, fgetc, fputs, fprintf, etc. that are not included\nin the above list will work out-of-the-box and without special treatment or\nwrappers from the fileio module.\n\nYou can use fileio.c/h as a module in your application, or you can link\nagainst one of the pre-compiled object files built by make.  For a program\nthat simulates ATmega128 for example, the link command would read\n\n    avr-gcc -mmcu=atmega128 fileio-atmega128.o -Wl,-wrap,fclose -Wl,-wrap,feof ...\n\nand then simulate program.elf with avrtest or avrtest_log.\n\nIn order to circumvent AVR-LibC stdio.h pecularities and also for\nbetter performance, the fileio module provides functions that use\nhandles directly instead of the need for an intermediate FILE*.\nThese functions with their obvious semantics are:\n\n    fileio_handle_t host_fopen (const char *filename, const char *mode);\n    int host_fclose (fileio_handle_t);\n    int host_fflush (fileio_handle_t)\n    int host_feof (fileio_handle_t);\n    int host_fseek (fileio_handle_t, long pos, uint8_t whence);\n    int host_fgetc (fileio_handle_t);\n    int host_fputc (char, fileio_handle_t);\n    void host_clearerr (fileio_handle_t);\n    size_t host_fwrite (const void*, size_t, size_t, fileio_handle_t);\n    size_t host_fread (void*, size_t, size_t, fileio_handle_t);\n\n-------------------------------------------------\nFile I/O:  Caveats, Restrictions and Limitations\n-------------------------------------------------\n\nDue to peculiarities of AVR-LibC's stdio.h implementation, the\nfollowing rules have to be obeyed when using file I/O via fileio.c:\n\n* The linker must be called with -wrap for the following symbols:\n\n      feof, fwrite, fread, fclose, cleaerr\n\n  i.e. avr-gcc has to be called with\n\n      avr-gcc ... -Wl,-wrap,feof -Wl,-wrap,fwrite -Wl,-wrap,fread ...\n\n  when linking.  For the documentation of -wrap, see\n  http://sourceware.org/binutils/docs-2.32/ld/Options.html#index-_002d_002dwrap_003dsymbol\n\n* When using AVRtest to run the GCC test suite for AVR, the host interactions\n  that exit-*.o supplies via stdout and stderr should be sufficient.\n  The complexity of fileio is not needed for the GCC test suite.\n\n---------------------------------------------------------------\nFile I/O:  Special Streams for the Host's stdin, stdout, stderr\n---------------------------------------------------------------\n\nThe fileio module provides\n\n    FILE *host_stdin;\n    FILE *host_stdout;\n    FILE *host_stderr;\n\nthat are associated to the host's stdin, stdout and stderr, respectively.\nThe respective handles to use with functions like host_fflush() are:\n\n    HANDLE_stdin\n    HANDLE_stdout\n    HANDLE_stderr\n\n\n=======================\nPerformance Measurement\n=======================\n\n* This feature is only supported by avrtest_log and avrtest-xmega_log.\n\nThe simulator supports 7 independently operating performance-meters 1..7:\n\n    PERF_START (N);\n\nstarts perf-meter N which will start capturing values of the running program\nlike program counter, instruction count, stack pointer, call depth, etc.\n\n    PERF_STOP (N);\n\nwill halt the perf-meter.  Upon encountering the next PERF_START(N)\nthe meter will be re-enabled and proceed.  The collected values can\nbe dumped at any time to the standard output of the host computer by\n\n    PERF_DUMP (N);\n\nor\n\n    PERF_DUMP_ALL;\n\nThis will show a summary of the extremal values for the perf-meter(s) and\nreset it completely so that you can use it for a different task afterwards.\nDisplayed values are:\n\n - Stack (abs):  Values of the stack pointer (SP).\n - Stack (rel):  Stack usage relative to the starting point.\n - Calls (abs):  The absolute call depth (CALLs increment, RETs decrement).\n - Calls (rel):  Call depth relative to the starting point.\n\nTracking of the call depth won't work as expected for setjmp / longjmp\nand similar functions that set SP to an unknown call depth.\n\nIn order to give a specific perf-meter N a more descriptive name there are\n\n    PERF_LABEL (N, L);\n    PERF_PLABEL (N, L);\n\nwhere label L is a C-string residing in RAM or Flash, respectively.\navrtest_log will cache the label so you can override it after PERF_LABEL.\n\nIf you want to find out what value lead to the round with mimimal or maximal\ninstruction cycles, the next START/STOP round can be tagged with a value:\n\n    PERF_TAG_STR (N, STR);      Tag perf-meter N with string STR\n    PERF_TAG_U16 (N, U);        ... with a 16-bit unsigned integer U\n    PERF_TAG_S16 (N, U);        ... with a 16-bit signed integer U\n    PERF_TAG_U32 (N, U);        ... with a 32-bit unsigned integer U\n    PERF_TAG_S32 (N, U);        ... with a 32-bit signed integer U\n    PERF_TAG_FLOAT (N, F);      ... with float F\n\nJust like with LOG_XXX(), S16 and S32 are represented internally as \"int\",\nU16 and U32 as \"unsigned\" and float as \"double\".  The default format strings\nto print the tags are \"%s\" for string, \" %u \" for the unsigned versions,\n\" %d \" for the signed ones and \" %.6f \" for float.\n\nCustom format strings can be supplied by\n\n    PERF_TAG_FMT_U16 (N, FMT, U);\n    PERF_TAG_PFMT_S32 (N, FMT, U);\n\netc. with a format string FMT located in RAM resp. Flash.\n\nExample:\n\n\n#include \u003cmath.h\u003e\n#include \"avrtest.h\"\n\nfloat x, y;\n\nint main (void)\n{\n    PERF_LABEL (1, \"resource consumption of sin()\");\n\n    for (x = 0.0; x \u003c= 3.14159; x += 0.01)\n    {\n        PERF_TAG_FMT_FLOAT (1, \" sin (%.5f) \", x);\n        PERF_START (1);\n        y = sin (x);\n        PERF_STOP (1);\n\n        PERF_TAG_FMT_FLOAT (2, \" x=%.5f \", x);\n        PERF_STAT_FLOAT (2, fabs (x * (1 - x*x / 6) - y));\n    }\n\n    PERF_DUMP_ALL;\n    return 0;\n}\n\n\nCompiling as usual, linking against exit-*.o and running\n\n    avrtest_log ... -no-log -q\n\nproduces an output like\n\n\n--- Dump # 1:\n Timer T1 \"resource consumption of sin()\" (315 rounds):  027c--029e\n              Instructions        Ticks\n    Total:       411402          541887\n    Mean:          1306            1720\n    Stand.Dev:     75.5            85.6\n    Min:            686            1029\n    Max:           1515            1952\n    Calls (abs) in [   1,   5] was:   1 now:   1\n    Calls (rel) in [   0,   4] was:   0 now:   0\n    Stack (abs) in [04f8,04e5] was:04f8 now:04f8\n    Stack (rel) in [   0,  19] was:   0 now:   0\n\n           Min round Max round    Min tag           /   Max tag\n    Calls       -all-same-                          /\n    Stack       -all-same-                          /\n    Instr.         1       315     sin (0.00000)    /   sin (3.14000)\n    Ticks          1       315     sin (0.00000)    /   sin (3.14000)\n\n Stat  T2 \"\" (315 Values)\n    Mean:       3.589886e-001     round    tag\n    Stand.Dev:  5.247231e-001\n    Min:        0.000000e+000         1     x=0.00000\n    Max:        2.021442e+000       315     x=3.14000\n\n\nThe computation of sin (x) took 1029..1952 cycles (with an average\nof 1720 cycles) for the 315 values it had been computed.\nsin() needs 19 bytes stack space.  The maximal difference between\nsin (x) and the 3rd-order approximation  x - x^3 / 6  is 2.02144\nand occurred for x = 3.14000.\n\n    PERF_STAT_FLOAT (N, F);\n\nin the example makes perf-meter N gather statistics of float value F:\nmean (expected value), standard deviation, minimum, maximum, and the\nSTART/STOP round for which a minimal / maximal value of F has been seen.\nIf rounds have been tagged, the tags for the rounds that yielded a minimal\nand maximal value of F are also displayed.  Besides PERF_STAT_FLOAT there\nis also PERF_STAT_U32 and PERF_STAT_S32 to get statistics for (un)signed\n32-bit integer values.\n\nIn the sample code from above, one is interested in the resource consumption\nof the sin function.  In order to supply that function with a value x and to\nstore the result y, additional instructions are needed:\n\n    PERF_START (1);\n    y = sin (x);\n    PERF_STOP (1);\n\nIf these additional instructions are of no interest, use\n\n    PERF_START_CALL (N);\n\nwhich only adds costs of instructions that are at a call depth of at\nleast 1 (relative to the starting point).  This includes costs of\nCALL and RET that start / finish the function.\n\nMake sure that the function of interest is not inlined or optimized away,\ne.g. by making inputs and outputs volatile and attributing the function\nwith __attribute__((noinline,noclone)).  The additional overhead caused by\nthe volatile accesses does not matter as it is ignored by PERF_START_CALL.\n\n\n=============================\nTiming Data and Random Values\n=============================\n\nFollowing functions return an unsigned 32-bit value:\n\n    avrtest_cycles();       Program cycles of simulated instructions\n    avrtest_insns();        Number of simulated instructions\n    avrtest_prand();        A 32-bit pseudo random number\n    avrtest_rand();         A 32-bit random number\n\nThe values are \"owned\" by the program and are distinct from the\ncounters used by performance meters or that are displayed when AVRtest\nterminates.  Except rand, the values can be reset to their value at\nprogram start:\n\n    avrtest_reset_cycles();       Set cycles of simulated instructions to 0\n    avrtest_reset_insns();        Set number of simulated instructions to 0\n    avrtest_reset_prand();        Reset the pseudo random number generator\n    avrtest_reset_all();          Reset all of them\n\nIn order to determine the run time of a function more precisely, there is:\n\n    avrtest_cycles_call();        The next avrtest_cycles() will capture the\n                                  number of cycles from the first [R]CALL\n                                  after avrtest_cycles_call() up to the\n                                  respective RET.\nExample:\n\n    avrtest_cycles_call();\n    func();\n    // Get cycles consumed by func(), including [R]CALL and RET.\n    avrtest_cycles_call();\n\nThe simulator does not account cycles to syscalls.\nThe values returned by `avrtest_prand()` do not depend on the host machine.\nThey only depend on the number of calls since the last reset.\n\n\n===================================\n32-Bit and 64-Bit Integer Emulation\n===================================\n\nAVRtest supports syscalls like avrtest_\u003cop\u003es32 and avrtest_\u003cop\u003eu32\nwith obvious semantics for \u003cop\u003e in: mul, div, mod.\n\nAVRtest supports syscalls like avrtest_\u003cop\u003es64 and avrtest_\u003cop\u003eu64\nwith obvious semantics for \u003cop\u003e in: mul, div, mod.\n\n\n=====================\nIEEE single Emulation\n=====================\n\nAVRtest supports syscalls like\n\n    float avrtest_mulf (float, float);\n    float avrtest_sinf (float);\n\nin order to help with IEEE single implementation.\n\nSupported functions with one float argument are:\n    sin, asin, sinh, asinh, cos, acos, cosh, acosh, tan, atan, tanh, atanh,\n    exp, log, log2, log10, sqrt, cbrt, trunc, ceil, floor, round, fabs.\n\nSupported functions with two float arguments are:\n    mul, div, add, sub, ulp, prand,\n    pow, atan2, hypot, fdim, fmin, fmax, fmod.\n\nSome more functions are:\n    frexp, ldexp, modf, powi, cmp, uto, sto, strto.\n\nDon't forget to append 'f' to the function name for the float versions.\n\navrtest_utof and avrtest_stof convert uint32_t resp. int32_t to float.\navrtest_cmpf compares two floating-point values.  It returns -1, 0, +1\nwhen the values are less, equal or greater, respectively.\nIt returns -128 for unordered comparisons.\navrtest_strtof converts an ASCII string to float, just like strtof.\navrtest_prandf returns an evenly distributed pseudo-random number\nin the specified range.  The pseudo-random source is the same like\nfor avrtest_prand.\navrtest_ftol and avrtest_ltof convert between float and long double.\navrtest_powif implements __builtin_powif.\n\nAVRtest will terminate with an error if the host IEEE single cannot\nbe used for emulation.\n\nHere is an example for the usage of avrtest_sinf:\n\n#include \"avrtest.h\"\n\nfloat compute_sinf (float x)\n{\n    float y = avrtest_sinf (x);\n    LOG_FMT_FLOAT (\"sinf(%f) = \", x);\n    LOG_FMT_FLOAT (\"%f\\n\", y);\n    return y;\n}\n\nFixed-point to/from float conversions avrtest_\u003cfx\u003etof and\navrtest_fto\u003cfx\u003e are supported for \u003cfx\u003e in:\n* k, uk, hk, uhk, r, ur, hr, uhr.\n\nFor example uhk are \"unsigned short accum\" conversions.\nThey require that \u003cstdfix.h\u003e is included prior to avrtest.h.\n\n\n=====================\nIEEE double Emulation\n=====================\n\nAVRtest supports syscalls like\n\n    long double avrtest_mull (long double, long double);\n    long double avrtest_sinl (long double);\n\nPlus, there are syscalls like\n\n    uint64_t avrtest_mul_d64 (uint64_t, uint64_t);\n    uint64_t double avrtest_sin_d64 (uint64_t);\n\nwith the same functionality, but they interpret uint64_t as IEEE double.\nThe _d64 versions are available irrespective of the layout of long double.\n\nSupported functions are the same like for IEEE single but with 'l'\ninstead of 'f' at the end of the syscall name;\nwith the one exception of `avrtest_strtold` that an ASCII string to\nlong double, just like `strtold`.\n\nAVRtest will terminate with an error when the host IEEE double cannot\nbe used for emulation.  The functions are not available for Reduced Tiny.\n\nHere is an example for the usage of avrtest_sqrtl:\n\n#include \"avrtest.h\"\n\nlong double compute_sqrtl (long double)\n{\n    long double y = avrtest_sqrtl (x);\n    // The host uses \"double\" for floating-point values, thus\n    // use \"%f\" (or similar) to print and NOT \"%Lf\".\n    LOG_FMT_LDOUBLE (\"square-root(%f) = \", x);\n    LOG_FMT_LDOUBLE (\"%f\\n\", y);\n    return y;\n}\n\n\n==============================\nAssembler Support in avrtest.h\n==============================\n\navrtest.h adds assembler support for a few AVRtest features:\n\n    avrtest_syscall \u003csysno\u003e\n    LOG_OFF             ;; Same as \"avrtest_syscall 0\"\n    LOG_ON              ;; Same as \"avrtest_syscall 1\"\n    LOG_PUSH_OFF        ;; Same as \"avrtest_syscall 9\"\n    LOG_PUSH_ON         ;; Same as \"avrtest_syscall 10\"\n    LOG_POP             ;; Same as \"avrtest_syscall 11\"\n    AVRTEST_ABORT       ;; Same as \"avrtest_syscall 31\"\n    AVRTEST_EXIT        ;; Same as \"avrtest_syscall 30\", exit value = R25:R24.\n    AVRTEST_PUTCHAR     ;; Same as \"avrtest_syscall 29\", char = R24\n    AVRTEST_ABORT_2ND_HIT ;; Same as \"avrtest_syscall 25\"\n\n\"avrtest_syscall \u003csysno\u003e\" is an assembler macro which expands to\n\n    CPSE  R\u003csysno\u003e, R\u003csysno\u003e\n    .word 0xffff\n\ni.e. it does not change any register and does not change the program\nstatus (SREG).\n\nExample:\n\n    #include \"avrtest.h\"\n\n    .text\n    .global func\n\n    func:\n        LOG_ON\n        ret\n\nAnd then call this function from assembler or from C code after\ndeclaring it with \"extern void func (void);\".\n\n\n================\nCompiler Support\n================\n\n* avr-gcc can be used with avrtest.h.\n\n* To date (2024), clang has bugs so that programs that include avrtest.h\n  cannot be compiled and terminate with an error message (or internal error)\n  for the used inline assembly.\n\n* avrtest.h supports `avr-gcc -mint8` with an 8-bit int type.\n  Notice that  -mint8  is not a multilib option and therefore functions\n  from libgcc and AVR-LibC will not work when they take an int, long\n  or long long parameter.  In particular, [__builtin_]exit() will\n  take an 8-bit value, and avrtest will likely get a trashed 16-bit return\n  value.  The same applies to returning from main.  What works though\n  is to use avrtest_exit() to terminate the program.\n  Also notice that with  -mint8  no 64-bit integer types like long long\n  or uint64_t are available.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsprintersb%2Fatest","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsprintersb%2Fatest","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsprintersb%2Fatest/lists"}