From 7d835d59fd4f5c2e08186e7ec013f65bb0d6c78f Mon Sep 17 00:00:00 2001 From: Archit Aggarwal Date: Thu, 22 Jul 2021 16:51:03 -0700 Subject: [PATCH] Add code examples in doxygen manual (#42) Major Changes This PR makes the major update of adding code examples for coreSNTP library APIs in doxygen documentation. This is done by providing an example POSIX application of using the library to setup an SNTP client, and adding references to the relevant parts of the example file in the doxygen documentation of APIs. This PR also adds a mechanism to validate build of the POSIX example application through a CI check. Minor Changes Fixes in doxygen documentation Re-purpose size_table.html for public visibility in README.md --- .github/workflows/ci.yml | 17 +- README.md | 4 +- .../code_examples/example_sntp_client_posix.c | 265 ++++++++++++++++++ docs/doxygen/config.doxyfile | 7 +- .../{size_table.html => size_table.md} | 0 docs/doxygen/pages.dox | 37 ++- docs/doxygen/porting.dox | 43 ++- lexicon.txt | 1 + source/include/core_sntp_client.h | 7 +- test/CMakeLists.txt | 56 ++-- test/unit-test/core_sntp_config.h | 2 + 11 files changed, 386 insertions(+), 53 deletions(-) create mode 100644 docs/doxygen/code_examples/example_sntp_client_posix.c rename docs/doxygen/include/{size_table.html => size_table.md} (100%) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1b69e44..15febc0 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -16,7 +16,6 @@ jobs: cmake -S test -B build/ \ -G "Unix Makefiles" \ -DCMAKE_BUILD_TYPE=Debug \ - -DBUILD_CLONE_SUBMODULES=ON \ -DCMAKE_C_FLAGS='-O0 -Wall -Wextra -Werror -Wformat -Wformat-security -Warray-bounds' make -C build/ coverity_analysis -j8 - name: Build Library in Release mode @@ -24,9 +23,17 @@ jobs: rm -rf ./build cmake -S test -B build/ -G "Unix Makefiles" \ -DCMAKE_BUILD_TYPE=Release \ - -DBUILD_CLONE_SUBMODULES=ON \ -DCMAKE_C_FLAGS='-Wall -Wextra -Werror -DNDEBUG -Wformat -Wformat-security -Warray-bounds' make -C build/ coverity_analysis -j8 + build-code-example: + runs-on: ubuntu-latest + steps: + - name: Clone This Repo + uses: actions/checkout@v2 + - name: Build Code Example used in Doxygen + run: | + cmake -S test -B Build -DBUILD_CODE_EXAMPLE=ON + make -C Build code_example_posix -j8 unittest-with-sanitizer: runs-on: ubuntu-latest steps: @@ -48,7 +55,7 @@ jobs: cmake -S test -B build/ \ -G "Unix Makefiles" \ -DCMAKE_BUILD_TYPE=Debug \ - -DBUILD_CLONE_SUBMODULES=ON \ + -DBUILD_UNIT_TESTS=ON \ -DCMAKE_C_FLAGS="${CFLAGS}" make -C build all -j8 - name: Run unit tests with sanitizer @@ -68,7 +75,7 @@ jobs: cmake -S test -B build/ \ -G "Unix Makefiles" \ -DCMAKE_BUILD_TYPE=Debug \ - -DBUILD_CLONE_SUBMODULES=ON \ + -DBUILD_UNIT_TESTS=ON \ -DCMAKE_C_FLAGS='--coverage -Wall -Wextra -Werror -DNDEBUG -Wno-error=pedantic -Wno-variadic-macros -DLOGGING_LEVEL_DEBUG=1' make -C build/ all - name: Test @@ -164,4 +171,4 @@ jobs: uses: FreeRTOS/CI-CD-Github-Actions/memory_statistics@main with: config: .github/memory_statistics_config.json - check_against: docs/doxygen/include/size_table.html + check_against: docs/doxygen/include/size_table.md diff --git a/README.md b/README.md index 4148248..1246072 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ An SNTP client can request time from both NTP and SNTP servers. According to the This library has gone through code quality checks including verification that no function has a [GNU Complexity](https://www.gnu.org/software/complexity/manual/complexity.html) score over 8, and checks against deviations from mandatory rules in the [MISRA coding standard](https://www.misra.org.uk). Deviations from the MISRA C:2012 guidelines are documented under [MISRA Deviations](MISRA.md). This library has also undergone both static code analysis from [Coverity static analysis](https://scan.coverity.com/), and validation of memory safety through the [CBMC automated reasoning tool](https://www.cprover.org/cbmc/). +See memory requirements for this library [here](./docs/doxygen/include/size_table.md). + ## Cloning this repository This repo uses [Git Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) to bring in dependent components. @@ -57,7 +59,7 @@ git submodule update --checkout --init --recursive test/unit-test/CMock 1. Go to the root directory of this repository. (Make sure that the **CMock** submodule is cloned as described [above](#checkout-cmock-submodule)) -1. Run the *cmake* command: `cmake -S test -B build` +1. Run the *cmake* command: `cmake -S test -B build -DBUILD_UNIT_TESTS=ON` 1. Run this command to build the library and unit tests: `make -C build all` diff --git a/docs/doxygen/code_examples/example_sntp_client_posix.c b/docs/doxygen/code_examples/example_sntp_client_posix.c new file mode 100644 index 0000000..ce8ff1a --- /dev/null +++ b/docs/doxygen/code_examples/example_sntp_client_posix.c @@ -0,0 +1,265 @@ +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include "core_sntp_client.h" + +/* @[code_example_sntpdnsresolve] */ +/* Example POSIX implementation of SntpDnsReolve_t interface. */ +static bool resolveDns( const SntpServerInfo_t * pServerAddr, + uint32_t * pIpV4Addr ) +{ + bool status = false; + int32_t dnsStatus = -1; + struct addrinfo hints; + struct addrinfo * pListHead = NULL; + + hints.ai_family = AF_UNSPEC; + + hints.ai_socktype = ( int32_t ) SOCK_STREAM; + hints.ai_protocol = IPPROTO_TCP; + + dnsStatus = getaddrinfo( pServerAddr->pServerName, NULL, &hints, &pListHead ); + + if( dnsStatus == 0 ) + { + struct sockaddr_in * pAddrInfo = ( struct sockaddr_in * ) pListHead->ai_addr; + inet_ntop( pAddrInfo->sin_family, + &pAddrInfo->sin_addr, + ( int8_t * ) pIpV4Addr, + INET_ADDRSTRLEN ); + + status = true; + } + + freeaddrinfo( pListHead ); + + return status; +} +/* @[code_example_sntpdnsresolve] */ + +/* @[code_example_networkcontext] */ +/* Example definition of NetworkContext_t for UDP socket operations. */ +struct NetworkContext +{ + int udpSocket; +}; +/* @[code_example_networkcontext] */ + +/* @[code_example_udptransport_sendto] */ +/* Example POSIX implementation of the UdpTransportSendTo_t function of UDP transport interface. */ +static int32_t UdpTransport_Send( NetworkContext_t * pNetworkContext, + uint32_t serverAddr, + uint16_t serverPort, + const void * pBuffer, + uint16_t bytesToSend ) +{ + int32_t bytesSent = -1, pollStatus = 1; + struct pollfd pollFds; + + pollFds.events = POLLOUT | POLLPRI; + pollFds.revents = 0; + pollFds.fd = pNetworkContext->udpSocket; + + /* Check if there is data to read from the socket. */ + pollStatus = poll( &pollFds, 1, 0 ); + + if( pollStatus > 0 ) + { + struct sockaddr_in addrInfo; + addrInfo.sin_family = AF_INET; + addrInfo.sin_port = htons( serverPort ); + addrInfo.sin_addr.s_addr = htonl( serverAddr ); + + bytesSent = sendto( pNetworkContext->udpSocket, + pBuffer, + bytesToSend, 0, + ( const struct sockaddr * ) &addrInfo, + sizeof( addrInfo ) ); + } + else if( pollStatus == 0 ) + { + bytesSent = 0; + } + + return bytesSent; +} +/* @[code_example_udptransport_sendto] */ + +/* @[code_example_udptransport_recvfrom] */ +/* Example POSIX implementation of the UdpTransportRecvFrom_t function of UDP transport interface. */ +static int32_t UdpTransport_Recv( NetworkContext_t * pNetworkContext, + uint32_t serverAddr, + uint16_t serverPort, + void * pBuffer, + uint16_t bytesToRecv ) +{ + int32_t bytesReceived = -1, pollStatus = 1; + struct pollfd pollFds; + + pollFds.events = POLLIN | POLLPRI; + pollFds.revents = 0; + pollFds.fd = pNetworkContext->udpSocket; + + /* Check if there is data to read from the socket. */ + pollStatus = poll( &pollFds, 1, 0 ); + + if( pollStatus > 0 ) + { + struct sockaddr_in addrInfo; + addrInfo.sin_family = AF_INET; + addrInfo.sin_port = htons( serverPort ); + addrInfo.sin_addr.s_addr = htonl( serverAddr ); + socklen_t addrLen = sizeof( addrInfo ); + + bytesReceived = recvfrom( pNetworkContext->udpSocket, pBuffer, + bytesToRecv, 0, + ( struct sockaddr * ) &addrInfo, + &addrLen ); + } + else if( pollStatus == 0 ) + { + bytesReceived = 0; + } + + return bytesReceived; +} +/* @[code_example_udptransport_recvfrom] */ + +/* @[code_example_sntpsettime] */ +/* Example implementation of the SntpSetTime_t interface for POSIX platforms. */ +static void sntpClient_SetTime( const SntpServerInfo_t * pTimeServer, + const SntpTimestamp_t * pServerTime, + int64_t clockOffsetMs, + SntpLeapSecondInfo_t leapSecondInfo ) +{ + /* @[code_example_sntp_converttounixtime] */ + uint32_t unixSecs; + uint32_t unixMs; + SntpStatus_t status = Sntp_ConvertToUnixTime( pServerTime, &unixSecs, &unixMs ); + + /* @[code_example_sntp_converttounixtime] */ + assert( status == SntpSuccess ); + + struct timespec serverTime = + { + .tv_sec = unixSecs, + .tv_nsec = unixMs * 1000 + }; + + clock_settime( CLOCK_REALTIME, &serverTime ); +} +/* @[code_example_sntpsettime] */ + +/* @[code_example_sntpgettime] */ +/* Example implementation of the SntpGetTime_t interface for POSIX platforms. */ +static void sntpClient_GetTime( SntpTimestamp_t * pCurrentTime ) +{ + struct timespec currTime; + + ( void ) clock_gettime( CLOCK_REALTIME, &currTime ); + + pCurrentTime->seconds = currTime.tv_sec; + pCurrentTime->fractions = ( currTime.tv_sec / 1000 ) * SNTP_FRACTION_VALUE_PER_MICROSECOND; +} +/* @[code_example_sntpgettime] */ + +/* Configuration constants for the example SNTP client. */ +#define TEST_TIME_SERVER_1 "0.pool.ntp.org" +#define TEST_TIME_SERVER_2 "1.pool.ntp.org" + +#define SERVER_RESPONSE_TIMEOUT_MS 3000 +#define TIME_REQUEST_SEND_WAIT_TIME_MS 2000 +#define TIME_REQUEST_RECEIVE_WAIT_TIME_MS 1000 + +#define SYSTEM_CLOCK_FREQUENCY_TOLERANCE_PPM 500 +#define SYSTEM_CLOCK_DESIRED_ACCURACY_MS 300 + +int main( void ) +{ + /* @[code_example_sntp_init] */ + /* Memory for network buffer. */ + uint8_t networkBuffer[ SNTP_PACKET_BASE_SIZE ]; + + /* Create UDP socket. */ + NetworkContext_t udpContext; + + udpContext.udpSocket = socket( AF_INET, SOCK_DGRAM, 0 ); + + /* Setup list of time servers. */ + SntpServerInfo_t pTimeServers[] = + { + { + .port = SNTP_DEFAULT_SERVER_PORT, + .pServerName = TEST_TIME_SERVER_1, + .serverNameLen = strlen( TEST_TIME_SERVER_1 ) + }, + { + .port = SNTP_DEFAULT_SERVER_PORT, + .pServerName = TEST_TIME_SERVER_2, + .serverNameLen = strlen( TEST_TIME_SERVER_2 ) + } + }; + + /* Set the UDP transport interface object. */ + UdpTransportInterface_t udpTransportIntf; + udpTransportIntf.pUserContext = &udpContext; + udpTransportIntf.sendTo = UdpTransport_Send; + udpTransportIntf.recvFrom = UdpTransport_Recv; + + /* Context variable. */ + SntpContext_t context; + + /* Initialize context. */ + SntpStatus_t status = Sntp_Init( &context, + pTimeServers, + sizeof( pTimeServers ) / sizeof( SntpServerInfo_t ), + SERVER_RESPONSE_TIMEOUT_MS, + networkBuffer, + SNTP_PACKET_BASE_SIZE, + resolveDns, + sntpClient_GetTime, + sntpClient_SetTime, + &udpTransportIntf, + NULL ); + assert( status == SntpSuccess ); + /* @[code_example_sntp_init] */ + + /* Calculate the polling interval period for the SNTP client. */ + /* @[code_example_sntp_calculatepollinterval] */ + uint32_t pollingIntervalPeriod; + status = Sntp_CalculatePollInterval( SYSTEM_CLOCK_FREQUENCY_TOLERANCE_PPM, + SYSTEM_CLOCK_DESIRED_ACCURACY_MS, + &pollingIntervalPeriod ); + /* @[code_example_sntp_calculatepollinterval] */ + assert( status == SntpSuccess ); + + /* Loop of SNTP client for period time synchronization. */ + /* @[code_example_sntp_send_receive] */ + while( 1 ) + { + status = Sntp_SendTimeRequest( &context, + rand() % UINT32_MAX, + TIME_REQUEST_SEND_WAIT_TIME_MS ); + assert( status == SntpSuccess ); + + do + { + status = Sntp_ReceiveTimeResponse( &context, TIME_REQUEST_RECEIVE_WAIT_TIME_MS ); + } while( status == SntpNoResponseReceived ); + + assert( status == SntpSuccess ); + + /* Delay of poll interval period before next time synchronization. */ + sleep( pollingIntervalPeriod ); + } + + /* @[code_example_sntp_send_receive] */ + + return EXIT_SUCCESS; +} diff --git a/docs/doxygen/config.doxyfile b/docs/doxygen/config.doxyfile index 90ec875..c5b0c95 100644 --- a/docs/doxygen/config.doxyfile +++ b/docs/doxygen/config.doxyfile @@ -798,14 +798,17 @@ EXCLUDE_SYMLINKS = NO # that contain example code fragments that are included (see the \include # command). -EXAMPLE_PATH = source/include docs/doxygen/include +EXAMPLE_PATH = source/include \ + docs/doxygen/include \ + docs/doxygen/code_examples \ + test/unit-test # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and # *.h) to filter out the source-files in the directories. If left blank all # files are included. -EXAMPLE_PATTERNS = * +EXAMPLE_PATTERNS = *c # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be # searched for input files to be used with the \include or \dontinclude commands diff --git a/docs/doxygen/include/size_table.html b/docs/doxygen/include/size_table.md similarity index 100% rename from docs/doxygen/include/size_table.html rename to docs/doxygen/include/size_table.md diff --git a/docs/doxygen/pages.dox b/docs/doxygen/pages.dox index ce3b638..2f5ed0f 100644 --- a/docs/doxygen/pages.dox +++ b/docs/doxygen/pages.dox @@ -21,7 +21,7 @@ This library is optimized for resource constrained embedded devices. Features of @section sntp_memory_requirements Memory Requirements @brief Memory requirements of the coreSNTP library. -@include{doc} size_table.html +@include{doc} size_table.md @section sntp_design Design @brief coreSNTP Library Design @@ -45,7 +45,7 @@ As visible in the above architecture diagram, the Managed Client API laye - [UDP Transport Interface](@ref UdpTransportInterface_t) - This allows library to send and receive SNTP packets over network UDP layer to communicate with SNTP/NTP servers. - [Get Time Interface](@ref SntpGetTime_t) - This allows library to obtain system time for tracking timeouts as well as creating SNTP time requests. - [Set Time Interface](@ref SntpSetTime_t) - This allows library to notify application about updating system time with the latest time provided by server as well as the system clock drift calculated by library. -- (Authentication Interface)[@ref SntpAuthenticationInterface_t] (Optional) - This allows library to perform mutual authentication in communicating with time servers for security. It is RECOMMENDED that applications enable authentication when communicating with time servers. +- [Authentication Interface](@ref SntpAuthenticationInterface_t) (Optional) - This allows library to perform mutual authentication in communicating with time servers for security. It is RECOMMENDED that applications enable authentication when communicating with time servers.

*/ @@ -89,29 +89,50 @@ All the configurations settings for the coreSNTP library are function-like macro @snippet core_sntp_client.h define_sntp_init @copydoc Sntp_Init +For an example POSIX application of using the coreSNTP library APIs to create an SNTP client, refer to @ref code_example. +Below is the part of the code example relevant to the @ref Sntp_Init API. +@snippet example_sntp_client_posix.c code_example_sntp_init + @page sntp_sendtimerequest_function Sntp_SendTimeRequest -@snippet core_sntp_client.h define_sntp_sendtimerequest @copydoc Sntp_SendTimeRequest +For an example POSIX application of using the coreSNTP library APIs to create an SNTP client, refer to @ref code_example. +Below is the part of the code example relevant to the @ref Sntp_ReceiveTimeResponse API. +@snippet example_sntp_client_posix.c code_example_sntp_send_receive + @page sntp_receivetimeresponse_function Sntp_ReceiveTimeResponse -@snippet core_sntp_client.h define_sntp_receivetimeresponse @copydoc Sntp_ReceiveTimeResponse +For an example POSIX application of the coreSNTP library APIs to create an SNTP client, refer to @ref code_example. +Below is the part of the example application relevant to the @ref Sntp_ReceiveTimeResponse API. +@snippet example_sntp_client_posix.c code_example_sntp_send_receive + @page sntp_serializerequest_function Sntp_SerializeRequest -@snippet core_sntp_serializer.h define_sntp_serializerequest @copydoc Sntp_SerializeRequest @page sntp_deserializeresponse_function Sntp_DeserializeResponse -@snippet core_sntp_serializer.h define_sntp_deserializeresponse @copydoc Sntp_DeserializeResponse @page sntp_calculatepollinterval_function Sntp_CalculatePollInterval -@snippet core_sntp_serializer.h define_sntp_calculatepollinterval @copydoc Sntp_CalculatePollInterval +Here is a code example of using the API. +@snippet example_sntp_client_posix.c code_example_sntp_calculatepollinterval + @page sntp_converttounixtime_function Sntp_ConvertToUnixTime -@snippet core_sntp_serializer.h define_sntp_converttounixtime @copydoc Sntp_ConvertToUnixTime + +Here is a code example of using the API. +@snippet example_sntp_client_posix.c code_example_sntp_converttounixtime +*/ + +/** +@page code_example Example application of using coreSNTP APIs +@brief Example application of setting up an SNTP client with coreSNTP Library on POSIX platforms. + +This code ONLY showcases how coreSNTP library APIs can be used. For best practices on running an SNTP client, +refer to the [FreeRTOS Demo on GitHub](https://github.com/FreeRTOS/FreeRTOS/tree/main/FreeRTOS-Plus/Demo/coreSNTP_Windows_Simulator).
+@include example_sntp_client_posix.c */ diff --git a/docs/doxygen/porting.dox b/docs/doxygen/porting.dox index 473751c..7ee33c5 100644 --- a/docs/doxygen/porting.dox +++ b/docs/doxygen/porting.dox @@ -3,9 +3,12 @@ @brief Guide for porting coreSNTP library to a new platform. A port of coreSNTP library for a new platform must provide the following components: -1. [Configuration Macros](@ref sntp_porting_config) -2. [Transport Interface](@ref sntp_porting_transport) -3. [Time Function](@ref sntp_porting_time) +1. [Logging Configuration Macros](@ref sntp_porting_config) +2. [DNS Resolve Function](@ref sntp_porting_dnsresolve) +3. [UDP Transport Interface](@ref sntp_porting_transport) +4. [Get Time Function](@ref sntp_porting_gettime) +5. [Set Time Function](@ref sntp_porting_settime) +6. [Authentication Interface](@ref sntp_porting_authentication) @section sntp_porting_config Configuration Macros for Logging @brief Macros for enabling logging that can be defined through the config header `core_sntp_config.h`, or passed in as compiler options. @@ -20,6 +23,21 @@ The following logging macros are used throughout the library: - @ref LogInfo - @ref LogDebug +Here is an example implementation of logging macros for POSIX platforms +@snippet core_sntp_config.h code_example_loggingmacros + +@section sntp_porting_dnsresolve DNS Resolve Function +@brief The coreSNTP library requires a DNS Resolve interface that must be implemented to obtain the latest IPv4 +address information of a time server before sending it a time request. + +@see [DNS Resolve Function](@ref SntpResolveDns_t) + +@note The coreSNTP library will re-resolve the DNS name of a time server on each attempt of requesting time from it. +For efficiency of DNS resolution operations, your implementation can utilize DNS caching of resolved domains if +your platform supports it. + +@snippet example_sntp_client_posix.c code_example_sntpdnsresolve + @section sntp_porting_transport UDP Transport Interface @brief The coreSNTP library requires a UDP transport interface that must be implemented in order to send and receive SNTP packets over the network. @@ -33,18 +51,18 @@ duration of an SNTP request-response iteration as opposed to keeping it always o A port must implement functions corresponding to the following functions pointers: - [UDP Transport Send](@ref UdpTransportSendTo_t): A function to send bytes on the network over UDP. It is RECOMMENDED to implement this function as non-blocking so the total block time can be managed by the @ref Sntp_SendTimeRequest API. +@snippet example_sntp_client_posix.c code_example_udptransport_sendto + - [UDP Transport Receive](@ref UdpTransportRecvFrom_t): A function to receive bytes from the network over UDP. It is RECOMMENDED to implement this function as non-blocking so the total block time can be managed by the @ref Sntp_ReceiveTimeResponse API. +@snippet example_sntp_client_posix.c code_example_udptransport_recvfrom + The above two functions take in a pointer to a @ref NetworkContext_t, the typename of a `struct NetworkContext`. The NetworkContext struct must also be defined by the port, and ought to contain any information necessary to send and receive data with the @ref UdpTransportSendTo_t and @ref UdpTransportRecvFrom_t implementations, respectively: -@code -// Example definition of NetworkContext -struct NetworkContext { - // Fields necessary for the transport implementations, e.g. a UDP socket descriptor. -}; -@endcode + +@snippet example_sntp_client_posix.c code_example_networkcontext @section sntp_porting_gettime Get Time Function @brief The coreSNTP library uses this function to obtain time from system for tracking timeout @@ -57,16 +75,20 @@ acceptable for this function to provide the system-time that does not match the time information is received from a time server, the system time can be corrected to match the real-world time. Refer to the next section on how to correct the system time. +@snippet example_sntp_client_posix.c code_example_sntpgettime + @section sntp_porting_settime Set Time Function @brief The coreSNTP library calls this function to notify the device about the latest time received from a time server as well as the clock drift of the system time from the server time. +@snippet example_sntp_client_posix.c code_example_sntpsettime + @see @ref SntpSetTime_t Platforms should implement this function to perform clock disciple operation on the system clock, that is appropriate for the clock accuracy needs of the application. -@section sntp_porting_time Authentication Interface +@section sntp_porting_authentication Authentication Interface @brief The coreSNTP library exposes an authentication interface to allow customer-chosen authentication mechanism to be used in SNTP communication with time server(s) for security. @@ -75,6 +97,7 @@ that modify or spoof server responses. The SNTPv4 protocol is flexible to be use cryptographic algorithm depending on the support provided by time servers of your choice. For an example of using AES-128-CMAC as the authentication algorithm, please refer to [coreSNTP demo in FreeRTOS/FreeRTOS repository](https://github.com/FreeRTOS/FreeRTOS/tree/main/FreeRTOS-Plus/Demo/coreSNTP_Windows_Simulator). + @see @ref SntpAuthenticationInterface_t A port that uses authentication to communicate with time server must implement the following function pointers: - [Add client authentication code](@ref SntpGenerateAuthCode_t): A function to generate and append authentication data for client to be validated diff --git a/lexicon.txt b/lexicon.txt index 21fea79..fa88666 100644 --- a/lexicon.txt +++ b/lexicon.txt @@ -96,6 +96,7 @@ loginfo logwarn lsb mainpage +md mdash misra mtu diff --git a/source/include/core_sntp_client.h b/source/include/core_sntp_client.h index 929e1ae..dc49f2c 100644 --- a/source/include/core_sntp_client.h +++ b/source/include/core_sntp_client.h @@ -621,14 +621,13 @@ SntpStatus_t Sntp_SendTimeRequest( SntpContext_t * pContext, * - #SntpErrorNetworkFailure if there is a failure in the user-defined transport * - #SntpErrorAuthFailure if an internal error occurs in the user-defined * authentication interface when validating the server response. - * receive interface in receiving server response from the network. * - #SntpServerNotAuthenticated when the server could not be authenticated from * its response with the user-defined authentication interface. - * - #SntpInvalidResponse if the server response fails sanity checks expected in an + * - #SntpInvalidResponse if the server response fails sanity checks expected in an * SNTP response packet. - * - #SntpErrorResponseTimeout if a timeout has occurred in receiving response from + * - #SntpErrorResponseTimeout if a timeout has occurred in receiving response from * the server. - * - #SntpRejectedResponse if the server responded with a rejection for the time + * - #SntpRejectedResponse if the server responded with a rejection for the time * request. */ /* @[define_sntp_receivetimeresponse] */ diff --git a/test/CMakeLists.txt b/test/CMakeLists.txt index bc2bb92..e8da13b 100644 --- a/test/CMakeLists.txt +++ b/test/CMakeLists.txt @@ -1,6 +1,5 @@ cmake_minimum_required( VERSION 3.13.0 ) project( "coreSNTP unit test" - VERSION 1.0.0 LANGUAGES C ) # Allow the project to be organized into folders. @@ -48,36 +47,47 @@ target_include_directories( coverity_analysis # Build SNTP library target without custom config dependency. target_compile_definitions( coverity_analysis PUBLIC SNTP_DO_NOT_USE_CUSTOM_CONFIG=1 ) +# ==================================== Code Example Build ==================================== + +if(${BUILD_CODE_EXAMPLE}) + # Target for Coverity analysis that builds the library. + add_executable( code_example_posix + ${MODULE_ROOT_DIR}/docs/doxygen/code_examples/example_sntp_client_posix.c ) + + # Add coreSNTP library public include path. + target_link_libraries( code_example_posix + coverity_analysis ) + +endif() + # ==================================== Unit Test Configuration ==================================== -# Include CMock build configuration. -include( unit-test/cmock_build.cmake ) - -# Check if the CMock source directory exists, and if not present, clone the submodule -# if BUILD_CLONE_SUBMODULES configuration is enabled. -if( NOT EXISTS ${CMOCK_DIR}/src ) - # Attempt to clone CMock. - if( ${BUILD_CLONE_SUBMODULES} ) - clone_cmock() - else() - message( FATAL_ERROR "The required submodule CMock does not exist. Either clone it manually, or set BUILD_CLONE_SUBMODULES to 1 to automatically clone it during build." ) +if(${BUILD_UNIT_TESTS}) + # Include CMock build configuration. + include( unit-test/cmock_build.cmake ) + + # Check if the CMock source directory exists, and if not present, clone the submodule + # if BUILD_CLONE_SUBMODULES configuration is enabled. + if( NOT EXISTS ${CMOCK_DIR}/src ) + # Attempt to clone CMock. + clone_cmock() endif() -endif() -# Add unit test and coverage configuration. + # Add unit test and coverage configuration. -# Use CTest utility for managing test runs. This has to be added BEFORE -# defining test targets with add_test() -enable_testing() + # Use CTest utility for managing test runs. This has to be added BEFORE + # defining test targets with add_test() + enable_testing() -# Add build targets for CMock, required for unit testing. -add_cmock_targets() + # Add build targets for CMock, required for unit testing. + add_cmock_targets() -# Add function to enable CMock/Unity based tests and coverage. -include( ${MODULE_ROOT_DIR}/tools/cmock/create_test.cmake ) + # Add function to enable CMock/Unity based tests and coverage. + include( ${MODULE_ROOT_DIR}/tools/cmock/create_test.cmake ) -# Include build configuration for unit tests. -add_subdirectory( unit-test ) + # Include build configuration for unit tests. + add_subdirectory( unit-test ) +endif() # ==================================== Coverage Analysis configuration ============================ diff --git a/test/unit-test/core_sntp_config.h b/test/unit-test/core_sntp_config.h index 8e6c46f..ab9a451 100644 --- a/test/unit-test/core_sntp_config.h +++ b/test/unit-test/core_sntp_config.h @@ -30,6 +30,7 @@ /* Standard include. */ #include +/* @[code_example_loggingmacros] */ /************* Define Logging Macros using printf function ***********/ #define PrintfError( ... ) printf( "Error: "__VA_ARGS__ ); printf( "\n" ) @@ -54,5 +55,6 @@ #endif /* ifdef LOGGING_LEVEL_ERROR */ /**************************************************/ +/* @[code_example_loggingmacros] */ #endif /* ifndef CORE_SNTP_CONFIG_H_ */