sim3u167bgm SOC support

[M1cha]

Introduction

GARDENA uses a sim3u167bgm module in their smart Gateway and I've ported zephyr to it. The work is already done in terms of what is needed for that product and we want to mainline this now so others can benefit from it as well.

Problem description

Support for the SOC, GARDENAs SOM and every driver it's currently using should be merged.

Proposed change

This issue serves as an overview of this port and will link to all related PRs.

Detailed RFC

In this section of the document the target audience is the dev team. Upon
reading this section each engineer should have a rather clear picture of what
needs to be done in order to implement the described feature.

HAL

The port used silab's SI32 HAL from the Precision32 IDE.
This is only used for the register definitions. The drivers are fully zephyr-native.

It might be worth taking a look at the license That's linked to in every file's copyright header.

Drivers

We currently only intend to add support for drivers that we need. See the task list for a list of which ones we wrote.

There won't be a pinctrl driver since the hardware is too limited for that(you can't change the config at runtime without temporarily disconnecting all pins), but my port allows using pinctrl devicetree nodes to define the initial configuration.

Board

The intention is to only add support for the GARDENA smart gateway. It's readily available and can be used by anyone to develop software because root access is provided by default via UART. SPI, USART0, a few GPIOs, the reset pin and SWD are connected to the Linux SoC.

If it's a hard requirement to support Silabs official development board as well we can do that but it's currently not planned.

Dependencies

None that aren't already mainline. The PRs will contain everything that's needed.

Concerns and Unresolved Questions

• HAL license compatibility
• do we need to support the official devkit?

Task List

• add si32 HAL to hal_silabs add si32 HAL hal_silabs#29
• add AHB clock control driver SIM3U support #57871
• add APB clock control driver SIM3U support #57871
• add PLL clock control driver SIM3U support #57871
• add flash driver SIM3U support #57871
• add GPIO driver for ports 0-3 SIM3U support #57871
• add GPIO driver for port 4 (high drive) SIM3U support #57871
• add USART driver SIM3U support #57871
• add SPI driver SIM3U support #57871
• add sim3u167bgm SOC SIM3U support #57871
• add GARDENA board SIM3U support #57871

[M1cha]

About the license, this is the comment header from the source files:

//------------------------------------------------------------------------------
// Copyright (c) 2012 by Silicon Laboratories. 
// All rights reserved. This program and the accompanying materials
// are made available under the terms of the Silicon Laboratories End User 
// License Agreement which accompanies this distribution, and is available at
// http://developer.silabs.com/legal/version/v10/License_Agreement_v10.htm
// Original content and implementation provided by Silicon Laboratories.
//------------------------------------------------------------------------------

This is the "Silicon Laboratories End User License Agreement which accompanies this distribution" (Documentation/Silabs_License_Agreement.txt):
Silabs_License_Agreement.txt

This is what you can find at http://developer.silabs.com/legal/version/v10/License_Agreement_v10.htm as of today (2023-02-03):

END-USER LICENSE AGREEMENT
IMPORTANT:  READ CAREFULLY
BEFORE AGREEING TO TERMS

THIS PRODUCT CONTAINS CERTAIN COMPUTER PROGRAMS AND OTHER THIRD PARTY PROPRIETARY MATERIAL ("LICENSED PRODUCT"), THE USE OF WHICH IS SUBJECT TO THIS END-USER LICENSE AGREEMENT. INDICATING YOUR AGREEMENT CONSTITUTES YOUR AND (IF APPLICABLE) YOUR COMPANY'S ASSENT TO AND ACCEPTANCE OF THIS END-USER LICENSE AGREEMENT (THE "LICENSE" OR "AGREEMENT"). IF YOU DO NOT AGREE WITH ALL OF THE TERMS, YOU MUST NOT USE THIS PRODUCT. WRITTEN APPROVAL IS NOT A PREREQUISITE TO THE VALIDITY OR ENFORCEABILITY OF THIS AGREEMENT, AND NO SOLICITATION OF SUCH WRITTEN APPROVAL BY OR ON BEHALF OF SILICON LABORATORIES, INC. ("SILICON LABS") SHALL BE CONSTRUED AS AN INFERENCE TO THE CONTRARY. IF THESE TERMS ARE CONSIDERED AN OFFER BY SILICON LABS, ACCEPTANCE IS EXPRESSLY LIMITED TO THESE TERMS.

LICENSE AND WARRANTY: The Licensed Product and the embedded Software which is made the subject of this License is either the property of SILICON LABS or a third party from whom SILICON LABS has the authorization to distribute to you subject to the terms of this Agreement. This Licensed Product is protected by state, federal, and international copyright law. Although SILICON LABS continues to own the Licensed Product and the right to distribute the embedded third party Software, you will have certain rights to use the Licensed Product and the embedded Software after your acceptance of this License. Except as may be modified by a license addendum which accompanies this License, your rights and obligations with respect to the use of this Product and the embedded software are as follows:

1. AS APPROPRIATE WITH RESPECT TO THE LICENSED PRODUCT, YOU MAY: Use, copy, distribute and make derivative works of the Software for any purpose, including commercial applications, subject to the following restrictions: (i) The origin of this software must not be misrepresented; (ii) you must not claim that you wrote the original software; (iii) altered source versions must be plainly marked as such, and must not be misrepresented as being the original software; and (iv) any notices contained in the Software may not be removed or altered, including notices in source code versions.

2. YOU MAY NOT: (A) Sublicense, assign, rent or lease any portion of the Licensed Product or the embedded Software; or (B) Remove any product identification, copyright or other notices that appear on the Licensed Product or embedded Software.

3. Limited Use: Use of any of the Software is strictly limited to use in systems containing one or more SILICON LABS products when the Software is enabled to be functional. Any unauthorized use is expressly prohibited and will constitute a breach of this Agreement.

4. Warranty: SILICON LABS does not warrant that the Licensed Product or embedded Software will meet your requirements or that operation of the Licensed Product will be uninterrupted or that the embedded Software will be error-free. You agree that the Licensed Product is provided "AS IS" and that SILICON LABS makes no warranty as to the Licensed Product or embedded Software. SILICON LABS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT, RELATED TO THE SOFTWARE, ITS USE OR ANY INABILITY TO USE IT, THE RESULTS OF ITS USE AND THIS AGREEMENT.

YOU MAY HAVE OTHER RIGHTS, WHICH VARY FROM STATE TO STATE.

5. Disclaimer of Damages: IN NO EVENT WILL SILICON LABS BE LIABLE TO YOU FOR ANY SPECIAL, CONSEQUENTIAL, INDIRECT, OR SIMILAR DAMAGES, INCLUDING ANY LOST PROFITS OR LOST DATA ARISING OUT OF THE USE OR INABILITY TO USE THE LICENSED PRODUCT EVEN IF SILICON LABS HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

SOME STATES DO NOT ALLOW THE LIMITATION OR EXCLUSION OF LIABILITY FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES. SO THE ABOVE LIMITATION OR EXCLUSION MAY NOT APPLY TO YOU.

IN NO CASE SHALL SILICON LABS' LIABILITY EXCEED THE PURCHASE PRICE FOR THE LICENSED PRODUCT. The disclaimers and limitations set forth above will apply regardless of whether you accept the Licensed Software.

6. Term and Termination: The term of this Agreement and the License granted herein shall begin upon use of the Licensed Product and continue in perpetuity unless you breach any of the obligations set out under this Agreement. Upon your breach of this Agreement by you, the license granted hereunder shall terminate immediately and you shall cease all use of the Licensed Products and return same as well as any copies of the Licensed Product and/or embedded Software to SILICON LABS immediately. Termination of this License upon your breach is only one remedy available to SILICON LABS. In addition to termination of this Agreement upon your breach, SILICON LABS shall be entitled to seek any and all other available remedies, at law or at equity, arising from your breach.

7. Export: You shall comply with all applicable federal, provincial, state and local laws, regulations and ordinances including but not limited to applicable U.S. Export Administration Laws and Regulations. You shall not export or re-export, or allow the export or re-export of the Licensed Product, any component of the Licensed Product, or any copy of the embedded Software in violation of any such restrictions, laws or regulations, or to Cuba, Libya, North Korea, Iran, Iraq, or Rwanda or to any Group D:1 or E:2 country (or any national of such country) specified in the then current Supplement No. 1 to Part 740, or, in violation of the embargo provisions in Part 746, of the U.S. Export Administration Regulations (or any successor regulations or supplement), except in compliance with and with all licenses and approvals required under applicable export laws and regulations, including without limitation, those of the U.S. Department of Commerce.

8. General: This Agreement will be governed by the laws of the State of Texas and any applicable federal laws or regulations. The waiver by either Party of any default or breach of this Agreement shall not constitute a waiver of any other or subsequent default or breach. This Agreement constitutes the complete and exclusive statement of the mutual understanding between you and SILICON LABS with respect to this subject matter herein. This Agreement may only be modified by a written addendum, which has been signed by both you and SILICON LABS. Should you have any questions concerning this Agreement, or if you desire to contact SILICON LABS for any reason, please write:

Silicon Laboratories, Inc.
400 West Cesar Chavez
Austin, Texas 78701, U.S.A.

While the distributed license is proprietary since it says things like Use only one copy of any version of the Licensed Product, the online version seems like a custom, yet permissive license with phrases like YOU MAY: Use, copy, distribute and make derivative works of the Software. That means They've updated the License behind that URL at some point even though it still has the same URL, name and version. I don't know what this means legally or what Silicon Labs' stance is on this but I guess the safest way is to assume that the shipped license has priority which would mean that we can't use the HAL.

Unless an official Silicon Labs representative steps in and gives their green light I don't think we can merge this.
I might pick up on Christian Taedckes work for generating an SVD from the reference manual instead and adjust my drivers accordingly. The change should be minimal given both the HAL and the SVD provide 1:1 register abstractions. I'd also be able to verify the results by comparing the resulting binaries.

Any comments on that?
CC: @chrta

[rettichschnidi]

FYI: I notified GARDENAs SiLabs FAE on 2023-03-02 about this issue. SiLabs sent a question back about the HAL version used on 2023-04-28, which we answered the same day.

Will post updates here once things progress.

[silabs-Joe]

I am a Silicon Labs employee. I've checked with our legal team and it is their opinion that the newer license (linked in the header files) applies to the HAL files, and it is ok to port code with the Si32 HAL register definitions to the Zephyr OS project. Please let me know if you have any questions.

Best regards,
Joe Stine

[M1cha]

Thanks a lot. I've created the HAL-PR and linked it in this issues description. I've also added a link to the full code of the current port.

[M1cha]

@silabs-Joe Unfortunately the license is still not compatible: zephyrproject-rtos/hal_silabs#29 (comment)

[github-actions]

This issue has been marked as stale because it has been open (more than) 60 days with no activity. Remove the stale label or add a comment saying that you would like to have the label removed otherwise this issue will automatically be closed in 14 days. Note, that you can always re-open a closed issue at any time.

[M1cha]

@github-actions I'm still working on it.

[rettichschnidi]

I did some work on top of @M1cha's efforts and created two up-to-date PRs which (hopefully) address all previous problems. Additionally, it is now based on the official SiLabs development kit.

PRs:

• Add si32 HAL hal_silabs#66
• Add initial Silabs SiM3U support #76677