blob: f18d878ddd3426277974b699f44e79025a5a5793 [file] [log] [blame]
/*
* Copyright (c) 2017, Texas Instruments Incorporated
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
*
* * Neither the name of Texas Instruments Incorporated nor the names of
* its contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
* OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
* WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
* OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
* EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/** ============================================================================
* @file SwiP.h
*
* @brief Software Interrupt module for the RTOS Porting Interface
*
* ============================================================================
*/
#ifndef ti_dpl_SwiP__include
#define ti_dpl_SwiP__include
#ifdef __cplusplus
extern "C" {
#endif
#include <stdint.h>
/*!
* @brief Number of bytes greater than or equal to the size of any RTOS
* SwiP object.
*
* nortos: 40
* SysBIOS: 52
*/
#define SwiP_STRUCT_SIZE (52)
/*!
* @brief SemaphoreP structure.
*
* Opaque structure that should be large enough to hold any of the
* RTOS specific SwiP objects.
*/
typedef union SwiP_Struct {
uint32_t dummy; /*!< Align object */
char data[SwiP_STRUCT_SIZE];
} SwiP_Struct;
#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>
/*!
* @brief Opaque client reference to an instance of a SwiP
*
* A SwiP_Handle returned from the ::SwiP_create represents that instance.
*/
typedef void *SwiP_Handle;
/*!
* @brief Status codes for SwiP APIs
* TODO: See if we need more error codes.
*/
typedef enum SwiP_Status {
SwiP_OK = 0,
SwiP_FAILURE = -1
} SwiP_Status;
/*!
* @brief Prototype for the entry function for a hardware interrupt
*/
typedef void (*SwiP_Fxn)(uintptr_t arg0, uintptr_t arg1);
/*!
* @brief Basic SwiP Parameters
*
* Structure that contains the parameters passed into ::SwiP_create
* and ::SwiP_construct when creating or constructing a SwiP instance.
* The ::SwiP_Params_init function should be used to initialize the
* fields to default values before the application sets the fields
* manually. The SwiP default parameters are noted in ::SwiP_Params_init.
*
* Each SwiP object has a "trigger" used either to determine whether to
* post the SwiP or as a value that can be evaluated within the SwiP's
* function.
*
* The SwiP_andn and SwiP_dec functions post the SwiP
* if the trigger value transitions to 0. The SwiP_or and
* SwiP_inc functions also modify the trigger value. SwiP_or
* sets bits, and SwiP_andn clears bits.
*/
typedef struct SwiP_Params {
uintptr_t arg0; /*!< Argument passed into the SwiP function. */
uintptr_t arg1; /*!< Argument passed into the SwiP function. */
uint32_t priority; /*!< priority, 0 is min, 1, 2, ..., ~0 for max */
uint32_t trigger; /*!< Initial SwiP trigger value. */
} SwiP_Params;
/*!
* @brief Function to construct a software interrupt object.
*
* @param swiP Pointer to SwiP_Struct object.
* @param swiFxn entry function of the software interrupt
*
* @param params Pointer to the instance configuration parameters. NULL
* denotes to use the default parameters. The SwiP default
* parameters are noted in ::SwiP_Params_init.
*
* @return A SwiP_Handle on success or a NULL on an error
*/
extern SwiP_Handle SwiP_construct(SwiP_Struct *swiP, SwiP_Fxn swiFxn,
SwiP_Params *params);
/*!
* @brief Function to destruct a software interrupt object
*
* @param swiP Pointer to a SwiP_Struct object that was passed to
* SwiP_construct().
*
* @return
*/
extern void SwiP_destruct(SwiP_Struct *swiP);
/*!
* @brief Initialize params structure to default values.
*
* The default parameters are:
* - name: NULL
*
* @param params Pointer to the instance configuration parameters.
*/
extern void SwiP_Params_init(SwiP_Params *params);
/*!
* @brief Function to create a software interrupt object.
*
* @param swiFxn entry function of the software interrupt
*
* @param params Pointer to the instance configuration parameters. NULL
* denotes to use the default parameters. The SwiP default
* parameters are noted in ::SwiP_Params_init.
*
* @return A SwiP_Handle on success or a NULL on an error
*/
extern SwiP_Handle SwiP_create(SwiP_Fxn swiFxn,
SwiP_Params *params);
/*!
* @brief Function to delete a software interrupt object
*
* @param handle returned from the SwiP_create call
*
*/
extern void SwiP_delete(SwiP_Handle handle);
/*!
* @brief Function to disable software interrupts
*
* This function can be called multiple times, but must unwound in the reverse
* order. For example
* @code
* uintptr_t key1, key2;
* key1 = SwiP_disable();
* key2 = SwiP_disable();
* SwiP_restore(key2);
* SwiP_restore(key1);
* @endcode
*
* @return A key that must be passed to SwiP_restore to re-enable interrupts.
*/
extern uintptr_t SwiP_disable(void);
/*!
* @brief Function to get the trigger value of the currently running SwiP.
*
*/
extern uint32_t SwiP_getTrigger();
/*!
* @brief Clear bits in SwiP's trigger. Post SwiP if trigger becomes 0.
*
* @param handle returned from the SwiP_create or SwiP_construct call
* @param mask inverse value to be ANDed
*/
extern void SwiP_andn(SwiP_Handle handle, uint32_t mask);
/*!
* @brief Decrement SwiP's trigger value. Post SwiP if trigger becomes 0.
*
* @param handle returned from the SwiP_create or SwiP_construct call
*/
extern void SwiP_dec(SwiP_Handle handle);
/*!
* @brief Increment the SwiP's trigger value and post the SwiP.
*
* @param handle returned from the SwiP_create or SwiP_construct call
*/
extern void SwiP_inc(SwiP_Handle handle);
/*!
* @brief Or the mask with the SwiP's trigger value and post the SwiP.
*
* @param handle returned from the SwiP_create or SwiP_construct call
* @param mask value to be ORed
*/
extern void SwiP_or(SwiP_Handle handle, uint32_t mask);
/*!
* @brief Unconditionally post a software interrupt.
*
* @param handle returned from the SwiP_create or SwiP_construct call
*/
extern void SwiP_post(SwiP_Handle handle);
/*!
* @brief Function to restore software interrupts
*
* @param key return from SwiP_disable
*/
extern void SwiP_restore(uintptr_t key);
/*!
* @brief Function to set the priority of a software interrupt
*
* @param handle returned from the SwiP_create or SwiP_construct call
* @param priority new priority
*/
extern void SwiP_setPriority(SwiP_Handle handle, uint32_t priority);
#ifdef __cplusplus
}
#endif
#endif /* ti_dpl_SwiP__include */