0.17.0 --- the atoms an OS library composes, part of a region published, and the image a loader starts

README.md

@@ -77,16 +77,16 @@ conditional on the target.
 
 ```toml
 [dependencies]
-openkal = "0.16.0"
+openkal = "0.17.0"
 
 [target.'cfg(os = "linux")'.dependencies]
-openkal-linux = "0.15.1"
+openkal-linux = "0.18.0"
 
 [target.'cfg(os = "macos")'.dependencies]
-openkal-macos = "0.12.1"
+openkal-macos = "0.15.0"
 
 [target.'cfg(windows)'.dependencies]
-openkal-windows = "0.10.2"
+openkal-windows = "0.13.0"
 ```
 
 The program imports the interface and names no implementation.
@@ -115,6 +115,7 @@ its own. The layer names are those of the build tool (`mcpp`, *The Target Side*)
 | `c-abi = musl` | `openkal-musl` | a POSIX-shaped C environment built on `kal_*`; what it cannot provide it refuses and lists | the platform's own C runtime headers (`io.h`, `TargetConditionals.h`); facilities openkal does not define (`epoll`, signal handlers) |
 | `c++-abi = libc++` | `openkal-llvm-runtime` | a C++ runtime configured for that C library | |
 | build tool | `mcpp` | a layer supplied by the dependency graph is supplied wholly by it: the host's headers and libraries are not searched | whether a package's source compiles against that C library |
+| image (`<arch>-openkal`, clause 12) | `openkal-image`'s loader, holding one implementation | the same bytes run in every environment of the architecture that has a loader; a required interface the implementation lacks is refused at load and named | a platform format, signature or installer (a program carrying the image as a native executable provides those) |
 
 Four rules follow, and they bind packages rather than this specification.
 

SURFACE.txt

@@ -1,4 +1,4 @@
-# The C surface of openkal 0.16, one name per line.
+# The C surface of openkal 0.17, one name per line.
 #
 # This file is normative and is the single source consulted by clause 9. A
 # conforming implementation exports the names of the interfaces it provides
@@ -37,6 +37,9 @@ kal_memory_granularity
 # openkal.env
 kal_env_arg
 kal_env_arg_count
+kal_env_image
+kal_env_loader
+kal_env_system
 kal_env_var
 kal_env_var_at
 kal_env_var_count
@@ -69,6 +72,7 @@ kal_fs_preopen_count
 kal_fs_props
 kal_fs_remove
 kal_fs_rename
+kal_fs_rename_flags
 kal_fs_seek
 kal_fs_set_executable_at
 kal_fs_set_modified
@@ -80,12 +84,16 @@ kal_fs_unlock
 kal_process_channel
 kal_process_channel_close
 kal_process_close
+kal_process_end_as_requested
+kal_process_info
 kal_process_job_close
 kal_process_job_enter
 kal_process_job_terminate
+kal_process_open_id
 kal_process_props
-kal_process_stop_requested
+kal_process_self
 kal_process_spawn
+kal_process_stop_requested
 kal_process_terminate
 kal_process_wait
 # openkal.task
@@ -102,8 +110,10 @@ kal_task_yield
 # openkal.exec
 kal_exec_alloc
 kal_exec_free
+kal_exec_granularity
 kal_exec_props
 kal_exec_publish
+kal_exec_publish_part
 # openkal.terminal
 kal_terminal_get_mode
 kal_terminal_props
@@ -114,7 +124,9 @@ kal_net_accept
 kal_net_close
 kal_net_close_listener
 kal_net_connect
+kal_net_connect_at
 kal_net_listen
+kal_net_listen_at
 kal_net_listener_local
 kal_net_local
 kal_net_peer

conformance/src/declarations.c

@@ -37,13 +37,18 @@ void okc_declarations_c(void)
     (void)sizeof(&kal_datagram_send_to);
     (void)sizeof(&kal_env_arg);
     (void)sizeof(&kal_env_arg_count);
+    (void)sizeof(&kal_env_image);
+    (void)sizeof(&kal_env_loader);
+    (void)sizeof(&kal_env_system);
     (void)sizeof(&kal_env_var);
     (void)sizeof(&kal_env_var_at);
     (void)sizeof(&kal_env_var_count);
     (void)sizeof(&kal_exec_alloc);
     (void)sizeof(&kal_exec_free);
+    (void)sizeof(&kal_exec_granularity);
     (void)sizeof(&kal_exec_props);
     (void)sizeof(&kal_exec_publish);
+    (void)sizeof(&kal_exec_publish_part);
     (void)sizeof(&kal_exit);
     (void)sizeof(&kal_free);
     (void)sizeof(&kal_fs_capacity);
@@ -65,6 +70,7 @@ void okc_declarations_c(void)
     (void)sizeof(&kal_fs_props);
     (void)sizeof(&kal_fs_remove);
     (void)sizeof(&kal_fs_rename);
+    (void)sizeof(&kal_fs_rename_flags);
     (void)sizeof(&kal_fs_seek);
     (void)sizeof(&kal_fs_set_executable_at);
     (void)sizeof(&kal_fs_set_modified);
@@ -78,7 +84,9 @@ void okc_declarations_c(void)
     (void)sizeof(&kal_net_close);
     (void)sizeof(&kal_net_close_listener);
     (void)sizeof(&kal_net_connect);
+    (void)sizeof(&kal_net_connect_at);
     (void)sizeof(&kal_net_listen);
+    (void)sizeof(&kal_net_listen_at);
     (void)sizeof(&kal_net_listener_local);
     (void)sizeof(&kal_net_local);
     (void)sizeof(&kal_net_peer);
@@ -88,10 +96,14 @@ void okc_declarations_c(void)
     (void)sizeof(&kal_process_channel);
     (void)sizeof(&kal_process_channel_close);
     (void)sizeof(&kal_process_close);
+    (void)sizeof(&kal_process_end_as_requested);
+    (void)sizeof(&kal_process_info);
     (void)sizeof(&kal_process_job_close);
     (void)sizeof(&kal_process_job_enter);
     (void)sizeof(&kal_process_job_terminate);
+    (void)sizeof(&kal_process_open_id);
     (void)sizeof(&kal_process_props);
+    (void)sizeof(&kal_process_self);
     (void)sizeof(&kal_process_spawn);
     (void)sizeof(&kal_process_stop_requested);
     (void)sizeof(&kal_process_terminate);

conformance/src/sections/child.cpp

@@ -35,6 +35,7 @@ const char* argument_for(errand e) {
         case errand::wait_to_be_terminated: return "--child-wait";
         case errand::report_grants:      return "--child-grants";
         case errand::report_no_preopens: return "--child-no-preopens";
+        case errand::end_as_requested:   return "--child-end-as-requested";
         case errand::none:               break;
     }
     return "";
@@ -54,6 +55,7 @@ errand child_errand() {
         if (same(a, len, argument_for(errand::wait_to_be_terminated))) return errand::wait_to_be_terminated;
         if (same(a, len, argument_for(errand::report_grants)))      return errand::report_grants;
         if (same(a, len, argument_for(errand::report_no_preopens))) return errand::report_no_preopens;
+        if (same(a, len, argument_for(errand::end_as_requested)))   return errand::end_as_requested;
     }
 #endif
     return errand::none;
@@ -132,6 +134,21 @@ after g_after;
             kal_exit(34);
         case errand::abort_with_message:
             kal_abort("openkal-conformance: the message kal_abort was given\n", 52);
+        case errand::end_as_requested:
+            // The word is taken over, awaited for two seconds, and the copy then
+            // ends as the request would have. 98: no request arrived as one ---
+            // the environment ended this copy outright, or never asked. 99: the
+            // operation returned although a request had arrived.
+#if defined(MCPP_FEATURE_PROCESS) && defined(MCPP_FEATURE_TIME)
+            if (const kal_u32* word = kal_process_stop_requested()) {
+                kal_stream_write(kal_stdout(), "ARMED\n", 6);
+                for (int i = 0; i < 400 && *word == 0; ++i) kal_time_sleep(5u * 1000u * 1000u);
+                if (*word == 0) kal_exit(98);
+                kal_process_end_as_requested();
+                kal_exit(99);
+            }
+#endif
+            kal_exit(98);
         case errand::wait_to_be_terminated:
 #ifdef MCPP_FEATURE_TIME
             for (;;) kal_time_sleep(5u * 1000u * 1000u);

conformance/src/sections/child.cppm

@@ -25,6 +25,7 @@ enum class errand {
     wait_to_be_terminated,   // so that a request to terminate has something to reach
     report_grants,       // the directories a starter granted are its preopens
     report_no_preopens,  // ... and a count of zero leaves it none (clause 7.13)
+    end_as_requested,    // takes the request over, then ends as it would have (0.17)
 };
 
 // The names the starter grants and the copy expects, in order, and the marker

conformance/src/sections/env.cpp

@@ -31,6 +31,35 @@ void run() {
     char buf[room];
     const kal_uintptr count = kal_env_arg_count();
 
+    // The image and the system (version 0.17): a name, or not found; and the
+    // length the value has, as every enquiry here reports it.
+    {
+        const kal_intptr n = kal_env_image(buf, room);
+        observe(kind::behaviour, n > 0 || n == -kal_err_not_found,
+                "the image a program was started from is named, or not found");
+        observe(kind::behaviour, kal_env_image(nullptr, 0) == n,
+                "a capacity of zero reports the image's length without writing");
+    }
+    {
+        // Built for its environment, a program has no loader to name; an image
+        // is told the program that runs it.
+        const kal_intptr n = kal_env_loader(buf, room);
+        observe(kind::behaviour, n > 0 || n == -kal_err_not_found,
+                "the loader of an image is named, and a program built for its environment has none");
+        observe(kind::behaviour, kal_env_loader(nullptr, 0) == n,
+                "a capacity of zero reports the loader's length without writing");
+    }
+    {
+        const kal_intptr n = kal_env_system(buf, room);
+        bool lower = n > 0 && n < static_cast<kal_intptr>(room);
+        for (kal_intptr i = 0; lower && i < n; ++i)
+            lower = (buf[i] >= 'a' && buf[i] <= 'z') || (buf[i] >= '0' && buf[i] <= '9');
+        observe(kind::behaviour, lower || n == -kal_err_not_found,
+                "the system is a lower-case name, or not found");
+        observe(kind::behaviour, kal_env_system(nullptr, 0) == n,
+                "a capacity of zero reports the system's length without writing");
+    }
+
     // Position zero is the name by which the program was started, and an
     // environment that has no such name reports an empty string rather than
     // omitting it --- so the count is at least one on every environment.

conformance/src/sections/exec.cpp

@@ -145,6 +145,42 @@ void run() {
         unobserved(kind::behaviour, "openkal.exec",
                    "the implementation does not report republishing");
     }
+
+    // PART OF A REGION (version 0.17). Two granules: the first published and
+    // executed, the second written AFTER the first was published --- which is
+    // what a loader does with an image's data beside its instructions.
+    const kal_uintptr g = kal_exec_granularity();
+    observe(kind::behaviour, g != 0 && (g & (g - 1)) == 0,
+            "the protection granularity is a power of two");
+    if (g != 0) {
+        observe(kind::behaviour, kal_exec_publish_part(nullptr, 0, g) != kal_ok,
+                "publishing part of no region is refused");
+        void* r = kal_exec_alloc(2 * g);
+        observe(kind::behaviour, r != nullptr, "a region of two granules is reserved");
+        if (r != nullptr) {
+            auto* c = static_cast<unsigned char*>(r);
+            for (unsigned long i = 0; i < kReturns42Size; ++i) c[i] = kReturns42[i];
+            observe(kind::behaviour, kal_exec_publish_part(r, 0, g / 2 == 0 ? 1 : g / 2) == kal_err_invalid,
+                    "a part that is not a multiple of the granularity is refused");
+            observe(kind::behaviour, kal_exec_publish_part(r, 0, g) == kal_ok,
+                    "the first granule is published");
+#if defined(__GNUC__) || defined(__clang__)
+            __builtin___clear_cache(static_cast<char*>(r), static_cast<char*>(r) + kReturns42Size);
+#endif
+            c[g] = 7;
+            c[g + 1] = static_cast<unsigned char>(c[g] + 1);
+            observe(kind::behaviour, c[g + 1] == 8,
+                    "the part not published is still writable");
+            fn h = nullptr;
+            {
+                auto* d = reinterpret_cast<unsigned char*>(&h);
+                const auto* b = reinterpret_cast<const unsigned char*>(&r);
+                for (unsigned long i = 0; i < sizeof h; ++i) d[i] = b[i];
+            }
+            observe(kind::behaviour, h() == 42, "the published part is executed");
+            kal_exec_free(r, 2 * g);
+        }
+    }
 #endif
 }