From f60b0093b7a225f9f93323098f5a9e2120b55b41 Mon Sep 17 00:00:00 2001 From: Kevin O'Connor Date: Wed, 11 Jul 2018 14:35:28 -0400 Subject: [PATCH] docs: Add a section with micro-controller porting tips to Code_Overview.md Signed-off-by: Kevin O'Connor --- docs/Code_Overview.md | 53 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/docs/Code_Overview.md b/docs/Code_Overview.md index af68b27b..bcf50ab5 100644 --- a/docs/Code_Overview.md +++ b/docs/Code_Overview.md @@ -334,6 +334,59 @@ Useful steps: to micro-controller commands. This is useful to exercise corner cases and to check for regressions. +Porting to a new micro-controller +================================= + +This section provides some tips on porting Klipper's micro-controller +code to a new architecture. This type of activity requires good +knowledge of embedded development and hands-on access to the target +micro-controller. + +Useful steps: +1. Start by identifying any 3rd party libraries that will be used + during the port. Common examples include "CMSIS" wrappers and + manufacturer "HAL" libraries. All 3rd party code needs to be GNU + GPLv3 compatible. The 3rd party code should be committed to the + Klipper lib/ directory. Update the lib/README file with information + on where and when the library was obtained. It is preferable to + copy the code into the Klipper repository unchanged, but if any + changes are required then those changes should be listed explicitly + in the lib/README file. +2. Create a new architecture sub-directory in the src/ directory and + add initial Kconfig and Makefile support. Use the existing + architectures as a guide. The src/simulator provides a basic + example of a minimum starting point. +3. The first main coding task is to bring up communication support to + the target board. This is the most difficult step in a new port. + Once basic communication is working, the remaining steps tend to be + much easier. It is typical to use an RS-232 style serial port + during initial development as these types of hardware devices are + generally easier to enable and control. During this phase, make + liberal use of helper code from the src/generic/ directory (check + how src/simulator/Makefile includes the generic C code into the + build). It is also necessary to define timer_read_time() (which + returns the current system clock) in this phase, but it is not + necessary to fully support timer irq handling. +4. Get familiar with the the console.py tool (as described in the + [debugging document](Debugging.md)) and verify connectivity to the + micro-controller with it. This tool translates the low-level + micro-controller communication protocol to a human readable form. +5. Add support for timer dispatch from hardware interrupts. See + Klipper + [commit 970831ee](https://github.com/KevinOConnor/klipper/commit/970831ee0d3b91897196e92270d98b2a3067427f) + as an example of steps 1-5 done for the LPC176x architecture. +6. Bring up basic GPIO input and output support. See Klipper + [commit c78b9076](https://github.com/KevinOConnor/klipper/commit/c78b90767f19c9e8510c3155b89fb7ad64ca3c54) + as an example of this. +7. Bring up additional peripherals - for example see Klipper commit + [65613aed](https://github.com/KevinOConnor/klipper/commit/65613aeddfb9ef86905cb1dade9e773a02ef3c27), + [c812a40a](https://github.com/KevinOConnor/klipper/commit/c812a40a3782415e454b04bf7bd2158a6f0ec8b5), + and + [c381d03a](https://github.com/KevinOConnor/klipper/commit/c381d03aad5c3ee761169b7c7bced519cc14da29). +8. Create a sample Klipper config file in the config/ directory. Test + the micro-controller with the main klippy.py program. +9. Consider adding build test cases in the test/ directory. + Time ====