new port questions

[holla2040]

I've been following grblHAL's progress for a couple years. I'm thinking about starting a port for a Teknic ClearCore controller, https://www.teknic.com/products/io-motion-controller/, which uses an M4 SAM E53.

The terjeio/grblHAL readme states "You can even add your own driver if you feel so inclined." This template link is down https://github.com/terjeio/grblHAL/blob/master/templates/arm-driver

The HAL dev ref in the wiki, https://github.com/terjeio/grblHAL/wiki/Hardware-Abstraction-Layer-(HAL)----developer-reference is 18 months old. Is a newer one planned? or is this still current.

I understand the pending grblHAL move is in progress and the ports are in various stages of development...

1. Which port follows the directory/file structure that you want to see with all new ports?
2. Is there a template to follow?
3. Is the HAL Dev Ref page, dated 2019, close to current code revision level?
4. Have you benchmarked grblHAL's performance when the core runs in a FreeRTOS task?
5. Do you see any advantage to using FreeRTOS for some more complex designs requiring CPU
   to multitask with other non-grbl related tasks?

Thanks for your time.

[terjeio]

The terjeio/grblHAL readme states "You can even add your own driver if you feel so inclined." This template link is down
I have updated the readme in this repo to point to the correct location.

The HAL dev ref in the wiki, https://github.com/terjeio/grblHAL/wiki/Hardware-Abstraction-Layer-(HAL)----developer-reference is 18 months old. Is a newer one planned? or is this still current.

It is not current and should be updated.

Which port follows the directory/file structure that you want to see with all new ports?

The directory structure depends on the target compiler/IDE requirements, file naming consistent with other drivers. At least a my_machine.h for driver configuration and driver.c/driver.h for the main driver code. I like to keep communication code and eeprom/flash settings storage code in separate files. If multiple boards are supported they should have their own pin mapping files and, if needed, support code.

Is there a template to follow?

Yes and no - the provided template is for a basic driver, check out (or use) actual drivers for ideas. Driver complexity may differ a lot, if for a single board/single configuration it can be relatively simple - if support for many is required it may get complicated.

Is the HAL Dev Ref page, dated 2019, close to current code revision level?

No - there has been a lot of additions since then. But the architecture is basically the same with heavy use of function pointers to glue everything together.

Have you benchmarked grblHAL's performance when the core runs in a FreeRTOS task?

No, but I do not think it should suffer much as critical parts of the code is run from interrupts. I have a STM32F756 Nucleo-144 board that I intend to write a driver for, this will run the core as a FreeRTOS task and have networking support including the http protocol for running the ESP32 WebUI. When I get around to write this then benchmarking it could be a good idea.

Do you see any advantage to using FreeRTOS for some more complex designs requiring CPU to multitask with other non-grbl related tasks?

Adding networking protocols is likely easier when using a RTOS. Other than that I am not too keen to burden the processor with other tasks such as keeping an UI updated. It is better to offload such tasks to a second processor? But then a complex design may not require processor capacity that will impact interrupt latency and thus step rate/jitter in a way that affects the target application...

[holla2040]

Thanks for answering these questions. I'll start working on a port after I decide upon which IDE/dev environment to support. Learning towards the Arduino supplied toolchain. I've migrated my embedded development to running in docker containers. Grabbed your email address, got that too.

[holla2040]

My Teknic ClearCore port is coming along. I have the stream and nvs storage implemented. Any progress on the HAL document? Thanks.

[terjeio]

Any progress on the HAL document?

Only in my head this far - I have set myself up for a rather large task depending on how I scope it. Recently I have expanded on the auxillary I/O support and simplified pin mapping for ABC-motors including remapping to ganged/squared axes. When this is completed (some testing remains) I really should start writing documentation...

Combined with the fact that user code can be "hooked" into the both the HAL and parts of the core means it is possible to view the whole as a kind of operating system that can be drawn upon by user code. So I have to decide on how to approach the documentation, aim it only on driver developers or developers generally that may also use an exisiting driver and add their own code (plugin)? What do you think?

[terjeio]

I have generated raw documentation for the core, you can find it here for now.

This is the HAL bit.

[holla2040]

Its getting late here after a long day. I'll look at this in the morning.

I will answer your question about who is the target audience for docs. I suspect more developers will want to use grblHAL for port modifications and customization. This group will be larger and most likely generate more issues if the documentation doesn't help them.

The port developer, like myself, have a general grbl internal knowledge and just need to understand what the callbacks need to accomplish and how this will be used by the core.

I'm really tired, going to shutdown now.

[holla2040]

Your raw documentation is a good start. Using doxygen is also good because its understandable source is embedded in the code, to read there as well. I'll brush up on doxygen usage and add it to my port as well.

[holla2040]

For C code, does enabling doxygen's call graph generate call tree diagrams? https://youtu.be/5G1zUpNFmEY?t=3617

[terjeio]

Could well be as I believe have seen those in documentation of C code elsewhere. How that would work with the HAL function pointers I do not know. To be investigated later.

Mind you today is my first encounter with this tool so I am very much in a learning phase. I have pushed updates every few minutes to see how my added details show up...

BTW is there any part of the documentation you want me to expand on first?

[holla2040]

For me personally as a port developer, I'd like the HAL callback functions into the driver documented.

[holla2040]

As for my doxygen knowledge, I probably know less than you.

[terjeio]

For me personally as a port developer, I'd like the HAL callback functions into the driver documented.

For me calls from the core into the the driver are not callbacks, calls from the driver back to the core are.

An example might be the limits API that is nearly completed.

Is my way of thinking and language use way off? I am not a native english speaker...

[holla2040]

OK, I'm thinking the opposite for callbacks. Since the core is the main execution loop, the driver in driver_init sets up the core's function pointers to callback to the driver for additional information/execution.

For example,
hal.stream.read = serialGetC;

my port implements serialGetC which is called by the core, so its a callback. This is my understanding of the term 'callback'.

[holla2040]

https://www.geeksforgeeks.org/callbacks-in-c/

[terjeio]

my port implements serialGetC which is called by the core, so its a callback. This is my understanding of the term 'callback'.

My understanding is the opposite, a callback is typically something that happens asynchronously e.g. a call to a interrupt handler. Most callbacks in grblHAL is in fact triggered by interrupts, however some are used to enumerate data the core do not have access to directly. For example the enumerate_pins handler uses a callback for getting the enumerated data without building a large data structure to hold it.

When a call is isued and a result is returned immediately it is not a callback, even if it is over a function pointer.

So IMO this statement from the link above is plainly wrong:

In C, a callback function is a function that is called through a function pointer.

The function pointers into the driver could have been plain static calls, but at the cost of losing the freedom to switch functionality at run time. Passing the calls over a function pointer does not magically change them into callbacks.

[holla2040]

I can see your point. Ultimately, the interaction between the core and driver is accomplished via function pointers, which is quite normal for C. Let's just move onto to more important work. Thanks for the discussion. Please close this issue.

[terjeio]

Ok, then I guess should just continue adding documentation from the top down in the hal.h file for now. Some of it will take me around into other files so it will take some time. If anything is not clear please shout out.