You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

77 lines
3.0 KiB

  1. Files for each peripheral (examples given for STM32 GPIO)
  2. ---------------------------------------------------------
  3. In include/libopencm3/stm32.
  4. A "dispatch" header to point to the subfamily header (gpio.h)
  5. In include/libopencm3/stm32/f*
  6. A file with defines that are specific to the subfamily, and an include of
  7. needed common header files (gpio.h).
  8. In include/libopencm3/stm32/common
  9. A file with defines common to all subfamilies. Includes the cm3 common header
  10. (gpio_common_all.h).
  11. In include/libopencm3/stm32/common
  12. May be one other file with defines common to a subgroup of devices.
  13. This includes the file common to all (gpio_common_f24.h).
  14. In lib/stm32/f*
  15. A file with functions specific to the subfamily. Includes the "dispatch" header
  16. and any common headers needed (gpio.c).
  17. In lib/stm32/common
  18. Has functions common to all subfamilies. Includes the "dispatch" header
  19. (gpio_common_all.c).
  20. In lib/stm32/common
  21. May be one other file with functions common to a group of subfamilies. Includes
  22. the "dispatch" header and the file common to all (gpio_common_f24.h).
  23. Makefiles in lib/stm32/f? have the common object files added and the
  24. common directory added to VPATH.
  25. NOTE: The common source files MUST have the "dispatch" header so that
  26. compilation will use the specific defines for the subfamily being compiled.
  27. These can differ between subfamilies.
  28. NOTE: The common source files must have a line of the form
  29. #ifdef LIBOPENCM3_xxx_H
  30. where xxx is the associated peripheral name. This prevents the common files
  31. from being included accidentally into a user's application. This however
  32. causes doxygen to skip processing of the remainder of the file. Thus a
  33. @cond ... @endcond
  34. directive must be placed around the statement to prevent doxygen from
  35. processing it. This works only for doxygen 1.8.4 or later. At the present
  36. time most distros have an earlier buggy version.
  37. Documentation
  38. -------------
  39. In include/libopencm3/stm32/f*
  40. A file doc-stm32f*.h contains a definition of the particular family grouping.
  41. This grouping will appear in the main index of the resulting document with all
  42. documentation under it.
  43. All header files for a peripheral (common or otherwise) will subgroup under a
  44. name which is the same in all families (such as gpio_defines). The peripheral
  45. header file in include/libopencm3/stm32/f* will then include this group as a
  46. subgroup under the specific family group. Doxygen is run separately for each
  47. family so there is no danger of accidentally including the wrong stuff.
  48. Similarly for the source files for a peripheral which will subgroup under a
  49. same name (such as gpio_files). The peripheral source file in lib/stm32/f*
  50. will include this as a subgroup under the specific family group.
  51. DOXYFILE for a particular family will list the family specific and common files
  52. (headers and source) that are to be included. The result (in the long run) will
  53. be that all peripherals will appear under the same family grouping in the
  54. documentation, even if they are identical over a number of families. That is
  55. probably most useful to end users who only need to see the documentation for
  56. one family.