Where to find documentation on GPIO_InitTypeDef ?

[jefazo92]

Hi everyone,

I am student who is new to STM32. I am trying to understand how to program the MCU and noticed GPIO_InitTypeDef data type. I went into the reference manual but did not find anything about it. Is there a document including all the functions a user can apply to the STM32 (and hopefully find information on GPIO_InitTypeDef) ? Thank you in advance.

[Tesla DeLorean]

Grep the source code, most stuff has a lot of the documentation in the comments.

If you are using a suitable IDE you should be able to Right Click and go to the definitions of structures and functions.

[jefazo92]

Hi @Community member​ , thank you for replying so quickly. I am using the STM32CubeIDE. I am right clicking the data type but nothing happens.

[Tesla DeLorean]

Using Keil here.

Then use "Find in Files" or equivalent to navigate to the source/include file

Probably in stm32xyz_hal_gpio.h

/**
 * @brief GPIO Init structure definition
 */
typedef struct
{
 uint32_t Pin; /*!< Specifies the GPIO pins to be configured.
 This parameter can be any value of @ref GPIO_pins_define */
 
 uint32_t Mode; /*!< Specifies the operating mode for the selected pins.
 This parameter can be a value of @ref GPIO_mode_define */
 
 uint32_t Pull; /*!< Specifies the Pull-up or Pull-Down activation for the selected pins.
 This parameter can be a value of @ref GPIO_pull_define */
 
 uint32_t Speed; /*!< Specifies the speed for the selected pins.
 This parameter can be a value of @ref GPIO_speed_define */
 
 uint32_t Alternate; /*!< Peripheral to be connected to the selected pins.
 This parameter can be a value of @ref GPIO_Alternate_function_selection */
}GPIO_InitTypeDef;

[jefazo92]

​Hi @Community member​  thank you again for your quick answers to both posts. For the CubeIDE I've found that when you hover over keywords highlighted in green, like GPIO_InitTypeDef, the information appears. But what I am trying to understand now is why

GPIO_InitTypeDef GPIO_InitStruct = {0};

Why is is it set to 0 and not any other number ?

[waclawek.jan]

This is general C, not STM32-specific. This initializes the first member of given struct explicitly to 0 and other members implicitly to 0. This mimics the same behaviour than if the struct would be defined as a global uninitialised variable (when it is entirely zeroed at the program entry). Local variables without explicit initializer have undefined value.

The "library" is deliberately designed so that zero init struct members "do no harm" (i.e. usually don't change the reset default values, or previously set values of the peripheral registers).

JW

[jefazo92]

@Community member​  Thank you for your reply. Where can I find more information about this ? Did you find this information in the STM32G4 HAL doc ? Or did you know this from previous experience with microcontrollers ?

[Pavel A.]

> I am using the STM32CubeIDE. I am right clicking the data type but nothing happens.

This should work. If it does not, right click on the project (in the project explorer tree) and select Index-> Rebuild.

If still won't find the declaration - check the indexing settings in Eclipse

Window-> Preferences-> C/C++ -> Indexer

(Note: you want to find declaration of the GPIO_InitTypeDef struct, not the GPIO_InitStruct variable - the latter is trivial =)

-- pa

[berendi]

> Is there a document including all the functions a user can apply to the STM32

It is the reference manual and the datasheet. The reference manual documents the interface to the user program, the datasheet documents the external connections.

The full functionality of the microcontroller is exposed through the hardware registers, which are extensively documented in the reference manual.

> and hopefully find information on GPIO_InitTypeDef

GPIO_InitTypeDef belongs to a software library (called HAL - Hardware Abstraction Layer for no apparent reason) which can be used to program STM32 microcontrollers. The HAL library however does not cover all the functionality of the MCU, and the documentation mostly consists of one-liner Captain Obvious descriptions of its functions and data structures, not very suitable for understanding the workings of the microcontroller. Fortunately it is not needed to program the MCU, there is nothing in HAL that can't be achieved using the well documented register interface.

[jefazo92]

Thank you for your reply @berendi​ and everyone else for your comments and support, I was looking at the docs (reference manual) provided in "Sofware and Tools" for the NUCLEO-G474RE but the HAL document was not included there. It is really frustating that not all documents are included in one same section (this goes for all MCUs) making the user to search endlessly until the document is found in another section not specific to the MCU being used.

[waclawek.jan]

@berendi​ had a rant on the pros and cons of using "libraries" or not - maybe he could link it in here.

Imo this is educational thus generational thing - novices are taught and told to expect things to come in "libraries" and manufacturers like ST are just too happy to supply them, as they are a good tool to lock in the user. The downside is, that manufacturers such as ST then refuse to produce clean and concise examples, which are the real pinnacle of support and education (together with accompanying documentation, a.k.a. Application notes).

JW

[berendi]

Here you are

https://community.st.com/s/question/0D70X000007RFqt/writing-own-drivers-vs-hal-for-professional-project

[waclawek.jan]

Oh. How did you manage link to the inidividual post?

Jan

[waclawek.jan]

> Where can I find more information about this ? Did you find this information in the STM32G4 HAL doc ?

> Or did you know this from previous experience with microcontrollers ?

As I've said, this is general C, so the source is any C textbook. Primary source is the C standard, e.g. C99, 6.7.8 Initialization #21:

If there are fewer initializers in a brace-enclosed list than there are elements or members

of an aggregate, or fewer characters in a string literal used to initialize an array of known

size than there are elements in the array, the remainder of the aggregate shall be

initialized implicitly the same as objects that have static storage duration.

The need for a safe initializer for the struct is underpinned by the fact that uninitialized local init-structs were perhaps the most common problem with the ST "libraries" encountered on this forum in the past, before CubeMX started to generate this ={0} initializer.

SPL provided initialization functions for the structs, and its usage was written in SPL's manual, but nobody read it. Eg. in a randomly chosen https://www.st.com/content/ccc/resource/technical/document/user_manual/59/2d/ab/ad/f8/29/49/d6/DM00023896.pdf/files/DM00023896.pdf/jcr:content/translations/en.DM00023896.pdf chapter 2.3 Peripheral initialization and configuration :

[...] Configure only a few members of the structure: in this case modify the

PPP_InitStructure variable that has been already filled by a call to the

PPP_StructInit(..) function. This ensures that the other members of the

PPP_InitStructure variable are initialized to the appropriate values (in most cases

their default values).

But even SPL strived to keep the "safe values to be zero" unwritten rule, as that increased the chance that even if the user did not fill in the whole init-struct, as long as it was global, it was zeroed by the rules of C.

Cube continued this practice and then as I've said CubeMX included the explicit initializer, but I'm not sure it's documented anywhere.

As you've might have guessed, I don't use any of these "libraries".

JW