[ros-diffs] [greatlrd] 21852: adding doc for how DdCreateDirectDrawObject (GdiEntry1) and DdDeleteDirectDrawObject (GdiEntry3) works in reactos. doc by request by some devlopers

Author: greatlrd
Date: Mon May  8 20:48:10 2006
New Revision: 21852

URL: http://svn.reactos.ru/svn/reactos?rev=21852&view=rev
Log:
adding doc for how DdCreateDirectDrawObject (GdiEntry1) and DdDeleteDirectDrawObject
(GdiEntry3) works in reactos. doc by request by some devlopers 

Added:
    trunk/reactos/media/doc/DdCreateDirectDrawObject.txt   (with props)
    trunk/reactos/media/doc/DdDeleteDirectDrawObject.txt   (with props)
Modified:
    trunk/reactos/media/doc/LPC.txt   (contents, props changed)
    trunk/reactos/media/doc/books.txt   (contents, props changed)
    trunk/reactos/media/doc/irp cancel boilerplate.c   (contents, props changed)
    trunk/reactos/media/doc/locks.txt   (contents, props changed)
    trunk/reactos/media/doc/memcpy_optimize.txt   (props changed)

Added: trunk/reactos/media/doc/DdCreateDirectDrawObject.txt
URL:
http://svn.reactos.ru/svn/reactos/trunk/reactos/media/doc/DdCreateDirectDra…
==============================================================================
--- trunk/reactos/media/doc/DdCreateDirectDrawObject.txt (added)
+++ trunk/reactos/media/doc/DdCreateDirectDrawObject.txt Mon May  8 20:48:10 2006
@@ -1,0 +1,32 @@
+DdCreateDirectDrawObject  
+
+When IN HDC is not NULL
+1. we need check the IN HDC is NULL or not
+2. if it not null we need create a directdraw handler 
+   and store it to pDirectDrawGlobal->hDD
+3. if the directdraw handle is null return false
+   we did fail to create directdraw HAL 
+4. if the directdraw handle was not null we return true
+   we did susses to create directdraw HAL 
+ 
+When IN HDC is NULL   
+Now we come to if IN HDC is null basic we need create
+   a hdc and cashe some data
+1. if internal cache of directdraw handle is not null
(pDirectDrawGlobalInternal->hDD)
+   we take it and fill to the public directdraw handler (pDirectDrawGlobal->hDD)
+   and return susses.
+ 
+2.  if no internal cache of directdraw handle is found we need create it
+    by using CreateDC for tempary HDC that will be cache in the win32k later
+ 
+3.  we need check see if we got a tempary HDC or not, if we fail getting tempary 
+    HDC return FALSE
+ 
+4. Now we trying create directdraw handler it being cache to
(pDirectDrawGlobalInternal->hDD)
+   and it also set same handler to the public (pDirectDrawGlobal->hDD)
+5. if it fails to create directdraw handle return false
+   we did fail to create directdraw HAL 
+6. if it susses create directdraw handle return true
+   we did susses to create directdraw HAL    
+ 
+To create a directdraw handler you need call the NtGdiDdCreateDirectDrawObject with a
hdc

Propchange: trunk/reactos/media/doc/DdCreateDirectDrawObject.txt
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: trunk/reactos/media/doc/DdCreateDirectDrawObject.txt
------------------------------------------------------------------------------
    svn:keywords = author date id revision

Added: trunk/reactos/media/doc/DdDeleteDirectDrawObject.txt
URL:
http://svn.reactos.ru/svn/reactos/trunk/reactos/media/doc/DdDeleteDirectDra…
==============================================================================
--- trunk/reactos/media/doc/DdDeleteDirectDrawObject.txt (added)
+++ trunk/reactos/media/doc/DdDeleteDirectDrawObject.txt Mon May  8 20:48:10 2006
@@ -1,0 +1,16 @@
+DdDeleteDirectDrawObject
+
+we need release directdraw handler the cache or not cache handler
+1. check see if DirectDrawGlobal->hDD is NULL or not
+
+2. if both cache directdraw handler and public handler is NULL
+   then we need return false, fail to release it or it was already release
+
+3. if public directdraw handler is not null we need release it 
+   and return if we susses or not. 
+
+4. we need check if we need rest the internal cache if public being release
+     
+
+use  NtGdiDdDeleteDirectDrawObject((HANDLE)DirectDrawGlobal->hDD); 
+to release a directdraw handler. 

Propchange: trunk/reactos/media/doc/DdDeleteDirectDrawObject.txt
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: trunk/reactos/media/doc/DdDeleteDirectDrawObject.txt
------------------------------------------------------------------------------
    svn:keywords = author date id revision

Modified: trunk/reactos/media/doc/LPC.txt
URL:
http://svn.reactos.ru/svn/reactos/trunk/reactos/media/doc/LPC.txt?rev=21852…
==============================================================================
--- trunk/reactos/media/doc/LPC.txt (original)
+++ trunk/reactos/media/doc/LPC.txt Mon May  8 20:48:10 2006
@@ -1,53 +1,53 @@
-==============================================================
-=                                                            =
-=               NOTES FROM THE UNDERGROUND                   =
-=                                                            =
-==============================================================
-Below are some of Alex's notes on the mysterious LPC Subsystem
-
-=========================
-1. Sizes, sizes, sizes...
-=========================
-
-There are four imporant LPC Sizes to keep in mind. Try to understand them:
-
-/* 
- * This determines the absolute maximum message size (0x100 bytes). For
- * larger values, use a section-backed message.
- */
-#define PORT_MAXIMUM_MESSAGE_LENGTH 256
-
-/*
- * This determines the maximum length of an LPC request. It is the largest
- * amount of bytes that an LPC request can take. To calculate this, assume
- * that this is a CONNECTION_REQUEST message, which includes the additionnal
- * LPCP_CONNECTION_MESSAGE structure as well. Therefore, we add the kernel LPC,
- * header, the maximum port size and the size of the connection request 
- * structure. This gives a value of 0x15C. However, one must note that NT
- * allocates the Lookaside List using a 16-byte aligned value, making this
- * number 0x160.
- */
-#define LPCP_MAX_MESSAGE_SIZE   ROUND_UP(PORT_MAXIMUM_MESSAGE_LENGTH + \
-                                         sizeof(LPCP_MESSAGE) + \
-                                         sizeof(LPCP_CONNECTION_MESSAGE), 16)
-
-/*
- * Now, for an actual LPC Request size, we remove the kernel LPC header, which
- * yields the size of the actual LPC Data that follows the Header, making this
- * number 0x148.
- */
-#define LPC_MAX_MESSAGE_LENGTH (LPCP_MAX_MESSAGE_SIZE - \
-                                FIELD_OFFSET(LPCP_MESSAGE, Request))
-
-/*
- * Finally, we'll calculate the maximum size of the Connection Info, giving us
- * 0x104
- */
-#define LPC_MAX_DATA_LENGTH     (LPC_MAX_MESSAGE_LENGTH - \
-                                 sizeof(PORT_MESSAGE) - \
-                                 sizeof(LPCP_CONNECTION_MESSAGE))
-
-==========================
-2. Structures
-==========================
+==============================================================
+=                                                            =
+=               NOTES FROM THE UNDERGROUND                   =
+=                                                            =
+==============================================================
+Below are some of Alex's notes on the mysterious LPC Subsystem
+
+=========================
+1. Sizes, sizes, sizes...
+=========================
+
+There are four imporant LPC Sizes to keep in mind. Try to understand them:
+
+/* 
+ * This determines the absolute maximum message size (0x100 bytes). For
+ * larger values, use a section-backed message.
+ */
+#define PORT_MAXIMUM_MESSAGE_LENGTH 256
+
+/*
+ * This determines the maximum length of an LPC request. It is the largest
+ * amount of bytes that an LPC request can take. To calculate this, assume
+ * that this is a CONNECTION_REQUEST message, which includes the additionnal
+ * LPCP_CONNECTION_MESSAGE structure as well. Therefore, we add the kernel LPC,
+ * header, the maximum port size and the size of the connection request 
+ * structure. This gives a value of 0x15C. However, one must note that NT
+ * allocates the Lookaside List using a 16-byte aligned value, making this
+ * number 0x160.
+ */
+#define LPCP_MAX_MESSAGE_SIZE   ROUND_UP(PORT_MAXIMUM_MESSAGE_LENGTH + \
+                                         sizeof(LPCP_MESSAGE) + \
+                                         sizeof(LPCP_CONNECTION_MESSAGE), 16)
+
+/*
+ * Now, for an actual LPC Request size, we remove the kernel LPC header, which
+ * yields the size of the actual LPC Data that follows the Header, making this
+ * number 0x148.
+ */
+#define LPC_MAX_MESSAGE_LENGTH (LPCP_MAX_MESSAGE_SIZE - \
+                                FIELD_OFFSET(LPCP_MESSAGE, Request))
+
+/*
+ * Finally, we'll calculate the maximum size of the Connection Info, giving us
+ * 0x104
+ */
+#define LPC_MAX_DATA_LENGTH     (LPC_MAX_MESSAGE_LENGTH - \
+                                 sizeof(PORT_MESSAGE) - \
+                                 sizeof(LPCP_CONNECTION_MESSAGE))
+
+==========================
+2. Structures
+==========================
 SOON. TODO.

Propchange: trunk/reactos/media/doc/LPC.txt
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: trunk/reactos/media/doc/LPC.txt
------------------------------------------------------------------------------
    svn:keywords = author date id revision

Modified: trunk/reactos/media/doc/books.txt
URL:
http://svn.reactos.ru/svn/reactos/trunk/reactos/media/doc/books.txt?rev=218…
==============================================================================
--- trunk/reactos/media/doc/books.txt (original)
+++ trunk/reactos/media/doc/books.txt Mon May  8 20:48:10 2006
@@ -1,18 +1,18 @@
-References (Rex's at least)
-
-Baker, Art. The Windows NT Device Driver Book. Prentice Hall, 1997.
-Borate, Dabak & Phadke. Undocumented Windows NT. M&T Books, 1999.
-Brain, Marshall. Win32 System Services. Prentice Hall, 1996.
-Cant, Chris. Writing Windows WDM Device Drivers. R&D Books, 1999.
-Canton & Sanchez. IBM Microcomputers: A Programmer's Handbook. McGraw Hill,
1990.
-Davis & Wallace. Windows Undocumented File Formats. R&D Books, 1997.
-Mason & Viscarola. Windows NT Device Driver Development. Macmillan, 1999.
-Mitchell, Stan. Inside the Windows 95 File System. O'Reilly, 1997.
-Murray, James D. Windows NT Event Logging. O'Reilly, 1998.
-Nagar, Rajeev. Windows NT File System Internals. O'Reilly, 1997.
-Osbourne, Sandra. Windows NT Registry: A Settings Reference. New Riders, 1998.
-Pietrek, Matt. Windows 95 System Programming Secrets. IDG, 1995.
-Richter, Jeffery. Advanced Windows, 3rd ed. Microsoft, 1997.
-Simon, Richard J. Windows NT Win32 API Superbible. Waite Group, 1996.
-Solomon, David A. Inside Windows NT, 2nd Ed. Microsoft, 1998.
-"The NT Insider." Open Systems Resources, 1999-2000.
+References (Rex's at least)
+
+Baker, Art. The Windows NT Device Driver Book. Prentice Hall, 1997.
+Borate, Dabak & Phadke. Undocumented Windows NT. M&T Books, 1999.
+Brain, Marshall. Win32 System Services. Prentice Hall, 1996.
+Cant, Chris. Writing Windows WDM Device Drivers. R&D Books, 1999.
+Canton & Sanchez. IBM Microcomputers: A Programmer's Handbook. McGraw Hill,
1990.
+Davis & Wallace. Windows Undocumented File Formats. R&D Books, 1997.
+Mason & Viscarola. Windows NT Device Driver Development. Macmillan, 1999.
+Mitchell, Stan. Inside the Windows 95 File System. O'Reilly, 1997.
+Murray, James D. Windows NT Event Logging. O'Reilly, 1998.
+Nagar, Rajeev. Windows NT File System Internals. O'Reilly, 1997.
+Osbourne, Sandra. Windows NT Registry: A Settings Reference. New Riders, 1998.
+Pietrek, Matt. Windows 95 System Programming Secrets. IDG, 1995.
+Richter, Jeffery. Advanced Windows, 3rd ed. Microsoft, 1997.
+Simon, Richard J. Windows NT Win32 API Superbible. Waite Group, 1996.
+Solomon, David A. Inside Windows NT, 2nd Ed. Microsoft, 1998.
+"The NT Insider." Open Systems Resources, 1999-2000.

Propchange: trunk/reactos/media/doc/books.txt
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: trunk/reactos/media/doc/books.txt
------------------------------------------------------------------------------
    svn:keywords = author date id revision

Modified: trunk/reactos/media/doc/irp cancel boilerplate.c
URL:
http://svn.reactos.ru/svn/reactos/trunk/reactos/media/doc/irp%20cancel%20bo…
==============================================================================
--- trunk/reactos/media/doc/irp cancel boilerplate.c (original)
+++ trunk/reactos/media/doc/irp cancel boilerplate.c Mon May  8 20:48:10 2006
@@ -1,103 +1,103 @@
-
-
-/*
-Boiler plate for irp cancelation, for irp queues you manage yourself
--Gunnar
-*/
-
-
-
-CancelRoutine(
-   DEV_OBJ Dev,
-   Irp
-   )
-{
-   //don't need this since we have our own sync. protecting irp cancellation
-   IoReleaseCancelSpinLock(Irp->CancelIrql); 
- 
-   theLock = Irp->Tail.Overlay.DriverContext[3];
- 
-   Lock(theLock);   
-   RemoveEntryList(&Irp->Tail.Overlay.ListEntry);
-   Unlock(theLock);
- 
-   Irp->IoStatus.Status = STATUS_CANCELLED;
-   Irp->IoStatus.Information = 0;
- 
-   IoCompleteRequest(Irp, IO_NO_INCREMENT);
- 
-}
- 
- 
-QUEUE_BOLIERPLATE
-{
-   Lock(theLock);
- 
-   Irp->Tail.Overlay.DriverContext[3] = &theLock;
- 
-   IoSetCancelRoutine(Irp, CancelRoutine);
-   if (Irp->Cancel && IoSetCancelRoutine(Irp, NULL))
-   {              
-      /*
-      Irp has already been cancelled (before we got to queue it),
-      and we got to remove the cancel routine before the canceler could, 
-      so we cancel/complete the irp ourself.
-      */
-      
-      Unlock(theLock);
- 
-      Irp->IoStatus.Status = STATUS_CANCELLED;
-      Irp->IoStatus.Information = 0;
-      IoCompleteRequest(Irp, IO_NO_INCREMENT);
- 
-      return FALSE;
-   }
- 
-   //else were ok   
- 
- 
-   Irp->IoStatus.Status = STATUS_PENDING;
-   IoMarkIrpPending(Irp);
- 
-   InsertTailList(Queue);
-   
-   Unlock(theLock);
- 
-}
- 
- 
-DEQUEUE_BOILERPLATE
-{
-   Lock(theLock);
- 
-   Irp = RemoveHeadList(Queue);
- 
-   if (!IoSetCancelRoutine(Irp, NULL))
-   {
-      /*
-      Cancel routine WILL be called after we release the spinlock. It will try to remove

-      the irp from the list and cancel/complete this irp. Since we allready removed it, 
-      make its ListEntry point to itself.
-      */
- 
-      InitializeListHead(&Irp->Tail.Overlay.ListEntry);
-      
-      Unlock(theLock);
-      
-      return;
-   } 
- 
- 
-   /*
-   Cancel routine will NOT be called, canceled or not.
-   The Irp might have been canceled (Irp->Cancel flag set) but we don't care,
-   since we are to complete this Irp now anyways.
-   */
- 
-   Unlock(theLock);
- 
-   Irp->IoStatus.Status = STATUS_SUCCESS;
-   Irp->IoStatus.Information = 0;
-   IoCompleteRequest(Irp, IO_NO_INCREMENT);
- 
-}
+
+
+/*
+Boiler plate for irp cancelation, for irp queues you manage yourself
+-Gunnar
+*/
+
+
+
+CancelRoutine(
+   DEV_OBJ Dev,
+   Irp
+   )
+{
+   //don't need this since we have our own sync. protecting irp cancellation
+   IoReleaseCancelSpinLock(Irp->CancelIrql); 
+ 
+   theLock = Irp->Tail.Overlay.DriverContext[3];
+ 
+   Lock(theLock);   
+   RemoveEntryList(&Irp->Tail.Overlay.ListEntry);
+   Unlock(theLock);
+ 
+   Irp->IoStatus.Status = STATUS_CANCELLED;
+   Irp->IoStatus.Information = 0;
+ 
+   IoCompleteRequest(Irp, IO_NO_INCREMENT);
+ 
+}
+ 
+ 
+QUEUE_BOLIERPLATE
+{
+   Lock(theLock);
+ 
+   Irp->Tail.Overlay.DriverContext[3] = &theLock;
+ 
+   IoSetCancelRoutine(Irp, CancelRoutine);
+   if (Irp->Cancel && IoSetCancelRoutine(Irp, NULL))
+   {              
+      /*
+      Irp has already been cancelled (before we got to queue it),
+      and we got to remove the cancel routine before the canceler could, 
+      so we cancel/complete the irp ourself.
+      */
+      
+      Unlock(theLock);
+ 
+      Irp->IoStatus.Status = STATUS_CANCELLED;
+      Irp->IoStatus.Information = 0;
+      IoCompleteRequest(Irp, IO_NO_INCREMENT);
+ 
+      return FALSE;
+   }
+ 
+   //else were ok   
+ 
+ 
+   Irp->IoStatus.Status = STATUS_PENDING;
+   IoMarkIrpPending(Irp);
+ 
+   InsertTailList(Queue);
+   
+   Unlock(theLock);
+ 
+}
+ 
+ 
+DEQUEUE_BOILERPLATE
+{
+   Lock(theLock);
+ 
+   Irp = RemoveHeadList(Queue);
+ 
+   if (!IoSetCancelRoutine(Irp, NULL))
+   {
+      /*
+      Cancel routine WILL be called after we release the spinlock. It will try to remove

+      the irp from the list and cancel/complete this irp. Since we allready removed it, 
+      make its ListEntry point to itself.
+      */
+ 
+      InitializeListHead(&Irp->Tail.Overlay.ListEntry);
+      
+      Unlock(theLock);
+      
+      return;
+   } 
+ 
+ 
+   /*
+   Cancel routine will NOT be called, canceled or not.
+   The Irp might have been canceled (Irp->Cancel flag set) but we don't care,
+   since we are to complete this Irp now anyways.
+   */
+ 
+   Unlock(theLock);
+ 
+   Irp->IoStatus.Status = STATUS_SUCCESS;
+   Irp->IoStatus.Information = 0;
+   IoCompleteRequest(Irp, IO_NO_INCREMENT);
+ 
+}

Propchange: trunk/reactos/media/doc/irp cancel boilerplate.c
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: trunk/reactos/media/doc/irp cancel boilerplate.c
------------------------------------------------------------------------------
    svn:keywords = author date id revision

Modified: trunk/reactos/media/doc/locks.txt
URL:
http://svn.reactos.ru/svn/reactos/trunk/reactos/media/doc/locks.txt?rev=218…
==============================================================================
--- trunk/reactos/media/doc/locks.txt (original)
+++ trunk/reactos/media/doc/locks.txt Mon May  8 20:48:10 2006
@@ -1,39 +1,39 @@
-Next-Gen (NT 5.2) Executive Locks in NTOSKRNL.
-------------------------------
-1a. Rundown Protection
-USED IN: Thread/Process Ps* Code.
-EXAMPLES: NtSetInformationProcess/Thread, PspCreateThread/Process,
PspSuspend/ResumeThread...
-REPLACES: Unlocked access and/or PsLock/UnlockProcess.
-ROS STATUS: Implemented. Code needs cleanup. Not yet tested. Not yet used.
-
-1b. Cache-Aware Rundown Protection
-USED IN: Unknown. Functions exported for drivers.
-EXAMPLES: None.
-REPLACES: Nothing.
-ROS STATUS: Unimplemented.
-
-2. Guarded Mutex
-USED IN: Configuration Manager, MCB Functions (FsRtl), Binary Hive Module (Hv), PnP
(Notifications), LPC, Jobs (Ps), Device Map (Ob), and Memory Management (Address
Space/Virtual Memory).
-EXAMPLES: Too many.
-REPLACES: Anything that used FAST_MUTEX.
-ROS STATUS: Implemented, slightly tested; appears to still contain a bug.
-
-3. Fast Referencing
-USED IN: Tokens.
-EXAMPLES: R: PsReferencePrimary/EffectiveToken. D: Failure code of anything that calls
those two functions.
-REPLACES: Normal referencing.
-ROS STATUS: Hackplemented stubs.
-
-4a. Pushlocks
-USED IN: Configuration Manager (Cm), Handle Table (Ex), Binary Hive Module (Hv), Memory
Management (Address Space/Virtual Memory), Object Namespace (Directories/Names) (Ob),
Impersonation (Ps).
-EXAMPLES: Too many.
-REPLACES: Anything that used ERESOURCE.
-ROS STATUS: Implemented (missing Block/([Timed]Wait)Unblock) and slightly tested.
-
-4b. Cache-Aware Pushlocks
-USED IN: AWE (Mm).
-EXAMPLES: None.
-REPLACES: Executive Resources.
-ROS STATUS: Unimplemented.
-
+Next-Gen (NT 5.2) Executive Locks in NTOSKRNL.
+------------------------------
+1a. Rundown Protection
+USED IN: Thread/Process Ps* Code.
+EXAMPLES: NtSetInformationProcess/Thread, PspCreateThread/Process,
PspSuspend/ResumeThread...
+REPLACES: Unlocked access and/or PsLock/UnlockProcess.
+ROS STATUS: Implemented. Code needs cleanup. Not yet tested. Not yet used.
+
+1b. Cache-Aware Rundown Protection
+USED IN: Unknown. Functions exported for drivers.
+EXAMPLES: None.
+REPLACES: Nothing.
+ROS STATUS: Unimplemented.
+
+2. Guarded Mutex
+USED IN: Configuration Manager, MCB Functions (FsRtl), Binary Hive Module (Hv), PnP
(Notifications), LPC, Jobs (Ps), Device Map (Ob), and Memory Management (Address
Space/Virtual Memory).
+EXAMPLES: Too many.
+REPLACES: Anything that used FAST_MUTEX.
+ROS STATUS: Implemented, slightly tested; appears to still contain a bug.
+
+3. Fast Referencing
+USED IN: Tokens.
+EXAMPLES: R: PsReferencePrimary/EffectiveToken. D: Failure code of anything that calls
those two functions.
+REPLACES: Normal referencing.
+ROS STATUS: Hackplemented stubs.
+
+4a. Pushlocks
+USED IN: Configuration Manager (Cm), Handle Table (Ex), Binary Hive Module (Hv), Memory
Management (Address Space/Virtual Memory), Object Namespace (Directories/Names) (Ob),
Impersonation (Ps).
+EXAMPLES: Too many.
+REPLACES: Anything that used ERESOURCE.
+ROS STATUS: Implemented (missing Block/([Timed]Wait)Unblock) and slightly tested.
+
+4b. Cache-Aware Pushlocks
+USED IN: AWE (Mm).
+EXAMPLES: None.
+REPLACES: Executive Resources.
+ROS STATUS: Unimplemented.
+
 TODO: Kernel Locks (Queued and In-Stack Spinlocks)

Propchange: trunk/reactos/media/doc/locks.txt
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: trunk/reactos/media/doc/locks.txt
------------------------------------------------------------------------------
    svn:keywords = author date id revision

Propchange: trunk/reactos/media/doc/memcpy_optimize.txt
------------------------------------------------------------------------------
    svn:keywords = author date id revision