kolibrios/kernel/branches/kolibri-lldw/docs/drivers_api.txt

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;                                                              ;;
;; Copyright (C) KolibriOS team 2011-2012. All rights reserved. ;;
;; Distributed under terms of the GNU General Public License    ;;
;;                                                              ;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

All functions are stdcall unless mentioned otherwise.

=== Disk ===
The kernel exports the functions 'DiskAdd', 'DiskMediaChanged', 'DiskDel' for
drivers. They must be called in the following order: DiskAdd, then zero or
more DiskMediaChanged, then optionally DiskDel. The driver must not call
two functions in parallel, including two calls to DiskMediaChanged.

void* DiskAdd(DISKFUNC* functions, const char* name, void* userdata, int flags);
; The pointer 'functions' must be valid at least until the disk will be deleted
; (until DISKFUNC.close is called).
; The pointer 'name' can be invalid after this function returns.
; It should point to ASCIIZ-string without leading '/' in latin lowercase and
; digits, like 'usbhd0'.
; The value 'userdata' is any pointer-sized data, passed as is to all
; callbacks.
DISK_NO_INSERT_NOTIFICATION = 1
; The bitfield 'flags' has currently only one bit defined. If it is set, the
; driver will never call DiskMediaChanged(hDisk, true), so the kernel must scan
; for media insertion when the operation is requested.
struc DISKFUNC
{
  .strucsize  dd ?
  .close      dd ?
; void close(void* userdata);
; Optional.
; The last function that is called for the given disk. The kernel calls it when
; the kernel has finished all operations with the disk and it is safe to free
; all driver-specific data identified by 'userdata'.
  .closemedia dd ?
; void closemedia(void* userdata);
; Optional.
; The kernel calls this function when it finished all processing with the
; current media. If media is removed, the driver should decline all requests
; to that media with DISK_STATUS_NO_MEDIA, even if new media is inserted,
; until this function is called. If media is removed, a new call to
; DiskMediaChanged(hDisk, true) is not allowed until this function is called.
  .querymedia dd ?
; int querymedia(void* userdata, DISKMEDIAINFO* info);
; return value: 0 = success, otherwise = error
  .read       dd ?
; int read(void* userdata, void* buffer, __int64 startsector,
;          int* numsectors);
; return value: 0 = success, otherwise = error
  .write      dd ?
; int write(void* userdata, const void* buffer, __int64 startsector,
;           int* numsectors);
; Optional.
; return value: 0 = success, otherwise = error
  .flush      dd ?
; int flush(void* userdata);
; Optional.
; Flushes the hardware cache, if it exists. Note that a driver should not
; implement a software cache for read/write, since they are called from the
; kernel cache manager.
  .adjust_cache_size dd ?
; unsigned int adjust_cache_size(void* userdata, unsigned int suggested_size);
; Optional.
; Returns the cache size for this device in bytes. 0 = disable cache.
}
struc DISKMEDIAINFO
{
  .flags      dd ?
DISK_MEDIA_READONLY = 1
  .sectorsize dd ?
  .capacity   dq ?
}
void DiskDel(void* hDisk);
; This function informs the kernel that the disk should be deleted from the
; system. This function removes the disk from the global file system; however,
; it is possible that active operations with the disk are still running. When
; the disk is actually removed, the kernel calls the 'close' function, which
; can free all device-related resources.
void DiskMediaChanged(void* hDisk, int newstate);
; This function informs the kernel that a media has been inserted, removed or
; changed. 'newstate' should be zero if currently there is no media inserted
; and nonzero in the other case. This function must not be called with nonzero
; 'newstate' from any of callbacks. This function must not be called if another
; call to this function is active.

=== Timers ===
Timers allow to schedule a function call to some time in the future, once
or periodically. A timer function can do anything, including adding/removing
other timers and itself, but it should not run time-consuming tasks, since that
would block the processing thread for a long time; for such tasks it is
recommended to create new thread.

void* TimerHS(unsigned int deltaStart, unsigned int interval,
              void* timerFunc, void* userData);
; Registers a timer which is activated in (deltaStart == 0 ? deltaStart :
; interval) 1/100ths of second starting from the current time. If interval
; is zero, this timer is automatically deleted when activated. Otherwise,
; this timer will be activated every (interval) 1/100ths of second from the
; first activation. Activated timer calls timerFunc(userData) as stdcall.
; Returned value: NULL = failed, otherwise = timer handle which can be passed
; to CancelTimerHS.
void CancelTimerHS(void* hTimer);
; Cancels previously registered timer.