Add SOLID target support

[kawadakk]

This PR adds support for *-kmc-solid_*, a new Tier 3 target.

[newpavlov]

Thank you! Looks good apart from small nits.

[newpavlov]

It would be nice to link a relevant documentation if it's available publicly.

[kawadakk]

No, it's not available publicly (yet).

[josephlr]

@newpavlov are you OK merging pre-release OS support? Or do you want to wait for external documentation?

[josephlr]

It looks like the OS is documented here: http://solid.kmckk.com/doc/skit/current/solid_os.html (in-browser Google translate is a must if you do not speak Japanese).

I found references to functions like:

• SOLID_MEM_Alloc
• SOLID_RTC_ReadTime
• SOLID_TIMER_Suspend

However, there's no reference to SOLID_RNG_SampleRandomBytes. @kawadakk is this some sort of extension to the base SOLID system?

[kawadakk]

It's optional but indeed included in the base system. It's added quite recently, and the documentation hasn't been updated yet.

[josephlr]

Awesome! If that's the case I'd be fine with adding this support now.

[josephlr]

@kawadakk is there documentation for SOLID_RNG_SampleRandomBytes anywhere? I'd love to update out documentation for this.

[kawadakk]

@josephlr Sorry, it's still unavailable. I'd be happy to provide information if you have something specific in mind.

[josephlr]

Oh I just wanted to:

• add a link to our docs when one is available
• make sure that the signature for SOLID_RNG_SampleRandomBytes is correct.
  • We currently have the signature declaration as: fn(*mut u8, usize) -> i32
  • Similar functions in the SOLID docs have signatures like fn(*mut c_void, usize) -> c_int
  • I realize this signatures are API compatible, but we generally want to have our declarations exactly match those in the relevant OS docs.

[newpavlov]

For consistency with other targets it would be nice to use ret instead of er here. Also is there a meaningful information in those error code? If not, it may be worth to return a fixed constant as we do for example with iOS.

[kawadakk]

Yes, it contains meaningful information, such as -1001 (SOLID_ERR_NOTSUPPORTED) when the support is lacking.

[josephlr]

Do these ITRON error numbers correspond to errno values?

Specifically, if the return value ret is negative, do we have that ret == -raw_os_error_code, where raw_os_error_code would be an errno value or something you would pass to io::Error::from_raw_os_error?

[kawadakk]

It's not exactly errno, but it can be meaningfully passed to io::Error::from_raw_os_error, provided that the negative sign is preserved.

Actually I just now realized that there exists impl From<Error> for io::Error, which passes the value returned by crate::Error::raw_os_error to io::Error::from_raw_os_error. I pushed the commit 730b326 to negate the error code back in crate::Error::raw_os_error. I hope it's not too much clutter to introduce outside the platform-specific code.

[josephlr]

Instead of just trusting that this function returns 0i32 or a negative i32, could we explicitly check (like we do on other OSes). Something like:

if ret == 0 {
    Ok(())
} else if ret < 0 {
    // ITRON error numbers are always negative, so we negate it so that it
    // falls in the dedicated OS error range (1..INTERNAL_START).
    Err(NonZeroU32::new((-ret) as u32).unwrap())
} else {
    Err(Error::ERRNO_NOT_POSITIVE)
}

[kawadakk]

After scouring documents and pondering for a bit, since all non-negative ITRON error codes are supposed to represent success, I think we can just check if it's negative here. (Implemented in 16f30f0)

[josephlr]

@kawadakk can you also add support for one of the *-kmc-solid_asp3 targets in our CI configuration? No need for all of them, just aarch64-kmc-solid_asp3 would be fine.

[josephlr]

Looks good to me, will let @newpavlov also approve before merging.