what is the meaning of this macro _IOR(MY_MACIG, 0, int)?

Question

i was going through ioctl sample programs to check how it communicates with kernel space. in program WRITE_IOCTL is used as command

#define WRITE_IOCTL _IOW(MY_MACIG, 1, int)
ioctl(fd, WRITE_IOCTL, "hello world")

I am not able to understand what is _IOW(MY_MACIG, 1, int). here is the link from where i downloaded the program. please help me. http://people.ee.ethz.ch/~arkeller/linux/multi/kernel_user_space_howto-4.html

Solution 1

As you may know, an ioctl should be unique, as explained in the Linux Device Drivers book:

The ioctl command numbers should be unique across the system in order to prevent errors caused by issuing the right command to the wrong device.Such a mismatch is not unlikely to happen, and a program might find itself trying to change the baudrate of a non-serial-port input stream, such as a FIFO or an audio device. If each ioctl number is unique, the application gets an EINVAL error rather than succeeding in doing something unintended.

Furthermore, an ioctl can require to write data to and/or read data from kernel space.

When one creates it's own driver that performs ioctls, he will need to describe all this in the ioctl command.

_IO, _IOW, _IOR, _IORW are helper macros to create a unique ioctl identifier and add the required R/W needed features (direction).

These can take the following params: magic number, the command id, and the data type that will be passed (if any)

The magic number is a unique number that will allow the driver to detect errors such as the one mentioned in the LDD book's quote.

The command id, is a way for your dirver to understand what command is needed to be called.

Last parameter (the type) will allow the kernel to understand the size to be copied.

hope this helps.

PS: you can have more details in Linux Device Drivers book (chapter 6) https://lwn.net/images/pdf/LDD3/ch06.pdf

Solution 2

From http://www.circlemud.org/jelson/software/fusd/docs/node31.html:

The Linux header file /usr/include/asm/ioctl.h defines macros that must be used to create the ioctl command number. These macros take various combinations of three arguments:

• type, an 8-bit integer selected to be specific to the device driver. type should be chosen so as not to conflict with other drivers that might be ``listening'' to the same file descriptor. (Inside the kernel, for example, the TCP and IP stacks use distinct numbers since an ioctl sent to a socket file descriptor might be examined by both stacks.)
• number, an 8-bit integer command number. Within a driver, distinct numbers should be chosen for each different kind of ioctl command that the driver services
• data_type, the name of a type used to compute how many bytes are exchanged between the client and the driver. This argument is, for example, the name of a structure.

The macros used to generate command numbers are:

• _IO(int type, int number), used for a simple ioctl that sends nothing but the type and number, and receives back nothing but an (integer) retval
• _IOR(int type, int number, data_type), used for an ioctl that reads data from the device driver. The driver will be allowed to return sizeof(data_type) bytes to the user
• _IOW(int type, int number, data_type), similar to _IOR, but used to write data to the driver
• _IORW(int type, int number, data_type), a combination of _IOR and _IOW. That is, data is both written to the driver and then read back from the driver by the client

Comments

[Ayman Khamouma]

if you believe my answer is good please think about voting for it, otherwise comment on it :)

[Jonathan Ben-Avraham]

OP link is broken. See github.com/frobino/de1-soc/blob/master/linux_software/… for the code.

[Jonathan Ben-Avraham]

See duplicate question stackoverflow.com/questions/14626867/…

[Ayman Khamouma]

not really, but some devices use their major numbers as magic number, this is ok as long as it is unique, see kernel documentation: cs.fsu.edu/~baker/devices/lxr/http/source/linux/Documentatio‌​n/…

[Gdogg]

Good info. I stumbled on this while looking some stuff up. I would like to add that you can see the implementation of these macros here

[nyholku]

Technically this [an ioctl needs to be unique] is wrong I believe, this is a convention and there is no technical reason for the ioctl parameters to be unique. Still maybe good idea to follow the convention but it is not necessary. Also I doubt the kernel cares about magic number as far which device is called, the ioctl first parameter does that.

[nyholku]

@ Ayman Khamouma thanks for updating your answer. After some further googling I'm not sure if there is some convention that needs to be followed. So while I think my comment may have been literally correct (i.e. the parameter does not need to be unique and it is not used to find the device) there may still be something in the magic numbers that must follow some convention. So anyone going that finds him/her self in the position where a new magic number is called for better heed the convention and use the macros that are used to come up with those magic numbers.