1NOTE: The comments in this file relate to the original WinCE port
2done by Tristan Savatier. The semaphore routines have been
3completely rewritten since (2005-04-25), having been progressively
4broken more and more by changes to the library. All of the semaphore
5routines implemented for W9x/WNT/2000 and up should now also work for
6WinCE. Also, pthread_mutex_timedlock should now work.
7
8Additional WinCE updates have been applied since this as well. Check the
9ChangeLog file and search for WINCE for example. (2007-01-07)
10
11[RPJ]
12
13----
14
15Some interesting news:
16
17I have been able to port pthread-win32 to Windows-CE,
18which uses a subset of the WIN32 API.
19
20Since we intend to keep using pthread-win32 for our
21Commercial WinCE developments, I would be very interested
22if WinCE support could be added to the main source tree
23of pthread-win32.  Also, I would like to be credited
24for this port :-)
25
26Now, here is the story...
27
28The port was performed and tested on a Casio "Cassiopeia"
29PalmSize PC, which runs a MIP processor.  The OS in the
30Casio is WinCE version 2.11, but I used VC++ 6.0 with
31the WinCE SDK for version 2.01.
32
33I used pthread-win32 to port a heavily multithreaded
34commercial application (real-time MPEG video player)
35from Linux to WinCE.  I consider the changes that
36I have done to be quite well tested.
37
38Overall the modifications that we had to do are minor.
39
40The WinCE port were based on pthread-win32-snap-1999-05-30,
41but I am certain that they can be integrated very easiely
42to more recent versions of the source.
43
44I have attached the modified source code:
45pthread-win32-snap-1999-05-30-WinCE.
46
47All the changes do not affect the code compiled on non-WinCE
48environment, provided that the macros used for WinCE compilation
49are not used, of course!
50
51Overall description of the WinCE port:
52-------------------------------------
53
54Most of the changes had to be made in areas where
55pthread-win32 was relying on some standard-C librairies
56(e.g. _ftime, calloc, errno), which are not available
57on WinCE. We have changed the code to use native Win32
58API instead (or in some cases we made wrappers).
59
60The Win32 Semaphores are not available,
61so we had to re-implement Semaphores using mutexes
62and events.
63
64Limitations / known problems of the WinCE port:
65----------------------------------------------
66
67Not all the semaphore routines have been ported
68(semaphores are defined by Posix but are not part
69pf pthread).  I have just done enough to make
70pthread routines (that rely internally on semaphores)
71work, like signal conditions.
72
73I noticed that the Win32 threads work slightly
74differently on WinCE.  This may have some impact
75on some tricky parts of pthread-win32, but I have
76not really investigated.  For example, on WinCE,
77the process is killed if the main thread falls off
78the bottom (or calls pthread_exit), regardless
79of the existence of any other detached thread.
80Microsoft manual indicates that this behavior is
81deffirent from that of Windows Threads for other
82Win32 platforms.
83
84
85Detailed descriptions of the changes and rationals:
86
87------------------------------------
88- use a new macro NEED_ERRNO.
89
90If defined, the code in errno.c that defines a reentrant errno
91is compiled, regardless of _MT and _REENTRANT.
92
93Rational: On WinCE, there is no support for <stdio.h>, <errno.h> or
94any other standard C library, i.e. even if _MT or _REENTRANT
95is defined, errno is not provided by any library.  NEED_ERRNO
96must be set to compile for WinCE.
97
98------------------------------------
99- In implement.h, change #include <semaphore.h> to #include "semaphore.h".
100
101Rational: semaphore.h is provided in pthread-win32 and should not
102be searched in the systems standard include.  would not compile.
103This change does not seem to create problems on "classic" win32
104(e.g. win95).
105
106------------------------------------
107- use a new macro NEED_CALLOC.
108
109If defined, some code in misc.c will provide a replacement
110for calloc, which is not available on Win32.
111
112
113------------------------------------
114- use a new macro NEED_CREATETHREAD.
115
116If defined, implement.h defines the macro _beginthreadex
117and _endthreadex.
118
119Rational: On WinCE, the wrappers _beginthreadex and _endthreadex
120do not exist. The native Win32 routines must be used.
121
122------------------------------------
123- in misc.c:
124
125#ifdef NEED_DUPLICATEHANDLE
126	  /* DuplicateHandle does not exist on WinCE */
127	  self->threadH = GetCurrentThread();
128#else
129	  if( !DuplicateHandle(
130			       GetCurrentProcess(),
131			       GetCurrentThread(),
132			       GetCurrentProcess(),
133			       &self->threadH,
134			       0,
135			       FALSE,
136			       DUPLICATE_SAME_ACCESS ) )
137	    {
138	      free( self );
139	      return (NULL);
140	    }
141#endif
142
143Rational: On WinCE, DuplicateHandle does not exist.  I could not understand
144why DuplicateHandle must be used.  It seems to me that getting the current
145thread handle with GetCurrentThread() is sufficient, and it seems to work
146perfectly fine, so maybe DuplicateHandle was just plain useless to begin with ?
147
148------------------------------------
149- In private.c, added some code at the beginning of ptw32_processInitialize
150to detect the case of multiple calls to ptw32_processInitialize.
151
152Rational: In order to debug pthread-win32, it is easier to compile
153it as a regular library (it is not possible to debug DLL's on winCE).
154In that case, the application must call ptw32_rocessInitialize()
155explicitely, to initialize pthread-win32.  It is safer in this circumstance
156to handle the case where ptw32_processInitialize() is called on
157an already initialized library:
158
159int
160ptw32_processInitialize (void)
161{
162	if (ptw32_processInitialized) {
163		/*
164		 * ignore if already initialized. this is useful for
165		 * programs that uses a non-dll pthread
166		 * library. such programs must call ptw32_processInitialize() explicitely,
167		 * since this initialization routine is automatically called only when
168		 * the dll is loaded.
169		 */
170		return TRUE;
171	}
172    ptw32_processInitialized = TRUE;
173  	[...]
174}
175
176------------------------------------
177- in private.c, if macro NEED_FTIME is defined, add routines to
178convert timespec_to_filetime and filetime_to_timespec, and modified
179code that was using _ftime() to use Win32 API instead.
180
181Rational: _ftime is not available on WinCE.  It is necessary to use
182the native Win32 time API instead.
183
184Note: the routine timespec_to_filetime is provided as a convenience and a mean
185to test that filetime_to_timespec works, but it is not used by the library.
186
187------------------------------------
188- in semaphore.c, if macro NEED_SEM is defined, add code for the routines
189_increase_semaphore and _decrease_semaphore, and modify significantly
190the implementation of the semaphores so that it does not use CreateSemaphore.
191
192Rational: CreateSemaphore is not available on WinCE.  I had to re-implement
193semaphores using mutexes and Events.
194
195Note: Only the semaphore routines that are used by pthread are implemented
196(i.e. signal conditions rely on a subset of the semaphores routines, and
197this subset works). Some other semaphore routines (e.g. sem_trywait) are
198not yet supported on my WinCE port (and since I don't need them, I am not
199planning to do anything about them).
200
201------------------------------------
202- in tsd.c, changed the code that defines TLS_OUT_OF_INDEXES
203
204/* TLS_OUT_OF_INDEXES not defined on WinCE */
205#ifndef TLS_OUT_OF_INDEXES
206#define TLS_OUT_OF_INDEXES 0xffffffff
207#endif
208
209Rational: TLS_OUT_OF_INDEXES is not defined in any standard include file
210on WinCE.
211
212------------------------------------
213- added file need_errno.h
214
215Rational: On WinCE, there is no errno.h file. need_errno.h is just a
216copy of windows version of errno.h, with minor modifications due to the fact
217that some of the error codes are defined by the WinCE socket library.
218In pthread.h, if NEED_ERRNO is defined, the file need_errno.h is
219included (instead of <errno.h>).
220
221
222-- eof
223