Offer safe PLL's

[DigitalBrains1]

We have the convention that if a function can lead to timing violations, we prefix the name of that function with unsafe. The functions in Clash.Intel.ClockGen and Clash.Xilinx.ClockGen before this PR do not follow that convention. The locked output of these clock generators is an asynchronous signal. All our examples showed the correct way to handle this, but it should be called out by an unsafe prefix, and we should offer an easy-to-use alternative. It was too easy for a user to forget to synchronise the locked signal.

This PR deprecates the Intel functions and adds new functions, both a safe variant and, for advanced use cases, an unsafe variant. The safe variant incorporates resetSynchronizer so there's just a ready-to-use Reset instead of the asynchronous locked signal.

For Xilinx, it was decided to not deprecate the functions but rather scrap them altogether and provide new, safe ones with the same name as the old unsafe ones. The functions in Clash 1.6 are so broken that keeping them around as deprecated functions doesn't add much utility for our users; better to bite the bullet. PR #2427 had already changed the API for Xilinx, by the way.

• All documentation and examples now shows the safe variants where that makes sense. Since we recommend people always use a PLL, in practice that meant we recommended people to use functions like unsafeFromActiveLow. Now people can follow the recommendation without being exposed to unsafe stuff.
• All clock generators support multiple output clocks.
• It is no longer required to give a clock generator a name. Instead, people can set the name of the instance with Clash.Magic.setName if they need a predictable name.
• Intel PLL's now account for the ResetPolarity of the input domain instead of always expecting an active-high signal.

Still TODO:

• Write a changelog entry (see changelog/README.md)
• Check copyright notices are up to date in edited files

[christiaanb]

LGTM

Only some minor details w.r.t. documentation: The Intel docs say things about Xilinx.

[DigitalBrains1]

Ah, I had neglected to mention that I was still working on the Intel documentation, I simply copied the Xilinx one and still need to adjust those things.

[DigitalBrains1]

Since your review, I've made the following changes:

• Finished documentation for Clash.Intel.ClockGen

• For both Xilinx and Intel: switched the example to use the implicit Prelude as I think this is more familiar to a novice

• Again for both: added an example of the use of the unsafe functions

• Adjusted the commit message for the Improve readability of Clash.Clocks.Deriving commit, from No functional change to:

  No functional change, except that the clocks function is now annotated with a CLASH_OPAQUE "pragma" rather than a mere NOINLINE.

  We discovered this had been overlooked for PR Warn against non-opaque primitive functions on GHC >= 9.4 #2511, but since this PR fundamentally changed the code, we decided to adjust it here.