Syllable Device Driver API


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_sioport_root_resource (void)
 Return pointer to the toplevel resource tree for I/O ports.
Resource_smemory_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.

Function Documentation

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_ids 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 

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:

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 

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])


Generated on Sat May 9 22:53:30 2009 for Syllable device driver API by  doxygen 1.5.1