{"id":27813946,"url":"https://github.com/stsquad/risu","last_synced_at":"2025-05-01T12:07:18.609Z","repository":{"id":11490228,"uuid":"13963770","full_name":"stsquad/risu","owner":"stsquad","description":"My copy of Pete Maydell's risu code generator/tester (see git://git.linaro.org/people/pmaydell/risu.git)","archived":false,"fork":false,"pushed_at":"2020-06-23T08:24:44.000Z","size":1515,"stargazers_count":3,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-05-01T12:07:11.706Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stsquad.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-10-29T17:51:23.000Z","updated_at":"2022-04-14T01:24:58.000Z","dependencies_parsed_at":"2022-09-22T23:02:10.156Z","dependency_job_id":null,"html_url":"https://github.com/stsquad/risu","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/stsquad%2Frisu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stsquad%2Frisu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stsquad%2Frisu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stsquad%2Frisu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stsquad","download_url":"https://codeload.github.com/stsquad/risu/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251871583,"owners_count":21657473,"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":[],"created_at":"2025-05-01T12:07:17.893Z","updated_at":"2025-05-01T12:07:18.557Z","avatar_url":"https://github.com/stsquad.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"risu -- random instruction sequence generator for userspace testing\n\nrisu is a tool intended to assist in testing the implementation of\nmodels of the ARM architecture such as qemu and valgrind. In particular\nit restricts itself to considering the parts of the architecture\nvisible from Linux userspace, so it can be used to test programs\nwhich only implement userspace, like valgrind and qemu's linux-user\nmode.\n\nrisu is also the Japanese word for squirrel.\n\nBuilding\n--------\n\nrisu comes in two parts -- a perl script 'risugen' for generating\ntest blobs (which can be run anywhere), and a Linux executable\n'risu' which runs on the target architecture (ie ARM). To\nbuild the executable part:\n\n    [VAR=VALUE] ... ./configure [--static]\n    make\n\nwhere [VAR=VALUE] ... allows you to specify any options.\nMost useful is\n CROSS_PREFIX= which specifies the cross compiler prefix; you'll\n   need this if you're not building on the target system\n   (Example: CROSS_PREFIX=arm-linux-gnueabihf- )\n\nPassing --static will build a statically linked binary which is useful\nif you don't want to mess around with a chroot to run the binary.\n\nFor other possibilities run 'configure --help'.\n\nBuilding into a separate build tree from the source code is supported:\n    mkdir my-build-dir\n    cd my-build-dir\n    [VAR=VALUE] ... ../configure\n    make\n\nThe build directory doesn't need to be inside the source tree;\njust run configure from inside it.\n\nFor risu developers: there is a build-all-archs script which\nwill automatically configure and build risu for every CPU\narchitecture that we support and that you have a cross compiler\ninstalled for. This is useful for confirming that your changes\nto risu haven't broken anything.\n\nCoding Style\n------------\n\nrisu follows the same coding style as the QEMU project, namely 4\nspaces (no tabs) for indentation and the One True Brace Style variant\nof K\u0026R. The source tree includes a .dir-locals.el for Emacs users that\nwill set this automatically. Other editors are available.\n\n\nUsage\n-----\n\nThe principle is straightforward: we generate a random sequence of\ninstructions, and run it on both native hardware and the model under\ntest. Register values are cross-checked after every instruction and\nif there is a mismatch then the test fails.\n\nrisugen is a Perl script which generates a binary blob containing\nthe random instructions. It works by reading a configuration file\nwhich specifies instruction patterns to be generated. Command line\noptions can be used to restrict the set of instruction patterns\nused. For example:\n\n  ./risugen --numinsns 10000 --pattern 'VQSHL.*imm.*' arm.risu vqshlimm.out\n\nreads the configuration file arm.risu, and generates 10000 instructions\nbased on the instruction patterns matching the regular expression\n\"VQSHL.*imm.*\". The resulting binary is written to vqshlimm.out.\n\nThis binary can then be passed to the risu program, which is\nwritten in C. You need to run risu on both an ARM native target\nand on the program under test. The ARM native system is the 'master'\nend, so run it like this:\n\n  ./risu --master vqshlimm.out\n\nIt will sit waiting for a TCP connection from the 'apprentice'\nwhich must be run on the program under test. In theory this is\nas simple as:\n\n  risu --host ip-addr-of-master vqshlimm.out\n\nHowever since you actually need to run it under qemu or similar\nyou probably need an ARM chroot to run it in, and to do something\nlike:\n\n  sudo chroot /srv/chroot/arm-mav /risu --host ipaddr vqshlimm.out\n\nIf you built the binary statically you can simply run:\n\n  /path/to/qemu ./risu --host ipaddr vqshlimm.out\n\n\nWhen the apprentice connects to the master, they will both start\nrunning the binary and checking results with each other. When the\ntest ends the master will print a register dump and the match or\nmismatch status to its standard output.\n\nNB that in the register dump the r15 (pc) value will be given\nas an offset from the start of the binary, not an absolute value.\n\nWhile the master/slave setup works well it is a bit fiddly for running\nregression tests and other sorts of automation. For this reason risu\nsupports recording a trace of its execution to a file. For example:\n\n  risu --master FxxV_across_lanes.risu.bin -t FxxV_across_lanes.risu.trace\n\nAnd then playback with:\n\n  risu FxxV_across_lanes.risu.bin -t FxxV_across_lanes.risu.trace\n\nIdeally it should be built with zlib to compress the trace files which\nwould otherwise be huge. If building with zlib proves too tricky you\ncan pipe to stdout and an external compression binary using \"-t -\".\n\n  risu --master FxxV_across_lanes.risu.bin -t - | gzip --best \u003e trace.file\n\nand:\n\n  gunzip -c trace.file | risu -t - FxxV_across_lanes.risu.bin\n\nFile format\n-----------\n\nThe .risu file specifies instruction patterns to be tested.\n\nLines starting with '#' are comments and are ignored.\nBlank lines are ignored. A '\\' at the end of the line is \na line continuation character.\n\nLines starting with a '.' are directives to risu/risugen:\n * \".mode [thumb|arm]\" specifies whether the file contains ARM\n   or Thumb instructions; it must precede all instruction patterns.\n\nOther lines are instruction patterns:\n insnname encodingname bitfield ... [ [ !blockname ] { blocktext } ]\nwhere each bitfield is either:\n  var:sz  specifying a variable field of size sz (sz == 0 if :sz omitted)\n  [01]*   specifying fixed bits\nField names beginning 'r' are special as they are assumed to be general\npurpose registers. They get an automatic \"cannot be 13 or 15\" (sp/pc)\nconstraint.\n\nThe optional blocks at the end of the line are generally named;\nan unnamed block is (for backwards compatibility) treated as one\nnamed \"constraints\". Currently the following named blocks are\naccepted:\n\n * constraints :\n\nThe block is a perl statement to be evaluated and which\nmust return true if the generated statement is OK, false if the\ngenerator should retry with a fresh random number. It is evaluated\nin a context where variables with the same names as the defined\nvariable fields are initialised. The intention is that odd cases\nwhere you need to apply some sort of constraint to the generated\ninstruction can be handled via this mechanism.\nNB that there is no sanity checking that you don't do bad things\nin the eval block, although there is a basic check for syntax\nerrors and and we bail out if the constraint returns failure too often.\n\n * memory :\n\nThe block indicates what memory address the instruction accesses\n(either load or store). It should be a fragment of perl code which\nis a call to a risugen function which implements support for the\naddressing mode used by the instruction. As with the 'constraints'\nblock, the variable field values are provided as Perl variables.\nBy convention, the function always accepts as its last argument(s)\na list of the registers which will be trashed by the function\n(this information is needed to avoid problems handling insns which\nload to their base register.)\nCurrently supported addressing modes:\n reg(reg, trashed);\n reg_plus_imm(reg, immediate, trashed);\n reg_minus_imm(reg, immediate, trashed);\n reg_plus_reg(basereg, indexreg, trashed);\n reg_plus_reg_shifted(basereg, indexreg, shift, trashed);\n    -- this is for [basereg + indexreg LSL shift]\nThe block can also include a call to the align() function\nto indicate the memory alignment required for the access.\nThe default is 4-alignment. The align() call must precede\nthe addressing mode function call.\n\nImplementation details and points to note\n-----------------------------------------\n\nThe register checking is done by registering a signal handler for\nSIGILL, which then has access to register contents via the\nsigcontext argument to the handler. Particular opcodes in the\nguaranteed-to-UNDEF space are then used to say \"check register\nvalues\" and \"end of test\".\n\nThere are some obvious limitations to this approach:\n\n * we assume that all the interesting state is in the registers\naccessible to a signal handler. This is true in most cases but\nwe can't test complex instructions like ldrexd/strexd.\n * the generator is fairly simplistic and just alternates generated\ninstructions and \"check-registers\" commands. So branches and\nloads or stores can't be checked this way. (This is more of a\nrestriction in the generator, not the test harness proper.)\n * we only catch gross errors of decode or implementation of\nan instruction. We won't notice problems like overenthusiastic\nreordering of instructions in the model's code generator, for\nexample.\n * by definition, we can only test user-space visible instructions,\nnot those which are only accessible to privileged code.\n\nSome limits which are more accidental:\n\n * I'm only testing ARM. The generator is rather ARM-specific.\nThe test harness is less so (there's a skeleton of an x86\nimplementation, for example) but only ARM is tested.\n * we don't actually compare FP status flags, simply because\nI'm pretty sure qemu doesn't get them right yet and I'm more\ninterested in fixing gross bugs first.\n * You can compile statically to avoid the requirement for the ARM\nchroot for qemu testing but you can no longer use gethostbyname() and need\nto specify your hosts by IP address.\n * the documentation is rather minimal. This is because I don't\nreally expect many people to need to use this :-)\n\nContributed scripts\n-------------------\n\nThe contrib/ directory contains various contributed scripts\nand other tools that are not necessary to use risu, but\nmight be helpful. See the comments in each script for\nmore information and documentation.\n\n-- Peter Maydell \u003cpeter.maydell@linaro.org\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstsquad%2Frisu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstsquad%2Frisu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstsquad%2Frisu/lists"}