From 7085ed2d6c16fa9df3cc7e1271927a898dd872d8 Mon Sep 17 00:00:00 2001 From: Kevin O'Connor Date: Mon, 22 Nov 2021 11:01:39 -0500 Subject: [PATCH] docs: Add low-level MMIO coding hints to Code_Overview.md Signed-off-by: Kevin O'Connor --- docs/Code_Overview.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/docs/Code_Overview.md b/docs/Code_Overview.md index 80322a94..16854073 100644 --- a/docs/Code_Overview.md +++ b/docs/Code_Overview.md @@ -388,8 +388,8 @@ Useful steps: 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 + much easier. It is typical to use a UART type serial device 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 @@ -416,6 +416,20 @@ Useful steps: the micro-controller with the main klippy.py program. 9. Consider adding build test cases in the test/ directory. +Additional coding tips: +1. Avoid using "C bitfields" to access IO registers; prefer direct + read and write operations of 32bit, 16bit, or 8bit integers. The C + language specifications don't clearly specify how the compiler must + implement C bitfields (eg, endianness, and bit layout), and it's + difficult to determine what IO operations will occur on a C + bitfield read or write. +2. Prefer writing explicit values to IO registers instead of using + read-modify-write operations. That is, if updating a field in an IO + register where the other fields have known values, then it is + preferable to explicitly write the full contents of the register. + Explicit writes produce code that is smaller, faster, and easier to + debug. + ## Coordinate Systems Internally, Klipper primarily tracks the position of the toolhead in