Xilinx / Xilinx/embeddedsw

XSpiPs_CfgInitialize() documentation should mention zeroing out XSpiPs before passing it

Open
#372 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
HTML
Stars
1.2k
Forks
1.1k
PR merge metrics
No merged PRs in 30d

Description

Hi, I recently ran into an issue using XSpiPs_CfgInitialize() where I got undefined behavior. The documentation for the function describes it like so:

Initializes a specific XSpiPs instance such that the driver is ready to use.

With this in mind, for my use case, I stack-allocated an XSpiPs, left it in an uninitialized state (since I expected the API to properly initialize it for me), passed it in and called it a day. Things worked fine for a while, but eventually, I intermittently started receiving XST_DEVICE_IS_STARTED back from it. I was very puzzled until I saw the API's implementation:

s32 XSpiPs_CfgInitialize(XSpiPs *InstancePtr, const XSpiPs_Config *ConfigPtr,
			 u32 EffectiveAddr)
{
	s32 Status;
	Xil_AssertNonvoid(InstancePtr != NULL);
	Xil_AssertNonvoid(ConfigPtr != NULL);

	/*
	 * If the device is busy, disallow the initialize and return a status
	 * indicating it is already started. This allows the user to stop the
	 * device and re-initialize, but prevents a user from inadvertently
	 * initializing. This assumes the busy flag is cleared at startup.
	 */
	if (InstancePtr->IsBusy == TRUE) {
		Status = (s32)XST_DEVICE_IS_STARTED;
	} else {
       // start setting default values...
       ...
}

The issue was the if (InstancePtr->IsBusy == TRUE) check reading into my garbage stack memory. Now, I know it's common in C to defensively memset such types to zero them out, so perhaps it was my fault. I'm actually working with the API through Rust FFI so that habit kinda left my mind. I also realize that most users of the API would probably statically-allocate an XSpiPs so that it's initialized to zero naturally, rather than stack-allocate it. Regardless though, I think things like this should be noted in user-facing comments/docs to save them some headache.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start from the linked XSpiPs_CfgInitialize() API documentation and locate the source declaration or comment that generates it. Document the zero-initialization requirement described in the issue, then inspect the generated API documentation to confirm the guidance is visible to users.

Written by the indexing model from the issue text.

Assessment

Tech stack
c
Domain
documentation, embedded-iot
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.