{"id":113,"date":"2014-11-11T11:26:14","date_gmt":"2014-11-11T11:26:14","guid":{"rendered":"http:\/\/visualgdb.com\/w\/?p=113"},"modified":"2018-05-14T10:40:26","modified_gmt":"2018-05-14T17:40:26","slug":"arm-newlib-nano","status":"publish","type":"post","link":"https:\/\/visualgdb.com\/tutorials\/arm\/newlib-nano\/","title":{"rendered":"Building ARM Projects with Newlib-Nano"},"content":{"rendered":"

This tutorial demonstrates how to use newlib-nano, a lightweight version of the standard C\/C++ library that is included with our ARM toolchain. We will show the main differences compared to the full library and demonstrate some efficient debugging techniques. We will first create a very basic C++ project with the full-size library and then reduce its size by using newlib-nano. We will target the STM32F4Discovery board, however the techniques demonstrated here will work with any other ARM device as well.<\/p>\n

To use all features described in this tutorial please update to GCC 4.9.2 and VisualGDB 4.3.<\/p>\n

    \n
  1. Begin with creating a normal Embedded project with VisualGDB project wizard:\"01-newprj\"<\/a><\/li>\n
  2. Proceed with the default settings on the first page of the wizard:\"02-binprj\"<\/a><\/li>\n
  3. On the device selection page select the default C library type and disable the C++ binary size reduction:\"03-toolchain\"<\/a><\/li>\n
  4. Proceed with the default sample settings:\"04-sample\"<\/a><\/li>\n
  5. Select a debugging method that matches your hardware:\"05-jtag\"<\/a><\/li>\n
  6. Press Finish to create the project. Replace the contents of the main source file with a very basic main() function:\n
    #include<stm32f4xx_hal.h>\r\n\r\nint main(void)\r\n{\r\n    HAL_Init();\r\n\r\n   return 0;\r\n}<\/pre>\n
    Then build the project:\"06-basicprj\"<\/a>Note the memory utilization shown in the build output. Most likely you will use less than 2 kilobytes of FLASH.<\/li>\n
  7. Now add some basic C++ code to the project:\n
    #include <stm32f4xx_hal.h>\r\n#include <stdio.h>\r\n\r\nclass BaseClass\r\n{\r\npublic:\r\n   virtualvoid SomeMethod() = 0;\r\n};\r\n\r\nclass ChildClass : public BaseClass\r\n{\r\npublic:\r\n    virtual void SomeMethod()\r\n    {\r\n    }\r\n};\r\n\r\nint main(void)\r\n{\r\n    HAL_Init();\r\n\r\n    ChildClass inst;\r\n    inst.SomeMethod();\r\n\r\n   return 0;\r\n}<\/pre>\n
    Build the project again. You will see that the amount of used memory increased by more than 70K:\"07-morecode\"<\/a><\/li>\n
  8. We will now track down the source of the high memory consumption and show how to reduce it. Open the Embedded Memory Explorer pane:\"08-memexp\"<\/a><\/li>\n
  9. Then click “Explore details”:\"09-memstat\"<\/a>As you can see, most of the memory is used by various library functions that we don’t call directly. Those functions come from the default C++ exception handling mechanism. The default implementation for the pure virtual SomeMethod() actually throws an exception and this automatically involves lots of heavy code that deals with name demangling and information formatting.<\/li>\n
  10. While using 70K of code to get user-friendly printing of unhandled exceptions could be a good tradeoff for desktop programs, it is certainly not for embedded targets. We can disable it by linking with a special library that provides an alternate implementation for the pure virtual method that simply activates a hardware breakpoint. Enable the corresponding checkbox in the VisualGDB Project Properties:\"10-compactcpp\"<\/a><\/li>\n
  11. If you now rebuild your project, you will notice that it requires about a hundred bytes of memory more than the original main() function:\"11-compactbuild\"<\/a><\/li>\n
  12. Another scenario that may involve the heavy exception-related code is using C++ allocation operators. Add the following code to your main() function:\n
    char *p = newchar[128];\r\ndelete[] p;<\/pre>\n
    Then build your project:\"12-newdel\"<\/a>You will see that the exception-related functions have been linked again driving the image size to 70K+.<\/li>\n
  13. In this case you can reduce the binary size by switching from the classical C\/C++ library to a reduced-size version, newlib-nano. It provides many trade-offs that reduce the size of your binaries, e.g. contains a C++ library built without exception support. You can select newlib-nano via VisualGDB project properties:\"13-nano\"<\/a><\/li>\n
  14. However, if you build your project now, you will get several ‘undefined symbol’ errors:\"14-sbrk\"<\/a><\/li>\n
  15. This happens because newlib-nano comes without default implementations for the system calls required by the memory allocation code. This can be fixed by linking with a library that provides default versions of those system calls:\"15-nosys\"<\/a><\/li>\n
  16. Now the build will succeed resulting in a small binary again:\"16-nosysnewdel\"<\/a><\/li>\n
  17. The problem now is that the default syscall stubs provided by the toolchain are not smart enough to detect the out-of-memory condition. Hence the memory allocation will always succeed leading to memory damage in case the memory runs out:\"17-outofmem\"<\/a><\/li>\n
  18. We can fix that by copying the implementation of _sbrk(), a function responsible for memory allocation from the full version of newlib. First switch back to full newlib without syscall stubs in the VisualGDB Project Properties:\"18-defaultlib\"<\/a><\/li>\n
  19. Then set a breakpoint on the _sbrk() function (Ctrl-B):\"19-sbrk-bp\"<\/a><\/li>\n
  20. Start debugging. Once the breakpoint is triggered, VisualGDB will suggest downloading the newlib source code:\"20-getlib\"<\/a><\/li>\n
  21. Proceed with the download:\"21-instlib\"<\/a><\/li>\n
  22. Once the source is downloaded, you will see that the current _sbrk() implementation does check for the out-of-memory condition:\"22-sbrk\"<\/a><\/li>\n
  23. Now switch back to newlib-nano + syscall stubs and copy the “smart” _sbrk() implementation to your main source file:\n
    #include <errno.h>\r\n\r\nextern \"C\" caddr_t _sbrk (int incr)\r\n{\r\n   register char * stack_ptr asm (\"sp\");\r\n   extern char end asm (\"end\");\r\n   static char *heap_end;\r\n   char *prev_heap_end;\r\n\r\n   if (heap_end == NULL)\r\n        heap_end = &end;\r\n\r\n    prev_heap_end = heap_end;\r\n\r\n    if(heap_end + incr > stack_ptr)\r\n    {\r\n        errno = ENOMEM;\r\n        return (caddr_t) -1;\r\n    }\r\n\r\n    heap_end += incr;\r\n\r\n   return (caddr_t) prev_heap_end;\r\n}<\/pre>\n<\/li>\n
  24. If you build your project now, your binary will be slim again:\"23-sbrk-build\"<\/a><\/li>\n
  25. And trying to allocate too much memory will now result in a call to _abort() (as we are using libc++ without exception support) that by default generates a division-by-zero exception:\"24-exit\"<\/a><\/li>\n
  26. One last thing: by default newlib-nano does not support float\/double types in printf()\/scanf() functions. stepping through the following code (requires <math.h>):\n
    char *p = newchar[1024];\r\nsprintf(p, \"pi = %f\", acosf(-1));\r\ndelete[] p;<\/pre>\n
    You will notice that the %f specifier was simply ignored:\"25-format\"<\/a><\/li>\n
  27. This can be fixed by enabling the corresponding version of newlib-nano via VisualGDB Project Properties:\"26-float-printf\"<\/a><\/li>\n
  28. This costs ~10K of FLASH memory more, so only use it when you really need that functionality:\"27-printf-pi\"<\/a><\/li>\n<\/ol>\n
     <\/p>\n","protected":false},"excerpt":{"rendered":"
    This tutorial demonstrates how to use newlib-nano, a lightweight version of the standard C\/C++ library that is included with our<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[27],"tags":[53],"_links":{"self":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/113"}],"collection":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/comments?post=113"}],"version-history":[{"count":2,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/113\/revisions"}],"predecessor-version":[{"id":3987,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/posts\/113\/revisions\/3987"}],"wp:attachment":[{"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/media?parent=113"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/categories?post=113"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/visualgdb.com\/w\/wp-json\/wp\/v2\/tags?post=113"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}