From a2d986e2944141176eedaee6dc4be87be7eea57b Mon Sep 17 00:00:00 2001 From: RobMeades Date: Fri, 29 Mar 2024 08:46:24 +0000 Subject: [PATCH] Documentation change only: what to do if you don't know what a named pipe is. --- port/README.md | 3 ++- port/api/u_port_named_pipe.h | 12 +++++++++++- 2 files changed, 13 insertions(+), 2 deletions(-) diff --git a/port/README.md b/port/README.md index 2bba8541..b0e2778b 100644 --- a/port/README.md +++ b/port/README.md @@ -24,7 +24,8 @@ If your platform is not currently supported you may be able to port it yourself, - if your platform does not use [newlib](https://sourceware.org/newlib/) (if you are using GCC it will bring [newlib](https://sourceware.org/newlib/) with it) then you may find you are missing some C library functions; implementations of C library functions we have already found to be missing on some platforms can be found in [port/clib](/port/clib) and can just be hooked-in from there but you may need to add more if your code doesn't compile, - if your platform does not offer `malloc()` and `free()`, or you wish to do your own thing with heap memory, you should override the default, weakly-linked, implementations of `pUPortMalloc()` and `uPortFree()` by defining your own implementations of [these functions](/port/api/u_port_heap.h) in a file inside the `src` directory of your port, - if your platform supports setting a time-zone offset you will need to implement `uPortGetTimezoneOffsetSeconds()`; if not then you may simply include the file [port/u_port_timezone.c](/port/u_port_timezone.c) in your build (already included through weak linkage via [ubxlib.cmake](ubxlib.cmake) and [ubxlib.mk](ubxlib.mk)) to get a default timezone offset of zero, - - if your platform has some form of compile-time device configuration mechanism of its own (like the Zephyr Device Tree) then you may wish to implement `uPortBoardCfgDevice()` and `uPortBoardCfgNetwork()` (see [port/api/u_port_board_cfg.h](/port/api/u_port_board_cfg.h)) to accommodate that. + - if your platform has some form of compile-time device configuration mechanism of its own (like the Zephyr Device Tree) then you may wish to implement `uPortBoardCfgDevice()` and `uPortBoardCfgNetwork()` (see [port/api/u_port_board_cfg.h](/port/api/u_port_board_cfg.h)) to accommodate that, + - if you wish to test BLE bonding then you should implement the [named pipe API](api/u_port_named_pipe.h); if not then you may simply include the file [port/u_port_named_pipe.c](/port/u_port_named_pipe.c) in your build (already included through weak linkage via [ubxlib.cmake](ubxlib.cmake) and [ubxlib.mk](ubxlib.mk)) to get a default implementation that returns `U_ERROR_COMMON_NOT_SUPPORTED`. - provide your own versions of the header files `u_cfg_app_platform_specific.h`, `u_cfg_hw_platform_specific.h`, `u_cfg_test_platform_specific.h` and `u_cfg_os_platform_specific.h` (see examples in the existing platform directories); take particular note of translating the task priority values into those of your OS, - provide your own build metadata files (for CMake, Make, a home-grown Python lash-up, whatever): usually your chosen platform will dictate the shape of these and you just need to add to your existing structure the paths to the `ubxlib` source files and the `ubxlib` include files; otherwise take a look at the existing [nrf5 GCC platform](platform/nrf5sdk/mcu/nrf52/gcc/runner) or [static_size](platform/static_size) platforms as a starting point (though note that the latter does not bring in any `platform` or `test` files), - add [Unity](https://github.com/ThrowTheSwitch/Unity) to your build and then compile and run the tests in [u_port_test.c](test/u_port_test.c): if these pass then you have likely completed the necessary porting. diff --git a/port/api/u_port_named_pipe.h b/port/api/u_port_named_pipe.h index fb1c530e..ec24e7ae 100644 --- a/port/api/u_port_named_pipe.h +++ b/port/api/u_port_named_pipe.h @@ -27,7 +27,16 @@ */ /** @file - * @brief Porting layer for named pipes for inter-application communication. + * @brief Porting layer for named pipes for inter-application + * communication. + * + * Note: this API is currently only used while testing BLE bonding, + * it is not used in the core ubxlib code. It is currently only + * implemented on Windows and native Linux platforms. If you are + * creating your own port and do not wish to test BLE bonding you + * do not need to implement it. Where it is not implemented a weak + * implementation in u_port_named_pipe_default.c will take over and + * return #U_ERROR_COMMON_NOT_SUPPORTED. */ #ifdef __cplusplus @@ -51,6 +60,7 @@ typedef void *uPortNamePipeHandle_t; * -------------------------------------------------------------- */ /** Create a named pipe in server or client mode. + * * When in server mode the pipe is created on a system wide basis and * the caller program instance will be the owner of this. * If client mode this function just establishes what reference