WebSVN – Kolibri OS – Diff – /kernel/trunk/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.

Subversion Repositories Kolibri OS

(root)/kernel/trunk/docs/drivers_api.txt @ 8089 – Rev 2455 → 7727

Rev 2455		Rev 7727
1	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;	1	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
2	;; ;;	2	;; ;;
3	;; Copyright (C) KolibriOS team 2011-2012. All rights reserved. ;;	3	;; Copyright (C) KolibriOS team 2011-2012. All rights reserved. ;;
4	;; Distributed under terms of the GNU General Public License ;;	4	;; Distributed under terms of the GNU General Public License ;;
5	;; ;;	5	;; ;;
6	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;	6	;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
7		7
8	All functions are stdcall unless mentioned otherwise.	8	All functions are stdcall unless mentioned otherwise.
9		9
10	=== Disk ===	10	=== Disk ===
11	The kernel exports the functions 'DiskAdd', 'DiskMediaChanged', 'DiskDel' for	11	The kernel exports the functions 'DiskAdd', 'DiskMediaChanged', 'DiskDel' for
12	drivers. They must be called in the following order: DiskAdd, then zero or	12	drivers. They must be called in the following order: DiskAdd, then zero or
13	more DiskMediaChanged, then optionally DiskDel. The driver must not call	13	more DiskMediaChanged, then optionally DiskDel. The driver must not call
14	two functions in parallel, including two calls to DiskMediaChanged.	14	two functions in parallel, including two calls to DiskMediaChanged.
15		15
16	void* DiskAdd(DISKFUNC* functions, const char* name, void* userdata, int flags);	16	void* DiskAdd(DISKFUNC* functions, const char* name, void* userdata, int flags);
17	; The pointer 'functions' must be valid at least until the disk will be deleted	17	; The pointer 'functions' must be valid at least until the disk will be deleted
18	; (until DISKFUNC.close is called).	18	; (until DISKFUNC.close is called).
19	; The pointer 'name' can be invalid after this function returns.	19	; The pointer 'name' can be invalid after this function returns.
20	; It should point to ASCIIZ-string without leading '/' in latin lowercase and	20	; It should point to ASCIIZ-string without leading '/' in latin lowercase and
21	; digits, like 'usbhd0'.	21	; digits, like 'usbhd0'.
22	; The value 'userdata' is any pointer-sized data, passed as is to all	22	; The value 'userdata' is any pointer-sized data, passed as is to all
23	; callbacks.	23	; callbacks.
24	DISK_NO_INSERT_NOTIFICATION = 1	24	DISK_NO_INSERT_NOTIFICATION = 1
25	; The bitfield 'flags' has currently only one bit defined. If it is set, the	25	; The bitfield 'flags' has currently only one bit defined. If it is set, the
26	; driver will never call DiskMediaChanged(hDisk, true), so the kernel must scan	26	; driver will never call DiskMediaChanged(hDisk, true), so the kernel must scan
27	; for media insertion when the operation is requested.	27	; for media insertion when the operation is requested.
28	struc DISKFUNC	28	struc DISKFUNC
29	{	29	{
30	.strucsize dd ?	30	.strucsize dd ?
31	.close dd ?	31	.close dd ?
32	; void close(void* userdata);	32	; void close(void* userdata);
33	; Optional.	33	; Optional.
34	; The last function that is called for the given disk. The kernel calls it when	34	; The last function that is called for the given disk. The kernel calls it when
35	; the kernel has finished all operations with the disk and it is safe to free	35	; the kernel has finished all operations with the disk and it is safe to free
36	; all driver-specific data identified by 'userdata'.	36	; all driver-specific data identified by 'userdata'.
37	.closemedia dd ?	37	.closemedia dd ?
38	; void closemedia(void* userdata);	38	; void closemedia(void* userdata);
39	; Optional.	39	; Optional.
40	; The kernel calls this function when it finished all processing with the	40	; The kernel calls this function when it finished all processing with the
41	; current media. If media is removed, the driver should decline all requests	41	; current media. If media is removed, the driver should decline all requests
42	; to that media with DISK_STATUS_NO_MEDIA, even if new media is inserted,	42	; to that media with DISK_STATUS_NO_MEDIA, even if new media is inserted,
43	; until this function is called. If media is removed, a new call to	43	; until this function is called. If media is removed, a new call to
44	; DiskMediaChanged(hDisk, true) is not allowed until this function is called.	44	; DiskMediaChanged(hDisk, true) is not allowed until this function is called.
45	.querymedia dd ?	45	.querymedia dd ?
46	; int querymedia(void* userdata, DISKMEDIAINFO* info);	46	; int querymedia(void* userdata, DISKMEDIAINFO* info);
47	; return value: 0 = success, otherwise = error	47	; return value: 0 = success, otherwise = error
48	.read dd ?	48	.read dd ?
49	; int read(void* userdata, void* buffer, __int64 startsector,	49	; int read(void* userdata, void* buffer, __int64 startsector,
50	; int* numsectors);	50	; int* numsectors);
51	; return value: 0 = success, otherwise = error	51	; return value: 0 = success, otherwise = error
52	.write dd ?	52	.write dd ?
53	; int write(void* userdata, const void* buffer, __int64 startsector,	53	; int write(void* userdata, const void* buffer, __int64 startsector,
54	; int* numsectors);	54	; int* numsectors);
55	; Optional.	55	; Optional.
56	; return value: 0 = success, otherwise = error	56	; return value: 0 = success, otherwise = error
57	.flush dd ?	57	.flush dd ?
58	; int flush(void* userdata);	58	; int flush(void* userdata);
59	; Optional.	59	; Optional.
60	; Flushes the hardware cache, if it exists. Note that a driver should not	60	; Flushes the hardware cache, if it exists. Note that a driver should not
61	; implement a software cache for read/write, since they are called from the	61	; implement a software cache for read/write, since they are called from the
62	; kernel cache manager.	62	; kernel cache manager.
63	.adjust_cache_size dd ?	63	.adjust_cache_size dd ?
64	; unsigned int adjust_cache_size(unsigned int suggested_size);	64	; unsigned int adjust_cache_size(void* userdata, unsigned int suggested_size);
65	; Optional.	65	; Optional.
66	; Returns the cache size for this device in bytes. 0 = disable cache.	66	; Returns the cache size for this device in bytes. 0 = disable cache.
67	}	67	}
68	struc DISKMEDIAINFO	68	struc DISKMEDIAINFO
69	{	69	{
70	.flags dd ?	70	.flags dd ?
71	DISK_MEDIA_READONLY = 1	71	DISK_MEDIA_READONLY = 1
72	.sectorsize dd ?	72	.sectorsize dd ?
73	.capacity dq ?	73	.capacity dq ?
74	}	74	}
75	void DiskDel(void* hDisk);	75	void DiskDel(void* hDisk);
76	; This function informs the kernel that the disk should be deleted from the	76	; This function informs the kernel that the disk should be deleted from the
77	; system. This function removes the disk from the global file system; however,	77	; system. This function removes the disk from the global file system; however,
78	; it is possible that active operations with the disk are still running. When	78	; it is possible that active operations with the disk are still running. When
79	; the disk is actually removed, the kernel calls the 'close' function, which	79	; the disk is actually removed, the kernel calls the 'close' function, which
80	; can free all device-related resources.	80	; can free all device-related resources.
81	void DiskMediaChanged(void* hDisk, int newstate);	81	void DiskMediaChanged(void* hDisk, int newstate);
82	; This function informs the kernel that a media has been inserted, removed or	82	; This function informs the kernel that a media has been inserted, removed or
83	; changed. 'newstate' should be zero if currently there is no media inserted	83	; changed. 'newstate' should be zero if currently there is no media inserted
84	; and nonzero in the other case. This function must not be called with nonzero	84	; and nonzero in the other case. This function must not be called with nonzero
85	; 'newstate' from any of callbacks. This function must not be called if another	85	; 'newstate' from any of callbacks. This function must not be called if another
86	; call to this function is active.	86	; call to this function is active.
87		87
88	=== Timers ===	88	=== Timers ===
89	Timers allow to schedule a function call to some time in the future, once	89	Timers allow to schedule a function call to some time in the future, once
90	or periodically. A timer function can do anything, including adding/removing	90	or periodically. A timer function can do anything, including adding/removing
91	other timers and itself, but it should not run time-consuming tasks, since that	91	other timers and itself, but it should not run time-consuming tasks, since that
92	would block the processing thread for a long time; for such tasks it is	92	would block the processing thread for a long time; for such tasks it is
93	recommended to create new thread.	93	recommended to create new thread.
94		94
95	void* TimerHS(unsigned int deltaStart, unsigned int interval,	95	void* TimerHS(unsigned int deltaStart, unsigned int interval,
96	void* timerFunc, void* userData);	96	void* timerFunc, void* userData);
97	; Registers a timer which is activated in (deltaStart == 0 ? deltaStart :	97	; Registers a timer which is activated in (deltaStart == 0 ? deltaStart :
98	; interval) 1/100ths of second starting from the current time. If interval	98	; interval) 1/100ths of second starting from the current time. If interval
99	; is zero, this timer is automatically deleted when activated. Otherwise,	99	; is zero, this timer is automatically deleted when activated. Otherwise,
100	; this timer will be activated every (interval) 1/100ths of second from the	100	; this timer will be activated every (interval) 1/100ths of second from the
101	; first activation. Activated timer calls timerFunc(userData) as stdcall.	101	; first activation. Activated timer calls timerFunc(userData) as stdcall.
102	; Returned value: NULL = failed, otherwise = timer handle which can be passed	102	; Returned value: NULL = failed, otherwise = timer handle which can be passed
103	; to CancelTimerHS.	103	; to CancelTimerHS.
104	void CancelTimerHS(void* hTimer);	104	void CancelTimerHS(void* hTimer);
105	; Cancels previously registered timer.	105	; Cancels previously registered timer.