From cb374cd909e6bf0d630b42726ccb246ca1ea44e3 Mon Sep 17 00:00:00 2001 From: Joseph Hickey Date: Thu, 15 Apr 2021 23:37:48 -0400 Subject: [PATCH] Fix #832, improve scriptability of shared layer APIs To imporove scriptability of generating the shared layer stubs, makes two minor adjustments: - adds a typedef for the callback in OS_ObjectIdIteratorProcessEntry. This avoids the complex syntax of function pointer argument, which is hard to read but also harder to parse in a script, too. - Splits the "os-shared-printf.h" header into two parts, adding a new header file "os-shared-console.h". This is because OS_ConsoleOutput_Impl is implemented in a separate unit in the source, and this allows a better relationship between stub files and header files. --- src/os/shared/inc/os-shared-console.h | 94 +++++++++++++++++++++++++++ src/os/shared/inc/os-shared-idmap.h | 9 ++- src/os/shared/inc/os-shared-printf.h | 57 +--------------- 3 files changed, 103 insertions(+), 57 deletions(-) create mode 100644 src/os/shared/inc/os-shared-console.h diff --git a/src/os/shared/inc/os-shared-console.h b/src/os/shared/inc/os-shared-console.h new file mode 100644 index 000000000..b13762844 --- /dev/null +++ b/src/os/shared/inc/os-shared-console.h @@ -0,0 +1,94 @@ +/* + * NASA Docket No. GSC-18,370-1, and identified as "Operating System Abstraction Layer" + * + * Copyright (c) 2019 United States Government as represented by + * the Administrator of the National Aeronautics and Space Administration. + * All Rights Reserved. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +/** + * \file + * + * \ingroup shared + * + * Table implementation and calls related to the console buffer. + * + * This is a simple ring buffer that decouples + * the OS_printf() call from actual console output. + * + * The implementation layer may optionally spawn a + * "utility task" or equivalent to forward data, or + * it may process data immediately. + */ + +#ifndef OS_SHARED_CONSOLE_H +#define OS_SHARED_CONSOLE_H + +#include "osapi-printf.h" +#include "os-shared-printf.h" +#include "os-shared-globaldefs.h" + +/** + * The generic console data record + */ +typedef struct +{ + char device_name[OS_MAX_API_NAME]; + + char * BufBase; /**< Start of the buffer memory */ + size_t BufSize; /**< Total size of the buffer */ + volatile size_t ReadPos; /**< Offset of next byte to read */ + volatile size_t WritePos; /**< Offset of next byte to write */ + uint32 OverflowEvents; /**< Number of lines dropped due to overflow */ + +} OS_console_internal_record_t; + +extern OS_console_internal_record_t OS_console_table[OS_MAX_CONSOLES]; + +/**************************************************************************************** + CONSOLE / DEBUG API LOW-LEVEL IMPLEMENTATION FUNCTIONS + ****************************************************************************************/ + +/*--------------------------------------------------------------------------------------- + Name: OS_ConsoleAPI_Init + + Purpose: Initialize the OS-independent layer for console service + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ +int32 OS_ConsoleAPI_Init(void); + +/*---------------------------------------------------------------- + Function: OS_ConsoleCreate_Impl + + Purpose: Prepare a console device for use + For Async devices, this sets up the background writer task + ------------------------------------------------------------------*/ +int32 OS_ConsoleCreate_Impl(const OS_object_token_t *token); + +/*---------------------------------------------------------------- + Function: OS_ConsoleWakeup_Impl + + Purpose: Console output data notification + + This is a notification API that is invoked whenever there + is new data available in the console output buffer. + + It is only used of the console is configured for async operation, + and it should wakeup the actual console servicing thread. + ------------------------------------------------------------------*/ +void OS_ConsoleWakeup_Impl(const OS_object_token_t *token); + +#endif /* OS_SHARED_CONSOLE_H */ diff --git a/src/os/shared/inc/os-shared-idmap.h b/src/os/shared/inc/os-shared-idmap.h index 111d4e8ff..0e86a4cda 100644 --- a/src/os/shared/inc/os-shared-idmap.h +++ b/src/os/shared/inc/os-shared-idmap.h @@ -103,6 +103,13 @@ struct OS_object_token */ typedef bool (*OS_ObjectMatchFunc_t)(void *ref, const OS_object_token_t *token, const OS_common_record_t *obj); +/* + * A function to serve as callback with object ID iterators + * + * This is the prototype of callback functions for use with OS_ObjectIdIteratorProcessEntry() + */ +typedef int32 (*OS_ObjectIdIteratorProcessFunc_t)(osal_id_t, void *); + /* * State object associated with an object iterator */ @@ -533,7 +540,7 @@ static inline const OS_object_token_t *OS_ObjectIdIteratorRef(OS_object_iter_t * Returns: None ------------------------------------------------------------------*/ -int32 OS_ObjectIdIteratorProcessEntry(OS_object_iter_t *iter, int32 (*func)(osal_id_t, void *)); +int32 OS_ObjectIdIteratorProcessEntry(OS_object_iter_t *iter, OS_ObjectIdIteratorProcessFunc_t func); /* * Internal helper functions diff --git a/src/os/shared/inc/os-shared-printf.h b/src/os/shared/inc/os-shared-printf.h index b1cce4fcc..a54e80d43 100644 --- a/src/os/shared/inc/os-shared-printf.h +++ b/src/os/shared/inc/os-shared-printf.h @@ -29,53 +29,13 @@ #define OS_SHARED_PRINTF_H #include "osapi-printf.h" +#include "os-shared-console.h" #include "os-shared-globaldefs.h" -/* - * Variables related to the console buffer. - * This is a simple ring buffer that decouples - * the OS_printf() call from actual console output. - * - * The implementation layer may optionally spawn a - * "utility task" or equivalent to forward data, or - * it may process data immediately. - */ - -typedef struct -{ - char device_name[OS_MAX_API_NAME]; - - char * BufBase; /**< Start of the buffer memory */ - size_t BufSize; /**< Total size of the buffer */ - volatile size_t ReadPos; /**< Offset of next byte to read */ - volatile size_t WritePos; /**< Offset of next byte to write */ - uint32 OverflowEvents; /**< Number of lines dropped due to overflow */ - -} OS_console_internal_record_t; - -extern OS_console_internal_record_t OS_console_table[OS_MAX_CONSOLES]; - /**************************************************************************************** CONSOLE / DEBUG API LOW-LEVEL IMPLEMENTATION FUNCTIONS ****************************************************************************************/ -/*--------------------------------------------------------------------------------------- - Name: OS_ConsoleAPI_Init - - Purpose: Initialize the OS-independent layer for console service - - returns: OS_SUCCESS on success, or relevant error code ----------------------------------------------------------------------------------------*/ -int32 OS_ConsoleAPI_Init(void); - -/*---------------------------------------------------------------- - Function: OS_ConsoleCreate_Impl - - Purpose: Prepare a console device for use - For Async devices, this sets up the background writer task - ------------------------------------------------------------------*/ -int32 OS_ConsoleCreate_Impl(const OS_object_token_t *token); - /*---------------------------------------------------------------- Function: OS_ConsoleOutput_Impl @@ -88,19 +48,4 @@ int32 OS_ConsoleCreate_Impl(const OS_object_token_t *token); ------------------------------------------------------------------*/ void OS_ConsoleOutput_Impl(const OS_object_token_t *token); -/*---------------------------------------------------------------- - Function: OS_ConsoleOutput_Impl - - Purpose: Console output data notification - - This is a notification API that is invoked whenever there - is new data available in the console output buffer. - - For a synchronous console service, this may call - OS_ConsoleWrite_Impl() directly. For an async console - service, this should wakeup the actual console servicing - thread. - ------------------------------------------------------------------*/ -void OS_ConsoleWakeup_Impl(const OS_object_token_t *token); - #endif /* OS_SHARED_PRINTF_H */