hartmannathan commented on code in PR #11143: URL: https://github.com/apache/nuttx/pull/11143#discussion_r1385504188
########## Documentation/guides/stm32ccm.rst: ########## @@ -0,0 +1,108 @@ +=================== +STM32 CCM Allocator +=================== + +CCM Memory +========== + +The STM32 F2, F3, and F4 families have a special block of SRAM available called +CCM (Core Coupled Memory). This memory has the drawback that it cannot be used +for STM32 DMA operations. + +By default, the CCM memory is lumped in with the rest of memory when the NuttX +heaps are created. But this can be a problem because it will be a toss of the +coin if non-DMA-able CCM memory or other DMA-able memory gets returned when +``malloc()`` is called. That usually does not matter but it certainly does make +a difference if you are allocating memory that will be used for DMA! In that +case, getting CCM memory for you DMA buffer will cause a failure. + +CONFIG_STM32_CCMEXCLUDE +======================= + +There is a configuration option called ``CONFIG_STM32_CCMEXCLUDE`` that can be +used to exclude CCM memory from the heap. That solves the problem of getting +CCM memory when you want to allocate a DMA buffer. But then what do you do +with the CCM memory? Do you let it go unused? + +CCM Allocator +============= + +In order to make use of the CCM memory, a CCM memory allocator is available. +This memory allocator is automatically enabled when the following options are set: + +* ``CONFIG_STM32_CCMEXCLUDE`` CCM memory is excluded from the normally heap, and Review Comment: ```suggestion * ``CONFIG_STM32_CCMEXCLUDE`` CCM memory is excluded from the normal heap, and ``` ########## Documentation/guides/stm32ccm.rst: ########## @@ -0,0 +1,108 @@ +=================== +STM32 CCM Allocator +=================== + +CCM Memory +========== + +The STM32 F2, F3, and F4 families have a special block of SRAM available called +CCM (Core Coupled Memory). This memory has the drawback that it cannot be used +for STM32 DMA operations. + +By default, the CCM memory is lumped in with the rest of memory when the NuttX +heaps are created. But this can be a problem because it will be a toss of the +coin if non-DMA-able CCM memory or other DMA-able memory gets returned when +``malloc()`` is called. That usually does not matter but it certainly does make +a difference if you are allocating memory that will be used for DMA! In that +case, getting CCM memory for you DMA buffer will cause a failure. + +CONFIG_STM32_CCMEXCLUDE +======================= + +There is a configuration option called ``CONFIG_STM32_CCMEXCLUDE`` that can be +used to exclude CCM memory from the heap. That solves the problem of getting +CCM memory when you want to allocate a DMA buffer. But then what do you do +with the CCM memory? Do you let it go unused? + +CCM Allocator +============= + +In order to make use of the CCM memory, a CCM memory allocator is available. +This memory allocator is automatically enabled when the following options are set: + +* ``CONFIG_STM32_CCMEXCLUDE`` CCM memory is excluded from the normally heap, and +* ``CONFIG_MM_MULTIHEAP`` Support for multiple heaps is enabled. + +Under those conditions, the CCM memory allocator is enabled and the allocator +interfaces prototyped in the ``arch/arm/src/stm32/stm32_ccm.h`` are available + +NOTE: These interfaces are, technically, not prototyped since they are really +provided via C pre-processor macros. + +NOTE: that in order to use the CCM memory allocator functions, you must first call +``ccm_initialize()`` somwhere in your early boot-up logic. + +With these interfaces you have a (nearly) standard way to manager memory from a Review Comment: ```suggestion With these interfaces you have a (nearly) standard way to manage memory from a ``` ########## Documentation/guides/stm32ccm.rst: ########## @@ -0,0 +1,108 @@ +=================== +STM32 CCM Allocator +=================== + +CCM Memory +========== + +The STM32 F2, F3, and F4 families have a special block of SRAM available called +CCM (Core Coupled Memory). This memory has the drawback that it cannot be used +for STM32 DMA operations. + +By default, the CCM memory is lumped in with the rest of memory when the NuttX +heaps are created. But this can be a problem because it will be a toss of the +coin if non-DMA-able CCM memory or other DMA-able memory gets returned when +``malloc()`` is called. That usually does not matter but it certainly does make +a difference if you are allocating memory that will be used for DMA! In that +case, getting CCM memory for you DMA buffer will cause a failure. + +CONFIG_STM32_CCMEXCLUDE +======================= + +There is a configuration option called ``CONFIG_STM32_CCMEXCLUDE`` that can be +used to exclude CCM memory from the heap. That solves the problem of getting +CCM memory when you want to allocate a DMA buffer. But then what do you do +with the CCM memory? Do you let it go unused? + +CCM Allocator +============= + +In order to make use of the CCM memory, a CCM memory allocator is available. +This memory allocator is automatically enabled when the following options are set: + +* ``CONFIG_STM32_CCMEXCLUDE`` CCM memory is excluded from the normally heap, and +* ``CONFIG_MM_MULTIHEAP`` Support for multiple heaps is enabled. + +Under those conditions, the CCM memory allocator is enabled and the allocator +interfaces prototyped in the ``arch/arm/src/stm32/stm32_ccm.h`` are available Review Comment: ```suggestion interfaces prototyped in the ``arch/arm/src/stm32/stm32_ccm.h`` are available. ``` ########## Documentation/implementation/bottomhalf_interrupt.rst: ########## @@ -0,0 +1,133 @@ +============================== +Bottom-Half Interrupt Handlers +============================== + +RTOS Interrupts +=============== + +A well-design RTOS depends on the most minimal of interrupt level processing. +This is a very different concept that for bare metal programming: + +* With bare metal programming most of the real-time work is usually performed + in interrupt handlers. Interrupt handler execution may then extend in time + considerably due to this interrupt level processing. + +To compensate for this extended interrupt processing time, bare metal programmers +also need prioritized interrupts: + +* If an interrupt request for a higher priority interrupt occurs during the + extended processing of the lower priority interrupt, then that interrupt handler + will itself be interrupted to service the higher priority interrupt requests. + In this way bare metal interrupt handling is nested. + +With an RTOS, the real-time strategy is very different: + +* Interrupts must run very, very briefly so that they do not interfere with the + RTOS real-time scheduling. Normally, the interrupt simply performs whatever + minor housekeeping is necessary and then immediately defers processing by waking up + some task via some Inter-Process Communication(IPC). The RTOS is then responsible for + the real-time behavior, not the interrupt. And, + +* since the interrupts must be very brief, there is little or no gain from nesting of interrupts. + +Extending interrupt processing +============================== + +But what if extended interrupt processing is required? +What if there is a significant amount of hardware-related operations that absolutely +must be performed as quickly as possible before we can turn processing over to +general, real-time tasking? + +In NuttX, this is handled through a high priority trampoline called +the "High Priority Work Queue". It is a trampoline because it changes the interrupt +processing context for extended interrupt processing before notifying the normal +real-time task. +Processing on that ultra-high priority work thread then completes the extended +interrupt processing with interrupts enabled, but without interference from any +other real-time tasks. +At the completion of the extended processing, the high priority worker thread can Review Comment: Insert blank line for new paragraph? ########## Documentation/guides/stm32ccm.rst: ########## @@ -0,0 +1,108 @@ +=================== +STM32 CCM Allocator +=================== + +CCM Memory +========== + +The STM32 F2, F3, and F4 families have a special block of SRAM available called +CCM (Core Coupled Memory). This memory has the drawback that it cannot be used +for STM32 DMA operations. + +By default, the CCM memory is lumped in with the rest of memory when the NuttX +heaps are created. But this can be a problem because it will be a toss of the +coin if non-DMA-able CCM memory or other DMA-able memory gets returned when +``malloc()`` is called. That usually does not matter but it certainly does make +a difference if you are allocating memory that will be used for DMA! In that +case, getting CCM memory for you DMA buffer will cause a failure. + +CONFIG_STM32_CCMEXCLUDE +======================= + +There is a configuration option called ``CONFIG_STM32_CCMEXCLUDE`` that can be +used to exclude CCM memory from the heap. That solves the problem of getting +CCM memory when you want to allocate a DMA buffer. But then what do you do +with the CCM memory? Do you let it go unused? + +CCM Allocator +============= + +In order to make use of the CCM memory, a CCM memory allocator is available. +This memory allocator is automatically enabled when the following options are set: + +* ``CONFIG_STM32_CCMEXCLUDE`` CCM memory is excluded from the normally heap, and +* ``CONFIG_MM_MULTIHEAP`` Support for multiple heaps is enabled. + +Under those conditions, the CCM memory allocator is enabled and the allocator +interfaces prototyped in the ``arch/arm/src/stm32/stm32_ccm.h`` are available + +NOTE: These interfaces are, technically, not prototyped since they are really +provided via C pre-processor macros. + +NOTE: that in order to use the CCM memory allocator functions, you must first call +``ccm_initialize()`` somwhere in your early boot-up logic. + +With these interfaces you have a (nearly) standard way to manager memory from a +heap that consists of the the CCM SRAM. And, since the CCM memory, is no longer +a part of the normal heap, all allocated I/O buffers will be DMA-able (unless you +have included other non-DMA-able memory regions in the stack). + +CCM Stacks +========== + +One particular problem that has been reported by Petteri Aimonen requires some +additional work-arounds. The STM32 SPI driver supports DMA and with SPI is is Review Comment: ```suggestion additional work-arounds. The STM32 SPI driver supports DMA and with SPI it is ``` ########## Documentation/guides/stm32ccm.rst: ########## @@ -0,0 +1,108 @@ +=================== +STM32 CCM Allocator +=================== + +CCM Memory +========== + +The STM32 F2, F3, and F4 families have a special block of SRAM available called +CCM (Core Coupled Memory). This memory has the drawback that it cannot be used +for STM32 DMA operations. + +By default, the CCM memory is lumped in with the rest of memory when the NuttX +heaps are created. But this can be a problem because it will be a toss of the +coin if non-DMA-able CCM memory or other DMA-able memory gets returned when +``malloc()`` is called. That usually does not matter but it certainly does make +a difference if you are allocating memory that will be used for DMA! In that +case, getting CCM memory for you DMA buffer will cause a failure. + +CONFIG_STM32_CCMEXCLUDE +======================= + +There is a configuration option called ``CONFIG_STM32_CCMEXCLUDE`` that can be +used to exclude CCM memory from the heap. That solves the problem of getting +CCM memory when you want to allocate a DMA buffer. But then what do you do +with the CCM memory? Do you let it go unused? + +CCM Allocator +============= + +In order to make use of the CCM memory, a CCM memory allocator is available. +This memory allocator is automatically enabled when the following options are set: + +* ``CONFIG_STM32_CCMEXCLUDE`` CCM memory is excluded from the normally heap, and +* ``CONFIG_MM_MULTIHEAP`` Support for multiple heaps is enabled. + +Under those conditions, the CCM memory allocator is enabled and the allocator +interfaces prototyped in the ``arch/arm/src/stm32/stm32_ccm.h`` are available + +NOTE: These interfaces are, technically, not prototyped since they are really +provided via C pre-processor macros. + +NOTE: that in order to use the CCM memory allocator functions, you must first call Review Comment: ```suggestion NOTE: In order to use the CCM memory allocator functions, you must first call ``` ########## Documentation/implementation/bottomhalf_interrupt.rst: ########## @@ -0,0 +1,133 @@ +============================== +Bottom-Half Interrupt Handlers +============================== + +RTOS Interrupts +=============== + +A well-design RTOS depends on the most minimal of interrupt level processing. +This is a very different concept that for bare metal programming: + +* With bare metal programming most of the real-time work is usually performed + in interrupt handlers. Interrupt handler execution may then extend in time + considerably due to this interrupt level processing. + +To compensate for this extended interrupt processing time, bare metal programmers +also need prioritized interrupts: + +* If an interrupt request for a higher priority interrupt occurs during the + extended processing of the lower priority interrupt, then that interrupt handler + will itself be interrupted to service the higher priority interrupt requests. + In this way bare metal interrupt handling is nested. + +With an RTOS, the real-time strategy is very different: + +* Interrupts must run very, very briefly so that they do not interfere with the + RTOS real-time scheduling. Normally, the interrupt simply performs whatever + minor housekeeping is necessary and then immediately defers processing by waking up + some task via some Inter-Process Communication(IPC). The RTOS is then responsible for + the real-time behavior, not the interrupt. And, + +* since the interrupts must be very brief, there is little or no gain from nesting of interrupts. + +Extending interrupt processing +============================== + +But what if extended interrupt processing is required? +What if there is a significant amount of hardware-related operations that absolutely +must be performed as quickly as possible before we can turn processing over to +general, real-time tasking? + +In NuttX, this is handled through a high priority trampoline called +the "High Priority Work Queue". It is a trampoline because it changes the interrupt +processing context for extended interrupt processing before notifying the normal +real-time task. +Processing on that ultra-high priority work thread then completes the extended Review Comment: Insert blank line for new paragraph? ########## Documentation/guides/stm32ccm.rst: ########## @@ -0,0 +1,108 @@ +=================== +STM32 CCM Allocator +=================== + +CCM Memory +========== + +The STM32 F2, F3, and F4 families have a special block of SRAM available called +CCM (Core Coupled Memory). This memory has the drawback that it cannot be used +for STM32 DMA operations. + +By default, the CCM memory is lumped in with the rest of memory when the NuttX +heaps are created. But this can be a problem because it will be a toss of the +coin if non-DMA-able CCM memory or other DMA-able memory gets returned when +``malloc()`` is called. That usually does not matter but it certainly does make +a difference if you are allocating memory that will be used for DMA! In that +case, getting CCM memory for you DMA buffer will cause a failure. + +CONFIG_STM32_CCMEXCLUDE +======================= + +There is a configuration option called ``CONFIG_STM32_CCMEXCLUDE`` that can be +used to exclude CCM memory from the heap. That solves the problem of getting +CCM memory when you want to allocate a DMA buffer. But then what do you do +with the CCM memory? Do you let it go unused? + +CCM Allocator +============= + +In order to make use of the CCM memory, a CCM memory allocator is available. +This memory allocator is automatically enabled when the following options are set: + +* ``CONFIG_STM32_CCMEXCLUDE`` CCM memory is excluded from the normally heap, and +* ``CONFIG_MM_MULTIHEAP`` Support for multiple heaps is enabled. + +Under those conditions, the CCM memory allocator is enabled and the allocator +interfaces prototyped in the ``arch/arm/src/stm32/stm32_ccm.h`` are available + +NOTE: These interfaces are, technically, not prototyped since they are really +provided via C pre-processor macros. + +NOTE: that in order to use the CCM memory allocator functions, you must first call +``ccm_initialize()`` somwhere in your early boot-up logic. + +With these interfaces you have a (nearly) standard way to manager memory from a +heap that consists of the the CCM SRAM. And, since the CCM memory, is no longer Review Comment: ```suggestion heap that consists of the the CCM SRAM. And, since the CCM memory is no longer ``` ########## Documentation/implementation/bottomhalf_interrupt.rst: ########## @@ -0,0 +1,133 @@ +============================== +Bottom-Half Interrupt Handlers +============================== + +RTOS Interrupts +=============== + +A well-design RTOS depends on the most minimal of interrupt level processing. +This is a very different concept that for bare metal programming: + +* With bare metal programming most of the real-time work is usually performed + in interrupt handlers. Interrupt handler execution may then extend in time + considerably due to this interrupt level processing. + +To compensate for this extended interrupt processing time, bare metal programmers +also need prioritized interrupts: + +* If an interrupt request for a higher priority interrupt occurs during the + extended processing of the lower priority interrupt, then that interrupt handler + will itself be interrupted to service the higher priority interrupt requests. + In this way bare metal interrupt handling is nested. + +With an RTOS, the real-time strategy is very different: + +* Interrupts must run very, very briefly so that they do not interfere with the + RTOS real-time scheduling. Normally, the interrupt simply performs whatever + minor housekeeping is necessary and then immediately defers processing by waking up + some task via some Inter-Process Communication(IPC). The RTOS is then responsible for + the real-time behavior, not the interrupt. And, + +* since the interrupts must be very brief, there is little or no gain from nesting of interrupts. + +Extending interrupt processing +============================== + +But what if extended interrupt processing is required? +What if there is a significant amount of hardware-related operations that absolutely +must be performed as quickly as possible before we can turn processing over to +general, real-time tasking? + +In NuttX, this is handled through a high priority trampoline called +the "High Priority Work Queue". It is a trampoline because it changes the interrupt +processing context for extended interrupt processing before notifying the normal +real-time task. +Processing on that ultra-high priority work thread then completes the extended +interrupt processing with interrupts enabled, but without interference from any +other real-time tasks. +At the completion of the extended processing, the high priority worker thread can +then continue processing via some IPC to a normal real-time task. + +The portion of interrupt processing that is performed in the interrupt handler with +interrupts disabled is referred to as Top Half Interrupt processing; the portion of +interrupt processing that is performed on the high priority work queue with interrupts +enabled is referred to as Bottom Half Interrupt processing. + +High Priority Work Queue +======================== + +NuttX supports a high priority work queue as well as a low priority work queue with +somewhat different properties. +The high priority work queue is dedicated to the support of Bottom Half Interrupt +processing. +Other uses of the high priority work queue may be inappropriate and may harm the +real-time performance of your system. + +The high priority work queue must have these properties: + +* **Highest Priority** The high priority work queue must be the highest priority + task in your system. No other task should execute at a higher priority; No other + task can be permitted to interfere with execution of the high priority work queue. + +* **Zero Latency Context Switches** Provided that the priority of the high priority + work queue is the highest in the system, then there will be no context switch + overhead in getting from the Top Half Interrupt processing to the Bottom Half + Interrupt processing other that the normal overhead of returning from an interrupt. + Upon return from the interrupt, the system will immediately vector to high priority + worker thread. + +* **Brief Processing** Processing on the high priority work queue must still be brief. + If there is high priority work in progress when the high priority worker is signaled, + then that processing will be queued and delayed until it can be processed. That delay + will add jitter to your real-time response. You must not generate a backlog of work + for the high priority worker thread! + +* **No Waiting** Work executing on the high priority work queue must not wait for + resources or events on the high priority worker thread. Waiting on the high priority + work queue blocks the queue and will, again, damage real-time performance. + +Setting Up Bottom Half Interrupt Processing +=========================================== + +Bottom half interrupt processing is scheduled by top half interrupt processing by +simply calling the function ``work_queue()``: + +.. code-block:: C + + int work_queue(int qid, FAR struct work_s *work, worker_t worker, + FAR void *arg, clock_t delay); + +This same interface is the same for both high- and low-priory. Review Comment: ```suggestion This same interface is the same for both high- and low-priority. ``` ########## Documentation/guides/stm32ccm.rst: ########## @@ -0,0 +1,108 @@ +=================== +STM32 CCM Allocator +=================== + +CCM Memory +========== + +The STM32 F2, F3, and F4 families have a special block of SRAM available called +CCM (Core Coupled Memory). This memory has the drawback that it cannot be used +for STM32 DMA operations. + +By default, the CCM memory is lumped in with the rest of memory when the NuttX +heaps are created. But this can be a problem because it will be a toss of the +coin if non-DMA-able CCM memory or other DMA-able memory gets returned when +``malloc()`` is called. That usually does not matter but it certainly does make +a difference if you are allocating memory that will be used for DMA! In that +case, getting CCM memory for you DMA buffer will cause a failure. Review Comment: ```suggestion case, getting CCM memory for your DMA buffer will cause a failure. ``` ########## Documentation/guides/stm32nullpointer.rst: ########## @@ -0,0 +1,70 @@ +============================ +STM32 Null Pointer Detection +============================ + +The NULL Pointer Problem +======================== + +A common cause of software bugs is null pointers. Pointers may be NULL if they +are un-initialized and un-checked. The use of NULL pointers almost always results +in something bad happening. Often, NULL pointer access can cause error exceptions +and or diagnostic crashes. But on MCUs that have valid address decoding at address +0x0000:0000, the use of NULL pointers may not cause a crash at all but may, instead, +cause strange behaviors that can sometimes be difficult to debug. + +Cortex-M Memory +=============== + +The Cortex-M family (Cortex-M0, M3, and M4) are such MCUs. They have their +interrupt vectors positioned at address zero. Because of this, NULL pointer +accesses will not necessarily cause crashes. Instead, the NULL pointers will +access memory in the vicinity of the vector table and who knows what will happen +next? + +STM32 Memory Aliasing +===================== + +The STMicro STM32 family of Cortex-M3/4 MCUs do things a little differently. +FLASH is physically addressed at address 0x0800:0000; the STM32 vector table +is then physically located at 0x0800:0000 instead of 0x0000:0000. If the STM32 +hardware is configured to boot from FLASH, then the the STM32 will remap the +FLASH memory so that is aliased at address 0x0000:00000. In that way, the STM32 +can boot from FLASH or external memory or any other memory region that it is +capable of mapping. + +In the NuttX linker scripts, the applications are linked to execute from the +physical FLASH region at address 0x0800:00000. All valid FLASH memory access Review Comment: ```suggestion physical FLASH region at address 0x0800:0000. All valid FLASH memory access ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: commits-unsubscr...@nuttx.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
