Syllable device driver API: Syllable Device Driver API

Resource_s* ____request_resource	(	Resource_s *	psRoot,
		Resource_s *	psNew
	)

This function works similar to request_resource(), but it returns pointer to the conflicting resource.

Parameters:

	psRoot	pointer to the root of the resource tree
	psNew	pointer to the resource descriptor to be inserted

Returns:: NULL if resource was inserted
Pointer to the conflicting resource descriptor.

void __free_resource	(	Resource_s *	psRoot,
		uint	nStart,
		uint	nReqMask
	)

Free resource which starts in the 1st level of the root children.

Only resources that match given mask are freed. This is useful for free() like function when using resource manager to manage allocatable heaps.

Parameters:

	psRoot	parent resource
	nStart	address of the beginning of the resource to be freed
	nReqMask	required bits must be set in the resource flags

See also:: __release_region(), release_resource()

void __release_region	(	Resource_s *	psParent,
		uint	nStart,
		uint	nSize
	)

Release region in the resource tree.

Specified region is searched for in the resource tree. If the region wasn't found, function reports warning by the kernel message. Corresponding resource descriptor is removed and freed.

Parameters:

	psParent	root resource
	nStart	start of the resource
	nEnd	end of thre resource

See also:: release_resource()

Resource_s* __request_region	(	Resource_s *	psParent,
		uint	nStart,
		uint	nSize,
		const char *	pzName
	)

Request region in the given resource tree.

Caller provides region area and region name. Resource descriptor is automatically allocated. New resource is claimed.

Parameters:

	psParent	parent resource
	nStart	beginning of the resource area
	nSize	size of the resource
	pzName	name of the resource

Returns:: NULL if it was unable to claim resource
new resource descriptor

See also:: ____request_resource(), request_resource()

int adjust_resource	(	Resource_s *	psRes,
		uint	nStart,
		uint	nSize
	)

Adjust new resource area for the given base and size.

Children areas aren't touched. If children wouldn't fit in the new rage, error is returned.

Parameters:

	psRes	resource to be modified
	nStart	start of the resource
	nEnd	end of the resource

Returns:: 0 if everything went OK
-EBUSY if resource won't fit

status_t alloc_area_list	(	uint32_t	nProtection,
		uint32_t	nLockMode,
		uintptr_t	nAddress,
		uint_fast32_t	nCount,
		const char const	apzNames,
		size_t *	panOffsets,
		size_t *	panSizes,
		area_id *	panAreas
	)

Allocates an array of areas with the specified names, starting offsets and sizes.

All areas will have the same protection mask and locking mode.

Parameters:

	nProtection	a protection bitmask containing any combination of: `AREA_READ`, `AREA_WRITE`, `AREA_EXEC`, `AREA_KERNEL`, and `AREA_WRCOMB`.
	nLockMode	the locking mode to use: `AREA_NO_LOCK`, `AREA_LAZY_LOCK`, `AREA_FULL_LOCK`, or `AREA_CONTIGUOUS`.
	nAddress	the base virtual memory address for the new areas. Each area will start at `(nAddress + panOffsets[i])`.
	nCount	the number of areas to create. `apzNames`, `panOffsets`, `panSizes`, and `panAreas` are arrays of this size.
	apzNames	an array of pointers to strings containing the names to use for each area. Any entry can be `NULL` to create an unnamed area, or a `NULL` pointer can be passed here to create all areas without names.
	panOffsets	an array of byte offsets from `nAddress` to use as the start address for each area.
	panSizes	an array of sizes in bytes for each area.
	panAreas	the `area_id`s of the new areas will be copied to this array.

Returns:: -EINVAL if any of the areas to create would overlap or if the starting offsets are not in sequential order, -ENOADDRSPC if there isn't enough free virtual address space for the new areas, -ENOMEM if there isn't enough physical memory available; 0 otherwise.

See also:: find_unmapped_area(), do_create_area(), do_delete_area()

Author:: Kurt Skauen ([email protected])

void* alloc_real	(	uint32	nSize,
		uint32	nFlags
	)

Allocates memory in the real memory region.

Parameters:

	nSize	the size in bytes to allocate.
	nFlags	`MEMF_CLEAR` is valid.

Returns:: a pointer to the allocated memory.

See also:: free_real()

Author:: Arno Klenke ([email protected])

int alloc_tld ( void )

Allocates a TLD slot.

Description:: Allocates a TLD. A TLD (thread local storage) is an integer that is allocated on the process level but accessed by threads. A thread can assign an arbitrary value to a TLD and then retrieve the value later. The TLD handle can be distributed among the threads but each thread will have its own private storage for the TLD. This means that both thread A and thread B can store different values to the same TLD without overwriting each other's TLD. This is for example used to give each thread a private "errno" global variable.

Returns:: On success a positive handle is returned.

On error a negative error code is returned.

Error codes:: ENOMEM All TLD slots are in use.

See also:: free_tld(), set_tld(), get_tld()

Author:: Kurt Skauen ([email protected])

int allocate_resource	(	Resource_s *	psRoot,
		Resource_s *	psNew,
		uint	nSize,
		uint	nMin,
		uint	nMax,
		uint	nAlign,
		void()(void pData, Resource_s *psRes, uint nSize, uint nAlign)	pfnAlign,
		void *	pAlignData
	)

This function allocates resource in the resource tree.

It searches for the free area of the specified size and alignment. User has ability to modify resource alignment by the pfnAlign function. After the resource allocation, specified region is claimed in the resource tree.

Parameters:

	psRoot	root resource node which we want to allocate resource in
	psNew	pointer to the new resource descriptor
	nSize	requested size
	nMin	minimal address
	nMax	maximal resource address
	nAlign	starting address alignment
	pfnAlign	user alignment function (optional)
	pAlignData	data passed to pfnAlign

Returns:: 0 if resource was allocated
-EBUSY if there is no free resource with the specified constraints

See also:: request_resource()

int based_open	(	int	nRootFD,
		const char *	pzPath,
		int	nFlags,
			...
	)

Open a file relative to a given directory.

Description:: based_open() have the same semantics as open() except that you can specify the "current working directory" as a parameter.

The first parameter should be a file descriptor for a open directory and the path can be eighter absolute (starting with a "/") in which case the semantics is exactly the same as for open() or it can be relative to nRootFD.

The "real" current working directory is not affected.

This provide a thread-safe way to do do the following:

                int nOldDir = open( ".", O_RDONLY );
                fchdir( nRootFD );
                nFile = open( pzPath, ... );
                fchdir( nOldDir );
                close( nOldDir );

The problem with the above example in a multithreaded environment is that other threads will be affected by the change of current working directory and might get into trouble while we temporarily change it. Using based_open() is also more efficient since only one kernel-call is done (based_open() is just as efficient as open()).

Parameters:

	nRootFD	The directory to use as starting point when searching for `pzPath`
	pzPath	Path to the file to open. This can eighter be absolute or relative to `nRootFD`.
	nFlags	Flags controlling how to open the file. Look at open() for a full description of the flags.
	nMode	The access rights to set on the newly created file if O_CREAT is specified in `nFlags`

Returns:: based_open() return the new file descriptor on success or

a negatice error code if an error occurs.

Error codes:

EMFILE nRootFD is not a valid file descriptor
ENOTDIR nRootFD is not a directory
In addition all error-codes returned by open() can be returned.

See also:: open(), close()

Author:: Kurt Skauen ([email protected])

void boot_reserve_io_region	(	uint	nStart,
		uint	nEnd,
		const char *	pzName
	)

Reserves I/O port region at boot time.

Parameters:

	nStart	start of the area
	nEnd	end of the area
	pzName	name of the area

See also:: boot_reserve_mem_region()

void boot_reserve_mem_region	(	uint	nStart,
		uint	nEnd,
		const char *	pzName
	)

Reserves physical memory region at boot time.

Parameters:

	nStart	start of the area
	nEnd	end of the area
	pzName	name of the area

See also:: boot_reserve_io_region()

status_t claim_device	(	int	nDeviceID,
		int	nHandle,
		const char *	pzName,
		enum device_type	eType
	)

Claims a registered device.

Parameters:

	nDeviceID	the device id of the driver.
	nHandle	the handle returned by the register_device() call.
	pzName	the new name of the device.
	eType	the type of the device.

Returns:: 0 if successful or another value if the device is already claimed.

See also:: register_device(), release_device()

Author:: Arno Klenke ([email protected])

area_id create_area	(	const char *	pzName,
		void **	ppAddress,
		size_t	nSize,
		size_t	nMaxSize,
		flags_t	nProtection,
		flags_t	nLockMode
	)

Creates a new memory area in the current process.

Parameters:

	pzName	a pointer to the string containing the name for the new area.
	ppAddress	a pointer to the variable where the start address of the new area will be stored, or `NULL`. If non- `NULL`, the previous value of the variable it points to will be used as the preferred start address of the new area.
	nSize	the size in bytes of the requested area.
	nMaxSize	the maximum size in bytes of the requested area.
	nProtection	a protection bitmask containing any combination of: `AREA_READ`, `AREA_WRITE`, `AREA_EXEC`, `AREA_KERNEL`, and `AREA_WRCOMB`.
	nLockMode	the locking mode to use: `AREA_NO_LOCK`, `AREA_LAZY_LOCK`, `AREA_FULL_LOCK`, or `AREA_CONTIGUOUS`.

Returns:: -EINVAL if the preferred starting address at *ppAddress is not a multiple of PAGE_SIZE; -ENOADDRSPC if there isn't enough virtual address space, -ENOMEM if there isn't enough physical memory; the area_id of the new area otherwise.

See also:: alloc_area()

Author:: Kurt Skauen ([email protected])

int create_device_node	(	int	nDeviceID,
		int	nDeviceHandle,
		const char *	pzPath,
		const DeviceOperations_s *	psOps,
		void *	pNodeCookie
	)

Publish a device node inside the /dev/ directory.

Description:: Device drivers can call this function to publish their device nodes inside the /dev/ directory. AtheOS has a very flexible and dynamic system for managing device nodes. A device driver can create, rename and delete nodes inside the /dev/ directory at any time. Normally a device driver will call create_device_node() during initialization and delete_device_node() when being deinitialized, but it can also create and delete nodes at other points if it for example controls some form of removable device that might be added or removed after the device driver has been loaded.

Note:

Parameters:

	nDeviceID	This is the unique device ID passed to the driver in the "device_init()" funcion.
	nDeviceHandle	The device handle for your device. You can probably ask the bus manager to get it. If you do not have a handle then you can also pass -1.
	pzPath	The path is relative to /dev/ and can specify directories in addition to the node name. For example "disk/scsi/hda/raw" will create a device node name "raw" inside /dev/disk/scsi/hda/". The path should not have any leading or trailing slashes.
	psOps	Pointer to a DeviceOperations_s structure containing a list of function pointers that will be called by the kernel on behalf of the user of the device. Functions like read(), write(), ioctl(), etc. will be mapped more or less directly into calls into the device driver through these function pointers.
	pNodeCookie	This is just a void pointer that the kernel will be associating with the device node and that will be passed back to the driver when calling functions in psOps (it will be passed to the psOps functions as the pNode parameter). This can be used by the driver to associate some private data with the device node.

Returns:: create_device_node() returns a handle that can later be used to rename the node with rename_device_node() or to delete the node with delete_device_node(). If the node is not deleted before the driver is unloaded it will be deleted automatically by the kernel.

See also:: delete_device_node(), rename_device_node()

Author:: Kurt Skauen ([email protected])

int decode_disk_partitions	(	device_geometry *	psDiskGeom,
		Partition_s *	pasPartitions,
		int	nMaxPartitions,
		void *	pCookie,
		disk_read_op *	pfReadCallback
	)

Decode a hard-disk partition table.

Description:: decode_disk_partitions() can be called by block-device drivers to decode a disk's partition table. It will return both primary partitions and logical partitions within the extended partition if one exists. The extended partition itself will not be returned.

The caller must provide the device geometry and a callback that will be called to read the primary partition table and any existing nested extended partition tables.

The partition table is validated and the function will fail if it is found invalid. Checks performed include overlapping partitions, partitions ending outside the disk and the primary table containing more than one extended partition.

Note:: Primary partitions are numbered 0-3 based on their position inside the primary table. Logical partition are numbered from 4 and up. This might leave "holes" in the returned array of partitions. The returned count only indicates the highest used partition number and the caller must check each returned partition and filter out partitions where the type field is '0'.

Parameters:

	psDiskGeom	Pointer to a device_geometry structure describing the disk's geometry.
	pasPartitions	Pointer to an array of partition descriptors that will be filled in.
	nMaxPartitions	Number of entries allocated for pasPartitions. Maximum nMaxPartitions number of partitions will be returned. If the function returns exactly nMaxPartitions it might have overflowed and the call should be repeated with a larger buffer.
	pCookie	Pointer private to the caller that will be passed back to the pfReadCallback call-back function.
	pfReadCallback	Pointer to a function that will be called to read in partition tables.

Returns:: A positive maximum partition count on success or a negative error code on failure.

See also:: create_device_node(), delete_device_node()

Author:: Kurt Skauen ([email protected])

status_t delete_area ( area_id hArea )

Deletes the specified area.

Parameters:

hArea

a handle to the area to resize.

Returns:: -EINVAL if the area handle is invalid, -ENOADDRSPC if there isn't enough virtual address space available, -ENOMEM if there isn't enough physical memory available; 0 otherwise.

See also:: do_delete_area()

Author:: Kurt Skauen ([email protected])

int delete_device_node ( int nHandle )

Remove a device node from the /dev/ directory.

Description:: Delete a node previously created with create_device_node(). The device node will be removed from the /dev/ directory and the DeviceOperations_s structure and the cookie passed to create_device_node() can now be destroyed by the driver.

Parameters:

nHandle

A device-node handle returned by a previous call to create_device_node()

Returns:: 0 on success, a negative error code on failure

See also:: create_device_node(), rename_device_node()

Author:: Kurt Skauen ([email protected])

status_t delete_semaphore ( sem_id hSema )

Delete a kernel semaphore.

Description:: Delete a semaphore previously created with create_semaphore(). Resources consumed by the semaphore will be released and all threads currently blocked on the semaphore will be waked up and the blocking function will return an error code.

Parameters:

hSema

Semaphore handle returned by a previous call to create_semaphore()

Returns:: On success 0 is returned.

On error a negative error code is returned.

See also:: create_semaphore(), lock_semaphore(), lock_semaphore_ex(), unlock_semaphore(), unlock_semaphore_ex(), sleep_on_sem(), wakeup_sem(), unlock_and_suspend()

,spinunlock_and_suspend()

Author:: Kurt Skauen ([email protected])

void disable_device ( int nDeviceID )

Disable one PCI device driver.

Description:: Disables one PCI device driver. WARNING: This function will be removed in the futurue.

Parameters:

nDeviceID

Device id of the driver passed by device_init().

Returns:

See also:: disable_device_on_bus()

Author:: Arno Klenke ([email protected])

void disable_device_on_bus	(	int	nDeviceID,
		const char *	pzBus
	)

Disable one device driver.

Description:: Disables one device driver. The driver will be loaded again if enable_devices_on_bus() is called. You need to be sure that the busmanager enables the device driver again if new devices are detected. This is true for PCI, USB and ACPI devices.

Parameters:

	nDeviceID	Device id of the driver passed by device_init().
	pzBus	Busmanager name.

Returns:

See also:: enable_devices_on_bus, enable_all_devices()

Author:: Arno Klenke ([email protected])

void enable_all_devices ( void )

Enable all device drivers.

Description:: Enables all drivers which have been disabled by calling disable_device_on_bus().

Returns:

See also:: disable_device_on_bus()

Author:: Arno Klenke ([email protected])

void enable_devices_on_bus ( const char * pzBus )

Enable all device drivers for devices on a specific bus.

Description:: Enables all drivers which have been disabled by calling disable_device_on_bus() with the same bus name.

Returns:

See also:: disable_device_on_bus()

Author:: Arno Klenke ([email protected])

int freadlink	(	int	nFile,
		char *	pzBuffer,
		size_t	nBufSize
	)

Read the content of an previously opened symlink.

Description:: Read the content of a symlink previously opened with open( path, O_NOTRAVERSE ).

The semantics is the same as for readlink() except that it take and already opened symlink rather than a path-name.

Normally when passing a symlink path to open() it will automatically open the file/dir that the link points to and not the link itself. To stop open() from traversing the links you can add the O_NOTRAVERSE flag to the open-mode. open() will then return a file-handle representing the link itself rather than the file the link points at.

Parameters:

	nFile	File descriptor representing the symlink to read.
	pzBuffer	Pointer to a buffer of at least `nBufSize` bytes that will receive the content of the symlink. The buffer will not be NUL terminated but the number of bytes added to the buffer will be returned by freadlink().
	nBufSize	Size of pzBuffer.

Returns:: The call returns the number of bytes placed in the buffers on success, or

a negatice error code if an error occurs.

Error codes:

EBADF nFile is not a valid file descriptor or is not open for reading
EINVAL nFile is not a symlink
ENOSYS The filesystem hosting nFile does not support symbolic links.

See also:: readlink()

Author:: Kurt Skauen ([email protected])

void free_real ( void * pAddress )

Frees memory in the real memory region.

Parameters:

pAddress

a pointer to the allocated memory.

See also:: alloc_real()

Author:: Arno Klenke ([email protected])

int free_tld ( int nHandle )

Releases a TLD slot previously allocated with alloc_tld().

Parameters:

nHandle

The TLD slot to release.

Returns:: On success 0 is returned.

On error a negative error code is returned.

Error codes:

EINVAL Invalid TLD handle.

See also:: alloc_tld(), set_tld(), get_tld()

Author:: Kurt Skauen ([email protected])

status_t get_area_info	(	area_id	hArea,
		AreaInfo_s *	psInfo
	)

Returns an AreaInfo_s for the specified area.

Parameters:

	hArea	a handle to the area for which to return info.
	psInfo	a pointer to the `AreaInfo_s` in which to store the results.

Returns:: -EINVAL if the area handle is invalid or the area doesn't belong to this process; 0 otherwise.

Author:: Kurt Skauen ([email protected])

status_t get_area_physical_address	(	area_id	hArea,
		uintptr_t *	pnAddress
	)

Returns the starting physical memory address for the specified area.

Parameters:

	hArea	a handle to the area.
	pnAddress	a pointer to the variable where the starting physical address for hArea will be copied.

Returns:: -EINVAL if hArea is invalid; 0 otherwise.

See also:: claim_device(), unregister_device(), do_get_area_physical_address()

Author:: Arno Klenke ([email protected])

void* get_device_data ( int nHandle )

Returns the private device driver data of one device.

Parameters:

nHandle

the handle of the device.

See also:: set_device_data()

Author:: Arno Klenke ([email protected])

status_t get_device_info	(	DeviceInfo_s *	psInfo,
		int	nIndex
	)

Returns a DeviceInfo_s structure for a registered device.

Parameters:

	psInfo	a pointer to the `DeviceInfo_s` structure to fill.
	nIndex	the index of the device.

Returns:: 0 if successful.

Author:: Arno Klenke ([email protected])

void* get_tld_addr ( int nHandle )

Gives the address on the stack of the TLD.

Parameters:

nHandle

The TLD to calculate the address for. Deprecated & marked for removal.

Returns:: On success the address of the TLD is returned. On failure, NULL is returned.

Error codes:

NULL Invalid TLD handle.

See also:: alloc_tld(), set_tld(), get_tld()

Author:: Kristian Van Der Vliet ([email protected])

int insert_resource	(	Resource_s *	psParent,
		Resource_s *	psNew
	)

Insert resource into the resource tree.

This function works similar to request_resource(), when no resource conflict happens. If a conflict happens, and the conflicting resources fit entirely in the psNew resource range, resource psNew becomes new parent of the conflicting resources. Otherwise it becomes child of the conflicting resource.

Parameters:

	psParent	resource tree root
	psNew	pointer to the new resource to be inserted

Returns:: 0 if everything went OK
-EBUSY when function is unable to insert resource

See also:: request_resource(), ____request_resource()

Resource_s* ioport_root_resource ( void )

Return pointer to the toplevel resource tree for I/O ports.

All drivers which register I/O port, register them directly in this tree.

Warning:: Never modify this structure.

Returns:: Pointer to the resource descriptor.

status_t lock_semaphore	(	sem_id	hSema,
		uint32	nFlags,
		bigtime_t	nTimeOut
	)

Lock a semaphore.

Description:: Locks a semaphore. Equivalent of calling lock_semaphore_ex() with a count of 1.

Parameters:

	hSema	Semaphore handle to lock.
	nFlags

SEM_NOSIG Ignore signals while blocking on the semaphore. Only set this flag on semaphores that are known to be released realtively soon. Otherwhise the caller should handle the EINTR error and exit from the kernel as soon as possible if a signal is caught.

Parameters:

nTimeOut

Maximum number of micro seconds to wait for the semaphore to be released. If the timeout is 0 lock_semaphore_ex() will never return, and if it is INFINITE_TIMEOUT it will block until the semaphore can be acquired or a signel is caught.

Returns:: On success 0 is returned.

On error a negative error code is returned.

Error codes:

ETIME the semaphore could not be acquired before the timeout expiered.
EINTR a signal was caught before the semaphore could be acquired.
EINVAL hSema was not a valid semaphore handle, or the semaphore was deleted while we blocked.

See also:: lock_semaphore_ex()

Author:: Kurt Skauen ([email protected])

status_t lock_semaphore_ex	(	sem_id	hSema,
		int	nCount,
		uint32	nFlags,
		bigtime_t	nTimeOut
	)

Acquire a semaphore.

Description:: Acquire a semaphore. lock_semaphore_ex() will decrease the semaphore's nesting counter with "nCount".

If the timeout is larger than 0 and the nesting counter becomes negative the calling thread will be blocked. The thread will then stay blocked until one of the following conditions are met:

Another thread release the semaphore and cause the nesting counter to become positive again and the function returns successfully.
The timeout runs out and the function returns with an ETIME error.
The calling threads catch a signal and the function return the EINTR error code.

If the timeout is 0 lock_semaphore_ex() will never block, but instead returns immediatly with ETIME if the semaphore can not be acquired. If the timeout is INFINITE_TIMEOUT the thread will be blocked until it can be successfully acquired or a signal is caught.

Warning:: Since lock_semaphore_ex() called with a non-0 timeout might block it must never be called from a interrupt handler. Non-atomic resources accessed from interrupt handlers must be protected with spinlocks.

Parameters:

	hSema	Semaphore handle to lock.
	nCount	Positive value that should be subtracted from the current nesting counter.
	nFlags

SEM_NOSIG Ignore signals while blocking on the semaphore. Only set this flag on semaphores that are known to be released realtively soon. Otherwhise the caller should handle the EINTR error and exit from the kernel as soon as possible if a signal is caught.

Parameters:

nTimeOut

Maximum number of micro seconds to wait for the semaphore to be released. If the timeout is 0 lock_semaphore_ex() will never return, and if it is INFINITE_TIMEOUT it will block until the semaphore can be acquired or a signel is caught.

Returns:: On success 0 is returned.

On error a negative error code is returned.

Error codes:

ETIME the semaphore could not be acquired before the timeout expiered.
EINTR a signal was caught before the semaphore could be acquired.
EINVAL hSema was not a valid semaphore handle, or the semaphore was deleted while we blocked.

See also:: unlock_semaphore_ex(), lock_semaphore(), unlock_semaphore_ex(), create_semaphore(), delete_semaphore(), unlock_semaphore(), unlock_semaphore_ex(), sleep_on_sem(), wakeup_sem(), unlock_and_suspend()

spinunlock_and_suspend()

Author:: Kurt Skauen ([email protected])

status_t memcpy_from_user	(	void *	pDst,
		const void *	pSrc,
		size_t	nSize
	)

Copies a region of memory from user space into kernel space.

Parameters:

	pDst	the starting address of the destination region.
	pSrc	the starting address of the source region.
	nSize	the number of bytes to copy.

Returns:: The error code from verify_mem_area() on failure; 0 otherwise.

See also:: verify_mem_area()

Author:: Kurt Skauen ([email protected])

status_t memcpy_to_user	(	void *	pDst,
		const void *	pSrc,
		size_t	nSize
	)

Copies a region of memory from kernel space into user space.

Parameters:

	pDst	the starting address of the destination region.
	pSrc	the starting address of the source region.
	nSize	the number of bytes to copy.

Returns:: The error code from verify_mem_area() on failure; 0 otherwise.

See also:: verify_mem_area()

Author:: Kurt Skauen ([email protected])

Resource_s* memory_root_resource ( void )

Return pointer to the toplevel resource tree for physical memory areas.

All drivers which register memory regions use this tree (e.g. the PCI driver).

Warning:: Never modify this structure.

Returns:: Pointer to the resource descriptor.

status_t register_busmanager	(	int	nDeviceID,
		const char *	pzName,
		busmanager_get_hooks *	pfHooks
	)

Registers a busmanager.

Parameters:

	nDeviceID	device id of the driver registering this busmanager
	pzName	the name of the busmanager.
	pfHooks	pointer to the function table of the busmanager

See also:: get_busmanager()

Returns:: 0 if successful.

Author:: Arno Klenke ([email protected])

int register_device	(	const char *	pzName,
		const char *	pzBus
	)

Registers a device and returns a handle to it.

Parameters:

	pzName	the name of the device; will be overwritten after calling claim_device().
	pzBus	the name of the bus the device is attached to.

Returns:: a handle to the device.

See also:: claim_device(), unregister_device()

Author:: Arno Klenke ([email protected])

void release_device ( int nHandle )

Releases a device.

Parameters:

nHandle

the handle returned by the register_device() call.

See also:: claim_device(), unregister_device()

Author:: Arno Klenke ([email protected])

int release_resource ( Resource_s * psOld )

Removes source from the resource tree.

No memory is freed.

Parameters:

psOld

pointer to the resource descriptor

Returns:: 0 if descriptor was removed
-EINVAL if there was memory corruption

See also:: request_resource()

status_t remap_area	(	area_id	hArea,
		void *	pPhysAddress
	)

Remaps the specified area to use a different region of physical memory.

Parameters:

	hArea	a handle to the area to remap.
	pPhysAddress	the new start address in physical memory for the region.

Returns:: -EINVAL if the area handle is invalid or if nPhysAddress isn't a multiple of PAGE_SIZE; 0 otherwise.

See also:: do_remap_area()

Author:: Kurt Skauen ([email protected])

int rename_device_node	(	int	nHandle,
		const char *	pzNewPath
	)

Rename and/or move a device node.

Description:: A device driver can rename and/or move a device node inside the /dev/ hierarchy. The new path should be relative to /dev/ and have the same format as the path passed to create_device_node().

Parameters:

	nHandle	A device-node handle returned by a previous call to create_device_node()
	pzNewPath	The new device-node path.

Returns:

See also:: create_device_node(), delete_device_node()

Author:: Kurt Skauen ([email protected])

status_t rename_process	(	int	nProcessID,
		const char *	pzName
	)

Rename a process.

Description:: All processes have a name to aid debugging and to some degree make it possible to search for a process by name. The name is normally inherited from the parent during fork and later set to the executable name if the process exec's but it can also be set explicitly with rename_process().

Note:: The name will be replaced with the name of the executable if the process ever call execve().

Parameters:

	nProcessID	Identity of the process to rename. You can also pass in -1 to rename the calling process.
	pzName	The new process name. Maximum OS_NAME_LENGTH characters long including the 0 termination. On success 0 is returned.

On error a negative error code is returned.

Error codes:

ESRCH nProcessID is not -1 and there is not process with that ID.

See also:: rename_thread(), get_process_id()

Author:: Kurt Skauen ([email protected])

int request_resource	(	Resource_s *	psRoot,
		Resource_s *	psNew
	)

Register resource in the specified resource tree.

This function checks for resource collisions.

Parameters:

	psRoot	pointer to the root of the resource tree
	psNew	pointer to the resource descriptor to be inserted

Returns:

0 if resource was inserted successfuly

-EBUSY if there was resource conflict

Pointer to the resource descriptor.

See also:: ____request_resource()

status_t reset_semaphore	(	sem_id	hSema,
		int	nCount
	)

Reset the count on the given semaphore.

Description:: Reset the count of the given semaphore. The semaphore must be a SEMSTYLE_COUNTING type semaphore.

Warning: Calling this function when a thread has locked the semaphore or is sleeping on the semaphore is dangerous.

Parameters:

	hSema	The semaphore to modify.
	nCount	The new count for the semaphore.

Returns:: On success 0 is returned. On error a negative error code is returned.

Error codes:

EINVAL hSema os not a valid semaphore handle.

See also:: lock_semaphore(), unlock_semaphore()

Author:: Kristian Van Der Vliet ([email protected])

status_t resize_area	(	area_id	hArea,
		size_t	nNewSize,
		bool	bAtomic
	)

Resizes the specified area.

Parameters:

	hArea	a handle to the area to resize.
	nNewSize	the new area size in bytes.
	bAtomic	if `true`, resize_area() will repeatedly shrink the block cache by 64K and try again if an `-ENOMEM` error is returned by alloc_area_pages() or alloc_area_page_tables().

Returns:: -EINVAL if the area handle is invalid, -ENOADDRSPC if there isn't enough virtual address space available, -ENOMEM if there isn't enough physical memory available; 0 otherwise.

See also:: alloc_area_page_tables(), alloc_area_pages(), free_area_page_tables(), free_area_pages(), shrink_caches()

Author:: Kurt Skauen ([email protected])

void set_device_data	(	int	nHandle,
		void *	pData
	)

Sets private device driver data of one device.

Parameters:

	nHandle	the handle returned by the register_device() call.
	pData	the data.

See also:: get_device_data()

Author:: Arno Klenke ([email protected])

status_t sleep_on_sem	(	sem_id	hSema,
		bigtime_t	nTimeOut
	)

Non conditionally block on a semaphore (wait-queue).

Description:: Non conditionaly block on an semaphore until someone does a wakeup_sem(), we reach the timeout, or we catch a signal.

A semaphore (as created with create_semaphore()) can be used as a wait-queue rather than a semaphore/mutex by using sleep_on_sem() and wakeup_sem() instead of lock_semaphore() and unlock_semaphore().

Warning:: You should not mix calls to lock_semaphore()/unlock_semaphore() with sleep_on_sem()/wakeup_sem().

Parameters:

	hSema	The wait-queue to sleep on (created with create_semaphore()).
	nTimeOut	Maximum number of microseconds to wait for someone to wake us up before ETIME is returned.

Returns:: On success 0 is returned.

On error a negative error code is returned.

Error codes:

EINVAL hSema is not a valid semaphore handle.
ETIME Nobody woke us up before the timeout.

See also:: create_semaphore(), wakeup_sem()

Author:: Kurt Skauen ([email protected])

status_t spinunlock_and_suspend	(	sem_id	hWaitQueue,
		SpinLock_s *	psLock,
		uint32	nCPUFlags,
		bigtime_t	nTimeOut
	)

Release a spinlock and block on a wait-queue in one atomic operation.

Description:: Same as unlock_and_suspend() except that it releases a spinlock instead of a regular semaphore. This is usefull for device-drivers that receive or transmitt data through interrupt handlers, and then need to syncronize this with threads that deliver or use the data.

Note:: Interrupts *MUST* be disabled prior to calling this function. The CPU flags will be restored to the value of nCPUFlags before returning unless an error (other than receiving a signal) occured.

This function can only be called from the kernel, or from device drivers. From user-space you should use unlock_and_suspend()

Warning:

Parameters:

	hWaitQueue	Handle to the wait-queue to block on (created earlier with create_semaphore()).
	psLock	Spinlock to release.
	nCPUFlags	The CPU flags to restore before returning.
	nTimeOut	Maximum number of microseconds to wait for someone to wake us up before ETIME is returned.

Returns:: On success 0 is returned. On error a negative error code is returned.

See also:: unlock_and_suspend()

Author:: Kurt Skauen ([email protected])

status_t strcpy_to_user	(	char *	pzDst,
		const char *	pzSrc
	)

Copies a string from kernel space into user space.

Parameters:

	pzDst	the starting address of the destination region.
	pzSrc	the address of the string to copy.

Returns:: The error code from verify_mem_area() on failure; 0 otherwise.

See also:: verify_mem_area()

Author:: Kurt Skauen ([email protected])

status_t strlen_from_user ( const char * pzString )

Returns the length of the specified string.

Parameters:

pzString

the starting address of the string.

Returns:: The error code from verify_mem_area() on failure; the length of the string otherwise.

See also:: verify_mem_area()

Author:: Kurt Skauen ([email protected])

status_t strncpy_from_user	(	char *	pzDst,
		const char *	pzSrc,
		size_t	nMaxLen
	)

Copies a string from user space into kernel space.

Parameters:

	pzDst	the starting address of the destination region.
	pzSrc	the address of the string to copy.
	nMaxLen	the maximum size of the string to copy.

Returns:: The error code from verify_mem_area() on failure; 0 otherwise.

See also:: verify_mem_area()

Author:: Kurt Skauen ([email protected])

status_t strndup_from_user	(	const char *	pzSrc,
		size_t	nMaxLen,
		char **	ppzDst
	)

Copies a string from user space into a newly allocated kernel region.

Parameters:

	pzSrc	the address of the string to copy.
	nMaxLen	the maximum size of the string to copy.
	ppzDst	a pointer to the variable in which to store a pointer to the new string.

Returns:: -ENAMETOOLONG if the length of the string, including the trailing '\0', is greater than nMaxLen, -ENOMEM if there isn't enough free memory for kmalloc(), any error code from verify_mem_area() on failure; 0 otherwise.

See also:: verify_mem_area(), kmalloc()

Author:: Kurt Skauen ([email protected])

status_t unlock_and_suspend	(	sem_id	hWaitQueue,
		sem_id	hSema
	)

Unlock a reqular semaphore and block on a wait-queue.

Description:: Unlocks an regular semaphore, and sleep on a wait-queue in one atomic operation. No other thread's will be able to lock the semaphore until we are safely added to the wait-queue. This is useful for example when waiting for data to arrive to an object, since it can guaranty that nobody can lock the object, and attempt to wake up sleeper's while you are in the gap between unlocking the object and blocking on the wait-queue.

Parameters:

	hWaitQueue	Handle to the wait-queue to block on (created earlier with create_semaphore())
	hSema	Semaphore to release.

Returns:: 0 on success or a negative error code on failure.

See also:: unlock_semaphore(), sleep_on_sem(), spinunlock_and_suspend()

Author:: Kurt Skauen ([email protected])

status_t unlock_semaphore ( sem_id hSema )

Release a semaphore.

Description:: Same as unlock_semaphore_x() with a count of 1.

See also:: unlock_semaphore_x()

Author:: Kurt Skauen ([email protected])

status_t unlock_semaphore_ex	(	sem_id	hSema,
		int	nCount
	)

Release a semaphore.

Description:: Release a semaphore "nCount" number of times. The value of "nCount" will be added to the semaphores nesting counter and if the counter become positive (>=0) the first thread blocking on the semaphore will be unblocked.

Note:: If "nCount" is larger than 1 all blocked threads will be unblocked and they will then compeat for the semaphore based on their scheduler priority. If "nCount" is 1 only the first blocked thread will be unblocked.

Parameters:

	hSema	The semaphore to release.
	nCount	Number of times to release the semaphore.

Returns:: On success 0 is returned.

On error a negative error code is returned.

Error codes:

EINVAL hSema is not a valid semaphore handle.

See also:: unlock_semaphore(), lock_semaphore_ex()

Author:: Kurt Skauen ([email protected])

void unregister_device ( int nHandle )

Unregisters a previously registered device.

Note:: An error message will be written to the kernel log if the device is still claimed.

Parameters:

nHandle

the handle returned by the register_device() call.

See also:: register_device(), release_device()

Author:: Arno Klenke ([email protected])

status_t verify_mem_area	(	const void *	pAddress,
		size_t	nSize,
		bool	bWriteAccess
	)

Verifies a region of user memory for kernel access.

Parameters:

	pAddress	the start address of the region to lock.
	nSize	the size in bytes of the region to lock.
	bWriteAccess	`true` to lock the region for write access; `false` otherwise.

Returns:: -EFAULT if pAddress points to an address in kernel space, doesn't correspond to an area in user space, or if (pAddress + nSize - 1) extends beyond the end of the area; -ENOMEM if there isn't enough physical memory available; 0 otherwise.

See also:: alloc_area_pages()

Author:: Kurt Skauen ([email protected])

status_t wakeup_sem	(	sem_id	hSema,
		bool	bAll
	)

Wake up threads blocked on a wait-queue.

Description:

Wake up eighter the first thread (the one that first blocked) or all threads blocked on a wait-queue.

If "bAll" is true all semaphores blocked on the queue will be released otherwhice only the first thread will be unblocked.

Warning:: You should not mix calls to lock_semaphore()/unlock_semaphore() with sleep_on_sem()/wakeup_sem().

Parameters:

	hSema	Wait-queue to release (created with create_semaphore()).
	bAll	true to wake up all threads, false to only wake up the first thread in the queue.

Returns:: On success 0 is returned.

On error a negative error code is returned.

Error codes:

EINVAL hSema is not a valid semaphore handle.

See also:: sleep_on_sem(), create_semaphore()

Author:: Kurt Skauen ([email protected])

Syllable Device Driver API

Data Structures

Functions

Function Documentation


Data Structures
struct	Resource_s
	Descriptor of the resource. More...
Functions
status_t	alloc_area_list (uint32_t nProtection, uint32_t nLockMode, uintptr_t nAddress, uint_fast32_t nCount, const char const apzNames, size_t panOffsets, size_t panSizes, area_id *panAreas)
	Allocates an array of areas with the specified names, starting offsets and sizes.
status_t	resize_area (area_id hArea, size_t nNewSize, bool bAtomic)
	Resizes the specified area.
status_t	delete_area (area_id hArea)
	Deletes the specified area.
area_id	create_area (const char pzName, void *ppAddress, size_t nSize, size_t nMaxSize, flags_t nProtection, flags_t nLockMode)
	Creates a new memory area in the current process.
status_t	get_area_physical_address (area_id hArea, uintptr_t *pnAddress)
	Returns the starting physical memory address for the specified area.
status_t	get_area_info (area_id hArea, AreaInfo_s *psInfo)
	Returns an `AreaInfo_s` for the specified area.
status_t	remap_area (area_id hArea, void *pPhysAddress)
	Remaps the specified area to use a different region of physical memory.
status_t	memcpy_to_user (void pDst, const void pSrc, size_t nSize)
	Copies a region of memory from kernel space into user space.
status_t	memcpy_from_user (void pDst, const void pSrc, size_t nSize)
	Copies a region of memory from user space into kernel space.
status_t	strncpy_from_user (char pzDst, const char pzSrc, size_t nMaxLen)
	Copies a string from user space into kernel space.
status_t	strndup_from_user (const char pzSrc, size_t nMaxLen, char *ppzDst)
	Copies a string from user space into a newly allocated kernel region.
status_t	strcpy_to_user (char pzDst, const char pzSrc)
	Copies a string from kernel space into user space.
status_t	strlen_from_user (const char *pzString)
	Returns the length of the specified string.
status_t	verify_mem_area (const void *pAddress, size_t nSize, bool bWriteAccess)
	Verifies a region of user memory for kernel access.
int	register_device (const char pzName, const char pzBus)
	Registers a device and returns a handle to it.
void	unregister_device (int nHandle)
	Unregisters a previously registered device.
status_t	claim_device (int nDeviceID, int nHandle, const char *pzName, enum device_type eType)
	Claims a registered device.
void	release_device (int nHandle)
	Releases a device.
status_t	get_device_info (DeviceInfo_s *psInfo, int nIndex)
	Returns a `DeviceInfo_s` structure for a registered device.
void	set_device_data (int nHandle, void *pData)
	Sets private device driver data of one device.
void *	get_device_data (int nHandle)
	Returns the private device driver data of one device.
status_t	register_busmanager (int nDeviceID, const char pzName, busmanager_get_hooks pfHooks)
	Registers a busmanager.
void *	alloc_real (uint32 nSize, uint32 nFlags)
	Allocates memory in the real memory region.
void	free_real (void *pAddress)
	Frees memory in the real memory region.
status_t	rename_process (int nProcessID, const char *pzName)
	Rename a process.
int	alloc_tld (void)
	Allocates a TLD slot.
void *	get_tld_addr (int nHandle)
	Gives the address on the stack of the TLD.
int	free_tld (int nHandle)
	Releases a TLD slot previously allocated with alloc_tld().
void	boot_reserve_io_region (uint nStart, uint nEnd, const char *pzName)
	Reserves I/O port region at boot time.
void	boot_reserve_mem_region (uint nStart, uint nEnd, const char *pzName)
	Reserves physical memory region at boot time.
Resource_s *	ioport_root_resource (void)
	Return pointer to the toplevel resource tree for I/O ports.
Resource_s *	memory_root_resource (void)
	Return pointer to the toplevel resource tree for physical memory areas.
int	request_resource (Resource_s psRoot, Resource_s psNew)
	Register resource in the specified resource tree.
Resource_s *	____request_resource (Resource_s psRoot, Resource_s psNew)
	This function works similar to request_resource(), but it returns pointer to the conflicting resource.
int	release_resource (Resource_s *psOld)
	Removes source from the resource tree.
int	allocate_resource (Resource_s psRoot, Resource_s psNew, uint nSize, uint nMin, uint nMax, uint nAlign, void(pfnAlign)(void pData, Resource_s psRes, uint nSize, uint nAlign), void pAlignData)
	This function allocates resource in the resource tree.
int	insert_resource (Resource_s psParent, Resource_s psNew)
	Insert resource into the resource tree.
int	adjust_resource (Resource_s *psRes, uint nStart, uint nSize)
	Adjust new resource area for the given base and size.
Resource_s *	__request_region (Resource_s psParent, uint nStart, uint nSize, const char pzName)
	Request region in the given resource tree.
void	__release_region (Resource_s *psParent, uint nStart, uint nSize)
	Release region in the resource tree.
void	__free_resource (Resource_s *psRoot, uint nStart, uint nReqMask)
	Free resource which starts in the 1st level of the root children.
status_t	delete_semaphore (sem_id hSema)
	Delete a kernel semaphore.
status_t	lock_semaphore_ex (sem_id hSema, int nCount, uint32 nFlags, bigtime_t nTimeOut)
	Acquire a semaphore.
status_t	lock_semaphore (sem_id hSema, uint32 nFlags, bigtime_t nTimeOut)
	Lock a semaphore.
status_t	unlock_semaphore_ex (sem_id hSema, int nCount)
	Release a semaphore.
status_t	unlock_semaphore (sem_id hSema)
	Release a semaphore.
status_t	unlock_and_suspend (sem_id hWaitQueue, sem_id hSema)
	Unlock a reqular semaphore and block on a wait-queue.
status_t	spinunlock_and_suspend (sem_id hWaitQueue, SpinLock_s *psLock, uint32 nCPUFlags, bigtime_t nTimeOut)
	Release a spinlock and block on a wait-queue in one atomic operation.
status_t	reset_semaphore (sem_id hSema, int nCount)
	Reset the count on the given semaphore.
status_t	sleep_on_sem (sem_id hSema, bigtime_t nTimeOut)
	Non conditionally block on a semaphore (wait-queue).
status_t	wakeup_sem (sem_id hSema, bool bAll)
	Wake up threads blocked on a wait-queue.
void	disable_device_on_bus (int nDeviceID, const char *pzBus)
	Disable one device driver.
void	disable_device (int nDeviceID)
	Disable one PCI device driver.
void	enable_devices_on_bus (const char *pzBus)
	Enable all device drivers for devices on a specific bus.
void	enable_all_devices (void)
	Enable all device drivers.
int	create_device_node (int nDeviceID, int nDeviceHandle, const char pzPath, const DeviceOperations_s psOps, void *pNodeCookie)
	Publish a device node inside the /dev/ directory.
int	delete_device_node (int nHandle)
	Remove a device node from the /dev/ directory.
int	rename_device_node (int nHandle, const char *pzNewPath)
	Rename and/or move a device node.
int	decode_disk_partitions (device_geometry psDiskGeom, Partition_s pasPartitions, int nMaxPartitions, void pCookie, disk_read_op pfReadCallback)
	Decode a hard-disk partition table.
int	based_open (int nRootFD, const char *pzPath, int nFlags,...)
	Open a file relative to a given directory.
int	freadlink (int nFile, char *pzBuffer, size_t nBufSize)
	Read the content of an previously opened symlink.