device driver probe return codes

[Ben Dooks <ben-linux@fluff.org>]

I would like some feedback on the following regarding some
form of standardising return codes from a device driver probe
to try and stop some basic mistakes.

This document is not complete, any additions would be welcone.


probe() error return codes
==========================

-ENODEV		This should be reserved for the case where there
		really is no device here.

		If you do not have a necessary resource or other setup
		information this is NOT the error you want to return as
		the driver core will not print any error message to the
		user. Even if you driver prints a warning, this is still
		not the error code to return.

-ENXIO		See -ENODEV, this is taken by the driver core to mean
		there is "No such device or address (POSIX.1)".

-ENOMEM		This is used to signify lack of memory resources, such
		as a failure to kmalloc() device state.

-EBUSY		A resource you need is not avaialable.

		This is returned if you cannot get exclusive access to a
		resource such as a request_mem_region() has failed.

-EINVAL		An argument to the driver is invalid.

-EIO		An input/output error occured. This could be due to
		the device responding in an unexpected way or that
		the device did not complete a request properly.




Generic driver examples
=======================

Requesting an memory region
---------------------------

	if (!request_mem_region(start, len, why))
		return -EBUSY;

Mapping a IO region
-------------------

	regs = ioremap(base, size);
	if (!regs)
		return -EIO;

possibly -EFAULT here? 

Not -ENOMEM, which a number of drivers do.


Platform driver specific examples
=================================

Examples when writing platform drivers.

All examples in this section assume the probe prototype is:

static int my_probe(struct platform_device *pdev)


Checking platform data
----------------------

	if (!pdev->dev.platform_data)
		return -EINVAL;

should -ENOENT be returned here?


Finding platform resource(s)
----------------------------

	res = platform_get_resource(pdev, IORESOURCE_MEM, 0);
	if (!res)
		return -ENOENT;

	   
Getting a clock
---------------

	clk = clk_get(&pdev->dev, NULL);
	if (IS_ERR(clk))
		return PTR_ERR(clk);



-- 
Ben (ben@fluff.org, http://www.fluff.org/)

  'a smiley only costs 4 bytes'