From 9c2919739b4ecadff96799579e7926cbe0c94fe8 Mon Sep 17 00:00:00 2001 From: Michael Buesch Date: Sun, 12 Aug 2018 02:05:21 +0200 Subject: [PATCH] Add development documentation Signed-off-by: Michael Buesch --- COMPATIBILITY.md | 6 ++---- DEVELOPMENT.md | 33 +++++++++++++++++++++++++++++++++ MANIFEST.in | 2 ++ QUICK-START.md | 3 +-- README.md | 40 ++++++++++++++-------------------------- TODO.md | 21 +++++++-------------- 6 files changed, 59 insertions(+), 46 deletions(-) create mode 100644 DEVELOPMENT.md diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index 3b19ca83c..0c83b099a 100644 --- a/COMPATIBILITY.md +++ b/COMPATIBILITY.md @@ -1,5 +1,4 @@ -Awlsim - STEP 7 compatibility -============================= +# Awlsim - STEP 7 compatibility The execution of AWL/STL programs by Awlsim is supposed to be fully compatible with the execution of compiled AWL/STL programs on the real Siemens S7 CPU. However, there currently are some known differences. These are listed below. Any undocumented difference between Awlsim and STEP 7 is considered to be a bug that should be reported. @@ -14,8 +13,7 @@ The execution of AWL/STL programs by Awlsim is supposed to be fully compatible w * Undefined behavior is not emulated. For example: If reading uninitialized L-stack space in STEP 7 always yields a certain reproducible result, that does not mean that this AWL/STL code does the same thing in Awlsim. Reading uninitialized `TEMP`-memory is undefined. -Awlsim extensions -================= +# Awlsim extensions Extensions are features that Awlsim supports, but STEP 7 does not support. diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md new file mode 100644 index 000000000..b74ebc5f7 --- /dev/null +++ b/DEVELOPMENT.md @@ -0,0 +1,33 @@ +# Awlsim development notes + + +## Unit tests + +The unit test suite can be run with the invocation of the command `./tests/run.sh`. This will run all unit tests and show the results. +Please see `./tests/run.sh --help` for more options. + + +### Code coverage tracing + +To run a code statement coverage trace during unit testing the option `./tests/run.sh --coverage` is available. The results will be stored in `./code-coverage-report/`. It is desired to have a reasonable code coverage of the unit tests. All main code paths should be covered. + + +## Special annotations in the source code + +In order to support both compiling the Awlsim core with Cython and running the same code in a plain Python interpreter without compilation, a method to patch the files is required. The setup.py scrips patch each .py source file and create a .pyx file before starting Cython compilation. The Cython patching mechanism rewrites all `import`s to import the compiled Cython modules instead of the plain Python modules. In addition to that some special comments are provided as hint to the Cython patcher: + +* `#@cy` : Enable (un-comment) this line during Cython patching. +* `#@cy2` : Enable (un-comment) this line during Cython patching, if compiling for Python 2. +* `#@cy3` : Enable (un-comment) this line during Cython patching, if compiling for Python 3. +* `#@nocy` : Disable (comment) this line during Cython patching. +* `#@no-cython-patch` : Do not touch this line during cython patching. +* `#+NoneToNULL` : Transform all `None` keywords in this line into `NULL`. +* `#+cimport` : Transform all `import` keywords in this line into `cimport`. +* `#+cdef` : Add a `cdef` to this line. For functions or methods that means to change `def` into `cdef` in the function signature. For classes that means to change `class` to `cdef class`. +* `#+cpdef` : Same as `#+cdef`, but add `cpdef` instead. +* `#+cdef-foobar-bizz` : Same as `#+cdef`, but also add the additional words `foobar bizz` after `cdef`. Arbitrary words may be specified and the number of words is not limited. The dash `-` will be transformed into a space character. + +To disable code coverage tracing an additional special comment is provided: + +* `#@nocov` : This excludes the line from Python `coverage` tracing. + diff --git a/MANIFEST.in b/MANIFEST.in index 0a0038755..18e695e53 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -16,6 +16,8 @@ graft tests include COMPATIBILITY.html include COMPATIBILITY.md include COPYING.txt +include DEVELOPMENT.html +include DEVELOPMENT.md include QUICK-START.html include QUICK-START.md include README.html diff --git a/QUICK-START.md b/QUICK-START.md index fbece7ca7..2a2851a4d 100644 --- a/QUICK-START.md +++ b/QUICK-START.md @@ -1,5 +1,4 @@ -Awlsim - Quick start tutorial -============================= +# Awlsim - Quick start tutorial Start the GUI by invoking `awlsim-gui` on Linux, `awlsim-win.cmd` on Windows or `awlsim.cmd` on Windows (Awlsim standalone package). The following screen will appear: diff --git a/README.md b/README.md index 4f01fb6e8..dda00eecc 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,11 @@ -Awlsim - S7 compatible Programmable Logic Controller (PLC/SPS) -============================================================== +# Awlsim - S7 compatible Programmable Logic Controller (PLC/SPS) Awlsim is a free Step 7 compatible Programmable Logic Controller, that supports the automation languages AWL/STL and FUP/FBD. Awlsim itself is written in Python. The latest version of Awlsim can be downloaded at the [official Awlsim site](https://awlsim.de). -Awlsim - Programmable Logic Controller (PLC/SPS) ------------------------------------------------- +## Awlsim - Programmable Logic Controller (PLC/SPS) Awlsim is a free Step 7 compatible Programmable Logic Controller, that supports the automation languages AWL/STL and FUP/FBD. Awlsim itself is written in Python. The speed of execution ranges from several ten thousand AWL/STL instructions per second on slow embedded machines to a couple of million instructions per second on faster computers. @@ -16,20 +14,17 @@ AWL/STL programs on PLCs are used for automation of industrial processes. Howeve Awlsim can emulate CPUs with two and four accumulator registers (S7-3xx and S7-4xx). Compatibility to S7 hardware is a task taken seriously by the Awlsim project. We want to be as close as possible to the real PLC hardware with our AWL/STL code execution. For this reason Awlsim ships an extensive selftest suite. Missing features and differences between Awlsim and Step 7 are documented in the [COMPATIBILITY documentation](COMPATIBILITY.html) and [TODO documentation](TODO.html) files. -Quick start tutorial --------------------- +## Quick start tutorial See the [quick start tutorial](QUICK-START.html) for a simple example on how to use Awlsim in simulator mode. In simulator mode Awlsim can be run on any desktop PC. No special hardware is required. -Example project ---------------- +## Example project If you don't know where to start, you can find an example project in the `examples` directory as `EXAMPLE.awlpro`. You can easily run this example in simulation mode without the need for special hardware. -Git repository --------------- +## Git repository The latest development version of Awlsim can be fetched with git: @@ -45,8 +40,7 @@ After cloning the main repository the git submodules must also be fetched. The f -Dependencies ------------- +## Dependencies Awlsim depends on [Python](https://python.org) 3.4 or later or alternatively Python 2.7. @@ -68,8 +62,7 @@ pip3 install --upgrade Cython -Directory structure -------------------- +## Directory structure The Awlsim Git repository and source archive `awlsim-x.yz.tar.bz2` contain lots of files and directories. Here is an overview of the main files and directories and their purpose: @@ -95,6 +88,7 @@ These files and directories contain useful information about Awlsim. examples/ : Various example projects and feature demonstrations. COMPATIBILITY.md|html : S7 compatibility documentation. COPYING.txt : Main license. + DEVELOPMENT.md|html : How to enhance and develop Awlsim. QUICK-START.md|html : Quick start tutorial. README.md|html : Main README document. TODO.md|html : TODO list. @@ -150,14 +144,12 @@ The hardware modules are the glue between the Awlsim core and the real world. Th -FUP - Funktionsplan - Function block diagram --------------------------------------------- +## FUP - Funktionsplan - Function block diagram Awlsim supports programming in an S7-FUP like language. See [the FUP documentation](doc/fup/FUP.html) for more information about Awlsim's implementation of FUP. -Building Awlsim ---------------- +## Building Awlsim Awlsim can be run from the source directory in interpreted Python mode without building it. Just `cd` into the Awlsim source directory and execute the desired main executable (e.g. `./awlsim-gui` or `./awlsim-server` etc...). @@ -168,8 +160,7 @@ For convenience there also is a helper script `./maintenance/build.sh`, which wi There also is `./maintenance/build-noopt.sh`. That builds Cython modules without optimization. The build is much faster, but the resulting Cython libraries will be much slower. This is useful for development. Do not use this for production. -Building Debian / Raspbian / PiLC .deb packages ------------------------------------------------ +## Building Debian / Raspbian / PiLC .deb packages Installing or upgrading Awlsim on a Debian based system is easy. The `debuild` can be used to build the .deb packages. Just run the following commands to build all Awlsim .deb packages: @@ -192,15 +183,12 @@ this can be fixed by re-installing the libc development package: `sudo apt install --reinstall libc-dev` -Unit tests ----------- +## Development -The unit test suite can be run with the invocation of the command `./tests/run.sh`. This will run all unit tests and show the results. -Please see `./tests/run.sh --help` for more options. +Information about Awlsim development can be found in [the Awlsim development documentation](DEVELOPMENT.html). -License / Copyright -------------------- +## License / Copyright Copyright (C) Michael Büsch / et al. diff --git a/TODO.md b/TODO.md index 5d21f7bae..5d33d72b3 100644 --- a/TODO.md +++ b/TODO.md @@ -1,42 +1,35 @@ -Incomplete awlsim TODO list -=========================== +# Incomplete awlsim TODO list -S7 compatibility ----------------- +## S7 compatibility * Add feature: Parsing of attributes -core ----- +## core * Improve performance (cython) * Blocks that are no longer linked to (created by) sources should be removed. * Single download of symtab causes a redefinition error. * Add feature: LAD (KOP) compiler -AWL / STL optimizer -------------------- +## AWL / STL optimizer * Add optimization pass: O(UU)O(UU) -> UUOUU * Add optimization pass: U(UU)= -> UU= (also for other insn types) * Add optimization pass: Reordering of TEMP variables for space packing -GUI ---- +## GUI * Add feature: Save window status (open MDI windows, positions, etc) * Add feature: Show UDTs in block tree * Add feature: LAD (KOP) editor -FBD/FUP GUI only ----------------- +## FBD/FUP GUI only * Add feature: Exchange elements * Add feature: Live view of signal states (online diagnosis) * Add feature: Support modifying wires by clicking onto them -FBD/FUP compiler and GUI ------------------------- +## FBD/FUP compiler and GUI * Fix evaluation order in case of multiple parallel assignments and other elements * Add feature: Add option to disable elements