search

libhal / libhal.github.io

Organization wide repo for docs, assets, and tools any other static information
Apache License 2.0
0 stars 3 forks source link

Add discussion about preconditions & error surface area to interface tutorial #35

Open kammce opened 3 months ago

kammce commented 3 months ago

The stance is that interfaces should be designed around the philosophy that all API calls do not need to concern themselves with preconditions before being called. The API call may not behave has the user may have wanted but it will work with the conditions it currently has.

For example, if you call hal::spi::transfer and you forgot to set the clock rate, transfer wills till work, but it will use a slower clock rate. This is fine. transfer does not have any preconditions, just that the configuration is undefined from the point of view of the application and depends on what it configures at the start.

Any API that requires preconditions should be closely evaluated and a means to make the API no longer have a precondition should be sought out. We cannot avoid preconditions everywhere, but we should try to.

I'm conflicted on how this will work for networking. And I'll just leave that comment for now.

kammce commented 3 months ago

This may require some research and discussion.