# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1614554576 -3600
# Node ID 18b94d0fe7a6fbe44f49926f517e160058f9aade
# Parent  b9368c4d902b4e00ef62de9731cc3f3793e45e9d
Renamed context_open to file_context, reordered definitions and added comments.

diff -r b9368c4d902b -r 18b94d0fe7a6 dstest_test_client.cc
--- a/dstest_test_client.cc	Sun Feb 28 23:28:45 2021 +0100
+++ b/dstest_test_client.cc	Mon Mar 01 00:22:56 2021 +0100
@@ -138,7 +138,7 @@
 
 static long context_for_file(unsigned long fileid, file_t *file, l4_cap_idx_t server)
 {
-  long err = context_open(file, server);
+  long err = file_context(file, server);
 
   if (err)
   {
diff -r b9368c4d902b -r 18b94d0fe7a6 file.cc
--- a/file.cc	Sun Feb 28 23:28:45 2021 +0100
+++ b/file.cc	Mon Mar 01 00:22:56 2021 +0100
@@ -31,25 +31,7 @@
 
 
 
-offset_t file_span(file_t *file)
-{
-  offset_t size = file->end_pos - file->start_pos;
-
-  return (file->data_end < size) ? file->data_end : size;
-}
-
-void file_init(file_t *file)
-{
-  file->memory = NULL;
-  file->ref = L4_INVALID_CAP;
-}
-
-long file_open(file_t *file, l4_cap_idx_t context_ref)
-{
-  client_OpenerContext context(context_ref);
-  file_init(file);
-  return context.open(L4_FPAGE_RW, &file->size, &file->ref);
-}
+/* Release resources for the given file. */
 
 void file_close(file_t *file)
 {
@@ -62,18 +44,9 @@
   file_init(file);
 }
 
-long file_mmap(file_t *file, offset_t position, offset_t length)
-{
-  client_MappedFile mapped_file(file->ref);
-  long err = mapped_file.mmap(position, length, &file->start_pos, &file->end_pos, &file->data_end);
+/* Initialise a file structure for a context obtained from the given server. */
 
-  if (err)
-    return err;
-
-  return ipc_attach_dataspace(file->ref, file->end_pos - file->start_pos, (void **) &file->memory);
-}
-
-long context_open(file_t *file, l4_cap_idx_t server)
+long file_context(file_t *file, l4_cap_idx_t server)
 {
   client_Opener opener(server);
   unsigned long size, flags;
@@ -95,4 +68,43 @@
   return ipc_attach_dataspace(file->ref, size, (void **) &file->memory);
 }
 
+/* Initialise the given file structure. */
+
+void file_init(file_t *file)
+{
+  file->memory = NULL;
+  file->ref = L4_INVALID_CAP;
+}
+
+/* Map a region of the given file to a memory region. */
+
+long file_mmap(file_t *file, offset_t position, offset_t length)
+{
+  client_MappedFile mapped_file(file->ref);
+  long err = mapped_file.mmap(position, length, &file->start_pos, &file->end_pos, &file->data_end);
+
+  if (err)
+    return err;
+
+  return ipc_attach_dataspace(file->ref, file->end_pos - file->start_pos, (void **) &file->memory);
+}
+
+/* Open a file using the given structure and context reference. */
+
+long file_open(file_t *file, l4_cap_idx_t context_ref)
+{
+  client_OpenerContext context(context_ref);
+  file_init(file);
+  return context.open(L4_FPAGE_RW, &file->size, &file->ref);
+}
+
+/* Return the amount of data in the mapped region for the given file. */
+
+offset_t file_span(file_t *file)
+{
+  offset_t size = file->end_pos - file->start_pos;
+
+  return (file->data_end < size) ? file->data_end : size;
+}
+
 // vim: tabstop=2 expandtab shiftwidth=2
diff -r b9368c4d902b -r 18b94d0fe7a6 file.h
--- a/file.h	Sun Feb 28 23:28:45 2021 +0100
+++ b/file.h	Mon Mar 01 00:22:56 2021 +0100
@@ -25,18 +25,37 @@
 
 
 
+EXTERN_C_BEGIN
+
+/* File access abstraction. */
+
 typedef struct
 {
+  /* File object reference. */
+
   l4_cap_idx_t ref;
+
+  /* Mapped memory accessing a file region. */
+
   char *memory;
-  offset_t start_pos, end_pos, data_end, size;
+
+  /* File region parameters. */
+
+  offset_t start_pos, end_pos;  /* start and end of region */
+  offset_t data_end;            /* amount of data in the region */
+  offset_t size;                /* total size of file */
+
 } file_t;
 
-offset_t file_span(file_t *file);
+/* File access operations. */
+
+void file_close(file_t *file);
+long file_context(file_t *file, l4_cap_idx_t server);
 void file_init(file_t *file);
+long file_mmap(file_t *file, offset_t position, offset_t length);
 long file_open(file_t *file, l4_cap_idx_t context_ref);
-void file_close(file_t *file);
-long file_mmap(file_t *file, offset_t position, offset_t length);
-long context_open(file_t *file, l4_cap_idx_t server);
+offset_t file_span(file_t *file);
+
+EXTERN_C_END
 
 // vim: tabstop=2 expandtab shiftwidth=2