From db3548dfd81b6056ba9f0524b26e809ce7ea6845 Mon Sep 17 00:00:00 2001 From: ReservedField Date: Mon, 24 Oct 2016 21:07:22 +0200 Subject: [PATCH] Add ISR-safety notes to the documentation --- include/Atomizer.h | 2 +- include/Dataflash.h | 12 ++++++------ include/Display.h | 21 +++++++++++---------- include/Display_SSD.h | 2 +- include/Display_SSD1306.h | 2 +- include/Display_SSD1327.h | 2 +- include/Thread.h | 28 ++++++++++------------------ include/TimerUtils.h | 2 +- include/USB_VirtualCOM.h | 4 ++-- src/thread/Thread.c | 4 ++-- 10 files changed, 36 insertions(+), 43 deletions(-) diff --git a/include/Atomizer.h b/include/Atomizer.h index 39f1c13..02ce2f5 100755 --- a/include/Atomizer.h +++ b/include/Atomizer.h @@ -193,7 +193,7 @@ uint8_t Atomizer_IsOn(); Atomizer_Error_t Atomizer_GetError(); /** - * Reads the atomizer info. + * Reads the atomizer info (not ISR-safe). * This may power up the atomizer for resistance measuring, * depending on the situation. Refresh rate is internally * limited, so you can call this as often as you like. diff --git a/include/Dataflash.h b/include/Dataflash.h index 4697d12..416e397 100644 --- a/include/Dataflash.h +++ b/include/Dataflash.h @@ -57,7 +57,7 @@ void Dataflash_Init(); /** * Gets a list of magic numbers for structures present - * int the dataflash. + * in the dataflash (not ISR-safe). * * @param magicList An array at least DATAFLASH_STRUCT_MAX_COUNT * elements big to receive the magic numbers. @@ -67,7 +67,7 @@ void Dataflash_Init(); uint8_t Dataflash_GetMagicList(uint32_t *magicList); /** - * Reads a structure from the dataflash. + * Reads a structure from the dataflash (not ISR-safe). * * @param structInfo Structure info. * @param dst Pointer to structure to be filled. @@ -77,7 +77,7 @@ uint8_t Dataflash_GetMagicList(uint32_t *magicList); uint8_t Dataflash_ReadStruct(const Dataflash_StructInfo_t *structInfo, void *dst); /** - * Selects the set of dataflash structures to be used from now on. + * Selects the set of dataflash structures to be used from now on (not ISR-safe). * This can only be called once (further calls will be ignored) and must * have been called prior to performing updates (they'll fail otherwise). * NOTE: GCC and Clang went big-hammer on multiple-indirection const casts, @@ -92,7 +92,7 @@ uint8_t Dataflash_ReadStruct(const Dataflash_StructInfo_t *structInfo, void *dst uint8_t Dataflash_SelectStructSet(Dataflash_StructInfo_t **structInfo, uint8_t count); /** - * Updates/writes a structure in the dataflash. + * Updates/writes a structure in the dataflash (not ISR-safe). * The dataflash structure set must have already been selected, or * this will fail. * The update operation is a read-compare-write, i.e. it won't waste flash @@ -107,7 +107,7 @@ uint8_t Dataflash_SelectStructSet(Dataflash_StructInfo_t **structInfo, uint8_t c uint8_t Dataflash_UpdateStruct(const Dataflash_StructInfo_t *structInfo, void *src); /** - * Invalidates a structure in the dataflash. + * Invalidates a structure in the dataflash (not ISR-safe). * This doesn't actually erase the structure, but marks it in a * way such that it won't be read by the dataflash routines. * NOTE: This is provided for development/debugging only. You should @@ -123,7 +123,7 @@ uint8_t Dataflash_UpdateStruct(const Dataflash_StructInfo_t *structInfo, void *s uint8_t Dataflash_InvalidateStruct(const Dataflash_StructInfo_t *structInfo); /** - * Erases the whole dataflash. + * Erases the whole dataflash (not ISR-safe). * This actually erases all the flash memory belonging to dataflash. * NOTE: This is provided for development/debugging only. Do NOT use this * in production code. The right way to restore defaults is to push an diff --git a/include/Display.h b/include/Display.h index 37a9281..697543a 100644 --- a/include/Display.h +++ b/include/Display.h @@ -91,7 +91,7 @@ void Display_Init(); Display_Type_t Display_GetType(); /** - * Turns the display on or off. + * Turns the display on or off (not ISR-safe). * This only acts on the pixels, the display will * still be powered. If you want to control the supply * rails, use Display_SSD_SetPowerOn(). @@ -101,7 +101,7 @@ Display_Type_t Display_GetType(); void Display_SetOn(uint8_t isOn); /** - * Powers the display on or off. + * Powers the display on or off (not ISR-safe). * This turns the actual supply rails on/off, cutting * off all current draw from the display when off. It is * slower than Display_SSD_SetOn(). @@ -118,29 +118,30 @@ void Display_SetPowerOn(uint8_t isPowerOn); bool Display_IsFlipped(); /** - * Flips the display. + * Flips the display (not ISR-safe). */ void Display_Flip(); /** - * Sets whether the display colors are inverted. + * Sets whether the display colors are inverted (not ISR-safe). * * @param invert True for inverted display, false for normal display. */ void Display_SetInverted(bool invert); /** - * Sends the framebuffer to the controller and updates the display. + * Sends the framebuffer to the controller and updates the display + * (not ISR-safe). */ void Display_Update(); /** - * Clears the framebuffer. + * Clears the framebuffer (not ISR-safe). */ void Display_Clear(); /** - * Copies a bitmap into the framebuffer. + * Copies a bitmap into the framebuffer (not ISR-safe). * * @param x X coordinate to place the bitmap at. * @param y Y coordinate to place the bitmap at. @@ -151,7 +152,7 @@ void Display_Clear(); void Display_PutPixels(int x, int y, const uint8_t *bitmap, int w, int h); /** - * Draws a line into the framebuffer. + * Draws a line into the framebuffer (not ISR-safe). * * @param startX X coordinate to start the line at. * @param startY Y coordinate to start the line at. @@ -161,7 +162,7 @@ void Display_PutPixels(int x, int y, const uint8_t *bitmap, int w, int h); void Display_PutLine(int startX, int startY, int endX, int endY); /** - * Blits text into the framebuffer. + * Blits text into the framebuffer (not ISR-safe). * * @param x X coordinate to place the text at. * @param y Y coordinato to place the text at. @@ -181,7 +182,7 @@ void Display_PutText(int x, int y, const char *txt, const Font_Info_t *font); uint8_t *Display_GetFramebuffer(); /* - * Sets the display contrast. + * Sets the display contrast (not ISR-safe). * * @param contrast Contrast (0 - 255). */ diff --git a/include/Display_SSD.h b/include/Display_SSD.h index ca939eb..a040c49 100644 --- a/include/Display_SSD.h +++ b/include/Display_SSD.h @@ -19,7 +19,7 @@ */ /** - * NOTE: this low-level interface is not thread-safe. + * NOTE: this low-level interface is not guaranteed to be thread/ISR-safe. */ #ifndef EVICSDK_DISPLAY_SSD_H diff --git a/include/Display_SSD1306.h b/include/Display_SSD1306.h index 95fca8a..041c965 100644 --- a/include/Display_SSD1306.h +++ b/include/Display_SSD1306.h @@ -19,7 +19,7 @@ */ /** - * NOTE: this low-level interface is not thread-safe. + * NOTE: this low-level interface is not guaranteed to be thread/ISR-safe. */ #ifndef EVICSDK_DISPLAY_SSD1306_H diff --git a/include/Display_SSD1327.h b/include/Display_SSD1327.h index 49e686c..93620d6 100644 --- a/include/Display_SSD1327.h +++ b/include/Display_SSD1327.h @@ -19,7 +19,7 @@ */ /** - * NOTE: this low-level interface is not thread-safe. + * NOTE: this low-level interface is not guaranteed to be thread/ISR-safe. */ #ifndef EVICSDK_DISPLAY_SSD1327_H diff --git a/include/Thread.h b/include/Thread.h index 68fc42d..2332a8b 100644 --- a/include/Thread.h +++ b/include/Thread.h @@ -92,15 +92,6 @@ typedef enum { */ typedef void *(*Thread_EntryPtr_t)(void *args); -/* Only *FromISR functions are safe to call from interrupt/callback context. */ -#define Thread_SemaphoreTryDownFromISR Thread_SemaphoreTryDown -#define Thread_SemaphoreUpFromISR Thread_SemaphoreUp -#define Thread_SemaphoreGetCountFromISR Thread_SemaphoreGetCount -#define Thread_MutexGetStateFromISR Thread_MutexGetState -#define Thread_GetSysTicksFromISR Thread_GetSysTicks -#define Thread_IrqDisableFromISR Thread_IrqDisable -#define Thread_IrqRestoreFromISR Thread_IrqRestore - /** * Initializes the thread manager. */ @@ -121,12 +112,12 @@ Thread_Error_t Thread_Create(Thread_t *thread, Thread_EntryPtr_t entry, void *ar /** * Yields this thread back to the scheduler, letting - * other threads run. + * other threads run (not ISR-safe). */ void Thread_Yield(); /** - * Waits for another thread to complete. + * Waits for another thread to complete (not ISR-safe). * Each thread can only have one other thread waiting on it. * Attempting to join a thread that already has another thread * waiting on it will fail with TD_ALREADY_JOINED. @@ -140,7 +131,8 @@ void Thread_Yield(); Thread_Error_t Thread_Join(Thread_t thread, void **ret); /** - * Delays the current thread for the specified amount of time. + * Delays the current thread for the specified amount of time + * (not ISR-safe). * It is guaranteed that the actual delay time will never be less * than the specified time, but it may be longer. * @@ -151,14 +143,14 @@ void Thread_DelayMs(uint32_t delay); /** * Enters a global critical section, disabling scheduling * for other threads. - * Critical sections can be nested. + * Critical sections can be nested. No-op from ISRs. */ void Thread_CriticalEnter(); /** * Exits a global critical section, re-enabling scheduling * for other threads once the last nested critical section - * is exited. + * is exited. No-op from ISRs. */ void Thread_CriticalExit(); @@ -183,7 +175,7 @@ Thread_Error_t Thread_SemaphoreCreate(Thread_Semaphore_t *sema, int32_t count); Thread_Error_t Thread_SemaphoreDestroy(Thread_Semaphore_t sema); /** - * Decrements the semaphore count. + * Decrements the semaphore count (not ISR-safe). * If count is zero, waits until another thread increments it. * * @param sema Semaphore handle. @@ -243,7 +235,7 @@ Thread_Error_t Thread_MutexCreate(Thread_Mutex_t *mutex); Thread_Error_t Thread_MutexDestroy(Thread_Mutex_t mutex); /** - * Locks a mutex. + * Locks a mutex (not ISR-safe). * If the mutex is locked, waits until it's unlocked. * * @param mutex Mutex handle. @@ -253,7 +245,7 @@ Thread_Error_t Thread_MutexDestroy(Thread_Mutex_t mutex); Thread_Error_t Thread_MutexLock(Thread_Mutex_t mutex); /** - * Locks a mutex. + * Locks a mutex (not ISR-safe). * If the mutex is locked, fails without waiting. * * @param mutex Mutex handle. @@ -263,7 +255,7 @@ Thread_Error_t Thread_MutexLock(Thread_Mutex_t mutex); Thread_Error_t Thread_MutexTryLock(Thread_Mutex_t mutex); /** - * Unlocks a mutex. + * Unlocks a mutex (not ISR-safe). * Only the thread that locked a mutex can unlock it. * * @param mutex Mutex handle. diff --git a/include/TimerUtils.h b/include/TimerUtils.h index 5f3281b..76a6a21 100644 --- a/include/TimerUtils.h +++ b/include/TimerUtils.h @@ -80,7 +80,7 @@ int8_t Timer_CreateTimeout(uint16_t timeout, uint8_t isPeriodic, Timer_Callback_ void Timer_DeleteTimer(int8_t index); /** - * Delays for the specified time. + * Delays for the specified time (not ISR-safe). * Do not call from interrupt/callback context. * * @param delay Delay in milliseconds. diff --git a/include/USB_VirtualCOM.h b/include/USB_VirtualCOM.h index 4c8ecde..0a87f99 100644 --- a/include/USB_VirtualCOM.h +++ b/include/USB_VirtualCOM.h @@ -54,7 +54,7 @@ typedef void (*USB_VirtualCOM_RxCallback_t)(); void USB_VirtualCOM_Init(); /** - * Sends data over the USB virtual COM port. + * Sends data over the USB virtual COM port (not ISR-safe). * * @param buf Data buffer. * @param size Number of bytes to send. @@ -62,7 +62,7 @@ void USB_VirtualCOM_Init(); void USB_VirtualCOM_Send(const uint8_t *buf, uint32_t size); /** - * Sends a string over the USB virtual COM port. + * Sends a string over the USB virtual COM port (not ISR-safe). * * @param str String to send. */ diff --git a/src/thread/Thread.c b/src/thread/Thread.c index 8bf2846..649b31e 100644 --- a/src/thread/Thread.c +++ b/src/thread/Thread.c @@ -715,7 +715,7 @@ void Thread_DelayMs(uint32_t delay) { } void Thread_CriticalEnter() { - // For internal use only: no-op from ISRs or startup code. + // No-op from ISRs or startup code if(THREAD_GET_IRQN() != 0 || Thread_curTcb == NULL) { return; } @@ -731,7 +731,7 @@ void Thread_CriticalEnter() { } void Thread_CriticalExit() { - // For internal use only: no-op from ISRs or startup code. + // No-op from ISRs or startup code if(THREAD_GET_IRQN() != 0 || Thread_curTcb == NULL) { return; }