Document "pico_generate_pio_header" parameters usable in CMake.

[VBHunt]

There are only usage examples for pico_generate_pio_header. and it is unclear the semantic circumstances that are required to use the various parameters. For example the pio/ws2812/CMakeLists.txt shows, in part, the following:

add_executable(pio_ws2812)
file(MAKE_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}/generated)
# generate the header file into the source tree as it is included in the RP2040 datasheet
pico_generate_pio_header(pio_ws2812 ${CMAKE_CURRENT_LIST_DIR}/ws2812.pio OUTPUT_DIR ${CMAKE_CURRENT_LIST_DIR}/generated)
target_sources(pio_ws2812 PRIVATE ws2812.c)
target_link_libraries(pio_ws2812 PRIVATE pico_stdlib hardware_pio)
pico_add_extra_outputs(pio_ws2812)

Yet a similar identical in structure CMakeLists.txt file fails:

set(FTCHIP FT245)
#set(FTCHIP FT232H)

set(PIOFILE ${PROJECT}_${FTCHIP}.pio)

file(MAKE_DIRECTORY ${CMAKE_CURRENT_LIST_DIR}/generated)

# Generate PIO header
pico_generate_pio_header(${PROJECT}
${CMAKE_CURRENT_LIST_DIR}/${PIOFILE}
OUTPUT_DIR
${CMAKE_CURRENT_LIST_DIR}/generated
)

[cmake] CMake Error at /home/vbh/.pico-sdk/sdk/2.1.0/tools/CMakeLists.txt:182 (add_custom_target):
[cmake] add_custom_target called with invalid target name
[cmake] "/home/vbh/PicoProjects/vtpusb/picoSrc/sft/vtpRead/_FT245.pio_OUTPUT_DIR_pio_h".
[cmake] Target names may not contain a slash. Use ADD_CUSTOM_COMMAND to generate
[cmake] files.
[cmake] Call Stack (most recent call first):
[cmake] CMakeLists.txt:44 (pico_generate_pio_header)

Note that "OUTPUT_DIR" is apparently used to place the generated .h file in a directory in the 2812 case while in the latter case it is appended to the 2nd parameter of pico_generate_pio_header() along with _pio.h
Since there is no documentation defining the acceptable parameters and their ranges, it is difficult to understand without forensic programming what the circumstances are for the use of "OUTPUT_DIR" or any other parameters that may not have examples.

In summary, the CMake functions used to access features of the PICO family may need to be fully documented as to semantic function together with parameters and their ranges so as to minimize both developer effort and support requests.
vtpRead.zip

Enclosed are the following files: vtpRead.c, vtpRead_FT245.pio, vtpRead_FT232H.pio, include/vtpRead.h and CMakeLists.txt

[lurch]

Hopefully @kilograham will be able to provide more information after the holidays, but in the meantime:

• There's a brief mention of pico_generate_pio_header in section 3.2.1.3 of https://datasheets.raspberrypi.com/pico/raspberry-pi-pico-c-sdk.pdf
• The implementation of the pico_generate_pio_header function is at https://github.com/raspberrypi/pico-sdk/blob/develop/tools/CMakeLists.txt#L156

So if you sprinkle some message() calls inside pico_generate_pio_header to print out the value of various variables, maybe you'll be able to figure out where it's going wrong? Which version of cmake do you have installed?

[VBHunt]

Thanks Lurch for the superb information. I read the brief mention in the sdk doc but did not know where to look for the implementation of pico_generate_pio_header to dig out the usage. I may now be able to figure out what the range and usage of the parameters are to fijx my problem. I hope that the documentation experts will fully document this important tool ( along with clear and concise documentation of the PIO and it's operation. e.g. At what time in a PIO instruction to the side-effect I/Os take place? Is it at the beginning, somewhere in the middle or at the end (give or take a few nanoseconds)?)
Again thanks for the assistance. You have likely saved me several hours of forensic investigation.