|
- Files for each peripheral (examples given for STM32 GPIO)
- ---------------------------------------------------------
-
- In include/libopencm3/stm32.
- A "dispatch" header to point to the subfamily header (gpio.h)
-
- In include/libopencm3/stm32/f*
- A file with defines that are specific to the subfamily, and an include of
- needed common header files (gpio.h).
-
- In include/libopencm3/stm32/common
- A file with defines common to all subfamilies. Includes the cm3 common header
- (gpio_common_all.h).
-
- In include/libopencm3/stm32/common
- May be one other file with defines common to a subgroup of devices.
- This includes the file common to all (gpio_common_f24.h).
-
- In lib/stm32/f*
- A file with functions specific to the subfamily. Includes the "dispatch" header
- and any common headers needed (gpio.c).
-
- In lib/stm32/common
- Has functions common to all subfamilies. Includes the "dispatch" header
- (gpio_common_all.c).
-
- In lib/stm32/common
- May be one other file with functions common to a group of subfamilies. Includes
- the "dispatch" header and the file common to all (gpio_common_f24.h).
-
- Makefiles in lib/stm32/f? have the common object files added and the
- common directory added to VPATH.
-
- NOTE: The common source files MUST have the "dispatch" header so that
- compilation will use the specific defines for the subfamily being compiled.
- These can differ between subfamilies.
-
- NOTE: The common source files must have a line of the form
-
- #ifdef LIBOPENCM3_xxx_H
-
- where xxx is the associated peripheral name. This prevents the common files
- from being included accidentally into a user's application. This however
- causes doxygen to skip processing of the remainder of the file. Thus a
-
- @cond ... @endcond
-
- directive must be placed around the statement to prevent doxygen from
- processing it. This works only for doxygen 1.8.4 or later. At the present
- time most distros have an earlier buggy version.
-
- Documentation
- -------------
-
- In include/libopencm3/stm32/f*
- A file doc-stm32f*.h contains a definition of the particular family grouping.
- This grouping will appear in the main index of the resulting document with all
- documentation under it.
-
- All header files for a peripheral (common or otherwise) will subgroup under a
- name which is the same in all families (such as gpio_defines). The peripheral
- header file in include/libopencm3/stm32/f* will then include this group as a
- subgroup under the specific family group. Doxygen is run separately for each
- family so there is no danger of accidentally including the wrong stuff.
-
- Similarly for the source files for a peripheral which will subgroup under a
- same name (such as gpio_files). The peripheral source file in lib/stm32/f*
- will include this as a subgroup under the specific family group.
-
- DOXYFILE for a particular family will list the family specific and common files
- (headers and source) that are to be included. The result (in the long run) will
- be that all peripherals will appear under the same family grouping in the
- documentation, even if they are identical over a number of families. That is
- probably most useful to end users who only need to see the documentation for
- one family.
|
