# Documentation for uxTaskGetStackHighWaterMark should be updated?

**URL:** <https://forums.freertos.org/t/documentation-for-uxtaskgetstackhighwatermark-should-be-updated/7057>\
**Category:** Kernel\
**Created:** [March 14, 2018, 1:36am UTC](https://forums.freertos.org/t/documentation-for-uxtaskgetstackhighwatermark-should-be-updated/7057 "2018-03-14T01:36:41Z")\
**Posts on this page:** 11\
**Page:** 1

<div class="post-metadata">

**Author:** ![system](https://d2v6vdsk2p900z.cloudfront.net/original/1X/7fc8fdb729c645aab5b20282bbe34e57cb407be6.jpeg) [@system](https://forums.freertos.org/u/system)\
**Post date:** [March 14, 2018, 1:36am UTC](https://forums.freertos.org/t/documentation-for-uxtaskgetstackhighwatermark-should-be-updated/7057/1 "2018-03-14T01:36:41Z")

</div>

**[jankok](https://sourceforge.net/u/jankok/)** wrote on [Wednesday, March 14, 2018](https://sourceforge.net/p/freertos/discussion/382005/thread/b3eb917a/#0ee6):

At [https://www.freertos.org/uxTaskGetStackHighWaterMark.html](https://www.freertos.org/uxTaskGetStackHighWaterMark.html) it gives the return type as UBaseType\_t, however, at least in Amazon’s portmacro.h, UBaseType\_t is typedef’d as unsigned char. This caused me considerable puzzlement when I increased the initial stack size for a task and it caused the reported high water mark to _decrease_, as the high water mark number rolled over from 255 to 0.

Amazon’s portmacro.h for Arduino contains:

```auto
#define portSTACK_TYPE uint8_t
typedef portSTACK_TYPE StackType_t;
typedef signed char BaseType_t;
typedef unsigned char UBaseType_t;

```

and FreeRTOSconfig.h contains:

```auto
#define configMINIMAL_STACK_SIZE ( ( portSTACK_TYPE ) 192 )
#define configSTACK_DEPTH_TYPE uint16_t

```

Does this look correct? It looks odd to me since portSTACK\_TYPE ends up defined as uint8\_t, which might cause problems if one were to try to increase configMINIMAL\_STACK\_SIZE beyond 255.

In any case, it seems to me the documentation for uxTaskGetStackHighWaterMark should be updated to show some other return type.

---

<div class="post-metadata">

**Author:** ![rtel](https://d3iykfbgfh8zhg.cloudfront.net/user_avatar/forums.freertos.org/rtel/32/31_2.png) [@rtel](https://forums.freertos.org/u/rtel)\
**Post date:** [March 14, 2018, 2:55am UTC](https://forums.freertos.org/t/documentation-for-uxtaskgetstackhighwatermark-should-be-updated/7057/2 "2018-03-14T02:55:49Z")

</div>

**[rtel](https://sourceforge.net/u/rtel/)** wrote on [Wednesday, March 14, 2018](https://sourceforge.net/p/freertos/discussion/382005/thread/b3eb917a/#0ee6/3545):

This has been discussed multiple times, so you will find info in the  
forum. Some changes were made in V10 to allow you to use a different  
data type - I think using vTaskGetInfo() rather than  
uxTaskGetStackHighWaterMark().

> In any case, it seems to me the documentation for  
> uxTaskGetStackHighWaterMark should be updated to show some other return  
> type.

As can be seen in the header file and the source file, the prototype for  
the function is:

UBaseType\_t uxTaskGetStackHighWaterMark( TaskHandle\_t xTask );

So the return type is shown correctly in the documentation. The ‘base  
type’ is the natural (most efficient) type for the architecture so is  
different in different ports - normally 32-bits - but not on an AVR.

---

<div class="post-metadata">

**Author:** ![system](https://d2v6vdsk2p900z.cloudfront.net/original/1X/7fc8fdb729c645aab5b20282bbe34e57cb407be6.jpeg) [@system](https://forums.freertos.org/u/system)\
**Post date:** [March 14, 2018, 6:56am UTC](https://forums.freertos.org/t/documentation-for-uxtaskgetstackhighwatermark-should-be-updated/7057/3 "2018-03-14T06:56:32Z")

</div>

**[jankok](https://sourceforge.net/u/jankok/)** wrote on [Wednesday, March 14, 2018](https://sourceforge.net/p/freertos/discussion/382005/thread/b3eb917a/#2232):

Well, task.h shows

```auto
#if configENABLE_BACKWARD_COMPATIBILITY == 1
UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
#else
configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark( TaskHandle_t xTask ) PRIVILEGED_FUNCTION;
#endif /* configENABLE_BACKWARD_COMPATIBILITY */

```

So the return type depends on whether configENABLE\_BACKWARD\_COMPATIBILITY == 1. In the Arduino FreeRTOS library, configENABLE\_BACKWARD\_COMPATIBILITY is not defined at all, so the return type is configSTACK\_DEPTH\_TYPE which is uint16\_t. And indeed the function can return a value greater than 255. I’ve tested it.

The documentation says the return type is UBaseType\_t, but that’s not true for the Arduino port, and that can lead users like me to get nonsensical values for the high water mark, when taking the usage example code for uxTaskGetStackHighWaterMark at face value.

Should portSTACK\_TYPE , BaseType\_t and UBaseType\_t be defined as 16-bit types in the Arduino port? If not, I think the documentation for uxTaskGetStackHighWaterMark should be updated to warn about the confusing type issues.

In any case, thanks for the help, Richard, and thanks for making FreeRTOS available to the world - for free! 🙂

---

<div class="post-metadata">

**Author:** ![rtel](https://d3iykfbgfh8zhg.cloudfront.net/user_avatar/forums.freertos.org/rtel/32/31_2.png) [@rtel](https://forums.freertos.org/u/rtel)\
**Post date:** [March 14, 2018, 2:07pm UTC](https://forums.freertos.org/t/documentation-for-uxtaskgetstackhighwatermark-should-be-updated/7057/4 "2018-03-14T14:07:10Z")

</div>

**[rtel](https://sourceforge.net/u/rtel/)** wrote on [Wednesday, March 14, 2018](https://sourceforge.net/p/freertos/discussion/382005/thread/b3eb917a/#2232/99c3):

> Well, task.h shows
> 
> #if configENABLE\_BACKWARD\_COMPATIBILITY == 1  
> UBaseType\_t uxTaskGetStackHighWaterMark( TaskHandle\_t xTask ) PRIVILEGED\_FUNCTION;  
> #else  
> configSTACK\_DEPTH\_TYPE uxTaskGetStackHighWaterMark( TaskHandle\_t xTask ) PRIVILEGED\_FUNCTION;  
> #endif /\* configENABLE\_BACKWARD\_COMPATIBILITY \*/
> 
> So the return type depends on whether  
> configENABLE\_BACKWARD\_COMPATIBILITY == 1. In the Arduino FreeRTOS  
> library, configENABLE\_BACKWARD\_COMPATIBILITY is not defined at all, so  
> the return type is configSTACK\_DEPTH\_TYPE which is uint16\_t. And indeed  
> the function can return a value greater than 255. I’ve tested it.

Curious - I think if configENABLE\_BACKWARD\_COMPATIBILITY is not defined  
at all then it will default to 1. We always try to ensure FreeRTOS  
versions default to being backward compatible to ensure upgrading is  
easy. If that is the case then uxTaskGetStackHighwaterMark() should  
have a return type of UBaseType\_t - are you 100% positive  
configENABLE\_BACKWARD\_COMPATIBILITY is not defined anywhere in your  
application?

> Should portSTACK\_TYPE , BaseType\_t and UBaseType\_t be defined as 16-bit  
> types in the Arduino port?

No - portSTACK\_TYPE is dictated by the architecture, you can’t choose a  
value for it as if it is wrong the code just won’t work.

The base type is set to the ‘natural’ size of the architecture to ensure  
it is as efficient as possible and is predominantly used for booleans,  
rather than holding values. uxTaskGetStackHighWaterMark() returning  
such a value is a symptom of FreeRTOS being 15 years old.

---

<div class="post-metadata">

**Author:** ![system](https://d2v6vdsk2p900z.cloudfront.net/original/1X/7fc8fdb729c645aab5b20282bbe34e57cb407be6.jpeg) [@system](https://forums.freertos.org/u/system)\
**Post date:** [March 14, 2018, 6:48pm UTC](https://forums.freertos.org/t/documentation-for-uxtaskgetstackhighwatermark-should-be-updated/7057/5 "2018-03-14T18:48:20Z")

</div>

**[jankok](https://sourceforge.net/u/jankok/)** wrote on [Wednesday, March 14, 2018](https://sourceforge.net/p/freertos/discussion/382005/thread/b3eb917a/#cfae):

> Curious - I think if configENABLE\_BACKWARD\_COMPATIBILITY is not defined  
> at all then it will default to 1.

Aparently not. According to [If (The C Preprocessor)](http://gcc.gnu.org/onlinedocs/cpp/If.html#If) , in the expression part of a #if, “Identifiers that are not macros … are all considered to be the number zero.”

I grepped for COMPATIBILITY in the Arduino library src directory and didn’t see any definitions of configENABLE\_BACKWARD\_COMPATIBILITY. So the #if is interpreting it as 0.

I think we can agree that in a processor that can have more than 255 words of stack space, the return type of the function should not be an 8-bit type. So, what should the return type of the function be?

My suggestion is to cut the Gordian knot, keep it simple, define it as just:  
configSTACK\_DEPTH\_TYPE uxTaskGetStackHighWaterMark( TaskHandle\_t xTask ) PRIVILEGED\_FUNCTION;  
Forget about configENABLE\_BACKWARD\_COMPATIBILITY. It seems to me the purpose of that is to avoid problems for users of ancient code _if they update to a newer version of the FreeRTOS library_. If they don’t update, there should be no problem. If they do update, having them define configSTACK\_DEPTH\_TYPE seems like a small price to pay. You could add code like this before the declaration of uxTaskGetStackHighWaterMark in task.h:

```auto
#ifndef configSTACK_DEPTH_TYPE
	#error Missing definition: configMAX_STACK_DEPTH_TYPE must be defined in FreeRTOSConfig.h. See the Configuration section of the FreeRTOS API documentation for details.
#endif

```

---

<div class="post-metadata">

**Author:** ![rtel](https://d3iykfbgfh8zhg.cloudfront.net/user_avatar/forums.freertos.org/rtel/32/31_2.png) [@rtel](https://forums.freertos.org/u/rtel)\
**Post date:** [March 14, 2018, 6:51pm UTC](https://forums.freertos.org/t/documentation-for-uxtaskgetstackhighwatermark-should-be-updated/7057/6 "2018-03-14T18:51:40Z")

</div>

**[rtel](https://sourceforge.net/u/rtel/)** wrote on [Wednesday, March 14, 2018](https://sourceforge.net/p/freertos/discussion/382005/thread/b3eb917a/#cfae/6fe9):

It should be defaulted in FreeRTOS.h - see line 867 (at the time of  
writing) here:  
[https://sourceforge.net/p/freertos/code/HEAD/tree/trunk/FreeRTOS/Source/include/FreeRTOS.h#l4](https://sourceforge.net/p/freertos/code/HEAD/tree/trunk/FreeRTOS/Source/include/FreeRTOS.h#l4)

---

<div class="post-metadata">

**Author:** ![system](https://d2v6vdsk2p900z.cloudfront.net/original/1X/7fc8fdb729c645aab5b20282bbe34e57cb407be6.jpeg) [@system](https://forums.freertos.org/u/system)\
**Post date:** [March 15, 2018, 12:38am UTC](https://forums.freertos.org/t/documentation-for-uxtaskgetstackhighwatermark-should-be-updated/7057/7 "2018-03-15T00:38:55Z")

</div>

**[jankok](https://sourceforge.net/u/jankok/)** wrote on [Thursday, March 15, 2018](https://sourceforge.net/p/freertos/discussion/382005/thread/b3eb917a/#ece5):

All right, so I guess you’re saying that ports to processors, where UBaseType\_t is not large enough to hold a stack size value, should include

```auto
#define configENABLE_BACKWARD_COMPATIBILITY 0
#define configSTACK_DEPTH_TYPE uint16_t // or whatever

```

in FreeRTOSConfig.h. The latest Arduino FreeRTOS library FreeRTOSConfig.h contains the second line but not the first. Arduino\_FreeRTOS.h is V10.0.0 and doesn’t contain the code to default configENABLE\_BACKWARD\_COMPATIBILITY to 1 if undefined.

I guess I can live with that. However, I still think [https://www.freertos.org/uxTaskGetStackHighWaterMark.html](https://www.freertos.org/uxTaskGetStackHighWaterMark.html) should be updated, because if someone copies the example usage code, while using an AVR or similar processor, the results won’t make sense if the high water mark is greater than 255. I got bitten by that, and that’s why I came here and started this thread!

(I was having problems that I thought might be due to some sort of memory corruption. I tried investigating stack space using the example code in that web page. I started going crazy because increasing the allocated stack space could sometimes _decrease_ the high water mark, and I never could get the high water mark very large. It was only when I tried seeing exactly how large I could make it, and I increased the stack space by 1 and saw the high water mark go from 255 to 0, that a light bulb turned on and I realized that the high water mark was somehow getting truncated to 8 bits.)

---

<div class="post-metadata">

**Author:** ![system](https://d2v6vdsk2p900z.cloudfront.net/original/1X/7fc8fdb729c645aab5b20282bbe34e57cb407be6.jpeg) [@system](https://forums.freertos.org/u/system)\
**Post date:** [March 20, 2018, 10:34pm UTC](https://forums.freertos.org/t/documentation-for-uxtaskgetstackhighwatermark-should-be-updated/7057/8 "2018-03-20T22:34:56Z")

</div>

**[jankok](https://sourceforge.net/u/jankok/)** wrote on [Tuesday, March 20, 2018](https://sourceforge.net/p/freertos/discussion/382005/thread/b3eb917a/#8255):

Rick Richard ran into the same problem, see [https://sourceforge.net/p/freertos/discussion/382005/thread/335d645d/](https://sourceforge.net/p/freertos/discussion/382005/thread/335d645d/)

The problem occurs on processors where sizeof(UBaseType\_t) != sizeof(configSTACK\_DEPTH\_TYPE). For example on an 8-bit AVR processor, the stack can grow one byte at a time, but the stack can have more than 255 elements, so UBaseType\_t is defined as uint8\_t and configSTACK\_DEPTH\_TYPE is defined as uint16\_t.

I think the simplest solution that would maintain backward compatibility with existing user’s code, would be to change the return type of uxTaskGetStackHighWaterMark to be configSTACK\_DEPTH\_TYPE, and then default the value of configSTACK\_DEPTH\_TYPE to be UBaseType\_t if configSTACK\_DEPTH\_TYPE is not defined in FreeRTOSConfig.h.

In any case, the documentation for uxTaskGetStackHighWaterMark should be updated to show the correct return type, so users don’t keep tripping over this problem. Would you like me to file this as a bug?

---

<div class="post-metadata">

**Author:** ![rtel](https://d3iykfbgfh8zhg.cloudfront.net/user_avatar/forums.freertos.org/rtel/32/31_2.png) [@rtel](https://forums.freertos.org/u/rtel)\
**Post date:** [March 20, 2018, 10:41pm UTC](https://forums.freertos.org/t/documentation-for-uxtaskgetstackhighwatermark-should-be-updated/7057/9 "2018-03-20T22:41:09Z")

</div>

**[rtel](https://sourceforge.net/u/rtel/)** wrote on [Tuesday, March 20, 2018](https://sourceforge.net/p/freertos/discussion/382005/thread/b3eb917a/#8255/7fbf):

While I agree the documentation can be updated to make the behaviour  
very clear, it is still unclear to me which documentation does not show  
the function returning the type it does actually return. Can you let me  
know, as then I can fix it.

---

<div class="post-metadata">

**Author:** ![system](https://d2v6vdsk2p900z.cloudfront.net/original/1X/7fc8fdb729c645aab5b20282bbe34e57cb407be6.jpeg) [@system](https://forums.freertos.org/u/system)\
**Post date:** [March 21, 2018, 12:53am UTC](https://forums.freertos.org/t/documentation-for-uxtaskgetstackhighwatermark-should-be-updated/7057/10 "2018-03-21T00:53:37Z")

</div>

**[jankok](https://sourceforge.net/u/jankok/)** wrote on [Wednesday, March 21, 2018](https://sourceforge.net/p/freertos/discussion/382005/thread/b3eb917a/#8255/7fbf/34d2):

[https://www.freertos.org/uxTaskGetStackHighWaterMark.html](https://www.freertos.org/uxTaskGetStackHighWaterMark.html)

---

<div class="post-metadata">

**Author:** ![rtel](https://d3iykfbgfh8zhg.cloudfront.net/user_avatar/forums.freertos.org/rtel/32/31_2.png) [@rtel](https://forums.freertos.org/u/rtel)\
**Post date:** [March 21, 2018, 1:38am UTC](https://forums.freertos.org/t/documentation-for-uxtaskgetstackhighwatermark-should-be-updated/7057/11 "2018-03-21T01:38:20Z")

</div>

**[rtel](https://sourceforge.net/u/rtel/)** wrote on [Wednesday, March 21, 2018](https://sourceforge.net/p/freertos/discussion/382005/thread/b3eb917a/#8255/7fbf/34d2/0756):

That page shows the function returning UBaseType\_t - which is what it  
does return.