comment on serial.h

pabigot wrote on Sunday, June 10, 2012:

I’m implementing the interface defined in Demo/Common/include/serial.h.  I also see hints in things like FreeRTOS-Plus and other forum posts that a refactoring of FreeRTOS may be underway.  If that’s so, please consider:

* Adding documentation to interface declarations so ports know what the function is supposed to do.  For example, various ports appear to have chosen to have the return values of xSerialGetChar and xSerialPutChar be either pdFAIL or pdPASS, although the return type would support just about anything, and my initial assumption is it would be like putchar(3).

* Consistently using either xPort or pxPort as the parameter name for the xComPortHandle.  I think the pxPort uses are inconsistent with the coding standard, since the value is an instance of the type even though what the type hides is the fact that it’s a pointer to something which might be a structure.  But I suppose that’s a grey area.


rtel wrote on Sunday, June 10, 2012:

The code in FreeRTOS/Demo is not part of the FreeRTOS kernel code, and is provided as a working starting point only.  Where the code is common to lots of demos for lots of ports it is documented, where the code is non-portable, for UARTs etc, there is less documentation.  Things like FreeRTOS+IO is official code, and *extensively* documented.

Note that the UART drivers found in FreeRTOS/Demo are *not* intended to be examples of efficient implementations.  They are primarily designed almost with the opposite intention of stress testing a port and the FreeRTOS implementation by generating as many interrupts as possible by passing single characters through queue and causing lots of context switches.  The example transfer modes in FreeRTOS+IO are much better - and DMA best of all (but that does not test much outside of the hardware).

Yes - there is some inconsistency in the naming - apologies for that.  Most if not all the core kernel code should not suffer from that.  The inconsistency arises from a knowledge of the underlying implementation, where really pointers are passed around - but the names should be used form the point of view of somebody who is just using an API without knowledge of its inner workings.


pabigot wrote on Monday, June 11, 2012:

Thanks.  I’m really looking to re-use existing standard interfaces for common capabilities rather than create my own.  When will FreeRTOS+IO be released independently of the LPC1769 demo?  Will there be a repository for it and other parts of FreeRTOS-Products that can be mirrored and maintained locally as with FreeRTOS itself?  Or does that exist and I’m not finding it?

rtel wrote on Monday, June 11, 2012:

The FreeRTOS+IO code is a bit like the main FreeRTOS code in that a lot of it is generic, and some specific to a port.  The port layer if fatter than for the FreeRTOS code though as it deals with individual peripherals, not just the core.

The code will make it into the repository at some point, but I would not like to say exactly when.  I think there is already a link to the download on the FreeRTOS+IO demo project page - but you might be right in that the download also includes the NXP port layer.


pabigot wrote on Monday, June 11, 2012:

Yes; I had downloaded that, but it appeared to be a work-in-progress since that demo package was the recommended location to obtain the code.  FreeRTOS+CLI was in the repository and got pulled out, and I figured that other components of FreeRTOS-Products would similarly be separated out.  If that was the case, my preference was to try to locate existing interfaces to implement, but on the whole serial.h does not meet my needs so I’m looking for alternatives.

Do you feel that the interface in FreeRTOS_DriverInterface.h is essentially final?  If not, I can start another thread with some comments on it.  E.g., the use of character strings to identify devices is perhaps too expensive for lower-end MSP430 devices.  If the names of available devices are meant to encode the Peripheral_Type_t and an instance number, it’d be better to pass those as integers.  (And why is it eSSP_TYPE when the example pcPath is /SPI2/?  And why do the example paths end with what appears to be a directory separator–will names be used to identify device components or capabilities at some point, e.g. /UART0/TXBUF?  Questions start arising very quickly.)

rtel wrote on Monday, June 11, 2012:

The interface will get extended, but the use of strings to identify the devices is not going to change because it follows the POSIX convention (although not 100% the POSIX standard, as the FreeRTOS+IO implementation is leaner).  If you use const strings then they should remain in flash.

On the LPC, the SSP port is used for SPI communications. 


pabigot wrote on Monday, June 11, 2012:

OK.  Since most MCUs are not LPCs, it would have been less confusing to me if the generic peripheral type were eSPI_TYPE, and the spelling of the path were /SSP on the LPC’s instances of those devices.

Sure the strings go in flash.  Still, if an MCU has four UARTS named /UART0 through /UART3, that’s two instances (device table and open command parameter) of four device strings of six characters each taking up 48 bytes of flash unless the linker detects and merges string constants.  Hard to justify on an 16 kB MCU.

davedoors wrote on Monday, June 11, 2012:

I think the names of the devices are not part of the IO core code, but the board support package, so you could call them whatever you like. That would save a few bytes (“u1”, “u2”, etc.)