Documented custom CMake functions

Author: NidasioAlberto

miosix/cmake/AddProcess.cmake

@@ -23,7 +23,15 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, see <http://www.gnu.org/licenses/>
 
-# Function to link the Miosix libraries to a target and register the build command
+# Function to create a Miosix process
+#
+#   miosix_add_process(<target> <source1> <source2> ...)
+#
+# What is does:
+# - Create an executable target with the given sources
+# - Link the libraries required by processes
+# - Tell the linker to produce a map file
+# - Run strip and mx-postlinker on the executable
 function(miosix_add_process TARGET SOURCES)
     # Define the executable with its sources
     add_executable(${TARGET} ${SOURCES})

miosix/cmake/AddRomfsImage.cmake

@@ -32,6 +32,20 @@ ExternalProject_Add(buildromfs
     INSTALL_COMMAND "" # Skip install
 )
 
+# Create a target that builds the romfs image and combines it the kernel into a single binary image
+#
+#   miosix_add_romfs_image(
+#     IMAGE_NAME <name>
+#     KERNEL <kernel>
+#     DIR_NAME <dir_name>
+#     PROCESSES <process1> <process2> ...
+#   )
+#
+# What it does:
+# - Copies all processes binaries to a single directory named <dir_name>
+# - Creates a romfs image with of the directory <dir_name>
+# - Combines the kernel and the romfs image into a single binary image
+# - Registers a custom target (named <dir_name>) with to run the above steps
 function(miosix_add_romfs_image)
     cmake_parse_arguments(ROMFS "" "IMAGE_NAME;KERNEL;DIR_NAME" "PROCESSES" ${ARGN})
 

miosix/cmake/CreateProcessesDir.cmake

@@ -23,6 +23,16 @@
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, see <http://www.gnu.org/licenses/>
 
+# Copies processes binaries into a single directory
+#
+#   miosix_create_processes_dir(
+#     DIR_NAME <dir_name>
+#     PROCESSES <process1> <process2> ...
+#   )
+#
+# This function addresses two use cases:
+# - When you need to build a romfs image, you need all processes into a single directory
+# - If you want to load processes on to an SD card for example, is useful to have all processes grouped togheter
 function(miosix_create_processes_dir)
     cmake_parse_arguments(PROCS "" "DIR_NAME" "PROCESSES" ${ARGN})
 

miosix/cmake/LinkTarget.cmake

@@ -40,6 +40,14 @@ function(miosix_add_program_target TARGET)
 endfunction()
 
 # Function to link the Miosix libraries to a target and register the build command
+#
+#   miosix_link_target(<target>)
+#
+# What it does:
+# - Links the Miosix libraries to the target
+# - Tells the linker to generate the map file
+# - Registers custom targets to create the hex and bin files (${TARGET}_bin and ${TARGET}_hex)
+# - Registers a custom target to flash the program to the board (${TARGET}_program)
 function(miosix_link_target TARGET)
     if (NOT TARGET miosix)
         message(FATAL_ERROR "The board you selected is not supported")