From 1dc7d758f96dd2b9bd7b03f01ca032d68b696cf0 Mon Sep 17 00:00:00 2001 From: root Date: Sun, 2 Nov 2014 10:14:39 +0000 Subject: fish --- libopencm3/HACKING_COMMON_DOC | 76 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 libopencm3/HACKING_COMMON_DOC (limited to 'libopencm3/HACKING_COMMON_DOC') diff --git a/libopencm3/HACKING_COMMON_DOC b/libopencm3/HACKING_COMMON_DOC new file mode 100644 index 0000000..b0fa4b3 --- /dev/null +++ b/libopencm3/HACKING_COMMON_DOC @@ -0,0 +1,76 @@ +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. + -- cgit v1.2.3