0 | module Data.C.Array8
  1 |
  2 | import Control.Monad.Resource
  3 | import Data.C.Integer
  4 | import Data.C.Array
  5 | import Data.Linear.ELift1
  6 | import Data.Vect
  7 |
  8 | import public Data.Fin
  9 | import public Data.Linear.Token
 10 | import public Data.Array.Index
 11 |
 12 | import Syntax.T1
 13 |
 14 | %default total
 15 |
 16 | export %foreign "scheme,chez:(lambda (x y z) (foreign-set! 'unsigned-8 x y z))"
 17 | prim__setbits8 : AnyPtr -> Integer -> Bits8 -> PrimIO ()
 18 |
 19 | export %foreign "scheme,chez:(lambda (x y) (foreign-ref 'unsigned-8 x y))"
 20 | prim__getbits8 : AnyPtr -> Integer -> Bits8
 21 |
 22 | --------------------------------------------------------------------------------
 23 | -- Immutable API
 24 | --------------------------------------------------------------------------------
 25 |
 26 | export
 27 | record CIArray8 (n : Nat) where
 28 |   constructor IA
 29 |   ptr : AnyPtr
 30 |
 31 | export %inline
 32 | at : CIArray8 n -> Fin n -> Bits8
 33 | at r x = prim__getbits8 r.ptr (cast $ finToNat x)
 34 |
 35 | export %inline
 36 | ix : CIArray8 n -> (0 m : Nat) -> (x : Ix (S m) n) => Bits8
 37 | ix r m = at r (ixToFin x)
 38 |
 39 | export %inline
 40 | atNat : CIArray8 n -> (m : Nat) -> (0 lt : LT m n) => Bits8
 41 | atNat r m = at r (natToFinLT m)
 42 |
 43 | foldrI : (m : Nat) -> (0 _ : LTE m n) => (Bits8 -> b -> b) -> b -> CIArray8 n -> b
 44 | foldrI 0     _ x r = x
 45 | foldrI (S k) f x r = foldrI k f (f (atNat r k) x) r
 46 |
 47 | foldrKV_ :
 48 |      (m : Nat)
 49 |   -> {auto 0 prf : LTE m n}
 50 |   -> (Fin n -> Bits8 -> b -> b)
 51 |   -> b
 52 |   -> CIArray8 n
 53 |   -> b
 54 | foldrKV_ 0     _ x r = x
 55 | foldrKV_ (S k) f x r =
 56 |   let fin := natToFinLT k @{prf} in foldrKV_ k f (f fin (at r fin) x) r
 57 |
 58 | foldlI : (m : Nat) -> (x : Ix m n) => (b -> Bits8 -> b) -> b -> CIArray8 n -> b
 59 | foldlI 0     _ v r = v
 60 | foldlI (S k) f v r = foldlI k f (f v (ix r k)) r
 61 |
 62 | foldlKV_ :
 63 |      (m : Nat)
 64 |   -> {auto x : Ix m n}
 65 |   -> (Fin n -> b -> Bits8 -> b)
 66 |   -> b
 67 |   -> CIArray8 n
 68 |   -> b
 69 | foldlKV_ 0     _ v r = v
 70 | foldlKV_ (S k) f v r =
 71 |   let fin := ixToFin x in foldlKV_ k f (f fin v (at r fin)) r
 72 |
 73 | ontoVect :
 74 |      (r : CIArray8 n)
 75 |   -> Vect m Bits8
 76 |   -> (k : Nat)
 77 |   -> {auto 0 lt : LTE k n}
 78 |   -> Vect (m+k) Bits8
 79 | ontoVect r vs 0     = rewrite plusCommutative m 0 in vs
 80 | ontoVect r vs (S x) =
 81 |   let v := atNat r x {lt}
 82 |    in rewrite sym (plusSuccRightSucc m x) in ontoVect r (v::vs) x
 83 |
 84 | ||| Reads the values from a C pointer into a vector.
 85 | export %inline
 86 | toVect : {n : _} -> (r : CIArray8 n) -> Vect n Bits8
 87 | toVect r = ontoVect r [] n
 88 |
 89 | ||| Right fold over the values of an array plus their indices.
 90 | export %inline
 91 | foldrKV : {n : _} -> (Fin n -> Bits8 -> b -> b) -> b -> CIArray8 n -> b
 92 | foldrKV = foldrKV_ n
 93 |
 94 | ||| Right fold over the values of an array
 95 | export %inline
 96 | foldr : {n : _} -> (Bits8 -> b -> b) -> b -> CIArray8 n -> b
 97 | foldr = foldrI n
 98 |
 99 | ||| Left fold over the values of an array plus their indices.
100 | export %inline
101 | foldlKV : {n : _} -> (Fin n -> b -> Bits8 -> b) -> b -> CIArray8 n -> b
102 | foldlKV = foldlKV_ n
103 |
104 | ||| Left fold over the values of an array
105 | export %inline
106 | foldl : {n : _} -> (b -> Bits8 -> b) -> b -> CIArray8 n -> b
107 | foldl = foldlI n
108 |
109 | --------------------------------------------------------------------------------
110 | -- Mutable C Arrays
111 | --------------------------------------------------------------------------------
112 |
113 | ||| A wrapped pointer to a C-array holding `n` unsigned 8-bit
114 | ||| values (C-primitive).
115 | |||
116 | ||| Reading from and writing to such an array is O(1) and runs in `IO`.
117 | |||
118 | ||| See `CArray8` for a pure version of mutable C arrays using linear types.
119 | ||| See `CArray8S` for a pure versoin of mutable C arrays using linear types (overwritting/scrubbing before freeing).
120 | ||| See `CArray8IO` for a version of mutable C arrays usable in IO.
121 | ||| See `CArray8IOS` for a version of the mutable C arrays usuable in IO (overwritting/scrubbing before freeing)
122 | |||
123 | ||| Note : In typical use cases, the memory allocated for a C array must
124 | |||        be manually released with a call to `free` unless it is part
125 | |||        of a larger structure `Struct` or managed by an external library.
126 | export
127 | record PrimCArray8 (s : Type) (b : Bool) (n : Nat) where
128 |   constructor PCA8
129 |   ptr : AnyPtr
130 |
131 | ||| Convenience alias for `PrimCArray8 s False n a`
132 | public export
133 | 0 CArray8 : (s : Type) -> (n : Nat) -> Type
134 | CArray8 s n = PrimCArray8 s False n
135 |
136 | ||| Convenience alias for `PrimCArray8 s True n a`
137 | public export
138 | 0 CArray8S : (s : Type) -> (n : Nat) -> Type
139 | CArray8S s n = PrimCArray8 s True n
140 |
141 | ||| Convenience alias for `PrimCArray8 World False n a`
142 | public export
143 | 0 CArray8IO : (n : Nat) -> Type
144 | CArray8IO n = PrimCArray8 World False n
145 |
146 | ||| Convenience alias for `PrimCArray8 World True n a`
147 | public export
148 | 0 CArray8IOS : (n : Nat) -> Type
149 | CArray8IOS n = PrimCArray8 World True n
150 |
151 | export %inline
152 | unsafeUnwrap : CArray8 s n -> AnyPtr
153 | unsafeUnwrap = ptr
154 |
155 | export %inline
156 | unsafeWrap : AnyPtr -> CArray8 s n
157 | unsafeWrap = PCA8
158 |
159 | --------------------------------------------------------------------------------
160 | -- Linear API
161 | --------------------------------------------------------------------------------
162 |
163 | ||| Allocates a new C-pointer of `sizeof a * n` bytes.
164 | export %inline
165 | malloc1 : (n : Nat) -> F1 s (PrimCArray8 s b n)
166 | malloc1 n t =
167 |   let p := prim__malloc (cast n)
168 |    in PCA8 p # t
169 |
170 | ||| Like `malloc1` but resets all allocated bytes to zero.
171 | export %inline
172 | calloc1 : (n : Nat) -> F1 s (PrimCArray8 s b n)
173 | calloc1 n t =
174 |   let p := prim__calloc (cast n) 1
175 |    in PCA8 p # t
176 |
177 | ||| Frees the memory allocated for a C array without
178 | ||| overwriting its contents.
179 | export %inline
180 | free1 : (r : CArray8 s n) -> F1' s
181 | free1 r = ffi (prim__free r.ptr)
182 |
183 | ||| Overwrites the contents of a C array before freeing
184 | ||| the underlying memory.
185 | export %inline
186 | frees1 : {n : Nat} -> (r : CArray8S s n) -> F1' s
187 | frees1 {n} r t =
188 |   let () # t := ffi (prim__scrub r.ptr (cast n)) t
189 |    in ffi (prim__free r.ptr) t
190 |
191 | parameters {0 n      : Nat}
192 |            (r        : PrimCArray8 s b n)
193 |
194 |   ||| Reads a value from a C-pointer at the given position.
195 |   export %inline
196 |   get : Fin n -> F1 s Bits8
197 |   get x t = prim__getbits8 r.ptr (cast $ finToNat x) # t
198 |
199 |   ||| Reads a value from a C-pointer at the given position.
200 |   export %inline
201 |   getIx : (0 m : Nat) -> (x : Ix (S m) n) => F1 s Bits8
202 |   getIx m = get (ixToFin x)
203 |
204 |   ||| Reads a value from a C-pointer at the given position.
205 |   export %inline
206 |   getNat : (m : Nat) -> (0 lt : LT m n) => F1 s Bits8
207 |   getNat m = get (natToFinLT m)
208 |
209 |   ||| Writes a value to a C pointer at the given position.
210 |   export %inline
211 |   set : Fin n -> Bits8 -> F1' s
212 |   set x v = ffi $ prim__setbits8 r.ptr (cast $ finToNat x) v
213 |
214 |   ||| Writes a value to a C pointer at the given position.
215 |   export %inline
216 |   setIx : (0 m : Nat) -> (x : Ix (S m) n) => Bits8 -> F1' s
217 |   setIx m = set (ixToFin x)
218 |
219 |   ||| Writes a value to a C pointer at the given position.
220 |   export %inline
221 |   setNat : (m : Nat) -> (0 lt : LT m n) => Bits8 -> F1' s
222 |   setNat m = set (natToFinLT m)
223 |
224 |   writeVect1 : Vect k Bits8 -> Ix k n => F1' s
225 |   writeVect1           []        t = () # t
226 |   writeVect1 {k = S m} (x :: xs) t =
227 |     let _ # t := Array8.setIx m x t
228 |      in writeVect1 xs t
229 |
230 |   ||| Writes the values from a vector to a C pointer
231 |   export %inline
232 |   writeVect : Vect n Bits8 -> F1' s
233 |   writeVect as = writeVect1 as
234 |
235 |   ||| Temporarily wraps the mutable array in an immutable wrapper and
236 |   ||| run a computation with that.
237 |   |||
238 |   ||| This is safe, because the pure function cannot possibly share the
239 |   ||| immutable array by storing it in a mutable reference. It is
240 |   ||| referentially transparent, because we call it from a linear context.
241 |   export %inline
242 |   withIArray : (CIArray8 n -> c) -> F1 s c
243 |   withIArray f t = f (IA r.ptr) # t
244 |
245 | ||| Writes the values from a list to a C pointer
246 | export %inline
247 | writeList : (as : List Bits8) -> PrimCArray8 s b (length as) -> F1' s
248 | writeList as r = writeVect r (fromList as)
249 |
250 | ||| Allocates a C array, runs a computation, and releases
251 | ||| the array using the supplied cleanup operation.
252 | |||
253 | ||| The Boolean index is erased because cleanup behavior
254 | ||| is supplied explicitly rather than selected by inspecting b.
255 | export
256 | withPrimCArray8 :
257 |      {0 b : Bool}
258 |   -> (n : Nat)
259 |   -> (release : forall s . PrimCArray8 s b n -> F1' s)
260 |   -> (f : forall s . PrimCArray8 s b n -> F1 s c)
261 |   -> c
262 | withPrimCArray8 n release f =
263 |   run1 $ \t =>
264 |     let r  # t := Array8.malloc1 n t
265 |         v  # t := f r t
266 |         () # t := release r t
267 |      in v # t
268 |
269 | ||| Allocates a C array, runs a computation, and frees
270 | ||| the underlying memory afterward.
271 | export
272 | withCArray :
273 |      (n : Nat)
274 |   -> (f : forall s . CArray8 s n -> F1 s b)
275 |   -> b
276 | withCArray n f =
277 |   withPrimCArray8 n free1 f
278 |
279 | ||| Allocates a C array, runs a computation, and securely
280 | ||| scrubs the underlying memory before freeing it.
281 | export
282 | withCArrayS :
283 |      (n : Nat)
284 |   -> (f : forall s . CArray8S s n -> F1 s b)
285 |   -> b
286 | withCArrayS n f =
287 |   withPrimCArray8 n frees1 f
288 |
289 | --------------------------------------------------------------------------------
290 | -- Lift1 API
291 | --------------------------------------------------------------------------------
292 |
293 | parameters {auto has : Lift1 s f}
294 |
295 |   ||| Allocates a new C-pointer of `sizeof a * n` bytes.
296 |   export %inline
297 |   malloc : (n : Nat) -> f (PrimCArray8 s b n)
298 |   malloc n = lift1 (malloc1 n)
299 |
300 |   ||| Like `malloc` but resets all allocated bytes to zero.
301 |   export %inline
302 |   calloc : (n : Nat) -> f (PrimCArray8 s b n)
303 |   calloc n = lift1 (calloc1 n)
304 |
305 |   ||| Frees a C array without scrubbing its contents.
306 |   |||
307 |   ||| Note: Only call this if the C array is no longer used and has been
308 |   |||       allocated via a call to `malloc` or `alloc` (either in C land
309 |   |||       or in Idris). Afterwards, it is no longer safe to use the array
310 |   |||       for reading or writing, nor is it safe to call `free` on it again.
311 |   |||
312 |   |||       For safe resource management, use the linear version of
313 |   |||       C arrays if possible. Otherwise, consider using a safer monad
314 |   |||       than `IO` if possible.
315 |   export %inline
316 |   free : CArray8 s n -> f ()
317 |   free arr = lift1 (free1 arr)
318 |
319 |   ||| Scrubs and frees a C array.
320 |   |||
321 |   ||| Note: Only call this if the C array is no longer used and has been
322 |   |||       allocated via a call to `malloc` or `alloc` (either in C land
323 |   |||       or in Idris). Afterwards, it is no longer safe to use the array
324 |   |||       for reading or writing, nor is it safe to call `free` on it again.
325 |   |||
326 |   |||       For safe resource management, use the linear version of
327 |   |||       C arrays if possible. Otherwise, consider using a safer monad
328 |   |||       than `IO` if possible.
329 |   export %inline
330 |   frees : {n : Nat} -> CArray8S s n -> f ()
331 |   frees arr = lift1 (frees1 arr)
332 |
333 |   export %inline
334 |   fromList : (as : List Bits8) -> f (PrimCArray8 s b (length as))
335 |   fromList as = Prelude.do
336 |     arr <- Array8.malloc (length as)
337 |     lift1 $ writeList as arr
338 |     pure arr
339 |
340 | --------------------------------------------------------------------------------
341 | -- Resource
342 | --------------------------------------------------------------------------------
343 |
344 | export %inline
345 | ELift1 s f => Resource f (CArray8 s n) where
346 |   cleanup arr = lift1 (free1 arr)
347 |
348 | export %inline
349 | {n : Nat} -> ELift1 s f => Resource f (CArray8S s n) where
350 |   cleanup arr = lift1 (frees1 arr)
351 |