Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
portability-refactor [2017/01/25 15:45]
arthur
portability-refactor [2017/01/25 18:35]
arthur
Line 1: Line 1:
 == Portability refactor Documentation == Portability refactor Documentation
 +
 +The purpose of this document is to outline the current problems with Smoothie'​s portability,​
 +propose a solution and guide the implementation.
 +
 +== The problem
 +Though Smoothie is based on mBed, it is not easily ported to other boards / processors.
 +
 +For various reasons, suchs as conceptual mismatch between needed and actually functionality ​
 +by mBed, not everything Smoothie does can use mBed.
 +
 +This simple fact means that some porting work will alway be necessary - but we could reduce the effort needed
 +by centralizing the chip specific functions in a - Smoothie specific - hardware abstraction layer (HAL).
 +
 +== Proposed solution
 +# Refactor everything LPC17xx specific into a new folder structure /​hal/​LPC17xx.
 +# Check everything whether it can be replaced if we were using a newer version of mBed. If so, update and refactor to use these mBed libs.
 +# Finally, prove that porting is possible by actually doing it. 
 +
 +Please note that no. 1 is basically run time neutral (given a sufficiently smart compiler).
 +Step 3 would be a good time to add even very detailed comments to the LPC HAL guiding further ports.
 +
 +== Details
 +
 +The affected subsystems are
 +* GPIO
 +* Timers / Tickers
 +* SPI
 +* Watchdog
 +* Ethernet (refactor, possibly the port can leave it out for the time being)
 +* USB
 +* Makefile system (at least for the final porting step)
 +
 +There is a surprisingly small number of files that contain '​LPC'​.
 +Here's what FF proposes to do abouth them
 +* <​kbd>​libs/​ADC/​adc.cpp</​kbd>​ -> ?
 +> adc.cpp is a special ADC library for mBed that does burst mode, where the normal mBed lib does not. it should be moved to the HAL --arthur
 +* <​kbd>​./​libs/​FPointer.h</​kbd>​ -> just a comment about data sizes -> Replace with ARM c3
 +> Jim says, should use std::​function --arthur
 +>> The only place FPointer is used is in Hook.cpp - it derives a class adding interval and countdown. Could be combined? --Flo
 +* <​kbd>​./​libs/​Kernel.cpp</​kbd>​ -> Timer init -> move to HAL
 +* <​kbd>​./​libs/​MRI_Hooks.cpp</​kbd>​ -> debug interface -> Ports will need to include their own hardware specific debug interface (e.g. ST-Link)
 +* <​kbd>​./​libs/​Network/​uip/​Network.cpp</​kbd>​ -> Ethernet is LPC specific. -> move to HAL
 +* <​kbd>​./​libs/​Network/​uip/​Network.h</​kbd>​ -> move to HAL
 +* <​kbd>​./​libs/​Pin.h</​kbd>​ -> GPIO -> separate into abstract base and hardware specific implementation,​ move the later to HAL. Possibly a good mBed candidate.
 +> Pin is very very time-critical and should not use mBed ( also, we need not to use any additional ram ), so this should just move to the HAL --arthur
 +* <​kbd>​./​libs/​RingBuffer.h</​kbd>​ -> Not sure why the header is included here -> remove.
 +* <​kbd>​./​libs/​SlowTicker.h</​kbd>​ -> __disable_irq / __enable_irq -> replace with macro from HAL
 +> That's common to all Cortex-M, so it shouldn'​t go in a HAL --arthur
 +* <​kbd>​./​libs/​StepTicker.cpp</​kbd>​ ->​Tickers -> move HAL
 +* <​kbd>​./​libs/​USBDevice/​DFU.cpp</​kbd>​ -> move to HAL
 +* <​kbd>​./​libs/​USBDevice/​USB.cpp</​kbd>​ -> comment only -> still move the complete USBDevice to HAL
 +* <​kbd>​./​libs/​USBDevice/​USBDevice/​USBEndpoints.h</​kbd>​ -> Same.
 + * <​kbd>​./​libs/​USBDevice/​USBSerial/​CircBuffer.h</​kbd>​ -> irq enable/​disable -> see <​kbd>​SlowTicker.h</​kbd>​
 +> Same remark --arthur
 +* <​kbd>​./​libs/​gpio.cpp</​kbd>​ -> Again not sure why the header'​s included here -> move HAL. First candidate for mBed.
 +* <​kbd>​./​libs/​spi_hal.h</​kbd>​ -> A non Mbed HAL -> move to HAL
 +* <​kbd>​./​libs/​utils.cpp</​kbd>​ -> Watchdog timer setup. -> move to HAL.
 +* <​kbd>​./​main.cpp</​kbd>​ -> There are some memory section directives in here. -> Move USB init to HAL (AHBSRAM0 directives),​ not sure about AHB0 object
 +> « That can't move », «they can be handled in the linker directoves for different chips» says Jim --arthur
 +* <​kbd>​./​makefile</​kbd>​ -> my suggestion would be to provide a makefile (in subfolders) per target board.
 +> no change to the makefile system should be made. a new makefile can be made in a separate branch when a port is actually started --arthur
 +* <​kbd>​./​modules/​tools/​spindle/​Spindle.cpp</​kbd>​ -> IRQ priority setting. -> HAL function.
 +* <​kbd>​./​modules/​utils/​simpleshell/​SimpleShell.cpp</​kbd>​ -> Debug statement what cpu's being used. -> new HAL function.
 +
 +
 +== Open Questions
 +* What's the difference between the clasess in GPIO and Pin? Pin is used just about everywhere, GPIO only in Step/​SlowTicker.cpp - once to apperantly toggle some Leds, once to optionally toggle a debug pin. Any reason not to replace these two instances with Pin and remove GPIO? --Flo