Luahid api draft #252

qrsikno2 · 2025-05-17T13:05:42Z

There is the background of this api:
#249
#250

examples/slow_mouse.lua

test_main.lua

lneto · 2025-05-19T15:38:42Z

examples/slow_mouse.lua

+		return device.vendor_id == 0x1233
+	end,
+
+	report_descriptor = {


can you clarify from where these values come from? what's the original driver?

I write it to run a imaginary driver. That's because a set of devices may have their own quirks(maybe) which make it very difficult to cope with diffierent situation. But The draft needs a full example for diffierent apis i think.

if needed, i will redraft an example to "port" a driver.

I would start by "porting" a driver using the proposed API.. so we can have a better sense..

lneto · 2025-05-19T15:39:56Z

examples/slow_mouse.lua

+local function dummy_submitx(value)
+	-- pass
+end
+local function dummy_submity(value)


please, mind \n's.. observer the style of other examples..

lneto · 2025-05-19T15:40:15Z

examples/slow_mouse.lua

+local function dummy_submitx(value)
+	-- pass
+end
+local function dummy_submity(value)


what's the purpose of these two funcs?

lneto · 2025-05-19T15:40:54Z

examples/slow_mouse.lua

+local function dummy_submity(value)
+	-- pass
+end
+local slow_mouse_driver = {


please, add readme entry for describing this API and every field in this table..

lneto · 2025-05-25T15:56:36Z

examples/xiaomi_mouse.lua

+-- example of a slow mouse driver
+local hid = require("luahid")
+
+local fixed_xiaomi_report_descriptor = {


please, add a comment with a link to reference kernel code of the original driver

is this the right one? https://elixir.bootlin.com/linux/v6.14.7/source/drivers/hid/hid-xiaomi.c

how do you plan to parse and use such values in your binding? would it be an actual binding or will it ending up being tied to this particular driver?

yes, the link is right.
what is the difference between "actual binding" and "being tied to this particular driver"?

please, add a comment with a link to reference kernel code of the original driver请添加一条评论，并附上引用原始驱动内核代码的链接

done

lneto · 2025-05-25T15:57:15Z

examples/xiaomi_mouse.lua

+		{ vendor_id = 0x2717, product_id = 0x5014 },  -- copied from kernel src 
+	},
+
+	report_descriptor = fixed_xiaomi_report_descriptor


that's it? don't you need any callback? just this descriptor?

you probably should support callbacks on your API, instead of just assuming such table.. devices drivers should use such callbacks to do their own work.. e.g., https://elixir.bootlin.com/linux/v6.14.7/source/drivers/hid/hid-xiaomi.c#L64

btw, that's one reason this example (xiaome mouse) is not that good.. because it's very limited.. if you see, https://elixir.bootlin.com/linux/v6.14.7/source/include/linux/hid.h#L811, we have many other callbacks to be defined that you must give support in your API..

@qrsikno2 , I agree with Lourival here. Using callbacks will make the luahid library "generic". By generic we mean:

You cannot directly call the kernel C functions from lua scripts (E.g: xiaomi_mouse.lua)

So you create a library luahid that will provide an interface (API) to the lua scripts.

The luahid must allow the scripts to register their own callbacks, in this sense, this library becomes generic. The use of callbacks will allow you to register your own functions for the xiaomi mouse or apple keyboard. This is how even the kernel works. The hid_driver is a struct with function pointers so that any driver can use this struct and define their own drivers, hence the hid API is generic.

So xiaomi_mouse.lua calls the luahid functions, which call the Kernel C functions.

I think there is no need to have callbacks in this scene. that is because the hid-xiaomi is only going to fix special device's report descriptor, so you just need to provide the vendor_id+product_id+descriptor. and this makes the example very clear and simple

I think i would show (callbacks apis) in the other example, but xiaomi is the simplest one, so i ported it firstly.
I was very consider about that i cannot show all the apis just by true examples, just because their usage is fragmented

that's it? don't you need any callback? just this descriptor?

yes, just because the default functions have been implemented by the kernel.
and the device's usage(about ranges, buttons and etc) is defined by the descriptor.

that's one reason this example (xiaome mouse) is not that good..

should i change the code to port another driver or just add(not delete but keep the xiaomi mouse as a simplest example) another example for the "another" more complex mouse driver ？

By callback we mean this:
The hid-xiaomi.c (lines 85-90), the descriptors are set by a function called xiaomi_report_fixup which is a callback function, that will be called by the kernel. But in the example you have directly exported the descriptor table.

static struct hid_driver xiaomi_driver = { .name = "xiaomi", .id_table = xiaomi_devices, .report_fixup = xiaomi_report_fixup, };

This is fine for a single implementation. But since luahid is a library, it needs to handle all types of HID devices, so it's better to handle this in a function. In that function you can just return the descriptor table. Something like this:

local function xiaomi_report_fixup() return fixed_xiaomi_report_descriptor end

In the driver table, you can set it:

local xiaomi_mouse_driver = { name = "luahid_xiaomi_mouse_driver", ... report_fixup = xiaomi_report_fixup }

So your luahid will use this table to then use your functions and tables to pass on to the kernel in a general way for every program.

done, changed in new commit =)

lneto · 2025-05-25T15:57:54Z

examples/xiaomi_mouse.lua

+local xiaomi_mouse_driver = {
+	name = "luahid_xiaomi_mouse_driver",
+	match_list = {
+		{ vendor_id = 0x2717, product_id = 0x5014 },  -- copied from kernel src 


please, add a link from the original source

I think i would change the pattern of match_list just because some devices need to given a bus_type and device_type.
Is that ok for my apis?

As my previous comment, the match_list is of type struct hid_device_id in the kernel right ?

struct hid_device_id { __u16 bus; __u16 group; __u32 vendor; __u32 product; kernel_ulong_t driver_data; };

So this can just be a device id table,

local xiaomi_id = { bus = 0x123, group = 0x2345, -- sample values vendor = 0x11, procuct = 0x01 } -- under the xiaomi driver, you can use this local xiaomi_mouse_driver = { name = "luahid_xiaomi_mouse_driver", .... id_table = xiaomi_id } ...

yes quite right. i think the table can be write into 'plural' form:

local xiaomi_id1 = { bus = 0x123, group = 0x2345, -- sample values vendor = 0x11, procuct = 0x01 } local xiaomi_id2 = { bus = 0x123, group = 0x2345, -- sample values vendor = 0x11, procuct = 0x02 } -- under the xiaomi driver, you can use this local xiaomi_mouse_driver = { name = "luahid_xiaomi_mouse_driver", .... id_table = {xiaomi_id1, xiaomi_id2}, -- or id_table = {xiaomi_id1}, embraced with '{}' maybe better. } ...

lneto · 2025-05-25T16:16:26Z

examples/simple_generic_mouse.lua

+	name = "luahid_simple_generic_mouse_driver",
+}
+
+hid.register(mouse_driver)


I don't see the point of this script.. can you explain it or remove it from the PR?

qrsikno2 added 2 commits March 14, 2025 12:06

feat(lualinux): add some time funcalls and test file

57ff3b7

feat(examples):add a example usage of luahid apis

2756769

qrsikno2 mentioned this pull request May 17, 2025

[GSoC 2025] Basic APIs for luahid #249

Open

lneto reviewed May 17, 2025

View reviewed changes

examples/slow_mouse.lua Outdated Show resolved Hide resolved

lneto reviewed May 17, 2025

View reviewed changes

examples/slow_mouse.lua Outdated Show resolved Hide resolved

lneto reviewed May 17, 2025

View reviewed changes

test_main.lua Outdated Show resolved Hide resolved

qrsikno2 added 2 commits May 17, 2025 21:38

refractor(trash):delete trash code

d31641a

docs&style(example of luahid): add license and revised code style.

b101a19

lneto reviewed May 19, 2025

View reviewed changes

reconstruct code as real driver

33e410c

lneto reviewed May 25, 2025

View reviewed changes

qrsikno2 added 4 commits May 26, 2025 13:15

revised mouse

4c9760b

add comment links

bc9b0c1

docs(xiaomi): add links for ported xiaomi driver

caa6e86

refractor(xiaomi): revised the apis into callbacks

878dd84

lneto force-pushed the master branch 2 times, most recently from 17ac113 to 925bfd9 Compare July 14, 2025 01:10

Luahid api draft #252

Are you sure you want to change the base?

Luahid api draft #252

Uh oh!

Conversation

qrsikno2 commented May 17, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lneto May 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qrsikno2 May 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qrsikno2 May 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qrsikno2 May 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qrsikno2 May 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

lneto May 25, 2025 •

edited

Loading

qrsikno2 May 26, 2025 •

edited

Loading

qrsikno2 May 26, 2025 •

edited

Loading

qrsikno2 May 26, 2025 •

edited

Loading

qrsikno2 May 26, 2025 •

edited

Loading