From f582a36e4df16d5709943f7df17a900c8bcc12ab Mon Sep 17 00:00:00 2001 From: Kevin O'Connor Date: Wed, 25 May 2016 11:37:40 -0400 Subject: Initial commit of source code. Signed-off-by: Kevin O'Connor --- docs/Code_Overview.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 docs/Code_Overview.md (limited to 'docs/Code_Overview.md') diff --git a/docs/Code_Overview.md b/docs/Code_Overview.md new file mode 100644 index 00000000..34550e25 --- /dev/null +++ b/docs/Code_Overview.md @@ -0,0 +1,93 @@ +This document describes the overall code layout and major code flow of +Klipper. + +Directory Layout +================ + +The **src/** directory contains the C source for the micro-controller +code. The **src/avr/** directory contains specific code for Atmel +ATmega micro-controllers. The **src/simulator/** contains code stubs +that allow the micro-controller to be test compiled on other +architectures. + +The **klippy/** directory contains the C and Python source for the +host part of the firmware. + +The **config/** directory contains example printer configuration +files. + +The **scripts/** directory contains build-time scripts useful for +compiling the micro-controller code. + +During compilation, the build may create an **out/** directory. This +contains temporary build time objects. The final micro-controller +object that is built is in **out/klipper.elf.hex** + +Micro-controller code flow +========================== + +Execution of the micro-controller code starts in **src/avr/main.c** +which calls sched_main() located in **src/sched.c**. The sched_main() +code starts by running all functions that have been tagged with the +DECL_INIT() macro. It then goes on to repeatedly run all functions +tagged with the DECL_TASK() macro. + +One of the main task functions is command_task() located in +**src/command.c**. This function processes incoming serial commands +and runs the associated command function for them. Command functions +are declared using the DECL_COMMAND() macro. + +Task, init, and command functions always run with interrupts enabled +(however, they can temporarily disable interrupts if needed). These +functions should never pause, delay, or do any work that lasts more +than a few micro-seconds. These functions schedule work at specific +times by scheduling timers. + +Timer functions are scheduled by calling sched_timer() (located in +**src/sched.c**). The scheduler code will arrange for the given +function to be called at the requested clock time. Timer interrupts +are initially handled in an interrupt handler in **src/avr/timer.c**, +but this just calls sched_timer_kick() located in **src/sched.c**. The +timer interrupt leads to execution of schedule timer functions. Timer +functions always run with interrupts disabled. The timer functions +should always complete within a few micro-seconds. At completion of +the timer event, the function may choose to reschedule itself. + +In the event an error is detected the code can invoke shutdown() (a +macro which calls sched_shutdown() located in **src/sched.c**). +Invoking shutdown() causes all functions tagged with the +DECL_SHUTDOWN() macro to be run. Shutdown functions always run with +interrupts disabled. + +Much of the functionality of the micro-controller involves working +with General-Purpose Input/Output pins (GPIO). In order to abstract +the low-level architecture specific code from the high-level task +code, all GPIO events are implemented via wrappers. These wrappers are +located in **src/avr/gpio.c**. The code is compiled with gcc's "-flto +-fwhole-program" optimization which does an excellent job of inlining +functions across compilation units, so most of these tiny gpio +functions are inlined into their callers, and there is no run-time +cost to using them. + +Klippy code overview +==================== + +The host code (Klippy) is intended to run on a low-cost computer (such +as a Raspberry Pi) paired with the micro-controller. The code is +primarily written in Python, however it does use CFFI to implement +some functionality in C code. + +Initial execution starts in **klippy/klippy.py**. This reads the +command-line arguments, opens the printer config file, instantiates +the main printer objects, and starts the serial connection. The main +execution of gcode commands is in the process_commands() method in +**klippy/gcode.py**. This code translates the gcode commands into +printer object calls, which frequently translate the actions to +commands to be executed on the micro-controller (as declared via the +DECL_COMMAND macro in the micro-controller code). + +There are three threads in the Klippy host code. The main thread +handles incoming gcode commands. A second thread (which resides +entirely in the **klippy/serialqueue.c** C code) handles low-level IO +with the serial port. The third thread is used to process response +messages from the micro-controller in the Python code. -- cgit v1.2.3-70-g09d2