Clarity of reference material for PIO operations such as the JMP and IN Instructions .

[VBruceHunt]

The current PIO Instruction Set Reference in the "Raspberry Pi Pico-series C/C++ SDK" (build-date 2024-11-25, build version 66f614e-clean) fails to clearly describe the semantic action of the instruction. This is a request for accurate detailed descriptions of the semantic actions performed by the instructions. For example:

Jump
The term EXECCTRL_JMP_PIN appears exactly once in the SDK and is nowhere defined. As reference material every technical term should be clearly defined. In particular it is unclear where and how one uses it to select a specific GPIO pin and thus renders the description to be tantalizingly unhelpful. Because the author knows the meaning and usage of the term sadly it does not translate to the reader.

The term SHIFTCTRL_PULL_THRESH appears exactly three times in the document (for JMP, OUT and PULL) and is not defined. It appears that the following clause and sentence is intended to clarify, "(The same as for autopull), and (This is the same threshold used by autopull.)" . The term "autopull threshold" appears twice in the SDK. The first appearance is in a dependent clause in the description of the "% c-sdk {" parameters (see the last bullet point on page 44 of section 3.2 "Getting started with PIO". Here we learn that autopull threshold meaning is inferred from the following:

".True for autopull. 32 or 24 for the number of bits for the autopull threshold, i.e. the point at which the state machine triggers a refill of the OSR, depending on whether the LEDs are RGB or RGBW."

So we can surmise from the above description that the autopull threshold is measured in bits and not bytes, half-words or words. This crucial information is obscurely hidden in an example. It should be clearly defined in the reference material and the suspected (hoped for?) relation to SHIFTCTRL_PULL_THRESH clearly revealed there as well.

The second appearance of the term autopull threshold is in the parameter, bits_per_word comment of a signature for the sm_config_set_in_shift function affirming our supposition of its meaning. This appears in a comment on page 607 of the SDK for a term initially indirectly used ( SHIFTCTRL_PULL_THRESH appears to mean autopull threshold ) on page 64 of the SDK.

The technical terms directly defining the operational characteristics of a referenced capability used in a reference document should be clearly defined so that the reader can directly apply the information. This is after all the purpose of reference documentation.

IN
The term push threshold is clearly defined as a parameter definition to the API signature sm_config_set_in_shift on page 232 used for reference documentation on page 66.

The IN instruction shifts data into the ISR but nowhere in the description does it tell you where in the ISR are the bits inserted. Since there is no means to select the insert point, this suggests that it is fixed and likely to be either at bit 31 going down or at bit 0 going up. Again the lack of clarity in description leads to forensic programming to discover how it really works. This is important because the shift direction is often determined by the insert point, the endiness of the processor and the transmission order of incoming data.

In summary, the reference information should be complete and clear; especially is the use of essential technical terms that describe operations.