Add a documentation file to describe the Device Tree bindings for the
Ethernet Media Access Controller found in the J-Core family of SoCs.
Signed-off-by: Artur Rojek <contact@artur-rojek.eu>
---
.../devicetree/bindings/net/jcore,emac.yaml | 42 +++++++++++++++++++
1 file changed, 42 insertions(+)
create mode 100644 Documentation/devicetree/bindings/net/jcore,emac.yaml
diff --git a/Documentation/devicetree/bindings/net/jcore,emac.yaml b/Documentation/devicetree/bindings/net/jcore,emac.yaml
new file mode 100644
index 000000000000..a4384f7ed83d
--- /dev/null
+++ b/Documentation/devicetree/bindings/net/jcore,emac.yaml
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/net/jcore,emac.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: J-Core Ethernet Media Access Controller
+
+description: |
+ This node provides properties for configuring the Ethernet MAC found
+ in the J-Core family of SoCs.
+
+maintainers:
+ - Artur Rojek <contact@artur-rojek.eu>
+
+properties:
+ compatible:
+ const: jcore,emac
+
+ reg:
+ maxItems: 1
+
+ interrupts:
+ maxItems: 1
+
+required:
+ - compatible
+ - reg
+ - interrupts
+
+allOf:
+ - $ref: ethernet-controller.yaml#
+
+additionalProperties: false
+
+examples:
+ - |
+ ethernet@10000 {
+ compatible = "jcore,emac";
+ reg = <0x10000 0x2000>;
+ interrupts = <0x11>;
+ };
--
2.50.1On 15/08/2025 21:48, Artur Rojek wrote:
> Add a documentation file to describe the Device Tree bindings for the
> Ethernet Media Access Controller found in the J-Core family of SoCs.
>
> Signed-off-by: Artur Rojek <contact@artur-rojek.eu>
> ---
> .../devicetree/bindings/net/jcore,emac.yaml | 42 +++++++++++++++++++
> 1 file changed, 42 insertions(+)
> create mode 100644 Documentation/devicetree/bindings/net/jcore,emac.yaml
>
> diff --git a/Documentation/devicetree/bindings/net/jcore,emac.yaml b/Documentation/devicetree/bindings/net/jcore,emac.yaml
> new file mode 100644
> index 000000000000..a4384f7ed83d
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/net/jcore,emac.yaml
> @@ -0,0 +1,42 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/net/jcore,emac.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: J-Core Ethernet Media Access Controller
> +
> +description: |
> + This node provides properties for configuring the Ethernet MAC found
> + in the J-Core family of SoCs.
> +
> +maintainers:
> + - Artur Rojek <contact@artur-rojek.eu>
> +
> +properties:
> + compatible:
> + const: jcore,emac
You need SoC-based compatibles. And then also rename the file to match it.
> +
> + reg:
> + maxItems: 1
> +
> + interrupts:
> + maxItems: 1
> +
> +required:
> + - compatible
> + - reg
> + - interrupts
> +
> +allOf:
> + - $ref: ethernet-controller.yaml#
> +
> +additionalProperties: false
unevaluatedProperties instead
> +
> +examples:
> + - |
> + ethernet@10000 {
> + compatible = "jcore,emac";
> + reg = <0x10000 0x2000>;
> + interrupts = <0x11>;
That's not hex...
> + };
Best regards,
Krzysztof
On 2025-08-16 10:19, Krzysztof Kozlowski wrote:
> On 15/08/2025 21:48, Artur Rojek wrote:
>> Add a documentation file to describe the Device Tree bindings for the
>> Ethernet Media Access Controller found in the J-Core family of SoCs.
>>
>> Signed-off-by: Artur Rojek <contact@artur-rojek.eu>
>> ---
>> .../devicetree/bindings/net/jcore,emac.yaml | 42
>> +++++++++++++++++++
>> 1 file changed, 42 insertions(+)
>> create mode 100644
>> Documentation/devicetree/bindings/net/jcore,emac.yaml
>>
>> diff --git a/Documentation/devicetree/bindings/net/jcore,emac.yaml
>> b/Documentation/devicetree/bindings/net/jcore,emac.yaml
>> new file mode 100644
>> index 000000000000..a4384f7ed83d
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/net/jcore,emac.yaml
>> @@ -0,0 +1,42 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/net/jcore,emac.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: J-Core Ethernet Media Access Controller
>> +
>> +description: |
>> + This node provides properties for configuring the Ethernet MAC
>> found
>> + in the J-Core family of SoCs.
>> +
>> +maintainers:
>> + - Artur Rojek <contact@artur-rojek.eu>
>> +
>> +properties:
>> + compatible:
>> + const: jcore,emac
>
> You need SoC-based compatibles. And then also rename the file to match
> it.
Given how the top-most compatible of the bindings [1] of the board I am
using has "jcore,j2-soc", this driver should probably go with
"jcore,j2-emac".
But as this is an FPGA design, I don't know how widespread the use is
across other jcore derived SoCs (if any?).
I will wait for Jeff (who's design this is) to clarify on that.
PS. Too bad we already have other IP cores following the old pattern:
> $ grep -r "compatible = \"jcore," bindings/ | grep -v "emac"
> bindings/timer/jcore,pit.yaml: compatible = "jcore,pit";
> bindings/spi/jcore,spi.txt: compatible = "jcore,spi2";
> bindings/interrupt-controller/jcore,aic.yaml: compatible =
> "jcore,aic2";
Cheers,
Artur
[1]
https://raw.githubusercontent.com/j-core/jcore-soc/refs/heads/master/targets/boards/turtle_1v1/board.dts
>
>> +
>> + reg:
>> + maxItems: 1
>> +
>> + interrupts:
>> + maxItems: 1
>> +
>> +required:
>> + - compatible
>> + - reg
>> + - interrupts
>> +
>> +allOf:
>> + - $ref: ethernet-controller.yaml#
>> +
>> +additionalProperties: false
>
> unevaluatedProperties instead
>
>> +
>> +examples:
>> + - |
>> + ethernet@10000 {
>> + compatible = "jcore,emac";
>> + reg = <0x10000 0x2000>;
>> + interrupts = <0x11>;
>
> That's not hex...
>
>> + };
>
>
> Best regards,
> Krzysztof
Hi Artur,
On Sat, 16 Aug 2025 at 14:06, Artur Rojek <contact@artur-rojek.eu> wrote:
> On 2025-08-16 10:19, Krzysztof Kozlowski wrote:
> > On 15/08/2025 21:48, Artur Rojek wrote:
> >> Add a documentation file to describe the Device Tree bindings for the
> >> Ethernet Media Access Controller found in the J-Core family of SoCs.
> >>
> >> Signed-off-by: Artur Rojek <contact@artur-rojek.eu>
> >> --- /dev/null
> >> +++ b/Documentation/devicetree/bindings/net/jcore,emac.yaml
> >> +properties:
> >> + compatible:
> >> + const: jcore,emac
> >
> > You need SoC-based compatibles. And then also rename the file to match
> > it.
>
> Given how the top-most compatible of the bindings [1] of the board I am
> using has "jcore,j2-soc", this driver should probably go with
> "jcore,j2-emac".
>
> But as this is an FPGA design, I don't know how widespread the use is
> across other jcore derived SoCs (if any?).
> I will wait for Jeff (who's design this is) to clarify on that.
>
> PS. Too bad we already have other IP cores following the old pattern:
>
> > $ grep -r "compatible = \"jcore," bindings/ | grep -v "emac"
> > bindings/timer/jcore,pit.yaml: compatible = "jcore,pit";
> > bindings/spi/jcore,spi.txt: compatible = "jcore,spi2";
> > bindings/interrupt-controller/jcore,aic.yaml: compatible =
> > "jcore,aic2";
I would go with "jcore,emac", as it is already in use.
If an incompatible version comes up, it should use a different
(versioned?) compatible value.
Gr{oetje,eeting}s,
Geert
--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
On 18/08/2025 08:43, Geert Uytterhoeven wrote: >>> >>> You need SoC-based compatibles. And then also rename the file to match >>> it. >> >> Given how the top-most compatible of the bindings [1] of the board I am >> using has "jcore,j2-soc", this driver should probably go with >> "jcore,j2-emac". >> >> But as this is an FPGA design, I don't know how widespread the use is >> across other jcore derived SoCs (if any?). >> I will wait for Jeff (who's design this is) to clarify on that. >> >> PS. Too bad we already have other IP cores following the old pattern: >> >>> $ grep -r "compatible = \"jcore," bindings/ | grep -v "emac" >>> bindings/timer/jcore,pit.yaml: compatible = "jcore,pit"; >>> bindings/spi/jcore,spi.txt: compatible = "jcore,spi2"; >>> bindings/interrupt-controller/jcore,aic.yaml: compatible = >>> "jcore,aic2"; > > I would go with "jcore,emac", as it is already in use. git grep jcore,emac Gives me zero? > If an incompatible version comes up, it should use a different > (versioned?) compatible value. Versions are allowed if they follow some documented and known vendor SoC versioning scheme. Is this the case here? This is some sort of SoC, right? So it should have actual SoC name? Best regards, Krzysztof
On 8/18/25 03:07, Krzysztof Kozlowski wrote: > On 18/08/2025 08:43, Geert Uytterhoeven wrote: >>>> >>>> You need SoC-based compatibles. And then also rename the file to match >>>> it. >>> >>> Given how the top-most compatible of the bindings [1] of the board I am >>> using has "jcore,j2-soc", this driver should probably go with >>> "jcore,j2-emac". >>> >>> But as this is an FPGA design, I don't know how widespread the use is >>> across other jcore derived SoCs (if any?). >>> I will wait for Jeff (who's design this is) to clarify on that. >>> >>> PS. Too bad we already have other IP cores following the old pattern: >>> >>>> $ grep -r "compatible = \"jcore," bindings/ | grep -v "emac" >>>> bindings/timer/jcore,pit.yaml: compatible = "jcore,pit"; >>>> bindings/spi/jcore,spi.txt: compatible = "jcore,spi2"; >>>> bindings/interrupt-controller/jcore,aic.yaml: compatible = >>>> "jcore,aic2"; >> >> I would go with "jcore,emac", as it is already in use. > > git grep jcore,emac > > Gives me zero? Ethernet support wasn't part of the original kernel submission, in part because we hadn't created the turtle board yet (and _still_ don't have a consumer retail arm to get them out into the world in less than triple digit lot sizes) and the off the shelf FPGA board we were pointing the open source community at circa 2016 (Numato Mimas V2) didn't include ethernet. (Also, our internal driver had half an unfinished IEEE-1588 implementation in it, which we kept meaning to clean out for public consumption. We took a different approach to time synchronization but had never produced a clean driver for external use until Artur decided to do one, which was very nice of him.) >> If an incompatible version comes up, it should use a different >> (versioned?) compatible value. > > Versions are allowed if they follow some documented and known vendor SoC > versioning scheme. Is this the case here? This ethernet implementation hasn't significantly changed in 10 years. Whenever we've needed something else we've done different I/O devices that weren't ethernet. (Even the USB 2.0 "ethernet" isn't technically ethernet, it made our board act as a USB dongle that showed up as an ethernet device to the computer it was plugged into so we could exchange data. No actual ethernetting really occurred, it's kind a like calling slip/ppp or virtio-net an ethernet interface.) In theory gigabit phy would be a successor to this, A) no idea if they would share any code on the VHDL _or_ C side, B) that kind of phy requires 125mhz clock speed which is less cost effective in FPGA, especially now that AMD bought xilinx and doubled the prices. (We've stuck with LPDDR2 for similar reasons, although that's on the shorter term todo list to support. I mean yeah we _could_ use various FPGAs' builtin DDR3 library but we don't because we only want to use stuff we can implement ourselves in ASIC, and we need to not just test the state machine (minimum jedec clock speed 300mhz: kintex or vertex territory) but also commission the analog part of the circuit which is process-specific so you have to pick a fab to have them drawn for if you're avoiding NDAs and per-chip royalties for other people's black box libraries. (Oh, and the higher up the FPGA stack you go the less likely yosys' open source FPGA tools are to work right, and the more NDA-clingy the closed source tools get, which is kind of annoying for a mostly non-US development team. (Lots of testing for $50 FPGAs, far less for $700 FPGAs plus the more lawsuit-happy the vendors get about their crown jewels.) Gowin is trying but those suckers SUCK DOWN power, the ones I've seen are Lattice clones not Xilinx clones (ecp5 exists if we want _bigger_ lattice, the question is _faster_), and going that direction is really just a different kind of ecosystem lock-in...) tl;dr: the 100baseT engine works fine for its niche, we've had no reason to fiddle with it. > This is some sort of SoC, right? So it should have actual SoC name? https://github.com/j-core/jcore-soc Internally we have branches for various projects, which are named after the project not the base platform. It's "j2" because it's the dual processor version. J1 is what we use on ICE-40: https://github.com/j-core/jcore-j1-ghdl They're _mostly_ the same but the j2 SOC build has a whole automatic bus generator thing that pulls in dependencies (it's written in cloture and java) and the broken out j1 builds with just the 01 and 02 stages of the https://github.com/j-core/openlane-vhdl-build open source toolflow/toolchain. (There's a todo item to reorganize the repositories so j1 becomes a git submodule of j2 which would naturally keep them in sync, but it was all originally done in mercurial and needs a bit more massaging. Plus recently we've done a j1 fork removing the hardware multiplier and did a software multiplier toolchain, which hasn't made it over to the J2 side yet because it really needs a better configure mechanism (VHDL generics sure but what _selects_ them...) which REALLY says we need to rewrite the makefiles entirely... it's on the todo list.) Rob P.S. We haven't been pushing to github much since Microsoft bought it. I'm trying to convince Jeff to look at codeberg but he's hung up on the gitea->forgejo fork...
On Aug 18, 2025, at 17:07, Krzysztof Kozlowski <krzk@kernel.org> wrote: > git grep jcore,emac > > Gives me zero? Um, right. It’s not upstream yet. Thanks for your work to get that done, Artur. >> If an incompatible version comes up, it should use a different >> (versioned?) compatible value. > > Versions are allowed if they follow some documented and known vendor SoC versioning scheme. Is this the case here? > > This is some sort of SoC, right? So it should have actual SoC name? No. It’s a generic IP core for multiple SoCs, which do have names. This is the correct naming scheme. All compatible devices and SoCs match properly. J. > Best regards, > Krzysztof
On 18/08/2025 10:21, D. Jeff Dionne wrote: > On Aug 18, 2025, at 17:07, Krzysztof Kozlowski <krzk@kernel.org> wrote: > >> git grep jcore,emac >> >> Gives me zero? > > Um, right. It’s not upstream yet. Thanks for your work to get that done, Artur. > >>> If an incompatible version comes up, it should use a different >>> (versioned?) compatible value. >> >> Versions are allowed if they follow some documented and known vendor SoC versioning scheme. Is this the case here? >> >> This is some sort of SoC, right? So it should have actual SoC name? > > No. It’s a generic IP core for multiple SoCs, which do have names. Then you need other SoCs compatibles, because we do not allow generic items. See writing bindings. > > This is the correct naming scheme. All compatible devices and SoCs match properly. No, it is not a correct naming scheme. Please read writing bindings. Best regards, Krzysztof
Hi Krzysztof,
On Mon, 18 Aug 2025 at 11:58, Krzysztof Kozlowski <krzk@kernel.org> wrote:
> On 18/08/2025 10:21, D. Jeff Dionne wrote:
> > On Aug 18, 2025, at 17:07, Krzysztof Kozlowski <krzk@kernel.org> wrote:
> >> git grep jcore,emac
> >>
> >> Gives me zero?
> >
> > Um, right. It’s not upstream yet. Thanks for your work to get that done, Artur.
> >
> >>> If an incompatible version comes up, it should use a different
> >>> (versioned?) compatible value.
> >>
> >> Versions are allowed if they follow some documented and known vendor SoC versioning scheme. Is this the case here?
> >>
> >> This is some sort of SoC, right? So it should have actual SoC name?
> >
> > No. It’s a generic IP core for multiple SoCs, which do have names.
>
> Then you need other SoCs compatibles, because we do not allow generic
> items. See writing bindings.
>
> > This is the correct naming scheme. All compatible devices and SoCs match properly.
>
> No, it is not a correct naming scheme. Please read writing bindings.
Can we please relax this for this specific compatible value?
All other devices in this specific hardware implementation were
accepted without SoC-specific compatible values ca. 9 years ago. AFAIK
the Ethernet MAC was the sole missing piece, because its Linux driver
was never attempted to be upstreamed before.
Thanks!
Gr{oetje,eeting}s,
Geert
--
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org
In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
-- Linus Torvalds
On 18/08/2025 12:57, Geert Uytterhoeven wrote: >>> >>> No. It’s a generic IP core for multiple SoCs, which do have names. >> >> Then you need other SoCs compatibles, because we do not allow generic >> items. See writing bindings. >> >>> This is the correct naming scheme. All compatible devices and SoCs match properly. >> >> No, it is not a correct naming scheme. Please read writing bindings. > > Can we please relax this for this specific compatible value? We can... > All other devices in this specific hardware implementation were > accepted without SoC-specific compatible values ca. 9 years ago. AFAIK > the Ethernet MAC was the sole missing piece, because its Linux driver > was never attempted to be upstreamed before. ...just provide some context and rationale in the commit msg. Some (different) people pick up some irrelevant commits and use them as argument in different discussions in style: it was allowed there, so I can do the same. Best regards, Krzysztof
Something like: J-Core SoCs are assembled with an SoC generator tool from standard components. An SoC has a ROM from soc_gen with a Device Tree binary included. Therefore, J-Core SoC devices are designed to ‘just work’ with linux, but this means the DT entires are generic, slightly different than standard device tree practice. J > On Aug 18, 2025, at 22:41, Krzysztof Kozlowski <krzk@kernel.org> wrote: > > On 18/08/2025 12:57, Geert Uytterhoeven wrote: >>>> >>>> No. It’s a generic IP core for multiple SoCs, which do have names. >>> >>> Then you need other SoCs compatibles, because we do not allow generic >>> items. See writing bindings. >>> >>>> This is the correct naming scheme. All compatible devices and SoCs match properly. >>> >>> No, it is not a correct naming scheme. Please read writing bindings. >> >> Can we please relax this for this specific compatible value? > > We can... > >> All other devices in this specific hardware implementation were >> accepted without SoC-specific compatible values ca. 9 years ago. AFAIK >> the Ethernet MAC was the sole missing piece, because its Linux driver >> was never attempted to be upstreamed before. > > ...just provide some context and rationale in the commit msg. > > Some (different) people pick up some irrelevant commits and use them as > argument in different discussions in style: it was allowed there, so I > can do the same. > > Best regards, > Krzysztof
On Mon, Aug 18, 2025 at 10:55:51PM +0900, D. Jeff Dionne wrote: > Something like: Please don't top post to maillists. > J-Core SoCs are assembled with an SoC generator tool from standard > components. An SoC has a ROM from soc_gen with a Device Tree binary > included. Therefore, J-Core SoC devices are designed to ‘just work’ > with linux, but this means the DT entires are generic, slightly > different than standard device tree practice. Yes. Though doesn't the SoC generator evolve/change? New features in the IP blocks, bug fixes, etc. Soft IP for FPGAs is similar I think. There we typically just require the versioning schema be documented and correlate to the IP versions (vs. made up v1, v2, v3). This is all pretty niche I think, so I'm not too concerned about what you do here. Rob > > J > > > On Aug 18, 2025, at 22:41, Krzysztof Kozlowski <krzk@kernel.org> wrote: > > > > On 18/08/2025 12:57, Geert Uytterhoeven wrote: > >>>> > >>>> No. It’s a generic IP core for multiple SoCs, which do have names. > >>> > >>> Then you need other SoCs compatibles, because we do not allow generic > >>> items. See writing bindings. > >>> > >>>> This is the correct naming scheme. All compatible devices and SoCs match properly. > >>> > >>> No, it is not a correct naming scheme. Please read writing bindings. > >> > >> Can we please relax this for this specific compatible value? > > > > We can... > > > >> All other devices in this specific hardware implementation were > >> accepted without SoC-specific compatible values ca. 9 years ago. AFAIK > >> the Ethernet MAC was the sole missing piece, because its Linux driver > >> was never attempted to be upstreamed before. > > > > ...just provide some context and rationale in the commit msg. > > > > Some (different) people pick up some irrelevant commits and use them as > > argument in different discussions in style: it was allowed there, so I > > can do the same. > > > > Best regards, > > Krzysztof >
On 8/20/25 16:39, Rob Herring wrote: > On Mon, Aug 18, 2025 at 10:55:51PM +0900, D. Jeff Dionne wrote: >> J-Core SoCs are assembled with an SoC generator tool from standard >> components. An SoC has a ROM from soc_gen with a Device Tree binary >> included. Therefore, J-Core SoC devices are designed to ‘just work’ >> with linux, but this means the DT entires are generic, slightly >> different than standard device tree practice. > > Yes. Though doesn't the SoC generator evolve/change? New features in the > IP blocks, bug fixes, etc. Soft IP for FPGAs is similar I think. The j-core guys almost never change the hardware interface on a deployed I/O device: when the existing interface is too limiting they do a new design with a different interface. (You'll notice in the github soc_top, components/ has ddr and ddr2, and components/misc has aic and aic2 from when the interrupt controller changed, for example. Those aren't version numbers, those are rewrites.) Outputting a different constellation of devices/busses from the SOC generator is more akin to running "make menuconfig". There isn't an ancestor/descendant relationship there, it's a generator working from a configuration to instantiate and connect existing components. > There > we typically just require the versioning schema be documented and > correlate to the IP versions (vs. made up v1, v2, v3). There hasn't been a new version of the 100baseT specification recently. The same chunk of bitstream is still driving the same PHY chips on the boards (or compatible, long out of patent) via the same small parallel bus at 50mhz. The engineers are no more interested in changing the kernel side interface than they are in changing the PHY side interface. > This is all pretty niche I think, so I'm not too concerned about what > you do here. Eh, not that niche. Just hardware development culture rather than software development culture. What's the model number on your microwave? If you need to replace it, how many versions will you advance? Chip model numbers tend to be assigned by marketing well after the fact, and don't necessarily have a linear relationship even for the big boys making central components other people build entire systems around: https://en.wikipedia.org/wiki/List_of_Qualcomm_Snapdragon_systems_on_chips The Pentium II's development name was Kalmath, Pentium III was Katmai, then Pentium 4 was a space heater and everybody backed up and switched to "Pentium M" (which was MEANT to be a mobile chip but was instead a "not stupid" chip) and then they did "Core"... And then "Core 2" and "Core Duo" were different things and "Core 2 Duo" was both of those things, and then they had i3 and i5 and i7 but they all came out at the same time... Jeep produced a "Cherokee" for 50 years and expected the user to step from a 1973 model to a 2023 model and be able to drive it the same (modulo major flag day changes like stick shift or leaded gasoline) with zero learning curve. Hardware developers of today go "here's an sd card, it goes click-click into your device and it just works, the only numbers you really need to know are price and capacity" (modulo microsd, but they still provide adapter sleds). Software developers think that "DOS 2.0" and "DOS 3.0" or "Windows 3.0" and "Windows 3.1" being profoundly different and largely incompatible is just normal, and track that stuff minutely. Different culture. Rob
© 2016 - 2025 Red Hat, Inc.