1Posted by Rudolf Nov 22, 2005 to the haiku-appsever ML: 2http://www.freelists.org/post/haiku-appserver/new-drawing-bug-Rudolf-some-stuff-for-you,10 3 4More good info @ http://www.freelists.org/archive/haiku-appserver 5 6 Be Docs (file: R4_Graphics_Driver_Docs): 7 8 Engine Synchronization 9 10 B_ACCELERANT_ENGINE_COUNT - No feature specific data required. 11 Return the number of acceleration engines that the device may operate in parallel. 12 It's not required for all engines to be equally capable (i.e. support the same 13 acceleration features). 14 15 B_ACQUIRE_ENGINE - No feature specific data required. 16 Request exclusive ownership of an acceleration engine with the capabilities mask specified. 17 The caller is willing to wait up to max_wait micro(milli?)-seconds. If the request can't be 18 fullfilled before that time expires, the accelerant should return B_WOULD_BLOCK immediatly. 19 If non-zero, sync_token points to a synchronization token retrieved from either 20 release_engine() or get_sync_token() to which the engine should be synchronized before 21 engine acquisition succeeds. See B_SYNC_TO_TOKEN for more details. The engine_token for 22 the successfully acquired engine is returned in engine_token **et. 23 24 B_RELEASE_ENGINE - No feature specific data required. 25 Relinquish exclusive ownership of the engine specified by engine_token et. If 26 sync_token *st is non-zero, return a sync_token which can be utilized to ensure that the 27 specified engine has completed all acceleration operations issued up this point in time. 28 29 B_WAIT_ENGINE_IDLE - No feature specific data required. 30 Wait for the graphics device to be completely idle (i.e. no current running or pending 31 acceleration primitives, DMA transfers, etc.). 32 33 B_GET_SYNC_TOKEN - No feature specific data required. 34 Return a synchronization token for the specified engine. sync_token *st must point at 35 a sync_token which will be updated with the information required to ensure that a call to 36 sync_to_token() will be able to ensure that the specified engine has completed all of the 37 acceleration primitives, DMA transfers, etc. that have been issued up to this point in time. 38 39 B_SYNC_TO_TOKEN - No feature specific data required. 40 Ensure that the engine specified in sync_token *st has completed the acceleration 41 primitives, DMA transfers, etc., issued up to the point in time specified in the sync_token. 42 43 44 Rudolf's notes. 45 info on engine_token: 46 47 uint32 ACCELERANT_ENGINE_COUNT(void) 48 exists because in theory a single card can have multiple independant acceleration engines. 49 For instance one that can do 2D, and one that can do 3D (or combinations). See 50 'engine capabilities' flags in Accelerant.h. 51 (note: never seen multiple engines per card yet though. Was this meant for some very old 52 hardware with seperate 2D and 3D 'blocks'? Although I guess it's thinkable that multiple 53 equally capable engines would exist as well..) 54 55 In order to distinquish between multiple engines all acceleration commands are given along 56 with an engine_token *et, aquired when 57 status_t ACQUIRE_ENGINE(uint32 capabilities, uint32 max_wait, sync_token *st, engine_token **et) 58 was called. 59 status_t SYNC_TO_TOKEN(sync_token *st) 60 is an exeption: here the engine is ID'd by member: (defined in Accelerant.h) 61 uint32 engine_id. 62 void WAIT_ENGINE_IDLE(void) 63 is an exeption also because this function returns only when *ALL* engines are completely 64 idle. Hence no need for distinction. 65 66 Furthermore the absense of the use of engine_token in both SYNC_TO_TOKEN and WAIT_ENGINE_IDLE 67 would seem to indicate these hooks may be used *without having acquired the engine*. (?). 68 69 70 info on sync_token: 71 72-- How does the acceleration cmd interface work? There's a circular buffer that stores cmd's. 73 There's a hardware pointer that points 'at' the command currently being executed (think 74 of stacks: some architectures point to the first 'free' location, some to the 'last used' 75 location.) 76 There's also a second pointer which points at the first free location, i.e. where new cmd's 77 will be stored pending execution. This second pointer is a software maintained pointer (in 78 the driver). 79 80-- What's a sync_token? A Sync_token in nothing more than a extra pointer (one per token). This 81 pointer points at the first free location in the cmd buffer at that point in time the 82 sync_token was 'filled'. In theory it doesn't change during the (rest of the) life-time of 83 the token, although the driver-implementation could (?) do that anyway for some internal 84 reason. 85 Driver users (i.e. app_server) are responsible for reserving memory for a sync_token. They 86 pass a pointer to it to the driver (if they want to use it). The driver in turns fills it 87 with the needed info. Driver users may never modify the content of the sync_token(s). 88 89-- When would a user be interested in a sync_token? If multiple independant (so non-overlapping) 90 'regions' require multiple updates each alternatingly done by software and acceleration engine, 91 it might be interesting to use sync_tokens (for instance). 92 It would be possible to issue all engine commands concerning area #1, ask for a sync token, 93 issue all engine commands concerning area #2, and then do this: 94 - SYNC_TO_TOKEN (so waiting until all engine commands concerning area #1 are done); 95 - Draw in area #1 using software (while the acc engine is in the process of updating area #2: 96 (so some 'parallel processing' is done here). 97 98 If no sync token would be used, instead of syncing to token, wait_engine_idle would be used. 99 This of course would mean that no 'parallel processing' could be done... 100 Worse yet: if some seperate user is also using the engine (between RELEASE and AQUIRE engine 101 done by 'user #1' (i.e. app_server), the acc engine might *never* become fully idle. 102 A nice example here would be 3D acceleration: as long as no non-accelerated drawing has to be 103 done there, there's no reason the engine would need to be idle at all for this (apart from 104 processing 'user-input' like joystick controls). 105 You see: an acceleration engine automatically serializes it's cmd processing so update errors 106 because of out-of-order execution wouldn't happen. 107 108-- Why didn't I implement sync_token stuff in the matrox, nvidia and neomagic drivers? 109 Lack of 'known specs' yet. You see, even if the pointers in the cmd buffer are known: that's 110 not enough yet: 111 - The fact that an command is fetched from the buffer does *not* mean it's 112 execution is completely done. 113 - The implementation via just a pointer is not enough: if you wait too long, the current 114 free pointer might have cycled around the buffer. This means a simple compare to that 115 pointer is not conclusive. Much better would be actually inserting 'dummy commands' inside 116 the command buffer at the place a sync_token is generated. This dummy commands would be 117 executed just once, when we reached our goal. If the dummy command clears a variable 118 especially setup for the sync_token in question: we would have a conclusive result without 119 even the use of an actual pointer in the sync_token. AND: updating the tokens would have no 120 software overhead, as the acc engine would do it. (via 'pointers only' some invalidation 121 code has to be executed once the hardware pointer cycles around). 122 123 NOTE PLEASE: 124 This information is based upon my understanding of hardware inner workings. As this 125 understanding grows and is corrected over time, I might contradict myself later on if 126 asked again. :-) 127 128 129//actual hooks: 130 uint32 ACCELERANT_ENGINE_COUNT(void); 131 status_t ACQUIRE_ENGINE(uint32 capabilities, uint32 max_wait, 132sync_token *st, engine_token **et); 133 status_t RELEASE_ENGINE(engine_token *et, sync_token *st); 134 status_t GET_SYNC_TOKEN(engine_token *et, sync_token *st); 135 status_t SYNC_TO_TOKEN(sync_token *st); 136 void WAIT_ENGINE_IDLE(void); 137